@harness-fe/runtime 3.0.1

package/dist/parent-inherit.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Same-origin iframe identity inheritance.
+ *
+ * Extracted from `client.ts` so unit tests don't have to load the rrweb
+ * recorder (rrweb has a CJS/ESM dual-shape that breaks happy-dom test envs).
+ */
+export interface ParentInheritance {
+    tabId?: string;
+    sessionId?: string;
+    parentProjectId?: string;
+}
+/**
+ * Reach across to a same-origin parent window to inherit the harness-fe
+ * identity triple (tabId, sessionId, parentProjectId). Cross-origin parents
+ * throw on property access; we catch and return {} so the child runtime
+ * silently falls back to generating its own ids.
+ *
+ * Resolution order for each field:
+ *   tabId            ← parent.__harness_fe_client__.tabId
+ *                    ← parent.sessionStorage.getItem('__hfe_tab_id__')
+ *   sessionId        ← parent.__hfe_session_id__
+ *                    ← parent.__harness_fe_client__.sessionId
+ *   parentProjectId  ← parent.__HARNESS_FE__.projectId
+ */
+export declare function tryInheritFromParent(): ParentInheritance;

package/dist/parent-inherit.js

@@ -0,0 +1,43 @@
+/**
+ * Same-origin iframe identity inheritance.
+ *
+ * Extracted from `client.ts` so unit tests don't have to load the rrweb
+ * recorder (rrweb has a CJS/ESM dual-shape that breaks happy-dom test envs).
+ */
+const TAB_ID_KEY = '__hfe_tab_id__';
+/**
+ * Reach across to a same-origin parent window to inherit the harness-fe
+ * identity triple (tabId, sessionId, parentProjectId). Cross-origin parents
+ * throw on property access; we catch and return {} so the child runtime
+ * silently falls back to generating its own ids.
+ *
+ * Resolution order for each field:
+ *   tabId            ← parent.__harness_fe_client__.tabId
+ *                    ← parent.sessionStorage.getItem('__hfe_tab_id__')
+ *   sessionId        ← parent.__hfe_session_id__
+ *                    ← parent.__harness_fe_client__.sessionId
+ *   parentProjectId  ← parent.__HARNESS_FE__.projectId
+ */
+export function tryInheritFromParent() {
+    if (typeof window === 'undefined')
+        return {};
+    if (window.parent === window)
+        return {};
+    try {
+        const p = window.parent;
+        const parentTabId = p.__harness_fe_client__?.tabId ??
+            p.sessionStorage?.getItem(TAB_ID_KEY) ??
+            undefined;
+        const parentSessionId = p.__hfe_session_id__ ??
+            p.__harness_fe_client__?.sessionId ??
+            undefined;
+        return {
+            tabId: parentTabId ?? undefined,
+            sessionId: parentSessionId ?? undefined,
+            parentProjectId: p.__HARNESS_FE__?.projectId,
+        };
+    }
+    catch {
+        return {};
+    }
+}

package/dist/recording.d.ts

@@ -0,0 +1,27 @@
+import type { RrwebChunkPayload } from '@harness-fe/protocol';
+export { RRWEB_FULL_SNAPSHOT_TYPE, chunkHasFullSnapshot } from './rrweb-types.js';
+export declare class RrwebRecorder {
+    private readonly onChunk;
+    private stopRecording?;
+    private flushTimer?;
+    private chunkSeq;
+    private buffer;
+    constructor(onChunk: (chunk: RrwebChunkPayload) => void);
+    start(): void;
+    stop(): void;
+    /**
+     * Force rrweb to emit a fresh Meta + FullSnapshot pair right now.
+     *
+     * Used by the client on every ws hello-ack so each new connection has its
+     * own baseline. Without this, the only FullSnapshot for the session is
+     * the one rrweb emits at `start()`; if that chunk gets evicted from the
+     * outbox (FIFO overflow) or lost because the daemon was down at the
+     * critical moment, the session is unreplayable for the rest of its life.
+     *
+     * Safe to call repeatedly — rrweb just emits another type:2 each time.
+     * No-op if the recorder hasn't been started.
+     */
+    takeFullSnapshot(): void;
+    private push;
+    private flush;
+}

