@ggts-sh/spec 0.43.0

package/src/error-catalog.ts

@@ -0,0 +1,253 @@
+/**
+ * Validation error catalog — stable codes for agent diagnostics and docs.
+ * Dual-channel codes (also emitable by the pipeline) pull summary/fix from
+ * error-prose-shared.ts (#987). SpecError instance types and didYouMean live
+ * in errors.ts. Pipeline-only codes live in pipeline-error-catalog.ts.
+ */
+
+import { DUAL_ERROR_PROSE } from "./error-prose-shared.js";
+
+/** One entry of the validation error catalog (docs render straight from it). */
+export interface ErrorCatalogEntry {
+  /** 1 = schema shape / structural (no data needed); 2 = data-aware (opt-in). */
+  tier: 1 | 2;
+  /** What went wrong, in one sentence. */
+  summary: string;
+  /** How to fix it, prescriptively (instances carry a concrete fix.example). */
+  fix: string;
+}
+
+/**
+ * The stable catalog of validation error codes — THE single source for the
+ * docs error-reference page and llms-full.txt for validation. Dual-channel
+ * prose is shared with PIPELINE_ERROR_CATALOG via DUAL_ERROR_PROSE.
+ * Audited M3: every code has a prescriptive summary + fix; a coverage test
+ * asserts every code is exercised by a snapshot test.
+ */
+export const ERROR_CATALOG = {
+  // --- tier 1 (schema shape, no data needed) -------------------------------
+  "invalid-spec-root": {
+    tier: 1,
+    summary: "The spec is not a JSON object.",
+    fix: 'Provide an object with at least one layer: {"layers": [{"geom": "point", ...}]}.',
+  },
+  "missing-layers": {
+    tier: 1,
+    summary: "`layers` is missing or not an array.",
+    fix: "Add a layers array with at least one layer object.",
+  },
+  "empty-layers": {
+    tier: 1,
+    summary: "`layers` is present but empty (a plot needs at least one layer).",
+    fix: 'Add a layer, e.g. {"geom": "point"}.',
+  },
+  "invalid-layer": {
+    tier: 1,
+    summary: "A layer is not an object.",
+    fix: 'Replace the entry with a layer object carrying a "geom".',
+  },
+  "missing-geom": {
+    tier: 1,
+    summary: 'A layer has no "geom" discriminator.',
+    fix: 'Add a geom name to the layer, e.g. {"geom": "point"}.',
+  },
+  "unknown-geom": {
+    tier: 1,
+    summary: 'A layer\'s "geom" is not a known geom name.',
+    fix: "Use one of the allowed geoms (the error lists them, with a did-you-mean).",
+  },
+  "invalid-channel-value": {
+    tier: 1,
+    summary:
+      "A channel value is not one of the canonical forms {field}/{value}/{stat}/null (bare strings are builder-only shorthand).",
+    fix: 'Wrap field mappings as {"field": "column_name"} and constants as {"value": ...}.',
+  },
+  "unexpected-property": {
+    tier: 1,
+    summary: "An object carries a property the schema does not allow.",
+    fix: "Remove or rename the property (the error suggests the closest allowed name).",
+  },
+  "missing-property": {
+    tier: 1,
+    summary: "A required property is missing.",
+    fix: "Add the named property.",
+  },
+  "invalid-enum-value": {
+    tier: 1,
+    summary: "A value is outside its declared enum/literal set.",
+    fix: "Use one of the allowed values (the error lists them, with a did-you-mean).",
+  },
+  "value-out-of-range": {
+    tier: 1,
+    summary: "A numeric value is outside its declared bounds.",
+    fix: "Set the value inside the bounds stated by the error message.",
+  },
+  "invalid-data": {
+    tier: 1,
+    summary: "`data` (or a dataset entry) matches none of the data forms.",
+    fix: 'Use {"values": [...rows]}, {"columns": {...arrays}}, or {"name": "dataset"}.',
+  },
+  "invalid-type": {
+    tier: 1,
+    summary: "Fallback: a value has the wrong JSON type.",
+    fix: "Give the property the JSON type the message names.",
+  },
+  "scale-scheme-type": {
+    tier: 1,
+    summary: "A named color scheme is incompatible with the configured color scale type.",
+    fix: 'Use a categorical scheme with "ordinal" (or a sequential-family scheme like "viridis" for discrete viridis), or "viridis"/hex stops with "sequential". Cyclic *O schemes are sequential only.',
+  },
+  "scale-scheme-oob": {
+    tier: 1,
+    summary: "The out-of-bounds policy is incompatible with the named color scheme or scale type.",
+    fix: 'Use oob "wrap" with a cyclic *O scheme. Do not set wrap on a binned color scale.',
+  },
+  "scale-cyclic-domain": {
+    tier: 1,
+    summary: "A cyclic color scheme is missing the explicit two-value domain period.",
+    fix: "Set domain to one period, for example [0, 360] for angles in degrees.",
+  },
+  "scale-range-color": {
+    tier: 1,
+    summary: "A custom color range contains a color outside the supported hex syntax.",
+    fix: "Replace each custom color with #rgb or #rrggbb syntax.",
+  },
+  "scale-type-transform-conflict": {
+    tier: 1,
+    ...DUAL_ERROR_PROSE["scale-type-transform-conflict"],
+  },
+  "color-manual-domain-range": {
+    tier: 1,
+    ...DUAL_ERROR_PROSE["color-manual-domain-range"],
+  },
+  "scale-binned-breaks": {
+    tier: 1,
+    summary:
+      "A binned style scale's authored breaks are missing, non-finite after parsing, duplicated, or not strictly increasing.",
+    fix: "Provide 2+ strictly increasing boundaries (numeric, or temporal strings that parse under the scale's parser).",
+  },
+  "scale-binned-domain": {
+    tier: 1,
+    summary:
+      "A binned style scale's explicit domain does not match the first and last authored breaks.",
+    fix: "Set domain to the first and last break values, or omit domain and let breaks define it.",
+  },
+  "guide-aesthetic-incompatible": {
+    tier: 1,
+    ...DUAL_ERROR_PROSE["guide-aesthetic-incompatible"],
+  },
+  "coord-fixed-free-scales": {
+    tier: 1,
+    ...DUAL_ERROR_PROSE["coord-fixed-free-scales"],
+  },
+  // --- tier 1 structural (grammar rules the schema alone cannot express) ---
+  "missing-required-channel": {
+    tier: 2,
+    summary: "A geom is missing a required aesthetic channel (x, y, label, ...).",
+    fix: "Map the named channel to a data field in the layer's aes or the plot-level aes.",
+  },
+  "rule-form-ambiguous": {
+    tier: 2,
+    ...DUAL_ERROR_PROSE["rule-form-ambiguous"],
+  },
+  "rule-form-missing": {
+    tier: 2,
+    ...DUAL_ERROR_PROSE["rule-form-missing"],
+  },
+  "rule-both-axes": {
+    tier: 2,
+    ...DUAL_ERROR_PROSE["rule-both-axes"],
+  },
+  "computed-y-mapped": {
+    tier: 2,
+    ...DUAL_ERROR_PROSE["computed-y-mapped"],
+  },
+  "bin-center-and-boundary": {
+    tier: 2,
+    ...DUAL_ERROR_PROSE["bin-center-and-boundary"],
+  },
+  "facet-form-ambiguous": {
+    tier: 2,
+    ...DUAL_ERROR_PROSE["facet-form-ambiguous"],
+  },
+  "facet-form-missing": {
+    tier: 2,
+    ...DUAL_ERROR_PROSE["facet-form-missing"],
+  },
+  "facet-ncol-without-wrap": {
+    tier: 2,
+    summary: "facet.ncol only applies to the wrap form.",
+    fix: "Remove ncol, or switch to the wrap form.",
+  },
+  "unsupported-geom-aesthetic": {
+    tier: 2,
+    ...DUAL_ERROR_PROSE["unsupported-geom-aesthetic"],
+  },
+  "ribbon-orientation-ambiguous": {
+    tier: 2,
+    ...DUAL_ERROR_PROSE["ribbon-orientation-ambiguous"],
+  },
+  "paint-stops-unordered": {
+    tier: 2,
+    summary: "A gradient paint's color stops are not in non-decreasing offset order.",
+    fix: "Sort stops by offset ascending (each offset between 0 and 1 inclusive).",
+  },
+  "paint-scale-conflict": {
+    tier: 2,
+    summary:
+      "Within-mark fillPaint/strokePaint cannot combine with a data-mapped fill/color scale channel.",
+    fix: "Remove the data-mapped fill/color aesthetic, or remove the paint and keep the scale.",
+  },
+  // --- tier 2 (data-aware; needs inline data or a DataProfile) -------------
+  "unknown-field": {
+    tier: 2,
+    ...DUAL_ERROR_PROSE["unknown-field"],
+  },
+  "all-null-column": {
+    tier: 2,
+    ...DUAL_ERROR_PROSE["all-null-column"],
+  },
+  "scale-type-mismatch": {
+    tier: 2,
+    summary: "A configured scale type is incompatible with the mapped field's type.",
+    fix: "Change the scale type to match the field (band for categories, time for temporal), or map a compatible field.",
+  },
+  "channel-type-mismatch": {
+    tier: 2,
+    ...DUAL_ERROR_PROSE["channel-type-mismatch"],
+  },
+  "unknown-stat-column": {
+    tier: 2,
+    ...DUAL_ERROR_PROSE["unknown-stat-column"],
+  },
+  "manual-fun-required": {
+    // Structural grammar (layerStructuralErrors) — opt-in tier-2 only; not plain validate().
+    tier: 2,
+    ...DUAL_ERROR_PROSE["manual-fun-required"],
+  },
+  "summary-rolling-window-required": {
+    // Structural grammar (layerStructuralErrors) — opt-in tier-2 only; not plain validate().
+    tier: 2,
+    ...DUAL_ERROR_PROSE["summary-rolling-window-required"],
+  },
+  "summary-fun-unsupported": {
+    // Structural grammar (layerStructuralErrors) — opt-in tier-2 only; not plain validate().
+    tier: 2,
+    ...DUAL_ERROR_PROSE["summary-fun-unsupported"],
+  },
+  "invalid-data-profile": {
+    tier: 2,
+    summary: "The provided DataProfile is malformed.",
+    fix: 'Provide { fields: [{ name, type: "quantitative"|"temporal"|"ordinal"|"nominal" }], rowCount? }.',
+  },
+  "validation-limit": {
+    tier: 2,
+    summary: "Validation input exceeded a documented limit (rows/bytes/depth/diagnostics).",
+    fix: "Validate with a DataProfile instead of huge inline data, or raise the limit via options.limits.",
+  },
+} as const satisfies Record<string, ErrorCatalogEntry>;
+
+export type SpecErrorCode = keyof typeof ERROR_CATALOG;
+
+/** The stable list of validation error codes (keys of ERROR_CATALOG). */
+export const ERROR_CODES = Object.keys(ERROR_CATALOG) as readonly SpecErrorCode[];

