ggaction 0.0.17 → 0.0.18

package/types/program.d.ts

@@ -7,6 +7,7 @@ export interface TextMeasurement {
   readonly fontFamily: string;
   readonly fontSize: number;
   readonly fontWeight: TextMetricFontWeight;
+  readonly fontStyle?: "normal" | "italic";
   readonly width: number;
 }
 export interface TextMetricsProfile {
@@ -18,6 +19,11 @@ export interface ApplyTextMetricsOptions { profile: TextMetricsProfile; }
 
 export type ThemeName = "light" | "dark";
 export interface ThemeTokens {
+  axisLabel?: string;
+  axisLabelFontFamily?: string;
+  axisTitleFontFamily?: string;
+  axisLabelFontSize?: number;
+  axisTitleFontSize?: number;
   background: string;
   mark: string;
   text: string;
@@ -162,6 +168,8 @@ export interface EditCompositionLayoutOptions {
   gap?: number;
   align?: CompositionAlign;
   padding?: number | CompositionPadding;
+  /** Interpret gap between child canvases (default) or inner plot regions. */
+  spacing?: "canvas" | "plot";
 }
 export interface ReplaceCompositionChildOptions {
   target: string;
@@ -208,6 +216,9 @@ export interface FacetOptions {
   padding?: number | CompositionPadding;
   scales?: FacetScaleResolutions;
   guides?: FacetGuideOptions;
+  headers?: FacetHeadersOptions;
+  /** Interpret gap between child canvases (default) or inner plot regions. */
+  spacing?: "canvas" | "plot";
 }
 export interface FacetGridRole {
   field: string;
@@ -224,6 +235,9 @@ export interface FacetGridOptions {
   padding?: number | CompositionPadding;
   scales?: FacetScaleResolutions;
   guides?: FacetGuideOptions;
+  headers?: FacetHeadersOptions;
+  /** Interpret gap between child canvases (default) or inner plot regions. */
+  spacing?: "canvas" | "plot";
 }
 export interface RepeatChartsOptions {
   id?: string;
@@ -236,6 +250,9 @@ export interface RepeatChartsOptions {
   padding?: number | CompositionPadding;
   scales?: FacetScaleResolutions;
   guides?: FacetGuideOptions;
+  headers?: FacetHeadersOptions;
+  /** Interpret gap between child canvases (default) or inner plot regions. */
+  spacing?: "canvas" | "plot";
 }
 export interface EditFacetSourceOptions { program: ChartProgram; }
 export interface EditFacetHeadersOptions {
@@ -249,6 +266,10 @@ export interface EditFacetHeadersOptions {
   side?: FacetHeaderSide;
   align?: FacetHeaderAlign;
 }
+export type FacetHeadersOptions = Omit<EditFacetHeadersOptions, "role" | "side"> & {
+  row?: Omit<EditFacetHeadersOptions, "role">;
+  column?: Omit<EditFacetHeadersOptions, "role">;
+};
 export type FacetHeaderRole = "all" | "row" | "column";
 export type FacetHeaderSide = "top" | "bottom" | "left" | "right";
 export type FacetHeaderAlign = "start" | "center" | "end";
@@ -265,6 +286,7 @@ export interface FacetCompositionSpec {
   readonly type: "facet";
   readonly children: readonly string[];
   readonly columns: number;
+  readonly spacing?: "canvas" | "plot";
   readonly gap: number;
   readonly align: CompositionAlign;
   readonly padding: Readonly<Required<CompositionPadding>>;
@@ -389,6 +411,7 @@ export type DatasetRegressionTransform = {
       method: "linear";
       degree?: never;
       span?: never;
+      robustIterations?: never;
     } & ({ interval: false; confidenceMethod?: never; level?: never; confidence?: never } | ({ interval: "mean" | "prediction" } & (
       | { confidenceMethod: ConfidenceIntervalMethod; level: number; confidence?: never }
       | { confidence: number; confidenceMethod?: never; level?: never }
@@ -397,6 +420,7 @@ export type DatasetRegressionTransform = {
       method: "polynomial";
       degree: number;
       span?: never;
+      robustIterations?: never;
     } & ({ interval: false; confidenceMethod?: never; level?: never; confidence?: never } | ({ interval: "mean" | "prediction" } & (
       | { confidenceMethod: ConfidenceIntervalMethod; level: number; confidence?: never }
       | { confidence: number; confidenceMethod?: never; level?: never }
@@ -404,6 +428,7 @@ export type DatasetRegressionTransform = {
   | {
       method: "loess";
       span: number;
+      robustIterations?: number;
       degree?: never;
       confidenceMethod?: never;
       level?: never;
@@ -761,11 +786,28 @@ export interface DatasetFoldTransform {
     readonly value: string;
   };
 }
+export type ParseTimeFormat = "auto" | "%Y-%m-%d" | "%d/%m/%Y" | "%m/%d/%Y";
 export type ComputedExpression =
   | { readonly field: string }
   | { readonly constant: number | string | boolean | null }
   | {
-      readonly op: "negate" | "absolute" | "log" | "sqrt" | "not" | "isNull";
+      readonly op: "getPath";
+      readonly operand: { readonly field: string };
+      readonly path: readonly [string, ...string[]];
+    }
+  | {
+      readonly op: "replaceLiteral";
+      readonly operand: ComputedExpression;
+      readonly search: string;
+      readonly replacement: string;
+    }
+  | {
+      readonly op: "parseTime";
+      readonly operand: ComputedExpression;
+      readonly format?: ParseTimeFormat;
+    }
+  | {
+      readonly op: "negate" | "absolute" | "log" | "sqrt" | "not" | "isNull" | "toNumber";
       readonly operand: ComputedExpression;
     }
   | {
@@ -852,6 +894,7 @@ type DatasetImputedBaseTransform = {
   readonly maxGap?: number;
 };
 export type DatasetImputedTransform = DatasetImputedBaseTransform & (
+  | { readonly method: "mean"; readonly value?: never; readonly sortBy: readonly DatasetWindowSort[]; }
   | {
       readonly method: "constant";
       readonly value: DatasetScalar;
@@ -1082,6 +1125,10 @@ export type StrokeStyleDetails = {
 };
 export type RectStyleDetails = StrokeStyleDetails & {
   cornerRadius?: number;
+  cornerRadiusTopLeft?: number;
+  cornerRadiusTopRight?: number;
+  cornerRadiusBottomRight?: number;
+  cornerRadiusBottomLeft?: number;
 };
 export type PaletteName =
   | "accent"
@@ -1156,6 +1203,7 @@ export interface DatasetFieldLineage {
   readonly role: string;
 }
 export interface DatasetSchemaField {
+  /** Lossless stored row key; empty names cannot be used as action field references. */
   readonly name: string;
   readonly storageType: DatasetStorageType;
   readonly nullable: boolean;
@@ -1169,6 +1217,7 @@ export interface DatasetSchema {
   readonly fields: readonly DatasetSchemaField[];
 }
 export interface SourceSchemaField {
+  /** Exact source row key, including an empty string or whitespace. */
   name: string;
   storageType: Exclude<DatasetStorageType, "unknown" | "mixed">;
   nullable?: boolean;
@@ -1240,6 +1289,15 @@ export interface CanvasOptions {
   height?: number;
   background?: string;
   margin?: number | Partial<Record<"top" | "right" | "bottom" | "left", number>>;
+  /** Exact inner dimensions with automatic outer guide margins; false disables this mode. */
+  plot?: { width: number; height: number } | false;
+  /** Optional inner plot outline. Defaults off; an object replaces the complete style on edit. */
+  plotBorder?: false | {
+    /** Non-empty color string. Defaults to #ddd. */
+    color?: string;
+    /** Positive finite width smaller than both plot dimensions. Defaults to 1. */
+    lineWidth?: number;
+  };
 }
 
 export interface FitCanvasOptions {
@@ -1261,7 +1319,7 @@ export type RotationUnit = "radians" | "degrees";
 export type RotationInput = number | { value: number; unit: RotationUnit };
 type ValueFormatDigit = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
 type ValueFormatPrecision = ValueFormatDigit | 10 | 11 | 12 | `0${ValueFormatDigit}`;
-type TimeAxisDirective = "Y" | "m" | "d" | "b";
+type TimeAxisDirective = "Y" | "m" | "d" | "b" | "H" | "M" | "S" | "L";
 export type NumericFormatString = `.${ValueFormatPrecision}${"f" | "%" | "e"}`;
 export type UtcFormatString = `${string}%${TimeAxisDirective}${string}`;
 export type ValueFormat = "auto" | NumericFormatString | UtcFormatString;
@@ -1277,6 +1335,10 @@ export interface AxisLineStyleOptions {
 export interface AxisTickStyleOptions extends AxisLineStyleOptions {
   length?: number;
 }
+export interface CartesianAxisTickStyleOptions extends AxisTickStyleOptions {
+  /** Signed logical pixels along the axis: positive right for x, down for y. */
+  alongOffset?: number;
+}
 export interface AxisLabelStyleOptions {
   offset?: number;
   format?: AxisFormat;
@@ -1285,6 +1347,18 @@ export interface AxisLabelStyleOptions {
   fontFamily?: string;
   fontWeight?: string | number;
 }
+export type CartesianAxisLabelColorMap = ReadonlyArray<Readonly<{
+  value: DatasetScalar;
+  color: string;
+}>>;
+export interface CartesianAxisLabelStyleOptions extends AxisLabelStyleOptions {
+  /** Typed raw-tick color overrides; missing entries use color. Auto removes the map. */
+  colorMap?: CartesianAxisLabelColorMap | "auto";
+  /** Keep unrotated label bounds inside the mapped axis span; defaults to false. */
+  flush?: boolean;
+  /** Signed displacement from the mapped tick position, independent of outward offset. */
+  alongOffset?: number;
+}
 export interface AxisLabelLayoutOptions {
   /** Legacy numbers are radians; structured values make radians or degrees explicit. */
   rotation?: RotationInput;
@@ -1300,10 +1374,11 @@ export interface AxisTicksAndLabelsOptions<P extends string> {
   position?: P;
   count?: number;
   values?: readonly AxisValue[];
-  ticks?: AxisTickStyleOptions;
-  labels?: AxisLabelStyleOptions & AxisLabelLayoutOptions & DisplayLabelOptions;
+  ticks?: CartesianAxisTickStyleOptions;
+  labels?: CartesianAxisLabelStyleOptions & AxisLabelLayoutOptions & DisplayLabelOptions;
 }
 export interface AxisTitleOptions<P extends string> {
+  /** Hard breaks retain ordered centered lines, spaced at 1.2 times fontSize. */
   text?: string;
   scale?: string;
   position?: P;
@@ -1334,14 +1409,15 @@ export interface CreateAxesOptions {
   radius?: false | CompleteRadialAxisOptions;
 }
 export interface AxisTickOptions<P extends string>
-  extends AxisTickStyleOptions {
+  extends CartesianAxisTickStyleOptions {
   scale?: string;
   position?: P;
   count?: number;
   values?: readonly AxisValue[];
 }
+/** Cartesian label maps use typed category values or finite numeric/timestamp keys on continuous scales. Empty mapped labels are omitted without removing ticks. */
 export interface AxisLabelOptions<P extends string>
-  extends AxisLabelStyleOptions, AxisLabelLayoutOptions, DisplayLabelOptions {
+  extends CartesianAxisLabelStyleOptions, AxisLabelLayoutOptions, DisplayLabelOptions {
   scale?: string;
   position?: P;
   count?: number;
@@ -1464,17 +1540,29 @@ export interface EditRadialAxisOptions
 }
 
 export interface GridDirectionOptions {
+  /** Signed logical pixels along the scale: vertical lines right, horizontal lines down. */
+  alongOffset?: number;
+  /** Grid draw order relative to marks at zero: positive above, nonpositive behind. */
+  zIndex?: number;
+  /** Band centers by default; boundary draws both edges of each selected band. */
+  bandPosition?: "center" | "boundary";
   scale?: string;
   coordinate?: string;
   count?: number;
-  values?: readonly number[];
+  values?: readonly CategoryValue[];
   color?: string;
   lineWidth?: number;
   strokeDash?: readonly number[];
 }
 export interface EditGridOptions {
+  /** Absolute signed logical-pixel displacement; omission preserves the current value. */
+  alongOffset?: number;
+  /** Preserve omitted order; finite values sort Cartesian grids relative to marks at zero. */
+  zIndex?: number;
+  /** Band centers by default; boundary draws both edges of each selected band. */
+  bandPosition?: "center" | "boundary";
   count?: number;
-  values?: readonly number[] | "auto";
+  values?: readonly CategoryValue[] | "auto";
   color?: string;
   lineWidth?: number;
   strokeDash?: readonly number[];
@@ -1521,7 +1609,7 @@ type CartesianAxesOptions = Omit<
   coordinate?: { id?: string; type?: "auto" | "cartesian" };
 };
 type CAxisTicks<P extends string> = Omit<AxisTicksAndLabelsOptions<P>, "labels"> & {
-  labels?: AxisLabelStyleOptions & AxisLabelLayoutOptions;
+  labels?: CartesianAxisLabelStyleOptions & AxisLabelLayoutOptions & DisplayLabelOptions;
 };
 type CAxis<P extends string> = Omit<CompleteAxisOptions<P>, "ticksAndLabels"> & {
   ticksAndLabels?: false | Omit<CAxisTicks<P>, "scale" | "position">;
@@ -1531,11 +1619,14 @@ type CAxes = Omit<CartesianAxesOptions, "x" | "y"> & {
   y?: false | CAxis<YAxisPosition>;
 };
 type CartesianGridOptions = Pick<CreateGridOptions, "horizontal" | "vertical">;
-type FilledMarkLegendOptions = Omit<LegendOptions, "symbol"> & {
-  symbol?: "auto"
-    | { width?: number; height?: number; stroke?: string; strokeWidth?: number }
-    | { layers: readonly LegendSymbolLayer[] };
-};
+type FilledLegendSymbolRecipe = "auto"
+  | { width?: number; height?: number; stroke?: string; strokeWidth?: number }
+  | { layers: readonly LegendSymbolLayer[] };
+type FilledMarkLegendOptions = Omit<LegendOptions, "symbol" | "representation"> & (
+  | { representation?: "gradient"; symbol?: FilledLegendSymbolRecipe }
+  | { representation: "symbols"; symbol?: "auto" | { type?: "point"; radius?: number; stroke?: string; strokeWidth?: number } }
+);
+type DistributiveLegendOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
 type CategoricalLegendTextOptions = {
   offset?: number;
   color?: string;
@@ -1546,7 +1637,7 @@ type CategoricalLegendTextOptions = {
 };
 type PathLegendOptions = Omit<
   LegendOptions,
-  "symbol" | "gradient" | "count" | "values" | "labels"
+  "symbol" | "gradient" | "count" | "values" | "labels" | "representation"
 > & {
   symbol?: "auto" | { length?: number; lineWidth?: number }
     | { layers: readonly LegendSymbolLayer[] };
@@ -1555,7 +1646,7 @@ type PathLegendOptions = Omit<
 type CartesianGuideOptions = {
   axes?: false | CartesianAxesOptions;
   grid?: false | CartesianGridOptions;
-  legend?: false | (Omit<FilledMarkLegendOptions, "order"> & { order?: CartesianLegendOrder });
+  legend?: false | (DistributiveLegendOmit<FilledMarkLegendOptions, "order"> & { order?: CartesianLegendOrder });
 };
 type CartesianPathGuideOptions = Omit<CartesianGuideOptions, "legend"> & {
   legend?: false | (Omit<PathLegendOptions, "order"> & { order?: LegendValueOrder });
@@ -1563,8 +1654,9 @@ type CartesianPathGuideOptions = Omit<CartesianGuideOptions, "legend"> & {
 type CartesianCategoricalGuideOptions = Omit<CartesianGuideOptions, "legend"> & {
   legend?: false | (Omit<
     FilledMarkLegendOptions,
-    "count" | "values" | "gradient" | "labels" | "order"
+    "count" | "values" | "gradient" | "labels" | "order" | "representation" | "symbol"
   > & {
+    symbol?: FilledLegendSymbolRecipe;
     labels?: CategoricalLegendTextOptions;
     order?: CartesianLegendOrder;
   });
@@ -1576,7 +1668,7 @@ type CCategoricalGuides = Omit<CartesianCategoricalGuideOptions, "axes"> & {
   axes?: false | CAxes;
 };
 type ColorGuides = Omit<CartesianGuideOptions, "legend"> & {
-  legend?: false | (Omit<FilledMarkLegendOptions, "values" | "order"> & {
+  legend?: false | (DistributiveLegendOmit<FilledMarkLegendOptions, "order"> & {
     order?: CartesianLegendOrder;
   });
 };
@@ -1617,9 +1709,11 @@ export type PolarFrameCenter = {
 export type PolarFrameRadius =
   | { unit: "fraction"; value: number }
   | { unit: "px"; value: number };
+export type ArcInnerRadius = number | { unit: "px"; value: number };
 export type PolarFrameOptions = "auto" | {
   center?: PolarFrameCenter;
   radius?: PolarFrameRadius;
+  overflow?: "error" | "allow";
 };
 
 type EditCoordinateTarget = {
@@ -1724,6 +1818,14 @@ type ContinuousSizeScaleOptions = SizeScaleCommonOptions &
     domain?: "auto" | readonly [number, number];
     range?: "auto" | readonly [number, number];
   };
+export type CategoricalSizeScaleOptions = SizeScaleCommonOptions & {
+  type?: "ordinal";
+  domain?: "auto" | readonly (string | number | boolean)[];
+  range?: "auto" | readonly [number, ...number[]];
+  clamp?: never;
+  base?: never;
+  exponent?: never;
+};
 export type SizeScaleOptions =
   | (ContinuousSizeScaleOptions & {
       type?: "linear";
@@ -1772,6 +1874,7 @@ export type SizeScaleOptions =
 export type ShapeScaleOptions = ScaleFields<"id"> & {
   type?: "ordinal";
   domain?: "auto" | readonly unknown[];
+  /** One entry per domain value; explicit repeated shapes are allowed. Auto uses distinct shapes. */
   range?: "auto" | readonly PointShape[];
   unknown?: PointShape;
 };
@@ -1832,8 +1935,8 @@ export type EditStrokeScaleOptions = { target: string } & Omit<
 >;
 type ExistingSizeScaleEditPatch = {
   type?: never;
-  domain?: "auto" | readonly [number, ...number[]];
-  range?: "auto" | readonly [number, number, ...number[]];
+  domain?: "auto" | readonly [string | number | boolean, ...(string | number | boolean)[]];
+  range?: "auto" | readonly [number, ...number[]];
   unknown?: number;
   clamp?: boolean;
   reverse?: boolean;
@@ -1841,6 +1944,7 @@ type ExistingSizeScaleEditPatch = {
   exponent?: number;
 };
 type SizeScaleTypeEditPatch =
+  | (WithoutScaleId<CategoricalSizeScaleOptions> & { type: "ordinal" })
   | (Omit<WithoutScaleId<SizeScaleOptions>, "type"> & { type?: "linear" })
   | (Omit<Extract<WithoutScaleId<SizeScaleOptions>, { type: "log" }>, "type"> & {
       type: "log";
@@ -1979,6 +2083,8 @@ export type RadialEncodingOptions = {
   coordinate?: string;
 } & (
   | { field: string; mapping?: false; aggregate?: never; scale?: RadiusScaleOptions }
+  | { field: string; mapping?: never; aggregate: "sum"; scale?: RadiusScaleOptions }
+  | { field?: never; mapping?: never; aggregate: "count"; scale?: RadiusScaleOptions }
   | { field: string; mapping?: RadialMapping; aggregate: "sum"; scale?: MeasuredRadiusScaleOptions }
   | { field?: never; mapping?: RadialMapping; aggregate: "count"; scale?: MeasuredRadiusScaleOptions }
 );
@@ -2223,7 +2329,8 @@ type TimeUnitDataBaseOptions = {
   source?: string;
   field: string;
   temporalUnit?: TemporalInputUnit;
-  as: string;
+  /** Defaults to `${field}_${unit}`; collisions are rejected. */
+  as?: string;
   timeZone?: string;
 };
 export type TimeUnitDataOptions = TimeUnitDataBaseOptions & (
@@ -2345,6 +2452,7 @@ type ImputedDataBaseOptions = {
   maxGap?: number;
 };
 export type ImputedDataOptions = ImputedDataBaseOptions & (
+  | { method?: "mean"; value?: never; sortBy?: readonly WindowSort[]; }
   | {
       method: "constant";
       value: DatasetScalar;
@@ -2362,7 +2470,7 @@ export type ImputedDataOptions = ImputedDataBaseOptions & (
     }
 );
 export interface StackDataOptions {
-  id: string;
+  id?: string;
   source?: string;
   category: string;
   group: string;
@@ -2553,11 +2661,24 @@ export type BoxPlotPositionChannel =
   | BoxPlotCategoryChannel
   | BoxPlotMeasureChannel;
 
-export type BoxPlotWhisker =
+export type BoxPlotWhisker = (
   | { type?: "tukey"; factor?: number }
-  | { type: "minmax"; factor?: never };
+  | { type: "minmax"; factor?: never }
+) & Pick<ErrorBarOptions, "caps" | "capSize" | "stroke" | "strokeWidth" | "strokeDash" | "opacity" |
+  "lineCap" | "lineJoin" | "miterLimit">;
+
+export interface BoxPlotSummaryFields {
+  min: string;
+  q1: string;
+  median: string;
+  q3: string;
+  max: string;
+}
+
+type BoxPlotWidth = { band?: number; pixels?: never } | { band?: never; pixels: number };
 
 export interface BoxPlotOptions {
+  summary?: BoxPlotSummaryFields;
   id?: string;
   target?: string;
   data?: string;
@@ -2565,7 +2686,7 @@ export interface BoxPlotOptions {
   y?: BoxPlotPositionChannel;
   coordinate?: string;
   whisker?: BoxPlotWhisker;
-  width?: { band?: number };
+  width?: BoxPlotWidth;
   outliers?: boolean;
   box?: RectStyleDetails & {
     fill?: string;
@@ -2574,6 +2695,7 @@ export interface BoxPlotOptions {
     strokeWidth?: number;
   };
   median?: StrokeStyleDetails & {
+    width?: { pixels: number } | "auto";
     stroke?: string;
     strokeWidth?: number;
   };
@@ -2586,12 +2708,13 @@ export interface BoxPlotOptions {
 }
 
 export interface EditBoxPlotOptions {
+  summary?: BoxPlotSummaryFields | false;
   target?: string;
   data?: string;
   x?: BoxPlotPositionChannel;
   y?: BoxPlotPositionChannel;
   whisker?: BoxPlotWhisker;
-  width?: { band?: number };
+  width?: BoxPlotWidth;
   outliers?: boolean;
   box?: RectStyleDetails & {
     fill?: string;
@@ -2600,6 +2723,7 @@ export interface EditBoxPlotOptions {
     strokeWidth?: number;
   };
   median?: StrokeStyleDetails & {
+    width?: { pixels: number } | "auto";
     stroke?: string;
     strokeWidth?: number;
   };
@@ -2688,7 +2812,7 @@ export type ViolinPlotColorOptions =
     };
 
 export interface ViolinPlotAreaOptions extends StrokeStyleDetails {
-  fill?: string;
+  fill?: FillPaint;
   opacity?: number;
   stroke?: string;
   strokeWidth?: number;
@@ -2763,6 +2887,11 @@ type LineXPositionChannel =
           temporalUnit?: TemporalInputUnit;
           scale?: NonPointTemporalPositionScaleOptions;
         }
+      | {
+          fieldType: "nominal" | "ordinal";
+          bin?: never;
+          scale?: NonPointCategoricalPositionScaleOptions;
+        }
     ));
 type LineYPositionChannel =
   | string
@@ -2788,13 +2917,14 @@ type BarYPositionChannel =
   | string
   | {
       field: string;
+      bin?: never;
       fieldType: "temporal";
       temporalUnit?: TemporalInputUnit;
       aggregate?: never;
       stack?: never;
       scale?: NonPointTemporalPositionScaleOptions;
     }
-  | ({ field: string; stack?: StackMode } & (
+  | ({ field: string; bin?: never; stack?: StackMode } & (
       | {
           fieldType?: "quantitative";
           aggregate?: never;
@@ -2829,7 +2959,7 @@ type BasicColorChannel =
       field: string;
       fieldType: "temporal";
       temporalUnit?: TemporalInputUnit;
-      scale?: Omit<ContinuousColorScaleOptions, "midpoint"> & { midpoint?: "auto" };
+      scale?: Omit<ContinuousColorScaleOptions, "midpoint" | "type" | "base" | "constant"> & { midpoint?: "auto"; type?: "sequential" };
       palette?: Palette;
     };
 type NonPointCategoricalColorChannel =
@@ -2894,14 +3024,10 @@ type RectColorChannel =
       field: string;
       fieldType: "temporal";
       temporalUnit?: TemporalInputUnit;
-      scale?: Omit<NonPointContinuousColorScaleOptions, "midpoint"> & { midpoint?: "auto" };
+      scale?: Omit<NonPointContinuousColorScaleOptions, "midpoint" | "type" | "base" | "constant"> & { midpoint?: "auto"; type?: "sequential" };
       palette?: Palette;
     };
-export type BasicSizeChannel = string | {
-  field: string;
-  fieldType?: "quantitative";
-  scale?: SizeScaleOptions;
-};
+export type BasicSizeChannel = string | WithoutEncodingTarget<SizeEncodingOptions>;
 export type BasicShapeChannel = string | {
   field: string;
   fieldType?: "nominal";
@@ -2965,6 +3091,7 @@ export interface CreateScatterPlotOptions {
   x: PointFacadePositionChannel;
   y: PointFacadePositionChannel;
   color?: BasicColorChannel;
+  stroke?: string | WithoutEncodingTarget<Extract<StrokeEncodingOptions, { field: string }>>;
   size?: BasicSizeChannel;
   shape?: BasicShapeChannel;
   point?: StrokeStyleDetails & {
@@ -3133,7 +3260,7 @@ type PolarLegendOrder = LegendValueOrder | { channel: "theta"; values?: never };
 type PolarPathLegendOptions = Omit<PathLegendOptions, "order"> & {
   order?: PolarLegendOrder;
 };
-type PolarPointLegendOptions = Omit<FilledMarkLegendOptions, "order"> & {
+type PolarPointLegendOptions = DistributiveLegendOmit<FilledMarkLegendOptions, "order"> & {
   order?: PolarLegendOrder;
 };
 export type PolarPathGuideOptions = Omit<PolarChartGuideOptions, "legend"> & {
@@ -3163,7 +3290,7 @@ export interface CreatePolarLinePlotOptions {
   color?: LineCategoricalColorChannel;
   groupBy?: string | readonly [string, ...string[]];
   strokeDash?: BasicStrokeDashChannel;
-  line?: Omit<NonNullable<CreateLinePlotOptions["line"]>, "closed" | "curve"> & {
+  line?: Omit<NonNullable<CreateLinePlotOptions["line"]>, "closed" | "curve" | "tension"> & {
     curve?: "linear";
     closed?: boolean;
   };
@@ -3229,7 +3356,7 @@ export type CreateRadarPlotOptions = {
   ];
   color?: LineCategoricalColorChannel;
   strokeDash?: BasicStrokeDashChannel;
-  line?: Omit<NonNullable<CreateLinePlotOptions["line"]>, "closed" | "curve"> & {
+  line?: Omit<NonNullable<CreateLinePlotOptions["line"]>, "closed" | "curve" | "tension"> & {
     curve?: "linear";
     closed?: true;
   };
@@ -3258,8 +3385,17 @@ export interface RugTickOptions extends StrokeStyleDetails {
   strokeWidth?: number;
   opacity?: number;
 }
-export type RugGuideOptions = Omit<CartesianGuideOptions, "axes" | "legend"> & {
+type ContinuousGridDirectionOptions = Omit<GridDirectionOptions, "bandPosition"> & {
+  /** Continuous position scales do not have categorical band edges. */
+  bandPosition?: never;
+};
+type ContinuousCartesianGridOptions = {
+  vertical?: boolean | ContinuousGridDirectionOptions;
+  horizontal?: boolean | ContinuousGridDirectionOptions;
+};
+export type RugGuideOptions = Omit<CartesianGuideOptions, "axes" | "legend" | "grid"> & {
   axes?: false | CAxes;
+  grid?: false | ContinuousCartesianGridOptions;
   legend?: false;
 };
 export type CreateRugPlotOptions = {
@@ -3423,6 +3559,7 @@ export type GroupEncodingOptions = { target?: string; fieldType?: "nominal" } &
 export interface SeriesLayoutOptions { target?: string; mode: ColorLayout; }
 export interface BasicSeriesLayoutOptions { target?: string; mode: Exclude<ColorLayout, "center">; }
 export type AreaPlotIndependentChannel = string | ({ field: string } & (
+  | { fieldType: "nominal" | "ordinal"; scale?: NonPointCategoricalPositionScaleOptions }
   | { fieldType?: "quantitative"; scale?: NonPointQuantitativePositionScaleOptions }
   | { fieldType: "temporal"; temporalUnit?: TemporalInputUnit; scale?: NonPointTemporalPositionScaleOptions }
 ));
@@ -3436,8 +3573,8 @@ export type CreateAreaPlotOptions = {
   groupBy?: string | readonly [string, ...string[]];
   layout?: Exclude<ColorLayout, "group">; missing?: "error" | "break";
   color?: string | { field: string; fieldType?: "nominal" | "ordinal"; scale?: NonPointCategoricalColorScaleOptions; palette?: Palette };
-  area?: StrokeStyleDetails & { fill?: string; opacity?: number; stroke?: string; strokeWidth?: number; curve?: CurveInterpolation };
-  guides?: false | DensityPlotGuideOptions;
+  area?: StrokeStyleDetails & { fill?: FillPaint; opacity?: number; stroke?: string; strokeWidth?: number; curve?: CurveInterpolation };
+  guides?: false | (Omit<DensityPlotGuideOptions, "grid"> & { grid?: false | CartesianGridOptions });
 } & (
   | { valueChannel?: "y"; x: AreaPlotIndependentChannel; y: Exclude<AreaPlotMeasureChannel, { lower: unknown }>; baseline?: number }
   | { valueChannel?: "y"; x: AreaPlotIndependentChannel; y: Extract<AreaPlotMeasureChannel, { lower: unknown }>; baseline?: never }
@@ -3457,11 +3594,22 @@ export interface CreateLinePlotOptions {
   line?: StrokeStyleDetails & {
     strokeWidth?: number;
     curve?: CurveInterpolation;
+    tension?: number;
     stroke?: string;
     opacity?: number;
     closed?: false;
   };
-  guides?: false | CPathGuides;
+  guides?: false | (Omit<CPathGuides, "legend" | "grid"> & {
+    grid?: false | (Omit<CartesianGridOptions, "horizontal"> & {
+      horizontal?: boolean | (Omit<GridDirectionOptions, "bandPosition"> & {
+        /** Line y is continuous; band positioning is available only for categorical x grids. */
+        bandPosition?: never;
+      });
+    });
+    legend?: false | (Omit<PathLegendOptions, "order"> & {
+      order?: LegendValueOrder | { channel: "x"; values?: never };
+    });
+  });
 }
 
 type BasicHistogramEncoding =
@@ -3473,22 +3621,44 @@ type BasicHistogramEncoding =
       : never
     : never;
 
-export interface CreateBarPlotOptions {
+export type BarRangePositionChannel = {
+  lower: string;
+  upper: string;
+  fieldType?: "quantitative";
+  scale?: NonPointZeroSupportingPositionScaleOptions;
+  field?: never;
+  aggregate?: never;
+  stack?: never;
+};
+type BarFieldPosition<T> = T extends string ? T : T & { lower?: never; upper?: never };
+type BarRangeOppositePositionChannel = string | {
+  field: string;
+  fieldType?: "nominal" | "ordinal" | "temporal";
+  temporalUnit?: TemporalInputUnit;
+  scale?: NonPointBandPositionScaleOptions | NonPointTemporalPositionScaleOptions;
+  bin?: never;
+  aggregate?: never;
+  stack?: never;
+};
+export type CreateBarPlotOptions = {
   id?: string;
   data?: string;
   coordinate?: string;
-  x: BandPositionChannel;
-  y: BarYPositionChannel;
+  orientation?: "vertical" | "horizontal";
   color?: BarColorChannel;
-  width?: Omit<BarWidthOptions, "target">;
+  width?: Omit<BarWidthOptions, "target" | "interval">;
   bar?: RectStyleDetails & {
-    fill?: string;
+    fill?: FillPaint;
     opacity?: number;
     stroke?: FilledMarkStroke;
     strokeWidth?: number;
   };
   guides?: false | ColorGuides;
-}
+} & (
+  | { x: BarFieldPosition<BandPositionChannel>; y: BarFieldPosition<BarYPositionChannel> }
+  | { x: BarRangePositionChannel; y: BarRangeOppositePositionChannel }
+  | { x: BarRangeOppositePositionChannel; y: BarRangePositionChannel }
+);
 
 export type CreateHistogramOptions = BasicHistogramEncoding & {
   id?: string;
@@ -3497,7 +3667,7 @@ export type CreateHistogramOptions = BasicHistogramEncoding & {
   field: string;
   color?: HistogramCategoricalColorChannel;
   bar?: RectStyleDetails & {
-    fill?: string;
+    fill?: FillPaint;
     opacity?: number;
     stroke?: FilledMarkStroke;
     strokeWidth?: number;
@@ -3507,7 +3677,7 @@ export type CreateHistogramOptions = BasicHistogramEncoding & {
 
 export type HorizonPlotGuideOptions = {
   axes?: false | (Omit<CAxes, "y"> & { y?: false });
-  grid?: false | (Pick<CartesianGridOptions, "vertical"> & { horizontal?: false });
+  grid?: false | { vertical?: boolean | ContinuousGridDirectionOptions; horizontal?: false };
   legend?: false;
 };
 export interface CreateHorizonPlotOptions {
@@ -3529,7 +3699,8 @@ export interface CreateHorizonPlotOptions {
 }
 
 export type DensityPlotLegendOptions = Omit<PieLegendOptions, "order"> & { order?: LegendValueOrder };
-export type DensityPlotGuideOptions = Omit<CCategoricalGuides, "legend"> & {
+export type DensityPlotGuideOptions = Omit<CCategoricalGuides, "legend" | "grid"> & {
+  grid?: false | ContinuousCartesianGridOptions;
   legend?: false | DensityPlotLegendOptions;
 };
 export interface CreateDensityPlotOptions {
@@ -3555,7 +3726,7 @@ export interface CreateDensityPlotOptions {
     palette?: Palette;
     layout?: "overlay";
   };
-  area?: StrokeStyleDetails & { fill?: string; opacity?: number; stroke?: string; strokeWidth?: number; curve?: CurveInterpolation };
+  area?: StrokeStyleDetails & { fill?: FillPaint; opacity?: number; stroke?: string; strokeWidth?: number; curve?: CurveInterpolation };
   guides?: false | DensityPlotGuideOptions;
 }
 
@@ -3572,32 +3743,38 @@ export type PieColor = string | {
 };
 export type PieLegendOptions = Omit<
   FilledMarkLegendOptions,
-  "count" | "values" | "gradient" | "channels" | "order" | "labels"
+  "count" | "values" | "gradient" | "channels" | "order" | "labels" | "representation" | "symbol"
 > & {
+  symbol?: FilledLegendSymbolRecipe;
   channels?: readonly ["color"];
   order?: LegendValueOrder | { channel: "theta"; values?: never };
   labels?: CategoricalLegendTextOptions;
 };
+export type PieRadiusChannel = string | {
+  scale?: RadiusScaleOptions;
+} & ({ field: string; aggregate?: "sum" } | { field?: never; aggregate: "count" });
+
 export type CreatePiePlotOptions = {
   id?: string;
   data?: string;
   coordinate?: string;
   category: PieCategory;
   color?: false | PieColor;
-  arc?: StrokeStyleDetails & { innerRadius?: number; padAngle?: number; fill?: string; opacity?: number; stroke?: string; strokeWidth?: number };
+  radius?: PieRadiusChannel;
+  arc?: StrokeStyleDetails & { innerRadius?: ArcInnerRadius; padAngle?: number; fill?: string; opacity?: number; stroke?: string; strokeWidth?: number };
   guides?: false | { axes?: false; grid?: false; legend?: false | PieLegendOptions };
-} & ({ value?: never; aggregate?: "count" } | { value: string; aggregate: "sum" });
+} & ({ value?: never; aggregate?: "count" } | { value: string; aggregate?: "sum" });
 
 export type MeasuredRadialGuideOptions = {
   axes?: false | CategoricalPolarAxesOptions;
   grid?: false | CategoricalPolarGridOptions;
   legend?: false | PieLegendOptions;
 };
-export type CreateRosePlotOptions = Omit<CreatePiePlotOptions, "guides" | "arc" | "aggregate" | "value"> & {
+export type CreateRosePlotOptions = Omit<CreatePiePlotOptions, "guides" | "arc" | "aggregate" | "value" | "radius"> & {
   radiusScale?: MeasuredRadiusScaleOptions;
-  arc?: StrokeStyleDetails & { innerRadius?: number; padAngle?: 0; fill?: string; opacity?: number; stroke?: string; strokeWidth?: number };
+  arc?: StrokeStyleDetails & { innerRadius?: ArcInnerRadius; padAngle?: 0; fill?: string; opacity?: number; stroke?: string; strokeWidth?: number };
   guides?: false | MeasuredRadialGuideOptions;
-} & ({ value?: never; aggregate?: "count" } | { value: string; aggregate: "sum" });
+} & ({ value?: never; aggregate?: "count" } | { value: string; aggregate?: "sum" });
 export type CreateRadialBarPlotOptions = CreateRosePlotOptions;
 
 export interface HeatmapBaseOptions {
@@ -3624,7 +3801,7 @@ export interface PreGriddedHeatmapOptions extends HeatmapBaseOptions {
   x: HeatmapCategoryPositionChannel;
   y: HeatmapCategoryPositionChannel;
   bin?: never;
-  color: RectColorChannel;
+  color?: RectColorChannel;
 }
 
 export interface BinnedHeatmapPositionChannel {
@@ -3697,7 +3874,7 @@ export interface ErrorBandOptions extends StrokeStyleDetails {
   y?: ErrorBandPositionChannel | ErrorBandIntervalChannel;
   groupBy?: string;
   coordinate?: string;
-  fill?: string;
+  fill?: FillPaint;
   opacity?: number;
   curve?: CurveInterpolation;
   boundaries?: false | (StrokeStyleDetails & {
@@ -3715,7 +3892,7 @@ export interface EditErrorBandOptions extends StrokeStyleDetails {
   x?: ErrorBandPositionChannel | ErrorBandIntervalChannel;
   y?: ErrorBandPositionChannel | ErrorBandIntervalChannel;
   groupBy?: string | false;
-  fill?: string | false;
+  fill?: FillPaint | false;
   opacity?: number;
   curve?: CurveInterpolation;
   statistics?: {
@@ -3785,6 +3962,12 @@ export interface YOffsetEncodingOptions extends OffsetEncodingOptions {}
 export type TextFormat = ValueFormat;
 
 export interface TextMarkOptions {
+  /** Logical-pixel baseline spacing; defaults to 1.2 times fontSize. */
+  lineHeight?: number;
+  /** Anchor the first line or center the complete multiline block. */
+  blockAlign?: "first" | "middle";
+  /** Follow resolved source appearance; an explicit fill takes precedence. Source-owned labels only. */
+  inheritColor?: "fill" | "stroke" | false;
   id?: string;
   data?: string;
   /** Explicit source mark. Mutually exclusive with data; may be incomplete. */
@@ -3918,6 +4101,18 @@ type AnnotationBaseOptions = Omit<TextMarkOptions, "id" | "data" | "source" | "t
 
 type AnnotationAnchor =
   | {
+      anchor: "plot-center";
+      x?: never;
+      y?: never;
+      space?: never;
+      source?: never;
+      align?: never;
+      baseline?: never;
+      data?: string;
+      coordinate?: string;
+    }
+  | {
+      anchor?: never;
       x?: never;
       y?: never;
       space?: never;
@@ -3926,6 +4121,7 @@ type AnnotationAnchor =
       coordinate?: never;
     }
   | {
+      anchor?: never;
       x: unknown;
       y: unknown;
       space?: "data";
@@ -3934,6 +4130,7 @@ type AnnotationAnchor =
       coordinate?: never;
     }
   | {
+      anchor?: never;
       x: number;
       y: number;
       space: "plot";
@@ -3944,9 +4141,30 @@ type AnnotationAnchor =
 
 export type CreateAnnotationOptions = AnnotationBaseOptions & AnnotationAnchor;
 
+type TextPlotPositionChannel =
+  | string
+  | ({ field: string } & PositionScaleBranches<
+      NonPointQuantitativePositionScaleOptions,
+      NonPointTemporalPositionScaleOptions,
+      NonPointCategoricalPositionScaleOptions>)
+  | WithoutEncodingTarget<Extract<DatumPositionEncodingOptions, { datum: unknown }>> & { coordinate?: never };
+
+export interface CreateTextPlotOptions {
+  id?: string;
+  data?: string;
+  coordinate?: string;
+  x: TextPlotPositionChannel;
+  y: TextPlotPositionChannel;
+  text: string | WithoutEncodingTarget<Extract<TextEncodingOptions, { field: string } | { value: unknown }>>;
+  color?: RectColorChannel;
+  style?: Omit<TextMarkOptions, "id" | "data" | "source" | "text" | "inheritColor">;
+  guides?: false | ColorGuides;
+}
+
 export type BarWidthOptions = { target?: string } & (
-  | { band?: number; pixels?: never }
-  | { band?: never; pixels: number }
+  | { band?: number; pixels?: never; interval?: never }
+  | { band?: never; pixels: number; interval?: never }
+  | { band?: never; pixels?: never; interval: { unit: Exclude<TimeUnit, "week" | "weekday">; insetStart?: number; insetEnd?: number } }
 );
 
 export interface DashScaleOptions {
@@ -3975,7 +4193,9 @@ export type StrokeDashEncodingOptions =
 export type NonPointContinuousColorScaleOptions = ScaleFields<
   "id" | "interpolate" | "midpoint" | "clamp" | "reverse"
 > & {
-  type?: "sequential";
+  type?: "sequential" | "log" | "sqrt" | "symlog";
+  base?: number;
+  constant?: number;
   domain?: "auto" | readonly [unknown, unknown];
   range?: "auto" | readonly [string, string, ...string[]];
   palette?: PaletteName | {
@@ -4039,7 +4259,7 @@ export type ColorEncodingOptions =
       fieldType: "temporal";
       temporalUnit?: TemporalInputUnit;
       aggregate?: never;
-      scale?: Omit<ContinuousColorScaleOptions, "midpoint"> & { midpoint?: "auto" };
+      scale?: Omit<ContinuousColorScaleOptions, "midpoint" | "type" | "base" | "constant"> & { midpoint?: "auto"; type?: "sequential" };
       palette?: Palette;
       layout?: never;
     };
@@ -4162,9 +4382,10 @@ export type StrokeWidthEncodingOptions =
 export type SizeEncodingOptions = {
   field: string;
   target?: string;
-  fieldType?: "quantitative";
-  scale?: SizeScaleOptions;
-};
+} & (
+  | { fieldType?: "quantitative"; scale?: SizeScaleOptions }
+  | { fieldType: "nominal" | "ordinal"; scale?: CategoricalSizeScaleOptions }
+);
 
 export type ShapeEncodingOptions = {
   field: string;
@@ -4259,6 +4480,7 @@ type RegressionParameterOptions =
       method?: "linear";
       degree?: never;
       span?: never;
+      robustIterations?: never;
       confidenceMethod?: ConfidenceIntervalMethod;
       level?: number;
       confidence?: number;
@@ -4269,6 +4491,7 @@ type RegressionParameterOptions =
       method: "polynomial";
       degree?: number;
       span?: never;
+      robustIterations?: never;
       confidenceMethod?: ConfidenceIntervalMethod;
       level?: number;
       confidence?: number;
@@ -4279,6 +4502,8 @@ type RegressionParameterOptions =
       method: "loess";
       degree?: never;
       span?: number;
+      /** Residual reweighting passes, integer 0..32; default 0. */
+      robustIterations?: number;
       confidenceMethod?: never;
       level?: never;
       confidence?: never;
@@ -4326,6 +4551,7 @@ export interface EditRegressionOptions {
   method?: RegressionMethod;
   degree?: number;
   span?: number;
+  robustIterations?: number;
   confidenceMethod?: ConfidenceIntervalMethod;
   level?: number;
   confidence?: number;
@@ -4374,6 +4600,8 @@ export interface LegendTextOptions {
 }
 
 export interface LegendTitleStyleOptions {
+  /** Align a top title inside its measured content block; omission keeps native layout defaults. */
+  align?: "left" | "center" | "right";
   color?: string;
   fontSize?: number;
   fontFamily?: string;
@@ -4419,32 +4647,45 @@ export type LegendOrder = LegendValueOrder |
   { channel: "x" | "y" | "theta"; values?: never };
 
 export interface LegendOptions {
+  /** Continuous color only. Omission creates the existing gradient; symbols samples the same scale without changing marks. */
+  representation?: "gradient" | "symbols";
   /** Categorical, interval, size, or stroke-width layout. Defaults to edge; legacy-bottom is categorical and requires bottom position. */
   layout?: "edge" | "legacy-bottom";
+  /** Categorical and ordinal-size display limit; omitted or false shows every item. */
+  overflow?: false | { maxItems: number; summary?: "ellipsis-count" };
   /** Categorical item order; preserves the appearance scale's assignments. */
   order?: LegendOrder;
   target?: string;
   /** Exact requested content; omission infers encoded point color/shape/size. Explicit subsets include size only when listed. */
   channels?: readonly ("color" | "stroke" | "strokeDash" | "strokeWidth" | "shape" | "size" | "opacity")[];
-  position?: "right" | "left" | "bottom" | "top";
+  /** Outside right/left: complete legend stack top aligns with the plot top, including borders and excluding chart titles. */
+  position?: "right" | "left" | "bottom" | "top" | "top-left" | "top-right" | "bottom-left" | "bottom-right";
+  /** Arrange every legend block owned by the selected target. Item direction and columns remain independent. */
+  blockLayout?: "row" | "column" | "wrap";
+  /** Occupied group top-left relative to the plot. Cannot be supplied with position, align, or offset in the same call. */
+  at?: { x: number; y: number };
   /** Single top/bottom edge: align complete occupied bounds, including border strokes, to the plot. Side positions require center. */
   align?: "left" | "center" | "right";
   /** Categorical sides require vertical (the default); horizontal edges default to horizontal. */
   direction?: "horizontal" | "vertical";
-  /** Categorical sides allow omission or 1; multiple columns require a horizontal edge. */
+  /** Categorical legends accept a positive column count on every supported position. */
   columns?: number;
   /** Single top/bottom edge: gap from the plot to the nearest occupied legend edge. */
   offset?: number;
   titlePosition?: "top" | "left";
-  title?: string;
-  /** Exact ascending samples for continuous size, opacity, or stroke-width legends. Cannot be combined with count. */
+  /** false hides the title while retaining its inferred field text. */
+  /** LF, CRLF and CR preserve explicit title lines, including blank lines. */
+  title?: string | false;
+  /** Exact ascending samples for continuous size, opacity, stroke-width, or color with representation symbols. Cannot be combined with count. */
   values?: readonly number[];
   count?: number;
-  gradient?: { length?: number; thickness?: number };
+  /** Body-only opacity defaults to 1; edits preserve omitted fields. */
+  gradient?: { length?: number; thickness?: number; opacity?: number };
   symbol?: LegendSymbolRecipe;
   labels?: LegendTextOptions;
   /** New categorical+size blocks share typography on every edge; retained standalone size styles remain independent. */
   titleStyle?: LegendTitleStyleOptions;
+  /** Vertical items default to 18 logical pixels; the pitch grows to fit samples and labels. */
   itemGap?: number;
   border?: boolean | LegendBorderOptions;
 }
@@ -4477,11 +4718,17 @@ export interface EditLegendBlockOptions {
   gap?: number;
   text?: LegendBlockTextPatch;
   symbol?: LegendBlockSymbolPatch;
+  /** An empty mapped label omits only text; its category and symbol remain. */
   labelMap?: DisplayLabelMap | "auto";
 }
 
+export interface LegendTitleStyleEditOptions extends Omit<LegendTitleStyleOptions, "align"> {
+  align?: "left" | "center" | "right" | "auto";
+}
+
 export interface EditLegendOptions
-  extends Omit<LegendOptions, "title" | "values"> {
+  extends Omit<LegendOptions, "title" | "values" | "titleStyle"> {
+  titleStyle?: LegendTitleStyleEditOptions;
   /** Exact final content set for the whole target; omission preserves content. */
   channels?: LegendOptions["channels"];
   title?: string | "auto" | false;
@@ -4492,16 +4739,22 @@ export interface EditLegendOptions
 export interface EditLegendLayoutOptions {
   target?: string;
   layout?: "edge" | "legacy-bottom";
-  position?: "right" | "left" | "bottom" | "top";
+  /** Outside right/left: complete legend stack top aligns with the plot top, including borders and excluding chart titles. */
+  position?: "right" | "left" | "bottom" | "top" | "top-left" | "top-right" | "bottom-left" | "bottom-right";
+  /** Opt into whole-target legend group layout; a requested row never wraps. */
+  blockLayout?: "row" | "column" | "wrap";
+  /** Move the complete occupied group top-left to plot-relative logical pixels. A later position clears this anchor. */
+  at?: { x: number; y: number };
   /** Single top/bottom edge: align complete occupied bounds, including border strokes, to the plot. Side positions require center. */
   align?: "left" | "center" | "right";
   /** Categorical sides require vertical (the default); horizontal edges default to horizontal. */
   direction?: "horizontal" | "vertical";
-  /** Categorical sides allow omission or 1; multiple columns require a horizontal edge. */
+  /** Categorical legends accept a positive column count on every supported position. */
   columns?: number;
   /** Single top/bottom edge: gap from the plot to the nearest occupied legend edge. */
   offset?: number;
   titlePosition?: "top" | "left";
+  /** Explicit spacing override; vertical creation defaults to 18 logical pixels. */
   itemGap?: number;
 }
 
@@ -4509,7 +4762,7 @@ export interface EditLegendLabelsOptions extends LegendTextOptions {
   target?: string;
 }
 
-export interface EditLegendTitleOptions extends LegendTitleStyleOptions {
+export interface EditLegendTitleOptions extends LegendTitleStyleEditOptions {
   target?: string;
   title?: string | "auto" | false;
 }
@@ -4518,7 +4771,7 @@ export interface EditLegendSymbolsOptions {
   target?: string;
   symbol?: LegendSymbolRecipe;
   count?: number;
-  gradient?: { length?: number; thickness?: number };
+  gradient?: { length?: number; thickness?: number; opacity?: number };
 }
 
 export interface EditLegendBorderOptions {
@@ -4536,6 +4789,7 @@ export interface EditAxisOptions<P extends string> {
 }
 
 export interface TitleTextStyleOptions {
+  fontStyle?: "normal" | "italic";
   color?: string;
   fontSize?: number;
   fontFamily?: string;
@@ -4579,11 +4833,15 @@ export interface RemoveCategoryOrderOptions {
 }
 
 export interface TitleOptions {
+  /** Explicit hard lines are retained; blank lines reserve spacing without painted text. */
   text: string;
+  /** Multiline subtitle with at least one non-empty hard line. */
   subtitle?: string;
   position?: "top" | "bottom" | "left" | "right";
   align?: "left" | "center" | "right";
   offset?: number;
+  /** Signed logical-pixel shift along the selected edge; defaults to zero. */
+  alongOffset?: number;
   gap?: number;
   maxWidth?: number;
   wrap?: "word" | "character";
@@ -4729,6 +4987,7 @@ export class ChartProgram {
     data?: string;
     strokeWidth?: number;
     curve?: CurveInterpolation;
+    tension?: number;
     stroke?: string;
     opacity?: number;
     closed?: boolean;
@@ -4737,6 +4996,7 @@ export class ChartProgram {
     target?: string;
     strokeWidth?: number;
     curve?: CurveInterpolation;
+    tension?: number;
     stroke?: string;
     opacity?: number;
     closed?: boolean;
@@ -4744,8 +5004,9 @@ export class ChartProgram {
   createBarMark(options?: RectStyleDetails & {
     id?: string;
     data?: string;
+    orientation?: "vertical" | "horizontal";
     missing?: "error" | "skip";
-    fill?: string;
+    fill?: FillPaint;
     opacity?: number;
     stroke?: FilledMarkStroke;
     strokeWidth?: number;
@@ -4753,7 +5014,7 @@ export class ChartProgram {
   editBarMark(options: RectStyleDetails & {
     target?: string;
     missing?: "error" | "skip";
-    fill?: string;
+    fill?: FillPaint;
     opacity?: number;
     stroke?: FilledMarkStroke;
     strokeWidth?: number;
@@ -4761,7 +5022,7 @@ export class ChartProgram {
   createAreaMark(options?: StrokeStyleDetails & {
     id?: string;
     data?: string;
-    fill?: string;
+    fill?: FillPaint;
     opacity?: number;
     stroke?: string;
     strokeWidth?: number;
@@ -4771,7 +5032,7 @@ export class ChartProgram {
   createArcMark(options?: StrokeStyleDetails & {
     id?: string;
     data?: string;
-    innerRadius?: number;
+    innerRadius?: ArcInnerRadius;
     padAngle?: number;
     fill?: string;
     opacity?: number;
@@ -4780,7 +5041,7 @@ export class ChartProgram {
   }): ChartProgram;
   editArcMark(options: StrokeStyleDetails & {
     target?: string;
-    innerRadius?: number;
+    innerRadius?: ArcInnerRadius;
     padAngle?: number;
     fill?: string;
     opacity?: number;
@@ -4792,6 +5053,7 @@ export class ChartProgram {
   createRuleMark(options?: { id?: string; data?: string; missing?: "error" | "skip" } & RuleStyleOptions): ChartProgram;
   editRuleMark(options: { target?: string; missing?: "error" | "skip" } & RuleStyleOptions): ChartProgram;
   createTextMark(options?: TextMarkOptions): ChartProgram;
+  createTextPlot(options: CreateTextPlotOptions): ChartProgram;
   createMarkLabels(options?: CreateMarkLabelsOptions): ChartProgram;
   editMarkLabelSelection(options: EditMarkLabelSelectionOptions): ChartProgram;
   editMarkLabelPlacement(options: EditMarkLabelPlacementOptions): ChartProgram;
@@ -4804,7 +5066,7 @@ export class ChartProgram {
   removeLabelLayout(options?: RemoveLabelLayoutOptions): ChartProgram;
   editAreaMark(options: StrokeStyleDetails & {
     target?: string;
-    fill?: string;
+    fill?: FillPaint;
     opacity?: number;
     stroke?: string | false;
     strokeWidth?: number;
@@ -4963,7 +5225,7 @@ export class ChartProgram {
   editRadialGrid(options: EditPolarGridOptions): ChartProgram;
   editGrid(options: EditGridDirectionsOptions): ChartProgram;
   removeGrid(options?: RemoveGridOptions): ChartProgram;
-  /** Combined categorical and size legends support all four edges with layout "edge". */
+  /** Combined categorical and size legends support all four edges and plot corners with layout "edge". */
   createLegend(options?: LegendOptions): ChartProgram;
   editLegend(options: EditLegendOptions): ChartProgram;
   editLegendBlock(options: EditLegendBlockOptions): ChartProgram;