@se-studio/core-ui 1.0.14 → 1.0.15

package/README.md

@@ -323,20 +323,39 @@ const previewConfig = mergeCmsRendererConfig(
 );
 ```
 
-## API Exports
-
-### Component Configuration Types
-
-- `ComponentConfig<TComponent, TContext>` - Type-safe component configuration
-- `CollectionConfig<TCollection, TContext>` - Type-safe collection configuration
-- `CmsRendererConfig` - Complete renderer configuration type
-
-### Utility Functions
-
-- `buildPageMetadata(page)` - Generate Next.js metadata from page data
-- `handleCmsError(error)` - Error handling utility for CMS operations
-- `extractComponentInfo(component, config)` - Extract component rendering info
-- `extractCollectionInfo(collection, config)` - Extract collection rendering info
+## API Reference
+
+### Main Exports
+
+#### Components
+- **`CmsContent`** - Main component for rendering CMS content with automatic component mapping
+- **`CmsComponent`** - Renders individual CMS components with type-based routing
+- **`CmsCollection`** - Renders CMS collections (arrays of components)
+- **`Visual`** - Optimized image/video/animation component with Next.js Image integration
+- **`RTF`** - Renders Contentful rich text with support for embedded entries and assets
+- **`UnusedChecker`** - Development utility to detect unused CMS content types
+
+#### Hooks
+- **`useAnalytics`** - Hook for accessing analytics functions (trackEvent, trackPage, trackClick)
+- **`useClickTracking`** - Hook for tracking click events with analytics
+- **`useDocumentVisible`** - Hook for tracking document visibility
+
+#### Utilities
+- **`buildPageMetadata`** - Generates Next.js metadata object from CMS page model
+- **`handleCmsError`** - Error handling utility for CMS operations
+- **`extractComponentInfo`** - Extract specific component information fields
+- **`extractCollectionInfo`** - Extract specific collection information fields
+- **`extractPageContext`** - Extract specific page context fields
+- **`cn`** - Utility function for merging Tailwind CSS classes
+
+#### Types
+- **`CmsRendererConfig`** - Complete renderer configuration type
+- **`ComponentRenderer<T>`** - Type for component renderer functions
+- **`CollectionRenderer<T>`** - Type for collection renderer functions
+- **`ComponentConfig<T>`** - Type-safe component configuration
+- **`CollectionConfig<T>`** - Type-safe collection configuration
+
+For detailed JSDoc documentation on all exports, see the TypeScript declaration files (`.d.ts`) in the package.
 
 ## Advanced Usage
 

package/dist/CmsRendererConfig.d.ts

@@ -1,3 +1,4 @@
+/** biome-ignore-all lint/suspicious/noExplicitAny: Any is allowed */
 import type { IContentContext } from '@se-studio/core-data-types';
 import type { React } from 'next/dist/server/route-modules/app-page/vendored/rsc/entrypoints';
 import type { CollectionMap, CollectionRenderer, EmbeddedCollectionMap } from './components/CmsCollection';
@@ -12,20 +13,141 @@ export type CmsRendererTypes = {
     ExternaComponentNameType: string;
     ExternalComponentType: any;
 };
+/**
+ * Configuration object that bundles all CMS renderer maps and display options.
+ * Create this once at the project level and pass it to CmsContent.
+ *
+ * This provides a clean, extensible API for configuring how CMS content is rendered,
+ * making it easy to add new renderer types without breaking existing code.
+ *
+ * @example Basic configuration
+ * ```tsx
+ * const rendererConfig = createCmsRendererConfig<MyProjectConfig>({
+ *   componentMap: {
+ *     "Hero": HeroComponent,
+ *     "CTA": CTAComponent,
+ *     "Content Block": ContentBlock,
+ *   },
+ *   collectionMap: {
+ *     "FAQs": FAQCollection,
+ *     "Related Articles": RelatedArticles,
+ *   },
+ *   showUnknownTypeErrors: process.env.NODE_ENV === 'development',
+ * });
+ * ```
+ *
+ * @example With all renderer types
+ * ```tsx
+ * const rendererConfig = createCmsRendererConfig<MyProjectConfig>({
+ *   componentMap: { ... },
+ *   collectionMap: { ... },
+ *   externalComponentMap: {
+ *     "Contact Form": ContactFormRenderer,
+ *     "Newsletter": NewsletterRenderer,
+ *   },
+ *   visualComponentRenderer: VisualRenderer,
+ *   internalLinkRenderer: InternalLinkRenderer,
+ *   showUnknownTypeErrors: true,
+ *   showRenderErrors: true,
+ * });
+ * ```
+ */
 export interface CmsRendererConfig<TConfig extends CmsRendererTypes = CmsRendererTypes> {
+    /**
+     * Map of component types to their renderers.
+     * Each key should match a ComponentType from your CMS configuration.
+     *
+     * @example
+     * ```tsx
+     * componentMap: {
+     *   "Hero": HeroComponent,
+     *   "CTA": CTAComponent,
+     * }
+     * ```
+     */
     componentMap: ComponentMap<TConfig['ComponentNameType'], TConfig['ComponentType']>;
     embeddedComponentMap: EmbeddedComponentMap<TConfig['ComponentNameType'], TConfig['ComponentType']>;
+    /**
+     * Map of collection types to their renderers.
+     * Each key should match a CollectionType from your CMS configuration.
+     *
+     * @example
+     * ```tsx
+     * collectionMap: {
+     *   "FAQs": FAQCollection,
+     *   "Related Articles": RelatedArticles,
+     * }
+     * ```
+     */
     collectionMap: CollectionMap<TConfig['CollectionNameType'], TConfig['CollectionType']>;
     embeddedCollectionMap: EmbeddedCollectionMap<TConfig['CollectionNameType'], TConfig['CollectionType']>;
+    /**
+     * Map of external component types to their renderers (optional).
+     * Use this for third-party integrations, forms, widgets, etc.
+     *
+     * @example
+     * ```tsx
+     * externalComponentMap: {
+     *   "Contact Form": ContactFormRenderer,
+     *   "Newsletter": NewsletterRenderer,
+     * }
+     * ```
+     */
     externalComponentMap: ExternalComponentMap<TConfig['ExternaComponentNameType'], TConfig['ExternalComponentType']>;
     embeddedExternalComponentMap: EmbeddedExternalComponentMap<TConfig['ExternaComponentNameType'], TConfig['ExternalComponentType']>;
+    /**
+     * Renderer for Visual content types (optional).
+     * Use this to define how images, videos, and other visual assets are rendered.
+     *
+     * @example
+     * ```tsx
+     * visualComponentRenderer: ({ information, contentContext }) => (
+     *   <VisualComponent visual={information} />
+     * )
+     * ```
+     */
     visualComponentRenderer: VisualComponentRenderer;
+    /**
+     * Renderer for Internal Link content types (optional).
+     * Use this to define how internal navigation links are rendered.
+     *
+     * @example
+     * ```tsx
+     * internalLinkRenderer: ({ information }) => (
+     *   <Link href={information.href}>{information.text}</Link>
+     * )
+     * ```
+     */
     internalLinkRenderer: InternalLinkRenderer;
+    /**
+     * Map of custom content types to their renderers (optional).
+     * Use this for project-specific content types that extend the base CMS content model.
+     *
+     * @example
+     * ```tsx
+     * customContentMap: {
+     *   "pricingPlan": PricingPlanRenderer,
+     *   "testimonial": TestimonialRenderer,
+     * }
+     * ```
+     */
     customContentMap?: Partial<Record<string, React.FC<{
         information: any;
         contentContext: IContentContext;
     }>>>;
+    /**
+     * Show error panels for unknown content types in development mode (default: false).
+     * When true, displays a visual warning when a component/collection type is not mapped.
+     *
+     * Recommended: Set to `process.env.NODE_ENV === 'development'`
+     */
     showUnknownTypeErrors: boolean;
+    /**
+     * Show error panels for rendering errors (default: false).
+     * When true, displays error details when a component throws during rendering.
+     *
+     * Recommended: Set to `process.env.NODE_ENV === 'development'`
+     */
     showRenderErrors: boolean;
     defaultComponentRenderer: ComponentRenderer<any>;
     defaultCollectionRenderer: CollectionRenderer<any>;

package/dist/CmsRendererConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CmsRendererConfig.d.ts","sourceRoot":"","sources":["../src/CmsRendererConfig.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kEAAkE,CAAC;AAC9F,OAAO,KAAK,EACV,aAAa,EACb,kBAAkB,EAClB,qBAAqB,EACtB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAC7F,OAAO,KAAK,EACV,4BAA4B,EAC5B,oBAAoB,EACrB,MAAM,mCAAmC,CAAC;AAE3C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,GAAG,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,GAAG,CAAC;IACpB,wBAAwB,EAAE,MAAM,CAAC;IACjC,qBAAqB,EAAE,GAAG,CAAC;CAC5B,CAAC;AAyCF,MAAM,WAAW,iBAAiB,CAAC,OAAO,SAAS,gBAAgB,GAAG,gBAAgB;IAapF,YAAY,EAAE,YAAY,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC;IAEnF,oBAAoB,EAAE,oBAAoB,CACxC,OAAO,CAAC,mBAAmB,CAAC,EAC5B,OAAO,CAAC,eAAe,CAAC,CACzB,CAAC;IAcF,aAAa,EAAE,aAAa,CAAC,OAAO,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC;IACvF,qBAAqB,EAAE,qBAAqB,CAC1C,OAAO,CAAC,oBAAoB,CAAC,EAC7B,OAAO,CAAC,gBAAgB,CAAC,CAC1B,CAAC;IAcF,oBAAoB,EAAE,oBAAoB,CACxC,OAAO,CAAC,0BAA0B,CAAC,EACnC,OAAO,CAAC,uBAAuB,CAAC,CACjC,CAAC;IACF,4BAA4B,EAAE,4BAA4B,CACxD,OAAO,CAAC,0BAA0B,CAAC,EACnC,OAAO,CAAC,uBAAuB,CAAC,CACjC,CAAC;IAaF,uBAAuB,EAAE,uBAAuB,CAAC;IAajD,oBAAoB,EAAE,oBAAoB,CAAC;IAc3C,gBAAgB,CAAC,EAAE,OAAO,CACxB,MAAM,CACJ,MAAM,EACN,KAAK,CAAC,EAAE,CAAC;QACP,WAAW,EAAE,GAAG,CAAC;QACjB,cAAc,EAAE,eAAe,CAAC;KACjC,CAAC,CACH,CACF,CAAC;IAQF,qBAAqB,EAAE,OAAO,CAAC;IAQ/B,gBAAgB,EAAE,OAAO,CAAC;IAE1B,wBAAwB,EAAE,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACjD,yBAAyB,EAAE,kBAAkB,CAAC,GAAG,CAAC,CAAC;CACpD"}
+{"version":3,"file":"CmsRendererConfig.d.ts","sourceRoot":"","sources":["../src/CmsRendererConfig.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kEAAkE,CAAC;AAC9F,OAAO,KAAK,EACV,aAAa,EACb,kBAAkB,EAClB,qBAAqB,EACtB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAC7F,OAAO,KAAK,EACV,4BAA4B,EAC5B,oBAAoB,EACrB,MAAM,mCAAmC,CAAC;AAE3C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,GAAG,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,GAAG,CAAC;IACpB,wBAAwB,EAAE,MAAM,CAAC;IACjC,qBAAqB,EAAE,GAAG,CAAC;CAC5B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,WAAW,iBAAiB,CAAC,OAAO,SAAS,gBAAgB,GAAG,gBAAgB;IACpF;;;;;;;;;;;OAWG;IACH,YAAY,EAAE,YAAY,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC;IAEnF,oBAAoB,EAAE,oBAAoB,CACxC,OAAO,CAAC,mBAAmB,CAAC,EAC5B,OAAO,CAAC,eAAe,CAAC,CACzB,CAAC;IAEF;;;;;;;;;;;OAWG;IACH,aAAa,EAAE,aAAa,CAAC,OAAO,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC;IACvF,qBAAqB,EAAE,qBAAqB,CAC1C,OAAO,CAAC,oBAAoB,CAAC,EAC7B,OAAO,CAAC,gBAAgB,CAAC,CAC1B,CAAC;IAEF;;;;;;;;;;;OAWG;IACH,oBAAoB,EAAE,oBAAoB,CACxC,OAAO,CAAC,0BAA0B,CAAC,EACnC,OAAO,CAAC,uBAAuB,CAAC,CACjC,CAAC;IACF,4BAA4B,EAAE,4BAA4B,CACxD,OAAO,CAAC,0BAA0B,CAAC,EACnC,OAAO,CAAC,uBAAuB,CAAC,CACjC,CAAC;IAEF;;;;;;;;;;OAUG;IACH,uBAAuB,EAAE,uBAAuB,CAAC;IAEjD;;;;;;;;;;OAUG;IACH,oBAAoB,EAAE,oBAAoB,CAAC;IAE3C;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,EAAE,OAAO,CACxB,MAAM,CACJ,MAAM,EACN,KAAK,CAAC,EAAE,CAAC;QACP,WAAW,EAAE,GAAG,CAAC;QACjB,cAAc,EAAE,eAAe,CAAC;KACjC,CAAC,CACH,CACF,CAAC;IAEF;;;;;OAKG;IACH,qBAAqB,EAAE,OAAO,CAAC;IAE/B;;;;;OAKG;IACH,gBAAgB,EAAE,OAAO,CAAC;IAE1B,wBAAwB,EAAE,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACjD,yBAAyB,EAAE,kBAAkB,CAAC,GAAG,CAAC,CAAC;CACpD"}

package/dist/analytics/AnalyticsProvider.d.ts

@@ -4,6 +4,13 @@ export interface AnalyticsProviderProps {
     adapter: AnalyticsAdapter;
     children: React.ReactNode;
 }
+/**
+ * Provider component that makes analytics adapter available to child components
+ */
 export declare function AnalyticsProvider({ adapter, children }: AnalyticsProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access the analytics adapter from context
+ * @throws Error if used outside of AnalyticsProvider
+ */
 export declare function useAnalyticsContext(): AnalyticsAdapter;
 //# sourceMappingURL=AnalyticsProvider.d.ts.map

package/dist/analytics/AnalyticsProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AnalyticsProvider.d.ts","sourceRoot":"","sources":["../../src/analytics/AnalyticsProvider.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAIhD,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,gBAAgB,CAAC;IAC1B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAKD,wBAAgB,iBAAiB,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,sBAAsB,2CAE9E;AAMD,wBAAgB,mBAAmB,IAAI,gBAAgB,CAMtD"}
+{"version":3,"file":"AnalyticsProvider.d.ts","sourceRoot":"","sources":["../../src/analytics/AnalyticsProvider.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAIhD,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,gBAAgB,CAAC;IAC1B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,sBAAsB,2CAE9E;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,gBAAgB,CAMtD"}

package/dist/analytics/AnalyticsProvider.js

@@ -2,9 +2,16 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useContext } from 'react';
 const AnalyticsContext = createContext(null);
+/**
+ * Provider component that makes analytics adapter available to child components
+ */
 export function AnalyticsProvider({ adapter, children }) {
     return _jsx(AnalyticsContext.Provider, { value: adapter, children: children });
 }
+/**
+ * Hook to access the analytics adapter from context
+ * @throws Error if used outside of AnalyticsProvider
+ */
 export function useAnalyticsContext() {
     const adapter = useContext(AnalyticsContext);
     if (!adapter) {

package/dist/analytics/AnalyticsProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"AnalyticsProvider.js","sourceRoot":"","sources":["../../src/analytics/AnalyticsProvider.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAGb,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAGlD,MAAM,gBAAgB,GAAG,aAAa,CAA0B,IAAI,CAAC,CAAC;AAUtE,MAAM,UAAU,iBAAiB,CAAC,EAAE,OAAO,EAAE,QAAQ,EAA0B;IAC7E,OAAO,KAAC,gBAAgB,CAAC,QAAQ,IAAC,KAAK,EAAE,OAAO,YAAG,QAAQ,GAA6B,CAAC;AAC3F,CAAC;AAMD,MAAM,UAAU,mBAAmB;IACjC,MAAM,OAAO,GAAG,UAAU,CAAC,gBAAgB,CAAC,CAAC;IAC7C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,8DAA8D,CAAC,CAAC;IAClF,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"AnalyticsProvider.js","sourceRoot":"","sources":["../../src/analytics/AnalyticsProvider.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAGb,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAGlD,MAAM,gBAAgB,GAAG,aAAa,CAA0B,IAAI,CAAC,CAAC;AAOtE;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,EAAE,OAAO,EAAE,QAAQ,EAA0B;IAC7E,OAAO,KAAC,gBAAgB,CAAC,QAAQ,IAAC,KAAK,EAAE,OAAO,YAAG,QAAQ,GAA6B,CAAC;AAC3F,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB;IACjC,MAAM,OAAO,GAAG,UAAU,CAAC,gBAAgB,CAAC,CAAC;IAC7C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,8DAA8D,CAAC,CAAC;IAClF,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/analytics/adapters/ConsoleAnalyticsAdapter.d.ts

@@ -1,4 +1,8 @@
 import type { AnalyticsAdapter, ClickTrackingProperties, PageTrackingProperties } from '../types';
+/**
+ * Console adapter used as the default/example implementation.
+ * Customer projects should provide their own adapter that satisfies `AnalyticsAdapter`.
+ */
 export declare class ConsoleAnalyticsAdapter implements AnalyticsAdapter {
     private log;
     trackEvent(event: string, properties: Record<string, unknown>): void;

package/dist/analytics/adapters/ConsoleAnalyticsAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ConsoleAnalyticsAdapter.d.ts","sourceRoot":"","sources":["../../../src/analytics/adapters/ConsoleAnalyticsAdapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAMlG,qBAAa,uBAAwB,YAAW,gBAAgB;IAC9D,OAAO,CAAC,GAAG;IAKX,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIpE,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,sBAAsB,GAAG,IAAI;IAIhE,UAAU,CAAC,UAAU,EAAE,uBAAuB,GAAG,IAAI;CAGtD"}
+{"version":3,"file":"ConsoleAnalyticsAdapter.d.ts","sourceRoot":"","sources":["../../../src/analytics/adapters/ConsoleAnalyticsAdapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAElG;;;GAGG;AACH,qBAAa,uBAAwB,YAAW,gBAAgB;IAC9D,OAAO,CAAC,GAAG;IAKX,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIpE,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,sBAAsB,GAAG,IAAI;IAIhE,UAAU,CAAC,UAAU,EAAE,uBAAuB,GAAG,IAAI;CAGtD"}

package/dist/analytics/adapters/ConsoleAnalyticsAdapter.js

@@ -1,6 +1,11 @@
 'use client';
+/**
+ * Console adapter used as the default/example implementation.
+ * Customer projects should provide their own adapter that satisfies `AnalyticsAdapter`.
+ */
 export class ConsoleAnalyticsAdapter {
     log(...args) {
+        // eslint-disable-next-line no-console -- intentional logging adapter
         console.log('[Analytics]', ...args);
     }
     trackEvent(event, properties) {

package/dist/analytics/adapters/ConsoleAnalyticsAdapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"ConsoleAnalyticsAdapter.js","sourceRoot":"","sources":["../../../src/analytics/adapters/ConsoleAnalyticsAdapter.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAQb,MAAM,OAAO,uBAAuB;IAC1B,GAAG,CAAC,GAAG,IAAe;QAE5B,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,GAAG,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,UAAU,CAAC,KAAa,EAAE,UAAmC;QAC3D,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;IACvC,CAAC;IAED,SAAS,CAAC,GAAW,EAAE,UAAkC;QACvD,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,GAAG,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED,UAAU,CAAC,UAAmC;QAC5C,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAChC,CAAC;CACF"}
+{"version":3,"file":"ConsoleAnalyticsAdapter.js","sourceRoot":"","sources":["../../../src/analytics/adapters/ConsoleAnalyticsAdapter.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAIb;;;GAGG;AACH,MAAM,OAAO,uBAAuB;IAC1B,GAAG,CAAC,GAAG,IAAe;QAC5B,qEAAqE;QACrE,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,GAAG,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,UAAU,CAAC,KAAa,EAAE,UAAmC;QAC3D,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;IACvC,CAAC;IAED,SAAS,CAAC,GAAW,EAAE,UAAkC;QACvD,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,GAAG,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED,UAAU,CAAC,UAAmC;QAC5C,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAChC,CAAC;CACF"}

package/dist/analytics/types.d.ts

@@ -1,4 +1,7 @@
 import type { IAnalyticsContext } from '@se-studio/core-data-types';
+/**
+ * Properties for tracking a click event
+ */
 export interface ClickTrackingProperties extends IAnalyticsContext {
     componentType: string;
     url: string;
@@ -6,13 +9,33 @@ export interface ClickTrackingProperties extends IAnalyticsContext {
     linkText: string;
     location?: string;
 }
+/**
+ * Properties for tracking a page view
+ */
 export interface PageTrackingProperties extends IAnalyticsContext {
     url: string;
     pathname: string;
 }
+/**
+ * Interface that analytics adapters must implement
+ */
 export interface AnalyticsAdapter {
+    /**
+     * Track a custom event
+     * @param event - Event name
+     * @param properties - Event properties
+     */
     trackEvent(event: string, properties: Record<string, unknown>): void;
+    /**
+     * Track a page view
+     * @param url - Full URL of the page
+     * @param properties - Page properties
+     */
     trackPage(url: string, properties: PageTrackingProperties): void;
+    /**
+     * Track a component click
+     * @param properties - Click tracking properties
+     */
     trackClick(properties: ClickTrackingProperties): void;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/analytics/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/analytics/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAKpE,MAAM,WAAW,uBAAwB,SAAQ,iBAAiB;IAChE,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAKD,MAAM,WAAW,sBAAuB,SAAQ,iBAAiB;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;CAClB;AAKD,MAAM,WAAW,gBAAgB;IAM/B,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAOrE,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAMjE,UAAU,CAAC,UAAU,EAAE,uBAAuB,GAAG,IAAI,CAAC;CACvD"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/analytics/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEpE;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,iBAAiB;IAChE,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAuB,SAAQ,iBAAiB;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAErE;;;;OAIG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAEjE;;;OAGG;IACH,UAAU,CAAC,UAAU,EAAE,uBAAuB,GAAG,IAAI,CAAC;CACvD"}

package/dist/analytics/useAnalytics.d.ts

@@ -1,4 +1,39 @@
 import type { IAnalyticsContext } from '@se-studio/core-data-types';
+/**
+ * Hook for accessing analytics functions.
+ *
+ * Provides a clean API for tracking events, pages, and clicks. Must be used
+ * within an AnalyticsProvider context.
+ *
+ * @returns Object with tracking functions:
+ * - `trackEvent` - Track custom events
+ * - `trackPage` - Track page views
+ * - `trackClick` - Track click interactions
+ *
+ * @throws {Error} If used outside of AnalyticsProvider
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { useAnalytics } from '@se-studio/core-ui';
+ *
+ * function MyComponent() {
+ *   const { trackClick, trackPage } = useAnalytics();
+ *
+ *   useEffect(() => {
+ *     trackPage(window.location.href, window.location.pathname, {
+ *       page_title: 'Home',
+ *       page_type: 'landing',
+ *     });
+ *   }, []);
+ *
+ *   return (
+ *     <button onClick={() => trackClick('Button', 'Sign up', { page_title: 'Home' })}>
+ *       Sign up
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
 export declare function useAnalytics(): {
     trackEvent: (event: string, properties: Record<string, unknown>) => void;
     trackPage: (url: string, pathname: string, analyticsContext: IAnalyticsContext) => void;

package/dist/analytics/useAnalytics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useAnalytics.d.ts","sourceRoot":"","sources":["../../src/analytics/useAnalytics.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AASpE,wBAAgB,YAAY;wBAIhB,MAAM,cAAc,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;qBAO7C,MAAM,YAAY,MAAM,oBAAoB,iBAAiB;gCAalD,MAAM,YACX,MAAM,oBACE,iBAAiB,YACzB;QACR,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB;EAqBN"}
+{"version":3,"file":"useAnalytics.d.ts","sourceRoot":"","sources":["../../src/analytics/useAnalytics.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAKpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,YAAY;wBAIhB,MAAM,cAAc,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;qBAO7C,MAAM,YAAY,MAAM,oBAAoB,iBAAiB;gCAalD,MAAM,YACX,MAAM,oBACE,iBAAiB,YACzB;QACR,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB;EAqBN"}

package/dist/analytics/useAnalytics.js

@@ -1,6 +1,41 @@
 'use client';
 import { useCallback } from 'react';
 import { useAnalyticsContext } from './AnalyticsProvider';
+/**
+ * Hook for accessing analytics functions.
+ *
+ * Provides a clean API for tracking events, pages, and clicks. Must be used
+ * within an AnalyticsProvider context.
+ *
+ * @returns Object with tracking functions:
+ * - `trackEvent` - Track custom events
+ * - `trackPage` - Track page views
+ * - `trackClick` - Track click interactions
+ *
+ * @throws {Error} If used outside of AnalyticsProvider
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { useAnalytics } from '@se-studio/core-ui';
+ *
+ * function MyComponent() {
+ *   const { trackClick, trackPage } = useAnalytics();
+ *
+ *   useEffect(() => {
+ *     trackPage(window.location.href, window.location.pathname, {
+ *       page_title: 'Home',
+ *       page_type: 'landing',
+ *     });
+ *   }, []);
+ *
+ *   return (
+ *     <button onClick={() => trackClick('Button', 'Sign up', { page_title: 'Home' })}>
+ *       Sign up
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
 export function useAnalytics() {
     const adapter = useAnalyticsContext();
     const trackEvent = useCallback((event, properties) => {

package/dist/analytics/useAnalytics.js.map

@@ -1 +1 @@
-{"version":3,"file":"useAnalytics.js","sourceRoot":"","sources":["../../src/analytics/useAnalytics.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAGb,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAO1D,MAAM,UAAU,YAAY;IAC1B,MAAM,OAAO,GAAG,mBAAmB,EAAE,CAAC;IAEtC,MAAM,UAAU,GAAG,WAAW,CAC5B,CAAC,KAAa,EAAE,UAAmC,EAAE,EAAE;QACrD,OAAO,CAAC,UAAU,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IACxC,CAAC,EACD,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,MAAM,SAAS,GAAG,WAAW,CAC3B,CAAC,GAAW,EAAE,QAAgB,EAAE,gBAAmC,EAAE,EAAE;QACrE,MAAM,UAAU,GAA2B;YACzC,GAAG;YACH,QAAQ;YACR,GAAG,gBAAgB;SACpB,CAAC;QACF,OAAO,CAAC,SAAS,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IACrC,CAAC,EACD,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,MAAM,UAAU,GAAG,WAAW,CAC5B,CACE,aAAqB,EACrB,QAAgB,EAChB,gBAAmC,EACnC,OAGC,EACD,EAAE;QACF,MAAM,GAAG,GAAG,OAAO,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACtE,MAAM,UAAU,GAA4B;YAC1C,aAAa;YACb,GAAG;YACH,QAAQ;YACR,QAAQ,EAAE,OAAO,EAAE,QAAQ;YAC3B,SAAS,EAAE,OAAO,EAAE,SAAS;YAC7B,GAAG,gBAAgB;SACpB,CAAC;QACF,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;IACjC,CAAC,EACD,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,OAAO;QACL,UAAU;QACV,SAAS;QACT,UAAU;KACX,CAAC;AACJ,CAAC"}
+{"version":3,"file":"useAnalytics.js","sourceRoot":"","sources":["../../src/analytics/useAnalytics.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAGb,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAG1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,OAAO,GAAG,mBAAmB,EAAE,CAAC;IAEtC,MAAM,UAAU,GAAG,WAAW,CAC5B,CAAC,KAAa,EAAE,UAAmC,EAAE,EAAE;QACrD,OAAO,CAAC,UAAU,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IACxC,CAAC,EACD,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,MAAM,SAAS,GAAG,WAAW,CAC3B,CAAC,GAAW,EAAE,QAAgB,EAAE,gBAAmC,EAAE,EAAE;QACrE,MAAM,UAAU,GAA2B;YACzC,GAAG;YACH,QAAQ;YACR,GAAG,gBAAgB;SACpB,CAAC;QACF,OAAO,CAAC,SAAS,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IACrC,CAAC,EACD,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,MAAM,UAAU,GAAG,WAAW,CAC5B,CACE,aAAqB,EACrB,QAAgB,EAChB,gBAAmC,EACnC,OAGC,EACD,EAAE;QACF,MAAM,GAAG,GAAG,OAAO,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACtE,MAAM,UAAU,GAA4B;YAC1C,aAAa;YACb,GAAG;YACH,QAAQ;YACR,QAAQ,EAAE,OAAO,EAAE,QAAQ;YAC3B,SAAS,EAAE,OAAO,EAAE,SAAS;YAC7B,GAAG,gBAAgB;SACpB,CAAC;QACF,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;IACjC,CAAC,EACD,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,OAAO;QACL,UAAU;QACV,SAAS;QACT,UAAU;KACX,CAAC;AACJ,CAAC"}

package/dist/components/ClientMonitor.js

@@ -3,13 +3,17 @@ import { usePathname } from 'next/navigation';
 import { useEffect } from 'react';
 import { useDocumentVisible } from '../hooks/useDocumentVisible';
 const _observers = new Map();
+// Maps to store element metadata for scroll progress calculation
 const _sectionHeights = new Map();
 const _sectionThresholds = new Map();
+// Dense thresholds for IntersectionObserver (0, 0.05, 0.1, ... 1.0)
 const SECTION_THRESHOLDS = Array.from({ length: 21 }, (_, i) => i * 0.05);
+// Tracking for tall elements that need scroll listener
 const _intersectingTallElements = new Set();
 let _scrollRAFId = null;
 let _scrollListenerAttached = false;
 const isDevelopment = process.env.NODE_ENV === 'development';
+// Module-level debug flag, set by ClientMonitor component
 let _debugEnabled = false;
 function shouldDebug(element) {
     if (!isDevelopment)
@@ -20,6 +24,7 @@ function shouldDebug(element) {
         return true;
     return false;
 }
+// Updates scroll progress for a single element (used by scroll handler)
 function updateScrollProgress(element) {
     const elementHeight = _sectionHeights.get(element);
     const threshold = _sectionThresholds.get(element);
@@ -42,6 +47,7 @@ function updateScrollProgress(element) {
         element.dataset.debugIsTallElement = 'true';
     }
 }
+// RAF-throttled scroll handler for tall elements
 function handleScroll() {
     if (_scrollRAFId !== null)
         return;
@@ -52,6 +58,7 @@ function handleScroll() {
         }
     });
 }
+// Attach scroll listener if not already attached
 function attachScrollListener() {
     if (!_scrollListenerAttached) {
         window.addEventListener('scroll', handleScroll, { passive: true });
@@ -61,6 +68,7 @@ function attachScrollListener() {
         }
     }
 }
+// Detach scroll listener if no tall elements are being tracked
 function detachScrollListener() {
     if (_scrollListenerAttached && _intersectingTallElements.size === 0) {
         window.removeEventListener('scroll', handleScroll);
@@ -90,21 +98,26 @@ function getElementThreshold(element, defaultThreshold) {
 function handleVideo(video, isIntersecting) {
     if (!isIntersecting) {
         if (!video.paused) {
+            // console.log("pause video", video.src);
             video.pause();
         }
     }
     else if (video.paused) {
+        // console.log("play video", video.src);
         video
             .play()
             .then(() => {
             video.controls = false;
         })
             .catch(() => {
+            // console.log("failed to play", error);
+            // video.controls = true;
         });
     }
 }
 function handleAnimation(animation, isIntersecting) {
     const currentState = animation.currentState;
+    // console.log('current state', currentState)
     if (!isIntersecting) {
         if (currentState === 'playing') {
             animation.pause();
@@ -112,9 +125,11 @@ function handleAnimation(animation, isIntersecting) {
     }
     else {
         if (currentState === 'paused') {
+            // console.log('play animation')
             animation.play();
         }
         if (!currentState || currentState === 'loading') {
+            // console.log('set to autoplay')
             if (animation.play) {
                 animation.play();
             }
@@ -126,6 +141,7 @@ function handleAnimatedSection(section, isIntersecting, entry) {
     const elementHeight = _sectionHeights.get(section);
     const threshold = _sectionThresholds.get(section);
     if (elementHeight === undefined || threshold === undefined) {
+        // Fallback to intersection-based behavior if height/threshold not available
         section.dataset.visible = isIntersecting ? 'true' : 'false';
         if (isIntersecting && !section.dataset.seen) {
             section.dataset.seen = 'true';
@@ -143,15 +159,18 @@ function handleAnimatedSection(section, isIntersecting, entry) {
         return;
     }
     const isTallElement = elementHeight > window.innerHeight;
+    // For tall elements, use scroll listener for continuous tracking
     if (isTallElement) {
         if (isIntersecting) {
             _intersectingTallElements.add(section);
             attachScrollListener();
+            // Immediately update scroll progress
             updateScrollProgress(section);
         }
         else {
             _intersectingTallElements.delete(section);
             detachScrollListener();
+            // Mark as not visible when leaving viewport
             section.dataset.visible = 'false';
         }
         if (shouldDebug(section)) {
@@ -161,6 +180,7 @@ function handleAnimatedSection(section, isIntersecting, entry) {
         }
         return;
     }
+    // For normal-sized elements, IntersectionObserver provides enough granularity
     const scrollProgress = (window.innerHeight - entry.boundingClientRect.top) / elementHeight;
     const shouldTrigger = scrollProgress >= threshold;
     section.dataset.visible = shouldTrigger ? 'true' : 'false';
@@ -181,6 +201,7 @@ function handleAnimatedSection(section, isIntersecting, entry) {
 }
 function intersectionHandler(entries) {
     for (const entry of entries) {
+        // console.log("target", entry.target.localName, entry.target);
         const target = entry.target;
         switch (target.localName) {
             case 'video':
@@ -232,6 +253,7 @@ function findAllVideos(defaultThreshold) {
         observer.observe(video);
     }
     return () => {
+        // console.log("clear down video observers");
         for (const [observer, videoList] of videoObservers) {
             for (const video of videoList) {
                 observer.unobserve(video);
@@ -261,6 +283,7 @@ function findAllAnimations(defaultThreshold) {
         observer.observe(animation);
     }
     return () => {
+        // console.log("clear down animation observers");
         for (const [observer, animationList] of animationObservers) {
             for (const animation of animationList) {
                 observer.unobserve(animation);
@@ -274,12 +297,15 @@ function findAllAnimatedSections(defaultThreshold) {
     if (shouldDebug()) {
         console.log(`[ClientMonitor] Found ${sections.length} animated section(s)`);
     }
+    // Create a shared observer with dense thresholds for all sections
+    // This gives us callbacks at every 5% intersection change
     const sectionObserver = new IntersectionObserver((entries) => {
         for (const entry of entries) {
             const element = entry.target;
             handleAnimatedSection(element, entry.isIntersecting, entry);
         }
     }, { threshold: SECTION_THRESHOLDS });
+    // Set up ResizeObserver to track element heights
     const resizeObserver = new ResizeObserver((entries) => {
         for (const entry of entries) {
             const element = entry.target;
@@ -289,25 +315,34 @@ function findAllAnimatedSections(defaultThreshold) {
     for (const section of sections) {
         const sectionElement = section;
         const threshold = getElementThreshold(sectionElement, defaultThreshold);
+        // Store threshold for this element
         _sectionThresholds.set(sectionElement, threshold);
+        // Get initial height and store it
         const height = sectionElement.offsetHeight;
         _sectionHeights.set(sectionElement, height);
+        // Observe element for size changes
         resizeObserver.observe(sectionElement);
+        // Track element for cleanup
         sectionElements.push(sectionElement);
         if (shouldDebug(sectionElement)) {
             sectionElement.setAttribute('data-monitor-threshold', threshold.toString());
             sectionElement.setAttribute('data-monitor-observed', 'true');
         }
+        // Observe with shared dense-threshold observer
         sectionObserver.observe(sectionElement);
     }
     return () => {
+        // Clean up IntersectionObserver
         sectionObserver.disconnect();
+        // Clean up ResizeObserver and maps
         for (const sectionElement of sectionElements) {
             resizeObserver.unobserve(sectionElement);
             _sectionHeights.delete(sectionElement);
             _sectionThresholds.delete(sectionElement);
+            // Remove from tall element tracking if present
             _intersectingTallElements.delete(sectionElement);
         }
+        // Clean up scroll listener
         if (_scrollListenerAttached) {
             window.removeEventListener('scroll', handleScroll);
             _scrollListenerAttached = false;
@@ -332,6 +367,7 @@ function findAll(defaultThreshold) {
     };
 }
 export const ClientMonitor = ({ defaultThreshold = 0.2, enableDebug = false, }) => {
+    // Set module-level flag on mount/update
     _debugEnabled = enableDebug;
     const isDocumentVisible = useDocumentVisible();
     const pathname = usePathname();