@ggts-sh/spec 0.43.0

package/src/schema.ts

@@ -0,0 +1,287 @@
+/**
+ * The ggts spec schema — TypeBox is the source of truth (decision 0004).
+ *
+ * These definitions ARE the published JSON Schema (via `Type.Cyclic` for named
+ * `$defs`, emitted to `schema/v0.json` by `scripts/emit-schema.ts`) AND the TS
+ * types (via `Static<>`) AND the runtime validator input (`Value.Check`).
+ * One artifact, no drift.
+ *
+ * Authoring rules (from decision 0004):
+ * - Strict objects everywhere (`additionalProperties: false`).
+ * - Every field carries a description written for LLMs; numeric constraints
+ *   are ALSO stated in descriptions because constrained-decoding grammars may
+ *   drop or reject numeric keywords.
+ * - No bare-string channel shorthand in the schema: agents emit canonical
+ *   channel forms only. The shorthand exists only in the TS builder/adapter.
+ * - Unions are `anyOf` by construction (TypeBox default) — the form OpenAI
+ *   structured outputs accept.
+ * - `Type.Record` is used for `data.columns`/`datasets` only; the artifact
+ *   emitter rewrites its `patternProperties` to `additionalProperties`
+ *   (semantically identical for the `^(.*)$` pattern) so the published
+ *   schema stays inside portable JSON Schema.
+ *
+ * Layout: name registries (`schema-names.ts`), ordered `$defs` bag
+ * (`schema-declarations.ts`), pipeline catalogs (`schema-catalog.ts`), the
+ * Cyclic/Module assembly + imported schemas (`schema-imports.ts`), and the
+ * public Static type bag (`schema-types.ts`). This module is a pure
+ * re-export facade.
+ * `$defs` key **insertion order** in the declarations bag is load-bearing for
+ * the byte-stable `schema/v0.json` artifact.
+ */
+export {
+  CATEGORICAL_SCHEME_NAMES,
+  COLOR_SCHEME_NAMES,
+  CYCLIC_SCHEME_NAMES,
+  LINETYPE_NAMES,
+  MAX_BINNED_BREAKS,
+  MAX_GLOW_RADIUS,
+  MAX_PAINT_STOPS,
+  POINT_SHAPE_NAMES,
+  SEQUENTIAL_SCHEME_NAMES,
+  THEME_NAMES,
+  THEME_NAME_ALIASES,
+} from "./schema-names.js";
+export type { LinetypeName, PointShapeName } from "./schema-names.js";
+
+export {
+  ALIAS_GEOMS,
+  CHANNELS,
+  CURRENT_EDITION,
+  GEOM_ALIASES,
+  GEOM_DEFAULTS,
+  KNOWN_GEOMS,
+  KNOWN_POSITIONS,
+  KNOWN_STATS,
+} from "./schema-catalog.js";
+export type {
+  AliasGeomName,
+  ChannelName,
+  GeomName,
+  NormalizedGeomName,
+  PositionName,
+  StatName,
+} from "./schema-catalog.js";
+
+export {
+  AesSchema,
+  AblineLayerSchema,
+  AreaLayerSchema,
+  BarLayerSchema,
+  Bin2dLayerSchema,
+  BlankLayerSchema,
+  BoxplotLayerSchema,
+  ChannelValueSchema,
+  ColLayerSchema,
+  ContourLayerSchema,
+  CoordFixedSpecSchema,
+  CoordRadialSpecSchema,
+  CoordSfSpecSchema,
+  CoordSpecSchema,
+  CoordTransformAxisSpecSchema,
+  CoordTransformSpecSchema,
+  CountLayerSchema,
+  CrossbarLayerSchema,
+  CurveLayerSchema,
+  DataRefSchema,
+  Density2dFilledLayerSchema,
+  Density2dLayerSchema,
+  DensityLayerSchema,
+  DotplotLayerSchema,
+  ErrorbarLayerSchema,
+  FacetFieldRefSchema,
+  FacetSpecSchema,
+  FacetStripSpecSchema,
+  FreqpolyLayerSchema,
+  FunctionLayerSchema,
+  HexLayerSchema,
+  HistogramLayerSchema,
+  HlineLayerSchema,
+  JitterLayerSchema,
+  LabelLayerSchema,
+  LayerSpecSchema,
+  LinerangeLayerSchema,
+  LineLayerSchema,
+  MapLayerSchema,
+  PathLayerSchema,
+  PlotSpecSchema,
+  PointLayerSchema,
+  PointrangeLayerSchema,
+  PolygonLayerSchema,
+  QuantileLayerSchema,
+  QqLayerSchema,
+  QqLineLayerSchema,
+  RasterLayerSchema,
+  RectLayerSchema,
+  RibbonLayerSchema,
+  RuleLayerSchema,
+  RugLayerSchema,
+  ScalesSchema,
+  SegmentLayerSchema,
+  SfLabelLayerSchema,
+  SfLayerSchema,
+  SfTextLayerSchema,
+  SmoothLayerSchema,
+  SpokeLayerSchema,
+  StepLayerSchema,
+  TemporalParserSpecSchemaRef,
+  TextLayerSchema,
+  TileLayerSchema,
+  VlineLayerSchema,
+  ViolinLayerSchema,
+  SpecModule,
+} from "./schema-imports.js";
+export type { SpecImportSchema } from "./schema-imports.js";
+
+export type {
+  A11yMode,
+  AblineLayer,
+  AblineParams,
+  Aes,
+  AlphaScaleSpec,
+  AreaLayer,
+  AreaParams,
+  AxisGuideSpec,
+  BandAxisGuideSpec,
+  BarLayer,
+  BarParams,
+  Bin2dLayer,
+  Bin2dParams,
+  BlankLayer,
+  BlankParams,
+  BoxplotLayer,
+  BoxplotParams,
+  CellValue,
+  ChannelValue,
+  ColorScaleSpec,
+  ColorStop,
+  ColorbarGuideSpec,
+  ColorstepsGuideSpec,
+  ContourLayer,
+  ContourParams,
+  CoordFixedSpec,
+  CoordRadialSpec,
+  CoordSfSpec,
+  CoordSpec,
+  CoordTransformAxisSpec,
+  CoordTransformSpec,
+  CountLayer,
+  CrossbarLayer,
+  CrossbarParams,
+  CurveLayer,
+  CurveParams,
+  DataColumns,
+  DataName,
+  DataRef,
+  DataValues,
+  Density2dFilledLayer,
+  Density2dLayer,
+  Density2dParams,
+  DensityLayer,
+  DensityParams,
+  DotplotLayer,
+  DotplotParams,
+  ErrorbarLayer,
+  ErrorbarParams,
+  FacetFieldRef,
+  FacetScales,
+  FacetSpec,
+  FacetStripSpec,
+  FreqpolyLayer,
+  FunctionArgs,
+  FunctionLayer,
+  FunctionParams,
+  FunctionRegistryName,
+  GlowSpec,
+  GuideSpec,
+  GuideThemeSpec,
+  GuidesSpec,
+  HexLayer,
+  HexParams,
+  HlineLayer,
+  HlineParams,
+  InlineData,
+  JitterLayer,
+  LabelLayer,
+  LabelParams,
+  Labs,
+  LayerSpec,
+  LegendGuideSpec,
+  LegendSpec,
+  LinerangeLayer,
+  LinerangeParams,
+  LineLayer,
+  LineParams,
+  LinetypeScaleSpec,
+  LinearGradientPaint,
+  MapLayer,
+  MapParams,
+  NoneGuideSpec,
+  NormalizedLayerSpec,
+  NormalizedSpec,
+  PaintSpace,
+  PointLayer,
+  PathLayer,
+  ColLayer,
+  HistogramLayer,
+  PathParams,
+  ColParams,
+  PointParams,
+  PointPosition,
+  PointrangeLayer,
+  PointrangeParams,
+  PolygonLayer,
+  PolygonParams,
+  PortableSpec,
+  PositionParams,
+  PositionScaleSpec,
+  PositiveStyleScaleSpec,
+  QuantileLayer,
+  QuantileParams,
+  QqLayer,
+  QqLineLayer,
+  QqLineParams,
+  QqParams,
+  RadialGradientPaint,
+  GradientPaint,
+  RasterLayer,
+  RasterParams,
+  RectLayer,
+  RectParams,
+  RenderBackend,
+  RibbonLayer,
+  RibbonParams,
+  RuleLayer,
+  RuleParams,
+  RugLayer,
+  RugParams,
+  ScaleExpansion,
+  Scales,
+  SegmentLayer,
+  SegmentParams,
+  SfLabelLayer,
+  SfLabelParams,
+  SfLayer,
+  SfParams,
+  SfTextLayer,
+  SfTextParams,
+  ShapeScaleSpec,
+  SmoothLayer,
+  SmoothParams,
+  SpokeLayer,
+  SpokeParams,
+  StackablePosition,
+  StepLayer,
+  StepParams,
+  SummaryFun,
+  TemporalParserSpec,
+  TextLayer,
+  TextParams,
+  ThemeName,
+  ThemeSpec,
+  TileLayer,
+  TileParams,
+  VlineLayer,
+  VlineParams,
+  ViolinLayer,
+  ViolinParams,
+} from "./schema-types.js";

