@trackunit/react-map 0.0.4-alpha-9d327375fc1.0

package/src/layers/useShapes/useShapeDecorations.d.ts

@@ -0,0 +1,56 @@
+import { type Entity, type MapInteractionState, type MapLayer, type ShapeEntity } from "@trackunit/react-map-adapter-shared";
+import { type RefObject } from "react";
+import type { MapApi } from "../../core/types";
+import type { LayerHandle, ShapeStyle } from "../types";
+type UseShapeDecorationsConfig = Readonly<{
+    onDecorationsChange: (layers: ReadonlyArray<MapLayer>) => void;
+    onStyleOverridesChange: (overrides: ReadonlyMap<string, ReadonlyMap<string, ShapeStyle>>) => void;
+    api: MapApi | undefined;
+    handles: ReadonlyArray<LayerHandle>;
+    renderedSourceIds: RefObject<Set<string>>;
+    hasSourceReadiness: boolean;
+    readyRevision: number;
+    interaction: MapInteractionState;
+    select?: (entity: Entity | null) => void;
+    hover?: (entity: Entity | null) => void;
+}>;
+/**
+ * Interaction data for a single placed decoration. Layers matches portal
+ * descriptors to entries via source ID and wraps interactive ones with
+ * `<InteractiveDecoration>`.
+ */
+export type InteractionEntry = Readonly<{
+    entity: ShapeEntity;
+    onClick?: (entity: ShapeEntity) => void;
+    onHover?: (entity: ShapeEntity | null) => void;
+}>;
+/**
+ * External store for the interaction map, consumed by Layers via
+ * `useSyncExternalStore` to avoid reading a ref during render.
+ */
+export type InteractionMapStore = Readonly<{
+    subscribe: (listener: () => void) => () => void;
+    getSnapshot: () => ReadonlyMap<string, InteractionEntry>;
+}>;
+/**
+ * Unified decoration hook — replaces both the old `useShapeDecorations` and
+ * `useEdgeLabels` with a single pass per feature.
+ *
+ * Processing per feature:
+ * 1. Collect decorations from `handle.getDecorations`
+ * 2. Partition: static anchors vs viewport-aware (`vertex-auto`, `edge-auto`)
+ * 3. Resolve static anchors, compute edge properties for `edge-*` anchors
+ * 4. `vertex-auto`: `findBestVisibleVertex`
+ * 5. `edge-auto`: build `ShapeLabelResolutionContext`, invoke optional
+ *    `resolveLabel`, then `computeEdgeAutoPlacement` → placed / hidden
+ * 6. Create `kind:"anchor"` marker sources for all placed decorations
+ * 7. Build interaction map for Layers to wrap interactive portals
+ *
+ * Has no dependency on `api.annotations` — consumers that want chrome-bar
+ * fallback opt in explicitly via `useMapAnnotation`.
+ *
+ * @returns Interaction map keyed by source ID.
+ * @internal
+ */
+export declare const useShapeDecorations: ({ onDecorationsChange, onStyleOverridesChange, api, handles, renderedSourceIds, hasSourceReadiness, readyRevision, interaction, select, hover, }: UseShapeDecorationsConfig) => InteractionMapStore;
+export {};

package/src/layers/useShapes/useShapeLabelHelpers.d.ts

@@ -0,0 +1,29 @@
+import { edgeLabel } from "./decorationFactories";
+import { createShapeLabelPolicy } from "./shapeLabelPolicy";
+export type ShapeLabelHelpers = Readonly<{
+    edgeLabel: typeof edgeLabel;
+    createShapeLabelPolicy: typeof createShapeLabelPolicy;
+}>;
+/**
+ * Build-your-own hook: stable references to shape edge-label primitives.
+ *
+ * Returns `edgeLabel` and `createShapeLabelPolicy` for consumers building
+ * custom shape layers that need edge-label decorations and the annotation-opt-in
+ * coupling described in ADR-0017, without reimplementing the placement logic.
+ *
+ * Named `useShapeLabelHelpers` to distinguish it from the existing
+ * `useShapeDecorations` internal hook.
+ *
+ * @example
+ * ```tsx
+ * const { edgeLabel, createShapeLabelPolicy } = useShapeLabelHelpers();
+ * const policy = useMemo(() => createShapeLabelPolicy({
+ *   annotateWhen: (_f, ctx) => ctx.isViewportInsideShape,
+ *   resolve: (_f, ctx) => ctx.isSelected ? "force" : "auto",
+ * }), [createShapeLabelPolicy]);
+ *
+ * // Inside getDecorations:
+ * getDecorations: (feature) => [edgeLabel(feature.properties?.name)],
+ * ```
+ */
+export declare const useShapeLabelHelpers: () => ShapeLabelHelpers;

