@hostess/browser 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Horizon Web Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# @hostess/browser
+
+Framework-agnostic browser core for Hostess **Audience Analytics** and **Speed
+Insights**. Page views and Core Web Vitals from any site behind a Hostess URL —
+cookieless, no consent banner, ~1.7 KB gzipped for analytics.
+
+```bash
+npm install @hostess/browser
+```
+
+```ts
+import { inject, injectSpeedInsights } from "@hostess/browser";
+
+inject(); // page views
+injectSpeedInsights(); // LCP, CLS, INP, FCP, TTFB
+```
+
+This is the shared core that framework adapters build on — `@hostess/nextjs`
+re-exports `<Analytics />` and `<SpeedInsights />` on top of it. Use it directly
+in any SPA, or (later) via a `<script>` tag on static sites.
+
+## API
+
+```ts
+inject(opts?);              // one pv beacon per page view (load + SPA navigations)
+injectSpeedInsights(opts?); // wv beacons from the web-vitals attribution build
+track(name, props?);        // custom events — phase 2, currently a no-op stub
+
+type RouteInfo = { route: string; path: string };
+type RouteProvider = {
+  current(): RouteInfo;
+  onChange(cb: (info: RouteInfo, nav: "spa" | "back-forward") => void): () => void;
+};
+
+// opts: { routeProvider?: RouteProvider; debug?: boolean }
+```
+
+Both entry points are **idempotent** and safe to call during SSR (they no-op
+without a DOM). The only framework-specific concern is route-template
+reconstruction, expressed through `RouteProvider`; the default provider uses
+`location.pathname` as both `route` and `path` and tracks SPA navigations via
+`history`/`popstate`.
+
+## What it sends
+
+Same-origin `POST /_hostess/rum` — a JSON array of beacons (≤ 20, ≤ 8 KB per
+request) via `navigator.sendBeacon`, falling back to `fetch(keepalive)`. Flushed
+when the page is hidden (where CLS and INP finalize) and at queue thresholds.
+
+Each beacon (schema v1):
+
+| Field | Meaning |
+| --- | --- |
+| `v` | schema version (`1`) |
+| `k` | `pv` (page view) or `wv` (web vital) |
+| `route` / `path` | route template and concrete path (query stripped) |
+| `ref` | referrer **origin only**, `""` for same-origin/direct |
+| `utm` | the five `utm_*` params only |
+| `nav` | `load` / `spa` / `back-forward` |
+| `dc` | coarse device class (`desktop` / `mobile` / `tablet`) |
+| `sdk` | `browser@<version>` (adapters override) |
+
+`wv` beacons add `m` (metric name), `val` (ms; CLS unitless), and `rating`.
+Everything else — visitor identity, country, browser/OS, hostname — is derived
+**server-side** and never sent by the client.
+
+## Privacy
+
+Hard lines enforced in code and asserted in tests:
+
+- **No cookies, no `localStorage`, no fingerprinting.**
+- **No query strings** and no raw URLs with parameter values — only the five
+  `utm_*` keys cross the wire, and referrers are reduced to their origin.
+- **No user identifiers.** Visitor uniqueness is derived server-side from a
+  daily-rotating salt (the Plausible model).
+
+`NODE_ENV=development` sends **nothing**. `debug: true` logs the would-be
+payloads to the console (in any environment).
+
+## Failure posture
+
+Beacons are fire-and-forget. If the ingest endpoint is missing or disabled
+(`insights.browser: disabled` → 404), the queue detects it on the first
+observable request and **stops for the rest of the page's lifetime** — silent
+and free after the first failure.
+
+## Bundle
+
+Tree-shakeable, `sideEffects: false`, ESM + CJS via bunchee. Importing only
+`inject` pulls ~1.7 KB gzipped; `injectSpeedInsights` adds the `web-vitals`
+attribution build (~6 KB gzipped total).
+
+## Development
+
+```bash
+pnpm install
+pnpm --filter @hostess/browser build
+pnpm --filter @hostess/browser test
+```

package/dist/index.cjs