package/src/stat-reference-build.ts

@@ -0,0 +1,145 @@
+/**
+ * STAT_REFERENCE builder. Gen-only: `scripts/gen-reference-catalogs.ts`.
+ * Runtime uses generated/stat-reference-data.ts.
+ */
+import {
+  GEOM_DEFAULTS,
+  KNOWN_GEOMS,
+  KNOWN_STATS,
+  type GeomName,
+  type StatName,
+} from "./schema-catalog.js";
+import { buildGeomReference } from "./geom-reference-build.js";
+
+const GEOM_REFERENCE = buildGeomReference();
+import { STAT_COLUMNS } from "./validate-data-checks-layer.js";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface StatReferenceEntry {
+  readonly name: StatName;
+  /** Route slug — same as stat name (snake_case). */
+  readonly slug: string;
+  /** Short purpose text for the stat transform. */
+  readonly summary: string;
+  /**
+   * Columns this stat publishes for `{ stat: "…" }` channel resolution
+   * (after_stat). Empty when the stat passes rows through or only rewrites
+   * positions without new after_stat names in STAT_COLUMNS.
+   */
+  readonly generatedColumns: readonly string[];
+  /** Geoms whose layer schema allows this stat. */
+  readonly compatibleGeoms: readonly GeomName[];
+  /** Geoms whose GEOM_DEFAULTS.stat is this stat. */
+  readonly defaultForGeoms: readonly GeomName[];
+}
+
+// ---------------------------------------------------------------------------
+// Hand-authored summaries (module contracts; not inventable from TypeBox alone)
+// ---------------------------------------------------------------------------
+
+/**
+ * One-paragraph purpose for each KNOWN_STATS entry. Source notes live in
+ * packages/core/src/stats/* module headers; keep these short for the index.
+ */
+const STAT_SUMMARIES: Readonly<Record<StatName, string>> = Object.freeze({
+  identity:
+    "Pass rows through unchanged. Default for most geoms: each mapped row becomes one mark with no aggregation.",
+  unique:
+    "Keep one row per distinct mapped (x, y) pair (and group). Use when duplicate coordinates would overplot; default for none.",
+  manual:
+    "Author-supplied after_stat values via params — skip automatic transforms when you already computed summaries.",
+  connect:
+    "Expand successive points into connection vertices (linear, hv, vh, mid) for stepped or path-style joins between observations.",
+  count:
+    "Count rows (or sum weights) per distinct x within each group. Default for geom_bar; publishes after_stat count.",
+  bin: "Bin continuous x into histogram breaks. Publishes count, density, ncount, and ndensity; default for histogram and freqpoly.",
+  bin_hex:
+    "Hexagonal 2D binning over continuous x and y. Publishes count/density columns for geom_hex heatmaps.",
+  bin_2d:
+    "Rectangular 2D binning over continuous x and y. Publishes count/density and bin edges for geom_bin_2d tiles.",
+  smooth:
+    "Fit a smoother (lm or loess) and evaluate along x. Publishes y, ymin, ymax, and se; default for geom_smooth.",
+  quantile:
+    "Estimate conditional quantiles of y given x. Publishes y at each requested probability; default for geom_quantile.",
+  boxplot:
+    "Five-number summary per group (hinges and whiskers). Publishes ymin, lower, middle, upper, ymax; default for geom_boxplot.",
+  density:
+    "1D Gaussian kernel density estimate along x. Publishes density, count, scaled, and ndensity; default for geom_density.",
+  summary:
+    "Collapse each discrete-x group to one summary (default mean ± se). Publishes y, ymin, ymax for error-style geoms.",
+  sum: "Count overlapping points at each (x, y) cell for geom_count. Publishes n and prop (not y).",
+  ydensity:
+    "Kernel density along y for violin shapes. Publishes density, count, scaled, violinwidth, and y; default for geom_violin.",
+  function:
+    "Evaluate a pure function on an x grid. Publishes y; default for geom_function when no data rows drive the mark.",
+  ecdf: "Empirical cumulative distribution F̂(x). Publishes ecdf; pair with step or path geoms for CDF plots.",
+  summary_bin:
+    "Bin continuous x, then summarize y in each bin (mean ± se by default). Publishes y, ymin, ymax for binned summaries.",
+  summary_rolling:
+    "Centered rolling window over continuous x (params.window, in x units): summarize y per (group, unique x). Partial windows at the ends are kept. Publishes y.",
+  contour:
+    "Marching-squares isolines over a regular x×y×z grid. Publishes level; default for geom_contour.",
+  align:
+    "Interpolate series onto a shared x grid so continuous-x stacks and overlays line up (stack-friendly zeros outside range).",
+  density_2d:
+    "Bivariate KDE with isolines. Publishes level and density; default for geom_density_2d.",
+  density_2d_filled:
+    "Bivariate KDE with closed density rings for filled contours. Publishes level and density; default for geom_density_2d_filled.",
+  bindot:
+    "Histodot binning for geom_dotplot: one stack position per observation. Publishes stackpos (and bin occupancy).",
+  ellipse:
+    "Confidence ellipse over bivariate points (level and type from params). Passes geometry suited to path/polygon-style marks.",
+  sf: "Simple-features geometry expansion for geom_sf: multiparts and holes become drawable rings without after_stat columns.",
+  sf_coordinates:
+    "Label anchors from SF geometries for geom_sf_text and geom_sf_label (one point per feature or part).",
+  qq: "Sample vs theoretical quantiles for Q–Q plots. Publishes sample and theoretical; default for geom_qq.",
+  qq_line:
+    "Reference line through Q–Q sample/theoretical quantiles. Publishes sample and theoretical; default for geom_qq_line.",
+});
+
+// ---------------------------------------------------------------------------
+// Build
+// ---------------------------------------------------------------------------
+
+function buildCompatibleGeoms(stat: StatName): readonly GeomName[] {
+  const geoms: GeomName[] = [];
+  for (const geom of KNOWN_GEOMS) {
+    if (GEOM_REFERENCE[geom].allowedStats.includes(stat)) {
+      geoms.push(geom);
+    }
+  }
+  return Object.freeze(geoms);
+}
+
+function buildDefaultForGeoms(stat: StatName): readonly GeomName[] {
+  const geoms: GeomName[] = [];
+  for (const geom of KNOWN_GEOMS) {
+    if (GEOM_DEFAULTS[geom].stat === stat) {
+      geoms.push(geom);
+    }
+  }
+  return Object.freeze(geoms);
+}
+
+function buildEntry(stat: StatName): StatReferenceEntry {
+  const columns = STAT_COLUMNS[stat] ?? [];
+  return Object.freeze({
+    name: stat,
+    slug: stat,
+    summary: STAT_SUMMARIES[stat],
+    generatedColumns: Object.freeze([...columns]),
+    compatibleGeoms: buildCompatibleGeoms(stat),
+    defaultForGeoms: buildDefaultForGeoms(stat),
+  });
+}
+
+export function buildStatReference(): Readonly<Record<StatName, StatReferenceEntry>> {
+  const out = {} as Record<StatName, StatReferenceEntry>;
+  for (const stat of KNOWN_STATS) {
+    out[stat] = buildEntry(stat);
+  }
+  return Object.freeze(out);
+}

