@scalebun/web 1.0.0

package/dist/features/inapp/core/triggers.js

@@ -0,0 +1,368 @@
+import { matchRoute } from './targeting';
+import { ChordManager } from './keyboard';
+/** Pure: does a variant's trigger ref match this fired signal? */
+export function matchTrigger(ref, sig) {
+    if (ref.type !== sig.type)
+        return false;
+    switch (ref.type) {
+        case 'route':
+            // ref.match is a glob (undefined ⇒ any route).
+            return matchRoute(ref.match ? [ref.match] : undefined, sig.value ?? '');
+        case 'event':
+            return ref.match == null || ref.match === sig.value;
+        case 'idle':
+            // fire once the signalled idle time reaches the ref threshold.
+            return (sig.arg ?? 0) >= (ref.arg ?? 0);
+        case 'element':
+        case 'hover':
+        case 'selection':
+        case 'keyboard':
+        case 'right-click':
+            // selector/key-bound: the plugin already resolved the target; match on value equality.
+            return ref.match == null || ref.match === sig.value;
+        default:
+            return true;
+    }
+}
+export class TriggerBus {
+    constructor(now = () => Date.now()) {
+        this.listeners = new Set();
+        this.plugins = [];
+        this.now = now;
+    }
+    on(cb) {
+        this.listeners.add(cb);
+        return () => this.listeners.delete(cb);
+    }
+    /** Emit a signal to all subscribers. Plugins and host code both call this. */
+    fire(sig) {
+        const full = { ...sig, at: sig.at ?? this.now() };
+        for (const l of this.listeners) {
+            try {
+                l(full);
+            }
+            catch {
+                /* a listener must never break the bus */
+            }
+        }
+    }
+    /** Register + start a plugin. */
+    use(plugin) {
+        this.plugins.push(plugin);
+        plugin.start(this);
+    }
+    stop() {
+        for (const p of this.plugins)
+            p.stop();
+        this.plugins = [];
+        this.listeners.clear();
+    }
+}
+// ── Route plugin ────────────────────────────────────────────────────────────────
+/** Emits a `route` signal on pushState/replaceState/popstate/hashchange. Patches history once. */
+export function routePlugin() {
+    let unpatch = null;
+    let onPop = null;
+    const currentPath = () => (typeof location !== 'undefined' ? location.pathname + location.search : '');
+    return {
+        type: 'route',
+        start(bus) {
+            if (typeof window === 'undefined' || typeof history === 'undefined')
+                return;
+            const emit = () => bus.fire({ type: 'route', value: currentPath() });
+            const origPush = history.pushState;
+            const origReplace = history.replaceState;
+            history.pushState = function (...args) {
+                const r = origPush.apply(this, args);
+                emit();
+                return r;
+            };
+            history.replaceState = function (...args) {
+                const r = origReplace.apply(this, args);
+                emit();
+                return r;
+            };
+            onPop = emit;
+            window.addEventListener('popstate', emit);
+            window.addEventListener('hashchange', emit);
+            unpatch = () => {
+                history.pushState = origPush;
+                history.replaceState = origReplace;
+            };
+            // fire the initial route so route-gated variants get a chance on mount.
+            emit();
+        },
+        stop() {
+            unpatch?.();
+            unpatch = null;
+            if (onPop && typeof window !== 'undefined') {
+                window.removeEventListener('popstate', onPop);
+                window.removeEventListener('hashchange', onPop);
+            }
+            onPop = null;
+        },
+    };
+}
+// ── Event plugin ────────────────────────────────────────────────────────────────
+/**
+ * Bridges product-analytics events to `event` triggers. It has no listeners of its own — the feature
+ * shell calls `fireEvent(name)` when it observes a tracked event (from the capture pipeline). Exposed
+ * as a plugin so start/stop lifecycle is uniform; returns the bridge fn for the shell to call.
+ */
+export function eventPlugin() {
+    let bus = null;
+    return {
+        type: 'event',
+        start(b) {
+            bus = b;
+        },
+        stop() {
+            bus = null;
+        },
+        fireEvent(name) {
+            bus?.fire({ type: 'event', value: name });
+        },
+    };
+}
+// ── Idle plugin ─────────────────────────────────────────────────────────────────
+/**
+ * Emits an `idle` signal (arg = threshold ms) after that many ms without user activity. Thresholds
+ * come from the active variants' idle triggers; activity (pointer/key/scroll) re-arms all timers.
+ */
+export function idlePlugin() {
+    let bus = null;
+    let thresholds = [];
+    let timers = [];
+    let onActivity = null;
+    const ACTIVITY = ['mousemove', 'mousedown', 'keydown', 'scroll', 'touchstart', 'pointerdown'];
+    const clear = () => {
+        for (const t of timers)
+            clearTimeout(t);
+        timers = [];
+    };
+    const arm = () => {
+        clear();
+        if (!bus)
+            return;
+        for (const ms of thresholds) {
+            if (ms > 0)
+                timers.push(setTimeout(() => bus?.fire({ type: 'idle', arg: ms }), ms));
+        }
+    };
+    return {
+        type: 'idle',
+        start(b) {
+            bus = b;
+            if (typeof window === 'undefined')
+                return;
+            onActivity = arm;
+            for (const e of ACTIVITY)
+                window.addEventListener(e, onActivity, { passive: true });
+            arm();
+        },
+        stop() {
+            clear();
+            if (onActivity && typeof window !== 'undefined') {
+                for (const e of ACTIVITY)
+                    window.removeEventListener(e, onActivity);
+            }
+            onActivity = null;
+            bus = null;
+        },
+        setThresholds(ms) {
+            thresholds = Array.from(new Set(ms.filter((n) => n > 0)));
+            arm();
+        },
+    };
+}
+/**
+ * Fires an `element` signal when a target element becomes visible at its ratio (IntersectionObserver).
+ * New matching elements added later (lazy/virtualized DOM) are picked up via a MutationObserver rescan.
+ * Fires once per selector until re-armed (setTargets). Degrades to a no-op without IntersectionObserver.
+ */
+export function elementPlugin() {
+    let bus = null;
+    let targets = [];
+    let io = null;
+    let mo = null;
+    const observed = new WeakSet();
+    const fired = new Set();
+    const scan = () => {
+        if (!io || typeof document === 'undefined')
+            return;
+        for (const t of targets) {
+            for (const el of document.querySelectorAll(t.selector)) {
+                if (!observed.has(el)) {
+                    observed.add(el);
+                    io.observe(el);
+                }
+            }
+        }
+    };
+    const onEntries = (entries) => {
+        for (const e of entries) {
+            for (const t of targets) {
+                const need = t.ratio ?? 0.5;
+                if (!fired.has(t.selector) && e.isIntersecting && e.intersectionRatio >= need && e.target.matches(t.selector)) {
+                    fired.add(t.selector);
+                    bus?.fire({ type: 'element', value: t.selector, arg: Math.round(need * 100) });
+                }
+            }
+        }
+    };
+    return {
+        type: 'element',
+        start(b) {
+            bus = b;
+            if (typeof IntersectionObserver === 'undefined' || typeof document === 'undefined')
+                return;
+            io = new IntersectionObserver(onEntries, { threshold: [0, 0.25, 0.5, 0.75, 1] });
+            if (typeof MutationObserver !== 'undefined') {
+                mo = new MutationObserver(() => scan());
+                mo.observe(document.documentElement, { subtree: true, childList: true });
+            }
+            scan();
+        },
+        stop() {
+            io?.disconnect();
+            io = null;
+            mo?.disconnect();
+            mo = null;
+            fired.clear();
+            bus = null;
+        },
+        setTargets(t) {
+            targets = t;
+            fired.clear();
+            scan();
+        },
+    };
+}
+/** Fires a `keyboard` signal when a registered chord is pressed (⌘K → open palette). Uses the
+ *  conflict-safe ChordManager (skips typing unless `global`). */
+export function keyboardPlugin(initial = []) {
+    let bus = null;
+    let chords = initial;
+    const mgr = new ChordManager();
+    let unregs = [];
+    const bind = () => {
+        for (const u of unregs)
+            u();
+        unregs = [];
+        for (const c of chords) {
+            unregs.push(mgr.register(c.combo, () => bus?.fire({ type: 'keyboard', value: c.combo }), { global: c.global }));
+        }
+    };
+    return {
+        type: 'keyboard',
+        start(b) {
+            bus = b;
+            mgr.start();
+            bind();
+        },
+        stop() {
+            for (const u of unregs)
+                u();
+            unregs = [];
+            mgr.stop();
+            bus = null;
+        },
+        setChords(c) {
+            chords = c;
+            bind();
+        },
+    };
+}
+// ── Selection / right-click / hover plugins (P3.5) ───────────────────────────────
+/** Fires a `selection` signal (value = selected text) when the user finishes selecting text. Powers
+ *  "select text → ask AI". */
+export function selectionPlugin() {
+    let bus = null;
+    let onSel = null;
+    return {
+        type: 'selection',
+        start(b) {
+            bus = b;
+            if (typeof document === 'undefined')
+                return;
+            onSel = () => {
+                const t = document.getSelection?.()?.toString().trim();
+                if (t)
+                    bus?.fire({ type: 'selection', value: t });
+            };
+            document.addEventListener('mouseup', onSel);
+            document.addEventListener('keyup', onSel);
+        },
+        stop() {
+            if (onSel && typeof document !== 'undefined') {
+                document.removeEventListener('mouseup', onSel);
+                document.removeEventListener('keyup', onSel);
+            }
+            onSel = null;
+            bus = null;
+        },
+    };
+}
+/** Fires a `right-click` signal on contextmenu (optionally scoped to a selector). Never preventDefault
+ *  — the host keeps its native menu; the variant decides what to surface. */
+export function contextMenuPlugin(selector) {
+    let bus = null;
+    let onCtx = null;
+    return {
+        type: 'right-click',
+        start(b) {
+            bus = b;
+            if (typeof document === 'undefined')
+                return;
+            onCtx = (e) => {
+                if (selector && !e.target?.closest?.(selector))
+                    return;
+                bus?.fire({ type: 'right-click', value: selector ?? '' });
+            };
+            document.addEventListener('contextmenu', onCtx);
+        },
+        stop() {
+            if (onCtx && typeof document !== 'undefined')
+                document.removeEventListener('contextmenu', onCtx);
+            onCtx = null;
+            bus = null;
+        },
+    };
+}
+/** Fires a `hover` signal when the pointer enters an element matching a registered selector. */
+export function hoverPlugin() {
+    let bus = null;
+    let selectors = [];
+    let onOver = null;
+    const fired = new Set();
+    return {
+        type: 'hover',
+        start(b) {
+            bus = b;
+            if (typeof document === 'undefined')
+                return;
+            onOver = (e) => {
+                const el = e.target;
+                for (const sel of selectors) {
+                    if (!fired.has(sel) && el?.closest?.(sel)) {
+                        fired.add(sel);
+                        bus?.fire({ type: 'hover', value: sel });
+                    }
+                }
+            };
+            document.addEventListener('mouseover', onOver);
+        },
+        stop() {
+            if (onOver && typeof document !== 'undefined')
+                document.removeEventListener('mouseover', onOver);
+            onOver = null;
+            fired.clear();
+            bus = null;
+        },
+        setSelectors(s) {
+            selectors = s;
+            fired.clear();
+        },
+    };
+}
+//# sourceMappingURL=triggers.js.map

