@opendata-ai/openchart-core 8.0.0-rc.9 → 8.0.0

package/schema/vizspec.schema.json

@@ -27,13 +27,13 @@
           "$ref": "#/definitions/TileMapSpec"
         },
         {
-          "$ref": "#/definitions/MapSpec"
+          "$ref": "#/definitions/GeoMapSpec"
         },
         {
           "$ref": "#/definitions/BarListSpec"
         }
       ],
-      "description": "Top-level visualization spec: union discriminated by structural shape.\n\n- ChartSpec: has `mark` field (no `type`, no `layer`)\n- LayerSpec: has `layer` field\n- TableSpec: has `type: 'table'`\n- GraphSpec: has `type: 'graph'`\n- SankeySpec: has `type: 'sankey'`\n- TileMapSpec: has `type: 'tilemap'`\n- MapSpec: has `type: 'map'`\n- BarListSpec: has `type: 'barlist'`\n\nElection parliament (hemicycle) charts are `ChartSpec` with `mark: 'parliament'`, not a separate top-level type: seat data (party + seats) maps naturally onto encoding.color/y like arc and waffle, and riding the existing chart pipeline gets scales, legend, tooltips, a11y, and dark mode for free instead of a second bespoke compile path (see `packages/engine/src/charts/parliament/`)."
+      "description": "Top-level visualization spec: union discriminated by structural shape.\n\n- ChartSpec: has `mark` field (no `type`, no `layer`)\n- LayerSpec: has `layer` field\n- TableSpec: has `type: 'table'`\n- GraphSpec: has `type: 'graph'`\n- SankeySpec: has `type: 'sankey'`\n- TileMapSpec: has `type: 'tilemap'`\n- GeoMapSpec: has `type: 'map'`\n- BarListSpec: has `type: 'barlist'`\n\nElection parliament (hemicycle) charts are `ChartSpec` with `mark: 'parliament'`, not a separate top-level type: seat data (party + seats) maps naturally onto encoding.color/y like arc and waffle, and riding the existing chart pipeline gets scales, legend, tooltips, a11y, and dark mode for free instead of a second bespoke compile path (see `packages/engine/src/charts/parliament/`)."
     },
     "ChartSpec": {
       "anyOf": [
@@ -140,7 +140,7 @@
                         },
                         "size": {
                           "type": "number",
-                          "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                          "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                         },
                         "filled": {
                           "type": "boolean",
@@ -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",
@@ -409,7 +416,7 @@
                         },
                         "size": {
                           "type": "number",
-                          "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                          "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                         },
                         "filled": {
                           "type": "boolean",
@@ -450,8 +457,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",
@@ -678,7 +692,7 @@
                         },
                         "size": {
                           "type": "number",
-                          "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                          "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                         },
                         "filled": {
                           "type": "boolean",
@@ -719,8 +733,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",
@@ -947,7 +968,7 @@
                         },
                         "size": {
                           "type": "number",
-                          "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                          "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                         },
                         "filled": {
                           "type": "boolean",
@@ -988,8 +1009,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",
@@ -1216,7 +1244,7 @@
                         },
                         "size": {
                           "type": "number",
-                          "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                          "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                         },
                         "filled": {
                           "type": "boolean",
@@ -1257,8 +1285,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",
@@ -1485,7 +1520,7 @@
                         },
                         "size": {
                           "type": "number",
-                          "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                          "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                         },
                         "filled": {
                           "type": "boolean",
@@ -1526,8 +1561,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",
@@ -1754,7 +1796,7 @@
                         },
                         "size": {
                           "type": "number",
-                          "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                          "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                         },
                         "filled": {
                           "type": "boolean",
@@ -1795,8 +1837,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",
@@ -2023,7 +2072,7 @@
                         },
                         "size": {
                           "type": "number",
-                          "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                          "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                         },
                         "filled": {
                           "type": "boolean",
@@ -2064,8 +2113,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",
@@ -2292,7 +2348,7 @@
                         },
                         "size": {
                           "type": "number",
-                          "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                          "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                         },
                         "filled": {
                           "type": "boolean",
@@ -2333,8 +2389,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",
@@ -2561,7 +2624,7 @@
                         },
                         "size": {
                           "type": "number",
-                          "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                          "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                         },
                         "filled": {
                           "type": "boolean",
@@ -2602,8 +2665,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",
@@ -2830,7 +2900,7 @@
                         },
                         "size": {
                           "type": "number",
-                          "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                          "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                         },
                         "filled": {
                           "type": "boolean",
@@ -2871,8 +2941,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",
@@ -3099,7 +3176,7 @@
                         },
                         "size": {
                           "type": "number",
-                          "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                          "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                         },
                         "filled": {
                           "type": "boolean",
@@ -3140,8 +3217,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",
@@ -3368,7 +3452,7 @@
                         },
                         "size": {
                           "type": "number",
-                          "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                          "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                         },
                         "filled": {
                           "type": "boolean",
@@ -3409,8 +3493,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",
@@ -3637,7 +3728,7 @@
                         },
                         "size": {
                           "type": "number",
-                          "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                          "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                         },
                         "filled": {
                           "type": "boolean",
@@ -3678,8 +3769,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",
@@ -3906,7 +4004,7 @@
                         },
                         "size": {
                           "type": "number",
-                          "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                          "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                         },
                         "filled": {
                           "type": "boolean",
@@ -3947,8 +4045,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",
@@ -4175,7 +4280,7 @@
                         },
                         "size": {
                           "type": "number",
-                          "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                          "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                         },
                         "filled": {
                           "type": "boolean",
@@ -4216,8 +4321,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",
@@ -4484,6 +4596,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": {
@@ -4518,7 +4653,7 @@
               "$ref": "#/definitions/ValueDef"
             }
           ],
