insomni-plot 0.1.0-alpha.0

package/src/marks.ts

@@ -0,0 +1,1292 @@
+import {
+  BLACK,
+  type Color,
+  type Group,
+  type Layer,
+  type LineCap,
+  type LineJoin,
+  polylineEllipseRing,
+  polylineRectRing,
+  type Vec2,
+} from "insomni";
+import { resamplePoints, type LineCurve } from "./marks/curve.ts";
+import { stack, type StackOffset, type StackOrder, type StackSegment } from "./marks/stack.ts";
+import type { BandScale, ContinuousScale, GroupedBandScale } from "./scales.ts";
+import { DEFAULT_OVERLAY_SCALE } from "./grammar/constants.ts";
+
+export {
+  cardinalCurve,
+  defineCurve,
+  resamplePoints,
+  type CustomCurve,
+  type LineCurve,
+  type LineCurvePreset,
+} from "./marks/curve.ts";
+export {
+  stack,
+  type StackOffset,
+  type StackOptions,
+  type StackOrder,
+  type StackSegment,
+} from "./marks/stack.ts";
+
+// ---------------------------------------------------------------------------
+// Shared types
+// ---------------------------------------------------------------------------
+
+export interface MarkOrigin {
+  x?: number;
+  y?: number;
+}
+
+export interface MarkBuilder {
+  addTo(layer: Layer, origin?: MarkOrigin): Layer;
+  readonly length: number;
+}
+
+export type Accessor<T, V> = (datum: T, index: number) => V;
+export type ValueOrAccessor<T, V> = V | Accessor<T, V>;
+
+function resolve<T, V>(value: ValueOrAccessor<T, V>, datum: T, index: number): V {
+  return typeof value === "function" ? (value as Accessor<T, V>)(datum, index) : value;
+}
+export { resolve as resolveValueOrAccessor };
+
+// Hoist the typeof/?? branching out of inner loops: pick once per render,
+// then call the returned function per datum.
+function toAccessor<T, V>(value: ValueOrAccessor<T, V> | undefined, fallback: V): Accessor<T, V> {
+  if (value === undefined) return () => fallback;
+  if (typeof value === "function") return value as Accessor<T, V>;
+  return () => value;
+}
+
+function toAccessorOrUndefined<T, V>(
+  value: ValueOrAccessor<T, V> | undefined,
+): Accessor<T, V | undefined> {
+  if (value === undefined) return () => undefined;
+  if (typeof value === "function") return value as Accessor<T, V>;
+  return () => value;
+}
+
+// ---------------------------------------------------------------------------
+// pointMark
+// ---------------------------------------------------------------------------
+
+/**
+ * Discrete marker glyphs for `pointMark`. The first four are filled solids;
+ * the `-open` variants render the same outline with no fill (caller must
+ * supply a stroke). `cross`, `plus`, and `star` are filled glyphs whose
+ * "arm" thickness scales with `radius`.
+ */
+export type PointShapeKind =
+  | "circle"
+  | "square"
+  | "triangle"
+  | "diamond"
+  | "circle-open"
+  | "square-open"
+  | "triangle-open"
+  | "diamond-open"
+  | "cross"
+  | "plus"
+  | "star";
+
+/** Shape ordering used by the default categorical shape scale. */
+export const POINT_SHAPE_PALETTE: readonly PointShapeKind[] = [
+  "circle",
+  "triangle",
+  "square",
+  "diamond",
+  "plus",
+  "cross",
+  "star",
+  "circle-open",
+  "triangle-open",
+  "square-open",
+  "diamond-open",
+];
+
+/**
+ * Border treatment applied orthogonally to a point's shape kind.
+ *
+ * - `"solid"` (default): existing behavior — fill + optional solid stroke.
+ * - `"open"`: fill is suppressed; stroke uses `stroke ?? fill` as the color
+ *   (equivalent to the `-open` shape variants, but composable with any kind).
+ * - `"dashed"` / `"dotted"`: fill is kept; the stroke is rendered as a polyline
+ *   ring with a dash pattern. Required because SDF strokes don't support
+ *   per-shape dashes; this routes the border through `tessellatePolyline`.
+ */
+export type PointBorderStyle = "solid" | "dashed" | "dotted" | "open";
+
+/** Line-stroke dash treatment. Maps to polyline `dashPattern`. */
+export type LineDashStyle = "solid" | "dashed" | "dotted";
+
+/** Default dash pattern emitted for `"dashed"` border/line styles. */
+export const DASHED_PATTERN: readonly number[] = [4, 4];
+/** Default dash pattern emitted for `"dotted"` border/line styles. */
+export const DOTTED_PATTERN: readonly number[] = [1, 3];
+
+function dashPatternFor(
+  style: PointBorderStyle | LineDashStyle | undefined,
+): readonly number[] | undefined {
+  if (style === "dashed") return DASHED_PATTERN;
+  if (style === "dotted") return DOTTED_PATTERN;
+  return undefined;
+}
+
+export interface PointMarkOptions<T> {
+  x: Accessor<T, number>;
+  y: Accessor<T, number>;
+  radius?: ValueOrAccessor<T, number>;
+  fill?: ValueOrAccessor<T, Color>;
+  stroke?: ValueOrAccessor<T, Color>;
+  strokeWidth?: ValueOrAccessor<T, number>;
+  shape?: ValueOrAccessor<T, PointShapeKind>;
+  /**
+   * Per-datum border treatment (`"solid"` | `"dashed"` | `"dotted"` | `"open"`).
+   * Composes with any shape kind; e.g. `shape: "circle", borderStyle: "open"`
+   * is equivalent to `shape: "circle-open"`. Dashed/dotted borders bypass the
+   * SDF shader (which has no dash support) and route through a polyline ring.
+   */
+  borderStyle?: ValueOrAccessor<T, PointBorderStyle>;
+  /**
+   * Optional secondary glyph drawn on top of the base shape at the same anchor.
+   * Pass `null` to skip overlay for a specific datum. The overlay's radius is
+   * `radius * overlayScale`; its color falls back to the base stroke (or fill
+   * if no stroke) so badges contrast against the base shape.
+   */
+  overlayGlyph?: ValueOrAccessor<T, PointShapeKind | null>;
+  /** Overlay radius as a fraction of the base radius. Default `0.6`. */
+  overlayScale?: ValueOrAccessor<T, number>;
+  /**
+   * Per-datum GPU emphasis key (P5-T3) applied to every primitive a point emits
+   * (base shape + overlay glyph). Used by boxplot/violin point overlays + mean
+   * markers to tag a whole entity's dots with the entity's key. `undefined` →
+   * untagged (no dim).
+   */
+  emphasisKey?: Accessor<T, number | undefined>;
+  group?: Group;
+}
+
+const SQRT3_OVER_2 = Math.sqrt(3) / 2;
+/** Half-thickness of cross/plus arms as a fraction of `radius`. */
+const ARM_HALF = 0.28;
+/** Star inner-vertex radius as a fraction of `radius`. */
+const STAR_INNER = 0.5;
+
+// Precomputed cos/sin values scaled by the appropriate radius factors (1 or STAR_INNER).
+// The angles are -Math.PI / 2 + (i * Math.PI) / 5 for i = 0 to 9.
+const STAR_COS_SIN: readonly { cos: number; sin: number }[] = Array.from({ length: 10 }, (_, i) => {
+  const angle = -Math.PI / 2 + (i * Math.PI) / 5;
+  const scale = i % 2 === 0 ? 1 : STAR_INNER;
+  return { cos: Math.cos(angle) * scale, sin: Math.sin(angle) * scale };
+});
+
+/**
+ * Emit a filled polygon plus an optional solid stroke outline.
+ *
+ * v3's `PolygonShape` is fill-only (stroke is a separate polyline ring, not a
+ * field), so this mirrors the rect/ellipse stroked-shape pattern: push a
+ * fill-only polygon when a real fill is present, and push a closed-loop
+ * polyline ring over the same points when a stroke is present. A stroke-only
+ * mark (no fill) emits only the ring — v3 requires `fill`, so `pushPolygon` is
+ * never called without one.
+ */
+export function pushFilledPolygon(
+  layer: Layer,
+  points: readonly Vec2[],
+  opts: PolygonOpts & { holes?: readonly (readonly Vec2[])[] },
+): void {
+  const { fill, stroke, strokeWidth, holes, group, emphasisKey } = opts;
+  if (fill !== undefined) {
+    layer.pushPolygon({ points, holes, fill, group, emphasisKey });
+  }
+  if (stroke !== undefined && strokeWidth !== undefined && strokeWidth > 0) {
+    layer.pushPolyline({
+      points,
+      color: stroke,
+      width: strokeWidth,
+      closed: true,
+      group,
+      emphasisKey,
+    });
+  }
+}
+
+function addTriangle(layer: Layer, cx: number, cy: number, r: number, opts: PolygonOpts): void {
+  const points: Vec2[] = [
+    { x: cx, y: cy - r },
+    { x: cx + r * SQRT3_OVER_2, y: cy + r * 0.5 },
+    { x: cx - r * SQRT3_OVER_2, y: cy + r * 0.5 },
+  ];
+  pushFilledPolygon(layer, points, opts);
+}
+
+function addDiamond(layer: Layer, cx: number, cy: number, r: number, opts: PolygonOpts): void {
+  const points: Vec2[] = [
+    { x: cx, y: cy - r },
+    { x: cx + r, y: cy },
+    { x: cx, y: cy + r },
+    { x: cx - r, y: cy },
+  ];
+  pushFilledPolygon(layer, points, opts);
+}
+
+function addPlusPoints(cx: number, cy: number, r: number, rotation: number): Vec2[] {
+  const a = ARM_HALF * r;
+  if (rotation === 0) {
+    return [
+      { x: cx - a, y: cy - r },
+      { x: cx + a, y: cy - r },
+      { x: cx + a, y: cy - a },
+      { x: cx + r, y: cy - a },
+      { x: cx + r, y: cy + a },
+      { x: cx + a, y: cy + a },
+      { x: cx + a, y: cy + r },
+      { x: cx - a, y: cy + r },
+      { x: cx - a, y: cy + a },
+      { x: cx - r, y: cy + a },
+      { x: cx - r, y: cy - a },
+      { x: cx - a, y: cy - a },
+    ];
+  }
+  const cos = Math.cos(rotation);
+  const sin = Math.sin(rotation);
+  const cosR = r * cos;
+  const sinR = r * sin;
+  const cosA = a * cos;
+  const sinA = a * sin;
+  return [
+    { x: cx - cosA + sinR, y: cy - sinA - cosR },
+    { x: cx + cosA + sinR, y: cy + sinA - cosR },
+    { x: cx + cosA + sinA, y: cy + sinA - cosA },
+    { x: cx + cosR + sinA, y: cy + sinR - cosA },
+    { x: cx + cosR - sinA, y: cy + sinR + cosA },
+    { x: cx + cosA - sinA, y: cy + sinA + cosA },
+    { x: cx + cosA - sinR, y: cy + sinA + cosR },
+    { x: cx - cosA - sinR, y: cy - sinA + cosR },
+    { x: cx - cosA - sinA, y: cy - sinA + cosA },
+    { x: cx - cosR - sinA, y: cy - sinR + cosA },
+    { x: cx - cosR + sinA, y: cy - sinR - cosA },
+    { x: cx - cosA + sinA, y: cy - sinA - cosA },
+  ];
+}
+
+function addStarPoints(cx: number, cy: number, r: number): Vec2[] {
+  return [
+    { x: cx + STAR_COS_SIN[0]!.cos * r, y: cy + STAR_COS_SIN[0]!.sin * r },
+    { x: cx + STAR_COS_SIN[1]!.cos * r, y: cy + STAR_COS_SIN[1]!.sin * r },
+    { x: cx + STAR_COS_SIN[2]!.cos * r, y: cy + STAR_COS_SIN[2]!.sin * r },
+    { x: cx + STAR_COS_SIN[3]!.cos * r, y: cy + STAR_COS_SIN[3]!.sin * r },
+    { x: cx + STAR_COS_SIN[4]!.cos * r, y: cy + STAR_COS_SIN[4]!.sin * r },
+    { x: cx + STAR_COS_SIN[5]!.cos * r, y: cy + STAR_COS_SIN[5]!.sin * r },
+    { x: cx + STAR_COS_SIN[6]!.cos * r, y: cy + STAR_COS_SIN[6]!.sin * r },
+    { x: cx + STAR_COS_SIN[7]!.cos * r, y: cy + STAR_COS_SIN[7]!.sin * r },
+    { x: cx + STAR_COS_SIN[8]!.cos * r, y: cy + STAR_COS_SIN[8]!.sin * r },
+    { x: cx + STAR_COS_SIN[9]!.cos * r, y: cy + STAR_COS_SIN[9]!.sin * r },
+  ];
+}
+
+export interface PolygonOpts {
+  fill?: Color;
+  stroke?: Color;
+  strokeWidth?: number;
+  group?: Group;
+  /**
+   * GPU emphasis key (P5-T3) threaded onto the polygon fill AND its stroke-ring
+   * polyline so the whole filled shape dims as one unit. `undefined` → untagged
+   * (no dim). Used by boxplot/violin/ridgeline to tag a logical entity's fill.
+   */
+  emphasisKey?: number;
+}
+
+/** Stroke width used when a dashed/dotted border is requested without an explicit width. */
+const DEFAULT_DASH_STROKE_WIDTH = 1;
+
+/** `*-open` shape variants treated as their solid counterpart for border-style routing. */
+const OPEN_TO_SOLID: Partial<Record<PointShapeKind, PointShapeKind>> = {
+  "circle-open": "circle",
+  "square-open": "square",
+  "triangle-open": "triangle",
+  "diamond-open": "diamond",
+};
+
+function isOpenVariant(shape: PointShapeKind): boolean {
+  return shape.endsWith("-open");
+}
+
+// Outline vertex ring for a normalized (non-`-open`) point shape, used for
+// dashed/dotted borders. Triangle/diamond mirror the vertex layout in
+// `addTriangle`/`addDiamond` so the dash overlay aligns with the solid fill.
+function pointShapeRingPoints(
+  shape: PointShapeKind,
+  cx: number,
+  cy: number,
+  radius: number,
+): Vec2[] | undefined {
+  switch (shape) {
+    case "circle":
+      return polylineEllipseRing({ cx, cy, rx: radius, ry: radius });
+    case "square":
+      return polylineRectRing({
+        x: cx - radius,
+        y: cy - radius,
+        width: radius * 2,
+        height: radius * 2,
+      });
+    case "triangle":
+      return [
+        { x: cx, y: cy - radius },
+        { x: cx + radius * SQRT3_OVER_2, y: cy + radius * 0.5 },
+        { x: cx - radius * SQRT3_OVER_2, y: cy + radius * 0.5 },
+      ];
+    case "diamond":
+      return [
+        { x: cx, y: cy - radius },
+        { x: cx + radius, y: cy },
+        { x: cx, y: cy + radius },
+        { x: cx - radius, y: cy },
+      ];
+    case "plus":
+      return addPlusPoints(cx, cy, radius, 0);
+    case "cross":
+      return addPlusPoints(cx, cy, radius, Math.PI / 4);
+    case "star":
+      return addStarPoints(cx, cy, radius);
+    default:
+      return undefined;
+  }
+}
+
+interface ShapeEmitContext {
+  layer: Layer;
+  cx: number;
+  cy: number;
+  radius: number;
+  fill: Color;
+  stroke: Color | undefined;
+  strokeWidth: number | undefined;
+  borderStyle: PointBorderStyle;
+  group: Group | undefined;
+  /** GPU emphasis key (P5-T3) threaded onto every primitive this glyph emits. */
+  emphasisKey?: number;
+}
+
+/**
+ * Emit a single point glyph honoring `borderStyle`. For solid/open borders we
+ * fall through to existing SDF/polygon paths; for dashed/dotted we suppress
+ * the native stroke and emit a separate polyline ring with the dash pattern.
+ */
+function emitPointShape(shape: PointShapeKind, ctx: ShapeEmitContext): void {
+  const { layer, cx, cy, radius, group, emphasisKey } = ctx;
+
+  // Normalize `-open` shape variants. If the user supplied an `-open` shape
+  // with no explicit borderStyle, treat as `'open'`; otherwise borderStyle wins.
+  const normalizedShape = OPEN_TO_SOLID[shape] ?? shape;
+  const effectiveBorder: PointBorderStyle =
+    ctx.borderStyle === "solid" && isOpenVariant(shape) ? "open" : ctx.borderStyle;
+
+  const open = effectiveBorder === "open";
+  const dashed = effectiveBorder === "dashed" || effectiveBorder === "dotted";
+
+  // For "open", suppress fill and fall back to fill color for the stroke.
+  const fill: Color | undefined = open ? undefined : ctx.fill;
+  const baseStroke: Color | undefined = open ? (ctx.stroke ?? ctx.fill) : ctx.stroke;
+
+  // For dashed/dotted, the SDF/polygon stroke is suppressed (handled below
+  // by a separate polyline ring). Solid keeps the native stroke path.
+  const sdfStroke = dashed ? undefined : baseStroke;
+  const sdfStrokeWidth = dashed ? undefined : ctx.strokeWidth;
+
+  switch (normalizedShape) {
+    case "circle":
+      layer.pushCircle({
+        cx,
+        cy,
+        radius,
+        fill,
+        stroke: sdfStroke,
+        strokeWidth: sdfStrokeWidth,
+        group,
+        emphasisKey,
+      });
+      break;
+    case "square": {
+      const side = radius * 2;
+      layer.pushRect({
+        x: cx - radius,
+        y: cy - radius,
+        width: side,
+        height: side,
+        fill,
+        stroke: sdfStroke,
+        strokeWidth: sdfStrokeWidth,
+        group,
+        emphasisKey,
+      });
+      break;
+    }
+    case "triangle":
+      addTriangle(layer, cx, cy, radius, {
+        fill,
+        stroke: sdfStroke,
+        strokeWidth: sdfStrokeWidth,
+        group,
+        emphasisKey,
+      });
+      break;
+    case "diamond":
+      addDiamond(layer, cx, cy, radius, {
+        fill,
+        stroke: sdfStroke,
+        strokeWidth: sdfStrokeWidth,
+        group,
+        emphasisKey,
+      });
+      break;
+    case "plus":
+      pushFilledPolygon(layer, addPlusPoints(cx, cy, radius, 0), {
+        fill,
+        stroke: sdfStroke,
+        strokeWidth: sdfStrokeWidth,
+        group,
+        emphasisKey,
+      });
+      break;
+    case "cross":
+      pushFilledPolygon(layer, addPlusPoints(cx, cy, radius, Math.PI / 4), {
+        fill,
+        stroke: sdfStroke,
+        strokeWidth: sdfStrokeWidth,
+        group,
+        emphasisKey,
+      });
+      break;
+    case "star":
+      pushFilledPolygon(layer, addStarPoints(cx, cy, radius), {
+        fill,
+        stroke: sdfStroke,
+        strokeWidth: sdfStrokeWidth,
+        group,
+        emphasisKey,
+      });
+      break;
+  }
+
+  if (!dashed) return;
+
+  // Dashed/dotted border — emit a polyline ring approximating the shape's
+  // outline and stroke it with the requested dash pattern. Without an
+  // explicit stroke color, fall back to the fill so the outline is visible.
+  const dashStroke = baseStroke ?? ctx.fill;
+  if (!dashStroke || dashStroke.a <= 0) return;
+  const ringPoints = pointShapeRingPoints(normalizedShape, cx, cy, radius);
+  if (!ringPoints) return;
+  layer.pushPolyline({
+    points: ringPoints,
+    color: dashStroke,
+    width: ctx.strokeWidth ?? DEFAULT_DASH_STROKE_WIDTH,
+    closed: true,
+    dashPattern: dashPatternFor(effectiveBorder),
+    group,
+    emphasisKey,
+  });
+}
+
+/**
+ * Single-point swatch emission for legends and other one-off renders.
+ *
+ * Internal helper exported so the legend renderer can produce a swatch that
+ * matches the on-chart point exactly — same shape, border treatment, and
+ * overlay glyph — without re-implementing the dispatch. Composes the same
+ * primitives that `pointMark` calls per datum.
+ */
+export interface PointSwatchEmitOptions {
+  cx: number;
+  cy: number;
+  radius: number;
+  fill: Color;
+  stroke?: Color;
+  strokeWidth?: number;
+  shape?: PointShapeKind;
+  borderStyle?: PointBorderStyle;
+  overlayGlyph?: PointShapeKind | null;
+  overlayScale?: number;
+  group?: Group;
+}
+
+export function emitPointSwatch(layer: Layer, opts: PointSwatchEmitOptions): void {
+  const shape = opts.shape ?? "circle";
+  const borderStyle = opts.borderStyle ?? "solid";
+  emitPointShape(shape, {
+    layer,
+    cx: opts.cx,
+    cy: opts.cy,
+    radius: opts.radius,
+    fill: opts.fill,
+    stroke: opts.stroke,
+    strokeWidth: opts.strokeWidth,
+    borderStyle,
+    group: opts.group,
+  });
+  const overlay = opts.overlayGlyph;
+  if (!overlay) return;
+  const overlayScale = opts.overlayScale ?? DEFAULT_OVERLAY_SCALE;
+  emitPointShape(overlay, {
+    layer,
+    cx: opts.cx,
+    cy: opts.cy,
+    radius: opts.radius * overlayScale,
+    fill: opts.stroke ?? opts.fill,
+    stroke: opts.stroke,
+    strokeWidth: opts.strokeWidth,
+    borderStyle: "solid",
+    group: opts.group,
+  });
+}
+
+export function pointMark<T>(data: readonly T[], options: PointMarkOptions<T>): MarkBuilder {
+  return {
+    length: data.length,
+    addTo(layer: Layer, origin: MarkOrigin = {}) {
+      const ox = origin.x ?? 0;
+      const oy = origin.y ?? 0;
+      const group = options.group;
+
+      // Hoist per-render: turn each option into a function we can call per
+      // datum without re-checking typeof / re-resolving `??` fallbacks.
+      const xFn = options.x;
+      const yFn = options.y;
+      const radiusFn = toAccessor(options.radius, 3);
+      const fillFn = toAccessor(options.fill, BLACK);
+      const strokeFn = toAccessorOrUndefined(options.stroke);
+      const strokeWidthFn = toAccessorOrUndefined(options.strokeWidth);
+      const shapeFn = toAccessor<T, PointShapeKind>(options.shape, "circle");
+      const borderStyleFn = toAccessor<T, PointBorderStyle>(options.borderStyle, "solid");
+      const overlayGlyphFn =
+        options.overlayGlyph === undefined
+          ? undefined
+          : toAccessorOrUndefined(options.overlayGlyph);
+      const overlayScaleFn = toAccessor(options.overlayScale, DEFAULT_OVERLAY_SCALE);
+      const emphasisKeyFn = options.emphasisKey;
+
+      for (let i = 0; i < data.length; i++) {
+        const datum = data[i]!;
+        const cx = ox + xFn(datum, i);
+        const cy = oy + yFn(datum, i);
+        if (!Number.isFinite(cx) || !Number.isFinite(cy)) continue;
+        const radius = radiusFn(datum, i);
+        const fill = fillFn(datum, i);
+        const stroke = strokeFn(datum, i);
+        const strokeWidth = strokeWidthFn(datum, i);
+        const shape = shapeFn(datum, i);
+        const borderStyle = borderStyleFn(datum, i);
+        const emphasisKey = emphasisKeyFn?.(datum, i);
+
+        emitPointShape(shape, {
+          layer,
+          cx,
+          cy,
+          radius,
+          fill,
+          stroke,
+          strokeWidth,
+          borderStyle,
+          group,
+          emphasisKey,
+        });
+
+        if (overlayGlyphFn !== undefined) {
+          const overlay = overlayGlyphFn(datum, i);
+          if (overlay) {
+            const overlayScale = overlayScaleFn(datum, i);
+            // Overlay color: prefer the base stroke for contrast with fill;
+            // fall back to fill itself if no stroke was specified.
+            const overlayFill = stroke ?? fill;
+            emitPointShape(overlay, {
+              layer,
+              cx,
+              cy,
+              radius: radius * overlayScale,
+              fill: overlayFill,
+              stroke,
+              strokeWidth,
+              borderStyle: "solid",
+              group,
+              emphasisKey,
+            });
+          }
+        }
+      }
+      return layer;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// lineMark
+// ---------------------------------------------------------------------------
+
+export interface LineMarkOptions<T> {
+  x: Accessor<T, number>;
+  y: Accessor<T, number>;
+  stroke?: Color;
+  strokeWidth?: number;
+  curve?: LineCurve;
+  /** Resample density for smooth curves (`monotone-x`, `basis`). Default `16`. */
+  curveSamples?: number;
+  cap?: LineCap;
+  join?: LineJoin;
+  dashPattern?: readonly number[];
+  dashOffset?: number;
+  /**
+   * Categorical dash treatment. `"solid"` (default) leaves the stroke as a
+   * continuous line; `"dashed"` and `"dotted"` map to default dash patterns.
+   * `dashPattern` takes precedence when both are supplied.
+   */
+  dashStyle?: LineDashStyle;
+  defined?: Accessor<T, boolean>;
+  /**
+   * GPU emphasis key (P5-T3) applied to every polyline segment of this line.
+   * A whole line/series shares one key so it dims/un-dims together. `undefined`
+   * → untagged (no dim).
+   */
+  emphasisKey?: number;
+  group?: Group;
+}
+
+function collectSegments<T>(
+  data: readonly T[],
+  x: Accessor<T, number>,
+  y: Accessor<T, number>,
+  ox: number,
+  oy: number,
+  defined: Accessor<T, boolean> | undefined,
+): Vec2[][] {
+  const segments: Vec2[][] = [];
+  let current: Vec2[] = [];
+
+  for (let i = 0; i < data.length; i++) {
+    const datum = data[i]!;
+    const isDefined = defined ? defined(datum, i) : true;
+    if (!isDefined) {
+      if (current.length > 0) {
+        segments.push(current);
+        current = [];
+      }
+      continue;
+    }
+    const px = ox + x(datum, i);
+    const py = oy + y(datum, i);
+    if (!Number.isFinite(px) || !Number.isFinite(py)) {
+      if (current.length > 0) {
+        segments.push(current);
+        current = [];
+      }
+      continue;
+    }
+    current.push({ x: px, y: py });
+  }
+
+  if (current.length > 0) segments.push(current);
+  return segments;
+}
+
+export function lineMark<T>(data: readonly T[], options: LineMarkOptions<T>): MarkBuilder {
+  return {
+    length: data.length,
+    addTo(layer: Layer, origin: MarkOrigin = {}) {
+      const ox = origin.x ?? 0;
+      const oy = origin.y ?? 0;
+      const color = options.stroke ?? BLACK;
+      const width = options.strokeWidth ?? 1;
+      const curve = options.curve ?? "linear";
+      const samples = Math.max(2, options.curveSamples ?? 16);
+      const segments = collectSegments(data, options.x, options.y, ox, oy, options.defined);
+      const dashPattern = options.dashPattern ?? dashPatternFor(options.dashStyle);
+
+      for (const raw of segments) {
+        if (raw.length < 2) continue;
+        const points = curve === "linear" ? raw : resamplePoints(raw, curve, samples);
+        layer.pushPolyline({
+          points,
+          color,
+          width,
+          cap: options.cap,
+          join: options.join,
+          dashPattern,
+          dashOffset: options.dashOffset,
+          group: options.group,
+          emphasisKey: options.emphasisKey,
+        });
+      }
+      return layer;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// areaMark
+// ---------------------------------------------------------------------------
+
+export interface AreaMarkOptions<T> {
+  x: Accessor<T, number>;
+  y0: Accessor<T, number>;
+  y1: Accessor<T, number>;
+  fill?: Color;
+  stroke?: Color;
+  strokeWidth?: number;
+  defined?: Accessor<T, boolean>;
+  group?: Group;
+}
+
+interface AreaSegment {
+  top: Vec2[];
+  bottom: Vec2[];
+}
+
+function collectAreaSegments<T>(
+  data: readonly T[],
+  x: Accessor<T, number>,
+  y0: Accessor<T, number>,
+  y1: Accessor<T, number>,
+  ox: number,
+  oy: number,
+  defined: Accessor<T, boolean> | undefined,
+): AreaSegment[] {
+  const segments: AreaSegment[] = [];
+  let current: AreaSegment = { top: [], bottom: [] };
+
+  const flush = () => {
+    if (current.top.length > 0) segments.push(current);
+    current = { top: [], bottom: [] };
+  };
+
+  for (let i = 0; i < data.length; i++) {
+    const datum = data[i]!;
+    const isDefined = defined ? defined(datum, i) : true;
+    if (!isDefined) {
+      flush();
+      continue;
+    }
+    const px = ox + x(datum, i);
+    const p1 = oy + y1(datum, i);
+    const p0 = oy + y0(datum, i);
+    if (!Number.isFinite(px) || !Number.isFinite(p0) || !Number.isFinite(p1)) {
+      flush();
+      continue;
+    }
+    current.top.push({ x: px, y: p1 });
+    current.bottom.push({ x: px, y: p0 });
+  }
+
+  flush();
+  return segments;
+}
+
+export function areaMark<T>(data: readonly T[], options: AreaMarkOptions<T>): MarkBuilder {
+  return {
+    length: data.length,
+    addTo(layer: Layer, origin: MarkOrigin = {}) {
+      const ox = origin.x ?? 0;
+      const oy = origin.y ?? 0;
+      const fill = options.fill ?? BLACK;
+      const segments = collectAreaSegments(
+        data,
+        options.x,
+        options.y0,
+        options.y1,
+        ox,
+        oy,
+        options.defined,
+      );
+
+      for (const { top, bottom } of segments) {
+        if (top.length < 2) continue;
+        const topLen = top.length;
+        const bottomLen = bottom.length;
+        const points: Vec2[] = [];
+        points.length = topLen + bottomLen;
+        for (let i = 0; i < topLen; i++) {
+          points[i] = top[i]!;
+        }
+        for (let i = 0; i < bottomLen; i++) {
+          points[topLen + i] = bottom[bottomLen - 1 - i]!;
+        }
+        pushFilledPolygon(layer, points, {
+          fill,
+          stroke: options.stroke,
+          strokeWidth: options.strokeWidth,
+          group: options.group,
+        });
+      }
+      return layer;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// barMark
+// ---------------------------------------------------------------------------
+
+/**
+ * Bar border treatment — shared between `barMark`, `categoricalBarMark`,
+ * `stackedBarMark`, and `groupedBarMark`. Same routing as point borders:
+ * `"open"` suppresses fill; `"dashed"` / `"dotted"` emit a polyline ring
+ * around the rect because SDF rect strokes have no native dash support.
+ */
+export type BarBorderStyle = "solid" | "dashed" | "dotted" | "open";
+
+interface BarRectOpts {
+  fill: Color;
+  stroke: Color | undefined;
+  strokeWidth: number | undefined;
+  cornerRadius: number | undefined;
+  rotation?: number | undefined;
+  borderStyle: BarBorderStyle;
+  group: Group | undefined;
+  /** Per-instance GPU emphasis key (P5-T3). Rides onto every primitive of the bar. */
+  emphasisKey?: number | undefined;
+}
+
+function emitBarRect(
+  layer: Layer,
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+  opts: BarRectOpts,
+): void {
+  const open = opts.borderStyle === "open";
+  const dashed = opts.borderStyle === "dashed" || opts.borderStyle === "dotted";
+
+  const fill: Color | undefined = open ? undefined : opts.fill;
+  const baseStroke: Color | undefined = open ? (opts.stroke ?? opts.fill) : opts.stroke;
+  const sdfStroke = dashed ? undefined : baseStroke;
+  const sdfStrokeWidth = dashed ? undefined : opts.strokeWidth;
+
+  layer.pushRect({
+    x,
+    y,
+    width,
+    height,
+    fill,
+    stroke: sdfStroke,
+    strokeWidth: sdfStrokeWidth,
+    cornerRadius: opts.cornerRadius,
+    rotation: opts.rotation,
+    group: opts.group,
+    emphasisKey: opts.emphasisKey,
+  });
+
+  if (!dashed) return;
+  const dashStroke = baseStroke ?? opts.fill;
+  if (!dashStroke || dashStroke.a <= 0) return;
+  // Rotation isn't honored for dashed rings yet — SDF rect rotation rotates the
+  // shape locally, which doesn't map cleanly to a polyline ring built in
+  // world-space. Bars rarely combine rotation with dashed borders; document
+  // and proceed without rotation for now.
+  const ringPoints = polylineRectRing({
+    x,
+    y,
+    width,
+    height,
+    cornerRadius: opts.cornerRadius,
+  });
+  layer.pushPolyline({
+    points: ringPoints,
+    color: dashStroke,
+    width: opts.strokeWidth ?? DEFAULT_DASH_STROKE_WIDTH,
+    closed: true,
+    dashPattern: dashPatternFor(opts.borderStyle),
+    group: opts.group,
+    emphasisKey: opts.emphasisKey,
+  });
+}
+
+export interface BarMarkOptions<T> {
+  x: Accessor<T, number>;
+  y: Accessor<T, number>;
+  width: ValueOrAccessor<T, number>;
+  height: ValueOrAccessor<T, number>;
+  fill?: ValueOrAccessor<T, Color>;
+  stroke?: ValueOrAccessor<T, Color>;
+  strokeWidth?: ValueOrAccessor<T, number>;
+  cornerRadius?: ValueOrAccessor<T, number>;
+  rotation?: ValueOrAccessor<T, number>;
+  /** Per-datum border treatment. See {@link BarBorderStyle}. */
+  borderStyle?: ValueOrAccessor<T, BarBorderStyle>;
+  group?: Group;
+}
+
+export function barMark<T>(data: readonly T[], options: BarMarkOptions<T>): MarkBuilder {
+  return {
+    length: data.length,
+    addTo(layer: Layer, origin: MarkOrigin = {}) {
+      const ox = origin.x ?? 0;
+      const oy = origin.y ?? 0;
+      const group = options.group;
+
+      for (let i = 0; i < data.length; i++) {
+        const datum = data[i]!;
+        const x = ox + options.x(datum, i);
+        const y = oy + options.y(datum, i);
+        const width = resolve(options.width, datum, i);
+        const height = resolve(options.height, datum, i);
+        const fill = options.fill === undefined ? BLACK : resolve(options.fill, datum, i);
+        const stroke = options.stroke === undefined ? undefined : resolve(options.stroke, datum, i);
+        const strokeWidth =
+          options.strokeWidth === undefined ? undefined : resolve(options.strokeWidth, datum, i);
+        const cornerRadius =
+          options.cornerRadius === undefined ? undefined : resolve(options.cornerRadius, datum, i);
+        const rotation =
+          options.rotation === undefined ? undefined : resolve(options.rotation, datum, i);
+        const borderStyle: BarBorderStyle =
+          options.borderStyle === undefined ? "solid" : resolve(options.borderStyle, datum, i);
+
+        emitBarRect(layer, x, y, width, height, {
+          fill,
+          stroke,
+          strokeWidth,
+          cornerRadius,
+          rotation,
+          borderStyle,
+          group,
+        });
+      }
+      return layer;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// categoricalBarMark — single-series oriented bars driven by scales
+// ---------------------------------------------------------------------------
+
+export type BarOrientation = "y" | "x";
+
+export interface CategoricalBarMarkOptions<T, C> {
+  /**
+   * `"y"` (default) → vertical bars, value mapped to height.
+   * `"x"` → horizontal bars, value mapped to width.
+   */
+  orientation?: BarOrientation;
+  category: Accessor<T, C>;
+  value: Accessor<T, number>;
+  /** Band scale resolving categories to one of the layer's axes. */
+  categoryScale: BandScale<C>;
+  /** Continuous scale resolving values to the perpendicular axis. */
+  valueScale: ContinuousScale;
+  /** Baseline value (in domain units). Default `0`. */
+  baseline?: number;
+  fill?: ValueOrAccessor<T, Color>;
+  stroke?: ValueOrAccessor<T, Color>;
+  strokeWidth?: ValueOrAccessor<T, number>;
+  cornerRadius?: ValueOrAccessor<T, number>;
+  /** Per-datum border treatment. See {@link BarBorderStyle}. */
+  borderStyle?: ValueOrAccessor<T, BarBorderStyle>;
+  /** Per-datum GPU emphasis key (P5-T3). `undefined` → untagged (no dim). */
+  emphasisKey?: Accessor<T, number | undefined>;
+  group?: Group;
+}
+
+export function categoricalBarMark<T, C>(
+  data: readonly T[],
+  options: CategoricalBarMarkOptions<T, C>,
+): MarkBuilder {
+  const orientation = options.orientation ?? "y";
+  const baseline = options.baseline ?? 0;
+  const bw = options.categoryScale.bandwidth();
+  const baselinePos = options.valueScale(baseline);
+
+  return {
+    length: data.length,
+    addTo(layer: Layer, origin: MarkOrigin = {}) {
+      const ox = origin.x ?? 0;
+      const oy = origin.y ?? 0;
+      const group = options.group;
+      for (let i = 0; i < data.length; i++) {
+        const datum = data[i]!;
+        const cat = options.category(datum, i);
+        const v = options.value(datum, i);
+        const valuePos = options.valueScale(v);
+        const fill = options.fill === undefined ? BLACK : resolve(options.fill, datum, i);
+        const stroke = options.stroke === undefined ? undefined : resolve(options.stroke, datum, i);
+        const strokeWidth =
+          options.strokeWidth === undefined ? undefined : resolve(options.strokeWidth, datum, i);
+        const cornerRadius =
+          options.cornerRadius === undefined ? undefined : resolve(options.cornerRadius, datum, i);
+        const borderStyle: BarBorderStyle =
+          options.borderStyle === undefined ? "solid" : resolve(options.borderStyle, datum, i);
+
+        let x: number;
+        let y: number;
+        let width: number;
+        let height: number;
+        if (orientation === "y") {
+          x = options.categoryScale(cat);
+          y = Math.min(valuePos, baselinePos);
+          width = bw;
+          height = Math.abs(valuePos - baselinePos);
+        } else {
+          x = Math.min(valuePos, baselinePos);
+          y = options.categoryScale(cat);
+          width = Math.abs(valuePos - baselinePos);
+          height = bw;
+        }
+
+        emitBarRect(layer, ox + x, oy + y, width, height, {
+          fill,
+          stroke,
+          strokeWidth,
+          cornerRadius,
+          borderStyle,
+          group,
+          emphasisKey: options.emphasisKey?.(datum, i),
+        });
+      }
+      return layer;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// stackedBarMark — multi-series stacked bars driven by stack() + a value scale
+// ---------------------------------------------------------------------------
+
+export interface StackedBarMarkOptions<T, C, K extends string> {
+  orientation?: BarOrientation;
+  category: Accessor<T, C>;
+  categoryScale: BandScale<C>;
+  valueScale: ContinuousScale;
+  /** Per-segment fill — typically `colorScale(palette, keys)` (a function of `K`). */
+  color: (key: K, segment: StackSegment<T, K>) => Color;
+  offset?: StackOffset;
+  order?: StackOrder;
+  value?: (datum: T, key: K, datumIndex: number) => number;
+  cornerRadius?: number;
+  stroke?: Color;
+  strokeWidth?: number;
+  /** Border treatment shared across every segment. See {@link BarBorderStyle}. */
+  borderStyle?: BarBorderStyle;
+  /** Per-segment GPU emphasis key (P5-T3). `undefined` → untagged (no dim). */
+  emphasisKey?: (key: K, segment: StackSegment<T, K>) => number | undefined;
+  group?: Group;
+}
+
+export interface StackedMarkBuilder<T, K extends string> extends MarkBuilder {
+  /** Per-(datum, key) layout segments — useful for `valueLabelMark` over totals. */
+  readonly segments: readonly StackSegment<T, K>[];
+}
+
+export function stackedBarMark<T, C, K extends string>(
+  data: readonly T[],
+  keys: readonly K[],
+  options: StackedBarMarkOptions<T, C, K>,
+): StackedMarkBuilder<T, K> {
+  const orientation = options.orientation ?? "y";
+  const segments = stack(data, keys, {
+    value: options.value,
+    offset: options.offset,
+    order: options.order,
+  });
+  const bw = options.categoryScale.bandwidth();
+
+  return {
+    length: segments.length,
+    segments,
+    addTo(layer: Layer, origin: MarkOrigin = {}) {
+      const ox = origin.x ?? 0;
+      const oy = origin.y ?? 0;
+      for (const seg of segments) {
+        const cat = options.category(seg.datum, seg.datumIndex);
+        const basePos = options.valueScale(seg.base);
+        const topPos = options.valueScale(seg.top);
+        const fill = options.color(seg.key, seg);
+
+        let x: number;
+        let y: number;
+        let width: number;
+        let height: number;
+        if (orientation === "y") {
+          x = options.categoryScale(cat);
+          y = Math.min(basePos, topPos);
+          width = bw;
+          height = Math.abs(topPos - basePos);
+        } else {
+          x = Math.min(basePos, topPos);
+          y = options.categoryScale(cat);
+          width = Math.abs(topPos - basePos);
+          height = bw;
+        }
+
+        emitBarRect(layer, ox + x, oy + y, width, height, {
+          fill,
+          stroke: options.stroke,
+          strokeWidth: options.strokeWidth,
+          cornerRadius: options.cornerRadius,
+          borderStyle: options.borderStyle ?? "solid",
+          group: options.group,
+          emphasisKey: options.emphasisKey?.(seg.key, seg),
+        });
+      }
+      return layer;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// groupedBarMark — multi-series grouped bars driven by groupedBandScale
+// ---------------------------------------------------------------------------
+
+export interface GroupedBarMarkOptions<T, C, K extends string> {
+  orientation?: BarOrientation;
+  category: Accessor<T, C>;
+  groupedScale: GroupedBandScale<C, K>;
+  valueScale: ContinuousScale;
+  /** Per-key fill — typically `colorScale(palette, keys)`. */
+  color: (key: K) => Color;
+  /** Per-(datum, key) value resolver. Default `datum[key]`. */
+  value?: (datum: T, key: K, datumIndex: number) => number;
+  /** Domain-space baseline. Default `0`. */
+  baseline?: number;
+  cornerRadius?: number;
+  stroke?: Color;
+  strokeWidth?: number;
+  /** Border treatment shared across every bar in the grouped layout. */
+  borderStyle?: BarBorderStyle;
+  /** Per-(datum, key) GPU emphasis key (P5-T3). `undefined` → untagged. */
+  emphasisKey?: (datum: T, key: K, datumIndex: number) => number | undefined;
+  group?: Group;
+}
+
+export function groupedBarMark<T, C, K extends string>(
+  data: readonly T[],
+  options: GroupedBarMarkOptions<T, C, K>,
+): MarkBuilder {
+  const orientation = options.orientation ?? "y";
+  const baseline = options.baseline ?? 0;
+  const baselinePos = options.valueScale(baseline);
+  const innerKeys = options.groupedScale.innerKeys;
+  const bw = options.groupedScale.bandwidth();
+  const value =
+    options.value ?? ((datum: T, key: K) => (datum as Record<string, number>)[key] ?? 0);
+
+  return {
+    length: data.length * innerKeys.length,
+    addTo(layer: Layer, origin: MarkOrigin = {}) {
+      const ox = origin.x ?? 0;
+      const oy = origin.y ?? 0;
+      for (let i = 0; i < data.length; i++) {
+        const datum = data[i]!;
+        const cat = options.category(datum, i);
+        for (const key of innerKeys) {
+          const v = value(datum, key, i);
+          const valuePos = options.valueScale(v);
+          const innerPos = options.groupedScale(cat, key);
+          if (Number.isNaN(innerPos)) continue;
+          const fill = options.color(key);
+
+          let x: number;
+          let y: number;
+          let width: number;
+          let height: number;
+          if (orientation === "y") {
+            x = innerPos;
+            y = Math.min(valuePos, baselinePos);
+            width = bw;
+            height = Math.abs(valuePos - baselinePos);
+          } else {
+            x = Math.min(valuePos, baselinePos);
+            y = innerPos;
+            width = Math.abs(valuePos - baselinePos);
+            height = bw;
+          }
+
+          emitBarRect(layer, ox + x, oy + y, width, height, {
+            fill,
+            stroke: options.stroke,
+            strokeWidth: options.strokeWidth,
+            cornerRadius: options.cornerRadius,
+            borderStyle: options.borderStyle ?? "solid",
+            group: options.group,
+            emphasisKey: options.emphasisKey?.(datum, key, i),
+          });
+        }
+      }
+      return layer;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// stackedAreaMark — multi-series stacked area along a continuous x axis
+// ---------------------------------------------------------------------------
+
+export interface StackedAreaMarkOptions<T, K extends string> {
+  /** Continuous x position resolver — already in layer-space pixels. */
+  x: Accessor<T, number>;
+  /** Continuous scale that maps stack base/top values to layer-space pixels. */
+  valueScale: ContinuousScale;
+  /** Per-series fill. */
+  color: (key: K) => Color;
+  offset?: StackOffset;
+  order?: StackOrder;
+  value?: (datum: T, key: K, datumIndex: number) => number;
+  defined?: Accessor<T, boolean>;
+  stroke?: Color;
+  strokeWidth?: number;
+  group?: Group;
+}
+
+export function stackedAreaMark<T, K extends string>(
+  data: readonly T[],
+  keys: readonly K[],
+  options: StackedAreaMarkOptions<T, K>,
+): StackedMarkBuilder<T, K> {
+  const segments = stack(data, keys, {
+    value: options.value,
+    offset: options.offset,
+    order: options.order,
+  });
+
+  // Group segments by key, preserve datum order (segments are already datum-major).
+  const byKey = new Map<K, StackSegment<T, K>[]>();
+  for (const seg of segments) {
+    let arr = byKey.get(seg.key);
+    if (!arr) {
+      arr = [];
+      byKey.set(seg.key, arr);
+    }
+    arr.push(seg);
+  }
+
+  // After ordering, the keys actually used may be in different order.
+  const orderedKeys: K[] = [];
+  for (const seg of segments) {
+    if (!orderedKeys.includes(seg.key)) orderedKeys.push(seg.key);
+    if (orderedKeys.length === keys.length) break;
+  }
+
+  return {
+    length: segments.length,
+    segments,
+    addTo(layer: Layer, origin: MarkOrigin = {}) {
+      for (const key of orderedKeys) {
+        const series = byKey.get(key)!;
+        // Build a flat row array in datum order so areaMark can iterate.
+        areaMark(series, {
+          x: (s) => options.x(s.datum, s.datumIndex),
+          y0: (s) => options.valueScale(s.base),
+          y1: (s) => options.valueScale(s.top),
+          fill: options.color(key),
+          stroke: options.stroke,
+          strokeWidth: options.strokeWidth,
+          defined: options.defined ? (s) => options.defined!(s.datum, s.datumIndex) : undefined,
+          group: options.group,
+        }).addTo(layer, origin);
+      }
+      return layer;
+    },
+  };
+}