@perspective-dev/viewer-charts 5.3.0 → 5.4.0

package/dist/esm/interaction/legend-controller.d.ts

@@ -0,0 +1,246 @@
+import { type PluginConfig } from "../charts/chart";
+import type { PlotRect } from "../layout/plot-layout";
+import type { InteractionEvent } from "../transport/protocol";
+/** Minimum legend width for any mode (drag clamp + config clamp). */
+export declare const LEGEND_MIN_WIDTH = 48;
+/** Maximum configurable legend width (further clamped to canvas/2). */
+export declare const LEGEND_MAX_WIDTH = 512;
+/** Minimum floating-panel height. */
+export declare const LEGEND_MIN_HEIGHT = 48;
+/** Floating-panel header strip height (title + move grip). */
+export declare const LEGEND_HEADER_H = 18;
+/** Entry row height shared by every swatch-list legend painter. */
+export declare const LEGEND_LINE_HEIGHT = 18;
+/**
+ * Floating-frame chrome, as consumed from the panel box by
+ * `paintFloatingLegendFrame`: `PAD_L` insets the content from the left
+ * edge, `W` is the total width the frame takes, and `H` the total
+ * height it takes BELOW the header (split evenly above/below). The
+ * auto-size math is the frame's inverse, so both must read the same
+ * constants — a drifted pair sizes a panel that clips its own last row.
+ */
+export declare const LEGEND_FRAME_PAD_L = 8;
+export declare const LEGEND_FRAME_W = 12;
+export declare const LEGEND_FRAME_H = 8;
+/** Width the header title is laid out against: `box.width - PAD`. */
+export declare const LEGEND_TITLE_PAD = 16;
+/**
+ * Entry-row chrome left of the label text: swatch (10) + gap (6).
+ * Gradient legends substitute their own (bar 16 + gap 5).
+ */
+export declare const LEGEND_ENTRY_LEADING = 16;
+/**
+ * Sidebar gutter width when the sidebar legend is active: the
+ * configured `legend_width_px`, or `legacy` (the chart family's
+ * historical gutter constant) when the config is 0 (auto).
+ */
+export declare function legendSidebarWidth(cfg: PluginConfig, legacy: number): number;
+/**
+ * `legend_mode` with `"auto"` resolved away — the only form the
+ * layout/paint/interaction paths consume. Painters record the resolved
+ * mode in `setPainted`, so the controller's drag semantics follow it
+ * with no separate resolution.
+ */
+export type ResolvedLegendMode = "sidebar" | "none" | "floating";
+/**
+ * `"auto"` resolves to `"floating"` when every legend entry fits the
+ * DEFAULT floating panel (160 px ≈ header + 7 rows) without scrolling —
+ * a compact overlay that frees the whole gutter — and to `"sidebar"`
+ * otherwise, where a long list gets dedicated, scrollable space instead
+ * of occluding the plot. Continuous gradient legends have no entry
+ * list; callers pass `entryCount = 0` and they resolve to floating.
+ */
+export declare const AUTO_FLOATING_MAX_ROWS = 7;
+export declare function resolveLegendMode(cfg: PluginConfig, entryCount: number): ResolvedLegendMode;
+/**
+ * Right-margin width a plot layout should reserve for the legend.
+ * `legacy` is the family's historical `hasLegend` gutter (80 for
+ * single-plot layouts, 96 for facet grids). Modes `"none"` and
+ * `"floating"` collapse the gutter to the no-legend breathing margin —
+ * the plot widens and the floating panel overlays it. `entryCount`
+ * feeds the `"auto"` resolution ({@link resolveLegendMode}); pass the
+ * same count the legend painter will enumerate.
+ */
+export declare function legendRightGutter(cfg: PluginConfig, hasLegend: boolean, legacy?: number, entryCount?: number): number;
+/**
+ * Tree-chart variant of {@link legendRightGutter}: trees reserve `0`
+ * (fully flush cells) rather than a 16px breathing margin when no
+ * sidebar legend is present.
+ */
+export declare function legendTreeGutter(cfg: PluginConfig, hasLegend: boolean, legacy: number, entryCount?: number): number;
+/**
+ * Content measurements a floating panel needs to size itself in
+ * `legend_size_mode: "auto"`. Supplied by the call site (which owns the
+ * chrome canvas and the label set) and consumed ONLY by that mode, so a
+ * `"fixed"` panel — and every sidebar legend — pays nothing.
+ */
+export interface LegendAutoFit {
+    /**
+     * Entry rows the painter will enumerate. `0` marks a continuous
+     * gradient legend, which has no row list and keeps the default
+     * panel height.
+     */
+    entryCount: number;
+    /**
+     * Panel width in CSS px that fits the widest entry label AND the
+     * header title, frame chrome included. Invoked at most once per
+     * `floatingBox` call; see `legendAutoFit`.
+     */
+    boxWidth?: () => number;
+}
+/**
+ * Cursor-zone classification for a point over the painted legend.
+ * Sidebar legends expose only `resize-w` (their left edge) plus
+ * `scrollbar` / `body`; floating panels add the E/S/SE handles and the
+ * `move` grip (header strip — the body also moves, gated by
+ * {@link MOVE_THRESHOLD} so entry clicks still land).
+ */
+export type LegendHitZone = "none" | "body" | "move" | "scrollbar" | "resize-w" | "resize-e" | "resize-s" | "resize-se";
+/**
+ * Frame snapshot the legend painters hand back after painting: the
+ * panel's outer box, the scrollable content rect inside it, and the
+ * full (unclipped) content height. Hit-testing and wheel/drag routing
+ * all consult the LAST PAINTED geometry — between paints the on-screen
+ * pixels are exactly this snapshot, so events resolve against what the
+ * user actually sees.
+ */
+export interface PaintedLegend {
+    mode: "sidebar" | "floating";
+    box: PlotRect;
+    content: PlotRect;
+    contentHeight: number;
+    /**
+     * The resolved right-gutter width this frame (sidebar mode only).
+     * The width-drag applies its delta to this — NOT to `box.width`,
+     * which excludes the gutter's padding — so a drag that starts on
+     * an auto-width (config 0) legend continues from the family's
+     * legacy width without a jump.
+     */
+    sidebarGutter?: number;
+}
+/**
+ * Per-event services the worker renderer supplies. The controller is
+ * pure state — it never reaches into the chart or transport itself.
+ */
+export interface LegendEventCtx {
+    /**
+     * The chart's live plugin config. Drag gestures mutate the legend
+     * fields on this object directly (the worker-local copy), so the
+     * next paint lays out from the in-progress values; the persisted
+     * delta is posted once at pointerup.
+     */
+    cfg: PluginConfig;
+    cssWidth: number;
+    cssHeight: number;
+    /**
+     * Visible toggleable entry rects (series legends). A floating-panel
+     * click that lands on one passes through to the chart's own legend
+     * click handler instead of being consumed.
+     */
+    legendRects: ReadonlyArray<{
+        rect: PlotRect;
+    }>;
+    /**
+     * Schedule a repaint. `relayout: true` when the gesture changed the
+     * plot geometry (sidebar width) and a full GL pass is required;
+     * `false` for chrome-only changes (scroll, floating move/resize).
+     */
+    repaint(relayout: boolean): void;
+    /** Post a persisted config delta (pointerup, changed fields only). */
+    postDelta(fields: Partial<PluginConfig>): void;
+    setCursor(cursor: string): void;
+    /** Dismiss any active plot hover (cursor entered the legend). */
+    dispatchLeave(): void;
+}
+/**
+ * Single owner of legend interaction state: last-painted geometry,
+ * scroll offset, hover cursor, and the drag state machine. One
+ * instance per chart (`AbstractChart._legend`); the worker renderer
+ * consults {@link handleEvent} FIRST for every forwarded interaction
+ * event, so legend gestures structurally preempt plot zoom / pan /
+ * tooltip routing rather than racing them.
+ *
+ * The scroll offset is transient (never persisted); geometry fields
+ * (`legend_size_mode`, `legend_width_px`, `legend_height_px`,
+ * `legend_x`, `legend_y`) round-trip through `plugin_config`.
+ */
+export declare class LegendController {
+    private _painted;
+    private _scroll;
+    private _drag;
+    private _suppressClick;
+    private _hoverInside;
+    private _lastCursor;
+    /**
+     * Clamp and return the scroll offset for this frame. Painters call
+     * this before drawing the entry window so the offset is always
+     * valid against the CURRENT content/viewport pair (content can
+     * shrink between frames — data updates, panel resizes).
+     */
+    clampScroll(viewHeight: number, contentHeight: number): number;
+    /** Record this frame's painted geometry. */
+    setPainted(p: PaintedLegend): void;
+    /**
+     * Record that no legend was painted this frame (mode `"none"`, or
+     * no legend content). Kills every hit zone until the next paint.
+     */
+    clearPainted(): void;
+    /**
+     * Resolve the floating panel's outer box from config. Offsets are
+     * normalized to the free span and measured from the
+     * `legend_anchor` corner, so every `legend_x`/`legend_y` in [0, 1]
+     * yields a fully on-canvas box at any canvas size.
+     *
+     * `fit` drives `legend_size_mode: "auto"` (see {@link LegendAutoFit});
+     * omitting it in auto mode falls back to the fixed-mode defaults,
+     * so a call site that cannot measure still paints a sane panel. The
+     * canvas clamps apply to BOTH modes — an auto panel never grows
+     * past half the canvas width or its full height, it scrolls
+     * instead.
+     */
+    floatingBox(cfg: PluginConfig, cssWidth: number, cssHeight: number, fit?: LegendAutoFit): PlotRect;
+    /**
+     * Called by `setPluginConfig` BEFORE the incoming config replaces
+     * the current one. A restore whose legend fields EQUAL the current
+     * values is the persistence echo of a completed drag — a no-op
+     * here, so scroll and any in-flight gesture survive. Different
+     * values (the user typed in the settings form, or a restore raced
+     * in) win unconditionally: any in-flight drag is cancelled.
+     */
+    reconcileConfig(prev: PluginConfig, next: PluginConfig): void;
+    cancelGesture(): void;
+    /**
+     * Route one forwarded interaction event. Returns `true` when the
+     * event was consumed (the caller must not forward it to zoom /
+     * tooltip routing).
+     */
+    handleEvent(event: InteractionEvent, ctx: LegendEventCtx): boolean;
+    /** Classify a canvas-CSS-px point against the last painted legend. */
+    hitTest(mx: number, my: number): LegendHitZone;
+    private _scrollable;
+    private _inScrollbar;
+    private _onWheel;
+    private _onPointerDown;
+    private _onPointerMove;
+    private _onPointerUp;
+    private _onDblClick;
+    private _onClick;
+    private _applyDrag;
+    /**
+     * First write of a resize gesture on an auto-sized floating panel:
+     * switch it to `"fixed"`. Without this the gesture would be inert —
+     * the next paint recomputes the content size and discards it.
+     *
+     * BOTH dimensions are seeded from the box on screen, not just the
+     * dragged one: the saved `legend_width_px` / `legend_height_px` are
+     * whatever the panel had before it went auto, so adopting them
+     * wholesale would jump the edge the user is NOT dragging.
+     */
+    private _freezeAutoSize;
+    /** Bottom-edge resize: new height with the top edge held fixed. */
+    private _applySouthResize;
+    private _writeAnchoredPos;
+    private _setScroll;
+    private static _cursorFor;
+    private _setCursor;
+}

