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

package/src/layers/internal/computeBounds.d.ts

@@ -0,0 +1,34 @@
+import { type GeoJsonBbox, type GeoJsonGeometry, type GeoJsonPosition } from "@trackunit/geo-json-utils";
+import type { FitBoundsOptions, MapApi } from "../../core/types";
+/**
+ * Compute a bounding box from an array of positions.
+ * Returns null if the array is empty.
+ *
+ * @param positions - Array of [longitude, latitude] positions
+ * @returns GeoJsonBbox as [minLon, minLat, maxLon, maxLat] or null
+ */
+export declare const computeBoundsFromPositions: (positions: ReadonlyArray<GeoJsonPosition>) => GeoJsonBbox | null;
+/**
+ * For a GeoJSON bbox `[minLon, minLat, maxLon, maxLat]`, returns the **larger**
+ * of the east–west extent and the north–south extent, in **degrees**.
+ *
+ * Used when choosing `fitBounds` padding so padding follows the longer geographic
+ * axis (a very thin box still gets a sensible scale).
+ */
+export declare const maxLongitudeLatitudeSpanDegrees: (bbox: GeoJsonBbox) => number;
+/**
+ * Compute dynamic fitBounds options based on the geographic span of a bounding box.
+ * Smaller shapes get more padding and a maxZoom cap to avoid over-zooming;
+ * larger shapes get less padding.
+ */
+export declare const computeFitPadding: (maxSpanDegrees: number) => FitBoundsOptions;
+/**
+ * Compute bounds from a geometry and fit the map viewport with span-based dynamic padding.
+ * No-op if the geometry yields no positions (e.g. empty GeometryCollection).
+ */
+export declare const fitFeatureBounds: (api: MapApi, geometry: GeoJsonGeometry) => void;
+/**
+ * Merge multiple bounding boxes into one that encompasses all of them.
+ * Ignores null entries. Returns null if all inputs are null.
+ */
+export declare const mergeBounds: (boxes: ReadonlyArray<GeoJsonBbox | null>) => GeoJsonBbox | null;

package/src/layers/internal/countFeaturesInViewport.d.ts

@@ -0,0 +1,14 @@
+import { type GeoJsonBbox, type GeoJsonFeatureCollection } from "@trackunit/geo-json-utils";
+/**
+ * Count features in `collection` whose geometry overlaps (or touches) `bounds`.
+ *
+ * Returns the total feature count when `bounds` is null (e.g. before the map
+ * has reported its first viewport). For Point features this is equivalent to
+ * the previous marker-only point-in-bounds check; for non-Point features it is
+ * a cheap bbox-vs-bbox intersection — full geometry clipping is intentionally
+ * avoided since this runs every adaptive resolution pass.
+ *
+ * Shared by both the marker adaptive resolution system and the shape label
+ * resolution system so the two never disagree on what "in viewport" means.
+ */
+export declare const countFeaturesInViewport: (collection: GeoJsonFeatureCollection, bounds: Readonly<GeoJsonBbox> | null) => number;

package/src/layers/internal/createLazyGetter.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Create a getter that lazily computes and caches a value.
+ * The getter calls `compute` on first invocation and returns
+ * the cached result on subsequent calls.
+ *
+ * Designed for use with `useMemo`:
+ * ```ts
+ * const getBounds = useMemo(
+ *   () => createLazyGetter(() => computeBounds(data)),
+ *   [data]
+ * );
+ * ```
+ * When `useMemo` re-runs (deps changed), a fresh getter with an
+ * empty cache is created, discarding the old one.
+ */
+export declare const createLazyGetter: <TValue>(compute: () => TValue) => (() => TValue);

package/src/layers/internal/layerHelpers.d.ts

