@scalebun-release/web 2.2.2

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

@@ -0,0 +1,55 @@
+import type { ObserverHub } from './observers.js';
+import type { WaitOutcome } from './wait.js';
+import type { AnchorSpec, AnchorResult, TourSpec, TourStatus, RenderContext, TourContext } from './types.js';
+import type { WaitCondition } from './wait.js';
+export interface TourEngineDeps {
+    hub: ObserverHub;
+    resolveAnchor: (spec: AnchorSpec) => AnchorResult;
+    waitFor: (getEl: () => Element | null, opts: {
+        conditions: WaitCondition[];
+        timeoutMs?: number;
+    }, hub: ObserverHub) => Promise<WaitOutcome>;
+    render: (ctx: RenderContext) => void;
+    hide: () => void;
+    emit: (name: string, props?: Record<string, unknown>) => void;
+    now: () => number;
+    /** Persist the current step index for durable resume (index -1 = tour finished → clear). */
+    persist?: (tourId: string, index: number) => void;
+    loadIndex?: (tourId: string) => number | undefined;
+}
+export declare class TourEngine {
+    private readonly deps;
+    private tour;
+    private index;
+    private status;
+    private startedAt;
+    private token;
+    private stepCleanup;
+    private pendingEvent;
+    private context;
+    constructor(deps: TourEngineDeps);
+    get state(): {
+        tourId: string | null;
+        index: number;
+        status: TourStatus;
+    };
+    start(tour: TourSpec, opts?: {
+        resume?: boolean;
+        context?: TourContext;
+    }): void;
+    next(): void;
+    back(): void;
+    skip(): void;
+    /** Host signals a custom-event advance (for `advance: { event }`). */
+    notify(event: string): void;
+    end(status?: Exclude<TourStatus, 'idle' | 'running'>, method?: string): void;
+    private enter;
+    private applyFallback;
+    private paint;
+    private armAdvance;
+    private completeStep;
+    private controls;
+    private clearStep;
+    dispose(): void;
+}
+//# sourceMappingURL=tour.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tour.d.ts","sourceRoot":"","sources":["../../../src/features/coach/tour.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAC1C,OAAO,KAAK,EACV,UAAU,EAAE,YAAY,EAAa,QAAQ,EAAE,UAAU,EAAE,aAAa,EAAE,WAAW,EACtF,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,WAAW,CAAC;IACjB,aAAa,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,YAAY,CAAC;IAClD,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,OAAO,GAAG,IAAI,EAAE,IAAI,EAAE;QAAE,UAAU,EAAE,aAAa,EAAE,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IAC5I,MAAM,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,IAAI,CAAC;IACrC,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAC9D,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,4FAA4F;IAC5F,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClD,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CACpD;AAED,qBAAa,UAAU;IAUT,OAAO,CAAC,QAAQ,CAAC,IAAI;IATjC,OAAO,CAAC,IAAI,CAAyB;IACrC,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,OAAO,CAAmB;gBAEL,IAAI,EAAE,cAAc;IAEjD,IAAI,KAAK,IAAI;QAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,UAAU,CAAA;KAAE,CAExE;IAED,KAAK,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,IAAI;IAe/E,IAAI,IAAI,IAAI;IACZ,IAAI,IAAI,IAAI;IAOZ,IAAI,IAAI,IAAI;IAMZ,sEAAsE;IACtE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAG3B,GAAG,CAAC,MAAM,GAAE,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAe,EAAE,MAAM,SAAQ,GAAG,IAAI;YAgB1E,KAAK;IAkCnB,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,KAAK;IAMb,OAAO,CAAC,UAAU;IAqBlB,OAAO,CAAC,YAAY;IAgBpB,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,SAAS;IAOjB,OAAO,IAAI,IAAI;CAKhB"}

package/dist/features/coach/tour.js

