@graphysdk/react-renderer 1.9.0-beta.1793879014563 → 1.9.0-beta.1793882432228

package/dist/editable.d.ts

@@ -1,4 +1,7 @@
 import { AxisKey } from '@graphysdk/viz-engine';
+import { BoxSize } from '@graphysdk/viz-engine';
+import { CartesianCoordSystem } from '@graphysdk/viz-engine';
+import { ColorScheme } from '@graphysdk/viz-engine';
 import { Command } from '@graphysdk/viz-engine';
 import { CommandContext } from '@graphysdk/viz-engine';
 import { ComponentType } from 'react';
@@ -13,31 +16,41 @@ import { FormattedAxis } from '@graphysdk/viz-engine';
 import { FormattedHeadline } from '@graphysdk/viz-engine';
 import { FormattedLegend } from '@graphysdk/viz-engine';
 import { FormattingLocale } from '@graphysdk/viz-engine';
+import { GeomName } from '@graphysdk/viz-engine';
+import { GeomStyleReaders } from '@graphysdk/viz-engine';
 import { GraphLayout } from '@graphysdk/viz-engine';
 import { GraphyBadgeVariant } from '@graphysdk/viz-engine';
 import { HeadlineMeasurer } from '@graphysdk/viz-engine';
+import { HoverHit } from '@graphysdk/viz-engine';
 import { IntroStaggerOrder } from '@graphysdk/viz-engine';
 import { JSX } from 'react/jsx-runtime';
+import { LayerIntroPlan } from '@graphysdk/viz-engine';
 import { LegendPosition } from '@graphysdk/viz-engine';
 import { LineType } from '@graphysdk/viz-engine';
 import { MainAxis } from '@graphysdk/viz-engine';
 import { Observation } from '@graphysdk/viz-engine';
 import { ObservationsTarget } from '@graphysdk/viz-engine';
+import { PolarCoordSystem } from '@graphysdk/viz-engine';
 import { PositionAdjustment } from '@graphysdk/viz-engine';
 import { ReactElement } from 'react';
 import { ReactNode } from 'react';
 import { Rect } from '@graphysdk/viz-engine';
+import { RenderHitTester } from '@graphysdk/viz-engine';
 import { ResolvedHeadlineSize } from '@graphysdk/viz-engine';
 import { ResolvedObservationAnchorSpec } from '@graphysdk/viz-engine';
 import { ResolvedPaint } from '@graphysdk/viz-engine';
 import { Scene } from '@graphysdk/viz-engine';
 import { SceneLayer } from '@graphysdk/viz-engine';
+import { SceneLayerFor } from '@graphysdk/viz-engine';
 import { SourceContent } from '@graphysdk/viz-engine';
+import { StyleImageSymbol } from '@graphysdk/viz-engine';
 import { StylePointSymbol } from '@graphysdk/viz-engine';
+import { StyleReadersForLayer } from '@graphysdk/viz-engine';
 import { TextContent } from '@graphysdk/viz-engine';
 import { TextMeasurer } from '@graphysdk/viz-engine';
 import { TextStyle } from '@graphysdk/viz-engine';
 import { TooltipContent } from '@graphysdk/viz-engine';
+import { XYPoint } from '@graphysdk/viz-engine';
 
 /** The pin an annotate menu writes against, resolved from the selected observation. */
 export declare interface AnnotateAnchor {
@@ -296,6 +309,11 @@ export declare interface ControlTooltipProps {
     children: ReactElement;
 }
 
+declare type CoordKind = CoordSystem['type'];
+
+/** Maps a coord-kind discriminator to the corresponding `CoordSystem` member. */
+declare type CoordSystemFor<C extends CoordKind> = C extends 'cartesian' ? CartesianCoordSystem : C extends 'polar' ? PolarCoordSystem : never;
+
 /** A hex picker behind a trigger, for a color none of the swatches offer. */
 export declare const CustomColor: ({ value, onChange, onCommit, popupAttributes, variant, }: CustomColorControlProps) => JSX.Element;
 
@@ -921,7 +939,7 @@ declare const EDITOR_EN_GB: {
                     readonly star: "Star";
                     readonly wye: "Wye";
                 };
-                readonly custom: "Custom";
+                readonly custom: "Custom shape";
                 readonly oversized: "This image is too large. Choose one under 512 KB.";
                 readonly undecodable: "This file could not be read as an image.";
             };
