@ggts-sh/svelte 0.43.0

package/dist/scene/batch-presentation.svelte.js

@@ -0,0 +1,207 @@
+import { pathData, pointShapeGeometry, resolveGlyphMark, resolvePathMark, resolvePointMark, resolveRectMark, resolveSegmentMark, themeVar, } from "@ggts-sh/core";
+/** Panel-local box origin for a glyph anchor + box size (geom_label).
+ *  Local twin of packages/core labelBoxOrigin — keep private; no new
+ *  public core export for a Svelte-scene paint parity fix. */
+function labelBoxOrigin(x, y, width, height, anchor, padding) {
+    let left = x - width / 2;
+    if (anchor === "start")
+        left = x - padding;
+    else if (anchor === "end")
+        left = x - width + padding;
+    return { x: left, y: y - height / 2 };
+}
+/** Keyboard-focus cap: point marks become focusable tooltip targets only
+ *  up to this many marks per batch (a11y pass; beyond it, the canvas-style
+ *  data-table strategy is the documented alternative). */
+const FOCUSABLE_LIMIT = 100;
+const NO_ROW = 0xffffffff;
+const styleNumber = (value) => Math.round(value * 1_000_000) / 1_000_000;
+export function createBatchPresentation(deps) {
+    const batch = $derived(deps.batch());
+    const theme = $derived(deps.theme());
+    const focusMask = $derived(deps.focusMask());
+    const focusable = $derived(deps.focusable());
+    const pointsFocusable = $derived(focusable && batch.kind === "points" && batch.rowIndex.length <= FOCUSABLE_LIMIT);
+    const ink = $derived(themeVar("ink", theme));
+    const accent = $derived(themeVar("accent", theme));
+    const points = $derived.by(() => {
+        if (batch.kind !== "points")
+            return [];
+        return Array.from({ length: batch.rowIndex.length }, (_, j) => {
+            const style = resolvePointMark(batch, j, ink);
+            const size = styleNumber(style.size);
+            const x = batch.positions[j * 2];
+            const y = batch.positions[j * 2 + 1];
+            return {
+                index: j,
+                x,
+                y,
+                fill: style.fill,
+                size,
+                alpha: styleNumber(style.alpha),
+                shape: style.shape,
+                // Rebuild geometry with display-rounded size so path `d` matches prior SSR.
+                geometry: pointShapeGeometry(style.shape, x, y, size),
+                row: batch.rowIndex[j] === NO_ROW ? null : batch.rowIndex[j],
+            };
+        });
+    });
+    const subpaths = $derived.by(() => {
+        if (batch.kind !== "paths")
+            return [];
+        const out = [];
+        const themeColors = { ink, accent };
+        for (let s = 0; s < batch.pathOffsets.length - 1; s++) {
+            const d = pathData(batch.positions, batch.pathOffsets[s], batch.pathOffsets[s + 1], batch.curve, batch.closed === true, batch.ringStarts);
+            if (d === "")
+                continue;
+            const style = resolvePathMark(batch, s, themeColors);
+            out.push({
+                index: s,
+                d,
+                stroke: style.stroke,
+                fill: style.fill,
+                linewidth: styleNumber(style.width),
+                alpha: styleNumber(style.alpha),
+                dasharray: style.dash.length === 0 ? undefined : style.dash.join(" "),
+                linecap: style.linecap,
+                linejoin: style.linejoin,
+                fillRule: batch.fillRule,
+            });
+        }
+        return out;
+    });
+    const rects = $derived.by(() => {
+        if (batch.kind !== "rects")
+            return [];
+        const themeColors = { accent, paper: themeVar("paper", theme), ink };
+        return Array.from({ length: batch.rects.length / 4 }, (_, j) => {
+            const style = resolveRectMark(batch, j, themeColors);
+            return {
+                index: j,
+                x: batch.rects[j * 4],
+                y: batch.rects[j * 4 + 1],
+                width: batch.rects[j * 4 + 2],
+                height: batch.rects[j * 4 + 3],
+                fill: style.fill,
+                stroke: style.stroke,
+                strokeWidth: style.strokeWidth,
+                alpha: styleNumber(style.alpha),
+                dasharray: style.dash.length === 0 ? undefined : style.dash.join(" "),
+            };
+        });
+    });
+    const segments = $derived.by(() => {
+        if (batch.kind !== "segments")
+            return [];
+        return Array.from({ length: batch.segments.length / 4 }, (_, j) => {
+            const mark = resolveSegmentMark(batch, j, ink);
+            return {
+                index: j,
+                x1: batch.segments[j * 4],
+                y1: batch.segments[j * 4 + 1],
+                x2: batch.segments[j * 4 + 2],
+                y2: batch.segments[j * 4 + 3],
+                ...(batch.renderPositions !== undefined &&
+                    batch.renderPathOffsets !== undefined && {
+                    d: pathData(batch.renderPositions, batch.renderPathOffsets[j], batch.renderPathOffsets[j + 1], "linear"),
+                }),
+                stroke: mark.stroke,
+                linewidth: styleNumber(mark.width),
+                alpha: styleNumber(mark.alpha),
+                // Conditional: only set when the batch opts in (rule batches leave undefined).
+                ...(mark.linecap !== undefined && { linecap: mark.linecap }),
+                dasharray: mark.dash.length === 0 ? undefined : mark.dash.join(" "),
+            };
+        });
+    });
+    const glyphs = $derived.by(() => {
+        if (batch.kind !== "glyphs")
+            return [];
+        // Measured extents alone do not paint a box (geom_text measures for
+        // inspect hover/hit). Visual chrome is geom_label / sf_label only —
+        // parity with packages/core render-svg-marks renderGlyphs.
+        const hasBox = batch.boxWidths !== undefined &&
+            batch.boxHeights !== undefined &&
+            (batch.boxRadius !== undefined ||
+                batch.boxFill !== undefined ||
+                batch.boxFills !== undefined ||
+                batch.boxStroke !== undefined ||
+                batch.boxStrokes !== undefined);
+        const paper = themeVar("paper", theme);
+        return batch.texts.map((text, j) => {
+            const mark = resolveGlyphMark(batch, j, ink);
+            const x = batch.positions[j * 2];
+            const y = batch.positions[j * 2 + 1];
+            let box;
+            if (hasBox) {
+                const width = batch.boxWidths[j];
+                const height = batch.boxHeights[j];
+                const pad = batch.boxPadding ?? 0;
+                const origin = labelBoxOrigin(x, y, width, height, batch.anchor, pad);
+                box = {
+                    x: styleNumber(origin.x),
+                    y: styleNumber(origin.y),
+                    width: styleNumber(width),
+                    height: styleNumber(height),
+                    fill: batch.boxFills?.[j] ?? batch.boxFill ?? paper,
+                    stroke: batch.boxStrokes?.[j] ?? batch.boxStroke ?? ink,
+                    strokeWidth: styleNumber(batch.boxStrokeWidth ?? 0.5),
+                    radius: styleNumber(batch.boxRadius ?? 0),
+                };
+            }
+            return {
+                index: j,
+                x,
+                y,
+                text,
+                fill: mark.fill,
+                size: styleNumber(mark.size),
+                alpha: styleNumber(mark.alpha),
+                box,
+            };
+        });
+    });
+    const alpha = $derived(batch.alpha === 1 ? undefined : batch.alpha);
+    function presentationOrder(items) {
+        if (focusMask === null)
+            return items.map((item) => ({ item, focused: true }));
+        const presented = items.map((item) => ({
+            item,
+            focused: focusMask.isFocused(item.index),
+        }));
+        return [
+            ...presented.filter((item) => !item.focused),
+            ...presented.filter((item) => item.focused),
+        ];
+    }
+    function itemOpacity(mapped, focused) {
+        const opacity = focusMask === null || focused ? mapped : mapped * theme.interactionMuted;
+        return opacity === 1 ? undefined : opacity;
+    }
+    return {
+        get points() {
+            return points;
+        },
+        get subpaths() {
+            return subpaths;
+        },
+        get rects() {
+            return rects;
+        },
+        get segments() {
+            return segments;
+        },
+        get glyphs() {
+            return glyphs;
+        },
+        get alpha() {
+            return alpha;
+        },
+        get pointsFocusable() {
+            return pointsFocusable;
+        },
+        presentationOrder,
+        itemOpacity,
+    };
+}

