@ggts-sh/spec 0.43.0

package/src/schema-names.ts

@@ -0,0 +1,243 @@
+/**
+ * Named registries shared by the TypeBox schema graph and runtime catalogs.
+ * Kept separate from the `$defs` object so scale/theme name lists can change
+ * without editing the full declarations bag.
+ */
+
+/**
+ * Hard cap on a binned position scale's bins (automatic or explicit). This is
+ * the single shared source of truth: the TypeBox `breaks` `maxItems` below,
+ * the core runtime boundary resolver, and the `binned-scale-break-limit`
+ * pipeline error all key off it. `n` boundaries produce `n − 1` bins, so the
+ * schema allows at most `MAX_BINNED_BREAKS + 1` break values.
+ */
+export const MAX_BINNED_BREAKS = 64;
+
+/** Maximum gradient color stops in a portable paint (closed, bounded). */
+export const MAX_PAINT_STOPS = 16;
+
+/** Maximum glow blur radius in CSS px (bounded filter work). */
+export const MAX_GLOW_RADIUS = 32;
+
+/** Named categorical color schemes known to this schema version. */
+export const CATEGORICAL_SCHEME_NAMES = [
+  "observable10",
+  "ipsum",
+  "flexoki",
+  "colorblind",
+  // ggthemes ports (#1159): Stata s2color default
+  "stata",
+  /** ggthemes scale_colour/fill_economist — Economist blues/greens (fill order). */
+  "economist",
+  /** ggthemes scale_colour/fill_solarized — Solarized accents, blue first. */
+  "solarized",
+  // ggthemes ports (#1159): Few "Show Me the Numbers" variants + FiveThirtyEight
+  "few",
+  "few_light",
+  "few_dark",
+  "fivethirtyeight",
+  // ggthemes ports (#1159): Paul Tol + Canva default
+  "ptol",
+  "canva",
+  /** ggthemes wsj_pal — scale_colour/fill_wsj palette variants. */
+  "wsj",
+  "wsj_rgby",
+  "wsj_red_green",
+  "wsj_black_green",
+  "wsj_dem_rep",
+  // ggthemes tableau_color_pal regular variants (#1159)
+  "tableau20",
+  "tableau_colorblind",
+  "tableau_seattle_grays",
+  "tableau_jewel_bright",
+  "tableau_hue_circle",
+  // ggthemes ports (#1159): pander
+  "pander",
+  // ColorBrewer qualitative (#825)
+  "Dark2",
+  /** Even HSL hues — ggplot2-shaped scale_*_hue default discrete path (#829). */
+  "hue",
+  // Crameri Scientific colour maps v8.0.1 categorical (*S) 10-class prefixes
+  "actonS",
+  "bamakoS",
+  "batlowS",
+  "batlowWS",
+  "batlowKS",
+  "bilbaoS",
+  "budaS",
+  "davosS",
+  "devonS",
+  "glasgowS",
+  "grayCS",
+  "hawaiiS",
+  "imolaS",
+  "lajollaS",
+  "lapazS",
+  "lipariS",
+  "naviaS",
+  "nuukS",
+  "osloS",
+  "tokyoS",
+  "turkuS",
+] as const;
+
+/**
+ * Crameri cyclic (*O) sequential schemes. Periodic data only: wrap OOB and
+ * an explicit [min, max] period. Not legal on ordinal or binned scales.
+ */
+export const CYCLIC_SCHEME_NAMES = ["bamO", "brocO", "corkO", "romaO", "vikO"] as const;
+
+/**
+ * Named sequential color schemes known to this schema version.
+ * Viridis family maps (matplotlib/CC0 samples + Google turbo), ColorBrewer
+ * sequential/diverging ramps (#825), and Crameri Scientific colour maps
+ * v8.0.1 continuous suite plus cyclic (*O) ramps; used by continuous color
+ * scales. Discrete even-sampling (viridis_d parity) covers viridis-family
+ * and non-cyclic Crameri ramps only.
+ */
+export const SEQUENTIAL_SCHEME_NAMES = [
+  "viridis",
+  "magma",
+  "plasma",
+  "inferno",
+  "cividis",
+  "turbo",
+  // ColorBrewer sequential + diverging ramps (#825)
+  "Blues",
+  "Greens",
+  "Reds",
+  "Oranges",
+  "Purples",
+  "Greys",
+  "YlOrRd",
+  "YlGnBu",
+  "BuPu",
+  "RdYlBu",
+  "RdBu",
+  "BrBG",
+  "Spectral",
+  "PuOr",
+  // Crameri Scientific colour maps v8.0.1 continuous suite (seq / div / multi-seq)
+  "acton",
+  "bamako",
+  "batlow",
+  "batlowW",
+  "batlowK",
+  "bilbao",
+  "buda",
+  "davos",
+  "devon",
+  "glasgow",
+  "grayC",
+  "hawaii",
+  "imola",
+  "lajolla",
+  "lapaz",
+  "lipari",
+  "navia",
+  "naviaW",
+  "nuuk",
+  "oslo",
+  "tokyo",
+  "turku",
+  "bam",
+  "berlin",
+  "broc",
+  "cork",
+  "lisbon",
+  "managua",
+  "roma",
+  "tofino",
+  "vanimo",
+  "vik",
+  "bukavu",
+  "fes",
+  "oleron",
+  // Crameri cyclic (*O) — sequential family, wrap OOB, explicit period
+  ...CYCLIC_SCHEME_NAMES,
+] as const;
+
+export const COLOR_SCHEME_NAMES = [
+  ...CATEGORICAL_SCHEME_NAMES,
+  ...SEQUENTIAL_SCHEME_NAMES,
+] as const;
+
+/** Audited finite point symbols, ordered by default assignment priority. */
+export const POINT_SHAPE_NAMES = [
+  "circle",
+  "triangle",
+  "square",
+  "diamond",
+  "plus",
+  "cross",
+  "circle-open",
+] as const;
+export type PointShapeName = (typeof POINT_SHAPE_NAMES)[number];
+
+/** Audited finite stroke patterns, ordered by default assignment priority. */
+export const LINETYPE_NAMES = [
+  "solid",
+  "dashed",
+  "dotted",
+  "dotdash",
+  "longdash",
+  "twodash",
+] as const;
+export type LinetypeName = (typeof LINETYPE_NAMES)[number];
+
+/** Built-in theme names known to this schema version. */
+export const THEME_NAMES = [
+  "default",
+  "light",
+  "dark",
+  "minimal",
+  "ggplot2",
+  "classic",
+  "bw",
+  "hrbr",
+  "few",
+  "clean",
+  "fivethirtyeight",
+  "economist",
+  "tufte",
+  "linedraw",
+  "void",
+  // ggthemes theme ports (#1158): Stata family
+  "stata",
+  "stata_s1color",
+  // ggthemes theme_solarized: light (default) and dark (light = FALSE) variants.
+  "solarized",
+  "solarizeddark",
+  // ggthemes theme ports (#1158)
+  "economist_white",
+  "solarized_2",
+  "solarized_2dark",
+  /** ggthemes theme_wsj (Wall Street Journal). */
+  "wsj",
+  "hc",
+  "hcdark",
+  "pander",
+  // ggthemes minimalist family (#1158): theme_base / igray / map / solid
+  "base",
+  "igray",
+  "map",
+  "solid",
+  "grey",
+  "gray",
+  // Snapshot/unit-test complete theme (#823). Last: ordered docs/VR rosters
+  // append after product themes (and after name aliases).
+  "test",
+] as const;
+
+type ThemeNameValue = (typeof THEME_NAMES)[number];
+
+/**
+ * Registered theme names that share another theme's token map / evidence.
+ * Keys are first-class ThemeName values (PortableSpec accepts them); values
+ * are the canonical theme that owns the built-in tokens and visual evidence.
+ * UK `grey` and US `gray` both alias the grey-panel `ggplot2` look (#824).
+ */
+export const THEME_NAME_ALIASES = {
+  grey: "ggplot2",
+  gray: "ggplot2",
+} as const satisfies Partial<Record<ThemeNameValue, ThemeNameValue>>;

