fimo-analytics 2.7.0-experimental.1

package/README.md

@@ -0,0 +1,242 @@
+# fimo-analytics
+
+Fimo pageviews for existing websites. One framework-free tracker, with optional
+framework adapters. No framework peer is needed for JavaScript or plain HTML.
+
+This source introduces the package. Installation from npm requires a release
+that contains it; source presence is not evidence of publication. The package
+releases with the Fimo package group, but the standalone API has no dependency
+on the Fimo CLI or a hosting adapter.
+
+## Connection
+
+```sh
+pnpm add fimo-analytics
+```
+
+Configure the complete ingestion URL, including `/e/p`, for your project and
+branch. Use the tenant API base URL supplied by your Fimo connection and append
+`/e/p`; do not substitute your site's public URL or guess a tenant hostname.
+An origin-relative endpoint such as `/analytics-proxy/e/p` requires a proxy you
+already configured. There is no endpoint-discovery API in this package.
+
+```ts
+import { init } from 'fimo-analytics';
+
+const analytics = init({
+  endpoint: 'https://YOUR-TENANT-API-HOST/e/p',
+  enabled: true,
+});
+// When the application that owns the tracker is disposed:
+analytics.destroy();
+```
+
+Standalone tracking is enabled by default. Pass `enabled: false` in development
+and preview builds. Every send also checks for `bl_preview_token` in the current
+URL. Disabled and server-side initialization is inert, with no storage or
+network effects. Invalid active configuration throws before sending.
+
+## Framework adapters
+
+Install only the peers for your framework. Every component accepts `endpoint`
+and `enabled`, renders no visible UI, and cleans up when removed. Put it in a
+persistent application root. Generic React, Svelte and Vue observe browser
+history. Framework router adapters emit after committed navigation.
+
+### React and React Router
+
+```tsx
+import { Analytics } from 'fimo-analytics/react';
+// React Router: import { Analytics } from 'fimo-analytics/react-router';
+
+<Analytics endpoint={endpoint} enabled={isProduction} />;
+```
+
+The React Router component goes inside the router. It also accepts an optional
+`pageName`. It reads the router location, including virtual HashRouter paths.
+
+The upgraded `fimo-react-router` still exposes `Pageview({ routes })` and
+`FimoProviders` still mounts it. They retain `VITE_API_URL`,
+`VITE_ENABLE_ANALYTICS=true`, route-name matching and preview guards. No extra
+component is needed when that integration already tracks your application.
+
+### Next.js App and Pages routers
+
+```tsx
+import { Analytics } from 'fimo-analytics/next';
+
+// App Router: include this in app/layout.tsx, inside <body>.
+// Pages Router: include it in pages/_app.tsx beside <Component {...pageProps} />.
+<Analytics endpoint={endpoint} enabled={isProduction} />;
+```
+
+The adapter owns the client boundary and Suspense boundary for static App
+Router pages. Pages Router uses successful route-completion events. Both track
+query-only navigation; prefetching does not create pageviews.
+
+For App Router, keep one installation in the root layout. It can commit an
+intermediate URL before a server redirect reaches its destination. Both URLs can
+produce pageviews. Destination-only counting is not guaranteed for these redirects.
+Pages Router uses a different completion signal and does not share this limitation
+in the tested redirect journey.
+
+### Astro
+
+```astro
+---
+import Analytics from 'fimo-analytics/astro';
+const endpoint = 'https://YOUR-TENANT-API-HOST/e/p';
+---
+<html>
+  <body>
+    <slot />
+    <Analytics endpoint={endpoint} enabled={import.meta.env.PROD} />
+  </body>
+</html>
+```
+
+Use your shared layout. No React island or `client:*` directive is needed.
+Ordinary documents and Astro ClientRouter navigation are supported.
+
+### Svelte and SvelteKit
+
+```svelte
+<script>
+  import Analytics from 'fimo-analytics/svelte';
+  // SvelteKit: import Analytics from 'fimo-analytics/sveltekit';
+  const endpoint = 'https://YOUR-TENANT-API-HOST/e/p';
+</script>
+
+<Analytics {endpoint} enabled={import.meta.env.PROD} />
+```
+
+Use the root component, or `src/routes/+layout.svelte` in SvelteKit.
+The SvelteKit adapter uses `afterNavigate` and does not emit during SSR.
+
+### Vue
+
+```vue
+<script setup>
+import { Analytics } from 'fimo-analytics/vue';
+const endpoint = 'https://YOUR-TENANT-API-HOST/e/p';
+</script>
+
+<template><Analytics :endpoint="endpoint" /></template>
+```
+
+For Vue Router, use the manual core in your root component instead of mounting
+the generic history component. Wait for the initial router navigation before
+mounting the application, as in `await router.isReady()`.
+
+```ts
+import { onMounted, onUnmounted } from 'vue';
+import { useRouter } from 'vue-router';
+import { init, type Analytics } from 'fimo-analytics';
+
+const router = useRouter();
+let analytics: Analytics | undefined;
+let remove: (() => void) | undefined;
+onMounted(() => {
+  analytics = init({ endpoint, routing: 'manual', enabled: isProduction });
+  analytics.pageview();
+  remove = router.afterEach((_to, _from, failure) => {
+    if (!failure) analytics?.pageview();
+  });
+});
+onUnmounted(() => {
+  remove?.();
+  analytics?.destroy();
+});
+```
+
+### Nuxt
+
+The Nuxt module also needs the optional `@nuxt/kit` peer.
+
+```sh
+pnpm add -D @nuxt/kit
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['fimo-analytics/nuxt'],
+  analytics: {
+    endpoint: 'https://YOUR-TENANT-API-HOST/e/p',
+    enabled: process.env.NODE_ENV === 'production',
+  },
+});
+```
+
+The module installs a client-only plugin, tracks successful router navigation
+including reused pages and query changes, and cleans up during application
+disposal. Its configuration is public browser data. Never put secrets in it.
+
+### Plain HTML
+
+Copy `node_modules/fimo-analytics/dist/browser.js` to your site's static assets,
+then reference that file. Keep the copied asset pinned to the installed package.
+
+```html
+<script defer src="/fimo-analytics.js" data-endpoint="https://YOUR-TENANT-API-HOST/e/p" data-enabled="true"></script>
+```
+
+This is a classic script, not a module script. It uses its own `data-endpoint`
+and the same core. Use `data-enabled="false"` for disabled builds. No CDN or
+server-response injection is configured automatically.
+
+## Manual navigation and lifetime
+
+```ts
+const analytics = init({ endpoint, routing: 'manual' });
+// Call only after the application's router commits navigation.
+analytics.pageview({ path: '/pricing?plan=team', pageName: 'Pricing' });
+analytics.destroy();
+```
+
+History mode is the default. It sends initially and observes `pushState`,
+`replaceState` and `popstate`. Manual mode sends only when called. Default paths
+include pathname and query; fragments are excluded. Default page names use the
+pathname without a trailing slash. Explicit virtual paths support hash routers.
+
+Consecutive same-path sends collapse across mounts and installed copies for the
+same endpoint. `/a → /b → /a` counts three. Different active routing modes for
+one endpoint throw. `destroy()` releases one handle, is safe to repeat, and
+makes that handle inert. Last-handle disposal removes listeners and owned
+history wrappers. Same-path remounts remain deduplicated for the document's
+lifetime. Reloads and BFCache restores count as fresh visits.
+
+## Compatibility and delivery
+
+The package preserves `fimo.analytics.visitor-id` in localStorage and
+`fimo.analytics.session-id` in sessionStorage, without an inactivity timeout.
+Blocked storage falls back to stable IDs for this browser document, shared
+across copies. A later full page load may receive new IDs when storage is blocked.
+
+Requests use the existing URL-encoded `p,n,v,s,r,u` fields, document referrer,
+user agent, keepalive, CORS, and omitted credentials. Query parameters remain
+available for server-side campaign attribution. Project and branch are selected
+by the configured tenant endpoint. This package adds no custom events or schema.
+Delivery is best effort, with no retry after a network error, 429 or 202. A
+successful HTTP response is not proof that the destination stored the event.
+
+Earlier immutable applications keep their existing tracker and reporting.
+Older Fimo releases do not gain these exports or instrument missing trackers
+merely because this package is released. Never add a standalone tracker beside
+an unmodified legacy sender; the legacy sender cannot join the shared registry.
+Older template-based projects keep their copied sender until a supported
+upgrade changes their dependencies. The package does not add or remove endpoint
+aliases, alter historical rows, or change retention.
+
+## Version qualification and validation
+
+The fixture matrix pins React 19.2.4, React Router 7.18.2, Next.js 16.3.3,
+Astro 7.2.2, Svelte 5.56.9, SvelteKit 2.70.3, Vue 3.5.42, Vue Router 5.3.1,
+and Nuxt 4.5.2. Peer ranges express intended compatibility; they do not mean
+that every old release in those ranges has been browser-tested. In particular,
+React 18, React Router 8 and Next 15 require their own acceptance evidence before
+claiming tested support. Install a release that actually contains these exports.
+
+See [the fixture instructions](test/README.md) in the source checkout for exact
+build, tarball smoke, bundle measurement and browser commands. Nothing here
+asserts that the package has been npm-published or verified on a customer site.

