@scalebun/web 1.0.0

package/dist/features/coach/CoachmarkFeature.d.ts

@@ -0,0 +1,78 @@
+import type { TourSpec, TourContext } from './types';
+export interface CoachmarkDeps {
+    trackEvent: (name: string, props?: Record<string, unknown>) => void;
+    replayCoord: () => {
+        sessionId?: string;
+        seq?: number;
+        t?: number;
+    } | undefined;
+    /** For fetching dashboard-authored tours from the config lane (startById). Optional. */
+    apiBaseUrl?: string;
+    clientKey?: string;
+}
+type CoachEvent = {
+    event: string;
+} & Record<string, unknown>;
+export declare class CoachmarkFeature {
+    private readonly deps;
+    private readonly hub;
+    private readonly renderer;
+    private readonly engine;
+    private readonly listeners;
+    private toursCache;
+    constructor(deps: CoachmarkDeps);
+    start(tour: TourSpec, opts?: {
+        resume?: boolean;
+        context?: TourContext;
+    }): void;
+    /**
+     * Tell the dashboard which anchors this page actually has.
+     *
+     * Authors had to type an anchor key from memory into an empty box — so `checkout` when the code
+     * said `checkout-btn` published happily and the step silently degraded to a modal. Reporting the
+     * real keys turns that box into a list of what exists.
+     *
+     * Rides the normal analytics lane as `$coachmark_anchor_seen`, one event per key, so it needs no
+     * new endpoint and no table — the coach analytics service already reads `$coachmark_*` from the
+     * Event table.
+     *
+     * DEDUPED PER SESSION. A tour that restarts, or a SPA that re-renders, must not re-emit the same
+     * keys: the value is the SET of anchors, not a count of sightings, and an undeduped version would
+     * put a per-render event stream into the customer's analytics for no extra information.
+     *
+     * Safe to call as often as you like. Typically once after `init()` during integration; `start()`
+     * also calls it.
+     */
+    reportAnchors(): void;
+    /** Keys already reported this page-lifetime — see `reportAnchors`. */
+    private readonly reportedAnchors;
+    /** Fetch dashboard-published tours from the config lane. Best-effort — [] on any failure. Cached,
+     *  except a `preview` token (a one-off draft test) always does a fresh, un-cached fetch. */
+    fetchTours(preview?: string): Promise<TourSpec[]>;
+    /** Start a dashboard-authored tour by id. Returns false if the tour isn't published/found. Pass a
+     *  `preview` token (from the dashboard) to run a DRAFT tour before it's published. */
+    startById(id: string, opts?: {
+        resume?: boolean;
+        context?: TourContext;
+        preview?: string;
+    }): Promise<boolean>;
+    next(): void;
+    back(): void;
+    skip(): void;
+    end(): void;
+    notify(event: string): void;
+    current(): {
+        tourId: string | null;
+        index: number;
+        status: string;
+    };
+    /** Subscribe to a specific `$coachmark_*` event, or `'*'` for all. Returns an unsubscribe fn. */
+    on(event: string, cb: (e: CoachEvent) => void): () => void;
+    private emit;
+    private progress;
+    private persist;
+    private loadIndex;
+    dispose(): void;
+}
+export {};
+//# sourceMappingURL=CoachmarkFeature.d.ts.map

package/dist/features/coach/CoachmarkFeature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CoachmarkFeature.d.ts","sourceRoot":"","sources":["../../../src/features/coach/CoachmarkFeature.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAErD,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACpE,WAAW,EAAE,MAAM;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IAChF,wFAAwF;IACxF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,KAAK,UAAU,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAG9D,qBAAa,gBAAgB;IAOf,OAAO,CAAC,QAAQ,CAAC,IAAI;IANjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqB;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuB;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmD;IAC7E,OAAO,CAAC,UAAU,CAA2B;gBAEhB,IAAI,EAAE,aAAa;IAchD,KAAK,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,IAAI;IAM/E;;;;;;;;;;;;;;;;;OAiBG;IACH,aAAa,IAAI,IAAI;IAQrB,sEAAsE;IACtE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IAErD;gGAC4F;IACtF,UAAU,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAgBvD;0FACsF;IAChF,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,WAAW,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAMnH,IAAI,IAAI,IAAI;IACZ,IAAI,IAAI,IAAI;IACZ,IAAI,IAAI,IAAI;IACZ,GAAG,IAAI,IAAI;IACX,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAC3B,OAAO,IAAI;QAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE;IAInE,iGAAiG;IACjG,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,GAAG,MAAM,IAAI;IAO1D,OAAO,CAAC,IAAI;IAUZ,OAAO,CAAC,QAAQ;IAGhB,OAAO,CAAC,OAAO;IAOf,OAAO,CAAC,SAAS;IAIjB,OAAO,IAAI,IAAI;CAMhB"}