@@ -0,0 +1,181 @@
+/**
+ * TourEngine (B2.1) — the step state machine: sequencing, anchor resolution + wait (via B1), the
+ * never-dead-end fallback ladder (anchor-fail → modal | skip | end), advance conditions (next /
+ * anchor-click / anchor-gone / event / timer), durable resume, and lifecycle telemetry. DOM rendering is
+ * delegated to an injected `render` callback so the engine is pure orchestration + fully unit-testable.
+ */
+import { evalPredicate, resolveNext } from './predicate.js';
+export class TourEngine {
+    constructor(deps) {
+        this.deps = deps;
+        this.tour = null;
+        this.index = 0;
+        this.status = 'idle';
+        this.startedAt = 0;
+        this.token = 0; // bumped on every step change → discards superseded async waits
+        this.stepCleanup = null;
+        this.pendingEvent = null;
+        this.context = {};
+    }
+    get state() {
+        return { tourId: this.tour?.id ?? null, index: this.index, status: this.status };
+    }
+    start(tour, opts) {
+        if (this.status === 'running')
+            this.end('abandoned', 'superseded');
+        this.tour = tour;
+        this.context = opts?.context ?? {};
+        this.status = 'running';
+        this.startedAt = this.deps.now();
+        const resumed = !!opts?.resume;
+        this.index = resumed ? (this.deps.loadIndex?.(tour.id) ?? 0) : 0;
+        if (this.index >= tour.steps.length || this.index < 0)
+            this.index = 0;
+        this.deps.emit('$coachmark_tour_started', {
+            tourId: tour.id, version: tour.version ?? 1, resumed: resumed && this.index > 0, steps: tour.steps.length,
+        });
+        void this.enter(this.index);
+    }
+    next() { if (this.status === 'running')
+        this.completeStep('next'); }
+    back() {
+        if (this.status === 'running' && this.index > 0) {
+            const step = this.tour.steps[this.index];
+            this.deps.emit('$coachmark_step_back', { tourId: this.tour.id, stepId: step.id, index: this.index });
+            void this.enter(this.index - 1);
+        }
+    }
+    skip() {
+        if (this.status !== 'running')
+            return;
+        const step = this.tour.steps[this.index];
+        this.deps.emit('$coachmark_step_skipped', { tourId: this.tour.id, stepId: step.id, index: this.index, bySystem: false });
+        void this.enter(this.index + 1);
+    }
+    /** Host signals a custom-event advance (for `advance: { event }`). */
+    notify(event) {
+        if (this.status === 'running' && this.pendingEvent === event)
+            this.completeStep('event');
+    }
+    end(status = 'abandoned', method = 'api') {
+        if (this.status !== 'running')
+            return;
+        const tour = this.tour;
+        this.clearStep();
+        this.status = status;
+        this.deps.hide();
+        this.deps.persist?.(tour.id, -1);
+        if (status === 'completed') {
+            this.deps.emit('$coachmark_tour_completed', { tourId: tour.id, version: tour.version ?? 1, steps: tour.steps.length, totalMs: this.deps.now() - this.startedAt });
+        }
+        else {
+            const step = tour.steps[this.index];
+            this.deps.emit('$coachmark_tour_abandoned', { tourId: tour.id, stepId: step?.id, index: this.index, method });
+        }
+    }
+    // ── internals ────────────────────────────────────────────────────────────
+    async enter(i) {
+        this.clearStep();
+        const tour = this.tour;
+        if (!tour || this.status !== 'running')
+            return;
+        if (i >= tour.steps.length)
+            return this.end('completed');
+        this.index = i;
+        const myToken = ++this.token;
+        const step = tour.steps[i];
+        // conditional skip — evaluated on enter, before any render/persist.
+        if (step.skipIf && evalPredicate(step.skipIf, this.context)) {
+            this.deps.emit('$coachmark_step_skipped', { tourId: tour.id, stepId: step.id, index: i, bySystem: true, reason: 'skipIf' });
+            return void this.enter(i + 1);
+        }
+        this.deps.persist?.(tour.id, i);
+        let el = null;
+        if (step.anchor) {
+            const conds = step.waitConditions ?? ['exists', 'visible'];
+            const getEl = () => this.deps.resolveAnchor(step.anchor).el;
+            const outcome = await this.deps.waitFor(getEl, { conditions: conds, timeoutMs: step.timeoutMs ?? 5000 }, this.deps.hub);
+            if (myToken !== this.token || this.status !== 'running')
+                return; // superseded mid-wait
+            if (!outcome.ok) {
+                this.deps.emit('$coachmark_anchor_failed', { tourId: tour.id, stepId: step.id, index: i, reason: outcome.reason, strategiesTried: this.deps.resolveAnchor(step.anchor).strategiesTried });
+                return this.applyFallback(step, i);
+            }
+            const r = this.deps.resolveAnchor(step.anchor);
+            if (r.strategyIndex > 0)
+                this.deps.emit('$coachmark_anchor_healed', { tourId: tour.id, stepId: step.id, index: i, winningStrategy: r.strategyIndex });
+            el = outcome.el;
+        }
+        this.paint(step, el, i, false);
+    }
+    applyFallback(step, i) {
+        const fb = step.fallback ?? 'modal';
+        this.deps.emit('$coachmark_step_fallback', { tourId: this.tour.id, stepId: step.id, index: i, fallback: fb, reason: 'anchor-fail' });
+        if (fb === 'skip')
+            return void this.enter(i + 1);
+        if (fb === 'end')
+            return this.end('abandoned', 'anchor-fail');
+        this.paint(step, null, i, true); // 'modal' → centered, anchorless
+    }
+    paint(step, el, i, degraded) {
+        this.deps.render({ step, el, index: i, total: this.tour.steps.length, degraded, controls: this.controls() });
+        this.deps.emit('$coachmark_step_entered', { tourId: this.tour.id, stepId: step.id, index: i, anchored: !!el, degraded });
+        this.armAdvance(step, el);
+    }
+    armAdvance(step, el) {
+        const adv = step.advance ?? 'next';
+        this.pendingEvent = null;
+        if (adv === 'next')
+            return;
+        if (adv === 'anchor-click' && el) {
+            const h = () => this.completeStep('click');
+            el.addEventListener('click', h, { once: true });
+            this.stepCleanup = () => el.removeEventListener('click', h);
+        }
+        else if (adv === 'anchor-gone' && step.anchor) {
+            const myToken = this.token;
+            const getEl = () => this.deps.resolveAnchor(step.anchor).el;
+            void this.deps.waitFor(getEl, { conditions: ['gone'], timeoutMs: 3600000 }, this.deps.hub)
+                .then((o) => { if (o.ok && myToken === this.token && this.status === 'running')
+                this.completeStep('gone'); });
+        }
+        else if (typeof adv === 'object' && 'timer' in adv) {
+            const t = setTimeout(() => this.completeStep('timer'), adv.timer);
+            this.stepCleanup = () => clearTimeout(t);
+        }
+        else if (typeof adv === 'object' && 'event' in adv) {
+            this.pendingEvent = adv.event;
+        }
+    }
+    completeStep(by) {
+        if (this.status !== 'running' || !this.tour)
+            return;
+        const step = this.tour.steps[this.index];
+        this.deps.emit('$coachmark_step_completed', { tourId: this.tour.id, stepId: step.id, index: this.index, advanceBy: by });
+        // branching — route to a predicate-selected step id, else advance linearly.
+        const targetId = resolveNext(step.next, this.context);
+        if (targetId) {
+            const ti = this.tour.steps.findIndex((s) => s.id === targetId);
+            if (ti >= 0) {
+                this.deps.emit('$coachmark_branched', { tourId: this.tour.id, fromStep: step.id, toStep: targetId, index: ti });
+                return void this.enter(ti);
+            }
+        }
+        void this.enter(this.index + 1);
+    }
+    controls() {
+        return { next: () => this.next(), back: () => this.back(), skip: () => this.skip(), close: () => this.end('abandoned', 'dismiss') };
+    }
+    clearStep() {
+        this.stepCleanup?.();
+        this.stepCleanup = null;
+        this.pendingEvent = null;
+        this.token++; // invalidate any in-flight wait
+    }
+    dispose() {
+        this.clearStep();
+        this.status = 'idle';
+        this.tour = null;
+    }
+}
+//# sourceMappingURL=tour.js.map

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

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

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

