@jwiedeman/gtm-kit-react 1.1.6 → 1.2.0

package/README.md

@@ -124,16 +124,65 @@ const client = useGtmClient();
 
 ### `useGtmReady()`
 
-Get a function that resolves when GTM is fully loaded.
+Get a function that resolves when GTM is fully loaded. Best for awaiting in event handlers.
 
 ```tsx
 const whenReady = useGtmReady();
 
-useEffect(() => {
-  whenReady().then(() => {
-    console.log('GTM is ready!');
-  });
-}, [whenReady]);
+const handleClick = async () => {
+  await whenReady();
+  console.log('GTM is ready!');
+};
+```
+
+### `useIsGtmReady()`
+
+Get a function for synchronous ready checks. Best for conditionals in callbacks.
+
+```tsx
+const isReady = useIsGtmReady();
+
+const handleClick = () => {
+  if (isReady()) {
+    // GTM is loaded, safe to use advanced features
+  }
+};
+```
+
+### `useGtmInitialized()`
+
+Get a reactive boolean that updates when GTM initializes. Best for conditional rendering.
+
+```tsx
+const isInitialized = useGtmInitialized();
+
+return isInitialized ? <Analytics /> : <Skeleton />;
+```
+
+### `useGtmError()`
+
+Get error state from the GTM provider.
+
+```tsx
+const { hasError, errorMessage } = useGtmError();
+
+if (hasError) {
+  console.error('GTM failed:', errorMessage);
+}
+```
+
+### `useIsGtmProviderPresent()`
+
+Check if GtmProvider exists without throwing. Useful for optional GTM integration.
+
+```tsx
+const hasProvider = useIsGtmProviderPresent();
+
+// Safe to call - won't throw if provider is missing
+if (hasProvider) {
+  const push = useGtmPush();
+  push({ event: 'optional_tracking' });
+}
 ```
 
 ---

package/dist/index.cjs

@@ -4,13 +4,240 @@ var react = require('react');
 var gtmKit = require('@jwiedeman/gtm-kit');
 var jsxRuntime = require('react/jsx-runtime');
 
-var u=react.createContext(null),d=(t,n)=>{process.env.NODE_ENV!=="production"&&t!==n&&console.warn("[react-gtm-kit] GtmProvider received new configuration; reconfiguration after mount is not supported. The initial configuration will continue to be used.");},G=t=>{let n=react.useRef(),e=react.useRef();return n.current?e.current&&d(e.current,t):(n.current=gtmKit.createGtmClient(t),e.current=t),n.current},f=({config:t,children:n})=>{let e=G(t);react.useEffect(()=>(e.init(),()=>{e.teardown();}),[e]);let p=react.useMemo(()=>({client:e,push:o=>e.push(o),setConsentDefaults:(o,r)=>e.setConsentDefaults(o,r),updateConsent:(o,r)=>e.updateConsent(o,r),whenReady:()=>e.whenReady(),onReady:o=>e.onReady(o)}),[e]);return jsxRuntime.jsx(u.Provider,{value:p,children:n})},s=()=>{let t=react.useContext(u);if(!t)throw new Error("useGtm hook must be used within a GtmProvider instance.");return t},v=s,x=()=>s().client,y=()=>s().push,h=()=>{let{setConsentDefaults:t,updateConsent:n}=s();return react.useMemo(()=>({setConsentDefaults:t,updateConsent:n}),[t,n])},P=()=>{let{whenReady:t}=s();return t};
+// src/provider.tsx
+var isSsr = () => typeof window === "undefined";
+var useHydrated = () => {
+  return react.useSyncExternalStore(
+    // Subscribe function (no-op, state never changes after hydration)
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    () => () => {
+    },
+    // getSnapshot (client): always true after first render
+    () => true,
+    // getServerSnapshot (server): always false
+    () => false
+  );
+};
+var GtmContext = react.createContext(null);
+var warnOnNestedProvider = () => {
+  if (process.env.NODE_ENV !== "production") {
+    console.warn(
+      "[gtm-kit/react] Nested GtmProvider detected. You should only have one GtmProvider at the root of your app. The nested provider will be ignored."
+    );
+  }
+};
+var warnOnConfigChange = (initialConfig, nextConfig) => {
+  if (process.env.NODE_ENV !== "production" && initialConfig !== nextConfig) {
+    console.warn(
+      "[gtm-kit/react] GtmProvider received new configuration; reconfiguration after mount is not supported. The initial configuration will continue to be used."
+    );
+  }
+};
+var extractContainerIds = (config) => {
+  const containers = config.containers;
+  const containerArray = Array.isArray(containers) ? containers : [containers];
+  return containerArray.map((container) => {
+    if (typeof container === "string") {
+      return container;
+    }
+    return container.id;
+  });
+};
+var warnOnOrphanedSsrScripts = (configuredContainers) => {
+  if (process.env.NODE_ENV !== "production" && typeof document !== "undefined") {
+    const gtmScripts = document.querySelectorAll('script[src*="googletagmanager.com/gtm.js"]');
+    gtmScripts.forEach((script) => {
+      const src = script.src;
+      const idMatch = src.match(/[?&]id=([^&]+)/);
+      const scriptContainerId = idMatch == null ? void 0 : idMatch[1];
+      if (scriptContainerId && !configuredContainers.includes(scriptContainerId)) {
+        console.warn(
+          `[gtm-kit/react] Found pre-rendered GTM script for container "${scriptContainerId}" that is not configured in GtmProvider. This may indicate a hydration mismatch between SSR and client-side rendering. Configure GtmProvider with containers: "${scriptContainerId}" to properly hydrate.`
+        );
+      }
+    });
+    const gtmNoscripts = document.querySelectorAll('noscript iframe[src*="googletagmanager.com/ns.html"]');
+    gtmNoscripts.forEach((iframe) => {
+      const src = iframe.src;
+      const idMatch = src.match(/[?&]id=([^&]+)/);
+      const iframeContainerId = idMatch == null ? void 0 : idMatch[1];
+      if (iframeContainerId && !configuredContainers.includes(iframeContainerId)) {
+        console.warn(
+          `[gtm-kit/react] Found pre-rendered GTM noscript iframe for container "${iframeContainerId}" that is not configured in GtmProvider. If you pre-render noscript fallbacks on the server, ensure your GtmProvider has the same container ID.`
+        );
+      }
+    });
+  }
+};
+var useStableClient = (config) => {
+  const clientRef = react.useRef();
+  const configRef = react.useRef();
+  if (!clientRef.current) {
+    clientRef.current = gtmKit.createGtmClient(config);
+    configRef.current = config;
+  } else if (configRef.current) {
+    warnOnConfigChange(configRef.current, config);
+  }
+  return clientRef.current;
+};
+var GtmProvider = ({ config, children }) => {
+  const existingContext = react.useContext(GtmContext);
+  react.useEffect(() => {
+    if (existingContext) {
+      warnOnNestedProvider();
+    }
+  }, [existingContext]);
+  if (existingContext) {
+    return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children });
+  }
+  return /* @__PURE__ */ jsxRuntime.jsx(GtmProviderInner, { config, children });
+};
+var GtmProviderInner = ({ config, children }) => {
+  const client = useStableClient(config);
+  react.useEffect(() => {
+    warnOnOrphanedSsrScripts(extractContainerIds(config));
+    client.init();
+    return () => {
+      client.teardown();
+    };
+  }, [client, config]);
+  const value = react.useMemo(
+    () => ({
+      client,
+      push: (value2) => client.push(value2),
+      setConsentDefaults: (state, options) => client.setConsentDefaults(state, options),
+      updateConsent: (state, options) => client.updateConsent(state, options),
+      isReady: () => client.isReady(),
+      whenReady: () => client.whenReady(),
+      onReady: (callback) => client.onReady(callback)
+    }),
+    [client]
+  );
+  return /* @__PURE__ */ jsxRuntime.jsx(GtmContext.Provider, { value, children });
+};
+var useGtmContext = () => {
+  const context = react.useContext(GtmContext);
+  if (!context) {
+    throw new Error(
+      '[gtm-kit/react] useGtm() was called outside of a GtmProvider. Make sure to wrap your app with <GtmProvider config={{ containers: "GTM-XXXXXX" }}>.'
+    );
+  }
+  return context;
+};
+var useGtm = useGtmContext;
+var useIsGtmProviderPresent = () => {
+  const context = react.useContext(GtmContext);
+  return context !== null;
+};
+var useGtmClient = () => {
+  return useGtmContext().client;
+};
+var useGtmPush = () => {
+  return useGtmContext().push;
+};
+var useGtmConsent = () => {
+  const { setConsentDefaults, updateConsent } = useGtmContext();
+  return react.useMemo(() => ({ setConsentDefaults, updateConsent }), [setConsentDefaults, updateConsent]);
+};
+var useGtmReady = () => {
+  const { whenReady } = useGtmContext();
+  return whenReady;
+};
+var useIsGtmReady = () => {
+  const { isReady } = useGtmContext();
+  return isReady;
+};
+var useGtmInitialized = () => {
+  const { isReady, onReady } = useGtmContext();
+  const [initialized, setInitialized] = react.useState(() => isReady());
+  react.useEffect(() => {
+    if (isReady()) {
+      setInitialized(true);
+      return;
+    }
+    const unsubscribe = onReady(() => {
+      setInitialized(true);
+    });
+    return unsubscribe;
+  }, [isReady, onReady]);
+  return initialized;
+};
+var useGtmError = () => {
+  const { onReady } = useGtmContext();
+  const [errorState, setErrorState] = react.useState({
+    hasError: false,
+    failedScripts: [],
+    errorMessage: null
+  });
+  react.useEffect(() => {
+    const unsubscribe = onReady((states) => {
+      var _a, _b;
+      const failedScripts = states.filter((s) => s.status === "failed" || s.status === "partial");
+      if (failedScripts.length > 0) {
+        const firstError = (_b = (_a = failedScripts.find((s) => s.error)) == null ? void 0 : _a.error) != null ? _b : null;
+        setErrorState({
+          hasError: true,
+          failedScripts,
+          errorMessage: firstError
+        });
+      }
+    });
+    return unsubscribe;
+  }, [onReady]);
+  return errorState;
+};
+var GtmErrorBoundary = class extends react.Component {
+  constructor(props) {
+    super(props);
+    this.reset = () => {
+      this.setState({ hasError: false, error: null });
+    };
+    this.state = { hasError: false, error: null };
+  }
+  static getDerivedStateFromError(error) {
+    return { hasError: true, error };
+  }
+  componentDidCatch(error, errorInfo) {
+    const { onError, logErrors = process.env.NODE_ENV !== "production" } = this.props;
+    if (logErrors) {
+      console.error("[gtm-kit/react] Error caught by GtmErrorBoundary:", error);
+      console.error("[gtm-kit/react] Component stack:", errorInfo.componentStack);
+    }
+    if (onError) {
+      try {
+        onError(error, errorInfo);
+      } catch (e) {
+      }
+    }
+  }
+  render() {
+    const { hasError, error } = this.state;
+    const { children, fallback } = this.props;
+    if (hasError && error) {
+      if (fallback === void 0) {
+        return children;
+      }
+      if (typeof fallback === "function") {
+        return fallback(error, this.reset);
+      }
+      return fallback;
+    }
+    return children;
+  }
+};
 