@@ -0,0 +1,18 @@
+import type { DomPortalDescriptor, DomRenderState, MapTheme } from "@trackunit/react-map-adapter-shared";
+import type { UseLayersReturn } from "../useLayers";
+export declare const EMPTY_PORTALS: ReadonlyArray<DomPortalDescriptor>;
+/** No-op subscribe for when a marker/cluster portal store is not available */
+export declare const noopSubscribe: (_callback: () => void) => (() => void);
+/** Empty snapshot for when a marker/cluster portal store is not available */
+export declare const emptySnapshot: () => ReadonlyArray<DomPortalDescriptor>;
+export declare const DEFAULT_RENDER_STATE: DomRenderState;
+/** Delay before clearing hover state to prevent flickering from rapid mouseleave/mouseenter pairs */
+export declare const HOVER_END_DEBOUNCE_MS = 100;
+/**
+ * Compute `DomRenderState` for a given feature ID by checking
+ * whether it matches the current selected/hovered entity.
+ *
+ * `isMounting` is always `false` until slice 6 (SAGA-424) wires
+ * `useMarkerMountBridge`.
+ */
+export declare const computeItemRenderState: (featureId: string, interaction: UseLayersReturn["interaction"], theme?: MapTheme, labelVisible?: boolean) => DomRenderState;

package/src/layers/internal/markerPortalZIndex.d.ts

@@ -0,0 +1,17 @@
+import { type ClusterRenderConfig, type DomRenderState, type RenderConfig } from "@trackunit/react-map-adapter-shared";
+import type { LayerHandle, MarkerLayerHandle } from "../types";
+export declare const findMarkersLayerHandle: (handles: ReadonlyArray<LayerHandle>, sourceId: string) => MarkerLayerHandle | undefined;
+/**
+ * Resolves the CSS `z-index` for a marker/cluster DOM portal container.
+ *
+ * When `resolveDomPortalStacking` is omitted on the active render config,
+ * falls back to the pre–stacking-hierarchy behavior: `circle` geometry with
+ * interaction-only phases.
+ *
+ * Accepts both marker `RenderConfig` and cluster `ClusterRenderConfig`. The
+ * `DomRenderState` passed in is the marker-shaped state computed by `<Layers>`
+ * for z-index purposes (clusters use the same hovered/selected phase
+ * vocabulary even though their render callback ultimately receives a simpler
+ * `ClusterRenderState`).
+ */
+export declare const resolveMarkerPortalContainerZIndex: (renderConfig: RenderConfig<unknown> | ClusterRenderConfig<unknown, unknown>, sourceData: unknown, itemState: DomRenderState) => number;

package/src/layers/internal/useDblClickFit.d.ts

@@ -0,0 +1,13 @@
+import type { Entity } from "@trackunit/react-map-adapter-shared";
+import type { MapApi } from "../../core/types";
+import type { LayerHandle } from "../types";
+/**
+ * Creates a dblclick handler that fits the viewport to the double-clicked
+ * entity's bounds. Behaviour per entity type:
+ *
+ * - **shape**: fit to the individual feature's geometry
+ * - **marker**: panTo + zoom to a close level
+ * - **cluster**: fit to bounds of contained markers when any resolve from loaded handles; if none (e.g. server cluster), fit to `bbox` when present on the entity
+ * - **route**: fit to the route layer's bounds
+ */
+export declare const useDblClickFit: (api: MapApi | undefined, handles: ReadonlyArray<LayerHandle>) => ((entity: Entity) => void) | undefined;

package/src/layers/internal/useEntityInteraction.d.ts

@@ -0,0 +1,21 @@
+import type { Entity, LayerPort } from "@trackunit/react-map-adapter-shared";
+type UseEntityInteractionConfig = Readonly<{
+    layerPort: LayerPort | null;
+    hover: (entity: Entity | null) => void;
+    select: (entity: Entity | null) => void;
+    dblClick?: (entity: Entity) => void;
+}>;
+/**
+ * Subscribes to entity interaction events (click, dblclick, hover-start,
+ * hover-end) from the map adapter and dispatches to the provided callbacks.
+ *
+ * Hover-end is debounced to prevent flickering from rapid mouseleave/mouseenter
+ * pairs when the cursor moves within a marker's DOM tree.
+ *
+ * @returns A stable callback to guard/unguard against adapter hover events.
+ *   Call with `true` when a DOM-path hover begins (cancels pending timers and
+ *   suppresses adapter hover-start/hover-end). Call with `false` when the DOM
+ *   hover ends, allowing adapter events to flow again.
+ */
+export declare const useEntityInteraction: ({ layerPort, hover, select, dblClick, }: UseEntityInteractionConfig) => ((active: boolean) => void);
+export {};

