histropediajs 1.5.0 → 1.6.0

package/index.d.ts

@@ -1,1718 +1,1883 @@
-// Type definitions for HistropediaJS – public API only
-
-// ------------------------------------------------------------------------------------
-// Helpers
-// ------------------------------------------------------------------------------------
-
-/**
- * Deeply partial helper for ergonomic option updates.
- *
- * Notes:
- * - Functions are left as-is (not recursed).
- * - Arrays/tuples are treated as replace-whole values (not recursed).
- */
-export type DeepPartial<T> = T extends (...args: any) => any
-  ? T
-  : T extends readonly any[]
-    ? T
-    : T extends object
-      ? { [K in keyof T]?: DeepPartial<T[K]> }
-      : T;
-
-/** Built-in card layouts stay in autocomplete while custom registered names still type-check. */
-export type CardLayoutName = 'portrait' | 'landscape' | (string & {});
-
-/** Runtime visibility state used by lanes and time bands. */
-export type VisibilityState = 'visible' | 'hidden';
-
-/** Canvas-relative 2D position used by rendered articles. */
-export interface CanvasPosition {
-  left: number;
-  top: number;
-}
-
-/** Main-line indicator coordinates for an article currently in range. */
-export interface ArticleIndicator {
-  fromX: number;
-  toX: number;
-}
-
-/** Computed article time span after precision expansion. */
-export interface ArticlePeriod {
-  from: DmyInstance;
-  to: DmyInstance;
-  isToPresent: boolean;
-  /** Approximate duration in decimal years, used for sorting/layout decisions. */
-  years: number;
-}
-
-/** Computed time-band span after precision expansion. */
-export interface TimeBandPeriod {
-  from: DmyInstance;
-  to: DmyInstance;
-  isToPresent: boolean;
-}
-
-/** Hit area metadata returned by card layouts when the star icon is visible. */
-export interface CardLayoutIconBox extends CanvasPosition {
-  width: number;
-  height: number;
-  centreX: number;
-  centreY: number;
-  innerRadius: number;
-  outerRadius: number;
-}
-
-// ------------------------------------------------------------------------------------
-// Date and precision
-// ------------------------------------------------------------------------------------
-
-/** Date precision constants (public). */
-export const PRECISION_DAY: 'day';
-export const PRECISION_MONTH: 'month';
-export const PRECISION_YEAR: 'year';
-export const PRECISION_DECADE: 'decade';
-export const PRECISION_CENTURY: 'century';
-export const PRECISION_MILLENNIUM: 'millennium';
-export const PRECISION_MILLION_YEARS: 'million-years';
-export const PRECISION_BILLION_YEARS: 'billion-years';
-
-/** @deprecated Use the equivalent string precision instead. */
-export type LegacyPrecision = 11 | 10 | 9 | 8 | 7 | 6 | 3 | 1;
-
-/**
- * Date precision used by Article/TimeBand ranges.
- * Legacy numeric precision values remain supported for backwards compatibility.
- */
-export type Precision =
-  | typeof PRECISION_DAY
-  | typeof PRECISION_MONTH
-  | typeof PRECISION_YEAR
-  | typeof PRECISION_DECADE
-  | typeof PRECISION_CENTURY
-  | typeof PRECISION_MILLENNIUM
-  | typeof PRECISION_MILLION_YEARS
-  | typeof PRECISION_BILLION_YEARS
-  | LegacyPrecision;
-
-/** Plain YMD date parts (no precision). */
-export type DateParts = {
-  year: number;
-  month?: number;
-  day?: number;
-};
-
-/** General date input that can include precision. */
-export type DateInput = DateParts & { precision?: Precision };
-
-/** Internal date input shape (consumer-friendly). */
-export interface Dmy {
-  year: number;
-  month?: number;
-  day?: number;
-  precision?: Precision;
-}
-
-/** Formatting options for Dmy.format. */
-export interface DmyFormatOptions {
-  yearPrefix?: { value?: number; label?: string };
-  bceText?: string;
-  thousandsSeparator?: string;
-}
-
-/** Histropedia date helper instance. */
-export interface DmyInstance extends Dmy {
-  getDaysTo(other: Dmy): number;
-  getMonthsTo(other: Dmy): number;
-  getYearsTo(other: Dmy): number;
-  getLeapYearsSinceYearZero(): number;
-  getDaysSinceYearZero(): number;
-  getDayOfYear(): number;
-  getNextDay(): DmyInstance;
-  addDays(amount: number): DmyInstance;
-  addMonths(amount: number): DmyInstance;
-  addYears(amount: number): DmyInstance;
-  getPreviousDay(): DmyInstance;
-  getNextMonth(): DmyInstance;
-  getPreviousMonth(): DmyInstance;
-  format(format?: string, options?: DmyFormatOptions): string;
-  isSame(other: Dmy): boolean;
-  isAfter(other: Dmy): boolean;
-  isBetween(from: Dmy, to: Dmy): boolean;
-  compare(other: Dmy): number;
-  toKeyString(): string;
-  asFloat(): number;
-  isInFuture(): boolean;
-  convertToIso(): DmyInstance;
-}
-
-export type FitDateRangeInput = DmyInstance | DateParts;
-
-export interface DmyConstructor {
-  new (year: number, month?: number, day?: number): DmyInstance;
-  new (value: Dmy): DmyInstance;
-  readonly prototype: DmyInstance;
-  getByDayOfYear(year: number, dayOfYear: number): DmyInstance;
-  CreateAsStartOfPeriod(date: Dmy, precision?: Precision): DmyInstance;
-  CreateAsEndOfPeriod(date: Dmy, precision?: Precision): DmyInstance;
-  now(): DmyInstance;
-  fromString(dateString: string): DmyInstance;
-}
-
-export const Dmy: DmyConstructor;
-
-// ------------------------------------------------------------------------------------
-// Public constants (used in options)
-// ------------------------------------------------------------------------------------
-
-export const DENSITY_ALL: 'all';
-export const DENSITY_LOW: 'low';
-export const DENSITY_MEDIUM: 'medium';
-export const DENSITY_HIGH: 'high';
-/** @deprecated Use the equivalent string density instead. */
-export type LegacyDensity = 0 | 1 | 2 | 3;
-export type Density =
-  | typeof DENSITY_ALL
-  | typeof DENSITY_LOW
-  | typeof DENSITY_MEDIUM
-  | typeof DENSITY_HIGH
-  | LegacyDensity;
-
-export const RANGE_ALL: 'all';
-export const RANGE_SCREEN: 'screen';
-/** @deprecated Use the equivalent string auto-stacking range instead. */
-export type LegacyAutoStackRange = 0 | 1;
-export type AutoStackRange = typeof RANGE_ALL | typeof RANGE_SCREEN | LegacyAutoStackRange;
-
-export const MINOR_MARKER: 0;
-export const MAJOR_MARKER: 1;
-export const ERA_MARKER: 2;
-export type MarkerType = typeof MINOR_MARKER | typeof MAJOR_MARKER | typeof ERA_MARKER;
-
-export const ZOOM_DAY: 0;
-export const ZOOM_MONTH: 1;
-export const ZOOM_YEAR: 2;
-export const ZOOM_DECADE: 3;
-export const ZOOM_CENTURY: 4;
-export const ZOOM_MILLENNIUM: 5;
-export const ZOOM_10_THOUSAND_YEARS: 6;
-export const ZOOM_100_THOUSAND_YEARS: 7;
-export const ZOOM_MILLION_YEARS: 8;
-export const ZOOM_10_MILLION_YEARS: 9;
-export const ZOOM_100_MILLION_YEARS: 10;
-export const ZOOM_BILLION_YEARS: 11;
-export type ZoomLevel =
-  | typeof ZOOM_DAY
-  | typeof ZOOM_MONTH
-  | typeof ZOOM_YEAR
-  | typeof ZOOM_DECADE
-  | typeof ZOOM_CENTURY
-  | typeof ZOOM_MILLENNIUM
-  | typeof ZOOM_10_THOUSAND_YEARS
-  | typeof ZOOM_100_THOUSAND_YEARS
-  | typeof ZOOM_MILLION_YEARS
-  | typeof ZOOM_10_MILLION_YEARS
-  | typeof ZOOM_100_MILLION_YEARS
-  | typeof ZOOM_BILLION_YEARS;
-
-export interface YearPrefixSettings {
-  label: string;
-  value: number;
-}
-
-export const YEAR_PREFIXES: Readonly<Record<number, YearPrefixSettings>>;
-
-export interface DensitySetting {
-  region: number;
-  zoom: {
-    from: number;
-    to: number;
-  };
-  low: number;
-  medium: number;
-  high: number;
-  all: number;
-  step: {
-    months: number;
-    days: number;
-  };
-}
-
-export const DENSITY_SETTINGS: readonly DensitySetting[];
-
-export interface LoggerInstance {
-  setEnabled(enabled: boolean): void;
-  isEnabled(): boolean;
-  setPrefix(prefix: string): void;
-  getPrefix(): string;
-  log(...args: unknown[]): void;
-  warn(...args: unknown[]): void;
-  error(...args: unknown[]): void;
-  info(...args: unknown[]): void;
-  debug(...args: unknown[]): void;
-  group(...args: unknown[]): void;
-  groupCollapsed(...args: unknown[]): void;
-  groupEnd(): void;
-}
-
-export const Logger: LoggerInstance;
-
-// ------------------------------------------------------------------------------------
-// Animation types
-// ------------------------------------------------------------------------------------
-
-/** Allowed easing names used by animations. */
-export type EasingName =
-  | 'linear'
-  | 'swing'
-  | 'easeInQuad'
-  | 'easeOutQuad'
-  | 'easeInOutQuad'
-  | 'easeInCubic'
-  | 'easeOutCubic'
-  | 'easeInOutCubic';
-
-// ------------------------------------------------------------------------------------
-// Style types
-// ------------------------------------------------------------------------------------
-
-export interface ArticleStyleText {
-  font?: string;
-  color?: string;
-  align?: 'left' | 'right' | 'center' | 'start' | 'end';
-  baseline?: 'top' | 'middle' | 'alphabetic' | 'bottom';
-  margin?: number;
-  lineHeight?: number;
-  numberOfLines?: number;
-  offsetY?: number;
-}
-
-export interface ArticleStyle {
-  /** @defaultValue 150 */
-  width?: number;
-  /** Landscape card layout only. @defaultValue 70 */
-  height?: number;
-  /** Card background fill color. @defaultValue '#e9e9e9' */
-  color?: string;
-  /** Inner card background. @defaultValue '#fff' */
-  backgroundColor?: string;
-  /** Portrait card layout only. @defaultValue 3 */
-  topRadius?: number;
-  /** Landscape card layout only. @defaultValue 4 */
-  borderRadius?: number;
-  /**
-   * Shorthand for the article image maximum height.
-   *
-   * @deprecated Deprecated since 1.3.0 — Use `image.maxHeight` instead.
-   * @defaultValue 400
-   */
-  maxImageHeight?: number;
-  image?: {
-    /** @defaultValue 'natural' */
-    shape?: 'natural' | 'square' | 'circle';
-    /** @defaultValue 0 */
-    margin?: number;
-    /** @defaultValue 400 */
-    maxHeight?: number;
-    /** @defaultValue 0 */
-    borderRadius?: number;
-  };
-  header?: {
-    /** Portrait card layout only. @defaultValue 50 */
-    height?: number;
-    text?: ArticleStyleText;
-  };
-  subheader?: {
-    /** Portrait card layout only. @defaultValue 30 */
-    height?: number;
-    /** Portrait card layout only. @defaultValue '#555' */
-    color?: string;
-    text?: ArticleStyleText;
-  };
-  shadow?: {
-    /** @defaultValue 0 */ x?: number;
-    /** @defaultValue 0 */ y?: number;
-    /** @defaultValue 0 */ amount?: number;
-    /** @defaultValue '#000' */ color?: string;
-  };
-  border?: {
-    /** @defaultValue '#ddd' */ color?: string;
-    /** @defaultValue 1 */ width?: number;
-  };
-  connectorLine?: {
-    /** @defaultValue true */ visible?: boolean;
-    /** @defaultValue 18 */ offsetX?: number;
-    /** @defaultValue -20 */ offsetY?: number;
-    /** @defaultValue 1 */ thickness?: number;
-    arrow?: {
-      /** @defaultValue 16 */ width?: number;
-      /** @defaultValue 45 */ height?: number;
-    };
-  };
-  star?: {
-    /** @defaultValue 16 */ width?: number;
-    /** @defaultValue 3 */ margin?: number;
-  };
-}
-
-export interface TimeBandStyleText {
-  font?: string;
-  color?: string;
-  align?: 'left' | 'right' | 'center' | 'start' | 'end';
-  baseline?: 'top' | 'middle' | 'alphabetic' | 'bottom';
-  /** Vertical align inside band area. */
-  verticalAlign?: 'top' | 'middle' | 'bottom';
-  /** Horizontal/vertical padding in px. @defaultValue 4 */
-  margin?: number;
-  /** Extra vertical offset in px. @defaultValue 0 */
-  offsetY?: number;
-}
-
-export interface TimeBandStyle {
-  /** @defaultValue 'rgba(200, 200, 200, 0.25)' */
-  backgroundColor?: string;
-  border?: { color?: string; width?: number };
-  text?: TimeBandStyleText;
-}
-
-export interface TimelineStyleMarkerKind {
-  /** @defaultValue 12 (minor) / 30 (major) */ height?: number;
-  /** Extend marker to canvas top/bottom. @defaultValue false */ extend?: boolean;
-  color?: string;
-  futureColor?: string;
-}
-
-export interface TimelineStyleOptions {
-  mainLine?: {
-    /** @defaultValue true */ visible?: boolean;
-    /** @defaultValue 'bottom' */ position?: 'top' | 'bottom';
-    /** thickness in px. @defaultValue 8 */ size?: number;
-    /** Draw small article position ticks. @defaultValue true */
-    showDateIndicators?: boolean;
-  };
-  draggingHighlight?: {
-    /** @defaultValue true */ visible?: boolean;
-    /** @defaultValue 'rgba(237, 247, 255, 0.5)' */ color?: string;
-    /** Up/down extents relative to the main line. Accepts px, `'edge'`, or `{ value: 'edge', padding?: number }`.
-     * @defaultValue {up: 0, down: 'edge'}
-     */
-    area?: { up?: AreaValue; down?: AreaValue };
-  };
-  marker?: {
-    minor?: TimelineStyleMarkerKind;
-    major?: TimelineStyleMarkerKind;
-  };
-  dateLabel?: {
-    minor?: {
-      font?: string;
-      color?: string;
-      futureColor?: string;
-      textAlign?: CanvasTextAlign;
-      offset?: { x?: number; y?: number };
-      /** Text appended for BCE labeling. */
-      bceText?: string;
-      /** Thousands separator for large year labels. */
-      thousandsSeparator?: string;
-      /** Map of year-scale prefixes to display (e.g. ka, Ma, Ga). */
-      yearPrefixes?: Record<string, { label: string; value: number; minDivision: number }>;
-    };
-    major?: {
-      font?: string;
-      color?: string;
-      futureColor?: string;
-      textAlign?: CanvasTextAlign;
-      offset?: { x?: number; y?: number };
-      bceText?: string;
-      thousandsSeparator?: string;
-      yearPrefixes?: Record<string, { label: string; value: number; minDivision: number }>;
-    };
-  };
-  cursor?: {
-    clickable?: string;
-    timeline?: { hover?: string; dragging?: string };
-    article?: { hoverDraggable?: string; dragging?: string };
-  };
-}
-
-// ------------------------------------------------------------------------------------
-// Data schemas for loading
-// ------------------------------------------------------------------------------------
-
-export interface ArticleData {
-  id: string | number;
-  title: string;
-  subtitle?: string;
-  lane?: string | number;
-  from: DateInput;
-  to?: DateInput;
-  /** If true, the period ends at the present day. */
-  isToPresent?: boolean;
-  imageUrl?: string;
-  rank?: number;
-  starred?: boolean;
-  hiddenByFilter?: boolean | ((article: Article) => boolean);
-  hidePeriodLine?: boolean | ((article: Article) => boolean);
-  /** Initial offset from computed position (px). */
-  offsetLeft?: number;
-  /** Initial offset from computed position (px). */
-  offsetTop?: number;
-  /** Override default card layout for this article. */
-  cardLayout?: CardLayoutName;
-  style?: ArticleStyle;
-  hoverStyle?: ArticleStyle;
-  activeStyle?: ArticleStyle;
-}
-
-export interface ArticleCardLayoutBreakpoint {
-  maxHeight: number;
-  layout: CardLayoutName;
-}
-
-export interface TimeBandData {
-  id: string | number;
-  title: string;
-  from: DateInput;
-  to?: DateInput;
-  /** If true, the band ends at the present day. */
-  isToPresent?: boolean;
-  /** Visibility of this band: 'visible' | 'hidden' or a function returning one. Defaults to 'visible'. */
-  visibility?: VisibilityState | ((band: TimeBand) => VisibilityState);
-  style?: TimeBandStyle;
-}
-
-export type ChartType = 'line' | 'area';
-export type ChartScaleSource = 'data' | 'viewport';
-export type ChartScaleTickMode = 'round' | 'exact';
-export type ChartAreaStackingInterpolation = 'linear' | 'step' | 'none';
-
-export interface ChartPointData {
-  date: DateInput;
-  value: number | null;
-}
-
-export interface ChartSeriesStyle {
-  color?: string;
-  lineWidth?: number;
-  lineDash?: number[];
-  area?: {
-    fillColor?: string | null;
-    opacity?: number;
-  };
-  point?: {
-    visible?: boolean;
-    radius?: number;
-    fillColor?: string | null;
-    strokeColor?: string | null;
-    lineWidth?: number;
-  };
-}
-
-export interface ChartGridLineStyle {
-  visible?: boolean;
-  color?: string;
-  /** Stroke thickness in canvas pixels. */
-  thickness?: number;
-}
-
-export interface ChartMinorGridLineStyle extends ChartGridLineStyle {
-  /** Hide minor grid lines while the timeline minor unit size is below this many pixels. @defaultValue 40 */
-  minimumSpacing?: number;
-}
-
-export interface ChartGridLineOptions {
-  x?: {
-    major?: ChartGridLineStyle;
-    minor?: ChartMinorGridLineStyle;
-  };
-  y?: {
-    major?: ChartGridLineStyle;
-  };
-}
-
-export interface ChartStyle {
-  padding?: {
-    top?: number;
-    right?: number;
-    bottom?: number;
-    left?: number;
-  };
-  backgroundColor?: string;
-  gridLine?: ChartGridLineOptions;
-  axis?: {
-    visible?: boolean;
-    color?: string;
-    lineWidth?: number;
-  };
-  yAxis?: {
-    visible?: boolean;
-    font?: string;
-    color?: string;
-    margin?: number;
-    /** Thousands separator for numeric y-axis labels. Set to null or an empty string to disable. @defaultValue ',' */
-    thousandsSeparator?: string | null;
-    formatter?: ((value: number) => string) | null;
-  };
-  legend?: {
-    visible?: boolean | 'auto';
-    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
-    font?: string;
-    color?: string;
-    markerSize?: number;
-    markerGap?: number;
-    itemGap?: number;
-    inset?: { x?: number; y?: number };
-  };
-  series?: ChartSeriesStyle;
-}
-
-export interface ChartScaleOptions {
-  /** Use all loaded values or only values inside the current viewport. @defaultValue 'data' */
-  source?: ChartScaleSource;
-  /** Include 0 in the computed domain before padding/fixed bounds. @defaultValue false */
-  includeZero?: boolean;
-  /** Fractional padding applied to auto domains. @defaultValue 0.05 */
-  padding?: number;
-  /** Fixed minimum y value. */
-  min?: number;
-  /** Fixed maximum y value. */
-  max?: number;
-  /** Controls how y-axis tick values are generated. @defaultValue 'round' */
-  tickMode?: ChartScaleTickMode;
-  /** Preferred number of y-axis ticks. Rounded ticks may vary slightly. @defaultValue 5 */
-  tickTarget?: number;
-}
-
-export interface ChartTypeOptions {
-  area?: {
-    stacking?: {
-      /** Enable stacked area rendering. When false, area series fill independently from zero. @defaultValue true */
-      active?: boolean;
-      /** How missing series values are resolved across the shared area x-domain. @defaultValue 'linear' */
-      interpolation?: ChartAreaStackingInterpolation;
-    };
-  };
-}
-
-export interface ChartSeriesData {
-  id?: string | number;
-  title?: string;
-  points?: ChartPointData[];
-  style?: ChartSeriesStyle;
-}
-
-export interface ChartData {
-  id: string | number;
-  type?: ChartType;
-  title?: string;
-  lane?: string | number;
-  visibility?: VisibilityState | ((chart: Chart) => VisibilityState);
-  series?: ChartSeriesData[];
-  scale?: ChartScaleOptions;
-  typeOptions?: ChartTypeOptions;
-  area?: { up?: AreaValue; down?: AreaValue };
-  style?: ChartStyle;
-}
-
-export interface LaneLayout {
-  height?: number;
-  /**
-   * Relative share of the remaining automatic lane height for lanes without a fixed `height`.
-   * Hidden lanes are excluded from the distribution.
-   *
-   * @defaultValue 1
-   */
-  heightWeight?: number;
-  header?: {
-    visible?: boolean;
-    height?: number;
-    padding?: { left?: number; right?: number };
-  };
-}
-
-/** Decorative lane chrome styles. Only explicitly provided values are written inline. */
-export interface LaneStyle {
-  header?: {
-    backgroundColor?: string;
-  };
-  body?: {
-    backgroundColor?: string;
-    borderColor?: string;
-    borderWidth?: number;
-    borderRadius?: number;
-  };
-  title?: {
-    color?: string;
-    font?: string;
-    textAlign?: 'left' | 'center' | 'right';
-  };
-}
-
-export interface DistanceToBaselineResponsiveCardLayoutOptions {
-  /** Fraction of the available content height used to calculate the baseline distance. */
-  ratio?: number;
-  /** Minimum responsive baseline distance in px. */
-  min?: number;
-  /** Maximum responsive baseline distance in px. */
-  max?: number;
-}
-
-export interface DistanceToBaselineResponsiveOptions {
-  /** Enable responsive baseline distance calculations. @defaultValue true */
-  active?: boolean;
-  /**
-   * Restrict responsive baseline calculations to lanes only.
-   * When true, timelines without active lanes use the static `distanceToBaseline.value`.
-   *
-   * @defaultValue true
-   */
-  lanesOnly?: boolean;
-  /**
-   * Responsive baseline settings keyed by the resolved default card layout name.
-   *
-   * @defaultValue `{ portrait: { ratio: 0.75, min: 140, max: 350 }, landscape: { ratio: 0.45, min: 50, max: 160 } }`
-   */
-  byCardLayout?: Partial<Record<CardLayoutName, DistanceToBaselineResponsiveCardLayoutOptions>>;
-}
-
-export interface DistanceToBaselineOptions {
-  /**
-   * Distance of cards from their baseline in px:
-   * the shared timeline axis without lanes, or the lane bottom with lanes.
-   *
-   * @defaultValue 350
-   */
-  value?: number;
-  /** Responsive baseline distance settings. */
-  responsive?: DistanceToBaselineResponsiveOptions;
-}
-
-export interface LaneArticleOverrides {
-  defaultData?: Partial<ArticleData>;
-  /** Lane-local density grouping/filtering input. */
-  density?: ArticleOptions['density'];
-  defaultCardLayout?: CardLayoutName;
-  defaultStyle?: ArticleStyle;
-  defaultHoverStyle?: ArticleStyle;
-  defaultActiveStyle?: ArticleStyle;
-  layoutStyles?: ArticleOptions['layoutStyles'];
-  /** Distance of cards from this lane's baseline in px, plus responsive settings for this lane. */
-  distanceToBaseline?: DistanceToBaselineOptions;
-  /**
-   * @deprecated Deprecated since 1.3.4 — Use `distanceToBaseline.value` instead.
-   */
-  distanceToMainLine?: number;
-  autoStacking?: {
-    /** Enable or disable automatic row assignment for this lane. */
-    active?: boolean;
-    rowSpacing?: number;
-    fitToHeight?: boolean;
-    topGap?: number | ((timeline: Timeline) => number);
-  };
-  periodLine?: {
-    /** Additional gap from the active baseline in px. */
-    baselineGap?: number;
-    /** Gap between stacked period lines in px. */
-    spacing?: number;
-    /** Line thickness in px. */
-    thickness?: number;
-  };
-}
-
-export interface LaneData {
-  id: string | number;
-  title?: string;
-  visibility?: VisibilityState | ((lane: Lane) => VisibilityState);
-  /** Additional CSS class for the lane root beside `histropedia-lane` and `histropedia-lane-index-N`. */
-  className?: string;
-  /** Additional CSS class for the lane header beside `histropedia-lane-header`. */
-  headerClassName?: string;
-  /** Additional CSS class for the lane body beside `histropedia-lane-body`. */
-  bodyClassName?: string;
-  /** Additional CSS class for the lane title beside `histropedia-lane-title`. */
-  titleClassName?: string;
-  layout?: LaneLayout;
-  style?: LaneStyle;
-  article?: LaneArticleOverrides;
-}
-
-// ------------------------------------------------------------------------------------
-// Timeline options
-// ------------------------------------------------------------------------------------
-
-export interface TimelineZoomOptions {
-  /** @defaultValue 34 */ initial?: number;
-  /** @defaultValue 0 */ minimum?: number;
-  /** @defaultValue 123 */ maximum?: number;
-  /** Zoom step multiplier per wheel unit. @defaultValue 0.1 */
-  wheelStep?: number;
-  /** Overall wheel speed. @defaultValue 3 */
-  wheelSpeed?: number;
-  /** Allow Ctrl+wheel zoom. @defaultValue false */
-  allowCtrlWheel?: boolean;
-  /** 'auto' picks smooth vs discrete from device; 'discrete' forces stepped. @defaultValue 'auto' */
-  wheelMode?: 'auto' | 'discrete';
-  /** Animate discrete/notched wheel zoom steps. */
-  discreteWheelAnimation?: {
-    /** Enable animated wheel zoom. @defaultValue true */
-    active?: boolean;
-    /** Animation duration in ms. @defaultValue 250 */
-    duration?: number;
-  };
-  /** Gain for proportional (trackpad) mode. @defaultValue 2 */
-  proportionalGain?: number;
-  /** Exponent for proportional (trackpad) mode. @defaultValue 1.1 */
-  proportionalExponent?: number;
-  /** Zoom ratio between unit-size levels. @defaultValue 0.8 */
-  ratio?: number;
-  unitSize?: {
-    /** Size of a day at zoom=0 (and density region size). @defaultValue 200 */
-    initial?: number;
-    /** Unit-size threshold to show minor labels. @defaultValue 48 */
-    showMinorLabels?: number;
-    /** Minimum unit size in px. @defaultValue 8 */
-    minimum?: number;
-  };
-}
-
-export interface PanMomentumOptions {
-  /** Continue timeline panning after a drag release. @defaultValue true */
-  active?: boolean;
-  /** Pointer movement sample window in ms used to estimate release velocity. @defaultValue 100 */
-  sampleWindow?: number;
-  /** Minimum release velocity in px/ms before momentum starts. @defaultValue 0.01 */
-  minVelocity?: number;
-  /** Velocity in px/ms at which momentum stops. @defaultValue 0.005 */
-  stopVelocity?: number;
-  /** Exponential friction coefficient per ms. Lower values travel farther. @defaultValue 0.004 */
-  friction?: number;
-  /** Maximum momentum duration in ms. @defaultValue 1200 */
-  maxDuration?: number;
-}
-
-export interface TimelinePanOptions {
-  /** Momentum behaviour after a timeline drag release. */
-  momentum?: PanMomentumOptions;
-}
-
-export interface TimelineDebugOverlayOptions {
-  /** Draw vertical guides at article-density region boundaries. @defaultValue false */
-  densityRegions?: boolean;
-}
-
-export interface ArticleOptions {
-  /** Density filter for visible articles. @defaultValue DENSITY_ALL */
-  density?: Density;
-  /** Allow dragging event cards. @defaultValue true */
-  draggable?: boolean;
-  /**
-   * Distance of cards from their baseline in px, plus responsive settings.
-   *
-   * Responsive calculations use the resolved default card layout for the timeline or lane.
-   */
-  distanceToBaseline?: DistanceToBaselineOptions;
-  /**
-   * @deprecated Deprecated since 1.3.4 — Use `distanceToBaseline.value` instead.
-   */
-  distanceToMainLine?: number;
-  /** Collect ongoing events on main line. @defaultValue false */
-  collectOngoing?: boolean;
-  /** Auto stacking options. */
-  autoStacking?: {
-    /** @defaultValue true */
-    active?: boolean;
-    /** Distance between rows in px. @defaultValue 50 */
-    rowSpacing?: number;
-    /** Range considered for stacking. @defaultValue RANGE_ALL */
-    range?: AutoStackRange;
-    /** Fit to available height by adjusting rowSpacing. @defaultValue true */
-    fitToHeight?: boolean;
-    /** Top gap in px or a function returning px. @defaultValue 10 */
-    topGap?: number | ((timeline: Timeline) => number);
-  };
-  periodLine?: {
-    /** Anchor period lines to the shared axis or each lane bottom. @defaultValue 'lane' */
-    position?: 'axis' | 'lane';
-    /**
-     * Default value merged into `article.defaultData.hidePeriodLine`.
-     *
-     * @deprecated Deprecated since 1.3.0 — Use `defaultData.hidePeriodLine` instead.
-     */
-    defaultHide?: boolean;
-    /** Additional gap from the active baseline in px. @defaultValue 0 */
-    baselineGap?: number;
-    /** Gap between stacked period lines in px. @defaultValue 4 */
-    spacing?: number;
-    /** Line thickness in px. @defaultValue 10 */
-    thickness?: number;
-    stacking?: {
-      /** Comparator used when assigning period-line stacks. */
-      sorter?: ArticleSorter;
-      /** Reverse stacking order. @defaultValue false */
-      reverseOrder?: boolean;
-    };
-  };
-  animation?: {
-    fade?: { active?: boolean; duration?: number; easing?: EasingName };
-    move?: { active?: boolean; duration?: number; easing?: EasingName };
-  };
-  star?: { /** Show star icon. @defaultValue true */ visible?: boolean };
-  /** Default data merged into every loaded article. */
-  defaultData?: Partial<ArticleData>;
-  /** Fallback card layout name used when no breakpoint matches. @defaultValue 'portrait' */
-  defaultCardLayout?: CardLayoutName;
-  /** Ordered max-height overrides evaluated before falling back to `defaultCardLayout`. */
-  cardLayoutBreakpoints?: ArticleCardLayoutBreakpoint[];
-  /** Base styles. */
-  defaultStyle?: ArticleStyle;
-  defaultHoverStyle?: ArticleStyle;
-  defaultActiveStyle?: ArticleStyle;
-  /** Per-layout style overrides registered via Timeline.registerCardLayout. */
-  layoutStyles?: Record<
-    string,
-    Partial<{
-      style: ArticleStyle;
-      hoverStyle: ArticleStyle;
-      activeStyle: ArticleStyle;
-    }>
-  >;
-}
-
-/** Pixels from the main line, the `'edge'` keyword, or `{ value: 'edge', padding?: number }` for edge-stretching with padding. */
-export type AreaValue = number | 'edge' | { value: 'edge'; padding?: number };
-
-export interface TimeBandOptions {
-  /** Enable drawing of bands. @defaultValue true */
-  visible?: boolean;
-  /** Reserve extra space near main line when bands are present. @defaultValue true */
-  reserveSpace?: boolean;
-  /** Pixels to reserve when reserveSpace is true. @defaultValue 20 */
-  reserveSpacePixels?: number;
-  /** Up/down extents of the band area relative to the main line. Accepts px, `'edge'`, or `{ value: 'edge', padding?: number }`. @defaultValue {up: 0, down: 'edge'} */
-  area?: { up?: AreaValue; down?: AreaValue };
-  /** Global default style merged into each band. */
-  defaultStyle?: TimeBandStyle;
-  /** Bands to load initially. */
-  data?: TimeBandData[];
-}
-
-export interface ChartOptions {
-  /** Enable drawing of loaded charts. @defaultValue true */
-  visible?: boolean;
-  /** Main-view chart area relative to the shared axis. Lane-scoped charts use lane body geometry. */
-  area?: { up?: AreaValue; down?: AreaValue };
-  /** Global chart grid-line defaults merged into each chart style. */
-  gridLine?: ChartGridLineOptions;
-  /** Default data merged into every loaded chart. */
-  defaultData?: Partial<ChartData>;
-  /** Global default chart style merged into each chart. */
-  defaultStyle?: ChartStyle;
-  /** Charts to load initially. */
-  data?: ChartData[];
-}
-
-export interface LaneOptions {
-  /**
-   * Enable lane DOM chrome. Article layout still remains lane-aware when lane data is present.
-   * @defaultValue true
-   */
-  visible?: boolean;
-  /** Default lane id used when an article does not specify `lane`. @defaultValue 'default' */
-  defaultId?: string | number;
-  /** Gap between rendered lanes in px. @defaultValue 12 */
-  gap?: number;
-  /** Space reserved above the topmost lane in px. @defaultValue 0 */
-  topGap?: number;
-  /** Space between the painted edge of the shared main line and the lane area in px. @defaultValue 24 */
-  axisGap?: number;
-  /** Global default lane layout merged into each lane. */
-  defaultLayout?: LaneLayout;
-  /** Global default lane style merged into each lane. Only explicitly provided values are written inline. */
-  defaultStyle?: LaneStyle;
-  /** CSS class added to each lane root element beside `histropedia-lane` and `histropedia-lane-index-N`. */
-  defaultClassName?: string;
-  /** CSS class added to each lane header element beside `histropedia-lane-header`. */
-  defaultHeaderClassName?: string;
-  /** CSS class added to each lane body element beside `histropedia-lane-body`. */
-  defaultBodyClassName?: string;
-  /** CSS class added to each lane title element beside `histropedia-lane-title`. */
-  defaultTitleClassName?: string;
-  /** Lanes to load initially. */
-  data?: LaneData[];
-}
-
-/**
- * Image loading and URL sanitization options.
- *
- * By default, the built-in sanitizer allows http, https, data:image/* and blob:.
- * You can restrict schemes and/or remote origins, or provide a custom sanitizer.
- */
-export type ImageDecodeMode = 'auto' | 'prefer-bitmap' | 'bitmap' | 'prefer-img' | 'img';
-
-export interface ImageSanitizerOptions {
-  /**
-   * Allowed URL schemes for images.
-   * @defaultValue ['http', 'https', 'data', 'blob']
-   */
-  allowedSchemes?: string[];
-
-  /**
-   * Allowed origins/hosts for remote images. Supports full origins, bare hostnames,
-   * leading-dot, and wildcard-prefixed (`*.example.com`) entries.
-   */
-  allowedOrigins?: string[];
-}
-
-export interface ImageOptions {
-  /**
-   * Built-in URL sanitization controls.
-   */
-  sanitizer?: ImageSanitizerOptions;
-
-  /**
-   * Optional override for image URL sanitization. Receives the raw URL and the
-   * current sanitizer configuration from `image.sanitizer`. Return a trusted URL
-   * string to allow the load or null to block it.
-   */
-  customSanitizer?: (url: string, options: ImageSanitizerOptions) => string | null;
-
-  /**
-   * Maximum number of concurrent image fetch/decode operations. Values < 1 are clamped to 1.
-   * @defaultValue 6
-   */
-  maxConcurrent?: number;
-
-  /**
-   * Maximum decoded raster memory (in bytes) retained by the image cache.
-   * Set to `Infinity` to disable eviction, or reduce to bound memory usage.
-   * @defaultValue 64 * 1024 * 1024 (64 MiB)
-   */
-  maxCacheBytes?: number;
-
-  /**
-   * Force cross-origin requests to opt-in via CORS (sets `crossOrigin = 'anonymous'`).
-   * When true, images served without CORS headers will fail to load but canvas readbacks
-   * remain untainted.
-   * @defaultValue false
-   */
-  requireCORS?: boolean;
-
-  /**
-   * Controls how raster data is produced once an image loads.
-   *
-   * - 'auto' (default) prefers ImageBitmap when supported, falling back to `<img>`.
-   * - 'prefer-bitmap' aggressively tries ImageBitmap but falls back to `<img>` if needed.
-   * - 'bitmap' requires ImageBitmap support and treats failures as errors.
-   * - 'prefer-img' keeps `<img>` unless decoding fails, then falls back to ImageBitmap.
-   * - 'img' forces `<img>` and never calls `createImageBitmap`.
-   */
-  decodeMode?: ImageDecodeMode;
-}
-
-export interface TimelineDateBoundsOptions {
-  /** Earliest allowed visible viewport edge. @defaultValue null */
-  minDate?: DateParts | null;
-  /** Latest allowed visible viewport edge. @defaultValue null */
-  maxDate?: DateParts | null;
-  /**
-   * Boundary behaviour during active user interaction.
-   * - 'elastic': allow resisted temporary overflow and settle back when interaction ends.
-   * - 'clamp': prevent overflow immediately.
-   * @defaultValue 'elastic'
-   */
-  overflow?: 'elastic' | 'clamp';
-}
-
-export interface TimelineOptions {
-  /** Canvas width in px. @defaultValue 1000 */
-  width?: number;
-  /** Canvas height in px. @defaultValue 500 */
-  height?: number;
-  /** Canvas/backing-store configuration. */
-  canvas?: {
-    /** Device pixel ratio to use; 'auto' follows device. @defaultValue 'auto' */ dpr?:
-      | 'auto'
-      | number;
-    /**
-     * Behaviour for dpr:'auto'.
-     * - 'stable' (default) rounds devicePixelRatio up to the nearest integer.
-     * - 'native' uses the raw devicePixelRatio value.
-     * @defaultValue 'stable'
-     */
-    dprMode?: 'stable' | 'native';
-    /** Maximum DPR to apply for performance. @defaultValue 3 */ maxDpr?: number;
-  };
-  /** Per-timeline visual diagnostics. Independent from global debug logging. */
-  debugOverlays?: TimelineDebugOverlayOptions;
-  /** Vertical offset of the main line in px. @defaultValue 40 */
-  verticalOffset?: number;
-  /** Enable user interactions (wheel/drag/pinch). @defaultValue true */
-  enableUserControl?: boolean;
-  /** Show interactive cursors. @defaultValue true */
-  enableCursor?: boolean;
-  /** Zoom configuration. */
-  zoom?: TimelineZoomOptions;
-  /** Initial date (top-left when position not offset). @defaultValue {year:1990,month:1,day:1} */
-  initialDate?: DateParts;
-  /**
-   * Optional visible viewport date bounds. Bounds constrain viewport edges, not only the centre date.
-   * With both dates set, the settled viewport stays within `[minDate, maxDate]`.
-   */
-  bounds?: TimelineDateBoundsOptions;
-  /** Shift BCE input dates by +1 so 1BCE = year 0 internally. @defaultValue false */
-  shiftBceDates?: boolean;
-  /** Hide the built-in Histropedia branding/footer links. Defaults to false when omitted. */
-  disableBranding?: boolean;
-  /**
-   * Drag activation vicinity near the main line.
-   * - boolean: enable/disable dragging anywhere on the timeline
-   * - function: (event, relativePosition) => boolean; return true to allow dragging
-   *   where relativePosition is { left: number; top: number }
-   * - object: { up?: number; down?: number } in pixels from the main line
-   * @defaultValue true
-   */
-  draggingVicinity?:
-    | boolean
-    | ((event: PointerEvent, relativePosition: { left: number; top: number }) => boolean)
-    | { up?: number; down?: number };
-  /** Timeline panning configuration. */
-  pan?: TimelinePanOptions;
-  /** Canvas/UI styling. */
-  style?: TimelineStyleOptions;
-  /** Time band configuration. */
-  timeBand?: TimeBandOptions;
-  /** Chart layer configuration. */
-  chart?: ChartOptions;
-  /** Lane configuration. */
-  lane?: LaneOptions;
-  /** Article configuration. */
-  article?: ArticleOptions;
-  /** Configure image sanitization, caching, and loader behaviour. */
-  image?: ImageOptions;
-  /** Register event handlers via object literal: { 'article-click': fn, ... } */
-  on?: Partial<EventHandlerMap>;
-  /**
-   * Called after every draw pass.
-   *
-   * @deprecated Deprecated since 1.3.0 — Use `on['timeline-render-end']` instead.
-   */
-  onRedraw?: (ctx: RedrawContext) => void;
-  /**
-   * Article click handler configured via this option.
-   *
-   * @deprecated Deprecated since 1.3.0 — Use `on['article-click']` for click events or `on['article-select']` for selection by any means.
-   */
-  onArticleClick?: (article: Article, event?: Event) => void;
-  /**
-   * Article double click handler configured via this option.
-   *
-   * @deprecated Deprecated since 1.3.0 — Use `on['article-dblclick']` instead.
-   */
-  onArticleDoubleClick?: (article: Article, event?: Event) => void;
-  /**
-   * Timeline save handler configured via this option.
-   *
-   * @deprecated Deprecated since 1.3.0 — Use `on['timeline-state-change']` instead.
-   */
-  onSave?: (state: string) => void;
-}
-
-// ------------------------------------------------------------------------------------
-// Events
-// ------------------------------------------------------------------------------------
-
-/** Token produced by the timescale manager for marker drawing and viewport drag payloads. */
-export interface TimelineToken {
-  unit: ZoomLevel;
-  value: DmyInstance;
-  length: number;
-  label?: string;
-  type?: MarkerType;
-  drawX?: number;
-}
-
-export interface ZoomPayload {
-  zoom: number;
-  zoomDelta: number;
-}
-export interface WheelPayload {
-  centre: { x: number; y: number };
-  zoom: number;
-  zoomDelta: number;
-}
-export interface PinchPayload {
-  centre: { x: number; y: number } | null;
-  scale: number;
-  zoom: number;
-  distance: number;
-  zoomDelta: number;
-  dx?: number;
-  totalZoomDelta: number;
-  pointers: PointerEvent[];
-}
-export interface ViewportDragPayload {
-  startToken: TimelineToken;
-  offsetX: number;
-  dx?: number;
-  totalDx?: number;
-}
-export interface TimelineClickPayload {
-  viewport: { x: number; y: number };
-}
-export interface DragDelta {
-  dx: number;
-  dy: number;
-  totalDx: number;
-  totalDy: number;
-}
-
-/** Token cache exposed to redraw hooks for advanced positioning work. */
-export interface RedrawCycleContext {
-  tokens: {
-    start: DmyInstance;
-    end: DmyInstance;
-    [tokenKey: string]: DmyInstance | number;
-  };
-}
-
-/** Data delivered to redraw lifecycle handlers. */
-export interface RedrawContext {
-  canvasContext: CanvasRenderingContext2D;
-  /** Present for timeline-render-end; omitted for timeline-render-start. */
-  drawCycleContext?: RedrawCycleContext;
-  top: number;
-}
-
-export interface EventPayloadMap {
-  // zoom
-  zoom: [ZoomPayload];
-  'zoom-wheel': [WheelPayload, WheelEvent];
-  'zoom-pinch-start': [PinchPayload, PointerEvent];
-  'zoom-pinch': [PinchPayload, PointerEvent];
-  'zoom-pinch-end': [PinchPayload, PointerEvent];
-  // viewport
-  'viewport-drag-start': [ViewportDragPayload, PointerEvent];
-  'viewport-drag': [ViewportDragPayload, PointerEvent];
-  'viewport-drag-end': [ViewportDragPayload, PointerEvent];
-  // articles
-  'article-pointerenter': [Article, PointerEvent];
-  'article-pointermove': [Article, PointerEvent];
-  'article-pointerleave': [Article, PointerEvent];
-  'article-click': [Article, PointerEvent];
-  'article-dblclick': [Article, PointerEvent];
-  'article-select': [Article];
-  'article-drag-start': [Article, PointerEvent];
-  'article-drag': [Article, DragDelta, PointerEvent];
-  'article-drag-end': [Article, PointerEvent];
-  // timeline
-  'timeline-render-start': [RedrawContext];
-  'timeline-render-end': [RedrawContext];
-  'timeline-click': [TimelineClickPayload, PointerEvent];
-  'timeline-dblclick': [TimelineClickPayload, PointerEvent];
-  'timeline-state-change': [string];
-}
-
-export type TimelineEvent = keyof EventPayloadMap;
-export type EventHandlerMap = { [K in TimelineEvent]: (...args: EventPayloadMap[K]) => void };
-
-/** Backward-compatible alias for the article instance passed as `this` to card layout hooks. */
-export type CardLayoutArticleContext = Article;
-
-/** Full card layout definition stored by the runtime registry. */
-export interface RegisteredCardLayout {
-  name: string;
-  draw(this: Article, ctx: CanvasRenderingContext2D): void;
-  getWidth?(this: Article): number;
-  getHeight?(this: Article): number;
-  getIconBox?(this: Article): CardLayoutIconBox | false;
-  defaultStyle?: ArticleStyle;
-  defaultHoverStyle?: ArticleStyle;
-  defaultActiveStyle?: ArticleStyle;
-}
-
-/** Alias definition that points one layout name at another registered layout. */
-export interface CardLayoutAliasDefinition {
-  name: string;
-  aliasOf: CardLayoutName;
-}
-
-/** Definition accepted by `Timeline.registerCardLayout(...)`. */
-export type CardLayoutDefinition = RegisteredCardLayout | CardLayoutAliasDefinition;
-
-// ------------------------------------------------------------------------------------
-// Classes
-// ------------------------------------------------------------------------------------
-
-export interface AnimOptions {
-  /** Duration in ms. @defaultValue 2000 */ duration?: number;
-  /** Easing name. @defaultValue 'swing' */ easing?: EasingName;
-  /** Callback when animation completes. */ complete?: () => void;
-  /** Additional horizontal shift, used by pinch. */ offsetX?: number;
-}
-
-export type FitDateRangePadding = number | { left?: number; right?: number };
-
-export interface FitDateRangeAnimationOptions {
-  /** Enable simultaneous animated zooming and panning. @defaultValue false */
-  active?: boolean;
-  /** Duration in ms. Inherits the viewport animation default when omitted. */
-  duration?: number;
-  /** Easing name. Inherits the viewport animation default when omitted. */
-  easing?: EasingName;
-}
-
-export interface FitDateRangeOptions {
-  /** Edge padding in px, or per-side padding for asymmetric fits. @defaultValue 0 */
-  padding?: FitDateRangePadding;
-  /** Optional animation settings for the fit. */
-  animation?: FitDateRangeAnimationOptions;
-}
-
-export interface SetStartDateOptions {
-  /** Left padding in px for the supplied start date. This only affects the left side. @defaultValue 0 */
-  padding?: number;
-  /** Optional animation settings matching `fitDateRange(..., { animation })`. */
-  animation?: FitDateRangeAnimationOptions;
-}
-
-export interface FitArticleRangeOptions {
-  /** Edge padding in px, or per-side padding for asymmetric fits. @defaultValue 0 */
-  padding?: FitDateRangePadding;
-  /** Optional animation settings for the fit. */
-  animation?: FitDateRangeAnimationOptions;
-}
-
-export interface FitArticlesOptions {
-  /** Space in px between the outermost fitted article cards and the viewport edge. @defaultValue 40 */
-  padding?: FitDateRangePadding;
-  /** Optional article predicate. Defaults to fitting articles that are not `hiddenByFilter`. */
-  articleFilter?: (article: Article) => boolean;
-  /** Optional animation settings for the fit. */
-  animation?: FitDateRangeAnimationOptions;
-}
-
-export class Timeline {
-  /**
-   * Create a timeline bound to an existing canvas element or a container element (a canvas will be created).
-   * @example
-   * const tl = new Timeline(containerEl, { initialDate: { year: 1066, month: 10, day: 14 } });
-   */
-  constructor(container: HTMLCanvasElement | HTMLElement, options?: TimelineOptions);
-
-  /** Root canvas used for rendering. */
-  readonly canvas: HTMLCanvasElement;
-  /** 2D drawing context bound to `canvas`. */
-  readonly canvasContext: CanvasRenderingContext2D;
-  /** Current merged runtime options. */
-  options: TimelineOptions;
-  /** User-visible title used by serialized state helpers. */
-  title: string;
-  /** Current y-coordinate of the timeline baseline in canvas pixels. */
-  top: number;
-  readonly articles: Article[];
-  readonly lanes: Lane[];
-  readonly timeBands: TimeBand[];
-  readonly charts: Chart[];
-
-  /** Register a reusable card layout globally for all timelines. */
-  static registerCardLayout(definition: CardLayoutDefinition): void;
-  /** Resolve a previously registered card layout by name. */
-  static getCardLayout(name: CardLayoutName): RegisteredCardLayout | null;
-
-  // Data loading
-  /** Load articles and redraw. */
-  load(articles: ArticleData[]): void;
-  /** Load lanes and redraw. */
-  loadLanes(lanes: LaneData[]): void;
-  /** Load time bands and redraw. */
-  loadTimeBands(bands: TimeBandData[]): void;
-  /** Load new charts and redraw; duplicate ids are skipped with a warning. */
-  loadCharts(charts: ChartData[]): void;
-  /** Remove a chart by id and redraw when found. */
-  removeChart(id: string | number): boolean;
-  /** Remove all loaded charts and redraw. */
-  clearCharts(): void;
-  /** Stamp a lane id onto a batch of charts, load them, and redraw. */
-  loadLaneCharts(laneId: string | number, charts: ChartData[]): void;
-  /** Stamp a lane id onto a batch of articles, load them, and redraw. */
-  loadLaneArticles(laneId: string | number, articles: ArticleData[]): void;
-
-  // Query
-  getArticleById(id: string | number): Article | undefined;
-  getActiveArticle(): Article | null;
-  getLaneById(id: string | number): Lane | undefined;
-  getChartById(id: string | number): Chart | undefined;
-  hasArticle(id: string | number): boolean;
-
-  // Selection and ordering
-  bringFront(articleId: string | number): void;
-  /** Selects and brings the article to the front; emits 'article-select'. */
-  select(articleId: string | number): void;
-  /** Reorder articles to match the array of ids (topmost last). */
-  reorderArticles(ids: Array<string | number>): void;
-  /** Move a lane to a public lane index where 0 is nearest the axis. */
-  moveLaneToIndex(lane: Lane | string | number, index: number): Lane;
-  /** Move lane so it ends up immediately before targetLane. */
-  moveLaneBefore(lane: Lane | string | number, targetLane: Lane | string | number): Lane;
-  /** Move lane so it ends up immediately after targetLane. */
-  moveLaneAfter(lane: Lane | string | number, targetLane: Lane | string | number): Lane;
-  /** Move lane one position farther from the axis. */
-  moveLaneUp(lane: Lane | string | number): Lane;
-  /** Move lane one position closer to the axis. */
-  moveLaneDown(lane: Lane | string | number): Lane;
-  /** Update the serializable title stored by `getStatusForSave()`. */
-  setTitle(title: string): void;
-
-  // Navigation & view
-  /** Set start date (left edge). Accepts Dmy-compatible objects or strings in "-YYYY-MM-DD" style. */
-  setStartDate(date: Dmy | string, options?: SetStartDateOptions): void;
-  /** @deprecated Use `setStartDate(date, { padding })` instead. */
-  setStartDate(date: Dmy | string, pixelOffset?: number): void;
-  /** Set centre date using startDate + offset computation. */
-  setCentreDate(date: Dmy | string, pixelOffset?: number): void;
-  /** Current zoom value. */
-  getZoom(): number;
-  /** Set zoom (optionally pivoting around a pixel). */
-  setZoom(zoom: number, pivotPixel?: number, offsetX?: number): void;
-  /** Smooth pan by pixels (negative = right). */
-  goToPixelAnim(pixels: number, options?: AnimOptions): void;
-  /** @deprecated Use `setStartDate(dmy, { padding, animation: { active: true, ... } })` instead. */
-  goToDateAnim(dmy: Dmy, options?: AnimOptions): void;
-  /** Fit a date range into the viewport with optional edge padding. Dates may be passed in either order; year-only and month-only inputs are treated as full periods. */
-  fitDateRange(
-    start: FitDateRangeInput,
-    end: FitDateRangeInput,
-    options?: FitDateRangeOptions,
-  ): void;
-  /** Fit a single article's full period into the viewport using `article.period.from` and `article.period.to`. */
-  fitArticleRange(article: Article, options?: FitArticleRangeOptions): boolean;
-  /** Fit currently unfiltered article cards into the viewport using each article's start date, card width, and connector offset. */
-  fitArticles(options?: FitArticlesOptions): boolean;
-  /** Animate to an absolute zoom value using the built-in tween. */
-  zoomToAnim(newZoom: number, complete?: () => void): void;
-
-  // Drawing
-  /** Request a redraw (coalesced if an animation is running). */
-  requestRedraw(redrawFunction?: () => void): void;
-  /** Full draw cycle. */
-  redraw(): void;
-  /** Reposition-only draw (for zoom/start-date changes). */
-  repositionRedraw(): void;
-  /** Default draw including reposition and stacking. */
-  defaultRedraw(): void;
-  /** Toggle auto fit-to-height for article stacking and return the new enabled state. */
-  toggleAutoFit(): boolean;
-  /** Recompute row spacing so visible rows fit in the available height. */
-  fitToHeight(withRedraw?: boolean): number | undefined;
-  /**
-   * @deprecated Deprecated since 1.3.0 — Use `timeline.on('timeline-render-end', handler)` instead.
-   */
-  onRedraw(handler: (ctx: RedrawContext) => void): void;
-
-  // Interaction toggles
-  enableZoomByWheel(): void;
-  disableZoomByWheel(): void;
-
-  // Misc utilities
-  /** Current canvas width in CSS pixels. */
-  getWidth(): number;
-  /** Current applied device pixel ratio for the canvas. */
-  getCanvasDpr(): number;
-  /** Get canvas-relative coordinates for a DOM event. */
-  getRelativePosition(evt: MouseEvent | PointerEvent | TouchEvent): { left: number; top: number };
-
-  // Options
-  /** Get or set options via dot-path or partial object. */
-  setOption(path: string, value: unknown): void;
-  setOption<T extends DeepPartial<TimelineOptions>>(patch: T): void;
-  setOption(path: string): unknown;
-  /** Resize the canvas. */
-  setSize(width: number, height: number): void;
-  /** Serialize the current timeline state to the legacy compact JSON string. */
-  getStatusForSave(): string;
-  /** Register a reusable card layout from an instance. Delegates to the static method. */
-  registerCardLayout(definition: CardLayoutDefinition): void;
-  /** Resolve a previously registered card layout by name. */
-  getCardLayout(name: CardLayoutName): RegisteredCardLayout | null;
-
-  // Event bus
-  on<T extends TimelineEvent>(event: T, handler: (...args: EventPayloadMap[T]) => void): void;
-  on(event: string, handler: (...args: any[]) => void): void;
-  off<T extends TimelineEvent>(event: T, handler: (...args: EventPayloadMap[T]) => void): void;
-  off(event: string, handler: (...args: any[]) => void): void;
-  /**
-   * Trigger a built-in or custom event.
-   * Custom event payloads are intentionally untyped because the runtime does not enforce a schema.
-   */
-  trigger<T extends TimelineEvent>(event: T, ...args: EventPayloadMap[T]): void;
-  trigger(event: string, ...args: any[]): void;
-}
-
-export class Article {
-  /** Stable article identifier. */
-  id: string | number;
-  /** Owning timeline instance. */
-  owner: Timeline;
-  /** Latest runtime data backing this article. */
-  data: ArticleData;
-  title: string;
-  subtitle: string;
-  rank: number;
-  laneId: string | number | null;
-  cardLayout: CardLayoutName | null;
-  period: ArticlePeriod;
-  position: CanvasPosition;
-  registeredPosition: CanvasPosition;
-  offset: CanvasPosition;
-  finalOffset: CanvasPosition;
-  indicator: ArticleIndicator;
-  row: number;
-  image: CanvasImageSource | null;
-  imageLoaded: boolean;
-  style: ArticleStyle;
-  hoverStyle: ArticleStyle;
-  activeStyle: ArticleStyle;
-  activeHoverStyle: ArticleStyle;
-  opacity: number;
-  isActive: boolean;
-  isVisible: boolean;
-  isDragging: boolean;
-  isStarred: boolean;
-  isMouseover: boolean;
-  hiddenByFilter: boolean;
-  isDataLoaded: boolean;
-
-  /** Update article data at runtime (dot-path or object). */
-  setOption(path: string, value: unknown): void;
-  setOption(patch: Partial<ArticleData>): void;
-  setOption(path: string): unknown;
-
-  /** Update normal style (dot-path or object). */
-  setStyle(path: string, value: unknown): void;
-  setStyle(style: Partial<ArticleStyle>): void;
-  setStyle(path: string): unknown;
-
-  /** Update hover style (dot-path or object). */
-  setHoverStyle(path: string, value: unknown): void;
-  setHoverStyle(style: Partial<ArticleStyle>): void;
-  setHoverStyle(path: string): unknown;
-
-  /** Update active style (dot-path or object). */
-  setActiveStyle(path: string, value: unknown): void;
-  setActiveStyle(style: Partial<ArticleStyle>): void;
-  setActiveStyle(path: string): unknown;
-
-  /** Move instantly to absolute canvas position. */
-  moveTo(position: { left: number; top: number }): void;
-  /** Move by delta from current position. */
-  moveToOffset(offset: { left: number; top: number }): void;
-  /** Override the card layout used by this article. */
-  setCardLayout(cardLayout: CardLayoutName): void;
-  /** Small per-layout memoization helper. */
-  memo<T>(key: string, factory: () => T): T;
-  /** Clear cached measurements/layout artifacts for this article. */
-  invalidateCaches(): void;
-  /** Resolve the clickable star hit area, or `false` when none is present. */
-  getIconBox(): CardLayoutIconBox | false;
-
-  /** Measured card width. */
-  getWidth(): number;
-  /** Measured card height. */
-  getHeight(): number;
-}
-
-export class TimeBand {
-  id: string | number;
-  owner: Timeline;
-  data: TimeBandData;
-  title: string;
-  style: TimeBandStyle;
-  period: TimeBandPeriod;
-  visibility: VisibilityState;
-
-  /** Update band data at runtime (dot-path or object). */
-  setOption(path: string, value: unknown): void;
-  setOption(patch: Partial<TimeBandData>): void;
-  setOption(path: string): unknown;
-
-  /** Update band style (dot-path or object). */
-  setStyle(path: string, value: unknown): void;
-  setStyle(style: Partial<TimeBandStyle>): void;
-  setStyle(path: string): unknown;
-}
-
-export class Chart {
-  id: string | number;
-  owner: Timeline;
-  data: ChartData;
-  type: ChartType;
-  title: string;
-  laneId: string | number | null;
-  area: { up?: AreaValue; down?: AreaValue } | null;
-  scale: ChartScaleOptions;
-  typeOptions: ChartTypeOptions;
-  style: ChartStyle;
-  series: Array<{
-    id: string | number;
-    title: string;
-    style: ChartSeriesStyle;
-    points: Array<{ date: DmyInstance; value: number | null }>;
-  }>;
-  visibility: VisibilityState;
-
-  /** Add one series to this chart and redraw. */
-  addSeries(series: ChartSeriesData): void;
-
-  /** Remove one series by id and redraw when found. */
-  removeSeriesById(id: string | number): boolean;
-
-  /** Return the normalized runtime series with this id. */
-  getSeriesById(id: string | number):
-    | {
-        id: string | number;
-        title: string;
-        style: ChartSeriesStyle;
-        points: Array<{ date: DmyInstance; value: number | null }>;
-      }
-    | undefined;
-
-  /** Update chart data at runtime (dot-path or object). */
-  setOption(path: string, value: unknown): void;
-  setOption(patch: Partial<Omit<ChartData, 'id'>>): void;
-  setOption(path: string): unknown;
-
-  /** Update chart style (dot-path or object). */
-  setStyle(path: string, value: unknown): void;
-  setStyle(style: Partial<ChartStyle>): void;
-  setStyle(path: string): unknown;
-
-  /** Resolve the active y-domain for the chart. */
-  getScaleDomain(drawCycleContext?: RedrawCycleContext): { min: number; max: number };
-}
-
-export class Lane {
-  id: string | number;
-  owner: Timeline;
-  data: LaneData;
-  title: string;
-  layout: LaneLayout;
-  style: LaneStyle;
-  order: number;
-  isImplicit: boolean;
-  visibility: VisibilityState;
-
-  /** Update lane data at runtime (dot-path or object). */
-  setOption(path: string, value: unknown): void;
-  setOption(patch: Partial<LaneData>): void;
-  setOption(path: string): unknown;
-
-  /** Hide the lane by setting visibility to "hidden". */
-  hide(): void;
-
-  /** Show the lane by setting visibility to "visible". */
-  show(): void;
-
-  /** Move this lane to a public lane index where 0 is nearest the axis. */
-  moveToIndex(index: number): Lane;
-
-  /** Move this lane so it ends up immediately before targetLane. */
-  moveBefore(targetLane: Lane | string | number): Lane;
-
-  /** Move this lane so it ends up immediately after targetLane. */
-  moveAfter(targetLane: Lane | string | number): Lane;
-
-  /** Move this lane one position farther from the axis. */
-  moveUp(): Lane;
-
-  /** Move this lane one position closer to the axis. */
-  moveDown(): Lane;
-
-  /** Update lane style (dot-path or object). */
-  setStyle(path: string, value: unknown): void;
-  setStyle(style: Partial<LaneStyle>): void;
-  setStyle(path: string): unknown;
-}
-
-/** Built-in sorter signature used by stacking and layout helpers. */
-export type ArticleSorter = (articleA: any, articleB: any) => number;
-
-export const ARTICLE_DURATION_SORTER: ArticleSorter;
-export const ARTICLE_DURATION_YEARS_SORTER: ArticleSorter;
-export const ARTICLE_IMAGE_QUEUE_SORTER: ArticleSorter;
-export const ARTICLE_FROM_SORTER: ArticleSorter;
-export const ARTICLE_TO_SORTER: ArticleSorter;
-export const ARTICLE_TOP_SORTER: ArticleSorter;
-export const ARTICLE_ROW_SORTER: ArticleSorter;
-export const ARTICLE_RANK_SORTER: ArticleSorter;
-export const ARTICLE_EFFECTIVE_RANK_SORTER: ArticleSorter;
-export const ARTICLE_POSITION_SORTER: ArticleSorter;
-
-// ------------------------------------------------------------------------------------
-// Default export for UMD / ESM default
-// ------------------------------------------------------------------------------------
-
-export interface HistropediaApi {
-  Timeline: typeof Timeline;
-  Article: typeof Article;
-  Chart: typeof Chart;
-  Lane: typeof Lane;
-  TimeBand: typeof TimeBand;
-  Dmy: DmyConstructor;
-  Logger: LoggerInstance;
-  setDebug(enabled: boolean): void;
-  isDebugEnabled(): boolean;
-  enableDebug(): void;
-  disableDebug(): void;
-  ARTICLE_DURATION_SORTER: typeof ARTICLE_DURATION_SORTER;
-  ARTICLE_DURATION_YEARS_SORTER: typeof ARTICLE_DURATION_YEARS_SORTER;
-  ARTICLE_IMAGE_QUEUE_SORTER: typeof ARTICLE_IMAGE_QUEUE_SORTER;
-  ARTICLE_FROM_SORTER: typeof ARTICLE_FROM_SORTER;
-  ARTICLE_TO_SORTER: typeof ARTICLE_TO_SORTER;
-  ARTICLE_TOP_SORTER: typeof ARTICLE_TOP_SORTER;
-  ARTICLE_ROW_SORTER: typeof ARTICLE_ROW_SORTER;
-  ARTICLE_RANK_SORTER: typeof ARTICLE_RANK_SORTER;
-  ARTICLE_EFFECTIVE_RANK_SORTER: typeof ARTICLE_EFFECTIVE_RANK_SORTER;
-  ARTICLE_POSITION_SORTER: typeof ARTICLE_POSITION_SORTER;
-  MINOR_MARKER: typeof MINOR_MARKER;
-  MAJOR_MARKER: typeof MAJOR_MARKER;
-  ERA_MARKER: typeof ERA_MARKER;
-  ZOOM_DAY: typeof ZOOM_DAY;
-  ZOOM_MONTH: typeof ZOOM_MONTH;
-  ZOOM_YEAR: typeof ZOOM_YEAR;
-  ZOOM_DECADE: typeof ZOOM_DECADE;
-  ZOOM_CENTURY: typeof ZOOM_CENTURY;
-  ZOOM_MILLENNIUM: typeof ZOOM_MILLENNIUM;
-  ZOOM_10_THOUSAND_YEARS: typeof ZOOM_10_THOUSAND_YEARS;
-  ZOOM_100_THOUSAND_YEARS: typeof ZOOM_100_THOUSAND_YEARS;
-  ZOOM_MILLION_YEARS: typeof ZOOM_MILLION_YEARS;
-  ZOOM_10_MILLION_YEARS: typeof ZOOM_10_MILLION_YEARS;
-  ZOOM_100_MILLION_YEARS: typeof ZOOM_100_MILLION_YEARS;
-  ZOOM_BILLION_YEARS: typeof ZOOM_BILLION_YEARS;
-  YEAR_PREFIXES: typeof YEAR_PREFIXES;
-  DENSITY_SETTINGS: typeof DENSITY_SETTINGS;
-  PRECISION_DAY: typeof PRECISION_DAY;
-  PRECISION_MONTH: typeof PRECISION_MONTH;
-  PRECISION_YEAR: typeof PRECISION_YEAR;
-  PRECISION_DECADE: typeof PRECISION_DECADE;
-  PRECISION_CENTURY: typeof PRECISION_CENTURY;
-  PRECISION_MILLENNIUM: typeof PRECISION_MILLENNIUM;
-  PRECISION_MILLION_YEARS: typeof PRECISION_MILLION_YEARS;
-  PRECISION_BILLION_YEARS: typeof PRECISION_BILLION_YEARS;
-  DENSITY_ALL: typeof DENSITY_ALL;
-  DENSITY_LOW: typeof DENSITY_LOW;
-  DENSITY_MEDIUM: typeof DENSITY_MEDIUM;
-  DENSITY_HIGH: typeof DENSITY_HIGH;
-  RANGE_ALL: typeof RANGE_ALL;
-  RANGE_SCREEN: typeof RANGE_SCREEN;
-}
-
-declare const HistropediaModule: HistropediaApi;
-
-export default HistropediaModule;
-
-declare global {
-  const Histropedia: HistropediaApi;
-
-  interface Window {
-    Histropedia: HistropediaApi;
-  }
-}
+// Type definitions for HistropediaJS – public API only
+
+// ------------------------------------------------------------------------------------
+// Helpers
+// ------------------------------------------------------------------------------------
+
+/**
+ * Deeply partial helper for ergonomic option updates.
+ *
+ * Notes:
+ * - Functions are left as-is (not recursed).
+ * - Arrays/tuples are treated as replace-whole values (not recursed).
+ */
+export type DeepPartial<T> = T extends (...args: any) => any
+  ? T
+  : T extends readonly any[]
+    ? T
+    : T extends object
+      ? { [K in keyof T]?: DeepPartial<T[K]> }
+      : T;
+
+/** Built-in card layouts stay in autocomplete while custom registered names still type-check. */
+export type CardLayoutName = 'portrait' | 'landscape' | (string & {});
+
+/** Runtime visibility state used by lanes and time bands. */
+export type VisibilityState = 'visible' | 'hidden';
+
+/** Pixel-grid mode used for built-in article cards and their connectors. */
+export type ArticlePixelSnapMode = 'device' | 'css' | 'none' | boolean;
+
+/** Canvas-relative 2D position used by rendered articles. */
+export interface CanvasPosition {
+  left: number;
+  top: number;
+}
+
+/** Main-line indicator coordinates for an article currently in range. */
+export interface ArticleIndicator {
+  fromX: number;
+  toX: number;
+}
+
+/** Computed article time span after precision expansion. */
+export interface ArticlePeriod {
+  from: DmyInstance;
+  to: DmyInstance;
+  isToPresent: boolean;
+  /** Approximate duration in decimal years, used for sorting/layout decisions. */
+  years: number;
+}
+
+/** Computed time-band span after precision expansion. */
+export interface TimeBandPeriod {
+  from: DmyInstance;
+  to: DmyInstance;
+  isToPresent: boolean;
+}
+
+/** Rectangular hover/click area returned by card layouts for the built-in star interaction. */
+export interface CardLayoutIconBox extends CanvasPosition {
+  width: number;
+  height: number;
+  /** @deprecated Drawing geometry is derived from the rectangle and ignored by hit-testing. */
+  centreX?: number;
+  /** @deprecated Drawing geometry is derived from the rectangle and ignored by hit-testing. */
+  centreY?: number;
+  /** @deprecated Drawing geometry is derived from the rectangle and ignored by hit-testing. */
+  innerRadius?: number;
+  /** @deprecated Drawing geometry is derived from the rectangle and ignored by hit-testing. */
+  outerRadius?: number;
+}
+
+// ------------------------------------------------------------------------------------
+// Date and precision
+// ------------------------------------------------------------------------------------
+
+/** Date precision constants (public). */
+export const PRECISION_MILLISECOND: 'millisecond';
+export const PRECISION_SECOND: 'second';
+export const PRECISION_MINUTE: 'minute';
+export const PRECISION_HOUR: 'hour';
+export const PRECISION_DAY: 'day';
+export const PRECISION_MONTH: 'month';
+export const PRECISION_YEAR: 'year';
+export const PRECISION_DECADE: 'decade';
+export const PRECISION_CENTURY: 'century';
+export const PRECISION_MILLENNIUM: 'millennium';
+export const PRECISION_MILLION_YEARS: 'million-years';
+export const PRECISION_BILLION_YEARS: 'billion-years';
+
+/** @deprecated Use the equivalent string precision instead. */
+export type LegacyPrecision = 15 | 14 | 13 | 12 | 11 | 10 | 9 | 8 | 7 | 6 | 3 | 1;
+
+/**
+ * Date precision used by Article/TimeBand ranges.
+ * Legacy numeric precision values remain supported for backwards compatibility.
+ */
+export type Precision =
+  | typeof PRECISION_MILLISECOND
+  | typeof PRECISION_SECOND
+  | typeof PRECISION_MINUTE
+  | typeof PRECISION_HOUR
+  | typeof PRECISION_DAY
+  | typeof PRECISION_MONTH
+  | typeof PRECISION_YEAR
+  | typeof PRECISION_DECADE
+  | typeof PRECISION_CENTURY
+  | typeof PRECISION_MILLENNIUM
+  | typeof PRECISION_MILLION_YEARS
+  | typeof PRECISION_BILLION_YEARS
+  | LegacyPrecision;
+
+/** Plain calendar date and optional time parts (no precision). */
+export type DateParts = {
+  year: number;
+  month?: number;
+  day?: number;
+  hour?: number;
+  minute?: number;
+  second?: number;
+  millisecond?: number;
+};
+
+/** General date input that can include precision. */
+export type DateInput = DateParts & { precision?: Precision };
+
+/**
+ * Calendar date string without a timezone.
+ *
+ * Accepted grammar: `year[-month[-day]][T| ]hour[:minute[:second[.SSS]]]`, with the
+ * time portion optional. Years may be negative and may contain more than four digits,
+ * for example `-44-03-15T09:01` or
+ * `1000000000-06-15T12:30:05.250`.
+ */
+export type DateString = string;
+
+/** Calendar-value shape. Fields remain writable for backwards compatibility. */
+export interface Dmy {
+  year: number;
+  month?: number;
+  day?: number;
+  hour?: number;
+  minute?: number;
+  second?: number;
+  millisecond?: number;
+  precision?: Precision;
+}
+
+/** Formatting options for Dmy.format. */
+export interface DmyFormatOptions {
+  yearPrefix?: { value?: number; label?: string };
+  bceText?: string;
+  thousandsSeparator?: string;
+}
+
+/** Histropedia date helper instance. */
+export interface DmyInstance extends Dmy {
+  getDaysTo(other: Dmy): number;
+  getMonthsTo(other: Dmy): number;
+  getYearsTo(other: Dmy): number;
+  getLeapYearsSinceYearZero(): number;
+  getDaysSinceYearZero(): number;
+  getMillisecondsOfDay(): number;
+  getDayOfYear(): number;
+  getNextDay(): DmyInstance;
+  addDays(amount: number): DmyInstance;
+  addHours(amount: number): DmyInstance;
+  addMinutes(amount: number): DmyInstance;
+  addSeconds(amount: number): DmyInstance;
+  addMilliseconds(amount: number): DmyInstance;
+  /** Supports positive amounts only and returns the first day of the resulting month. */
+  addMonths(amount: number): DmyInstance;
+  /** Adds years and returns January 1 of the resulting year. */
+  addYears(amount: number): DmyInstance;
+  getPreviousDay(): DmyInstance;
+  getNextMonth(): DmyInstance;
+  getPreviousMonth(): DmyInstance;
+  format(format?: string, options?: DmyFormatOptions): string;
+  isSame(other: Dmy): boolean;
+  isAfter(other: Dmy): boolean;
+  isBetween(from: Dmy, to: Dmy): boolean;
+  compare(other: Dmy): number;
+  toKeyString(): string;
+  /** Approximate decimal-year position rounded to two decimal places. */
+  asFloat(): number;
+  isInFuture(): boolean;
+  /** Converts BCE numbering in place and returns this instance. */
+  convertToIso(): DmyInstance;
+}
+
+/** Date value accepted by timeline navigation and date-bound APIs. */
+export type DateValue = DmyInstance | DateParts | DateString;
+
+export type FitDateRangeInput = DateValue;
+
+export interface DmyConstructor {
+  /** Creates a mutable calendar value. Raw omitted month/day fields remain undefined. */
+  new (
+    year: number,
+    month?: number,
+    day?: number,
+    hour?: number,
+    minute?: number,
+    second?: number,
+    millisecond?: number,
+  ): DmyInstance;
+  new (value: Dmy): DmyInstance;
+  readonly prototype: DmyInstance;
+  getByDayOfYear(year: number, dayOfYear: number): DmyInstance;
+  CreateAsStartOfPeriod(date: Dmy, precision?: Precision): DmyInstance;
+  CreateAsEndOfPeriod(date: Dmy, precision?: Precision): DmyInstance;
+  CreateAsExclusiveEndOfPeriod(date: Dmy, precision?: Precision): DmyInstance;
+  /** Returns the current local date at midnight. */
+  now(): DmyInstance;
+  /** Invalid grammar returns a Dmy whose year is NaN; parsed fields use legacy normalization. */
+  fromString(dateString: DateString): DmyInstance;
+}
+
+export const Dmy: DmyConstructor;
+
+// ------------------------------------------------------------------------------------
+// Public constants (used in options)
+// ------------------------------------------------------------------------------------
+
+export const DENSITY_ALL: 'all';
+export const DENSITY_LOW: 'low';
+export const DENSITY_MEDIUM: 'medium';
+export const DENSITY_HIGH: 'high';
+/** @deprecated Use the equivalent string density instead. */
+export type LegacyDensity = 0 | 1 | 2 | 3;
+export type Density =
+  | typeof DENSITY_ALL
+  | typeof DENSITY_LOW
+  | typeof DENSITY_MEDIUM
+  | typeof DENSITY_HIGH
+  | LegacyDensity;
+
+export const RANGE_ALL: 'all';
+export const RANGE_SCREEN: 'screen';
+/** @deprecated Use the equivalent string auto-stacking range instead. */
+export type LegacyAutoStackRange = 0 | 1;
+export type AutoStackRange = typeof RANGE_ALL | typeof RANGE_SCREEN | LegacyAutoStackRange;
+
+export const MINOR_MARKER: 0;
+export const MAJOR_MARKER: 1;
+export const ERA_MARKER: 2;
+export type MarkerType = typeof MINOR_MARKER | typeof MAJOR_MARKER | typeof ERA_MARKER;
+
+export const ZOOM_DAY: 0;
+export const ZOOM_HOUR: -1;
+export const ZOOM_MINUTE: -2;
+export const ZOOM_SECOND: -3;
+export const ZOOM_MILLISECOND: -4;
+export const ZOOM_MONTH: 1;
+export const ZOOM_YEAR: 2;
+export const ZOOM_DECADE: 3;
+export const ZOOM_CENTURY: 4;
+export const ZOOM_MILLENNIUM: 5;
+export const ZOOM_10_THOUSAND_YEARS: 6;
+export const ZOOM_100_THOUSAND_YEARS: 7;
+export const ZOOM_MILLION_YEARS: 8;
+export const ZOOM_10_MILLION_YEARS: 9;
+export const ZOOM_100_MILLION_YEARS: 10;
+export const ZOOM_BILLION_YEARS: 11;
+export type ZoomLevel =
+  | typeof ZOOM_MILLISECOND
+  | typeof ZOOM_SECOND
+  | typeof ZOOM_MINUTE
+  | typeof ZOOM_HOUR
+  | typeof ZOOM_DAY
+  | typeof ZOOM_MONTH
+  | typeof ZOOM_YEAR
+  | typeof ZOOM_DECADE
+  | typeof ZOOM_CENTURY
+  | typeof ZOOM_MILLENNIUM
+  | typeof ZOOM_10_THOUSAND_YEARS
+  | typeof ZOOM_100_THOUSAND_YEARS
+  | typeof ZOOM_MILLION_YEARS
+  | typeof ZOOM_10_MILLION_YEARS
+  | typeof ZOOM_100_MILLION_YEARS
+  | typeof ZOOM_BILLION_YEARS;
+
+export interface YearPrefixSettings {
+  label: string;
+  value: number;
+}
+
+export const YEAR_PREFIXES: Readonly<Record<number, YearPrefixSettings>>;
+
+export interface DensitySetting {
+  region: number;
+  zoom: {
+    from: number;
+    to: number;
+  };
+  low: number;
+  medium: number;
+  high: number;
+  all: number;
+  step: {
+    months: number;
+    days: number;
+    /** Binary subdivisions of one day used by sub-day density regions. */
+    divisionsPerDay?: number;
+  };
+}
+
+export const DENSITY_SETTINGS: readonly DensitySetting[];
+
+export interface LoggerInstance {
+  setEnabled(enabled: boolean): void;
+  isEnabled(): boolean;
+  setPrefix(prefix: string): void;
+  getPrefix(): string;
+  log(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+  info(...args: unknown[]): void;
+  debug(...args: unknown[]): void;
+  group(...args: unknown[]): void;
+  groupCollapsed(...args: unknown[]): void;
+  groupEnd(): void;
+}
+
+export const Logger: LoggerInstance;
+
+// ------------------------------------------------------------------------------------
+// Animation types
+// ------------------------------------------------------------------------------------
+
+/** Allowed easing names used by animations. */
+export type EasingName =
+  | 'linear'
+  | 'swing'
+  | 'easeInQuad'
+  | 'easeOutQuad'
+  | 'easeInOutQuad'
+  | 'easeInCubic'
+  | 'easeOutCubic'
+  | 'easeInOutCubic';
+
+// ------------------------------------------------------------------------------------
+// Style types
+// ------------------------------------------------------------------------------------
+
+export interface ArticleStyleText {
+  font?: string;
+  color?: string;
+  align?: 'left' | 'right' | 'center' | 'start' | 'end';
+  baseline?: 'top' | 'hanging' | 'middle' | 'alphabetic' | 'bottom';
+  margin?: number;
+  lineHeight?: number;
+  numberOfLines?: number;
+  offsetY?: number;
+}
+
+export interface ArticleStyle {
+  /** @defaultValue 150 */
+  width?: number;
+  /** Landscape card layout only. @defaultValue 70 */
+  height?: number;
+  /** Card background fill color. @defaultValue '#e5e5e5' */
+  color?: string;
+  /** Inner card background. @defaultValue '#fff' */
+  backgroundColor?: string;
+  /** Portrait card layout only. @defaultValue 3 */
+  topRadius?: number;
+  /** Landscape card layout only. @defaultValue 4 */
+  borderRadius?: number;
+  /**
+   * Shorthand for the article image maximum height.
+   *
+   * @deprecated Deprecated since 1.3.0 — Use `image.maxHeight` instead.
+   * @defaultValue 400
+   */
+  maxImageHeight?: number;
+  image?: {
+    /** @defaultValue 'natural' */
+    shape?: 'natural' | 'square' | 'circle';
+    /** @defaultValue 0 */
+    margin?: number;
+    /** @defaultValue 200 */
+    maxHeight?: number;
+    /** @defaultValue 0 */
+    borderRadius?: number;
+  };
+  header?: {
+    /** Portrait card layout only. @defaultValue 50 */
+    height?: number;
+    text?: ArticleStyleText;
+  };
+  subheader?: {
+    /** Portrait card layout only. @defaultValue 30 */
+    height?: number;
+    /** Portrait card layout only. @defaultValue '#555' */
+    color?: string;
+    text?: ArticleStyleText;
+  };
+  shadow?: {
+    /** @defaultValue 0 */ x?: number;
+    /** @defaultValue 0 */ y?: number;
+    /** @defaultValue 0 */ amount?: number;
+    /** @defaultValue '#000' */ color?: string;
+  };
+  border?: {
+    /** @defaultValue '#ddd' */ color?: string;
+    /** @defaultValue 1 */ width?: number;
+  };
+  connectorLine?: {
+    /** @defaultValue true */ visible?: boolean;
+    /** @defaultValue 18 */ offsetX?: number;
+    /** @defaultValue -20 */ offsetY?: number;
+    /** @defaultValue 1 */ thickness?: number;
+    arrow?: {
+      /** @defaultValue 16 */ width?: number;
+      /** @defaultValue 45 */ height?: number;
+    };
+  };
+  star?: {
+    /** @defaultValue 16 */ width?: number;
+    /** @defaultValue 3 */ margin?: number;
+  };
+}
+
+export interface TimeBandStyleText {
+  font?: string;
+  color?: string;
+  align?: 'left' | 'right' | 'center' | 'start' | 'end';
+  baseline?: 'top' | 'middle' | 'alphabetic' | 'bottom';
+  /** Vertical align inside band area. */
+  verticalAlign?: 'top' | 'middle' | 'bottom';
+  /** Horizontal/vertical padding in px. @defaultValue 4 */
+  margin?: number;
+  /** Extra vertical offset in px. @defaultValue 0 */
+  offsetY?: number;
+}
+
+export interface TimeBandStyle {
+  /** @defaultValue 'rgba(200, 200, 200, 0.25)' */
+  backgroundColor?: string;
+  border?: { color?: string; width?: number };
+  text?: TimeBandStyleText;
+}
+
+export interface TimelineStyleMarkerKind {
+  /** @defaultValue 12 (minor) / 30 (major) */ height?: number;
+  /** Extend marker to canvas top/bottom. @defaultValue false */ extend?: boolean;
+  color?: string;
+  futureColor?: string;
+}
+
+export interface TimelineStyleMainLineGradient {
+  type: 'gradient';
+  topColor: string;
+  bottomColor: string;
+}
+
+export interface TimelineDateIndicatorStyle {
+  /** @defaultValue 'rectangle' */ shape?: 'rectangle' | 'circle';
+  /** Rectangle width or circle diameter in px. @defaultValue 4 */ size?: number;
+  /** CSS colour or the article colour resolved for the indicator state. @defaultValue '#666' */
+  color?: string;
+  /** Canvas opacity from 0 to 1. @defaultValue 1 */ opacity?: number;
+}
+
+export interface TimelineDateIndicatorOptions extends TimelineDateIndicatorStyle {
+  /** @defaultValue true */ visible?: boolean;
+  /** Sparse overrides applied only to articles hidden by density filtering. @defaultValue { opacity: 0.25 } */
+  hiddenStyle?: TimelineDateIndicatorStyle;
+  /** Sparse overrides applied only to the active/selected article. @defaultValue { color: 'article', opacity: 1 } */
+  activeStyle?: TimelineDateIndicatorStyle;
+}
+
+export interface TimelineStyleOptions {
+  mainLine?: {
+    /** @defaultValue true */ visible?: boolean;
+    /** @defaultValue 'bottom' */ position?: 'top' | 'bottom';
+    /** thickness in px. @defaultValue 8 */ size?: number;
+    /** Solid CSS colour or a vertical gradient. @defaultValue '#cdd2d8' */
+    color?: string | TimelineStyleMainLineGradient;
+    /** Article date indicators drawn on the main line. */
+    dateIndicators?: TimelineDateIndicatorOptions;
+  };
+  draggingHighlight?: {
+    /** @defaultValue true */ visible?: boolean;
+    /** @defaultValue 'rgba(237, 247, 255, 0.5)' */ color?: string;
+    /** Up/down extents relative to the main line. Accepts px, `'edge'`, or `{ value: 'edge', padding?: number }`.
+     * @defaultValue {up: 0, down: 'edge'}
+     */
+    area?: { up?: AreaValue; down?: AreaValue };
+  };
+  marker?: {
+    minor?: TimelineStyleMarkerKind;
+    major?: TimelineStyleMarkerKind;
+  };
+  dateLabel?: {
+    minor?: {
+      font?: string;
+      color?: string;
+      futureColor?: string;
+      textAlign?: CanvasTextAlign;
+      offset?: { x?: number; y?: number };
+      /** Text appended for BCE labeling. */
+      bceText?: string;
+      /** Thousands separator for large year labels. */
+      thousandsSeparator?: string;
+      /** Map of year-scale prefixes to display (e.g. ka, Ma, Ga). */
+      yearPrefixes?: Record<string, { label: string; value: number; minDivision: number }>;
+    };
+    major?: {
+      font?: string;
+      color?: string;
+      futureColor?: string;
+      textAlign?: CanvasTextAlign;
+      offset?: { x?: number; y?: number };
+      sticky?: {
+        /** Keep the current major label visible at the viewport's left edge. `'auto'` enables this for month-scale and smaller divisions. @defaultValue 'auto' */
+        enabled?: 'auto' | boolean;
+        /** Horizontal inset from the viewport's left edge in px. @defaultValue 4 */
+        offsetX?: number;
+      };
+      bceText?: string;
+      thousandsSeparator?: string;
+      yearPrefixes?: Record<string, { label: string; value: number; minDivision: number }>;
+    };
+    parent?: {
+      /** Enable and reserve space for the parent-context row at every scale. @defaultValue false */
+      visible?: boolean;
+      /** Current major-label levels at which to render parent text. @defaultValue 'all' */
+      levels?: 'all' | Array<
+            | 'millisecond'
+            | 'second'
+            | 'minute'
+            | 'hour'
+            | 'day'
+            | 'month'
+            | 'year'
+            | 'decade'
+            | 'century'
+            | 'millennium'
+          >;
+      /** Reserved row height in px whenever the parent row is enabled. @defaultValue 20 */
+      height?: number;
+      font?: string;
+      color?: string;
+      futureColor?: string;
+      textAlign?: CanvasTextAlign;
+      offset?: { x?: number; y?: number };
+      sticky?: {
+        /** Keep the current parent interval visible at the viewport's left edge. @defaultValue true */
+        enabled?: boolean;
+        /** Horizontal inset from the viewport's left edge in px. @defaultValue 4 */
+        offsetX?: number;
+      };
+    };
+  };
+  cursor?: {
+    clickable?: string;
+    timeline?: { hover?: string; dragging?: string };
+    article?: { hoverDraggable?: string; dragging?: string };
+  };
+}
+
+// ------------------------------------------------------------------------------------
+// Data schemas for loading
+// ------------------------------------------------------------------------------------
+
+export interface ArticleData {
+  id: string | number;
+  title: string;
+  subtitle?: string;
+  lane?: string | number;
+  from: DateInput;
+  to?: DateInput;
+  /** If true, the period ends at the present day. */
+  isToPresent?: boolean;
+  imageUrl?: string;
+  rank?: number;
+  starred?: boolean;
+  hiddenByFilter?: boolean | ((article: Article) => boolean);
+  hidePeriodLine?: boolean | ((article: Article) => boolean);
+  /** Initial offset from computed position (px). */
+  offsetLeft?: number;
+  /** Initial offset from computed position (px). */
+  offsetTop?: number;
+  /** Override default card layout for this article. */
+  cardLayout?: CardLayoutName;
+  style?: ArticleStyle;
+  hoverStyle?: ArticleStyle;
+  activeStyle?: ArticleStyle;
+}
+
+export interface ArticleCardLayoutBreakpoint {
+  maxHeight: number;
+  layout: CardLayoutName;
+}
+
+export interface TimeBandData {
+  id: string | number;
+  title: string;
+  from: DateInput;
+  to?: DateInput;
+  /** If true, the band ends at the present day. */
+  isToPresent?: boolean;
+  /** Visibility of this band: 'visible' | 'hidden' or a function returning one. Defaults to 'visible'. */
+  visibility?: VisibilityState | ((band: TimeBand) => VisibilityState);
+  style?: TimeBandStyle;
+}
+
+export type ChartType = 'line' | 'area';
+export type ChartScaleSource = 'data' | 'viewport';
+export type ChartScaleTickMode = 'round' | 'exact';
+export type ChartAreaStackingInterpolation = 'linear' | 'step' | 'none';
+
+export interface ChartPointData {
+  date: DateInput;
+  value: number | null;
+}
+
+export interface ChartSeriesStyle {
+  color?: string;
+  lineWidth?: number;
+  lineDash?: number[];
+  area?: {
+    fillColor?: string | null;
+    opacity?: number;
+  };
+  point?: {
+    visible?: boolean;
+    radius?: number;
+    fillColor?: string | null;
+    strokeColor?: string | null;
+    lineWidth?: number;
+  };
+}
+
+export interface ChartGridLineStyle {
+  visible?: boolean;
+  color?: string;
+  /** Stroke thickness in canvas pixels. */
+  thickness?: number;
+}
+
+export interface ChartMinorGridLineStyle extends ChartGridLineStyle {
+  /** Hide minor grid lines while the timeline minor unit size is below this many pixels. @defaultValue 20 */
+  minimumSpacing?: number;
+}
+
+export interface ChartGridLineOptions {
+  x?: {
+    major?: ChartGridLineStyle;
+    minor?: ChartMinorGridLineStyle;
+  };
+  y?: {
+    major?: ChartGridLineStyle;
+  };
+}
+
+export interface ChartStyle {
+  padding?: {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+  };
+  backgroundColor?: string;
+  gridLine?: ChartGridLineOptions;
+  axis?: {
+    visible?: boolean;
+    color?: string;
+    lineWidth?: number;
+  };
+  yAxis?: {
+    visible?: boolean;
+    font?: string;
+    color?: string;
+    margin?: number;
+    /** Thousands separator for numeric y-axis labels. Set to null or an empty string to disable. @defaultValue ',' */
+    thousandsSeparator?: string | null;
+    formatter?: ((value: number) => string) | null;
+  };
+  legend?: {
+    visible?: boolean | 'auto';
+    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    font?: string;
+    color?: string;
+    markerSize?: number;
+    markerGap?: number;
+    itemGap?: number;
+    inset?: { x?: number; y?: number };
+  };
+  series?: ChartSeriesStyle;
+}
+
+export interface ChartScaleOptions {
+  /** Use all loaded values or only values inside the current viewport. @defaultValue 'data' */
+  source?: ChartScaleSource;
+  /** Include 0 in the computed domain before padding/fixed bounds. @defaultValue false */
+  includeZero?: boolean;
+  /** Fractional padding applied to auto domains. @defaultValue 0.05 */
+  padding?: number;
+  /** Fixed minimum y value. */
+  min?: number;
+  /** Fixed maximum y value. */
+  max?: number;
+  /** Controls how y-axis tick values are generated. @defaultValue 'round' */
+  tickMode?: ChartScaleTickMode;
+  /** Preferred number of y-axis ticks. Rounded ticks may vary slightly. @defaultValue 5 */
+  tickTarget?: number;
+}
+
+export interface ChartTypeOptions {
+  area?: {
+    stacking?: {
+      /** Enable stacked area rendering. When false, area series fill independently from zero. @defaultValue true */
+      active?: boolean;
+      /** How missing series values are resolved across the shared area x-domain. @defaultValue 'linear' */
+      interpolation?: ChartAreaStackingInterpolation;
+    };
+  };
+}
+
+export interface ChartSeriesData {
+  id?: string | number;
+  title?: string;
+  points?: ChartPointData[];
+  style?: ChartSeriesStyle;
+}
+
+export interface ChartData {
+  id: string | number;
+  type?: ChartType;
+  title?: string;
+  lane?: string | number;
+  visibility?: VisibilityState | ((chart: Chart) => VisibilityState);
+  series?: ChartSeriesData[];
+  scale?: ChartScaleOptions;
+  typeOptions?: ChartTypeOptions;
+  area?: { up?: AreaValue; down?: AreaValue };
+  style?: ChartStyle;
+}
+
+export interface LaneLayout {
+  height?: number;
+  /**
+   * Relative share of the remaining automatic lane height for lanes without a fixed `height`.
+   * Hidden lanes are excluded from the distribution.
+   *
+   * @defaultValue 1
+   */
+  heightWeight?: number;
+  header?: {
+    visible?: boolean;
+    height?: number;
+    padding?: { left?: number; right?: number };
+  };
+}
+
+/** Decorative lane chrome styles. Only explicitly provided values are written inline. */
+export interface LaneStyle {
+  header?: {
+    backgroundColor?: string;
+  };
+  body?: {
+    backgroundColor?: string;
+    borderColor?: string;
+    borderWidth?: number;
+    borderRadius?: number;
+  };
+  title?: {
+    color?: string;
+    font?: string;
+    textAlign?: 'left' | 'center' | 'right';
+  };
+}
+
+export interface DistanceToBaselineResponsiveCardLayoutOptions {
+  /** Fraction of the available content height used to calculate the baseline distance. */
+  ratio?: number;
+  /** Minimum responsive baseline distance in px. */
+  min?: number;
+  /** Maximum responsive baseline distance in px. */
+  max?: number;
+}
+
+export interface DistanceToBaselineResponsiveOptions {
+  /** Enable responsive baseline distance calculations. @defaultValue true */
+  active?: boolean;
+  /**
+   * Restrict responsive baseline calculations to lanes only.
+   * When true, timelines without active lanes use the static `distanceToBaseline.value`.
+   *
+   * @defaultValue true
+   */
+  lanesOnly?: boolean;
+  /**
+   * Responsive baseline settings keyed by the resolved default card layout name.
+   *
+   * @defaultValue `{ portrait: { ratio: 0.6, min: 310, max: 410 }, landscape: { ratio: 0.6, min: 100, max: 160 } }`
+   */
+  byCardLayout?: Partial<Record<CardLayoutName, DistanceToBaselineResponsiveCardLayoutOptions>>;
+}
+
+export interface DistanceToBaselineOptions {
+  /**
+   * Distance of cards from their baseline in px:
+   * the shared timeline axis without lanes, or the lane bottom with lanes.
+   *
+   * @defaultValue 350
+   */
+  value?: number;
+  /** Responsive baseline distance settings. */
+  responsive?: DistanceToBaselineResponsiveOptions;
+}
+
+export interface LaneArticleOverrides {
+  defaultData?: Partial<ArticleData>;
+  /** Lane-local density grouping/filtering input. */
+  density?: ArticleOptions['density'];
+  defaultCardLayout?: CardLayoutName;
+  defaultStyle?: ArticleStyle;
+  defaultHoverStyle?: ArticleStyle;
+  defaultActiveStyle?: ArticleStyle;
+  layoutStyles?: ArticleOptions['layoutStyles'];
+  /** Distance of cards from this lane's baseline in px, plus responsive settings for this lane. */
+  distanceToBaseline?: DistanceToBaselineOptions;
+  /**
+   * @deprecated Deprecated since 1.3.4 — Use `distanceToBaseline.value` instead.
+   */
+  distanceToMainLine?: number;
+  autoStacking?: {
+    /** Enable or disable automatic row assignment for this lane. */
+    active?: boolean;
+    rowSpacing?: number;
+    fitToHeight?: boolean;
+    topGap?: number | ((timeline: Timeline) => number);
+  };
+  periodLine?: {
+    /** Additional gap from the active baseline in px. */
+    baselineGap?: number;
+    /** Gap between stacked period lines in px. */
+    spacing?: number;
+    /** Line thickness in px. */
+    thickness?: number;
+  };
+}
+
+export interface LaneData {
+  id: string | number;
+  title?: string;
+  visibility?: VisibilityState | ((lane: Lane) => VisibilityState);
+  /** Additional CSS class for the lane root beside `histropedia-lane` and `histropedia-lane-index-N`. */
+  className?: string;
+  /** Additional CSS class for the lane header beside `histropedia-lane-header`. */
+  headerClassName?: string;
+  /** Additional CSS class for the lane body beside `histropedia-lane-body`. */
+  bodyClassName?: string;
+  /** Additional CSS class for the lane title beside `histropedia-lane-title`. */
+  titleClassName?: string;
+  layout?: LaneLayout;
+  style?: LaneStyle;
+  article?: LaneArticleOverrides;
+}
+
+// ------------------------------------------------------------------------------------
+// Timeline options
+// ------------------------------------------------------------------------------------
+
+export interface TimelineZoomOptions {
+  /** @defaultValue 34 */ initial?: number;
+  /**
+   * Finest permitted zoom. The default `0` preserves day as the finest unit;
+   * set a negative value to opt in to hour, minute, second, and millisecond zoom.
+   * With all other zoom defaults unchanged, approximately `-82` makes one
+   * millisecond about 200 px wide.
+   * @defaultValue 0
+   */
+  minimum?: number;
+  /** @defaultValue 123 */ maximum?: number;
+  /** Zoom step multiplier per wheel unit. @defaultValue 0.2 */
+  wheelStep?: number;
+  /** Overall wheel speed. @defaultValue 3 */
+  wheelSpeed?: number;
+  /** Allow Ctrl+wheel zoom. @defaultValue false */
+  allowCtrlWheel?: boolean;
+  /** 'auto' picks smooth vs discrete from device; 'discrete' forces stepped. @defaultValue 'auto' */
+  wheelMode?: 'auto' | 'discrete';
+  /** Animate discrete/notched wheel zoom steps. */
+  discreteWheelAnimation?: {
+    /** Enable animated wheel zoom. @defaultValue true */
+    active?: boolean;
+    /** Animation duration in ms. @defaultValue 250 */
+    duration?: number;
+  };
+  /** Gain for proportional (trackpad) mode. @defaultValue 2 */
+  proportionalGain?: number;
+  /** Exponent for proportional (trackpad) mode. @defaultValue 1.1 */
+  proportionalExponent?: number;
+  /** Zoom ratio between unit-size levels. @defaultValue 0.8 */
+  ratio?: number;
+  unitSize?: {
+    /** Size of a day at zoom=0 (and density region size). @defaultValue 200 */
+    initial?: number;
+    /** Spacing threshold to show minor labels and adaptive sub-day subdivisions. @defaultValue 48 */
+    showMinorLabels?: number;
+    /** Minimum unit size in px. @defaultValue 8 */
+    minimum?: number;
+    /** Minimum spacing between sub-day major markers in px. @defaultValue 120 */
+    minimumMajor?: number;
+  };
+}
+
+export interface PanMomentumOptions {
+  /** Continue timeline panning after a drag release. @defaultValue true */
+  active?: boolean;
+  /** Pointer movement sample window in ms used to estimate release velocity. @defaultValue 100 */
+  sampleWindow?: number;
+  /** Minimum release velocity in px/ms before momentum starts. @defaultValue 0.01 */
+  minVelocity?: number;
+  /** Velocity in px/ms at which momentum stops. @defaultValue 0.005 */
+  stopVelocity?: number;
+  /** Exponential friction coefficient per ms. Lower values travel farther. @defaultValue 0.005 */
+  friction?: number;
+  /** Maximum momentum duration in ms. @defaultValue 5600 */
+  maxDuration?: number;
+}
+
+export interface TimelinePanOptions {
+  /** Momentum behaviour after a timeline drag release. */
+  momentum?: PanMomentumOptions;
+}
+
+export interface TimelineDebugOverlayOptions {
+  /** Draw vertical guides at article-density region boundaries. @defaultValue false */
+  densityRegions?: boolean;
+}
+
+export interface ArticleOptions {
+  /** Density filter for visible articles. @defaultValue DENSITY_ALL */
+  density?: Density;
+  /** Rendering alignment shared by built-in cards and their connectors. */
+  rendering?: {
+    /**
+     * Snap to physical device pixels, whole CSS pixels, or retain subpixel coordinates.
+     * `true` is equivalent to `'device'`; `false` is equivalent to `'none'`.
+     * @defaultValue 'device'
+     */
+    pixelSnap?: ArticlePixelSnapMode;
+  };
+  /** Allow dragging event cards. @defaultValue true */
+  draggable?: boolean;
+  /**
+   * Distance of cards from their baseline in px, plus responsive settings.
+   *
+   * Responsive calculations use the resolved default card layout for the timeline or lane.
+   */
+  distanceToBaseline?: DistanceToBaselineOptions;
+  /**
+   * @deprecated Deprecated since 1.3.4 — Use `distanceToBaseline.value` instead.
+   */
+  distanceToMainLine?: number;
+  /** Collect ongoing events on main line. @defaultValue false */
+  collectOngoing?: boolean;
+  /** Auto stacking options. */
+  autoStacking?: {
+    /** @defaultValue true */
+    active?: boolean;
+    /** Distance between rows in px. @defaultValue 50 */
+    rowSpacing?: number;
+    /** Range considered for stacking. @defaultValue RANGE_ALL */
+    range?: AutoStackRange;
+    /** Fit to available height by adjusting rowSpacing. @defaultValue true */
+    fitToHeight?: boolean;
+    /** Top gap in px or a function returning px. @defaultValue 10 */
+    topGap?: number | ((timeline: Timeline) => number);
+  };
+  periodLine?: {
+    /** Anchor period lines to the shared axis or each lane bottom. @defaultValue 'lane' */
+    position?: 'axis' | 'lane';
+    /**
+     * Default value merged into `article.defaultData.hidePeriodLine`.
+     *
+     * @deprecated Deprecated since 1.3.0 — Use `defaultData.hidePeriodLine` instead.
+     */
+    defaultHide?: boolean;
+    /** Additional gap from the active baseline in px. @defaultValue 0 */
+    baselineGap?: number;
+    /** Gap between stacked period lines in px. @defaultValue 4 */
+    spacing?: number;
+    /** Line thickness in px. @defaultValue 10 */
+    thickness?: number;
+    stacking?: {
+      /** Comparator used when assigning period-line stacks. */
+      sorter?: ArticleSorter;
+      /** Reverse stacking order. @defaultValue false */
+      reverseOrder?: boolean;
+    };
+  };
+  animation?: {
+    fade?: { active?: boolean; duration?: number; easing?: EasingName };
+    move?: { active?: boolean; duration?: number; easing?: EasingName };
+  };
+  star?: { /** Show star icon. @defaultValue true */ visible?: boolean };
+  /** Default data merged into every loaded article. */
+  defaultData?: Partial<ArticleData>;
+  /** Fallback card layout name used when no breakpoint matches. @defaultValue 'portrait' */
+  defaultCardLayout?: CardLayoutName;
+  /** Ordered max-height overrides evaluated before falling back to `defaultCardLayout`. */
+  cardLayoutBreakpoints?: ArticleCardLayoutBreakpoint[];
+  /** Explicit timeline-wide styles applied after the selected layout's registered defaults. */
+  defaultStyle?: ArticleStyle;
+  defaultHoverStyle?: ArticleStyle;
+  defaultActiveStyle?: ArticleStyle;
+  /** Explicit per-layout overrides applied after the generic style at the same scope. */
+  layoutStyles?: Record<
+    string,
+    Partial<{
+      style: ArticleStyle;
+      hoverStyle: ArticleStyle;
+      activeStyle: ArticleStyle;
+    }>
+  >;
+}
+
+/** Pixels from the main line, the `'edge'` keyword, or `{ value: 'edge', padding?: number }` for edge-stretching with padding. */
+export type AreaValue = number | 'edge' | { value: 'edge'; padding?: number };
+
+export interface TimeBandOptions {
+  /** Enable drawing of bands. @defaultValue true */
+  visible?: boolean;
+  /** Reserve extra space near main line when bands are present. @defaultValue true */
+  reserveSpace?: boolean;
+  /** Pixels to reserve when reserveSpace is true. @defaultValue 20 */
+  reserveSpacePixels?: number;
+  /** Up/down extents of the band area relative to the main line. Accepts px, `'edge'`, or `{ value: 'edge', padding?: number }`. @defaultValue {up: 0, down: 'edge'} */
+  area?: { up?: AreaValue; down?: AreaValue };
+  /** Global default style merged into each band. */
+  defaultStyle?: TimeBandStyle;
+  /** Bands to load initially. */
+  data?: TimeBandData[];
+}
+
+export interface ChartOptions {
+  /** Enable drawing of loaded charts. @defaultValue true */
+  visible?: boolean;
+  /** Main-view chart area relative to the shared axis. Lane-scoped charts use lane body geometry. */
+  area?: { up?: AreaValue; down?: AreaValue };
+  /**
+   * Colors assigned cyclically to series without an explicit or shared style color.
+   * @defaultValue ['#2563eb', '#dc2626', '#16a34a', '#9333ea', '#ea580c', '#0891b2', '#be123c', '#4f46e5']
+   */
+  seriesColors?: string[];
+  /**
+   * Global chart grid-line defaults merged into each chart style.
+   * @deprecated Use `defaultStyle.gridLine` instead.
+   */
+  gridLine?: ChartGridLineOptions;
+  /** Default data merged into every loaded chart. */
+  defaultData?: Partial<ChartData>;
+  /** Global default chart style merged into each chart. */
+  defaultStyle?: ChartStyle;
+  /** Charts to load initially. */
+  data?: ChartData[];
+}
+
+export interface LaneOptions {
+  /**
+   * Enable lane DOM chrome. Article layout still remains lane-aware when lane data is present.
+   * @defaultValue true
+   */
+  visible?: boolean;
+  /** Default lane id used when an article does not specify `lane`. @defaultValue 'default' */
+  defaultId?: string | number;
+  /** Gap between rendered lanes in px. @defaultValue 0 */
+  gap?: number;
+  /** Space reserved above the topmost lane in px. @defaultValue 0 */
+  topGap?: number;
+  /** Space between the painted edge of the shared main line and the lane area in px. @defaultValue 0 */
+  axisGap?: number;
+  /** Global default lane layout merged into each lane. */
+  defaultLayout?: LaneLayout;
+  /** Global default lane style merged into each lane. Only explicitly provided values are written inline. */
+  defaultStyle?: LaneStyle;
+  /** CSS class added to each lane root element beside `histropedia-lane` and `histropedia-lane-index-N`. */
+  defaultClassName?: string;
+  /** CSS class added to each lane header element beside `histropedia-lane-header`. */
+  defaultHeaderClassName?: string;
+  /** CSS class added to each lane body element beside `histropedia-lane-body`. */
+  defaultBodyClassName?: string;
+  /** CSS class added to each lane title element beside `histropedia-lane-title`. */
+  defaultTitleClassName?: string;
+  /** Lanes to load initially. */
+  data?: LaneData[];
+}
+
+/**
+ * Image loading and URL sanitization options.
+ *
+ * By default, the built-in sanitizer allows http, https, data:image/* and blob:.
+ * You can restrict schemes and/or remote origins, or provide a custom sanitizer.
+ */
+export type ImageDecodeMode = 'auto' | 'prefer-bitmap' | 'bitmap' | 'prefer-img' | 'img';
+
+export interface ImageSanitizerOptions {
+  /**
+   * Allowed URL schemes for images.
+   * @defaultValue ['http', 'https', 'data', 'blob']
+   */
+  allowedSchemes?: string[];
+
+  /**
+   * Allowed origins/hosts for remote images. Supports full origins, bare hostnames,
+   * leading-dot, and wildcard-prefixed (`*.example.com`) entries.
+   */
+  allowedOrigins?: string[];
+}
+
+export interface ImageOptions {
+  /**
+   * Built-in URL sanitization controls.
+   */
+  sanitizer?: ImageSanitizerOptions;
+
+  /**
+   * Optional override for image URL sanitization. Receives the raw URL and the
+   * current sanitizer configuration from `image.sanitizer`. Return a trusted URL
+   * string to allow the load or null to block it.
+   */
+  customSanitizer?: (url: string, options: ImageSanitizerOptions) => string | null;
+
+  /**
+   * Maximum number of concurrent image fetch/decode operations. Values < 1 are clamped to 1.
+   * @defaultValue 6
+   */
+  maxConcurrent?: number;
+
+  /**
+   * Maximum decoded raster memory (in bytes) retained by the image cache.
+   * Set to `Infinity` to disable eviction, or reduce to bound memory usage.
+   * @defaultValue 64 * 1024 * 1024 (64 MiB)
+   */
+  maxCacheBytes?: number;
+
+  /**
+   * Force cross-origin requests to opt-in via CORS (sets `crossOrigin = 'anonymous'`).
+   * When true, images served without CORS headers will fail to load but canvas readbacks
+   * remain untainted.
+   * @defaultValue false
+   */
+  requireCORS?: boolean;
+
+  /**
+   * Controls how raster data is produced once an image loads.
+   *
+   * - 'auto' (default) prefers ImageBitmap when supported, falling back to `<img>`.
+   * - 'prefer-bitmap' aggressively tries ImageBitmap but falls back to `<img>` if needed.
+   * - 'bitmap' requires ImageBitmap support and treats failures as errors.
+   * - 'prefer-img' keeps `<img>` unless decoding fails, then falls back to ImageBitmap.
+   * - 'img' forces `<img>` and never calls `createImageBitmap`.
+   */
+  decodeMode?: ImageDecodeMode;
+}
+
+export interface TimelineDateBoundsOptions {
+  /** Earliest allowed visible viewport edge. @defaultValue null */
+  minDate?: DateValue | null;
+  /** Latest allowed visible viewport edge. @defaultValue null */
+  maxDate?: DateValue | null;
+  /**
+   * Boundary behaviour during active user interaction.
+   * - 'elastic': allow resisted temporary overflow and settle back when interaction ends.
+   * - 'clamp': prevent overflow immediately.
+   * @defaultValue 'elastic'
+   */
+  overflow?: 'elastic' | 'clamp';
+}
+
+export interface TimelineOptions {
+  /** Canvas width in px. @defaultValue 1000 */
+  width?: number;
+  /** Canvas height in px. @defaultValue 500 */
+  height?: number;
+  /** Canvas/backing-store configuration. */
+  canvas?: {
+    /** Device pixel ratio to use; 'auto' follows device. @defaultValue 'auto' */ dpr?:
+      | 'auto'
+      | number;
+    /**
+     * Behaviour for dpr:'auto'.
+     * - 'stable' (default) rounds devicePixelRatio up to the nearest integer.
+     * - 'native' uses the raw devicePixelRatio value.
+     * @defaultValue 'stable'
+     */
+    dprMode?: 'stable' | 'native';
+    /** Maximum DPR to apply for performance. @defaultValue 3 */ maxDpr?: number;
+  };
+  /** Per-timeline visual diagnostics. Independent from global debug logging. */
+  debugOverlays?: TimelineDebugOverlayOptions;
+  /** Vertical offset of the main line in px. @defaultValue 40 */
+  verticalOffset?: number;
+  /** Enable user interactions (wheel/drag/pinch). @defaultValue true */
+  enableUserControl?: boolean;
+  /** Show interactive cursors. @defaultValue true */
+  enableCursor?: boolean;
+  /** Zoom configuration. */
+  zoom?: TimelineZoomOptions;
+  /** Initial date/time (top-left when position not offset). @defaultValue {year:1990,month:1,day:1} */
+  initialDate?: DateValue;
+  /**
+   * Optional visible viewport date bounds. Bounds constrain viewport edges, not only the centre date.
+   * With both dates set, the settled viewport stays within `[minDate, maxDate]`.
+   */
+  bounds?: TimelineDateBoundsOptions;
+  /** Shift BCE input dates by +1 so 1BCE = year 0 internally. @defaultValue false */
+  shiftBceDates?: boolean;
+  /** Hide the built-in Histropedia branding/footer links. Defaults to false when omitted. */
+  disableBranding?: boolean;
+  /**
+   * Drag activation vicinity near the main line.
+   * - boolean: enable/disable dragging anywhere on the timeline
+   * - function: (event, relativePosition) => boolean; return true to allow dragging
+   *   where relativePosition is { left: number; top: number }
+   * - object: { up?: number; down?: number } in pixels from the main line;
+   *   an omitted side extends to the corresponding canvas edge
+   * @defaultValue true
+   */
+  draggingVicinity?:
+    | boolean
+    | ((event: PointerEvent, relativePosition: { left: number; top: number }) => boolean)
+    | { up?: number; down?: number };
+  /** Timeline panning configuration. */
+  pan?: TimelinePanOptions;
+  /** Canvas/UI styling. */
+  style?: TimelineStyleOptions;
+  /** Time band configuration. */
+  timeBand?: TimeBandOptions;
+  /** Chart layer configuration. */
+  chart?: ChartOptions;
+  /** Lane configuration. */
+  lane?: LaneOptions;
+  /** Article configuration. */
+  article?: ArticleOptions;
+  /** Configure image sanitization, caching, and loader behaviour. */
+  image?: ImageOptions;
+  /** Register event handlers via object literal: { 'article-click': fn, ... } */
+  on?: Partial<EventHandlerMap>;
+  /**
+   * Called after every draw pass.
+   *
+   * @deprecated Deprecated since 1.3.0 — Use `on['timeline-render-end']` instead.
+   */
+  onRedraw?: (ctx: RedrawContext) => void;
+  /**
+   * Article click handler configured via this option.
+   *
+   * @deprecated Deprecated since 1.3.0 — Use `on['article-click']` for click events or `on['article-select']` for selection by any means.
+   */
+  onArticleClick?: (article: Article, event?: Event) => void;
+  /**
+   * Article double click handler configured via this option.
+   *
+   * @deprecated Deprecated since 1.3.0 — Use `on['article-dblclick']` instead.
+   */
+  onArticleDoubleClick?: (article: Article, event?: Event) => void;
+  /**
+   * Timeline save handler configured via this option.
+   *
+   * @deprecated Deprecated since 1.3.0 — Use `on['timeline-state-change']` instead.
+   */
+  onSave?: (state: string) => void;
+}
+
+// ------------------------------------------------------------------------------------
+// Events
+// ------------------------------------------------------------------------------------
+
+/** Token produced by the timescale manager for marker drawing and viewport drag payloads. */
+export interface TimelineToken {
+  unit: ZoomLevel;
+  value: DmyInstance;
+  length: number;
+  label?: string;
+  type?: MarkerType;
+  drawX?: number;
+}
+
+export interface ZoomPayload {
+  zoom: number;
+  zoomDelta: number;
+}
+export interface WheelPayload {
+  centre: { x: number; y: number };
+  zoom: number;
+  zoomDelta: number;
+}
+export interface PinchPayload {
+  centre: { x: number; y: number } | null;
+  scale: number;
+  zoom: number;
+  distance: number;
+  zoomDelta: number;
+  dx?: number;
+  totalZoomDelta: number;
+  pointers: PointerEvent[];
+}
+export interface ViewportDragPayload {
+  startToken: TimelineToken;
+  offsetX: number;
+  dx?: number;
+  totalDx?: number;
+}
+export interface TimelineClickPayload {
+  viewport: { x: number; y: number };
+}
+export interface DragDelta {
+  dx: number;
+  dy: number;
+  totalDx: number;
+  totalDy: number;
+}
+
+/** Token cache exposed to redraw hooks for advanced positioning work. */
+export interface RedrawCycleContext {
+  tokens: {
+    start: DmyInstance;
+    end: DmyInstance;
+    [tokenKey: string]: DmyInstance | number;
+  };
+}
+
+/** Data delivered to redraw lifecycle handlers. */
+export interface RedrawContext {
+  canvasContext: CanvasRenderingContext2D;
+  /** Present for timeline-render-end; omitted for timeline-render-start. */
+  drawCycleContext?: RedrawCycleContext;
+  top: number;
+}
+
+export interface EventPayloadMap {
+  // zoom
+  zoom: [ZoomPayload];
+  'zoom-wheel': [WheelPayload, WheelEvent];
+  'zoom-pinch-start': [PinchPayload, PointerEvent];
+  'zoom-pinch': [PinchPayload, PointerEvent];
+  'zoom-pinch-end': [PinchPayload, PointerEvent];
+  // viewport
+  'viewport-drag-start': [ViewportDragPayload, PointerEvent];
+  'viewport-drag': [ViewportDragPayload, PointerEvent];
+  'viewport-drag-end': [ViewportDragPayload, PointerEvent];
+  // articles
+  'article-pointerenter': [Article, PointerEvent];
+  'article-pointermove': [Article, PointerEvent];
+  'article-pointerleave': [Article, PointerEvent];
+  'article-click': [Article, PointerEvent];
+  'article-dblclick': [Article, PointerEvent];
+  'article-select': [Article];
+  'article-drag-start': [Article, PointerEvent];
+  'article-drag': [Article, DragDelta, PointerEvent];
+  'article-drag-end': [Article, PointerEvent];
+  // timeline
+  'timeline-render-start': [RedrawContext];
+  'timeline-render-end': [RedrawContext];
+  'timeline-click': [TimelineClickPayload, PointerEvent];
+  'timeline-dblclick': [TimelineClickPayload, PointerEvent];
+  'timeline-state-change': [string];
+}
+
+export type TimelineEvent = keyof EventPayloadMap;
+export type EventHandlerMap = { [K in TimelineEvent]: (...args: EventPayloadMap[K]) => void };
+
+/** Backward-compatible alias for the article instance passed as `this` to card layout hooks. */
+export type CardLayoutArticleContext = Article;
+
+/** Full card layout definition stored by the runtime registry. */
+export interface RegisteredCardLayout {
+  name: string;
+  draw(this: Article, ctx: CanvasRenderingContext2D): void;
+  getWidth?(this: Article): number;
+  getHeight?(this: Article): number;
+  getIconBox?(this: Article): CardLayoutIconBox | false;
+  defaultStyle?: ArticleStyle;
+  defaultHoverStyle?: ArticleStyle;
+  defaultActiveStyle?: ArticleStyle;
+}
+
+/** Alias definition that points one layout name at another registered layout. */
+export interface CardLayoutAliasDefinition {
+  name: string;
+  aliasOf: CardLayoutName;
+}
+
+/** Definition accepted by `Timeline.registerCardLayout(...)`. */
+export type CardLayoutDefinition = RegisteredCardLayout | CardLayoutAliasDefinition;
+
+// ------------------------------------------------------------------------------------
+// Classes
+// ------------------------------------------------------------------------------------
+
+export interface AnimOptions {
+  /** Duration in ms. @defaultValue 2000 */ duration?: number;
+  /** Easing name. @defaultValue 'swing' */ easing?: EasingName;
+  /** Callback when animation completes. */ complete?: () => void;
+  /** Additional horizontal shift, used by pinch. */ offsetX?: number;
+}
+
+export type FitDateRangePadding = number | { left?: number; right?: number };
+
+export interface FitDateRangeAnimationOptions {
+  /** Enable simultaneous animated zooming and panning. @defaultValue false */
+  active?: boolean;
+  /** Duration in ms. Inherits the viewport animation default when omitted. */
+  duration?: number;
+  /** Easing name. Inherits the viewport animation default when omitted. */
+  easing?: EasingName;
+}
+
+export interface FitDateRangeOptions {
+  /** Edge padding in px, or per-side padding for asymmetric fits. @defaultValue 0 */
+  padding?: FitDateRangePadding;
+  /** Optional animation settings for the fit. */
+  animation?: FitDateRangeAnimationOptions;
+}
+
+export interface SetStartDateOptions {
+  /** Left padding in px for the supplied start date. This only affects the left side. @defaultValue 0 */
+  padding?: number;
+  /** Optional animation settings matching `fitDateRange(..., { animation })`. */
+  animation?: FitDateRangeAnimationOptions;
+}
+
+export interface FitArticleRangeOptions {
+  /** Edge padding in px, or per-side padding for asymmetric fits. @defaultValue 0 */
+  padding?: FitDateRangePadding;
+  /** Optional animation settings for the fit. */
+  animation?: FitDateRangeAnimationOptions;
+}
+
+export interface FitArticlesOptions {
+  /** Space in px between the outermost fitted article cards and the viewport edge. @defaultValue 40 */
+  padding?: FitDateRangePadding;
+  /** Optional article predicate. Defaults to fitting articles that are not `hiddenByFilter`. */
+  articleFilter?: (article: Article) => boolean;
+  /** Optional animation settings for the fit. */
+  animation?: FitDateRangeAnimationOptions;
+}
+
+export class Timeline {
+  /**
+   * Create a timeline bound to an existing canvas element or a container element (a canvas will be created).
+   * @example
+   * const tl = new Timeline(containerEl, { initialDate: { year: 1066, month: 10, day: 14 } });
+   */
+  constructor(container: HTMLCanvasElement | HTMLElement, options?: TimelineOptions);
+
+  /** Root canvas used for rendering. */
+  readonly canvas: HTMLCanvasElement;
+  /** 2D drawing context bound to `canvas`. */
+  readonly canvasContext: CanvasRenderingContext2D;
+  /** Current merged runtime options. */
+  options: TimelineOptions;
+  /** User-visible title used by serialized state helpers. */
+  title: string;
+  /** Current y-coordinate of the timeline baseline in canvas pixels. */
+  top: number;
+  readonly articles: Article[];
+  readonly lanes: Lane[];
+  readonly timeBands: TimeBand[];
+  readonly charts: Chart[];
+
+  /** Register a reusable card layout globally for all timelines. */
+  static registerCardLayout(definition: CardLayoutDefinition): void;
+  /** Resolve a previously registered card layout by name. */
+  static getCardLayout(name: CardLayoutName): RegisteredCardLayout | null;
+
+  // Data loading
+  /** Load articles and redraw. */
+  load(articles: ArticleData[]): void;
+  /** Load lanes and redraw. */
+  loadLanes(lanes: LaneData[]): void;
+  /** Load time bands and redraw. */
+  loadTimeBands(bands: TimeBandData[]): void;
+  /** Load new charts and redraw; duplicate ids are skipped with a warning. */
+  loadCharts(charts: ChartData[]): void;
+  /** Remove a chart by id and redraw when found. */
+  removeChart(id: string | number): boolean;
+  /** Remove all loaded charts and redraw. */
+  clearCharts(): void;
+  /** Stamp a lane id onto a batch of charts, load them, and redraw. */
+  loadLaneCharts(laneId: string | number, charts: ChartData[]): void;
+  /** Stamp a lane id onto a batch of articles, load them, and redraw. */
+  loadLaneArticles(laneId: string | number, articles: ArticleData[]): void;
+
+  // Query
+  getArticleById(id: string | number): Article | undefined;
+  getActiveArticle(): Article | null;
+  getLaneById(id: string | number): Lane | undefined;
+  getChartById(id: string | number): Chart | undefined;
+  hasArticle(id: string | number): boolean;
+
+  // Selection and ordering
+  bringFront(articleId: string | number): void;
+  /** Selects and brings the article to the front; emits 'article-select'. */
+  select(articleId: string | number): void;
+  /** Reorder articles to match the array of ids (topmost last). */
+  reorderArticles(ids: Array<string | number>): void;
+  /** Move a lane to a public lane index where 0 is nearest the axis. */
+  moveLaneToIndex(lane: Lane | string | number, index: number): Lane;
+  /** Move lane so it ends up immediately before targetLane. */
+  moveLaneBefore(lane: Lane | string | number, targetLane: Lane | string | number): Lane;
+  /** Move lane so it ends up immediately after targetLane. */
+  moveLaneAfter(lane: Lane | string | number, targetLane: Lane | string | number): Lane;
+  /** Move lane one position farther from the axis. */
+  moveLaneUp(lane: Lane | string | number): Lane;
+  /** Move lane one position closer to the axis. */
+  moveLaneDown(lane: Lane | string | number): Lane;
+  /** Update the serializable title stored by `getStatusForSave()`. */
+  setTitle(title: string): void;
+
+  // Navigation & view
+  /** Set start date (left edge). Accepts Dmy-compatible objects or ISO-like date/time strings. */
+  setStartDate(date: DateValue, options?: SetStartDateOptions): void;
+  /** @deprecated Use `setStartDate(date, { padding })` instead. */
+  setStartDate(date: DateValue, pixelOffset?: number): void;
+  /** Set centre date using startDate + offset computation. */
+  setCentreDate(date: DateValue, pixelOffset?: number): void;
+  /** Current zoom value. */
+  getZoom(): number;
+  /** Set zoom (optionally pivoting around a pixel). */
+  setZoom(zoom: number, pivotPixel?: number, offsetX?: number): void;
+  /** Smooth pan by pixels (negative = right). */
+  goToPixelAnim(pixels: number, options?: AnimOptions): void;
+  /** @deprecated Use `setStartDate(dmy, { padding, animation: { active: true, ... } })` instead. */
+  goToDateAnim(dmy: DateValue, options?: AnimOptions): void;
+  /** Fit a date range into the viewport with optional edge padding. Dates may be passed in either order; year-only and month-only inputs are treated as full periods. */
+  fitDateRange(
+    start: FitDateRangeInput,
+    end: FitDateRangeInput,
+    options?: FitDateRangeOptions,
+  ): void;
+  /** Fit a single article's full period into the viewport using `article.period.from` and `article.period.to`. */
+  fitArticleRange(article: Article, options?: FitArticleRangeOptions): boolean;
+  /** Fit currently unfiltered article cards into the viewport using each article's start date, card width, and connector offset. */
+  fitArticles(options?: FitArticlesOptions): boolean;
+  /** Animate to an absolute zoom value using the built-in tween. */
+  zoomToAnim(newZoom: number, complete?: () => void): void;
+
+  // Drawing
+  /** Request a redraw (coalesced if an animation is running). */
+  requestRedraw(redrawFunction?: () => void): void;
+  /** Full draw cycle. */
+  redraw(): void;
+  /** Reposition-only draw (for zoom/start-date changes). */
+  repositionRedraw(): void;
+  /** Default draw including reposition and stacking. */
+  defaultRedraw(): void;
+  /** Toggle auto fit-to-height for article stacking and return the new enabled state. */
+  toggleAutoFit(): boolean;
+  /** Recompute row spacing so visible rows fit in the available height. */
+  fitToHeight(withRedraw?: boolean): number | undefined;
+  /**
+   * @deprecated Deprecated since 1.3.0 — Use `timeline.on('timeline-render-end', handler)` instead.
+   */
+  onRedraw(handler: (ctx: RedrawContext) => void): void;
+
+  // Interaction toggles
+  enableZoomByWheel(): void;
+  disableZoomByWheel(): void;
+
+  // Misc utilities
+  /** Current canvas width in CSS pixels. */
+  getWidth(): number;
+  /** Current applied device pixel ratio for the canvas. */
+  getCanvasDpr(): number;
+  /** Get canvas-relative coordinates for a DOM event. */
+  getRelativePosition(evt: MouseEvent | PointerEvent | TouchEvent): { left: number; top: number };
+
+  // Options
+  /** Get or set options via dot-path or partial object. */
+  setOption(path: string, value: unknown): void;
+  setOption<T extends DeepPartial<TimelineOptions>>(patch: T): void;
+  setOption(path: string): unknown;
+  /** Resize the canvas. */
+  setSize(width: number, height: number): void;
+  /** Serialize the current timeline state to the legacy compact JSON string. */
+  getStatusForSave(): string;
+  /** Register a reusable card layout from an instance. Delegates to the static method. */
+  registerCardLayout(definition: CardLayoutDefinition): void;
+  /** Resolve a previously registered card layout by name. */
+  getCardLayout(name: CardLayoutName): RegisteredCardLayout | null;
+
+  // Event bus
+  on<T extends TimelineEvent>(event: T, handler: (...args: EventPayloadMap[T]) => void): void;
+  on(event: string, handler: (...args: any[]) => void): void;
+  off<T extends TimelineEvent>(event: T, handler: (...args: EventPayloadMap[T]) => void): void;
+  off(event: string, handler: (...args: any[]) => void): void;
+  /**
+   * Trigger a built-in or custom event.
+   * Custom event payloads are intentionally untyped because the runtime does not enforce a schema.
+   */
+  trigger<T extends TimelineEvent>(event: T, ...args: EventPayloadMap[T]): void;
+  trigger(event: string, ...args: any[]): void;
+}
+
+export class Article {
+  /** Stable article identifier. */
+  id: string | number;
+  /** Owning timeline instance. */
+  owner: Timeline;
+  /** Latest runtime data backing this article. */
+  data: ArticleData;
+  title: string;
+  subtitle: string;
+  rank: number;
+  laneId: string | number | null;
+  cardLayout: CardLayoutName | null;
+  period: ArticlePeriod;
+  position: CanvasPosition;
+  registeredPosition: CanvasPosition;
+  offset: CanvasPosition;
+  finalOffset: CanvasPosition;
+  indicator: ArticleIndicator;
+  row: number;
+  image: CanvasImageSource | null;
+  imageLoaded: boolean;
+  style: ArticleStyle;
+  hoverStyle: ArticleStyle;
+  activeStyle: ArticleStyle;
+  activeHoverStyle: ArticleStyle;
+  opacity: number;
+  isActive: boolean;
+  isVisible: boolean;
+  isDragging: boolean;
+  isStarred: boolean;
+  isMouseover: boolean;
+  hiddenByFilter: boolean;
+  isDataLoaded: boolean;
+
+  /** Update article data at runtime (dot-path or object). */
+  setOption(path: string, value: unknown): void;
+  setOption(patch: Partial<ArticleData>): void;
+  setOption(path: string): unknown;
+
+  /** Update normal style (dot-path or object). */
+  setStyle(path: string, value: unknown): void;
+  setStyle(style: Partial<ArticleStyle>): void;
+  setStyle(path: string): unknown;
+
+  /** Update hover style (dot-path or object). */
+  setHoverStyle(path: string, value: unknown): void;
+  setHoverStyle(style: Partial<ArticleStyle>): void;
+  setHoverStyle(path: string): unknown;
+
+  /** Update active style (dot-path or object). */
+  setActiveStyle(path: string, value: unknown): void;
+  setActiveStyle(style: Partial<ArticleStyle>): void;
+  setActiveStyle(path: string): unknown;
+
+  /** Move instantly to absolute canvas position. */
+  moveTo(position: { left: number; top: number }): void;
+  /** Move by delta from current position. */
+  moveToOffset(offset: { left: number; top: number }): void;
+  /** Override the card layout used by this article. */
+  setCardLayout(cardLayout: CardLayoutName): void;
+  /** Small per-layout memoization helper. */
+  memo<T>(key: string, factory: () => T): T;
+  /** Clear cached measurements/layout artifacts for this article. */
+  invalidateCaches(): void;
+  /** Resolve the rectangular star hover/click area, or `false` when none is present. */
+  getIconBox(): CardLayoutIconBox | false;
+
+  /** Fully merged style for the current normal, hover, active, or active-hover state. */
+  getCurrentStyle(): ArticleStyle;
+
+  /** Measured card width. */
+  getWidth(): number;
+  /** Measured card height. */
+  getHeight(): number;
+}
+
+export class TimeBand {
+  id: string | number;
+  owner: Timeline;
+  data: TimeBandData;
+  title: string;
+  style: TimeBandStyle;
+  period: TimeBandPeriod;
+  visibility: VisibilityState;
+
+  /** Update band data at runtime (dot-path or object). */
+  setOption(path: string, value: unknown): void;
+  setOption(patch: Partial<TimeBandData>): void;
+  setOption(path: string): unknown;
+
+  /** Update band style (dot-path or object). */
+  setStyle(path: string, value: unknown): void;
+  setStyle(style: Partial<TimeBandStyle>): void;
+  setStyle(path: string): unknown;
+}
+
+export class Chart {
+  id: string | number;
+  owner: Timeline;
+  data: ChartData;
+  type: ChartType;
+  title: string;
+  laneId: string | number | null;
+  area: { up?: AreaValue; down?: AreaValue } | null;
+  scale: ChartScaleOptions;
+  typeOptions: ChartTypeOptions;
+  style: ChartStyle;
+  series: Array<{
+    id: string | number;
+    title: string;
+    style: ChartSeriesStyle;
+    points: Array<{ date: DmyInstance; value: number | null }>;
+  }>;
+  visibility: VisibilityState;
+
+  /** Add one series to this chart and redraw. */
+  addSeries(series: ChartSeriesData): void;
+
+  /** Remove one series by id and redraw when found. */
+  removeSeriesById(id: string | number): boolean;
+
+  /** Return the normalized runtime series with this id. */
+  getSeriesById(id: string | number):
+    | {
+        id: string | number;
+        title: string;
+        style: ChartSeriesStyle;
+        points: Array<{ date: DmyInstance; value: number | null }>;
+      }
+    | undefined;
+
+  /** Update chart data at runtime (dot-path or object). */
+  setOption(path: string, value: unknown): void;
+  setOption(patch: Partial<Omit<ChartData, 'id'>>): void;
+  setOption(path: string): unknown;
+
+  /** Update chart style (dot-path or object). */
+  setStyle(path: string, value: unknown): void;
+  setStyle(style: Partial<ChartStyle>): void;
+  setStyle(path: string): unknown;
+
+  /** Resolve the active y-domain for the chart. */
+  getScaleDomain(drawCycleContext?: RedrawCycleContext): { min: number; max: number };
+}
+
+export class Lane {
+  id: string | number;
+  owner: Timeline;
+  data: LaneData;
+  title: string;
+  layout: LaneLayout;
+  style: LaneStyle;
+  order: number;
+  isImplicit: boolean;
+  visibility: VisibilityState;
+
+  /** Update lane data at runtime (dot-path or object). */
+  setOption(path: string, value: unknown): void;
+  setOption(patch: Partial<LaneData>): void;
+  setOption(path: string): unknown;
+
+  /** Hide the lane by setting visibility to "hidden". */
+  hide(): void;
+
+  /** Show the lane by setting visibility to "visible". */
+  show(): void;
+
+  /** Move this lane to a public lane index where 0 is nearest the axis. */
+  moveToIndex(index: number): Lane;
+
+  /** Move this lane so it ends up immediately before targetLane. */
+  moveBefore(targetLane: Lane | string | number): Lane;
+
+  /** Move this lane so it ends up immediately after targetLane. */
+  moveAfter(targetLane: Lane | string | number): Lane;
+
+  /** Move this lane one position farther from the axis. */
+  moveUp(): Lane;
+
+  /** Move this lane one position closer to the axis. */
+  moveDown(): Lane;
+
+  /** Update lane style (dot-path or object). */
+  setStyle(path: string, value: unknown): void;
+  setStyle(style: Partial<LaneStyle>): void;
+  setStyle(path: string): unknown;
+}
+
+/** Built-in sorter signature used by stacking and layout helpers. */
+export type ArticleSorter = (articleA: any, articleB: any) => number;
+
+export const ARTICLE_DURATION_SORTER: ArticleSorter;
+export const ARTICLE_DURATION_YEARS_SORTER: ArticleSorter;
+export const ARTICLE_IMAGE_QUEUE_SORTER: ArticleSorter;
+export const ARTICLE_FROM_SORTER: ArticleSorter;
+export const ARTICLE_TO_SORTER: ArticleSorter;
+export const ARTICLE_TOP_SORTER: ArticleSorter;
+export const ARTICLE_ROW_SORTER: ArticleSorter;
+export const ARTICLE_RANK_SORTER: ArticleSorter;
+export const ARTICLE_EFFECTIVE_RANK_SORTER: ArticleSorter;
+export const ARTICLE_POSITION_SORTER: ArticleSorter;
+
+// ------------------------------------------------------------------------------------
+// Default export for UMD / ESM default
+// ------------------------------------------------------------------------------------
+
+export interface HistropediaApi {
+  Timeline: typeof Timeline;
+  Article: typeof Article;
+  Chart: typeof Chart;
+  Lane: typeof Lane;
+  TimeBand: typeof TimeBand;
+  Dmy: DmyConstructor;
+  Logger: LoggerInstance;
+  setDebug(enabled: boolean): void;
+  isDebugEnabled(): boolean;
+  enableDebug(): void;
+  disableDebug(): void;
+  ARTICLE_DURATION_SORTER: typeof ARTICLE_DURATION_SORTER;
+  ARTICLE_DURATION_YEARS_SORTER: typeof ARTICLE_DURATION_YEARS_SORTER;
+  ARTICLE_IMAGE_QUEUE_SORTER: typeof ARTICLE_IMAGE_QUEUE_SORTER;
+  ARTICLE_FROM_SORTER: typeof ARTICLE_FROM_SORTER;
+  ARTICLE_TO_SORTER: typeof ARTICLE_TO_SORTER;
+  ARTICLE_TOP_SORTER: typeof ARTICLE_TOP_SORTER;
+  ARTICLE_ROW_SORTER: typeof ARTICLE_ROW_SORTER;
+  ARTICLE_RANK_SORTER: typeof ARTICLE_RANK_SORTER;
+  ARTICLE_EFFECTIVE_RANK_SORTER: typeof ARTICLE_EFFECTIVE_RANK_SORTER;
+  ARTICLE_POSITION_SORTER: typeof ARTICLE_POSITION_SORTER;
+  MINOR_MARKER: typeof MINOR_MARKER;
+  MAJOR_MARKER: typeof MAJOR_MARKER;
+  ERA_MARKER: typeof ERA_MARKER;
+  ZOOM_DAY: typeof ZOOM_DAY;
+  ZOOM_HOUR: typeof ZOOM_HOUR;
+  ZOOM_MINUTE: typeof ZOOM_MINUTE;
+  ZOOM_SECOND: typeof ZOOM_SECOND;
+  ZOOM_MILLISECOND: typeof ZOOM_MILLISECOND;
+  ZOOM_MONTH: typeof ZOOM_MONTH;
+  ZOOM_YEAR: typeof ZOOM_YEAR;
+  ZOOM_DECADE: typeof ZOOM_DECADE;
+  ZOOM_CENTURY: typeof ZOOM_CENTURY;
+  ZOOM_MILLENNIUM: typeof ZOOM_MILLENNIUM;
+  ZOOM_10_THOUSAND_YEARS: typeof ZOOM_10_THOUSAND_YEARS;
+  ZOOM_100_THOUSAND_YEARS: typeof ZOOM_100_THOUSAND_YEARS;
+  ZOOM_MILLION_YEARS: typeof ZOOM_MILLION_YEARS;
+  ZOOM_10_MILLION_YEARS: typeof ZOOM_10_MILLION_YEARS;
+  ZOOM_100_MILLION_YEARS: typeof ZOOM_100_MILLION_YEARS;
+  ZOOM_BILLION_YEARS: typeof ZOOM_BILLION_YEARS;
+  YEAR_PREFIXES: typeof YEAR_PREFIXES;
+  DENSITY_SETTINGS: typeof DENSITY_SETTINGS;
+  PRECISION_DAY: typeof PRECISION_DAY;
+  PRECISION_HOUR: typeof PRECISION_HOUR;
+  PRECISION_MINUTE: typeof PRECISION_MINUTE;
+  PRECISION_SECOND: typeof PRECISION_SECOND;
+  PRECISION_MILLISECOND: typeof PRECISION_MILLISECOND;
+  PRECISION_MONTH: typeof PRECISION_MONTH;
+  PRECISION_YEAR: typeof PRECISION_YEAR;
+  PRECISION_DECADE: typeof PRECISION_DECADE;
+  PRECISION_CENTURY: typeof PRECISION_CENTURY;
+  PRECISION_MILLENNIUM: typeof PRECISION_MILLENNIUM;
+  PRECISION_MILLION_YEARS: typeof PRECISION_MILLION_YEARS;
+  PRECISION_BILLION_YEARS: typeof PRECISION_BILLION_YEARS;
+  DENSITY_ALL: typeof DENSITY_ALL;
+  DENSITY_LOW: typeof DENSITY_LOW;
+  DENSITY_MEDIUM: typeof DENSITY_MEDIUM;
+  DENSITY_HIGH: typeof DENSITY_HIGH;
+  RANGE_ALL: typeof RANGE_ALL;
+  RANGE_SCREEN: typeof RANGE_SCREEN;
+}
+
+declare const HistropediaModule: HistropediaApi;
+
+export default HistropediaModule;
+
+declare global {
+  const Histropedia: HistropediaApi;
+
+  interface Window {
+    Histropedia: HistropediaApi;
+  }
+}