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

package/dist/index.d.cts

@@ -1,45 +1,52 @@
+/**
+ * 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';
+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';
+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';
-import type { ExperienceEventType } from '@contentful/optimization-api-client';
-import { Flags } from '@contentful/optimization-api-client';
-import { Flags as Flags_2 } from '@contentful/optimization-api-schemas';
+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';
-import type { InsightsEventType } from '@contentful/optimization-api-client';
-import { Json } 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 { LogEvent } from 'diary';
-import type { LogLevels } from 'diary';
-import { MergeTagEntry } from '@contentful/optimization-api-client';
-import { OptimizationData } from '@contentful/optimization-api-client';
+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';
+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';
+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';
-import { Profile } from '@contentful/optimization-api-client';
+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';
+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';
+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';
@@ -57,23 +64,30 @@ declare abstract class AnalyticsBase extends ProductBase {
      * Track a UI component view event.
      *
      * @param payload - Component view builder arguments.
-     * @param duplicationScope - Optional string used to scope duplication used in Stateful
-     * implementations.
-     * @privateRemarks
-     * Duplication prevention should be handled in Stateful implementations
+     * @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 trackComponentView(payload: ComponentViewBuilderArgs, duplicationScope?: string): Promise<void> | void;
+    abstract trackComponentHover(payload: ComponentHoverBuilderArgs): Promise<void> | void;
     /**
      * Track a flag (feature) view event.
      *
      * @param payload - Flag view builder arguments.
-     * @param duplicationScope - Optional string used to scope duplication used in Stateful
-     * implementations.
      * @returns A promise that resolves when processing is complete (or `void`).
-     * @privateRemarks
-     * Duplication prevention should be handled in Stateful implementations
      */
-    abstract trackFlagView(payload: ComponentViewBuilderArgs, duplicationScope?: string): Promise<void> | void;
+    abstract trackFlagView(payload: ComponentViewBuilderArgs): Promise<void> | void;
 }
 
 /**
@@ -86,6 +100,11 @@ 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;
 }
 
 /**
@@ -104,30 +123,51 @@ export declare interface AnalyticsProductConfigDefaults {
  * 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 profile. */
+    /** 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; `'trackComponentView'` is normalized
-     * to `'component'` for allow‑list checks.
+     * @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;
     /**
@@ -135,40 +175,56 @@ export declare class AnalyticsStateful extends AnalyticsBase implements ConsentG
      *
      * @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: unknown[]): void;
+    onBlockedByConsent(name: string, payload: readonly unknown[]): void;
     /**
-     * Guard used to suppress duplicate component/flag view events based on a
-     * duplication key and the component identifier.
+     * Queue a component view event for the active profile.
      *
-     * @param _name - The operation name (unused).
-     * @param payload - Tuple of [builderArgs, duplicationScope].
-     * @returns `true` if the event is NOT a duplicate and should proceed.
+     * @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' })
+     * ```
      */
-    isNotDuplicated(_name: string, payload: [ComponentViewBuilderArgs, string]): boolean;
+    trackComponentView(payload: ComponentViewBuilderArgs): Promise<void>;
     /**
-     * Hook invoked when an operation is blocked by the duplication guard.
+     * Queue a component click event for the active profile.
      *
-     * @param name - The blocked operation name.
-     * @param payload - The original arguments supplied to the operation.
+     * @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' })
+     * ```
      */
-    onBlockedByDuplication(name: string, payload: unknown[]): void;
+    trackComponentClick(payload: ComponentClickBuilderArgs): Promise<void>;
     /**
-     * Queue a component view event for the active profile.
+     * Queue a component hover event for the active profile.
      *
-     * @param payload - Component view builder arguments.
-     * @param _duplicationScope - Optional string used to scope duplication (used
-     * by guards); an empty string `''` is converted to the `undefined` scope
+     * @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' })
+     * ```
      */
-    trackComponentView(payload: ComponentViewBuilderArgs, _duplicationScope?: string): Promise<void>;
+    trackComponentHover(payload: ComponentHoverBuilderArgs): Promise<void>;
     /**
      * Queue a flag view event for the active profile.
      *
      * @param payload - Flag view builder arguments.
-     * @param _duplicationScope - Optional string used to scope duplication (used
-     * by guards); an empty string `''` is converted to the `undefined` scope
+     * @returns A promise that resolves when the event has been queued.
+     * @example
+     * ```ts
+     * await analytics.trackFlagView({ componentId: 'feature-flag-123' })
+     * ```
      */