package/dist/features/coach/CoachmarkFeature.js

@@ -0,0 +1,161 @@
+/**
+ * CoachmarkFeature (B2.3) — the lazy orchestrator wiring B1 (anchor/wait) + B2 (TourEngine + renderer).
+ * Fully lazy like PushFeature (NOT in the FEATURES manifest) — the facade loads it on first
+ * `ScaleBun.coachmarks()` use, so an app that never runs a tour pays ~zero eager cost. Every lifecycle
+ * event is replayCoord-stamped (the moat: watch the exact replay frame a user abandoned a step).
+ */
+import { ObserverHub } from './observers';
+import { CoachRenderer } from './overlay';
+import { TourEngine } from './tour';
+import { resolveAnchor, collectAnchorKeys } from './anchor';
+import { waitFor } from './wait';
+const PROGRESS_KEY = 'scalebun_coach_progress';
+export class CoachmarkFeature {
+    constructor(deps) {
+        this.deps = deps;
+        this.hub = new ObserverHub();
+        this.renderer = new CoachRenderer();
+        this.listeners = new Map();
+        this.toursCache = null;
+        /** Keys already reported this page-lifetime — see `reportAnchors`. */
+        this.reportedAnchors = new Set();
+        this.engine = new TourEngine({
+            hub: this.hub,
+            resolveAnchor: (spec) => resolveAnchor(spec),
+            waitFor: (getEl, opts, hub) => waitFor(getEl, opts, hub),
+            render: (ctx) => this.renderer.render(ctx),
+            hide: () => this.renderer.hide(),
+            emit: (name, props) => this.emit(name, props),
+            now: () => Date.now(),
+            persist: (id, i) => this.persist(id, i),
+            loadIndex: (id) => this.loadIndex(id),
+        });
+    }
+    start(tour, opts) {
+        // Keep the dashboard's anchor list fresh from real usage, not just from an explicit setup call.
+        this.reportAnchors();
+        this.engine.start(tour, opts);
+    }
+    /**
+     * Tell the dashboard which anchors this page actually has.
+     *
+     * Authors had to type an anchor key from memory into an empty box — so `checkout` when the code
+     * said `checkout-btn` published happily and the step silently degraded to a modal. Reporting the
+     * real keys turns that box into a list of what exists.
+     *
+     * Rides the normal analytics lane as `$coachmark_anchor_seen`, one event per key, so it needs no
+     * new endpoint and no table — the coach analytics service already reads `$coachmark_*` from the
+     * Event table.
+     *
+     * DEDUPED PER SESSION. A tour that restarts, or a SPA that re-renders, must not re-emit the same
+     * keys: the value is the SET of anchors, not a count of sightings, and an undeduped version would
+     * put a per-render event stream into the customer's analytics for no extra information.
+     *
+     * Safe to call as often as you like. Typically once after `init()` during integration; `start()`
+     * also calls it.
+     */
+    reportAnchors() {
+        for (const key of collectAnchorKeys()) {
+            if (this.reportedAnchors.has(key))
+                continue;
+            this.reportedAnchors.add(key);
+            this.emit('$coachmark_anchor_seen', { anchorKey: key });
+        }
+    }
+    /** Fetch dashboard-published tours from the config lane. Best-effort — [] on any failure. Cached,
+     *  except a `preview` token (a one-off draft test) always does a fresh, un-cached fetch. */
+    async fetchTours(preview) {
+        if (!preview && this.toursCache)
+            return this.toursCache;
+        const { apiBaseUrl, clientKey } = this.deps;
+        if (!apiBaseUrl || !clientKey || typeof fetch === 'undefined')
+            return preview ? [] : (this.toursCache = []);
+        try {
+            const url = `${apiBaseUrl}/sdk/coach/config${preview ? `?preview=${encodeURIComponent(preview)}` : ''}`;
+            const res = await fetch(url, { headers: { 'x-scalebun-client-key': clientKey }, cache: 'no-store' });
+            if (!res.ok)
+                return preview ? [] : (this.toursCache = []);
+            const data = (await res.json());
+            const tours = data.tours ?? [];
+            return preview ? tours : (this.toursCache = tours);
+        }
+        catch {
+            return preview ? [] : (this.toursCache = []);
+        }
+    }
+    /** Start a dashboard-authored tour by id. Returns false if the tour isn't published/found. Pass a
+     *  `preview` token (from the dashboard) to run a DRAFT tour before it's published. */
+    async startById(id, opts) {
+        const tour = (await this.fetchTours(opts?.preview)).find((t) => t.id === id);
+        if (!tour)
+            return false;
+        this.engine.start(tour, opts);
+        return true;
+    }
+    next() { this.engine.next(); }
+    back() { this.engine.back(); }
+    skip() { this.engine.skip(); }
+    end() { this.engine.end('abandoned', 'api'); }
+    notify(event) { this.engine.notify(event); }
+    current() {
+        return this.engine.state;
+    }
+    /** Subscribe to a specific `$coachmark_*` event, or `'*'` for all. Returns an unsubscribe fn. */
+    on(event, cb) {
+        let set = this.listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        set.add(cb);
+        return () => { this.listeners.get(event)?.delete(cb); };
+    }
+    emit(name, props) {
+        const rc = this.deps.replayCoord();
+        const payload = { ...props, ...(rc ? { replayCoord: rc } : {}) };
+        this.deps.trackEvent(name, payload); // → analytics lane (funnel + replay deep-link)
+        const e = { event: name, ...payload };
+        for (const cb of this.listeners.get(name) ?? []) {
+            try {
+                cb(e);
+            }
+            catch { /* host cb threw */ }
+        }
+        for (const cb of this.listeners.get('*') ?? []) {
+            try {
+                cb(e);
+            }
+            catch { /* host cb threw */ }
+        }
+    }
+    // ── durable resume (localStorage — a tiny {tourId: index} map) ──
+    progress() {
+        try {
+            return JSON.parse(localStorage.getItem(PROGRESS_KEY) || '{}');
+        }
+        catch {
+            return {};
+        }
+    }
+    persist(tourId, index) {
+        try {
+            const p = this.progress();
+            if (index < 0)
+                delete p[tourId];
+            else
+                p[tourId] = index;
+            localStorage.setItem(PROGRESS_KEY, JSON.stringify(p));
+        }
+        catch { /* storage unavailable */ }
+    }
+    loadIndex(tourId) {
+        return this.progress()[tourId];
+    }
+    dispose() {
+        this.engine.dispose();
+        this.renderer.hide();
+        this.hub.dispose();
+        this.listeners.clear();
+    }
+}
+//# sourceMappingURL=CoachmarkFeature.js.map

