@getmicdrop/venue-calendar 4.3.62 → 4.3.64

package/dist/types/index.d.ts

@@ -1,597 +1,602 @@
-/**
- * TypeScript definitions for @getmicdrop/venue-calendar
- */
-
-// ============================================================================
-// Event Data Types
-// ============================================================================
-
-/**
- * Event data structure returned from the API or passed to components
- */
-export interface EventData {
-  id: string | number;
-  name: string;
-  date: string;
-  startDateTime?: string;
-  endDateTime?: string;
-  image?: string;
-  description?: string;
-  venueId?: string | number;
-  venueID?: string | number;
-  timeZone?: string;
-  location?: string;
-  slug?: string;
-  status?: 'on_sale' | 'selling_fast' | 'sold_out';
-}
-
-/**
- * Ticket data structure
- */
-export interface TicketData {
-  id: string | number;
-  name: string;
-  price: number;
-  quantity?: number;
-  description?: string;
-  available?: number;
-}
-
-// ============================================================================
-// Theme Types
-// ============================================================================
-
-/**
- * Theme color configuration using HSL format
- * All values should be HSL strings like "217 91% 60%"
- */
-export interface ThemeColors {
-  /** Brand primary color */
-  brandPrimary: string;
-  /** Primary text color */
-  textPrimary: string;
-  /** Secondary text color */
-  textSecondary: string;
-  /** Tertiary text color */
-  textTertiary: string;
-  /** Primary background color */
-  bgPrimary: string;
-  /** Secondary background color */
-  bgSecondary: string;
-  /** Quaternary background color */
-  bgQuaternary: string;
-  /** Primary stroke/border color */
-  strokePrimary: string;
-  /** Secondary stroke/border color */
-  strokeSecondary: string;
-  /** On sale status color */
-  statusOnSale: string;
-  /** Selling fast status color */
-  statusSellingFast: string;
-  /** Sold out status color */
-  statusSoldOut: string;
-  /** Today's date background color */
-  todayBg: string;
-  /** Today's date text color */
-  todayText: string;
-  /** Event dot color for on sale */
-  eventDotOnSale: string;
-  /** Event dot color for selling fast */
-  eventDotSellingFast: string;
-  /** Event dot color for sold out */
-  eventDotSoldOut: string;
-  /** Hover background color */
-  hoverBg: string;
-  /** Focus ring color */
-  focusRing: string;
-}
-
-/**
- * Preset themes collection
- */
-export interface Themes {
-  light: ThemeColors;
-  dark: ThemeColors;
-  highContrast: ThemeColors;
-}
-
-// ============================================================================
-// View Option Types
-// ============================================================================
-
-/**
- * View option for the calendar view switcher
- */
-export interface ViewOption {
-  id: number;
-  text: string;
-  /** @deprecated Not rendered — the view switcher shows `text` only. Kept optional for backward compatibility. */
-  icon?: string;
-  ariaLabel?: string;
-}
-
-export type ViewType = 'list' | 'gallery' | 'calendar';
-
-// ============================================================================
-// Component Props Interfaces
-// ============================================================================
-
-/**
- * Base options for all init functions
- */
-export interface BaseInitOptions {
-  /** CSS selector or HTMLElement to mount the component */
-  target: string | HTMLElement;
-  /** The venue ID (optional, default: '1') */
-  venueId?: string;
-  /** The organization ID (optional, default: '1') */
-  organizationId?: string;
-  /**
-   * BCP-47 locale tag (e.g. 'es', 'es-MX'). Selects the bundled locale for the
-   * label catalogue; undefined falls back to the browser locale, then English.
-   * Threaded through every init entry point (vc#693).
-   */
-  locale?: string;
-}
-
-/**
- * Options for initializing the Venue Calendar component
- */
-export interface CalendarProps extends BaseInitOptions {
-  /** Initial view: 'list', 'gallery', or 'calendar' (default: 'calendar') */
-  view?: ViewType;
-  /** Array of event objects to display */
-  events?: EventData[];
-  /** Whether to show view switcher (default: true) */
-  showViewOptions?: boolean;
-  /** Whether to show month navigation (default: true) */
-  showMonthSwitcher?: boolean;
-  /** Show the search box even without the view switcher (default: false) */
-  showSearch?: boolean;
-  /** Gallery/List/Carousel show at most this many events; null = all, with
-   * load more on Gallery (default: null) */
-  maxItems?: number | null;
-  /** Hide card parts; only `false` hides (default: every part shown) */
-  eventDetails?: {
-    poster?: boolean;
-    date?: boolean;
-    description?: boolean;
-  } | null;
-  /** Which show the Featured view spotlights. Falls through to the next
-   * upcoming show when the pick is absent or no longer in the feed — a
-   * collection pick always falls through, since the event feed carries no
-   * collection membership to match on (default: null) */
-  featuredItem?: {
-    type?: 'event' | 'series' | 'collection';
-    id: string | number;
-  } | null;
-  /** How big each view draws its events: S packs more in, L gives each
-   * event more room, M is the default look (default: 'M') */
-  size?: 'S' | 'M' | 'L';
-  /** Level of the calendar's screen-reader heading: 2 when the host page
-   * already carries its h1 (default: 1) */
-  headingLevel?: 1 | 2;
-  /** How every card draws its poster: 'fit' shows the whole poster, 'fill'
-   * crops it to cover the frame (default: 'fit') */
-  posterFit?: 'fill' | 'fit';
-  /** What fills around a 'fit' poster: a blurred copy of it, or the
-   * section's own colour (default: 'blur') */
-  posterBackdrop?: 'blur' | 'color';
-  /** Opening a show rewrites the host page's title and share tags to the
-   * show's, restoring them on close. Both embeds turn it on unless the host
-   * sets inject-seo="false" (default for a direct call: false) */
-  injectSeo?: boolean;
-  /** Current month store (Svelte writable store) */
-  currentMonth?: import('svelte/store').Writable<number>;
-  /** Current year store (Svelte writable store) */
-  currentYear?: import('svelte/store').Writable<number>;
-  /** Handler for navigating to next month */
-  handleNext?: () => void;
-  /** Handler for navigating to previous month */
-  handlePrev?: () => void;
-  /** Callback function when an event is clicked */
-  onEventClick?: (_event: EventData) => void;
-  /**
-   * Render the show detail / series / collection IN-PLACE on click + deep
-   * link instead of navigating the host page (default: true for embeds).
-   * Pass false to keep the host responsible for navigation, or supply your
-   * own onEventClick to take over click handling entirely.
-   */
-  inlineEntityViews?: boolean;
-  /**
-   * The host's brand scheme, applied on the widget's root so every calendar
-   * surface — time buttons included — wears it. null = the default palette.
-   */
-  colors?: ColorSchemeColors | null;
-}
-
-/**
- * Options for initializing the (inline) Event Page.
- */
-export interface EventPageOptions extends BaseInitOptions {
-  /** The event ID to display (the page self-fetches), or pass rawEvent. */
-  eventId?: string | number;
-  /** Pre-fetched raw event payload (skips the self-fetch). */
-  rawEvent?: any;
-  /** Event slug (cosmetic). */
-  slug?: string;
-  /** Callback when the back control is clicked. */
-  onNavigateBack?: () => void;
-  /** Callback when proceeding to checkout (cart already created). */
-  onNavigateToCart?: (
-    _id: string | number,
-    _slug: string,
-    _rawEvent: any
-  ) => void;
-  /** Callback when a series occurrence is clicked. */
-  onBuyTickets?: (_eventId: string | number, _slug: string) => void;
-  /** i18n label overrides. */
-  labels?: Record<string, string>;
-}
-
-/**
- * Success callback data from checkout
- */
-export interface CheckoutSuccessData {
-  orderId?: string;
-  eventId?: string;
-  event?: EventData;
-}
-
-/**
- * Options for initializing the Checkout View
- */
-export interface CheckoutOptions extends BaseInitOptions {
-  /** The event ID to display */
-  eventId: string;
-  /** The event slug (optional) */
-  slug?: string;
-  /** Array of available tickets (optional) */
-  availableTickets?: TicketData[];
-  /** Callback when checkout is successful */
-  onSuccess?: (_data: CheckoutSuccessData) => void;
-  /** Callback when navigating to success page */
-  onNavigateToSuccess?: (_data: CheckoutSuccessData) => void;
-}
-
-/**
- * Options for initializing the Success View
- */
-export interface SuccessViewOptions extends BaseInitOptions {
-  /** The event ID (optional) */
-  eventId?: string;
-  /** The event slug (optional) */
-  slug?: string;
-  /** The order ID (optional) */
-  orderId?: string;
-}
-
-/**
- * Alias for CalendarProps for backward compatibility
- */
-export type InitOptions = CalendarProps;
-
-// ============================================================================
-// Svelte Component Instance
-// ============================================================================
-
-/**
- * Svelte component instance returned by init functions
- */
-export interface SvelteComponentInstance {
-  /** Destroy the component and clean up */
-  $destroy?: () => void;
-  /** Internal cleanup for success listener */
-  _successCleanup?: () => void;
-}
-
-// ============================================================================
-// Exported Functions
-// ============================================================================
-
-/**
- * Initialize the Venue Calendar component
- * @param options - Configuration options
- * @returns The Svelte component instance, or null if target not found
- */
-export function initVenueCalendar(
-  _options: CalendarProps
-): SvelteComponentInstance | null;
-
-/**
- * Initialize the (inline) Event Page.
- * @param options - Configuration options
- * @returns The Svelte component instance, or null if target not found / no event
- */
-export function initEventPage(
-  _options: EventPageOptions
-): SvelteComponentInstance | null;
-
-/**
- * Initialize the Checkout View
- * @param options - Configuration options
- * @returns The Svelte component instance, or null if target not found or eventId missing
- */
-export function initCheckoutView(
-  _options: CheckoutOptions
-): SvelteComponentInstance | null;
-
-/**
- * Alias for initCheckoutView
- */
-export const initCheckout: typeof initCheckoutView;
-
-/**
- * Initialize the Success View
- * @param options - Configuration options
- * @returns The Svelte component instance, or null if target not found
- */
-export function initSuccessView(
-  _options: SuccessViewOptions
-): SvelteComponentInstance | null;
-
-/**
- * Alias for initSuccessView
- */
-export const initSuccess: typeof initSuccessView;
-
-/**
- * Auto-mount: Automatically finds and mounts calendar to elements with class 'micdrop-calendar-container'
- */
-export function autoMount(): void;
-
-// ============================================================================
-// Runtime Configuration
-// ============================================================================
-
-/**
- * Opt-in embed integration settings for a venue site embedding the widget.
- */
-export interface EmbedConfig {
-  /**
-   * Emit a MICDROP_CHECKOUT_COMPLETE postMessage when an order completes. The
-   * payload is non-PII: `{ orderId, eventId }`. Default: false.
-   */
-  postMessageOnSuccess?: boolean;
-  /**
-   * REQUIRED concrete origin (e.g. 'https://venue.example') for the
-   * MICDROP_CHECKOUT_COMPLETE message. The message is never posted to '*'; without a
-   * concrete absolute origin nothing is sent and a warning is logged.
-   */
-  postMessageTargetOrigin?: string | null;
-}
-
-/**
- * Options for {@link configureVenueCalendar}. All fields are optional — pass
- * only the keys you want to change.
- */
-export interface ConfigureVenueCalendarOptions {
-  /** Called whenever the widget surfaces a caught error (wire into Sentry/Rollbar/etc). */
-  onError?: (_error: Error, _context: { source: string }) => void;
-  /** Override the backend origin for multi-region setups. */
-  apiBaseUrl?: string;
-  /** Request timeout in ms, forwarded to the API client. */
-  apiTimeout?: number;
-  /** Retry count, forwarded to the API client. */
-  apiRetries?: number;
-  /** Opt-in embed integration settings (see {@link EmbedConfig}). */
-  embed?: EmbedConfig;
-}
-
-/**
- * Configure the calendar widget at runtime: error reporting, API overrides,
- * and the opt-in embed integration (e.g. the MICDROP_CHECKOUT_COMPLETE postMessage).
- * @param options - Configuration options
- */
-export function configureVenueCalendar(
-  _options?: ConfigureVenueCalendarOptions
-): void;
-
-// ============================================================================
-// Theme Exports
-// ============================================================================
-
-/**
- * Collection of preset themes
- */
-export const themes: Themes;
-
-/**
- * Light theme preset
- */
-export const lightTheme: ThemeColors;
-
-/**
- * Dark theme preset
- */
-export const darkTheme: ThemeColors;
-
-/**
- * High contrast theme preset for accessibility
- */
-export const highContrastTheme: ThemeColors;
-
-/**
- * Apply a theme to the calendar widget
- * @param theme - Theme object with HSL color values
- * @param container - Optional container element (defaults to document.documentElement)
- */
-export function applyTheme(
-  _theme: Partial<ThemeColors>,
-  _container?: HTMLElement
-): void;
-
-/**
- * Generate CSS string for embedding themes
- * @param theme - Theme object
- * @returns CSS string with custom properties
- */
-export function generateThemeCSS(_theme: Partial<ThemeColors>): string;
-
-// ============================================================================
-// Brand scheme → calendar CSS variables
-// ============================================================================
-
-/**
- * The builder's saved colour scheme: token name → hex string. Partial schemes
- * are fine — a missing or invalid token is left to the stylesheet's default.
- */
-export type ColorSchemeColors = Record<string, string>;
-
-/**
- * Map a scheme to venue-calendar's CSS variables (`--brand-primary` …) as
- * wrapper-less HSL strings ("209 99% 50%").
- */
-export function schemeColorsToCSSVars(
-  _colors: ColorSchemeColors | null | undefined
-): Record<string, string>;
-
-/**
- * Write a scheme onto an element as inline custom properties. Pass the
- * widget's own root: the stylesheet declares the default palette on that root,
- * so a variable set on an ancestor never reaches it. Returns the names written.
- */
-export function applySchemeColors(
-  _colors: ColorSchemeColors | null | undefined,
-  _container: HTMLElement
-): string[];
-
-/** Remove what applySchemeColors wrote. */
-export function clearSchemeColors(
-  _container: HTMLElement,
-  _names: string[]
-): void;
-
-// ============================================================================
-// Scarcity Canon
-// ============================================================================
-// These MUST be declared by hand. This file is not generated — it is copied
-// verbatim from `src/lib/types/` to `dist/types/` by vite.config.lib.js and is
-// what package.json's "types" points at, so a runtime `export` added to
-// VenueCalendar.js is invisible to TypeScript until it is also declared here.
-// The `exports` map has no wildcard either, so a deep import
-// (`@getmicdrop/venue-calendar/constants/scarcity`) is not an escape hatch.
-// Consumers — notably micdrop-frontend's admin mirror in
-// `src/lib/foundry/settings-tickets/scarcity.ts` — import these from the
-// package ENTRY, and that import only typechecks because of the declarations
-// below. Keep them in sync with `src/lib/constants/scarcity.ts`.
-
-/**
- * Scarcity tier for a ticket. `sold-out` at zero remaining, `urgent` carries an
- * exact count ("Only N left"), `low` is the vague badge, `plenty` no claim.
- */
-export type ScarcityLevel = 'sold-out' | 'urgent' | 'low' | 'plenty';
-
-/**
- * The sliding-scale knobs behind every scarcity claim in venue-calendar.
- * Percent thresholds bend toward the absolute floor/cap so the claim scales
- * with venue size; `MAX_EXACT_COUNT` caps when an exact count may be revealed.
- */
-export const SCARCITY_THRESHOLDS: {
-  readonly URGENT_PCT: 10;
-  readonly LOW_PCT: 20;
-  readonly MAX_EXACT_COUNT: 20;
-  readonly ABSOLUTE_FLOOR: 5;
-  readonly ABSOLUTE_CAP: 30;
-};
-
-/**
- * Compute the scarcity level for a (remaining, total) pair.
- *
- * Returns 'plenty' when `total <= 0` (no percentage to compute — treat as
- * unlimited/unknown capacity, make no claim) and 'sold-out' for remaining <= 0.
- */
-export function computeScarcityLevel(
-  _remaining: number,
-  _total: number
-): ScarcityLevel;
-
-// ============================================================================
-// Svelte Component Exports
-// ============================================================================
-
-/**
- * VenueCalendar Svelte component (CalendarContainer)
- */
-export const VenueCalendar: any;
-
-/**
- * Checkout Svelte component
- */
-export const Checkout: any;
-
-/**
- * CheckoutView alias for Checkout
- */
-export const CheckoutView: any;
-
-/**
- * Success Svelte component
- */
-export const Success: any;
-
-/**
- * EventPage Svelte component — full event page with EventMeta, ScarcityBadge, etc.
- */
-export const EventPage: any;
-
-/**
- * SeriesPage Svelte component — series landing page with hero, upcoming dates, performers, FAQ sidebar
- */
-export const SeriesPage: any;
-
-/**
- * SeriesHomeView alias (deprecated — use SeriesPage instead)
- */
-export const SeriesHomeView: any;
-
-/**
- * CollectionView Svelte component
- */
-export const CollectionView: any;
-
-/**
- * ViewTicketsEmbed — the buyer's post-purchase ticket view (dice-swipe), as a
- * LOADER: calling it resolves to the component, which is what keeps the view in
- * its own chunk. Takes `{ orderUUID, locale?, labels? }` and self-fetches the
- * order.
- *
- * This file is hand-written, so an export missing from it is invisible until a
- * consumer imports it: the runtime barrel has exported this one since v3.6.0,
- * and micdrop-frontend's apex `/tickets/<orderUUID>` route (MIC-3859) could not
- * type-check against the published package without a local module augmentation.
- * That augmentation can be deleted once a release carrying this line is pinned.
- */
-export const ViewTicketsEmbed: any;
-
-// ============================================================================
-// Default Export
-// ============================================================================
-
-declare const _default: {
-  initVenueCalendar: typeof initVenueCalendar;
-  initEventPage: typeof initEventPage;
-  initCheckoutView: typeof initCheckoutView;
-  initCheckout: typeof initCheckoutView;
-  initSuccessView: typeof initSuccessView;
-  initSuccess: typeof initSuccessView;
-  autoMount: typeof autoMount;
-  VenueCalendar: any;
-  themes: Themes;
-  lightTheme: ThemeColors;
-  darkTheme: ThemeColors;
-  highContrastTheme: ThemeColors;
-  applyTheme: typeof applyTheme;
-  generateThemeCSS: typeof generateThemeCSS;
-  Checkout: any;
-  CheckoutView: any;
-  Success: any;
-  /** @deprecated Use Success instead */
-  Sucess: any;
-  EventPage: any;
-  SeriesPage: any;
-  SeriesHomeView: any;
-  CollectionView: any;
-};
-
-export default _default;
+/**
+ * TypeScript definitions for @getmicdrop/venue-calendar
+ */
+
+// ============================================================================
+// Event Data Types
+// ============================================================================
+
+/**
+ * Event data structure returned from the API or passed to components
+ */
+export interface EventData {
+  id: string | number;
+  name: string;
+  date: string;
+  startDateTime?: string;
+  endDateTime?: string;
+  image?: string;
+  description?: string;
+  venueId?: string | number;
+  venueID?: string | number;
+  timeZone?: string;
+  location?: string;
+  slug?: string;
+  status?: 'on_sale' | 'selling_fast' | 'sold_out';
+}
+
+/**
+ * Ticket data structure
+ */
+export interface TicketData {
+  id: string | number;
+  name: string;
+  price: number;
+  quantity?: number;
+  description?: string;
+  available?: number;
+}
+
+// ============================================================================
+// Theme Types
+// ============================================================================
+
+/**
+ * Theme color configuration using HSL format
+ * All values should be HSL strings like "217 91% 60%"
+ */
+export interface ThemeColors {
+  /** Brand primary color */
+  brandPrimary: string;
+  /** Primary text color */
+  textPrimary: string;
+  /** Secondary text color */
+  textSecondary: string;
+  /** Tertiary text color */
+  textTertiary: string;
+  /** Primary background color */
+  bgPrimary: string;
+  /** Secondary background color */
+  bgSecondary: string;
+  /** Quaternary background color */
+  bgQuaternary: string;
+  /** Primary stroke/border color */
+  strokePrimary: string;
+  /** Secondary stroke/border color */
+  strokeSecondary: string;
+  /** On sale status color */
+  statusOnSale: string;
+  /** Selling fast status color */
+  statusSellingFast: string;
+  /** Sold out status color */
+  statusSoldOut: string;
+  /** Today's date background color */
+  todayBg: string;
+  /** Today's date text color */
+  todayText: string;
+  /** Event dot color for on sale */
+  eventDotOnSale: string;
+  /** Event dot color for selling fast */
+  eventDotSellingFast: string;
+  /** Event dot color for sold out */
+  eventDotSoldOut: string;
+  /** Hover background color */
+  hoverBg: string;
+  /** Focus ring color */
+  focusRing: string;
+}
+
+/**
+ * Preset themes collection
+ */
+export interface Themes {
+  light: ThemeColors;
+  dark: ThemeColors;
+  highContrast: ThemeColors;
+}
+
+// ============================================================================
+// View Option Types
+// ============================================================================
+
+/**
+ * View option for the calendar view switcher
+ */
+export interface ViewOption {
+  id: number;
+  text: string;
+  /** @deprecated Not rendered — the view switcher shows `text` only. Kept optional for backward compatibility. */
+  icon?: string;
+  ariaLabel?: string;
+}
+
+export type ViewType = 'list' | 'gallery' | 'calendar';
+
+// ============================================================================
+// Component Props Interfaces
+// ============================================================================
+
+/**
+ * Base options for all init functions
+ */
+export interface BaseInitOptions {
+  /** CSS selector or HTMLElement to mount the component */
+  target: string | HTMLElement;
+  /** The venue ID (optional, default: '1') */
+  venueId?: string;
+  /** The organization ID (optional, default: '1') */
+  organizationId?: string;
+  /**
+   * BCP-47 locale tag (e.g. 'es', 'es-MX'). Selects the bundled locale for the
+   * label catalogue; undefined falls back to the browser locale, then English.
+   * Threaded through every init entry point (vc#693).
+   */
+  locale?: string;
+}
+
+/**
+ * Options for initializing the Venue Calendar component
+ */
+export interface CalendarProps extends BaseInitOptions {
+  /** Initial view: 'list', 'gallery', or 'calendar' (default: 'calendar') */
+  view?: ViewType;
+  /** Array of event objects to display */
+  events?: EventData[];
+  /** Whether to show view switcher (default: true) */
+  showViewOptions?: boolean;
+  /** Whether to show month navigation (default: true) */
+  showMonthSwitcher?: boolean;
+  /** Show the search box even without the view switcher (default: false) */
+  showSearch?: boolean;
+  /** Gallery/List/Carousel show at most this many events; null = all, with
+   * load more on Gallery (default: null) */
+  maxItems?: number | null;
+  /** Hide card parts; only `false` hides (default: every part shown) */
+  eventDetails?: {
+    poster?: boolean;
+    date?: boolean;
+    description?: boolean;
+  } | null;
+  /** Which show the Featured view spotlights. Falls through to the next
+   * upcoming show when the pick is absent or no longer in the feed — a
+   * collection pick always falls through, since the event feed carries no
+   * collection membership to match on (default: null) */
+  featuredItem?: {
+    type?: 'event' | 'series' | 'collection';
+    id: string | number;
+  } | null;
+  /** How big each view draws its events: S packs more in, L gives each
+   * event more room, M is the default look (default: 'M') */
+  size?: 'S' | 'M' | 'L';
+  /** Level of the calendar's screen-reader heading: 2 when the host page
+   * already carries its h1 (default: 1) */
+  headingLevel?: 1 | 2;
+  /** How every card draws its poster: 'fit' shows the whole poster, 'fill'
+   * crops it to cover the frame (default: 'fit') */
+  posterFit?: 'fill' | 'fit';
+  /** What fills around a 'fit' poster: a blurred copy of it, or the
+   * section's own colour (default: 'blur') */
+  posterBackdrop?: 'blur' | 'color';
+  /** Opening a show rewrites the host page's title and share tags to the
+   * show's, restoring them on close. Both embeds turn it on unless the host
+   * sets inject-seo="false" (default for a direct call: false) */
+  injectSeo?: boolean;
+  /** Current month store (Svelte writable store) */
+  currentMonth?: import('svelte/store').Writable<number>;
+  /** Current year store (Svelte writable store) */
+  currentYear?: import('svelte/store').Writable<number>;
+  /** Handler for navigating to next month */
+  handleNext?: () => void;
+  /** Handler for navigating to previous month */
+  handlePrev?: () => void;
+  /** Callback function when an event is clicked */
+  onEventClick?: (_event: EventData) => void;
+  /**
+   * Render the show detail / series / collection IN-PLACE on click + deep
+   * link instead of navigating the host page (default: true for embeds).
+   * Pass false to keep the host responsible for navigation, or supply your
+   * own onEventClick to take over click handling entirely.
+   */
+  inlineEntityViews?: boolean;
+  /**
+   * The host's brand scheme, applied on the widget's root so every calendar
+   * surface — time buttons included — wears it. null = the default palette.
+   */
+  colors?: ColorSchemeColors | null;
+}
+
+/**
+ * Options for initializing the (inline) Event Page.
+ */
+export interface EventPageOptions extends BaseInitOptions {
+  /** The event ID to display (the page self-fetches), or pass rawEvent. */
+  eventId?: string | number;
+  /** Pre-fetched raw event payload (skips the self-fetch). */
+  rawEvent?: any;
+  /** Event slug (cosmetic). */
+  slug?: string;
+  /** Callback when the back control is clicked. */
+  onNavigateBack?: () => void;
+  /** Callback when proceeding to checkout (cart already created). */
+  onNavigateToCart?: (
+    _id: string | number,
+    _slug: string,
+    _rawEvent: any
+  ) => void;
+  /** Callback when a series occurrence is clicked. */
+  onBuyTickets?: (_eventId: string | number, _slug: string) => void;
+  /** i18n label overrides. */
+  labels?: Record<string, string>;
+}
+
+/**
+ * Success callback data from checkout
+ */
+export interface CheckoutSuccessData {
+  orderId?: string;
+  eventId?: string;
+  event?: EventData;
+}
+
+/**
+ * Options for initializing the Checkout View
+ */
+export interface CheckoutOptions extends BaseInitOptions {
+  /** The event ID to display */
+  eventId: string;
+  /** The event slug (optional) */
+  slug?: string;
+  /** Array of available tickets (optional) */
+  availableTickets?: TicketData[];
+  /** Callback when checkout is successful */
+  onSuccess?: (_data: CheckoutSuccessData) => void;
+  /** Callback when navigating to success page */
+  onNavigateToSuccess?: (_data: CheckoutSuccessData) => void;
+}
+
+/**
+ * Options for initializing the Success View
+ */
+export interface SuccessViewOptions extends BaseInitOptions {
+  /** The event ID (optional) */
+  eventId?: string;
+  /** The event slug (optional) */
+  slug?: string;
+  /** The order ID (optional) */
+  orderId?: string;
+}
+
+/**
+ * Alias for CalendarProps for backward compatibility
+ */
+export type InitOptions = CalendarProps;
+
+// ============================================================================
+// Svelte Component Instance
+// ============================================================================
+
+/**
+ * Svelte component instance returned by init functions
+ */
+export interface SvelteComponentInstance {
+  /** Destroy the component and clean up */
+  $destroy?: () => void;
+  /** Internal cleanup for success listener */
+  _successCleanup?: () => void;
+}
+
+// ============================================================================
+// Exported Functions
+// ============================================================================
+
+/**
+ * Initialize the Venue Calendar component
+ * @param options - Configuration options
+ * @returns The Svelte component instance, or null if target not found
+ */
+export function initVenueCalendar(
+  _options: CalendarProps
+): SvelteComponentInstance | null;
+
+/**
+ * Initialize the (inline) Event Page.
+ * @param options - Configuration options
+ * @returns The Svelte component instance, or null if target not found / no event
+ */
+export function initEventPage(
+  _options: EventPageOptions
+): SvelteComponentInstance | null;
+
+/**
+ * Initialize the Checkout View
+ * @param options - Configuration options
+ * @returns The Svelte component instance, or null if target not found or eventId missing
+ */
+export function initCheckoutView(
+  _options: CheckoutOptions
+): SvelteComponentInstance | null;
+
+/**
+ * Alias for initCheckoutView
+ */
+export const initCheckout: typeof initCheckoutView;
+
+/**
+ * Initialize the Success View
+ * @param options - Configuration options
+ * @returns The Svelte component instance, or null if target not found
+ */
+export function initSuccessView(
+  _options: SuccessViewOptions
+): SvelteComponentInstance | null;
+
+/**
+ * Alias for initSuccessView
+ */
+export const initSuccess: typeof initSuccessView;
+
+/**
+ * Auto-mount: Automatically finds and mounts calendar to elements with class 'micdrop-calendar-container'
+ */
+export function autoMount(): void;
+
+// ============================================================================
+// Runtime Configuration
+// ============================================================================
+
+/**
+ * Opt-in embed integration settings for a venue site embedding the widget.
+ */
+export interface EmbedConfig {
+  /**
+   * Emit a MICDROP_CHECKOUT_COMPLETE postMessage when an order completes. The
+   * payload is non-PII: `{ orderId, eventId }`. Default: false.
+   */
+  postMessageOnSuccess?: boolean;
+  /**
+   * REQUIRED concrete origin (e.g. 'https://venue.example') for the
+   * MICDROP_CHECKOUT_COMPLETE message. The message is never posted to '*'; without a
+   * concrete absolute origin nothing is sent and a warning is logged.
+   */
+  postMessageTargetOrigin?: string | null;
+}
+
+/**
+ * Options for {@link configureVenueCalendar}. All fields are optional — pass
+ * only the keys you want to change.
+ */
+export interface ConfigureVenueCalendarOptions {
+  /** Called whenever the widget surfaces a caught error (wire into Sentry/Rollbar/etc). */
+  onError?: (_error: Error, _context: { source: string }) => void;
+  /** Override the backend origin for multi-region setups. */
+  apiBaseUrl?: string;
+  /** Request timeout in ms, forwarded to the API client. */
+  apiTimeout?: number;
+  /** Retry count, forwarded to the API client. */
+  apiRetries?: number;
+  /** Opt-in embed integration settings (see {@link EmbedConfig}). */
+  embed?: EmbedConfig;
+}
+
+/**
+ * Configure the calendar widget at runtime: error reporting, API overrides,
+ * and the opt-in embed integration (e.g. the MICDROP_CHECKOUT_COMPLETE postMessage).
+ * @param options - Configuration options
+ */
+export function configureVenueCalendar(
+  _options?: ConfigureVenueCalendarOptions
+): void;
+
+// ============================================================================
+// Theme Exports
+// ============================================================================
+
+/**
+ * Collection of preset themes
+ */
+export const themes: Themes;
+
+/**
+ * Light theme preset
+ */
+export const lightTheme: ThemeColors;
+
+/**
+ * Dark theme preset
+ */
+export const darkTheme: ThemeColors;
+
+/**
+ * High contrast theme preset for accessibility
+ */
+export const highContrastTheme: ThemeColors;
+
+/**
+ * Apply a theme to the calendar widget
+ * @param theme - Theme object with HSL color values
+ * @param container - Optional container element (defaults to document.documentElement)
+ */
+export function applyTheme(
+  _theme: Partial<ThemeColors>,
+  _container?: HTMLElement
+): void;
+
+/**
+ * Generate CSS string for embedding themes
+ * @param theme - Theme object
+ * @returns CSS string with custom properties
+ */
+export function generateThemeCSS(_theme: Partial<ThemeColors>): string;
+
+// ============================================================================
+// Brand scheme → calendar CSS variables
+// ============================================================================
+
+/**
+ * The builder's saved colour scheme: token name → hex string. Partial schemes
+ * are fine — a missing or invalid token is left to the stylesheet's default.
+ */
+export type ColorSchemeColors = Record<string, string>;
+
+/**
+ * Map a scheme to venue-calendar's CSS variables (`--brand-primary` …) as
+ * wrapper-less HSL strings ("209 99% 50%").
+ */
+export function schemeColorsToCSSVars(
+  _colors: ColorSchemeColors | null | undefined
+): Record<string, string>;
+
+/**
+ * Write a scheme onto an element as inline custom properties. Pass the
+ * widget's own root: the stylesheet declares the default palette on that root,
+ * so a variable set on an ancestor never reaches it. Returns the names written.
+ */
+export function applySchemeColors(
+  _colors: ColorSchemeColors | null | undefined,
+  _container: HTMLElement
+): string[];
+
+/** Remove what applySchemeColors wrote. */
+export function clearSchemeColors(
+  _container: HTMLElement,
+  _names: string[]
+): void;
+
+// ============================================================================
+// Scarcity Canon
+// ============================================================================
+// These MUST be declared by hand. This file is not generated — it is copied
+// verbatim from `src/lib/types/` to `dist/types/` by vite.config.lib.js and is
+// what package.json's "types" points at, so a runtime `export` added to
+// VenueCalendar.js is invisible to TypeScript until it is also declared here.
+// The `exports` map has no wildcard either, so a deep import
+// (`@getmicdrop/venue-calendar/constants/scarcity`) is not an escape hatch.
+// Consumers — notably micdrop-frontend's admin mirror in
+// `src/lib/foundry/settings-tickets/scarcity.ts` — import these from the
+// package ENTRY, and that import only typechecks because of the declarations
+// below. Keep them in sync with `src/lib/constants/scarcity.ts`.
+
+/**
+ * Scarcity tier for a ticket. `sold-out` at zero remaining, `urgent` carries an
+ * exact count ("Only N left"), `low` is the vague badge, `plenty` no claim.
+ */
+export type ScarcityLevel = 'sold-out' | 'urgent' | 'low' | 'plenty';
+
+/**
+ * The sliding-scale knobs behind every scarcity claim in venue-calendar.
+ * Percent thresholds bend toward the absolute floor/cap so the claim scales
+ * with venue size; `MAX_EXACT_COUNT` caps when an exact count may be revealed.
+ */
+export const SCARCITY_THRESHOLDS: {
+  readonly URGENT_PCT: 10;
+  readonly LOW_PCT: 20;
+  readonly MAX_EXACT_COUNT: 20;
+  readonly ABSOLUTE_FLOOR: 5;
+  readonly ABSOLUTE_CAP: 30;
+};
+
+/**
+ * Compute the scarcity level for a (remaining, total) pair.
+ *
+ * Returns 'plenty' when `total <= 0` (no percentage to compute — treat as
+ * unlimited/unknown capacity, make no claim) and 'sold-out' for remaining <= 0.
+ *
+ * The implementation takes a third `policy` parameter (MIC-3808) and this
+ * declaration deliberately omits it: it exists only so a test can reach the
+ * branch, and a package consumer passing its own policy would be standing up a
+ * second scarcity ladder. Narrowing the public signature is the point, not drift.
+ */
+export function computeScarcityLevel(
+  _remaining: number,
+  _total: number
+): ScarcityLevel;
+
+// ============================================================================
+// Svelte Component Exports
+// ============================================================================
+
+/**
+ * VenueCalendar Svelte component (CalendarContainer)
+ */
+export const VenueCalendar: any;
+
+/**
+ * Checkout Svelte component
+ */
+export const Checkout: any;
+
+/**
+ * CheckoutView alias for Checkout
+ */
+export const CheckoutView: any;
+
+/**
+ * Success Svelte component
+ */
+export const Success: any;
+
+/**
+ * EventPage Svelte component — full event page with EventMeta, ScarcityBadge, etc.
+ */
+export const EventPage: any;
+
+/**
+ * SeriesPage Svelte component — series landing page with hero, upcoming dates, performers, FAQ sidebar
+ */
+export const SeriesPage: any;
+
+/**
+ * SeriesHomeView alias (deprecated — use SeriesPage instead)
+ */
+export const SeriesHomeView: any;
+
+/**
+ * CollectionView Svelte component
+ */
+export const CollectionView: any;
+
+/**
+ * ViewTicketsEmbed — the buyer's post-purchase ticket view (dice-swipe), as a
+ * LOADER: calling it resolves to the component, which is what keeps the view in
+ * its own chunk. Takes `{ orderUUID, locale?, labels? }` and self-fetches the
+ * order.
+ *
+ * This file is hand-written, so an export missing from it is invisible until a
+ * consumer imports it: the runtime barrel has exported this one since v3.6.0,
+ * and micdrop-frontend's apex `/tickets/<orderUUID>` route (MIC-3859) could not
+ * type-check against the published package without a local module augmentation.
+ * That augmentation can be deleted once a release carrying this line is pinned.
+ */
+export const ViewTicketsEmbed: any;
+
+// ============================================================================
+// Default Export
+// ============================================================================
+
+declare const _default: {
+  initVenueCalendar: typeof initVenueCalendar;
+  initEventPage: typeof initEventPage;
+  initCheckoutView: typeof initCheckoutView;
+  initCheckout: typeof initCheckoutView;
+  initSuccessView: typeof initSuccessView;
+  initSuccess: typeof initSuccessView;
+  autoMount: typeof autoMount;
+  VenueCalendar: any;
+  themes: Themes;
+  lightTheme: ThemeColors;
+  darkTheme: ThemeColors;
+  highContrastTheme: ThemeColors;
+  applyTheme: typeof applyTheme;
+  generateThemeCSS: typeof generateThemeCSS;
+  Checkout: any;
+  CheckoutView: any;
+  Success: any;
+  /** @deprecated Use Success instead */
+  Sucess: any;
+  EventPage: any;
+  SeriesPage: any;
+  SeriesHomeView: any;
+  CollectionView: any;
+};
+
+export default _default;