package/components/Analytics.astro

@@ -0,0 +1,33 @@
+---
+import type { AnalyticsProps } from '../dist/index.js';
+interface Props extends AnalyticsProps {}
+const { endpoint, enabled = true } = Astro.props;
+---
+<fimo-analytics data-endpoint={endpoint} data-enabled={String(enabled)} hidden></fimo-analytics>
+<script>
+  import { type Analytics } from '../dist/index.js';
+  import { initOrWarn } from '../dist/internal.js';
+  if (!customElements.get('fimo-analytics')) {
+    customElements.define('fimo-analytics', class extends HTMLElement {
+      tracker?: Analytics;
+      commit = () => {
+        document.removeEventListener('astro:page-load', this.commit);
+        this.tracker?.pageview();
+      };
+      connectedCallback() {
+        this.tracker = initOrWarn({ endpoint: this.dataset.endpoint!, enabled: this.dataset.enabled !== 'false', routing: 'manual' });
+        // FIMO-2558: after-swap has the committed URL. Page-load can be delayed by
+        // scripts until another navigation commits, so use it only for initial mounting.
+        document.addEventListener('astro:after-swap', this.commit);
+        document.addEventListener('astro:page-load', this.commit, { once: true });
+        // Static pages have no router lifecycle.
+        if (!document.querySelector('meta[name="astro-view-transitions-enabled"]')) this.commit();
+      }
+      disconnectedCallback() {
+        document.removeEventListener('astro:after-swap', this.commit);
+        document.removeEventListener('astro:page-load', this.commit);
+        this.tracker?.destroy();
+      }
+    });
+  }
+</script>