package/dist/scene/geometry.d.ts

@@ -0,0 +1,2 @@
+export { type PlotRect } from "@ggts-sh/core";
+export { type PanelBounds, panelBoundsFrom, type ContinuousZoomDomains, clamp, frozenZoomDomains, normalizedRect, HOVER_RING_RADIUS, HOVER_CROSSHAIR_GAP_RADIUS, glyphHoverBox, crosshairGapForBox, glyphExtentsFromBatch, type CrosshairGapBox, CROSSHAIR_BOX_GAP_PAD, gappedCrosshairSegmentsWithObstacles, gappedCrosshairSegments, crosshairGlyphObstacles, } from "@ggts-sh/core/interaction";

package/dist/scene/geometry.js

@@ -0,0 +1,3 @@
+// Shared pure behavior used by React and Svelte.
+export {} from "@ggts-sh/core";
+export { panelBoundsFrom, clamp, frozenZoomDomains, normalizedRect, HOVER_RING_RADIUS, HOVER_CROSSHAIR_GAP_RADIUS, glyphHoverBox, crosshairGapForBox, glyphExtentsFromBatch, CROSSHAIR_BOX_GAP_PAD, gappedCrosshairSegmentsWithObstacles, gappedCrosshairSegments, crosshairGlyphObstacles, } from "@ggts-sh/core/interaction";

