@flowsterix/core 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1056 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  MemoryStorageAdapter: () => MemoryStorageAdapter,
+  buildStepIdMap: () => buildStepIdMap,
+  compareVersions: () => compareVersions,
+  createApiStorageAdapter: () => createApiStorageAdapter,
+  createEventBus: () => createEventBus,
+  createFlow: () => createFlow,
+  createFlowStore: () => createFlowStore,
+  createLocalStorageAdapter: () => createLocalStorageAdapter,
+  flowDefinitionSchema: () => flowDefinitionSchema,
+  parseVersion: () => parseVersion,
+  resolveMaybePromise: () => resolveMaybePromise,
+  serializeVersion: () => serializeVersion,
+  validateFlowDefinition: () => validateFlowDefinition
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/validation.ts
+var import_zod = require("zod");
+var targetSchema = import_zod.z.union([
+  import_zod.z.literal("screen"),
+  import_zod.z.object({
+    selector: import_zod.z.string().optional(),
+    getNode: import_zod.z.custom(
+      (value) => typeof value === "function",
+      {
+        message: "getNode must be a function returning an Element"
+      }
+    ).optional(),
+    description: import_zod.z.string().optional()
+  }).refine((value) => Boolean(value.selector || value.getNode), {
+    message: "target requires either a selector or getNode definition"
+  })
+]).describe("Step target definition");
+var maskSchema = import_zod.z.union([
+  import_zod.z.literal("hole"),
+  import_zod.z.literal("none"),
+  import_zod.z.object({
+    padding: import_zod.z.number().nonnegative().optional(),
+    radius: import_zod.z.number().nonnegative().optional()
+  })
+]);
+var controlStateSchema = import_zod.z.union([
+  import_zod.z.literal("auto"),
+  import_zod.z.literal("hidden"),
+  import_zod.z.literal("disabled")
+]);
+var advanceRuleSchema = import_zod.z.union([
+  import_zod.z.object({ type: import_zod.z.literal("manual") }),
+  import_zod.z.object({
+    type: import_zod.z.literal("event"),
+    event: import_zod.z.string(),
+    on: import_zod.z.union([import_zod.z.literal("target"), import_zod.z.string()]).optional()
+  }),
+  import_zod.z.object({
+    type: import_zod.z.literal("predicate"),
+    pollMs: import_zod.z.number().positive().optional(),
+    timeoutMs: import_zod.z.number().positive().optional(),
+    check: import_zod.z.custom(
+      (value) => typeof value === "function",
+      {
+        message: "predicate check must be a function"
+      }
+    )
+  }),
+  import_zod.z.object({ type: import_zod.z.literal("delay"), ms: import_zod.z.number().nonnegative() }),
+  import_zod.z.object({
+    type: import_zod.z.literal("route"),
+    to: import_zod.z.union([import_zod.z.string(), import_zod.z.instanceof(RegExp)]).optional()
+  })
+]);
+var waitForSchema = import_zod.z.object({
+  selector: import_zod.z.string().optional(),
+  timeout: import_zod.z.number().positive().optional(),
+  predicate: import_zod.z.custom(
+    (value) => typeof value === "function",
+    {
+      message: "waitFor.predicate must be a function"
+    }
+  ).optional(),
+  pollMs: import_zod.z.number().positive().optional(),
+  subscribe: import_zod.z.custom(
+    (value) => typeof value === "function",
+    {
+      message: "waitFor.subscribe must be a function"
+    }
+  ).optional()
+}).partial();
+var scrollMarginSchema = import_zod.z.union([
+  import_zod.z.number().nonnegative(),
+  import_zod.z.object({
+    top: import_zod.z.number().nonnegative().optional(),
+    bottom: import_zod.z.number().nonnegative().optional(),
+    left: import_zod.z.number().nonnegative().optional(),
+    right: import_zod.z.number().nonnegative().optional()
+  }).strict()
+]);
+var hudPopoverSchema = import_zod.z.object({
+  offset: import_zod.z.number().optional(),
+  role: import_zod.z.string().optional(),
+  ariaLabel: import_zod.z.string().optional(),
+  ariaDescribedBy: import_zod.z.string().optional(),
+  ariaModal: import_zod.z.boolean().optional()
+});
+var hudBackdropSchema = import_zod.z.object({
+  interaction: import_zod.z.union([import_zod.z.literal("block"), import_zod.z.literal("passthrough")]).optional()
+});
+var hudBehaviorSchema = import_zod.z.object({
+  lockBodyScroll: import_zod.z.boolean().optional()
+});
+var hudSchema = import_zod.z.object({
+  render: import_zod.z.union([import_zod.z.literal("default"), import_zod.z.literal("none")]).optional(),
+  popover: hudPopoverSchema.optional(),
+  backdrop: hudBackdropSchema.optional(),
+  behavior: hudBehaviorSchema.optional(),
+  tokens: import_zod.z.record(import_zod.z.string(), import_zod.z.any()).optional()
+});
+var resumeStrategySchema = import_zod.z.union([
+  import_zod.z.literal("chain"),
+  import_zod.z.literal("current")
+]);
+var flowVersionSchema = import_zod.z.object({
+  major: import_zod.z.number().nonnegative().int(),
+  minor: import_zod.z.number().nonnegative().int()
+});
+var migrateFnSchema = import_zod.z.custom(
+  (value) => typeof value === "function",
+  { message: "migrate must be a function" }
+).optional();
+var placementSchema = import_zod.z.union([
+  import_zod.z.literal("auto"),
+  import_zod.z.literal("top"),
+  import_zod.z.literal("bottom"),
+  import_zod.z.literal("left"),
+  import_zod.z.literal("right"),
+  import_zod.z.literal("auto-start"),
+  import_zod.z.literal("auto-end"),
+  import_zod.z.literal("top-start"),
+  import_zod.z.literal("top-end"),
+  import_zod.z.literal("bottom-start"),
+  import_zod.z.literal("bottom-end"),
+  import_zod.z.literal("left-start"),
+  import_zod.z.literal("left-end"),
+  import_zod.z.literal("right-start"),
+  import_zod.z.literal("right-end")
+]);
+var stepSchema = import_zod.z.object({
+  id: import_zod.z.string().min(1),
+  target: targetSchema,
+  route: import_zod.z.union([import_zod.z.string(), import_zod.z.instanceof(RegExp)]).optional(),
+  placement: placementSchema.optional(),
+  mask: maskSchema.optional(),
+  targetBehavior: import_zod.z.object({
+    hidden: import_zod.z.union([import_zod.z.literal("screen"), import_zod.z.literal("skip")]).optional(),
+    hiddenDelayMs: import_zod.z.number().nonnegative().optional(),
+    scrollMargin: scrollMarginSchema.optional(),
+    scrollMode: import_zod.z.union([import_zod.z.literal("preserve"), import_zod.z.literal("start"), import_zod.z.literal("center")]).optional()
+  }).optional(),
+  content: import_zod.z.any(),
+  advance: import_zod.z.array(advanceRuleSchema).optional(),
+  waitFor: waitForSchema.optional(),
+  onResume: import_zod.z.custom((value) => typeof value === "function").optional(),
+  onEnter: import_zod.z.custom((value) => typeof value === "function").optional(),
+  onExit: import_zod.z.custom((value) => typeof value === "function").optional(),
+  controls: import_zod.z.object({
+    back: controlStateSchema.optional(),
+    next: controlStateSchema.optional()
+  }).optional()
+});
+var flowDefinitionSchema = import_zod.z.object({
+  id: import_zod.z.string().min(1),
+  version: flowVersionSchema,
+  steps: import_zod.z.array(stepSchema).min(1),
+  hud: hudSchema.optional(),
+  resumeStrategy: resumeStrategySchema.optional(),
+  autoStart: import_zod.z.boolean().optional(),
+  metadata: import_zod.z.record(import_zod.z.string(), import_zod.z.any()).optional(),
+  migrate: migrateFnSchema
+});
+var validateFlowDefinition = (definition) => {
+  return flowDefinitionSchema.parse(definition);
+};
+
+// src/createFlow.ts
+var createFlow = (definition) => {
+  const parsed = flowDefinitionSchema.parse(
+    definition
+  );
+  return {
+    ...parsed,
+    steps: parsed.steps.map((step) => ({ ...step }))
+  };
+};
+
+// src/events.ts
+var createEventBus = () => {
+  const listeners = /* @__PURE__ */ new Map();
+  const on = (event, handler) => {
+    const set = listeners.get(event) ?? /* @__PURE__ */ new Set();
+    set.add(handler);
+    listeners.set(event, set);
+    return () => off(event, handler);
+  };
+  const once = (event, handler) => {
+    const wrapper = (payload) => {
+      off(event, wrapper);
+      handler(payload);
+    };
+    return on(event, wrapper);
+  };
+  const off = (event, handler) => {
+    const set = listeners.get(event);
+    if (!set) return;
+    set.delete(handler);
+    if (set.size === 0) {
+      listeners.delete(event);
+    }
+  };
+  const emit = (event, payload) => {
+    const set = listeners.get(event);
+    if (!set) return;
+    for (const handler of Array.from(set)) {
+      ;
+      handler(payload);
+    }
+  };
+  const clear = () => {
+    listeners.clear();
+  };
+  return { on, once, off, emit, clear };
+};
+
+// src/storage.ts
+var resolveMaybePromise = async (value) => await value;
+var MemoryStorageAdapter = class {
+  store = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Set();
+  get = (key) => {
+    return this.store.get(key) ?? null;
+  };
+  set = (key, snapshot) => {
+    this.store.set(key, snapshot);
+    this.emit();
+  };
+  remove = (key) => {
+    this.store.delete(key);
+    this.emit();
+  };
+  subscribe = (listener) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+  emit() {
+    for (const listener of Array.from(this.listeners)) {
+      listener();
+    }
+  }
+};
+var safeGlobal = typeof globalThis !== "undefined" ? globalThis : void 0;
+var isStorageSnapshotShape = (value) => {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const snapshot = value;
+  const hasValidVersion = typeof snapshot.version === "string" || typeof snapshot.version === "number";
+  return hasValidVersion && typeof snapshot.updatedAt === "number" && "value" in snapshot;
+};
+var createLocalStorageAdapter = (storage = getLocalStorage()) => {
+  const listeners = /* @__PURE__ */ new Set();
+  const get = (key) => {
+    if (!storage) return null;
+    const raw = storage.getItem(key);
+    if (!raw) return null;
+    try {
+      const parsed = JSON.parse(raw);
+      if (!isStorageSnapshotShape(parsed)) {
+        return null;
+      }
+      return parsed;
+    } catch (error) {
+      console.warn(
+        "[tour][storage] Failed to parse snapshot for key",
+        key,
+        error
+      );
+      return null;
+    }
+  };
+  const set = (key, snapshot) => {
+    if (!storage) return;
+    storage.setItem(key, JSON.stringify(snapshot));
+    emit();
+  };
+  const remove = (key) => {
+    if (!storage) return;
+    storage.removeItem(key);
+    emit();
+  };
+  const subscribe = (listener) => {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+  };
+  const emit = () => {
+    for (const listener of Array.from(listeners)) {
+      listener();
+    }
+  };
+  return { get, set, remove, subscribe };
+};
+function getLocalStorage() {
+  try {
+    if (!safeGlobal) return null;
+    if ("localStorage" in safeGlobal) {
+      return safeGlobal.localStorage;
+    }
+  } catch (error) {
+    console.warn("[tour][storage] localStorage unavailable", error);
+  }
+  return null;
+}
+function createApiStorageAdapter(options) {
+  const {
+    baseUrl,
+    getHeaders = () => ({}),
+    fetch: fetchFn = globalThis.fetch
+  } = options;
+  const buildUrl = (key) => `${baseUrl.replace(/\/$/, "")}/${encodeURIComponent(key)}`;
+  const get = async (key) => {
+    try {
+      const headers = await Promise.resolve(getHeaders());
+      const res = await fetchFn(buildUrl(key), { headers });
+      if (res.status === 404) return null;
+      if (!res.ok) {
+        console.warn("[tour][storage] API get failed", res.status, res.statusText);
+        return null;
+      }
+      const data = await res.json();
+      if (!isStorageSnapshotShape(data)) {
+        console.warn("[tour][storage] Invalid snapshot shape from API");
+        return null;
+      }
+      return data;
+    } catch (error) {
+      console.warn("[tour][storage] API get error", error);
+      return null;
+    }
+  };
+  const set = async (key, snapshot) => {
+    try {
+      const headers = await Promise.resolve(getHeaders());
+      const res = await fetchFn(buildUrl(key), {
+        method: "PUT",
+        headers: { "Content-Type": "application/json", ...headers },
+        body: JSON.stringify(snapshot)
+      });
+      if (!res.ok) {
+        console.warn("[tour][storage] API set failed", res.status, res.statusText);
+      }
+    } catch (error) {
+      console.warn("[tour][storage] API set error", error);
+    }
+  };
+  const remove = async (key) => {
+    try {
+      const headers = await Promise.resolve(getHeaders());
+      const res = await fetchFn(buildUrl(key), {
+        method: "DELETE",
+        headers
+      });
+      if (!res.ok && res.status !== 404) {
+        console.warn("[tour][storage] API remove failed", res.status, res.statusText);
+      }
+    } catch (error) {
+      console.warn("[tour][storage] API remove error", error);
+    }
+  };
+  return { get, set, remove };
+}
+
+// src/version.ts
+var serializeVersion = (version) => `${version.major}.${version.minor}`;
+var parseVersion = (versionStr) => {
+  const parts = versionStr.split(".");
+  if (parts.length === 2) {
+    const major = parseInt(parts[0], 10);
+    const minor = parseInt(parts[1], 10);
+    if (!isNaN(major) && !isNaN(minor)) {
+      return { major, minor };
+    }
+  }
+  console.warn(`[tour][version] Invalid version string: "${versionStr}", defaulting to 0.0`);
+  return { major: 0, minor: 0 };
+};
+var compareVersions = (stored, current) => {
+  if (stored.major === current.major && stored.minor === current.minor) {
+    return "same";
+  }
+  if (stored.major !== current.major) {
+    return "major";
+  }
+  return "minor";
+};
+var buildStepIdMap = (definition) => {
+  const map = /* @__PURE__ */ new Map();
+  definition.steps.forEach((step, index) => {
+    map.set(step.id, index);
+  });
+  return map;
+};
+var handleVersionMismatch = (params) => {
+  const {
+    storedState,
+    storedVersion,
+    definition,
+    currentVersion,
+    stepIdMap,
+    now
+  } = params;
+  const comparison = compareVersions(storedVersion, currentVersion);
+  if (comparison === "same") {
+    return {
+      state: storedState,
+      action: "continued"
+    };
+  }
+  if (storedState.status === "completed" || storedState.status === "cancelled") {
+    return {
+      state: {
+        ...storedState,
+        version: serializeVersion(currentVersion)
+      },
+      action: "continued"
+    };
+  }
+  if (storedState.status === "idle" || storedState.stepIndex < 0) {
+    return {
+      state: {
+        ...storedState,
+        version: serializeVersion(currentVersion),
+        stepIndex: -1
+      },
+      action: "continued"
+    };
+  }
+  if (comparison === "minor") {
+    const resolvedState = resolveMinorMismatch({
+      storedState,
+      currentVersion,
+      stepIdMap,
+      definition
+    });
+    if (resolvedState) {
+      return { state: resolvedState, action: "continued" };
+    }
+    return {
+      state: createResetState(currentVersion, now),
+      action: "reset"
+    };
+  }
+  if (definition.migrate) {
+    const migrationCtx = {
+      oldState: storedState,
+      oldVersion: storedVersion,
+      newVersion: currentVersion,
+      stepIdMap,
+      definition
+    };
+    try {
+      const migrated = definition.migrate(migrationCtx);
+      if (migrated) {
+        return {
+          state: {
+            ...migrated,
+            version: serializeVersion(currentVersion)
+          },
+          action: "migrated"
+        };
+      }
+    } catch (error) {
+      console.warn("[tour][version] Migration function threw error", error);
+    }
+  }
+  return {
+    state: createResetState(currentVersion, now),
+    action: "reset"
+  };
+};
+var resolveMinorMismatch = (params) => {
+  const { storedState, currentVersion, stepIdMap, definition } = params;
+  if (storedState.stepId) {
+    const newIndex = stepIdMap.get(storedState.stepId);
+    if (newIndex !== void 0) {
+      return {
+        ...storedState,
+        stepIndex: newIndex,
+        version: serializeVersion(currentVersion)
+      };
+    }
+  }
+  if (storedState.stepIndex >= 0 && storedState.stepIndex < definition.steps.length) {
+    return {
+      ...storedState,
+      version: serializeVersion(currentVersion),
+      stepId: definition.steps[storedState.stepIndex].id
+    };
+  }
+  return null;
+};
+var createResetState = (version, now) => ({
+  status: "idle",
+  stepIndex: -1,
+  version: serializeVersion(version),
+  updatedAt: now()
+});
+
+// src/state.ts
+var DEFAULT_STORAGE_PREFIX = "tour";
+var clampIndex = (value, max) => {
+  if (value < 0) return 0;
+  if (value > max) return max;
+  return value;
+};
+var cloneState = (state) => ({ ...state });
+var getStepDirection = (previousIndex, currentIndex) => {
+  if (currentIndex > previousIndex) return "forward";
+  if (currentIndex < previousIndex) return "backward";
+  return "none";
+};
+var getStepEnterReason = (previousState, currentState, direction) => {
+  if (previousState.status === "idle" && currentState.status === "running") {
+    return "start";
+  }
+  if (previousState.status === "paused" && currentState.status === "running") {
+    return "resume";
+  }
+  if (direction === "forward") return "advance";
+  if (direction === "backward") return "back";
+  return "jump";
+};
+var getStepExitReason = (currentState, direction) => {
+  if (currentState.status === "paused") return "pause";
+  if (currentState.status === "cancelled") return "cancel";
+  if (currentState.status === "completed") return "complete";
+  if (direction === "forward") return "advance";
+  if (direction === "backward") return "back";
+  return "unknown";
+};
+var getStepCompleteReason = (currentState) => {
+  if (currentState.status === "completed") {
+    return "flowComplete";
+  }
+  return "advance";
+};
+var createInitialState = (definition, now) => ({
+  status: "idle",
+  stepIndex: -1,
+  version: serializeVersion(definition.version),
+  updatedAt: now()
+});
+var getStep = (definition, index) => {
+  if (index < 0) return null;
+  return definition.steps[index] ?? null;
+};
+var snapshotFromState = (state) => ({
+  version: state.version,
+  value: cloneState(state),
+  updatedAt: state.updatedAt
+});
+var isFlowStateSnapshot = (snapshot) => {
+  if (!snapshot) return false;
+  const { value } = snapshot;
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const flowValue = value;
+  const hasValidVersion = typeof flowValue.version === "string" || typeof flowValue.version === "number";
+  return typeof flowValue.status === "string" && typeof flowValue.stepIndex === "number" && hasValidVersion;
+};
+var createFlowStore = (definition, flowOptions = {}) => {
+  const {
+    storageAdapter,
+    storageKey = `${DEFAULT_STORAGE_PREFIX}:${definition.id}`,
+    eventBus = createEventBus(),
+    now = () => Date.now(),
+    persistOnChange = true,
+    analytics,
+    onVersionMismatch
+  } = flowOptions;
+  const currentVersion = definition.version;
+  const stepIdMap = buildStepIdMap(definition);
+  let state = createInitialState(definition, now);
+  const subscribers = /* @__PURE__ */ new Set();
+  let destroyed = false;
+  let unsubscribeStorage = null;
+  let isHydrating = false;
+  let hasHydrated = !storageAdapter;
+  let pendingStartOptions;
+  const callAnalytics = (event, payload) => {
+    if (!analytics) return;
+    const eventName = String(event);
+    const handlerKey = `on${eventName.charAt(0).toUpperCase()}${eventName.slice(
+      1
+    )}`;
+    const handler = analytics[handlerKey];
+    handler?.(payload);
+  };
+  const emitEvent = (event, payload) => {
+    eventBus.emit(event, payload);
+    callAnalytics(event, payload);
+  };
+  const emitFlowError = (code, error, meta) => {
+    emitEvent("flowError", {
+      flow: definition,
+      state,
+      code,
+      error,
+      meta
+    });
+  };
+  const scheduleMicrotask = (fn) => {
+    if (typeof queueMicrotask === "function") {
+      queueMicrotask(fn);
+      return;
+    }
+    Promise.resolve().then(fn).catch((error) => {
+      console.warn("[tour][flow] async scheduling failed", error);
+      emitFlowError("async.schedule_failed", error, {
+        operation: "queueMicrotaskFallback"
+      });
+    });
+  };
+  const runPendingStart = () => {
+    if (!pendingStartOptions) return;
+    const pending = pendingStartOptions;
+    pendingStartOptions = void 0;
+    scheduleMicrotask(() => {
+      start(pending);
+    });
+  };
+  const notifySubscribers = () => {
+    for (const listener of Array.from(subscribers)) {
+      listener(state);
+    }
+  };
+  const persistState = (nextState) => {
+    if (!storageAdapter || !persistOnChange) return;
+    if (isHydrating) return;
+    const result = storageAdapter.set(storageKey, snapshotFromState(nextState));
+    if (result instanceof Promise) {
+      result.catch((error) => {
+        console.warn("[tour][storage] Failed to persist flow state", error);
+        emitFlowError("storage.persist_failed", error, { key: storageKey });
+      });
+    }
+  };
+  const emitLifecycleEvents = (previousState, currentState, lifecycleOptions) => {
+    if (previousState.status !== currentState.status) {
+      if (currentState.status === "running") {
+        const payload = { flow: definition, state: currentState };
+        if (previousState.status === "paused") {
+          emitEvent("flowResume", payload);
+        } else {
+          emitEvent("flowStart", payload);
+        }
+      }
+      if (currentState.status === "paused") {
+        emitEvent("flowPause", { flow: definition, state: currentState });
+      }
+      if (currentState.status === "cancelled") {
+        emitEvent("flowCancel", {
+          flow: definition,
+          state: currentState,
+          reason: lifecycleOptions?.cancelReason
+        });
+      }
+      if (currentState.status === "completed") {
+        emitEvent("flowComplete", { flow: definition, state: currentState });
+      }
+    }
+    const previousStep = getStep(definition, previousState.stepIndex);
+    const currentStep = getStep(definition, currentState.stepIndex);
+    const direction = getStepDirection(
+      previousState.stepIndex,
+      currentState.stepIndex
+    );
+    const shouldEmitStepExit = previousStep !== null && (direction !== "none" || currentState.status !== "running");
+    if (shouldEmitStepExit) {
+      const exitedStep = previousStep;
+      emitEvent("stepExit", {
+        flow: definition,
+        state: currentState,
+        currentStep,
+        currentStepIndex: currentState.stepIndex,
+        previousStep: exitedStep,
+        previousStepIndex: previousState.stepIndex,
+        direction,
+        reason: getStepExitReason(currentState, direction)
+      });
+    }
+    const shouldEmitStepComplete = previousStep !== null && (direction === "forward" || currentState.status === "completed" && previousState.status !== "completed");
+    if (shouldEmitStepComplete) {
+      const completedStep = previousStep;
+      emitEvent("stepComplete", {
+        flow: definition,
+        state: currentState,
+        currentStep,
+        currentStepIndex: currentState.stepIndex,
+        previousStep: completedStep,
+        previousStepIndex: previousState.stepIndex,
+        direction,
+        reason: getStepCompleteReason(currentState)
+      });
+    }
+    const shouldEmitStepEnter = currentState.status === "running" && currentStep !== null && (direction !== "none" || previousState.status !== "running");
+    if (shouldEmitStepEnter) {
+      const enteredStep = currentStep;
+      emitEvent("stepEnter", {
+        flow: definition,
+        state: currentState,
+        currentStep: enteredStep,
+        currentStepIndex: currentState.stepIndex,
+        previousStep,
+        previousStepIndex: previousState.stepIndex,
+        direction,
+        reason: getStepEnterReason(previousState, currentState, direction)
+      });
+    }
+    if (previousState.stepIndex !== currentState.stepIndex || previousState.status !== currentState.status) {
+      emitEvent("stepChange", {
+        flow: definition,
+        state: currentState,
+        step: currentStep,
+        previousStep
+      });
+    }
+    emitEvent("stateChange", { flow: definition, state: currentState });
+  };
+  const commit = (nextState, commitConfig = {}) => {
+    const {
+      persist: shouldPersist = true,
+      emitLifecycle = true,
+      preserveTimestamp = false,
+      cancelReason
+    } = commitConfig;
+    if (destroyed) {
+      const error = new Error("Flow store has been destroyed");
+      emitFlowError("flow.store_destroyed", error, { operation: "commit" });
+      throw error;
+    }
+    const previousState = state;
+    const timestamp = preserveTimestamp ? nextState.updatedAt : now();
+    const currentStepId = nextState.stepIndex >= 0 ? definition.steps[nextState.stepIndex]?.id : void 0;
+    const hydratedNext = {
+      ...nextState,
+      version: serializeVersion(currentVersion),
+      stepId: currentStepId,
+      updatedAt: timestamp
+    };
+    const changed = previousState.status !== hydratedNext.status || previousState.stepIndex !== hydratedNext.stepIndex || previousState.updatedAt !== hydratedNext.updatedAt;
+    if (!changed) {
+      return state;
+    }
+    state = hydratedNext;
+    if (shouldPersist) {
+      persistState(state);
+    }
+    if (emitLifecycle) {
+      emitLifecycleEvents(previousState, state, { cancelReason });
+    }
+    notifySubscribers();
+    return state;
+  };
+  const hydrateFromStorage = async () => {
+    if (!storageAdapter || isHydrating) return;
+    isHydrating = true;
+    try {
+      const snapshot = await resolveMaybePromise(
+        storageAdapter.get(storageKey)
+      );
+      if (!snapshot || !isFlowStateSnapshot(snapshot)) return;
+      const storedVersion = parseVersion(snapshot.version);
+      const storedState = {
+        ...snapshot.value,
+        // Normalize version to string format if it was legacy number
+        version: typeof snapshot.value.version === "number" ? serializeVersion({ major: snapshot.value.version, minor: 0 }) : snapshot.value.version
+      };
+      const { state: resolvedState, action } = handleVersionMismatch({
+        storedState,
+        storedVersion,
+        definition,
+        currentVersion,
+        stepIdMap,
+        now
+      });
+      if (action !== "continued" || serializeVersion(storedVersion) !== serializeVersion(currentVersion)) {
+        const mismatchInfo = {
+          flowId: definition.id,
+          oldVersion: storedVersion,
+          newVersion: currentVersion,
+          action,
+          resolvedStepId: resolvedState.stepIndex >= 0 ? definition.steps[resolvedState.stepIndex]?.id : void 0,
+          resolvedStepIndex: resolvedState.stepIndex >= 0 ? resolvedState.stepIndex : void 0
+        };
+        emitEvent("versionMismatch", { ...mismatchInfo, flow: definition });
+        onVersionMismatch?.(mismatchInfo);
+        if (action === "reset") {
+          state = resolvedState;
+          notifySubscribers();
+          return;
+        }
+      }
+      commit(resolvedState, {
+        persist: action !== "continued",
+        // Persist if we migrated
+        preserveTimestamp: action === "continued"
+      });
+    } catch (error) {
+      console.warn("[tour][storage] failed to hydrate flow state", error);
+      emitFlowError("storage.hydrate_failed", error, { key: storageKey });
+    } finally {
+      isHydrating = false;
+      hasHydrated = true;
+      runPendingStart();
+    }
+  };
+  if (storageAdapter) {
+    void hydrateFromStorage();
+    if (storageAdapter.subscribe) {
+      unsubscribeStorage = storageAdapter.subscribe(() => {
+        void hydrateFromStorage();
+      });
+    }
+  }
+  const start = (startConfig) => {
+    if (!hasHydrated) {
+      pendingStartOptions = startConfig ?? {};
+      if (!isHydrating) {
+        void hydrateFromStorage();
+      }
+      return state;
+    }
+    const { fromStepId, fromStepIndex, resume } = startConfig ?? {};
+    if (resume && (state.status === "paused" || state.status === "running")) {
+      return resumeFlow();
+    }
+    let targetIndex = 0;
+    if (typeof fromStepIndex === "number") {
+      targetIndex = clampIndex(fromStepIndex, definition.steps.length - 1);
+    } else if (fromStepId) {
+      const index = definition.steps.findIndex((step) => step.id === fromStepId);
+      if (index === -1) {
+        const error = new Error(
+          `Step with id "${fromStepId}" not found in flow ${definition.id}`
+        );
+        emitFlowError("flow.step_not_found", error, {
+          stepId: fromStepId,
+          operation: "start"
+        });
+        throw error;
+      }
+      targetIndex = index;
+    } else if (state.stepIndex >= 0) {
+      const canResumeFromStoredStep = state.status === "running" || state.status === "paused" || state.status === "cancelled" && state.cancelReason === "keyboard";
+      if (canResumeFromStoredStep) {
+        targetIndex = clampIndex(state.stepIndex, definition.steps.length - 1);
+      }
+    }
+    return commit({
+      status: "running",
+      stepIndex: targetIndex,
+      version: state.version,
+      updatedAt: state.updatedAt
+    });
+  };
+  const next = () => {
+    if (state.status !== "running") {
+      return state;
+    }
+    if (state.stepIndex >= definition.steps.length - 1) {
+      return complete();
+    }
+    return commit({
+      status: "running",
+      stepIndex: state.stepIndex + 1,
+      version: state.version,
+      updatedAt: state.updatedAt
+    });
+  };
+  const back = () => {
+    if (state.status !== "running") {
+      return state;
+    }
+    if (state.stepIndex <= 0) {
+      return state;
+    }
+    return commit({
+      status: "running",
+      stepIndex: state.stepIndex - 1,
+      version: state.version,
+      updatedAt: state.updatedAt
+    });
+  };
+  const goToStep = (step) => {
+    if (state.status !== "running") {
+      return state;
+    }
+    let targetIndex;
+    if (typeof step === "number") {
+      targetIndex = clampIndex(step, definition.steps.length - 1);
+    } else {
+      const index = definition.steps.findIndex((item) => item.id === step);
+      if (index === -1) {
+        const error = new Error(
+          `Step with id "${step}" not found in flow ${definition.id}`
+        );
+        emitFlowError("flow.step_not_found", error, {
+          stepId: step,
+          operation: "goToStep"
+        });
+        throw error;
+      }
+      targetIndex = index;
+    }
+    return commit({
+      status: "running",
+      stepIndex: targetIndex,
+      version: state.version,
+      updatedAt: state.updatedAt
+    });
+  };
+  const pause = () => {
+    if (state.status !== "running") {
+      return state;
+    }
+    return commit({
+      status: "paused",
+      stepIndex: state.stepIndex,
+      version: state.version,
+      updatedAt: state.updatedAt
+    });
+  };
+  const resumeFlow = () => {
+    if (state.status !== "paused") {
+      return state;
+    }
+    const index = clampIndex(
+      state.stepIndex < 0 ? 0 : state.stepIndex,
+      definition.steps.length - 1
+    );
+    return commit({
+      status: "running",
+      stepIndex: index,
+      version: state.version,
+      updatedAt: state.updatedAt
+    });
+  };
+  const cancel = (reason) => {
+    if (state.status === "cancelled") {
+      return state;
+    }
+    return commit(
+      {
+        status: "cancelled",
+        stepIndex: state.stepIndex,
+        version: state.version,
+        updatedAt: state.updatedAt,
+        cancelReason: reason
+      },
+      { cancelReason: reason }
+    );
+  };
+  const complete = () => {
+    if (state.status === "completed") {
+      return state;
+    }
+    return commit({
+      status: "completed",
+      stepIndex: clampIndex(state.stepIndex, definition.steps.length - 1),
+      version: state.version,
+      updatedAt: state.updatedAt
+    });
+  };
+  const subscribe = (listener) => {
+    if (destroyed) {
+      const error = new Error("Cannot subscribe to a destroyed flow store");
+      emitFlowError("flow.store_destroyed", error, { operation: "subscribe" });
+      throw error;
+    }
+    subscribers.add(listener);
+    listener(state);
+    return () => {
+      subscribers.delete(listener);
+    };
+  };
+  const destroy = () => {
+    if (destroyed) return;
+    destroyed = true;
+    subscribers.clear();
+    eventBus.clear();
+    if (unsubscribeStorage) {
+      unsubscribeStorage();
+    }
+  };
+  return {
+    definition,
+    events: eventBus,
+    getState: () => state,
+    start,
+    next,
+    back,
+    goToStep,
+    pause,
+    resume: resumeFlow,
+    cancel,
+    complete,
+    subscribe,
+    destroy
+  };
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MemoryStorageAdapter,
+  buildStepIdMap,
+  compareVersions,
+  createApiStorageAdapter,
+  createEventBus,
+  createFlow,
+  createFlowStore,
+  createLocalStorageAdapter,
+  flowDefinitionSchema,
+  parseVersion,
+  resolveMaybePromise,
+  serializeVersion,
+  validateFlowDefinition
+});