impact-nova 2.5.6 → 2.5.8

package/dist/lib/fiscal-calendar/types.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Headless fiscal calendar types. No React. Civil dates are YYYY-MM-DD.
+ */
+export type CivilDate = string;
+export type CalendarKind = "gregorian" | "fiscal";
+export type FiscalMode = "basic" | "advanced" | "custom";
+export type RetailPatternId = "4-4-5" | "4-5-4" | "5-4-4";
+export type LeapWeekPolicy = "append-last-period" | "period-13";
+export type FyLabelStyle = "fy-short" | "fy-long" | "ending-year" | "starting-year";
+export type Weekday = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/** Per-period week counts, e.g. [4,4,5,4,4,5,4,4,5,4,4,5] */
+export type FiscalMonthPattern = number[];
+export type FyAnchorRule = "on-or-before" | "closest-weekday";
+export type FiscalCalendarConfig = {
+    kind: "shifted-year";
+    fyStartMonth: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+    fyStartDay?: number;
+    fyLabel?: FyLabelStyle;
+    weekStartsOn?: Weekday;
+} | {
+    kind: "retail";
+    pattern: RetailPatternId | FiscalMonthPattern;
+    weekStartsOn: Weekday;
+    fyAnchor: {
+        month: number;
+        day: number;
+        rule: FyAnchorRule;
+    };
+    leapWeekPolicy?: LeapWeekPolicy;
+    fyLabel?: FyLabelStyle;
+} | {
+    kind: "custom-table";
+    periods: ReadonlyArray<{
+        fy: number;
+        period: number;
+        start: CivilDate;
+        end: CivilDate;
+    }>;
+    fyLabel?: FyLabelStyle;
+    weekStartsOn?: Weekday;
+};
+export interface FiscalWeek {
+    fy: number;
+    week: number;
+    start: CivilDate;
+    end: CivilDate;
+    period: number;
+    quarter: 1 | 2 | 3 | 4;
+}
+export interface FiscalPeriod {
+    fy: number;
+    period: number;
+    label: string;
+    displayLabel: string;
+    start: CivilDate;
+    end: CivilDate;
+    weekCount: number;
+    quarter: 1 | 2 | 3 | 4;
+    gregorianMonthSpan: ReadonlyArray<{
+        year: number;
+        month: number;
+    }>;
+}
+export interface FiscalQuarter {
+    fy: number;
+    quarter: 1 | 2 | 3 | 4;
+    start: CivilDate;
+    end: CivilDate;
+    periods: readonly number[];
+}
+export interface FiscalYearModel {
+    fy: number;
+    start: CivilDate;
+    end: CivilDate;
+    weekCount: 52 | 53;
+    periodCount: 12 | 13;
+    weeks: readonly FiscalWeek[];
+    periods: readonly FiscalPeriod[];
+    quarters: readonly FiscalQuarter[];
+}
+export interface DateCellMeta {
+    iso: CivilDate;
+    gregorian: {
+        year: number;
+        month: number;
+        day: number;
+    };
+    fy?: number;
+    fiscalWeek?: number;
+    fiscalPeriod?: number;
+    fiscalQuarter?: 1 | 2 | 3 | 4;
+    isPeriodStart?: boolean;
+    isPeriodEnd?: boolean;
+    isFyStart?: boolean;
+    isFyEnd?: boolean;
+    crossesGregorianMonth?: boolean;
+}
+export type Granularity = "day" | "week" | "period" | "quarter" | "year";
+export type CalendarSelectionMode = "single" | "multiple" | "range" | "multi-range";
+export interface CalendarInterval {
+    start: CivilDate;
+    end: CivilDate;
+    granularity: Granularity;
+    fy?: number;
+    period?: number;
+    week?: number;
+    quarter?: 1 | 2 | 3 | 4;
+}
+export type CalendarSelection = {
+    mode: "single";
+    value: CalendarInterval | null;
+} | {
+    mode: "multiple";
+    value: CalendarInterval[];
+} | {
+    mode: "range";
+    value: {
+        from: CalendarInterval;
+        to?: CalendarInterval;
+    } | null;
+} | {
+    mode: "multi-range";
+    value: Array<{
+        from: CalendarInterval;
+        to: CalendarInterval;
+    }>;
+};
+/** Picker-facing week value. Dates are local civil midnights. */
+export interface WeekSelection {
+    year: number;
+    month: number;
+    weekOfMonth: number;
+    startDate: Date;
+    endDate: Date;
+}
+/** Legacy fiscal-month block described as a WeekSelection (weekOfMonth = period index). */
+export interface FiscalMonth {
+    index: number;
+    startDate: Date;
+    endDate: Date;
+    weekCount: number;
+}
+export declare const FISCAL_PATTERNS: Record<RetailPatternId, FiscalMonthPattern>;
+export declare const DEFAULT_LEAP_WEEK_POLICY: LeapWeekPolicy;
+export declare const DEFAULT_FY_LABEL: FyLabelStyle;