-exports.GtmProvider = f;
-exports.useGtm = v;
-exports.useGtmClient = x;
-exports.useGtmConsent = h;
-exports.useGtmPush = y;
-exports.useGtmReady = P;
+exports.GtmErrorBoundary = GtmErrorBoundary;
+exports.GtmProvider = GtmProvider;
+exports.isSsr = isSsr;
+exports.useGtm = useGtm;
+exports.useGtmClient = useGtmClient;
+exports.useGtmConsent = useGtmConsent;
+exports.useGtmError = useGtmError;
+exports.useGtmInitialized = useGtmInitialized;
+exports.useGtmPush = useGtmPush;
+exports.useGtmReady = useGtmReady;
+exports.useHydrated = useHydrated;
+exports.useIsGtmProviderPresent = useIsGtmProviderPresent;
+exports.useIsGtmReady = useIsGtmReady;
 //# sourceMappingURL=out.js.map
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/provider.tsx"],"names":["createContext","useContext","useEffect","useMemo","useRef","createGtmClient","jsx","GtmContext","warnOnConfigChange","initialConfig","nextConfig","useStableClient","config","clientRef","configRef","GtmProvider","children","client","value","state","options","callback","useGtmContext","context","useGtm","useGtmClient","useGtmPush","useGtmConsent","setConsentDefaults","updateConsent","useGtmReady","whenReady"],"mappings":"AAAA,OAAS,iBAAAA,EAAe,cAAAC,EAAY,aAAAC,EAAW,WAAAC,EAAS,UAAAC,MAAgD,QACxG,OACE,mBAAAC,MAOK,qBAmEE,cAAAC,MAAA,oBA/CT,IAAMC,EAAaP,EAAsC,IAAI,EAEvDQ,EAAqB,CAACC,EAAuCC,IAA6C,CAC1G,QAAQ,IAAI,WAAa,cAAgBD,IAAkBC,GAC7D,QAAQ,KACN,2JAEF,CAEJ,EAEMC,EAAmBC,GAA8C,CACrE,IAAMC,EAAYT,EAAkB,EAC9BU,EAAYV,EAA+B,EAEjD,OAAKS,EAAU,QAGJC,EAAU,SACnBN,EAAmBM,EAAU,QAASF,CAAM,GAH5CC,EAAU,QAAUR,EAAgBO,CAAM,EAC1CE,EAAU,QAAUF,GAKfC,EAAU,OACnB,EAEaE,EAAc,CAAC,CAAE,OAAAH,EAAQ,SAAAI,CAAS,IAAqC,CAClF,IAAMC,EAASN,EAAgBC,CAAM,EAErCV,EAAU,KACRe,EAAO,KAAK,EACL,IAAM,CACXA,EAAO,SAAS,CAClB,GACC,CAACA,CAAM,CAAC,EAEX,IAAMC,EAAQf,EACZ,KAAO,CACL,OAAAc,EACA,KAAOC,GAAUD,EAAO,KAAKC,CAAK,EAClC,mBAAoB,CAACC,EAAOC,IAAYH,EAAO,mBAAmBE,EAAOC,CAAO,EAChF,cAAe,CAACD,EAAOC,IAAYH,EAAO,cAAcE,EAAOC,CAAO,EACtE,UAAW,IAAMH,EAAO,UAAU,EAClC,QAAUI,GAAaJ,EAAO,QAAQI,CAAQ,CAChD,GACA,CAACJ,CAAM,CACT,EAEA,OAAOX,EAACC,EAAW,SAAX,CAAoB,MAAOW,EAAQ,SAAAF,EAAS,CACtD,EAEMM,EAAgB,IAAuB,CAC3C,IAAMC,EAAUtB,EAAWM,CAAU,EACrC,GAAI,CAACgB,EACH,MAAM,IAAI,MAAM,yDAAyD,EAE3E,OAAOA,CACT,EAEaC,EAASF,EAETG,EAAe,IACnBH,EAAc,EAAE,OAGZI,EAAa,IACjBJ,EAAc,EAAE,KAGZK,EAAgB,IAAqB,CAChD,GAAM,CAAE,mBAAAC,EAAoB,cAAAC,CAAc,EAAIP,EAAc,EAC5D,OAAOnB,EAAQ,KAAO,CAAE,mBAAAyB,EAAoB,cAAAC,CAAc,GAAI,CAACD,EAAoBC,CAAa,CAAC,CACnG,EAEaC,EAAc,IAA0C,CACnE,GAAM,CAAE,UAAAC,CAAU,EAAIT,EAAc,EACpC,OAAOS,CACT","sourcesContent":["import { createContext, useContext, useEffect, useMemo, useRef, type PropsWithChildren, type JSX } from 'react';\nimport {\n  createGtmClient,\n  type ConsentRegionOptions,\n  type ConsentState,\n  type CreateGtmClientOptions,\n  type DataLayerValue,\n  type GtmClient,\n  type ScriptLoadState\n} from '@jwiedeman/gtm-kit';\n\nexport interface GtmProviderProps extends PropsWithChildren {\n  config: CreateGtmClientOptions;\n}\n\nexport interface GtmContextValue {\n  client: GtmClient;\n  push: (value: DataLayerValue) => void;\n  setConsentDefaults: (state: ConsentState, options?: ConsentRegionOptions) => void;\n  updateConsent: (state: ConsentState, options?: ConsentRegionOptions) => void;\n  whenReady: () => Promise<ScriptLoadState[]>;\n  onReady: (callback: (state: ScriptLoadState[]) => void) => () => void;\n}\n\nexport interface GtmConsentApi {\n  setConsentDefaults: (state: ConsentState, options?: ConsentRegionOptions) => void;\n  updateConsent: (state: ConsentState, options?: ConsentRegionOptions) => void;\n}\n\nconst GtmContext = createContext<GtmContextValue | null>(null);\n\nconst warnOnConfigChange = (initialConfig: CreateGtmClientOptions, nextConfig: CreateGtmClientOptions): void => {\n  if (process.env.NODE_ENV !== 'production' && initialConfig !== nextConfig) {\n    console.warn(\n      '[react-gtm-kit] GtmProvider received new configuration; reconfiguration after mount is not supported. ' +\n        'The initial configuration will continue to be used.'\n    );\n  }\n};\n\nconst useStableClient = (config: CreateGtmClientOptions): GtmClient => {\n  const clientRef = useRef<GtmClient>();\n  const configRef = useRef<CreateGtmClientOptions>();\n\n  if (!clientRef.current) {\n    clientRef.current = createGtmClient(config);\n    configRef.current = config;\n  } else if (configRef.current) {\n    warnOnConfigChange(configRef.current, config);\n  }\n\n  return clientRef.current!;\n};\n\nexport const GtmProvider = ({ config, children }: GtmProviderProps): JSX.Element => {\n  const client = useStableClient(config);\n\n  useEffect(() => {\n    client.init();\n    return () => {\n      client.teardown();\n    };\n  }, [client]);\n\n  const value = useMemo<GtmContextValue>(\n    () => ({\n      client,\n      push: (value) => client.push(value),\n      setConsentDefaults: (state, options) => client.setConsentDefaults(state, options),\n      updateConsent: (state, options) => client.updateConsent(state, options),\n      whenReady: () => client.whenReady(),\n      onReady: (callback) => client.onReady(callback)\n    }),\n    [client]\n  );\n\n  return <GtmContext.Provider value={value}>{children}</GtmContext.Provider>;\n};\n\nconst useGtmContext = (): GtmContextValue => {\n  const context = useContext(GtmContext);\n  if (!context) {\n    throw new Error('useGtm hook must be used within a GtmProvider instance.');\n  }\n  return context;\n};\n\nexport const useGtm = useGtmContext;\n\nexport const useGtmClient = (): GtmClient => {\n  return useGtmContext().client;\n};\n\nexport const useGtmPush = (): ((value: DataLayerValue) => void) => {\n  return useGtmContext().push;\n};\n\nexport const useGtmConsent = (): GtmConsentApi => {\n  const { setConsentDefaults, updateConsent } = useGtmContext();\n  return useMemo(() => ({ setConsentDefaults, updateConsent }), [setConsentDefaults, updateConsent]);\n};\n\nexport const useGtmReady = (): (() => Promise<ScriptLoadState[]>) => {\n  const { whenReady } = useGtmContext();\n  return whenReady;\n};\n"]}
+{"version":3,"sources":["../src/provider.tsx"],"names":["value"],"mappings":";AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAKK;AACP;AAAA,EACE;AAAA,OAOK;AA+LI;AAzLJ,IAAM,QAAQ,MAAe,OAAO,WAAW;AAc/C,IAAM,cAAc,MAAe;AAExC,SAAO;AAAA;AAAA;AAAA,IAGL,MAAM,MAAM;AAAA,IAAC;AAAA;AAAA,IAEb,MAAM;AAAA;AAAA,IAEN,MAAM;AAAA,EACR;AACF;AAsBA,IAAM,aAAa,cAAsC,IAAI;AAE7D,IAAM,uBAAuB,MAAY;AACvC,MAAI,QAAQ,IAAI,aAAa,cAAc;AACzC,YAAQ;AAAA,MACN;AAAA,IAEF;AAAA,EACF;AACF;AAEA,IAAM,qBAAqB,CAAC,eAAuC,eAA6C;AAC9G,MAAI,QAAQ,IAAI,aAAa,gBAAgB,kBAAkB,YAAY;AACzE,YAAQ;AAAA,MACN;AAAA,IAEF;AAAA,EACF;AACF;AAKA,IAAM,sBAAsB,CAAC,WAA6C;AACxE,QAAM,aAAa,OAAO;AAC1B,QAAM,iBAAiB,MAAM,QAAQ,UAAU,IAAI,aAAa,CAAC,UAAU;AAE3E,SAAO,eAAe,IAAI,CAAC,cAAc;AACvC,QAAI,OAAO,cAAc,UAAU;AACjC,aAAO;AAAA,IACT;AACA,WAAO,UAAU;AAAA,EACnB,CAAC;AACH;AAOA,IAAM,2BAA2B,CAAC,yBAAyC;AACzE,MAAI,QAAQ,IAAI,aAAa,gBAAgB,OAAO,aAAa,aAAa;AAE5E,UAAM,aAAa,SAAS,iBAAiB,4CAA4C;AAEzF,eAAW,QAAQ,CAAC,WAAW;AAC7B,YAAM,MAAO,OAA6B;AAC1C,YAAM,UAAU,IAAI,MAAM,gBAAgB;AAC1C,YAAM,oBAAoB,mCAAU;AAEpC,UAAI,qBAAqB,CAAC,qBAAqB,SAAS,iBAAiB,GAAG;AAC1E,gBAAQ;AAAA,UACN,gEAAgE,iBAAiB,kKAEpC,iBAAiB;AAAA,QAChE;AAAA,MACF;AAAA,IACF,CAAC;AAGD,UAAM,eAAe,SAAS,iBAAiB,sDAAsD;AACrG,iBAAa,QAAQ,CAAC,WAAW;AAC/B,YAAM,MAAO,OAA6B;AAC1C,YAAM,UAAU,IAAI,MAAM,gBAAgB;AAC1C,YAAM,oBAAoB,mCAAU;AAEpC,UAAI,qBAAqB,CAAC,qBAAqB,SAAS,iBAAiB,GAAG;AAC1E,gBAAQ;AAAA,UACN,yEAAyE,iBAAiB;AAAA,QAE5F;AAAA,MACF;AAAA,IACF,CAAC;AAAA,EACH;AACF;AAEA,IAAM,kBAAkB,CAAC,WAA8C;AACrE,QAAM,YAAY,OAAkB;AACpC,QAAM,YAAY,OAA+B;AAEjD,MAAI,CAAC,UAAU,SAAS;AACtB,cAAU,UAAU,gBAAgB,MAAM;AAC1C,cAAU,UAAU;AAAA,EACtB,WAAW,UAAU,SAAS;AAC5B,uBAAmB,UAAU,SAAS,MAAM;AAAA,EAC9C;AAEA,SAAO,UAAU;AACnB;AAsCO,IAAM,cAAc,CAAC,EAAE,QAAQ,SAAS,MAAqC;AAClF,QAAM,kBAAkB,WAAW,UAAU;AAG7C,YAAU,MAAM;AACd,QAAI,iBAAiB;AACnB,2BAAqB;AAAA,IACvB;AAAA,EACF,GAAG,CAAC,eAAe,CAAC;AAGpB,MAAI,iBAAiB;AACnB,WAAO,gCAAG,UAAS;AAAA,EACrB;AAEA,SAAO,oBAAC,oBAAiB,QAAiB,UAAS;AACrD;AAEA,IAAM,mBAAmB,CAAC,EAAE,QAAQ,SAAS,MAAqC;AAChF,QAAM,SAAS,gBAAgB,MAAM;AAErC,YAAU,MAAM;AAEd,6BAAyB,oBAAoB,MAAM,CAAC;AAEpD,WAAO,KAAK;AACZ,WAAO,MAAM;AACX,aAAO,SAAS;AAAA,IAClB;AAAA,EACF,GAAG,CAAC,QAAQ,MAAM,CAAC;AAEnB,QAAM,QAAQ;AAAA,IACZ,OAAO;AAAA,MACL;AAAA,MACA,MAAM,CAACA,WAAU,OAAO,KAAKA,MAAK;AAAA,MAClC,oBAAoB,CAAC,OAAO,YAAY,OAAO,mBAAmB,OAAO,OAAO;AAAA,MAChF,eAAe,CAAC,OAAO,YAAY,OAAO,cAAc,OAAO,OAAO;AAAA,MACtE,SAAS,MAAM,OAAO,QAAQ;AAAA,MAC9B,WAAW,MAAM,OAAO,UAAU;AAAA,MAClC,SAAS,CAAC,aAAa,OAAO,QAAQ,QAAQ;AAAA,IAChD;AAAA,IACA,CAAC,MAAM;AAAA,EACT;AAEA,SAAO,oBAAC,WAAW,UAAX,EAAoB,OAAe,UAAS;AACtD;AAEA,IAAM,gBAAgB,MAAuB;AAC3C,QAAM,UAAU,WAAW,UAAU;AACrC,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI;AAAA,MACR;AAAA,IAEF;AAAA,EACF;AACA,SAAO;AACT;AAiBO,IAAM,SAAS;AAqBf,IAAM,0BAA0B,MAAe;AACpD,QAAM,UAAU,WAAW,UAAU;AACrC,SAAO,YAAY;AACrB;AAgBO,IAAM,eAAe,MAAiB;AAC3C,SAAO,cAAc,EAAE;AACzB;AAwBO,IAAM,aAAa,MAAyC;AACjE,SAAO,cAAc,EAAE;AACzB;AAoBO,IAAM,gBAAgB,MAAqB;AAChD,QAAM,EAAE,oBAAoB,cAAc,IAAI,cAAc;AAC5D,SAAO,QAAQ,OAAO,EAAE,oBAAoB,cAAc,IAAI,CAAC,oBAAoB,aAAa,CAAC;AACnG;AA6BO,IAAM,cAAc,MAA0C;AACnE,QAAM,EAAE,UAAU,IAAI,cAAc;AACpC,SAAO;AACT;AA6BO,IAAM,gBAAgB,MAAuB;AAClD,QAAM,EAAE,QAAQ,IAAI,cAAc;AAClC,SAAO;AACT;AA4BO,IAAM,oBAAoB,MAAe;AAC9C,QAAM,EAAE,SAAS,QAAQ,IAAI,cAAc;AAC3C,QAAM,CAAC,aAAa,cAAc,IAAI,SAAS,MAAM,QAAQ,CAAC;AAE9D,YAAU,MAAM;AAEd,QAAI,QAAQ,GAAG;AACb,qBAAe,IAAI;AACnB;AAAA,IACF;AAGA,UAAM,cAAc,QAAQ,MAAM;AAChC,qBAAe,IAAI;AAAA,IACrB,CAAC;AAED,WAAO;AAAA,EACT,GAAG,CAAC,SAAS,OAAO,CAAC;AAErB,SAAO;AACT;AA4BO,IAAM,cAAc,MAAqB;AAC9C,QAAM,EAAE,QAAQ,IAAI,cAAc;AAClC,QAAM,CAAC,YAAY,aAAa,IAAI,SAAwB;AAAA,IAC1D,UAAU;AAAA,IACV,eAAe,CAAC;AAAA,IAChB,cAAc;AAAA,EAChB,CAAC;AAED,YAAU,MAAM;AACd,UAAM,cAAc,QAAQ,CAAC,WAAW;AAlgB5C;AAmgBM,YAAM,gBAAgB,OAAO,OAAO,CAAC,MAAM,EAAE,WAAW,YAAY,EAAE,WAAW,SAAS;AAE1F,UAAI,cAAc,SAAS,GAAG;AAC5B,cAAM,cAAa,yBAAc,KAAK,CAAC,MAAM,EAAE,KAAK,MAAjC,mBAAoC,UAApC,YAA6C;AAChE,sBAAc;AAAA,UACZ,UAAU;AAAA,UACV;AAAA,UACA,cAAc;AAAA,QAChB,CAAC;AAAA,MACH;AAAA,IACF,CAAC;AAED,WAAO;AAAA,EACT,GAAG,CAAC,OAAO,CAAC;AAEZ,SAAO;AACT;AAyBO,IAAM,mBAAN,cAA+B,UAAwD;AAAA,EAC5F,YAAY,OAA8B;AACxC,UAAM,KAAK;AAyBb,iBAAQ,MAAY;AAClB,WAAK,SAAS,EAAE,UAAU,OAAO,OAAO,KAAK,CAAC;AAAA,IAChD;AA1BE,SAAK,QAAQ,EAAE,UAAU,OAAO,OAAO,KAAK;AAAA,EAC9C;AAAA,EAEA,OAAO,yBAAyB,OAAqC;AACnE,WAAO,EAAE,UAAU,MAAM,MAAM;AAAA,EACjC;AAAA,EAEA,kBAAkB,OAAc,WAA4B;AAC1D,UAAM,EAAE,SAAS,YAAY,QAAQ,IAAI,aAAa,aAAa,IAAI,KAAK;AAE5E,QAAI,WAAW;AACb,cAAQ,MAAM,qDAAqD,KAAK;AACxE,cAAQ,MAAM,oCAAoC,UAAU,cAAc;AAAA,IAC5E;AAEA,QAAI,SAAS;AACX,UAAI;AACF,gBAAQ,OAAO,SAAS;AAAA,MAC1B,SAAQ;AAAA,MAER;AAAA,IACF;AAAA,EACF;AAAA,EAMA,SAAoB;AAClB,UAAM,EAAE,UAAU,MAAM,IAAI,KAAK;AACjC,UAAM,EAAE,UAAU,SAAS,IAAI,KAAK;AAEpC,QAAI,YAAY,OAAO;AACrB,UAAI,aAAa,QAAW;AAE1B,eAAO;AAAA,MACT;AAEA,UAAI,OAAO,aAAa,YAAY;AAClC,eAAO,SAAS,OAAO,KAAK,KAAK;AAAA,MACnC;AAEA,aAAO;AAAA,IACT;AAEA,WAAO;AAAA,EACT;AACF","sourcesContent":["import {\n  Component,\n  createContext,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\n  useSyncExternalStore,\n  type ErrorInfo,\n  type PropsWithChildren,\n  type ReactNode,\n  type JSX\n} from 'react';\nimport {\n  createGtmClient,\n  type ConsentRegionOptions,\n  type ConsentState,\n  type CreateGtmClientOptions,\n  type DataLayerValue,\n  type GtmClient,\n  type ScriptLoadState\n} from '@jwiedeman/gtm-kit';\n\n/**\n * Check if code is running in a server-side rendering environment.\n * Returns true if window is undefined (Node.js/SSR), false in browser.\n */\nexport const isSsr = (): boolean => typeof window === 'undefined';\n\n/**\n * Hook that returns false during SSR and initial hydration, then true after hydration completes.\n * Use this to prevent hydration mismatches when rendering GTM-dependent content.\n *\n * @example\n * ```tsx\n * const isHydrated = useHydrated();\n *\n * // Safe: won't cause hydration mismatch\n * return isHydrated ? <DynamicContent /> : <StaticPlaceholder />;\n * ```\n */\nexport const useHydrated = (): boolean => {\n  // useSyncExternalStore with getServerSnapshot ensures consistent SSR/hydration\n  return useSyncExternalStore(\n    // Subscribe function (no-op, state never changes after hydration)\n    // eslint-disable-next-line @typescript-eslint/no-empty-function\n    () => () => {},\n    // getSnapshot (client): always true after first render\n    () => true,\n    // getServerSnapshot (server): always false\n    () => false\n  );\n};\n\nexport interface GtmProviderProps extends PropsWithChildren {\n  config: CreateGtmClientOptions;\n}\n\nexport interface GtmContextValue {\n  client: GtmClient;\n  push: (value: DataLayerValue) => void;\n  setConsentDefaults: (state: ConsentState, options?: ConsentRegionOptions) => void;\n  updateConsent: (state: ConsentState, options?: ConsentRegionOptions) => void;\n  /** Synchronously check if all GTM scripts have finished loading */\n  isReady: () => boolean;\n  whenReady: () => Promise<ScriptLoadState[]>;\n  onReady: (callback: (state: ScriptLoadState[]) => void) => () => void;\n}\n\nexport interface GtmConsentApi {\n  setConsentDefaults: (state: ConsentState, options?: ConsentRegionOptions) => void;\n  updateConsent: (state: ConsentState, options?: ConsentRegionOptions) => void;\n}\n\nconst GtmContext = createContext<GtmContextValue | null>(null);\n\nconst warnOnNestedProvider = (): void => {\n  if (process.env.NODE_ENV !== 'production') {\n    console.warn(\n      '[gtm-kit/react] Nested GtmProvider detected. You should only have one GtmProvider at the root of your app. ' +\n        'The nested provider will be ignored.'\n    );\n  }\n};\n\nconst warnOnConfigChange = (initialConfig: CreateGtmClientOptions, nextConfig: CreateGtmClientOptions): void => {\n  if (process.env.NODE_ENV !== 'production' && initialConfig !== nextConfig) {\n    console.warn(\n      '[gtm-kit/react] GtmProvider received new configuration; reconfiguration after mount is not supported. ' +\n        'The initial configuration will continue to be used.'\n    );\n  }\n};\n\n/**\n * Extracts container IDs from the provider config.\n */\nconst extractContainerIds = (config: CreateGtmClientOptions): string[] => {\n  const containers = config.containers;\n  const containerArray = Array.isArray(containers) ? containers : [containers];\n\n  return containerArray.map((container) => {\n    if (typeof container === 'string') {\n      return container;\n    }\n    return container.id;\n  });\n};\n\n/**\n * Warns in development if there are orphaned SSR-rendered GTM scripts without a matching client.\n * This helps developers identify hydration mismatches where GTM was rendered on the server\n * but the GtmProvider config doesn't match or is missing.\n */\nconst warnOnOrphanedSsrScripts = (configuredContainers: string[]): void => {\n  if (process.env.NODE_ENV !== 'production' && typeof document !== 'undefined') {\n    // Find all GTM scripts on the page\n    const gtmScripts = document.querySelectorAll('script[src*=\"googletagmanager.com/gtm.js\"]');\n\n    gtmScripts.forEach((script) => {\n      const src = (script as HTMLScriptElement).src;\n      const idMatch = src.match(/[?&]id=([^&]+)/);\n      const scriptContainerId = idMatch?.[1];\n\n      if (scriptContainerId && !configuredContainers.includes(scriptContainerId)) {\n        console.warn(\n          `[gtm-kit/react] Found pre-rendered GTM script for container \"${scriptContainerId}\" that is not configured in GtmProvider. ` +\n            'This may indicate a hydration mismatch between SSR and client-side rendering. ' +\n            `Configure GtmProvider with containers: \"${scriptContainerId}\" to properly hydrate.`\n        );\n      }\n    });\n\n    // Also check for noscript iframes\n    const gtmNoscripts = document.querySelectorAll('noscript iframe[src*=\"googletagmanager.com/ns.html\"]');\n    gtmNoscripts.forEach((iframe) => {\n      const src = (iframe as HTMLIFrameElement).src;\n      const idMatch = src.match(/[?&]id=([^&]+)/);\n      const iframeContainerId = idMatch?.[1];\n\n      if (iframeContainerId && !configuredContainers.includes(iframeContainerId)) {\n        console.warn(\n          `[gtm-kit/react] Found pre-rendered GTM noscript iframe for container \"${iframeContainerId}\" that is not configured in GtmProvider. ` +\n            'If you pre-render noscript fallbacks on the server, ensure your GtmProvider has the same container ID.'\n        );\n      }\n    });\n  }\n};\n\nconst useStableClient = (config: CreateGtmClientOptions): GtmClient => {\n  const clientRef = useRef<GtmClient>();\n  const configRef = useRef<CreateGtmClientOptions>();\n\n  if (!clientRef.current) {\n    clientRef.current = createGtmClient(config);\n    configRef.current = config;\n  } else if (configRef.current) {\n    warnOnConfigChange(configRef.current, config);\n  }\n\n  return clientRef.current!;\n};\n\n/**\n * GTM Provider component that initializes Google Tag Manager for your React app.\n *\n * ## SSR/Hydration Behavior\n *\n * This provider is SSR-safe and handles hydration correctly:\n * - **Server**: No GTM initialization occurs (no window/document access)\n * - **Client Hydration**: GTM initializes only after hydration via useEffect\n * - **No Hydration Mismatch**: Provider renders the same on server and client\n *\n * ## Usage with SSR Frameworks\n *\n * ```tsx\n * // Next.js, Remix, etc.\n * export default function App({ children }) {\n *   return (\n *     <GtmProvider config={{ containers: 'GTM-XXXXXX' }}>\n *       {children}\n *     </GtmProvider>\n *   );\n * }\n * ```\n *\n * ## Preventing Hydration Mismatches\n *\n * If you render different content based on GTM state, use `useHydrated`:\n *\n * ```tsx\n * const isHydrated = useHydrated();\n * const isGtmReady = useGtmInitialized();\n *\n * // Safe: both server and client initially render the placeholder\n * if (!isHydrated) return <Placeholder />;\n * return isGtmReady ? <TrackedContent /> : <LoadingContent />;\n * ```\n */\nexport const GtmProvider = ({ config, children }: GtmProviderProps): JSX.Element => {\n  const existingContext = useContext(GtmContext);\n\n  // Warn if we're inside another GtmProvider (nested providers)\n  useEffect(() => {\n    if (existingContext) {\n      warnOnNestedProvider();\n    }\n  }, [existingContext]);\n\n  // If nested, just pass through children without creating a new context\n  if (existingContext) {\n    return <>{children}</>;\n  }\n\n  return <GtmProviderInner config={config}>{children}</GtmProviderInner>;\n};\n\nconst GtmProviderInner = ({ config, children }: GtmProviderProps): JSX.Element => {\n  const client = useStableClient(config);\n\n  useEffect(() => {\n    // Check for orphaned SSR scripts before initializing\n    warnOnOrphanedSsrScripts(extractContainerIds(config));\n\n    client.init();\n    return () => {\n      client.teardown();\n    };\n  }, [client, config]);\n\n  const value = useMemo<GtmContextValue>(\n    () => ({\n      client,\n      push: (value) => client.push(value),\n      setConsentDefaults: (state, options) => client.setConsentDefaults(state, options),\n      updateConsent: (state, options) => client.updateConsent(state, options),\n      isReady: () => client.isReady(),\n      whenReady: () => client.whenReady(),\n      onReady: (callback) => client.onReady(callback)\n    }),\n    [client]\n  );\n\n  return <GtmContext.Provider value={value}>{children}</GtmContext.Provider>;\n};\n\nconst useGtmContext = (): GtmContextValue => {\n  const context = useContext(GtmContext);\n  if (!context) {\n    throw new Error(\n      '[gtm-kit/react] useGtm() was called outside of a GtmProvider. ' +\n        'Make sure to wrap your app with <GtmProvider config={{ containers: \"GTM-XXXXXX\" }}>.'\n    );\n  }\n  return context;\n};\n\n/**\n * Hook to access the full GTM context. Throws if used outside GtmProvider.\n *\n * For most use cases, prefer the specific hooks:\n * - `useGtmPush()` - Push events to dataLayer\n * - `useGtmConsent()` - Manage consent state\n * - `useGtmClient()` - Access the raw GTM client\n *\n * @throws Error if called outside of GtmProvider\n *\n * @example\n * ```tsx\n * const { push, client, isReady, whenReady } = useGtm();\n * ```\n */\nexport const useGtm = useGtmContext;\n\n/**\n * Hook to check if GtmProvider is present without throwing.\n *\n * Useful for components that may be rendered before the provider mounts,\n * or for optional GTM integration.\n *\n * @returns `true` if inside GtmProvider, `false` otherwise\n *\n * @example\n * ```tsx\n * const hasProvider = useIsGtmProviderPresent();\n *\n * const handleClick = () => {\n *   if (hasProvider) {\n *     // Safe to use GTM hooks\n *   }\n * };\n * ```\n */\nexport const useIsGtmProviderPresent = (): boolean => {\n  const context = useContext(GtmContext);\n  return context !== null;\n};\n\n/**\n * Hook to access the raw GTM client instance.\n *\n * @throws Error if called outside of GtmProvider\n * @returns The GTM client instance\n *\n * @example\n * ```tsx\n * const client = useGtmClient();\n *\n * // Access low-level APIs\n * const diagnostics = client.getDiagnostics();\n * ```\n */\nexport const useGtmClient = (): GtmClient => {\n  return useGtmContext().client;\n};\n\n/**\n * Hook to get the push function for sending events to the dataLayer.\n *\n * This is the most commonly used hook for tracking events.\n *\n * @throws Error if called outside of GtmProvider\n * @returns Function to push values to the dataLayer\n *\n * @example\n * ```tsx\n * const push = useGtmPush();\n *\n * const handleAddToCart = (product) => {\n *   push({\n *     event: 'add_to_cart',\n *     ecommerce: {\n *       items: [{ item_id: product.id, item_name: product.name }]\n *     }\n *   });\n * };\n * ```\n */\nexport const useGtmPush = (): ((value: DataLayerValue) => void) => {\n  return useGtmContext().push;\n};\n\n/**\n * Hook to access consent management functions.\n *\n * @throws Error if called outside of GtmProvider\n * @returns Object with `setConsentDefaults` and `updateConsent` functions\n *\n * @example\n * ```tsx\n * const { updateConsent } = useGtmConsent();\n *\n * const handleAcceptCookies = () => {\n *   updateConsent({\n *     ad_storage: 'granted',\n *     analytics_storage: 'granted'\n *   });\n * };\n * ```\n */\nexport const useGtmConsent = (): GtmConsentApi => {\n  const { setConsentDefaults, updateConsent } = useGtmContext();\n  return useMemo(() => ({ setConsentDefaults, updateConsent }), [setConsentDefaults, updateConsent]);\n};\n\n/**\n * Hook that returns the `whenReady` promise function.\n *\n * **When to use**: When you need to await GTM script loading before taking an action.\n * The returned function returns a Promise that resolves when scripts finish loading.\n *\n * **Comparison of GTM readiness hooks:**\n * | Hook | Returns | Re-renders | Use Case |\n * |------|---------|------------|----------|\n * | `useGtmReady()` | `() => Promise` | No | Await in event handlers |\n * | `useIsGtmReady()` | `() => boolean` | No | Synchronous checks in callbacks |\n * | `useGtmInitialized()` | `boolean` | Yes | Conditional rendering |\n *\n * @returns Function that returns a Promise resolving to script load states\n *\n * @example\n * ```tsx\n * const whenReady = useGtmReady();\n *\n * const handleClick = async () => {\n *   const states = await whenReady();\n *   if (states.every(s => s.status === 'loaded')) {\n *     // Safe to rely on GTM being fully loaded\n *   }\n * };\n * ```\n */\nexport const useGtmReady = (): (() => Promise<ScriptLoadState[]>) => {\n  const { whenReady } = useGtmContext();\n  return whenReady;\n};\n\n/**\n * Hook that returns a function to synchronously check if GTM is ready.\n *\n * **When to use**: When you need to check readiness without triggering re-renders,\n * typically in event handlers or callbacks.\n *\n * **Comparison of GTM readiness hooks:**\n * | Hook | Returns | Re-renders | Use Case |\n * |------|---------|------------|----------|\n * | `useGtmReady()` | `() => Promise` | No | Await in event handlers |\n * | `useIsGtmReady()` | `() => boolean` | No | Synchronous checks in callbacks |\n * | `useGtmInitialized()` | `boolean` | Yes | Conditional rendering |\n *\n * @returns Function that returns `true` if scripts loaded, `false` if still loading\n *\n * @example\n * ```tsx\n * const checkReady = useIsGtmReady();\n *\n * const handleSubmit = () => {\n *   if (checkReady()) {\n *     // GTM is ready, proceed with tracking\n *     push({ event: 'form_submit' });\n *   }\n * };\n * ```\n */\nexport const useIsGtmReady = (): (() => boolean) => {\n  const { isReady } = useGtmContext();\n  return isReady;\n};\n\n/**\n * Reactive hook that returns `true` when GTM scripts have finished loading.\n *\n * **When to use**: When you need to conditionally render UI based on GTM readiness.\n * This hook triggers a re-render when the state changes.\n *\n * **Comparison of GTM readiness hooks:**\n * | Hook | Returns | Re-renders | Use Case |\n * |------|---------|------------|----------|\n * | `useGtmReady()` | `() => Promise` | No | Await in event handlers |\n * | `useIsGtmReady()` | `() => boolean` | No | Synchronous checks in callbacks |\n * | `useGtmInitialized()` | `boolean` | Yes | Conditional rendering |\n *\n * @returns `true` if GTM is initialized, `false` otherwise (reactive)\n *\n * @example\n * ```tsx\n * const isInitialized = useGtmInitialized();\n *\n * if (!isInitialized) {\n *   return <LoadingSpinner />;\n * }\n *\n * return <AnalyticsDashboard />;\n * ```\n */\nexport const useGtmInitialized = (): boolean => {\n  const { isReady, onReady } = useGtmContext();\n  const [initialized, setInitialized] = useState(() => isReady());\n\n  useEffect(() => {\n    // Already initialized on mount\n    if (isReady()) {\n      setInitialized(true);\n      return;\n    }\n\n    // Subscribe to ready event\n    const unsubscribe = onReady(() => {\n      setInitialized(true);\n    });\n\n    return unsubscribe;\n  }, [isReady, onReady]);\n\n  return initialized;\n};\n\n/**\n * Result from the useGtmError hook.\n */\nexport interface GtmErrorState {\n  /** Whether any scripts failed to load */\n  hasError: boolean;\n  /** Array of failed script states (status 'failed' or 'partial') */\n  failedScripts: ScriptLoadState[];\n  /** Convenience getter for the first error message, if any */\n  errorMessage: string | null;\n}\n\n/**\n * Hook to capture GTM script load errors.\n * Returns reactive state that updates when scripts fail to load.\n *\n * @example\n * ```tsx\n * const { hasError, failedScripts, errorMessage } = useGtmError();\n *\n * if (hasError) {\n *   console.error('GTM failed to load:', errorMessage);\n *   // Optionally show fallback UI or retry logic\n * }\n * ```\n */\nexport const useGtmError = (): GtmErrorState => {\n  const { onReady } = useGtmContext();\n  const [errorState, setErrorState] = useState<GtmErrorState>({\n    hasError: false,\n    failedScripts: [],\n    errorMessage: null\n  });\n\n  useEffect(() => {\n    const unsubscribe = onReady((states) => {\n      const failedScripts = states.filter((s) => s.status === 'failed' || s.status === 'partial');\n\n      if (failedScripts.length > 0) {\n        const firstError = failedScripts.find((s) => s.error)?.error ?? null;\n        setErrorState({\n          hasError: true,\n          failedScripts,\n          errorMessage: firstError\n        });\n      }\n    });\n\n    return unsubscribe;\n  }, [onReady]);\n\n  return errorState;\n};\n\n/**\n * Props for GtmErrorBoundary component.\n */\nexport interface GtmErrorBoundaryProps {\n  children: ReactNode;\n  /** Fallback UI to render when an error occurs */\n  fallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode);\n  /** Callback invoked when an error is caught */\n  onError?: (error: Error, errorInfo: ErrorInfo) => void;\n  /** Whether to log errors to console (default: true in development) */\n  logErrors?: boolean;\n}\n\ninterface GtmErrorBoundaryState {\n  hasError: boolean;\n  error: Error | null;\n}\n\n/**\n * Error boundary component for GTM provider.\n * Catches errors during GTM initialization and renders a fallback UI.\n * Analytics and tracking will be disabled when an error occurs.\n */\nexport class GtmErrorBoundary extends Component<GtmErrorBoundaryProps, GtmErrorBoundaryState> {\n  constructor(props: GtmErrorBoundaryProps) {\n    super(props);\n    this.state = { hasError: false, error: null };\n  }\n\n  static getDerivedStateFromError(error: Error): GtmErrorBoundaryState {\n    return { hasError: true, error };\n  }\n\n  componentDidCatch(error: Error, errorInfo: ErrorInfo): void {\n    const { onError, logErrors = process.env.NODE_ENV !== 'production' } = this.props;\n\n    if (logErrors) {\n      console.error('[gtm-kit/react] Error caught by GtmErrorBoundary:', error);\n      console.error('[gtm-kit/react] Component stack:', errorInfo.componentStack);\n    }\n\n    if (onError) {\n      try {\n        onError(error, errorInfo);\n      } catch {\n        // Ignore callback errors\n      }\n    }\n  }\n\n  reset = (): void => {\n    this.setState({ hasError: false, error: null });\n  };\n\n  render(): ReactNode {\n    const { hasError, error } = this.state;\n    const { children, fallback } = this.props;\n\n    if (hasError && error) {\n      if (fallback === undefined) {\n        // Default: render children without GTM (silent fallback)\n        return children;\n      }\n\n      if (typeof fallback === 'function') {\n        return fallback(error, this.reset);\n      }\n\n      return fallback;\n    }\n\n    return children;\n  }\n}\n"]}