@@ -1635,6 +1653,52 @@ declare interface EditorSurfaceSlotProps {
     animateTransitions: boolean;
 }
 
+/** Round marks of one size, which the outline grows from their edge. */
+declare interface EditOutlineDots {
+    kind: 'dots';
+    /** Each dot's center, in panel pixels. */
+    centers: readonly XYPoint[];
+    /** The diameter every dot covers, its border included, in pixels. */
+    size: number;
+}
+
+/** A filled region, which the outline grows from its edge. */
+declare interface EditOutlineRegion extends MorphingEditOutlineShape {
+    kind: 'region';
+    /** `'evenodd'` punches a subpath inside another out of it, as a ring's hole. */
+    fillRule?: 'nonzero' | 'evenodd';
+}
+
+/** One shape edit mode outlines. It carries no paint: the editor draws the outline round it in its own look. */
+declare type EditOutlineShape = EditOutlineRegion | EditOutlineStroke | EditOutlineDots;
+
+/**
+ * The input a geom's {@link GeomRenderContract.getEditOutlineShapes} receives: the observations to outline as a
+ * layer, and what their shapes are placed and sized by.
+ */
+declare interface EditOutlineShapesInput<G extends GeomName | string = string, C extends CoordKind = CoordKind> {
+    /** The outlined observations. */
+    layer: SceneLayerOf<G>;
+    /** The full layer `layer` was taken from — for context the subset can't see, like a stack's silhouette. */
+    sourceLayer: SceneLayerOf<G>;
+    coordSystem: CoordSystemFor<C>;
+    /** The panel's pixel rect. Shapes are placed in its local `0…width` / `0…height`. */
+    panelRect: GraphLayout['panel'];
+    /** Cascade readers for this layer, for the sizes a shape matches: a line's width, a point's size. */
+    styleReaders: StyleReadersOf<G>;
+    /** Whether the chart animates transitions, for a shape to copy where the geom's paint springs. */
+    animateTransitions: boolean;
+    /** The outlined layer's renderer's {@link GeomRenderContract.symbols}, so a point outline traces only what it draws. */
+    symbols?: readonly PointSymbolName[];
+}
+
+/** A stroke, which the outline grows from either side of its thickness. */
+declare interface EditOutlineStroke extends MorphingEditOutlineShape {
+    kind: 'stroke';
+    /** The thickness the stroke is drawn at, in pixels. */
+    width: number;
+}
+
 /**
  * The chart's text and its size: what the header and footer show, and how large everything is drawn.
  *
@@ -1745,13 +1809,15 @@ declare const EN_GB: {
 };
 
 /** A labeled file picker. A host can swap it for its own upload control. */
-export declare const FileInput: ({ label, accept, onFile, disabled, id }: FileInputControlProps) => JSX.Element;
+export declare const FileInput: ({ label, accept, onFile, disabled, id, variant }: FileInputControlProps) => JSX.Element;
 
 /** A file the host picks. The section decides what to do with it. */
 export declare interface FileInputControlProps extends ControlBaseProps {
     label: string;
     accept: string;
     onFile: (file: File) => void;
+    /** `default` is a button showing the label. `chip` is the icon alone, named by a tooltip, for the end of a row of options. */
+    variant?: 'default' | 'chip';
 }
 
 /**
@@ -1786,6 +1852,186 @@ export declare interface GeomEditMenuActions {
 /** A component is the style menu, the shape hosts already pass; the pair names each action. */
 export declare type GeomEditMenuEntry = ObservationsEditMenu | GeomEditMenuActions;
 