package/dist/scene/stratum-paint.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Canvas stratum painting and batch focus-mask projection for GGPlot mark
+ * compositing. SSR-safe to import; paintCanvasStratum touches the DOM only
+ * when called with a live canvas element.
+ */
+import type { BatchInteractionMask, GeometryBatch, RenderModel } from "@ggts-sh/core";
+/**
+ * Project full-scene interaction masks onto a stratum batch subset using
+ * scene batch identity. Builds a batch→index Map once (O(S + B)) rather than
+ * `indexOf` per batch (O(B · S)), matching host masksForBatches semantics.
+ * Empty interactionMasks → empty result (no focus styling).
+ */
+export declare function resolveBatchFocusMasks(sceneBatches: readonly GeometryBatch[], batches: readonly GeometryBatch[], interactionMasks: readonly (BatchInteractionMask | null)[]): (BatchInteractionMask | null)[];
+export type PaintCanvasStratumInput = {
+    readonly canvas: HTMLCanvasElement;
+    readonly scene: RenderModel["scene"];
+    readonly batches: readonly GeometryBatch[];
+    readonly focusMasks: readonly (BatchInteractionMask | null)[];
+};
+/**
+ * Size for DPR and draw one canvas stratum.
+ * Returns false when a 2d context is unavailable — callers must not notify
+ * the paint ledger in that case (keeps data-gg-ready false).
+ */
+export declare function paintCanvasStratum(input: PaintCanvasStratumInput): boolean;

package/dist/scene/stratum-paint.js

@@ -0,0 +1,40 @@
+/**
+ * Canvas stratum painting and batch focus-mask projection for GGPlot mark
+ * compositing. SSR-safe to import; paintCanvasStratum touches the DOM only
+ * when called with a live canvas element.
+ */
+import { cssColorResolver, drawStratum, sizeCanvasForDpr } from "@ggts-sh/core/dom";
+/**
+ * Project full-scene interaction masks onto a stratum batch subset using
+ * scene batch identity. Builds a batch→index Map once (O(S + B)) rather than
+ * `indexOf` per batch (O(B · S)), matching host masksForBatches semantics.
+ * Empty interactionMasks → empty result (no focus styling).
+ */
+export function resolveBatchFocusMasks(sceneBatches, batches, interactionMasks) {
+    if (interactionMasks.length === 0)
+        return [];
+    const indexByBatch = new Map(sceneBatches.map((batch, index) => [batch, index]));
+    return batches.map((batch) => {
+        const index = indexByBatch.get(batch);
+        return index === undefined ? null : (interactionMasks[index] ?? null);
+    });
+}
+/**
+ * Size for DPR and draw one canvas stratum.
+ * Returns false when a 2d context is unavailable — callers must not notify
+ * the paint ledger in that case (keeps data-gg-ready false).
+ */
+export function paintCanvasStratum(input) {
+    const ctx = input.canvas.getContext("2d");
+    if (ctx === null)
+        return false;
+    const dpr = window.devicePixelRatio || 1;
+    sizeCanvasForDpr(input.canvas, ctx, input.scene.width, input.scene.height, dpr);
+    drawStratum(ctx, input.scene, input.batches, cssColorResolver(input.canvas), input.focusMasks.length > 0
+        ? {
+            focusMasks: input.focusMasks,
+            mutedAlpha: input.scene.theme.interactionMuted,
+        }
+        : undefined);
+    return true;
+}

