histropediajs 1.4.0

package/index.d.ts

@@ -0,0 +1,1464 @@
+// 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
+// ------------------------------------------------------------------------------------
+
+/** Numeric precision constants (public). */
+export const PRECISION_DAY: 11;
+export const PRECISION_MONTH: 10;
+export const PRECISION_YEAR: 9;
+export const PRECISION_DECADE: 8;
+export const PRECISION_CENTURY: 7;
+export const PRECISION_MILLENNIUM: 6;
+export const PRECISION_MILLION_YEARS: 3;
+export const PRECISION_BILLION_YEARS: 1;
+
+/**
+ * Date precision used by Article/TimeBand ranges.
+ * Matches the numeric constants exported above.
+ */
+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;
+
+/** 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: 0;
+export const DENSITY_LOW: 1;
+export const DENSITY_MEDIUM: 2;
+export const DENSITY_HIGH: 3;
+export type Density =
+  | typeof DENSITY_ALL
+  | typeof DENSITY_LOW
+  | typeof DENSITY_MEDIUM
+  | typeof DENSITY_HIGH;
+
+export const RANGE_ALL: 0;
+export const RANGE_SCREEN: 1;
+export type AutoStackRange = typeof RANGE_ALL | typeof RANGE_SCREEN;
+
+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 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 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 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 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;
+  };
+  /** 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;
+  /** 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;
+  /** 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 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[];
+
+  /** 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;
+  /** 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;
+  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). String input accepted in "-YYYY-MM-DD" style. */
+  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;
+  /** Smoothly scroll so that the given date is centred/positioned. */
+  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 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;
+  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;
+  }
+}