package/dist/index.d.cts

@@ -1,6 +1,24 @@
-import { PropsWithChildren, JSX } from 'react';
+import { PropsWithChildren, JSX, ReactNode, ErrorInfo, Component } from 'react';
 import { CreateGtmClientOptions, GtmClient, DataLayerValue, ConsentState, ConsentRegionOptions, ScriptLoadState } from '@jwiedeman/gtm-kit';
 
+/**
+ * Check if code is running in a server-side rendering environment.
+ * Returns true if window is undefined (Node.js/SSR), false in browser.
+ */
+declare const isSsr: () => boolean;
+/**
+ * Hook that returns false during SSR and initial hydration, then true after hydration completes.
+ * Use this to prevent hydration mismatches when rendering GTM-dependent content.
+ *
+ * @example
+ * ```tsx
+ * const isHydrated = useHydrated();
+ *
+ * // Safe: won't cause hydration mismatch
+ * return isHydrated ? <DynamicContent /> : <StaticPlaceholder />;
+ * ```
+ */
+declare const useHydrated: () => boolean;
 interface GtmProviderProps extends PropsWithChildren {
     config: CreateGtmClientOptions;
 }
@@ -9,6 +27,8 @@ interface GtmContextValue {
     push: (value: DataLayerValue) => void;
     setConsentDefaults: (state: ConsentState, options?: ConsentRegionOptions) => void;
     updateConsent: (state: ConsentState, options?: ConsentRegionOptions) => void;
+    /** Synchronously check if all GTM scripts have finished loading */
+    isReady: () => boolean;
     whenReady: () => Promise<ScriptLoadState[]>;
     onReady: (callback: (state: ScriptLoadState[]) => void) => () => void;
 }