-          "description": "Size channel. Used by point/bubble charts to scale dot area by a quantitative field. Accepts a conditional definition to vary size based on data predicates, or a bare `{ value }` constant (VL aligned; expanded to `mark.size`)."
+          "description": "Size channel. Used by point/bubble charts to scale dots by a quantitative field, area-proportionally (sqrt curve). The units are dot RADII in px: `scale.range` defaults to [3, 30] for scatter, and a bare `{ value }` constant expands to `mark.size`, also a radius. This differs from Vega-Lite, where point size is an area in px^2 -- VL-scale values (60-900) are rejected by validation with the conversion. Accepts a conditional definition to vary size based on data predicates."
         },
         "detail": {
           "$ref": "#/definitions/EncodingChannel%3CDataRow%3E",
@@ -4583,6 +4718,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 +5235,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 +6033,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 +7089,7 @@
         "update": {
           "anyOf": [
             {
-              "$ref": "#/definitions/AnimationPhaseConfig"
+              "$ref": "#/definitions/UpdatePhaseConfig"
             },
             {
               "type": "boolean"
@@ -7022,6 +7170,36 @@
       "additionalProperties": false,
       "description": "Stagger configuration for sequential element reveal."
     },
+    "UpdatePhaseConfig": {
+      "type": "object",
+      "properties": {
+        "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": [
@@ -7183,7 +7361,7 @@
               "$ref": "#/definitions/ValueDef"
             }
           ],
-          "description": "Size channel. Used by point/bubble charts to scale dot area by a quantitative field. Accepts a conditional definition to vary size based on data predicates, or a bare `{ value }` constant (VL aligned; expanded to `mark.size`)."
+          "description": "Size channel. Used by point/bubble charts to scale dots by a quantitative field, area-proportionally (sqrt curve). The units are dot RADII in px: `scale.range` defaults to [3, 30] for scatter, and a bare `{ value }` constant expands to `mark.size`, also a radius. This differs from Vega-Lite, where point size is an area in px^2 -- VL-scale values (60-900) are rejected by validation with the conversion. Accepts a conditional definition to vary size based on data predicates."
         },
         "detail": {
           "$ref": "#/definitions/EncodingChannel%3CDataRow%3E",
@@ -7248,6 +7426,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": [
@@ -7294,7 +7480,7 @@
               "$ref": "#/definitions/ValueDef"
             }
           ],
-          "description": "Size channel. Used by point/bubble charts to scale dot area by a quantitative field. Accepts a conditional definition to vary size based on data predicates, or a bare `{ value }` constant (VL aligned; expanded to `mark.size`)."
+          "description": "Size channel. Used by point/bubble charts to scale dots by a quantitative field, area-proportionally (sqrt curve). The units are dot RADII in px: `scale.range` defaults to [3, 30] for scatter, and a bare `{ value }` constant expands to `mark.size`, also a radius. This differs from Vega-Lite, where point size is an area in px^2 -- VL-scale values (60-900) are rejected by validation with the conversion. Accepts a conditional definition to vary size based on data predicates."
         },
         "detail": {
           "$ref": "#/definitions/EncodingChannel%3CDataRow%3E",
@@ -7359,6 +7545,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": [
@@ -7405,7 +7599,7 @@
               "$ref": "#/definitions/ValueDef"
             }
           ],