package/dist/features/inapp/core/triggers.js.map

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

package/dist/features/inapp/inappContract.web.d.ts

@@ -0,0 +1,47 @@
+/**
+ * In-App Messaging 2.0 — the contract layer (spec §7.1).
+ *
+ * Runtime, zero-dependency constants + a single `validateVariant()` guard shared by:
+ *   • the SDK client-guard (reject a malformed served variant before it reaches a renderer), and
+ *   • the backend validator (reject a variant the author tried to publish).
+ * Same rules on both sides ⇒ "you can't publish what the server would 400" (fixes the mobile finding
+ * that web sat outside the parity/validation gate).
+ *
+ * This file also encodes the **physical facts** the Orchestrator (§8) needs — which zone a surface
+ * lives in, its focus class, its attention cost, and zone capacities — so the scheduler is pure data
+ * over these tables and a new surface just adds rows here.
+ */
+import type { BlockKind, FocusClass, Platform, PriorityTier, Surface, TriggerType, Variant, Zone } from './types';
+export declare const PLATFORMS: readonly Platform[];
+export declare const SURFACES: readonly Surface[];
+export declare const PRIORITY_TIERS: readonly PriorityTier[];
+export declare const TRIGGER_TYPES: readonly TriggerType[];
+export declare const BLOCK_KINDS: readonly BlockKind[];
+export declare const SURFACE_ZONE: Record<Surface, Zone>;
+export declare const SURFACE_FOCUS: Record<Surface, FocusClass>;
+export declare const SURFACE_COST: Record<Surface, number>;
+export declare const ZONE_CAP: Record<string, number>;
+export declare const TIER_WEIGHT: Record<PriorityTier, number>;
+export declare const FOCUS_STEALING_ZONES: readonly Zone[];
+/** Resolve the concrete zone for a variant, refining the static map with its surfaceOptions. */
+export declare function zoneForVariant(v: Pick<Variant, 'surface' | 'surfaceOptions'>): Zone;
+/** Capacity for a concrete zone key (handles the dynamic `inline:<slot>` family). */
+export declare function zoneCap(zone: Zone): number;
+export interface ValidationIssue {
+    path: string;
+    message: string;
+}
+/**
+ * Validate one variant against the contract. Returns [] when valid. Pure + zero-dep so the same code
+ * runs in the browser (before render) and on the server (before publish).
+ */
+export declare function validateVariant(v: Variant): ValidationIssue[];
+/** Convenience: is this variant contract-valid? */
+export declare function isValidVariant(v: Variant): boolean;
+/**
+ * Server-authoritative guard (§P4.2): strip preview-only block props (e.g. a quiz answer key) from a
+ * variant before it reaches the client. Pure — returns a new variant; never mutates the input. The
+ * server calls this before serving; the SDK can call it defensively on ingest.
+ */
+export declare function stripPreviewOnly(v: Variant): Variant;
+//# sourceMappingURL=inappContract.web.d.ts.map