package/src/layers/internal/useFitFeatureBounds.d.ts

@@ -0,0 +1,19 @@
+import { fitFeatureBounds } from "./computeBounds";
+export type FitFeatureBoundsHelpers = Readonly<{
+    fitFeatureBounds: typeof fitFeatureBounds;
+}>;
+/**
+ * Build-your-own hook: stable reference to the `fitFeatureBounds` map action.
+ *
+ * Returns the `fitFeatureBounds` helper for consumers who need to programmatically
+ * zoom/fit the viewport to a GeoJSON geometry — for example in click handlers that
+ * should navigate to a selected shape or annotation.
+ *
+ * @example
+ * ```tsx
+ * const { fitFeatureBounds } = useFitFeatureBounds();
+ * // On click:
+ * fitFeatureBounds(api, feature.geometry);
+ * ```
+ */
+export declare const useFitFeatureBounds: () => FitFeatureBoundsHelpers;

package/src/layers/internal/useLayerHandleSync.d.ts

@@ -0,0 +1,18 @@
+import type { LayerPort, MapInteractionState, MapLayer } from "@trackunit/react-map-adapter-shared";
+import { type RefObject } from "react";
+import type { LayerHandle } from "../types";
+export type UseLayerHandleSyncReturn = Readonly<{
+    renderedSourceIds: RefObject<Set<string>>;
+    hasSourceReadiness: boolean;
+    readyRevision: number;
+}>;
+/**
+ * Syncs layer handles and interaction state to the map adapter via `LayerPort.setSnapshot`.
+ *
+ * Computes a full `LayerSnapshot` from the current handles and interaction state
+ * and pushes it to the adapter on every change. The adapter owns the diff.
+ *
+ * Also manages `onSourceReady` subscriptions for shape layers so edge labels
+ * can defer rendering until the parent shape source has finished drawing.
+ */
+export declare const useLayerHandleSync: (layerPort: LayerPort | null, handles: ReadonlyArray<LayerHandle>, interaction: MapInteractionState, decorationLayers?: ReadonlyArray<MapLayer>) => UseLayerHandleSyncReturn;

package/src/layers/internal/useLayerReady.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Result of the `useLayerReady` hook.
+ * Provides the `ready` promise, `loadsData` flag, and current `isLoading` state
+ * for use in layer handles.
+ */
+export type LayerReadyResult = Readonly<{
+    /** Resolves when initial data is available. Stable reference across renders. */
+    ready: Promise<void>;
+    /** Whether this layer fetches its own data (true when `loading` arg is provided). */
+    loadsData: boolean;
+    /** Current loading state. */
+    isLoading: boolean;
+}>;
+/**
+ * Shared hook that tracks initial data readiness for a layer.
+ *
+ * - `loading: undefined` -> not a data-loading layer; ready immediately.
+ * - `loading: false` -> data-loading layer with data already available; ready immediately.
+ * - `loading: true` -> data-loading layer still waiting; ready is a deferred promise
+ *   that resolves on the first `true -> false` transition.
+ *
+ * Once resolved, the promise stays resolved. Subsequent `true -> false` cycles
+ * do NOT re-pend -- this hook tracks *initial* readiness only.
+ */
+export declare const useLayerReady: (loading?: boolean) => LayerReadyResult;

package/src/layers/internal/useMarkerMountBridge.d.ts