package/src/layers/useShapes/useShapes.d.ts

@@ -0,0 +1,50 @@
+import { type GeoJsonFeature, type GeoJsonFeatureCollection } from "@trackunit/geo-json-utils";
+import type { ControlConfig } from "../../controls/types";
+import type { FitParticipation, ShapeInteractiveMode, ShapeLayerHandle, ShapeStyle } from "../types";
+import type { ShapeDecoration } from "./shapeDecorations";
+import type { ShapeLabelResolutionContext } from "./shapeLabelResolution";
+export type UseShapesOptions = Readonly<{
+    /** Unique ID for this layer */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** GeoJSON FeatureCollection containing polygon, multipolygon, and/or line features */
+    features: GeoJsonFeatureCollection;
+    /** Resolves the style for each shape. Called without context for the static pre-pass. */
+    resolveStyle: (feature: GeoJsonFeature, ctx?: ShapeLabelResolutionContext) => ShapeStyle;
+    /** Which parts of the shape respond to interaction. Default: `"stroke"` */
+    interactive?: ShapeInteractiveMode;
+    /** Optional controls to contribute to the map UI */
+    controls?: ReadonlyArray<ControlConfig>;
+    /**
+     * Produce custom decorations for each feature. Called per-feature during the
+     * decoration rendering pass. These are merged with auto-generated decorations
+     * (e.g. multi-geometry "+" badges) unless `skipAutoDecorations` is true.
+     */
+    getDecorations?: (feature: GeoJsonFeature) => ReadonlyArray<ShapeDecoration | undefined | null>;
+    /** When true, suppress all auto-generated decorations (e.g. multi-geometry "+" badges). Default: false */
+    skipAutoDecorations?: boolean;
+    /** Whether the layer is currently loading its initial data. Omit for static (non-loading) layers. */
+    loading?: boolean;
+    /** Controls whether this layer's bounds are included in fit-to-content operations. Default: `"all"` */
+    fitParticipation?: FitParticipation;
+}>;
+export type UseShapesReturn = ShapeLayerHandle;
+/**
+ * `useShapes` -- creates a shape layer handle from a GeoJSON FeatureCollection.
+ *
+ * Input is pure GeoJSON. The hook does not transform geometry -- it computes
+ * bounds and wraps the data in a layer handle.
+ *
+ * @example
+ * ```tsx
+ * const zones = useShapes({
+ *   id: "zones",
+ *   name: "Zones",
+ *   features: zoneFeatureCollection,
+ *   resolveStyle: () => ({ fill: "rgba(0,0,255,0.1)", stroke: "blue", strokeWidth: 2 }),
+ *   interactive: "stroke",
+ * });
+ * ```
+ */
+export declare const useShapes: (options: UseShapesOptions) => UseShapesReturn;

package/src/markers/MapMarker.d.ts