@@ -16,11 +36,272 @@ interface GtmConsentApi {
     setConsentDefaults: (state: ConsentState, options?: ConsentRegionOptions) => void;
     updateConsent: (state: ConsentState, options?: ConsentRegionOptions) => void;
 }
+/**
+ * GTM Provider component that initializes Google Tag Manager for your React app.
+ *
+ * ## SSR/Hydration Behavior
+ *
+ * This provider is SSR-safe and handles hydration correctly:
+ * - **Server**: No GTM initialization occurs (no window/document access)
+ * - **Client Hydration**: GTM initializes only after hydration via useEffect
+ * - **No Hydration Mismatch**: Provider renders the same on server and client
+ *
+ * ## Usage with SSR Frameworks
+ *
+ * ```tsx
+ * // Next.js, Remix, etc.
+ * export default function App({ children }) {
+ *   return (
+ *     <GtmProvider config={{ containers: 'GTM-XXXXXX' }}>
+ *       {children}
+ *     </GtmProvider>
+ *   );
+ * }
+ * ```
+ *
+ * ## Preventing Hydration Mismatches
+ *
+ * If you render different content based on GTM state, use `useHydrated`:
+ *
+ * ```tsx
+ * const isHydrated = useHydrated();
+ * const isGtmReady = useGtmInitialized();
+ *
+ * // Safe: both server and client initially render the placeholder
+ * if (!isHydrated) return <Placeholder />;
+ * return isGtmReady ? <TrackedContent /> : <LoadingContent />;
+ * ```
+ */
 declare const GtmProvider: ({ config, children }: GtmProviderProps) => JSX.Element;
+/**
+ * Hook to access the full GTM context. Throws if used outside GtmProvider.
+ *
+ * For most use cases, prefer the specific hooks:
+ * - `useGtmPush()` - Push events to dataLayer
+ * - `useGtmConsent()` - Manage consent state
+ * - `useGtmClient()` - Access the raw GTM client
+ *
+ * @throws Error if called outside of GtmProvider
+ *
+ * @example
+ * ```tsx
+ * const { push, client, isReady, whenReady } = useGtm();
+ * ```
+ */
 declare const useGtm: () => GtmContextValue;
+/**
+ * Hook to check if GtmProvider is present without throwing.
+ *
+ * Useful for components that may be rendered before the provider mounts,
+ * or for optional GTM integration.
+ *
+ * @returns `true` if inside GtmProvider, `false` otherwise
+ *
+ * @example
+ * ```tsx
+ * const hasProvider = useIsGtmProviderPresent();
+ *
+ * const handleClick = () => {
+ *   if (hasProvider) {
+ *     // Safe to use GTM hooks
+ *   }
+ * };
+ * ```
+ */
+declare const useIsGtmProviderPresent: () => boolean;
+/**
+ * Hook to access the raw GTM client instance.
+ *
+ * @throws Error if called outside of GtmProvider
+ * @returns The GTM client instance
+ *
+ * @example
+ * ```tsx
+ * const client = useGtmClient();
+ *
+ * // Access low-level APIs
+ * const diagnostics = client.getDiagnostics();
+ * ```
+ */
 declare const useGtmClient: () => GtmClient;
