@graphysdk/viz-engine 0.0.1-plugins.8 → 0.0.1-plugins.9

package/dist/index.d.ts

@@ -408,6 +408,8 @@ export declare interface AppearanceSpec {
      */
     cornerRadius: number;
     /**
+     * How non-matched observations are de-emphasised when a highlight is active.
+     * See {@link HighlightStyle}: `'dim'` lowers opacity, `'desaturate'` greys them out.
      * @default 'dim'
      */
     highlightStyle: HighlightStyle;
@@ -503,8 +505,11 @@ declare interface Axes {
  * Groups all axis-related settings per axis.
  */
 declare interface AxesConfig {
+    /** Configuration for the horizontal (x) axis. */
     x: XAxisConfig;
+    /** Configuration for the primary vertical (y) axis. */
     y: YAxisConfig;
+    /** Configuration for the secondary y axis, present only on dual-axis charts. */
     ySecondary?: YAxisConfig;
 }
 
@@ -580,7 +585,9 @@ export declare interface AxisTickCandidate {
  * Configuration for a single axis's ticks
  */
 declare interface AxisTicksConfig {
+    /** Whether tick marks and their labels are drawn for this axis. */
     isVisible: boolean;
+    /** Which ticks to label — see {@link AxisLabelMode} (`'auto'` = all, `'edges'` = first/last only). */
     mode: AxisLabelMode;
 }
 
@@ -703,7 +710,7 @@ declare interface BaseGeomOptions<T extends GeomParams> {
      * (average line); `stat.smooth({ method })` fits a regression curve (trendline).
      * @default 'identity'
      */
-    stat?: StatName | StatInput;
+    stat?: StatLayerInput | StatLayerInput[];
     /**
      * How sibling marks sharing an x position are arranged. `'identity'` overlaps them; `'stack'` stacks by
      * `color`; `'dodge'` places them side by side; `'fill'` stacks then normalises each column to 100% (also
@@ -922,6 +929,12 @@ declare type BuiltinParams<G extends string> = G extends GeomName ? Extract<Buil
     geom: G;
 }>['params'] : Record<string, unknown>;
 
+/***************************************************************
+ * Transform Input
+ ***************************************************************/
+/** The built-in transforms; their `transformType` literals form the closed {@link TransformType}. */
+declare type BuiltinTransformInput = ReshapeTransformInput | FilterTransformInput | SortTransformInput | AggregateTransformInput | ConstantTransformInput;
+
 /**
  * Caching decorator for any TextMeasurer implementation.
  *
@@ -1611,7 +1624,7 @@ export declare interface CompiledSpec {
     annotations: CompiledAnnotations;
 }
 
-declare interface CompiledStat {
+export declare interface CompiledStat {
     /** The transformed dataset. */
     data: Dataset;
     /** Any mapping overrides produced by the stat (e.g., `y` → `'count'` for `CountStat`). */
@@ -1878,7 +1891,15 @@ declare interface ConfigCompilerInput {
  * Any omitted group or field falls back to its resolved default.
  */
 declare type ConfigInput = Omit<DeepPartial<ConfigSpec>, 'legend' | 'content'> & {
+    /**
+     * Legend overrides. Overridden from the deep-partial default so it accepts the
+     * flat {@link LegendConfigInput} (`{ position, display }`) rather than a nested partial.
+     */
     legend?: LegendConfigInput;
+    /**
+     * Content overrides. Overridden from the deep-partial default so titles/source
+     * accept the author-friendly {@link ContentInput} shape (strings or rich objects).
+     */
     content?: ContentInput;
 };
 
@@ -1886,7 +1907,9 @@ declare type ConfigInput = Omit<DeepPartial<ConfigSpec>, 'legend' | 'content'> &
  * Config specification with type tag
  */
 declare interface ConfigItem {
+    /** Discriminant marking this as a config item in a pipeable spec. */
     type: 'config';
+    /** The author-supplied partial configuration to merge over the defaults. */
     config: ConfigInput;
 }
 
@@ -1896,13 +1919,26 @@ declare interface ConfigItem {
  * partial {@link ConfigInput} to `config(...)` instead.
  */
 export declare interface ConfigSpec {
+    /**
+     * Locale used to interpret raw string values into numbers/dates (e.g. which
+     * thousands/decimal separators to expect). Acts as the fallback for output
+     * formatting when no separate `formattingLocale` is supplied.
+     * @default 'en-US'
+     */
     parsingLocale: Locale;
+    /** Legend placement and display mode. */
     legend: LegendConfig;
+    /** Per-axis settings for the x, y, and optional secondary y axes. */
     axes: AxesConfig;
+    /** Plot panel framing (the box drawn around the data area). */
     panel: PanelConfig;
+    /** Big-number summary figure shown above or inside the chart. */
     headline: HeadlineConfig;
+    /** Chart-wide number formatting applied by the renderer to every numeric value. */
     numberFormat: NumberFormatConfig;
+    /** Titles, subtitle, caption, and source attribution. */
     content: ContentConfig;
+    /** Render-only styling: text scale, background, border, corner radius, highlight style. */
     appearance: AppearanceSpec;
 }
 
@@ -2251,12 +2287,15 @@ declare interface CreateCommandMetadataOptions {
 }
 
 /**
- * Builds a compiler instance. Pass `geoms` to register custom (or override built-in) geom
- * definitions per-instance — there is no global registry to mutate, so injected geoms never bleed
- * across instances. An injected geom whose `type` matches a built-in overrides it (last write wins).
+ * Builds a compiler instance. Pass `geoms` / `stats` / `transforms` to register custom (or override
+ * built-in) definitions per-instance — there is no global registry to mutate, so injected definitions
+ * never bleed across instances. An injected definition whose `type` matches a built-in overrides it
+ * (last write wins).
  */
 export declare const createCompiler: (opts?: {
     geoms?: readonly Geom[];
+    stats?: readonly Stat[];
+    transforms?: readonly TransformStrategy[];
 }) => Compiler;
 
 /**
@@ -2266,19 +2305,26 @@ export declare const createCompiler: (opts?: {
 export declare function createEmptyHighlight(strategy: HighlightStrategy | null): CompiledLayerHighlight | null;
 
 /**
- * Builds a Graphy authoring surface for a set of custom geoms and/or annotations: a `geom` builder that
- * merges the built-in methods with one method per registered custom geom, an `annotation` builder that
- * merges the built-in kinds with one method per registered annotation kind, plus the standard
- * `createSpec`. The 90% case stays the plain `import { geom, annotation, createSpec }`; reach for this only
- * when authoring custom geoms (decision 8) or custom annotations (ADR-035). Registration is per-instance —
- * geoms are injected to `createCompiler({ geoms })`; annotations need no compile-side registry (coordinate
- * resolution is generic), only the render plugin via `<GraphProvider annotationPlugins={[...]}>`.
+ * Builds a Graphy authoring surface for a set of custom geoms, stats, transforms, and/or annotations: a
+ * `geom` builder merging the built-in methods with one per registered custom geom, a `stat` builder
+ * merging the built-in stats with one per registered custom stat, a `transform` builder merging the
+ * built-in transforms with one per registered custom transform, an `annotation` builder merging the
+ * built-in kinds with one per registered annotation kind, plus the standard `createSpec`. The 90% case
+ * stays the plain `import { geom, stat, transform, annotation, createSpec }`; reach for this only when
+ * authoring custom geoms (ADR-033), stats/transforms (ADR-039), or annotations (ADR-035). Registration is
+ * per-instance — geoms, stats, and transforms are injected to `createCompiler({ geoms, stats, transforms })`;
+ * annotations need no compile-side registry (coordinate resolution is generic), only the render plugin via
+ * `<GraphProvider annotationPlugins={[...]}>`.
  */
-export declare function createGraphyBuilder<const Geoms extends readonly Geom[] = readonly [], const Annotations extends readonly AnnotationDef[] = readonly []>(options: {
+export declare function createGraphyBuilder<const Geoms extends readonly Geom[] = readonly [], const Stats extends readonly StatDef[] = readonly [], const Transforms extends readonly TransformDef[] = readonly [], const Annotations extends readonly AnnotationDef[] = readonly []>(options: {
     geoms?: Geoms;
+    stats?: Stats;
+    transforms?: Transforms;
     annotations?: Annotations;
 }): {
     geom: typeof geom & CustomGeomBuilders<Geoms>;
+    stat: typeof stat & CustomStatBuilders<Stats>;
+    transform: typeof transform & CustomTransformBuilders<Transforms>;
     annotation: typeof annotation & CustomAnnotationBuilders<Annotations>;
     createSpec: typeof createSpec;
 };
@@ -2411,7 +2457,7 @@ declare type CustomGeomBuilders<Geoms extends readonly Geom[]> = {
  */
 declare interface CustomGeomOptions<TParams extends object, TAes extends string> {
     aes?: Partial<Record<TAes, AestheticValue>>;
-    stat?: StatName | StatInput;
+    stat?: StatLayerInput | StatLayerInput[];
     position?: PositionType;
     yScaleType?: YScaleType;
     params?: Partial<TParams>;
@@ -2448,6 +2494,46 @@ declare type CustomPaletteInput = {
 
 export declare type CustomPalettesInput = Record<string, string[]>;
 
+/**
+ * One builder method per registered custom stat, keyed by its `type` and typed from its definition — so
+ * `stat.shareOfTotal(...)` exists because `shareOfTotal` was registered, with options checked against the
+ * stat's resolved spec. The options argument is required only when the stat declares a required option;
+ * a stat with no options or only optional ones is callable with none.
+ */
+declare type CustomStatBuilders<Stats extends readonly StatDef[]> = {
+    [Definition in Stats[number] as Definition['type']]: Partial<StatOptionsOf<Definition>> extends StatOptionsOf<Definition> ? (options?: StatOptionsOf<Definition>) => CustomStatInput : (options: StatOptionsOf<Definition>) => CustomStatInput;
+};
+
+/**
+ * A custom stat's serialised input — its registered `type` plus arbitrary plain-data options. Produced
+ * by the `stat.<type>(...)` method of `createGraphyBuilder({ stats })`; carried on a layer's `stat`
+ * field and passed through resolution unchanged (it is already a resolved spec).
+ */
+export declare interface CustomStatInput extends StatSpecBase {
+    [option: string]: unknown;
+}
+
+/**
+ * One builder method per registered custom transform, keyed by its `transformType` and typed from its
+ * definition — so `transform.topN(...)` exists because `topN` was registered, with options checked
+ * against the transform's options. The options argument is required only when the transform declares a
+ * required option; a transform with no options or only optional ones is callable with none.
+ */
+declare type CustomTransformBuilders<Transforms extends readonly TransformDef[]> = {
+    [Definition in Transforms[number] as Definition['transformType']]: Partial<TransformOptionsOf<Definition>> extends TransformOptionsOf<Definition> ? (options?: TransformOptionsOf<Definition>) => CustomTransformInput : (options: TransformOptionsOf<Definition>) => CustomTransformInput;
+};
+
+/**
+ * A custom transform's serialised input — its registered `transformType` plus plain-data options.
+ * Produced by the `transform.<type>(...)` method of `createGraphyBuilder({ transforms })`; carried on a
+ * spec or layer `transforms` array and dispatched by `transformType` like any built-in.
+ */
+export declare interface CustomTransformInput {
+    type: 'transform';
+    transformType: string;
+    options?: Record<string, unknown>;
+}
+
 /**
  * The raw input dataset to visualize, structured as a table of `columns` + `rows`. This is what you
  * hand to the compiler and to `<GraphProvider data>` — the untransformed, pre-compile shape, distinct
@@ -2842,9 +2928,13 @@ declare type DatetimeTickIntervalUnit = 'hour' | 'day' | 'week' | 'month' | 'qua
 /**
  * Recursively makes every property of `T` optional.
  * Unlike the built-in `Partial`, this applies to nested objects as well.
+ *
+ * An `unknown`/`any` property is treated as a leaf (kept as-is) rather than recursed into — recursing an
+ * open value bag like `Record<string, unknown>` would otherwise rewrite each `unknown` value to `{}`,
+ * making the original value un-assignable to its own `DeepPartial`.
  */
 declare type DeepPartial<T> = {
-    [K in keyof T]?: T[K] extends Array<infer U> ? Array<DeepPartial<U>> : NonNullable<T[K]> extends object ? DeepPartial<NonNullable<T[K]>> : T[K];
+    [K in keyof T]?: unknown extends T[K] ? T[K] : T[K] extends Array<infer U> ? Array<DeepPartial<U>> : NonNullable<T[K]> extends object ? DeepPartial<NonNullable<T[K]>> : T[K];
 };
 
 export declare const DEFAULT_COLOR_PALETTE: string[];
@@ -2881,6 +2971,46 @@ export declare function defineAnnotation<const TType extends string, TParams ext
     coordinates?: AnnotationArity;
 }): AnnotationDef<TParams, TType>;
 
+/**
+ * Declares a custom stat — the grammar-correct home for a per-group derived value (share-of-total,
+ * running total, rank, z-score). The `compute` receives the layer dataset, the effective mapping, the
+ * resolved spec, and a `column` namespacing helper; it returns the transformed dataset plus any mapping
+ * rebinding (`{ y: column('share') }`), exactly as the built-in `count`/`smooth` stats do.
+ *
+ * `TSpec` is the resolved spec interface (its `type` literal plus options). Declare it so the builder
+ * method `stat.<type>(options)` is typed; the compute reads `input.spec` narrowed to it.
+ *
+ * @example
+ *   interface ShareStatSpec { type: 'shareOfTotal'; field: string }
+ *   export const shareOfTotal = defineStat<ShareStatSpec>({
+ *     type: 'shareOfTotal',
+ *     computedColumns: ['share'],
+ *     computedVariables: ['y'],
+ *     compute: ({ data, spec, column }) => {
+ *       const total = data.getValues(spec.field, { type: 'numeric', skipNulls: true }).reduce((a, b) => a + b, 0);
+ *       const share = column('share');
+ *       const values = data.getValues(spec.field, { type: 'numeric' }).map((v) => (v ?? 0) / total);
+ *       return { data: data.addVariable(share, 'numeric', values), mapping: { y: share } };
+ *     },
+ *   });
+ */
+export declare function defineStat<const TSpec extends StatSpecBase = StatSpecBase>(manifest: StatDefinitionManifest<TSpec>): StatDef<TSpec>;
+
+/**
+ * Declares a custom transform — mapping-blind, whole-table reshaping (top-N-with-"Other", an exotic
+ * fold/pivot) the five built-ins don't cover. Prefer a stat (`defineStat`) for any per-group derived
+ * value; reach for a transform only to reshape the table itself. The `apply` receives the dataset and
+ * the transform's options and returns a new dataset.
+ *
+ * @example
+ *   interface TopNOptions { valueName: string; n: number }
+ *   export const topN = defineTransform<'topN', TopNOptions>({
+ *     transformType: 'topN',
+ *     apply: (data, { valueName }) => data.orderBy(valueName, 'desc'), // …keep first n, fold rest into "Other"…
+ *   });
+ */
+export declare function defineTransform<const TType extends string, TOptions extends object = object>(manifest: TransformDefinitionManifest<TType, TOptions>): TransformDef<TType, TOptions>;
+
 declare interface DifferenceArrowDimensions {
     /** Gap between the arrow start point and its anchored observation. */
     arrowStartGap: number;
@@ -3495,8 +3625,10 @@ declare interface GeomMappingValidationInput {
 /** A built-in geom's name — the default vocabulary the spec builder offers out of the box. */
 export declare type GeomName = (typeof GEOM_NAMES)[number];
 
+/** {@link BaseGeomOptions} specialised to geom `G`, so its `params` is typed to that geom's param shape. */
 declare type GeomOptions<G extends GeomName> = BaseGeomOptions<GeomParamsMap[G]>;
 
+/** Union of every built-in geom's params type; the upper bound for {@link BaseGeomOptions}'s generic. */
 declare type GeomParams = GeomParamsMap[keyof GeomParamsMap];
 
 /**
@@ -4476,13 +4608,27 @@ declare interface LayerCompilerInput {
  */
 declare type LayerInput = BuiltinLayerInput | CustomLayerInput;
 
+/**
+ * Geom-agnostic fields shared by every layer input, before resolution. Builders produce this shape (with
+ * `geom` and `params` added per geom); all fields are optional and filled with defaults during resolution.
+ */
 declare interface LayerInputBase {
+    /** Discriminant marking this spec item as a layer. */
     type: 'layer';
+    /** Optional stable identifier for the layer; auto-assigned during resolution when omitted. */
     id?: string;
+    /**
+     * Layer-level aesthetic mapping (the builder's `aes`), shallow-merged OVER the spec-level mapping for this
+     * layer only. Retargets a channel per layer or pins a constant via `{ y: { value } }`.
+     */
     mapping?: AesMapping;
-    stat?: StatName | StatInput;
+    /** Statistical transform(s) applied before positioning — a single stat or a pipeline. @default 'identity' */
+    stat?: StatLayerInput | StatLayerInput[];
+    /** How sibling marks sharing an x position are arranged (`'stack'`, `'dodge'`, `'fill'`, `'identity'`). Default is per-geom. */
     position?: PositionType;
+    /** Which Y axis the layer binds to — `'secondary'` targets the right-hand axis in a dual-axis combo. @default 'primary' */
     yScaleType?: YScaleType;
+    /** Per-observation value labels drawn on the marks. @default off */
     dataLabels?: DataLabelsInput;
     /**
      * Ordered transforms applied to this layer's view of the data, on top of any
@@ -4497,6 +4643,7 @@ declare interface LayerInputBase {
     interactive?: boolean;
 }
 
+/** A built-in layer input narrowed to geom `G`: the shared base plus that geom's tag and partial `params`. */
 declare type LayerInputOf<G extends GeomName> = LayerInputBase & {
     geom: G;
     params?: Partial<GeomParamsMap[G]>;
@@ -4507,18 +4654,32 @@ declare type LayerInputOf<G extends GeomName> = LayerInputBase & {
  */
 declare type LayerSpec = BuiltinLayerSpec | CustomLayerSpec;
 
+/**
+ * Geom-agnostic fields shared by every resolved layer spec. Mirrors {@link LayerInputBase} with all fields
+ * required and defaults applied (`stat` resolved to {@link ResolvedStatSpec}[], `dataLabels` fully expanded).
+ */
 declare interface LayerSpecBase {
+    /** Discriminant marking this spec item as a layer. */
     type: 'layer';
+    /** Resolved stable identifier for the layer (always present after resolution). */
     id: string;
+    /** Resolved aesthetic mapping for this layer, merged from spec-level and layer-level inputs. */
     mapping: AesMapping;
-    stat: StatSpec;
+    /** Resolved statistical-transform pipeline (empty array means identity). */
+    stat: ResolvedStatSpec[];
+    /** Resolved arrangement of sibling marks at the same x position. */
     position: PositionType;
+    /** Resolved Y-axis binding (`'primary'` or `'secondary'`). */
     yScaleType: YScaleType;
+    /** Resolved ordered transforms applied to this layer's view of the data. */
     transforms: TransformInput[];
+    /** Whether the layer participates in hover hit-detection. */
     interactive: boolean;
+    /** Resolved per-observation data-labels configuration. */
     dataLabels: DataLabelsConfig;
 }
 
+/** A resolved built-in layer spec narrowed to geom `G`: the shared base plus that geom's tag and full `params`. */
 declare type LayerSpecOf<G extends GeomName> = LayerSpecBase & {
     geom: G;
     params: GeomParamsMap[G];
@@ -4554,7 +4715,7 @@ declare interface LayerValidationCheckInput {
 declare interface LayerValidationInput {
     layerId: string;
     geom: GeomIdentity;
-    stat: StatSpec;
+    stat: ResolvedStatSpec[];
     /** `spec.mapping` merged with `layer.mapping` */
     effectiveMapping: AesMapping;
     /** Layer's dataset after its own transforms have been applied */
@@ -4593,6 +4754,9 @@ declare class LayerValidator {
      * without a `validateMapping` hook impose none.
      */
     private validateGeomMapping;
+    /** Unions the `computedVariables` of every stat in the layer's pipeline — any aesthetic computed by
+     *  any stage is waived from the pre-stat existence/required checks. */
+    private collectComputedVariables;
     /**
      * Rejects a layer whose coord is absent from the geom's declared `supportedCoordTypes` (e.g. a rule
      * has no meaning under polar pie/donut coords). The supported set lives on the geom definition, so
@@ -5136,7 +5300,9 @@ declare interface PaletteScaleSpec {
  * Panel configuration
  */
 declare interface PanelConfig {
+    /** Border drawn around the plot panel (the data area). */
     border: {
+        /** Whether the panel border is rendered. */
         isVisible: boolean;
     };
 }
@@ -5694,6 +5860,12 @@ export declare interface ResolvedObservationAnchor extends AnchorPosition {
     color: string | undefined;
 }
 
+/**
+ * A fully-resolved stat spec: a built-in {@link StatSpec} or a custom stat's `{ type, ...options }`.
+ * What the {@link StatCompiler} dispatches on and a stat's `compute` receives.
+ */
+export declare type ResolvedStatSpec = StatSpec | CustomStatInput;
+
 /**
  * A custom annotation's coordinate resolved to normalized panel space, in **top-left [0,1]** — the
  * space the draw function paints in. `observation` is attached only for a snap-to-observation
@@ -6485,6 +6657,18 @@ export declare class SpecResolver {
     }): Spec;
 }
 
+/**
+ * Render a {@link SpecInput} as fluent builder source — `pipe(createSpec({…}), geom.x(…), scale.x(…),
+ * config({…}))` — emitting only values that differ from their defaults. Returns `null` when the spec
+ * contains something the builder form cannot faithfully represent (a custom geom, a transform, a polar
+ * coord, …), so the caller can fall back to a literal object and never lose data.
+ *
+ * The defaults are static (data-independent), so this needs no dataset. Position scales are emitted in
+ * the inferred `scale.x(opts)` form on purpose: the resolver only applies context defaults (e.g. a bar
+ * chart's `zero: true`) to inferred scales, so converting them to an explicit type would change the chart.
+ */
+export declare function specToBuilderSource(input: SpecInput): string | null;
+
 export declare interface StackTotalEntry {
     /** Serialised x value for stable join keys across observations. */
     xKey: string;
@@ -6527,9 +6711,11 @@ declare abstract class Stage<Input, Output> {
 
 /**
  * Base class for statistical transformations applied to layer data (e.g. binning, counting, smoothing).
+ * Built-ins use a literal {@link StatName}; custom stats authored with `defineStat` carry any registered
+ * `type` string ({@link StatIdentity}).
  */
-declare abstract class Stat {
-    abstract readonly type: StatName;
+export declare abstract class Stat {
+    abstract readonly type: StatIdentity;
     /**
      * Aesthetics this stat will compute (e.g. count computes 'y'). Used by validation to skip existence checks.
      */
@@ -6563,25 +6749,28 @@ export declare const stat: {
 };
 
 /**
- * Resolves a stat by name and delegates computation.
+ * Resolves stats by name and delegates computation. A layer's `stat` is an ordered pipeline (Decision 8):
+ * each step sees the dataset and effective mapping produced by the previous step, so a later stat can read
+ * an earlier stat's emitted column. Returns the net mapping overrides (last-writer-wins) for the caller to
+ * merge over the layer's effective mapping.
  */
 declare class StatCompiler {
     private readonly registry;
     constructor(registry: StatRegistry);
-    compute(spec: StatSpec, input: {
+    compute(specs: ResolvedStatSpec[], input: {
         data: Dataset;
         mapping: AesMapping;
         xScaleIsDiscrete: boolean;
     }): CompiledStat;
 }
 
-declare interface StatCompilerInput {
+export declare interface StatCompilerInput {
     /** The input dataset. */
     data: Dataset;
     /** The effective mapping for the layer. */
     mapping: AesMapping;
-    /** The resolved stat spec. Narrow by `spec.type` to access stat-specific params. */
-    spec: StatSpec;
+    /** The resolved stat spec (built-in or custom). Narrow by `spec.type` to access stat-specific params. */
+    spec: ResolvedStatSpec;
     /**
      * Whether the x aesthetic resolves to a discrete (band) scale. The `smooth` stat emits one fitted
      * point per observed x when set.
@@ -6589,12 +6778,71 @@ declare interface StatCompilerInput {
     xScaleIsDiscrete: boolean;
 }
 
+/**
+ * A registered custom stat: a {@link Stat} the compiler consumes, carrying the resolved-spec type so
+ * `createGraphyBuilder({ stats })` can type its `stat.<type>(options)` builder method.
+ */
+export declare interface StatDef<TSpec extends StatSpecBase = StatSpecBase> extends Stat {
+    readonly type: TSpec['type'] & string;
+    /**
+     * Phantom — carries the resolved-spec type to the type level so the registration-typed builder can
+     * recover the stat's options. Never set at runtime.
+     */
+    readonly __spec?: TSpec;
+}
+
+/**
+ * The compute input an authored stat receives: the standard {@link StatCompilerInput}, but with `spec`
+ * narrowed to the stat's own resolved spec `TSpec`, plus a `column` helper that namespaces a declared
+ * computed column to a collision-safe internal name (Decision 9).
+ */
+export declare interface StatDefinitionInput<TSpec extends StatSpecBase = StatSpecBase> extends Omit<StatCompilerInput, 'spec'> {
+    /** The resolved spec for this stat — its `type` plus the options the builder passed. */
+    spec: TSpec;
+    /**
+     * Namespaces a column declared in `computedColumns` to `\0graphy\0_<type>_<local>` — globally unique,
+     * so a stat's output can never collide with a user column or another stat. Throws on an undeclared name.
+     * Write the returned name into `addVariable`/`addConstantVariable` and into any `mapping` rebinding.
+     */
+    column: (localName: string) => string;
+}
+
+/**
+ * The manifest passed to {@link defineStat}. Declares the stat's `type`, the columns it emits
+ * (`computedColumns`, namespaced per-type), the aesthetics it rebinds (`computedVariables`, which waive
+ * the validator's pre-stat existence/required checks), and the `compute` itself.
+ */
+export declare interface StatDefinitionManifest<TSpec extends StatSpecBase = StatSpecBase> {
+    /** The registered stat name; keys both the registry and the `stat.<type>(...)` builder method. */
+    type: TSpec['type'] & string;
+    /** Local names of the columns `compute` emits via `column(...)`. Namespaced per-type for collision-safety. */
+    computedColumns?: readonly string[];
+    /** Aesthetics `compute` rebinds (e.g. `'y'`). Waives the validator's pre-stat existence/required checks. */
+    computedVariables?: readonly AestheticKey[];
+    /** Derives the layer's summary from its dataset. Not called on an empty dataset (the base short-circuits). */
+    compute: (input: StatDefinitionInput<TSpec>) => CompiledStat;
+}
+
+/**
+ * The open identity of a stat: a built-in {@link StatName} or any custom stat's `type` string
+ * registered via `createCompiler({ stats })`. The `& {}` keeps the built-in names as autocomplete
+ * candidates without collapsing the union to bare `string` (mirrors `GeomIdentity`).
+ */
+export declare type StatIdentity = StatName | (string & {});
+
 /**
  * Any value the `stat` builder produces — passed as the `stat` option of a geom.
  * The string-shorthand variants (`stat.identity()`, `stat.count()`, `stat.mean()`) carry only
  * a `type`; `smooth` additionally carries the regression parameters.
  */
-declare type StatInput = IdentityStatSpec | CountStatSpec | SmoothStatInput | MeanStatSpec;
+export declare type StatInput = IdentityStatSpec | CountStatSpec | SmoothStatInput | MeanStatSpec;
+
+/**
+ * A single stat a layer's `stat` option accepts — a built-in name, a built-in {@link StatInput}, or a
+ * custom stat input. A layer's `stat` is one of these or an ordered list of them (Decision 8): each step
+ * sees the previous step's emitted columns, e.g. `[stat.percentOfTotal(...), stat.window({ op: 'rank' })]`.
+ */
+declare type StatLayerInput = StatName | StatInput | CustomStatInput;
 
 /**
  * Statistical transformation applied to data before rendering.
@@ -6604,19 +6852,37 @@ declare type StatInput = IdentityStatSpec | CountStatSpec | SmoothStatInput | Me
  * - `'smooth'` — Fit a regression curve through `(x, y)` and emit the fitted points
  * - `'mean'` — Reduce the dataset to a single observation holding the mean of `y`
  */
-declare type StatName = 'identity' | 'count' | 'smooth' | 'mean';
+export declare type StatName = 'identity' | 'count' | 'smooth' | 'mean';
 
 /**
- * Built-in stat implementations keyed by {@link StatName}.
+ * The options a registered custom stat's builder method accepts — its resolved spec minus the `type`
+ * discriminant (the builder fills `type`). Recovered structurally from the definition's phantom spec.
  */
-declare class StatRegistry extends Registry<StatName, Stat> {
-    constructor();
+declare type StatOptionsOf<Definition> = Definition extends StatDef<infer TSpec> ? Omit<TSpec, 'type'> : never;
+
+/**
+ * Stat implementations keyed by `type`. Built-ins are registered first; any custom stats injected via
+ * `createCompiler({ stats })` register afterwards (a custom `type` matching a built-in overrides it,
+ * last write wins) — mirroring `GeomRegistry`.
+ */
+declare class StatRegistry extends Registry<string, Stat> {
+    constructor(opts?: {
+        stats?: readonly Stat[];
+    });
 }
 
 /**
- * Discriminated union of all resolved stat specs (post-resolution).
+ * Discriminated union of all built-in resolved stat specs (post-resolution).
+ */
+export declare type StatSpec = IdentityStatSpec | CountStatSpec | SmoothStatSpec | MeanStatSpec;
+
+/**
+ * The minimal shape every stat spec shares: its `type` discriminant. A custom stat's resolved spec
+ * extends this with arbitrary plain-data options; `defineStat<TSpec>` narrows `TSpec` from it.
  */
-declare type StatSpec = IdentityStatSpec | CountStatSpec | SmoothStatSpec | MeanStatSpec;
+export declare interface StatSpecBase {
+    type: StatIdentity;
+}
 
 /**
  * Sticker annotation: a built-in emoji-like image pinned to a single observation.
@@ -6814,32 +7080,71 @@ declare interface TransformCompilerInput {
     transforms: TransformInput[];
 }
 
-/***************************************************************
- * Transform Input
- ***************************************************************/
+/**
+ * A registered custom transform: a {@link TransformStrategy} the compiler consumes, carrying the option
+ * type so `createGraphyBuilder({ transforms })` can type its `transform.<type>(options)` builder method.
+ */
+export declare interface TransformDef<TType extends string = string, TOptions extends object = object> extends TransformStrategy {
+    readonly transformType: TType;
+    /**
+     * Phantom — carries the options type to the type level so the registration-typed builder can recover
+     * the transform's options. Never set at runtime.
+     */
+    readonly __options?: TOptions;
+}
+
+/**
+ * The manifest passed to {@link defineTransform}. Declares the `transformType` and an `apply` that
+ * reshapes the dataset given the transform's plain-data options.
+ */
+export declare interface TransformDefinitionManifest<TType extends string = string, TOptions extends object = object> {
+    /** The registered transform name; keys both the registry and the `transform.<type>(...)` builder method. */
+    transformType: TType;
+    /** Reshapes the dataset given the transform's options. Mapping-blind, whole-table surgery. */
+    apply: (data: Dataset, options: TOptions) => Dataset;
+}
+
+/**
+ * The open identity of a transform: a built-in {@link TransformType} or any custom transform's
+ * `transformType` string registered via `createCompiler({ transforms })` (mirrors `GeomIdentity`).
+ */
+export declare type TransformIdentity = TransformType | (string & {});
+
 /**
  * Any value the `transform` builder produces. Transforms run before stats and scaling, in the
  * order they appear, reshaping the dataset that every layer then maps over.
  */
-declare type TransformInput = ReshapeTransformInput | FilterTransformInput | SortTransformInput | AggregateTransformInput | ConstantTransformInput;
+export declare type TransformInput = BuiltinTransformInput | CustomTransformInput;
 
 /**
- * Built-in transform implementations keyed by transform type.
+ * The options a registered custom transform's builder method accepts — recovered structurally from the
+ * definition's phantom options type.
  */
-declare class TransformRegistry extends Registry<TransformType, TransformStrategy> {
-    constructor();
+declare type TransformOptionsOf<Definition> = Definition extends TransformDef<string, infer TOptions> ? TOptions : never;
+
+/**
+ * Transform strategies keyed by `transformType`. Built-ins register first; any custom transforms
+ * injected via `createCompiler({ transforms })` register afterwards (a custom `transformType` matching
+ * a built-in overrides it, last write wins) — mirroring `GeomRegistry` / `StatRegistry`.
+ */
+declare class TransformRegistry extends Registry<string, TransformStrategy> {
+    constructor(opts?: {
+        transforms?: readonly TransformStrategy[];
+    });
 }
 
 /**
- * Strategy interface for compiling a specific transform type.
+ * Strategy interface for compiling a specific transform type. Built-ins use a literal
+ * {@link TransformType}; custom transforms authored with `defineTransform` carry any registered
+ * `transformType` string ({@link TransformIdentity}).
  */
-declare interface TransformStrategy {
-    readonly transformType: TransformType;
+export declare interface TransformStrategy {
+    readonly transformType: TransformIdentity;
     apply: (data: Dataset, transform: TransformInput) => Dataset;
 }
 
-/** Discriminant tag of a {@link TransformInput}. */
-declare type TransformType = TransformInput['transformType'];
+/** Discriminant tag of a built-in {@link TransformInput}. */
+export declare type TransformType = BuiltinTransformInput['transformType'];
 
 declare type TrendlineType = 'linear' | 'loess' | 'exponential' | 'logarithmic' | 'quadratic' | 'power' | 'polynomial';
 
@@ -6895,7 +7200,7 @@ declare interface ValueMapping {
 }
 
 /** A column of a variable in the dataset. When `valueFormat` is omitted, the Dataset assigns a type-based default (`numeric → decimal`, `categorical → text`, `temporal → date`). */
-declare type Variable = {
+export declare type Variable = {
     type: DataType;
     values: DataValue[];
     valueFormat?: ValueFormat;
@@ -6910,7 +7215,7 @@ declare type Variable = {
 export declare function variableFor(axis: ChannelAxis, name: string): string;
 
 /** A map of variable names to their type and values. */
-declare type VariableMap = Record<VariableName, Variable>;
+export declare type VariableMap = Record<VariableName, Variable>;
 
 /**
  * Binds a channel to a data column by name. `{ variable: 'revenue' }` reads the `revenue` column
@@ -7009,7 +7314,7 @@ declare interface XAxisConfig {
      */
     label: string | null;
     /**
-     * Position of the y axis.
+     * Position of the x axis.
      * @default 'bottom'
      */
     position: AxisPosition;