@@ -0,0 +1,115 @@
+import { type CommonProps, type Refable, type Styleable } from "@trackunit/react-components";
+import { type HTMLAttributes, type ReactElement } from "react";
+import type { MapTheme } from "../core/types";
+import type { MarkerDomSize, MarkerState, StickPositioning } from "./model/markerDomTypes";
+import { type MarkerColorConfig } from "./shared/markerColors";
+type MapMarkerDivHandlers = Pick<HTMLAttributes<HTMLDivElement>, "onClick" | "onKeyDown" | "onMouseEnter" | "onMouseLeave" | "onFocus" | "onBlur">;
+type MapMarkerBaseProps = CommonProps & Styleable & Refable<HTMLDivElement> & MapMarkerDivHandlers & {
+    /**
+     * Five-tier density ladder for the **default** (`state="default"`) **circle** only: diameter,
+     * optional icon slot, center dot, and in-circle direction arrow (`MARKER_SIZE_MAP`).
+     *
+     * In **pill** states (`hovered`, `expanded`, `selected`), disc, icon slot, label text size,
+     * pill-direction arrow, and pill padding are fixed to the **`md`** tier (`MARKER_PILL_CONTENT_LAYOUT_SIZE`)
+     * so the pill does not scale with this prop. Indicator and **stick** modes both use that split
+     * (collapsed circle vs expanded pill at the tip). **Stick anchor pin** (geo end) ignores `size`:
+     * fixed **`xs`** when the pin is visible, **`sm`** when `selected` (`upgradeMarkerDomSize` from that
+     * base). Same `cvaMarkerIndicator` + `MarkerDiscContent` stack as the map disc. The tip resting circle
+     * and pill still follow `size` + resolvers. The tip pill stays fixed **`md`**.
+     */
+    size: MarkerDomSize;
+    /** Indicator fill (CSS color). */
+    color: string;
+    state?: MarkerState;
+    labelVisible?: boolean;
+    /** Heading in degrees; renders GpsArrow (plan §5). */
+    direction?: number;
+    theme: MapTheme;
+    colorConfig?: MarkerColorConfig;
+    icon?: ReactElement | null;
+    /** When set, drives `aria-expanded` for paired panels (plan §13). */
+    panelOpen?: boolean;
+    /**
+     * When provided, the marker renders as a **stick**: an attachment arm from the
+     * geographic anchor to the indicator/pill. When omitted, the marker renders as
+     * a regular indicator at the anchor (ADR-0010).
+     */
+    stickPositioning?: StickPositioning;
+};
+export type MapMarkerProps = (MapMarkerBaseProps & {
+    label: string;
+    "aria-label"?: string;
+}) | (MapMarkerBaseProps & {
+    label?: never;
+    "aria-label": string;
+});
+export declare const MapMarker: import("react").ForwardRefExoticComponent<(Omit<CommonProps & Styleable & Refable<HTMLDivElement> & MapMarkerDivHandlers & {
+    /**
+     * Five-tier density ladder for the **default** (`state="default"`) **circle** only: diameter,
+     * optional icon slot, center dot, and in-circle direction arrow (`MARKER_SIZE_MAP`).
+     *
+     * In **pill** states (`hovered`, `expanded`, `selected`), disc, icon slot, label text size,
+     * pill-direction arrow, and pill padding are fixed to the **`md`** tier (`MARKER_PILL_CONTENT_LAYOUT_SIZE`)
+     * so the pill does not scale with this prop. Indicator and **stick** modes both use that split
+     * (collapsed circle vs expanded pill at the tip). **Stick anchor pin** (geo end) ignores `size`:
+     * fixed **`xs`** when the pin is visible, **`sm`** when `selected` (`upgradeMarkerDomSize` from that
+     * base). Same `cvaMarkerIndicator` + `MarkerDiscContent` stack as the map disc. The tip resting circle
+     * and pill still follow `size` + resolvers. The tip pill stays fixed **`md`**.
+     */
+    size: MarkerDomSize;
+    /** Indicator fill (CSS color). */
+    color: string;
+    state?: MarkerState;
+    labelVisible?: boolean;
+    /** Heading in degrees; renders GpsArrow (plan §5). */
+    direction?: number;
+    theme: MapTheme;
+    colorConfig?: MarkerColorConfig;
+    icon?: ReactElement | null;
+    /** When set, drives `aria-expanded` for paired panels (plan §13). */
+    panelOpen?: boolean;
+    /**
+     * When provided, the marker renders as a **stick**: an attachment arm from the
+     * geographic anchor to the indicator/pill. When omitted, the marker renders as
+     * a regular indicator at the anchor (ADR-0010).
+     */
+    stickPositioning?: StickPositioning;
+} & {
+    label: string;
+    "aria-label"?: string;
+}, "ref"> | Omit<CommonProps & Styleable & Refable<HTMLDivElement> & MapMarkerDivHandlers & {
+    /**
+     * Five-tier density ladder for the **default** (`state="default"`) **circle** only: diameter,
+     * optional icon slot, center dot, and in-circle direction arrow (`MARKER_SIZE_MAP`).
+     *
+     * In **pill** states (`hovered`, `expanded`, `selected`), disc, icon slot, label text size,
+     * pill-direction arrow, and pill padding are fixed to the **`md`** tier (`MARKER_PILL_CONTENT_LAYOUT_SIZE`)
+     * so the pill does not scale with this prop. Indicator and **stick** modes both use that split
+     * (collapsed circle vs expanded pill at the tip). **Stick anchor pin** (geo end) ignores `size`:
+     * fixed **`xs`** when the pin is visible, **`sm`** when `selected` (`upgradeMarkerDomSize` from that
+     * base). Same `cvaMarkerIndicator` + `MarkerDiscContent` stack as the map disc. The tip resting circle
+     * and pill still follow `size` + resolvers. The tip pill stays fixed **`md`**.
+     */
+    size: MarkerDomSize;
+    /** Indicator fill (CSS color). */
+    color: string;
+    state?: MarkerState;
+    labelVisible?: boolean;
+    /** Heading in degrees; renders GpsArrow (plan §5). */
+    direction?: number;
+    theme: MapTheme;
+    colorConfig?: MarkerColorConfig;
+    icon?: ReactElement | null;
+    /** When set, drives `aria-expanded` for paired panels (plan §13). */
+    panelOpen?: boolean;
+    /**
+     * When provided, the marker renders as a **stick**: an attachment arm from the
+     * geographic anchor to the indicator/pill. When omitted, the marker renders as
+     * a regular indicator at the anchor (ADR-0010).
+     */
+    stickPositioning?: StickPositioning;
+} & {
+    label?: never;
+    "aria-label": string;
+}, "ref">) & import("react").RefAttributes<HTMLDivElement>>;
+export {};