package/src/error-prose-shared.ts

@@ -0,0 +1,106 @@
+/**
+ * Shared summary/fix prose for diagnostic codes that both validation
+ * (ERROR_CATALOG) and the pipeline (PIPELINE_ERROR_CATALOG) can emit.
+ * One object per code — import into both catalogs so the strings cannot drift.
+ *
+ * #987: missing-channel vs missing-required-channel is intentionally NOT
+ * merged here (different public code strings; one rename per change).
+ */
+
+/** Prose body shared by dual-channel error codes. */
+export interface SharedErrorProse {
+  summary: string;
+  fix: string;
+}
+
+/**
+ * Dual-channel codes and their single prose source.
+ * Keep keys sorted; scripts/error-catalog-shared-prose.test.ts pins membership.
+ */
+export const DUAL_ERROR_PROSE = {
+  "all-null-column": {
+    summary: "A mapped column contains only null values.",
+    fix: "Map the channel to a column with actual values, or fix the data.",
+  },
+  "bin-center-and-boundary": {
+    summary: "A bin-stat layer sets BOTH params.center and params.boundary.",
+    fix: "Keep one bin-grid alignment parameter and remove the other.",
+  },
+  "channel-type-mismatch": {
+    summary:
+      "A mapped field's type is incompatible with the layer's geom/stat (e.g. a nominal x on smooth/bin/density, a continuous x on boxplot).",
+    fix: "Map a field of the type the geom/stat needs, or switch to a geom that fits the field (the message suggests one).",
+  },
+  "color-manual-domain-range": {
+    summary: "A manual color/fill scale has a different number of domain values and range colors.",
+    fix: "Provide exactly one range color for every domain value.",
+  },
+  "computed-y-mapped": {
+    summary: "A layer whose stat computes y (count, bin, density) maps aes.y to a data field.",
+    fix: 'Unset y with null — or, for pre-computed bar heights, switch the layer to geom "col".',
+  },
+  "coord-fixed-free-scales": {
+    summary: "Fixed-aspect coordinates cannot represent free positional facet scales truthfully.",
+    fix: 'Use facet.scales = "fixed", or remove coord_fixed / coord_sf.',
+  },
+  "facet-form-ambiguous": {
+    summary: "A facet sets BOTH the wrap form and the rows/cols grid form.",
+    fix: "Keep facet.wrap (and drop rows/cols), or keep rows/cols (and drop wrap).",
+  },
+  "facet-form-missing": {
+    summary: "A facet sets neither wrap nor rows/cols — nothing to partition by.",
+    fix: "Set facet.wrap (wrap form) or facet.rows/facet.cols (grid form).",
+  },
+  "guide-aesthetic-incompatible": {
+    summary: "A guide variant is incompatible with its aesthetic or trained scale family.",
+    fix: "Use axis for x/y, legend for discrete/style scales, colorbar for sequential color, or colorsteps for binned color.",
+  },
+  "manual-fun-required": {
+    summary: "A layer uses stat manual without params.fun.",
+    fix: "Set params.fun to one of first|last|mean|median|min|max|sum (portable named registry; #814).",
+  },
+  "summary-rolling-window-required": {
+    summary: "A layer uses stat summary_rolling without params.window.",
+    fix: "Set params.window to the rolling-window width in x data units (greater than 0).",
+  },
+  "summary-fun-unsupported": {
+    summary: "A summary stat uses params.fun first|last, which only stat manual implements.",
+    fix: "Use mean, median, or sum (min/max via funMin/funMax where supported); first|last belong to stat manual.",
+  },
+  "ribbon-orientation-ambiguous": {
+    summary:
+      "A ribbon layer maps both x-orientation (x+ymin+ymax) and y-orientation (y+xmin+xmax) contracts without params.orientation.",
+    fix: 'Set params.orientation to "x" or "y", or map only one complete interval contract.',
+  },
+  "rule-both-axes": {
+    summary: "A data-driven rule layer maps BOTH aes.x and aes.y (pick one direction).",
+    fix: "Keep one direction (vertical: map x; horizontal: map y) and unset the other with null.",
+  },
+  "rule-form-ambiguous": {
+    summary:
+      "A rule layer mixes the annotation form (params.xintercept/yintercept) with mapped aes.x/aes.y.",
+    fix: "Use fixed intercepts OR a data mapping, never both (unset the other with null).",
+  },
+  "rule-form-missing": {
+    summary:
+      "A rule layer has neither intercept params nor a mapped aes.x/aes.y — nothing to draw.",
+    fix: "Set params.yintercept/xintercept (annotation) or map aes.x/aes.y (data-driven).",
+  },
+  "scale-type-transform-conflict": {
+    summary:
+      'A scale declares an incompatible type/family with its transform (temporal/discrete/manual/identity with a non-identity transform, or type: "log" with a non-log10 transform).',
+    fix: 'Use identity for temporal/discrete/manual/identity scales; for base-10 log use type: "linear" with transform: "log10"; or choose a quantitative family that admits the transform.',
+  },
+  "unknown-field": {
+    summary: "A channel maps a field that does not exist in the data.",
+    fix: "Map the channel to one of the available fields (the error lists them, with a did-you-mean).",
+  },
+  "unknown-stat-column": {
+    summary: "A { stat } channel names a column the layer's stat does not generate.",
+    fix: "Use one of the columns the stat generates (the error lists them), or change the layer's stat.",
+  },
+  "unsupported-geom-aesthetic": {
+    summary: "A mapped style aesthetic is not consumed by the selected geom.",
+    fix: "Remove the mapping or move it to one of the compatible geoms listed in the error.",
+  },
+} as const satisfies Record<string, SharedErrorProse>;

