impact-nova 2.5.22 → 2.6.0

package/dist/lib/guidance/engine/guidance-engine.d.ts

@@ -6,6 +6,7 @@ import { GuidanceTargetRefRegistry } from '../targets/ref-registry';
 type Listener = () => void;
 export declare class GuidanceEngine {
     private sessionState;
+    private activationToken;
     private readonly listeners;
     private readonly eventHandlers;
     private readonly guideRegistry;
@@ -47,9 +48,17 @@ export declare class GuidanceEngine {
     private resolveGuideStartStepIndex;
     dismiss(dismissMode?: 'session' | 'forever' | 'snoozed'): Promise<void>;
     snooze(guideId?: string): Promise<void>;
+    goToPreviousStep(): Promise<void>;
+    goToStep(stepId: string): Promise<void>;
     advanceStep(): Promise<void>;
     retryCurrentStep(): Promise<void>;
     skipStep(): Promise<void>;
+    /**
+     * Leaves a step whose target will not appear, including while the engine is
+     * still waiting for that target.
+     */
+    continuePastUnavailableStep(): Promise<void>;
+    private moveToFollowingStep;
     getRenderInstruction(): RenderInstruction | null;
     private syncRenderInstructionCache;
     evaluateTriggers(routeScope?: string): Promise<void>;

package/dist/lib/guidance/engine/guidance-engine.js

@@ -1,15 +1,16 @@
-import { GuideRegistry as l } from "./guide-registry.js";
-import { getStepIndex as u, getNextStepId as p, getStepById as S, resolveLocalizedStepContent as f } from "./step-navigation.js";
+import { GuideRegistry as S } from "./guide-registry.js";
+import { getStepIndex as u, getNextStepId as c, getStepById as g, resolveLocalizedStepContent as f } from "./step-navigation.js";
 import { TriggerPluginRegistry as v } from "../triggers/trigger-registry.js";
 import { registerBuiltInTriggerPlugins as w } from "../triggers/built-in-triggers.js";
-import { TargetResolver as m, resolveTargetSynchronously as y, waitForTargetResolved as I } from "../targets/target-resolver.js";
+import { TargetResolver as m, resolveTargetSynchronously as I, waitForTargetResolved as y } from "../targets/target-resolver.js";
 import { GuidanceTargetRefRegistry as R } from "../targets/ref-registry.js";
-import { buildGuidanceStorageKey as a, buildSessionStatsKey as g, createDefaultSessionStats as G } from "../storage/storage-keys.js";
+import { buildGuidanceStorageKey as r, buildSessionStatsKey as h, createDefaultSessionStats as G } from "../storage/storage-keys.js";
 class _ {
   sessionState = { status: "idle" };
+  activationToken = 0;
   listeners = /* @__PURE__ */ new Set();
   eventHandlers = /* @__PURE__ */ new Map();
-  guideRegistry = new l();
+  guideRegistry = new S();
   triggerRegistry = new v();
   targetRefRegistry = new R();
   targetResolver;
@@ -127,7 +128,7 @@ class _ {
     const e = this.sessionState.guideId;
     if (e) {
       if (t === "forever" && await this.config.storage.set({
-        [a(this.config.tenantId, e, "dismissed")]: {
+        [r(this.config.tenantId, e, "dismissed")]: {
           dismissed: !0,
           timestamp: Date.now()
         }
@@ -141,6 +142,26 @@ class _ {
   async snooze(t) {
     (t ?? this.sessionState.guideId) && await this.dismiss("snoozed");
   }
+  async goToPreviousStep() {
+    const t = this.sessionState.guideId, e = this.sessionState.stepId;
+    if (!t || !e || this.sessionState.status !== "active")
+      return;
+    const s = this.guideRegistry.get(t);
+    if (!s)
+      return;
+    const i = u(s, e);
+    i <= 0 || s.steps[i - 1]?.advanceOn !== "click-next" || await this.activateGuide(s, i - 1);
+  }
+  async goToStep(t) {
+    const e = this.sessionState.guideId;
+    if (!e || this.sessionState.status !== "active")
+      return;
+    const s = this.guideRegistry.get(e);
+    if (!s)
+      return;
+    const i = u(s, t);
+    i < 0 || await this.activateGuide(s, i);
+  }
   async advanceStep() {
     const t = this.sessionState.guideId, e = this.sessionState.stepId;
     if (!t || !e || this.sessionState.status !== "active")
@@ -149,10 +170,10 @@ class _ {
     if (!s)
       return;
     this.track("step.completed", { guideId: t, stepId: e });
-    const i = await p(
+    const i = await c(
       s,
       e,
-      (r) => this.triggerRegistry.evaluateExpression(r, this.buildTriggerContext())
+      (a) => this.triggerRegistry.evaluateExpression(a, this.buildTriggerContext())
     );
     if (!i) {
       await this.completeGuide(t);
@@ -173,7 +194,38 @@ class _ {
   }
   async skipStep() {
     const t = this.sessionState.guideId, e = this.sessionState.stepId;
-    !t || !e || (this.track("step.skipped", { guideId: t, stepId: e }), await this.advanceStep());
+    if (!t || !e || this.sessionState.status !== "active")
+      return;
+    const s = this.guideRegistry.get(t);
+    !s || !g(s, e)?.skippable || await this.moveToFollowingStep();
+  }
+  /**
+   * Leaves a step whose target will not appear, including while the engine is
+   * still waiting for that target.
+   */
+  async continuePastUnavailableStep() {
+    const t = this.sessionState.status;
+    t !== "evaluating" && t !== "blocked" && t !== "active" || (this.activationToken += 1, await this.moveToFollowingStep());
+  }
+  async moveToFollowingStep() {
+    const t = this.sessionState.guideId, e = this.sessionState.stepId;
+    if (!t || !e)
+      return;
+    const s = this.guideRegistry.get(t);
+    if (!s)
+      return;
+    this.track("step.skipped", { guideId: t, stepId: e });
+    const i = await c(
+      s,
+      e,
+      (a) => this.triggerRegistry.evaluateExpression(a, this.buildTriggerContext())
+    );
+    if (!i) {
+      await this.completeGuide(t);
+      return;
+    }
+    const n = u(s, i);
+    await this.activateGuide(s, n);
   }
   getRenderInstruction() {
     return this.cachedRenderInstruction;
@@ -183,11 +235,12 @@ class _ {
       this.cachedRenderInstruction = null;
       return;
     }
-    const t = this.guideRegistry.get(this.sessionState.guideId), e = t ? S(t, this.sessionState.stepId) : void 0;
+    const t = this.guideRegistry.get(this.sessionState.guideId), e = t ? g(t, this.sessionState.stepId) : void 0;
     if (!t || !e) {
       this.cachedRenderInstruction = null;
       return;
     }
+    const s = this.sessionState.stepIndex > 0 ? t.steps[this.sessionState.stepIndex - 1] : void 0;
     this.cachedRenderInstruction = {
       guideId: t.id,
       stepId: e.id,
@@ -197,7 +250,11 @@ class _ {
       content: f(t, e, this.config.locale),
       target: this.sessionState.resolvedTarget ?? null,
       skippable: e.skippable,
-      advanceOn: e.advanceOn
+      advanceOn: e.advanceOn,
+      canGoBack: s?.advanceOn === "click-next",
+      placement: e.placement ?? "auto",
+      modalBehavior: e.modalBehavior,
+      interactionFooter: e.interactionFooter
     };
   }
   async evaluateTriggers(t) {
@@ -207,106 +264,111 @@ class _ {
     if (e.guidesShownThisSession >= this.config.maxGuidesPerSession || e.lastGuideEndedAt && Date.now() - e.lastGuideEndedAt < this.config.cooldownBetweenGuides)
       return;
     const s = t ? this.guideRegistry.getForRoute(t) : [], i = s.length > 0 ? s : this.guideRegistry.getAll();
-    await this.hydrateVisitCounts(i.map((o) => o.id));
+    await this.hydrateVisitCounts(i.map((d) => d.id));
     const n = [];
-    for (const o of this.guideRegistry.getSortedByPriority(
-      i.map((d) => d.id)
+    for (const d of this.guideRegistry.getSortedByPriority(
+      i.map((o) => o.id)
     ))
-      await this.isGuideEligible(o, e) && n.push(o);
+      await this.isGuideEligible(d, e) && n.push(d);
     if (!n.length)
       return;
-    const r = n[0];
+    const a = n[0];
     this.log("evaluateTriggers.start", {
-      guideId: r.id,
+      guideId: a.id,
       routePath: this.routePath
-    }), this.track("guide.triggered", { guideId: r.id }), await this.start(r.id);
+    }), this.track("guide.triggered", { guideId: a.id }), await this.start(a.id);
   }
   async activateGuide(t, e) {
-    const s = t.steps[e];
-    if (!s) {
+    const s = ++this.activationToken, i = t.steps[e];
+    if (!i) {
       await this.completeGuide(t.id);
       return;
     }
-    let i = null;
-    if (s.target) {
-      if (i = y(
+    let n = null;
+    if (i.target) {
+      if (n = I(
         this.targetResolver,
-        s.target
-      ), i?.element || (this.setSession({
+        i.target
+      ), n?.element || (this.setSession({
         status: "evaluating",
         guideId: t.id,
         stepIndex: e,
-        stepId: s.id
-      }), i = await I(
+        stepId: i.id
+      }), n = await y(
         this.targetResolver,
-        s.target,
-        s.timeout ?? 5e3
-      )), !i?.element) {
+        i.target,
+        i.timeout ?? 5e3,
+        () => s !== this.activationToken
+      )), s !== this.activationToken)
+        return;
+      if (!n?.element) {
         this.log("activateGuide.blocked", {
           guideId: t.id,
-          stepId: s.id,
+          stepId: i.id,
           stepIndex: e,
-          reason: i ? "target_not_visible" : "target_not_found",
-          targetId: s.target?.targetId
+          reason: n ? "target_not_visible" : "target_not_found",
+          targetId: i.target?.targetId
         }), this.setSession({
           status: "blocked",
           guideId: t.id,
           stepIndex: e,
-          stepId: s.id,
-          reason: i ? "target_not_visible" : "target_not_found"
+          stepId: i.id,
+          reason: n ? "target_not_visible" : "target_not_found"
         });
         return;
       }
-    } else if (s.renderer !== "announcement") {
+    } else if (i.renderer !== "announcement") {
       this.log("activateGuide.blocked", {
         guideId: t.id,
-        stepId: s.id,
+        stepId: i.id,
         stepIndex: e,
         reason: "target_not_found"
       }), this.setSession({
         status: "blocked",
         guideId: t.id,
         stepIndex: e,
-        stepId: s.id,
+        stepId: i.id,
         reason: "target_not_found"
       });
       return;
     }
-    const n = this.sessionState;
-    if (n.status === "idle" || n.guideId !== t.id) {
-      this.log("guideStart", { guideId: t.id, stepId: s.id }), this.emitEvent("guideStart", { guideId: t.id, stepId: s.id }), this.track("guide.started", { guideId: t.id });
+    if (s !== this.activationToken)
+      return;
+    const a = this.sessionState;
+    if (a.status === "idle" || a.guideId !== t.id) {
+      this.log("guideStart", { guideId: t.id, stepId: i.id }), this.emitEvent("guideStart", { guideId: t.id, stepId: i.id }), this.track("guide.started", { guideId: t.id });
       const o = await this.loadSessionStats();
       o.guidesShownThisSession += 1, await this.saveSessionStats(o), await this.incrementVisitCount(t.id);
     }
-    this.emitEvent("stepChange", { guideId: t.id, stepId: s.id }), this.track("step.viewed", { guideId: t.id, stepId: s.id }), this.log("step.active", {
+    this.emitEvent("stepChange", { guideId: t.id, stepId: i.id }), this.track("step.viewed", { guideId: t.id, stepId: i.id }), this.log("step.active", {
       guideId: t.id,
-      stepId: s.id,
+      stepId: i.id,
       stepIndex: e,
-      hasTarget: !!s.target
+      hasTarget: !!i.target
     }), this.setSession({
       status: "active",
       guideId: t.id,
       stepIndex: e,
-      stepId: s.id,
-      resolvedTarget: i?.element ? {
-        ...i,
-        rect: i.element.getBoundingClientRect()
+      stepId: i.id,
+      resolvedTarget: n?.element ? {
+        ...n,
+        rect: n.element.getBoundingClientRect()
       } : void 0
     }), t.persistence.resumeOnRefresh && await this.config.storage.set({
-      [a(this.config.tenantId, t.id, "lastStep")]: {
-        stepId: s.id,
+      [r(this.config.tenantId, t.id, "lastStep")]: {
+        stepId: i.id,
         timestamp: Date.now()
       }
     });
   }
   async completeGuide(t) {
     this.guideRegistry.get(t)?.persistence.mode === "showOnce" && await this.config.storage.set({
-      [a(this.config.tenantId, t, "dismissed")]: {
+      [r(this.config.tenantId, t, "dismissed")]: {
         dismissed: !0,
         timestamp: Date.now()
       }
     }), await this.config.storage.delete([
-      a(this.config.tenantId, t, "lastStep")
+      r(this.config.tenantId, t, "lastStep")
     ]);
     const s = await this.loadSessionStats();
     s.lastGuideEndedAt = Date.now(), await this.saveSessionStats(s), this.emitEvent("guideEnd", { guideId: t, reason: "completed" }), this.track("guide.completed", { guideId: t }), this.setSession({ status: "completed", guideId: t }), await this.dequeueNextGuide();
@@ -321,19 +383,19 @@ class _ {
     return this.isGuideEligible(s, i);
   }
   async isGuideEligible(t, e) {
-    const s = a(
+    const s = r(
       this.config.tenantId,
       t.id,
       "dismissed"
     );
     if ((await this.config.storage.get([s]))[s]?.dismissed && t.persistence.mode !== "replayable")
       return !1;
-    const r = e.snoozedUntil[t.id];
-    if (r && Date.now() < r || (e.dismissedCounts[t.id] ?? 0) >= 3 && t.persistence.mode === "showOnce")
+    const a = e.snoozedUntil[t.id];
+    if (a && Date.now() < a || (e.dismissedCounts[t.id] ?? 0) >= 3 && t.persistence.mode === "showOnce")
       return !1;
     if (t.persistence.schedule) {
-      const d = Date.now(), c = Date.parse(t.persistence.schedule.start), h = Date.parse(t.persistence.schedule.end);
-      if (d < c || d > h)
+      const o = Date.now(), l = Date.parse(t.persistence.schedule.start), p = Date.parse(t.persistence.schedule.end);
+      if (o < l || o > p)
         return !1;
     }
     return this.triggerRegistry.evaluateAll(
@@ -371,31 +433,31 @@ class _ {
     await this.start(t);
   }
   async loadSessionStats() {
-    const t = g(this.config.tenantId);
+    const t = h(this.config.tenantId);
     return (await this.config.storage.get([t]))[t] ?? G();
   }
   async saveSessionStats(t) {
     await this.config.storage.set({
-      [g(this.config.tenantId)]: t
+      [h(this.config.tenantId)]: t
     });
   }
   async hydrateVisitCounts(t) {
     if (!t.length)
       return;
     const e = t.map(
-      (i) => a(this.config.tenantId, i, "visitCount")
+      (i) => r(this.config.tenantId, i, "visitCount")
     ), s = await this.config.storage.get(e);
     for (const i of t) {
-      const n = a(
+      const n = r(
         this.config.tenantId,
         i,
         "visitCount"
-      ), r = s[n];
-      typeof r == "number" && (this.visitCounts[i] = r);
+      ), a = s[n];
+      typeof a == "number" && (this.visitCounts[i] = a);
     }
   }
   async incrementVisitCount(t) {
-    const e = a(
+    const e = r(
       this.config.tenantId,
       t,
       "visitCount"
@@ -413,7 +475,7 @@ class _ {
   }
   async clearPersistedLastStep(t) {
     await this.config.storage.delete([
-      a(this.config.tenantId, t, "lastStep")
+      r(this.config.tenantId, t, "lastStep")
     ]);
   }
   scheduleEvaluation() {

package/dist/lib/guidance/engine/manifest-validator.js

@@ -1,16 +1,17 @@
-function a(t) {
+function c(t) {
   return {
     ...t,
-    title: c(t.title),
-    body: c(t.body),
-    footer: t.footer ? c(t.footer) : void 0,
+    title: o(t.title),
+    body: o(t.body),
+    badge: d(t.badge),
+    footer: t.footer ? o(t.footer) : void 0,
     media: t.media ? {
       ...t.media,
       src: l(t.media.src)
     } : void 0,
     actions: t.actions?.map((i) => ({
       ...i,
-      label: c(i.label)
+      label: o(i.label)
     }))
   };
 }
@@ -19,17 +20,23 @@ function p(t) {
     ...t,
     steps: t.steps.map((i) => ({
       ...i,
-      content: a(i.content)
+      content: c(i.content)
     })),
     locale: Object.fromEntries(
       Object.entries(t.locale).map(([i, n]) => [
         i,
-        n.map((r) => a(r))
+        n.map((e) => c(e))
       ])
     )
   };
 }
-function c(t) {
+function d(t) {
+  if (!t)
+    return;
+  const i = o(t);
+  return i.length > 0 ? i : void 0;
+}
+function o(t) {
   return t.replace(/<[^>]*>/g, "").replace(/javascript:/gi, "").trim();
 }
 function l(t) {
@@ -44,18 +51,18 @@ function l(t) {
   }
   return "";
 }
-function f(t) {
+function h(t) {
   const i = [];
   t.schemaVersion !== 1 && i.push(`Unsupported schemaVersion: ${t.schemaVersion}`), t.id || i.push("Guide manifest requires id"), t.steps.length || i.push("Guide manifest requires at least one step");
   const n = /* @__PURE__ */ new Set();
-  for (const r of t.steps)
-    n.has(r.id) && i.push(`Duplicate step id: ${r.id}`), n.add(r.id), (r.content.body.includes("<script") || r.content.body.includes("javascript:")) && i.push(`Step ${r.id} body contains disallowed content`);
+  for (const e of t.steps)
+    n.has(e.id) && i.push(`Duplicate step id: ${e.id}`), n.add(e.id), (e.content.body.includes("<script") || e.content.body.includes("javascript:")) && i.push(`Step ${e.id} body contains disallowed content`);
   if (t.transitions?.length) {
-    const r = d(t);
-    r && i.push(r);
+    const e = f(t);
+    e && i.push(e);
   }
-  for (const r of t.triggers) {
-    const s = u(r);
+  for (const e of t.triggers) {
+    const s = u(e);
     s && i.push(s);
   }
   return i;
@@ -73,30 +80,30 @@ function u(t) {
   }
   return t.plugin ? null : "Trigger plugin key is required";
 }
-function d(t) {
+function f(t) {
   const i = /* @__PURE__ */ new Map();
-  for (const e of t.transitions ?? []) {
-    const o = i.get(e.from) ?? [];
-    o.push(e.to), i.set(e.from, o);
+  for (const r of t.transitions ?? []) {
+    const a = i.get(r.from) ?? [];
+    a.push(r.to), i.set(r.from, a);
   }
-  const n = /* @__PURE__ */ new Set(), r = /* @__PURE__ */ new Set(), s = (e) => {
-    if (n.has(e))
+  const n = /* @__PURE__ */ new Set(), e = /* @__PURE__ */ new Set(), s = (r) => {
+    if (n.has(r))
       return !0;
-    if (r.has(e))
+    if (e.has(r))
       return !1;
-    n.add(e);
-    for (const o of i.get(e) ?? [])
-      if (s(o))
+    n.add(r);
+    for (const a of i.get(r) ?? [])
+      if (s(a))
         return !0;
-    return n.delete(e), r.add(e), !1;
+    return n.delete(r), e.add(r), !1;
   };
-  for (const e of t.steps)
-    if (s(e.id))
+  for (const r of t.steps)
+    if (s(r.id))
       return "Guide transitions contain a cycle";
   return null;
 }
 export {
   p as sanitizeGuideManifest,
-  a as sanitizeStepContent,
-  f as validateGuideManifest
+  c as sanitizeStepContent,
+  h as validateGuideManifest
 };

package/dist/lib/guidance/targets/target-resolver.d.ts

@@ -9,5 +9,5 @@ export declare class TargetResolver {
     resolve(descriptor: TargetDescriptor, scopeRoot?: HTMLElement | null, adapterType?: string, adapterConfig?: Record<string, unknown>): ResolvedTarget | null;
 }
 export declare function resolveTargetSynchronously(resolver: TargetResolver, descriptor: TargetDescriptor): ResolvedTarget | null;
-export declare function waitForTargetResolved(resolver: TargetResolver, descriptor: TargetDescriptor, timeoutMs?: number): Promise<ResolvedTarget | null>;
+export declare function waitForTargetResolved(resolver: TargetResolver, descriptor: TargetDescriptor, timeoutMs?: number, isCancelled?: () => boolean): Promise<ResolvedTarget | null>;
 export declare function waitForTargetVisible(element: HTMLElement, timeoutMs?: number): Promise<boolean>;

package/dist/lib/guidance/targets/target-resolver.js

@@ -10,18 +10,18 @@ class f {
   unregisterAdapter(e) {
     this.adapterPlugins.delete(e);
   }
-  resolve(e, t, n, r) {
-    if (n) {
-      const s = this.adapterPlugins.get(n);
-      if (s?.resolve) {
+  resolve(e, t, s, n) {
+    if (s) {
+      const i = this.adapterPlugins.get(s);
+      if (i?.resolve) {
         const o = {
           targetDescriptor: e,
           scopeRoot: t
         };
         try {
-          const l = s.resolve(
+          const l = i.resolve(
             o,
-            r ?? {}
+            n ?? {}
           );
           if (l && !(l instanceof Promise))
             return l;
@@ -33,48 +33,50 @@ class f {
     return this.refRegistry.resolveDescriptor(e, t);
   }
 }
-const c = 16;
-function u(i) {
-  const e = i.getBoundingClientRect();
+const u = 16;
+function c(r) {
+  const e = r.getBoundingClientRect();
   return e.width > 0 && e.height > 0;
 }
-function d(i, e) {
-  const t = i.resolve(e);
-  return !t?.element || e.waitUntil === "visible" && !u(t.element) ? null : t;
+function d(r, e) {
+  const t = r.resolve(e);
+  return !t?.element || e.waitUntil === "visible" && !c(t.element) ? null : t;
 }
-async function w(i, e, t = 5e3) {
+async function w(r, e, t = 5e3, s) {
   const n = Date.now();
   for (; Date.now() - n < t; ) {
-    const r = i.resolve(e);
-    if (r?.element)
+    if (s?.())
+      return null;
+    const i = r.resolve(e);
+    if (i?.element)
       if (e.waitUntil === "visible") {
-        const s = t - (Date.now() - n);
+        const o = t - (Date.now() - n);
         if (await g(
-          r.element,
-          Math.max(s, c)
+          i.element,
+          Math.max(o, u)
         ))
-          return r;
+          return i;
       } else
-        return r;
-    await new Promise((s) => {
-      window.setTimeout(s, c);
+        return i;
+    await new Promise((o) => {
+      window.setTimeout(o, u);
     });
   }
   return null;
 }
-function g(i, e = 5e3) {
+function g(r, e = 5e3) {
   if (typeof window > "u" || typeof IntersectionObserver > "u")
     return Promise.resolve(!0);
-  const t = i.getBoundingClientRect();
-  return t.width > 0 && t.height > 0 ? Promise.resolve(!0) : new Promise((n) => {
-    const r = new IntersectionObserver((o) => {
+  const t = r.getBoundingClientRect();
+  return t.width > 0 && t.height > 0 ? Promise.resolve(!0) : new Promise((s) => {
+    const n = new IntersectionObserver((o) => {
       o.some(
         (a) => a.isIntersecting && a.intersectionRatio > 0
-      ) && (r.disconnect(), clearTimeout(s), n(!0));
-    }), s = setTimeout(() => {
-      r.disconnect(), n(!1);
+      ) && (n.disconnect(), clearTimeout(i), s(!0));
+    }), i = setTimeout(() => {
+      n.disconnect(), s(!1);
     }, e);
-    r.observe(i);
+    n.observe(r);
   });
 }
 export {