package/src/stat-reference.ts

@@ -0,0 +1,38 @@
+/**
+ * STAT_REFERENCE — per-stat API docs for the docs site.
+ *
+ * Catalog data is precomputed (`scripts/gen-reference-catalogs.ts`) so
+ * reference pages never load TypeBox or the validate data-checks path.
+ * Stats are not Svelte components: set `stat` on a `<Geom*>` shell or JSON layer.
+ */
+import { KNOWN_STATS, type GeomName, type StatName } from "./schema-catalog.js";
+import { STAT_REFERENCE_DATA } from "./generated/stat-reference-data.js";
+
+export interface StatReferenceEntry {
+  readonly name: StatName;
+  /** Route slug — same as stat name (snake_case). */
+  readonly slug: string;
+  /** Short purpose text for the stat transform. */
+  readonly summary: string;
+  /**
+   * Columns this stat publishes for `{ stat: "…" }` channel resolution
+   * (after_stat). Empty when the stat passes rows through or only rewrites
+   * positions without new after_stat names in STAT_COLUMNS.
+   */
+  readonly generatedColumns: readonly string[];
+  /** Geoms whose layer schema allows this stat. */
+  readonly compatibleGeoms: readonly GeomName[];
+  /** Geoms whose GEOM_DEFAULTS.stat is this stat. */
+  readonly defaultForGeoms: readonly GeomName[];
+}
+
+/**
+ * Complete per-stat API reference. Keys are exactly KNOWN_STATS.
+ * Precomputed at gen time from GEOM_REFERENCE + STAT_COLUMNS.
+ */
+export const STAT_REFERENCE: Readonly<Record<StatName, StatReferenceEntry>> = STAT_REFERENCE_DATA;
+
+/** Stable list order matching KNOWN_STATS (docs index, search, inventory). */
+export function statReferenceList(): readonly StatReferenceEntry[] {
+  return KNOWN_STATS.map((stat) => STAT_REFERENCE[stat]);
+}