-          "description": "Size channel. Used by point/bubble charts to scale dot area by a quantitative field. Accepts a conditional definition to vary size based on data predicates, or a bare `{ value }` constant (VL aligned; expanded to `mark.size`)."
+          "description": "Size channel. Used by point/bubble charts to scale dots by a quantitative field, area-proportionally (sqrt curve). The units are dot RADII in px: `scale.range` defaults to [3, 30] for scatter, and a bare `{ value }` constant expands to `mark.size`, also a radius. This differs from Vega-Lite, where point size is an area in px^2 -- VL-scale values (60-900) are rejected by validation with the conversion. Accepts a conditional definition to vary size based on data predicates."
         },
         "detail": {
           "$ref": "#/definitions/EncodingChannel%3CDataRow%3E",
@@ -7470,6 +7664,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": [
@@ -7516,7 +7718,7 @@
               "$ref": "#/definitions/ValueDef"
             }
           ],
-          "description": "Size channel. Used by point/bubble charts to scale dot area by a quantitative field. Accepts a conditional definition to vary size based on data predicates, or a bare `{ value }` constant (VL aligned; expanded to `mark.size`)."
+          "description": "Size channel. Used by point/bubble charts to scale dots by a quantitative field, area-proportionally (sqrt curve). The units are dot RADII in px: `scale.range` defaults to [3, 30] for scatter, and a bare `{ value }` constant expands to `mark.size`, also a radius. This differs from Vega-Lite, where point size is an area in px^2 -- VL-scale values (60-900) are rejected by validation with the conversion. Accepts a conditional definition to vary size based on data predicates."
         },
         "detail": {
           "$ref": "#/definitions/EncodingChannel%3CDataRow%3E",
@@ -7581,6 +7783,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": [
@@ -7627,7 +7837,7 @@
               "$ref": "#/definitions/ValueDef"
             }
           ],
-          "description": "Size channel. Used by point/bubble charts to scale dot area by a quantitative field. Accepts a conditional definition to vary size based on data predicates, or a bare `{ value }` constant (VL aligned; expanded to `mark.size`)."
+          "description": "Size channel. Used by point/bubble charts to scale dots by a quantitative field, area-proportionally (sqrt curve). The units are dot RADII in px: `scale.range` defaults to [3, 30] for scatter, and a bare `{ value }` constant expands to `mark.size`, also a radius. This differs from Vega-Lite, where point size is an area in px^2 -- VL-scale values (60-900) are rejected by validation with the conversion. Accepts a conditional definition to vary size based on data predicates."
         },
         "detail": {
           "$ref": "#/definitions/EncodingChannel%3CDataRow%3E",
@@ -7692,6 +7902,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": [
@@ -7738,7 +7956,7 @@
               "$ref": "#/definitions/ValueDef"
             }
           ],
-          "description": "Size channel. Used by point/bubble charts to scale dot area by a quantitative field. Accepts a conditional definition to vary size based on data predicates, or a bare `{ value }` constant (VL aligned; expanded to `mark.size`)."
+          "description": "Size channel. Used by point/bubble charts to scale dots by a quantitative field, area-proportionally (sqrt curve). The units are dot RADII in px: `scale.range` defaults to [3, 30] for scatter, and a bare `{ value }` constant expands to `mark.size`, also a radius. This differs from Vega-Lite, where point size is an area in px^2 -- VL-scale values (60-900) are rejected by validation with the conversion. Accepts a conditional definition to vary size based on data predicates."
         },
         "detail": {
           "$ref": "#/definitions/EncodingChannel%3CDataRow%3E",
@@ -7803,6 +8021,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": [
@@ -7849,7 +8075,7 @@
               "$ref": "#/definitions/ValueDef"
             }
           ],