package/dist/features/coach/CoachmarkFeature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CoachmarkFeature.js","sourceRoot":"","sources":["../../../src/features/coach/CoachmarkFeature.ts"],"names":[],"mappings":"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"}

package/dist/features/coach/anchor.d.ts

@@ -0,0 +1,32 @@
+/**
+ * AnchorEngine (B1.2) — the reliability moat. A target is a PRIORITIZED list of strategies (selector →
+ * data-attr → text → aria → xpath → nth), tried in order; the first hit wins. When the primary fails but
+ * a lower strategy resolves, that's "self-healing" (the caller emits $coachmark_anchor_healed so the
+ * dashboard can auto-suggest fixing the brittle primary selector — a feedback loop no competitor has).
+ * Traversal pierces open shadow roots (composed), which Pendo/Appcues mostly can't. Pure DOM, no deps.
+ */
+import type { AnchorSpec, AnchorResult } from './types';
+type Scope = Document | ShadowRoot | Element;
+/**
+ * Every `data-scalebun-anchor` key currently on the page.
+ *
+ * WHY THIS EXISTS. Declaring an anchor in code — `data-scalebun-anchor="checkout"` on web,
+ * `<ScaleBunAnchor anchorKey="checkout">` on React Native — is the stable way to mark a tour target:
+ * a CSS rebuild renames classes, it does not rename a data attribute. But the dashboard made an
+ * author TYPE that key into an empty box with no idea what the developers had actually added, so
+ * `checkout` vs `checkout-btn` published happily and the step silently degraded to a modal.
+ *
+ * Enumerating what really exists turns that text box into a list of real choices, on both platforms.
+ * Reported through the normal analytics lane (see `CoachmarkFeature.reportAnchors`) so it needs no
+ * new endpoint and no table.
+ *
+ * Pierces shadow roots for the same reason the resolvers do — a design-system app keeps most of its
+ * buttons inside one.
+ */
+export declare function collectAnchorKeys(root?: Scope, limit?: number): string[];
+/** Resolve a spec to an element, trying each strategy in order. `strategyIndex > 0` ⇒ self-healed. */
+export declare function resolveAnchor(spec: AnchorSpec, root?: Scope): AnchorResult;
+/** Convenience: did resolution fall back past the primary strategy? (drives the heal telemetry). */
+export declare function didHeal(r: AnchorResult): boolean;
+export {};
+//# sourceMappingURL=anchor.d.ts.map