@@ -0,0 +1,161 @@
+/**
+ * Coachmark engine contracts (headless-first). B1 = the reliability core: anchor discovery, positioning,
+ * and wait strategies; B2 = tours. See docs/INBOX-COACHMARKS-ARCHITECTURE.md §3.
+ */
+import type { WaitCondition } from './wait.js';
+/** One way to find a target element. Resolvers run in order; first stable hit wins → self-healing. */
+export type AnchorStrategy = {
+    kind: 'selector';
+    value: string;
+} | {
+    kind: 'data-attr';
+    value: string;
+} | {
+    kind: 'text';
+    value: string;
+    scope?: string;
+} | {
+    kind: 'aria';
+    role?: string;
+    name?: string;
+} | {
+    kind: 'xpath';
+    value: string;
+} | {
+    kind: 'nth';
+    selector: string;
+    index: number;
+};
+export interface AnchorSpec {
+    /** Prioritized resolver list — the multi-strategy that survives DOM churn better than one CSS selector. */
+    strategies: AnchorStrategy[];
+    /** Descend into open shadow roots (composed traversal). Default true. */
+    shadowPiercing?: boolean;
+    /** Minimum intersection ratio to consider the element "visible" (WaitEngine). Default 0.5. */
+    minVisibleRatio?: number;
+}
+/** Why an anchor resolution failed — powers the anchor-health dashboard (an industry first). */
+export type AnchorFailReason = 'not-found' | 'not-visible' | 'not-clickable' | 'timeout' | 'covered' | 'shadow-closed' | 'iframe-cross-origin';
+export interface AnchorResult {
+    el: Element | null;
+    /** Index of the strategy that resolved (>0 ⇒ the primary failed → emit $coachmark_anchor_healed). */
+    strategyIndex: number;
+    strategiesTried: number;
+}
+export type Side = 'top' | 'bottom' | 'left' | 'right';
+export type Align = 'start' | 'center' | 'end';
+export interface Placement {
+    side: Side;
+    align: Align;
+}
+/** A viewport-space rectangle (getBoundingClientRect shape). */
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface PositionInput {
+    anchor: Rect;
+    tooltip: {
+        width: number;
+        height: number;
+    };
+    /** The clamp region (viewport by default) in the same coord space as `anchor`. */
+    boundary: Rect;
+    /** Preferred placement; the engine flips/shifts from here to stay in-bounds. Default bottom/center. */
+    preferred?: Placement;
+    /** Gap between anchor and tooltip. Default 8. */
+    offset?: number;
+    /** Min inset from the boundary edges. Default 8. */
+    padding?: number;
+    /** Arrow half-extent; the arrow is clamped this far from the tooltip corners. Default 8. */
+    arrowSize?: number;
+    /** RTL mirrors start/end on the horizontal axis. Default false. */
+    rtl?: boolean;
+}
+export interface PositionResult {
+    /** The resolved placement (may differ from `preferred` after a flip). */
+    placement: Placement;
+    /** Tooltip top-left in the boundary/viewport coord space. */
+    x: number;
+    y: number;
+    /** Arrow center as an offset within the tooltip box (px), on the edge facing the anchor. */
+    arrow: {
+        x: number;
+        y: number;
+    };
+    flipped: boolean;
+    shifted: boolean;
+}
+/** How a step advances to the next. Default 'next' (a Next button / next() call). */
+export type AdvanceCondition = 'next' | 'anchor-click' | 'anchor-gone' | {
+    event: string;
+} | {
+    timer: number;
+};
+/** What to do when a step's anchor can't be resolved — never dead-ends (the fallback ladder). */
+export type StepFallback = 'skip' | 'end' | 'modal';
+export interface CoachStep {
+    id: string;
+    /** Omit for a centered modal (no anchor). */
+    anchor?: AnchorSpec;
+    title?: string;
+    body?: string;
+    placement?: Placement;
+    waitConditions?: WaitCondition[];
+    advance?: AdvanceCondition;
+    fallback?: StepFallback;
+    timeoutMs?: number;
+    /** Where to go after this step: a step id, or a branch list (first passing `when` wins). Default: linear. */
+    next?: string | Branch[];
+    /** Skip this step entirely when the predicate passes (evaluated on enter). */
+    skipIf?: Predicate;
+}
+export interface TourSpec {
+    id: string;
+    version?: number;
+    steps: CoachStep[];
+}
+export type TourStatus = 'idle' | 'running' | 'completed' | 'abandoned' | 'errored';
+/** What the DOM layer (B2.2) receives to render a step. `el` null ⇒ centered modal (anchorless/degraded). */
+export interface RenderContext {
+    step: CoachStep;
+    el: Element | null;
+    index: number;
+    total: number;
+    degraded: boolean;
+    controls: {
+        next: () => void;
+        back: () => void;
+        skip: () => void;
+        close: () => void;
+    };
+}
+export type CompareOp = 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'exists';
+/** A serializable predicate (dashboard-authorable) evaluated against the tour context. */
+export type Predicate = {
+    prop: string;
+    op?: CompareOp;
+    value?: unknown;
+} | {
+    flag: string;
+    is?: boolean;
+} | {
+    all: Predicate[];
+} | {
+    any: Predicate[];
+} | {
+    not: Predicate;
+};
+/** A conditional next-target. First branch whose `when` passes (or has no `when`) wins. */
+export interface Branch {
+    to: string;
+    when?: Predicate;
+}
+/** Host-provided evaluation context for branching/skip predicates. */
+export interface TourContext {
+    props?: Record<string, unknown>;
+    flags?: Record<string, boolean>;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/features/coach/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/features/coach/types.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,34 @@
+/**
+ * WaitEngine (B1.3) — a step never assumes the DOM is ready. `waitFor` resolves once an element
+ * satisfies a set of conditions (exists / visible / clickable / stable / gone), re-checking on every
+ * ObserverHub mutation + a poll fallback (for scroll/resize/async layout the observer misses), and
+ * rejecting with a typed reason on timeout. This "wait-until-really-ready + typed failure" is the layer
+ * that stops tours silently breaking on lazy/virtualized/SPA DOMs — the industry's #1 pain.
+ */
+import type { AnchorFailReason, Rect } from './types.js';
+import type { ObserverHub } from './observers.js';
+export type WaitCondition = 'exists' | 'visible' | 'clickable' | 'stable' | 'gone';
+export interface WaitOptions {
+    conditions: WaitCondition[];
+    timeoutMs?: number;
+    minVisibleRatio?: number;
+    stableFrames?: number;
+    boundary?: Rect;
+    pollMs?: number;
+}
+export interface WaitOutcome {
+    ok: boolean;
+    el: Element | null;
+    reason?: AnchorFailReason;
+}
+/** Fraction of the element's area inside the viewport (0..1). */
+export declare function visibleRatio(r: Rect, vp: Rect): number;
+/** Topmost-at-center hit test: the element (or a node it contains) is what a click would land on, and
+ *  it isn't disabled. Requires real layout — returns false under a zero-size/no-layout environment. */
+export declare function isClickable(el: Element): boolean;
+/**
+ * Resolve once `getEl()` satisfies the conditions, else reject with a reason after `timeoutMs`.
+ * `getEl` is re-invoked each check (the target may (dis)appear), so pass a fresh AnchorEngine resolve.
+ */
+export declare function waitFor(getEl: () => Element | null, opts: WaitOptions, hub: ObserverHub): Promise<WaitOutcome>;
+//# sourceMappingURL=wait.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../../../src/features/coach/wait.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEnF,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,OAAO,CAAC;IACZ,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;IACnB,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AAGD,iEAAiE;AACjE,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,GAAG,MAAM,CAMtD;AAcD;uGACuG;AACvG,wBAAgB,WAAW,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAShD;AAyBD;;;GAGG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,OAAO,GAAG,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CA6B9G"}

package/dist/features/coach/wait.js

@@ -0,0 +1,107 @@
+// ── pure predicates (unit-testable without layout) ───────────────────────────
+/** Fraction of the element's area inside the viewport (0..1). */
+export function visibleRatio(r, vp) {
+    const area = r.width * r.height;
+    if (area <= 0)
+        return 0;
+    const ix = Math.max(0, Math.min(r.x + r.width, vp.x + vp.width) - Math.max(r.x, vp.x));
+    const iy = Math.max(0, Math.min(r.y + r.height, vp.y + vp.height) - Math.max(r.y, vp.y));
+    return (ix * iy) / area;
+}
+function rectOf(el) {
+    const b = el.getBoundingClientRect();
+    return { x: b.left, y: b.top, width: b.width, height: b.height };
+}
+function viewport(boundary) {
+    if (boundary)
+        return boundary;
+    const w = typeof window !== 'undefined' ? window.innerWidth : 0;
+    const h = typeof window !== 'undefined' ? window.innerHeight : 0;
+    return { x: 0, y: 0, width: w, height: h };
+}
+/** Topmost-at-center hit test: the element (or a node it contains) is what a click would land on, and
+ *  it isn't disabled. Requires real layout — returns false under a zero-size/no-layout environment. */
+export function isClickable(el) {
+    if (el.disabled)
+        return false;
+    const r = el.getBoundingClientRect();
+    if (r.width === 0 || r.height === 0)
+        return false;
+    const top = typeof document !== 'undefined' && document.elementFromPoint
+        ? document.elementFromPoint(r.left + r.width / 2, r.top + r.height / 2)
+        : null;
+    if (!top)
+        return false;
+    return el === top || el.contains(top) || top.contains(el);
+}
+function satisfied(el, o, prevRect, stable) {
+    if (o.conditions.includes('gone'))
+        return el == null;
+    if (!el)
+        return false; // every non-'gone' condition needs an element
+    if (o.conditions.includes('visible') && visibleRatio(rectOf(el), viewport(o.boundary)) < (o.minVisibleRatio ?? 0.5))
+        return false;
+    if (o.conditions.includes('clickable') && !isClickable(el))
+        return false;
+    if (o.conditions.includes('stable')) {
+        const cur = JSON.stringify(rectOf(el));
+        if (cur !== prevRect.v) {
+            prevRect.v = cur;
+            stable.n = 0;
+            return false;
+        }
+        stable.n += 1;
+        if (stable.n < (o.stableFrames ?? 2))
+            return false;
+    }
+    return true;
+}
+/** Why the wait timed out — the first unmet condition (for $coachmark_anchor_failed telemetry). */
+function failReason(el, o) {
+    if (o.conditions.includes('gone'))
+        return 'timeout';
+    if (!el)
+        return 'not-found';
+    if (o.conditions.includes('visible') && visibleRatio(rectOf(el), viewport(o.boundary)) < (o.minVisibleRatio ?? 0.5))
+        return 'not-visible';
+    if (o.conditions.includes('clickable') && !isClickable(el))
+        return 'not-clickable';
+    return 'timeout';
+}
+/**
+ * Resolve once `getEl()` satisfies the conditions, else reject with a reason after `timeoutMs`.
+ * `getEl` is re-invoked each check (the target may (dis)appear), so pass a fresh AnchorEngine resolve.
+ */
+export function waitFor(getEl, opts, hub) {
+    return new Promise((resolve) => {
+        let done = false;
+        let unsub = () => { };
+        let timer;
+        let poll;
+        const prevRect = { v: '' };
+        const stable = { n: 0 };
+        const finish = (ok, el, reason) => {
+            if (done)
+                return;
+            done = true;
+            unsub();
+            if (timer)
+                clearTimeout(timer);
+            if (poll)
+                clearInterval(poll);
+            resolve({ ok, el, reason });
+        };
+        const check = () => {
+            if (done)
+                return;
+            const el = getEl();
+            if (satisfied(el, opts, prevRect, stable))
+                finish(true, opts.conditions.includes('gone') ? null : el);
+        };
+        unsub = hub.onChange(check);
+        poll = setInterval(check, opts.pollMs ?? 100); // catches scroll/resize/async layout the observer misses
+        timer = setTimeout(() => { const el = getEl(); finish(false, el, failReason(el, opts)); }, opts.timeoutMs ?? 5000);
+        check(); // immediate — resolve synchronously if already satisfied
+    });
+}
+//# sourceMappingURL=wait.js.map

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

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