package/src/errors.ts

@@ -0,0 +1,87 @@
+/**
+ * Agent-facing error contract (plan: "Validation for agents") + helpers.
+ * Every validation diagnostic is a SpecError:
+ *
+ *   { code, path, message, allowed?, fix? }
+ *
+ * The stable ERROR_CATALOG lives in error-catalog.ts and is re-exported here
+ * so package and deep imports keep the ./errors.js path.
+ *
+ * "Did you mean" suggestions use a small Levenshtein distance so agents get a
+ * concrete correction for typo'd geoms/channels/params.
+ */
+import type { JSONValue } from "./portability.js";
+import type { SpecErrorCode } from "./error-catalog.js";
+
+export {
+  ERROR_CATALOG,
+  ERROR_CODES,
+  type ErrorCatalogEntry,
+  type SpecErrorCode,
+} from "./error-catalog.js";
+
+export interface SpecErrorFix {
+  description: string;
+  example?: JSONValue;
+}
+
+export interface SpecError {
+  code: SpecErrorCode;
+  path: string;
+  message: string;
+  allowed?: string[];
+  fix?: SpecErrorFix;
+}
+
+/** Thrown by builder .spec() / render entry points when validation fails. */
+export class SpecValidationError extends Error {
+  readonly errors: readonly SpecError[];
+
+  constructor(errors: readonly SpecError[]) {
+    const lines = errors.map((e) => `  [${e.code}] ${e.path || "/"}: ${e.message}`);
+    super(
+      `Invalid plot spec (${errors.length} error${errors.length === 1 ? "" : "s"}):\n` +
+        lines.join("\n"),
+    );
+    this.name = "SpecValidationError";
+    this.errors = errors;
+  }
+}
+
+/** Classic dynamic-programming Levenshtein distance (small inputs only). */
+export function levenshtein(a: string, b: string): number {
+  if (a === b) return 0;
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  let prev = Array.from({ length: n + 1 }, (_, j) => j);
+  let curr = Array.from({ length: n + 1 }, () => 0);
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(prev[j]! + 1, curr[j - 1]! + 1, prev[j - 1]! + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[n]!;
+}
+
+/**
+ * The closest candidate within an input-length-scaled distance budget
+ * (<= max(1, floor(len/3)) edits, case-insensitive), or undefined.
+ */
+export function didYouMean(input: string, candidates: readonly string[]): string | undefined {
+  const budget = Math.max(1, Math.floor(input.length / 3));
+  let best: string | undefined;
+  let bestDist = budget + 1;
+  for (const candidate of candidates) {
+    const d = levenshtein(input.toLowerCase(), candidate.toLowerCase());
+    if (d < bestDist) {
+      bestDist = d;
+      best = candidate;
+    }
+  }
+  return best;
+}

package/src/generated/coord-reference-data.ts

@@ -0,0 +1,235 @@
+/**
+ * AUTO-GENERATED by scripts/gen-reference-catalogs.ts — do not edit by hand.
+ * Regenerate: bun run reference:catalogs:gen
+ *
+ * COORD_REFERENCE — per-coord API docs.
+ */
+export const COORD_REFERENCE_DATA = {
+  cartesian: {
+    name: "cartesian",
+    slug: "cartesian",
+    component: "CoordCartesian",
+    typeLiteral: "cartesian",
+    schemaType: "CoordCartesianSpec",
+    helper: "",
+    helperAlias: "",
+    alsoHelpers: [],
+    alsoExportedAs: [],
+    builderMethods: ["coord"],
+    summary:
+      'Default Cartesian coordinates. Omit coord or use CoordCartesian to clear a prior REPLACE-family coord; normalize() drops bare { type: "cartesian" }.',
+    params: [],
+    axisParams: [],
+  },
+  flip: {
+    name: "flip",
+    slug: "flip",
+    component: "CoordFlip",
+    typeLiteral: "flip",
+    schemaType: "CoordCartesianSpec",
+    helper: "",
+    helperAlias: "",
+    alsoHelpers: [],
+    alsoExportedAs: [],
+    builderMethods: ["coordFlip", "coord"],
+    summary:
+      "Swap display axes so semantic x paints vertically and y horizontally. The mechanism for horizontal bar charts; stack, dodge, and hit-testing follow the flip.",
+    params: [],
+    axisParams: [],
+  },
+  transform: {
+    name: "transform",
+    slug: "transform",
+    component: "CoordTransform",
+    typeLiteral: "transform",
+    schemaType: "CoordTransformSpec",
+    helper: "coordTransform",
+    helperAlias: "coord_transform",
+    alsoHelpers: [],
+    alsoExportedAs: [],
+    builderMethods: ["coordTransform", "coord"],
+    summary:
+      "Post-stat coordinate projection with independent x/y transforms (identity, log10, sqrt), semantic viewport limits, reverse, and panel clipping. Distinct from pre-stat scale transforms.",
+    params: [
+      {
+        name: "x",
+        description:
+          "Optional x-axis projector: transform, semantic limits, reverse, and expand. Accepts a transform name string or an axis options object on the helper/shell.",
+        typeSummary: "CoordTransformAxisSpec",
+        required: false,
+      },
+      {
+        name: "y",
+        description:
+          "Optional y-axis projector: transform, semantic limits, reverse, and expand. Accepts a transform name string or an axis options object on the helper/shell.",
+        typeSummary: "CoordTransformAxisSpec",
+        required: false,
+      },
+      {
+        name: "clip",
+        description:
+          "Clip marks to the panel rectangle (default true). Set false only when intentional overflow should remain visible.",
+        typeSummary: "boolean",
+        required: false,
+      },
+    ],
+    axisParams: [
+      {
+        name: "transform",
+        description:
+          "Post-stat coordinate transform for this axis: identity, base-10 logarithm, or square root.",
+        typeSummary: '"identity" | "log10" | "sqrt"',
+        required: true,
+      },
+      {
+        name: "limits",
+        description:
+          "Optional coordinate viewport [min, max] in semantic/source units. Exactly two numbers. Unlike scale limits, coordinate limits do not remove rows or recompute statistics.",
+        typeSummary: "[number, number]",
+        required: false,
+      },
+      {
+        name: "reverse",
+        description:
+          "Reverse this coordinate axis after its transform without changing stat inputs or the trained semantic scale domain.",
+        typeSummary: "boolean",
+        required: false,
+      },
+      {
+        name: "expand",
+        description:
+          "Whether explicit coordinate limits receive the default 5% transformed-space display expansion (default true). Set false for exact viewport limits.",
+        typeSummary: "boolean",
+        required: false,
+      },
+    ],
+  },
+  fixed: {
+    name: "fixed",
+    slug: "fixed",
+    component: "CoordFixed",
+    typeLiteral: "fixed",
+    schemaType: "CoordFixedSpec",
+    helper: "coordFixed",
+    helperAlias: "coord_fixed",
+    alsoHelpers: ["coordEqual", "coord_equal"],
+    alsoExportedAs: ["CoordEqual"],
+    builderMethods: ["coordFixed", "coordEqual", "coord"],
+    summary:
+      "Fixed physical data-unit aspect ratio (y-unit length / x-unit length). Layout fits the largest centered data rectangle after chart chrome; rejects free positional facet scales.",
+    params: [
+      {
+        name: "ratio",
+        description:
+          "Physical y-unit length divided by physical x-unit length (default 1, equal units).",
+        typeSummary: "number",
+        required: false,
+      },
+    ],
+    axisParams: [],
+  },
+  sf: {
+    name: "sf",
+    slug: "sf",
+    component: "CoordSf",
+    typeLiteral: "sf",
+    schemaType: "CoordSfSpec",
+    helper: "coordSf",
+    helperAlias: "coord_sf",
+    alsoHelpers: [],
+    alsoExportedAs: [],
+    builderMethods: ["coordSf", "coord"],
+    summary:
+      "Fixed-aspect coordinates for already-projected geom_sf maps. Same layout as fixed; no CRS reproject or graticules in v1 — data must already be in plot space.",
+    params: [
+      {
+        name: "ratio",
+        description:
+          "Physical y-unit length divided by physical x-unit length (default 1, equal projected units).",
+        typeSummary: "number",
+        required: false,
+      },
+    ],
+    axisParams: [],
+  },
+  radial: {
+    name: "radial",
+    slug: "radial",
+    component: "CoordRadial",
+    typeLiteral: "radial",
+    schemaType: "CoordRadialSpec",
+    helper: "coordRadial",
+    helperAlias: "coord_radial",
+    alsoHelpers: ["coordPolar", "coord_polar"],
+    alsoExportedAs: [],
+    builderMethods: ["coordRadial", "coordPolar", "coord"],
+    summary:
+      "Polar/radial coordinates (ggplot2 coord_radial). Maps one aesthetic to angle and the other to radius for pie charts, coxcombs, and polar scatter. coord_polar is a helper alias with clip on.",
+    params: [
+      {
+        name: "theta",
+        description:
+          'Which aesthetic maps to angle: "x" (default) or "y". The other aesthetic maps to radius. Pie charts use theta: "y".',
+        typeSummary: '"x" | "y"',
+        required: false,
+      },
+      {
+        name: "start",
+        description:
+          "Offset of the starting angle from 12 o'clock, in radians (default 0). Positive angles proceed clockwise when reverse does not flip theta.",
+        typeSummary: "number",
+        required: false,
+      },
+      {
+        name: "end",
+        description:
+          "Angle where the plot ends, in radians measured from 12 o'clock. Default is start + 2π (full circle). Use with start for partial polar plots.",
+        typeSummary: "number",
+        required: false,
+      },
+      {
+        name: "innerRadius",
+        description:
+          "Size of the inner radius hole as a fraction of the outer radius (0–1, default 0). Values above 0 produce a donut.",
+        typeSummary: "number",
+        required: false,
+      },
+      {
+        name: "expand",
+        description:
+          "When true (default), add a small expansion so data does not sit on the axes. When false, limits come directly from the scale (typical for pie/coxcomb).",
+        typeSummary: "boolean",
+        required: false,
+      },
+      {
+        name: "clip",
+        description:
+          'Clip marks to the panel. ggplot2 coord_radial defaults to clip off; coord_polar defaults to clip on. ggts stores the effective boolean (default false for type "radial").',
+        typeSummary: "boolean",
+        required: false,
+      },
+      {
+        name: "reverse",
+        description:
+          'Which directions to reverse: "none" (default), "theta", "r", or "thetar" (both). coord_polar(direction = -1) maps to reverse: "theta".',
+        typeSummary: '"none" | "theta" | "r" | "thetar"',
+        required: false,
+      },
+      {
+        name: "thetaLimits",
+        description:
+          "Optional [min, max] limits for the theta (angle) aesthetic in semantic units. Exactly two numbers.",
+        typeSummary: "[number, number]",
+        required: false,
+      },
+      {
+        name: "rLimits",
+        description:
+          "Optional [min, max] limits for the radius aesthetic in semantic units. Exactly two numbers.",
+        typeSummary: "[number, number]",
+        required: false,
+      },
+    ],
+    axisParams: [],
+  },
+} as const;