-          "description": "Size channel. Used by point/bubble charts to scale dot area by a quantitative field. Accepts a conditional definition to vary size based on data predicates, or a bare `{ value }` constant (VL aligned; expanded to `mark.size`)."
+          "description": "Size channel. Used by point/bubble charts to scale dots by a quantitative field, area-proportionally (sqrt curve). The units are dot RADII in px: `scale.range` defaults to [3, 30] for scatter, and a bare `{ value }` constant expands to `mark.size`, also a radius. This differs from Vega-Lite, where point size is an area in px^2 -- VL-scale values (60-900) are rejected by validation with the conversion. Accepts a conditional definition to vary size based on data predicates."
         },
         "detail": {
           "$ref": "#/definitions/EncodingChannel%3CDataRow%3E",
@@ -7914,6 +8140,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,
@@ -7956,7 +8190,7 @@
               "$ref": "#/definitions/ValueDef"
             }
           ],
-          "description": "Size channel. Used by point/bubble charts to scale dot area by a quantitative field. Accepts a conditional definition to vary size based on data predicates, or a bare `{ value }` constant (VL aligned; expanded to `mark.size`)."
+          "description": "Size channel. Used by point/bubble charts to scale dots by a quantitative field, area-proportionally (sqrt curve). The units are dot RADII in px: `scale.range` defaults to [3, 30] for scatter, and a bare `{ value }` constant expands to `mark.size`, also a radius. This differs from Vega-Lite, where point size is an area in px^2 -- VL-scale values (60-900) are rejected by validation with the conversion. Accepts a conditional definition to vary size based on data predicates."
         },
         "detail": {
           "$ref": "#/definitions/EncodingChannel%3CDataRow%3E",
@@ -8021,6 +8255,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": [
@@ -8064,7 +8306,7 @@
               "$ref": "#/definitions/ValueDef"
             }
           ],
-          "description": "Size channel. Used by point/bubble charts to scale dot area by a quantitative field. Accepts a conditional definition to vary size based on data predicates, or a bare `{ value }` constant (VL aligned; expanded to `mark.size`)."
+          "description": "Size channel. Used by point/bubble charts to scale dots by a quantitative field, area-proportionally (sqrt curve). The units are dot RADII in px: `scale.range` defaults to [3, 30] for scatter, and a bare `{ value }` constant expands to `mark.size`, also a radius. This differs from Vega-Lite, where point size is an area in px^2 -- VL-scale values (60-900) are rejected by validation with the conversion. Accepts a conditional definition to vary size based on data predicates."
         },
         "detail": {
           "$ref": "#/definitions/EncodingChannel%3CDataRow%3E",
@@ -8129,6 +8371,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": [
@@ -8174,7 +8424,7 @@
               "$ref": "#/definitions/ValueDef"
             }
           ],
-          "description": "Size channel. Used by point/bubble charts to scale dot area by a quantitative field. Accepts a conditional definition to vary size based on data predicates, or a bare `{ value }` constant (VL aligned; expanded to `mark.size`)."
+          "description": "Size channel. Used by point/bubble charts to scale dots by a quantitative field, area-proportionally (sqrt curve). The units are dot RADII in px: `scale.range` defaults to [3, 30] for scatter, and a bare `{ value }` constant expands to `mark.size`, also a radius. This differs from Vega-Lite, where point size is an area in px^2 -- VL-scale values (60-900) are rejected by validation with the conversion. Accepts a conditional definition to vary size based on data predicates."
         },
         "detail": {
           "$ref": "#/definitions/EncodingChannel%3CDataRow%3E",
@@ -8239,6 +8489,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": [
@@ -8284,7 +8542,7 @@
               "$ref": "#/definitions/ValueDef"
             }
           ],
-          "description": "Size channel. Used by point/bubble charts to scale dot area by a quantitative field. Accepts a conditional definition to vary size based on data predicates, or a bare `{ value }` constant (VL aligned; expanded to `mark.size`)."
+          "description": "Size channel. Used by point/bubble charts to scale dots by a quantitative field, area-proportionally (sqrt curve). The units are dot RADII in px: `scale.range` defaults to [3, 30] for scatter, and a bare `{ value }` constant expands to `mark.size`, also a radius. This differs from Vega-Lite, where point size is an area in px^2 -- VL-scale values (60-900) are rejected by validation with the conversion. Accepts a conditional definition to vary size based on data predicates."
         },
         "detail": {
           "$ref": "#/definitions/EncodingChannel%3CDataRow%3E",
@@ -8349,6 +8607,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": [
@@ -8395,7 +8661,7 @@
               "$ref": "#/definitions/ValueDef"
             }
           ],
