@scalebun/web 1.0.0

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';
+/** 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';
+import type { ObserverHub } from './observers';
+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":"AA2BA,gFAAgF;AAChF,iEAAiE;AACjE,MAAM,UAAU,YAAY,CAAC,CAAO,EAAE,EAAQ;IAC5C,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC;IAChC,IAAI,IAAI,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IACxB,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACvF,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACzF,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;AAC1B,CAAC;AAED,SAAS,MAAM,CAAC,EAAW;IACzB,MAAM,CAAC,GAAG,EAAE,CAAC,qBAAqB,EAAE,CAAC;IACrC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;AACnE,CAAC;AAED,SAAS,QAAQ,CAAC,QAAe;IAC/B,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,MAAM,CAAC,GAAG,OAAO,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IAChE,MAAM,CAAC,GAAG,OAAO,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IACjE,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;AAC7C,CAAC;AAED;uGACuG;AACvG,MAAM,UAAU,WAAW,CAAC,EAAW;IACrC,IAAK,EAA6B,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC1D,MAAM,CAAC,GAAG,EAAE,CAAC,qBAAqB,EAAE,CAAC;IACrC,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAClD,MAAM,GAAG,GAAG,OAAO,QAAQ,KAAK,WAAW,IAAI,QAAQ,CAAC,gBAAgB;QACtE,CAAC,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;QACvE,CAAC,CAAC,IAAI,CAAC;IACT,IAAI,CAAC,GAAG;QAAE,OAAO,KAAK,CAAC;IACvB,OAAO,EAAE,KAAK,GAAG,IAAI,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AAC5D,CAAC;AAED,SAAS,SAAS,CAAC,EAAkB,EAAE,CAAc,EAAE,QAAuB,EAAE,MAAqB;IACnG,IAAI,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,IAAI,IAAI,CAAC;IACrD,IAAI,CAAC,EAAE;QAAE,OAAO,KAAK,CAAC,CAAC,8CAA8C;IACrE,IAAI,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,eAAe,IAAI,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAClI,IAAI,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;QAAE,OAAO,KAAK,CAAC;IACzE,IAAI,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpC,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;QACvC,IAAI,GAAG,KAAK,QAAQ,CAAC,CAAC,EAAE,CAAC;YAAC,QAAQ,CAAC,CAAC,GAAG,GAAG,CAAC;YAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC;YAAC,OAAO,KAAK,CAAC;QAAC,CAAC;QACzE,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC;QACd,IAAI,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;IACrD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,mGAAmG;AACnG,SAAS,UAAU,CAAC,EAAkB,EAAE,CAAc;IACpD,IAAI,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IACpD,IAAI,CAAC,EAAE;QAAE,OAAO,WAAW,CAAC;IAC5B,IAAI,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,eAAe,IAAI,GAAG,CAAC;QAAE,OAAO,aAAa,CAAC;IAC1I,IAAI,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;QAAE,OAAO,eAAe,CAAC;IACnF,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,KAA2B,EAAE,IAAiB,EAAE,GAAgB;IACtF,OAAO,IAAI,OAAO,CAAc,CAAC,OAAO,EAAE,EAAE;QAC1C,IAAI,IAAI,GAAG,KAAK,CAAC;QACjB,IAAI,KAAK,GAAe,GAAG,EAAE,GAAE,CAAC,CAAC;QACjC,IAAI,KAAgD,CAAC;QACrD,IAAI,IAAgD,CAAC;QACrD,MAAM,QAAQ,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;QAExB,MAAM,MAAM,GAAG,CAAC,EAAW,EAAE,EAAkB,EAAE,MAAyB,EAAQ,EAAE;YAClF,IAAI,IAAI;gBAAE,OAAO;YACjB,IAAI,GAAG,IAAI,CAAC;YACZ,KAAK,EAAE,CAAC;YACR,IAAI,KAAK;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;YAC/B,IAAI,IAAI;gBAAE,aAAa,CAAC,IAAI,CAAC,CAAC;YAC9B,OAAO,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;QAC9B,CAAC,CAAC;QAEF,MAAM,KAAK,GAAG,GAAS,EAAE;YACvB,IAAI,IAAI;gBAAE,OAAO;YACjB,MAAM,EAAE,GAAG,KAAK,EAAE,CAAC;YACnB,IAAI,SAAS,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC;gBAAE,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACxG,CAAC,CAAC;QAEF,KAAK,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC5B,IAAI,GAAG,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,yDAAyD;QACxG,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,GAAG,MAAM,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,EAAE,UAAU,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,CAAC;QACnH,KAAK,EAAE,CAAC,CAAC,yDAAyD;IACpE,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/features/config/ConfigFeature.d.ts

@@ -0,0 +1,117 @@
+/**
+ * F-CFG — Config & Flags. Fetches GET /config (feature flags, remote config, experiments, rollouts,
+ * entitlements) with ETag/304 caching, persists it (flags available synchronously on next load), and
+ * evaluates flags/rollouts/experiments LOCALLY with deterministic fnv1a32 bucketing (the backend never
+ * assigns — see bucketing.ts; parity with RN + backend is a hard gate). Experiment exposure flows
+ * through the normal event lane: variant() emits one `experiment_exposure` event per (install, key).
+ *
+ * Zero third-party deps (web SDK core rule). Tiny + core (not lazy) — flags must resolve early/sync.
+ */
+import type { IFeature, FeatureContext } from '@scalebun/sdk-contracts';
+import { type VariationDetail } from './types';
+export declare class ConfigFeature implements IFeature {
+    readonly name = "config";
+    private ctx;
+    private active;
+    private payload;
+    private exposed;
+    private deviceId;
+    private clientKey;
+    private apiBaseUrl;
+    private lastFetch;
+    private onVisible?;
+    private es?;
+    private overrides;
+    private changeListeners;
+    private settled;
+    private resolveReady?;
+    private readyPromise;
+    get isActive(): boolean;
+    setup(ctx: FeatureContext): void;
+    /** F4 — subscribe to the realtime config stream. Each `change` nudge triggers an ETag-aware refresh()
+     *  (which no-ops on 304), so a kill-switch flip propagates in seconds; `ping` frames just keep-alive.
+     *  EventSource auto-reconnects on drop; SSR / no-EventSource envs simply skip it (foreground poll stays). */
+    private openStream;
+    /** F3 — coerce the loose bootstrap shape into a payload (null when absent/empty). */
+    private seedFromBootstrap;
+    private markReady;
+    private emitChange;
+    /** Re-fetch /config (ETag-aware). Keeps the cached payload on 304 / error (offline-safe). Fires
+     *  onChange listeners when a new version is applied (F3). */
+    refresh(): Promise<void>;
+    /** Resolves once the first config fetch settles (immediately when there's no network configured).
+     *  Bootstrap/cache make flags usable synchronously before this; ready() means "freshest attempted". */
+    ready(): Promise<void>;
+    /** Subscribe to config changes (a new version applied on refresh, or an override set/cleared).
+     *  Returns an unsubscribe fn. */
+    onChange(cb: () => void): () => void;
+    /** QA/dev: force a flag/experiment/rollout to a value locally (persisted). A string is matched
+     *  against a multivariate flag's variation keys; otherwise it's the served value verbatim. */
+    override(key: string, value: unknown): void;
+    clearOverride(key: string): void;
+    clearOverrides(): void;
+    private hasOverride;
+    /** F1 — the stable unit to bucket on. An explicit per-feature `bucketBy` context attribute always wins
+     *  (e.g. 'group_company' to flip a whole account together).
+     *
+     *  Otherwise the identity unit, and there are two, because they trade against each other:
+     *
+     *   - `deviceId` (stable): the same value before and after login, so a user NEVER changes variant
+     *     mid-session. This is what the RN SDK buckets on (`installationId`) and what the backend
+     *     aggregates exposures by, so it is also the only option under which web and mobile agree.
+     *   - `userId ?? deviceId` (legacy): gives a logged-in user the same assignment across devices and
+     *     across a storage clear — a genuine feature — but the identity CHANGES at login, which
+     *     re-buckets the user mid-experiment. On any experiment that spans signup that is not noise:
+     *     every converting user crosses the boundary, so the experiment measures the login, not the
+     *     treatment, and one human lands in both arms.
+     *
+     *  Correctness wins: the flip silently invalidates results, while cross-device consistency can be
+     *  recovered deliberately per experiment via `bucketBy: 'userId'`, and multi-device humans are
+     *  folded at analysis time from the backend's identity links.
+     *
+     *  Server-gated because switching re-buckets already-logged-in users once — enabled for new
+     *  experiments first, then globally. Absent ⇒ legacy behaviour, so old payloads are unchanged. */
+    private bucketingId;
+    /** Feature flag — F0: if the flag carries targeting, the first matching rule decides (serve, or a
+     *  per-rule % rollout); no rule matches → the flag's default `enabled`. No targeting → plain boolean.
+     *  F1: the % rollout buckets on the identity unit (or the flag's `bucketBy`), not the raw device.
+     *  F2: for a multivariate flag `isEnabled` is the truthiness of the served value. */
+    /** True when a read of `key` reflects real server config — i.e. the answer is a decision the user
+     *  actually experienced, and therefore an exposure worth recording. False in three cases that all
+     *  look like `false` to a caller but are NOT data:
+     *   - before bootstrap resolves (payload is EMPTY_CONFIG) — an absence of information,
+     *   - for a flag the server has never heard of,
+     *   - for a QA override — staff inspecting the system is not experiment traffic.
+     *  Without this, a first paint records a phantom `false` the user never saw, and the real value
+     *  then emits a second, contradictory exposure. */
+    knows(key: string): boolean;
+    isEnabled(key: string): boolean;
+    /** F2 — resolve a flag's served value with LD-style detail. Boolean flags (no `variations`) resolve to
+     *  their boolean; multivariate flags resolve to a variation's typed value. Precedence: a matching
+     *  targeting rule (TARGETING_MATCH / ROLLOUT) → fallthrough split (ROLLOUT) → default (DEFAULT); an
+     *  unknown flag is FLAG_NOT_FOUND (caller fallback). Never throws — safe defaults at every branch. */
+    variationDetail<T>(key: string, fallback: T): VariationDetail<T>;
+    /** F2 — the served value only (sugar over variationDetail). */
+    variation<T>(key: string, fallback: T): T;
+    /** Remote config value with type coercion + caller fallback (never throws). */
+    get<T>(key: string, fallback: T): T;
+    /** Feature rollout — deterministic percentage gate. F0: a matching targeting rule can override the
+     *  percentage for the matched audience; no match → the rollout's default percentage. */
+    isOn(key: string): boolean;
+    /** F5 — is the identified user in the global experiment holdout? Bucketed on the DEFAULT identity unit
+     *  (uniform across all experiments) so a held-out user is a clean, never-treated baseline everywhere. */
+    private inHoldout;
+    /** F5 — mutual exclusion: within a layer a user owns exactly one 0..99 slot, so only the experiment
+     *  whose `layerRange` covers that slot enrolls them (the rest of the layer excludes them). Bucketed on
+     *  the default identity unit so every experiment in the layer places the user identically. */
+    private inLayerSlot;
+    /** Experiment variant — deterministic; emits one exposure event per (install, key). F0: targeting acts
+     *  as an inclusion filter — no match ⇒ not enrolled (null); a matching rule may override the variant
+     *  set. F5: a global-holdout user, or a user whose layer slot belongs to a different experiment, is not
+     *  enrolled (null, no exposure) — keeping the holdout baseline clean and layers mutually exclusive. */
+    variant(key: string): string | null;
+    /** SDK-suppressible entitlement (fail-open: unknown → on). The bootstrap can gate features on this. */
+    entitlement(key: string): boolean;
+    teardown(): void;
+}
+//# sourceMappingURL=ConfigFeature.d.ts.map