package/src/markers/MapMarkerIcon.d.ts

@@ -0,0 +1,21 @@
+import { Icon } from "@trackunit/react-components";
+import { type ComponentProps, type ReactElement } from "react";
+import type { MarkerDomSize } from "./model/markerDomTypes";
+type MapMarkerIconProps = {
+    name: ComponentProps<typeof Icon>["name"];
+    size: MarkerDomSize;
+    /** Rendered as the native HTML title attribute. */
+    title?: string;
+};
+/**
+ * Renders a correctly-scaled icon for use in the `MapMarker` `icon` prop.
+ *
+ * Internally always renders a `size="small"` (16×16 micro) icon, then applies a
+ * CSS scale transform so the visual size matches the icon slot from
+ * `MARKER_SIZE_MAP[size].icon`. Returns `null` for `xs` (no icon slot).
+ *
+ * @example
+ * <MapMarker size="md" icon={<MapMarkerIcon name="Truck" size="md" />} />
+ */
+export declare function MapMarkerIcon({ name, size, title }: MapMarkerIconProps): ReactElement | null;
+export {};

package/src/markers/animation/applyStickFrame.d.ts

@@ -0,0 +1,15 @@
+import { type StickFrameGeometry } from "./stickFrame";
+export type StickFrameRefs = Readonly<{
+    surface: HTMLElement | null;
+    line: SVGLineElement | null;
+    /** Anchor pin: HTML wrapper (indicator disc stack), not an SVG circle. */
+    dot: HTMLDivElement | null;
+}>;
+/**
+ * Single imperative DOM updater for the stick animation. Called from the rAF
+ * loop with the current spring progress and a layout snapshot. Keeps all
+ * mutation in one place so `MapMarkerStickSurface` can stay declarative.
+ *
+ * No-ops if a ref is not attached yet (initial render or after unmount).
+ */
+export declare const applyStickFrame: (refs: StickFrameRefs, geometry: StickFrameGeometry, progress: number) => void;