package/dist/selection/selection-state.svelte.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Point-selection controller extracted from GGPlot for S8.
+ *
+ * Owns local selection state, the construction-time `effectiveSelectedKeys`
+ * derived, and commit/clear/toggle/emit handlers. Semantic Candidate
+ * projection and presentation shaping belong to the runtime projection module.
+ *
+ * `commitPointSelection` is PRIVATE (no external caller — toggle/clear only).
+ * Public API speaks PropertyKey; PublicKey casts stay at the host boundary.
+ */
+import type { InteractionContext } from "../interaction/interaction-context.svelte.js";
+import type { InteractionSource, PlotSelection } from "../interaction/interaction.js";
+export type SelectionState = {
+    readonly effectiveSelectedKeys: readonly PropertyKey[];
+    clearPointSelection(source: InteractionSource): void;
+    togglePointKeys(keys: readonly PropertyKey[], source: InteractionSource): void;
+    emitSelection(event: PlotSelection): void;
+};
+/**
+ * Create the point-selection controller. Construction registers only the
+ * `effectiveSelectedKeys` derived over interaction and scope.
+ */
+export declare function createSelectionState(context: InteractionContext): SelectionState;

package/dist/selection/selection-state.svelte.js

@@ -0,0 +1,73 @@
+/**
+ * Point-selection controller extracted from GGPlot for S8.
+ *
+ * Owns local selection state, the construction-time `effectiveSelectedKeys`
+ * derived, and commit/clear/toggle/emit handlers. Semantic Candidate
+ * projection and presentation shaping belong to the runtime projection module.
+ *
+ * `commitPointSelection` is PRIVATE (no external caller — toggle/clear only).
+ * Public API speaks PropertyKey; PublicKey casts stay at the host boundary.
+ */
+import { createScopedStore } from "../interaction/scoped-store.svelte.js";
+import { selectionAnnouncement } from "../assembly/labels.js";
+import { buildPointSelectionEvent, nextPointSelectionKeys, sameOrderedPropertyKeys, } from "./selection.js";
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create the point-selection controller. Construction registers only the
+ * `effectiveSelectedKeys` derived over interaction and scope.
+ */
+export function createSelectionState(context) {
+    const selectedKeys = createScopedStore({
+        initial: [],
+        controller: context.interaction,
+        scope: context.resolvedInteractionScope,
+        read: (controller, scope) => controller.selected(scope),
+        write: (controller, next, scope, source) => {
+            const transition = controller.setSelection(next, { scope, source });
+            if (transition === null)
+                return null;
+            return {
+                value: transition.snapshot.selections.find((selection) => selection.scope === scope.keys)
+                    ?.keys ?? [],
+            };
+        },
+        clearShared: (controller, scope, source) => controller.clearSelection({ scope, source }) !== null,
+        same: sameOrderedPropertyKeys,
+    });
+    /** Private — only clear/toggle call this; no external caller (P2-7). */
+    function commitPointSelection(keys, source) {
+        // Dedup for local storage; controller canonicalizes independently.
+        const committed = selectedKeys.set([...new Set(keys)], source);
+        if (committed === null)
+            return;
+        emitSelection(buildPointSelectionEvent(committed.value, source));
+    }
+    function clearPointSelection(source) {
+        if (selectedKeys.value.length === 0)
+            return;
+        commitPointSelection([], source);
+    }
+    function emitSelection(event) {
+        const message = selectionAnnouncement(event);
+        if (message !== null)
+            context.announce(message);
+        context.onselect()?.(event);
+        context.oninteraction()?.(event);
+    }
+    function togglePointKeys(keys, source) {
+        if (keys.length === 0)
+            return;
+        const next = nextPointSelectionKeys(selectedKeys.value, keys, context.selectConfig()?.multiple ?? false);
+        commitPointSelection(next, source);
+    }
+    return {
+        get effectiveSelectedKeys() {
+            return selectedKeys.value;
+        },
+        clearPointSelection,
+        togglePointKeys,
+        emitSelection,
+    };
+}

