@opendata-ai/openchart-core 8.0.0-rc.2 → 8.0.0-rc.21

package/schema/vizspec.schema.json

@@ -181,8 +181,15 @@
                           "description": "Clip marks to the chart area."
                         },
                         "trendline": {
-                          "type": "boolean",
-                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                          "anyOf": [
+                            {
+                              "type": "boolean"
+                            },
+                            {
+                              "$ref": "#/definitions/TrendlineConfig"
+                            }
+                          ],
+                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                         },
                         "dx": {
                           "type": "number",
@@ -222,6 +229,15 @@
                           ],
                           "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                         },
+                        "render": {
+                          "type": "string",
+                          "enum": [
+                            "auto",
+                            "svg",
+                            "canvas"
+                          ],
+                          "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                        },
                         "style": {
                           "type": "string",
                           "enum": [
@@ -450,8 +466,15 @@
                           "description": "Clip marks to the chart area."
                         },
                         "trendline": {
-                          "type": "boolean",
-                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                          "anyOf": [
+                            {
+                              "type": "boolean"
+                            },
+                            {
+                              "$ref": "#/definitions/TrendlineConfig"
+                            }
+                          ],
+                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                         },
                         "dx": {
                           "type": "number",
@@ -491,6 +514,15 @@
                           ],
                           "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                         },
+                        "render": {
+                          "type": "string",
+                          "enum": [
+                            "auto",
+                            "svg",
+                            "canvas"
+                          ],
+                          "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                        },
                         "style": {
                           "type": "string",
                           "enum": [
@@ -719,8 +751,15 @@
                           "description": "Clip marks to the chart area."
                         },
                         "trendline": {
-                          "type": "boolean",
-                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                          "anyOf": [
+                            {
+                              "type": "boolean"
+                            },
+                            {
+                              "$ref": "#/definitions/TrendlineConfig"
+                            }
+                          ],
+                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                         },
                         "dx": {
                           "type": "number",
@@ -760,6 +799,15 @@
                           ],
                           "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                         },
+                        "render": {
+                          "type": "string",
+                          "enum": [
+                            "auto",
+                            "svg",
+                            "canvas"
+                          ],
+                          "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                        },
                         "style": {
                           "type": "string",
                           "enum": [
@@ -988,8 +1036,15 @@
                           "description": "Clip marks to the chart area."
                         },
                         "trendline": {
-                          "type": "boolean",
-                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                          "anyOf": [
+                            {
+                              "type": "boolean"
+                            },
+                            {
+                              "$ref": "#/definitions/TrendlineConfig"
+                            }
+                          ],
+                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                         },
                         "dx": {
                           "type": "number",
@@ -1029,6 +1084,15 @@
                           ],
                           "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                         },
+                        "render": {
+                          "type": "string",
+                          "enum": [
+                            "auto",
+                            "svg",
+                            "canvas"
+                          ],
+                          "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                        },
                         "style": {
                           "type": "string",
                           "enum": [
@@ -1257,8 +1321,15 @@
                           "description": "Clip marks to the chart area."
                         },
                         "trendline": {
-                          "type": "boolean",
-                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                          "anyOf": [
+                            {
+                              "type": "boolean"
+                            },
+                            {
+                              "$ref": "#/definitions/TrendlineConfig"
+                            }
+                          ],
+                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                         },
                         "dx": {
                           "type": "number",
@@ -1298,6 +1369,15 @@
                           ],
                           "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                         },
+                        "render": {
+                          "type": "string",
+                          "enum": [
+                            "auto",
+                            "svg",
+                            "canvas"
+                          ],
+                          "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                        },
                         "style": {
                           "type": "string",
                           "enum": [
@@ -1526,8 +1606,15 @@
                           "description": "Clip marks to the chart area."
                         },
                         "trendline": {
-                          "type": "boolean",
-                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                          "anyOf": [
+                            {
+                              "type": "boolean"
+                            },
+                            {
+                              "$ref": "#/definitions/TrendlineConfig"
+                            }
+                          ],
+                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                         },
                         "dx": {
                           "type": "number",
@@ -1567,6 +1654,15 @@
                           ],
                           "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                         },
+                        "render": {
+                          "type": "string",
+                          "enum": [
+                            "auto",
+                            "svg",
+                            "canvas"
+                          ],
+                          "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                        },
                         "style": {
                           "type": "string",
                           "enum": [
@@ -1795,8 +1891,15 @@
                           "description": "Clip marks to the chart area."
                         },
                         "trendline": {
-                          "type": "boolean",
-                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                          "anyOf": [
+                            {
+                              "type": "boolean"
+                            },
+                            {
+                              "$ref": "#/definitions/TrendlineConfig"
+                            }
+                          ],
+                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                         },
                         "dx": {
                           "type": "number",
@@ -1836,6 +1939,15 @@
                           ],
                           "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                         },
+                        "render": {
+                          "type": "string",
+                          "enum": [
+                            "auto",
+                            "svg",
+                            "canvas"
+                          ],
+                          "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                        },
                         "style": {
                           "type": "string",
                           "enum": [
@@ -2064,8 +2176,15 @@
                           "description": "Clip marks to the chart area."
                         },
                         "trendline": {
-                          "type": "boolean",
-                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                          "anyOf": [
+                            {
+                              "type": "boolean"
+                            },
+                            {
+                              "$ref": "#/definitions/TrendlineConfig"
+                            }
+                          ],
+                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                         },
                         "dx": {
                           "type": "number",
@@ -2105,6 +2224,15 @@
                           ],
                           "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                         },
+                        "render": {
+                          "type": "string",
+                          "enum": [
+                            "auto",
+                            "svg",
+                            "canvas"
+                          ],
+                          "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                        },
                         "style": {
                           "type": "string",
                           "enum": [
@@ -2333,8 +2461,15 @@
                           "description": "Clip marks to the chart area."
                         },
                         "trendline": {
-                          "type": "boolean",
-                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                          "anyOf": [
+                            {
+                              "type": "boolean"
+                            },
+                            {
+                              "$ref": "#/definitions/TrendlineConfig"
+                            }
+                          ],
+                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                         },
                         "dx": {
                           "type": "number",
@@ -2374,6 +2509,15 @@
                           ],
                           "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                         },
+                        "render": {
+                          "type": "string",
+                          "enum": [
+                            "auto",
+                            "svg",
+                            "canvas"
+                          ],
+                          "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                        },
                         "style": {
                           "type": "string",
                           "enum": [
@@ -2602,8 +2746,15 @@
                           "description": "Clip marks to the chart area."
                         },
                         "trendline": {
-                          "type": "boolean",
-                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                          "anyOf": [
+                            {
+                              "type": "boolean"
+                            },
+                            {
+                              "$ref": "#/definitions/TrendlineConfig"
+                            }
+                          ],
+                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                         },
                         "dx": {
                           "type": "number",
@@ -2643,6 +2794,15 @@
                           ],
                           "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                         },
+                        "render": {
+                          "type": "string",
+                          "enum": [
+                            "auto",
+                            "svg",
+                            "canvas"
+                          ],
+                          "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                        },
                         "style": {
                           "type": "string",
                           "enum": [
@@ -2871,8 +3031,15 @@
                           "description": "Clip marks to the chart area."
                         },
                         "trendline": {
-                          "type": "boolean",
-                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                          "anyOf": [
+                            {
+                              "type": "boolean"
+                            },
+                            {
+                              "$ref": "#/definitions/TrendlineConfig"
+                            }
+                          ],
+                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                         },
                         "dx": {
                           "type": "number",
@@ -2912,6 +3079,15 @@
                           ],
                           "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                         },
+                        "render": {
+                          "type": "string",
+                          "enum": [
+                            "auto",
+                            "svg",
+                            "canvas"
+                          ],
+                          "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                        },
                         "style": {
                           "type": "string",
                           "enum": [
@@ -3140,8 +3316,15 @@
                           "description": "Clip marks to the chart area."
                         },
                         "trendline": {
-                          "type": "boolean",
-                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                          "anyOf": [
+                            {
+                              "type": "boolean"
+                            },
+                            {
+                              "$ref": "#/definitions/TrendlineConfig"
+                            }
+                          ],
+                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                         },
                         "dx": {
                           "type": "number",
@@ -3181,6 +3364,15 @@
                           ],
                           "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                         },
+                        "render": {
+                          "type": "string",
+                          "enum": [
+                            "auto",
+                            "svg",
+                            "canvas"
+                          ],
+                          "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                        },
                         "style": {
                           "type": "string",
                           "enum": [
@@ -3409,8 +3601,15 @@
                           "description": "Clip marks to the chart area."
                         },
                         "trendline": {
-                          "type": "boolean",
-                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                          "anyOf": [
+                            {
+                              "type": "boolean"
+                            },
+                            {
+                              "$ref": "#/definitions/TrendlineConfig"
+                            }
+                          ],
+                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                         },
                         "dx": {
                           "type": "number",
@@ -3450,6 +3649,15 @@
                           ],
                           "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                         },
+                        "render": {
+                          "type": "string",
+                          "enum": [
+                            "auto",
+                            "svg",
+                            "canvas"
+                          ],
+                          "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                        },
                         "style": {
                           "type": "string",
                           "enum": [
@@ -3678,8 +3886,15 @@
                           "description": "Clip marks to the chart area."
                         },
                         "trendline": {
-                          "type": "boolean",
-                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                          "anyOf": [
+                            {
+                              "type": "boolean"
+                            },
+                            {
+                              "$ref": "#/definitions/TrendlineConfig"
+                            }
+                          ],
+                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                         },
                         "dx": {
                           "type": "number",
@@ -3719,6 +3934,15 @@
                           ],
                           "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                         },
+                        "render": {
+                          "type": "string",
+                          "enum": [
+                            "auto",
+                            "svg",
+                            "canvas"
+                          ],
+                          "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                        },
                         "style": {
                           "type": "string",
                           "enum": [
@@ -3947,8 +4171,15 @@
                           "description": "Clip marks to the chart area."
                         },
                         "trendline": {
-                          "type": "boolean",
-                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                          "anyOf": [
+                            {
+                              "type": "boolean"
+                            },
+                            {
+                              "$ref": "#/definitions/TrendlineConfig"
+                            }
+                          ],
+                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                         },
                         "dx": {
                           "type": "number",
@@ -3988,6 +4219,15 @@
                           ],
                           "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                         },
+                        "render": {
+                          "type": "string",
+                          "enum": [
+                            "auto",
+                            "svg",
+                            "canvas"
+                          ],
+                          "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                        },
                         "style": {
                           "type": "string",
                           "enum": [
@@ -4216,8 +4456,15 @@
                           "description": "Clip marks to the chart area."
                         },
                         "trendline": {
-                          "type": "boolean",
-                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                          "anyOf": [
+                            {
+                              "type": "boolean"
+                            },
+                            {
+                              "$ref": "#/definitions/TrendlineConfig"
+                            }
+                          ],
+                          "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                         },
                         "dx": {
                           "type": "number",
@@ -4257,6 +4504,15 @@
                           ],
                           "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                         },
+                        "render": {
+                          "type": "string",
+                          "enum": [
+                            "auto",
+                            "svg",
+                            "canvas"
+                          ],
+                          "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                        },
                         "style": {
                           "type": "string",
                           "enum": [
@@ -4484,6 +4740,29 @@
       "additionalProperties": false,
       "description": "Radial gradient definition. Coordinates are in [0,1] normalized space relative to the mark's bounding box."
     },
+    "TrendlineConfig": {
+      "type": "object",
+      "properties": {
+        "layer": {
+          "type": "string",
+          "enum": [
+            "above",
+            "below"
+          ],
+          "description": "Stacking order relative to the point marks. `'below'` (default) draws the line behind the dots; `'above'` draws it on top so it stays visible over a dense cloud."
+        },
+        "stroke": {
+          "type": "string",
+          "description": "Stroke color. Defaults to the theme's high-contrast text color so the line reads on both light and dark grounds. Set an explicit CSS color to override."
+        },
+        "strokeWidth": {
+          "type": "number",
+          "description": "Stroke width in pixels. Defaults to 1.5. Over a dense cloud with `layer: 'above'`, a heavier line (e.g. 2.5) stays legible where the thin default disappears into the dots."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Configuration for the scatter regression trend line. Passed as the object form of `MarkDef.trendline`."
+    },
     "ArcEncoding<DataRow>": {
       "type": "object",
       "properties": {
@@ -4583,6 +4862,14 @@
         "facet": {
           "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
           "description": "Facet channel: partitions data into a grid of small-multiple panels. Each unique value of the facet field produces one panel. Panels share scales by default; use `resolve: { scale: { y: 'independent' } }` for per-panel axes."
+        },
+        "row": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Row facet channel: partitions data into vertically-stacked panels. Each unique value of the row field produces one panel, arranged in a single column. Shares the x-axis scale by default; y-axis is independent. Mutually exclusive with `facet` and `column`."
+        },
+        "column": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Column facet channel: partitions data into side-by-side panels. Each unique value of the column field produces one panel, arranged in a single row. Shares the y-axis scale by default; x-axis is independent. Mutually exclusive with `facet` and `row`."
         }
       },
       "required": [
@@ -5092,12 +5379,13 @@
       "type": "string",
       "enum": [
         "top",
+        "top-left",
         "right",
         "bottom",
         "bottom-right",
         "inline"
       ],
-      "description": "Legend position at a given breakpoint."
+      "description": "Legend position at a given breakpoint. `'top-left'` is a map-only overlay position: the legend floats inside the map area's top-left corner (with its own backdrop) instead of reserving a block of figure height. Charts treat it as the default position."
     },
     "AnnotationOffset": {
       "type": "object",
@@ -5889,6 +6177,10 @@
         "color": {
           "type": "string",
           "description": "Text color (CSS color string)."
+        },
+        "maxLines": {
+          "type": "number",
+          "description": "Maximum number of lines this chrome text may wrap to. Additional lines are dropped and the last kept line is truncated with an ellipsis. Bounds the chrome's contribution to layout height at any container width. Applies whether the font size comes from the theme default or an explicit override. Caps height only, not horizontal overflow of a single unbreakable word."
         }
       },
       "additionalProperties": false,
@@ -6941,7 +7233,7 @@
         "update": {
           "anyOf": [
             {
-              "$ref": "#/definitions/AnimationPhaseConfig"
+              "$ref": "#/definitions/UpdatePhaseConfig"
             },
             {
               "type": "boolean"
@@ -7022,33 +7314,63 @@
       "additionalProperties": false,
       "description": "Stagger configuration for sequential element reveal."
     },
-    "Display": {
-      "type": "string",
-      "enum": [
-        "full",
-        "sparkline"
-      ],
-      "description": "Chart display mode.\n- `'full'` (default): standard chart with chrome, axes, legend, padding.\n- `'sparkline'`: minimal inline mini-chart. Strips chrome, axes, legend,   watermark, animation, and reduces margins to a tiny safety pad. The mark   fills the container edge-to-edge. Best with `mark: 'line' | 'area' | 'bar'`.   Explicit user fields (chrome, legend, encoding.x.axis, etc.) still render   when set, so users can opt in to specific elements."
-    },
-    "SeriesSearchConfig": {
-      "type": "object",
-      "properties": {
-        "placeholder": {
-          "type": "string",
-          "description": "Placeholder text for the search input. Defaults to \"Find a series\"."
-        }
-      },
-      "additionalProperties": false,
-      "description": "Configuration for the searchable series highlight input (`seriesSearch`). The boolean form (`seriesSearch: true`) uses the defaults."
-    },
-    "YouDrawItConfig": {
+    "UpdatePhaseConfig": {
       "type": "object",
       "properties": {
-        "from": {
-          "type": [
-            "string",
-            "number"
-          ],
+        "duration": {
+          "type": "number",
+          "description": "Duration in ms. Default: 500 for enter."
+        },
+        "ease": {
+          "$ref": "#/definitions/AnimationEase",
+          "description": "Easing preset. Default: 'smooth'."
+        },
+        "stagger": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AnimationStagger"
+            },
+            {
+              "type": "boolean"
+            }
+          ],
+          "description": "Stagger config. true = defaults, false = no stagger. Default: true for enter."
+        },
+        "maxMarks": {
+          "type": "number",
+          "description": "Maximum mark count that still runs a tweened data-update transition. Default: 500. Above the cap the chart swaps instantly instead, because per-frame SVG attribute writes on thousands of elements drop frames on low-end devices. Raise it deliberately when the audience is desktop-heavy and you have measured the frame budget."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Data-update phase config. Adds `maxMarks` on top of the shared phase options; the cap is meaningless for enter/exit, which animate via CSS."
+    },
+    "Display": {
+      "type": "string",
+      "enum": [
+        "full",
+        "sparkline"
+      ],
+      "description": "Chart display mode.\n- `'full'` (default): standard chart with chrome, axes, legend, padding.\n- `'sparkline'`: minimal inline mini-chart. Strips chrome, axes, legend,   watermark, animation, and reduces margins to a tiny safety pad. The mark   fills the container edge-to-edge. Best with `mark: 'line' | 'area' | 'bar'`.   Explicit user fields (chrome, legend, encoding.x.axis, etc.) still render   when set, so users can opt in to specific elements."
+    },
+    "SeriesSearchConfig": {
+      "type": "object",
+      "properties": {
+        "placeholder": {
+          "type": "string",
+          "description": "Placeholder text for the search input. Defaults to \"Find a series\"."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Configuration for the searchable series highlight input (`seriesSearch`). The boolean form (`seriesSearch: true`) uses the defaults."
+    },
+    "YouDrawItConfig": {
+      "type": "object",
+      "properties": {
+        "from": {
+          "type": [
+            "string",
+            "number"
+          ],
           "description": "The x value (matching `encoding.x`'s domain) where drawing starts. Data before this point renders normally; data at or after it is hidden behind a hatched \"draw here\" region until reveal."
         },
         "prompt": {
@@ -7248,6 +7570,14 @@
         "facet": {
           "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
           "description": "Facet channel: partitions data into a grid of small-multiple panels. Each unique value of the facet field produces one panel. Panels share scales by default; use `resolve: { scale: { y: 'independent' } }` for per-panel axes."
+        },
+        "row": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Row facet channel: partitions data into vertically-stacked panels. Each unique value of the row field produces one panel, arranged in a single column. Shares the x-axis scale by default; y-axis is independent. Mutually exclusive with `facet` and `column`."
+        },
+        "column": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Column facet channel: partitions data into side-by-side panels. Each unique value of the column field produces one panel, arranged in a single row. Shares the y-axis scale by default; x-axis is independent. Mutually exclusive with `facet` and `row`."
         }
       },
       "required": [
@@ -7359,6 +7689,14 @@
         "facet": {
           "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
           "description": "Facet channel: partitions data into a grid of small-multiple panels. Each unique value of the facet field produces one panel. Panels share scales by default; use `resolve: { scale: { y: 'independent' } }` for per-panel axes."
+        },
+        "row": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Row facet channel: partitions data into vertically-stacked panels. Each unique value of the row field produces one panel, arranged in a single column. Shares the x-axis scale by default; y-axis is independent. Mutually exclusive with `facet` and `column`."
+        },
+        "column": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Column facet channel: partitions data into side-by-side panels. Each unique value of the column field produces one panel, arranged in a single row. Shares the y-axis scale by default; x-axis is independent. Mutually exclusive with `facet` and `row`."
         }
       },
       "required": [
@@ -7470,6 +7808,14 @@
         "facet": {
           "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
           "description": "Facet channel: partitions data into a grid of small-multiple panels. Each unique value of the facet field produces one panel. Panels share scales by default; use `resolve: { scale: { y: 'independent' } }` for per-panel axes."
+        },
+        "row": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Row facet channel: partitions data into vertically-stacked panels. Each unique value of the row field produces one panel, arranged in a single column. Shares the x-axis scale by default; y-axis is independent. Mutually exclusive with `facet` and `column`."
+        },
+        "column": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Column facet channel: partitions data into side-by-side panels. Each unique value of the column field produces one panel, arranged in a single row. Shares the y-axis scale by default; x-axis is independent. Mutually exclusive with `facet` and `row`."
         }
       },
       "required": [
@@ -7581,6 +7927,14 @@
         "facet": {
           "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
           "description": "Facet channel: partitions data into a grid of small-multiple panels. Each unique value of the facet field produces one panel. Panels share scales by default; use `resolve: { scale: { y: 'independent' } }` for per-panel axes."
+        },
+        "row": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Row facet channel: partitions data into vertically-stacked panels. Each unique value of the row field produces one panel, arranged in a single column. Shares the x-axis scale by default; y-axis is independent. Mutually exclusive with `facet` and `column`."
+        },
+        "column": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Column facet channel: partitions data into side-by-side panels. Each unique value of the column field produces one panel, arranged in a single row. Shares the y-axis scale by default; x-axis is independent. Mutually exclusive with `facet` and `row`."
         }
       },
       "required": [
@@ -7692,6 +8046,14 @@
         "facet": {
           "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
           "description": "Facet channel: partitions data into a grid of small-multiple panels. Each unique value of the facet field produces one panel. Panels share scales by default; use `resolve: { scale: { y: 'independent' } }` for per-panel axes."
+        },
+        "row": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Row facet channel: partitions data into vertically-stacked panels. Each unique value of the row field produces one panel, arranged in a single column. Shares the x-axis scale by default; y-axis is independent. Mutually exclusive with `facet` and `column`."
+        },
+        "column": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Column facet channel: partitions data into side-by-side panels. Each unique value of the column field produces one panel, arranged in a single row. Shares the y-axis scale by default; x-axis is independent. Mutually exclusive with `facet` and `row`."
         }
       },
       "required": [
@@ -7803,6 +8165,14 @@
         "facet": {
           "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
           "description": "Facet channel: partitions data into a grid of small-multiple panels. Each unique value of the facet field produces one panel. Panels share scales by default; use `resolve: { scale: { y: 'independent' } }` for per-panel axes."
+        },
+        "row": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Row facet channel: partitions data into vertically-stacked panels. Each unique value of the row field produces one panel, arranged in a single column. Shares the x-axis scale by default; y-axis is independent. Mutually exclusive with `facet` and `column`."
+        },
+        "column": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Column facet channel: partitions data into side-by-side panels. Each unique value of the column field produces one panel, arranged in a single row. Shares the y-axis scale by default; x-axis is independent. Mutually exclusive with `facet` and `row`."
         }
       },
       "required": [
@@ -7914,6 +8284,14 @@
         "facet": {
           "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
           "description": "Facet channel: partitions data into a grid of small-multiple panels. Each unique value of the facet field produces one panel. Panels share scales by default; use `resolve: { scale: { y: 'independent' } }` for per-panel axes."
+        },
+        "row": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Row facet channel: partitions data into vertically-stacked panels. Each unique value of the row field produces one panel, arranged in a single column. Shares the x-axis scale by default; y-axis is independent. Mutually exclusive with `facet` and `column`."
+        },
+        "column": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Column facet channel: partitions data into side-by-side panels. Each unique value of the column field produces one panel, arranged in a single row. Shares the y-axis scale by default; x-axis is independent. Mutually exclusive with `facet` and `row`."
         }
       },
       "additionalProperties": false,
@@ -8021,6 +8399,14 @@
         "facet": {
           "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
           "description": "Facet channel: partitions data into a grid of small-multiple panels. Each unique value of the facet field produces one panel. Panels share scales by default; use `resolve: { scale: { y: 'independent' } }` for per-panel axes."
+        },
+        "row": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Row facet channel: partitions data into vertically-stacked panels. Each unique value of the row field produces one panel, arranged in a single column. Shares the x-axis scale by default; y-axis is independent. Mutually exclusive with `facet` and `column`."
+        },
+        "column": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Column facet channel: partitions data into side-by-side panels. Each unique value of the column field produces one panel, arranged in a single row. Shares the y-axis scale by default; x-axis is independent. Mutually exclusive with `facet` and `row`."
         }
       },
       "required": [
@@ -8129,6 +8515,14 @@
         "facet": {
           "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
           "description": "Facet channel: partitions data into a grid of small-multiple panels. Each unique value of the facet field produces one panel. Panels share scales by default; use `resolve: { scale: { y: 'independent' } }` for per-panel axes."
+        },
+        "row": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Row facet channel: partitions data into vertically-stacked panels. Each unique value of the row field produces one panel, arranged in a single column. Shares the x-axis scale by default; y-axis is independent. Mutually exclusive with `facet` and `column`."
+        },
+        "column": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Column facet channel: partitions data into side-by-side panels. Each unique value of the column field produces one panel, arranged in a single row. Shares the y-axis scale by default; x-axis is independent. Mutually exclusive with `facet` and `row`."
         }
       },
       "required": [
@@ -8239,6 +8633,14 @@
         "facet": {
           "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
           "description": "Facet channel: partitions data into a grid of small-multiple panels. Each unique value of the facet field produces one panel. Panels share scales by default; use `resolve: { scale: { y: 'independent' } }` for per-panel axes."
+        },
+        "row": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Row facet channel: partitions data into vertically-stacked panels. Each unique value of the row field produces one panel, arranged in a single column. Shares the x-axis scale by default; y-axis is independent. Mutually exclusive with `facet` and `column`."
+        },
+        "column": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Column facet channel: partitions data into side-by-side panels. Each unique value of the column field produces one panel, arranged in a single row. Shares the y-axis scale by default; x-axis is independent. Mutually exclusive with `facet` and `row`."
         }
       },
       "required": [
@@ -8349,6 +8751,14 @@
         "facet": {
           "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
           "description": "Facet channel: partitions data into a grid of small-multiple panels. Each unique value of the facet field produces one panel. Panels share scales by default; use `resolve: { scale: { y: 'independent' } }` for per-panel axes."
+        },
+        "row": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Row facet channel: partitions data into vertically-stacked panels. Each unique value of the row field produces one panel, arranged in a single column. Shares the x-axis scale by default; y-axis is independent. Mutually exclusive with `facet` and `column`."
+        },
+        "column": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Column facet channel: partitions data into side-by-side panels. Each unique value of the column field produces one panel, arranged in a single row. Shares the y-axis scale by default; x-axis is independent. Mutually exclusive with `facet` and `row`."
         }
       },
       "required": [
@@ -8460,6 +8870,14 @@
         "facet": {
           "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
           "description": "Facet channel: partitions data into a grid of small-multiple panels. Each unique value of the facet field produces one panel. Panels share scales by default; use `resolve: { scale: { y: 'independent' } }` for per-panel axes."
+        },
+        "row": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Row facet channel: partitions data into vertically-stacked panels. Each unique value of the row field produces one panel, arranged in a single column. Shares the x-axis scale by default; y-axis is independent. Mutually exclusive with `facet` and `column`."
+        },
+        "column": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Column facet channel: partitions data into side-by-side panels. Each unique value of the column field produces one panel, arranged in a single row. Shares the y-axis scale by default; x-axis is independent. Mutually exclusive with `facet` and `row`."
         }
       },
       "required": [
@@ -8571,6 +8989,14 @@
         "facet": {
           "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
           "description": "Facet channel: partitions data into a grid of small-multiple panels. Each unique value of the facet field produces one panel. Panels share scales by default; use `resolve: { scale: { y: 'independent' } }` for per-panel axes."
+        },
+        "row": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Row facet channel: partitions data into vertically-stacked panels. Each unique value of the row field produces one panel, arranged in a single column. Shares the x-axis scale by default; y-axis is independent. Mutually exclusive with `facet` and `column`."
+        },
+        "column": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Column facet channel: partitions data into side-by-side panels. Each unique value of the column field produces one panel, arranged in a single row. Shares the y-axis scale by default; x-axis is independent. Mutually exclusive with `facet` and `row`."
         }
       },
       "additionalProperties": false,
@@ -8668,6 +9094,14 @@
         "facet": {
           "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
           "description": "Facet channel: partitions data into a grid of small-multiple panels. Each unique value of the facet field produces one panel. Panels share scales by default; use `resolve: { scale: { y: 'independent' } }` for per-panel axes."
+        },
+        "row": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Row facet channel: partitions data into vertically-stacked panels. Each unique value of the row field produces one panel, arranged in a single column. Shares the x-axis scale by default; y-axis is independent. Mutually exclusive with `facet` and `column`."
+        },
+        "column": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Column facet channel: partitions data into side-by-side panels. Each unique value of the column field produces one panel, arranged in a single row. Shares the y-axis scale by default; x-axis is independent. Mutually exclusive with `facet` and `row`."
         }
       },
       "required": [
@@ -8776,6 +9210,14 @@
         "facet": {
           "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
           "description": "Facet channel: partitions data into a grid of small-multiple panels. Each unique value of the facet field produces one panel. Panels share scales by default; use `resolve: { scale: { y: 'independent' } }` for per-panel axes."
+        },
+        "row": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Row facet channel: partitions data into vertically-stacked panels. Each unique value of the row field produces one panel, arranged in a single column. Shares the x-axis scale by default; y-axis is independent. Mutually exclusive with `facet` and `column`."
+        },
+        "column": {
+          "$ref": "#/definitions/FacetChannel%3CDataRow%3E",
+          "description": "Column facet channel: partitions data into side-by-side panels. Each unique value of the column field produces one panel, arranged in a single row. Shares the y-axis scale by default; x-axis is independent. Mutually exclusive with `facet` and `row`."
         }
       },
       "required": [
@@ -8867,7 +9309,7 @@
           "items": {
             "$ref": "#/definitions/Annotation"
           },
-          "description": "Annotations on the layered view."
+          "description": "Annotations for the layered chart. When present, these are the annotations rendered and available for editing. When absent, falls back to the first leaf layer's annotations. Annotations on second and later leaf layers are not rendered.\n\nFor edit persistence: the `data-annotation-index` stamped on each rendered annotation maps to this array (or the first leaf's if this is unset). Place annotations here for reliable index-based edit matching."
         },
         "labels": {
           "$ref": "#/definitions/LabelSpec",
@@ -8902,7 +9344,7 @@
           "items": {
             "type": "string"
           },
-          "description": "Hidden series names."
+          "description": "Series names to hide from rendering by default. This is the authored persistence target for legend visibility. Runtime legend toggles (legend-toggle edit events) layer on top of this via ephemeral runtime sets but never modify it."
         },
         "endpointLabels": {
           "anyOf": [
@@ -9063,8 +9505,15 @@
                       "description": "Clip marks to the chart area."
                     },
                     "trendline": {
-                      "type": "boolean",
-                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                      "anyOf": [
+                        {
+                          "type": "boolean"
+                        },
+                        {
+                          "$ref": "#/definitions/TrendlineConfig"
+                        }
+                      ],
+                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                     },
                     "dx": {
                       "type": "number",
@@ -9104,6 +9553,15 @@
                       ],
                       "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                     },
+                    "render": {
+                      "type": "string",
+                      "enum": [
+                        "auto",
+                        "svg",
+                        "canvas"
+                      ],
+                      "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                    },
                     "style": {
                       "type": "string",
                       "enum": [
@@ -9202,6 +9660,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -9310,7 +9776,7 @@
               "items": {
                 "type": "string"
               },
-              "description": "Series names to hide from rendering. Hidden series remain in the legend but are visually dimmed."
+              "description": "Series names to hide from rendering by default. This is the authored persistence target for legend visibility. Runtime legend toggles (legend-toggle edit events) layer on top of this via ephemeral runtime sets but never modify it."
             },
             "seriesStyles": {
               "type": "object",
@@ -9512,8 +9978,15 @@
                       "description": "Clip marks to the chart area."
                     },
                     "trendline": {
-                      "type": "boolean",
-                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                      "anyOf": [
+                        {
+                          "type": "boolean"
+                        },
+                        {
+                          "$ref": "#/definitions/TrendlineConfig"
+                        }
+                      ],
+                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                     },
                     "dx": {
                       "type": "number",
@@ -9553,6 +10026,15 @@
                       ],
                       "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                     },
+                    "render": {
+                      "type": "string",
+                      "enum": [
+                        "auto",
+                        "svg",
+                        "canvas"
+                      ],
+                      "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                    },
                     "style": {
                       "type": "string",
                       "enum": [
@@ -9651,6 +10133,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -9759,7 +10249,7 @@
               "items": {
                 "type": "string"
               },
-              "description": "Series names to hide from rendering. Hidden series remain in the legend but are visually dimmed."
+              "description": "Series names to hide from rendering by default. This is the authored persistence target for legend visibility. Runtime legend toggles (legend-toggle edit events) layer on top of this via ephemeral runtime sets but never modify it."
             },
             "seriesStyles": {
               "type": "object",
@@ -9961,8 +10451,15 @@
                       "description": "Clip marks to the chart area."
                     },
                     "trendline": {
-                      "type": "boolean",
-                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                      "anyOf": [
+                        {
+                          "type": "boolean"
+                        },
+                        {
+                          "$ref": "#/definitions/TrendlineConfig"
+                        }
+                      ],
+                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                     },
                     "dx": {
                       "type": "number",
@@ -10002,6 +10499,15 @@
                       ],
                       "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                     },
+                    "render": {
+                      "type": "string",
+                      "enum": [
+                        "auto",
+                        "svg",
+                        "canvas"
+                      ],
+                      "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                    },
                     "style": {
                       "type": "string",
                       "enum": [
@@ -10100,6 +10606,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -10208,7 +10722,7 @@
               "items": {
                 "type": "string"
               },
-              "description": "Series names to hide from rendering. Hidden series remain in the legend but are visually dimmed."
+              "description": "Series names to hide from rendering by default. This is the authored persistence target for legend visibility. Runtime legend toggles (legend-toggle edit events) layer on top of this via ephemeral runtime sets but never modify it."
             },
             "seriesStyles": {
               "type": "object",
@@ -10410,8 +10924,15 @@
                       "description": "Clip marks to the chart area."
                     },
                     "trendline": {
-                      "type": "boolean",
-                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                      "anyOf": [
+                        {
+                          "type": "boolean"
+                        },
+                        {
+                          "$ref": "#/definitions/TrendlineConfig"
+                        }
+                      ],
+                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                     },
                     "dx": {
                       "type": "number",
@@ -10451,6 +10972,15 @@
                       ],
                       "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                     },
+                    "render": {
+                      "type": "string",
+                      "enum": [
+                        "auto",
+                        "svg",
+                        "canvas"
+                      ],
+                      "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                    },
                     "style": {
                       "type": "string",
                       "enum": [
@@ -10549,6 +11079,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -10657,7 +11195,7 @@
               "items": {
                 "type": "string"
               },
-              "description": "Series names to hide from rendering. Hidden series remain in the legend but are visually dimmed."
+              "description": "Series names to hide from rendering by default. This is the authored persistence target for legend visibility. Runtime legend toggles (legend-toggle edit events) layer on top of this via ephemeral runtime sets but never modify it."
             },
             "seriesStyles": {
               "type": "object",
@@ -10859,8 +11397,15 @@
                       "description": "Clip marks to the chart area."
                     },
                     "trendline": {
-                      "type": "boolean",
-                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                      "anyOf": [
+                        {
+                          "type": "boolean"
+                        },
+                        {
+                          "$ref": "#/definitions/TrendlineConfig"
+                        }
+                      ],
+                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                     },
                     "dx": {
                       "type": "number",
@@ -10900,6 +11445,15 @@
                       ],
                       "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                     },
+                    "render": {
+                      "type": "string",
+                      "enum": [
+                        "auto",
+                        "svg",
+                        "canvas"
+                      ],
+                      "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                    },
                     "style": {
                       "type": "string",
                       "enum": [
@@ -10998,6 +11552,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -11106,7 +11668,7 @@
               "items": {
                 "type": "string"
               },
-              "description": "Series names to hide from rendering. Hidden series remain in the legend but are visually dimmed."
+              "description": "Series names to hide from rendering by default. This is the authored persistence target for legend visibility. Runtime legend toggles (legend-toggle edit events) layer on top of this via ephemeral runtime sets but never modify it."
             },
             "seriesStyles": {
               "type": "object",
@@ -11308,8 +11870,15 @@
                       "description": "Clip marks to the chart area."
                     },
                     "trendline": {
-                      "type": "boolean",
-                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                      "anyOf": [
+                        {
+                          "type": "boolean"
+                        },
+                        {
+                          "$ref": "#/definitions/TrendlineConfig"
+                        }
+                      ],
+                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                     },
                     "dx": {
                       "type": "number",
@@ -11349,6 +11918,15 @@
                       ],
                       "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                     },
+                    "render": {
+                      "type": "string",
+                      "enum": [
+                        "auto",
+                        "svg",
+                        "canvas"
+                      ],
+                      "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                    },
                     "style": {
                       "type": "string",
                       "enum": [
@@ -11447,6 +12025,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -11555,7 +12141,7 @@
               "items": {
                 "type": "string"
               },
-              "description": "Series names to hide from rendering. Hidden series remain in the legend but are visually dimmed."
+              "description": "Series names to hide from rendering by default. This is the authored persistence target for legend visibility. Runtime legend toggles (legend-toggle edit events) layer on top of this via ephemeral runtime sets but never modify it."
             },
             "seriesStyles": {
               "type": "object",
@@ -11757,8 +12343,15 @@
                       "description": "Clip marks to the chart area."
                     },
                     "trendline": {
-                      "type": "boolean",
-                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                      "anyOf": [
+                        {
+                          "type": "boolean"
+                        },
+                        {
+                          "$ref": "#/definitions/TrendlineConfig"
+                        }
+                      ],
+                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                     },
                     "dx": {
                       "type": "number",
@@ -11798,6 +12391,15 @@
                       ],
                       "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                     },
+                    "render": {
+                      "type": "string",
+                      "enum": [
+                        "auto",
+                        "svg",
+                        "canvas"
+                      ],
+                      "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                    },
                     "style": {
                       "type": "string",
                       "enum": [
@@ -11896,6 +12498,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -12004,7 +12614,7 @@
               "items": {
                 "type": "string"
               },
-              "description": "Series names to hide from rendering. Hidden series remain in the legend but are visually dimmed."
+              "description": "Series names to hide from rendering by default. This is the authored persistence target for legend visibility. Runtime legend toggles (legend-toggle edit events) layer on top of this via ephemeral runtime sets but never modify it."
             },
             "seriesStyles": {
               "type": "object",
@@ -12206,8 +12816,15 @@
                       "description": "Clip marks to the chart area."
                     },
                     "trendline": {
-                      "type": "boolean",
-                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                      "anyOf": [
+                        {
+                          "type": "boolean"
+                        },
+                        {
+                          "$ref": "#/definitions/TrendlineConfig"
+                        }
+                      ],
+                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                     },
                     "dx": {
                       "type": "number",
@@ -12247,6 +12864,15 @@
                       ],
                       "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                     },
+                    "render": {
+                      "type": "string",
+                      "enum": [
+                        "auto",
+                        "svg",
+                        "canvas"
+                      ],
+                      "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                    },
                     "style": {
                       "type": "string",
                       "enum": [
@@ -12345,6 +12971,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -12453,7 +13087,7 @@
               "items": {
                 "type": "string"
               },
-              "description": "Series names to hide from rendering. Hidden series remain in the legend but are visually dimmed."
+              "description": "Series names to hide from rendering by default. This is the authored persistence target for legend visibility. Runtime legend toggles (legend-toggle edit events) layer on top of this via ephemeral runtime sets but never modify it."
             },
             "seriesStyles": {
               "type": "object",
@@ -12655,8 +13289,15 @@
                       "description": "Clip marks to the chart area."
                     },
                     "trendline": {
-                      "type": "boolean",
-                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                      "anyOf": [
+                        {
+                          "type": "boolean"
+                        },
+                        {
+                          "$ref": "#/definitions/TrendlineConfig"
+                        }
+                      ],
+                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                     },
                     "dx": {
                       "type": "number",
@@ -12696,6 +13337,15 @@
                       ],
                       "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                     },
+                    "render": {
+                      "type": "string",
+                      "enum": [
+                        "auto",
+                        "svg",
+                        "canvas"
+                      ],
+                      "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                    },
                     "style": {
                       "type": "string",
                       "enum": [
@@ -12794,6 +13444,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -12902,7 +13560,7 @@
               "items": {
                 "type": "string"
               },
-              "description": "Series names to hide from rendering. Hidden series remain in the legend but are visually dimmed."
+              "description": "Series names to hide from rendering by default. This is the authored persistence target for legend visibility. Runtime legend toggles (legend-toggle edit events) layer on top of this via ephemeral runtime sets but never modify it."
             },
             "seriesStyles": {
               "type": "object",
@@ -13104,8 +13762,15 @@
                       "description": "Clip marks to the chart area."
                     },
                     "trendline": {
-                      "type": "boolean",
-                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                      "anyOf": [
+                        {
+                          "type": "boolean"
+                        },
+                        {
+                          "$ref": "#/definitions/TrendlineConfig"
+                        }
+                      ],
+                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                     },
                     "dx": {
                       "type": "number",
@@ -13145,6 +13810,15 @@
                       ],
                       "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                     },
+                    "render": {
+                      "type": "string",
+                      "enum": [
+                        "auto",
+                        "svg",
+                        "canvas"
+                      ],
+                      "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                    },
                     "style": {
                       "type": "string",
                       "enum": [
@@ -13243,6 +13917,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -13351,7 +14033,7 @@
               "items": {
                 "type": "string"
               },
-              "description": "Series names to hide from rendering. Hidden series remain in the legend but are visually dimmed."
+              "description": "Series names to hide from rendering by default. This is the authored persistence target for legend visibility. Runtime legend toggles (legend-toggle edit events) layer on top of this via ephemeral runtime sets but never modify it."
             },
             "seriesStyles": {
               "type": "object",
@@ -13553,8 +14235,15 @@
                       "description": "Clip marks to the chart area."
                     },
                     "trendline": {
-                      "type": "boolean",
-                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                      "anyOf": [
+                        {
+                          "type": "boolean"
+                        },
+                        {
+                          "$ref": "#/definitions/TrendlineConfig"
+                        }
+                      ],
+                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                     },
                     "dx": {
                       "type": "number",
@@ -13594,6 +14283,15 @@
                       ],
                       "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                     },
+                    "render": {
+                      "type": "string",
+                      "enum": [
+                        "auto",
+                        "svg",
+                        "canvas"
+                      ],
+                      "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                    },
                     "style": {
                       "type": "string",
                       "enum": [
@@ -13692,6 +14390,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -13800,7 +14506,7 @@
               "items": {
                 "type": "string"
               },
-              "description": "Series names to hide from rendering. Hidden series remain in the legend but are visually dimmed."
+              "description": "Series names to hide from rendering by default. This is the authored persistence target for legend visibility. Runtime legend toggles (legend-toggle edit events) layer on top of this via ephemeral runtime sets but never modify it."
             },
             "seriesStyles": {
               "type": "object",
@@ -14002,8 +14708,15 @@
                       "description": "Clip marks to the chart area."
                     },
                     "trendline": {
-                      "type": "boolean",
-                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                      "anyOf": [
+                        {
+                          "type": "boolean"
+                        },
+                        {
+                          "$ref": "#/definitions/TrendlineConfig"
+                        }
+                      ],
+                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                     },
                     "dx": {
                       "type": "number",
@@ -14043,6 +14756,15 @@
                       ],
                       "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                     },
+                    "render": {
+                      "type": "string",
+                      "enum": [
+                        "auto",
+                        "svg",
+                        "canvas"
+                      ],
+                      "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                    },
                     "style": {
                       "type": "string",
                       "enum": [
@@ -14141,6 +14863,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -14249,7 +14979,7 @@
               "items": {
                 "type": "string"
               },
-              "description": "Series names to hide from rendering. Hidden series remain in the legend but are visually dimmed."
+              "description": "Series names to hide from rendering by default. This is the authored persistence target for legend visibility. Runtime legend toggles (legend-toggle edit events) layer on top of this via ephemeral runtime sets but never modify it."
             },
             "seriesStyles": {
               "type": "object",
@@ -14451,8 +15181,15 @@
                       "description": "Clip marks to the chart area."
                     },
                     "trendline": {
-                      "type": "boolean",
-                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                      "anyOf": [
+                        {
+                          "type": "boolean"
+                        },
+                        {
+                          "$ref": "#/definitions/TrendlineConfig"
+                        }
+                      ],
+                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                     },
                     "dx": {
                       "type": "number",
@@ -14492,6 +15229,15 @@
                       ],
                       "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                     },
+                    "render": {
+                      "type": "string",
+                      "enum": [
+                        "auto",
+                        "svg",
+                        "canvas"
+                      ],
+                      "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                    },
                     "style": {
                       "type": "string",
                       "enum": [
@@ -14590,6 +15336,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -14698,7 +15452,7 @@
               "items": {
                 "type": "string"
               },
-              "description": "Series names to hide from rendering. Hidden series remain in the legend but are visually dimmed."
+              "description": "Series names to hide from rendering by default. This is the authored persistence target for legend visibility. Runtime legend toggles (legend-toggle edit events) layer on top of this via ephemeral runtime sets but never modify it."
             },
             "seriesStyles": {
               "type": "object",
@@ -14900,8 +15654,15 @@
                       "description": "Clip marks to the chart area."
                     },
                     "trendline": {
-                      "type": "boolean",
-                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                      "anyOf": [
+                        {
+                          "type": "boolean"
+                        },
+                        {
+                          "$ref": "#/definitions/TrendlineConfig"
+                        }
+                      ],
+                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                     },
                     "dx": {
                       "type": "number",
@@ -14941,6 +15702,15 @@
                       ],
                       "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                     },
+                    "render": {
+                      "type": "string",
+                      "enum": [
+                        "auto",
+                        "svg",
+                        "canvas"
+                      ],
+                      "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                    },
                     "style": {
                       "type": "string",
                       "enum": [
@@ -15039,6 +15809,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -15147,7 +15925,7 @@
               "items": {
                 "type": "string"
               },
-              "description": "Series names to hide from rendering. Hidden series remain in the legend but are visually dimmed."
+              "description": "Series names to hide from rendering by default. This is the authored persistence target for legend visibility. Runtime legend toggles (legend-toggle edit events) layer on top of this via ephemeral runtime sets but never modify it."
             },
             "seriesStyles": {
               "type": "object",
@@ -15349,8 +16127,15 @@
                       "description": "Clip marks to the chart area."
                     },
                     "trendline": {
-                      "type": "boolean",
-                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                      "anyOf": [
+                        {
+                          "type": "boolean"
+                        },
+                        {
+                          "$ref": "#/definitions/TrendlineConfig"
+                        }
+                      ],
+                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                     },
                     "dx": {
                       "type": "number",
@@ -15390,6 +16175,15 @@
                       ],
                       "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                     },
+                    "render": {
+                      "type": "string",
+                      "enum": [
+                        "auto",
+                        "svg",
+                        "canvas"
+                      ],
+                      "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                    },
                     "style": {
                       "type": "string",
                       "enum": [
@@ -15488,6 +16282,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -15596,7 +16398,7 @@
               "items": {
                 "type": "string"
               },
-              "description": "Series names to hide from rendering. Hidden series remain in the legend but are visually dimmed."
+              "description": "Series names to hide from rendering by default. This is the authored persistence target for legend visibility. Runtime legend toggles (legend-toggle edit events) layer on top of this via ephemeral runtime sets but never modify it."
             },
             "seriesStyles": {
               "type": "object",
@@ -15798,8 +16600,15 @@
                       "description": "Clip marks to the chart area."
                     },
                     "trendline": {
-                      "type": "boolean",
-                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals."
+                      "anyOf": [
+                        {
+                          "type": "boolean"
+                        },
+                        {
+                          "$ref": "#/definitions/TrendlineConfig"
+                        }
+                      ],
+                      "description": "Overlay a least-squares regression line on scatter (point) marks. Defaults to true. Set `mark: { type: 'point', trendline: false }` to suppress it when the chart already carries its own reference line (e.g. a manual x=y diagonal in a separate layer), which would otherwise produce two competing diagonals.\n\nPass an object to control stacking order: the line renders `below` the points by default, but a dense scatter (thousands of overlapping dots) fully occludes a line drawn underneath, so `{ layer: 'above' }` lifts the reference line over the cloud."
                     },
                     "dx": {
                       "type": "number",
@@ -15839,6 +16648,15 @@
                       ],
                       "description": "Pattern-fill reinforcement for filled marks (bar, area, arc).\n\n- `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,   crosshatch, vertical lines) layered over each series color so series   remain distinguishable without color vision. Marks too small to show   a legible pattern keep their solid fill.\n- `'none'` (default): solid fills only."
                     },
+                    "render": {
+                      "type": "string",
+                      "enum": [
+                        "auto",
+                        "svg",
+                        "canvas"
+                      ],
+                      "description": "Rendering backend for point marks. High-cardinality scatter plots draw thousands of SVG circles, which is what makes their entrance and update transitions stutter; a canvas layer draws the same dots in a handful of batched paint calls.\n\n- `'auto'` (default): canvas above 1,000 compiled point marks, SVG below.\n- `'svg'`: always SVG, whatever the point count.\n- `'canvas'`: always canvas, whatever the point count.\n\nCanvas mode trades per-mark keyboard focus and edit-mode point selection (the screen-reader data table still carries every row), and draws the trendline above the dots even when `trendline.layer` is `'below'`. Tooltips, hover, and click callbacks work the same in both modes.\n\nIgnored with a console warning for non-point marks, and for faceted, layered, and sparkline charts."
+                    },
                     "style": {
                       "type": "string",
                       "enum": [
@@ -15937,6 +16755,14 @@
               "$ref": "#/definitions/Chrome",
               "description": "Editorial chrome (title, subtitle, source, etc.)."
             },
+            "chromeLayout": {
+              "type": "string",
+              "enum": [
+                "subtract",
+                "grow"
+              ],
+              "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+            },
             "title": {
               "anyOf": [
                 {
@@ -16045,7 +16871,7 @@
               "items": {
                 "type": "string"
               },
-              "description": "Series names to hide from rendering. Hidden series remain in the legend but are visually dimmed."
+              "description": "Series names to hide from rendering by default. This is the authored persistence target for legend visibility. Runtime legend toggles (legend-toggle edit events) layer on top of this via ephemeral runtime sets but never modify it."
             },
             "seriesStyles": {
               "type": "object",
@@ -16198,7 +17024,7 @@
           "items": {
             "$ref": "#/definitions/Annotation"
           },
-          "description": "Annotations on the layered view."
+          "description": "Annotations for the layered chart. When present, these are the annotations rendered and available for editing. When absent, falls back to the first leaf layer's annotations. Annotations on second and later leaf layers are not rendered.\n\nFor edit persistence: the `data-annotation-index` stamped on each rendered annotation maps to this array (or the first leaf's if this is unset). Place annotations here for reliable index-based edit matching."
         },
         "labels": {
           "$ref": "#/definitions/LabelSpec",
@@ -16233,7 +17059,7 @@
           "items": {
             "type": "string"
           },
-          "description": "Hidden series names."
+          "description": "Series names to hide from rendering by default. This is the authored persistence target for legend visibility. Runtime legend toggles (legend-toggle edit events) layer on top of this via ephemeral runtime sets but never modify it."
         },
         "endpointLabels": {
           "anyOf": [
@@ -16570,6 +17396,34 @@
           "$ref": "#/definitions/DarkMode",
           "description": "Dark mode behavior."
         },
+        "animation": {
+          "$ref": "#/definitions/GraphAnimationSpec",
+          "description": "Motion configuration. DEFAULT-ON: omit for full defaults, `false` to opt out of choreography (layout warmup still applies)."
+        },
+        "interaction": {
+          "$ref": "#/definitions/GraphInteractionConfig",
+          "description": "Interaction behavior (hover mode, select-fly, opt-in physics)."
+        },
+        "legend": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "object",
+              "properties": {
+                "interactive": {
+                  "type": "boolean"
+                },
+                "counts": {
+                  "type": "boolean"
+                }
+              },
+              "additionalProperties": false
+            }
+          ],
+          "description": "Built-in legend. Interactive by default. Set `false` if you render your own legend, so the built-in filter UI doesn't compete with it."
+        },
         "watermark": {
           "type": "boolean",
           "description": "Whether to show the tryOpenData.ai watermark. Defaults to true."
@@ -16628,7 +17482,11 @@
         },
         "nodeSize": {
           "$ref": "#/definitions/GraphEncodingChannel",
-          "description": "Size mapping for nodes."
+          "description": "Size mapping for nodes. `scale.type` defaults to `'sqrt'` (area-perceptual, today's behavior); set `scale.type: 'linear'` for a linear radius ramp. `scale.range` sets the pixel radius extent (default `[3, 12]`)."
+        },
+        "nodeOpacity": {
+          "$ref": "#/definitions/GraphEncodingChannel",
+          "description": "Opacity mapping for nodes (VL opacity channel). Quantitative fields map linearly to `[0.25, 1]`; `scale.range` overrides.\n\nNOTE: there is deliberately no `edgeOpacity` channel — edge alpha is owned by the interaction alpha-tier machinery (hover dimming, search)."
         },
         "edgeColor": {
           "$ref": "#/definitions/GraphEncodingChannel",
@@ -16645,6 +17503,10 @@
         "nodeLabel": {
           "$ref": "#/definitions/GraphEncodingChannel",
           "description": "Label field for nodes."
+        },
+        "nodeLabelPriority": {
+          "$ref": "#/definitions/GraphEncodingChannel",
+          "description": "Label priority mapping for nodes. Maps a quantitative field to a 0-1 priority range; higher values are shown first as the user zooms in. Omit to use the default degree-based priority. `nodeOverrides[id].alwaysShowLabel` still wins as the hard override."
         }
       },
       "additionalProperties": false,
@@ -16664,6 +17526,42 @@
         "scale": {
           "$ref": "#/definitions/ScaleConfig",
           "description": "Scale configuration. Auto-derived from data if omitted."
+        },
+        "sort": {
+          "anyOf": [
+            {
+              "type": "string",
+              "const": "ascending"
+            },
+            {
+              "type": "string",
+              "const": "descending"
+            },
+            {
+              "type": "null"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          ],
+          "description": "Category ordering for the color domain and legend. Graph channels default `'ascending'` (VL-aligned, deterministic); `string[]` pins an explicit order; `null` keeps data order.\n\nNOTE: chart encoding channels keep data-order — this graph default is a deliberate divergence this release (see docs/migrating-v8.md)."
+        },
+        "highlight": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          ],
+          "description": "Category values to emphasize on load; the rest dim. Mirrors the chart `encoding.color.highlight` value list. Distinct from the `highlight()` runtime verb and `interaction.hover.mode`."
         }
       },
       "required": [
@@ -16717,6 +17615,35 @@
         "centerForce": {
           "type": "boolean",
           "description": "Whether to apply center force (default true)."
+        },
+        "seed": {
+          "type": "number",
+          "description": "Deterministic layout seed. Same spec + seed ⇒ identical settled layout within a given execution path (worker vs sync parity is not guaranteed)."
+        },
+        "energy": {
+          "type": "string",
+          "enum": [
+            "gentle",
+            "balanced",
+            "energetic"
+          ],
+          "description": "Repulsion preset (plain-language, no d3 jargon): `gentle`/`balanced`/`energetic` → chargeStrength −150/−300/−600 and velocityDecay 0.5/0.4/0.3. A raw `chargeStrength` wins over the preset."
+        },
+        "settle": {
+          "type": "string",
+          "enum": [
+            "quick",
+            "balanced",
+            "thorough"
+          ],
+          "description": "Settle-speed preset: `quick`/`balanced`/`thorough` → alphaDecay 0.05/0.0228/0.01. Higher = faster cool-down, less final refinement."
+        },
+        "warmup": {
+          "type": [
+            "boolean",
+            "number"
+          ],
+          "description": "Headless settle ticks run before the first paint. `true` → 100 ticks under a 250ms budget; a number sets an explicit tick count; `false` disables.\n\nLives in `layout`, NOT `animation`, on purpose: warmup *reduces* motion, so it must survive `animation: false` (opt-out consumers get less settling chaos, not more)."
         }
       },
       "required": [
@@ -16752,6 +17679,157 @@
       "additionalProperties": false,
       "description": "Per-node visual overrides, keyed by node id."
     },
+    "GraphAnimationSpec": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "$ref": "#/definitions/GraphAnimationConfig"
+        }
+      ],
+      "description": "Graph motion spec.\n- omitted → full defaults (default-ON)\n- `false` → no choreography (warmup still applies)\n- object → per-phase control\n\n`prefers-reduced-motion` is always respected regardless of this value."
+    },
+    "GraphAnimationConfig": {
+      "type": "object",
+      "properties": {
+        "enter": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AnimationPhaseConfig"
+            },
+            {
+              "type": "boolean"
+            }
+          ],
+          "description": "Node/edge reveal on first render. Default `{ duration: 500, ease: 'smooth', stagger: true }`."
+        },
+        "update": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AnimationPhaseConfig"
+            },
+            {
+              "type": "boolean"
+            }
+          ],
+          "description": "Data-update enter-fade for newly added marks. Default `{ duration: 300, ease: 'smooth' }`."
+        },
+        "exit": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AnimationPhaseConfig"
+            },
+            {
+              "type": "boolean"
+            }
+          ],
+          "description": "Ghost fade-out for removed marks. Default `{ duration: 300, ease: 'smooth' }`."
+        },
+        "camera": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "duration": {
+                  "type": "number"
+                },
+                "ease": {
+                  "$ref": "#/definitions/AnimationEase"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "boolean"
+            }
+          ],
+          "description": "Camera flight easing. Default duration `'auto'` (derived from the zoom distance)."
+        },
+        "hover": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "duration": {
+                  "type": "number"
+                },
+                "ease": {
+                  "$ref": "#/definitions/AnimationEase"
+                }
+              },
+              "additionalProperties": false
+            },
+            {
+              "type": "boolean"
+            }
+          ],
+          "description": "Hover emphasis crossfade. Default `{ duration: 150, ease: 'smooth' }`."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Per-phase and per-behavior motion config for a graph.\n\nDEFAULT-ON semantics (deliberately different from charts, which are opt-in): omit `animation` → the resolver returns full defaults; `animation: false` → no choreography (but `layout.warmup` still applies); a per-phase `false` disables just that phase. Graphs are default-on because physics motion already exists on load and choreography reduces the chaos."
+    },
+    "GraphInteractionConfig": {
+      "type": "object",
+      "properties": {
+        "hover": {
+          "type": "object",
+          "properties": {
+            "mode": {
+              "type": "string",
+              "enum": [
+                "neighbors",
+                "category",
+                "node",
+                "none"
+              ]
+            },
+            "dimOpacity": {
+              "type": "number"
+            }
+          },
+          "additionalProperties": false,
+          "description": "Hover emphasis behavior. `neighbors` (default) lights the hovered node and its adjacency; `category` lights same-category nodes; `node` lights only the hovered node; `none` disables. `dimOpacity` (default 0.15) is the node dim tier. Named `mode` (not `highlight`) to avoid colliding with the three other meanings of \"highlight\" (the encoding value list, the `highlight()` verb)."
+        },
+        "select": {
+          "type": "object",
+          "properties": {
+            "flyTo": {
+              "type": "boolean"
+            }
+          },
+          "additionalProperties": false,
+          "description": "Selecting a node flies the camera to it. Default `false`."
+        },
+        "cursorRepulsion": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "object",
+              "properties": {
+                "radius": {
+                  "type": "number"
+                },
+                "strength": {
+                  "type": "number"
+                }
+              },
+              "additionalProperties": false
+            }
+          ],
+          "description": "Opt-in cursor repulsion (nodes drift away from the pointer). Disabled under `prefers-reduced-motion` and above the node-count gate."
+        },
+        "springyDrag": {
+          "type": "boolean",
+          "description": "Opt-in springy node drag (user-initiated; no reduced-motion gate)."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Interaction behavior for a graph (hover mode, select-fly, opt-in physics)."
+    },
     "SankeySpec": {
       "type": "object",
       "properties": {
@@ -17235,6 +18313,10 @@
           "type": "boolean",
           "description": "Whether to show the tryOpenData.ai watermark. Defaults to true."
         },
+        "points": {
+          "$ref": "#/definitions/MapPointsLayer",
+          "description": "Optional point/symbol layer rendered above choropleth features."
+        },
         "animation": {
           "$ref": "#/definitions/AnimationSpec",
           "description": "Animation configuration for entrance animations."
@@ -17276,7 +18358,7 @@
               "type": "null"
             }
           ],
-          "description": "Focus on specific feature(s). null clears focus from a prior story step."
+          "description": "Focus the camera. A feature id (or array) fits those features; `{ features, padding }` adds breathing room; `{ points: true, padding }` fits the points layer's cluster instead of any feature (use when points occupy a small part of a large feature, so fitting the feature would leave the cluster small and off-center); `{ points: { field, value }, padding }` fits only the matching point subset, so a story can pan between sub-clusters. null clears focus from a prior story step."
         }
       },
       "required": [
@@ -17342,20 +18424,62 @@
             "features"
           ],
           "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "points": {
+              "$ref": "#/definitions/MapPointsFocus"
+            },
+            "padding": {
+              "type": "number"
+            }
+          },
+          "required": [
+            "points"
+          ],
+          "additionalProperties": false
+        }
+      ]
+    },
+    "MapPointsFocus": {
+      "anyOf": [
+        {
+          "type": "boolean",
+          "const": true
+        },
+        {
+          "type": "object",
+          "properties": {
+            "field": {
+              "type": "string"
+            },
+            "value": {
+              "type": [
+                "string",
+                "number"
+              ]
+            }
+          },
+          "required": [
+            "field",
+            "value"
+          ],
+          "additionalProperties": false
         }
       ],
-      "description": "Focus target for map camera: feature id(s) to zoom/pan to."
+      "description": "Fit the point layer's cluster. `true` fits every point; `{ field, value }` fits only the points whose data row has `row[field] === value` (e.g. only the campuses rated \"F\"), which lets a story pan between sub-clusters."
     },
     "MapEncoding": {
       "type": "object",
       "properties": {
         "key": {
           "$ref": "#/definitions/EncodingChannel",
-          "description": "Join key field in the data (required). Maps data rows to geo features via geo.idField."
+          "description": "Join key field in the data. Required for choropleth; optional in basemap-only mode (points layer with empty data)."
         },
         "color": {
           "$ref": "#/definitions/EncodingChannel",
-          "description": "Color encoding (required, quantitative or nominal). Drives fill color of features."
+          "description": "Color encoding (quantitative or nominal). Drives fill color of features. Optional when a points layer is present (basemap-only mode)."
         },
         "tooltip": {
           "anyOf": [
@@ -17372,12 +18496,65 @@
           "description": "Tooltip encoding (optional)."
         }
       },
+      "additionalProperties": false,
+      "description": "Encoding channels specific to map visualizations."
+    },
+    "MapPointsLayer": {
+      "type": "object",
+      "properties": {
+        "data": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/DataRow"
+          },
+          "description": "Tabular data for the points. Independent of the choropleth data join."
+        },
+        "longitude": {
+          "$ref": "#/definitions/EncodingChannel",
+          "description": "Field holding longitude (x coordinate)."
+        },
+        "latitude": {
+          "$ref": "#/definitions/EncodingChannel",
+          "description": "Field holding latitude (y coordinate)."
+        },
+        "size": {
+          "$ref": "#/definitions/EncodingChannel",
+          "description": "Optional quantitative size encoding. Area-proportional: r proportional to sqrt(value). No size legend is rendered in v1; explain the scale in chrome.subtitle if needed."
+        },
+        "color": {
+          "$ref": "#/definitions/EncodingChannel",
+          "description": "Optional color encoding (nominal or quantitative). Independent scale from choropleth."
+        },
+        "tooltip": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/EncodingChannel"
+            },
+            {
+              "type": "array",
+              "items": {
+                "$ref": "#/definitions/EncodingChannel"
+              }
+            }
+          ],
+          "description": "Tooltip channel(s), same shape as MapEncoding.tooltip."
+        },
+        "key": {
+          "$ref": "#/definitions/EncodingChannel",
+          "description": "Stable id for event callbacks. Data-update transitions for points are not yet supported."
+        },
+        "opacity": {
+          "type": "number",
+          "description": "Fill opacity for point circles. Default 0.65. Range 0-1."
+        }
+      },
       "required": [
-        "key",
-        "color"
+        "data",
+        "longitude",
+        "latitude"
       ],
       "additionalProperties": false,
-      "description": "Encoding channels specific to map visualizations."
+      "description": "Point/symbol layer rendered above choropleth features."
     },
     "BarListSpec": {
       "type": "object",
@@ -17520,6 +18697,14 @@
           "$ref": "#/definitions/Chrome",
           "description": "Editorial chrome (title, subtitle, source, etc.)."
         },
+        "chromeLayout": {
+          "type": "string",
+          "enum": [
+            "subtract",
+            "grow"
+          ],
+          "description": "How chrome height interacts with the container height budget.\n\n- `'subtract'` (default): the container height is fixed and chrome text   (title/subtitle/source) is subtracted from it, shrinking the plot. This   is the historical behavior.\n- `'grow'`: the container height is treated as the *plot* budget, and the   rendered SVG grows taller by the measured chrome height. The plot keeps   its full budget (minus axis/padding overhead) regardless of how many   lines the title wraps to.\n\n`'grow'` is a no-op for faceted specs in this version."
+        },
         "title": {
           "anyOf": [
             {
@@ -17628,7 +18813,7 @@
           "items": {
             "type": "string"
           },
-          "description": "Series names to hide from rendering. Hidden series remain in the legend but are visually dimmed."
+          "description": "Series names to hide from rendering by default. This is the authored persistence target for legend visibility. Runtime legend toggles (legend-toggle edit events) layer on top of this via ephemeral runtime sets but never modify it."
         },
         "seriesStyles": {
           "type": "object",