-          "description": "Size channel. Used by point/bubble charts to scale dot area by a quantitative field. Accepts a conditional definition to vary size based on data predicates, or a bare `{ value }` constant (VL aligned; expanded to `mark.size`)."
+          "description": "Size channel. Used by point/bubble charts to scale dots by a quantitative field, area-proportionally (sqrt curve). The units are dot RADII in px: `scale.range` defaults to [3, 30] for scatter, and a bare `{ value }` constant expands to `mark.size`, also a radius. This differs from Vega-Lite, where point size is an area in px^2 -- VL-scale values (60-900) are rejected by validation with the conversion. Accepts a conditional definition to vary size based on data predicates."
         },
         "detail": {
           "$ref": "#/definitions/EncodingChannel%3CDataRow%3E",
@@ -8460,6 +8726,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": [
@@ -8506,7 +8780,7 @@
               "$ref": "#/definitions/ValueDef"
             }
           ],
-          "description": "Size channel. Used by point/bubble charts to scale dot area by a quantitative field. Accepts a conditional definition to vary size based on data predicates, or a bare `{ value }` constant (VL aligned; expanded to `mark.size`)."
+          "description": "Size channel. Used by point/bubble charts to scale dots by a quantitative field, area-proportionally (sqrt curve). The units are dot RADII in px: `scale.range` defaults to [3, 30] for scatter, and a bare `{ value }` constant expands to `mark.size`, also a radius. This differs from Vega-Lite, where point size is an area in px^2 -- VL-scale values (60-900) are rejected by validation with the conversion. Accepts a conditional definition to vary size based on data predicates."
         },
         "detail": {
           "$ref": "#/definitions/EncodingChannel%3CDataRow%3E",
@@ -8571,6 +8845,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,
@@ -8603,7 +8885,7 @@
               "$ref": "#/definitions/ValueDef"
             }
           ],
-          "description": "Size channel. Used by point/bubble charts to scale dot area by a quantitative field. Accepts a conditional definition to vary size based on data predicates, or a bare `{ value }` constant (VL aligned; expanded to `mark.size`)."
+          "description": "Size channel. Used by point/bubble charts to scale dots by a quantitative field, area-proportionally (sqrt curve). The units are dot RADII in px: `scale.range` defaults to [3, 30] for scatter, and a bare `{ value }` constant expands to `mark.size`, also a radius. This differs from Vega-Lite, where point size is an area in px^2 -- VL-scale values (60-900) are rejected by validation with the conversion. Accepts a conditional definition to vary size based on data predicates."
         },
         "detail": {
           "$ref": "#/definitions/EncodingChannel%3CDataRow%3E",
@@ -8668,6 +8950,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": [
@@ -8711,7 +9001,7 @@
               "$ref": "#/definitions/ValueDef"
             }
           ],