package/src/schema-types.ts

@@ -0,0 +1,400 @@
+/**
+ * Spec type bag for Static<> extraction (not for JSON emission).
+ *
+ * Prefer `ReturnType<typeof Type.Module<...>>` over a `const SpecStatic =
+ * Type.Module(...)` value: once LayerSpec includes density_2d_filled + map the
+ * Module instance exceeds TS7056 declaration-serialize limits under composite
+ * emit. The type-level Module is enough for SpecType / Static<>.
+ */
+import Type, { type Static } from "typebox";
+
+import type { NormalizedGeomName } from "./schema-catalog.js";
+import type { SpecDeclarations } from "./schema-declarations.js";
+
+type SpecModuleStatic = ReturnType<typeof Type.Module<typeof SpecDeclarations>>;
+type SpecType<K extends keyof SpecModuleStatic> = Static<SpecModuleStatic[K]>;
+
+// ---------------------------------------------------------------------------
+// Static types (the package's public TS types)
+// ---------------------------------------------------------------------------
+
+/** A single data cell (JSON scalar). */
+export type CellValue = SpecType<"CellValue">;
+
+// The data-container types are written out by hand: TypeBox's computed module
+// types collapse `Type.Record`/`additionalProperties` value schemas to `{}`
+// in Static<>, losing the record value type. Runtime validation and the
+// emitted JSON Schema are unaffected (they come from the module above); these
+// aliases restore the intended TS shapes and are covered by assignability
+// tests against schema fixtures.
+
+/** Inline row-oriented data. */
+export interface DataValues {
+  values: Record<string, CellValue>[];
+}
+/** Inline column-oriented data (equal-length arrays). */
+export interface DataColumns {
+  columns: Record<string, CellValue[]>;
+}
+/** A reference to a named dataset. */
+export interface DataName {
+  name: string;
+}
+/** Where a plot's data comes from. */
+export type DataRef = DataValues | DataColumns | DataName;
+/** Inline data only ({values} or {columns}). */
+export type InlineData = DataValues | DataColumns;
+/** Canonical channel value: {field} | {value, scale?} | {stat} | null. */
+export type ChannelValue = SpecType<"ChannelValue">;
+/** Aesthetic mapping (canonical channel forms only). */
+export type Aes = SpecType<"Aes">;
+/** One ordered gradient color stop. */
+export type ColorStop = SpecType<"ColorStop">;
+/** Gradient coordinate space. */
+export type PaintSpace = SpecType<"PaintSpace">;
+/** Deterministic linear gradient paint. */
+export type LinearGradientPaint = SpecType<"LinearGradientPaint">;
+/** Deterministic radial gradient paint. */
+export type RadialGradientPaint = SpecType<"RadialGradientPaint">;
+/** Closed portable gradient paint (linear | radial). */
+export type GradientPaint = SpecType<"GradientPaint">;
+/** Bounded glow treatment. */
+export type GlowSpec = SpecType<"GlowSpec">;
+/** Point layer params. */
+export type PointParams = SpecType<"PointParams">;
+/** Line layer params. */
+export type LineParams = SpecType<"LineParams">;
+/** Path layer params (no bin knobs). */
+export type PathParams = SpecType<"PathParams">;
+/** Step layer params (ggplot2 geom_step direction). */
+export type StepParams = SpecType<"StepParams">;
+/** Col layer params. */
+export type ColParams = SpecType<"ColParams">;
+/** Bar/histogram layer params (styling + stat-bin controls). */
+export type BarParams = SpecType<"BarParams">;
+/** Area layer params. */
+export type AreaParams = SpecType<"AreaParams">;
+/** Rule layer params (annotation intercepts + styling). */
+export type RuleParams = SpecType<"RuleParams">;
+/** Hline alias params (yintercept + styling). */
+export type HlineParams = SpecType<"HlineParams">;
+/** Vline alias params (xintercept + styling). */
+export type VlineParams = SpecType<"VlineParams">;
+/** Segment layer params (styling + lineend). */
+export type SegmentParams = SpecType<"SegmentParams">;
+export type ViolinParams = SpecType<"ViolinParams">;
+/** Function layer params (named fun + grid). */
+export type FunctionParams = SpecType<"FunctionParams">;
+/** Named portable function registry entry. */
+export type FunctionRegistryName = SpecType<"FunctionRegistryName">;
+/** Args bag for registry functions. */
+export type FunctionArgs = SpecType<"FunctionArgs">;
+/** Polygon layer params (fill/stroke styling). */
+export type PolygonParams = SpecType<"PolygonParams">;
+export type AblineParams = SpecType<"AblineParams">;
+/** Curve layer params (curvature/angle/ncp + stroke). */
+export type CurveParams = SpecType<"CurveParams">;
+/** Simple-features layer params (geometry column + styling; #809 phase 1). */
+export type SfParams = SpecType<"SfParams">;
+/** Map layer params (fortified map DataRef + styling; #808). */
+export type MapParams = SpecType<"MapParams">;
+/** SF text layer params (geometry column + text styling; #809 phase 2). */
+export type SfTextParams = SpecType<"SfTextParams">;
+/** SF label layer params (geometry + text + box chrome; #809 phase 3). */
+export type SfLabelParams = SpecType<"SfLabelParams">;
+/** Rug layer params (sides, length, stroke styling). */
+export type RugParams = SpecType<"RugParams">;
+export type QqParams = SpecType<"QqParams">;
+export type QqLineParams = SpecType<"QqLineParams">;
+/** Text layer params. */
+export type TextParams = SpecType<"TextParams">;
+/** Label layer params (text + background box). */
+export type LabelParams = SpecType<"LabelParams">;
+/** Smooth layer params (method/se/level/span/degree/n + styling). */
+export type SmoothParams = SpecType<"SmoothParams">;
+/** Quantile layer params (quantiles/n + styling). */
+export type QuantileParams = SpecType<"QuantileParams">;
+/** Contour isoline params (bins/breaks/binwidth + stroke; #801). */
+export type ContourParams = SpecType<"ContourParams">;
+/** Boxplot layer params. */
+export type BoxplotParams = SpecType<"BoxplotParams">;
+/** Density layer params (bw/adjust/n/cut + styling). */
+export type DensityParams = SpecType<"DensityParams">;
+/** 2D density isoline params (#802). */
+export type Density2dParams = SpecType<"Density2dParams">;
+/** Dotplot layer params (histodot binning + stack + point style; #803). */
+export type DotplotParams = SpecType<"DotplotParams">;
+/** A summary function name (stat summary). */
+export type SummaryFun = SpecType<"SummaryFun">;
+/** Errorbar layer params (styling + summary-stat functions). */
+export type ErrorbarParams = SpecType<"ErrorbarParams">;
+/** Linerange params (alias of ErrorbarParams). */
+export type LinerangeParams = SpecType<"LinerangeParams">;
+/** Pointrange params (stem + mid point size/shape). */
+export type PointrangeParams = SpecType<"PointrangeParams">;
+/** Crossbar params (width, fatten, stroke). */
+export type CrossbarParams = SpecType<"CrossbarParams">;
+/** Rect layer params. */
+export type RectParams = SpecType<"RectParams">;
+/** Tile layer params. */
+export type TileParams = SpecType<"TileParams">;
+/** bin_2d layer params. */
+export type Bin2dParams = SpecType<"Bin2dParams">;
+/** Raster layer params. */
+export type RasterParams = SpecType<"RasterParams">;
+/** Hex bin heatmap params. */
+export type HexParams = SpecType<"HexParams">;
+/** Ribbon layer params (outline, orientation, stroke ends). */
+export type RibbonParams = SpecType<"RibbonParams">;
+/** Jitter/nudge position parameters. */
+export type PositionParams = SpecType<"PositionParams">;
+// Layer types: TypeBox Static collapses DataRef to object[]; restore the
+// hand-written DataRef on optional per-layer `data` (#589).
+type LayerWithDataRef<T> = Omit<T, "data"> & { data?: DataRef };
+/** A point layer. */
+export type PointLayer = LayerWithDataRef<SpecType<"PointLayer">>;
+/** A line layer. */
+export type LineLayer = LayerWithDataRef<SpecType<"LineLayer">>;
+/** A path layer (data-order polylines; ggplot2 geom_path). */
+export type PathLayer = LayerWithDataRef<SpecType<"PathLayer">>;
+/** A col layer (pre-computed bars). */
+export type ColLayer = LayerWithDataRef<SpecType<"ColLayer">>;
+/** A bar layer (count or bin stat). */
+export type BarLayer = LayerWithDataRef<SpecType<"BarLayer">>;
+/** A histogram layer (alias; normalize() canonicalizes to bar + stat bin). */
+export type HistogramLayer = LayerWithDataRef<SpecType<"HistogramLayer">>;
+/** A freqpoly layer (alias; normalize() → line + stat bin). */
+export type FreqpolyLayer = LayerWithDataRef<SpecType<"FreqpolyLayer">>;
+/** An area layer. */
+export type AreaLayer = LayerWithDataRef<SpecType<"AreaLayer">>;
+/** A rule (reference line) layer. */
+export type RuleLayer = LayerWithDataRef<SpecType<"RuleLayer">>;
+/** An hline layer (alias; normalize() → rule). */
+export type HlineLayer = LayerWithDataRef<SpecType<"HlineLayer">>;
+/** A vline layer (alias; normalize() → rule). */
+export type VlineLayer = LayerWithDataRef<SpecType<"VlineLayer">>;
+/** A jitter layer (alias; normalize() → point + position jitter). */
+export type JitterLayer = LayerWithDataRef<SpecType<"JitterLayer">>;
+/** A text-label layer. */
+export type TextLayer = LayerWithDataRef<SpecType<"TextLayer">>;
+/** A label layer (text with background box). */
+export type LabelLayer = LayerWithDataRef<SpecType<"LabelLayer">>;
+/** A smooth (fitted trend) layer. */
+export type SmoothLayer = LayerWithDataRef<SpecType<"SmoothLayer">>;
+/** A quantile regression layer. */
+export type QuantileLayer = LayerWithDataRef<SpecType<"QuantileLayer">>;
+/** A contour isoline layer (#801). */
+export type ContourLayer = LayerWithDataRef<SpecType<"ContourLayer">>;
+/** A boxplot layer. */
+export type BoxplotLayer = LayerWithDataRef<SpecType<"BoxplotLayer">>;
+/** A density (KDE) layer. */
+export type DensityLayer = LayerWithDataRef<SpecType<"DensityLayer">>;
+/** A 2D density isoline layer (#802). */
+export type Density2dLayer = LayerWithDataRef<SpecType<"Density2dLayer">>;
+/** A filled 2D density layer. */
+export type Density2dFilledLayer = LayerWithDataRef<SpecType<"Density2dFilledLayer">>;
+/** A stacked-dot (geom_dotplot) layer. */
+export type DotplotLayer = LayerWithDataRef<SpecType<"DotplotLayer">>;
+/** An errorbar layer. */
+export type ErrorbarLayer = LayerWithDataRef<SpecType<"ErrorbarLayer">>;
+/** A linerange layer (stem without caps). */
+export type LinerangeLayer = LayerWithDataRef<SpecType<"LinerangeLayer">>;
+/** A pointrange layer (stem + mid point). */
+export type PointrangeLayer = LayerWithDataRef<SpecType<"PointrangeLayer">>;
+/** A crossbar layer (interval box + mid line). */
+export type CrossbarLayer = LayerWithDataRef<SpecType<"CrossbarLayer">>;
+/** A rect layer (arbitrary xmin/xmax/ymin/ymax regions). */
+export type RectLayer = LayerWithDataRef<SpecType<"RectLayer">>;
+/** A tile layer (center-sized cells). */
+export type TileLayer = LayerWithDataRef<SpecType<"TileLayer">>;
+/** A 2D bin heatmap layer. */
+export type Bin2dLayer = LayerWithDataRef<SpecType<"Bin2dLayer">>;
+/** A raster layer (equal-cell dense grid). */
+export type RasterLayer = LayerWithDataRef<SpecType<"RasterLayer">>;
+/** A hexagonal bin heatmap layer. */
+export type HexLayer = LayerWithDataRef<SpecType<"HexLayer">>;
+/** A ribbon (interval band) layer. */
+export type RibbonLayer = LayerWithDataRef<SpecType<"RibbonLayer">>;
+/** A finite segment layer ((x,y)→(xend,yend)). */
+export type SegmentLayer = LayerWithDataRef<SpecType<"SegmentLayer">>;
+/** Count (geom_count / stat_sum) layer. */
+export type CountLayer = LayerWithDataRef<
+  SpecType<"CountLayer">
+>; /** A slope/intercept reference line layer (geom_abline). */
+/** A violin (mirrored y-density) layer. */
+export type ViolinLayer = LayerWithDataRef<SpecType<"ViolinLayer">>;
+/** An analytic function path layer (y = f(x) grid). */
+export type FunctionLayer = LayerWithDataRef<SpecType<"FunctionLayer">>;
+/** A closed polygon layer ((x,y) vertices in data order). */
+export type PolygonLayer = LayerWithDataRef<SpecType<"PolygonLayer">>;
+/** A slope/intercept reference line layer (geom_abline). */
+export type AblineLayer = LayerWithDataRef<SpecType<"AblineLayer">>;
+/** A curve layer (curved connectors). */
+export type CurveLayer = LayerWithDataRef<SpecType<"CurveLayer">>;
+/** A choropleth/map layer (#808). */
+export type MapLayer = LayerWithDataRef<SpecType<"MapLayer">>;
+export type SfLayer = LayerWithDataRef<SpecType<"SfLayer">>;
+/** An sf_text layer (labels at representative points; #809 phase 2). */
+export type SfTextLayer = LayerWithDataRef<SpecType<"SfTextLayer">>;
+/** An sf_label layer (boxed labels at representative points; #809 phase 3). */
+export type SfLabelLayer = LayerWithDataRef<SpecType<"SfLabelLayer">>;
+/**
+ * Empty params bag for blank layers.
+ *
+ * TypeBox `Type.Object({})` Static-infers as `{}`, which is *not* assignable
+ * to `Record<string, unknown>` and also poisons `LayerSpec["params"]` unions
+ * (oxlint no-unnecessary-type-assertion on every `(layer.params ?? {}) as X`).
+ * Override so blank matches every other geom params bag.
+ */
+export type BlankParams = Record<string, never>;
+/** A blank layer (no marks; trains scales from mapped aesthetics). */
+export type BlankLayer = LayerWithDataRef<
+  Omit<SpecType<"BlankLayer">, "params"> & { readonly params?: BlankParams }
+>;
+
+export type SpokeParams = SpecType<"SpokeParams">;
+export type SpokeLayer = LayerWithDataRef<SpecType<"SpokeLayer">>;
+/** A marginal rug layer (edge ticks). */
+export type RugLayer = LayerWithDataRef<SpecType<"RugLayer">>;
+/** A step-line layer (ggplot2 geom_step). */
+export type StepLayer = LayerWithDataRef<SpecType<"StepLayer">>;
+export type QqLayer = LayerWithDataRef<SpecType<"QqLayer">>;
+export type QqLineLayer = LayerWithDataRef<SpecType<"QqLineLayer">>;
+/** One plot layer, discriminated by `geom`. */
+export type LayerSpec =
+  | PointLayer
+  | LineLayer
+  | PathLayer
+  | ColLayer
+  | BarLayer
+  | HistogramLayer
+  | FreqpolyLayer
+  | AreaLayer
+  | RibbonLayer
+  | SegmentLayer
+  | CountLayer
+  | ViolinLayer
+  | FunctionLayer
+  | PolygonLayer
+  | AblineLayer
+  | CurveLayer
+  | MapLayer
+  | SfLayer
+  | SfTextLayer
+  | SfLabelLayer
+  | BlankLayer
+  | SpokeLayer
+  | RugLayer
+  | StepLayer
+  | RuleLayer
+  | HlineLayer
+  | VlineLayer
+  | JitterLayer
+  | TextLayer
+  | LabelLayer
+  | SmoothLayer
+  | QuantileLayer
+  | ContourLayer
+  | BoxplotLayer
+  | DensityLayer
+  | Density2dLayer
+  | Density2dFilledLayer
+  | DotplotLayer
+  | ErrorbarLayer
+  | LinerangeLayer
+  | PointrangeLayer
+  | CrossbarLayer
+  | RectLayer
+  | TileLayer
+  | Bin2dLayer
+  | RasterLayer
+  | HexLayer
+  | QqLayer
+  | QqLineLayer;
+/**
+ * A layer that survived normalize(): the alias geoms (histogram, freqpoly,
+ * jitter, hline, vline) are rewritten by then, so this union is 44 wide, not
+ * 49. Keying pipeline tables off it lets `tsc` name a geom nobody handled
+ * instead of leaving a silent `default:` arm (#1042).
+ */
+export type NormalizedLayerSpec = Extract<LayerSpec, { geom: NormalizedGeomName }>;
+/** Stackable position adjustment names. */
+export type StackablePosition = SpecType<"StackablePosition">;
+/** Position adjustments accepted by point layers. */
+export type PointPosition = "identity" | "jitter" | "nudge";
+/** Positional (x/y) scale configuration. */
+export type TemporalParserSpec = SpecType<"TemporalParserSpec">;
+export type PositionScaleSpec = SpecType<"PositionScaleSpec">;
+/** Display-domain expansion ({ mult?, add? }) for continuous/binned scales. */
+export type ScaleExpansion = SpecType<"ScaleExpansion">;
+/** Color/fill scale configuration. */
+export type ColorScaleSpec = SpecType<"ColorScaleSpec">;
+/** Positive numeric size/linewidth scale configuration. */
+export type PositiveStyleScaleSpec = SpecType<"PositiveStyleScaleSpec">;
+/** Opacity scale configuration. */
+export type AlphaScaleSpec = SpecType<"AlphaScaleSpec">;
+/** Finite point-shape scale configuration. */
+export type ShapeScaleSpec = SpecType<"ShapeScaleSpec">;
+/** Finite stroke-pattern scale configuration. */
+export type LinetypeScaleSpec = SpecType<"LinetypeScaleSpec">;
+/** Per-scale configuration for all position and style aesthetics. */
+export type Scales = SpecType<"Scales">;
+/** Facet-panel scale behavior. */
+export type FacetScales = SpecType<"FacetScales">;
+/** Facet configuration (wrap OR rows/cols grid). */
+export type FacetFieldRef = SpecType<"FacetFieldRef">;
+export type FacetStripSpec = SpecType<"FacetStripSpec">;
+export type FacetSpec = SpecType<"FacetSpec">;
+/** One post-stat coordinate axis transform. */
+export type CoordTransformAxisSpec = SpecType<"CoordTransformAxisSpec">;
+/** Post-stat coordinate transform configuration. */
+export type CoordTransformSpec = SpecType<"CoordTransformSpec">;
+/** Fixed-aspect Cartesian coordinate configuration. */
+export type CoordFixedSpec = SpecType<"CoordFixedSpec">;
+/** Simple-features fixed-aspect coordinates (already-projected maps; #809). */
+export type CoordSfSpec = SpecType<"CoordSfSpec">;
+/** Polar/radial coordinates (ggplot2 coord_radial / coord_polar). */
+export type CoordRadialSpec = SpecType<"CoordRadialSpec">;
+/** Cartesian, flipped, post-stat transformed, fixed-aspect, SF, or radial. */
+export type CoordSpec = SpecType<"CoordSpec">;
+/** Per-layer rendering backend hint. */
+export type RenderBackend = SpecType<"RenderBackend">;
+/** Plot-level accessibility mode. */
+export type A11yMode = "auto" | "force-svg";
+/** Bounded per-guide presentation theme overrides. */
+export type GuideThemeSpec = SpecType<"GuideThemeSpec">;
+export type BandAxisGuideSpec = SpecType<"BandAxisGuideSpec">;
+export type AxisGuideSpec = SpecType<"AxisGuideSpec">;
+export type LegendGuideSpec = SpecType<"LegendGuideSpec">;
+export type ColorbarGuideSpec = SpecType<"ColorbarGuideSpec">;
+export type ColorstepsGuideSpec = SpecType<"ColorstepsGuideSpec">;
+export type NoneGuideSpec = SpecType<"NoneGuideSpec">;
+/** One portable appearance-only guide configuration. */
+export type GuideSpec = SpecType<"GuideSpec">;
+/** Guide configuration keyed by aesthetic. */
+export type GuidesSpec = SpecType<"GuidesSpec">;
+/** Legacy legend ordering options. */
+export type LegendSpec = SpecType<"LegendSpec">;
+/** Built-in theme names. */
+export type ThemeName = SpecType<"ThemeName">;
+/** Theme object: named base + role overrides. */
+export type ThemeSpec = SpecType<"ThemeSpec">;
+/** Plot labels. */
+export type Labs = SpecType<"Labs">;
+/** The canonical, strictly-JSON plot spec (what agents emit and schemas describe). */
+export type PortableSpec = Omit<SpecType<"PlotSpec">, "data" | "datasets" | "layers"> & {
+  data?: DataRef;
+  datasets?: Record<string, InlineData>;
+  layers: LayerSpec[];
+};
+
+/**
+ * What normalize() returns: a PortableSpec whose layers carry no alias geom.
+ *
+ * Assignable to PortableSpec, so passing the result on is unchanged. The JSON
+ * Schema keeps describing PortableSpec — histogram and friends stay legal
+ * *input*; they just cannot survive normalize().
+ */
+export type NormalizedSpec = Omit<PortableSpec, "layers"> & {
+  layers: NormalizedLayerSpec[];
+};