-    trackFlagView(payload: ComponentViewBuilderArgs, _duplicationScope?: string): Promise<void>;
+    trackFlagView(payload: ComponentViewBuilderArgs): Promise<void>;
     /**
      * Intercept, validate, and place an event into the profile‑scoped queue; then
      * trigger a size‑based flush if necessary.
@@ -183,10 +239,48 @@ export declare class AnalyticsStateful extends AnalyticsBase implements ConsentG
     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.
      */
-    flush(): Promise<void>;
+    private getQueuedEventCount;
 }
 
 /**
@@ -210,21 +304,53 @@ export declare class AnalyticsStateless extends AnalyticsBase {
     /**
      * Build, intercept, validate, and send a component view event.
      *
-     * @param args - {@link TrackViewArgs} used to build the event. Includes an
+     * @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' } })
+     * ```
      */
-    trackComponentView(args: TrackViewArgs): Promise<void>;
+    trackComponentHover(args: TrackComponentHoverArgs): Promise<void>;
     /**
      * Build, intercept, validate, and send a flag view event.
      *
-     * @param args - {@link TrackViewArgs} used to build the event. Includes an
+     * @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: TrackViewArgs): Promise<void>;
+    trackFlagView(args: TrackComponentViewArgs): Promise<void>;
     /**
-     * Send a single {@link InsightsEvent} wrapped in a one‑item batch.
+     * 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.
@@ -240,6 +366,8 @@ export declare class AnalyticsStateless extends AnalyticsBase {
  * @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`). */
@@ -257,7 +385,7 @@ export declare interface AnalyticsStates {
  *
  * @example
  * ```ts
- * import { ANONYMOUS_ID_COOKIE } from '@contentful/optimization-core'
+ * import { ANONYMOUS_ID_COOKIE } from '@contentful/optimization-core/constants'
  * const profileId = request.cookies[ANONYMOUS_ID_COOKIE]
  * ```
  */
@@ -286,6 +414,38 @@ 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}.
  *
@@ -360,29 +520,23 @@ declare interface ConsentGuard {
     onBlockedByConsent: (name: string, args: unknown[]) => void;
 }
 
-export declare class ConsoleLogSink extends LogSink {
-    name: string;
-    readonly verbosity: LogLevels;
-    constructor(verbosity?: LogLevels);
-    ingest(event: LogEvent): void;
-}
-
 /**
  * Internal base that wires the API client, event builder, and logging.
  *
  * @internal
  */