package/dist/lib/fiscal-calendar/types.js

@@ -0,0 +1,10 @@
+const E = {
+  "4-4-5": [4, 4, 5, 4, 4, 5, 4, 4, 5, 4, 4, 5],
+  "4-5-4": [4, 5, 4, 4, 5, 4, 4, 5, 4, 4, 5, 4],
+  "5-4-4": [5, 4, 4, 5, 4, 4, 5, 4, 4, 5, 4, 4]
+}, L = "append-last-period", o = "fy-short";
+export {
+  o as DEFAULT_FY_LABEL,
+  L as DEFAULT_LEAP_WEEK_POLICY,
+  E as FISCAL_PATTERNS
+};

package/dist/lib/fiscal-calendar/week-selection.d.ts

@@ -0,0 +1,22 @@
+import { CalendarKind, FiscalMode, FiscalMonth, FiscalMonthPattern, Granularity, WeekSelection, FiscalCalendarConfig, Weekday } from './types';
+export type { FiscalMode, FiscalMonth, FiscalMonthPattern };
+export declare function getFiscalWeekSelection(date: Date, weekStartsOn: Weekday): WeekSelection;
+export declare function buildFiscalMonthCalendar(civilYear: number, pattern: FiscalMonthPattern, weekStartsOn: Weekday, fiscalYearStartMonth?: number): FiscalMonth[];
+export declare function getFiscalMonthSelection(date: Date, fiscalCalendar: FiscalMonth[]): WeekSelection | undefined;
+export declare function getCalendarWeekSelection(date: Date, weekStartsOn: Weekday): WeekSelection;
+export interface ResolveWeekSelectionOptions {
+    calendarKind?: CalendarKind;
+    fiscalMode?: FiscalMode;
+    granularity?: Granularity;
+    fiscalMonthPattern?: FiscalMonthPattern;
+    fiscalYearStartMonth?: number;
+    weekStartsOn?: Weekday;
+}
+export declare function resolveWeekSelection(date: Date, options?: ResolveWeekSelectionOptions): WeekSelection;
+export declare function toFiscalCalendarConfig(options: {
+    calendarKind?: CalendarKind;
+    fiscalMode?: FiscalMode;
+    fiscalMonthPattern?: FiscalMonthPattern;
+    fiscalYearStartMonth?: number;
+    weekStartsOn?: Weekday;
+}): FiscalCalendarConfig | undefined;

package/dist/lib/fiscal-calendar/week-selection.js