+/**
+ * Hook to get the push function for sending events to the dataLayer.
+ *
+ * This is the most commonly used hook for tracking events.
+ *
+ * @throws Error if called outside of GtmProvider
+ * @returns Function to push values to the dataLayer
+ *
+ * @example
+ * ```tsx
+ * const push = useGtmPush();
+ *
+ * const handleAddToCart = (product) => {
+ *   push({
+ *     event: 'add_to_cart',
+ *     ecommerce: {
+ *       items: [{ item_id: product.id, item_name: product.name }]
+ *     }
+ *   });
+ * };
+ * ```
+ */
 declare const useGtmPush: () => ((value: DataLayerValue) => void);
+/**
+ * Hook to access consent management functions.
+ *
+ * @throws Error if called outside of GtmProvider
+ * @returns Object with `setConsentDefaults` and `updateConsent` functions
+ *
+ * @example
+ * ```tsx
+ * const { updateConsent } = useGtmConsent();
+ *
+ * const handleAcceptCookies = () => {
+ *   updateConsent({
+ *     ad_storage: 'granted',
+ *     analytics_storage: 'granted'
+ *   });
+ * };
+ * ```
+ */
 declare const useGtmConsent: () => GtmConsentApi;
+/**
+ * Hook that returns the `whenReady` promise function.
+ *
+ * **When to use**: When you need to await GTM script loading before taking an action.
+ * The returned function returns a Promise that resolves when scripts finish loading.
+ *
+ * **Comparison of GTM readiness hooks:**
+ * | Hook | Returns | Re-renders | Use Case |
+ * |------|---------|------------|----------|
+ * | `useGtmReady()` | `() => Promise` | No | Await in event handlers |
+ * | `useIsGtmReady()` | `() => boolean` | No | Synchronous checks in callbacks |
+ * | `useGtmInitialized()` | `boolean` | Yes | Conditional rendering |
+ *
+ * @returns Function that returns a Promise resolving to script load states
+ *
+ * @example
+ * ```tsx
+ * const whenReady = useGtmReady();
+ *
+ * const handleClick = async () => {
+ *   const states = await whenReady();
+ *   if (states.every(s => s.status === 'loaded')) {
+ *     // Safe to rely on GTM being fully loaded
+ *   }
+ * };
+ * ```
+ */
 declare const useGtmReady: () => (() => Promise<ScriptLoadState[]>);
+/**
+ * Hook that returns a function to synchronously check if GTM is ready.
+ *
+ * **When to use**: When you need to check readiness without triggering re-renders,
+ * typically in event handlers or callbacks.
+ *
+ * **Comparison of GTM readiness hooks:**
+ * | Hook | Returns | Re-renders | Use Case |
+ * |------|---------|------------|----------|
+ * | `useGtmReady()` | `() => Promise` | No | Await in event handlers |
+ * | `useIsGtmReady()` | `() => boolean` | No | Synchronous checks in callbacks |
+ * | `useGtmInitialized()` | `boolean` | Yes | Conditional rendering |
+ *
+ * @returns Function that returns `true` if scripts loaded, `false` if still loading
+ *
+ * @example
+ * ```tsx
+ * const checkReady = useIsGtmReady();
+ *
+ * const handleSubmit = () => {
+ *   if (checkReady()) {
+ *     // GTM is ready, proceed with tracking
+ *     push({ event: 'form_submit' });
+ *   }
+ * };
+ * ```
+ */
+declare const useIsGtmReady: () => (() => boolean);
+/**
+ * Reactive hook that returns `true` when GTM scripts have finished loading.
+ *
+ * **When to use**: When you need to conditionally render UI based on GTM readiness.
+ * This hook triggers a re-render when the state changes.
+ *
+ * **Comparison of GTM readiness hooks:**
+ * | Hook | Returns | Re-renders | Use Case |
+ * |------|---------|------------|----------|
+ * | `useGtmReady()` | `() => Promise` | No | Await in event handlers |
+ * | `useIsGtmReady()` | `() => boolean` | No | Synchronous checks in callbacks |
+ * | `useGtmInitialized()` | `boolean` | Yes | Conditional rendering |
+ *
+ * @returns `true` if GTM is initialized, `false` otherwise (reactive)
+ *
+ * @example
+ * ```tsx
+ * const isInitialized = useGtmInitialized();
+ *
+ * if (!isInitialized) {
+ *   return <LoadingSpinner />;
+ * }
+ *
+ * return <AnalyticsDashboard />;
+ * ```
+ */
+declare const useGtmInitialized: () => boolean;
+/**
+ * Result from the useGtmError hook.
+ */
+interface GtmErrorState {
+    /** Whether any scripts failed to load */
+    hasError: boolean;
+    /** Array of failed script states (status 'failed' or 'partial') */
+    failedScripts: ScriptLoadState[];
+    /** Convenience getter for the first error message, if any */
+    errorMessage: string | null;
+}
+/**
+ * Hook to capture GTM script load errors.
+ * Returns reactive state that updates when scripts fail to load.
+ *
+ * @example
+ * ```tsx
+ * const { hasError, failedScripts, errorMessage } = useGtmError();
+ *
+ * if (hasError) {
+ *   console.error('GTM failed to load:', errorMessage);
+ *   // Optionally show fallback UI or retry logic
+ * }
+ * ```
+ */
+declare const useGtmError: () => GtmErrorState;
+/**
+ * Props for GtmErrorBoundary component.
+ */
+interface GtmErrorBoundaryProps {
+    children: ReactNode;
+    /** Fallback UI to render when an error occurs */
+    fallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode);
+    /** Callback invoked when an error is caught */
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+    /** Whether to log errors to console (default: true in development) */
+    logErrors?: boolean;
+}
+interface GtmErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * Error boundary component for GTM provider.
+ * Catches errors during GTM initialization and renders a fallback UI.
+ * Analytics and tracking will be disabled when an error occurs.
+ */
+declare class GtmErrorBoundary extends Component<GtmErrorBoundaryProps, GtmErrorBoundaryState> {
+    constructor(props: GtmErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): GtmErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    reset: () => void;
+    render(): ReactNode;
+}
 
-export { GtmConsentApi, GtmContextValue, GtmProvider, GtmProviderProps, useGtm, useGtmClient, useGtmConsent, useGtmPush, useGtmReady };
+export { GtmConsentApi, GtmContextValue, GtmErrorBoundary, GtmErrorBoundaryProps, GtmErrorState, GtmProvider, GtmProviderProps, isSsr, useGtm, useGtmClient, useGtmConsent, useGtmError, useGtmInitialized, useGtmPush, useGtmReady, useHydrated, useIsGtmProviderPresent, useIsGtmReady };

package/dist/index.d.ts

@@ -1,6 +1,24 @@
-import { PropsWithChildren, JSX } from 'react';
+import { PropsWithChildren, JSX, ReactNode, ErrorInfo, Component } from 'react';
 import { CreateGtmClientOptions, GtmClient, DataLayerValue, ConsentState, ConsentRegionOptions, ScriptLoadState } from '@jwiedeman/gtm-kit';
 
+/**
+ * Check if code is running in a server-side rendering environment.
+ * Returns true if window is undefined (Node.js/SSR), false in browser.
+ */
+declare const isSsr: () => boolean;
+/**
+ * Hook that returns false during SSR and initial hydration, then true after hydration completes.
+ * Use this to prevent hydration mismatches when rendering GTM-dependent content.
+ *
+ * @example
+ * ```tsx
+ * const isHydrated = useHydrated();
+ *
+ * // Safe: won't cause hydration mismatch
+ * return isHydrated ? <DynamicContent /> : <StaticPlaceholder />;
+ * ```
+ */
+declare const useHydrated: () => boolean;
 interface GtmProviderProps extends PropsWithChildren {
     config: CreateGtmClientOptions;
 }
@@ -9,6 +27,8 @@ interface GtmContextValue {
     push: (value: DataLayerValue) => void;
     setConsentDefaults: (state: ConsentState, options?: ConsentRegionOptions) => void;
     updateConsent: (state: ConsentState, options?: ConsentRegionOptions) => void;
+    /** Synchronously check if all GTM scripts have finished loading */
+    isReady: () => boolean;
     whenReady: () => Promise<ScriptLoadState[]>;
     onReady: (callback: (state: ScriptLoadState[]) => void) => () => void;
 }
@@ -16,11 +36,272 @@ interface GtmConsentApi {
     setConsentDefaults: (state: ConsentState, options?: ConsentRegionOptions) => void;
     updateConsent: (state: ConsentState, options?: ConsentRegionOptions) => void;
 }
+/**
+ * GTM Provider component that initializes Google Tag Manager for your React app.
+ *
+ * ## SSR/Hydration Behavior
+ *
+ * This provider is SSR-safe and handles hydration correctly:
+ * - **Server**: No GTM initialization occurs (no window/document access)
+ * - **Client Hydration**: GTM initializes only after hydration via useEffect
+ * - **No Hydration Mismatch**: Provider renders the same on server and client
+ *
+ * ## Usage with SSR Frameworks
+ *
+ * ```tsx
+ * // Next.js, Remix, etc.
+ * export default function App({ children }) {
+ *   return (
+ *     <GtmProvider config={{ containers: 'GTM-XXXXXX' }}>
+ *       {children}
+ *     </GtmProvider>
+ *   );
+ * }
+ * ```
+ *
+ * ## Preventing Hydration Mismatches
+ *
+ * If you render different content based on GTM state, use `useHydrated`:
+ *
+ * ```tsx
+ * const isHydrated = useHydrated();
+ * const isGtmReady = useGtmInitialized();
+ *
+ * // Safe: both server and client initially render the placeholder
+ * if (!isHydrated) return <Placeholder />;
+ * return isGtmReady ? <TrackedContent /> : <LoadingContent />;
+ * ```
+ */
 declare const GtmProvider: ({ config, children }: GtmProviderProps) => JSX.Element;
+/**
+ * Hook to access the full GTM context. Throws if used outside GtmProvider.
+ *
+ * For most use cases, prefer the specific hooks:
+ * - `useGtmPush()` - Push events to dataLayer
+ * - `useGtmConsent()` - Manage consent state
+ * - `useGtmClient()` - Access the raw GTM client
+ *
+ * @throws Error if called outside of GtmProvider
+ *
+ * @example
+ * ```tsx
+ * const { push, client, isReady, whenReady } = useGtm();
+ * ```
+ */
 declare const useGtm: () => GtmContextValue;
+/**
+ * Hook to check if GtmProvider is present without throwing.
+ *
+ * Useful for components that may be rendered before the provider mounts,
+ * or for optional GTM integration.
+ *
+ * @returns `true` if inside GtmProvider, `false` otherwise
+ *
+ * @example
+ * ```tsx
+ * const hasProvider = useIsGtmProviderPresent();
+ *
+ * const handleClick = () => {
+ *   if (hasProvider) {
+ *     // Safe to use GTM hooks
+ *   }
+ * };
+ * ```
+ */
+declare const useIsGtmProviderPresent: () => boolean;
+/**
+ * Hook to access the raw GTM client instance.
+ *
+ * @throws Error if called outside of GtmProvider
+ * @returns The GTM client instance
+ *
+ * @example
+ * ```tsx
+ * const client = useGtmClient();
+ *
+ * // Access low-level APIs
+ * const diagnostics = client.getDiagnostics();
+ * ```
+ */
 declare const useGtmClient: () => GtmClient;
+/**
+ * Hook to get the push function for sending events to the dataLayer.
+ *
+ * This is the most commonly used hook for tracking events.
+ *
+ * @throws Error if called outside of GtmProvider
+ * @returns Function to push values to the dataLayer
+ *
+ * @example
+ * ```tsx
+ * const push = useGtmPush();
+ *
+ * const handleAddToCart = (product) => {
+ *   push({
+ *     event: 'add_to_cart',
+ *     ecommerce: {
+ *       items: [{ item_id: product.id, item_name: product.name }]
+ *     }
+ *   });
+ * };
+ * ```
+ */
 declare const useGtmPush: () => ((value: DataLayerValue) => void);
+/**
+ * Hook to access consent management functions.
+ *
+ * @throws Error if called outside of GtmProvider
+ * @returns Object with `setConsentDefaults` and `updateConsent` functions
+ *
+ * @example
+ * ```tsx
+ * const { updateConsent } = useGtmConsent();
+ *
+ * const handleAcceptCookies = () => {
+ *   updateConsent({
+ *     ad_storage: 'granted',
+ *     analytics_storage: 'granted'
+ *   });
+ * };
+ * ```
+ */
 declare const useGtmConsent: () => GtmConsentApi;
+/**
+ * Hook that returns the `whenReady` promise function.
+ *
+ * **When to use**: When you need to await GTM script loading before taking an action.
+ * The returned function returns a Promise that resolves when scripts finish loading.
+ *
+ * **Comparison of GTM readiness hooks:**
+ * | Hook | Returns | Re-renders | Use Case |
+ * |------|---------|------------|----------|
+ * | `useGtmReady()` | `() => Promise` | No | Await in event handlers |
+ * | `useIsGtmReady()` | `() => boolean` | No | Synchronous checks in callbacks |
+ * | `useGtmInitialized()` | `boolean` | Yes | Conditional rendering |
+ *
+ * @returns Function that returns a Promise resolving to script load states
+ *
+ * @example
+ * ```tsx
+ * const whenReady = useGtmReady();
+ *
+ * const handleClick = async () => {
+ *   const states = await whenReady();
+ *   if (states.every(s => s.status === 'loaded')) {
+ *     // Safe to rely on GTM being fully loaded
+ *   }
+ * };
+ * ```
+ */
 declare const useGtmReady: () => (() => Promise<ScriptLoadState[]>);