package/components/Analytics.svelte

@@ -0,0 +1,9 @@
+<script lang="ts">
+  import { type AnalyticsProps } from '../dist/index.js';
+  import { initOrWarn } from '../dist/internal.js';
+  let { endpoint, enabled = true }: AnalyticsProps = $props();
+  $effect(() => {
+    const tracker = initOrWarn({ endpoint, enabled });
+    return () => tracker.destroy();
+  });
+</script>

package/components/SvelteKit.svelte

@@ -0,0 +1,16 @@
+<script lang="ts">
+  import { page } from '$app/state';
+
+  import { type AnalyticsProps } from '../dist/index.js';
+  import { initOrWarn } from '../dist/internal.js';
+  let { endpoint, enabled = true }: AnalyticsProps = $props();
+  $effect(() => {
+    const tracker = initOrWarn({ endpoint, enabled, routing: 'manual' });
+    $effect(() => {
+      // FIMO-2558: Shallow back/forward updates page.url without running afterNavigate.
+      const url = page.url;
+      tracker.pageview({ path: url.pathname + url.search });
+    });
+    return () => tracker.destroy();
+  });
+</script>

package/components/svelte.d.ts

@@ -0,0 +1,5 @@
+import type { Component } from 'svelte';
+
+import type { AnalyticsProps } from '../dist/index.js';
+declare const Analytics: Component<AnalyticsProps>;
+export default Analytics;

package/dist/browser.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/browser.js