package/dist/esm/interaction/tooltip-controller.d.ts

@@ -1,9 +1,7 @@
 import type { Canvas2D } from "../charts/canvas-types";
 import type { PlotLayout } from "../layout/plot-layout";
 import type { Theme } from "../theme/theme";
-/**
- * Minimal positioning input — PlotLayout satisfies this.
- */
+import { type TooltipContent, type TooltipStyle } from "./tooltip-grid";
 export interface CssBounds {
     cssWidth: number;
     cssHeight: number;
@@ -11,7 +9,7 @@ export interface CssBounds {
 export interface TooltipCallbacks {
     /**
      * RAF-throttled mouse position in CSS pixels, relative to the GL
-     * canvas (host already subtracted `getBoundingClientRect`).
+     * canvas.
      */
     onHover(mx: number, my: number): void;
     /**
@@ -19,8 +17,7 @@ export interface TooltipCallbacks {
      */
     onLeave(): void;
     /**
-     * Fires on click with mouse position. Return true to consume the click
-     * (skipping the default pin/dismiss flow — used for legend clicks).
+     * Fires on click with mouse position.
      */
     onClickPre?(mx: number, my: number): boolean;
     /**
@@ -28,74 +25,33 @@ export interface TooltipCallbacks {
      */
     onPin?(mx: number, my: number): void;
     /**
-     * Fires on dblclick (treemap drill-up gesture). Optional — charts
-     * that don't bind a handler simply ignore the event.
+     * Fires on dblclick (treemap drill-up gesture).
      */
     onDblClick?(mx: number, my: number): void;
     /**
-     * Fires when an active pin is dismissed by a click on the
-     * already-pinned target (the "click again to unpin" gesture in
-     * `dispatchClick`). Chart impls hook this to emit a
-     * `perspective-global-filter` with `selected: false`. Does *not*
-     * fire on the implicit dismiss inside `pin()` that replaces an
-     * existing pin — that path is followed by a fresh `onPin` which
-     * emits its own `selected: true`.
+     * Fires when an active pin is dismissed by a click.
      */
     onUnpin?(): void;
 }
 export interface RenderTooltipOptions {
-    /**
-     * Draw a dashed crosshair at `pos`. Used by scatter/line.
-     */
     crosshair?: boolean;
-    /**
-     * Draw a ring of `radius` CSS pixels at `pos`. Used to highlight a
-     * hovered point. Omit for bars (where the bar itself highlights).
-     */
     highlightRadius?: number;
+    maxColumnPx?: number;
+    opacity?: number;
 }
 /**
- * Side-channel from the chart back to the host's DOM. The chart calls
- * into a sink rather than touching the DOM itself; the host
- * materializes the actual visual (`<div>` for pinned tooltip, cursor
- * mutation on the GL canvas).
- *
- *   - `MessageHostSink` (in worker/) — forwards calls over a
- *                              `postMessage`-shaped channel back to
- *                              the host.
- *   - `DomHostSink` (in host transport) — receives the matching
- *                              envelopes and applies them to the DOM.
- *
- * The controller's `_pinned` flag is the source of truth for whether
- * hover updates are gated; the sink only owns the visual artifact.
+ * Side-channel from the chart back to the host's DOM.
  */
 export interface HostSink {
-    pin(lines: string[], pos: {
+    pin(grid: TooltipContent, pos: {
         px: number;
         py: number;
-    }, bounds: CssBounds): void;
+    }, bounds: CssBounds, style?: TooltipStyle): void;
     dismiss(): void;
     setCursor(cursor: string): void;
-    /**
-     * Forward a `perspective-click` to the host. Optional — only the
-     * worker-bound `MessageHostSink` implements it; `DomHostSink` (the
-     * host-side consumer of pin/dismiss) never sees user-event calls,
-     * so omits the implementation.
-     */
     emitUserClick?(detail: UserClickPayload): void;
-    /**
-     * Forward a `perspective-global-filter` to the host with the
-     * `selected: true` / `selected: false` semantics. The host owns the
-     * `removeConfigs` history (mirrors datagrid's
-     * `model._last_insert_configs`); the sink only ships the new state.
-     */
     emitUserSelect?(payload: UserSelectPayload): void;
 }
-/**
- * Plain-object payload for `HostSink.emitUserClick`. Matches
- * `PerspectiveClickDetail` byte-for-byte; defined locally to avoid a
- * cycle through `event-detail.ts`.
- */
 export interface UserClickPayload {
     row: Record<string, unknown>;
     column_names: string[];
@@ -103,11 +59,6 @@ export interface UserClickPayload {
         filter?: unknown[];
     };
 }
-/**
- * Plain-object payload for `HostSink.emitUserSelect`. The host
- * transport reconstructs a `PerspectiveSelectDetail` class instance
- * from this plus its cached `_lastInsertConfig`.
- */
 export interface UserSelectPayload {
     selected: boolean;
     row: Record<string, unknown>;
@@ -118,13 +69,7 @@ export interface UserSelectPayload {
 }
 /**
  * Owns the hover/click/dblclick state machine and the pinned-tooltip
- * lifecycle. The renderer drives this purely through
- * `dispatchHover` / `dispatchLeave` / `dispatchClick` /
- * `dispatchDblClick` — the host's `RawEventForwarder` captures DOM
- * events on the GL canvas and posts them as `InteractionEvent`s.
- *
- * Pinning + cursor changes go through a {@link HostSink} so the actual
- * DOM mutations happen host-side regardless of where the chart runs.
+ * lifecycle.
  */
 export declare class TooltipController {
     private _callbacks;
@@ -134,60 +79,40 @@ export declare class TooltipController {
     private _pinned;
     get isPinned(): boolean;
     /**
-     * Replace the active host sink. Dismisses any existing pin via the
-     * prior sink so we never leak a pinned artifact across resets —
-     * though in practice each chart instance uses one sink for its
-     * lifetime.
+     * Replace the active host sink.
      */
     setHost(sink: HostSink): void;
     /**
-     * Forward a cursor change to the host. No-op when no host sink is
-     * installed (chart constructed without a transport).
+     * Forward a cursor change to the host.
      */
     setCursor(cursor: string): void;
     /**
-     * Install the chart's tooltip callbacks. The renderer drives the
-     * controller via `dispatchHover` / `dispatchLeave` /
-     * `dispatchClick` / `dispatchDblClick`; this controller never
-     * touches the DOM directly.
+     * Install the chart's tooltip callbacks.
      */
     attach(callbacks: TooltipCallbacks): void;
     detach(): void;
     /**
      * Schedule an `onHover` callback for the given canvas-relative
-     * coords. Coalesces multiple calls within one animation frame so
-     * pointer streams don't backlog the chart's hit-test path.
-     *
-     * Workers ship with `requestAnimationFrame` (DedicatedWorkerGlobalScope
-     * exposes it for OffscreenCanvas painting), so the same coalescer
-     * works in both modes. We fall back to setTimeout if RAF is missing
-     * (e.g. node tests without a polyfill).
+     * coords.
      */
     dispatchHover(mx: number, my: number): void;
     dispatchLeave(): void;
     dispatchClick(mx: number, my: number): void;
     dispatchDblClick(mx: number, my: number): void;
     /**
-     * Pin a tooltip (or replace an active one). Forwards through the
-     * configured sink and flips the controller's pinned flag so hover
-     * dispatch is suppressed until dismissal.
+     * Pin a tooltip (or replace an active one).
      */
-    pin(lines: string[], pos: {
+    pin(grid: TooltipContent, pos: {
         px: number;
         py: number;
-    }, bounds: CssBounds): void;
+    }, bounds: CssBounds, style?: TooltipStyle): void;
     dismiss(): void;
 }
 /**
  * Paint a canvas tooltip (crosshair, highlight ring, box + text) onto
- * `canvas`. The helper normalizes the 2D context to a DPR-scaled
- * identity transform on entry and restores prior state on exit, so it
- * composes cleanly with other chrome painters that may have already
- * called `initCanvas` on the same canvas — re-applying `scale(dpr,dpr)`
- * blind would double-scale in that case, misplacing the tooltip
- * proportionally to its distance from the origin.
+ * `canvas`.
  */
 export declare function renderCanvasTooltip(canvas: Canvas2D | null, pos: {
     px: number;
     py: number;
-}, lines: string[], layout: PlotLayout, theme: Theme, dpr: number, options?: RenderTooltipOptions): void;
+}, grid: TooltipContent, layout: PlotLayout, theme: Theme, dpr: number, options?: RenderTooltipOptions): void;

package/dist/esm/interaction/tooltip-grid.d.ts

@@ -0,0 +1,33 @@
+import type { Context2D } from "../charts/canvas-types";
+import type { Theme } from "../theme/theme";
+export type TooltipRow = string[];
+export type TooltipContent = TooltipRow[];
+export interface TooltipStyle {
+    opacity: number;
+    maxColumnPx: number;
+}
+export declare const DEFAULT_TOOLTIP_STYLE: TooltipStyle;
+export declare function tooltipStyleOf(cfg: {
+    tooltip_opacity: number;
+    tooltip_max_column_px: number;
+}): TooltipStyle;
+export declare const NUMERIC_RE: RegExp;
+export declare const TOOLTIP_ROW_HEIGHT = 16;
+export declare const TOOLTIP_PADDING = 8;
+export declare const TOOLTIP_COL_GAP = 8;
+export interface MeasuredTooltipGrid {
+    rows: string[][];
+    colWidths: number[];
+    colRightAlign: boolean[];
+    boxW: number;
+    boxH: number;
+}
+/**
+ * Measure a tooltip grid under the current `ctx.font`.
+ */
+export declare function measureTooltipGrid(ctx: Context2D, grid: TooltipContent, maxColumnPx: number): MeasuredTooltipGrid;
+/**
+ * Paint a measured tooltip grid at `(tx, ty)`.
+ */
+export declare function paintTooltipGrid(ctx: Context2D, measured: MeasuredTooltipGrid, tx: number, ty: number, theme: Theme, opacity: number): void;
+export declare function ellipsize(ctx: Context2D, text: string, maxW: number): string;

package/dist/esm/layout/facet-grid.d.ts

@@ -32,6 +32,12 @@ export interface FacetGridOptions {
      * Reserve a right gutter for a single shared legend.
      */
     hasLegend?: boolean;
+    /**
+     * Width of the legend gutter when `hasLegend` is set. Defaults to
+     * the historical `LEGEND_GUTTER` (96). Callers resolve this from
+     * `plugin_config.legend_width_px` via `legendSidebarWidth`.
+     */
+    legendWidth?: number;
     /** Axis-label allowance (consumed only when the corresponding axis
      *  mode produces a gutter — outer band or per-cell). */
     hasXLabel?: boolean;

package/dist/esm/layout/ticks.d.ts

@@ -5,6 +5,7 @@
  * @param targetCount - Desired number of ticks (approximate)
  */
 export declare function computeNiceTicks(min: number, max: number, targetCount: number): number[];
+export declare function stepTickFormatter(isDate: boolean | undefined, ticks: number[] | null | undefined): (v: number) => string;
 /**
  * Format a numeric tick value for display.
  * Uses K/M/B suffixes for large numbers, fixed decimals for small.

package/dist/esm/map/tile-source.d.ts

@@ -53,14 +53,83 @@ export declare class TemplatedTileSource implements TileSource {
     urlFor(z: number, x: number, y: number): string;
 }
 /**
- * Identifier of the default tile providers shipped with `viewer-charts`.
- * Surfaced as the `map_tile_provider` PluginConfig enum so users can
- * pick light vs. dark vs. labels-only without writing a custom source.
+ * Declarative description of one raster XYZ tile provider — the shape
+ * of an entry in [tile-sources.json] and of the argument to
+ * `registerTileSource`. Everything the renderer needs to construct a
+ * concrete {@link TileSource} lives here; the TypeScript is generic
+ * over these entries and hardcodes no provider URLs.
  */
-export type TileProviderId = "carto-positron" | "carto-dark-matter" | "carto-voyager";
+export interface TileSourceSpec {
+    /** Registry key; the persisted `map_tile_provider` value. */
+    readonly id: string;
+    /** Human-readable enum-variant label on the settings panel. */
+    readonly label: string;
+    /**
+     * URL template with `{z}`/`{x}`/`{y}` placeholders and optional
+     * `{s}` subdomain rotation. A provider that needs an API key
+     * embeds it directly in the template it registers — keys never
+     * pass through `plugin_config`, so they never appear in `save()`
+     * output.
+     */
+    readonly template: string;
+    /** `{s}` rotation pool; required non-empty iff `template` has `{s}`. */
+    readonly subdomains: readonly string[];
+    /** See {@link TileSource.attribution}. */
+    readonly attribution: string;
+    /** See {@link TileSource.tileSize}. Default 256. */
+    readonly tile_size: number;
+    /** See {@link TileSource.maxZoom}. Default 19. */
+    readonly max_zoom: number;
+}
+/**
+ * Validate + normalize an untrusted spec (a JSON entry or a
+ * `registerTileSource` argument). Throws `TypeError` naming the
+ * offending field; returns a frozen spec with defaults applied.
+ */
+export declare function parseTileSourceSpec(input: unknown): TileSourceSpec;
+/**
+ * The set of known tile providers: the bundled entries from
+ * [tile-sources.json] plus any registered at runtime via
+ * `registerTileSource`. One instance exists per JS realm ({@link
+ * TILE_SOURCES}) — the plugin realm's is the source of truth for the
+ * settings-panel enum; the worker realm's resolves ids at render time.
+ * The realms need no eager mirroring: every `setPluginConfig` / `init`
+ * control message carries the resolved spec for the config's
+ * `map_tile_provider` alongside the config itself, so a worker can
+ * never hold a config whose spec it lacks.
+ */
+export declare class TileSourceRegistry {
+    private _specs;
+    constructor(seed: readonly unknown[]);
+    /**
+     * Add (or replace, by id) a provider. Validates via
+     * {@link parseTileSourceSpec} and returns the normalized spec.
+     * Replacement is safe for live charts: the cache identity below is
+     * content-derived, so a changed template yields a new cache key
+     * and the tile layer drops its stale textures on next bind.
+     */
+    register(input: unknown): TileSourceSpec;
+    /** Every known spec, bundled first, in insertion order. */
+    list(): readonly TileSourceSpec[];
+    /** The spec registered under `id`, or `undefined` if unknown. */
+    specFor(id: string): TileSourceSpec | undefined;
+    /**
+     * Resolve a `map_tile_provider` id to a concrete `TileSource`.
+     * Unknown ids fall back to the first bundled entry so a
+     * misconfigured `plugin_config` never produces a blank map — and
+     * so a config restored *before* its custom source is registered
+     * degrades to the default basemap until the next config forward
+     * carries the registered spec.
+     */
+    sourceFor(id: string): TileSource;
+}
+/**
+ * Realm-wide provider registry, seeded from [tile-sources.json]. A
+ * malformed bundled entry fails loudly here, at first import.
+ */
+export declare const TILE_SOURCES: TileSourceRegistry;
 /**
- * Resolve a `TileProviderId` (from PluginConfig) to a concrete
- * `TileSource`. Unknown ids fall back to Positron so a misconfigured
- * `_pluginConfig` never produces a blank map.
+ * Read-only listing of every known tile provider (bundled + runtime-
+ * registered), in settings-panel enum order. Public package export.
  */
-export declare function tileSourceFor(id: TileProviderId | string): TileSource;
+export declare function tileSources(): readonly TileSourceSpec[];