@contentful/optimization-core 0.1.0-alpha7 → 0.1.0-alpha9

package/dist/index.d.ts

@@ -1,15 +1,2432 @@
-export { batch, effect, signalFns, signals, type Signal, type SignalFns, type Signals, } from './signals';
-export * from '@contentful/optimization-api-client';
-export * from 'logger';
-export * from './analytics';
-export * from './CoreBase';
-export * from './CoreStateful';
-export * from './CoreStateless';
-export * from './global-constants';
-export * from './lib/decorators';
-export * from './lib/interceptor';
-export * from './lib/value-presence';
-export * from './personalization';
-export { default as CoreStateful } from './CoreStateful';
-export { default as CoreStateless } from './CoreStateless';
-//# sourceMappingURL=index.d.ts.map
+/**
+ * Optimization Core SDK — platform-agnostic personalization and analytics.
+ *
+ * @packageDocumentation
+ */
+
+import { ApiClient } from '@contentful/optimization-api-client';
+import { ApiClientConfig } from '@contentful/optimization-api-client';
+import { batch } from '@preact/signals-core';
+import type { ChainModifiers } from 'contentful';
+import { ChangeArray } from '@contentful/optimization-api-client/api-schemas';
+import { ComponentClickBuilderArgs } from '@contentful/optimization-api-client';
+import { ComponentHoverBuilderArgs } from '@contentful/optimization-api-client';
+import { ComponentViewBuilderArgs } from '@contentful/optimization-api-client';
+import { computed } from '@preact/signals-core';
+import { effect } from '@preact/signals-core';
+import type { Entry } from 'contentful';
+import { EntryReplacementVariant } from '@contentful/optimization-api-schemas';
+import { EntryReplacementVariant as EntryReplacementVariant_2 } from '@contentful/optimization-api-client/api-schemas';
+import type { EntrySkeletonType } from 'contentful';
+import { EventBuilder } from '@contentful/optimization-api-client';
+import { EventBuilderConfig } from '@contentful/optimization-api-client';
+import { ExperienceApiClientConfig } from '@contentful/optimization-api-client';
+import { ExperienceEvent } from '@contentful/optimization-api-client/api-schemas';
+import { ExperienceEventArray } from '@contentful/optimization-api-client/api-schemas';
+import type { ExperienceEventType } from '@contentful/optimization-api-client/api-schemas';
+import { Flags } from '@contentful/optimization-api-client/api-schemas';
+import { GlobalApiConfigProperties } from '@contentful/optimization-api-client';
+import { IdentifyBuilderArgs } from '@contentful/optimization-api-client';
+import { InsightsApiClientConfig } from '@contentful/optimization-api-client';
+import { InsightsEvent } from '@contentful/optimization-api-client/api-schemas';
+import type { InsightsEventType } from '@contentful/optimization-api-client/api-schemas';
+import { Json } from '@contentful/optimization-api-client/api-schemas';
+import type { LocaleCode } from 'contentful';
+import type { LogLevels } from '@contentful/optimization-api-client/logger';
+import { MergeTagEntry } from '@contentful/optimization-api-client/api-schemas';
+import { OptimizationData } from '@contentful/optimization-api-client/api-schemas';
+import { PageViewBuilderArgs } from '@contentful/optimization-api-client';
+import { PartialProfile } from '@contentful/optimization-api-client/api-schemas';
+import { PersonalizationEntry } from '@contentful/optimization-api-schemas';
+import { PersonalizationEntry as PersonalizationEntry_2 } from '@contentful/optimization-api-client/api-schemas';
+import { PersonalizedEntry } from '@contentful/optimization-api-schemas';
+import { PersonalizedEntry as PersonalizedEntry_2 } from '@contentful/optimization-api-client/api-schemas';
+import { Profile } from '@contentful/optimization-api-client/api-schemas';
+import { ReadonlySignal } from '@preact/signals-core';
+import { ScreenViewBuilderArgs } from '@contentful/optimization-api-client';
+import { SelectedPersonalization } from '@contentful/optimization-api-client/api-schemas';
+import { SelectedPersonalization as SelectedPersonalization_2 } from '@contentful/optimization-api-schemas';
+import { SelectedPersonalizationArray } from '@contentful/optimization-api-client/api-schemas';
+import { Signal } from '@preact/signals-core';
+import { TrackBuilderArgs } from '@contentful/optimization-api-client';
+import { untracked } from '@preact/signals-core';
+
+/**
+ * Base class for analytics implementations (internal).
+ *
+ * @internal
+ * @remarks
+ * Concrete analytics classes should implement the component/flag view tracking
+ * methods below. This base is not part of the public API.
+ */
+declare abstract class AnalyticsBase extends ProductBase {
+    /**
+     * Track a UI component view event.
+     *
+     * @param payload - Component view builder arguments.
+     * @returns A promise that resolves when processing is complete (or `void`).
+     */
+    abstract trackComponentView(payload: ComponentViewBuilderArgs): Promise<void> | void;
+    /**
+     * Track a UI component click event.
+     *
+     * @param payload - Component click builder arguments.
+     * @returns A promise that resolves when processing is complete (or `void`).
+     */
+    abstract trackComponentClick(payload: ComponentClickBuilderArgs): Promise<void> | void;
+    /**
+     * Track a UI component hover event.
+     *
+     * @param payload - Component hover builder arguments.
+     * @returns A promise that resolves when processing is complete (or `void`).
+     */
+    abstract trackComponentHover(payload: ComponentHoverBuilderArgs): Promise<void> | void;
+    /**
+     * Track a flag (feature) view event.
+     *
+     * @param payload - Flag view builder arguments.
+     * @returns A promise that resolves when processing is complete (or `void`).
+     */
+    abstract trackFlagView(payload: ComponentViewBuilderArgs): Promise<void> | void;
+}
+
+/**
+ * Configuration for the stateful analytics implementation.
+ *
+ * @public
+ */
+export declare interface AnalyticsProductConfig extends ProductConfig {
+    /**
+     * Default signal values applied on initialization.
+     */
+    defaults?: AnalyticsProductConfigDefaults;
+    /**
+     * Policy that controls stateful queue flush retries, backoff, and circuit
+     * behavior after repeated failures.
+     */
+    queuePolicy?: QueueFlushPolicy;
+}
+
+/**
+ * Default analytics state values applied at construction time.
+ *
+ * @public
+ */
+export declare interface AnalyticsProductConfigDefaults {
+    /** Whether analytics collection is allowed by default. */
+    consent?: boolean;
+    /** Default profile to associate with events. */
+    profile?: Profile;
+}
+
+/**
+ * Analytics implementation that maintains local state (consent, profile) and
+ * queues events until flushed or the queue reaches a maximum size.
+ *
+ * @remarks
+ * Repeated flush failures are managed by the configured {@link QueueFlushPolicy}
+ * using bounded backoff and a temporary circuit-open window.
+ *
+ * @public
+ */
+export declare class AnalyticsStateful extends AnalyticsBase implements ConsentGuard {
+    /** In-memory queue keyed by stable profile identifier. */
+    private readonly queue;
+    /** Shared queue flush retry runtime state machine. */
+    private readonly flushRuntime;
+    /** Exposed observable state references. */
+    readonly states: AnalyticsStates;
+    /**
+     * Create a new stateful analytics instance.
+     *
+     * @param options - Options to configure the analytics product for stateful environments.
+     * @example
+     * ```ts
+     * const analytics = new AnalyticsStateful({ api, builder, config: { defaults: { consent: true } }, interceptors })
+     * ```
+     */
+    constructor(options: AnalyticsStatefulOptions);
+    /**
+     * Reset analytics‑related signals and the last emitted event.
+     *
+     * @example
+     * ```ts
+     * analytics.reset()
+     * ```
+     */
+    reset(): void;
+    /**
+     * Determine whether the named operation is permitted based on consent and
+     * allowed event type configuration.
+     *
+     * @param name - The method name; component view/flag methods are normalized
+     * to `'component'`, component click methods are normalized to `'component_click'`,
+     * and component hover methods are normalized to `'component_hover'` for
+     * allow‑list checks.
+     * @returns `true` if the operation is permitted; otherwise `false`.
+     * @example
+     * ```ts
+     * if (analytics.hasConsent('track')) { ... }
+     * ```
+     */
+    hasConsent(name: string): boolean;
+    /**
+     * Hook invoked when an operation is blocked due to missing consent.
+     *
+     * @param name - The blocked operation name.
+     * @param payload - The original arguments supplied to the operation.
+     * @example
+     * ```ts
+     * analytics.onBlockedByConsent('track', [payload])
+     * ```
+     */
+    onBlockedByConsent(name: string, payload: readonly unknown[]): void;
+    /**
+     * Queue a component view event for the active profile.
+     *
+     * @param payload - Component view builder arguments.
+     * @returns A promise that resolves when the event has been queued.
+     * @example
+     * ```ts
+     * await analytics.trackComponentView({ componentId: 'hero-banner' })
+     * ```
+     */
+    trackComponentView(payload: ComponentViewBuilderArgs): Promise<void>;
+    /**
+     * Queue a component click event for the active profile.
+     *
+     * @param payload - Component click builder arguments.
+     * @returns A promise that resolves when the event has been queued.
+     * @example
+     * ```ts
+     * await analytics.trackComponentClick({ componentId: 'hero-banner' })
+     * ```
+     */
+    trackComponentClick(payload: ComponentClickBuilderArgs): Promise<void>;
+    /**
+     * Queue a component hover event for the active profile.
+     *
+     * @param payload - Component hover builder arguments.
+     * @returns A promise that resolves when the event has been queued.
+     * @example
+     * ```ts
+     * await analytics.trackComponentHover({ componentId: 'hero-banner' })
+     * ```
+     */
+    trackComponentHover(payload: ComponentHoverBuilderArgs): Promise<void>;
+    /**
+     * Queue a flag view event for the active profile.
+     *
+     * @param payload - Flag view builder arguments.
+     * @returns A promise that resolves when the event has been queued.
+     * @example
+     * ```ts
+     * await analytics.trackFlagView({ componentId: 'feature-flag-123' })
+     * ```
+     */
+    trackFlagView(payload: ComponentViewBuilderArgs): Promise<void>;
+    /**
+     * Intercept, validate, and place an event into the profile‑scoped queue; then
+     * trigger a size‑based flush if necessary.
+     *
+     * @param event - The event to enqueue.
+     */
+    private enqueueEvent;
+    /**
+     * Flush the queue automatically when the total number of queued events
+     * reaches {@link MAX_QUEUED_EVENTS}.
+     */
+    private flushMaxEvents;
+    /**
+     * Send all queued events grouped by profile and clear the queue.
+     *
+     * @param options - Optional flush controls.
+     * @param options.force - When `true`, bypass offline/backoff/circuit gates and attempt immediately.
+     * @remarks Only under rare circumstances should there be more than one
+     * profile in a stateful application.
+     * @example
+     * ```ts
+     * await analytics.flush()
+     * ```
+     */
+    flush(options?: {
+        force?: boolean;
+    }): Promise<void>;
+    /**
+     * Apply default stateful analytics values when provided.
+     *
+     * @param defaults - Optional defaults for analytics state.
+     */
+    private applyDefaults;
+    /**
+     * Initialize reactive effects for consent/profile logging and online flushes.
+     */
+    private initializeEffects;
+    /**
+     * Build batch payloads grouped by profile from the in-memory queue.
+     *
+     * @returns Grouped batch payloads.
+     */
+    private createBatches;
+    /**
+     * Attempt to send queued batches to the Insights API.
+     *
+     * @param batches - Batches to send.
+     * @returns `true` when send succeeds; otherwise `false`.
+     */
+    private trySendBatches;
+    /**
+     * Compute the total number of queued events across all profiles.
+     *
+     * @returns Total queued event count.
+     */
+    private getQueuedEventCount;
+}
+
+/**
+ * Options for configuring {@link AnalyticsStateful} functionality.
+ *
+ * @public
+ * @see {@link ProductBaseOptions}
+ */
+export declare type AnalyticsStatefulOptions = ProductBaseOptions & {
+    /** Configuration specific to the Analytics product */
+    config?: AnalyticsProductConfig;
+};
+
+/**
+ * Stateless analytics implementation that sends each event immediately in a
+ * single‑event batch.
+ *
+ * @public
+ */
+export declare class AnalyticsStateless extends AnalyticsBase {
+    /**
+     * Build, intercept, validate, and send a component view event.
+     *
+     * @param args - {@link TrackComponentViewArgs} used to build the event. Includes an
+     * optional partial profile.
+     * @returns A promise that resolves once the batch has been sent.
+     * @example
+     * ```ts
+     * await analytics.trackComponentView({ componentId: 'hero-banner', profile: { id: 'user-1' } })
+     * ```
+     */
+    trackComponentView(args: TrackComponentViewArgs): Promise<void>;
+    /**
+     * Build, intercept, validate, and send a component click event.
+     *
+     * @param args - {@link TrackComponentClickArgs} used to build the event. Includes an
+     * optional partial profile.
+     * @returns A promise that resolves once the batch has been sent.
+     * @example
+     * ```ts
+     * await analytics.trackComponentClick({ componentId: 'hero-banner', profile: { id: 'user-1' } })
+     * ```
+     */
+    trackComponentClick(args: TrackComponentClickArgs): Promise<void>;
+    /**
+     * Build, intercept, validate, and send a component hover event.
+     *
+     * @param args - {@link TrackComponentHoverArgs} used to build the event. Includes an
+     * optional partial profile.
+     * @returns A promise that resolves once the batch has been sent.
+     * @example
+     * ```ts
+     * await analytics.trackComponentHover({ componentId: 'hero-banner', profile: { id: 'user-1' } })
+     * ```
+     */
+    trackComponentHover(args: TrackComponentHoverArgs): Promise<void>;
+    /**
+     * Build, intercept, validate, and send a flag view event.
+     *
+     * @param args - {@link TrackComponentViewArgs} used to build the event. Includes an
+     * optional partial profile.
+     * @returns A promise that resolves once the batch has been sent.
+     * @example
+     * ```ts
+     * await analytics.trackFlagView({ componentId: 'feature-flag-123' })
+     * ```
+     */
+    trackFlagView(args: TrackComponentViewArgs): Promise<void>;
+    /**
+     * Send a single {@link AnalyticsEvent} wrapped in a one‑item batch.
+     *
+     * @param event - The event to send.
+     * @param profile - Optional partial profile to attach to the batch.
+     * @returns A promise that resolves when the API call completes.
+     * @internal
+     */
+    private sendBatchEvent;
+}
+
+/**
+ * Observables exposed by the stateful analytics product.
+ *
+ * @public
+ */
+export declare interface AnalyticsStates {
+    /** Observable stream of the latest blocked event payload (or `undefined`). */
+    blockedEventStream: Observable<BlockedEvent | undefined>;
+    /** Observable stream of the latest {@link AnalyticsEvent} or {@link PersonalizationEvent} (or `undefined`). */
+    eventStream: Observable<InsightsEvent | ExperienceEvent | undefined>;
+    /** Observable stream of the active {@link Profile} (or `undefined`). */
+    profile: Observable<Profile | undefined>;
+}
+
+/**
+ * Anonymous-ID cookie name used by the Optimization Core.
+ *
+ * @public
+ * @remarks
+ * This constant represents the cookie key used by the Optimization Framework
+ * to persist an anonymous identifier for tracking personalization and analytics
+ * events when no explicit profile is known.
+ *
+ * @example
+ * ```ts
+ * import { ANONYMOUS_ID_COOKIE } from '@contentful/optimization-core/constants'
+ * const profileId = request.cookies[ANONYMOUS_ID_COOKIE]
+ * ```
+ */
+export declare const ANONYMOUS_ID_COOKIE = "ctfl-opt-aid";
+
+/**
+ * Legacy anoynmous ID cookie key for migration from experience.js
+ *
+ * @internal
+ */
+export declare const ANONYMOUS_ID_COOKIE_LEGACY = "ntaid";
+
+/**
+ * Storage key for the anonymous identifier.
+ *
+ * @internal
+ */
+export declare const ANONYMOUS_ID_KEY = "__ctfl_opt_anonymous_id__";
+
+/**
+ * Legacy anoynmous ID storage key for migration from experience.js
+ *
+ * @internal
+ */
+export declare const ANONYMOUS_ID_KEY_LEGACY = "__nt_anonymous_id__";
+
+export { batch }
+
+/**
+ * Payload emitted when event processing is blocked.
+ *
+ * @public
+ */
+export declare interface BlockedEvent {
+    /** Why the event was blocked. */
+    reason: BlockedEventReason;
+    /** Product that blocked the event. */
+    product: BlockedEventProduct;
+    /** Method name that was blocked. */
+    method: string;
+    /** Original arguments passed to the blocked method call. */
+    args: readonly unknown[];
+}
+
+declare const blockedEvent: Signal<BlockedEvent | undefined>;
+
+/**
+ * Product that blocked the event.
+ *
+ * @public
+ */
+export declare type BlockedEventProduct = 'analytics' | 'personalization';
+
+/**
+ * Reasons why an event was blocked before being sent.
+ *
+ * @public
+ */
+export declare type BlockedEventReason = 'consent';
+
+/**
+ * A callback invoked when a method call is blocked by {@link guardedBy}.
+ *
+ * @param methodName - The name of the method that was attempted.
+ * @param args - The readonly array of arguments supplied to the blocked call.
+ * @returns Nothing.
+ *
+ * @public
+ */
+declare type BlockHandler = (methodName: string, args: readonly unknown[]) => void;
+
+declare const changes: Signal<ChangeArray | undefined>;
+
+/**
+ * Storage key for cached Custom Flags.
+ *
+ * @internal
+ */
+export declare const CHANGES_CACHE_KEY = "__ctfl_opt_changes__";
+
+declare const consent: Signal<boolean | undefined>;
+
+/**
+ * Storage key for the persisted consent status.
+ *
+ * @internal
+ */
+export declare const CONSENT_KEY = "__ctfl_opt_consent__";
+
+/**
+ * Controller for updating the current consent state.
+ *
+ * @internal
+ * @remarks
+ * Intended for internal wiring between Core classes and the consent signal/store.
+ */
+declare interface ConsentController {
+    /**
+     * Update the runtime consent state.
+     *
+     * @param accept - `true` when the user has granted consent; `false` otherwise.
+     */
+    consent: (accept: boolean) => void;
+}
+
+/**
+ * Contract implemented by classes that gate operations based on consent.
+ *
+ * @internal
+ * @remarks
+ * These methods are consumed by the `@guardedBy` decorator to decide whether to
+ * proceed with an operation and how to report blocked calls.
+ */
+declare interface ConsentGuard {
+    /**
+     * Determine whether the named operation is permitted given current consent and
+     * any allow‑list configuration.
+     *
+     * @param name - Logical operation/method name (e.g., `'track'`, `'page'`).
+     * @returns `true` if the operation may proceed; otherwise `false`.
+     * @remarks
+     * The mapping between method names and event type strings may be product‑specific.
+     */
+    hasConsent: (name: string) => boolean;
+    /**
+     * Hook invoked when an operation is blocked due to missing consent.
+     *
+     * @param name - The blocked operation/method name.
+     * @param args - The original call arguments, provided for diagnostics/telemetry.
+     * @returns Nothing. Implementations typically log and/or emit diagnostics.
+     */
+    onBlockedByConsent: (name: string, args: unknown[]) => void;
+}
+
+/**
+ * Internal base that wires the API client, event builder, and logging.
+ *
+ * @internal
+ */
+declare abstract class CoreBase implements ResolverMethods {
+    /** Product implementation for analytics. */
+    protected abstract _analytics: AnalyticsBase;
+    /** Product implementation for personalization. */
+    protected abstract _personalization: PersonalizationBase;
+    /** Shared Optimization API client instance. */
+    readonly api: ApiClient;
+    /** Shared event builder instance. */
+    readonly eventBuilder: EventBuilder;
+    /** Resolved core configuration (minus any name metadata). */
+    readonly config: Omit<CoreConfig, 'name'>;
+    /** Lifecycle interceptors for events and state updates. */
+    readonly interceptors: LifecycleInterceptors;
+    /**
+     * Create the core with API client and logging preconfigured.
+     *
+     * @param config - Core configuration including API and builder options.
+     * @example
+     * ```ts
+     * const sdk = new CoreStateless({ clientId: 'abc123', environment: 'prod' })
+     * ```
+     */
+    constructor(config: CoreConfig);
+    /**
+     * Static {@link FlagsResolver | resolver} for evaluating personalized
+     * custom flags.
+     */
+    get flagsResolver(): typeof FlagsResolver;
+    /**
+     * Static {@link MergeTagValueResolver | resolver} that returns values
+     * sourced from a user profile based on a Contentful Merge Tag entry.
+     */
+    get mergeTagValueResolver(): typeof MergeTagValueResolver;
+    /**
+     * Static {@link PersonalizedEntryResolver | resolver } for personalized
+     * Contentful entries (e.g., entry variants targeted to a profile audience).
+     *
+     * @remarks
+     * Used by higher-level personalization flows to materialize entry content
+     * prior to event emission.
+     */
+    get personalizedEntryResolver(): typeof PersonalizedEntryResolver;
+    /**
+     * Get the value of a custom flag derived from a set of optimization changes.
+     *
+     * @param name - The flag key to resolve.
+     * @param changes - Optional change list to resolve from.
+     * @returns The resolved JSON value for the flag if available.
+     * @remarks
+     * This is a convenience wrapper around personalization’s flag resolution.
+     * @example
+     * ```ts
+     * const darkMode = core.getCustomFlag('dark-mode', data.changes)
+     * ```
+     */
+    getCustomFlag(name: string, changes?: ChangeArray): Json;
+    /**
+     * Get all resolved custom flags derived from a set of optimization changes.
+     *
+     * @param changes - Optional change list to resolve from.
+     * @returns The resolved custom flag map.
+     * @remarks
+     * This is a convenience wrapper around personalization’s flag resolution.
+     * @example
+     * ```ts
+     * const flags = core.getCustomFlags(data.changes)
+     * ```
+     */
+    getCustomFlags(changes?: ChangeArray): Flags;
+    /**
+     * Resolve a Contentful entry to the appropriate personalized variant (or
+     * return the baseline entry if no matching variant is selected).
+     *
+     * @typeParam S - Entry skeleton type.
+     * @typeParam M - Chain modifiers.
+     * @typeParam L - Locale code.
+     * @param entry - The baseline entry to resolve.
+     * @param personalizations - Optional selection array for the current profile.
+     * @returns {@link ResolvedData} containing the resolved entry and
+         *   personalization metadata (if any).
+         * @example
+         * ```ts
+         * const { entry, personalization } = core.personalizeEntry(baselineEntry, data.personalizations)
+         * ```
+         */
+     personalizeEntry<S extends EntrySkeletonType, M extends ChainModifiers = ChainModifiers, L extends LocaleCode = LocaleCode>(entry: Entry<S, M, L>, personalizations?: SelectedPersonalizationArray): ResolvedData<S, M, L>;
+     /**
+      * Resolve a merge-tag value from the given entry node and profile.
+      *
+      * @param embeddedEntryNodeTarget - The merge-tag entry node to resolve.
+      * @param profile - Optional profile used for value lookup.
+      * @returns The resolved value (typically a string) or `undefined` if not found.
+      * @example
+      * ```ts
+      * const name = core.getMergeTagValue(mergeTagNode, profile)
+      * ```
+      */
+     getMergeTagValue(embeddedEntryNodeTarget: MergeTagEntry, profile?: Profile): string | undefined;
+     /**
+      * Convenience wrapper for sending an `identify` event via personalization.
+      *
+      * @param payload - Identify builder arguments.
+      * @returns The resulting {@link OptimizationData} for the identified user.
+      * @example
+      * ```ts
+      * const data = await core.identify({ userId: 'user-123', traits: { plan: 'pro' } })
+      * ```
+      */
+     identify(payload: IdentifyBuilderArgs & {
+         profile?: PartialProfile;
+     }): Promise<OptimizationData | undefined>;
+     /**
+      * Convenience wrapper for sending a `page` event via personalization.
+      *
+      * @param payload - Page view builder arguments.
+      * @returns The evaluated {@link OptimizationData} for this page view.
+      * @example
+      * ```ts
+      * const data = await core.page({ properties: { title: 'Home' } })
+      * ```
+      */
+     page(payload: PageViewBuilderArgs & {
+         profile?: PartialProfile;
+     }): Promise<OptimizationData | undefined>;
+     /**
+      * Convenience wrapper for sending a `screen` event via personalization.
+      *
+      * @param payload - Screen view builder arguments.
+      * @returns The evaluated {@link OptimizationData} for this screen view.
+      * @example
+      * ```ts
+      * const data = await core.screen({ name: 'HomeScreen' })
+      * ```
+      */
+     screen(payload: ScreenViewBuilderArgs & {
+         profile?: PartialProfile;
+     }): Promise<OptimizationData | undefined>;
+     /**
+      * Convenience wrapper for sending a custom `track` event via personalization.
+      *
+      * @param payload - Track builder arguments.
+      * @returns The evaluated {@link OptimizationData} for this event.
+      * @example
+      * ```ts
+      * const data = await core.track({ event: 'button_click', properties: { label: 'Buy' } })
+      * ```
+      */
+     track(payload: TrackBuilderArgs & {
+         profile?: PartialProfile;
+     }): Promise<OptimizationData | undefined>;
+     /**
+      * Track a component view in both personalization and analytics.
+      *
+      * @param payload - Component view builder arguments. When `payload.sticky` is
+      *   `true`, the event will also be sent via personalization as a sticky
+      *   component view.
+      * @returns A promise that resolves when all delegated calls complete.
+      * @remarks
+      * The sticky behavior is delegated to personalization; analytics is always
+      * invoked regardless of `sticky`.
+      * @example
+      * ```ts
+      * await core.trackComponentView({ componentId: 'hero-banner', sticky: true })
+      * ```
+      */
+     trackComponentView(payload: ComponentViewBuilderArgs & {
+         profile?: PartialProfile;
+     }): Promise<OptimizationData | undefined>;
+     /**
+      * Track a component click via analytics.
+      *
+      * @param payload - Component click builder arguments.
+      * @returns A promise that resolves when processing completes.
+      * @example
+      * ```ts
+      * await core.trackComponentClick({ componentId: 'hero-banner' })
+      * ```
+      */
+     trackComponentClick(payload: ComponentClickBuilderArgs): Promise<void>;
+     /**
+      * Track a component hover via analytics.
+      *
+      * @param payload - Component hover builder arguments.
+      * @returns A promise that resolves when processing completes.
+      * @example
+      * ```ts
+      * await core.trackComponentHover({ componentId: 'hero-banner' })
+      * ```
+      */
+     trackComponentHover(payload: ComponentHoverBuilderArgs): Promise<void>;
+     /**
+      * Track a feature flag view via analytics.
+      *
+      * @param payload - Component view builder arguments used to build the flag view event.
+      * @returns A promise that resolves when processing completes.
+      * @example
+      * ```ts
+      * await core.trackFlagView({ componentId: 'feature-flag-123' })
+      * ```
+      */
+     trackFlagView(payload: ComponentViewBuilderArgs): Promise<void>;
+    }
+
+    /**
+     * Options for configuring the {@link CoreBase} runtime and underlying clients.
+     *
+     * @public
+     */
+    export declare interface CoreConfig extends Pick<ApiClientConfig, GlobalApiConfigProperties> {
+        /**
+         * Configuration for the personalization (Experience) API client.
+         */
+        personalization?: Omit<ExperienceApiClientConfig, GlobalApiConfigProperties>;
+        /**
+         * Configuration for the analytics (Insights) API client.
+         */
+        analytics?: Omit<InsightsApiClientConfig, GlobalApiConfigProperties>;
+        /**
+         * Event builder configuration (channel/library metadata, etc.).
+         */
+        eventBuilder?: EventBuilderConfig;
+        /** Minimum log level for the default console sink. */
+        logLevel?: LogLevels;
+    }
+
+    /**
+     * Default values used to preconfigure the stateful core and products.
+     *
+     * @public
+     */
+    export declare interface CoreConfigDefaults {
+        /** Global consent default applied at construction time. */
+        consent?: boolean;
+        /** Default active profile used for personalization and analytics. */
+        profile?: Profile;
+        /** Initial diff of changes produced by the service. */
+        changes?: ChangeArray;
+        /** Preselected personalization variants (e.g., winning treatments). */
+        personalizations?: SelectedPersonalizationArray;
+    }
+
+    /**
+     * Core runtime that constructs stateful product instances and exposes shared
+     * states, including consent, blocked events, and the event stream.
+     *
+     * @remarks
+     * Extends {@link CoreBase} with stateful capabilities, including
+     * consent management via {@link ConsentController}.
+     * @see {@link CoreBase}
+     * @see {@link ConsentController}
+     * @public
+     */
+    export declare class CoreStateful extends CoreBase implements ConsentController {
+        private readonly singletonOwner;
+        private destroyed;
+        /** Stateful analytics product. */
+        protected _analytics: AnalyticsStateful;
+        /** Stateful personalization product. */
+        protected _personalization: PersonalizationStateful;
+        /**
+         * Create a stateful core with optional default consent and product defaults.
+         *
+         * @param config - Core and defaults configuration.
+         * @example
+         * ```ts
+         * const core = new CoreStateful({
+         *   clientId: 'app',
+         *   environment: 'prod',
+         *   defaults: { consent: true }
+         * })
+         * core.consent(true)
+         * ```
+         */
+        constructor(config: CoreStatefulConfig);
+        /**
+         * Release singleton ownership for stateful runtime usage.
+         *
+         * @remarks
+         * This method is idempotent and should be called when a stateful SDK instance
+         * is no longer needed (e.g. tests, hot reload, explicit teardown).
+         */
+        destroy(): void;
+        /**
+         * Expose merged observable state for consumers.
+         *
+         * @returns The combined {@link CoreStates} observable object.
+         */
+        get states(): CoreStates;
+        /**
+         * Reset internal state. Consent and preview panel state are intentionally preserved.
+         *
+         * @remarks
+         * Resetting personalization also resets analytics dependencies as a
+         * consequence of the current shared-state design.
+         * @example
+         * ```ts
+         * core.reset()
+         * ```
+         */
+        reset(): void;
+        /**
+         * Flush the queues for both the analytics and personalization products.
+         * @remarks
+         * The personalization queue is only populated if events have been triggered
+         * while a device is offline.
+         * @example
+         * ```ts
+         * await core.flush()
+         * ```
+         */
+        flush(): Promise<void>;
+        /**
+         * Update consent state
+         *
+         * @param accept - `true` if the user has granted consent; `false` otherwise.
+         * @example
+         * ```ts
+         * core.consent(true)
+         * ```
+         */
+        consent(accept: boolean): void;
+        /**
+         * Read current online state.
+         *
+         * @example
+         * ```ts
+         * if (this.online) {
+         *   await this.flush()
+         * }
+         * ```
+         */
+        protected get online(): boolean;
+        /**
+         * Update online state.
+         *
+         * @param isOnline - `true` if the runtime is online; `false` otherwise.
+         * @example
+         * ```ts
+         * this.online = navigator.onLine
+         * ```
+         */
+        protected set online(isOnline: boolean);
+        /**
+         * Register a preview panel compatible object to receive direct signal access.
+         * This enables the preview panel to modify SDK state for testing and simulation.
+         *
+         * @param previewPanel - An object implementing PreviewPanelSignalObject
+         * @remarks
+         * This method is intended for use by the Preview Panel component.
+         * Direct signal access allows immediate state updates without API calls.
+         * @example
+         * ```ts
+         * const previewBridge: PreviewPanelSignalObject = {}
+         * core.registerPreviewPanel(previewBridge)
+         * ```
+         */
+        registerPreviewPanel(previewPanel: PreviewPanelSignalObject): void;
+    }
+
+    /**
+     * Stateful analytics configuration.
+     *
+     * @public
+     */
+    export declare type CoreStatefulAnalyticsConfig = NonNullable<CoreConfig['analytics']> & {
+        /**
+         * Queue policy for stateful analytics event buffering and flush retries.
+         *
+         * @see {@link AnalyticsProductConfig.queuePolicy}
+         */
+        queuePolicy?: AnalyticsProductConfig['queuePolicy'];
+    };
+
+    /**
+     * Configuration for {@link CoreStateful}.
+     *
+     * @public
+     * @see {@link CoreConfig}
+     */
+    export declare interface CoreStatefulConfig extends CoreConfig {
+        /**
+         * Configuration for the analytics (Insights) API client plus stateful queue behavior.
+         */
+        analytics?: CoreStatefulAnalyticsConfig;
+        /**
+         * Configuration for the personalization (Experience) API client plus stateful queue behavior.
+         */
+        personalization?: CoreStatefulPersonalizationConfig;
+        /**
+         * Allow-listed event type strings permitted when consent is not set.
+         *
+         * @see {@link ProductConfig.allowedEventTypes}
+         */
+        allowedEventTypes?: ProductConfig['allowedEventTypes'];
+        /** Optional set of default values applied on initialization. */
+        defaults?: CoreConfigDefaults;
+        /** Function used to obtain an anonymous user identifier. */
+        getAnonymousId?: PersonalizationProductConfig['getAnonymousId'];
+        /**
+         * Callback invoked whenever an event call is blocked by checks.
+         */
+        onEventBlocked?: ProductConfig['onEventBlocked'];
+    }
+
+    /**
+     * Stateful personalization configuration.
+     *
+     * @public
+     */
+    export declare type CoreStatefulPersonalizationConfig = NonNullable<CoreConfig['personalization']> & {
+        /**
+         * Queue policy for stateful personalization offline event buffering.
+         *
+         * @see {@link PersonalizationProductConfig.queuePolicy}
+         */
+        queuePolicy?: PersonalizationProductConfig['queuePolicy'];
+    };
+
+    /**
+     * Core runtime that constructs product instances for stateless environments.
+     *
+     * @public
+     * @see {@link CoreBase}
+     */
+    export declare class CoreStateless extends CoreBase {
+        /** Stateless analytics product. */
+        protected _analytics: AnalyticsStateless;
+        /** Stateless personalization product. */
+        protected _personalization: PersonalizationStateless;
+        /**
+         * Create a stateless core. Product instances share the same API client and
+         * event builder configured in {@link CoreBase}.
+         *
+         * @param config - Stateless Core configuration.
+         * @example
+         * ```ts
+         * const sdk = new CoreStateless({ clientId: 'app', environment: 'prod' })
+         * core.trackFlagView({ componentId: 'hero' })
+         * ```
+         */
+        constructor(config: CoreStatelessConfig);
+    }
+
+    /**
+     * Configuration for the Node-specific Optimization SDK.
+     *
+     * @public
+     * @remarks
+     * This configuration extends {@link CoreConfig} but allows partial overrides
+     * of the event-builder configuration. SDKs commonly inject their own library
+     * metadata or channel definitions.
+     */
+    export declare interface CoreStatelessConfig extends CoreConfig {
+        /**
+         * Override configuration for the analytics (Insights) API client. Omits
+         * `beaconHandler`.
+         */
+        analytics?: Omit<CoreConfig['analytics'], 'beaconHandler'>;
+        /**
+         * Overrides for the event builder configuration. Omits methods that are only
+         * useful in stateful environments.
+         */
+        eventBuilder?: Omit<EventBuilderConfig, 'getLocale' | 'getPageProperties' | 'getUserAgent'>;
+    }
+
+    /**
+     * Combined observable state exposed by the stateful core.
+     *
+     * @public
+     * @see {@link AnalyticsStates}
+     * @see {@link PersonalizationStates}
+     */
+    export declare interface CoreStates extends AnalyticsStates, PersonalizationStates {
+        /** Current consent value (if any). */
+        consent: Observable<boolean | undefined>;
+        /** Whether the preview panel has been attached to the host runtime. */
+        previewPanelAttached: Observable<boolean>;
+        /** Whether the preview panel is currently open in the host runtime. */
+        previewPanelOpen: Observable<boolean>;
+        /** Stream of the most recent blocked event payload. */
+        blockedEventStream: Observable<BlockedEvent | undefined>;
+        /** Stream of the most recent event emitted (analytics or personalization). */
+        eventStream: Observable<InsightsEvent | ExperienceEvent | undefined>;
+    }
+
+    /**
+     * Storage key for the debug flag toggle.
+     *
+     * @internal
+     */
+    export declare const DEBUG_FLAG_KEY = "__ctfl_opt_debug__";
+
+    export { effect }
+
+    declare const event_2: Signal<InsightsEvent | ExperienceEvent | undefined>;
+
+    /**
+     * Union of all event {@link AnalyticsEventType | type keys} that this package may emit.
+     *
+     * @public
+     */
+    declare type EventType = InsightsEventType | ExperienceEventType;
+
+    declare const flags: ReadonlySignal<Flags | undefined>;
+
+    /**
+     * Resolves a {@link Flags} map from a list of optimization changes.
+     *
+     * @public
+     * @remarks
+     * Given an Optimization {@link ChangeArray}, this utility flattens the list into a
+     * simple key–value object suitable for quick lookups in client code. When `changes`
+     * is `undefined`, an empty object is returned. If a change value is wrapped in an
+     * object like `{ value: { ... } }`, this resolver unwraps it to the underlying object.
+     */
+    export declare const FlagsResolver: {
+        /**
+         * Build a flattened map of flag keys to values from a change list.
+         *
+         * @param changes - The change list returned by the optimization service.
+         * @returns A map of flag keys to their resolved values.
+         * @example
+         * ```ts
+         * const flags = FlagsResolver.resolve(data.changes)
+         * if (flags['theme'] === 'dark') enableDarkMode()
+         * ```
+         * @example
+         * // Handles wrapped values produced by the API
+         * ```ts
+         * const flags = FlagsResolver.resolve([
+         *   { type: 'Variable', key: 'price', value: { value: { amount: 10, currency: 'USD' } } }
+         * ])
+         * console.log(flags.price.amount) // 10
+         * ```
+         */
+        resolve(changes?: ChangeArray): Flags;
+    };
+
+    /**
+     * Decorator factory that **guards** class methods behind a synchronous predicate.
+     *
+     * When a decorated method is invoked:
+     * - If the predicate returns a value that evaluates to **allowed** (see `invert`), the original
+     *   method is executed and its result is returned.
+     * - If the call is **blocked**, the optional `onBlocked` hook is invoked (if configured) and:
+     *   - `undefined` is returned for sync methods; or
+     *   - `Promise<undefined>` is returned for async methods (to preserve `await` compatibility).
+     *
+     * @typeParam T - The instance type that owns both the predicate and the decorated method.
+     *
+     * @param predicateName - The name (string or symbol) of a **synchronous** instance method on `this`
+     * that acts as the predicate. It is called as `this[predicateName](methodName, argsArray)`.
+     * @param opts - Optional {@link GuardedByOptions | options} to configure inversion and `onBlocked`.
+     *
+     * @returns A methods-only class decorator compatible with Stage-3 decorators that wraps the method.
+     *
+     * @throws TypeError
+     * Thrown at initialization time (first instance construction) if `predicateName` does not resolve
+     * to a **synchronous function** on the instance.
+     *
+     * @remarks
+     * - This is a **methods-only** decorator; applying it to accessors/fields is a no-op.
+     * - The decorator preserves the original method's sync/async shape.
+     * - The predicate is invoked with `(decoratedMethodName, argsArray)` to support context-aware checks.
+     *
+     * @example
+     * Here, `canRun` allows the call when it returns truthy:
+     * ```ts
+     * class Runner {
+     *   canRun(method: string, _args: readonly unknown[]) { return method !== 'stop'; }
+     *
+     *   @guardedBy<Runner>('canRun')
+     *   go() { console.log('running'); }
+     * }
+     * ```
+     *
+     * @example
+     * Invert the predicate and call a handler on block:
+     * ```ts
+     * class Door {
+     *   isLocked() { return true } // truthy means "locked"
+     *   onBlocked(method: string) { console.warn(`${method} blocked`) }
+     *
+     *   @guardedBy<Door>('isLocked', { invert: true, onBlocked: 'onBlocked' })
+     *   open() { /* ... *\/ }
+     * }
+     * ```
+     *
+     * @public
+     */
+    export declare function guardedBy<T extends object>(predicateName: keyof T & (string | symbol), opts?: GuardedByOptions<T>): GuardedByFunction<T>;
+
+    /**
+     * The original method implementation.
+     *
+     * @typeParam A - The parameter tuple of the original method.
+     * @typeParam R - The return type of the original method.
+     * @param value - The method being decorated.
+     * @param context - The Stage-3 decorator context for a class method.
+     * @returns Nothing.
+     *
+     * @remarks
+     * Users do not call this directly; it's returned by {@link guardedBy}.
+     *
+     * @internal
+     */
+    declare type GuardedByFunction<T extends object> = <A extends readonly unknown[], R>(value: (...args: A) => R, context: ClassMethodDecoratorContext<T, (...args: A) => R>) => void;
+
+    /**
+     * Options that tweak the behavior of {@link guardedBy}.
+     *
+     * @typeParam T - The instance type on which the decorator is applied.
+     *
+     * @public
+     */
+    declare interface GuardedByOptions<T extends object> {
+        /**
+         * Inverts the predicate result.
+         *
+         * When `true`, a truthy predicate result **blocks** the method.
+         * When `false` (default) or omitted, a truthy predicate result **allows** the method.
+         *
+         * @defaultValue `false`
+         * @remarks
+         * This option is useful when the predicate expresses a *forbid* condition
+         * (e.g. "isLocked" or "isDestroyed") rather than an *allow* condition.
+         */
+        readonly invert?: boolean;
+        /**
+         * Either a function to call when a method is blocked, or the name/symbol of
+         * an instance method on `this` to call when blocked.
+         *
+         * Both forms are **synchronous** and receive `(methodName, argsArray)`.
+         * If omitted, blocked calls fail silently (i.e., return `undefined` or
+         * `Promise<undefined>` for async methods).
+         *
+         * @remarks
+         * - If a property key is supplied and the instance does not have a callable at that key,
+         *   the hook is ignored.
+         * - The hook **must not** be `async`; any async work should be scheduled manually.
+         */
+        readonly onBlocked?: BlockHandler | (keyof T & (string | symbol));
+    }
+
+    /**
+     * A function that receives a value of type `T` and returns a (possibly async)
+     * value of the same type `T`. The input is marked as `readonly` to discourage
+     * mutation of the original object.
+     *
+     * @typeParam T - The value type intercepted and returned.
+     * @param value - The current (readonly) value in the interception chain.
+     * @returns The next value for the chain, either directly or via a promise.
+     * @remarks Implementations SHOULD avoid mutating `value` and instead return a
+     * new or safely-updated instance.
+     * @see {@link InterceptorManager}
+     * @public
+     */
+    export declare type Interceptor<T> = (value: Readonly<T>) => MaybePromise<T>;
+
+    /**
+     * Manages a list of interceptors and provides a way to run them in sequence.
+     *
+     * Interceptors are executed in insertion order. Each interceptor receives the
+     * result of the previous interceptor (or the initial input for the first one)
+     * and may return a new value synchronously or asynchronously.
+     *
+     * @typeParam T - The value type processed by the interceptors.
+     * @remarks This class snapshots the current interceptor list at invocation time
+     * so additions/removals during `run` do not affect the in-flight execution.
+     * @example
+     * ```ts
+     * const mgr = new InterceptorManager<number>();
+     * const id = mgr.add((n) => n + 1);
+     * const final = await mgr.run(1); // 2
+     * mgr.remove(id);
+     * ```
+     * @public
+     */
+    export declare class InterceptorManager<T> {
+        /**
+         * The registry of interceptors keyed by their insertion id.
+         *
+         * @privateRemarks Internal storage; use {@link add}, {@link remove}, and
+         * {@link clear} to manage contents.
+         * @readonly
+         * @defaultValue `new Map()`
+         */
+        private readonly interceptors;
+        /**
+         * The next numeric id to assign to an added interceptor.
+         *
+         * @privateRemarks Used only to generate unique, monotonically increasing ids.
+         * @defaultValue `0`
+         */
+        private nextId;
+        /**
+         * Add an interceptor and return its identifier.
+         *
+         * @param interceptor - The interceptor function to register.
+         * @returns The numeric id that can later be used with {@link remove}.
+         * @remarks Interceptors are executed in the order they are added.
+         * @example
+         * ```ts
+         * const id = manager.add(async (value) => transform(value));
+         * ```
+         * @public
+         */
+        add(interceptor: Interceptor<T>): number;
+        /**
+         * Remove an interceptor by its identifier.
+         *
+         * @param id - The id previously returned by {@link add}.
+         * @returns `true` if an interceptor was removed; otherwise `false`.
+         * @example
+         * ```ts
+         * const removed = manager.remove(id);
+         * ```
+         * @public
+         */
+        remove(id: number): boolean;
+        /**
+         * Remove all registered interceptors.
+         *
+         * @returns Nothing.
+         * @remarks After calling this, {@link count} will return `0`.
+         * @example
+         * ```ts
+         * manager.clear();
+         * ```
+         * @public
+         */
+        clear(): void;
+        /**
+         * Get the number of currently registered interceptors.
+         *
+         * @returns The count of interceptors.
+         * @example
+         * ```ts
+         * if (manager.count() === 0) { /* ... *\/ }
+         * ```
+         * @public
+         */
+        count(): number;
+        /**
+         * Run all interceptors in sequence on an input value and return the final result.
+         *
+         * Supports both sync and async interceptors; the return type is always `Promise<T>`
+         * for consistency.
+         *
+         * @param input - The initial value to pass to the first interceptor.
+         * @returns A promise resolving to the final value after all interceptors have run.
+         * @throws May rethrow any error thrown by an interceptor. <!-- Intentionally vague: error type depends on interceptor implementation -->
+         * @remarks The interceptor list is snapshotted at invocation time; changes to
+         * the registry during execution do not affect the running sequence.
+         * @example
+         * ```ts
+         * const result = await manager.run(initial);
+         * ```
+         * @public
+         */
+        run(input: T): Promise<T>;
+    }
+
+    /**
+     * Lifecycle container for event and state interceptors.
+     *
+     * @public
+     */
+    export declare interface LifecycleInterceptors {
+        /** Interceptors invoked for individual events prior to validation/sending. */
+        event: InterceptorManager<InsightsEvent | ExperienceEvent>;
+        /** Interceptors invoked before optimization state updates. */
+        state: InterceptorManager<OptimizationData>;
+    }
+
+    /**
+     * A utility type representing a value that may be synchronously available or
+     * produced asynchronously.
+     *
+     * @typeParam T - The resolved value type.
+     * @public
+     */
+    declare type MaybePromise<T> = T | Promise<T>;
+
+    /**
+     * Resolves merge tag values from a {@link Profile}.
+     *
+     * @public
+     * @remarks
+     * *Merge tags* are references to user profile data that may be embedded in content
+     * and expanded at runtime. This resolver normalizes the merge-tag identifier into
+     * a set of candidate selectors and searches the profile for a matching value.
+     * Result values are returned as strings; numeric/boolean primitives are stringified.
+     */
+    export declare const MergeTagValueResolver: {
+        /**
+         * Generate a list of candidate selectors for a merge-tag ID.
+         *
+         * @param id - Merge-tag identifier (segments separated by `_`).
+         * @returns Array of dot-path selectors to try against a profile.
+         * @example
+         * ```ts
+         * // "profile_name_first" -> [
+         * //   'profile',
+         * //   'profile.name',
+         * //   'profile.name.first'
+         * // ]
+         * const selectors = MergeTagValueResolver.normalizeSelectors('profile_name_first')
+         * ```
+         */
+        normalizeSelectors(id: string): string[];
+        /**
+         * Look up a merge-tag value from a profile using normalized selectors.
+         *
+         * @param id - Merge-tag identifier.
+         * @param profile - Profile from which to resolve the value.
+         * @returns A stringified primitive if found; otherwise `undefined`.
+         * @remarks
+         * Only string/number/boolean primitives are returned; objects/arrays are ignored.
+         * @example
+         * ```ts
+         * const value = MergeTagValueResolver.getValueFromProfile('user_email', profile)
+         * if (value) sendEmailTo(value)
+         * ```
+         */
+        getValueFromProfile(id: string, profile?: Profile): string | undefined;
+        /**
+         * Resolve the display value for a merge-tag entry using the provided profile,
+         * falling back to the entry's configured `nt_fallback` when necessary.
+         *
+         * @param mergeTagEntry - The merge-tag entry to resolve.
+         * @param profile - Optional profile used for lookup.
+         * @returns The resolved string, or `undefined` if the entry is invalid and no
+         * fallback is available.
+         * @example
+         * ```ts
+         * const text = MergeTagValueResolver.resolve(entry, profile)
+         * render(text ?? 'Guest')
+         * ```
+         */
+        resolve(mergeTagEntry: MergeTagEntry | undefined, profile?: Profile): string | undefined;
+    };
+
+    declare interface Observable<T> {
+        subscribe: (next: (v: T) => void) => Subscription;
+    }
+
+    declare const online: Signal<boolean | undefined>;
+
+    /**
+     * The package name of the Optimization Core SDK, injected at build time.
+     *
+     * @public
+     */
+    export declare const OPTIMIZATION_CORE_SDK_NAME: string;
+
+    /**
+     * The current version of the Optimization Core SDK, injected at build time.
+     *
+     * @public
+     */
+    export declare const OPTIMIZATION_CORE_SDK_VERSION: string;
+
+    /**
+     * Internal base for personalization products.
+     *
+     * @internal
+     * @remarks
+     * Concrete implementations should extend this class to expose public methods for
+     * identify, page, and track events. This base wires in shared singleton
+     * resolvers used to fetch/resolve personalized data.
+     */
+    export declare abstract class PersonalizationBase extends ProductBase implements ResolverMethods {
+        /**
+         * Static {@link FlagsResolver | resolver} for evaluating personalized
+         * custom flags.
+         */
+        readonly flagsResolver: {
+            resolve(changes?: ChangeArray): Flags;
+        };
+        /**
+         * Static {@link MergeTagValueResolver | resolver} that returns values
+         * sourced from a user profile based on a Contentful Merge Tag entry.
+         */
+        readonly mergeTagValueResolver: {
+            normalizeSelectors(id: string): string[];
+            getValueFromProfile(id: string, profile?: Profile): string | undefined;
+            resolve(mergeTagEntry: MergeTagEntry | undefined, profile?: Profile): string | undefined;
+        };
+        /**
+         * Static {@link PersonalizedEntryResolver | resolver } for personalized
+         * Contentful entries (e.g., entry variants targeted to a profile audience).
+         *
+         * @remarks
+         * Used by higher-level personalization flows to materialize entry content
+         * prior to event emission.
+         */
+        readonly personalizedEntryResolver: {
+            getPersonalizationEntry({ personalizedEntry, selectedPersonalizations, }: {
+                personalizedEntry: PersonalizedEntry;
+                selectedPersonalizations: SelectedPersonalizationArray;
+            }, skipValidation?: boolean): PersonalizationEntry | undefined;
+            getSelectedPersonalization({ personalizationEntry, selectedPersonalizations, }: {
+                personalizationEntry: PersonalizationEntry;
+                selectedPersonalizations: SelectedPersonalizationArray;
+            }, skipValidation?: boolean): SelectedPersonalization_2 | undefined;
+            getSelectedVariant({ personalizedEntry, personalizationEntry, selectedVariantIndex, }: {
+                personalizedEntry: PersonalizedEntry;
+                personalizationEntry: PersonalizationEntry;
+                selectedVariantIndex: number;
+            }, skipValidation?: boolean): EntryReplacementVariant | undefined;
+            getSelectedVariantEntry<S extends EntrySkeletonType, M extends ChainModifiers = ChainModifiers, L extends LocaleCode = string>({ personalizationEntry, selectedVariant, }: {
+                personalizationEntry: PersonalizationEntry;
+                selectedVariant: EntryReplacementVariant;
+            }, skipValidation?: boolean): Entry<S, M, L> | undefined;
+            resolve<S extends EntrySkeletonType, M extends ChainModifiers = ChainModifiers, L extends LocaleCode = string>(entry: Entry<S, M, L>, selectedPersonalizations?: SelectedPersonalizationArray): ResolvedData<S, M, L>;
+        };
+        /**
+         * Get the specified Custom Flag's value from the supplied changes.
+         * @param name - The name/key of the Custom Flag.
+         * @param changes - Optional changes array.
+         * @returns The current value of the Custom Flag if found.
+         * @remarks
+         * The changes array can be sourced from the data returned when emitting any
+         * personalization event.
+         * */
+        getCustomFlag(name: string, changes?: ChangeArray): Json;
+        /**
+         * Get all resolved Custom Flags from the supplied changes.
+         * @param changes - Optional changes array.
+         * @returns The resolved Custom Flag map.
+         * @remarks
+         * The changes array can be sourced from the data returned when emitting any
+         * personalization event.
+         * */
+        getCustomFlags(changes?: ChangeArray): Flags;
+        /**
+         * Resolve a Contentful entry to a personalized variant using the current
+         * or provided selected personalizations.
+         *
+         * @typeParam S - Entry skeleton type.
+         * @typeParam M - Chain modifiers.
+         * @typeParam L - Locale code.
+         * @param entry - The entry to personalize.
+         * @param personalizations - Optional selected personalizations.
+         * @returns The resolved entry data.
+         * @remarks
+         * Selected personalizations can be sourced from the data returned when emitting any
+         * personalization event.
+         */
+        personalizeEntry<S extends EntrySkeletonType, M extends ChainModifiers = ChainModifiers, L extends LocaleCode = LocaleCode>(entry: Entry<S, M, L>, personalizations?: SelectedPersonalizationArray): ResolvedData<S, M, L>;
+        /**
+         * Resolve a merge tag to a value based on the current (or provided) profile.
+         *
+         * @param embeddedEntryNodeTarget - The merge tag entry node to resolve.
+         * @param profile - Optional profile.
+         * @returns The resolved value (type depends on the tag).
+         * @remarks
+         * Merge tags are references to profile data that can be substituted into content. The
+         * profile can be sourced from the data returned when emitting any personalization event.
+         */
+        getMergeTagValue(embeddedEntryNodeTarget: MergeTagEntry, profile?: Profile): string | undefined;
+        /**
+         * Identify the current profile/visitor to associate traits with a profile.
+         *
+         * @param payload - Identify builder payload.
+         * @returns The resulting {@link OptimizationData} for the identified user if the device is online.
+         */
+        abstract identify(payload: IdentifyBuilderArgs): Promise<OptimizationData | undefined>;
+        /**
+         * Record a page view.
+         *
+         * @param payload - Page view builder payload.
+         * @returns The evaluated {@link OptimizationData} for this page view if the device is online.
+         */
+        abstract page(payload: PageViewBuilderArgs): Promise<OptimizationData | undefined>;
+        /**
+         * Record a screen view.
+         *
+         * @param payload - Screen view builder payload.
+         * @returns The evaluated {@link OptimizationData} for this screen view if the device is online.
+         */
+        abstract screen(payload: ScreenViewBuilderArgs): Promise<OptimizationData | undefined>;
+        /**
+         * Record a custom track event.
+         *
+         * @param payload - Track builder payload.
+         * @returns The evaluated {@link OptimizationData} for this event if the device is online.
+         */
+        abstract track(payload: TrackBuilderArgs): Promise<OptimizationData | undefined>;
+        /**
+         * Record a "sticky" component view.
+         *
+         * @param payload - "Sticky" component view builder payload.
+         * @returns The evaluated {@link OptimizationData} for this component view if the device is online.
+         * @remarks
+         * This method is intended to be called only when a component is considered
+         * "sticky".
+         */
+        abstract trackComponentView(payload: ComponentViewBuilderArgs): Promise<OptimizationData | undefined>;
+    }
+
+    /**
+     * Context payload emitted when offline personalization events are dropped due to queue bounds.
+     *
+     * @public
+     */
+    export declare interface PersonalizationOfflineQueueDropContext {
+        /** Number of dropped events. */
+        droppedCount: number;
+        /** Dropped events in oldest-first order. */
+        droppedEvents: ExperienceEventArray;
+        /** Configured queue max size. */
+        maxEvents: number;
+        /** Queue size after enqueueing the current event. */
+        queuedEvents: number;
+    }
+
+    /**
+     * Configuration for {@link PersonalizationStateful}.
+     *
+     * @public
+     */
+    export declare interface PersonalizationProductConfig extends ProductConfig {
+        /** Default signal values applied during initialization. */
+        defaults?: PersonalizationProductConfigDefaults;
+        /**
+         * Policy that controls the offline personalization queue size and drop telemetry.
+         */
+        queuePolicy?: PersonalizationQueuePolicy;
+        /**
+         * Function used to obtain an anonymous user identifier.
+         *
+         * @remarks
+         * If a `getAnonymousId` function has been provided, the returned value will
+         * take precedence over the `id` property of the current {@link Profile}
+         * signal value
+         *
+         * @returns A string identifier, or `undefined` if no anonymous ID is available.
+         */
+        getAnonymousId?: () => string | undefined;
+    }
+
+    /**
+     * Default state values for {@link PersonalizationStateful} applied at construction time.
+     *
+     * @public
+     */
+    export declare interface PersonalizationProductConfigDefaults {
+        /** Whether personalization is allowed by default. */
+        consent?: boolean;
+        /** Initial diff of changes produced by the service. */
+        changes?: ChangeArray;
+        /** Default active profile used for personalization. */
+        profile?: Profile;
+        /** Preselected personalization variants (e.g., winning treatments). */
+        personalizations?: SelectedPersonalizationArray;
+    }
+
+    /**
+     * Policy options for the stateful personalization offline queue.
+     *
+     * @public
+     */
+    export declare interface PersonalizationQueuePolicy {
+        /**
+         * Maximum number of personalization events retained while offline.
+         */
+        maxEvents?: number;
+        /**
+         * Callback invoked whenever oldest events are dropped due to queue bounds.
+         */
+        onDrop?: (context: PersonalizationOfflineQueueDropContext) => void;
+        /**
+         * Policy that controls offline queue flush retries, backoff, and circuit
+         * behavior after repeated failures.
+         */
+        flushPolicy?: QueueFlushPolicy;
+    }
+
+    declare const personalizations: Signal<{
+        experienceId: string;
+        variantIndex: number;
+        variants: Record<string, string>;
+        sticky?: boolean | undefined;
+    }[] | undefined>;
+
+    /**
+     * Storage key for cached selected personalizations.
+     *
+     * @internal
+     */
+    export declare const PERSONALIZATIONS_CACHE_KEY = "__ctfl_opt_personalizations__";
+
+    /**
+     * Stateful personalization product that manages consent, profile, flags, and
+     * selected variants while emitting Experience events and updating state.
+     *
+     * @public
+     * @remarks
+     * The class maintains reactive signals and exposes read‑only observables via
+     * {@link PersonalizationStateful.states}. Events are validated via schema parsers and
+     * run through interceptors before being submitted. Resulting state is merged
+     * back into signals.
+     */
+    export declare class PersonalizationStateful extends PersonalizationBase implements ConsentGuard {
+        /** In-memory ordered queue for offline personalization events. */
+        private readonly offlineQueue;
+        /** Resolved offline queue policy values. */
+        private readonly queuePolicy;
+        /** Shared queue flush retry runtime state machine. */
+        private readonly flushRuntime;
+        /** Exposed observable state references. */
+        readonly states: PersonalizationStates;
+        /**
+         * Function that provides an anonymous ID when available.
+         *
+         * @internal
+         */
+        getAnonymousId: () => string | undefined;
+        /**
+         * Create a new stateful personalization instance.
+         *
+         * @param options - Options to configure the personalization product for stateful environments.
+         * @example
+         * ```ts
+         * const personalization = new PersonalizationStateful({ api, builder, config: { getAnonymousId }, interceptors })
+         * ```
+         */
+        constructor(options: PersonalizationStatefulOptions);
+        /**
+         * Reset stateful signals managed by this product.
+         *
+         * @remarks
+         * Clears `changes`, `profile`, and selected `personalizations`.
+         * @example
+         * ```ts
+         * personalization.reset()
+         * ```
+         */
+        reset(): void;
+        /**
+         * Get the specified Custom Flag's value (derived from the signal).
+         * @param name - The name or key of the Custom Flag.
+         * @returns The current value of the Custom Flag if found.
+         * @example
+         * ```ts
+         * const flagValue = personalization.getCustomFlag('dark-mode')
+         * ```
+         * */
+        getCustomFlag(name: string, changes?: ChangeArray | undefined): Json;
+        /**
+         * Get all resolved Custom Flags (derived from the signal).
+         * @param changes - Optional changes array; defaults to the current signal value.
+         * @returns The resolved Custom Flag map.
+         * @example
+         * ```ts
+         * const flags = personalization.getCustomFlags()
+         * ```
+         */
+        getCustomFlags(changes?: ChangeArray | undefined): Flags;
+        /**
+         * Resolve a Contentful entry to a personalized variant using the current
+         * or provided selections.
+         *
+         * @typeParam S - Entry skeleton type.
+         * @typeParam M - Chain modifiers.
+         * @typeParam L - Locale code.
+         * @param entry - The entry to personalize.
+         * @param personalizations - Optional selections; defaults to the current signal value.
+         * @returns The resolved entry data.
+         * @example
+         * ```ts
+         * const { entry } = personalization.personalizeEntry(baselineEntry)
+         * ```
+         */
+        personalizeEntry<S extends EntrySkeletonType, M extends ChainModifiers = ChainModifiers, L extends LocaleCode = LocaleCode>(entry: Entry<S, M, L>, personalizations?: SelectedPersonalizationArray | undefined): ResolvedData<S, M, L>;
+        /**
+         * Resolve a merge tag to a value based on the current (or provided) profile.
+         *
+         * @param embeddedEntryNodeTarget - The merge‑tag entry node to resolve.
+         * @param profile - Optional profile; defaults to the current signal value.
+         * @returns The resolved value (type depends on the tag).
+         * @remarks
+         * Merge tags are references to profile data that can be substituted into content.
+         * @example
+         * ```ts
+         * const name = personalization.getMergeTagValue(mergeTagNode)
+         * ```
+         */
+        getMergeTagValue(embeddedEntryNodeTarget: MergeTagEntry, profile?: Profile | undefined): string | undefined;
+        /**
+         * Determine whether the named operation is permitted based on consent and
+         * allowed event type configuration.
+         *
+         * @param name - Method name; `trackComponentView` is normalized to
+         * `'component'` for allow‑list checks.
+         * @returns `true` if the operation is permitted; otherwise `false`.
+         * @example
+         * ```ts
+         * if (personalization.hasConsent('track')) { ... }
+         * ```
+         */
+        hasConsent(name: string): boolean;
+        /**
+         * Hook invoked when an operation is blocked due to missing consent.
+         *
+         * @param name - The blocked operation name.
+         * @param payload - The original arguments supplied to the operation.
+         * @example
+         * ```ts
+         * personalization.onBlockedByConsent('track', [payload])
+         * ```
+         */
+        onBlockedByConsent(name: string, payload: readonly unknown[]): void;
+        /**
+         * Identify the current profile/visitor to associate traits with a profile
+         * and update optimization state.
+         *
+         * @param payload - Identify builder payload.
+         * @returns The resulting {@link OptimizationData} for the identified user.
+         * @example
+         * ```ts
+         * const data = await personalization.identify({ userId: 'user-123' })
+         * ```
+         */
+        identify(payload: IdentifyBuilderArgs): Promise<OptimizationData | undefined>;
+        /**
+         * Record a page view and update optimization state.
+         *
+         * @param payload - Page view builder payload.
+         * @returns The evaluated {@link OptimizationData} for this page view.
+         * @example
+         * ```ts
+         * const data = await personalization.page({ properties: { title: 'Home' } })
+         * ```
+         */
+        page(payload: PageViewBuilderArgs): Promise<OptimizationData | undefined>;
+        /**
+         * Record a screen view and update optimization state.
+         *
+         * @param payload - Screen view builder payload.
+         * @returns The evaluated {@link OptimizationData} for this screen view.
+         * @example
+         * ```ts
+         * const data = await personalization.screen({ name: 'HomeScreen' })
+         * ```
+         */
+        screen(payload: ScreenViewBuilderArgs): Promise<OptimizationData | undefined>;
+        /**
+         * Record a custom track event and update optimization state.
+         *
+         * @param payload - Track builder payload.
+         * @returns The evaluated {@link OptimizationData} for this event.
+         * @example
+         * ```ts
+         * const data = await personalization.track({ event: 'button_click' })
+         * ```
+         */
+        track(payload: TrackBuilderArgs): Promise<OptimizationData | undefined>;
+        /**
+         * Record a "sticky" component view and update optimization state.
+         *
+         * @param payload - Component view builder payload.
+         * @returns The evaluated {@link OptimizationData} for this component view.
+         * @example
+         * ```ts
+         * const data = await personalization.trackComponentView({ componentId: 'hero-banner' })
+         * ```
+         */
+        trackComponentView(payload: ComponentViewBuilderArgs): Promise<OptimizationData | undefined>;
+        /**
+         * Intercept, validate, and place an event into the offline event queue; then
+         * trigger a size‑based flush if necessary.
+         *
+         * @param event - The event to enqueue.
+         */
+        private sendOrEnqueueEvent;
+        /**
+         * Enqueue an offline event, dropping oldest events first when queue bounds are reached.
+         *
+         * @param event - Event to enqueue.
+         */
+        private enqueueOfflineEvent;
+        /**
+         * Drop oldest offline events from the queue.
+         *
+         * @param count - Number of oldest events to drop.
+         * @returns Dropped events in oldest-first order.
+         */
+        private dropOldestOfflineEvents;
+        /**
+         * Invoke offline queue drop callback in a fault-tolerant manner.
+         *
+         * @param context - Drop callback payload.
+         */
+        private invokeQueueDropCallback;
+        /**
+         * Flush the offline queue
+         *
+         * @param options - Optional flush controls.
+         * @param options.force - When `true`, bypass offline/backoff/circuit gates and attempt immediately.
+         *
+         * @example
+         * ```ts
+         * await personalization.flush()
+         */
+        flush(options?: {
+            force?: boolean;
+        }): Promise<void>;
+        /**
+         * Flush queued offline events using retry/circuit guards.
+         *
+         * @param options - Flush controls.
+         * @param options.force - When true, bypass online/backoff/circuit gates.
+         */
+        private flushOfflineQueue;
+        /**
+         * Attempt to send queued events to the Experience API.
+         *
+         * @param events - Snapshot of queued events to send.
+         * @returns `true` when send succeeds; otherwise `false`.
+         */
+        private tryUpsertQueuedEvents;
+        /**
+         * Submit events to the Experience API, updating output signals with the
+         * returned state.
+         *
+         * @param events - The events to submit.
+         * @returns The {@link OptimizationData} returned by the service.
+         * @internal
+         * @privateRemarks
+         * If a `getAnonymousId` function has been provided, the returned value will
+         * take precedence over the `id` property of the current {@link Profile}
+         * signal value
+         */
+        private upsertProfile;
+        /**
+         * Apply returned optimization state to local signals after interceptor processing.
+         *
+         * @param data - Optimization state returned by the service.
+         * @internal
+         */
+        private updateOutputSignals;
+    }
+
+    /**
+     * Options for configuring {@link PersonalizationStateful} functionality.
+     *
+     * @public
+     * @see {@link ProductBaseOptions}
+     */
+    export declare type PersonalizationStatefulOptions = ProductBaseOptions & {
+        /** Configuration specific to the Personalization product */
+        config?: PersonalizationProductConfig;
+    };
+
+    /**
+     * Stateless personalization implementation that immediately validates and sends
+     * a single event to the Experience API, upserting the profile as needed.
+     *
+     * @public
+     * @remarks
+     * Each public method constructs a strongly-typed event via the shared builder,
+     * runs it through event interceptors, and performs a profile upsert using the
+     * Experience API. If an anonymous ID is available from the builder, it will be
+     * preferred as the `profileId` unless an explicit profile is provided.
+     */
+    export declare class PersonalizationStateless extends PersonalizationBase {
+        /**
+         * Identify the current profile/visitor to associate traits with a profile.
+         *
+         * @param payload - Identify builder arguments with an optional partial
+         * profile to attach to the upsert request.
+         * @returns The resulting {@link OptimizationData} for the identified user.
+         * @example
+         * ```ts
+         * const data = await personalization.identify({ userId: 'user-123', profile: { id: 'anon-1' } })
+         * ```
+         */
+        identify(payload: IdentifyBuilderArgs & {
+            profile?: PartialProfile;
+        }): Promise<OptimizationData>;
+        /**
+         * Record a page view.
+         *
+         * @param payload - Page view builder arguments with an optional partial profile.
+         * @returns The evaluated {@link OptimizationData} for this page view.
+         * @example
+         * ```ts
+         * const data = await personalization.page({ properties: { title: 'Home' }, profile: { id: 'anon-1' } })
+         * ```
+         */
+        page(payload: PageViewBuilderArgs & {
+            profile?: PartialProfile;
+        }): Promise<OptimizationData>;
+        /**
+         * Record a screen view.
+         *
+         * @param payload - Screen view builder arguments with an optional partial profile.
+         * @returns The evaluated {@link OptimizationData} for this screen view.
+         * @example
+         * ```ts
+         * const data = await personalization.screen({ name: 'HomeScreen', profile: { id: 'anon-1' } })
+         * ```
+         */
+        screen(payload: ScreenViewBuilderArgs & {
+            profile?: PartialProfile;
+        }): Promise<OptimizationData>;
+        /**
+         * Record a custom track event.
+         *
+         * @param payload - Track builder arguments with an optional partial profile.
+         * @returns The evaluated {@link OptimizationData} for this event.
+         * @example
+         * ```ts
+         * const data = await personalization.track({ event: 'purchase', profile: { id: 'anon-1' } })
+         * ```
+         */
+        track(payload: TrackBuilderArgs & {
+            profile?: PartialProfile;
+        }): Promise<OptimizationData>;
+        /**
+         * Record a "sticky" component view.
+         *
+         * @param payload - Component view builder arguments with an optional partial profile.
+         * @returns The evaluated {@link OptimizationData} for this component view.
+         * @example
+         * ```ts
+         * const data = await personalization.trackComponentView({ componentId: 'hero', profile: { id: 'anon-1' } })
+         * ```
+         */
+        trackComponentView(payload: ComponentViewBuilderArgs & {
+            profile?: PartialProfile;
+        }): Promise<OptimizationData>;
+        /**
+         * Intercept, validate, and upsert the profile with a single personalization
+         * event.
+         *
+         * @param event - The {@link PersonalizationEvent} to submit.
+         * @param profile - Optional partial profile. If omitted, the anonymous ID from
+         * the builder (when present) is used as the `profileId`.
+         * @returns The {@link OptimizationData} returned by the Experience API.
+         * @internal
+         */
+        private upsertProfile;
+    }
+
+    /**
+     * Observables exposed by {@link PersonalizationStateful} that mirror internal signals.
+     *
+     * @public
+     */
+    export declare interface PersonalizationStates {
+        /** Observable stream of the latest blocked event payload (or `undefined`). */
+        blockedEventStream: Observable<BlockedEvent | undefined>;
+        /** Observable stream of the latest {@link AnalyticsEvent} or {@link PersonalizationEvent} (or `undefined`). */
+        eventStream: Observable<InsightsEvent | ExperienceEvent | undefined>;
+        /** Live view of effective flags for the current profile (if available). */
+        flags: Observable<Flags | undefined>;
+        /** Live view of the current profile. */
+        profile: Observable<Profile | undefined>;
+        /** Live view of selected personalizations (variants). */
+        personalizations: Observable<SelectedPersonalizationArray | undefined>;
+    }
+
+    /**
+     * Resolve a personalized Contentful entry to the correct variant for the current
+     * selections.
+     *
+     * @public
+     * @remarks
+     * Given a baseline {@link PersonalizedEntry} and a set of selected personalizations
+     * (variants per experience), this resolver finds the matching replacement variant
+     * for the component configured against the baseline entry.
+     *
+     * **Variant indexing**: `variantIndex` in {@link SelectedPersonalization} is treated as
+     * 1‑based (index 1 = first variant). A value of `0` indicates baseline.
+     */
+    export declare const PersonalizedEntryResolver: {
+        /**
+         * Find the personalization entry corresponding to one of the selected experiences.
+         *
+         * @param params - Object containing the baseline personalized entry and the selections.
+         * @param skipValidation - When `true`, skip type/shape validation for perf.
+         * @returns The matching {@link PersonalizationEntry}, or `undefined` if not found/invalid.
+         * @remarks
+         * A personalization entry is a personalization configuration object supplied in a
+         * `PersonalizedEntry.nt_experiences` array. A personalized entry may relate to
+         * multiple personalizations.
+         * @example
+         * ```ts
+         * const personalizationEntry = PersonalizedEntryResolver.getPersonalizationEntry({
+         *   personalizedEntry: entry,
+         *   selectedPersonalizations
+         * })
+         * ```
+         */
+        getPersonalizationEntry({ personalizedEntry, selectedPersonalizations, }: {
+            personalizedEntry: PersonalizedEntry_2;
+            selectedPersonalizations: SelectedPersonalizationArray;
+        }, skipValidation?: boolean): PersonalizationEntry_2 | undefined;
+        /**
+         * Look up the selection metadata for a specific personalization entry.
+         *
+         * @param params - Object with the target personalization entry and selections.
+         * @param skipValidation - When `true`, skip type checks.
+         * @returns The matching {@link SelectedPersonalization}, if present.
+         * @remarks
+         * Selected personalizations are supplied by the Experience API in the
+         * `experiences` response data property.
+         * @example
+         * ```ts
+         * const selectedPersonalization = PersonalizedEntryResolver.getSelectedPersonalization({
+         *   personalizationEntry,
+         *   selectedPersonalizations
+         * })
+         * ```
+         */
+        getSelectedPersonalization({ personalizationEntry, selectedPersonalizations, }: {
+            personalizationEntry: PersonalizationEntry_2;
+            selectedPersonalizations: SelectedPersonalizationArray;
+        }, skipValidation?: boolean): SelectedPersonalization | undefined;
+        /**
+         * Get the replacement variant config for the given selection index.
+         *
+         * @param params - Baseline entry, personalization entry, and 1‑based variant index.
+         * @param skipValidation - When `true`, skip type checks.
+         * @returns The {@link EntryReplacementVariant} for the component, if any.
+         * @remarks
+         * Entry replacement variants are variant configurations specified in a
+         * personalization configuration component's `variants` array supplied by the
+         * personalized entry via its `nt_config` field.
+         * @example
+         * ```ts
+         * const selectedVariant = PersonalizedEntryResolver.getSelectedVariant({
+         *   personalizedEntry: entry,
+         *   personalizationEntry,
+         *   selectedVariantIndex: 2 // second variant (1‑based)
+         * })
+         * ```
+         */
+        getSelectedVariant({ personalizedEntry, personalizationEntry, selectedVariantIndex, }: {
+            personalizedEntry: PersonalizedEntry_2;
+            personalizationEntry: PersonalizationEntry_2;
+            selectedVariantIndex: number;
+        }, skipValidation?: boolean): EntryReplacementVariant_2 | undefined;
+        /**
+         * Resolve the concrete Contentful entry that corresponds to a selected variant.
+         *
+         * @typeParam S - Entry skeleton type.
+         * @typeParam M - Chain modifiers.
+         * @typeParam L - Locale code.
+         * @param params - Personalization entry and selected variant.
+         * @param skipValidation - When `true`, skip type checks.
+         * @returns The resolved entry typed as {@link Entry} or `undefined`.
+         * @remarks
+         * A personalized entry will resolve either to the baseline (the entry
+         * supplied as `personalizedEntry`) or the selected variant.
+         * @example
+         * ```ts
+         * const selectedVariantEntry = PersonalizedEntryResolver.getSelectedVariantEntry<{ fields: unknown }>({
+         *   personalizationEntry,
+         *   selectedVariant
+         * })
+         * ```
+         */
+        getSelectedVariantEntry<S extends EntrySkeletonType, M extends ChainModifiers = ChainModifiers, L extends LocaleCode = string>({ personalizationEntry, selectedVariant, }: {
+            personalizationEntry: PersonalizationEntry_2;
+            selectedVariant: EntryReplacementVariant_2;
+        }, skipValidation?: boolean): Entry<S, M, L> | undefined;
+        /**
+         * Resolve the selected entry (baseline or variant) for a personalized entry
+         * and optional selected personalizations, returning both the entry and the
+         * personalization metadata.
+         *
+         * @typeParam S - Entry skeleton type.
+         * @typeParam M - Chain modifiers.
+         * @typeParam L - Locale code.
+         * @param entry - The baseline personalized entry.
+         * @param selectedPersonalizations - Optional selections for the current profile.
+         * @returns An object containing the resolved entry and (if chosen) the selection.
+         * @example
+         * ```ts
+         * const { entry: personalizedEntry, personalization } = PersonalizedEntryResolver.resolve(entry, selections)
+         * if (personalization) console.log('Variant index', personalization.variantIndex)
+         * ```
+         */
+        resolve<S extends EntrySkeletonType, M extends ChainModifiers = ChainModifiers, L extends LocaleCode = string>(entry: Entry<S, M, L>, selectedPersonalizations?: SelectedPersonalizationArray): ResolvedData<S, M, L>;
+    };
+
+    export declare const PREVIEW_PANEL_SIGNAL_FNS_SYMBOL: unique symbol;
+
+    /**
+     * Well-known symbols used by the preview panel bridge.
+     *
+     * @public
+     */
+    export declare const PREVIEW_PANEL_SIGNALS_SYMBOL: unique symbol;
+
+    declare const previewPanelAttached: Signal<boolean>;
+
+    declare const previewPanelOpen: Signal<boolean>;
+
+    /**
+     * Symbol-keyed signal bridge shared between core and first-party preview tooling.
+     *
+     * @public
+     */
+    export declare interface PreviewPanelSignalObject {
+        /** Signals instance populated by {@link CoreStateful.registerPreviewPanel}. */
+        [PREVIEW_PANEL_SIGNALS_SYMBOL]?: Signals | null | undefined;
+        /** Signal helper functions populated by {@link CoreStateful.registerPreviewPanel}. */
+        [PREVIEW_PANEL_SIGNAL_FNS_SYMBOL]?: SignalFns | null | undefined;
+    }
+
+    /**
+     * Shared base for all product implementations.
+     *
+     * @internal
+     * @remarks
+     * This abstract class is not exported as part of the public API surface.
+     * Concrete implementations (e.g., analytics) should extend this class and
+     * expose their own public methods.
+     */
+    declare abstract class ProductBase {
+        /**
+         * Allow‑list of event {@link AnalyticsEventType | type keys} permitted when consent is not present.
+         */
+        protected readonly allowedEventTypes?: string[];
+        /** Event builder used to construct strongly‑typed events. */
+        protected readonly builder: EventBuilder;
+        /** Optimization API client used to send events to the Experience and Insights APIs. */
+        protected readonly api: ApiClient;
+        /** Interceptors that can mutate/augment outgoing events or optimization state. */
+        readonly interceptors: LifecycleInterceptors;
+        /** Optional callback invoked when an event call is blocked. */
+        protected readonly onEventBlocked?: ProductConfig['onEventBlocked'];
+        /**
+         * Creates a new product base instance.
+         *
+         * @param options - Options for configuring the functionality common among products.
+         */
+        constructor(options: ProductBaseOptions);
+        /**
+         * Publish blocked event metadata to both callback and blocked event signal.
+         *
+         * @param reason - Reason the method call was blocked.
+         * @param product - Product that blocked the method call.
+         * @param method - Name of the blocked method.
+         * @param args - Original blocked call arguments.
+         */
+        protected reportBlockedEvent(reason: BlockedEventReason, product: BlockedEventProduct, method: string, args: readonly unknown[]): void;
+    }
+
+    /**
+     * Options for configuring the common functionality of {@link ProductBase} descendents.
+     *
+     * @public
+     */
+    declare interface ProductBaseOptions {
+        /** Optimization API client. */
+        api: ApiClient;
+        /** Event builder for constructing events. */
+        builder: EventBuilder;
+        /** Optional configuration for allow‑lists and guard callbacks. */
+        config?: ProductConfig;
+        /** Lifecycle container for event and state interceptors. */
+        interceptors: LifecycleInterceptors;
+    }
+
+    /**
+     * Common configuration for all product implementations.
+     *
+     * @public
+     */
+    declare interface ProductConfig {
+        /**
+         * The set of event type strings that are allowed to be sent even if consent is
+         * not granted.
+         *
+         * @defaultValue `['identify', 'page', 'screen']`
+         * @remarks These types are compared against the `type` property of events.
+         */
+        allowedEventTypes?: EventType[];
+        /**
+         * Callback invoked whenever an event call is blocked by guards.
+         *
+         * @remarks
+         * This callback is best-effort. Any exception thrown by the callback is
+         * swallowed to keep event handling fault tolerant.
+         */
+        onEventBlocked?: (event: BlockedEvent) => void;
+    }
+
+    declare const profile: Signal<Profile | undefined>;
+
+    /**
+     * Storage key for cached profile data.
+     *
+     * @internal
+     */
+    export declare const PROFILE_CACHE_KEY = "__ctfl_opt_profile__";
+
+    /**
+     * Context payload emitted when a queue flush fails.
+     *
+     * @public
+     */
+    declare interface QueueFlushFailureContext {
+        /** Number of consecutive failed flush attempts. */
+        consecutiveFailures: number;
+        /** Number of queued batches at the time of the failed attempt. */
+        queuedBatches: number;
+        /** Number of queued events at the time of the failed attempt. */
+        queuedEvents: number;
+        /** Delay before the next retry attempt is scheduled. */
+        retryDelayMs: number;
+    }
+
+    /**
+     * Policy options for controlling queue flush retry behavior.
+     *
+     * @public
+     */
+    declare interface QueueFlushPolicy {
+        /**
+         * Base retry backoff delay in milliseconds.
+         *
+         * @defaultValue `500`
+         */
+        baseBackoffMs?: number;
+        /**
+         * Maximum retry backoff delay in milliseconds.
+         *
+         * @defaultValue `30000`
+         */
+        maxBackoffMs?: number;
+        /**
+         * Jitter ratio applied to retry delay to avoid synchronized retries.
+         *
+         * @remarks
+         * Value is clamped to `[0, 1]`.
+         *
+         * @defaultValue `0.2`
+         */
+        jitterRatio?: number;
+        /**
+         * Consecutive failures threshold before opening the circuit window.
+         *
+         * @defaultValue `8`
+         */
+        maxConsecutiveFailures?: number;
+        /**
+         * Duration in milliseconds to wait before retrying after circuit opens.
+         *
+         * @defaultValue `120000`
+         */
+        circuitOpenMs?: number;
+        /**
+         * Callback invoked after each failed flush attempt.
+         */
+        onFlushFailure?: (context: QueueFlushFailureContext) => void;
+        /**
+         * Callback invoked when the circuit opens after consecutive failures.
+         */
+        onCircuitOpen?: (context: QueueFlushFailureContext) => void;
+        /**
+         * Callback invoked when a flush succeeds after previous failures.
+         */
+        onFlushRecovered?: (context: QueueFlushRecoveredContext) => void;
+    }
+
+    /**
+     * Context payload emitted when a failed queue flush sequence recovers.
+     *
+     * @public
+     */
+    declare interface QueueFlushRecoveredContext {
+        /** Consecutive failure count that existed immediately before recovery. */
+        consecutiveFailures: number;
+    }
+
+    /**
+     * Result returned by {@link PersonalizedEntryResolver.resolve}.
+     *
+     * @typeParam S - Entry skeleton type.
+     * @typeParam M - Chain modifiers.
+     * @typeParam L - Locale code.
+     * @public
+     */
+    export declare interface ResolvedData<S extends EntrySkeletonType, M extends ChainModifiers = ChainModifiers, L extends LocaleCode = LocaleCode> {
+        /** The baseline or resolved variant entry. */
+        entry: Entry<S, M, L>;
+        /** The selected personalization metadata, if a non‑baseline variant was chosen. */
+        personalization?: SelectedPersonalization;
+    }
+
+    /**
+     * These methods assist in resolving values via Resolvers
+     *
+     * @internal
+     * @privateRemarks
+     * This interface exists to document that the included methods should not be
+     * considered static.
+     */
+    export declare interface ResolverMethods {
+        /**
+         * Get the specified Custom Flag's value from the supplied changes.
+         * @param name - The name or key of the Custom Flag.
+         * @param changes - Optional changes array.
+         * @returns The current value of the Custom Flag if found.
+         * @remarks
+         * The changes array can be sourced from the data returned when emitting any
+         * personalization event.
+         * */
+        getCustomFlag: (name: string, changes?: ChangeArray) => Json;
+        /**
+         * Get all resolved Custom Flags from the supplied changes.
+         * @param changes - Optional changes array.
+         * @returns The resolved Custom Flag map.
+         * @remarks
+         * The changes array can be sourced from the data returned when emitting any
+         * personalization event.
+         * */
+        getCustomFlags: (changes?: ChangeArray) => Flags;
+        /**
+         * Resolve a Contentful entry to a personalized variant using the current
+         * or provided selected personalizations.
+         *
+         * @typeParam S - Entry skeleton type.
+         * @typeParam M - Chain modifiers.
+         * @typeParam L - Locale code.
+         * @param entry - The entry to personalize.
+         * @param personalizations - Optional selections.
+         * @returns The resolved entry data.
+         * @remarks
+         * Selected personalizations can be sourced from the data returned when emitting any
+         * personalization event.
+         */
+        personalizeEntry: <S extends EntrySkeletonType, M extends ChainModifiers, L extends LocaleCode>(entry: Entry<S, M, L>, personalizations?: SelectedPersonalizationArray) => ResolvedData<S, M, L>;
+        /**
+         * Resolve a merge tag to a value based on the current (or provided) profile.
+         *
+         * @param embeddedEntryNodeTarget - The merge‑tag entry node to resolve.
+         * @param profile - Optional profile.
+         * @returns The resolved value (type depends on the tag).
+         * @remarks
+         * Merge tags are references to profile data that can be substituted into content. The
+         * profile can be sourced from the data returned when emitting any personalization event.
+         */
+        getMergeTagValue: (embeddedEntryNodeTarget: MergeTagEntry, profile?: Profile) => string | undefined;
+    }
+
+    export { Signal }
+
+    export declare interface SignalFns {
+        batch: typeof batch;
+        computed: typeof computed;
+        effect: typeof effect;
+        untracked: typeof untracked;
+    }
+
+    export declare const signalFns: SignalFns;
+
+    export declare interface Signals {
+        blockedEvent: typeof blockedEvent;
+        changes: typeof changes;
+        consent: typeof consent;
+        event: typeof event_2;
+        flags: typeof flags;
+        online: typeof online;
+        previewPanelAttached: typeof previewPanelAttached;
+        previewPanelOpen: typeof previewPanelOpen;
+        personalizations: typeof personalizations;
+        profile: typeof profile;
+    }
+
+    export declare const signals: Signals;
+
+    declare interface Subscription {
+        unsubscribe: () => void;
+    }
+
+    export declare type TrackComponentClickArgs = ComponentClickBuilderArgs & {
+        profile?: PartialProfile;
+    };
+
+    export declare type TrackComponentHoverArgs = ComponentHoverBuilderArgs & {
+        profile?: PartialProfile;
+    };
+
+    /**
+     * Arguments for tracking a component/flag view in stateless mode.
+     *
+     * @public
+     * @remarks
+     * The `profile` is optional; when omitted, the APIs may infer identity via
+     * other means.
+     */
+    export declare type TrackComponentViewArgs = ComponentViewBuilderArgs & {
+        profile?: PartialProfile;
+    };
+
+    export { }