package/src/markers/animation/spring.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Pure semi-implicit Euler spring stepper used as the single easing
+ * source-of-truth for marker motion (stick endpoint + circle↔pill morph).
+ *
+ * The spring drives a scalar value (typically a `0..1` progress) toward a
+ * target. Each `step` call advances the simulation by `dtMs` milliseconds and
+ * returns the next state — no React, no DOM, no time source. Callers own time
+ * and apply the result however they like (rAF loop, fake timers in tests).
+ *
+ * Defaults are tuned for a snappy, decelerating attack: fast initial movement
+ * with a slight overshoot, settling in ~180–220 ms. Pair with an ease-out
+ * curve on CSS-driven companions (see `MARKER_MORPH_EASING`) so the morph
+ * reads as one decelerating motion across stick + pill rather than the
+ * mushy symmetric ease-in-out it replaced.
+ */
+export type SpringConfig = Readonly<{
+    /** Spring constant (higher = snappier). */
+    stiffness: number;
+    /** Damping coefficient (higher = less overshoot). */
+    damping: number;
+    /** Effective mass (higher = more inertia). */
+    mass: number;
+    /** Velocity below which the spring is considered at rest. */
+    restVelocity: number;
+    /** Distance to target below which the spring is considered at rest. */
+    restDelta: number;
+}>;
+export type SpringState = Readonly<{
+    value: number;
+    velocity: number;
+}>;
+export declare const MARKER_SPRING_CONFIG: SpringConfig;
+export declare const createSpringState: (initialValue: number) => SpringState;
+export declare const isSpringAtRest: (state: SpringState, target: number, config: SpringConfig) => boolean;
+/**
+ * Advances the spring by `dtMs`. Long frames are clamped and split into
+ * sub-steps to keep the integrator stable when the tab was throttled.
+ */
+export declare const stepSpring: (state: SpringState, target: number, dtMs: number, config: SpringConfig) => SpringState;
+/**
+ * Estimated settle time, in milliseconds, used to derive an equivalent CSS
+ * transition duration for properties that cannot be ref-driven (e.g. label
+ * grid track). Computed by simulating the spring from 0 to 1.
+ */
+export declare const estimateSpringSettleMs: (config: SpringConfig) => number;

package/src/markers/animation/stickFrame.d.ts

@@ -0,0 +1,82 @@
+import type { PillCSSPlacement, TipPoint } from "../geometry/stickPositioning";
+/**
+ * Pure geometry snapshot consumed by the per-frame interpolators. Any time
+ * the underlying layout changes (size tier, stick angle, label content), the
+ * caller computes a fresh `StickFrameGeometry` and the next animation frame
+ * naturally reflects it.
+ */
+export type StickFrameGeometry = Readonly<{
+    /** Tip position in anchor-relative coordinates (anchor = origin). */
+    tip: TipPoint;
+    /** CSS placement for the surface's expanded (pill-at-tip) state. */
+    pillCSS: PillCSSPlacement;
+    /**
+     * Half-extents of the SVG that draws the line/dot. The SVG sits centered on
+     * the anchor; its internal origin is `(svgHalfExtentX, svgHalfExtentY)`,
+     * which is also the anchor in the SVG's own coordinate space.
+     */
+    svgHalfExtentX: number;
+    svgHalfExtentY: number;
+    /** Visible circle diameter in collapsed/circle form. */
+    circleDiameterPx: number;
+    /** Outer pill height — also the diameter of the cap circle. */
+    pillHeightPx: number;
+    /** Stick anchor dot radius in pixels. */
+    dotRadiusPx: number;
+}>;
+export type SurfacePlacement = Readonly<{
+    /** Constant pixel `left` for the surface (top-left of the pill envelope at t=1). */
+    leftPx: number;
+    /** Constant pixel `top` for the surface (top-left of the pill envelope at t=1). */
+    topPx: number;
+    /** Animated transform components, ready to write into `style.transform`. */
+    translateXPct: number;
+    translateXPx: number;
+    translateYPx: number;
+}>;
+export type LineEndpoint = Readonly<{
+    x2: number;
+    y2: number;
+}>;
+export type DotAppearance = Readonly<{
+    opacity: number;
+    scale: number;
+}>;
+/**
+ * The constant pixel `left`/`top` for the surface — these never change during
+ * the animation. The outer container is anchor-zero (positioned exactly at
+ * the geographic anchor), so the surface's `left`/`top` are simply the
+ * pill's anchor-relative placement (`pillCSS`) with no extra offset adapter.
+ */
+export declare const computeSurfaceFixedOrigin: (geometry: StickFrameGeometry) => {
+    leftPx: number;
+    topPx: number;
+};
+/**
+ * Interpolates surface transform between the resting circle-at-anchor pose
+ * and the expanded pill-at-tip pose.
+ *
+ * - At `t = 0`: the visible circle sits centered on the anchor. Implemented
+ *   by translating the surface's top-left back from its expanded `left`/`top`
+ *   so the circle of diameter `circleDiameterPx` aligns with the anchor.
+ * - At `t = 1`: the surface is at its expanded pose with `pillCSS.translateXPct`
+ *   placing the appropriate pill cap at the tip.
+ */
+export declare const interpolateSurfacePlacement: (t: number, geometry: StickFrameGeometry) => SurfacePlacement;
+/**
+ * Format a transform string in the same three-function shape used previously.
+ * Centralized so the spring loop and React renders agree byte-for-byte.
+ */
+export declare const formatSurfaceTransform: (placement: SurfacePlacement) => string;
+/**
+ * Interpolates the SVG line endpoint between the anchor (zero-length line) and
+ * the tip. Coordinates are in the SVG's own coordinate space — the SVG's
+ * internal origin `(svgHalfExtentX, svgHalfExtentY)` is the anchor, so the tip
+ * lands at `(svgHalfExtentX + tip.x, svgHalfExtentY + tip.y)` at `t=1`.
+ */
+export declare const interpolateLineEndpoint: (t: number, geometry: StickFrameGeometry) => LineEndpoint;
+/**
+ * Interpolates the anchor dot's opacity and scale. Linear blend keeps the dot
+ * visually tied to the same progress value as the surface and line.
+ */
+export declare const interpolateDot: (t: number) => DotAppearance;