+/**
+ * Hook that returns a function to synchronously check if GTM is ready.
+ *
+ * **When to use**: When you need to check readiness without triggering re-renders,
+ * typically in event handlers or callbacks.
+ *
+ * **Comparison of GTM readiness hooks:**
+ * | Hook | Returns | Re-renders | Use Case |
+ * |------|---------|------------|----------|
+ * | `useGtmReady()` | `() => Promise` | No | Await in event handlers |
+ * | `useIsGtmReady()` | `() => boolean` | No | Synchronous checks in callbacks |
+ * | `useGtmInitialized()` | `boolean` | Yes | Conditional rendering |
+ *
+ * @returns Function that returns `true` if scripts loaded, `false` if still loading
+ *
+ * @example
+ * ```tsx
+ * const checkReady = useIsGtmReady();
+ *
+ * const handleSubmit = () => {
+ *   if (checkReady()) {
+ *     // GTM is ready, proceed with tracking
+ *     push({ event: 'form_submit' });
+ *   }
+ * };
+ * ```
+ */
+declare const useIsGtmReady: () => (() => boolean);
+/**
+ * Reactive hook that returns `true` when GTM scripts have finished loading.
+ *
+ * **When to use**: When you need to conditionally render UI based on GTM readiness.
+ * This hook triggers a re-render when the state changes.
+ *
+ * **Comparison of GTM readiness hooks:**
+ * | Hook | Returns | Re-renders | Use Case |
+ * |------|---------|------------|----------|
+ * | `useGtmReady()` | `() => Promise` | No | Await in event handlers |
+ * | `useIsGtmReady()` | `() => boolean` | No | Synchronous checks in callbacks |
+ * | `useGtmInitialized()` | `boolean` | Yes | Conditional rendering |
+ *
+ * @returns `true` if GTM is initialized, `false` otherwise (reactive)
+ *
+ * @example
+ * ```tsx
+ * const isInitialized = useGtmInitialized();
+ *
+ * if (!isInitialized) {
+ *   return <LoadingSpinner />;
+ * }
+ *
+ * return <AnalyticsDashboard />;
+ * ```
+ */
+declare const useGtmInitialized: () => boolean;
+/**
+ * Result from the useGtmError hook.
+ */
+interface GtmErrorState {
+    /** Whether any scripts failed to load */
+    hasError: boolean;
+    /** Array of failed script states (status 'failed' or 'partial') */
+    failedScripts: ScriptLoadState[];
+    /** Convenience getter for the first error message, if any */
+    errorMessage: string | null;
+}
+/**
+ * Hook to capture GTM script load errors.
+ * Returns reactive state that updates when scripts fail to load.
+ *
+ * @example
+ * ```tsx
+ * const { hasError, failedScripts, errorMessage } = useGtmError();
+ *
+ * if (hasError) {
+ *   console.error('GTM failed to load:', errorMessage);
+ *   // Optionally show fallback UI or retry logic
+ * }
+ * ```
+ */
+declare const useGtmError: () => GtmErrorState;
+/**
+ * Props for GtmErrorBoundary component.
+ */
+interface GtmErrorBoundaryProps {
+    children: ReactNode;
+    /** Fallback UI to render when an error occurs */
+    fallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode);
+    /** Callback invoked when an error is caught */
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+    /** Whether to log errors to console (default: true in development) */
+    logErrors?: boolean;
+}
+interface GtmErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * Error boundary component for GTM provider.
+ * Catches errors during GTM initialization and renders a fallback UI.
+ * Analytics and tracking will be disabled when an error occurs.
+ */
+declare class GtmErrorBoundary extends Component<GtmErrorBoundaryProps, GtmErrorBoundaryState> {
+    constructor(props: GtmErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): GtmErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    reset: () => void;
+    render(): ReactNode;
+}
 
-export { GtmConsentApi, GtmContextValue, GtmProvider, GtmProviderProps, useGtm, useGtmClient, useGtmConsent, useGtmPush, useGtmReady };
+export { GtmConsentApi, GtmContextValue, GtmErrorBoundary, GtmErrorBoundaryProps, GtmErrorState, GtmProvider, GtmProviderProps, isSsr, useGtm, useGtmClient, useGtmConsent, useGtmError, useGtmInitialized, useGtmPush, useGtmReady, useHydrated, useIsGtmProviderPresent, useIsGtmReady };

package/dist/index.js

@@ -1,9 +1,229 @@
-import { createContext, useEffect, useMemo, useRef, useContext } from 'react';
+import { createContext, useSyncExternalStore, useContext, useEffect, useMemo, useState, Component, useRef } from 'react';
 import { createGtmClient } from '@jwiedeman/gtm-kit';
-import { jsx } from 'react/jsx-runtime';
+import { jsx, Fragment } from 'react/jsx-runtime';
 
-var u=createContext(null),d=(t,n)=>{process.env.NODE_ENV!=="production"&&t!==n&&console.warn("[react-gtm-kit] GtmProvider received new configuration; reconfiguration after mount is not supported. The initial configuration will continue to be used.");},G=t=>{let n=useRef(),e=useRef();return n.current?e.current&&d(e.current,t):(n.current=createGtmClient(t),e.current=t),n.current},f=({config:t,children:n})=>{let e=G(t);useEffect(()=>(e.init(),()=>{e.teardown();}),[e]);let p=useMemo(()=>({client:e,push:o=>e.push(o),setConsentDefaults:(o,r)=>e.setConsentDefaults(o,r),updateConsent:(o,r)=>e.updateConsent(o,r),whenReady:()=>e.whenReady(),onReady:o=>e.onReady(o)}),[e]);return jsx(u.Provider,{value:p,children:n})},s=()=>{let t=useContext(u);if(!t)throw new Error("useGtm hook must be used within a GtmProvider instance.");return t},v=s,x=()=>s().client,y=()=>s().push,h=()=>{let{setConsentDefaults:t,updateConsent:n}=s();return useMemo(()=>({setConsentDefaults:t,updateConsent:n}),[t,n])},P=()=>{let{whenReady:t}=s();return t};
+// src/provider.tsx
+var isSsr = () => typeof window === "undefined";
+var useHydrated = () => {
+  return useSyncExternalStore(
+    // Subscribe function (no-op, state never changes after hydration)
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    () => () => {
+    },
+    // getSnapshot (client): always true after first render
+    () => true,
+    // getServerSnapshot (server): always false
+    () => false
+  );
+};
+var GtmContext = createContext(null);
+var warnOnNestedProvider = () => {
+  if (process.env.NODE_ENV !== "production") {
+    console.warn(
+      "[gtm-kit/react] Nested GtmProvider detected. You should only have one GtmProvider at the root of your app. The nested provider will be ignored."
+    );
+  }
+};
+var warnOnConfigChange = (initialConfig, nextConfig) => {
+  if (process.env.NODE_ENV !== "production" && initialConfig !== nextConfig) {
+    console.warn(
+      "[gtm-kit/react] GtmProvider received new configuration; reconfiguration after mount is not supported. The initial configuration will continue to be used."
+    );
+  }
+};
+var extractContainerIds = (config) => {
+  const containers = config.containers;
+  const containerArray = Array.isArray(containers) ? containers : [containers];
+  return containerArray.map((container) => {
+    if (typeof container === "string") {
+      return container;
+    }
+    return container.id;
+  });
+};
+var warnOnOrphanedSsrScripts = (configuredContainers) => {
+  if (process.env.NODE_ENV !== "production" && typeof document !== "undefined") {
+    const gtmScripts = document.querySelectorAll('script[src*="googletagmanager.com/gtm.js"]');
+    gtmScripts.forEach((script) => {
+      const src = script.src;
+      const idMatch = src.match(/[?&]id=([^&]+)/);
+      const scriptContainerId = idMatch == null ? void 0 : idMatch[1];
+      if (scriptContainerId && !configuredContainers.includes(scriptContainerId)) {
+        console.warn(
+          `[gtm-kit/react] Found pre-rendered GTM script for container "${scriptContainerId}" that is not configured in GtmProvider. This may indicate a hydration mismatch between SSR and client-side rendering. Configure GtmProvider with containers: "${scriptContainerId}" to properly hydrate.`
+        );
+      }
+    });
+    const gtmNoscripts = document.querySelectorAll('noscript iframe[src*="googletagmanager.com/ns.html"]');
+    gtmNoscripts.forEach((iframe) => {
+      const src = iframe.src;
+      const idMatch = src.match(/[?&]id=([^&]+)/);
+      const iframeContainerId = idMatch == null ? void 0 : idMatch[1];
+      if (iframeContainerId && !configuredContainers.includes(iframeContainerId)) {
+        console.warn(
+          `[gtm-kit/react] Found pre-rendered GTM noscript iframe for container "${iframeContainerId}" that is not configured in GtmProvider. If you pre-render noscript fallbacks on the server, ensure your GtmProvider has the same container ID.`
+        );
+      }
+    });
+  }
+};
+var useStableClient = (config) => {
+  const clientRef = useRef();
+  const configRef = useRef();
+  if (!clientRef.current) {
+    clientRef.current = createGtmClient(config);
+    configRef.current = config;
+  } else if (configRef.current) {
+    warnOnConfigChange(configRef.current, config);
+  }
+  return clientRef.current;
+};
+var GtmProvider = ({ config, children }) => {
+  const existingContext = useContext(GtmContext);
+  useEffect(() => {
+    if (existingContext) {
+      warnOnNestedProvider();
+    }
+  }, [existingContext]);
+  if (existingContext) {
+    return /* @__PURE__ */ jsx(Fragment, { children });
+  }
+  return /* @__PURE__ */ jsx(GtmProviderInner, { config, children });
+};
+var GtmProviderInner = ({ config, children }) => {
+  const client = useStableClient(config);
+  useEffect(() => {
+    warnOnOrphanedSsrScripts(extractContainerIds(config));
+    client.init();
+    return () => {
+      client.teardown();
+    };
+  }, [client, config]);
+  const value = useMemo(
+    () => ({
+      client,
+      push: (value2) => client.push(value2),
+      setConsentDefaults: (state, options) => client.setConsentDefaults(state, options),
+      updateConsent: (state, options) => client.updateConsent(state, options),
+      isReady: () => client.isReady(),
+      whenReady: () => client.whenReady(),
+      onReady: (callback) => client.onReady(callback)
+    }),
+    [client]
+  );
+  return /* @__PURE__ */ jsx(GtmContext.Provider, { value, children });
+};
+var useGtmContext = () => {
+  const context = useContext(GtmContext);
+  if (!context) {
+    throw new Error(
+      '[gtm-kit/react] useGtm() was called outside of a GtmProvider. Make sure to wrap your app with <GtmProvider config={{ containers: "GTM-XXXXXX" }}>.'
+    );
+  }
+  return context;
+};
+var useGtm = useGtmContext;
+var useIsGtmProviderPresent = () => {
+  const context = useContext(GtmContext);
+  return context !== null;
+};
+var useGtmClient = () => {
+  return useGtmContext().client;
+};
+var useGtmPush = () => {
+  return useGtmContext().push;
+};
+var useGtmConsent = () => {
+  const { setConsentDefaults, updateConsent } = useGtmContext();
+  return useMemo(() => ({ setConsentDefaults, updateConsent }), [setConsentDefaults, updateConsent]);
+};
+var useGtmReady = () => {
+  const { whenReady } = useGtmContext();
+  return whenReady;
+};
+var useIsGtmReady = () => {
+  const { isReady } = useGtmContext();
+  return isReady;
+};
+var useGtmInitialized = () => {
+  const { isReady, onReady } = useGtmContext();
+  const [initialized, setInitialized] = useState(() => isReady());
+  useEffect(() => {
+    if (isReady()) {
+      setInitialized(true);
+      return;
+    }
+    const unsubscribe = onReady(() => {
+      setInitialized(true);
+    });
+    return unsubscribe;
+  }, [isReady, onReady]);
+  return initialized;
+};
+var useGtmError = () => {
+  const { onReady } = useGtmContext();
+  const [errorState, setErrorState] = useState({
+    hasError: false,
+    failedScripts: [],
+    errorMessage: null
+  });
+  useEffect(() => {
+    const unsubscribe = onReady((states) => {
+      var _a, _b;
+      const failedScripts = states.filter((s) => s.status === "failed" || s.status === "partial");
+      if (failedScripts.length > 0) {
+        const firstError = (_b = (_a = failedScripts.find((s) => s.error)) == null ? void 0 : _a.error) != null ? _b : null;
+        setErrorState({
+          hasError: true,
+          failedScripts,
+          errorMessage: firstError
+        });
+      }
+    });
+    return unsubscribe;
+  }, [onReady]);
+  return errorState;
+};
+var GtmErrorBoundary = class extends Component {
+  constructor(props) {
+    super(props);
+    this.reset = () => {
+      this.setState({ hasError: false, error: null });
+    };
+    this.state = { hasError: false, error: null };
+  }
+  static getDerivedStateFromError(error) {
+    return { hasError: true, error };
+  }
+  componentDidCatch(error, errorInfo) {
+    const { onError, logErrors = process.env.NODE_ENV !== "production" } = this.props;
+    if (logErrors) {
+      console.error("[gtm-kit/react] Error caught by GtmErrorBoundary:", error);
+      console.error("[gtm-kit/react] Component stack:", errorInfo.componentStack);
+    }
+    if (onError) {
+      try {
+        onError(error, errorInfo);
+      } catch (e) {
+      }
+    }
+  }
+  render() {
+    const { hasError, error } = this.state;
+    const { children, fallback } = this.props;
+    if (hasError && error) {
+      if (fallback === void 0) {
+        return children;
+      }
+      if (typeof fallback === "function") {
+        return fallback(error, this.reset);
+      }
+      return fallback;
+    }
+    return children;
+  }
+};
 