package/dist/features/coach/anchor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchor.d.ts","sourceRoot":"","sources":["../../../src/features/coach/anchor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,UAAU,EAAkB,YAAY,EAAE,MAAM,SAAS,CAAC;AAExE,KAAK,KAAK,GAAG,QAAQ,GAAG,UAAU,GAAG,OAAO,CAAC;AAkE7C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,GAAE,KAAyE,EAC/E,KAAK,SAAM,GACV,MAAM,EAAE,CAYV;AAED,sGAAsG;AACtG,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,GAAE,KAAyE,GAAG,YAAY,CAS7I;AAED,oGAAoG;AACpG,wBAAgB,OAAO,CAAC,CAAC,EAAE,YAAY,GAAG,OAAO,CAEhD"}

package/dist/features/coach/anchor.js

@@ -0,0 +1,128 @@
+function esc(v) {
+    return typeof CSS !== 'undefined' && CSS.escape ? CSS.escape(v) : v.replace(/["\\]/g, '\\$&');
+}
+/** All elements under `root` matching `sel`, descending into open shadow roots when `pierce`. */
+function collectMatching(root, sel, pierce, out = []) {
+    try {
+        for (const e of [...root.querySelectorAll(sel)])
+            out.push(e);
+    }
+    catch { /* invalid selector */ }
+    if (pierce) {
+        for (const el of [...root.querySelectorAll('*')]) {
+            const sr = el.shadowRoot;
+            if (sr)
+                collectMatching(sr, sel, pierce, out);
+        }
+    }
+    return out;
+}
+/** First match of `sel` (light DOM fast-path, then shadow roots). */
+function queryDeep(root, sel, pierce) {
+    let hit = null;
+    try {
+        hit = root.querySelector(sel);
+    }
+    catch {
+        return null;
+    }
+    if (hit)
+        return hit;
+    if (!pierce)
+        return null;
+    for (const el of [...root.querySelectorAll('*')]) {
+        const sr = el.shadowRoot;
+        if (sr) {
+            const h = queryDeep(sr, sel, true);
+            if (h)
+                return h;
+        }
+    }
+    return null;
+}
+function byText(root, value, scope, pierce) {
+    const want = value.trim();
+    const matches = collectMatching(root, scope ?? '*', pierce).filter((e) => (e.textContent ?? '').trim() === want);
+    if (!matches.length)
+        return null;
+    // Most specific = fewest element descendants (the innermost element with exactly this text).
+    return matches.reduce((best, e) => (e.querySelectorAll('*').length < best.querySelectorAll('*').length ? e : best));
+}
+function byAria(root, role, name, pierce) {
+    const sel = role ? `[role="${esc(role)}"]` : 'button,a,[role],input,select,textarea,summary';
+    const cands = collectMatching(root, sel, pierce);
+    if (!name)
+        return cands[0] ?? null;
+    const want = name.trim();
+    return cands.find((e) => ((e.getAttribute('aria-label') ?? e.textContent ?? '').trim()) === want) ?? null;
+}
+function byXPath(value) {
+    if (typeof document === 'undefined' || !document.evaluate)
+        return null;
+    try {
+        const r = document.evaluate(value, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
+        return r.singleNodeValue ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function resolveStrategy(s, root, pierce) {
+    switch (s.kind) {
+        case 'selector': return queryDeep(root, s.value, pierce);
+        case 'data-attr': return queryDeep(root, `[data-scalebun-anchor="${esc(s.value)}"]`, pierce);
+        case 'nth': return collectMatching(root, s.selector, pierce)[s.index] ?? null;
+        case 'text': return byText(root, s.value, s.scope, pierce);
+        case 'aria': return byAria(root, s.role, s.name, pierce);
+        case 'xpath': return byXPath(s.value);
+    }
+}
+/**
+ * Every `data-scalebun-anchor` key currently on the page.
+ *
+ * WHY THIS EXISTS. Declaring an anchor in code — `data-scalebun-anchor="checkout"` on web,
+ * `<ScaleBunAnchor anchorKey="checkout">` on React Native — is the stable way to mark a tour target:
+ * a CSS rebuild renames classes, it does not rename a data attribute. But the dashboard made an
+ * author TYPE that key into an empty box with no idea what the developers had actually added, so
+ * `checkout` vs `checkout-btn` published happily and the step silently degraded to a modal.
+ *
+ * Enumerating what really exists turns that text box into a list of real choices, on both platforms.
+ * Reported through the normal analytics lane (see `CoachmarkFeature.reportAnchors`) so it needs no
+ * new endpoint and no table.
+ *
+ * Pierces shadow roots for the same reason the resolvers do — a design-system app keeps most of its
+ * buttons inside one.
+ */
+export function collectAnchorKeys(root = typeof document !== 'undefined' ? document : undefined, limit = 200) {
+    if (!root)
+        return [];
+    const seen = new Set();
+    for (const el of collectMatching(root, '[data-scalebun-anchor]', true)) {
+        const key = el.getAttribute('data-scalebun-anchor')?.trim();
+        // A blank attribute is a mistake, not an anchor — it would resolve to nothing and confuse the
+        // list it appears in.
+        if (key)
+            seen.add(key);
+        // Bounded: a mis-templated attribute inside a long list must not produce thousands of events.
+        if (seen.size >= limit)
+            break;
+    }
+    return [...seen].sort();
+}
+/** Resolve a spec to an element, trying each strategy in order. `strategyIndex > 0` ⇒ self-healed. */
+export function resolveAnchor(spec, root = typeof document !== 'undefined' ? document : undefined) {
+    const pierce = spec.shadowPiercing !== false;
+    let tried = 0;
+    for (let i = 0; i < spec.strategies.length; i++) {
+        tried++;
+        const el = root ? resolveStrategy(spec.strategies[i], root, pierce) : null;
+        if (el)
+            return { el, strategyIndex: i, strategiesTried: tried };
+    }
+    return { el: null, strategyIndex: -1, strategiesTried: tried };
+}
+/** Convenience: did resolution fall back past the primary strategy? (drives the heal telemetry). */
+export function didHeal(r) {
+    return r.el != null && r.strategyIndex > 0;
+}
+//# sourceMappingURL=anchor.js.map

package/dist/features/coach/anchor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchor.js","sourceRoot":"","sources":["../../../src/features/coach/anchor.ts"],"names":[],"mappings":"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"}

package/dist/features/coach/observers.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ObserverHub (B1.3) — ONE shared MutationObserver across every active wait/step (perf: not one per
+ * anchor). Subscribers are re-notified, coalesced to a single microtask, whenever the DOM mutates — this
+ * is what lets the WaitEngine re-check pending anchors as a lazy/SPA/virtualized DOM fills in. Degrades to
+ * a no-op (poll-only) where MutationObserver is unavailable.
+ */
+export declare class ObserverHub {
+    private mo;
+    private readonly subs;
+    private scheduled;
+    private start;
+    /** Subscribe to DOM mutations. Returns an unsubscribe fn. Starts the observer on first subscriber. */
+    onChange(cb: () => void): () => void;
+    private notify;
+    dispose(): void;
+}
+//# sourceMappingURL=observers.d.ts.map

package/dist/features/coach/observers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observers.d.ts","sourceRoot":"","sources":["../../../src/features/coach/observers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,EAAE,CAAiC;IAC3C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyB;IAC9C,OAAO,CAAC,SAAS,CAAS;IAE1B,OAAO,CAAC,KAAK;IAMb,sGAAsG;IACtG,QAAQ,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IASpC,OAAO,CAAC,MAAM;IASd,OAAO,IAAI,IAAI;CAKhB"}

package/dist/features/coach/observers.js

@@ -0,0 +1,49 @@
+/**
+ * ObserverHub (B1.3) — ONE shared MutationObserver across every active wait/step (perf: not one per
+ * anchor). Subscribers are re-notified, coalesced to a single microtask, whenever the DOM mutates — this
+ * is what lets the WaitEngine re-check pending anchors as a lazy/SPA/virtualized DOM fills in. Degrades to
+ * a no-op (poll-only) where MutationObserver is unavailable.
+ */
+export class ObserverHub {
+    constructor() {
+        this.mo = null;
+        this.subs = new Set();
+        this.scheduled = false;
+    }
+    start() {
+        if (this.mo || typeof MutationObserver === 'undefined' || typeof document === 'undefined')
+            return;
+        this.mo = new MutationObserver(() => this.notify());
+        this.mo.observe(document.documentElement, { subtree: true, childList: true, attributes: true });
+    }
+    /** Subscribe to DOM mutations. Returns an unsubscribe fn. Starts the observer on first subscriber. */
+    onChange(cb) {
+        this.subs.add(cb);
+        this.start();
+        return () => {
+            this.subs.delete(cb);
+            if (!this.subs.size)
+                this.dispose();
+        };
+    }
+    notify() {
+        if (this.scheduled)
+            return;
+        this.scheduled = true;
+        queueMicrotask(() => {
+            this.scheduled = false;
+            for (const cb of [...this.subs]) {
+                try {
+                    cb();
+                }
+                catch { /* subscriber threw */ }
+            }
+        });
+    }
+    dispose() {
+        this.mo?.disconnect();
+        this.mo = null;
+        this.subs.clear();
+    }
+}
+//# sourceMappingURL=observers.js.map

package/dist/features/coach/observers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observers.js","sourceRoot":"","sources":["../../../src/features/coach/observers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,OAAO,WAAW;IAAxB;QACU,OAAE,GAA4B,IAAI,CAAC;QAC1B,SAAI,GAAG,IAAI,GAAG,EAAc,CAAC;QACtC,cAAS,GAAG,KAAK,CAAC;IAgC5B,CAAC;IA9BS,KAAK;QACX,IAAI,IAAI,CAAC,EAAE,IAAI,OAAO,gBAAgB,KAAK,WAAW,IAAI,OAAO,QAAQ,KAAK,WAAW;YAAE,OAAO;QAClG,IAAI,CAAC,EAAE,GAAG,IAAI,gBAAgB,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QACpD,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,eAAe,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;IAClG,CAAC;IAED,sGAAsG;IACtG,QAAQ,CAAC,EAAc;QACrB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClB,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACrB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;gBAAE,IAAI,CAAC,OAAO,EAAE,CAAC;QACtC,CAAC,CAAC;IACJ,CAAC;IAEO,MAAM;QACZ,IAAI,IAAI,CAAC,SAAS;YAAE,OAAO;QAC3B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,cAAc,CAAC,GAAG,EAAE;YAClB,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;YACvB,KAAK,MAAM,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;gBAAC,IAAI,CAAC;oBAAC,EAAE,EAAE,CAAC;gBAAC,CAAC;gBAAC,MAAM,CAAC,CAAC,sBAAsB,CAAC,CAAC;YAAC,CAAC;QACrF,CAAC,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,IAAI,CAAC,EAAE,EAAE,UAAU,EAAE,CAAC;QACtB,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC;QACf,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;IACpB,CAAC;CACF"}

package/dist/features/coach/overlay.d.ts

@@ -0,0 +1,15 @@
+import type { RenderContext } from './types';
+export declare class CoachRenderer {
+    private host;
+    private root;
+    private card;
+    private spot;
+    private ctx;
+    private onReflow;
+    private ensure;
+    render(ctx: RenderContext): void;
+    /** (Re)position the card + spotlight against the current anchor rect. */
+    private position;
+    hide(): void;
+}
+//# sourceMappingURL=overlay.d.ts.map

package/dist/features/coach/overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../../../src/features/coach/overlay.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,aAAa,EAAQ,MAAM,SAAS,CAAC;AA+BnD,qBAAa,aAAa;IACxB,OAAO,CAAC,IAAI,CAA4B;IACxC,OAAO,CAAC,IAAI,CAA2B;IACvC,OAAO,CAAC,IAAI,CAA4B;IACxC,OAAO,CAAC,IAAI,CAA4B;IACxC,OAAO,CAAC,GAAG,CAA8B;IACzC,OAAO,CAAC,QAAQ,CAA+B;IAE/C,OAAO,CAAC,MAAM;IAYd,MAAM,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI;IAuDhC,yEAAyE;IACzE,OAAO,CAAC,QAAQ;IA4BhB,IAAI,IAAI,IAAI;CAMb"}