package/src/markers/animation/usePillBackgroundPaint.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Decides whether the pill background should be painted on the marker surface.
+ *
+ * The pill background is opaque while the marker is in pill state and is held
+ * for the duration of the collapse morph after `isPill` flips back to `false`.
+ * Without this lingering paint, the background would drop to transparent the
+ * instant the state changes, leaving the stick line visible through the
+ * collapsing surface for the entire morph (asymmetric with expand, where the
+ * background is opaque from the first frame).
+ *
+ * `lingerMs` should match the padding/border CSS transition duration so the
+ * paint flips off exactly when the surface has finished collapsing back to a
+ * circle.
+ */
+export declare const usePillBackgroundPaint: (isPill: boolean, lingerMs: number) => boolean;

package/src/markers/animation/useStickAnimation.d.ts

@@ -0,0 +1,21 @@
+import { type RefObject } from "react";
+import type { StickFrameGeometry } from "./stickFrame";
+import type { StickTweenHandle } from "./useStickTween";
+export type StickAnimationRefs = Readonly<{
+    surfaceRef: RefObject<HTMLDivElement | null>;
+    lineRef: RefObject<SVGLineElement | null>;
+    dotRef: RefObject<HTMLDivElement | null>;
+}>;
+/**
+ * Per-frame applier. Subscribes refs to the tween and writes the current
+ * geometry-derived placement on every animation frame plus every layout
+ * commit. `geometry` is captured by ref so prop-driven layout changes (size
+ * tier, angle) take effect immediately.
+ *
+ * The container is anchor-zero (its width/height are 0 and its position is
+ * the geographic anchor itself), so the previous "shrink to circle while
+ * resting / expand to envelope while animating" container-size dance is no
+ * longer needed and `useStickFrameSync` is now the only animation hook the
+ * marker needs.
+ */
+export declare const useStickFrameSync: (tween: StickTweenHandle, geometry: StickFrameGeometry) => StickAnimationRefs;

package/src/markers/animation/useStickTween.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Subscriber called every animation frame the spring is active. Receives the
+ * current progress value (`0..1`) so subscribers can update DOM imperatively
+ * without triggering React re-renders.
+ */
+export type StickTweenSubscriber = (progress: number) => void;
+export type StickTweenHandle = Readonly<{
+    /** Latest spring value. Read this on attach to render the initial frame. */
+    progressRef: {
+        readonly current: number;
+    };
+    /** Register a subscriber. Returns an unsubscribe function. */
+    subscribe: (subscriber: StickTweenSubscriber) => () => void;
+}>;
+/**
+ * Drives a single spring toward `target` (`0` or `1`) and notifies subscribers
+ * each frame. Subscribers receive the progress value imperatively so the
+ * marker DOM (surface position, line endpoint, dot scale) can be updated
+ * without re-rendering the React tree on every frame.
+ *
+ * The hook owns one `requestAnimationFrame` loop per marker. The loop:
+ * - starts when `target` differs from the current value,
+ * - clamps long frames (handled inside `stepSpring`),
+ * - pauses when the document becomes hidden and resumes when visible,
+ * - snaps directly to the target when the user prefers reduced motion,
+ * - stops cleanly on unmount.
+ */
+export declare const useStickTween: (target: number) => StickTweenHandle;

package/src/markers/geometry/stickPositioning.d.ts