package/dist/features/inapp/inappContract.web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inappContract.web.d.ts","sourceRoot":"","sources":["../../../src/features/inapp/inappContract.web.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EACV,SAAS,EACT,UAAU,EACV,QAAQ,EACR,YAAY,EACZ,OAAO,EACP,WAAW,EACX,OAAO,EACP,IAAI,EACL,MAAM,SAAS,CAAC;AAGjB,eAAO,MAAM,SAAS,EAAE,SAAS,QAAQ,EAA8B,CAAC;AAExE,eAAO,MAAM,QAAQ,EAAE,SAAS,OAAO,EAGtC,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,SAAS,YAAY,EAAqD,CAAC;AAExG,eAAO,MAAM,aAAa,EAAE,SAAS,WAAW,EAG/C,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAM3C,CAAC;AAKF,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,OAAO,EAAE,IAAI,CAiB9C,CAAC;AAGF,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,OAAO,EAAE,UAAU,CAiBrD,CAAC;AAIF,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAiBhD,CAAC;AAIF,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAY3C,CAAC;AAGF,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAMpD,CAAC;AAGF,eAAO,MAAM,oBAAoB,EAAE,SAAS,IAAI,EAA0B,CAAC;AAE3E,gGAAgG;AAChG,wBAAgB,cAAc,CAAC,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,GAAG,gBAAgB,CAAC,GAAG,IAAI,CAcnF;AAED,qFAAqF;AACrF,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAG1C;AAGD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAID;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,GAAG,eAAe,EAAE,CAoD7D;AAED,mDAAmD;AACnD,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAElD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAapD"}