package/dist/selection/selection.d.ts

@@ -0,0 +1 @@
+export { type PresentationChrome, type PresentationAnchor, EMPHASIS_RING_DENSITY_LIMIT, presentationChromeForKind, hoverChromeForKind, applyEmphasisRingDensityGate, sameOrderedPropertyKeys, buildPointSelectionEvent, uniqueKeysFromRowIndexes, nextPointSelectionKeys, iterateCandidates, collectCandidates, anchorsFromCandidateKeys, type PresentationInspectionFocus, presentationFocusFromInspection, mergePresentationFocusKeys, } from "@ggts-sh/core/interaction";

package/dist/selection/selection.js

@@ -0,0 +1,2 @@
+// Shared pure behavior used by React and Svelte.
+export { EMPHASIS_RING_DENSITY_LIMIT, presentationChromeForKind, hoverChromeForKind, applyEmphasisRingDensityGate, sameOrderedPropertyKeys, buildPointSelectionEvent, uniqueKeysFromRowIndexes, nextPointSelectionKeys, iterateCandidates, collectCandidates, anchorsFromCandidateKeys, presentationFocusFromInspection, mergePresentationFocusKeys, } from "@ggts-sh/core/interaction";

package/dist/surface/CaptureSurface.svelte

@@ -0,0 +1,109 @@
+<script lang="ts">
+  /**
+   * Pointer capture layer for GGPlot interaction (decision 0006).
+   * Host owns handlers, inspection/tool state, and focus restoration.
+   * Capture is a single absolutely positioned root under `.gg-plot-root`.
+   */
+  import {
+    isAreaTool,
+    type InteractionTool,
+  } from "../interaction/interaction.js";
+
+  let {
+    element = $bindable(null as HTMLDivElement | null),
+    plotId,
+    activeTool,
+    ariaLabel,
+    ariaControls,
+    onFocus,
+    onBlur,
+    onPointerMove,
+    onPointerLeave,
+    onPointerDown,
+    onPointerUp,
+    onPointerCancel,
+    onLostPointerCapture,
+    onClick,
+    onKeyDown,
+    onDblClick,
+  }: {
+    element?: HTMLDivElement | null;
+    plotId: string;
+    activeTool: InteractionTool;
+    ariaLabel: string;
+    ariaControls?: string | undefined;
+    onFocus: () => void;
+    onBlur: (event: FocusEvent) => void;
+    onPointerMove: (event: PointerEvent) => void;
+    onPointerLeave: () => void;
+    onPointerDown: (event: PointerEvent) => void;
+    onPointerUp: (event: PointerEvent) => void;
+    onPointerCancel: () => void;
+    onLostPointerCapture: () => void;
+    onClick: (event: MouseEvent) => void;
+    onKeyDown: (event: KeyboardEvent) => void;
+    onDblClick: () => void;
+  } = $props();
+</script>
+
+<!-- The capture layer is a pointer-only surface; the accessible
+     interaction paths are focusable marks and the data table. -->
+<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+<div
+  bind:this={element}
+  class="gg-capture"
+  class:gg-area-tool={isAreaTool(activeTool)}
+  role="group"
+  tabindex="0"
+  aria-label={ariaLabel}
+  aria-describedby={`${plotId}-description ${plotId}-active`}
+  aria-controls={ariaControls}
+  onfocus={onFocus}
+  onblur={onBlur}
+  onpointermove={onPointerMove}
+  onpointerleave={onPointerLeave}
+  onpointerdown={onPointerDown}
+  onpointerup={onPointerUp}
+  onpointercancel={onPointerCancel}
+  onlostpointercapture={onLostPointerCapture}
+  onclick={onClick}
+  onkeydown={onKeyDown}
+  ondblclick={onDblClick}
+></div>
+
+<style>
+  .gg-capture {
+    position: absolute;
+    inset: 0;
+    pointer-events: auto;
+    touch-action: pan-y pinch-zoom;
+    background: transparent;
+  }
+
+  .gg-capture.gg-area-tool {
+    touch-action: none;
+    cursor: crosshair;
+  }
+
+  .gg-capture:focus-visible {
+    outline: 2px solid var(--gg-focusRing, var(--gg-theme-focusRing, Highlight));
+    outline-offset: 2px;
+  }
+
+  /* Capture has no transitions; mirror PlotStatusChrome reduced-motion
+     policy for consumer-supplied overrides on this node. */
+  @media (prefers-reduced-motion: reduce) {
+    .gg-capture {
+      scroll-behavior: auto;
+      transition: none !important;
+      animation: none !important;
+    }
+  }
+
+  @media (forced-colors: active) {
+    .gg-capture:focus-visible {
+      outline-color: Highlight;
+    }
+  }
+</style>