-          "description": "Size channel. Used by point/bubble charts to scale dot area by a quantitative field. Accepts a conditional definition to vary size based on data predicates, or a bare `{ value }` constant (VL aligned; expanded to `mark.size`)."
+          "description": "Size channel. Used by point/bubble charts to scale dots by a quantitative field, area-proportionally (sqrt curve). The units are dot RADII in px: `scale.range` defaults to [3, 30] for scatter, and a bare `{ value }` constant expands to `mark.size`, also a radius. This differs from Vega-Lite, where point size is an area in px^2 -- VL-scale values (60-900) are rejected by validation with the conversion. Accepts a conditional definition to vary size based on data predicates."
         },
         "detail": {
           "$ref": "#/definitions/EncodingChannel%3CDataRow%3E",
@@ -8776,6 +9066,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 +9165,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 +9200,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": [
@@ -9022,7 +9320,7 @@
                     },
                     "size": {
                       "type": "number",
-                      "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                      "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                     },
                     "filled": {
                       "type": "boolean",
@@ -9063,8 +9361,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",
@@ -9202,6 +9507,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 +9623,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",
@@ -9471,7 +9784,7 @@
                     },
                     "size": {
                       "type": "number",
-                      "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                      "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                     },
                     "filled": {
                       "type": "boolean",
@@ -9512,8 +9825,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",
@@ -9651,6 +9971,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 +10087,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",
@@ -9920,7 +10248,7 @@
                     },
                     "size": {
                       "type": "number",
-                      "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                      "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                     },
                     "filled": {
                       "type": "boolean",
@@ -9961,8 +10289,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",
@@ -10100,6 +10435,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 +10551,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",
@@ -10369,7 +10712,7 @@
                     },
                     "size": {
                       "type": "number",
-                      "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                      "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                     },
                     "filled": {
                       "type": "boolean",
@@ -10410,8 +10753,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",
@@ -10549,6 +10899,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 +11015,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",
@@ -10818,7 +11176,7 @@
                     },
                     "size": {
                       "type": "number",
-                      "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                      "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                     },
                     "filled": {
                       "type": "boolean",
@@ -10859,8 +11217,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",
@@ -10998,6 +11363,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 +11479,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",
@@ -11267,7 +11640,7 @@
                     },
                     "size": {
                       "type": "number",
-                      "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                      "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                     },
                     "filled": {
                       "type": "boolean",
@@ -11308,8 +11681,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",
@@ -11447,6 +11827,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 +11943,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",
@@ -11716,7 +12104,7 @@
                     },
                     "size": {
                       "type": "number",
-                      "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                      "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                     },
                     "filled": {
                       "type": "boolean",
@@ -11757,8 +12145,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",
@@ -11896,6 +12291,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 +12407,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",
@@ -12165,7 +12568,7 @@
                     },
                     "size": {
                       "type": "number",
-                      "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                      "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                     },
                     "filled": {
                       "type": "boolean",
@@ -12206,8 +12609,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",
@@ -12345,6 +12755,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 +12871,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",
@@ -12614,7 +13032,7 @@
                     },
                     "size": {
                       "type": "number",
-                      "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                      "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                     },
                     "filled": {
                       "type": "boolean",
@@ -12655,8 +13073,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",
@@ -12794,6 +13219,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 +13335,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",
@@ -13063,7 +13496,7 @@
                     },
                     "size": {
                       "type": "number",
-                      "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                      "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                     },
                     "filled": {
                       "type": "boolean",
@@ -13104,8 +13537,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",
@@ -13243,6 +13683,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 +13799,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",
@@ -13512,7 +13960,7 @@
                     },
                     "size": {
                       "type": "number",
-                      "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                      "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                     },
                     "filled": {
                       "type": "boolean",
@@ -13553,8 +14001,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",
@@ -13692,6 +14147,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 +14263,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",
@@ -13961,7 +14424,7 @@
                     },
                     "size": {
                       "type": "number",
-                      "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                      "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                     },
                     "filled": {
                       "type": "boolean",
@@ -14002,8 +14465,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",
@@ -14141,6 +14611,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 +14727,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",
@@ -14410,7 +14888,7 @@
                     },
                     "size": {
                       "type": "number",
-                      "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                      "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                     },
                     "filled": {
                       "type": "boolean",
@@ -14451,8 +14929,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",
@@ -14590,6 +15075,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 +15191,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",
@@ -14859,7 +15352,7 @@
                     },
                     "size": {
                       "type": "number",
-                      "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                      "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                     },
                     "filled": {
                       "type": "boolean",
@@ -14900,8 +15393,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",
@@ -15039,6 +15539,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 +15655,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",
@@ -15308,7 +15816,7 @@
                     },
                     "size": {
                       "type": "number",
-                      "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                      "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                     },
                     "filled": {
                       "type": "boolean",
@@ -15349,8 +15857,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",
@@ -15488,6 +16003,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 +16119,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",
@@ -15757,7 +16280,7 @@
                     },
                     "size": {
                       "type": "number",
-                      "description": "Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band."
+                      "description": "Bar/column marks: fixed bar thickness in pixels. When set, bars are this height (horizontal) or width (vertical), centered within the band.\n\nPoint marks: the dot RADIUS in pixels (default 5, typical 2-12). This is NOT Vega-Lite's point `size`, which is an area in px^2 -- a VL size of 110 corresponds to `size: 6` here (r = sqrt(area / pi)). Validation rejects values above 50 with the conversion."
                     },
                     "filled": {
                       "type": "boolean",
@@ -15798,8 +16321,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",
@@ -15937,6 +16467,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 +16583,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 +16736,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 +16771,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 +17108,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 +17194,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 +17215,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 +17238,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 +17327,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 +17391,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": {
@@ -17192,7 +17982,7 @@
       ],
       "description": "Sequential color palette names available for tile maps."
     },