-export { f as GtmProvider, v as useGtm, x as useGtmClient, h as useGtmConsent, y as useGtmPush, P as useGtmReady };
+export { GtmErrorBoundary, GtmProvider, isSsr, useGtm, useGtmClient, useGtmConsent, useGtmError, useGtmInitialized, useGtmPush, useGtmReady, useHydrated, useIsGtmProviderPresent, useIsGtmReady };
 //# sourceMappingURL=out.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/provider.tsx"],"names":["createContext","useContext","useEffect","useMemo","useRef","createGtmClient","jsx","GtmContext","warnOnConfigChange","initialConfig","nextConfig","useStableClient","config","clientRef","configRef","GtmProvider","children","client","value","state","options","callback","useGtmContext","context","useGtm","useGtmClient","useGtmPush","useGtmConsent","setConsentDefaults","updateConsent","useGtmReady","whenReady"],"mappings":"AAAA,OAAS,iBAAAA,EAAe,cAAAC,EAAY,aAAAC,EAAW,WAAAC,EAAS,UAAAC,MAAgD,QACxG,OACE,mBAAAC,MAOK,qBAmEE,cAAAC,MAAA,oBA/CT,IAAMC,EAAaP,EAAsC,IAAI,EAEvDQ,EAAqB,CAACC,EAAuCC,IAA6C,CAC1G,QAAQ,IAAI,WAAa,cAAgBD,IAAkBC,GAC7D,QAAQ,KACN,2JAEF,CAEJ,EAEMC,EAAmBC,GAA8C,CACrE,IAAMC,EAAYT,EAAkB,EAC9BU,EAAYV,EAA+B,EAEjD,OAAKS,EAAU,QAGJC,EAAU,SACnBN,EAAmBM,EAAU,QAASF,CAAM,GAH5CC,EAAU,QAAUR,EAAgBO,CAAM,EAC1CE,EAAU,QAAUF,GAKfC,EAAU,OACnB,EAEaE,EAAc,CAAC,CAAE,OAAAH,EAAQ,SAAAI,CAAS,IAAqC,CAClF,IAAMC,EAASN,EAAgBC,CAAM,EAErCV,EAAU,KACRe,EAAO,KAAK,EACL,IAAM,CACXA,EAAO,SAAS,CAClB,GACC,CAACA,CAAM,CAAC,EAEX,IAAMC,EAAQf,EACZ,KAAO,CACL,OAAAc,EACA,KAAOC,GAAUD,EAAO,KAAKC,CAAK,EAClC,mBAAoB,CAACC,EAAOC,IAAYH,EAAO,mBAAmBE,EAAOC,CAAO,EAChF,cAAe,CAACD,EAAOC,IAAYH,EAAO,cAAcE,EAAOC,CAAO,EACtE,UAAW,IAAMH,EAAO,UAAU,EAClC,QAAUI,GAAaJ,EAAO,QAAQI,CAAQ,CAChD,GACA,CAACJ,CAAM,CACT,EAEA,OAAOX,EAACC,EAAW,SAAX,CAAoB,MAAOW,EAAQ,SAAAF,EAAS,CACtD,EAEMM,EAAgB,IAAuB,CAC3C,IAAMC,EAAUtB,EAAWM,CAAU,EACrC,GAAI,CAACgB,EACH,MAAM,IAAI,MAAM,yDAAyD,EAE3E,OAAOA,CACT,EAEaC,EAASF,EAETG,EAAe,IACnBH,EAAc,EAAE,OAGZI,EAAa,IACjBJ,EAAc,EAAE,KAGZK,EAAgB,IAAqB,CAChD,GAAM,CAAE,mBAAAC,EAAoB,cAAAC,CAAc,EAAIP,EAAc,EAC5D,OAAOnB,EAAQ,KAAO,CAAE,mBAAAyB,EAAoB,cAAAC,CAAc,GAAI,CAACD,EAAoBC,CAAa,CAAC,CACnG,EAEaC,EAAc,IAA0C,CACnE,GAAM,CAAE,UAAAC,CAAU,EAAIT,EAAc,EACpC,OAAOS,CACT","sourcesContent":["import { createContext, useContext, useEffect, useMemo, useRef, type PropsWithChildren, type JSX } from 'react';\nimport {\n  createGtmClient,\n  type ConsentRegionOptions,\n  type ConsentState,\n  type CreateGtmClientOptions,\n  type DataLayerValue,\n  type GtmClient,\n  type ScriptLoadState\n} from '@jwiedeman/gtm-kit';\n\nexport interface GtmProviderProps extends PropsWithChildren {\n  config: CreateGtmClientOptions;\n}\n\nexport interface GtmContextValue {\n  client: GtmClient;\n  push: (value: DataLayerValue) => void;\n  setConsentDefaults: (state: ConsentState, options?: ConsentRegionOptions) => void;\n  updateConsent: (state: ConsentState, options?: ConsentRegionOptions) => void;\n  whenReady: () => Promise<ScriptLoadState[]>;\n  onReady: (callback: (state: ScriptLoadState[]) => void) => () => void;\n}\n\nexport interface GtmConsentApi {\n  setConsentDefaults: (state: ConsentState, options?: ConsentRegionOptions) => void;\n  updateConsent: (state: ConsentState, options?: ConsentRegionOptions) => void;\n}\n\nconst GtmContext = createContext<GtmContextValue | null>(null);\n\nconst warnOnConfigChange = (initialConfig: CreateGtmClientOptions, nextConfig: CreateGtmClientOptions): void => {\n  if (process.env.NODE_ENV !== 'production' && initialConfig !== nextConfig) {\n    console.warn(\n      '[react-gtm-kit] GtmProvider received new configuration; reconfiguration after mount is not supported. ' +\n        'The initial configuration will continue to be used.'\n    );\n  }\n};\n\nconst useStableClient = (config: CreateGtmClientOptions): GtmClient => {\n  const clientRef = useRef<GtmClient>();\n  const configRef = useRef<CreateGtmClientOptions>();\n\n  if (!clientRef.current) {\n    clientRef.current = createGtmClient(config);\n    configRef.current = config;\n  } else if (configRef.current) {\n    warnOnConfigChange(configRef.current, config);\n  }\n\n  return clientRef.current!;\n};\n\nexport const GtmProvider = ({ config, children }: GtmProviderProps): JSX.Element => {\n  const client = useStableClient(config);\n\n  useEffect(() => {\n    client.init();\n    return () => {\n      client.teardown();\n    };\n  }, [client]);\n\n  const value = useMemo<GtmContextValue>(\n    () => ({\n      client,\n      push: (value) => client.push(value),\n      setConsentDefaults: (state, options) => client.setConsentDefaults(state, options),\n      updateConsent: (state, options) => client.updateConsent(state, options),\n      whenReady: () => client.whenReady(),\n      onReady: (callback) => client.onReady(callback)\n    }),\n    [client]\n  );\n\n  return <GtmContext.Provider value={value}>{children}</GtmContext.Provider>;\n};\n\nconst useGtmContext = (): GtmContextValue => {\n  const context = useContext(GtmContext);\n  if (!context) {\n    throw new Error('useGtm hook must be used within a GtmProvider instance.');\n  }\n  return context;\n};\n\nexport const useGtm = useGtmContext;\n\nexport const useGtmClient = (): GtmClient => {\n  return useGtmContext().client;\n};\n\nexport const useGtmPush = (): ((value: DataLayerValue) => void) => {\n  return useGtmContext().push;\n};\n\nexport const useGtmConsent = (): GtmConsentApi => {\n  const { setConsentDefaults, updateConsent } = useGtmContext();\n  return useMemo(() => ({ setConsentDefaults, updateConsent }), [setConsentDefaults, updateConsent]);\n};\n\nexport const useGtmReady = (): (() => Promise<ScriptLoadState[]>) => {\n  const { whenReady } = useGtmContext();\n  return whenReady;\n};\n"]}