package/dist/surface/CaptureSurface.svelte.d.ts

@@ -0,0 +1,27 @@
+/**
+   * Pointer capture layer for GGPlot interaction (decision 0006).
+   * Host owns handlers, inspection/tool state, and focus restoration.
+   * Capture is a single absolutely positioned root under `.gg-plot-root`.
+   */
+import { type InteractionTool } from "../interaction/interaction.js";
+type $$ComponentProps = {
+    element?: HTMLDivElement | null;
+    plotId: string;
+    activeTool: InteractionTool;
+    ariaLabel: string;
+    ariaControls?: string | undefined;
+    onFocus: () => void;
+    onBlur: (event: FocusEvent) => void;
+    onPointerMove: (event: PointerEvent) => void;
+    onPointerLeave: () => void;
+    onPointerDown: (event: PointerEvent) => void;
+    onPointerUp: (event: PointerEvent) => void;
+    onPointerCancel: () => void;
+    onLostPointerCapture: () => void;
+    onClick: (event: MouseEvent) => void;
+    onKeyDown: (event: KeyboardEvent) => void;
+    onDblClick: () => void;
+};
+declare const CaptureSurface: import("svelte").Component<$$ComponentProps, {}, "element">;
+type CaptureSurface = ReturnType<typeof CaptureSurface>;
+export default CaptureSurface;

package/dist/surface/area-brush.d.ts

@@ -0,0 +1,48 @@
+import { type PanelBounds, type PlotRect } from "../scene/geometry.js";
+/** Live brush corners; may be denormalized while dragging (x0>x1 or y0>y1). */
+export type BrushCorners = {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+};
+export type PlotPoint = Readonly<{
+    x: number;
+    y: number;
+}>;
+/** Degenerate brush at a single point (pointer-down / first keyboard corner). */
+export declare function brushAtPoint(point: PlotPoint): BrushCorners;
+/** Update the free corner of a brush (pointer move / second-corner down). */
+export declare function brushWithEnd(corners: BrushCorners, point: PlotPoint): BrushCorners;
+/**
+ * Pointer-down begin-area corners.
+ * Extend free corner only when reducer is awaiting second AND draft exists;
+ * otherwise start a degenerate brush at `point`. Both conditions are required
+ * so a surviving draft without first-corner state restarts fresh (not extend).
+ */
+export declare function initialBrushRect(input: {
+    readonly areaAwaitingSecond: boolean;
+    readonly existing: BrushCorners | null;
+    readonly point: PlotPoint;
+}): BrushCorners;
+/**
+ * Keyboard arrow nudge of the free corner, clamped to panel bounds.
+ * Does not normalize; callers keep denormalized corners until commit.
+ */
+export declare function nudgeBrushEnd(corners: BrushCorners, dx: number, dy: number, panel: PanelBounds): BrushCorners;
+/**
+ * Pointer brush-end evaluation.
+ * Too-small: BOTH spans &lt; min (see isBrushTooSmall); returns normalized corners
+ * for the retained draft (matches existing GGPlot behavior).
+ * Otherwise returns a normalized commit rect.
+ */
+export type PointerBrushEnd = {
+    readonly kind: "too-small";
+    readonly corners: PlotRect;
+} | {
+    readonly kind: "commit";
+    readonly rect: PlotRect;
+};
+export declare function evaluatePointerBrushEnd(corners: BrushCorners, endPoint: PlotPoint): PointerBrushEnd;
+/** Panel center for keyboard first-corner placement when no inspection anchor. */
+export declare function panelCenterAnchor(panel: PanelBounds | undefined): PlotPoint;

package/dist/surface/area-brush.js