@@ -0,0 +1,107 @@
+import { FISCAL_PATTERNS as y } from "./types.js";
+function g(t, a) {
+  const e = new Date(t), s = (e.getDay() + 7 - a) % 7;
+  return e.setDate(e.getDate() - s), e.setHours(0, 0, 0, 0), e;
+}
+function D(t, a) {
+  const e = new Date(t);
+  return e.setDate(e.getDate() + a), e;
+}
+function u(t, a) {
+  const e = g(t, a), n = D(e, 6), c = new Date(t.getFullYear(), t.getMonth(), 1).getDay(), o = e.getDate(), r = e.getMonth() === t.getMonth() ? o : 1, i = Math.ceil((r + c) / 7);
+  return {
+    year: t.getFullYear(),
+    month: t.getMonth(),
+    weekOfMonth: Math.max(1, i),
+    startDate: e,
+    endDate: n
+  };
+}
+function M(t, a, e, n = 1) {
+  if (a.length !== 12)
+    throw new Error(`fiscalMonthPattern must have exactly 12 entries, got ${a.length}`);
+  const s = new Date(t, n - 1, 1);
+  let c = g(s, e);
+  const o = [];
+  for (let r = 0; r < 12; r++) {
+    const i = a[r], f = new Date(c), l = D(f, i * 7 - 1);
+    o.push({ index: r, startDate: f, endDate: l, weekCount: i }), c = D(l, 1);
+  }
+  return o;
+}
+function w(t, a) {
+  const e = new Date(t);
+  e.setHours(0, 0, 0, 0);
+  for (const n of a) {
+    const s = new Date(n.startDate);
+    s.setHours(0, 0, 0, 0);
+    const c = new Date(n.endDate);
+    if (c.setHours(23, 59, 59, 999), e >= s && e <= c)
+      return {
+        year: n.startDate.getFullYear(),
+        month: n.startDate.getMonth(),
+        weekOfMonth: n.index + 1,
+        startDate: n.startDate,
+        endDate: n.endDate
+      };
+  }
+}
+function d(t, a) {
+  const e = g(t, a), n = D(e, 6), s = new Date(t.getFullYear(), t.getMonth(), 1), c = new Date(t.getFullYear(), t.getMonth() + 1, 0), o = e < s ? new Date(s) : new Date(e), r = n > c ? new Date(c) : new Date(n), f = new Date(o.getFullYear(), o.getMonth(), 1).getDay(), l = o.getDate(), h = Math.ceil((l + f) / 7);
+  return {
+    year: o.getFullYear(),
+    month: o.getMonth(),
+    weekOfMonth: Math.max(1, h),
+    startDate: o,
+    endDate: r
+  };
+}
+function F(t, a = {}) {
+  const {
+    calendarKind: e = "gregorian",
+    fiscalMode: n = "basic",
+    granularity: s,
+    fiscalMonthPattern: c,
+    fiscalYearStartMonth: o = 1,
+    weekStartsOn: r = 1
+  } = a;
+  if (e !== "fiscal")
+    return d(t, r);
+  if (n === "basic" || s !== "period")
+    return u(t, r);
+  const i = c ?? y["4-4-5"];
+  if (i.length !== 12)
+    return u(t, r);
+  const f = M(
+    t.getFullYear(),
+    i,
+    r,
+    o
+  ), l = w(t, f);
+  if (l) return l;
+  const h = M(
+    t.getFullYear() - 1,
+    i,
+    r,
+    o
+  );
+  return w(t, h) ?? u(t, r);
+}
+function S(t) {
+  if (t.calendarKind !== "fiscal") return;
+  const a = t.weekStartsOn ?? 1, e = t.fiscalYearStartMonth ?? 1;
+  return {
+    kind: "retail",
+    pattern: t.fiscalMonthPattern ?? y["4-4-5"],
+    weekStartsOn: a,
+    fyAnchor: { month: e, day: 1, rule: "on-or-before" }
+  };
+}
+export {
+  M as buildFiscalMonthCalendar,
+  d as getCalendarWeekSelection,
+  w as getFiscalMonthSelection,
+  u as getFiscalWeekSelection,
+  F as resolveWeekSelection,
+  S as toFiscalCalendarConfig
+};

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