package/src/structural-gate.ts

@@ -0,0 +1,42 @@
+/**
+ * TypeBox-free structural gates that always ran after schema shape success in
+ * validate(). Kept on the render path so pipeline/assemble drop only the
+ * Compile(PlotSpecSchema) tier, not color-scheme / binned-style / guide /
+ * coord-facet checks.
+ */
+import { SpecValidationError, type SpecError } from "./errors.js";
+import {
+  binnedStyleScaleStructuralErrors,
+  colorScaleStructuralErrors,
+  coordFacetStructuralErrors,
+  guideStructuralErrors,
+} from "./validate-structure.js";
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Unconditional structural diagnostics from validate() (pre tier-2 options).
+ * Safe to call without TypeBox / schema-declarations.
+ */
+export function structuralGateErrors(input: unknown): SpecError[] {
+  if (!isRecord(input)) return [];
+  const errors: SpecError[] = [];
+  if (isRecord(input["scales"])) {
+    errors.push(
+      ...colorScaleStructuralErrors(input["scales"]),
+      ...binnedStyleScaleStructuralErrors(input["scales"]),
+    );
+  }
+  const guides = isRecord(input["guides"]) ? input["guides"] : {};
+  const scales = isRecord(input["scales"]) ? input["scales"] : undefined;
+  errors.push(...guideStructuralErrors(guides, scales), ...coordFacetStructuralErrors(input));
+  return errors;
+}
+
+/** Throw SpecValidationError when structuralGateErrors is non-empty. */
+export function assertStructuralGate(input: unknown): void {
+  const errors = structuralGateErrors(input);
+  if (errors.length > 0) throw new SpecValidationError(errors);
+}