package/dist/recording.js

@@ -0,0 +1,86 @@
+import { record } from 'rrweb';
+export { RRWEB_FULL_SNAPSHOT_TYPE, chunkHasFullSnapshot } from './rrweb-types.js';
+const FLUSH_MS = 5_000;
+const MAX_EVENTS = 200;
+export class RrwebRecorder {
+    onChunk;
+    stopRecording;
+    flushTimer;
+    chunkSeq = 0;
+    buffer = [];
+    constructor(onChunk) {
+        this.onChunk = onChunk;
+    }
+    start() {
+        if (this.stopRecording)
+            return;
+        this.stopRecording = record({
+            emit: (event) => this.push(event),
+            inlineImages: false,
+            recordCanvas: false,
+            collectFonts: false,
+            maskAllInputs: false,
+        });
+        this.flushTimer = window.setInterval(() => this.flush(), FLUSH_MS);
+    }
+    stop() {
+        if (this.flushTimer !== undefined) {
+            window.clearInterval(this.flushTimer);
+            this.flushTimer = undefined;
+        }
+        this.stopRecording?.();
+        this.stopRecording = undefined;
+        this.flush();
+    }
+    /**
+     * Force rrweb to emit a fresh Meta + FullSnapshot pair right now.
+     *
+     * Used by the client on every ws hello-ack so each new connection has its
+     * own baseline. Without this, the only FullSnapshot for the session is
+     * the one rrweb emits at `start()`; if that chunk gets evicted from the
+     * outbox (FIFO overflow) or lost because the daemon was down at the
+     * critical moment, the session is unreplayable for the rest of its life.
+     *
+     * Safe to call repeatedly — rrweb just emits another type:2 each time.
+     * No-op if the recorder hasn't been started.
+     */
+    takeFullSnapshot() {
+        if (!this.stopRecording)
+            return;
+        try {
+            record.takeFullSnapshot(true);
+        }
+        catch {
+            // rrweb may throw if DOM is in an unexpected state — never let
+            // that bubble up and break the host page.
+        }
+    }
+    push(event) {
+        this.buffer.push(event);
+        if (this.buffer.length >= MAX_EVENTS)
+            this.flush();
+    }
+    flush() {
+        if (this.buffer.length === 0)
+            return;
+        const events = this.buffer.splice(0, this.buffer.length);
+        const startTs = getEventTimestamp(events[0]) ?? Date.now();
+        const endTs = getEventTimestamp(events[events.length - 1]) ?? startTs;
+        this.chunkSeq += 1;
+        this.onChunk({
+            chunkId: `rrc_${this.chunkSeq.toString().padStart(6, '0')}`,
+            startTs,
+            endTs,
+            eventCount: events.length,
+            events,
+        });
+    }
+}
+function getEventTimestamp(event) {
+    if (event && typeof event === 'object' && 'timestamp' in event) {
+        const ts = event.timestamp;
+        if (typeof ts === 'number')
+            return ts;
+    }
+    return undefined;
+}

package/dist/rrweb-types.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Pure helpers around rrweb event types — no rrweb import.
+ *
+ * rrweb itself is browser-only and dies on import in Node test contexts
+ * (transitively requires `document`/CommonJS shenanigans), so we keep
+ * anything that needs to be unit-testable in a separate module.
+ */
+/** rrweb event types: 2 = FullSnapshot baseline. */
+export declare const RRWEB_FULL_SNAPSHOT_TYPE = 2;
+/** True if any event in the chunk is an rrweb FullSnapshot (type:2). */
+export declare function chunkHasFullSnapshot(chunk: {
+    events: readonly unknown[];
+}): boolean;

package/dist/rrweb-types.js

