@harness-fe/runtime 3.0.1

package/src/parent-inherit.ts

@@ -0,0 +1,54 @@
+/**
+ * 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;
+}
+
+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(): ParentInheritance {
+    if (typeof window === 'undefined') return {};
+    if (window.parent === window) return {};
+    try {
+        const p = window.parent as Window & {
+            __hfe_session_id__?: string;
+            __harness_fe_client__?: { tabId?: string; sessionId?: string };
+            __HARNESS_FE__?: { projectId?: string };
+        };
+        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/src/recording.ts

@@ -0,0 +1,88 @@
+import { record } from 'rrweb';
+import type { RrwebChunkPayload } from '@harness-fe/protocol';
+
+export { RRWEB_FULL_SNAPSHOT_TYPE, chunkHasFullSnapshot } from './rrweb-types.js';
+
+const FLUSH_MS = 5_000;
+const MAX_EVENTS = 200;
+
+export class RrwebRecorder {
+    private stopRecording?: () => void;
+    private flushTimer?: number;
+    private chunkSeq = 0;
+    private buffer: unknown[] = [];
+
+    constructor(private readonly onChunk: (chunk: RrwebChunkPayload) => void) {}
+
+    start(): void {
+        if (this.stopRecording) return;
+        this.stopRecording = record({
+            emit: (event: unknown) => this.push(event),
+            inlineImages: false,
+            recordCanvas: false,
+            collectFonts: false,
+            maskAllInputs: false,
+        });
+        this.flushTimer = window.setInterval(() => this.flush(), FLUSH_MS);
+    }
+
+    stop(): void {
+        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(): void {
+        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.
+        }
+    }
+
+    private push(event: unknown): void {
+        this.buffer.push(event);
+        if (this.buffer.length >= MAX_EVENTS) this.flush();
+    }
+
+    private flush(): void {
+        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: unknown): number | undefined {
+    if (event && typeof event === 'object' && 'timestamp' in event) {
+        const ts = (event as { timestamp?: unknown }).timestamp;
+        if (typeof ts === 'number') return ts;
+    }
+    return undefined;
+}

package/src/rrweb-types.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from 'vitest';
+import { chunkHasFullSnapshot, RRWEB_FULL_SNAPSHOT_TYPE } from './rrweb-types.js';
+
+describe('chunkHasFullSnapshot', () => {
+    it('returns true when any event has type 2 (FullSnapshot)', () => {
+        const chunk = {
+            events: [
+                { type: 4, timestamp: 1, data: {} }, // Meta
+                { type: 2, timestamp: 2, data: {} }, // FullSnapshot
+                { type: 3, timestamp: 3, data: {} }, // Incremental
+            ],
+        };
+        expect(chunkHasFullSnapshot(chunk)).toBe(true);
+    });
+
+    it('returns false when only incremental events present', () => {
+        const chunk = {
+            events: [
+                { type: 3, timestamp: 1, data: {} },
+                { type: 3, timestamp: 2, data: {} },
+            ],
+        };
+        expect(chunkHasFullSnapshot(chunk)).toBe(false);
+    });
+
+    it('returns false for empty events array', () => {
+        expect(chunkHasFullSnapshot({ events: [] })).toBe(false);
+    });
+
+    it('tolerates malformed events without throwing', () => {
+        const chunk = {
+            events: [null, undefined, 42, 'string', { noType: true }],
+        };
+        expect(chunkHasFullSnapshot(chunk)).toBe(false);
+    });
+
+    it('exports the canonical FullSnapshot type constant', () => {
+        expect(RRWEB_FULL_SNAPSHOT_TYPE).toBe(2);
+    });
+});

package/src/rrweb-types.ts

@@ -0,0 +1,24 @@
+/**
+ * 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: { events: readonly unknown[] }): boolean {
+    for (const ev of chunk.events) {
+        if (
+            ev &&
+            typeof ev === 'object' &&
+            (ev as { type?: unknown }).type === RRWEB_FULL_SNAPSHOT_TYPE
+        ) {
+            return true;
+        }
+    }
+    return false;
+}

package/src/selectors.test.ts

@@ -0,0 +1,50 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, beforeEach } from 'vitest';
+import { resolveSelector } from './selectors.js';
+
+beforeEach(() => {
+    document.body.innerHTML = `
+    <div>
+      <button class="primary" aria-label="submit">Submit</button>
+      <a href="/x">Link</a>
+      <input type="text" />
+      <span data-morphix-comp="SubmitButton" data-morphix-loc="src/Login.tsx:42:8">component target</span>
+    </div>
+  `;
+});
+
+describe('resolveSelector', () => {
+    it('resolves by css', () => {
+        const r = resolveSelector({ css: 'button.primary' });
+        expect(r.via).toBe('css');
+        expect((r.element as HTMLElement).textContent).toBe('Submit');
+    });
+
+    it('resolves by aria-label', () => {
+        const r = resolveSelector({ ariaLabel: 'submit' });
+        expect(r.via).toBe('aria');
+        expect((r.element as HTMLElement).tagName.toLowerCase()).toBe('button');
+    });
+
+    it('resolves by role + text', () => {
+        const r = resolveSelector({ role: 'button', text: 'Submit' });
+        expect(r.via).toBe('role-text');
+    });
+
+    it('resolves by component data attribute', () => {
+        const r = resolveSelector({ component: 'SubmitButton' });
+        expect(r.via).toBe('component-attr');
+        expect((r.element as HTMLElement).textContent).toBe('component target');
+    });
+
+    it('resolves by file:line', () => {
+        const r = resolveSelector({ file: 'src/Login.tsx', line: 42 });
+        expect(r.via).toBe('file');
+    });
+
+    it('returns null for no match', () => {
+        const r = resolveSelector({ css: '.does-not-exist' });
+        expect(r.element).toBeNull();
+        expect(r.via).toBe('none');
+    });
+});

package/src/selectors.ts

@@ -0,0 +1,103 @@
+/**
+ * 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 function resolveSelector(selector: Selector): ResolveResult {
+    const nth = selector.nth ?? 0;
+
+    if (selector.css) {
+        const list = document.querySelectorAll(selector.css);
+        if (list[nth]) return { element: list[nth] as Element, index: nth, via: 'css' };
+    }
+
+    if (selector.ariaLabel) {
+        const list = document.querySelectorAll(`[aria-label="${escapeCss(selector.ariaLabel)}"]`);
+        if (list[nth]) return { element: list[nth] as Element, 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] as Element, 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] as Element, index: nth, via: 'file' };
+    }
+
+    return { element: null, index: -1, via: 'none' };
+}
+
+function escapeCss(value: string): string {
+    return value.replace(/(["\\])/g, '\\$1');
+}
+
+function matchByRoleText(role?: string, text?: string): Element[] {
+    const all = Array.from(document.querySelectorAll<HTMLElement>('*'));
+    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: HTMLElement): string | undefined {
+    const tag = el.tagName.toLowerCase();
+    if (tag === 'button') return 'button';
+    if (tag === 'a' && el.hasAttribute('href')) return 'link';
+    if (tag === 'input') {
+        const type = (el as HTMLInputElement).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/src/snapshot.ts

@@ -0,0 +1,112 @@
+/**
+ * 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';
+
+const VALUE_CAP = 32 * 1024;
+const TOTAL_CAP = 256 * 1024;
+
+function readStorage(storage: Storage | null | undefined): {
+    data: Record<string, string>;
+    truncated: boolean;
+} {
+    if (!storage) return { data: {}, truncated: false };
+    const out: Record<string, string> = {};
+    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: string | null = 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(): { w: number; h: number; dpr: number } | undefined {
+    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(): PageLoadPayload['performance'] {
+    if (typeof performance === 'undefined') return undefined;
+    try {
+        const nav = performance.getEntriesByType?.('navigation')[0] as
+            | PerformanceNavigationTiming
+            | undefined;
+        if (!nav) return undefined;
+        return {
+            navigationStart: nav.startTime,
+            domContentLoaded: nav.domContentLoadedEventEnd,
+            loadEventEnd: nav.loadEventEnd,
+        };
+    } catch {
+        return undefined;
+    }
+}
+
+export function collectPageLoadSnapshot(sessionId: string): PageLoadPayload {
+    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/src/visitor.ts

@@ -0,0 +1,116 @@
+/**
+ * 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';
+
+const VISITOR_ID_KEY = '__hfe_visitor_id__';
+
+/** Read or lazily create the visitorId. localStorage scope = per-origin. */
+export function getOrCreateVisitorId(): string {
+    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(): string {
+    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(): string | undefined {
+    if (typeof window === 'undefined' || window.parent === window) return undefined;
+    try {
+        const p = window.parent as Window & {
+            localStorage?: Storage;
+            __harness_fe_visitor_id__?: string;
+        };
+        // 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(): VisitorEnv {
+    const screenObj = (typeof screen !== 'undefined' ? screen : undefined) as Screen | undefined;
+    const dprNow = typeof window !== 'undefined' ? window.devicePixelRatio || 1 : 1;
+    const colorScheme: 'light' | 'dark' | 'unknown' =
+        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 as Navigator & { platform: string }).platform
+                : undefined,
+    };
+}
+
+/** Expose to same-origin iframes; called by client.ts after resolving id. */
+export function publishVisitorIdToWindow(id: string): void {
+    if (typeof window === 'undefined') return;
+    (window as Window & { __harness_fe_visitor_id__?: string }).__harness_fe_visitor_id__ = id;
+}