+{"version":3,"sources":["../src/provider.tsx"],"names":["value"],"mappings":"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","sourcesContent":["import {\n  Component,\n  createContext,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\n  useSyncExternalStore,\n  type ErrorInfo,\n  type PropsWithChildren,\n  type ReactNode,\n  type JSX\n} from 'react';\nimport {\n  createGtmClient,\n  type ConsentRegionOptions,\n  type ConsentState,\n  type CreateGtmClientOptions,\n  type DataLayerValue,\n  type GtmClient,\n  type ScriptLoadState\n} from '@jwiedeman/gtm-kit';\n\n/**\n * Check if code is running in a server-side rendering environment.\n * Returns true if window is undefined (Node.js/SSR), false in browser.\n */\nexport const isSsr = (): boolean => typeof window === 'undefined';\n\n/**\n * Hook that returns false during SSR and initial hydration, then true after hydration completes.\n * Use this to prevent hydration mismatches when rendering GTM-dependent content.\n *\n * @example\n * ```tsx\n * const isHydrated = useHydrated();\n *\n * // Safe: won't cause hydration mismatch\n * return isHydrated ? <DynamicContent /> : <StaticPlaceholder />;\n * ```\n */\nexport const useHydrated = (): boolean => {\n  // useSyncExternalStore with getServerSnapshot ensures consistent SSR/hydration\n  return useSyncExternalStore(\n    // Subscribe function (no-op, state never changes after hydration)\n    // eslint-disable-next-line @typescript-eslint/no-empty-function\n    () => () => {},\n    // getSnapshot (client): always true after first render\n    () => true,\n    // getServerSnapshot (server): always false\n    () => false\n  );\n};\n\nexport interface GtmProviderProps extends PropsWithChildren {\n  config: CreateGtmClientOptions;\n}\n\nexport interface GtmContextValue {\n  client: GtmClient;\n  push: (value: DataLayerValue) => void;\n  setConsentDefaults: (state: ConsentState, options?: ConsentRegionOptions) => void;\n  updateConsent: (state: ConsentState, options?: ConsentRegionOptions) => void;\n  /** Synchronously check if all GTM scripts have finished loading */\n  isReady: () => boolean;\n  whenReady: () => Promise<ScriptLoadState[]>;\n  onReady: (callback: (state: ScriptLoadState[]) => void) => () => void;\n}\n\nexport interface GtmConsentApi {\n  setConsentDefaults: (state: ConsentState, options?: ConsentRegionOptions) => void;\n  updateConsent: (state: ConsentState, options?: ConsentRegionOptions) => void;\n}\n\nconst GtmContext = createContext<GtmContextValue | null>(null);\n\nconst warnOnNestedProvider = (): void => {\n  if (process.env.NODE_ENV !== 'production') {\n    console.warn(\n      '[gtm-kit/react] Nested GtmProvider detected. You should only have one GtmProvider at the root of your app. ' +\n        'The nested provider will be ignored.'\n    );\n  }\n};\n\nconst warnOnConfigChange = (initialConfig: CreateGtmClientOptions, nextConfig: CreateGtmClientOptions): void => {\n  if (process.env.NODE_ENV !== 'production' && initialConfig !== nextConfig) {\n    console.warn(\n      '[gtm-kit/react] GtmProvider received new configuration; reconfiguration after mount is not supported. ' +\n        'The initial configuration will continue to be used.'\n    );\n  }\n};\n\n/**\n * Extracts container IDs from the provider config.\n */\nconst extractContainerIds = (config: CreateGtmClientOptions): string[] => {\n  const containers = config.containers;\n  const containerArray = Array.isArray(containers) ? containers : [containers];\n\n  return containerArray.map((container) => {\n    if (typeof container === 'string') {\n      return container;\n    }\n    return container.id;\n  });\n};\n\n/**\n * Warns in development if there are orphaned SSR-rendered GTM scripts without a matching client.\n * This helps developers identify hydration mismatches where GTM was rendered on the server\n * but the GtmProvider config doesn't match or is missing.\n */\nconst warnOnOrphanedSsrScripts = (configuredContainers: string[]): void => {\n  if (process.env.NODE_ENV !== 'production' && typeof document !== 'undefined') {\n    // Find all GTM scripts on the page\n    const gtmScripts = document.querySelectorAll('script[src*=\"googletagmanager.com/gtm.js\"]');\n\n    gtmScripts.forEach((script) => {\n      const src = (script as HTMLScriptElement).src;\n      const idMatch = src.match(/[?&]id=([^&]+)/);\n      const scriptContainerId = idMatch?.[1];\n\n      if (scriptContainerId && !configuredContainers.includes(scriptContainerId)) {\n        console.warn(\n          `[gtm-kit/react] Found pre-rendered GTM script for container \"${scriptContainerId}\" that is not configured in GtmProvider. ` +\n            'This may indicate a hydration mismatch between SSR and client-side rendering. ' +\n            `Configure GtmProvider with containers: \"${scriptContainerId}\" to properly hydrate.`\n        );\n      }\n    });\n\n    // Also check for noscript iframes\n    const gtmNoscripts = document.querySelectorAll('noscript iframe[src*=\"googletagmanager.com/ns.html\"]');\n    gtmNoscripts.forEach((iframe) => {\n      const src = (iframe as HTMLIFrameElement).src;\n      const idMatch = src.match(/[?&]id=([^&]+)/);\n      const iframeContainerId = idMatch?.[1];\n\n      if (iframeContainerId && !configuredContainers.includes(iframeContainerId)) {\n        console.warn(\n          `[gtm-kit/react] Found pre-rendered GTM noscript iframe for container \"${iframeContainerId}\" that is not configured in GtmProvider. ` +\n            'If you pre-render noscript fallbacks on the server, ensure your GtmProvider has the same container ID.'\n        );\n      }\n    });\n  }\n};\n\nconst useStableClient = (config: CreateGtmClientOptions): GtmClient => {\n  const clientRef = useRef<GtmClient>();\n  const configRef = useRef<CreateGtmClientOptions>();\n\n  if (!clientRef.current) {\n    clientRef.current = createGtmClient(config);\n    configRef.current = config;\n  } else if (configRef.current) {\n    warnOnConfigChange(configRef.current, config);\n  }\n\n  return clientRef.current!;\n};\n\n/**\n * GTM Provider component that initializes Google Tag Manager for your React app.\n *\n * ## SSR/Hydration Behavior\n *\n * This provider is SSR-safe and handles hydration correctly:\n * - **Server**: No GTM initialization occurs (no window/document access)\n * - **Client Hydration**: GTM initializes only after hydration via useEffect\n * - **No Hydration Mismatch**: Provider renders the same on server and client\n *\n * ## Usage with SSR Frameworks\n *\n * ```tsx\n * // Next.js, Remix, etc.\n * export default function App({ children }) {\n *   return (\n *     <GtmProvider config={{ containers: 'GTM-XXXXXX' }}>\n *       {children}\n *     </GtmProvider>\n *   );\n * }\n * ```\n *\n * ## Preventing Hydration Mismatches\n *\n * If you render different content based on GTM state, use `useHydrated`:\n *\n * ```tsx\n * const isHydrated = useHydrated();\n * const isGtmReady = useGtmInitialized();\n *\n * // Safe: both server and client initially render the placeholder\n * if (!isHydrated) return <Placeholder />;\n * return isGtmReady ? <TrackedContent /> : <LoadingContent />;\n * ```\n */\nexport const GtmProvider = ({ config, children }: GtmProviderProps): JSX.Element => {\n  const existingContext = useContext(GtmContext);\n\n  // Warn if we're inside another GtmProvider (nested providers)\n  useEffect(() => {\n    if (existingContext) {\n      warnOnNestedProvider();\n    }\n  }, [existingContext]);\n\n  // If nested, just pass through children without creating a new context\n  if (existingContext) {\n    return <>{children}</>;\n  }\n\n  return <GtmProviderInner config={config}>{children}</GtmProviderInner>;\n};\n\nconst GtmProviderInner = ({ config, children }: GtmProviderProps): JSX.Element => {\n  const client = useStableClient(config);\n\n  useEffect(() => {\n    // Check for orphaned SSR scripts before initializing\n    warnOnOrphanedSsrScripts(extractContainerIds(config));\n\n    client.init();\n    return () => {\n      client.teardown();\n    };\n  }, [client, config]);\n\n  const value = useMemo<GtmContextValue>(\n    () => ({\n      client,\n      push: (value) => client.push(value),\n      setConsentDefaults: (state, options) => client.setConsentDefaults(state, options),\n      updateConsent: (state, options) => client.updateConsent(state, options),\n      isReady: () => client.isReady(),\n      whenReady: () => client.whenReady(),\n      onReady: (callback) => client.onReady(callback)\n    }),\n    [client]\n  );\n\n  return <GtmContext.Provider value={value}>{children}</GtmContext.Provider>;\n};\n\nconst useGtmContext = (): GtmContextValue => {\n  const context = useContext(GtmContext);\n  if (!context) {\n    throw new Error(\n      '[gtm-kit/react] useGtm() was called outside of a GtmProvider. ' +\n        'Make sure to wrap your app with <GtmProvider config={{ containers: \"GTM-XXXXXX\" }}>.'\n    );\n  }\n  return context;\n};\n\n/**\n * Hook to access the full GTM context. Throws if used outside GtmProvider.\n *\n * For most use cases, prefer the specific hooks:\n * - `useGtmPush()` - Push events to dataLayer\n * - `useGtmConsent()` - Manage consent state\n * - `useGtmClient()` - Access the raw GTM client\n *\n * @throws Error if called outside of GtmProvider\n *\n * @example\n * ```tsx\n * const { push, client, isReady, whenReady } = useGtm();\n * ```\n */\nexport const useGtm = useGtmContext;\n\n/**\n * Hook to check if GtmProvider is present without throwing.\n *\n * Useful for components that may be rendered before the provider mounts,\n * or for optional GTM integration.\n *\n * @returns `true` if inside GtmProvider, `false` otherwise\n *\n * @example\n * ```tsx\n * const hasProvider = useIsGtmProviderPresent();\n *\n * const handleClick = () => {\n *   if (hasProvider) {\n *     // Safe to use GTM hooks\n *   }\n * };\n * ```\n */\nexport const useIsGtmProviderPresent = (): boolean => {\n  const context = useContext(GtmContext);\n  return context !== null;\n};\n\n/**\n * Hook to access the raw GTM client instance.\n *\n * @throws Error if called outside of GtmProvider\n * @returns The GTM client instance\n *\n * @example\n * ```tsx\n * const client = useGtmClient();\n *\n * // Access low-level APIs\n * const diagnostics = client.getDiagnostics();\n * ```\n */\nexport const useGtmClient = (): GtmClient => {\n  return useGtmContext().client;\n};\n\n/**\n * Hook to get the push function for sending events to the dataLayer.\n *\n * This is the most commonly used hook for tracking events.\n *\n * @throws Error if called outside of GtmProvider\n * @returns Function to push values to the dataLayer\n *\n * @example\n * ```tsx\n * const push = useGtmPush();\n *\n * const handleAddToCart = (product) => {\n *   push({\n *     event: 'add_to_cart',\n *     ecommerce: {\n *       items: [{ item_id: product.id, item_name: product.name }]\n *     }\n *   });\n * };\n * ```\n */\nexport const useGtmPush = (): ((value: DataLayerValue) => void) => {\n  return useGtmContext().push;\n};\n\n/**\n * Hook to access consent management functions.\n *\n * @throws Error if called outside of GtmProvider\n * @returns Object with `setConsentDefaults` and `updateConsent` functions\n *\n * @example\n * ```tsx\n * const { updateConsent } = useGtmConsent();\n *\n * const handleAcceptCookies = () => {\n *   updateConsent({\n *     ad_storage: 'granted',\n *     analytics_storage: 'granted'\n *   });\n * };\n * ```\n */\nexport const useGtmConsent = (): GtmConsentApi => {\n  const { setConsentDefaults, updateConsent } = useGtmContext();\n  return useMemo(() => ({ setConsentDefaults, updateConsent }), [setConsentDefaults, updateConsent]);\n};\n\n/**\n * Hook that returns the `whenReady` promise function.\n *\n * **When to use**: When you need to await GTM script loading before taking an action.\n * The returned function returns a Promise that resolves when scripts finish loading.\n *\n * **Comparison of GTM readiness hooks:**\n * | Hook | Returns | Re-renders | Use Case |\n * |------|---------|------------|----------|\n * | `useGtmReady()` | `() => Promise` | No | Await in event handlers |\n * | `useIsGtmReady()` | `() => boolean` | No | Synchronous checks in callbacks |\n * | `useGtmInitialized()` | `boolean` | Yes | Conditional rendering |\n *\n * @returns Function that returns a Promise resolving to script load states\n *\n * @example\n * ```tsx\n * const whenReady = useGtmReady();\n *\n * const handleClick = async () => {\n *   const states = await whenReady();\n *   if (states.every(s => s.status === 'loaded')) {\n *     // Safe to rely on GTM being fully loaded\n *   }\n * };\n * ```\n */\nexport const useGtmReady = (): (() => Promise<ScriptLoadState[]>) => {\n  const { whenReady } = useGtmContext();\n  return whenReady;\n};\n\n/**\n * Hook that returns a function to synchronously check if GTM is ready.\n *\n * **When to use**: When you need to check readiness without triggering re-renders,\n * typically in event handlers or callbacks.\n *\n * **Comparison of GTM readiness hooks:**\n * | Hook | Returns | Re-renders | Use Case |\n * |------|---------|------------|----------|\n * | `useGtmReady()` | `() => Promise` | No | Await in event handlers |\n * | `useIsGtmReady()` | `() => boolean` | No | Synchronous checks in callbacks |\n * | `useGtmInitialized()` | `boolean` | Yes | Conditional rendering |\n *\n * @returns Function that returns `true` if scripts loaded, `false` if still loading\n *\n * @example\n * ```tsx\n * const checkReady = useIsGtmReady();\n *\n * const handleSubmit = () => {\n *   if (checkReady()) {\n *     // GTM is ready, proceed with tracking\n *     push({ event: 'form_submit' });\n *   }\n * };\n * ```\n */\nexport const useIsGtmReady = (): (() => boolean) => {\n  const { isReady } = useGtmContext();\n  return isReady;\n};\n\n/**\n * Reactive hook that returns `true` when GTM scripts have finished loading.\n *\n * **When to use**: When you need to conditionally render UI based on GTM readiness.\n * This hook triggers a re-render when the state changes.\n *\n * **Comparison of GTM readiness hooks:**\n * | Hook | Returns | Re-renders | Use Case |\n * |------|---------|------------|----------|\n * | `useGtmReady()` | `() => Promise` | No | Await in event handlers |\n * | `useIsGtmReady()` | `() => boolean` | No | Synchronous checks in callbacks |\n * | `useGtmInitialized()` | `boolean` | Yes | Conditional rendering |\n *\n * @returns `true` if GTM is initialized, `false` otherwise (reactive)\n *\n * @example\n * ```tsx\n * const isInitialized = useGtmInitialized();\n *\n * if (!isInitialized) {\n *   return <LoadingSpinner />;\n * }\n *\n * return <AnalyticsDashboard />;\n * ```\n */\nexport const useGtmInitialized = (): boolean => {\n  const { isReady, onReady } = useGtmContext();\n  const [initialized, setInitialized] = useState(() => isReady());\n\n  useEffect(() => {\n    // Already initialized on mount\n    if (isReady()) {\n      setInitialized(true);\n      return;\n    }\n\n    // Subscribe to ready event\n    const unsubscribe = onReady(() => {\n      setInitialized(true);\n    });\n\n    return unsubscribe;\n  }, [isReady, onReady]);\n\n  return initialized;\n};\n\n/**\n * Result from the useGtmError hook.\n */\nexport interface GtmErrorState {\n  /** Whether any scripts failed to load */\n  hasError: boolean;\n  /** Array of failed script states (status 'failed' or 'partial') */\n  failedScripts: ScriptLoadState[];\n  /** Convenience getter for the first error message, if any */\n  errorMessage: string | null;\n}\n\n/**\n * Hook to capture GTM script load errors.\n * Returns reactive state that updates when scripts fail to load.\n *\n * @example\n * ```tsx\n * const { hasError, failedScripts, errorMessage } = useGtmError();\n *\n * if (hasError) {\n *   console.error('GTM failed to load:', errorMessage);\n *   // Optionally show fallback UI or retry logic\n * }\n * ```\n */\nexport const useGtmError = (): GtmErrorState => {\n  const { onReady } = useGtmContext();\n  const [errorState, setErrorState] = useState<GtmErrorState>({\n    hasError: false,\n    failedScripts: [],\n    errorMessage: null\n  });\n\n  useEffect(() => {\n    const unsubscribe = onReady((states) => {\n      const failedScripts = states.filter((s) => s.status === 'failed' || s.status === 'partial');\n\n      if (failedScripts.length > 0) {\n        const firstError = failedScripts.find((s) => s.error)?.error ?? null;\n        setErrorState({\n          hasError: true,\n          failedScripts,\n          errorMessage: firstError\n        });\n      }\n    });\n\n    return unsubscribe;\n  }, [onReady]);\n\n  return errorState;\n};\n\n/**\n * Props for GtmErrorBoundary component.\n */\nexport interface GtmErrorBoundaryProps {\n  children: ReactNode;\n  /** Fallback UI to render when an error occurs */\n  fallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode);\n  /** Callback invoked when an error is caught */\n  onError?: (error: Error, errorInfo: ErrorInfo) => void;\n  /** Whether to log errors to console (default: true in development) */\n  logErrors?: boolean;\n}\n\ninterface GtmErrorBoundaryState {\n  hasError: boolean;\n  error: Error | null;\n}\n\n/**\n * Error boundary component for GTM provider.\n * Catches errors during GTM initialization and renders a fallback UI.\n * Analytics and tracking will be disabled when an error occurs.\n */\nexport class GtmErrorBoundary extends Component<GtmErrorBoundaryProps, GtmErrorBoundaryState> {\n  constructor(props: GtmErrorBoundaryProps) {\n    super(props);\n    this.state = { hasError: false, error: null };\n  }\n\n  static getDerivedStateFromError(error: Error): GtmErrorBoundaryState {\n    return { hasError: true, error };\n  }\n\n  componentDidCatch(error: Error, errorInfo: ErrorInfo): void {\n    const { onError, logErrors = process.env.NODE_ENV !== 'production' } = this.props;\n\n    if (logErrors) {\n      console.error('[gtm-kit/react] Error caught by GtmErrorBoundary:', error);\n      console.error('[gtm-kit/react] Component stack:', errorInfo.componentStack);\n    }\n\n    if (onError) {\n      try {\n        onError(error, errorInfo);\n      } catch {\n        // Ignore callback errors\n      }\n    }\n  }\n\n  reset = (): void => {\n    this.setState({ hasError: false, error: null });\n  };\n\n  render(): ReactNode {\n    const { hasError, error } = this.state;\n    const { children, fallback } = this.props;\n\n    if (hasError && error) {\n      if (fallback === undefined) {\n        // Default: render children without GTM (silent fallback)\n        return children;\n      }\n\n      if (typeof fallback === 'function') {\n        return fallback(error, this.reset);\n      }\n\n      return fallback;\n    }\n\n    return children;\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwiedeman/gtm-kit-react",
-  "version": "1.1.6",
+  "version": "1.2.0",
   "description": "React hooks and provider for GTM Kit - Google Tag Manager integration. Supports React 16.8+.",
   "repository": {
     "type": "git",
@@ -49,7 +49,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@jwiedeman/gtm-kit": "^1.0.0"
+    "@jwiedeman/gtm-kit": "^1.2.0"
   },
   "peerDependencies": {
     "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"