@syntrologie/runtime-sdk 2.18.0 → 2.19.0

package/dist/observability/healthReporter.d.ts

@@ -9,6 +9,10 @@ export declare class HealthReporter {
     private timer;
     private pagehideHandler;
     private runtime;
+    /** Cleanup function for adapters that registered side effects (e.g. the
+     *  web-vitals long-task observer). Called from `stop()` so SPA re-init
+     *  via `initHealthReporter` doesn't accumulate observers. */
+    private adapterCleanup;
     constructor(config: HealthReporterConfig);
     /**
      * Bind runtime-derived attribute resolvers. Called after the canvas/telemetry
@@ -16,6 +20,13 @@ export declare class HealthReporter {
      * null-safe access at flush time.
      */
     bindRuntime(binding: ReporterRuntimeBinding): void;
+    /**
+     * Register a cleanup function to run on `stop()`. Used by adapters
+     * (e.g. webVitalsAdapter) that need to release per-bind resources
+     * like PerformanceObservers. Replaces any prior cleanup — only one
+     * adapter cleanup is tracked.
+     */
+    attachAdapterCleanup(cleanup: () => void): void;
     increment(signal: CounterSignal, by?: number): void;
     /**
      * @internal — exposed for test inspection only. Mid-window state is intentionally

package/dist/observability/index.d.ts

@@ -1,3 +1,5 @@
 export { getHealthReporter, HealthReporter, initHealthReporter } from './healthReporter';
 export { createOtlpEmitter } from './otlpEmitter';
+export { getSdkScriptUrl, getSdkScriptUrlPrefix } from './sdkScriptUrl';
 export type { CounterSignal, FlushPayload, HealthReporterConfig, HistogramSignal, ReporterResource, } from './types';
+export { bindWebVitals } from './webVitalsAdapter';

package/dist/observability/sdkScriptUrl.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The full URL of the SDK script, captured at module load. Returns
+ * `undefined` when the SDK is bundled into the host app (no separate
+ * `<script>` tag) or when running outside a browser.
+ */
+export declare function getSdkScriptUrl(): string | undefined;
+/**
+ * Directory prefix of the SDK script URL — useful for matching attribution
+ * entries from `PerformanceLongTaskTiming` against the SDK bundle and any
+ * sibling chunks (source maps, lazy-loaded adaptives) served from the same
+ * directory.
+ *
+ * Example: `https://cdn.syntrologie.com/runtime-sdk/v2/canary/smart-canvas.min.js`
+ *       → `https://cdn.syntrologie.com/runtime-sdk/v2/canary/`
+ */
+export declare function getSdkScriptUrlPrefix(): string | undefined;

package/dist/observability/types.d.ts

@@ -2,8 +2,23 @@
  * Names of signals the SDK emits. Add new entries as the taxonomy grows.
  * Counter signals are unbounded integers; histogram signals are millisecond floats.
  */
-export type CounterSignal = 'bootstrap_ok' | 'bootstrap_errors' | 'flag_fetch_count' | 'flag_fetch_errors';
-export type HistogramSignal = 'flag_fetch_latency_ms';
+export type CounterSignal = 'bootstrap_ok' | 'bootstrap_errors' | 'flag_fetch_count' | 'flag_fetch_errors' | 'longtasks_self_count'
+/** Cumulative blocking time (ms) from long tasks attributed to the SDK
+ *  script. Counter rather than histogram so HogQL sum() across windows
+ *  gives the total — which is what alerts/dashboards actually want. */
+ | 'longtasks_self_blocking_ms';
+/**
+ * Histogram signals. Web vitals are field-RUM measurements from the customer's
+ * browser, not synthetic Lighthouse audits — same metrics Lighthouse reports
+ * as "Core Web Vitals from CrUX," but measured live.
+ *
+ * - lcp_ms       — Largest Contentful Paint
+ * - inp_ms       — Interaction to Next Paint
+ * - cls_score    — Cumulative Layout Shift (unitless 0..1+)
+ * - fcp_ms       — First Contentful Paint
+ * - ttfb_ms      — Time to First Byte
+ */
+export type HistogramSignal = 'flag_fetch_latency_ms' | 'lcp_ms' | 'inp_ms' | 'cls_score' | 'fcp_ms' | 'ttfb_ms';
 /**
  * Resource attributes for the OTLP payload. The static fields are set at
  * reporter init; the dynamic fields are resolved at flush time via runtime

package/dist/observability/webVitalsAdapter.d.ts

@@ -0,0 +1,22 @@
+import type { HealthReporter } from './healthReporter';
+/**
+ * Bind the web-vitals callbacks to the given HealthReporter. Each metric
+ * fires once per session per metric (with possible BFCache reactivations).
+ *
+ * Idempotent across `Syntro.init()` re-calls: web-vitals subscriptions are
+ * registered once per page; later binds re-route to the most recent
+ * reporter via a window-scoped pointer. Long-task observers are per-bind
+ * and disposed via the returned cleanup function.
+ *
+ * Long-task tracking is opt-in via `attributedScriptUrlPrefix`: when the
+ * browser exposes long-task attribution and the offending script's URL
+ * starts with this prefix, the long task is counted toward the SDK's own
+ * blocking time. Pass the SDK script URL prefix (typically the CDN
+ * directory the bundle was loaded from).
+ *
+ * Safe to call in non-browser environments — returns a no-op cleanup
+ * function when `window` is unavailable.
+ */
+export declare function bindWebVitals(reporter: HealthReporter, options?: {
+    attributedScriptUrlPrefix?: string;
+}): () => void;