@ggts-sh/spec 0.43.0

package/src/builder-scales.ts

@@ -0,0 +1,443 @@
+/**
+ * AUTO-GENERATED by scripts/gen-builder-scales.ts — do not edit by hand.
+ * Regenerate: bun run builder:scales:gen
+ *
+ * Fluent builder scale sugar methods (thin wrappers over scale-helpers).
+ * Source of truth: builderScaleHelperNames() from SCALE_CAPABILITIES.
+ * Core builder: builder-core.ts. Public GGBuilder: builder.ts.
+ */
+import type { GGBuilder } from "./builder.js";
+import {
+  scaleAlphaBinned,
+  scaleAlphaContinuous,
+  scaleAlphaDate,
+  scaleAlphaDatetime,
+  scaleAlphaDiscrete,
+  scaleAlphaIdentity,
+  scaleAlphaManual,
+  scaleAlphaOrdinal,
+  scaleColorBinned,
+  scaleColorBrewer,
+  scaleColorContinuous,
+  scaleColorDate,
+  scaleColorDatetime,
+  scaleColorDiscrete,
+  scaleColorDistiller,
+  scaleColorFermenter,
+  scaleColorGradient,
+  scaleColorGradient2,
+  scaleColorGradientn,
+  scaleColorGrey,
+  scaleColorHue,
+  scaleColorIdentity,
+  scaleColorLog10,
+  scaleColorManual,
+  scaleColorOrdinal,
+  scaleColorSqrt,
+  scaleColorSteps,
+  scaleColorSteps2,
+  scaleColorStepsn,
+  scaleColorViridisB,
+  scaleColorViridisC,
+  scaleColorViridisD,
+  scaleFillBinned,
+  scaleFillBrewer,
+  scaleFillContinuous,
+  scaleFillDate,
+  scaleFillDatetime,
+  scaleFillDiscrete,
+  scaleFillDistiller,
+  scaleFillFermenter,
+  scaleFillGradient,
+  scaleFillGradient2,
+  scaleFillGradientn,
+  scaleFillGrey,
+  scaleFillHue,
+  scaleFillIdentity,
+  scaleFillLog10,
+  scaleFillManual,
+  scaleFillOrdinal,
+  scaleFillSqrt,
+  scaleFillSteps,
+  scaleFillSteps2,
+  scaleFillStepsn,
+  scaleFillViridisB,
+  scaleFillViridisC,
+  scaleFillViridisD,
+  scaleLinetypeBinned,
+  scaleLinetypeDiscrete,
+  scaleLinetypeIdentity,
+  scaleLinetypeManual,
+  scaleLinewidthBinned,
+  scaleLinewidthContinuous,
+  scaleLinewidthDate,
+  scaleLinewidthDatetime,
+  scaleLinewidthDiscrete,
+  scaleLinewidthIdentity,
+  scaleLinewidthManual,
+  scaleLinewidthOrdinal,
+  scaleRadius,
+  scaleShapeBinned,
+  scaleShapeDiscrete,
+  scaleShapeIdentity,
+  scaleShapeManual,
+  scaleShapeOrdinal,
+  scaleSizeArea,
+  scaleSizeBinned,
+  scaleSizeBinnedArea,
+  scaleSizeContinuous,
+  scaleSizeDate,
+  scaleSizeDatetime,
+  scaleSizeDiscrete,
+  scaleSizeIdentity,
+  scaleSizeManual,
+  scaleSizeOrdinal,
+  scaleXBinned,
+  scaleXContinuous,
+  scaleXDate,
+  scaleXDatetime,
+  scaleXDiscrete,
+  scaleXLog10,
+  scaleXMonthDay,
+  scaleXReverse,
+  scaleXSqrt,
+  scaleXTime,
+  scaleYBinned,
+  scaleYContinuous,
+  scaleYDate,
+  scaleYDatetime,
+  scaleYDiscrete,
+  scaleYLog10,
+  scaleYMonthDay,
+  scaleYReverse,
+  scaleYSqrt,
+  scaleYTime,
+} from "./scale-helpers.js";
+import type { Scales } from "./schema.js";
+
+/** Host must expose scales() returning the public fluent builder type. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- mixin host constructor
+type ScaleHostConstructor = new (...args: any[]) => {
+  scales(scales: Scales): GGBuilder;
+};
+
+/**
+ * Mixin that adds scaleX/Y/Color/Fill/style sugar methods.
+ * Every method is annotated to return GGBuilder so fluent chains keep full typing.
+ */
+export function WithBuilderScales<TBase extends ScaleHostConstructor>(Base: TBase) {
+  return class extends Base {
+    scaleAlphaBinned(...args: Parameters<typeof scaleAlphaBinned>): GGBuilder {
+      return this.scales(scaleAlphaBinned(...args));
+    }
+    scaleAlphaContinuous(...args: Parameters<typeof scaleAlphaContinuous>): GGBuilder {
+      return this.scales(scaleAlphaContinuous(...args));
+    }
+    scaleAlphaDate(...args: Parameters<typeof scaleAlphaDate>): GGBuilder {
+      return this.scales(scaleAlphaDate(...args));
+    }
+    scaleAlphaDatetime(...args: Parameters<typeof scaleAlphaDatetime>): GGBuilder {
+      return this.scales(scaleAlphaDatetime(...args));
+    }
+    scaleAlphaDiscrete(...args: Parameters<typeof scaleAlphaDiscrete>): GGBuilder {
+      return this.scales(scaleAlphaDiscrete(...args));
+    }
+    scaleAlphaIdentity(...args: Parameters<typeof scaleAlphaIdentity>): GGBuilder {
+      return this.scales(scaleAlphaIdentity(...args));
+    }
+    scaleAlphaManual(...args: Parameters<typeof scaleAlphaManual>): GGBuilder {
+      return this.scales(scaleAlphaManual(...args));
+    }
+    scaleAlphaOrdinal(...args: Parameters<typeof scaleAlphaOrdinal>): GGBuilder {
+      return this.scales(scaleAlphaOrdinal(...args));
+    }
+    scaleColorBinned(...args: Parameters<typeof scaleColorBinned>): GGBuilder {
+      return this.scales(scaleColorBinned(...args));
+    }
+    scaleColorBrewer(...args: Parameters<typeof scaleColorBrewer>): GGBuilder {
+      return this.scales(scaleColorBrewer(...args));
+    }
+    scaleColorContinuous(...args: Parameters<typeof scaleColorContinuous>): GGBuilder {
+      return this.scales(scaleColorContinuous(...args));
+    }
+    scaleColorDate(...args: Parameters<typeof scaleColorDate>): GGBuilder {
+      return this.scales(scaleColorDate(...args));
+    }
+    scaleColorDatetime(...args: Parameters<typeof scaleColorDatetime>): GGBuilder {
+      return this.scales(scaleColorDatetime(...args));
+    }
+    scaleColorDiscrete(...args: Parameters<typeof scaleColorDiscrete>): GGBuilder {
+      return this.scales(scaleColorDiscrete(...args));
+    }
+    scaleColorDistiller(...args: Parameters<typeof scaleColorDistiller>): GGBuilder {
+      return this.scales(scaleColorDistiller(...args));
+    }
+    scaleColorFermenter(...args: Parameters<typeof scaleColorFermenter>): GGBuilder {
+      return this.scales(scaleColorFermenter(...args));
+    }
+    scaleColorGradient(...args: Parameters<typeof scaleColorGradient>): GGBuilder {
+      return this.scales(scaleColorGradient(...args));
+    }
+    scaleColorGradient2(...args: Parameters<typeof scaleColorGradient2>): GGBuilder {
+      return this.scales(scaleColorGradient2(...args));
+    }
+    scaleColorGradientn(...args: Parameters<typeof scaleColorGradientn>): GGBuilder {
+      return this.scales(scaleColorGradientn(...args));
+    }
+    scaleColorGrey(...args: Parameters<typeof scaleColorGrey>): GGBuilder {
+      return this.scales(scaleColorGrey(...args));
+    }
+    scaleColorHue(...args: Parameters<typeof scaleColorHue>): GGBuilder {
+      return this.scales(scaleColorHue(...args));
+    }
+    scaleColorIdentity(...args: Parameters<typeof scaleColorIdentity>): GGBuilder {
+      return this.scales(scaleColorIdentity(...args));
+    }
+    scaleColorLog10(...args: Parameters<typeof scaleColorLog10>): GGBuilder {
+      return this.scales(scaleColorLog10(...args));
+    }
+    scaleColorManual(...args: Parameters<typeof scaleColorManual>): GGBuilder {
+      return this.scales(scaleColorManual(...args));
+    }
+    scaleColorOrdinal(...args: Parameters<typeof scaleColorOrdinal>): GGBuilder {
+      return this.scales(scaleColorOrdinal(...args));
+    }
+    scaleColorSqrt(...args: Parameters<typeof scaleColorSqrt>): GGBuilder {
+      return this.scales(scaleColorSqrt(...args));
+    }
+    scaleColorSteps(...args: Parameters<typeof scaleColorSteps>): GGBuilder {
+      return this.scales(scaleColorSteps(...args));
+    }
+    scaleColorSteps2(...args: Parameters<typeof scaleColorSteps2>): GGBuilder {
+      return this.scales(scaleColorSteps2(...args));
+    }
+    scaleColorStepsn(...args: Parameters<typeof scaleColorStepsn>): GGBuilder {
+      return this.scales(scaleColorStepsn(...args));
+    }
+    scaleColorViridisB(...args: Parameters<typeof scaleColorViridisB>): GGBuilder {
+      return this.scales(scaleColorViridisB(...args));
+    }
+    scaleColorViridisC(...args: Parameters<typeof scaleColorViridisC>): GGBuilder {
+      return this.scales(scaleColorViridisC(...args));
+    }
+    scaleColorViridisD(...args: Parameters<typeof scaleColorViridisD>): GGBuilder {
+      return this.scales(scaleColorViridisD(...args));
+    }
+    scaleFillBinned(...args: Parameters<typeof scaleFillBinned>): GGBuilder {
+      return this.scales(scaleFillBinned(...args));
+    }
+    scaleFillBrewer(...args: Parameters<typeof scaleFillBrewer>): GGBuilder {
+      return this.scales(scaleFillBrewer(...args));
+    }
+    scaleFillContinuous(...args: Parameters<typeof scaleFillContinuous>): GGBuilder {
+      return this.scales(scaleFillContinuous(...args));
+    }
+    scaleFillDate(...args: Parameters<typeof scaleFillDate>): GGBuilder {
+      return this.scales(scaleFillDate(...args));
+    }
+    scaleFillDatetime(...args: Parameters<typeof scaleFillDatetime>): GGBuilder {
+      return this.scales(scaleFillDatetime(...args));
+    }
+    scaleFillDiscrete(...args: Parameters<typeof scaleFillDiscrete>): GGBuilder {
+      return this.scales(scaleFillDiscrete(...args));
+    }
+    scaleFillDistiller(...args: Parameters<typeof scaleFillDistiller>): GGBuilder {
+      return this.scales(scaleFillDistiller(...args));
+    }
+    scaleFillFermenter(...args: Parameters<typeof scaleFillFermenter>): GGBuilder {
+      return this.scales(scaleFillFermenter(...args));
+    }
+    scaleFillGradient(...args: Parameters<typeof scaleFillGradient>): GGBuilder {
+      return this.scales(scaleFillGradient(...args));
+    }
+    scaleFillGradient2(...args: Parameters<typeof scaleFillGradient2>): GGBuilder {
+      return this.scales(scaleFillGradient2(...args));
+    }
+    scaleFillGradientn(...args: Parameters<typeof scaleFillGradientn>): GGBuilder {
+      return this.scales(scaleFillGradientn(...args));
+    }
+    scaleFillGrey(...args: Parameters<typeof scaleFillGrey>): GGBuilder {
+      return this.scales(scaleFillGrey(...args));
+    }
+    scaleFillHue(...args: Parameters<typeof scaleFillHue>): GGBuilder {
+      return this.scales(scaleFillHue(...args));
+    }
+    scaleFillIdentity(...args: Parameters<typeof scaleFillIdentity>): GGBuilder {
+      return this.scales(scaleFillIdentity(...args));
+    }
+    scaleFillLog10(...args: Parameters<typeof scaleFillLog10>): GGBuilder {
+      return this.scales(scaleFillLog10(...args));
+    }
+    scaleFillManual(...args: Parameters<typeof scaleFillManual>): GGBuilder {
+      return this.scales(scaleFillManual(...args));
+    }
+    scaleFillOrdinal(...args: Parameters<typeof scaleFillOrdinal>): GGBuilder {
+      return this.scales(scaleFillOrdinal(...args));
+    }
+    scaleFillSqrt(...args: Parameters<typeof scaleFillSqrt>): GGBuilder {
+      return this.scales(scaleFillSqrt(...args));
+    }
+    scaleFillSteps(...args: Parameters<typeof scaleFillSteps>): GGBuilder {
+      return this.scales(scaleFillSteps(...args));
+    }
+    scaleFillSteps2(...args: Parameters<typeof scaleFillSteps2>): GGBuilder {
+      return this.scales(scaleFillSteps2(...args));
+    }
+    scaleFillStepsn(...args: Parameters<typeof scaleFillStepsn>): GGBuilder {
+      return this.scales(scaleFillStepsn(...args));
+    }
+    scaleFillViridisB(...args: Parameters<typeof scaleFillViridisB>): GGBuilder {
+      return this.scales(scaleFillViridisB(...args));
+    }
+    scaleFillViridisC(...args: Parameters<typeof scaleFillViridisC>): GGBuilder {
+      return this.scales(scaleFillViridisC(...args));
+    }
+    scaleFillViridisD(...args: Parameters<typeof scaleFillViridisD>): GGBuilder {
+      return this.scales(scaleFillViridisD(...args));
+    }
+    scaleLinetypeBinned(...args: Parameters<typeof scaleLinetypeBinned>): GGBuilder {
+      return this.scales(scaleLinetypeBinned(...args));
+    }
+    scaleLinetypeDiscrete(...args: Parameters<typeof scaleLinetypeDiscrete>): GGBuilder {
+      return this.scales(scaleLinetypeDiscrete(...args));
+    }
+    scaleLinetypeIdentity(...args: Parameters<typeof scaleLinetypeIdentity>): GGBuilder {
+      return this.scales(scaleLinetypeIdentity(...args));
+    }
+    scaleLinetypeManual(...args: Parameters<typeof scaleLinetypeManual>): GGBuilder {
+      return this.scales(scaleLinetypeManual(...args));
+    }
+    scaleLinewidthBinned(...args: Parameters<typeof scaleLinewidthBinned>): GGBuilder {
+      return this.scales(scaleLinewidthBinned(...args));
+    }
+    scaleLinewidthContinuous(...args: Parameters<typeof scaleLinewidthContinuous>): GGBuilder {
+      return this.scales(scaleLinewidthContinuous(...args));
+    }
+    scaleLinewidthDate(...args: Parameters<typeof scaleLinewidthDate>): GGBuilder {
+      return this.scales(scaleLinewidthDate(...args));
+    }
+    scaleLinewidthDatetime(...args: Parameters<typeof scaleLinewidthDatetime>): GGBuilder {
+      return this.scales(scaleLinewidthDatetime(...args));
+    }
+    scaleLinewidthDiscrete(...args: Parameters<typeof scaleLinewidthDiscrete>): GGBuilder {
+      return this.scales(scaleLinewidthDiscrete(...args));
+    }
+    scaleLinewidthIdentity(...args: Parameters<typeof scaleLinewidthIdentity>): GGBuilder {
+      return this.scales(scaleLinewidthIdentity(...args));
+    }
+    scaleLinewidthManual(...args: Parameters<typeof scaleLinewidthManual>): GGBuilder {
+      return this.scales(scaleLinewidthManual(...args));
+    }
+    scaleLinewidthOrdinal(...args: Parameters<typeof scaleLinewidthOrdinal>): GGBuilder {
+      return this.scales(scaleLinewidthOrdinal(...args));
+    }
+    scaleRadius(...args: Parameters<typeof scaleRadius>): GGBuilder {
+      return this.scales(scaleRadius(...args));
+    }
+    scaleShapeBinned(...args: Parameters<typeof scaleShapeBinned>): GGBuilder {
+      return this.scales(scaleShapeBinned(...args));
+    }
+    scaleShapeDiscrete(...args: Parameters<typeof scaleShapeDiscrete>): GGBuilder {
+      return this.scales(scaleShapeDiscrete(...args));
+    }
+    scaleShapeIdentity(...args: Parameters<typeof scaleShapeIdentity>): GGBuilder {
+      return this.scales(scaleShapeIdentity(...args));
+    }
+    scaleShapeManual(...args: Parameters<typeof scaleShapeManual>): GGBuilder {
+      return this.scales(scaleShapeManual(...args));
+    }
+    scaleShapeOrdinal(...args: Parameters<typeof scaleShapeOrdinal>): GGBuilder {
+      return this.scales(scaleShapeOrdinal(...args));
+    }
+    scaleSizeArea(...args: Parameters<typeof scaleSizeArea>): GGBuilder {
+      return this.scales(scaleSizeArea(...args));
+    }
+    scaleSizeBinned(...args: Parameters<typeof scaleSizeBinned>): GGBuilder {
+      return this.scales(scaleSizeBinned(...args));
+    }
+    scaleSizeBinnedArea(...args: Parameters<typeof scaleSizeBinnedArea>): GGBuilder {
+      return this.scales(scaleSizeBinnedArea(...args));
+    }
+    scaleSizeContinuous(...args: Parameters<typeof scaleSizeContinuous>): GGBuilder {
+      return this.scales(scaleSizeContinuous(...args));
+    }
+    scaleSizeDate(...args: Parameters<typeof scaleSizeDate>): GGBuilder {
+      return this.scales(scaleSizeDate(...args));
+    }
+    scaleSizeDatetime(...args: Parameters<typeof scaleSizeDatetime>): GGBuilder {
+      return this.scales(scaleSizeDatetime(...args));
+    }
+    scaleSizeDiscrete(...args: Parameters<typeof scaleSizeDiscrete>): GGBuilder {
+      return this.scales(scaleSizeDiscrete(...args));
+    }
+    scaleSizeIdentity(...args: Parameters<typeof scaleSizeIdentity>): GGBuilder {
+      return this.scales(scaleSizeIdentity(...args));
+    }
+    scaleSizeManual(...args: Parameters<typeof scaleSizeManual>): GGBuilder {
+      return this.scales(scaleSizeManual(...args));
+    }
+    scaleSizeOrdinal(...args: Parameters<typeof scaleSizeOrdinal>): GGBuilder {
+      return this.scales(scaleSizeOrdinal(...args));
+    }
+    scaleXBinned(...args: Parameters<typeof scaleXBinned>): GGBuilder {
+      return this.scales(scaleXBinned(...args));
+    }
+    scaleXContinuous(...args: Parameters<typeof scaleXContinuous>): GGBuilder {
+      return this.scales(scaleXContinuous(...args));
+    }
+    scaleXDate(...args: Parameters<typeof scaleXDate>): GGBuilder {
+      return this.scales(scaleXDate(...args));
+    }
+    scaleXDatetime(...args: Parameters<typeof scaleXDatetime>): GGBuilder {
+      return this.scales(scaleXDatetime(...args));
+    }
+    scaleXDiscrete(...args: Parameters<typeof scaleXDiscrete>): GGBuilder {
+      return this.scales(scaleXDiscrete(...args));
+    }
+    scaleXLog10(...args: Parameters<typeof scaleXLog10>): GGBuilder {
+      return this.scales(scaleXLog10(...args));
+    }
+    scaleXMonthDay(...args: Parameters<typeof scaleXMonthDay>): GGBuilder {
+      return this.scales(scaleXMonthDay(...args));
+    }
+    scaleXReverse(...args: Parameters<typeof scaleXReverse>): GGBuilder {
+      return this.scales(scaleXReverse(...args));
+    }
+    scaleXSqrt(...args: Parameters<typeof scaleXSqrt>): GGBuilder {
+      return this.scales(scaleXSqrt(...args));
+    }
+    scaleXTime(...args: Parameters<typeof scaleXTime>): GGBuilder {
+      return this.scales(scaleXTime(...args));
+    }
+    scaleYBinned(...args: Parameters<typeof scaleYBinned>): GGBuilder {
+      return this.scales(scaleYBinned(...args));
+    }
+    scaleYContinuous(...args: Parameters<typeof scaleYContinuous>): GGBuilder {
+      return this.scales(scaleYContinuous(...args));
+    }
+    scaleYDate(...args: Parameters<typeof scaleYDate>): GGBuilder {
+      return this.scales(scaleYDate(...args));
+    }
+    scaleYDatetime(...args: Parameters<typeof scaleYDatetime>): GGBuilder {
+      return this.scales(scaleYDatetime(...args));
+    }
+    scaleYDiscrete(...args: Parameters<typeof scaleYDiscrete>): GGBuilder {
+      return this.scales(scaleYDiscrete(...args));
+    }
+    scaleYLog10(...args: Parameters<typeof scaleYLog10>): GGBuilder {
+      return this.scales(scaleYLog10(...args));
+    }
+    scaleYMonthDay(...args: Parameters<typeof scaleYMonthDay>): GGBuilder {
+      return this.scales(scaleYMonthDay(...args));
+    }
+    scaleYReverse(...args: Parameters<typeof scaleYReverse>): GGBuilder {
+      return this.scales(scaleYReverse(...args));
+    }
+    scaleYSqrt(...args: Parameters<typeof scaleYSqrt>): GGBuilder {
+      return this.scales(scaleYSqrt(...args));
+    }
+    scaleYTime(...args: Parameters<typeof scaleYTime>): GGBuilder {
+      return this.scales(scaleYTime(...args));
+    }
+  };
+}