@@ -0,0 +1,41 @@
+import type { RenderMedium } from "@trackunit/react-map-adapter-shared";
+export type UseMarkerMountBridgeReturn = Readonly<{
+    mountingIds: ReadonlySet<string>;
+}>;
+/**
+ * Pure transition detector — returns the subset of `currentMediums` whose
+ * medium is `"dom"` and whose previous medium was `"symbol"`. Exported for
+ * unit tests; the React hook below is the consumer.
+ */
+export declare const computeMountingFeatureIds: (currentMediums: ReadonlyMap<string, RenderMedium>, previousMediums: ReadonlyMap<string, RenderMedium>, existingIds: ReadonlySet<string>) => Set<string>;
+/**
+ * State-machine hook tracking `symbol → dom` transitions for adaptive markers
+ * (ADR-0009 §"Mounting bridge").
+ *
+ * On the commit where a feature's medium first appears as `"dom"` (after
+ * having been `"symbol"`), its id is included in `mountingIds`. On the next
+ * commit, `mountingIds` is empty again. `<Layers>` uses this signal to
+ * synthesize a first-commit render state with `isMounting: true` and
+ * `selected`/`hovered: false` so consumer-side CSS animations can morph from
+ * a small "default" footprint into the resting hover/select form.
+ *
+ * The hook is purely a state machine — it does not touch the DOM or the map
+ * adapter. The caller decides what `currentMediums` reflects; in `<Layers>`'s
+ * case it is derived from the published DOM portal descriptors so that the
+ * transition is detected at the moment the portal first renders, with
+ * non-portal adaptive features defaulting to `"symbol"`.
+ *
+ * Per-feature `previousMedium` is intentionally not exposed in the public
+ * render state — only `isMounting` (Q5 of the SAGA-414 design grilling).
+ *
+ * The two-pass mechanism is owned here: an internal mount store holds the
+ * `previousMediums` map and the active `mountingIds` set, and notifies
+ * subscribers via `useSyncExternalStore` rather than a React `setState` (so
+ * the cascading-render guard rail does not block the legitimate two-pass
+ * pattern). The detection layout effect calls `advance`; the passive clear
+ * effect calls `clear` after the browser has had a chance to paint the
+ * populated set once.
+ */
+export declare const useMarkerMountBridge: (features: ReadonlyArray<{
+    id: string;
+}>, currentMediums: ReadonlyMap<string, RenderMedium>) => UseMarkerMountBridgeReturn;

package/src/layers/internal/useViewportContext.d.ts

@@ -0,0 +1,34 @@
+import { type GeoJsonBbox, type GeoJsonFeature } from "@trackunit/geo-json-utils";
+import type { MapApi } from "../../core/types";
+/**
+ * Shared map view state consumed by adaptive rendering systems (marker render
+ * medium selection and shape label resolution). Combines high-frequency camera
+ * values with low-frequency tile size, so viewport reading is defined once.
+ */
+export type ViewportContext = Readonly<{
+    zoom: number;
+    bounds: Readonly<GeoJsonBbox> | null;
+    tileSize: number;
+    /**
+     * Returns `true` when the current viewport bounds are fully contained inside
+     * the given feature's geometry. Useful for suppressing edge labels and
+     * triggering annotation fallbacks when the user has zoomed into a shape.
+     *
+     * Returns `false` when bounds are not yet available or the feature has no
+     * polygon geometry.
+     */
+    isViewportInsideFeature: (feature: GeoJsonFeature) => boolean;
+}>;
+/**
+ * Reads `zoom` and `bounds` from the camera channel and `tileSize` from
+ * `api.state`, returning a stable `ViewportContext` reference that only changes
+ * when one of the underlying values changes. Falls back to sensible defaults
+ * while `api` is initializing.
+ *
+ * Stability matters because the result flows into `useMemo` deps in both
+ * `useAdaptiveMarkerResolution` and `useShapeDecorations` — if a new object
+ * came back every render the downstream resolution work would re-run for no
+ * reason. Bounds are projected to primitive deps so a fresh bbox array with
+ * equal values does not invalidate the memo.
+ */
+export declare const useViewportContext: (api: MapApi | undefined) => ViewportContext;

package/src/layers/mapFocus.d.ts