@@ -1,4 +1,4 @@
-import { GuidanceEngineConfig, GuidanceError, GuidanceEventHandler, GuidanceEventName, GuidanceSessionState, GuideManifest, RenderInstruction, Unsubscribe } from '../types/guidance.types';
+import { GuidanceEngineConfig, GuidanceError, GuidanceEventHandler, GuidanceEventName, GuidanceGuideReplayOptions, GuidanceGuideStartOptions, GuidanceSessionState, GuideManifest, RenderInstruction, Unsubscribe } from '../types/guidance.types';
 import { GuideRegistry } from './guide-registry';
 import { TriggerPluginRegistry } from '../triggers/trigger-registry';
 import { TargetResolver } from '../targets/target-resolver';
@@ -42,13 +42,13 @@ export declare class GuidanceEngine {
     emitCustomEvent(eventName: string): void;
     grantConsent(): void;
     setPreviewMode(enabled: boolean): void;
-    start(guideId: string, options?: {
-        manual?: boolean;
-    }): Promise<void>;
-    replay(guideId: string): Promise<void>;
+    start(guideId: string, options?: GuidanceGuideStartOptions): Promise<void>;
+    replay(guideId: string, options?: GuidanceGuideReplayOptions): Promise<void>;
+    private resolveGuideStartStepIndex;
     dismiss(dismissMode?: 'session' | 'forever' | 'snoozed'): Promise<void>;
     snooze(guideId?: string): Promise<void>;
     advanceStep(): Promise<void>;
+    retryCurrentStep(): Promise<void>;
     skipStep(): Promise<void>;
     getRenderInstruction(): RenderInstruction | null;
     private syncRenderInstructionCache;
@@ -64,6 +64,8 @@ export declare class GuidanceEngine {
     private saveSessionStats;
     private hydrateVisitCounts;
     private incrementVisitCount;
+    private log;
+    private clearPersistedLastStep;
     private scheduleEvaluation;
     private setSession;
     private notify;

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

@@ -1,17 +1,17 @@
-import { GuideRegistry as h } from "./guide-registry.js";
-import { getNextStepId as l, getStepIndex as p, getStepById as f, resolveLocalizedStepContent as S } from "./step-navigation.js";
+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 { TriggerPluginRegistry as v } from "../triggers/trigger-registry.js";
-import { registerBuiltInTriggerPlugins as m } from "../triggers/built-in-triggers.js";
-import { TargetResolver as w, resolveTargetSynchronously as y, waitForTargetResolved as R } from "../targets/target-resolver.js";
-import { GuidanceTargetRefRegistry as I } from "../targets/ref-registry.js";
-import { buildGuidanceStorageKey as a, buildSessionStatsKey as u, createDefaultSessionStats as G } from "../storage/storage-keys.js";
-class P {
+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 { GuidanceTargetRefRegistry as R } from "../targets/ref-registry.js";
+import { buildGuidanceStorageKey as a, buildSessionStatsKey as g, createDefaultSessionStats as G } from "../storage/storage-keys.js";
+class _ {
   sessionState = { status: "idle" };
   listeners = /* @__PURE__ */ new Set();
   eventHandlers = /* @__PURE__ */ new Map();
-  guideRegistry = new h();
+  guideRegistry = new l();
   triggerRegistry = new v();
-  targetRefRegistry = new I();
+  targetRefRegistry = new R();
   targetResolver;
   guideQueue = [];
   previewMode = !1;
@@ -26,7 +26,7 @@ class P {
   cachedRenderInstruction = null;
   config;
   constructor(t) {
-    this.config = t, this.targetResolver = new w(this.targetRefRegistry), m(this.triggerRegistry), this.consentGranted = !t.consentRequired;
+    this.config = t, this.targetResolver = new m(this.targetRefRegistry), w(this.triggerRegistry), this.consentGranted = !t.consentRequired;
   }
   get state() {
     return this.sessionState;
@@ -105,10 +105,23 @@ class P {
       }
       return;
     }
-    await this.canStartGuide(t, e?.manual ?? !1) && await this.activateGuide(s, 0);
+    if (!await this.canStartGuide(t, e?.manual ?? !1))
+      return;
+    const n = this.resolveGuideStartStepIndex(s, e?.stepId);
+    await this.activateGuide(s, n);
+  }
+  async replay(t, e) {
+    this.previewMode = !0, this.sessionState.guideId === t && this.sessionState.status !== "idle" && (this.log("replay.reset-session", {
+      guideId: t,
+      previousStatus: this.sessionState.status,
+      previousStepId: this.sessionState.stepId
+    }), this.emitEvent("guideEnd", { guideId: t, reason: "dismissed" }), await this.clearPersistedLastStep(t), this.setSession({ status: "idle" })), await this.start(t, { manual: !0, stepId: e?.stepId });
   }
-  async replay(t) {
-    this.previewMode = !0, await this.start(t, { manual: !0 });
+  resolveGuideStartStepIndex(t, e) {
+    if (!e)
+      return 0;
+    const s = u(t, e);
+    return s >= 0 ? s : 0;
   }
   async dismiss(t = "session") {
     const e = this.sessionState.guideId;
@@ -122,7 +135,7 @@ class P {
         const s = await this.loadSessionStats();
         s.snoozedUntil[e] = Date.now() + 1440 * 60 * 1e3, await this.saveSessionStats(s);
       }
-      this.emitEvent("guideEnd", { guideId: e, reason: "dismissed" }), this.track("guide.dismissed", { guideId: e, dismissMode: t }), this.setSession({ status: "dismissed", guideId: e, dismissMode: t }), await this.dequeueNextGuide();
+      this.emitEvent("guideEnd", { guideId: e, reason: "dismissed" }), this.track("guide.dismissed", { guideId: e, dismissMode: t }), this.log("dismiss", { guideId: e, dismissMode: t, stepId: this.sessionState.stepId }), this.setSession({ status: "dismissed", guideId: e, dismissMode: t }), this.clearPersistedLastStep(e), await this.dequeueNextGuide();
     }
   }
   async snooze(t) {
@@ -136,7 +149,7 @@ class P {
     if (!s)
       return;
     this.track("step.completed", { guideId: t, stepId: e });
-    const i = await l(
+    const i = await p(
       s,
       e,
       (r) => this.triggerRegistry.evaluateExpression(r, this.buildTriggerContext())
@@ -145,9 +158,19 @@ class P {
       await this.completeGuide(t);
       return;
     }
-    const n = p(s, i);
+    const n = u(s, i);
     await this.activateGuide(s, n);
   }
+  async retryCurrentStep() {
+    const t = this.sessionState.guideId, e = this.sessionState.stepId;
+    if (!t || !e || this.sessionState.status !== "blocked" && this.sessionState.status !== "evaluating")
+      return;
+    const s = this.guideRegistry.get(t);
+    if (!s)
+      return;
+    const i = u(s, e);
+    i < 0 || await this.activateGuide(s, i);
+  }
   async skipStep() {
     const t = this.sessionState.guideId, e = this.sessionState.stepId;
     !t || !e || (this.track("step.skipped", { guideId: t, stepId: e }), await this.advanceStep());
@@ -160,7 +183,7 @@ class P {
       this.cachedRenderInstruction = null;
       return;
     }
-    const t = this.guideRegistry.get(this.sessionState.guideId), e = t ? f(t, this.sessionState.stepId) : void 0;
+    const t = this.guideRegistry.get(this.sessionState.guideId), e = t ? S(t, this.sessionState.stepId) : void 0;
     if (!t || !e) {
       this.cachedRenderInstruction = null;
       return;
@@ -171,7 +194,7 @@ class P {
       stepIndex: this.sessionState.stepIndex,
       totalSteps: t.steps.length,
       renderer: e.renderer,
-      content: S(t, e, this.config.locale),
+      content: f(t, e, this.config.locale),
       target: this.sessionState.resolvedTarget ?? null,
       skippable: e.skippable,
       advanceOn: e.advanceOn
@@ -193,7 +216,10 @@ class P {
     if (!n.length)
       return;
     const r = n[0];
-    this.track("guide.triggered", { guideId: r.id }), await this.start(r.id);
+    this.log("evaluateTriggers.start", {
+      guideId: r.id,
+      routePath: this.routePath
+    }), this.track("guide.triggered", { guideId: r.id }), await this.start(r.id);
   }
   async activateGuide(t, e) {
     const s = t.steps[e];
@@ -201,43 +227,71 @@ class P {
       await this.completeGuide(t.id);
       return;
     }
-    let i = y(
-      this.targetResolver,
-      s.target
-    );
-    if (i?.element || (this.setSession({
-      status: "evaluating",
-      guideId: t.id,
-      stepIndex: e,
-      stepId: s.id
-    }), i = await R(
-      this.targetResolver,
-      s.target,
-      s.timeout ?? 5e3
-    )), !i?.element) {
-      this.setSession({
+    let i = null;
+    if (s.target) {
+      if (i = y(
+        this.targetResolver,
+        s.target
+      ), i?.element || (this.setSession({
+        status: "evaluating",
+        guideId: t.id,
+        stepIndex: e,
+        stepId: s.id
+      }), i = await I(
+        this.targetResolver,
+        s.target,
+        s.timeout ?? 5e3
+      )), !i?.element) {
+        this.log("activateGuide.blocked", {
+          guideId: t.id,
+          stepId: s.id,
+          stepIndex: e,
+          reason: i ? "target_not_visible" : "target_not_found",
+          targetId: s.target?.targetId
+        }), this.setSession({
+          status: "blocked",
+          guideId: t.id,
+          stepIndex: e,
+          stepId: s.id,
+          reason: i ? "target_not_visible" : "target_not_found"
+        });
+        return;
+      }
+    } else if (s.renderer !== "announcement") {
+      this.log("activateGuide.blocked", {
+        guideId: t.id,
+        stepId: s.id,
+        stepIndex: e,
+        reason: "target_not_found"
+      }), this.setSession({
         status: "blocked",
         guideId: t.id,
         stepIndex: e,
         stepId: s.id,
-        reason: i ? "target_not_visible" : "target_not_found"
+        reason: "target_not_found"
       });
       return;
     }
-    if (e === 0) {
-      this.emitEvent("guideStart", { guideId: t.id, stepId: s.id }), this.track("guide.started", { guideId: t.id });
-      const n = await this.loadSessionStats();
-      n.guidesShownThisSession += 1, await this.saveSessionStats(n), await this.incrementVisitCount(t.id);
+    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 });
+      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.setSession({
+    this.emitEvent("stepChange", { guideId: t.id, stepId: s.id }), this.track("step.viewed", { guideId: t.id, stepId: s.id }), this.log("step.active", {
+      guideId: t.id,
+      stepId: s.id,
+      stepIndex: e,
+      hasTarget: !!s.target
+    }), this.setSession({
       status: "active",
       guideId: t.id,
       stepIndex: e,
       stepId: s.id,
-      resolvedTarget: {
+      resolvedTarget: i?.element ? {
         ...i,
         rect: i.element.getBoundingClientRect()
-      }
+      } : void 0
     }), t.persistence.resumeOnRefresh && await this.config.storage.set({
       [a(this.config.tenantId, t.id, "lastStep")]: {
         stepId: s.id,
@@ -278,8 +332,8 @@ class P {
     if (r && Date.now() < r || (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), g = Date.parse(t.persistence.schedule.end);
-      if (d < c || d > g)
+      const d = Date.now(), c = Date.parse(t.persistence.schedule.start), h = Date.parse(t.persistence.schedule.end);
+      if (d < c || d > h)
         return !1;
     }
     return this.triggerRegistry.evaluateAll(
@@ -317,12 +371,12 @@ class P {
     await this.start(t);
   }
   async loadSessionStats() {
-    const t = u(this.config.tenantId);
+    const t = g(this.config.tenantId);
     return (await this.config.storage.get([t]))[t] ?? G();
   }
   async saveSessionStats(t) {
     await this.config.storage.set({
-      [u(this.config.tenantId)]: t
+      [g(this.config.tenantId)]: t
     });
   }
   async hydrateVisitCounts(t) {
@@ -348,6 +402,20 @@ class P {
     ), n = ((await this.config.storage.get([e]))[e] ?? 0) + 1;
     this.visitCounts[t] = n, await this.config.storage.set({ [e]: n });
   }
+  log(t, e) {
+    if (this.config.debug) {
+      if (e) {
+        console.info(`[guidance] ${t}`, e);
+        return;
+      }
+      console.info(`[guidance] ${t}`);
+    }
+  }
+  async clearPersistedLastStep(t) {
+    await this.config.storage.delete([
+      a(this.config.tenantId, t, "lastStep")
+    ]);
+  }
   scheduleEvaluation() {
     typeof window > "u" || (this.evaluationFrame !== null && cancelAnimationFrame(this.evaluationFrame), this.evaluationFrame = requestAnimationFrame(() => {
       this.evaluationFrame = null, this.evaluateTriggers(this.routePath);
@@ -380,5 +448,5 @@ class P {
   }
 }
 export {
-  P as GuidanceEngine
+  _ as GuidanceEngine
 };

package/dist/lib/guidance/triggers/trigger-registry.js

@@ -1,4 +1,4 @@
-class r {
+class s {
   plugins = /* @__PURE__ */ new Map();
   register(t) {
     this.plugins.set(t.type, t);
@@ -22,11 +22,11 @@ class r {
       );
       return t.op === "and" ? a.every(Boolean) : a.some(Boolean);
     }
-    const n = this.plugins.get(t.plugin);
-    if (!n?.evaluate)
+    const l = this.plugins.get(t.plugin);
+    if (!l?.evaluate)
       return !1;
     try {
-      return !!await n.evaluate(e, t.config ?? {});
+      return !!await l.evaluate(e, t.config ?? {});
     } catch {
       return !1;
     }
@@ -36,9 +36,9 @@ class r {
       t.map(
         (a) => this.evaluateExpression(a, e)
       )
-    )).every(Boolean) : !0;
+    )).every(Boolean) : !1;
   }
 }
 export {
-  r as TriggerPluginRegistry
+  s as TriggerPluginRegistry
 };

package/dist/lib/guidance/types/guidance.types.d.ts

@@ -5,6 +5,13 @@ export type EndReason = 'completed' | 'dismissed' | 'error' | 'skipped';
 export type BlockReason = 'target_not_found' | 'target_not_visible' | 'timeout';
 export type PersistenceMode = 'showOnce' | 'replayable' | 'dismissForever' | 'scheduled';
 export type AdvanceCondition = 'click-next' | 'click-target' | 'auto' | 'custom-event';
+export interface GuidanceGuideStartOptions {
+    manual?: boolean;
+    stepId?: string;
+}
+export interface GuidanceGuideReplayOptions {
+    stepId?: string;
+}
 export type MediaType = 'image' | 'video' | 'lottie';
 export interface StepAction {
     label: string;
@@ -29,7 +36,7 @@ export interface TargetDescriptor {
 }
 export interface Step {
     id: string;
-    target: TargetDescriptor;
+    target?: TargetDescriptor;
     renderer: string;
     content: StepContent;
     advanceOn: AdvanceCondition;
@@ -49,6 +56,7 @@ export interface PersistenceConfig {
         end: string;
     };
 }
+export type GuideType = 'tour' | 'whats-new' | 'how-to' | 'tip';
 export interface GuideMetadata {
     createdAt: string;
     updatedAt: string;
@@ -56,6 +64,8 @@ export interface GuideMetadata {
     title?: string;
     description?: string;
     category?: string;
+    /** Semantic content type for Help Center labeling and launch CTAs. */
+    guideType?: GuideType;
 }
 export interface GuideManifest {
     schemaVersion: GuidanceSchemaVersion;