-    "MapSpec": {
+    "GeoMapSpec": {
       "type": "object",
       "properties": {
         "type": {
@@ -17201,7 +17991,7 @@
           "description": "Discriminant: always \"map\"."
         },
         "geo": {
-          "$ref": "#/definitions/MapGeo",
+          "$ref": "#/definitions/GeoMapGeo",
           "description": "Geo configuration: TopoJSON features, join key, and projection."
         },
         "data": {
@@ -17212,7 +18002,7 @@
           "description": "Tabular data to join to geo features."
         },
         "encoding": {
-          "$ref": "#/definitions/MapEncoding",
+          "$ref": "#/definitions/GeoMapEncoding",
           "description": "Encoding channels mapping data fields to visual properties."
         },
         "chrome": {
@@ -17236,7 +18026,7 @@
           "description": "Whether to show the tryOpenData.ai watermark. Defaults to true."
         },
         "points": {
-          "$ref": "#/definitions/MapPointsLayer",
+          "$ref": "#/definitions/GeoMapPointsLayer",
           "description": "Optional point/symbol layer rendered above choropleth features."
         },
         "animation": {
@@ -17257,7 +18047,7 @@
       ],
       "additionalProperties": false
     },
-    "MapGeo": {
+    "GeoMapGeo": {
       "type": "object",
       "properties": {
         "features": {
@@ -17268,13 +18058,13 @@
           "description": "Field in the TopoJSON feature properties to use as the join key. Defaults to 'id'."
         },
         "projection": {
-          "$ref": "#/definitions/MapProjection",
+          "$ref": "#/definitions/GeoMapProjection",
           "description": "Map projection. Defaults to 'albersUsa'."
         },
         "focus": {
           "anyOf": [
             {
-              "$ref": "#/definitions/MapFocus"
+              "$ref": "#/definitions/GeoMapFocus"
             },
             {
               "type": "null"
@@ -17289,7 +18079,7 @@
       "additionalProperties": false,
       "description": "Geo configuration for map specs."
     },
-    "MapProjection": {
+    "GeoMapProjection": {
       "type": "string",
       "enum": [
         "albersUsa",
@@ -17299,7 +18089,7 @@
       ],
       "description": "Supported map projections."
     },
-    "MapFocus": {
+    "GeoMapFocus": {
       "anyOf": [
         {
           "type": "string"
@@ -17351,7 +18141,7 @@
           "type": "object",
           "properties": {
             "points": {
-              "$ref": "#/definitions/MapPointsFocus"
+              "$ref": "#/definitions/GeoMapPointsFocus"
             },
             "padding": {
               "type": "number"
@@ -17364,7 +18154,7 @@
         }
       ]
     },
-    "MapPointsFocus": {
+    "GeoMapPointsFocus": {
       "anyOf": [
         {
           "type": "boolean",
@@ -17392,7 +18182,7 @@
       ],
       "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": {
+    "GeoMapEncoding": {
       "type": "object",
       "properties": {
         "key": {
@@ -17421,7 +18211,7 @@
       "additionalProperties": false,
       "description": "Encoding channels specific to map visualizations."
     },
-    "MapPointsLayer": {
+    "GeoMapPointsLayer": {
       "type": "object",
       "properties": {
         "data": {
@@ -17459,7 +18249,7 @@
               }
             }
           ],
-          "description": "Tooltip channel(s), same shape as MapEncoding.tooltip."
+          "description": "Tooltip channel(s), same shape as GeoMapEncoding.tooltip."
         },
         "key": {
           "$ref": "#/definitions/EncodingChannel",
@@ -17619,6 +18409,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": [
             {
@@ -17727,7 +18525,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",