-declare abstract class CoreBase {
+declare abstract class CoreBase implements ResolverMethods {
     /** Product implementation for analytics. */
-    abstract readonly analytics: AnalyticsBase;
+    protected abstract _analytics: AnalyticsBase;
     /** Product implementation for personalization. */
-    abstract readonly personalization: PersonalizationBase;
+    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.
@@ -394,16 +548,52 @@ declare abstract class CoreBase {
      * ```
      */
     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
+     * @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).
@@ -415,6 +605,10 @@ declare abstract class CoreBase {
      * @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>;
      /**
@@ -423,13 +617,21 @@ declare abstract class CoreBase {
       * @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): unknown;
+     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;
@@ -439,6 +641,10 @@ declare abstract class CoreBase {
       *
       * @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;
@@ -448,6 +654,10 @@ declare abstract class CoreBase {
       *
       * @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;
@@ -457,6 +667,10 @@ declare abstract class CoreBase {
       *
       * @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;
@@ -467,25 +681,51 @@ declare abstract class CoreBase {
       * @param payload - Component view builder arguments. When `payload.sticky` is
       *   `true`, the event will also be sent via personalization as a sticky
       *   component view.
-      * @param duplicationScope - Optional string used to scope duplication used in Stateful
-      * implementations
       * @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;
-     }, duplicationScope?: string): Promise<OptimizationData | undefined>;
+     }): 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.
-      * @param duplicationScope - Optional string used to scope duplication used in Stateful
-      * implementations
       * @returns A promise that resolves when processing completes.
+      * @example
+      * ```ts
+      * await core.trackFlagView({ componentId: 'feature-flag-123' })
+      * ```
       */
-     trackFlagView(payload: ComponentViewBuilderArgs, duplicationScope?: string): Promise<void>;
+     trackFlagView(payload: ComponentViewBuilderArgs): Promise<void>;
     }
 
     /**
@@ -528,18 +768,22 @@ declare abstract class CoreBase {
 
     /**
      * Core runtime that constructs stateful product instances and exposes shared
-     * states, including consent and the event stream.
+     * states, including consent, blocked events, and the event stream.
      *
-     * @public
      * @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. */
-        readonly analytics: AnalyticsStateful;
+        protected _analytics: AnalyticsStateful;
         /** Stateful personalization product. */
-        readonly personalization: PersonalizationStateful;
+        protected _personalization: PersonalizationStateful;
         /**
          * Create a stateful core with optional default consent and product defaults.
          *
@@ -555,16 +799,30 @@ declare abstract class CoreBase {
          * ```
          */
         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 is intentionally preserved.
+         * 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;
         /**
@@ -572,20 +830,43 @@ declare abstract class CoreBase {
          * @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;
         /**
-         * Update online state
+         * Read current online state.
          *
-         * @param isOnline - `true` if the browser is online; `false` otherwise.
+         * @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 online(isOnline: boolean): void;
+        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.
@@ -594,10 +875,29 @@ declare abstract class CoreBase {
          * @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): PreviewPanelSignalObject;
+        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}.
      *
@@ -605,6 +905,14 @@ declare abstract class CoreBase {
      * @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.
          *
@@ -616,13 +924,25 @@ declare abstract class CoreBase {
         /** Function used to obtain an anonymous user identifier. */
         getAnonymousId?: PersonalizationProductConfig['getAnonymousId'];
         /**
-         * Initial duplication prevention configuration for component events.
-         *
-         * @see {@link ProductConfig.preventedComponentEvents}
+         * Callback invoked whenever an event call is blocked by checks.
          */
-        preventedComponentEvents?: ProductConfig['preventedComponentEvents'];
+        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.
      *
@@ -631,9 +951,9 @@ declare abstract class CoreBase {
      */
     export declare class CoreStateless extends CoreBase {
         /** Stateless analytics product. */
-        readonly analytics: AnalyticsStateless;
+        protected _analytics: AnalyticsStateless;
         /** Stateless personalization product. */
-        readonly personalization: PersonalizationStateless;
+        protected _personalization: PersonalizationStateless;
         /**
          * Create a stateless core. Product instances share the same API client and
          * event builder configured in {@link CoreBase}.
@@ -642,8 +962,6 @@ declare abstract class CoreBase {
          * @example
          * ```ts
          * const sdk = new CoreStateless({ clientId: 'app', environment: 'prod' })
-         * core.analytics.trackFlagView({ componentId: 'hero' })
-         * // or
          * core.trackFlagView({ componentId: 'hero' })
          * ```
          */
@@ -682,12 +1000,16 @@ declare abstract class CoreBase {
     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>;
     }
 
-    export declare function createScopedLogger(location: string): ScopedLogger;
-
     /**
      * Storage key for the debug flag toggle.
      *
@@ -806,6 +1128,8 @@ declare abstract class CoreBase {
      *
      * @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;
 
@@ -976,37 +1300,6 @@ declare abstract class CoreBase {
         state: InterceptorManager<OptimizationData>;
     }
 
-    export { LogEvent }
-
-    export declare class Logger {
-        readonly name = "@contentful/optimization";
-        private readonly PREFIX_PARTS;
-        private readonly DELIMITER;
-        private readonly diary;
-        private sinks;
-        constructor();
-        private assembleLocationPrefix;
-        addSink(sink: LogSink): void;
-        removeSink(name: string): void;
-        removeSinks(): void;
-        debug(logLocation: string, message: string, ...args: unknown[]): void;
-        info(logLocation: string, message: string, ...args: unknown[]): void;
-        log(logLocation: string, message: string, ...args: unknown[]): void;
-        warn(logLocation: string, message: string, ...args: unknown[]): void;
-        error(logLocation: string, message: string | Error, ...args: unknown[]): void;
-        fatal(logLocation: string, message: string | Error, ...args: unknown[]): void;
-        private onLogEvent;
-    }
-
-    export declare const logger: Logger;
-
-    export { LogLevels }
-
-    export declare abstract class LogSink {
-        abstract name: string;
-        abstract ingest(event: LogEvent): void;
-    }
-
     /**
      * A utility type representing a value that may be synchronously available or
      * produced asynchronously.
@@ -1027,19 +1320,6 @@ declare abstract class CoreBase {
      * Result values are returned as strings; numeric/boolean primitives are stringified.
      */
     export declare const MergeTagValueResolver: {
-        /**
-         * Type guard to ensure the input is a {@link MergeTagEntry}.
-         *
-         * @param embeddedEntryNodeTarget - Unknown value to validate.
-         * @returns `true` if the input is a valid merge-tag entry.
-         * @example
-         * ```ts
-         * if (MergeTagValueResolver.isMergeTagEntry(node)) {
-         *   // safe to read fields
-         * }
-         * ```
-         */
-        isMergeTagEntry(embeddedEntryNodeTarget: unknown): embeddedEntryNodeTarget is MergeTagEntry;
         /**
          * Generate a list of candidate selectors for a merge-tag ID.
          *
@@ -1062,13 +1342,13 @@ declare abstract class CoreBase {
          * @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)
          * ```
-         * @remarks
-         * Only string/number/boolean primitives are returned; objects/arrays are ignored.
          */
         getValueFromProfile(id: string, profile?: Profile): string | undefined;
         /**
@@ -1094,8 +1374,18 @@ declare abstract class CoreBase {
 
     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;
 
     /**
@@ -1107,20 +1397,19 @@ declare abstract class CoreBase {
      * identify, page, and track events. This base wires in shared singleton
      * resolvers used to fetch/resolve personalized data.
      */
-    declare abstract class PersonalizationBase extends ProductBase implements ResolverMethods {
+    export declare abstract class PersonalizationBase extends ProductBase implements ResolverMethods {
         /**
          * Static {@link FlagsResolver | resolver} for evaluating personalized
          * custom flags.
          */
         readonly flagsResolver: {
-            resolve(changes?: ChangeArray): Flags_2;
+            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: {
-            isMergeTagEntry(embeddedEntryNodeTarget: unknown): embeddedEntryNodeTarget is MergeTagEntry;
             normalizeSelectors(id: string): string[];
             getValueFromProfile(id: string, profile?: Profile): string | undefined;
             resolve(mergeTagEntry: MergeTagEntry | undefined, profile?: Profile): string | undefined;
@@ -1163,6 +1452,15 @@ declare abstract class CoreBase {
          * 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.
@@ -1188,7 +1486,7 @@ declare abstract class CoreBase {
          * 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): unknown;
+        getMergeTagValue(embeddedEntryNodeTarget: MergeTagEntry, profile?: Profile): string | undefined;
         /**
          * Identify the current profile/visitor to associate traits with a profile.
          *
@@ -1225,10 +1523,24 @@ declare abstract class CoreBase {
          * @remarks
          * This method is intended to be called only when a component is considered
          * "sticky".
-         * @privateRemarks
-         * Duplication prevention should be handled in Stateful implementations.
          */
-        abstract trackComponentView(payload: ComponentViewBuilderArgs, duplicationScope?: string): Promise<OptimizationData | undefined>;
+        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;
     }
 
     /**
@@ -1239,6 +1551,10 @@ declare abstract class CoreBase {
     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.
          *
@@ -1268,6 +1584,27 @@ declare abstract class CoreBase {
         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;
@@ -1294,8 +1631,12 @@ declare abstract class CoreBase {
      * back into signals.
      */
     export declare class PersonalizationStateful extends PersonalizationBase implements ConsentGuard {
-        /** In‑memory queue for offline events keyed by profile. */
+        /** 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;
         /**
@@ -1308,6 +1649,10 @@ declare abstract class CoreBase {
          * 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);
         /**
@@ -1315,14 +1660,32 @@ declare abstract class CoreBase {
          *
          * @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.
@@ -1333,6 +1696,10 @@ declare abstract class CoreBase {
          * @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>;
         /**
@@ -1343,8 +1710,12 @@ declare abstract class CoreBase {
          * @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): unknown;
+        getMergeTagValue(embeddedEntryNodeTarget: MergeTagEntry, profile?: Profile | undefined): string | undefined;
         /**
          * Determine whether the named operation is permitted based on consent and
          * allowed event type configuration.
@@ -1352,6 +1723,10 @@ declare abstract class CoreBase {
          * @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;
         /**
@@ -1359,30 +1734,22 @@ declare abstract class CoreBase {
          *
          * @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: unknown[]): void;
-        /**
-         * Guard used to suppress duplicate component view events for the same
-         * component based on a duplication key and the component identifier.
-         *
-         * @param _name - Operation name (unused).
-         * @param payload - Tuple `[builderArgs, duplicationScope]`.
-         * @returns `true` if the event is NOT a duplicate and should proceed.
-         */
-        isNotDuplicated(_name: string, payload: [ComponentViewBuilderArgs, string]): boolean;
-        /**
-         * Hook invoked when an operation is blocked by the duplication guard.
-         *
-         * @param _name - The blocked operation name (unused).
-         * @param payload - The original arguments supplied to the operation.
-         */
-        onBlockedByDuplication(_name: string, payload: unknown[]): void;
+        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>;
         /**
@@ -1390,6 +1757,10 @@ declare abstract class CoreBase {
          *
          * @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>;
         /**
@@ -1397,6 +1768,10 @@ declare abstract class CoreBase {
          *
          * @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>;
         /**
@@ -1404,20 +1779,76 @@ declare abstract class CoreBase {
          *
          * @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>;
-        trackComponentView(payload: ComponentViewBuilderArgs, _duplicationScope?: string): Promise<OptimizationData | undefined>;
         /**
-         * Intercept, validate, and place an event into the offline eventd queue; then
+         * 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(): Promise<void>;
+        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.
@@ -1469,6 +1900,10 @@ declare abstract class CoreBase {
          * @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;
@@ -1478,6 +1913,10 @@ declare abstract class CoreBase {
          *
          * @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;
@@ -1487,6 +1926,10 @@ declare abstract class CoreBase {
          *
          * @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;
@@ -1496,6 +1939,10 @@ declare abstract class CoreBase {
          *
          * @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;
@@ -1505,6 +1952,10 @@ declare abstract class CoreBase {
          *
          * @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;
@@ -1528,6 +1979,8 @@ declare abstract class CoreBase {
      * @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). */
@@ -1558,6 +2011,10 @@ declare abstract class CoreBase {
          * @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({
@@ -1565,10 +2022,6 @@ declare abstract class CoreBase {
          *   selectedPersonalizations
          * })
          * ```
-         * @remarks
-         * A personalization entry is a personalization configuration object supplied in a
-         * `PersonalizedEntry.nt_experiences` array. A personalized entry may relate to
-         * multiple personalizations.
          */
         getPersonalizationEntry({ personalizedEntry, selectedPersonalizations, }: {
             personalizedEntry: PersonalizedEntry_2;
@@ -1580,6 +2033,9 @@ declare abstract class CoreBase {
          * @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({
@@ -1587,9 +2043,6 @@ declare abstract class CoreBase {
          *   selectedPersonalizations
          * })
          * ```
-         * @remarks
-         * Selected personalizations are supplied by the Experience API in the
-         * `experiences` response data property.
          */
         getSelectedPersonalization({ personalizationEntry, selectedPersonalizations, }: {
             personalizationEntry: PersonalizationEntry_2;
@@ -1601,6 +2054,10 @@ declare abstract class CoreBase {
          * @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({
@@ -1609,10 +2066,6 @@ declare abstract class CoreBase {
          *   selectedVariantIndex: 2 // second variant (1‑based)
          * })
          * ```
-         * @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.
          */
         getSelectedVariant({ personalizedEntry, personalizationEntry, selectedVariantIndex, }: {
             personalizedEntry: PersonalizedEntry_2;
@@ -1628,6 +2081,9 @@ declare abstract class CoreBase {
          * @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 }>({
@@ -1635,9 +2091,6 @@ declare abstract class CoreBase {
          *   selectedVariant
          * })
          * ```
-         * @remarks
-         * A personalized entry will resolve either to the baseline (the entry
-         * supplied as `personalizedEntry`) or the selected variant.
          */
         getSelectedVariantEntry<S extends EntrySkeletonType, M extends ChainModifiers = ChainModifiers, L extends LocaleCode = string>({ personalizationEntry, selectedVariant, }: {
             personalizationEntry: PersonalizationEntry_2;
@@ -1663,17 +2116,29 @@ declare abstract class CoreBase {
         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;
+
     /**
-     * Interface for objects that can be registered with the preview panel system.
-     * When registered, the object receives direct access to SDK signals for state manipulation.
+     * 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 that will be populated by registerPreviewPanel */
-        signals: Signals | null | undefined;
-        /** Signal functions that can be used across micro-frontend barriers */
-        signalFns: SignalFns | null | undefined;
+        /** 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;
     }
 
     /**
@@ -1694,19 +2159,25 @@ declare abstract class CoreBase {
         protected readonly builder: EventBuilder;
         /** Optimization API client used to send events to the Experience and Insights APIs. */
         protected readonly api: ApiClient;
-        /**
-         * Deduplication helper used to track previously seen values within optional
-         * scopes
-         */
-        readonly duplicationDetector: ValuePresence;
         /** 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;
     }
 
     /**
@@ -1719,7 +2190,7 @@ declare abstract class CoreBase {
         api: ApiClient;
         /** Event builder for constructing events. */
         builder: EventBuilder;
-        /** Optional configuration for allow‑lists and duplication prevention. */
+        /** Optional configuration for allow‑lists and guard callbacks. */
         config?: ProductConfig;
         /** Lifecycle container for event and state interceptors. */
         interceptors: LifecycleInterceptors;
@@ -1735,20 +2206,18 @@ declare abstract class CoreBase {
          * The set of event type strings that are allowed to be sent even if consent is
          * not granted.
          *
-         * @defaultValue `['page', 'identify']`
+         * @defaultValue `['identify', 'page', 'screen']`
          * @remarks These types are compared against the `type` property of events.
          */
         allowedEventTypes?: EventType[];
         /**
-         * A map of duplication keys to a list of component IDs that should be
-         * considered duplicates and therefore suppressed.
+         * Callback invoked whenever an event call is blocked by guards.
          *
          * @remarks
-         * The actual duplication check is performed by {@link ValuePresence}. The
-         * keys of this record are used as duplication scopes. An empty string `''`
-         * is converted to an `indefined` scope when specific scopes are not required.
+         * This callback is best-effort. Any exception thrown by the callback is
+         * swallowed to keep event handling fault tolerant.
          */
-        preventedComponentEvents?: Record<string, string[]>;
+        onEventBlocked?: (event: BlockedEvent) => void;
     }
 
     declare const profile: Signal<Profile | undefined>;
@@ -1760,6 +2229,85 @@ declare abstract class CoreBase {
      */
     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}.
      *
@@ -1783,7 +2331,7 @@ declare abstract class CoreBase {
      * This interface exists to document that the included methods should not be
      * considered static.
      */
-    declare interface ResolverMethods {
+    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.
@@ -1794,6 +2342,15 @@ declare abstract class CoreBase {
          * 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.
@@ -1819,16 +2376,7 @@ declare abstract class CoreBase {
          * 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) => unknown;
-    }
-
-    export declare interface ScopedLogger {
-        debug: (message: string, ...args: unknown[]) => void;
-        info: (message: string, ...args: unknown[]) => void;
-        log: (message: string, ...args: unknown[]) => void;
-        warn: (message: string, ...args: unknown[]) => void;
-        error: (message: string | Error, ...args: unknown[]) => void;
-        fatal: (message: string | Error, ...args: unknown[]) => void;
+        getMergeTagValue: (embeddedEntryNodeTarget: MergeTagEntry, profile?: Profile) => string | undefined;
     }
 
     export { Signal }
@@ -1843,11 +2391,14 @@ declare abstract class CoreBase {
     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;
     }
@@ -1858,6 +2409,14 @@ declare abstract class CoreBase {
         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.
      *
@@ -1866,134 +2425,8 @@ declare abstract class CoreBase {
      * The `profile` is optional; when omitted, the APIs may infer identity via
      * other means.
      */
-    export declare type TrackViewArgs = ComponentViewBuilderArgs & {
+    export declare type TrackComponentViewArgs = ComponentViewBuilderArgs & {
         profile?: PartialProfile;
     };
 
-    /**
-     * Tracks whether a given value is present within one or more logical scopes.
-     *
-     * @remarks
-     * - Scope names are case-sensitive.
-     * - Presence is based on `Set.has` reference equality for objects and
-     *   value equality for primitives.
-     *
-     * @example
-     * ```ts
-     * const presence = new ValuePresence({ default: ['a', 'b'] })
-     * presence.isPresent('default', 'a') // true
-     * presence.addValue('default', 'c')
-     * presence.removeValue('default', 'b')
-     * presence.reset('default')
-     * ```
-     *
-     * @see {@link ValuePresenceScope}
-     * @public
-     */
-    export declare class ValuePresence {
-        #private;
-        /**
-         * Create a new {@link ValuePresence}.
-         *
-         * @param defaultMap - Optional initial data. Keys are scope names; values are arrays of items to seed.
-         * Empty-string keys are normalized to the default scope (`undefined`).
-         *
-         * @remarks
-         * - If `defaultMap` contains duplicate items for a scope, duplicates are collapsed by the `Set`.
-         */
-        constructor(defaultMap?: Record<string, unknown[]>);
-        /**
-         * Check whether a value is present within a given scope.
-         *
-         * @param scope - The scope to check. Use `undefined` for the default scope.
-         * @param value - The value to test for presence.
-         * @returns `true` if the value is present in the specified scope; otherwise `false`.
-         *
-         * @remarks
-         * Presence testing uses `Set.prototype.has` semantics.
-         *
-         * @example
-         * ```ts
-         * presence.isPresent(undefined, 42) // e.g., true or false
-         * ```
-         *
-         * @public
-         */
-        isPresent(scope: ValuePresenceScope, value: unknown): boolean;
-        /**
-         * Add a value to a scope, creating the scope if it does not exist.
-         *
-         * @param scope - Scope to add the value to. Use `undefined` for the default scope.
-         * @param value - The value to add.
-         * @returns void
-         *
-         * @remarks
-         * - No-op if the value is already present (due to `Set` semantics).
-         *
-         * @example
-         * ```ts
-         * presence.addValue('users', userId)
-         * ```
-         *
-         * @public
-         */
-        addValue(scope: ValuePresenceScope, value: unknown): void;
-        /**
-         * Remove a value from a scope.
-         *
-         * @param scope - Scope to remove from. Use `undefined` for the default scope.
-         * @param value - The value to remove.
-         * @returns void
-         *
-         * @remarks
-         * If the scope does not exist or the value is not present, this is a no-op.
-         *
-         * @example
-         * ```ts
-         * presence.removeValue('users', userId)
-         * ```
-         *
-         * @public
-         */
-        removeValue(scope: ValuePresenceScope, value: unknown): void;
-        /**
-         * Clear values from a single scope, or from all scopes.
-         *
-         * @param scope - If provided, clears only that scope. If omitted, clears all scopes.
-         * @returns void
-         *
-         * @remarks
-         * - When called with a specific scope that does not exist, this is a no-op.
-         * - When called with no arguments, all scopes and values are removed.
-         * - Clearing a non-existent scope will not create the scope.
-         *
-         * @example
-         * ```ts
-         * // Clear one scope
-         * presence.reset('users')
-         *
-         * // Clear all scopes
-         * presence.reset()
-         * ```
-         *
-         * @public
-         */
-        reset(scope?: ValuePresenceScope): void;
-    }
-
-    /**
-     * A scope identifier for grouping values.
-     *
-     * @remarks
-     * Use a non-empty string for a named scope. Use `undefined` for the
-     * "global/default" scope. An empty string (`""`) passed to the constructor
-     * initializer is normalized to `undefined`.
-     *
-     * @public
-     */
-    declare type ValuePresenceScope = string | undefined;
-
-
-    export * from "@contentful/optimization-api-client";
-
     export { }