package/dist/features/config/ConfigFeature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConfigFeature.d.ts","sourceRoot":"","sources":["../../../src/features/config/ConfigFeature.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAKxE,OAAO,EAAwD,KAAK,eAAe,EAAE,MAAM,SAAS,CAAC;AAUrG,qBAAa,aAAc,YAAW,QAAQ;IAC5C,QAAQ,CAAC,IAAI,YAAY;IACzB,OAAO,CAAC,GAAG,CAA+B;IAC1C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,QAAQ,CAAM;IACtB,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,UAAU,CAAM;IACxB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,SAAS,CAAC,CAAa;IAC/B,OAAO,CAAC,EAAE,CAAC,CAAc;IAEzB,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,eAAe,CAAyB;IAChD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAAC,CAAa;IAClC,OAAO,CAAC,YAAY,CAA8D;IAElF,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,KAAK,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI;IA4BhC;;iHAE6G;IAC7G,OAAO,CAAC,UAAU;IAmBlB,qFAAqF;IACrF,OAAO,CAAC,iBAAiB;IAezB,OAAO,CAAC,SAAS;IAOjB,OAAO,CAAC,UAAU;IAUlB;iEAC6D;IACvD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAoC9B;2GACuG;IACvG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAGtB;qCACiC;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAMpC;kGAC8F;IAC9F,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAK3C,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAOhC,cAAc,IAAI,IAAI;IAKtB,OAAO,CAAC,WAAW;IAMnB;;;;;;;;;;;;;;;;;;;sGAmBkG;IAClG,OAAO,CAAC,WAAW;IAWnB;;;yFAGqF;IACrF;;;;;;;uDAOmD;IACnD,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI3B,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAe/B;;;0GAGsG;IACtG,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC;IA8ChE,+DAA+D;IAC/D,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC;IAIzC,+EAA+E;IAC/E,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC;IAqBnC;4FACwF;IACxF,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAY1B;6GACyG;IACzG,OAAO,CAAC,SAAS;IAKjB;;kGAE8F;IAC9F,OAAO,CAAC,WAAW;IAOnB;;;2GAGuG;IACvG,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IA0CnC,uGAAuG;IACvG,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAKjC,QAAQ,IAAI,IAAI;CASjB"}