@@ -0,0 +1,69 @@
+import type { StickDistanceMode, StickPositioning } from "../model/markerDomTypes";
+export type TipPoint = Readonly<{
+    x: number;
+    y: number;
+}>;
+export type PillCSSPlacement = Readonly<{
+    pillLeft: number;
+    pillTop: number;
+    translateXPct: number;
+}>;
+export type StickSvgExtent = Readonly<{
+    halfWidth: number;
+    halfHeight: number;
+}>;
+/**
+ * Converts a user-facing distance to the internal stick-tip distance (where the
+ * SVG line physically ends). The three modes differ in what the user distance
+ * measures relative to the pill silhouette:
+ *
+ * - `"centerline"` — user distance IS the tip distance (line ends at cap center)
+ * - `"rounded-edge"` — user distance is to the tangent surface; add cap radius (`pillHeight/2`)
+ * - `"bbox-edge"` — user distance is to the nearest bbox face; add the angle-dependent half-extent.
+ *   Requires `pillWidth` for correct rectangle geometry; falls back to a square assumption if omitted.
+ */
+export declare function resolveStickInternalLength(userDist: number, mode: StickDistanceMode, angleRad: number, pillHeight: number, pillWidth?: number): number;
+/**
+ * Resolves the stick tip position from a `StickPositioning` descriptor.
+ *
+ * The returned point is in anchor-relative coordinates (anchor = (0, 0)) and
+ * represents the physical end of the SVG stick line. A soft floor prevents the
+ * tip from being closer to the anchor than `dotRadius + pillHeight/2`, which
+ * would obscure the dot or overlap the pill over the anchor.
+ *
+ * @param pillWidth — pill outer width in px, used by `"bbox-edge"` mode for accurate
+ *   rectangular bounding box geometry. Omit (or pass undefined) to fall back to a square
+ *   approximation (safe for circle-mode markers where width ≈ height).
+ */
+export declare function resolveTentativeTip(positioning: StickPositioning, pillHeight: number, dotRadius: number, pillWidth?: number): TipPoint;
+/**
+ * Computes the CSS `left`, `top`, and `translateX(%)` needed to align the pill
+ * so the correct rounded cap is tangent to the stick tip.
+ *
+ * Uses a smooth blend parameterized by `t ∈ [0, 1]`:
+ * - `t = 1` (tipX ≥ +pillHeight/2): left cap at tipX, pill extends right
+ * - `t = 0.5` (tipX = 0):           pill centered on tipX
+ * - `t = 0` (tipX ≤ -pillHeight/2): right cap at tipX, pill extends left
+ *
+ * The blend zone radius is `r = pillHeight/2` (the cap radius). This ensures
+ * the facing cap center sits at (tipX, tipY) for any `|tipX| ≥ r`, which keeps
+ * the visible stick length angle-independent for `rounded-edge` distance mode.
+ * A wider blend zone (e.g. `pillHeight`) displaces the cap from tipX by an
+ * amount proportional to pill width, causing the stick to appear shorter at
+ * oblique angles.
+ *
+ * `translateX(-N%)` is relative to the element's own width, so no JS pill-width
+ * measurement is needed.
+ */
+export declare function computePillCSSPlacement(tipX: number, tipY: number, pillHeight: number): PillCSSPlacement;
+/**
+ * Computes the half-extents of the SVG element that draws the stick line, dot,
+ * and (visually) covers the worst-case pill envelope around the anchor.
+ *
+ * The container itself is anchor-zero (zero-size, positioned exactly at the
+ * geographic anchor); the SVG sits centered on that anchor with its internal
+ * origin at `(halfWidth, halfHeight)`. The returned extents only need to be
+ * recomputed when layout-affecting inputs change (size tier, tip angle, label
+ * budget) — never per animation frame.
+ */
+export declare function computeStickSvgExtent(tip: TipPoint, pillHeight: number, dotRadius: number, maxPillWidth: number): StickSvgExtent;

package/src/markers/geometry/useDirectionIndicator.d.ts

@@ -0,0 +1,8 @@
+import type { MarkerDomSize } from "../model/markerDomTypes";
+export type DirectionIndicatorDisplay = Readonly<{
+    show: boolean;
+    pixelSize: number;
+    rotationDegrees: number;
+}>;
+export declare function resolveDirectionIndicatorDisplay(direction: number | undefined, effectiveSize: MarkerDomSize): DirectionIndicatorDisplay;
+export declare function useDirectionIndicator(direction: number | undefined, effectiveSize: MarkerDomSize): DirectionIndicatorDisplay;