@@ -0,0 +1,44 @@
+import { clamp, normalizedRect } from "../scene/geometry.js";
+import { isBrushTooSmall } from "../interval/interval.js";
+/** Degenerate brush at a single point (pointer-down / first keyboard corner). */
+export function brushAtPoint(point) {
+    return { x0: point.x, y0: point.y, x1: point.x, y1: point.y };
+}
+/** Update the free corner of a brush (pointer move / second-corner down). */
+export function brushWithEnd(corners, point) {
+    return { ...corners, x1: point.x, y1: point.y };
+}
+/**
+ * Pointer-down begin-area corners.
+ * Extend free corner only when reducer is awaiting second AND draft exists;
+ * otherwise start a degenerate brush at `point`. Both conditions are required
+ * so a surviving draft without first-corner state restarts fresh (not extend).
+ */
+export function initialBrushRect(input) {
+    return input.areaAwaitingSecond && input.existing !== null
+        ? brushWithEnd(input.existing, input.point)
+        : brushAtPoint(input.point);
+}
+/**
+ * Keyboard arrow nudge of the free corner, clamped to panel bounds.
+ * Does not normalize; callers keep denormalized corners until commit.
+ */
+export function nudgeBrushEnd(corners, dx, dy, panel) {
+    return {
+        ...corners,
+        x1: clamp(corners.x1 + dx, panel.x, panel.x + panel.width),
+        y1: clamp(corners.y1 + dy, panel.y, panel.y + panel.height),
+    };
+}
+export function evaluatePointerBrushEnd(corners, endPoint) {
+    const rect = normalizedRect(brushWithEnd(corners, endPoint));
+    if (isBrushTooSmall(rect))
+        return { kind: "too-small", corners: rect };
+    return { kind: "commit", rect };
+}
+/** Panel center for keyboard first-corner placement when no inspection anchor. */
+export function panelCenterAnchor(panel) {
+    if (panel === undefined)
+        return { x: 0, y: 0 };
+    return { x: panel.x + panel.width / 2, y: panel.y + panel.height / 2 };
+}

package/dist/surface/brush-finish.d.ts

@@ -0,0 +1,49 @@
+import type { InteractionTool } from "../interaction/interaction.js";
+import { type BrushCorners, type PlotPoint, type PointerBrushEnd } from "./area-brush.js";
+import type { PlotRect } from "../scene/geometry.js";
+export type FinishBrushAction = {
+    readonly type: "keep-second-corner";
+    readonly corners: PlotRect;
+} | {
+    readonly type: "select-end";
+    readonly rect: PlotRect;
+} | {
+    readonly type: "zoom-end";
+    readonly rect: PlotRect;
+} | {
+    readonly type: "end-area";
+};
+/**
+ * Pure routing after brush-end evaluation for pointer finish-brush and
+ * keyboard complete-area.
+ *
+ * Takes the full ended discriminant so actions carry rect/corners payloads —
+ * host must not re-narrow `ended.kind` for emit/apply.
+ *
+ * Priority:
+ *   1. keep-second-corner — too-small (wins for any tool); carries corners
+ *   2. select-end — commit + select-area; carries rect
+ *   3. zoom-end — commit + zoom-area; carries rect
+ *   4. end-area — commit + any other tool (clear draft + cancel-area, no emit)
+ *
+ * Host on keep-second-corner: brushRect = action.corners, announce, no cancel-area.
+ * Host on select-end/zoom-end/end-area: brushRect=null, cancel-area; emit/apply
+ * using action.rect when present.
+ *
+ * Keyboard complete-area always supplies `kind: "commit"` (no free-corner
+ * too-small evaluation); pointer uses `resolvePointerFinishBrushAction`.
+ */
+export declare function resolveFinishBrushAction(input: {
+    readonly ended: PointerBrushEnd;
+    readonly activeTool: InteractionTool;
+}): FinishBrushAction;
+/**
+ * Compose free-corner evaluation + finish routing for pointer finish-brush.
+ * Host supplies draft corners and the up event plot point; pure owns too-small
+ * vs commit and select/zoom/end payloads.
+ */
+export declare function resolvePointerFinishBrushAction(input: {
+    readonly brushCorners: BrushCorners;
+    readonly endPoint: PlotPoint;
+    readonly activeTool: InteractionTool;
+}): FinishBrushAction;