@@ -0,0 +1,29 @@
+import type { Icon } from "@trackunit/react-components";
+import type { ComponentProps } from "react";
+export type MapFocusTierDisplay = Readonly<{
+    /** Icon name for the marker icon slot and future legend. */
+    iconName?: ComponentProps<typeof Icon>["name"];
+    /** Hex color driving the marker (symbol + DOM) and future chart slice. */
+    color?: string;
+    /** Optional static label override used by future focus controls. */
+    label?: string;
+}>;
+export type MapFocusTier<TAsset> = Readonly<{
+    match: (asset: TAsset) => boolean;
+    /** Absent means this tier has no visual representation. */
+    display?: MapFocusTierDisplay;
+}>;
+/**
+ * Configurable policy driving marker expansion, icon, and color from a
+ * single asset property. Tiers are evaluated in order; first match wins.
+ */
+export type MapFocus<TAsset> = Readonly<{
+    /**
+     * Stable id used by feature state (for example persisted user preference)
+     * instead of serializing predicate functions.
+     */
+    id: string;
+    tiers: ReadonlyArray<MapFocusTier<TAsset>>;
+}>;
+export { buildExpandedIds } from "./buildExpandedIds";
+export { useExpandedIds } from "./useExpandedIds";

package/src/layers/routes/useRoute.d.ts