+/** The input a geom's {@link GeomRenderContract.hitTest} factory receives: the render input plus the panel. */
+declare type GeomHitTestInput<G extends GeomName | string = string, C extends CoordKind = CoordKind> = GeomRenderInput<G, C> & {
+    /**
+     * The panel's size in pixels: the data rectangle geoms paint into, already inset from axes and chrome, so marks are
+     * placed in local `0…width` / `0…height`.
+     */
+    panelSize: BoxSize;
+};
+
+/** Page-relative cursor coordinates the push-path tooltip anchors to. */
+declare interface GeomHoverCursor {
+    clientX: number;
+    clientY: number;
+}
+
+/**
+ * Pushes a hovered observation key into the central hover, or clears this layer's hover with `null`.
+ * A non-null key requires a `cursor` — a live geom takes the pointer events the cursor-follow
+ * tooltip would otherwise read, so the anchor can only come from the geom's own handler. Consumed by
+ * {@link LiveGeomApi.pushHover} and returned by `useGeomHover`.
+ */
+declare interface GeomHoverPush {
+    (key: string, cursor: GeomHoverCursor): void;
+    (key: null): void;
+}
+
+/**
+ * The props of a geom's {@link GeomRenderContract.LayerProvider}: always the full layer, whichever subset a paint
+ * inside it receives.
+ */
+declare interface GeomLayerProviderProps<G extends GeomName | string = string, C extends CoordKind = CoordKind> extends GeomRenderInputBase {
+    layer: SceneLayerOf<G>;
+    coordSystem: CoordSystemFor<C>;
+    /** The panel's size in pixels, which changes on every resize frame. */
+    panelSize: BoxSize;
+    children: ReactNode;
+}
+
+/** A live geom's paint function — receives the guaranteed wiring on `input.live`. */
+declare type GeomLiveRenderFn<G extends GeomName | string = string, C extends CoordKind = CoordKind> = (input: GeomLiveRenderInput<G, C>) => ReactNode;
+
+/**
+ * The input a live render (`{ fn, options: { live: true } }`) receives: the standard render
+ * input plus a guaranteed {@link LiveGeomApi}.
+ */
+declare interface GeomLiveRenderInput<G extends GeomName | string = string, C extends CoordKind = CoordKind> extends GeomRenderInput<G, C> {
+    live: LiveGeomApi;
+}
+
+/**
+ * A geom's `render`: either a plain paint function, or a live one paired with `options`, so a geom
+ * that owns its pointer events declares `{ fn, options: { live: true } }` without a second render
+ * entry point.
+ */
+declare type GeomRender<G extends GeomName | string = string, C extends CoordKind = CoordKind> = GeomRenderFn<G, C> | {
+    fn: GeomLiveRenderFn<G, C>;
+    options: GeomRenderOptions;
+};
+
+/**
+ * The render side of a geom: everything a single `(geom, coord)` composition needs to render and
+ * respond to hover. Generic over the geom name and coord kind, so a built-in renderer parameterised
+ * as `GeomRenderContract<'bar', 'cartesian'>` receives param-narrowed inputs (`SceneLayerFor<'bar'>`,
+ * `CartesianCoordSystem`), while the default `<string, CoordKind>` instantiation is the base/custom
+ * contract a plugin author writes against. The geom's name, highlight strategy, and `params` type are
+ * NOT restated here — they are read off the compile definition this contract is bound to (see
+ * {@link defineGeomRenderer}). This is the single declaration of a geom's render contract; the built-in
+ * narrow form below and the base/custom form (`geom-renderer.ts`) are both instantiations of it.
+ */
+declare interface GeomRenderContract<G extends GeomName | string = string, C extends CoordKind = CoordKind> {
+    /** The coord system this contract paints under. A geom may bind one contract per coord. */
+    coord: C;
+    swatchShape?: SwatchShape;
+    /**
+     * The hover-guide mode this `(geom, coord)` draws when it is the hovered layer (a
+     * {@link HoverGuideMode}). Omit it — or contribute `null` — to draw no guide (the geom's mark is its
+     * own highlight). A declared mode the composition can't realize draws nothing: a polar bar's `'band'`
+     * fills a wedge, but a pie/donut (no category band) resolves to an empty one. `resolveHoverGuideMode`
+     * reads the hovered layer's mode to pick the one guide the chart draws.
+     */
+    guideMode?: HoverGuideMode | null;
+    /**
+     * Where a geom `overpaint` lands. `'layer'`, the default, lays it over everything each hook draws.
+     * `'manual'` leaves it to the geom, which wraps its main shapes in `GeomOverpaint` itself so what it draws
+     * before or after them stays clear (a boxplot's whiskers and medians). A manual geom with no wrapper draws
+     * no overpaint.
+     */
+    overpaintPlacement?: OverpaintPlacement;
+    /**
+     * Every point symbol the paint draws, built-in shapes and glyph names, in the order Point shape offers them. A list
+     * also says the paint draws the host's glyphs and uploaded images, as `SymbolFigure` does; any other symbol is drawn
+     * as the first listed. The edit outline traces the listed built-in shapes. Omit it or leave it empty for a circle
+     * alone.
+     */
+    symbols?: readonly PointSymbolName[];
+    /**
+     * Wraps a layer's {@link render}, {@link renderHighlight} and {@link renderHover} in one component, so a value they
+     * share is computed once a layer and reaches them through its own context. It receives the panel, so a paint that
+     * reads only the value it derives re-renders when that value changes, not on every resize.
+     * {@link getEditOutlineShapes} runs outside it.
+     */
+    LayerProvider?: (props: GeomLayerProviderProps<G, C>) => ReactNode;
+    /**
+     * The geom's paint. A plain function paints with the other geoms; the `{ fn, options: { live: true } }`
+     * form paints above the central capture layer for a live or drag-driven geom that owns its pointer events
+     * (force-directed), with the wiring on `input.live`.
+     */
+    render: GeomRender<G, C>;
+    /**
+     * Optional repaint of the matched subset for the highlight overlay. Omit it and the highlight layer
+     * falls back to {@link render}. A geom overrides it when the plain column-grouped render would
+     * misrepresent a matched subset — a bar repaints each matched observation as an isolated stack segment
+     * (from its compiled stack role), so a lone mid-stack match keeps its square-edged silhouette and
+     * single-width border instead of regrouping into a standalone rounded bar.
+     */
+    renderHighlight?: (input: HighlightRenderInput<G, C>) => ReactNode;
+    /** Paints the hovered observation. Omit it for a geom with no hover paint. */
+    renderHover?: (input: HoverRenderInput<G, C>) => ReactNode;
+    /** Paints this layer's related observations when another layer is hovered. Omit it for a geom with none. */
+    renderHoverCompanions?: (input: HoverCompanionsRenderInput<G, C>) => ReactNode;
+    /**
+     * Editing only: the shapes edit mode outlines for the observations in `layer`, as data in panel pixels.
+     * A region is what they cover, one path where there are many, with rounded corners traced into it; a line is
+     * a stroke at the width it is drawn; round marks are dots at their size. Omit it and the editor outlines each
+     * observation's bounding box.
+     */
+    getEditOutlineShapes?: (input: EditOutlineShapesInput<G, C>) => readonly EditOutlineShape[];
+    /**
+     * Render-side spatial query for a `'renderHitTest'` layer whose geometry is precomputed into the
+     * scene (sankey ribbons, treemap tiles, voronoi cells). A
+     * **factory**: given the render input it returns the per-cursor {@link RenderHitTester};
+     * the renderer memoizes the factory on `layer.data` and the panel's size, so the read runs once
+     * per data or panel-size change and the per-move query allocates nothing. The author writes no hook;
+     * the renderer registers the tester on its behalf. The cursor arrives in panel-local `[0,1]` with a
+     * top-left origin — the frame the geom paints in. Returns the declared identity key of the observation
+     * under the cursor, or `null` for a miss.
+     */
+    hitTest?: (input: GeomHitTestInput<G, C>) => RenderHitTester;
+    /** Panel-space anchor for a matched observation; required when the def highlights via overlay-anchor. */
+    getOverlayAnchor?: (input: OverlayAnchorInput<G, C>) => OverlayAnchor | null;
+    /**
+     * The rect an observation is painted in, in panel `[0, 1]` with a top-left origin, where annotations
+     * anchored to it land. Omit it where the geom paints the box its position variables span.
+     */
+    getObservationRect?: (input: ObservationRectInput<G, C>) => Rect | null;
+}
+
+/** A geom's panel-SVG paint function — the plain `render` form. */
+declare type GeomRenderFn<G extends GeomName | string = string, C extends CoordKind = CoordKind> = (input: GeomRenderInput<G, C>) => ReactNode;
+
+declare interface GeomRenderInput<G extends GeomName | string = string, C extends CoordKind = CoordKind> extends GeomRenderInputBase {
+    layer: SceneLayerOf<G>;
+    coordSystem: CoordSystemFor<C>;
+    animateTransitions: boolean;
+    formattingLocale: FormattingLocale;
+    intro?: LayerIntroPlan | null;
+}
+
+/**
+ * The cascade paint context every geom render handler receives. Visual readers such as `getColor`
+ * see the data tier only; plugin paint should read {@link GeomRenderInputBase.styleReaders} so tokens,
+ * overrides, and the built-in default reach the mark.
+ */
+declare interface GeomRenderInputBase {
+    /** The provider's color scheme — pass to `createStyleResolver` when a plugin needs readers beyond this layer. */
+    colorScheme: ColorScheme;
+    /** Cascade readers for this layer: override → data → default, resolved for {@link GeomRenderInputBase.colorScheme}. */
+    styleReaders: GeomStyleReaders;
+}
+
+/** Options for the object form of `render`. */
+declare interface GeomRenderOptions {
+    /**
+     * Paint this render above the central capture layer rather than with the other geoms, for a live or
+     * drag-driven geom that must own its pointer events (force-directed). It still paints in the panel SVG, in
+     * the same units as every other geom. The renderer then supplies {@link GeomLiveRenderInput.live}.
+     */
+    live: true;
+}
+
 declare interface GlyphDefinition {
     name: string;
     definition: GlyphShape;
@@ -1913,6 +2159,8 @@ declare interface GraphHandle {
     canFormatDataLabelsAsPercentages: (layer: SceneLayer, coordType: CoordSystem['type']) => boolean;
     /** Glyphs mounted with this graph. A panel reads these from the handle it targets. */
     getGlyphs: () => readonly GlyphDefinition[];
+    /** What the point renderer under these coords draws, per the plugins the graph was built with. */
+    getPointSymbols: (coordType: CoordSystem['type']) => GeomRenderContract['symbols'];
 }
 
 /** The mode a chart runs in, which `GraphRenderer` takes as a prop and every row of `MODE_RULES` is keyed by. */
@@ -2087,6 +2335,47 @@ declare interface HeadlineSlotProps {
     inDonutHole?: boolean;
 }
 
+/**
+ * The input a geom's {@link GeomRenderContract.renderHighlight} receives: the matched-subset layer plus
+ * the full source layer (context the subset can't see, like a stack's silhouette). A superset of
+ * {@link GeomRenderInput}, so a geom that doesn't override `renderHighlight` still paints through the
+ * plain `render`.
+ */
+declare interface HighlightRenderInput<G extends GeomName | string = string, C extends CoordKind = CoordKind> extends GeomRenderInput<G, C> {
+    /** The full layer `layer` was filtered from — for context the subset can't see, like a stack's silhouette. */
+    sourceLayer: SceneLayerOf<G>;
+}
+
+declare interface HoverCompanionsRenderInput<G extends GeomName | string = string, C extends CoordKind = CoordKind> extends GeomRenderInputBase {
+    layer: SceneLayerOf<G>;
+    coordSystem: CoordSystemFor<C>;
+    primary: HoverHit;
+    related: HoverHit[];
+}
+
+/**
+ * The shape of positional guide the `HoverGuide` draws for a hovered observation, contributed per
+ * `(geom, coord)` renderer via `guideMode`:
+ *
+ * - `'band'` — a rectangle over the hovered category's band on the main axis (bars).
+ * - `'crosshair'` — a rule at the hovered value: a straight line under cartesian, a center-to-edge spoke
+ *   under polar (line and area).
+ *
+ * A renderer that omits `guideMode` draws no guide (scatter points). A declared `'band'` still draws
+ * nothing where the composition has no category band — a pie/donut resolves to an empty wedge. The chart
+ * draws the guide of whichever layer the cursor resolves to, so a combo shows a band over a hovered bar
+ * and a crosshair over a hovered line; see `resolveHoverGuideMode`.
+ */
+declare type HoverGuideMode = 'crosshair' | 'band';
+
+declare interface HoverRenderInput<G extends GeomName | string = string, C extends CoordKind = CoordKind> extends GeomRenderInputBase {
+    layer: SceneLayerOf<G>;
+    coordSystem: CoordSystemFor<C>;
+    primary: HoverHit;
+    group: HoverHit[];
+    related: HoverHit[];
+}
+
 declare type I18nLocale = keyof typeof dictionaries;
 
 declare type I18nRuntimeOverrides = RuntimeOverrides<GraphPhrases>;
@@ -2161,6 +2450,20 @@ declare interface ListProps {
     children: ReactNode;
 }
 
+/**
+ * The wiring handed to a live render via {@link GeomLiveRenderInput.live}. The geom
+ * writes only its simulation, marks, and drag handlers; the renderer owns the push wiring.
+ */
+declare interface LiveGeomApi {
+    /** Feeds the hovered observation's identity key into the unified hover store — the push path. */
+    pushHover: GeomHoverPush;
+    /**
+     * A pointer's client coordinates in the panel's units, whatever the graph's on-screen scale, so a drag
+     * moves a mark to the pointer. `null` before the panel mounts.
+     */
+    readPanelPoint: (cursor: GeomHoverCursor) => PanelPoint | null;
+}
+
 declare type LocaleShape = {
     dir?: TextDirection;
 } & Dictionary<typeof EN_GB>;
@@ -2180,6 +2483,15 @@ declare type LooseValue<T> = T extends (...args: infer A) => infer R ? (...args:
 /** Which column of the data feeds each of the chart's aesthetics. */
 export declare const MappingSection: ({ title, layout }: OverridableSectionProps) => JSX.Element | null;
 
+declare interface MorphingEditOutlineShape {
+    /** SVG path data in panel pixels. */
+    pathData: string;
+    /** Identifies the shape across renders, such as a line's group, so a morph starts from where it was. */
+    key?: string;
+    /** Whether a change of shape morphs to the new one, as the geom's paint does. Snaps when omitted. */
+    animateTransitions?: boolean;
+}
+
 /**
  * A number typed, scrubbed or stepped into a field.
  *
@@ -2216,9 +2528,35 @@ export declare interface NumberFieldControlProps extends ContinuousControlProps<
  */
 export declare const NumberFormatSection: ({ title, layout, preview }: OverridableSectionProps) => JSX.Element | null;
 
+declare interface ObservationRectInput<G extends GeomName | string = string, C extends CoordKind = CoordKind> {
+    layer: SceneLayerOf<G>;
+    coordSystem: CoordSystemFor<C>;
+    observation: Observation;
+    panelRect: GraphLayout['panel'];
+    styleReaders: StyleReadersOf<G>;
+}
+
 /** The rows the overlay menu draws under its title for a selection of observations. */
 export declare type ObservationsEditMenu = ComponentType<ResolvedObservations> & EditMenuRows<ObservationsTarget>;
 
+/**
+ * Anchor point in normalized [0,1] coord-space where a highlight overlay marker
+ * should be painted for one observation. Renderer turns [0,1] into pixels.
+ */
+declare interface OverlayAnchor {
+    x: number;
+    y: number;
+}
+
+declare interface OverlayAnchorInput<G extends GeomName | string = string, C extends CoordKind = CoordKind> {
+    layer: SceneLayerOf<G>;
+    coordSystem: CoordSystemFor<C>;
+    observation: Observation;
+}
+
+/** Where a geom `overpaint` lands: over everything a hook draws, or where the geom wraps it itself. */
+declare type OverpaintPlacement = 'layer' | 'manual';
+
 /**
  * What a host may override per section, spread by every section onto its `Section`, so the same
  * section can be mounted at two layouts without being forked to get them.
@@ -2248,6 +2586,12 @@ declare interface PanelExpansion {
     collapseAllSections: () => void;
 }
 
+/** A point in the panel's own units, the space a geom's `render` paints in. */
+declare interface PanelPoint {
+    x: number;
+    y: number;
+}
+
 declare interface PanelProps extends Omit<PanelRootProps, 'children'> {
     /**
      * Replaces the sections entirely. A panel is a convenience over composing them by hand, so the
@@ -2296,6 +2640,9 @@ export declare const PointEditMenu: {
  */
 export declare const PointSection: ({ title, layout, preview }: OverridableSectionProps) => JSX.Element | null;
 
+/** A point symbol a renderer can list by name: a built-in shape or a registered glyph's name. */
+declare type PointSymbolName = Exclude<StylePointSymbol, StyleImageSymbol>;
+
 /** How big a hole a round chart has, and where its sweep begins. */
 export declare const PolarSection: ({ title, layout, preview }: OverridableSectionProps) => JSX.Element | null;
 
@@ -2328,9 +2675,10 @@ export declare interface RadioGridControlProps extends ContinuousControlProps<st
      * `tile` (default) captions each icon; `swatch` drops the caption for a dense grid of pure
      * pictures — color chips a name would only clutter — naming each in a tooltip and through `aria-label` instead;
      * `icon` drops the tile too, names each in a tooltip and thickens the checked stroke for a 24-unit viewBox;
-     * `track` sets the pictures on a toggle group's sunken track, the checked one raised, each named through `aria-label`.
+     * `track` sets the pictures on a toggle group's sunken track, the checked one raised, each named through `aria-label`;
+     * `chip` packs them as a color row packs its chips, the checked one sunken and ringed, each named in a tooltip.
      */
-    itemLayout?: 'tile' | 'swatch' | 'icon' | 'track';
+    itemLayout?: 'tile' | 'swatch' | 'icon' | 'track' | 'chip';
 }
 
 /** A choice in a `RadioGrid`, which can sit somewhere other than its turn in the arrow keys' order. */
@@ -2376,6 +2724,13 @@ declare type RuntimeOverrides<Phrases> = {
     [Key in DotNotation<Phrases>]?: OverridePhrase<Phrases, Key>;
 };
 
+/**
+ * The compiled layer a renderer's handlers receive. A built-in renderer keyed to a `GeomName` gets
+ * its param-narrowed `SceneLayerFor<G>`; a custom renderer (`G = string`) is downstream of
+ * serialization, never sees the plugins array, and reads the base {@link SceneLayer} dynamically.
+ */
+declare type SceneLayerOf<G extends GeomName | string> = G extends GeomName ? SceneLayerFor<G> : SceneLayer;
+
 /**
  * One block of a panel: a heading, and the settings under it. Defaults to `fixed`, so a section that
  * forgot to declare a layout shows its controls rather than hiding them.
@@ -2500,6 +2855,12 @@ declare interface SourceStyle {
     link: TextStyle;
 }
 
+/**
+ * The style readers a handler that cannot call `useGeomStyleReader` receives: a built-in geom's own, whose
+ * builtin-backed properties resolve NonNullable, and the shared readers for a custom geom.
+ */
+declare type StyleReadersOf<G extends GeomName | string> = G extends GeomName ? StyleReadersForLayer<SceneLayerFor<G>> : GeomStyleReaders;
+
 /**
  * Whether the chart shows its subtitle, and what it says.
  *