@@ -0,0 +1,417 @@
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var attribution = require('web-vitals/attribution');
+
+/** True only in a real browser (guards against SSR / Node import). */ function hasDom() {
+    return typeof window !== "undefined" && typeof document !== "undefined";
+}
+/** True at the moment the page is hidden — the correctness-critical flush point. */ function isHidden() {
+    return typeof document !== "undefined" && document.visibilityState === "hidden";
+}
+/**
+ * `NODE_ENV=development` disables all beacons (bundlers inline this constant;
+ * the `typeof` guard keeps it safe when `process` is absent in the browser).
+ */ function isDevelopment() {
+    try {
+        return typeof process !== "undefined" && !!process.env && process.env.NODE_ENV === "development";
+    } catch  {
+        return false;
+    }
+}
+
+// Same-origin ingest path (howl-cloud/hostess#32). Never cross-origin, so no
+// CORS ever applies.
+const ENDPOINT = "/_hostess/rum";
+// Transport hard caps from schema v1: a request carries at most 20 beacons and
+// 8 KB. A flush is split into as many batches as needed to respect both.
+const MAX_BEACONS = 20;
+const MAX_BYTES = 8 * 1024;
+const encoder = typeof TextEncoder !== "undefined" ? new TextEncoder() : null;
+function byteLength(s) {
+    return encoder ? encoder.encode(s).length : s.length;
+}
+/** Greedily pack beacons into batches that respect both the count and byte caps. */ function splitBatches(beacons) {
+    const batches = [];
+    let current = [];
+    for (const beacon of beacons){
+        const candidate = current.length ? [
+            ...current,
+            beacon
+        ] : [
+            beacon
+        ];
+        const tooMany = candidate.length > MAX_BEACONS;
+        const tooBig = byteLength(JSON.stringify(candidate)) > MAX_BYTES;
+        if (current.length && (tooMany || tooBig)) {
+            batches.push(current);
+            current = [
+                beacon
+            ]; // a single beacon over 8 KB is unsplittable; send alone
+        } else {
+            current = candidate;
+        }
+    }
+    if (current.length) batches.push(current);
+    return batches;
+}
+/**
+ * Page-lifetime beacon queue. One instance per page (a window singleton shared
+ * by `inject` and `injectSpeedInsights`), so their beacons batch together.
+ *
+ * Flush triggers: the queue reaches `MAX_BEACONS`, the page transitions to
+ * hidden, or a beacon is enqueued while the page is already hidden. That last
+ * rule is what makes the CLS/INP path correct without depending on listener
+ * order: `web-vitals` finalizes those metrics inside its own
+ * `visibilitychange` handler, and whichever order the handlers run, a beacon
+ * pushed while hidden flushes immediately.
+ *
+ * Failure posture (fire-and-forget, back-off-and-stop): a disabled endpoint
+ * returns 404, but `navigator.sendBeacon`'s boolean only reports whether the UA
+ * queued the request, never the HTTP status. So the queue *probes* with an
+ * observable `fetch(keepalive)` until the first success; a 404 or network
+ * error there stops the queue for the rest of the page's life (silent and free
+ * after the first failure). Once the endpoint is confirmed live, it prefers
+ * `sendBeacon` — the only transport that reliably survives page unload.
+ */ class BeaconQueue {
+    push(beacon) {
+        if (this.stopped) return;
+        this.ensureListeners();
+        this.buffer.push(beacon);
+        if (this.buffer.length >= MAX_BEACONS || isHidden()) this.flush();
+    }
+    flush() {
+        if (this.stopped || this.buffer.length === 0) return;
+        const batches = splitBatches(this.buffer);
+        this.buffer = [];
+        for (const batch of batches)this.send(batch);
+    }
+    /** Halt all sending for the page lifetime and drop anything buffered. */ stop() {
+        this.stopped = true;
+        this.buffer = [];
+    }
+    ensureListeners() {
+        if (this.listening || typeof document === "undefined") return;
+        this.listening = true;
+        document.addEventListener("visibilitychange", ()=>{
+            if (isHidden()) this.flush();
+        });
+    }
+    send(batch) {
+        const body = JSON.stringify(batch);
+        // Fast path once the endpoint is confirmed live: sendBeacon survives unload.
+        if (this.verified && this.trySendBeacon(body)) return;
+        // Observable path: confirms the endpoint and detects a disabled one.
+        if (typeof fetch === "function") {
+            fetch(ENDPOINT, {
+                method: "POST",
+                body,
+                keepalive: true,
+                credentials: "omit",
+                // text/plain mirrors sendBeacon and keeps this a simple same-origin
+                // request; the ingest parses the JSON body regardless of content-type.
+                headers: {
+                    "Content-Type": "text/plain;charset=UTF-8"
+                }
+            }).then((res)=>{
+                if (res.ok) this.verified = true;
+                else this.stop();
+            }).catch(()=>this.stop());
+            return;
+        }
+        // No fetch available: last-resort sendBeacon (cannot observe the result).
+        if (!this.trySendBeacon(body)) this.stop();
+    }
+    trySendBeacon(body) {
+        const nav = typeof navigator !== "undefined" ? navigator : undefined;
+        if (!nav || typeof nav.sendBeacon !== "function") return false;
+        try {
+            return nav.sendBeacon(ENDPOINT, body);
+        } catch  {
+            return false;
+        }
+    }
+    constructor(){
+        this.buffer = [];
+        this.stopped = false;
+        this.verified = false;
+        this.listening = false;
+    }
+}
+
+const KEY = "__hostess_rum__";
+function state() {
+    const w = window;
+    return w[KEY] ??= {};
+}
+function getQueue() {
+    const st = state();
+    return st.queue ??= new BeaconQueue();
+}
+
+/** Strip the query string and hash, leaving only the path. */ function stripQuery(pathOrUrl) {
+    let end = pathOrUrl.length;
+    const q = pathOrUrl.indexOf("?");
+    const h = pathOrUrl.indexOf("#");
+    if (q >= 0) end = Math.min(end, q);
+    if (h >= 0) end = Math.min(end, h);
+    return pathOrUrl.slice(0, end);
+}
+// history.pushState / replaceState do not emit an event. Patch them once (per
+// page) to dispatch one, so the default provider can observe SPA navigations
+// without every provider stacking its own monkey-patch. popstate covers
+// back/forward natively.
+const LOCATION_CHANGE_EVENT = "hostess:locationchange";
+const HISTORY_PATCH_FLAG = "__hostess_history_patched__";
+function ensureHistoryEvents() {
+    const w = window;
+    if (w[HISTORY_PATCH_FLAG]) return;
+    w[HISTORY_PATCH_FLAG] = true;
+    for (const method of [
+        "pushState",
+        "replaceState"
+    ]){
+        const original = history[method];
+        history[method] = function(...args) {
+            const result = original.apply(this, args);
+            window.dispatchEvent(new Event(LOCATION_CHANGE_EVENT));
+            return result;
+        };
+    }
+}
+/**
+ * Default provider with no framework knowledge: `location.pathname` is used as
+ * both the route template and the concrete path — correct for non-parameterized
+ * sites, and the ingest's route-hygiene caps absorb the rest. It also emits
+ * navigation changes (pushState/replaceState → "spa", popstate →
+ * "back-forward") so `inject()` is useful standalone in a bare SPA; adapters
+ * that supply real templates replace this entirely.
+ */ function defaultRouteProvider() {
+    const read = ()=>{
+        const path = typeof location !== "undefined" ? location.pathname : "/";
+        return {
+            route: path,
+            path
+        };
+    };
+    return {
+        current: read,
+        onChange (cb) {
+            if (typeof window === "undefined") return ()=>{};
+            ensureHistoryEvents();
+            let last = location.pathname;
+            const emit = (nav)=>()=>{
+                    const path = location.pathname;
+                    if (path === last) return; // ignore hash-only / query-only changes
+                    last = path;
+                    cb({
+                        route: path,
+                        path
+                    }, nav);
+                };
+            const onSpa = emit("spa");
+            const onPop = emit("back-forward");
+            window.addEventListener(LOCATION_CHANGE_EVENT, onSpa);
+            window.addEventListener("popstate", onPop);
+            return ()=>{
+                window.removeEventListener(LOCATION_CHANGE_EVENT, onSpa);
+                window.removeEventListener("popstate", onPop);
+            };
+        }
+    };
+}
+
+/**
+ * Reduce a referrer URL to its origin only — never the path or query. Returns
+ * "" for direct visits, same-origin navigations, and non-http(s) schemes, so a
+ * beacon can never leak where on another site the visitor came from.
+ */ function referrerOrigin(ref) {
+    const raw = (typeof document !== "undefined" ? document.referrer : "");
+    if (!raw) return "";
+    let url;
+    try {
+        url = new URL(raw);
+    } catch  {
+        return "";
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") return "";
+    const here = typeof location !== "undefined" ? location.origin : "";
+    if (url.origin === here) return "";
+    return url.origin;
+}
+
+const UTM_KEYS = [
+    "source",
+    "medium",
+    "campaign",
+    "term",
+    "content"
+];
+// Matches the ingest's per-value cap; over-length values are truncated rather
+// than dropped so a long campaign name still attributes.
+const MAX_VALUE_LENGTH = 64;
+/**
+ * Extract the five `utm_*` parameters from a query string. Every other query
+ * parameter is ignored and never sent — this is the only place a raw query
+ * value crosses into a beacon.
+ */ function extractUtm(search) {
+    const qs = (typeof location !== "undefined" ? location.search : "");
+    const utm = {};
+    if (!qs) return utm;
+    let params;
+    try {
+        params = new URLSearchParams(qs);
+    } catch  {
+        return utm;
+    }
+    for (const key of UTM_KEYS){
+        const value = params.get(`utm_${key}`);
+        if (value != null && value !== "") {
+            utm[key] = value.slice(0, MAX_VALUE_LENGTH);
+        }
+    }
+    return utm;
+}
+
+/**
+ * Coarse device class from UA Client Hints with a UA-string fallback. Only
+ * three buckets — no model, no fingerprinting.
+ *
+ * Tablet is decided from the UA string first because UA-CH low-entropy hints
+ * have no tablet signal (an iPad reports `mobile: false`, indistinguishable
+ * from a desktop). Everything else prefers the `mobile` hint, falling back to
+ * UA-string keywords.
+ */ function deviceClass() {
+    const nav = typeof navigator !== "undefined" ? navigator : undefined;
+    const ua = nav?.userAgent ?? "";
+    if (/\bipad\b/i.test(ua) || /\btablet\b/i.test(ua) || /android/i.test(ua) && !/mobile/i.test(ua)) {
+        return "tablet";
+    }
+    const uaData = nav?.userAgentData;
+    if (uaData && typeof uaData.mobile === "boolean") {
+        return uaData.mobile ? "mobile" : "desktop";
+    }
+    if (/mobi|iphone|ipod|android/i.test(ua)) return "mobile";
+    return "desktop";
+}
+
+/**
+ * The single gate every beacon passes through.
+ *
+ * - `debug` logs the would-be payload (works even in development, so you can
+ *   verify what *would* be sent).
+ * - `NODE_ENV=development` is silent: it returns before the queue is ever
+ *   created, guaranteeing no network and no listeners in development.
+ */ function report(beacon, debug) {
+    if (debug) {
+        try {
+            console.log("[hostess/browser]", beacon);
+        } catch  {
+        // console unavailable — never let logging break the host page.
+        }
+    }
+    if (isDevelopment()) return;
+    getQueue().push(beacon);
+}
+
+// Bumped in lockstep with package.json on release. Surfaces in the `sdk`
+// beacon field as `browser@<version>` (framework adapters override the prefix).
+const SDK_VERSION = "0.1.0";
+
+function defaultSdk$1() {
+    return `browser@${SDK_VERSION}`;
+}
+/**
+ * Start collecting page views: one `pv` beacon on initial load, then one per
+ * SPA navigation reported by the route provider. Idempotent — a second call is
+ * a no-op. Safe to call during SSR (no-ops without a DOM).
+ */ function inject(opts = {}) {
+    if (!hasDom()) return;
+    const st = state();
+    if (st.pv) return;
+    st.pv = true;
+    const provider = opts.routeProvider ?? defaultRouteProvider();
+    const debug = opts.debug ?? false;
+    const sdk = opts.sdk ?? defaultSdk$1();
+    emitPageview(provider.current(), "load", debug, sdk);
+    provider.onChange((info, nav)=>emitPageview(info, nav, debug, sdk));
+}
+function emitPageview(info, nav, debug, sdk) {
+    const beacon = {
+        v: 1,
+        k: "pv",
+        route: info.route,
+        path: stripQuery(info.path),
+        ref: referrerOrigin(),
+        utm: extractUtm(),
+        nav,
+        dc: deviceClass(),
+        sdk
+    };
+    report(beacon, debug);
+}
+
+function defaultSdk() {
+    return `browser@${SDK_VERSION}`;
+}
+/**
+ * Start collecting Core Web Vitals (LCP, CLS, INP, FCP, TTFB) via the
+ * `web-vitals` attribution build. Each metric reports once, finalized at
+ * page-hide for the field-only values (CLS, INP) — the queue's hidden-flush
+ * path carries those out. No FID (deprecated). Idempotent; no-ops during SSR.
+ */ function injectSpeedInsights(opts = {}) {
+    if (!hasDom()) return;
+    const st = state();
+    if (st.wv) return;
+    st.wv = true;
+    const provider = opts.routeProvider ?? defaultRouteProvider();
+    const debug = opts.debug ?? false;
+    const sdk = opts.sdk ?? defaultSdk();
+    const handler = (metric)=>emitVital(metric, provider, debug, sdk);
+    attribution.onLCP(handler);
+    attribution.onCLS(handler);
+    attribution.onINP(handler);
+    attribution.onFCP(handler);
+    attribution.onTTFB(handler);
+}
+function emitVital(metric, provider, debug, sdk) {
+    const info = provider.current();
+    const beacon = {
+        v: 1,
+        k: "wv",
+        route: info.route,
+        path: stripQuery(info.path),
+        ref: referrerOrigin(),
+        utm: extractUtm(),
+        nav: navFromMetric(metric.navigationType),
+        dc: deviceClass(),
+        sdk,
+        m: metric.name,
+        val: metricValue(metric),
+        rating: metric.rating
+    };
+    report(beacon, debug);
+}
+// web-vitals does not track SPA soft navigations, so a vital is only ever
+// "load" or "back-forward" (bfcache restores).
+function navFromMetric(navigationType) {
+    return navigationType === "back-forward" || navigationType === "back-forward-cache" ? "back-forward" : "load";
+}
+// CLS is unitless and small — keep four decimals. The millisecond metrics are
+// rounded to whole ms.
+function metricValue(metric) {
+    return metric.name === "CLS" ? Math.round(metric.value * 10000) / 10000 : Math.round(metric.value);
+}
+
+/**
+ * Custom events — phase 2 (howl-cloud/hostess-js#3). Exported now as a typed
+ * no-op so adapters can re-export it today and the real implementation lands
+ * without a breaking API change. Records nothing yet.
+ */ function track(_name, _props) {
+// Intentionally empty until custom-event ingest exists.
+}
+
+exports.SDK_VERSION = SDK_VERSION;
+exports.defaultRouteProvider = defaultRouteProvider;
+exports.inject = inject;
+exports.injectSpeedInsights = injectSpeedInsights;
+exports.track = track;

package/dist/index.d.ts

@@ -0,0 +1,106 @@
+type DeviceClass = "desktop" | "mobile" | "tablet";
+type NavType = "load" | "spa" | "back-forward";
+type BeaconKind = "pv" | "wv";
+type WebVitalName = "LCP" | "CLS" | "INP" | "FCP" | "TTFB";
+type Rating = "good" | "needs-improvement" | "poor";
+/** Template + concrete path for a page view. Query string is always stripped. */
+interface RouteInfo {
+    /** Route template, e.g. `/blog/[slug]`. Equals `path` when no adapter. */
+    route: string;
+    /** Concrete path, e.g. `/blog/hello-world`. Query string stripped. */
+    path: string;
+}
+/**
+ * The single framework-specific seam. Adapters (e.g. `@hostess/nextjs`)
+ * implement this to supply real route templates and navigation events; the
+ * default provider uses `location.pathname` for both `route` and `path`.
+ */
+interface RouteProvider {
+    current(): RouteInfo;
+    /** Subscribe to client-side navigations. Returns an unsubscribe function. */
+    onChange(cb: (info: RouteInfo, nav: "spa" | "back-forward") => void): () => void;
+}
+/** The five UTM parameters, extracted client-side. Only present keys are set. */
+interface Utm {
+    source?: string;
+    medium?: string;
+    campaign?: string;
+    term?: string;
+    content?: string;
+}
+interface BaseBeacon {
+    /** Schema version. */
+    v: 1;
+    /** Beacon kind: pageview or web vital. */
+    k: BeaconKind;
+    route: string;
+    path: string;
+    /** Referrer origin only, "" for same-origin/direct. */
+    ref: string;
+    utm: Utm;
+    nav: NavType;
+    /** Coarse device class (UA-CH with UA fallback). */
+    dc: DeviceClass;
+    /** `<adapter>@<version>`, e.g. `browser@0.1.0`. */
+    sdk: string;
+}
+interface PageviewBeacon extends BaseBeacon {
+    k: "pv";
+}
+interface WebVitalBeacon extends BaseBeacon {
+    k: "wv";
+    m: WebVitalName;
+    /** Value in ms; CLS is unitless. */
+    val: number;
+    rating: Rating;
+}
+type Beacon = PageviewBeacon | WebVitalBeacon;
+interface InjectOptions {
+    /** Adapter-supplied route source. Defaults to a `location.pathname` provider. */
+    routeProvider?: RouteProvider;
+    /** Log would-be payloads to the console; still sends unless in development. */
+    debug?: boolean;
+    /**
+     * Override the `sdk` field. Framework adapters pass their own identifier
+     * (e.g. `nextjs@0.2.0`); defaults to `browser@<version>`. Not part of the
+     * documented public surface — reserved for adapters.
+     */
+    sdk?: string;
+}
+
+/**
+ * Start collecting page views: one `pv` beacon on initial load, then one per
+ * SPA navigation reported by the route provider. Idempotent — a second call is
+ * a no-op. Safe to call during SSR (no-ops without a DOM).
+ */
+declare function inject(opts?: InjectOptions): void;
+
+/**
+ * Start collecting Core Web Vitals (LCP, CLS, INP, FCP, TTFB) via the
+ * `web-vitals` attribution build. Each metric reports once, finalized at
+ * page-hide for the field-only values (CLS, INP) — the queue's hidden-flush
+ * path carries those out. No FID (deprecated). Idempotent; no-ops during SSR.
+ */
+declare function injectSpeedInsights(opts?: InjectOptions): void;
+
+/**
+ * Custom events — phase 2 (howl-cloud/hostess-js#3). Exported now as a typed
+ * no-op so adapters can re-export it today and the real implementation lands
+ * without a breaking API change. Records nothing yet.
+ */
+declare function track(_name: string, _props?: Record<string, string | number | boolean>): void;
+
+/**
+ * Default provider with no framework knowledge: `location.pathname` is used as
+ * both the route template and the concrete path — correct for non-parameterized
+ * sites, and the ingest's route-hygiene caps absorb the rest. It also emits
+ * navigation changes (pushState/replaceState → "spa", popstate →
+ * "back-forward") so `inject()` is useful standalone in a bare SPA; adapters
+ * that supply real templates replace this entirely.
+ */
+declare function defaultRouteProvider(): RouteProvider;
+
+declare const SDK_VERSION = "0.1.0";
+
+export { SDK_VERSION, defaultRouteProvider, inject, injectSpeedInsights, track };
+export type { Beacon, BeaconKind, DeviceClass, InjectOptions, NavType, PageviewBeacon, Rating, RouteInfo, RouteProvider, Utm, WebVitalBeacon, WebVitalName };

package/dist/index.js

@@ -0,0 +1,411 @@
+import { onLCP, onCLS, onINP, onFCP, onTTFB } from 'web-vitals/attribution';
+
+/** True only in a real browser (guards against SSR / Node import). */ function hasDom() {
+    return typeof window !== "undefined" && typeof document !== "undefined";
+}
+/** True at the moment the page is hidden — the correctness-critical flush point. */ function isHidden() {
+    return typeof document !== "undefined" && document.visibilityState === "hidden";
+}
+/**
+ * `NODE_ENV=development` disables all beacons (bundlers inline this constant;
+ * the `typeof` guard keeps it safe when `process` is absent in the browser).
+ */ function isDevelopment() {
+    try {
+        return typeof process !== "undefined" && !!process.env && process.env.NODE_ENV === "development";
+    } catch  {
+        return false;
+    }
+}
+
+// Same-origin ingest path (howl-cloud/hostess#32). Never cross-origin, so no
+// CORS ever applies.
+const ENDPOINT = "/_hostess/rum";
+// Transport hard caps from schema v1: a request carries at most 20 beacons and
+// 8 KB. A flush is split into as many batches as needed to respect both.
+const MAX_BEACONS = 20;
+const MAX_BYTES = 8 * 1024;
+const encoder = typeof TextEncoder !== "undefined" ? new TextEncoder() : null;
+function byteLength(s) {
+    return encoder ? encoder.encode(s).length : s.length;
+}
+/** Greedily pack beacons into batches that respect both the count and byte caps. */ function splitBatches(beacons) {
+    const batches = [];
+    let current = [];
+    for (const beacon of beacons){
+        const candidate = current.length ? [
+            ...current,
+            beacon
+        ] : [
+            beacon
+        ];
+        const tooMany = candidate.length > MAX_BEACONS;
+        const tooBig = byteLength(JSON.stringify(candidate)) > MAX_BYTES;
+        if (current.length && (tooMany || tooBig)) {
+            batches.push(current);
+            current = [
+                beacon
+            ]; // a single beacon over 8 KB is unsplittable; send alone
+        } else {
+            current = candidate;
+        }
+    }
+    if (current.length) batches.push(current);
+    return batches;
+}
+/**
+ * Page-lifetime beacon queue. One instance per page (a window singleton shared
+ * by `inject` and `injectSpeedInsights`), so their beacons batch together.
+ *
+ * Flush triggers: the queue reaches `MAX_BEACONS`, the page transitions to
+ * hidden, or a beacon is enqueued while the page is already hidden. That last
+ * rule is what makes the CLS/INP path correct without depending on listener
+ * order: `web-vitals` finalizes those metrics inside its own
+ * `visibilitychange` handler, and whichever order the handlers run, a beacon
+ * pushed while hidden flushes immediately.
+ *
+ * Failure posture (fire-and-forget, back-off-and-stop): a disabled endpoint
+ * returns 404, but `navigator.sendBeacon`'s boolean only reports whether the UA
+ * queued the request, never the HTTP status. So the queue *probes* with an
+ * observable `fetch(keepalive)` until the first success; a 404 or network
+ * error there stops the queue for the rest of the page's life (silent and free
+ * after the first failure). Once the endpoint is confirmed live, it prefers
+ * `sendBeacon` — the only transport that reliably survives page unload.
+ */ class BeaconQueue {
+    push(beacon) {
+        if (this.stopped) return;
+        this.ensureListeners();
+        this.buffer.push(beacon);
+        if (this.buffer.length >= MAX_BEACONS || isHidden()) this.flush();
+    }
+    flush() {
+        if (this.stopped || this.buffer.length === 0) return;
+        const batches = splitBatches(this.buffer);
+        this.buffer = [];
+        for (const batch of batches)this.send(batch);
+    }
+    /** Halt all sending for the page lifetime and drop anything buffered. */ stop() {
+        this.stopped = true;
+        this.buffer = [];
+    }
+    ensureListeners() {
+        if (this.listening || typeof document === "undefined") return;
+        this.listening = true;
+        document.addEventListener("visibilitychange", ()=>{
+            if (isHidden()) this.flush();
+        });
+    }
+    send(batch) {
+        const body = JSON.stringify(batch);
+        // Fast path once the endpoint is confirmed live: sendBeacon survives unload.
+        if (this.verified && this.trySendBeacon(body)) return;
+        // Observable path: confirms the endpoint and detects a disabled one.
+        if (typeof fetch === "function") {
+            fetch(ENDPOINT, {
+                method: "POST",
+                body,
+                keepalive: true,
+                credentials: "omit",
+                // text/plain mirrors sendBeacon and keeps this a simple same-origin
+                // request; the ingest parses the JSON body regardless of content-type.
+                headers: {
+                    "Content-Type": "text/plain;charset=UTF-8"
+                }
+            }).then((res)=>{
+                if (res.ok) this.verified = true;
+                else this.stop();
+            }).catch(()=>this.stop());
+            return;
+        }
+        // No fetch available: last-resort sendBeacon (cannot observe the result).
+        if (!this.trySendBeacon(body)) this.stop();
+    }
+    trySendBeacon(body) {
+        const nav = typeof navigator !== "undefined" ? navigator : undefined;
+        if (!nav || typeof nav.sendBeacon !== "function") return false;
+        try {
+            return nav.sendBeacon(ENDPOINT, body);
+        } catch  {
+            return false;
+        }
+    }
+    constructor(){
+        this.buffer = [];
+        this.stopped = false;
+        this.verified = false;
+        this.listening = false;
+    }
+}
+
+const KEY = "__hostess_rum__";
+function state() {
+    const w = window;
+    return w[KEY] ??= {};
+}
+function getQueue() {
+    const st = state();
+    return st.queue ??= new BeaconQueue();
+}
+
+/** Strip the query string and hash, leaving only the path. */ function stripQuery(pathOrUrl) {
+    let end = pathOrUrl.length;
+    const q = pathOrUrl.indexOf("?");
+    const h = pathOrUrl.indexOf("#");
+    if (q >= 0) end = Math.min(end, q);
+    if (h >= 0) end = Math.min(end, h);
+    return pathOrUrl.slice(0, end);
+}
+// history.pushState / replaceState do not emit an event. Patch them once (per
+// page) to dispatch one, so the default provider can observe SPA navigations
+// without every provider stacking its own monkey-patch. popstate covers
+// back/forward natively.
+const LOCATION_CHANGE_EVENT = "hostess:locationchange";
+const HISTORY_PATCH_FLAG = "__hostess_history_patched__";
+function ensureHistoryEvents() {
+    const w = window;
+    if (w[HISTORY_PATCH_FLAG]) return;
+    w[HISTORY_PATCH_FLAG] = true;
+    for (const method of [
+        "pushState",
+        "replaceState"
+    ]){
+        const original = history[method];
+        history[method] = function(...args) {
+            const result = original.apply(this, args);
+            window.dispatchEvent(new Event(LOCATION_CHANGE_EVENT));
+            return result;
+        };
+    }
+}
+/**
+ * Default provider with no framework knowledge: `location.pathname` is used as
+ * both the route template and the concrete path — correct for non-parameterized
+ * sites, and the ingest's route-hygiene caps absorb the rest. It also emits
+ * navigation changes (pushState/replaceState → "spa", popstate →
+ * "back-forward") so `inject()` is useful standalone in a bare SPA; adapters
+ * that supply real templates replace this entirely.
+ */ function defaultRouteProvider() {
+    const read = ()=>{
+        const path = typeof location !== "undefined" ? location.pathname : "/";
+        return {
+            route: path,
+            path
+        };
+    };
+    return {
+        current: read,
+        onChange (cb) {
+            if (typeof window === "undefined") return ()=>{};
+            ensureHistoryEvents();
+            let last = location.pathname;
+            const emit = (nav)=>()=>{
+                    const path = location.pathname;
+                    if (path === last) return; // ignore hash-only / query-only changes
+                    last = path;
+                    cb({
+                        route: path,
+                        path
+                    }, nav);
+                };
+            const onSpa = emit("spa");
+            const onPop = emit("back-forward");
+            window.addEventListener(LOCATION_CHANGE_EVENT, onSpa);
+            window.addEventListener("popstate", onPop);
+            return ()=>{
+                window.removeEventListener(LOCATION_CHANGE_EVENT, onSpa);
+                window.removeEventListener("popstate", onPop);
+            };
+        }
+    };
+}
+
+/**
+ * Reduce a referrer URL to its origin only — never the path or query. Returns
+ * "" for direct visits, same-origin navigations, and non-http(s) schemes, so a
+ * beacon can never leak where on another site the visitor came from.
+ */ function referrerOrigin(ref) {
+    const raw = (typeof document !== "undefined" ? document.referrer : "");
+    if (!raw) return "";
+    let url;
+    try {
+        url = new URL(raw);
+    } catch  {
+        return "";
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") return "";
+    const here = typeof location !== "undefined" ? location.origin : "";
+    if (url.origin === here) return "";
+    return url.origin;
+}
+
+const UTM_KEYS = [
+    "source",
+    "medium",
+    "campaign",
+    "term",
+    "content"
+];
+// Matches the ingest's per-value cap; over-length values are truncated rather
+// than dropped so a long campaign name still attributes.
+const MAX_VALUE_LENGTH = 64;
+/**
+ * Extract the five `utm_*` parameters from a query string. Every other query
+ * parameter is ignored and never sent — this is the only place a raw query
+ * value crosses into a beacon.
+ */ function extractUtm(search) {
+    const qs = (typeof location !== "undefined" ? location.search : "");
+    const utm = {};
+    if (!qs) return utm;
+    let params;
+    try {
+        params = new URLSearchParams(qs);
+    } catch  {
+        return utm;
+    }
+    for (const key of UTM_KEYS){
+        const value = params.get(`utm_${key}`);
+        if (value != null && value !== "") {
+            utm[key] = value.slice(0, MAX_VALUE_LENGTH);
+        }
+    }
+    return utm;
+}
+
+/**
+ * Coarse device class from UA Client Hints with a UA-string fallback. Only
+ * three buckets — no model, no fingerprinting.
+ *
+ * Tablet is decided from the UA string first because UA-CH low-entropy hints
+ * have no tablet signal (an iPad reports `mobile: false`, indistinguishable
+ * from a desktop). Everything else prefers the `mobile` hint, falling back to
+ * UA-string keywords.
+ */ function deviceClass() {
+    const nav = typeof navigator !== "undefined" ? navigator : undefined;
+    const ua = nav?.userAgent ?? "";
+    if (/\bipad\b/i.test(ua) || /\btablet\b/i.test(ua) || /android/i.test(ua) && !/mobile/i.test(ua)) {
+        return "tablet";
+    }
+    const uaData = nav?.userAgentData;
+    if (uaData && typeof uaData.mobile === "boolean") {
+        return uaData.mobile ? "mobile" : "desktop";
+    }
+    if (/mobi|iphone|ipod|android/i.test(ua)) return "mobile";
+    return "desktop";
+}
+
+/**
+ * The single gate every beacon passes through.
+ *
+ * - `debug` logs the would-be payload (works even in development, so you can
+ *   verify what *would* be sent).
+ * - `NODE_ENV=development` is silent: it returns before the queue is ever
+ *   created, guaranteeing no network and no listeners in development.
+ */ function report(beacon, debug) {
+    if (debug) {
+        try {
+            console.log("[hostess/browser]", beacon);
+        } catch  {
+        // console unavailable — never let logging break the host page.
+        }
+    }
+    if (isDevelopment()) return;
+    getQueue().push(beacon);
+}
+
+// Bumped in lockstep with package.json on release. Surfaces in the `sdk`
+// beacon field as `browser@<version>` (framework adapters override the prefix).
+const SDK_VERSION = "0.1.0";
+
+function defaultSdk$1() {
+    return `browser@${SDK_VERSION}`;
+}
+/**
+ * Start collecting page views: one `pv` beacon on initial load, then one per
+ * SPA navigation reported by the route provider. Idempotent — a second call is
+ * a no-op. Safe to call during SSR (no-ops without a DOM).
+ */ function inject(opts = {}) {
+    if (!hasDom()) return;
+    const st = state();
+    if (st.pv) return;
+    st.pv = true;
+    const provider = opts.routeProvider ?? defaultRouteProvider();
+    const debug = opts.debug ?? false;
+    const sdk = opts.sdk ?? defaultSdk$1();
+    emitPageview(provider.current(), "load", debug, sdk);
+    provider.onChange((info, nav)=>emitPageview(info, nav, debug, sdk));
+}
+function emitPageview(info, nav, debug, sdk) {
+    const beacon = {
+        v: 1,
+        k: "pv",
+        route: info.route,
+        path: stripQuery(info.path),
+        ref: referrerOrigin(),
+        utm: extractUtm(),
+        nav,
+        dc: deviceClass(),
+        sdk
+    };
+    report(beacon, debug);
+}
+
+function defaultSdk() {
+    return `browser@${SDK_VERSION}`;
+}
+/**
+ * Start collecting Core Web Vitals (LCP, CLS, INP, FCP, TTFB) via the
+ * `web-vitals` attribution build. Each metric reports once, finalized at
+ * page-hide for the field-only values (CLS, INP) — the queue's hidden-flush
+ * path carries those out. No FID (deprecated). Idempotent; no-ops during SSR.
+ */ function injectSpeedInsights(opts = {}) {
+    if (!hasDom()) return;
+    const st = state();
+    if (st.wv) return;
+    st.wv = true;
+    const provider = opts.routeProvider ?? defaultRouteProvider();
+    const debug = opts.debug ?? false;
+    const sdk = opts.sdk ?? defaultSdk();
+    const handler = (metric)=>emitVital(metric, provider, debug, sdk);
+    onLCP(handler);
+    onCLS(handler);
+    onINP(handler);
+    onFCP(handler);
+    onTTFB(handler);
+}
+function emitVital(metric, provider, debug, sdk) {
+    const info = provider.current();
+    const beacon = {
+        v: 1,
+        k: "wv",
+        route: info.route,
+        path: stripQuery(info.path),
+        ref: referrerOrigin(),
+        utm: extractUtm(),
+        nav: navFromMetric(metric.navigationType),
+        dc: deviceClass(),
+        sdk,
+        m: metric.name,
+        val: metricValue(metric),
+        rating: metric.rating
+    };
+    report(beacon, debug);
+}
+// web-vitals does not track SPA soft navigations, so a vital is only ever
+// "load" or "back-forward" (bfcache restores).
+function navFromMetric(navigationType) {
+    return navigationType === "back-forward" || navigationType === "back-forward-cache" ? "back-forward" : "load";
+}
+// CLS is unitless and small — keep four decimals. The millisecond metrics are
+// rounded to whole ms.
+function metricValue(metric) {
+    return metric.name === "CLS" ? Math.round(metric.value * 10000) / 10000 : Math.round(metric.value);
+}
+
+/**
+ * Custom events — phase 2 (howl-cloud/hostess-js#3). Exported now as a typed
+ * no-op so adapters can re-export it today and the real implementation lands
+ * without a breaking API change. Records nothing yet.
+ */ function track(_name, _props) {
+// Intentionally empty until custom-event ingest exists.
+}
+
+export { SDK_VERSION, defaultRouteProvider, inject, injectSpeedInsights, track };

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@hostess/browser",
+  "version": "0.1.0",
+  "description": "Framework-agnostic browser core for Hostess Audience Analytics and Speed Insights.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/howl-cloud/hostess-js",
+    "directory": "packages/browser"
+  },
+  "homepage": "https://hostess.sh",
+  "bugs": "https://github.com/howl-cloud/hostess-js/issues",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "web-vitals": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "bunchee": "^6.11.0",
+    "jsdom": "^25.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build": "bunchee",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}