package/dist/features/inapp/inappContract.web.js

@@ -0,0 +1,219 @@
+// ── Enumerations (single source of truth for validation) ────────────────────────
+export const PLATFORMS = ['web', 'ios', 'android'];
+export const SURFACES = [
+    'modal', 'slideover', 'panel', 'popover', 'coachmark', 'tour', 'hotspot', 'inline',
+    'banner', 'toast', 'center', 'launcher', 'palette', 'checklist', 'takeover', 'toolbar',
+];
+export const PRIORITY_TIERS = ['critical', 'high', 'normal', 'low', 'passive'];
+export const TRIGGER_TYPES = [
+    'manual', 'route', 'event', 'idle', 'element', 'hover', 'selection', 'keyboard',
+    'right-click', 'schedule', 'no-data', 'exit-intent',
+];
+export const BLOCK_KINDS = [
+    'heading', 'text', 'richtext', 'markdown', 'image', 'illustration', 'video', 'lottie', 'code',
+    'playground', 'embed', 'chart', 'sparkline', 'stat', 'table', 'form', 'nps', 'rating', 'poll',
+    'quiz', 'emoji', 'steps', 'checklist', 'progress', 'timeline', 'list', 'feature-grid', 'plan-cards',
+    'cta', 'shortcut', 'avatar', 'testimonial', 'social-proof', 'callout', 'badge', 'divider', 'spacer',
+    'countdown', 'carousel', 'qr', 'confetti', 'product-grid', 'spinwheel', 'scratch', 'slot',
+];
+// ── Surface → zone (§8.1) ───────────────────────────────────────────────────────
+// `banner` resolves to top/bottom by placement; `inline` resolves to `inline:<slot>` at runtime.
+// The static map returns the *default* zone; `zoneForVariant()` refines with surfaceOptions.
+export const SURFACE_ZONE = {
+    takeover: 'takeover',
+    modal: 'modal',
+    banner: 'top-banner',
+    toast: 'toast',
+    slideover: 'side-right',
+    panel: 'side-left',
+    popover: 'anchored',
+    coachmark: 'anchored',
+    tour: 'anchored',
+    hotspot: 'anchored',
+    toolbar: 'anchored',
+    launcher: 'launcher',
+    palette: 'palette',
+    center: 'center',
+    inline: 'inline:default',
+    checklist: 'launcher',
+};
+// ── Surface → focus class (§8.7 mutual-exclusion) ───────────────────────────────
+export const SURFACE_FOCUS = {
+    takeover: 'focus-stealing',
+    modal: 'focus-stealing',
+    banner: 'ambient',
+    toast: 'ambient',
+    slideover: 'ambient',
+    panel: 'ambient',
+    popover: 'ambient',
+    coachmark: 'ambient',
+    tour: 'ambient',
+    hotspot: 'ambient',
+    toolbar: 'ambient',
+    launcher: 'always-available', // launcher is always mountable; typed loosely on purpose
+    palette: 'on-demand',
+    center: 'none',
+    inline: 'in-flow',
+    checklist: 'ambient',
+};
+// ── Surface → attention cost (§8.3 token bucket) ────────────────────────────────
+// Ambient/passive surfaces spend 0 budget; interruptive ones spend more.
+export const SURFACE_COST = {
+    takeover: 5,
+    modal: 3,
+    tour: 2,
+    banner: 1,
+    toast: 0.5,
+    slideover: 0,
+    panel: 0,
+    popover: 0,
+    coachmark: 0,
+    hotspot: 0,
+    toolbar: 0,
+    inline: 0,
+    center: 0,
+    launcher: 0,
+    palette: 0,
+    checklist: 0,
+};
+// ── Zone capacities (§8.1) ──────────────────────────────────────────────────────
+// -1 ⇒ unbounded. Refined per concrete zone key (inline:* is always cap 1 per slot).
+export const ZONE_CAP = {
+    takeover: 1,
+    modal: 1,
+    'top-banner': 1,
+    'bottom-banner': 1,
+    toast: 3,
+    'side-right': 1,
+    'side-left': 1,
+    anchored: 1, // 1 active spotlight; passive hotspots handled as cost-0 coexisting
+    launcher: 1,
+    palette: 1,
+    center: -1,
+};
+// ── Priority tier base weights (§8.2) ───────────────────────────────────────────
+export const TIER_WEIGHT = {
+    critical: 1000,
+    high: 400,
+    normal: 200,
+    low: 100,
+    passive: 50,
+};
+// ── The two globally-exclusive focus-stealing zones ─────────────────────────────
+export const FOCUS_STEALING_ZONES = ['takeover', 'modal'];
+/** Resolve the concrete zone for a variant, refining the static map with its surfaceOptions. */
+export function zoneForVariant(v) {
+    if (v.surface === 'banner') {
+        return v.surfaceOptions?.placement === 'bottom' ? 'bottom-banner' : 'top-banner';
+    }
+    if (v.surface === 'panel') {
+        return v.surfaceOptions?.placement === 'right' ? 'side-right' : 'side-left';
+    }
+    if (v.surface === 'slideover') {
+        return v.surfaceOptions?.placement === 'left' ? 'side-left' : 'side-right';
+    }
+    if (v.surface === 'inline') {
+        return `inline:${v.surfaceOptions?.slot ?? 'default'}`;
+    }
+    return SURFACE_ZONE[v.surface];
+}
+/** Capacity for a concrete zone key (handles the dynamic `inline:<slot>` family). */
+export function zoneCap(zone) {
+    if (zone.startsWith('inline:'))
+        return 1;
+    return ZONE_CAP[zone] ?? 1;
+}
+const RE_ID = /^[a-z0-9][a-z0-9_-]*$/i;
+/**
+ * Validate one variant against the contract. Returns [] when valid. Pure + zero-dep so the same code
+ * runs in the browser (before render) and on the server (before publish).
+ */
+export function validateVariant(v) {
+    const issues = [];
+    const bad = (path, message) => issues.push({ path, message });
+    if (!v || typeof v !== 'object')
+        return [{ path: '', message: 'variant is not an object' }];
+    if (!v.id || !RE_ID.test(v.id))
+        bad('id', 'missing or malformed id');
+    if (!v.key)
+        bad('key', 'missing key');
+    if (!SURFACES.includes(v.surface))
+        bad('surface', `unknown surface "${v.surface}"`);
+    if (!PRIORITY_TIERS.includes(v.priority))
+        bad('priority', `unknown priority "${v.priority}"`);
+    if (!Array.isArray(v.platforms) || v.platforms.length === 0) {
+        bad('platforms', 'at least one platform required');
+    }
+    else {
+        for (const p of v.platforms)
+            if (!PLATFORMS.includes(p))
+                bad('platforms', `unknown platform "${p}"`);
+    }
+    if (!Array.isArray(v.blocks) || v.blocks.length === 0) {
+        bad('blocks', 'at least one block required');
+    }
+    else {
+        v.blocks.forEach((b, i) => {
+            if (!b || !BLOCK_KINDS.includes(b.kind))
+                bad(`blocks[${i}].kind`, `unknown block kind "${b?.kind}"`);
+        });
+    }
+    if (!Array.isArray(v.triggers) || v.triggers.length === 0) {
+        bad('triggers', 'at least one trigger required');
+    }
+    else {
+        v.triggers.forEach((t, i) => {
+            if (!t || !TRIGGER_TYPES.includes(t.type))
+                bad(`triggers[${i}].type`, `unknown trigger "${t?.type}"`);
+            // element/hover/selection/right-click triggers must carry a selector to bind to.
+            if ((t?.type === 'element' || t?.type === 'hover') && !t.match) {
+                bad(`triggers[${i}].match`, `${t.type} trigger requires a selector`);
+            }
+            if (t?.type === 'idle' && (typeof t.arg !== 'number' || t.arg <= 0)) {
+                bad(`triggers[${i}].arg`, 'idle trigger requires a positive ms arg');
+            }
+        });
+    }
+    // Anchored surfaces need something to anchor to — a targeting element or an element/hover trigger.
+    const anchored = ['popover', 'coachmark', 'hotspot', 'toolbar'];
+    if (anchored.includes(v.surface)) {
+        const hasAnchor = !!v.targeting?.element || (v.triggers ?? []).some((t) => t.match && (t.type === 'element' || t.type === 'hover'));
+        if (!hasAnchor)
+            bad('targeting.element', `${v.surface} requires an anchor selector`);
+    }
+    // Required-blocks contract: every block the variant declares as required must be present.
+    const required = v.contract?.requiredBlocks ?? [];
+    const present = new Set((v.blocks ?? []).map((b) => b?.kind));
+    for (const rb of required)
+        if (!present.has(rb))
+            bad('contract.requiredBlocks', `missing required block "${rb}"`);
+    return issues;
+}
+/** Convenience: is this variant contract-valid? */
+export function isValidVariant(v) {
+    return validateVariant(v).length === 0;
+}
+/**
+ * Server-authoritative guard (§P4.2): strip preview-only block props (e.g. a quiz answer key) from a
+ * variant before it reaches the client. Pure — returns a new variant; never mutates the input. The
+ * server calls this before serving; the SDK can call it defensively on ingest.
+ */
+export function stripPreviewOnly(v) {
+    const keys = v.contract?.previewOnlyFields;
+    if (!keys || keys.length === 0)
+        return v;
+    const drop = new Set(keys);
+    return {
+        ...v,
+        blocks: v.blocks.map((b) => {
+            if (!b.props)
+                return b;
+            const props = {};
+            for (const [k, val] of Object.entries(b.props))
+                if (!drop.has(k))
+                    props[k] = val;
+            return { ...b, props };
+        }),
+    };
+}
+//# sourceMappingURL=inappContract.web.js.map