@@ -0,0 +1 @@
+"use strict";(()=>{var g=Symbol.for("fimo.analytics.registry.v1"),m=()=>({pageview(){},destroy(){}}),P=()=>window.location.pathname+window.location.search,S=()=>new URLSearchParams(window.location.search).has("bl_preview_token");function b(t){if(typeof t!="string"||!t||t.trim()!==t||/[\\\s]/.test(t)||!(t.startsWith("/")&&!t.startsWith("//")||/^https?:\/\//i.test(t)))throw new TypeError("fimo-analytics requires an HTTP(S) endpoint or an origin-relative URL");let n=new URL(t,window.location.origin);if(!/^https?:$/.test(n.protocol)||n.username||n.password||n.hash)throw new TypeError("fimo-analytics endpoint must not contain credentials or a fragment");return n.href}var p={p:2048,n:512,r:2048,u:1024},w=(t,n)=>{if(t.length<=n)return t;let s=t.slice(0,n),a=s.charCodeAt(n-1);return a>=55296&&a<=56319?s.slice(0,-1):s},A=t=>t.length>=8&&t.length<=128;function y(t,n){let s;try{s=window[t];let e=s.getItem(n);if(e&&A(e))return e}catch{}let a=window.crypto?.randomUUID?.()??`${Date.now().toString(36)}-${Math.random().toString(36).slice(2,10)}`;try{s?.setItem(n,a)}catch{}return a}function E(t){let n=!0,s=()=>{if(n)for(let i of t.destinations.values())i.routing==="history"&&i.handles.values().next().value?.pageview()},a=["pushState","replaceState"].map(i=>{let o=window.history[i],r=function(...c){let d=o.apply(this,c);return s(),d};return window.history[i]=r,()=>{window.history[i]===r&&(window.history[i]=o)}}),e=i=>{if(i.persisted)for(let o of t.destinations.values()){let r=o.handles.values().next().value;!r||!o.lastPage||(o.lastPath=void 0,r.pageview(o.routing==="manual"?o.lastPage:void 0))}};return window.addEventListener("popstate",s),window.addEventListener("pageshow",e),()=>{n=!1,a.forEach(i=>i()),window.removeEventListener("popstate",s),window.removeEventListener("pageshow",e)}}function v(t){if(typeof window>"u"||typeof document>"u"||t.enabled===!1)return m();let n=b(t.endpoint),s=t.routing??"history";if(s!=="history"&&s!=="manual")throw new TypeError("Invalid analytics routing mode");let a=window,e=a[g]??(a[g]={destinations:new Map}),i=e.destinations.get(n);if(i?.handles.size&&i.routing!==s)throw new TypeError("Conflicting active analytics routing modes for the same endpoint");i||(i={routing:s,handles:new Set},e.destinations.set(n,i)),i.routing=s;let o=i,r=!1,c={pageview(d={}){if(r||S())return;let l=w((d.path??P()).split("#")[0]||"/",p.p);if(o.lastPath===l)return;let h=d.pageName??(l.split("?")[0].replace(/\/+$/,"")||"/");o.lastPath=l,o.lastPage={path:l,pageName:h},e.visitor??(e.visitor=y("localStorage","fimo.analytics.visitor-id")),e.session??(e.session=y("sessionStorage","fimo.analytics.session-id"));let u=new URLSearchParams({p:l,n:w(h,p.n),v:e.visitor,s:e.session});document.referrer&&u.set("r",w(document.referrer,p.r)),window.navigator.userAgent&&u.set("u",w(window.navigator.userAgent,p.u));try{window.fetch(n,{method:"POST",body:u,keepalive:!0,mode:"cors",credentials:"omit"}).catch(()=>{})}catch{}},destroy(){r||(r=!0,o.handles.delete(c),[...e.destinations.values()].some(d=>d.handles.size)||(e.stop?.(),e.stop=void 0))}};return o.handles.add(c),e.stop??(e.stop=E(e)),s==="history"&&c.pageview(),c}var f=document.currentScript;if(f)try{v({endpoint:f.dataset.endpoint,enabled:f.dataset.enabled!=="false"})}catch(t){console.warn("[fimo-analytics]",t)}})();

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export type AnalyticsOptions = {
+    /** Complete tenant ingestion URL, including /e/p, or an explicit origin-relative proxy. */
+    endpoint: string;
+    enabled?: boolean;
+    routing?: 'history' | 'manual';
+};
+export type AnalyticsProps = Pick<AnalyticsOptions, 'endpoint' | 'enabled'>;
+export type Pageview = {
+    path?: string;
+    pageName?: string;
+};
+export type Analytics = {
+    pageview(page?: Pageview): void;
+    destroy(): void;
+};
+/** Initialize once at the application root; destroy the handle when its owner unmounts. */
+export declare function init(options: AnalyticsOptions): Analytics;

package/dist/index.js

@@ -0,0 +1,180 @@
+// FIMO-2558: Share identity and consecutive-path dedupe across installed copies and HMR.
+const registryKey = Symbol.for('fimo.analytics.registry.v1');
+const inert = () => ({ pageview() { }, destroy() { } });
+const browserPath = () => window.location.pathname + window.location.search;
+const preview = () => new URLSearchParams(window.location.search).has('bl_preview_token');
+function endpointUrl(endpoint) {
+    if (typeof endpoint !== 'string' ||
+        !endpoint ||
+        endpoint.trim() !== endpoint ||
+        /[\\\s]/.test(endpoint) ||
+        !((endpoint.startsWith('/') && !endpoint.startsWith('//')) || /^https?:\/\//i.test(endpoint))) {
+        throw new TypeError('fimo-analytics requires an HTTP(S) endpoint or an origin-relative URL');
+    }
+    const url = new URL(endpoint, window.location.origin);
+    if (!/^https?:$/.test(url.protocol) || url.username || url.password || url.hash) {
+        throw new TypeError('fimo-analytics endpoint must not contain credentials or a fragment');
+    }
+    return url.href;
+}
+/**
+ * Ingestion validates the whole payload and rejects it outright, so a single
+ * over-long field drops the pageview rather than trimming it. A long referrer
+ * is the realistic case: some campaign and redirector URLs exceed 2048 bytes.
+ * Truncating records a slightly lossy visit instead of losing it entirely.
+ */
+const CAPS = { p: 2048, n: 512, r: 2048, u: 1024 };
+const clamp = (value, max) => {
+    if (value.length <= max)
+        return value;
+    const cut = value.slice(0, max);
+    // Cutting between the halves of a surrogate pair leaves a lone surrogate,
+    // which the form encoder replaces with U+FFFD — a stored character the
+    // visitor never requested. Drop the orphan instead.
+    const last = cut.charCodeAt(max - 1);
+    return last >= 0xd800 && last <= 0xdbff ? cut.slice(0, -1) : cut;
+};
+/** Ingestion also bounds the identifiers; a stored value outside them would 400 every send. */
+const usableId = (value) => value.length >= 8 && value.length <= 128;
+function storedId(kind, key) {
+    let storage;
+    try {
+        storage = window[kind];
+        const existing = storage.getItem(key);
+        if (existing && usableId(existing))
+            return existing;
+    }
+    catch {
+        /* Storage may be blocked, including the property getter. */
+    }
+    const id = window.crypto?.randomUUID?.() ?? `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+    try {
+        storage?.setItem(key, id);
+    }
+    catch {
+        /* Keep the document's in-memory ID. */
+    }
+    return id;
+}
+function observe(registry) {
+    let active = true;
+    const navigate = () => {
+        if (!active)
+            return;
+        for (const destination of registry.destinations.values()) {
+            if (destination.routing === 'history')
+                destination.handles.values().next().value?.pageview();
+        }
+    };
+    const restores = ['pushState', 'replaceState'].map((method) => {
+        const original = window.history[method];
+        const wrapper = function (...args) {
+            const result = original.apply(this, args);
+            navigate();
+            return result;
+        };
+        window.history[method] = wrapper;
+        return () => {
+            // Do not overwrite a router or library that wrapped us after initialization.
+            if (window.history[method] === wrapper)
+                window.history[method] = original;
+        };
+    });
+    const restorePage = (event) => {
+        if (!event.persisted)
+            return;
+        for (const destination of registry.destinations.values()) {
+            const handle = destination.handles.values().next().value;
+            if (!handle || !destination.lastPage)
+                continue;
+            destination.lastPath = undefined;
+            handle.pageview(destination.routing === 'manual' ? destination.lastPage : undefined);
+        }
+    };
+    window.addEventListener('popstate', navigate);
+    window.addEventListener('pageshow', restorePage);
+    return () => {
+        active = false;
+        restores.forEach((restore) => restore());
+        window.removeEventListener('popstate', navigate);
+        window.removeEventListener('pageshow', restorePage);
+    };
+}
+/** Initialize once at the application root; destroy the handle when its owner unmounts. */
+export function init(options) {
+    if (typeof window === 'undefined' || typeof document === 'undefined' || options.enabled === false)
+        return inert();
+    const endpoint = endpointUrl(options.endpoint);
+    const routing = options.routing ?? 'history';
+    if (routing !== 'history' && routing !== 'manual')
+        throw new TypeError('Invalid analytics routing mode');
+    const shared = window;
+    const registry = (shared[registryKey] ?? (shared[registryKey] = { destinations: new Map() }));
+    let destination = registry.destinations.get(endpoint);
+    if (destination?.handles.size && destination.routing !== routing) {
+        throw new TypeError('Conflicting active analytics routing modes for the same endpoint');
+    }
+    if (!destination) {
+        destination = { routing, handles: new Set() };
+        registry.destinations.set(endpoint, destination);
+    }
+    destination.routing = routing;
+    const state = destination;
+    let destroyed = false;
+    const handle = {
+        pageview(page = {}) {
+            if (destroyed || preview())
+                return;
+            // Clamp before the dedupe, not after: two navigations that differ only
+            // past the cap arrive as the same `p`, and comparing the raw values
+            // would send both and record them as duplicates of each other.
+            const path = clamp((page.path ?? browserPath()).split('#')[0] || '/', CAPS.p);
+            if (state.lastPath === path)
+                return;
+            const pageName = page.pageName ?? (path.split('?')[0].replace(/\/+$/, '') || '/');
+            state.lastPath = path;
+            state.lastPage = { path, pageName };
+            registry.visitor ?? (registry.visitor = storedId('localStorage', 'fimo.analytics.visitor-id'));
+            registry.session ?? (registry.session = storedId('sessionStorage', 'fimo.analytics.session-id'));
+            const body = new URLSearchParams({
+                p: path,
+                n: clamp(pageName, CAPS.n),
+                v: registry.visitor,
+                s: registry.session,
+            });
+            if (document.referrer)
+                body.set('r', clamp(document.referrer, CAPS.r));
+            if (window.navigator.userAgent)
+                body.set('u', clamp(window.navigator.userAgent, CAPS.u));
+            try {
+                void window
+                    .fetch(endpoint, {
+                    method: 'POST',
+                    body,
+                    keepalive: true,
+                    mode: 'cors',
+                    credentials: 'omit',
+                })
+                    .catch(() => { });
+            }
+            catch {
+                /* Best effort; never retry an ambiguous delivery without server idempotency. */
+            }
+        },
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            state.handles.delete(handle);
+            if (![...registry.destinations.values()].some((entry) => entry.handles.size)) {
+                registry.stop?.();
+                registry.stop = undefined;
+            }
+        },
+    };
+    state.handles.add(handle);
+    registry.stop ?? (registry.stop = observe(registry));
+    if (routing === 'history')
+        handle.pageview();
+    return handle;
+}

package/dist/internal.d.ts

@@ -0,0 +1,15 @@
+import { type Analytics, type AnalyticsOptions } from './index.js';
+/**
+ * An adapter must never take its host application down. `init` throws on a
+ * misconfigured endpoint — most often an unset environment variable
+ * interpolated into the URL, which arrives as the string `undefined/e/p` — and
+ * a throw inside a component's effect reaches the nearest error boundary, or
+ * blanks the root when there is none. Losing analytics is an acceptable
+ * outcome; losing the customer's page is not.
+ *
+ * `init` itself keeps throwing: it is the documented programmatic API, and a
+ * bad endpoint there is a programming error worth surfacing. The standalone
+ * browser script already degrades this way, and the framework adapters now
+ * match it.
+ */
+export declare function initOrWarn(options: AnalyticsOptions): Analytics;

package/dist/internal.js

@@ -0,0 +1,23 @@
+import { init } from './index.js';
+/**
+ * An adapter must never take its host application down. `init` throws on a
+ * misconfigured endpoint — most often an unset environment variable
+ * interpolated into the URL, which arrives as the string `undefined/e/p` — and
+ * a throw inside a component's effect reaches the nearest error boundary, or
+ * blanks the root when there is none. Losing analytics is an acceptable
+ * outcome; losing the customer's page is not.
+ *
+ * `init` itself keeps throwing: it is the documented programmatic API, and a
+ * bad endpoint there is a programming error worth surfacing. The standalone
+ * browser script already degrades this way, and the framework adapters now
+ * match it.
+ */
+export function initOrWarn(options) {
+    try {
+        return init(options);
+    }
+    catch (error) {
+        console.warn('[fimo-analytics]', error);
+        return { pageview() { }, destroy() { } };
+    }
+}

package/dist/next.d.ts

@@ -0,0 +1,2 @@
+import { type AnalyticsProps } from './index.js';
+export declare function Analytics({ endpoint, enabled }: AnalyticsProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/next.js

@@ -0,0 +1,38 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useRouter } from 'next/compat/router.js';
+import { usePathname, useSearchParams } from 'next/navigation.js';
+import { Suspense, useEffect } from 'react';
+import { initOrWarn } from './internal.js';
+function AppAnalytics({ endpoint, enabled }) {
+    const pathname = usePathname();
+    const search = useSearchParams();
+    const query = search?.toString();
+    useEffect(() => {
+        if (pathname === null)
+            return;
+        const tracker = initOrWarn({ endpoint, enabled, routing: 'manual' });
+        // Read the committed browser URL to retain its original query encoding and base path.
+        tracker.pageview();
+        return () => tracker.destroy();
+    }, [endpoint, enabled, pathname, query]);
+    return null;
+}
+export function Analytics({ endpoint, enabled }) {
+    const router = useRouter();
+    const ready = router?.isReady;
+    const events = router?.events;
+    useEffect(() => {
+        if (!ready || !events)
+            return;
+        const tracker = initOrWarn({ endpoint, enabled, routing: 'manual' });
+        const committed = () => tracker.pageview();
+        committed();
+        events.on('routeChangeComplete', committed);
+        return () => {
+            events.off('routeChangeComplete', committed);
+            tracker.destroy();
+        };
+    }, [endpoint, enabled, ready, events]);
+    return router ? null : (_jsx(Suspense, { fallback: null, children: _jsx(AppAnalytics, { endpoint: endpoint, enabled: enabled }) }));
+}

package/dist/nuxt-plugin.mjs

@@ -0,0 +1,23 @@
+import { defineNuxtPlugin, useRuntimeConfig, useRouter } from '#app';
+
+import { initOrWarn } from './internal.js';
+
+export default defineNuxtPlugin((app) => {
+  const options = useRuntimeConfig().public.fimoAnalytics;
+  const router = useRouter();
+  let tracker;
+  const mounted = app.hook('app:mounted', () => {
+    tracker = initOrWarn({ ...options, routing: 'manual' });
+    tracker.pageview();
+  });
+  const remove = router.afterEach((_to, _from, failure) => {
+    if (!failure) tracker?.pageview();
+  });
+  const destroy = () => {
+    mounted();
+    remove();
+    tracker?.destroy();
+  };
+  app.vueApp.onUnmount(destroy);
+  if (import.meta.hot) import.meta.hot.dispose(destroy);
+});

package/dist/nuxt.d.ts

@@ -0,0 +1,12 @@
+import type { NuxtModule } from '@nuxt/schema';
+import type { AnalyticsProps } from './index.js';
+declare const analytics: NuxtModule<AnalyticsProps>;
+export default analytics;
+declare module '@nuxt/schema' {
+    interface NuxtConfig {
+        analytics?: AnalyticsProps;
+    }
+    interface NuxtOptions {
+        analytics?: AnalyticsProps;
+    }
+}

package/dist/nuxt.js

@@ -0,0 +1,10 @@
+import { addPlugin, createResolver, defineNuxtModule } from '@nuxt/kit';
+const analytics = defineNuxtModule({
+    meta: { name: 'fimo-analytics', configKey: 'analytics' },
+    defaults: { endpoint: '', enabled: true },
+    setup(options, nuxt) {
+        nuxt.options.runtimeConfig.public.fimoAnalytics = options;
+        addPlugin({ src: createResolver(import.meta.url).resolve('./nuxt-plugin.mjs'), mode: 'client' });
+    },
+});
+export default analytics;

package/dist/react-router.d.ts

@@ -0,0 +1,4 @@
+import { type AnalyticsProps } from './index.js';
+export declare function Analytics({ endpoint, enabled, pageName }: AnalyticsProps & {
+    pageName?: string;
+}): null;

package/dist/react-router.js

@@ -0,0 +1,13 @@
+'use client';
+import { useEffect } from 'react';
+import { useLocation } from 'react-router';
+import { initOrWarn } from './internal.js';
+export function Analytics({ endpoint, enabled, pageName }) {
+    const { pathname, search } = useLocation();
+    useEffect(() => {
+        const tracker = initOrWarn({ endpoint, enabled, routing: 'manual' });
+        tracker.pageview({ path: pathname + search, pageName });
+        return () => tracker.destroy();
+    }, [endpoint, enabled, pathname, search, pageName]);
+    return null;
+}

package/dist/react.d.ts

@@ -0,0 +1,2 @@
+import { type AnalyticsProps } from './index.js';
+export declare function Analytics({ endpoint, enabled }: AnalyticsProps): null;

package/dist/react.js

@@ -0,0 +1,10 @@
+'use client';
+import { useEffect } from 'react';
+import { initOrWarn } from './internal.js';
+export function Analytics({ endpoint, enabled }) {
+    useEffect(() => {
+        const tracker = initOrWarn({ endpoint, enabled });
+        return () => tracker.destroy();
+    }, [endpoint, enabled]);
+    return null;
+}

package/dist/vue.d.ts

@@ -0,0 +1,21 @@
+export declare const Analytics: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    endpoint: {
+        type: StringConstructor;
+        required: true;
+    };
+    enabled: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>, () => null, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    endpoint: {
+        type: StringConstructor;
+        required: true;
+    };
+    enabled: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>> & Readonly<{}>, {
+    enabled: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

package/dist/vue.js

@@ -0,0 +1,21 @@
+import { defineComponent, onMounted, onUnmounted, watch } from 'vue';
+import { initOrWarn } from './internal.js';
+export const Analytics = defineComponent({
+    name: 'FimoAnalytics',
+    props: { endpoint: { type: String, required: true }, enabled: { type: Boolean, default: true } },
+    setup(props) {
+        let tracker;
+        let stop;
+        onMounted(() => {
+            stop = watch(() => [props.endpoint, props.enabled], () => {
+                tracker?.destroy();
+                tracker = initOrWarn({ endpoint: props.endpoint, enabled: props.enabled });
+            }, { immediate: true });
+        });
+        onUnmounted(() => {
+            stop?.();
+            tracker?.destroy();
+        });
+        return () => null;
+    },
+});

package/package.json

@@ -0,0 +1,120 @@
+{
+  "name": "fimo-analytics",
+  "version": "2.7.0-experimental.1",
+  "description": "Framework-independent Fimo pageview analytics with optional framework adapters.",
+  "files": [
+    "dist/",
+    "components/",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "./dist/browser.js",
+    "./components/*.astro",
+    "./components/*.svelte"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./react-router": {
+      "types": "./dist/react-router.d.ts",
+      "import": "./dist/react-router.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "import": "./dist/next.js"
+    },
+    "./vue": {
+      "types": "./dist/vue.d.ts",
+      "import": "./dist/vue.js"
+    },
+    "./nuxt": {
+      "types": "./dist/nuxt.d.ts",
+      "import": "./dist/nuxt.js"
+    },
+    "./svelte": {
+      "types": "./components/svelte.d.ts",
+      "svelte": "./components/Analytics.svelte",
+      "default": "./components/Analytics.svelte"
+    },
+    "./sveltekit": {
+      "types": "./components/svelte.d.ts",
+      "svelte": "./components/SvelteKit.svelte",
+      "default": "./components/SvelteKit.svelte"
+    },
+    "./astro": "./components/Analytics.astro",
+    "./browser": "./dist/browser.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node build.mjs",
+    "check:types": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm build && node --test test/*.test.mjs",
+    "test:e2e": "node test/run-e2e.mjs",
+    "test:fixtures": "node test/fixtures.mjs",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "@nuxt/kit": "4.5.2",
+    "@nuxt/schema": "4.5.2",
+    "@types/react": "19.2.14",
+    "esbuild": "^0.25.10",
+    "next": "16.3.3",
+    "react": "19.2.4",
+    "react-router": "7.18.2",
+    "typescript": "7.0.2",
+    "vue": "3.5.42"
+  },
+  "peerDependencies": {
+    "@nuxt/kit": "^4.5.2",
+    "@sveltejs/kit": "^2.12.0",
+    "astro": "^7.0.0",
+    "next": "^15.0.0 || ^16.0.0",
+    "nuxt": "^4.5.2",
+    "react": "^18.2.0 || ^19.0.0",
+    "react-router": "^7.0.0 || ^8.0.0",
+    "svelte": "^5.0.0",
+    "vue": "^3.5.0"
+  },
+  "peerDependenciesMeta": {
+    "@nuxt/kit": {
+      "optional": true
+    },
+    "nuxt": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-router": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    },
+    "astro": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    },
+    "@sveltejs/kit": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20.12.0"
+  }
+}