package/src/markers/internal/MapMarkerStickSurface.d.ts

@@ -0,0 +1,47 @@
+import { type CSSProperties, type HTMLAttributes, type ReactElement } from "react";
+import type { MapTheme } from "../../core/types";
+import { type DirectionIndicatorDisplay } from "../geometry/useDirectionIndicator";
+import type { MarkerDomSize, MarkerState, StickPositioning } from "../model/markerDomTypes";
+import type { ResolvedMarkerColors } from "../shared/markerColors";
+type MapMarkerStickSurfaceHandlers = Pick<HTMLAttributes<HTMLDivElement>, "onBlur" | "onClick" | "onFocus" | "onKeyDown" | "onMouseEnter" | "onMouseLeave">;
+export type MapMarkerStickSurfaceProps = MapMarkerStickSurfaceHandlers & {
+    readonly accessibleName: string;
+    readonly circleLayoutSize: MarkerDomSize;
+    readonly className: string | undefined;
+    readonly colors: ResolvedMarkerColors;
+    readonly contentLayoutSize: MarkerDomSize;
+    readonly dataTestId: string | undefined;
+    readonly direction: number | undefined;
+    readonly directionDisplay: DirectionIndicatorDisplay;
+    readonly icon: ReactElement | null;
+    readonly iconPx: number;
+    readonly labelText: string | undefined;
+    readonly labelVisible: boolean | undefined;
+    readonly panelOpen: boolean | undefined;
+    readonly state: MarkerState;
+    readonly stickPositioning: StickPositioning | undefined;
+    readonly style: CSSProperties | undefined;
+    readonly textPx: number;
+    readonly theme: MapTheme;
+};
+export declare const MapMarkerStickSurface: import("react").ForwardRefExoticComponent<MapMarkerStickSurfaceHandlers & {
+    readonly accessibleName: string;
+    readonly circleLayoutSize: MarkerDomSize;
+    readonly className: string | undefined;
+    readonly colors: ResolvedMarkerColors;
+    readonly contentLayoutSize: MarkerDomSize;
+    readonly dataTestId: string | undefined;
+    readonly direction: number | undefined;
+    readonly directionDisplay: DirectionIndicatorDisplay;
+    readonly icon: ReactElement | null;
+    readonly iconPx: number;
+    readonly labelText: string | undefined;
+    readonly labelVisible: boolean | undefined;
+    readonly panelOpen: boolean | undefined;
+    readonly state: MarkerState;
+    readonly stickPositioning: StickPositioning | undefined;
+    readonly style: CSSProperties | undefined;
+    readonly textPx: number;
+    readonly theme: MapTheme;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export {};

package/src/markers/model/mapMarkerDomPortalStacking.d.ts

@@ -0,0 +1,22 @@
+import type { DomPortalStackingInput, DomPortalStackingResult } from "@trackunit/react-map-adapter-shared";
+import type { MarkerState } from "./markerDomTypes";
+type MapMarkerDomPortalStackingBase = DomPortalStackingInput & {
+    /** `true` when `<MapMarker stickPositioning={...} />` is used. */
+    hasStick: boolean;
+};
+export type MapMarkerDomPortalStackingByPromotion = MapMarkerDomPortalStackingBase & {
+    expandedRank: number | null;
+};
+export type MapMarkerDomPortalStackingByMarkerState = MapMarkerDomPortalStackingBase & {
+    markerState: MarkerState;
+};
+export type MapMarkerDomPortalStackingParams = MapMarkerDomPortalStackingByPromotion | MapMarkerDomPortalStackingByMarkerState;
+/**
+ * Maps `<MapMarker>` presentation + state to `DomPortalStackingResult` for use with
+ * `markerRender.resolveDomPortalStacking` in `<Layers>`.
+ *
+ * Pass either `expandedRank` (for `resolveMarkerState`) or a pre-resolved `markerState`
+ * when the expanded state is data-driven and does not use `expandedRank` (for example, story helpers).
+ */
+export declare const resolveMapMarkerDomPortalStacking: (params: MapMarkerDomPortalStackingParams) => DomPortalStackingResult;
+export {};