@@ -0,0 +1,39 @@
+import { type GeoJsonPosition } from "@trackunit/geo-json-utils";
+import type { ControlConfig } from "../../controls/types";
+import type { FitParticipation, RouteLayerHandle, RouteStyle } from "../types";
+export type UseRouteOptions = Readonly<{
+    /** Unique ID for this layer */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Ordered waypoints that define the route */
+    waypoints: ReadonlyArray<GeoJsonPosition>;
+    /** Route styling */
+    style: RouteStyle;
+    /** Whether the route is interactive (clickable/hoverable). Default: true */
+    interactive?: boolean;
+    /** Optional controls to contribute to the map UI */
+    controls?: ReadonlyArray<ControlConfig>;
+    /** 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 UseRouteReturn = RouteLayerHandle;
+/**
+ * `useRoute` -- creates a route layer handle from an array of waypoints.
+ *
+ * Converts the waypoints to a GeoJSON LineString internally.
+ * Routes need at least 2 waypoints to be rendered.
+ *
+ * @example
+ * ```tsx
+ * const route = useRoute({
+ *   id: "delivery-route",
+ *   name: "Delivery Route",
+ *   waypoints: [[-73.98, 40.75], [-73.97, 40.76], [-73.96, 40.77]],
+ *   style: { color: "blue", width: 3, showDirectionArrows: true },
+ * });
+ * ```
+ */
+export declare const useRoute: (options: UseRouteOptions) => UseRouteReturn;

package/src/layers/shared/measureLabelWidth.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Measure the rendered pixel width of label text using an off-screen probe
+ * styled with the same CSS classes as shape edge labels (`cvaShapeLabel`).
+ *
+ * Shape edge labels and other layout utilities that need a DOM-measured width use this.
+ *
+ * Results are cached per label text. In environments where DOM measurement is
+ * unavailable or returns zero (SSR, jsdom), falls back to a character-count
+ * estimate (label.length * 6 + 16).
+ */
+export declare const measureLabelWidth: (label: string) => number;

package/src/layers/types.d.ts

@@ -0,0 +1,131 @@
+import type { GeoJsonBbox, GeoJsonFeature, GeoJsonFeatureCollection, GeoJsonPosition } from "@trackunit/geo-json-utils";
+import type { AdaptiveMarkerResolution, ClusterConfig, ClusterRenderConfig, RenderConfig, RouteStyle, ShapeInteractiveMode, ShapeStyle } from "@trackunit/react-map-adapter-shared";
+import type { ControlConfig } from "../controls/types";
+import type { ShapeDecoration } from "./useShapes/shapeDecorations";
+import type { ShapeLabelResolutionContext } from "./useShapes/shapeLabelResolution";
+export type { AdaptiveMarkerResolution, AdaptiveRenderConfig, AdaptiveRenderState, AdaptiveResolutionContext, CircleSymbolDescriptor, ClientClusterConfig, ClusterConfig, ClusterDomRenderConfig, ClusterInfo, ClusterRenderConfig, ClusterRenderState, ClusterSymbolRenderConfig, ClusterSymbolStyle, CommonRenderState, DomPortalStackingInput, DomPortalStackingResolver, DomPortalStackingResult, DomRenderConfig, DomRenderState, GeoJsonFeature, GeoJsonFeatureCollection, GeoJsonGeometry, MarkerAnchor, MarkerDomPortalStackGeometry, MarkerDomPortalStackPhase, PixelOffset, RenderConfig, RenderMedium, ResolutionContext, RouteStyle, ServerClusterConfig, ShapeInteractiveMode, ShapeStyle, ShapeStyleOverrides, SymbolDescriptor, SymbolRenderConfig, SymbolRenderState, } from "@trackunit/react-map-adapter-shared";
+export { computeMarkerDomPortalZIndex } from "@trackunit/react-map-adapter-shared";
+/**
+ * Controls whether a layer's bounds are included in fit-to-content operations.
+ *
+ * - `"all"` — participates in initial auto-fit, manual `fitNow()`, and future always-fit mode.
+ * - `"initial"` — only participates in the initial auto-fit on first load.
+ * - `"none"` — never participates in any fit operation.
+ */
+export type FitParticipation = "all" | "initial" | "none";
+/**
+ * Metadata common to all layer types.
+ * Every layer hook returns an object extending this shape.
+ */
+export type LayerMeta = Readonly<{
+    /** Unique identifier for this layer */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Whether this layer fetches its own data */
+    loadsData: boolean;
+    /** Whether data is currently loading */
+    loading: boolean;
+    /** Resolves when initial data is available (or immediately if loadsData is false) */
+    ready: Promise<void>;
+    /**
+     * Lazily compute bounding box of all features.
+     * Cached internally until source data reference changes.
+     */
+    getBounds: () => GeoJsonBbox | null;
+    /** Summary counts -- always cheap (derived from .length). Semantics depend on layer type. */
+    counts: Readonly<Record<string, number>>;
+    /** Controls this layer wants to contribute to the map UI */
+    controls: ReadonlyArray<ControlConfig>;
+    /**
+     * Controls whether this layer's bounds are included in fit-to-content operations.
+     * Default: `"all"`.
+     */
+    fitParticipation: FitParticipation;
+}>;
+/**
+ * Marker layer handle -- returned by `useMarkers`.
+ * Contains all data and configuration needed to render markers and clusters.
+ */
+export interface MarkerLayerHandle extends LayerMeta {
+    readonly layerType: "markers";
+    /** GeoJSON points for all positioned markers */
+    readonly features: GeoJsonFeatureCollection;
+    /** Marker render configuration */
+    readonly markerRender: RenderConfig<unknown>;
+    /** Cluster configuration, if clustering is enabled */
+    readonly clusterConfig: ClusterConfig<unknown> | null;
+    /** Cluster render configuration, if clustering is enabled */
+    readonly clusterRender: ClusterRenderConfig<unknown, unknown> | null;
+    /** Server-side cluster features (GeoJSON points), if using server-side clustering */
+    readonly clusterFeatures: GeoJsonFeatureCollection | null;
+    /**
+     * Per-cluster `memberItems` cross-referenced from the hook's `data` array via
+     * `getMarkerIds`. Keyed by cluster ID. `null` value when any member ID is
+     * missing from the data index. Null map when server clustering is not in
+     * use. Consumed by `<Layers>` to build `ClusterRenderState<TItem>` for DOM
+     * cluster portals.
+     */
+    readonly clusterMemberItems: ReadonlyMap<string, ReadonlyArray<unknown> | null> | null;
+    /**
+     * Filled by `<Layers>` when `markerRender.mode === "adaptive"` — per-feature
+     * resolved display modes for the map adapter (plan §8).
+     */
+    readonly adaptiveResolution?: AdaptiveMarkerResolution;
+}
+/**
+ * Shape layer handle -- returned by `useShapes`.
+ * Contains GeoJSON features (polygons, multipolygons, lines) with styling.
+ */
+export interface ShapeLayerHandle extends LayerMeta {
+    readonly layerType: "shapes";
+    /** GeoJSON features for all shapes */
+    readonly features: GeoJsonFeatureCollection;
+    /** Base shape style (static value). When per-feature styling is used, this is `{}`. */
+    readonly style: ShapeStyle;
+    /** Resolves shape style for static and viewport-aware rendering passes. */
+    readonly resolveStyle: (feature: GeoJsonFeature, ctx?: ShapeLabelResolutionContext) => ShapeStyle;
+    /** Per-feature resolved styles, keyed by `String(feature.id)`. */
+    readonly featureStyles?: ReadonlyMap<string, ShapeStyle>;
+    /** Which parts of the shape respond to interaction */
+    readonly interactive: ShapeInteractiveMode;
+    /**
+     * Returns all decorations for a feature, including auto-generated ones
+     * (e.g. multi-geometry "+" badges). Merging of custom and auto decorations
+     * is handled by `useShapes` at construction time.
+     */
+    readonly getDecorations: (feature: GeoJsonFeature) => ReadonlyArray<ShapeDecoration>;
+}
+/**
+ * Route layer handle -- returned by `useRoute`.
+ * Contains a polyline with waypoints and styling.
+ */
+export interface RouteLayerHandle extends LayerMeta {
+    readonly layerType: "route";
+    /** GeoJSON LineString feature for the route */
+    readonly features: GeoJsonFeatureCollection;
+    /** Waypoint positions (original input) */
+    readonly waypoints: ReadonlyArray<GeoJsonPosition>;
+    /** Route style */
+    readonly style: RouteStyle;
+    /** Whether route is interactive (clickable/hoverable). Default: false */
+    readonly interactive: boolean;
+}
+/**
+ * Image overlay handle -- returned by `useImageOverlay`.
+ * Contains a georeferenced image to display on the map.
+ */
+export interface ImageOverlayHandle extends LayerMeta {
+    readonly layerType: "image-overlay";
+    /** URL of the image to display */
+    readonly url: string;
+    /** Geographic bounds the image covers */
+    readonly imageBounds: GeoJsonBbox;
+    /** Opacity from 0 to 1 */
+    readonly opacity: number;
+}
+/**
+ * Discriminated union of all layer handle types.
+ * Discriminated on `layerType`.
+ */
+export type LayerHandle = MarkerLayerHandle | ShapeLayerHandle | RouteLayerHandle | ImageOverlayHandle;

package/src/layers/useExpandedIds.d.ts

@@ -0,0 +1,20 @@
+import type { MapFocus } from "./mapFocus";
+/**
+ * Stateful wrapper around `buildExpandedIds` that feeds the previous result
+ * back as `previousIds`, producing hysteresis: markers that were expanded
+ * stay expanded across incremental data updates (e.g. pan/zoom refetches).
+ *
+ * Memory rules:
+ * - A marker no longer in `items` is naturally forgotten (not a candidate).
+ * - When `focus.id` changes the memory is reset entirely.
+ *
+ * Callers replace a bare `useMemo(() => buildExpandedIds(...))` with this
+ * hook — the signature is identical except `previousIds` is managed
+ * internally.
+ *
+ * State is kept via the render-phase setState pattern (React docs §derived
+ * state): calling setState during render causes React to discard the current
+ * render and immediately re-render with the updated state, so callers never
+ * observe a stale value. This avoids reading/writing a ref during render.
+ */
+export declare const useExpandedIds: <TAsset>(items: ReadonlyArray<TAsset>, getId: (item: TAsset) => string, focus: MapFocus<TAsset>, limit: number, getPosition?: (item: TAsset) => readonly [number, number, ...Array<number>]) => ReadonlySet<string>;

package/src/layers/useFitToContent.d.ts

@@ -0,0 +1,57 @@
+import type { MapApi } from "../core/types";
+import type { LayerHandle } from "./types";
+/**
+ * Options for the `useFitToContent` hook.
+ */
+export type FitToContentOptions = Readonly<{
+    /** Skip the automatic initial fit entirely. Default: false */
+    disabled?: boolean;
+    /** Padding in pixels around the fitted bounds. Default: 50 */
+    padding?: number;
+    /** Maximum zoom level after fitting. Default: 18 */
+    maxZoom?: number;
+    /** Timeout in ms before fitting with whatever data is available. Default: 10000 */
+    timeout?: number;
+}>;
+/**
+ * Return type of the `useFitToContent` hook.
+ */
+export type FitToContentResult = Readonly<{
+    /** True once the initial fit has been performed (or skipped due to empty bounds). */
+    hasFitted: boolean;
+    /** True while waiting for participating layers to load before the initial fit. */
+    isWaiting: boolean;
+    /** Manually trigger a fit-to-content. Animates. Only includes `fitParticipation: "all"` layers. */
+    fitNow: () => void;
+}>;
+/**
+ * `useFitToContent` -- orchestrates a one-time viewport fit once all
+ * participating layers have loaded their initial data.
+ *
+ * Only layers with `fitParticipation !== "none"` are waited on and included
+ * in the initial fit. `fitNow()` only includes `fitParticipation: "all"` layers.
+ *
+ * A configurable timeout (default 10s) ensures the map fits to whatever
+ * data is available if some layers are slow.
+ *
+ * When using this hook alongside an adapter's `initialViewport`, note that the
+ * initial viewport serves as a loading-state viewport and will be overridden
+ * once layer data arrives and the fit is performed.
+ *
+ * @example
+ * ```tsx
+ * const markers = useMarkers({ id: "fleet", ..., loading: isLoading });
+ * const shapes = useShapes({ id: "zones", ..., fitParticipation: "none" });
+ * const layers = useLayers(api, [markers, shapes]);
+ *
+ * const { hasFitted, isWaiting, fitNow } = useFitToContent(api, layers.handles);
+ *
+ * return (
+ *   <Map>
+ *     <Layers api={api} layers={layers} />
+ *     {hasFitted ? <button onClick={fitNow}>Re-fit</button> : null}
+ *   </Map>
+ * );
+ * ```
+ */
+export declare const useFitToContent: (api: MapApi, handles: ReadonlyArray<LayerHandle>, options?: FitToContentOptions) => FitToContentResult;

package/src/layers/useLayers.d.ts

@@ -0,0 +1,58 @@
+import type { GeoJsonBbox } from "@trackunit/geo-json-utils";
+import { type Entity, type MapInteractionState } from "@trackunit/react-map-adapter-shared";
+import type { ControlConfig } from "../controls/types";
+import type { MapApi } from "../core/types";
+import type { LayerHandle } from "./types";
+/**
+ * Return type of `useLayers`.
+ */
+export type UseLayersReturn = Readonly<{
+    /** Shared interaction state across all layers */
+    interaction: MapInteractionState;
+    /** Select an entity (or null to clear selection). Works across all layer types. */
+    select: (entity: Entity | null) => void;
+    /** Hover an entity (or null to clear hover). Works across all layer types. */
+    hover: (entity: Entity | null) => void;
+    /** Clear all interaction state (selection and hover) */
+    clearAll: () => void;
+    /**
+     * Lazily compute combined bounds of all layers.
+     * Calls each layer's getBounds() and merges the results.
+     */
+    getBounds: () => GeoJsonBbox | null;
+    /** True while any layer is loading */
+    loading: boolean;
+    /** Resolves when ALL layers have their initial data */
+    ready: Promise<void>;
+    /** Aggregated controls from all layers */
+    controls: ReadonlyArray<ControlConfig>;
+    /** Layer handles (passed to Layers component for rendering) */
+    handles: ReadonlyArray<LayerHandle>;
+}>;
+/**
+ * `useLayers` -- aggregates layer handles and manages shared interaction state.
+ *
+ * This is the central hook that ties all layers together:
+ * - Shared hover/select interaction via a reducer (cross-layer, single entity at a time)
+ * - Combined bounds across all layers (lazy, cached)
+ * - Loading/ready coordination
+ * - Aggregated controls
+ *
+ * @example
+ * ```tsx
+ * const fleet = useMarkers({ ... });
+ * const shapes = useShapes({ ... });
+ * const layers = useLayers(api, [fleet, shapes]);
+ *
+ * // layers.interaction.selectedEntity
+ * // layers.getBounds()
+ * // layers.ready
+ *
+ * return (
+ *   <Map>
+ *     <Layers api={api} layers={layers} />
+ *   </Map>
+ * );
+ * ```
+ */
+export declare const useLayers: (api: MapApi, layers: ReadonlyArray<LayerHandle>) => UseLayersReturn;