@@ -0,0 +1,20 @@
+/**
+ * Pure helpers around rrweb event types — no rrweb import.
+ *
+ * rrweb itself is browser-only and dies on import in Node test contexts
+ * (transitively requires `document`/CommonJS shenanigans), so we keep
+ * anything that needs to be unit-testable in a separate module.
+ */
+/** rrweb event types: 2 = FullSnapshot baseline. */
+export const RRWEB_FULL_SNAPSHOT_TYPE = 2;
+/** True if any event in the chunk is an rrweb FullSnapshot (type:2). */
+export function chunkHasFullSnapshot(chunk) {
+    for (const ev of chunk.events) {
+        if (ev &&
+            typeof ev === 'object' &&
+            ev.type === RRWEB_FULL_SNAPSHOT_TYPE) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/selectors.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Selector resolution in the page. Phase A: CSS / role+text / ariaLabel /
+ * compile-time data-morphix-comp attribute (set by future vite-plugin AST
+ * transform — Phase B). file:line + runtime fiber lookup land in Phase B/C.
+ */
+import type { Selector } from '@harness-fe/protocol';
+export interface ResolveResult {
+    element: Element | null;
+    /** Index used when multiple matched (for diagnostics). */
+    index: number;
+    /** How we found it (for diagnostics). */
+    via: 'css' | 'aria' | 'role-text' | 'component-attr' | 'file' | 'none';
+}
+export declare function resolveSelector(selector: Selector): ResolveResult;

package/dist/selectors.js

@@ -0,0 +1,91 @@
+/**
+ * Selector resolution in the page. Phase A: CSS / role+text / ariaLabel /
+ * compile-time data-morphix-comp attribute (set by future vite-plugin AST
+ * transform — Phase B). file:line + runtime fiber lookup land in Phase B/C.
+ */
+export function resolveSelector(selector) {
+    const nth = selector.nth ?? 0;
+    if (selector.css) {
+        const list = document.querySelectorAll(selector.css);
+        if (list[nth])
+            return { element: list[nth], index: nth, via: 'css' };
+    }
+    if (selector.ariaLabel) {
+        const list = document.querySelectorAll(`[aria-label="${escapeCss(selector.ariaLabel)}"]`);
+        if (list[nth])
+            return { element: list[nth], index: nth, via: 'aria' };
+    }
+    if (selector.role || selector.text) {
+        const candidates = matchByRoleText(selector.role, selector.text);
+        if (candidates[nth]) {
+            return { element: candidates[nth], index: nth, via: 'role-text' };
+        }
+    }
+    if (selector.component) {
+        const list = document.querySelectorAll(`[data-morphix-comp="${escapeCss(selector.component)}"]`);
+        if (list[nth]) {
+            return { element: list[nth], index: nth, via: 'component-attr' };
+        }
+    }
+    if (selector.file) {
+        const lineSuffix = selector.line ? `:${selector.line}` : '';
+        const list = document.querySelectorAll(`[data-morphix-loc^="${escapeCss(selector.file)}${lineSuffix}"]`);
+        if (list[nth])
+            return { element: list[nth], index: nth, via: 'file' };
+    }
+    return { element: null, index: -1, via: 'none' };
+}
+function escapeCss(value) {
+    return value.replace(/(["\\])/g, '\\$1');
+}
+function matchByRoleText(role, text) {
+    const all = Array.from(document.querySelectorAll('*'));
+    return all.filter((el) => {
+        if (role) {
+            const elRole = el.getAttribute('role') ?? implicitRole(el);
+            if (elRole !== role)
+                return false;
+        }
+        if (text) {
+            // Use the element's own direct text (child text nodes only) for an
+            // exact match first, then fall back to full textContent for a
+            // contains-match. This prevents parent elements (e.g. <nav>,
+            // <ul>) from being returned ahead of the actual target element
+            // just because their textContent happens to include the search
+            // string via a descendant.
+            const directText = Array.from(el.childNodes)
+                .filter((n) => n.nodeType === Node.TEXT_NODE)
+                .map((n) => n.textContent ?? '')
+                .join('')
+                .trim();
+            const fullText = (el.textContent ?? '').trim();
+            const exactMatch = directText === text || fullText === text;
+            const containsMatch = directText.includes(text) || fullText.includes(text);
+            if (!exactMatch && !containsMatch)
+                return false;
+        }
+        return true;
+    });
+}
+function implicitRole(el) {
+    const tag = el.tagName.toLowerCase();
+    if (tag === 'button')
+        return 'button';
+    if (tag === 'a' && el.hasAttribute('href'))
+        return 'link';
+    if (tag === 'input') {
+        const type = el.type;
+        if (type === 'checkbox')
+            return 'checkbox';
+        if (type === 'radio')
+            return 'radio';
+        if (type === 'button' || type === 'submit')
+            return 'button';
+        return 'textbox';
+    }
+    if (tag === 'textarea')
+        return 'textbox';
+    if (tag === 'select')
+        return 'combobox';
+    return undefined;
+}

package/dist/snapshot.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Initial-state snapshot for a single page load. Collected once after
+ * `hello.ack` and emitted as the first event of the load.
+ *
+ * Caps:
+ *  - Single value: 32 KB → truncated with a placeholder
+ *  - Entire snapshot: 256 KB → marked truncated, late keys dropped
+ *
+ * No business code is modified by this helper.
+ */
+import type { PageLoadPayload } from '@harness-fe/protocol';
+export declare function collectPageLoadSnapshot(sessionId: string): PageLoadPayload;

package/dist/snapshot.js

@@ -0,0 +1,111 @@
+/**
+ * Initial-state snapshot for a single page load. Collected once after
+ * `hello.ack` and emitted as the first event of the load.
+ *
+ * Caps:
+ *  - Single value: 32 KB → truncated with a placeholder
+ *  - Entire snapshot: 256 KB → marked truncated, late keys dropped
+ *
+ * No business code is modified by this helper.
+ */
+const VALUE_CAP = 32 * 1024;
+const TOTAL_CAP = 256 * 1024;
+function readStorage(storage) {
+    if (!storage)
+        return { data: {}, truncated: false };
+    const out = {};
+    let total = 0;
+    let truncated = false;
+    let i = 0;
+    try {
+        for (i = 0; i < storage.length; i++) {
+            const key = storage.key(i);
+            if (key === null)
+                continue;
+            let value = null;
+            try {
+                value = storage.getItem(key);
+            }
+            catch {
+                continue;
+            }
+            if (value === null)
+                continue;
+            let trimmed = value;
+            if (trimmed.length > VALUE_CAP) {
+                trimmed = trimmed.slice(0, VALUE_CAP);
+                truncated = true;
+            }
+            if (total + trimmed.length > TOTAL_CAP) {
+                truncated = true;
+                break;
+            }
+            out[key] = trimmed;
+            total += trimmed.length;
+        }
+    }
+    catch {
+        // Storage access can throw (e.g. blocked third-party cookies).
+        truncated = true;
+    }
+    return { data: out, truncated };
+}
+function readViewport() {
+    if (typeof window === 'undefined')
+        return undefined;
+    try {
+        return {
+            w: Math.floor(window.innerWidth ?? 0),
+            h: Math.floor(window.innerHeight ?? 0),
+            dpr: window.devicePixelRatio ?? 1,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function readPerformance() {
+    if (typeof performance === 'undefined')
+        return undefined;
+    try {
+        const nav = performance.getEntriesByType?.('navigation')[0];
+        if (!nav)
+            return undefined;
+        return {
+            navigationStart: nav.startTime,
+            domContentLoaded: nav.domContentLoadedEventEnd,
+            loadEventEnd: nav.loadEventEnd,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function collectPageLoadSnapshot(sessionId) {
+    const local = readStorage(typeof localStorage !== 'undefined' ? localStorage : null);
+    const session = readStorage(typeof sessionStorage !== 'undefined' ? sessionStorage : null);
+    let cookie = '';
+    try {
+        cookie = typeof document !== 'undefined' ? document.cookie : '';
+    }
+    catch {
+        cookie = '';
+    }
+    return {
+        sessionId,
+        page: {
+            url: typeof location !== 'undefined' ? location.href : undefined,
+            title: typeof document !== 'undefined' ? document.title : undefined,
+            referrer: typeof document !== 'undefined' ? document.referrer : undefined,
+            userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : undefined,
+        },
+        viewport: readViewport(),
+        storage: {
+            local: local.data,
+            session: session.data,
+            cookie,
+            truncated: local.truncated || session.truncated,
+        },
+        performance: readPerformance(),
+    };
+}

package/dist/visitor.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Visitor identity + environment capture.
+ *
+ * `visitorId` is an opaque UUID persisted in `localStorage.__hfe_visitor_id__`
+ * (per-origin, per-browser). It stitches a user's activity across pageloads,
+ * refreshes, and tabs so the daemon can build a coherent user journey.
+ *
+ * Privacy: anonymous by default. No canvas / WebGL / AudioContext
+ * fingerprinting. The app may pass `userId` via `HarnessScript userId=…`
+ * which the daemon attaches to `VisitorMeta.userId` — that field is only
+ * meaningful when the host app explicitly opts in.
+ */
+import type { VisitorEnv } from '@harness-fe/protocol';
+/** Read or lazily create the visitorId. localStorage scope = per-origin. */
+export declare function getOrCreateVisitorId(): string;
+/**
+ * Same-origin iframe child inherits the parent's visitorId so the journey
+ * stitches across micro-frontends. Cross-origin children fall back to their
+ * own (a different visitorId — expected, browsers isolate localStorage).
+ */
+export declare function tryInheritVisitorFromParent(): string | undefined;
+/**
+ * Snapshot the browser environment for this pageload. Cheap (all sync
+ * reads); safe to call on every hello.
+ */
+export declare function collectEnv(): VisitorEnv;
+/** Expose to same-origin iframes; called by client.ts after resolving id. */
+export declare function publishVisitorIdToWindow(id: string): void;

package/dist/visitor.js

@@ -0,0 +1,107 @@
+/**
+ * Visitor identity + environment capture.
+ *
+ * `visitorId` is an opaque UUID persisted in `localStorage.__hfe_visitor_id__`
+ * (per-origin, per-browser). It stitches a user's activity across pageloads,
+ * refreshes, and tabs so the daemon can build a coherent user journey.
+ *
+ * Privacy: anonymous by default. No canvas / WebGL / AudioContext
+ * fingerprinting. The app may pass `userId` via `HarnessScript userId=…`
+ * which the daemon attaches to `VisitorMeta.userId` — that field is only
+ * meaningful when the host app explicitly opts in.
+ */
+const VISITOR_ID_KEY = '__hfe_visitor_id__';
+/** Read or lazily create the visitorId. localStorage scope = per-origin. */
+export function getOrCreateVisitorId() {
+    try {
+        const existing = localStorage.getItem(VISITOR_ID_KEY);
+        if (existing && existing.length > 0)
+            return existing;
+        const id = generateVisitorId();
+        localStorage.setItem(VISITOR_ID_KEY, id);
+        return id;
+    }
+    catch {
+        // localStorage can throw on iOS Safari private mode / disabled storage.
+        // Fall back to an in-memory ephemeral id so events still flow.
+        return generateVisitorId();
+    }
+}
+function generateVisitorId() {
+    try {
+        return `v_${crypto.randomUUID()}`;
+    }
+    catch {
+        return `v_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 12)}`;
+    }
+}
+/**
+ * Same-origin iframe child inherits the parent's visitorId so the journey
+ * stitches across micro-frontends. Cross-origin children fall back to their
+ * own (a different visitorId — expected, browsers isolate localStorage).
+ */
+export function tryInheritVisitorFromParent() {
+    if (typeof window === 'undefined' || window.parent === window)
+        return undefined;
+    try {
+        const p = window.parent;
+        // Prefer the runtime-exposed global; fall back to parent's localStorage
+        // when the parent's runtime hasn't yet exposed the cache (race).
+        if (p.__harness_fe_visitor_id__)
+            return p.__harness_fe_visitor_id__;
+        const fromLs = p.localStorage?.getItem(VISITOR_ID_KEY);
+        return fromLs ?? undefined;
+    }
+    catch {
+        // SecurityError when cross-origin — expected, swallow.
+        return undefined;
+    }
+}
+/**
+ * Snapshot the browser environment for this pageload. Cheap (all sync
+ * reads); safe to call on every hello.
+ */
+export function collectEnv() {
+    const screenObj = (typeof screen !== 'undefined' ? screen : undefined);
+    const dprNow = typeof window !== 'undefined' ? window.devicePixelRatio || 1 : 1;
+    const colorScheme = typeof window !== 'undefined' && typeof window.matchMedia === 'function'
+        ? window.matchMedia('(prefers-color-scheme: dark)').matches
+            ? 'dark'
+            : 'light'
+        : 'unknown';
+    const reducedMotion = typeof window !== 'undefined' && typeof window.matchMedia === 'function'
+        ? window.matchMedia('(prefers-reduced-motion: reduce)').matches
+        : false;
+    return {
+        userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : '',
+        language: typeof navigator !== 'undefined' ? navigator.language : 'en',
+        languages: typeof navigator !== 'undefined' && navigator.languages
+            ? Array.from(navigator.languages)
+            : [],
+        timezone: typeof Intl !== 'undefined' && Intl.DateTimeFormat
+            ? (Intl.DateTimeFormat().resolvedOptions().timeZone ?? 'UTC')
+            : 'UTC',
+        timezoneOffsetMin: new Date().getTimezoneOffset(),
+        screen: {
+            width: screenObj?.width ?? 0,
+            height: screenObj?.height ?? 0,
+            dpr: dprNow,
+            colorDepth: screenObj?.colorDepth,
+        },
+        viewport: {
+            width: typeof window !== 'undefined' ? window.innerWidth : 0,
+            height: typeof window !== 'undefined' ? window.innerHeight : 0,
+        },
+        colorScheme,
+        reducedMotion,
+        platform: typeof navigator !== 'undefined' && 'platform' in navigator
+            ? navigator.platform
+            : undefined,
+    };
+}
+/** Expose to same-origin iframes; called by client.ts after resolving id. */
+export function publishVisitorIdToWindow(id) {
+    if (typeof window === 'undefined')
+        return;
+    window.__harness_fe_visitor_id__ = id;
+}

package/dist/xhrPatch.d.ts

@@ -0,0 +1,26 @@
+/**
+ * XMLHttpRequest monkey-patch — captures URL/method/headers/body for
+ * request and response WITHOUT replacing the XMLHttpRequest constructor.
+ *
+ * The previous implementation wrapped `window.XMLHttpRequest` with a new
+ * constructor, which broke `xhr instanceof XMLHttpRequest` checks in
+ * business code. This patch attaches per-instance metadata via a
+ * non-enumerable Symbol key and overrides only prototype methods, leaving
+ * the constructor and prototype chain native.
+ *
+ * Capture rules mirror fetchPatch.ts:
+ *  - 256 KB body cap with content-type routing (json / text / binary)
+ *  - Sensitive header redaction (Authorization / Cookie / x-api-key / x-auth-*)
+ *  - Two events per request keyed by a shared `id` (`phase: 'req' | 'res'`)
+ *  - Errors inside capture are swallowed via `safeEmit`
+ *  - `__hfeInternal` opt-out via a magic header `x-hfe-internal: 1`
+ *    (XHR has no init-style options bag like fetch)
+ *  - Idempotent install + dispose() restores original prototype methods
+ */
+import type { NetworkEntry } from '@harness-fe/protocol';
+export interface XhrPatchOptions {
+    onEntry: (entry: NetworkEntry) => void;
+    bodyCap?: number;
+    denylist?: RegExp[];
+}
+export declare function installXhrPatch(opts: XhrPatchOptions): () => void;