package/src/builder.ts

@@ -0,0 +1,125 @@
+/**
+ * The fluent builder — one of the three surfaces that compile to the same
+ * PortableSpec (spec-first design; builder and Svelte components are sugar).
+ *
+ * - `gg(data, aes(...))` returns an immutable builder: every method returns a
+ *   NEW builder (the spec is the explicit first-class value — Hadley lesson 1;
+ *   no `+` operator, no mutation).
+ * - `.layer({ geom, ... })` is the canonical method (one layer concept —
+ *   Hadley lesson 2); `.geomPoint()` / `.geomBar()` / ... are documented
+ *   sugar for it.
+ * - `.spec()` normalizes and VALIDATES, returning a canonical PortableSpec or
+ *   throwing SpecValidationError. Builder output therefore always validates
+ *   against the published JSON Schema (property-tested).
+ *
+ * Implementation:
+ *  - builder-data.ts — Date snapshot / portable ISO materialization
+ *  - builder-options.ts — Geom*Options types
+ *  - builder-core.ts — state, layer/facet/coord/labs/theme/spec
+ *  - builder-geoms.ts — geom* sugar mixin (generated from KNOWN_GEOMS)
+ *  - builder-scales.ts — scaleX/Y/Color/Fill sugar mixin (generated)
+ */
+import type { AesInput } from "./normalize.js";
+import { toAuthoringDataRef, type DataInput } from "./builder-data.js";
+import { GGBuilderCore } from "./builder-core.js";
+import { WithBuilderGeoms } from "./builder-geoms.js";
+import { WithBuilderScales } from "./builder-scales.js";
+import { SpecValidationError } from "./errors.js";
+import type { PortableSpec } from "./schema.js";
+import { validate } from "./validate.js";
+
+export type {
+  AuthoringCellValue,
+  AuthoringColumns,
+  AuthoringDataRef,
+  AuthoringRows,
+  DataInput,
+} from "./builder-data.js";
+
+export type {
+  GeomAreaOptions,
+  GeomBarOptions,
+  GeomBoxplotOptions,
+  GeomColOptions,
+  GeomDensityOptions,
+  GeomDensity2dOptions,
+  GeomDensity2dFilledOptions,
+  GeomDotplotOptions,
+  GeomErrorbarOptions,
+  GeomLinerangeOptions,
+  GeomPointrangeOptions,
+  GeomCrossbarOptions,
+  GeomHistogramOptions,
+  GeomFreqpolyOptions,
+  GeomHlineOptions,
+  GeomJitterOptions,
+  GeomLineOptions,
+  GeomPathOptions,
+  GeomPointOptions,
+  GeomCountOptions,
+  GeomQuantileOptions,
+  GeomContourOptions,
+  GeomRasterOptions,
+  GeomHexOptions,
+  GeomRectOptions,
+  GeomRuleOptions,
+  GeomRugOptions,
+  GeomSegmentOptions,
+  GeomViolinOptions,
+  GeomFunctionOptions,
+  GeomPolygonOptions,
+  GeomAblineOptions,
+  GeomCurveOptions,
+  GeomMapOptions,
+  GeomBlankOptions,
+  GeomSfOptions,
+  GeomSfTextOptions,
+  GeomSfLabelOptions,
+  GeomSpokeOptions,
+  GeomStepOptions,
+  GeomQqOptions,
+  GeomQqLineOptions,
+  GeomSmoothOptions,
+  GeomTextOptions,
+  GeomLabelOptions,
+  GeomTileOptions,
+  GeomBin2dOptions,
+  GeomVlineOptions,
+} from "./builder-options.js";
+
+/**
+ * Identity helper for aesthetic mappings, mirroring ggplot2's aes(). Accepts
+ * the bare-string shorthand ('displ' means { field: 'displ' }); the shorthand
+ * is canonicalized away by normalize() and never reaches the JSON Schema.
+ */
+export function aes(mapping: AesInput): AesInput {
+  return mapping;
+}
+
+/**
+ * Immutable plot builder. Construct with gg(); finish with .spec() (validates)
+ * or .toPortable() (normalize only, no TypeBox).
+ */
+export class GGBuilder extends WithBuilderScales(WithBuilderGeoms(GGBuilderCore)) {
+  /**
+   * Compile to a canonical PortableSpec: normalize then TypeBox-validate.
+   * Throws SpecValidationError when the result does not satisfy the schema.
+   * Prefer {@link toPortable} on chart render paths that already run the
+   * pipeline structural gate — avoids loading typebox/compile into the bundle.
+   */
+  spec(): PortableSpec {
+    const portable = this.toPortable();
+    const result = validate(portable);
+    if (!result.ok) throw new SpecValidationError(result.errors);
+    return result.spec;
+  }
+}
+
+/** Start a plot: gg(data, aes({ x: 'displ', y: 'hwy' })).geomPoint().spec(). */
+export function gg(data?: DataInput, mapping?: AesInput): GGBuilder {
+  return new GGBuilder({
+    ...(data !== undefined && { data: toAuthoringDataRef(data) }),
+    ...(mapping !== undefined && { aes: mapping }),
+    layers: [],
+  });
+}