stitchkit 0.80.1 → 0.81.0

package/dist/tracking.js

@@ -0,0 +1,1090 @@
+import {
+  ApiError
+} from "./index-3xwxfj4z.js";
+import {
+  defineContract
+} from "./index-2bxcmqkb.js";
+import"./index-6k1937bx.js";
+import"./index-0w9abg87.js";
+import"./index-zcgf3gqf.js";
+import"./index-kzfs85xp.js";
+import"./index-77fekveh.js";
+
+// src/tracking/attribution.ts
+import { z as z2 } from "zod";
+
+// src/tracking/schemas.ts
+import { z } from "zod";
+var UtmDataSchema = z.object({
+  source: z.string().max(200).optional(),
+  medium: z.string().max(200).optional(),
+  campaign: z.string().max(200).optional(),
+  content: z.string().max(200).optional(),
+  term: z.string().max(200).optional()
+});
+var AttributionDataSchema = z.object({
+  utm: UtmDataSchema.optional(),
+  referrer: z.string().optional(),
+  landingPage: z.string().optional()
+});
+var DEFAULT_BUILD_ID_PATTERN = /^(dev|[a-f0-9]{7,40})$/;
+var TrackingDispositionStatusSchema = z.enum([
+  "accepted",
+  "duplicate",
+  "identity-invalid",
+  "excluded-bot"
+]);
+var TrackingDispositionSchema = z.object({
+  eventId: z.uuid(),
+  status: TrackingDispositionStatusSchema
+});
+var TrackEventsResponseSchema = z.object({
+  accepted: z.number().int().nonnegative(),
+  dispositions: z.array(TrackingDispositionSchema)
+});
+var VisitBootstrapResponseSchema = z.object({
+  visitId: z.uuid(),
+  expiresAt: z.iso.datetime()
+});
+var TrackingOutboxStateSchema = z.enum(["available", "unavailable"]);
+function trackingEventShape(eventTypes) {
+  return {
+    eventId: z.uuid(),
+    visitId: z.uuid(),
+    browserStreamId: z.uuid(),
+    browserSequence: z.number().int().nonnegative(),
+    type: z.enum(eventTypes),
+    page: z.string().max(2000),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+    clientTimestamp: z.number()
+  };
+}
+function visitEntryContextShape(buildIdPattern) {
+  return {
+    browserStreamId: z.uuid(),
+    previousVisitId: z.uuid().optional(),
+    origin: z.url().max(500),
+    landingPath: z.string().startsWith("/").max(300).regex(/^[^?#]*$/),
+    referrer: z.url().max(2000).optional(),
+    utm: UtmDataSchema.optional(),
+    displayMode: z.enum(["browser", "standalone"]),
+    screenWidth: z.number().int().positive().max(20000),
+    screenHeight: z.number().int().positive().max(20000),
+    buildId: z.string().regex(buildIdPattern),
+    outboxState: TrackingOutboxStateSchema,
+    outboxQueued: z.number().int().nonnegative().max(1000),
+    outboxDropped: z.number().int().nonnegative()
+  };
+}
+function createTrackingSchemas(config) {
+  const base = z.object(trackingEventShape(config.eventTypes));
+  const event = config.eventExtras ? base.extend(config.eventExtras.shape) : base;
+  const buildIdPattern = config.buildIdPattern ?? DEFAULT_BUILD_ID_PATTERN;
+  const maxEvents = config.maxEventsPerBatch ?? 50;
+  return {
+    event,
+    request: z.object({
+      buildId: z.string().regex(buildIdPattern),
+      events: z.array(event).min(1).max(maxEvents),
+      utm: UtmDataSchema.optional()
+    }),
+    response: TrackEventsResponseSchema,
+    disposition: TrackingDispositionSchema,
+    entry: z.object(visitEntryContextShape(buildIdPattern)),
+    bootstrap: VisitBootstrapResponseSchema
+  };
+}
+
+// src/tracking/attribution.ts
+var StoredTouchSchema = z2.object({ data: AttributionDataSchema, capturedAt: z2.number() });
+var StoredAttributionSchema = z2.object({
+  firstTouch: StoredTouchSchema,
+  currentTouch: StoredTouchSchema
+});
+function normalize(value) {
+  if (!value)
+    return;
+  return value.toLowerCase().trim().slice(0, 200) || undefined;
+}
+function parseUtmFromSearch(search) {
+  const params = new URLSearchParams(search);
+  const source = normalize(params.get("utm_source"));
+  if (!source)
+    return null;
+  return {
+    source,
+    medium: normalize(params.get("utm_medium")),
+    campaign: normalize(params.get("utm_campaign")),
+    content: normalize(params.get("utm_content")),
+    term: normalize(params.get("utm_term"))
+  };
+}
+function parseReferrer(referrer, currentHostname, referrerMap = []) {
+  if (!referrer)
+    return null;
+  try {
+    const hostname = new URL(referrer).hostname.toLowerCase();
+    if (hostname === currentHostname.toLowerCase())
+      return null;
+    const match = referrerMap.find((rule) => rule.pattern.test(hostname));
+    return match ? { source: match.source, medium: match.medium } : { source: hostname, medium: "referral" };
+  } catch {
+    return null;
+  }
+}
+function readStored(storage, key, now, ttlMs) {
+  try {
+    const raw = storage.getItem(key);
+    if (!raw)
+      return null;
+    const parsed = StoredAttributionSchema.safeParse(JSON.parse(raw));
+    if (!parsed.success || now - parsed.data.firstTouch.capturedAt > ttlMs) {
+      storage.removeItem(key);
+      return null;
+    }
+    return parsed.data;
+  } catch {
+    return null;
+  }
+}
+function writeStored(storage, key, value) {
+  try {
+    storage.setItem(key, JSON.stringify(value));
+  } catch {}
+}
+function resolveAttribution({
+  search,
+  referrer,
+  pathname,
+  hostname,
+  storage,
+  referrerMap = [],
+  storageKey = "tracking.attribution",
+  ttlMs = 90 * 24 * 60 * 60 * 1000,
+  now = Date.now()
+}) {
+  const stored = readStored(storage, storageKey, now, ttlMs);
+  const urlUtm = parseUtmFromSearch(search);
+  if (urlUtm) {
+    const currentTouch = {
+      utm: urlUtm,
+      referrer: referrer || undefined,
+      landingPage: pathname
+    };
+    const persisted = {
+      firstTouch: {
+        data: stored?.firstTouch.data ?? currentTouch,
+        capturedAt: stored?.firstTouch.capturedAt ?? now
+      },
+      currentTouch: { data: currentTouch, capturedAt: now }
+    };
+    writeStored(storage, storageKey, persisted);
+    return {
+      firstTouch: persisted.firstTouch.data,
+      currentTouch: persisted.currentTouch.data
+    };
+  }
+  if (stored)
+    return { firstTouch: stored.firstTouch.data, currentTouch: stored.currentTouch.data };
+  const fromReferrer = parseReferrer(referrer, hostname, referrerMap);
+  const firstTouch = {
+    utm: fromReferrer ? { source: fromReferrer.source, medium: fromReferrer.medium } : undefined,
+    referrer: referrer || undefined,
+    landingPage: pathname
+  };
+  writeStored(storage, storageKey, {
+    firstTouch: { data: firstTouch, capturedAt: now },
+    currentTouch: { data: firstTouch, capturedAt: now }
+  });
+  return { firstTouch, currentTouch: firstTouch };
+}
+// src/tracking/beacon.ts
+function sendUnloadBeacon(url, body, sender = typeof navigator === "undefined" ? undefined : navigator) {
+  if (!sender || typeof sender.sendBeacon !== "function")
+    return false;
+  return sender.sendBeacon(url, body);
+}
+// src/tracking/clicks.ts
+function label(target) {
+  return (target?.textContent ?? "").trim().slice(0, 100) || undefined;
+}
+function sanitizedHref(value, origin) {
+  if (!value)
+    return;
+  try {
+    const url = new URL(value, origin);
+    return url.origin === origin ? url.pathname : `${url.origin}${url.pathname}`;
+  } catch {
+    return;
+  }
+}
+function resolveTrackedClick(target, { origin, attributes = {}, isAction = () => true }) {
+  if (!target)
+    return null;
+  const trackAttribute = attributes.track ?? "data-track";
+  const actionAttribute = attributes.action ?? "data-track-action";
+  const contextAttribute = attributes.context ?? "data-track-context";
+  const tracked = target.closest(`[${trackAttribute}], [${actionAttribute}]`);
+  const anchor = target.closest("a[href]");
+  const href = anchor?.getAttribute("href") ?? tracked?.getAttribute("href") ?? null;
+  let sameOriginNavigation = false;
+  let outbound = false;
+  if (href) {
+    try {
+      const url = new URL(href, origin);
+      sameOriginNavigation = url.origin === origin;
+      outbound = url.protocol.startsWith("http") && !sameOriginNavigation;
+    } catch {
+      sameOriginNavigation = false;
+    }
+  }
+  const result = { leavesPage: sameOriginNavigation || outbound };
+  if (tracked) {
+    const action = tracked.getAttribute(actionAttribute);
+    const element = tracked.getAttribute(trackAttribute);
+    if (action && isAction(action)) {
+      result.interaction = {
+        action,
+        context: tracked.getAttribute(contextAttribute) ?? undefined
+      };
+    } else if (element) {
+      result.click = {
+        element,
+        elementText: label(tracked),
+        href: sanitizedHref(href, origin)
+      };
+    }
+  }
+  if (outbound && href) {
+    result.outbound = { href: sanitizedHref(href, origin) ?? href, label: label(anchor) };
+  }
+  return result.interaction || result.click || result.outbound ? result : null;
+}
+// src/tracking/delivery.ts
+function isRetryable(error) {
+  return ApiError.is(error) && (error.status === 0 || error.status >= 500);
+}
+function isUnauthorized(error) {
+  return ApiError.is(error) && (error.status === 401 || error.status === 403);
+}
+async function deliverTrackingBatch({
+  request,
+  onFailure,
+  onUnauthorized,
+  wait = (delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs)),
+  retryDelayMs = 250
+}) {
+  let recovered = false;
+  for (let attempt = 0;attempt < 2; attempt += 1) {
+    try {
+      await request();
+      return "delivered";
+    } catch (error) {
+      if (attempt === 0 && isRetryable(error)) {
+        await wait(retryDelayMs);
+        continue;
+      }
+      if (isUnauthorized(error) && onUnauthorized && !recovered) {
+        recovered = true;
+        if (await onUnauthorized())
+          continue;
+        return "auth-invalidated";
+      }
+      onFailure(error);
+      return "failed";
+    }
+  }
+  return "failed";
+}
+
+// src/tracking/scroll.ts
+function scrollDepthPercent(view) {
+  const scrollable = view.scrollHeight - view.innerHeight;
+  if (scrollable <= 0)
+    return 0;
+  return Math.max(0, Math.min(100, Math.round(view.scrollY / scrollable * 100)));
+}
+function createScrollMilestones(milestones = [25, 50, 75, 100]) {
+  const sorted = [...milestones].sort((a, b) => a - b);
+  let deepest = 0;
+  const fired = new Set;
+  return {
+    record(percent) {
+      deepest = Math.max(deepest, percent);
+    },
+    observe(percent) {
+      deepest = Math.max(deepest, percent);
+      const reached = [];
+      for (const milestone of sorted) {
+        if (deepest >= milestone && !fired.has(milestone)) {
+          fired.add(milestone);
+          reached.push(milestone);
+        }
+      }
+      return reached;
+    },
+    max: () => deepest,
+    reset() {
+      deepest = 0;
+      fired.clear();
+    }
+  };
+}
+
+// src/tracking/sequence-reserve.ts
+function createSequenceReserve(reserve, options = {}) {
+  const blockSize = options.blockSize ?? 16;
+  const lowWater = options.lowWater ?? 4;
+  const pool = [];
+  let pending = null;
+  let fallback = null;
+  const pushFallbackBlock = () => {
+    for (let i = 0;i < blockSize; i += 1) {
+      fallback = (fallback ?? 0) + 1;
+      pool.push(fallback);
+    }
+  };
+  const refill = () => {
+    if (pending)
+      return pending;
+    if (fallback !== null) {
+      pushFallbackBlock();
+      return Promise.resolve();
+    }
+    pending = reserve(blockSize).then((reserved) => {
+      pool.push(...reserved);
+    }).catch((error) => {
+      fallback = (options.fallbackBase ?? (() => Math.floor(Math.random() * 1e6)))() * 1e6;
+      options.onUnavailable?.(error);
+      pushFallbackBlock();
+    }).finally(() => {
+      pending = null;
+    });
+    return pending;
+  };
+  return {
+    take() {
+      const next = pool.shift() ?? null;
+      if (pool.length < lowWater)
+        refill();
+      return next;
+    },
+    refill,
+    shared: () => fallback === null,
+    reset() {
+      fallback = null;
+      pool.length = 0;
+    }
+  };
+}
+
+// src/tracking/visible-time.ts
+function createVisibleTimeMeter(options = {}) {
+  const now = options.now ?? (() => performance.now());
+  const wallClock = options.wallClock ?? (() => Date.now());
+  const randomUUID = options.randomUUID ?? (() => crypto.randomUUID());
+  let checkpointAt = now();
+  const cut = () => {
+    const at = now();
+    const activeDurationMs = Math.max(0, Math.round(at - checkpointAt));
+    checkpointAt = at;
+    return {
+      activeIntervalId: randomUUID(),
+      activeDurationMs,
+      intervalStartedAt: wallClock() - activeDurationMs
+    };
+  };
+  return {
+    checkpoint() {
+      checkpointAt = now();
+    },
+    cut,
+    heartbeat(visible) {
+      if (visible)
+        return { ...cut(), isVisible: true };
+      return { isVisible: false, activeDurationMs: 0 };
+    }
+  };
+}
+
+// src/tracking/client.ts
+var CONVENTIONAL_TRACKING_EVENT_TYPES = {
+  pageView: "PAGE_VIEW",
+  pageLeave: "PAGE_LEAVE",
+  scrollDepth: "SCROLL_DEPTH",
+  heartbeat: "SESSION_HEARTBEAT",
+  click: "CLICK",
+  outboundClick: "OUTBOUND_CLICK",
+  interaction: "INTERACTION"
+};
+function chunk(items, size) {
+  const chunks = [];
+  for (let at = 0;at < items.length; at += size)
+    chunks.push(items.slice(at, at + size));
+  return chunks;
+}
+function createTrackingClient(config) {
+  if (typeof config.buildId !== "string" || config.buildId.length === 0) {
+    throw new Error('[stitchkit] tracking client requires a buildId — a git SHA or "dev"');
+  }
+  const { host, builtin, outbox } = config;
+  const heartbeatMs = config.heartbeatMs ?? 30000;
+  const renewAfterHiddenMs = config.renewAfterHiddenMs ?? 30 * 60 * 1000;
+  const pendingLimit = config.pendingLimit ?? 100;
+  const batchSize = config.batchSize ?? 50;
+  const fail = config.onFailure ?? (() => {
+    return;
+  });
+  const decorate = config.decorate ?? ((event) => event);
+  const unload = config.unload ?? ((request) => config.unloadUrl === undefined ? false : sendUnloadBeacon(config.unloadUrl, JSON.stringify(request)));
+  let browserStreamId = null;
+  let visitId = null;
+  let outboxAvailable = outbox !== undefined;
+  let bootstrapping = null;
+  let pending = [];
+  let currentPage = null;
+  let attribution = null;
+  let running = 0;
+  const flushOwner = host.randomUUID();
+  const meter = createVisibleTimeMeter({
+    now: () => host.now(),
+    wallClock: () => host.wallClock(),
+    randomUUID: () => host.randomUUID()
+  });
+  const scroll = createScrollMilestones(config.scrollMilestones);
+  const sequences = createSequenceReserve((count) => {
+    if (!outbox || !outboxAvailable)
+      return Promise.reject(new Error("outbox unavailable"));
+    return outbox.reserveSequences(count);
+  }, {
+    ...config.sequence,
+    onUnavailable: outbox ? (error) => {
+      outboxAvailable = false;
+      fail("sequence reservation", error);
+    } : undefined
+  });
+  const currentUtm = () => attribution?.currentTouch.utm?.source ? attribution.currentTouch.utm : undefined;
+  const captureAttribution = (search, pathname) => {
+    if (!host.storage)
+      return null;
+    const page = host.page();
+    attribution = resolveAttribution({
+      search,
+      pathname,
+      referrer: page.referrer,
+      hostname: page.hostname,
+      storage: host.storage,
+      referrerMap: config.referrerMap,
+      now: host.wallClock()
+    });
+    return attribution;
+  };
+  const bootstrapVisit = (renew = false) => {
+    if (!renew && visitId && browserStreamId)
+      return Promise.resolve(visitId);
+    if (bootstrapping)
+      return bootstrapping;
+    const run = (async () => {
+      try {
+        const health = outbox ? await outbox.health() : { state: "unavailable", queued: 0, dropped: 0 };
+        const wasAvailable = outboxAvailable;
+        outboxAvailable = health.state === "available";
+        if (outboxAvailable && !wasAvailable && !sequences.shared())
+          sequences.reset();
+        browserStreamId = outboxAvailable && outbox ? await outbox.streamId() : browserStreamId ?? host.randomUUID();
+        await sequences.refill();
+        const page = host.page();
+        const touch = captureAttribution(page.search, page.pathname);
+        const response = await config.bootstrap({
+          browserStreamId,
+          previousVisitId: visitId ?? undefined,
+          origin: page.origin,
+          landingPath: page.pathname,
+          referrer: page.referrer || undefined,
+          utm: touch?.currentTouch.utm?.source ? touch.currentTouch.utm : undefined,
+          displayMode: page.displayMode,
+          screenWidth: page.screenWidth,
+          screenHeight: page.screenHeight,
+          buildId: config.buildId,
+          outboxState: health.state,
+          outboxQueued: health.queued,
+          outboxDropped: health.dropped
+        });
+        visitId = response.visitId;
+        config.onVisit?.(visitId);
+        return visitId;
+      } catch (error) {
+        fail("visit bootstrap", error);
+        return null;
+      } finally {
+        bootstrapping = null;
+      }
+    })();
+    bootstrapping = run;
+    return run;
+  };
+  const deliver = async (events) => {
+    let response = null;
+    const outcome = await deliverTrackingBatch({
+      request: async () => {
+        response = await config.deliver({
+          buildId: config.buildId,
+          events,
+          utm: currentUtm()
+        });
+      },
+      onUnauthorized: config.onUnauthorized,
+      onFailure: (error) => fail("event delivery", error)
+    });
+    return outcome === "delivered" ? response : null;
+  };
+  let flushing = null;
+  let queued = null;
+  const flushOutbox = () => {
+    if (!outbox || !outboxAvailable)
+      return Promise.resolve();
+    if (flushing) {
+      queued ??= flushing.then(() => {
+        queued = null;
+        return flushOutbox();
+      });
+      return queued;
+    }
+    flushing = (async () => {
+      try {
+        if (!await outbox.acquireLease(flushOwner))
+          return;
+        const batch = await outbox.readBatch(batchSize);
+        if (batch.length === 0)
+          return;
+        const response = await deliver(batch);
+        if (response) {
+          await outbox.acknowledge(response.dispositions.map((item) => item.eventId));
+        }
+      } catch (error) {
+        fail("outbox flush", error);
+      } finally {
+        flushing = null;
+      }
+    })();
+    return flushing;
+  };
+  const materialize = (draft2) => {
+    if (!visitId || !browserStreamId)
+      return null;
+    const sequence = sequences.take();
+    if (sequence === null)
+      return null;
+    return decorate({
+      ...draft2,
+      eventId: host.randomUUID(),
+      visitId,
+      browserStreamId,
+      browserSequence: sequence
+    });
+  };
+  const persistAndFlush = async (events) => {
+    if (!outbox || !outboxAvailable) {
+      for (const batch of chunk(events, batchSize))
+        await deliver(batch);
+      return;
+    }
+    try {
+      for (const event of events)
+        await outbox.enqueue(event);
+      await flushOutbox();
+    } catch (error) {
+      fail("event persistence", error);
+    }
+  };
+  const drainPending = () => {
+    const drafts = pending.splice(0);
+    if (drafts.length > 0)
+      send(drafts);
+  };
+  const send = (drafts) => {
+    if (!visitId || !browserStreamId) {
+      pending = [...pending, ...drafts].slice(-pendingLimit);
+      bootstrapVisit().then((issued) => {
+        if (issued)
+          drainPending();
+      });
+      return;
+    }
+    (async () => {
+      const events = [];
+      for (const draft2 of drafts) {
+        let event = materialize(draft2);
+        if (!event) {
+          await sequences.refill();
+          event = materialize(draft2);
+        }
+        if (event)
+          events.push(event);
+      }
+      if (events.length > 0)
+        await persistAndFlush(events);
+    })();
+  };
+  const sendOnUnload = (draft2) => {
+    const event = materialize(draft2);
+    if (!event) {
+      send([draft2]);
+      return;
+    }
+    unload({ buildId: config.buildId, events: [event], utm: currentUtm() });
+    if (outbox && outboxAvailable) {
+      outbox.enqueue(event).catch((error) => fail("unload event persistence", error));
+    }
+  };
+  const draft = (type, metadata) => ({
+    type,
+    page: currentPage ?? host.page().pathname,
+    metadata,
+    clientTimestamp: host.wallClock()
+  });
+  const leaveDraft = (page) => ({
+    type: builtin.pageLeave,
+    page,
+    metadata: { ...meter.cut(), scrollDepthPercent: scroll.max() },
+    clientTimestamp: host.wallClock()
+  });
+  function track(type, metadata) {
+    send([draft(type, metadata === undefined ? undefined : asMetadata(metadata))]);
+  }
+  const onNavigate = (pathname, search) => {
+    captureAttribution(search, pathname);
+    const previous = currentPage;
+    if (previous === pathname)
+      return;
+    if (previous && host.visible())
+      send([leaveDraft(previous)]);
+    currentPage = pathname;
+    meter.checkpoint();
+    scroll.reset();
+    const page = host.page();
+    send([
+      {
+        type: builtin.pageView,
+        page: pathname,
+        metadata: {
+          title: page.title,
+          screenWidth: page.viewportWidth,
+          screenHeight: page.viewportHeight,
+          referrer: previous ? undefined : page.referrer || undefined
+        },
+        clientTimestamp: host.wallClock()
+      }
+    ]);
+  };
+  const start = () => {
+    const generation = ++running;
+    const unsubscribe = [];
+    bootstrapVisit().then((issued) => {
+      if (!issued || generation !== running)
+        return;
+      drainPending();
+      flushOutbox();
+    });
+    const renewThenFlush = () => void bootstrapVisit(true).then(() => flushOutbox());
+    unsubscribe.push(host.on("online", renewThenFlush));
+    unsubscribe.push(host.interval(() => void flushOutbox(), heartbeatMs));
+    let hiddenAt = null;
+    let lastLeaveAt = Number.NEGATIVE_INFINITY;
+    const onHide = () => {
+      const at = host.now();
+      if (at - lastLeaveAt < 1000)
+        return;
+      lastLeaveAt = at;
+      sendOnUnload(leaveDraft(currentPage ?? host.page().pathname));
+      if (outbox && outboxAvailable)
+        outbox.releaseLease(flushOwner).catch(() => {
+          return;
+        });
+    };
+    unsubscribe.push(host.on("pagehide", onHide));
+    unsubscribe.push(host.on("visibilitychange", () => {
+      if (!host.visible()) {
+        hiddenAt = host.wallClock();
+        onHide();
+        return;
+      }
+      meter.checkpoint();
+      if (hiddenAt !== null && host.wallClock() - hiddenAt >= renewAfterHiddenMs) {
+        renewThenFlush();
+      }
+      hiddenAt = null;
+    }));
+    unsubscribe.push(host.interval(() => {
+      send([draft(builtin.heartbeat, { ...meter.heartbeat(host.visible()) })]);
+    }, heartbeatMs));
+    unsubscribe.push(host.on("scroll", () => scroll.record(host.scrollDepth())));
+    unsubscribe.push(host.interval(() => {
+      for (const milestone of scroll.observe(host.scrollDepth())) {
+        send([draft(builtin.scrollDepth, { maxPercent: milestone })]);
+      }
+    }, 2000));
+    unsubscribe.push(host.onClick((target) => {
+      const click = resolveTrackedClick(target, {
+        origin: host.page().origin,
+        attributes: config.clickAttributes,
+        isAction: config.isAction
+      });
+      if (!click)
+        return;
+      const drafts = [];
+      if (click.interaction)
+        drafts.push(draft(builtin.interaction, { ...click.interaction }));
+      if (click.click)
+        drafts.push(draft(builtin.click, { ...click.click }));
+      if (click.outbound)
+        drafts.push(draft(builtin.outboundClick, { ...click.outbound }));
+      if (click.leavesPage)
+        for (const item of drafts)
+          sendOnUnload(item);
+      else
+        send(drafts);
+    }));
+    return () => {
+      running += 1;
+      for (const off of unsubscribe.splice(0))
+        off();
+    };
+  };
+  return {
+    track,
+    onNavigate,
+    start,
+    visitId: () => visitId,
+    browserStreamId: () => browserStreamId,
+    attribution: () => attribution
+  };
+}
+function asMetadata(value) {
+  return typeof value === "object" && value !== null ? { ...value } : undefined;
+}
+// src/tracking/contract.ts
+function createTrackingContract(config) {
+  const schemas = createTrackingSchemas(config);
+  return defineContract({ prefix: config.prefix ?? "tracking", scope: config.scope }, {
+    bootstrap: {
+      method: "POST",
+      path: "/visit",
+      expose: ["HTTP"],
+      desc: "Issue or renew a browser visit lease",
+      input: schemas.entry,
+      output: schemas.bootstrap
+    },
+    track: {
+      method: "POST",
+      path: "/events",
+      desc: "Batch track browser events",
+      input: schemas.request,
+      output: schemas.response,
+      safelistedBody: true,
+      maxJsonBodyBytes: config.maxJsonBodyBytes ?? 256 * 1024
+    }
+  });
+}
+// src/tracking/host.ts
+function browserTrackingHost() {
+  return {
+    page: () => ({
+      pathname: window.location.pathname,
+      search: window.location.search,
+      origin: window.location.origin,
+      hostname: window.location.hostname,
+      title: document.title,
+      referrer: document.referrer,
+      viewportWidth: window.innerWidth,
+      viewportHeight: window.innerHeight,
+      screenWidth: window.screen.width,
+      screenHeight: window.screen.height,
+      displayMode: window.matchMedia("(display-mode: standalone)").matches ? "standalone" : "browser"
+    }),
+    visible: () => document.visibilityState === "visible",
+    scrollDepth() {
+      const scrollable = document.documentElement.scrollHeight - window.innerHeight;
+      if (scrollable <= 0)
+        return 0;
+      return Math.max(0, Math.min(100, Math.round(window.scrollY / scrollable * 100)));
+    },
+    on(event, handler) {
+      const target = event === "visibilitychange" ? document : window;
+      const options = event === "scroll" ? { passive: true } : undefined;
+      target.addEventListener(event, handler, options);
+      return () => target.removeEventListener(event, handler);
+    },
+    onClick(handler) {
+      const listener = (event) => {
+        handler(event.target instanceof Element ? event.target : null);
+      };
+      document.addEventListener("click", listener, { capture: true });
+      return () => document.removeEventListener("click", listener, { capture: true });
+    },
+    interval(handler, ms) {
+      const id = window.setInterval(handler, ms);
+      return () => window.clearInterval(id);
+    },
+    now: () => performance.now(),
+    wallClock: () => Date.now(),
+    randomUUID: () => crypto.randomUUID(),
+    storage: (() => {
+      try {
+        return window.localStorage;
+      } catch {
+        return null;
+      }
+    })()
+  };
+}
+// src/tracking/once-per-page.ts
+function createOncePerPage(options = {}) {
+  const windowMs = options.windowMs ?? 15000;
+  const now = options.now ?? (() => Date.now());
+  const seen = new Map;
+  return {
+    should(key, page) {
+      const scoped = `${page}|${key}`;
+      const at = now();
+      const last = seen.get(scoped);
+      if (last !== undefined && at - last < windowMs)
+        return false;
+      seen.set(scoped, at);
+      return true;
+    }
+  };
+}
+// src/tracking/outbox.ts
+var META_STREAM = "streamId";
+var META_SEQUENCE = "sequence";
+var META_LEASE = "lease";
+var META_DROPPED = "dropped";
+function numberOr(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function leaseOf(raw) {
+  if (typeof raw !== "object" || raw === null)
+    return null;
+  const owner = Reflect.get(raw, "owner");
+  const expiresAt = Reflect.get(raw, "expiresAt");
+  return typeof owner === "string" && typeof expiresAt === "number" ? { owner, expiresAt } : null;
+}
+function createTrackingOutbox(storage, options = {}) {
+  const maxEvents = options.maxEvents ?? 1000;
+  const maxAgeMs = options.maxAgeMs ?? 7 * 24 * 60 * 60 * 1000;
+  const leaseMs = options.leaseMs ?? 3000;
+  const now = options.now ?? (() => Date.now());
+  const randomUUID = options.randomUUID ?? (() => crypto.randomUUID());
+  const trim = () => storage.transact(async ({ meta, events }) => {
+    const all = await events.all();
+    const cutoff = now() - maxAgeMs;
+    const remove = all.filter((record, index) => record.enqueuedAt < cutoff || index < all.length - maxEvents);
+    for (const record of remove)
+      events.delete(record.event.eventId);
+    if (remove.length > 0) {
+      meta.put(META_DROPPED, numberOr(await meta.get(META_DROPPED), 0) + remove.length);
+    }
+  });
+  return {
+    streamId: () => storage.transact(async ({ meta }) => {
+      const existing = await meta.get(META_STREAM);
+      if (typeof existing === "string")
+        return existing;
+      const created = randomUUID();
+      meta.put(META_STREAM, created);
+      return created;
+    }),
+    reserveSequences: (count) => storage.transact(async ({ meta }) => {
+      const start = numberOr(await meta.get(META_SEQUENCE), 0) + 1;
+      meta.put(META_SEQUENCE, start + count - 1);
+      return Array.from({ length: count }, (_, index) => start + index);
+    }),
+    async enqueue(event) {
+      await storage.transact(async ({ events }) => {
+        events.put({ event, enqueuedAt: now() });
+      });
+      await trim();
+    },
+    acquireLease: (owner) => storage.transact(async ({ meta }) => {
+      const lease = leaseOf(await meta.get(META_LEASE));
+      const at = now();
+      const acquired = lease === null || lease.owner === owner || lease.expiresAt <= at;
+      if (acquired)
+        meta.put(META_LEASE, { owner, expiresAt: at + leaseMs });
+      return acquired;
+    }),
+    releaseLease: (owner) => storage.transact(async ({ meta }) => {
+      const lease = leaseOf(await meta.get(META_LEASE));
+      if (lease?.owner === owner)
+        meta.delete(META_LEASE);
+    }),
+    readBatch: (limit = 50) => storage.transact(async ({ events }) => (await events.all()).slice(0, limit).map((record) => record.event), "readonly"),
+    acknowledge: async (eventIds) => {
+      if (eventIds.length === 0)
+        return;
+      await storage.transact(async ({ events }) => {
+        for (const id of eventIds)
+          events.delete(id);
+      });
+    },
+    async health() {
+      try {
+        return await storage.transact(async ({ meta, events }) => ({
+          state: "available",
+          queued: await events.count(),
+          dropped: numberOr(await meta.get(META_DROPPED), 0)
+        }), "readonly");
+      } catch {
+        return { state: "unavailable", queued: 0, dropped: 0 };
+      }
+    }
+  };
+}
+// src/tracking/outbox-storage-indexeddb.ts
+var VERSION = 1;
+var EVENTS = "events";
+var META = "meta";
+function requestResult(request) {
+  return new Promise((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+  });
+}
+function transactionDone(transaction) {
+  return new Promise((resolve, reject) => {
+    transaction.oncomplete = () => resolve();
+    const failure = (event) => {
+      const target = event.target;
+      if (typeof target === "object" && target !== null && "error" in target && target.error instanceof Error) {
+        return target.error;
+      }
+      return transaction.error ?? new Error("IndexedDB transaction aborted");
+    };
+    transaction.onerror = (event) => reject(failure(event));
+    transaction.onabort = (event) => reject(failure(event));
+  });
+}
+function openDatabase(name, factory) {
+  return new Promise((resolve, reject) => {
+    const request = factory.open(name, VERSION);
+    request.onupgradeneeded = () => {
+      const database = request.result;
+      if (!database.objectStoreNames.contains(EVENTS)) {
+        const events = database.createObjectStore(EVENTS, { keyPath: "event.eventId" });
+        events.createIndex("sequence", "event.browserSequence", { unique: true });
+      }
+      if (!database.objectStoreNames.contains(META))
+        database.createObjectStore(META);
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+  });
+}
+function indexedDbOutboxStorage(name, factory = () => indexedDB) {
+  return {
+    async transact(fn, mode = "readwrite") {
+      const database = await openDatabase(name, factory());
+      try {
+        const transaction = database.transaction([META, EVENTS], mode);
+        const meta = transaction.objectStore(META);
+        const events = transaction.objectStore(EVENTS);
+        let result;
+        try {
+          result = await fn({
+            meta: {
+              get: (key) => requestResult(meta.get(key)),
+              put: (key, value) => void meta.put(value, key),
+              delete: (key) => void meta.delete(key)
+            },
+            events: {
+              put: (record) => void events.put(record),
+              delete: (eventId) => void events.delete(eventId),
+              all: async () => {
+                const raw = await requestResult(events.index("sequence").getAll());
+                return raw.flatMap((value) => isRecord(value) ? [value] : []);
+              },
+              count: () => requestResult(events.count())
+            }
+          });
+        } catch (error) {
+          transaction.abort();
+          throw error;
+        }
+        await transactionDone(transaction);
+        return result;
+      } finally {
+        database.close();
+      }
+    }
+  };
+}
+function isRecord(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const event = Reflect.get(value, "event");
+  return typeof Reflect.get(value, "enqueuedAt") === "number" && typeof event === "object" && event !== null && typeof Reflect.get(event, "eventId") === "string" && typeof Reflect.get(event, "browserSequence") === "number";
+}
+// src/tracking/outbox-storage-memory.ts
+function memoryOutboxStorage() {
+  let meta = new Map;
+  let events = new Map;
+  let chain = Promise.resolve();
+  return {
+    transact(fn) {
+      const run = chain.then(async () => {
+        const nextMeta = new Map(meta);
+        const nextEvents = new Map(events);
+        const result = await fn({
+          meta: {
+            get: async (key) => nextMeta.get(key),
+            put: (key, value) => void nextMeta.set(key, value),
+            delete: (key) => void nextMeta.delete(key)
+          },
+          events: {
+            put: (record) => void nextEvents.set(record.event.eventId, record),
+            delete: (eventId) => void nextEvents.delete(eventId),
+            all: async () => [...nextEvents.values()].sort((a, b) => a.event.browserSequence - b.event.browserSequence),
+            count: async () => nextEvents.size
+          }
+        });
+        meta = nextMeta;
+        events = nextEvents;
+        return result;
+      });
+      chain = run.catch(() => {
+        return;
+      });
+      return run;
+    }
+  };
+}
+export {
+  sendUnloadBeacon,
+  scrollDepthPercent,
+  resolveTrackedClick,
+  resolveAttribution,
+  parseUtmFromSearch,
+  parseReferrer,
+  memoryOutboxStorage,
+  indexedDbOutboxStorage,
+  deliverTrackingBatch,
+  createVisibleTimeMeter,
+  createTrackingSchemas,
+  createTrackingOutbox,
+  createTrackingContract,
+  createTrackingClient,
+  createSequenceReserve,
+  createScrollMilestones,
+  createOncePerPage,
+  browserTrackingHost,
+  VisitBootstrapResponseSchema,
+  UtmDataSchema,
+  TrackingOutboxStateSchema,
+  TrackingDispositionStatusSchema,
+  TrackingDispositionSchema,
+  TrackEventsResponseSchema,
+  DEFAULT_BUILD_ID_PATTERN,
+  CONVENTIONAL_TRACKING_EVENT_TYPES,
+  AttributionDataSchema
+};