@glowhop/core-tour 1.0.0

package/config/index.js

@@ -0,0 +1,999 @@
+// packages/core/src/definition/step-props.ts
+function cloneStepProps(props) {
+  return {
+    title: props.title,
+    content: props.content,
+    data: props.data === undefined ? undefined : structuredClone(props.data),
+    overlay: props.overlay && {
+      ...props.overlay,
+      animation: props.overlay.animation && { ...props.overlay.animation }
+    },
+    popover: props.popover && {
+      ...props.popover,
+      animation: props.popover.animation && { ...props.popover.animation },
+      arrow: props.popover.arrow && { ...props.popover.arrow },
+      keyboardShortcuts: props.popover.keyboardShortcuts && {
+        previous: props.popover.keyboardShortcuts.previous && [
+          ...props.popover.keyboardShortcuts.previous
+        ],
+        advance: props.popover.keyboardShortcuts.advance && [
+          ...props.popover.keyboardShortcuts.advance
+        ],
+        cancel: props.popover.keyboardShortcuts.cancel && [
+          ...props.popover.keyboardShortcuts.cancel
+        ]
+      },
+      placementTryOrder: props.popover.placementTryOrder && [...props.popover.placementTryOrder]
+    },
+    indicator: props.indicator && {
+      ...props.indicator,
+      animation: props.indicator.animation && { ...props.indicator.animation },
+      placementTryOrder: props.indicator.placementTryOrder && [
+        ...props.indicator.placementTryOrder
+      ]
+    }
+  };
+}
+function freezeStepProps(props) {
+  const cloned = cloneStepProps(props);
+  if (cloned.data)
+    Object.freeze(cloned.data);
+  if (cloned.overlay?.animation)
+    Object.freeze(cloned.overlay.animation);
+  if (cloned.overlay)
+    Object.freeze(cloned.overlay);
+  if (cloned.popover?.animation)
+    Object.freeze(cloned.popover.animation);
+  if (cloned.popover?.arrow)
+    Object.freeze(cloned.popover.arrow);
+  if (cloned.popover?.keyboardShortcuts?.previous)
+    Object.freeze(cloned.popover.keyboardShortcuts.previous);
+  if (cloned.popover?.keyboardShortcuts?.advance)
+    Object.freeze(cloned.popover.keyboardShortcuts.advance);
+  if (cloned.popover?.keyboardShortcuts?.cancel)
+    Object.freeze(cloned.popover.keyboardShortcuts.cancel);
+  if (cloned.popover?.keyboardShortcuts)
+    Object.freeze(cloned.popover.keyboardShortcuts);
+  if (cloned.popover?.placementTryOrder)
+    Object.freeze(cloned.popover.placementTryOrder);
+  if (cloned.popover)
+    Object.freeze(cloned.popover);
+  if (cloned.indicator?.animation)
+    Object.freeze(cloned.indicator.animation);
+  if (cloned.indicator?.placementTryOrder)
+    Object.freeze(cloned.indicator.placementTryOrder);
+  if (cloned.indicator)
+    Object.freeze(cloned.indicator);
+  return Object.freeze(cloned);
+}
+// packages/core/src/definition/workflow-definition.ts
+function freezeRecord(value) {
+  return Object.freeze(value);
+}
+function freezeAnimation(options) {
+  return options && freezeRecord({ ...options });
+}
+function freezeOverlay(options) {
+  return options && freezeRecord({
+    ...options,
+    animation: freezeAnimation(options.animation)
+  });
+}
+function freezePopover(options) {
+  return options && freezeRecord({
+    ...options,
+    animation: freezeAnimation(options.animation),
+    arrow: options.arrow && freezeRecord({ ...options.arrow }),
+    keyboardShortcuts: options.keyboardShortcuts && freezeRecord({
+      previous: options.keyboardShortcuts.previous && freezeRecord([...options.keyboardShortcuts.previous]),
+      advance: options.keyboardShortcuts.advance && freezeRecord([...options.keyboardShortcuts.advance]),
+      cancel: options.keyboardShortcuts.cancel && freezeRecord([...options.keyboardShortcuts.cancel])
+    }),
+    placementTryOrder: options.placementTryOrder && freezeRecord([...options.placementTryOrder])
+  });
+}
+function freezeIndicator(options) {
+  return options && freezeRecord({
+    ...options,
+    animation: freezeAnimation(options.animation),
+    placementTryOrder: options.placementTryOrder && freezeRecord([...options.placementTryOrder])
+  });
+}
+function freezeStep(draft) {
+  return freezeRecord({
+    id: draft.id,
+    target: draft.target,
+    resetPropsOnEnter: draft.resetPropsOnEnter,
+    props: freezeStepProps(draft.props),
+    behavior: draft.behavior && freezeRecord({
+      ...draft.behavior,
+      scroll: draft.behavior.scroll && freezeRecord({ ...draft.behavior.scroll })
+    }),
+    actions: freezeRecord(draft.actions.map((action) => action)),
+    eventHandlers: freezeRecord(draft.eventHandlers.map((handler) => freezeRecord({ ...handler }))),
+    advanceAction: draft.advanceAction,
+    previousAction: draft.previousAction,
+    cancelAction: draft.cancelAction
+  });
+}
+function freezeOptions(options) {
+  return freezeRecord({
+    ...options,
+    overlay: freezeOverlay(options.overlay),
+    popover: freezePopover(options.popover),
+    indicator: freezeIndicator(options.indicator),
+    behavior: options.behavior && freezeRecord({
+      ...options.behavior,
+      scroll: options.behavior.scroll && freezeRecord({ ...options.behavior.scroll })
+    })
+  });
+}
+function cloneWorkflowStepDraft(definition) {
+  return {
+    ...definition,
+    props: cloneStepProps(definition.props),
+    actions: definition.actions.map((action) => action),
+    eventHandlers: [...definition.eventHandlers]
+  };
+}
+function assertUniqueStepIds(name, drafts) {
+  const seen = new Map;
+  for (const [index, draft] of drafts.entries()) {
+    const label = `step ${index}${draft.props.title ? ` ("${String(draft.props.title)}")` : ""}`;
+    if (typeof draft.id !== "string" || draft.id.length === 0) {
+      throw new Error(`Workflow "${name}": ${label} is missing a non-empty "id".`);
+    }
+    const duplicate = seen.get(draft.id);
+    if (duplicate !== undefined) {
+      throw new Error(`Workflow "${name}": ${label} reuses the id "${draft.id}" already used by step ${duplicate}. Step ids must be unique.`);
+    }
+    seen.set(draft.id, index);
+  }
+}
+function createWorkflowDefinition(name, options, drafts) {
+  assertUniqueStepIds(name, drafts);
+  return freezeRecord({
+    name,
+    options: freezeOptions(options),
+    steps: freezeRecord(drafts.map(freezeStep))
+  });
+}
+// packages/core/src/runtime/abort.ts
+function abortError() {
+  return new DOMException("The operation was aborted", "AbortError");
+}
+function abortableDelay(delay, signal) {
+  if (signal.aborted)
+    throw abortError();
+  return new Promise((resolve, reject) => {
+    const cleanup = () => signal.removeEventListener("abort", onAbort);
+    const onAbort = () => {
+      clearTimeout(timeoutId);
+      cleanup();
+      reject(abortError());
+    };
+    const timeoutId = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, delay);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+// packages/core/src/builder/index.ts
+var DEFAULT_WAIT_INTERVAL = 16;
+var DEFAULT_WAIT_TIMEOUT = 3000;
+var INACTIVE_STEP_ERROR = "WorkflowStepBuilder is no longer active";
+var STEP_BUILDER_INTERNAL = Symbol("WorkflowStepBuilder.internal");
+function assertTimingValue(name, value) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new TypeError(`${name} must be a finite non-negative number`);
+  }
+}
+function throwIfAborted(signal) {
+  if (signal.aborted)
+    throw abortError();
+}
+function waitTimeoutError(timeout) {
+  return new Error(`waitUntil timed out after ${timeout}ms`);
+}
+function waitForPredicate(predicate, remainingTime, timeout, signal) {
+  throwIfAborted(signal);
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const cleanup = () => {
+      clearTimeout(timeoutId);
+      signal.removeEventListener("abort", onAbort);
+    };
+    const settle = (callback) => {
+      if (settled)
+        return;
+      settled = true;
+      cleanup();
+      callback();
+    };
+    const onAbort = () => settle(() => reject(abortError()));
+    const timeoutId = setTimeout(() => settle(() => reject(waitTimeoutError(timeout))), remainingTime);
+    signal.addEventListener("abort", onAbort, { once: true });
+    Promise.resolve().then(predicate).then((result) => settle(() => resolve(result)), (error) => settle(() => reject(error)));
+  });
+}
+function waitOptions(options = {}) {
+  const timeout = options.timeout ?? DEFAULT_WAIT_TIMEOUT;
+  const interval = options.interval ?? DEFAULT_WAIT_INTERVAL;
+  if (!Number.isFinite(timeout) || timeout < 0) {
+    throw new TypeError("wait timeout must be a finite non-negative number");
+  }
+  if (!Number.isFinite(interval) || interval <= 0) {
+    throw new TypeError("wait interval must be a finite positive number");
+  }
+  return { interval, timeout };
+}
+
+class WorkflowBuilder {
+  name;
+  options;
+  steps = [];
+  currentStep = null;
+  definition = null;
+  constructor(name, options = {}) {
+    this.name = name;
+    this.options = options;
+  }
+  step(options) {
+    this.assertBuilding();
+    this.commitCurrentStep();
+    this.currentStep = new WorkflowStepBuilder(this, {
+      id: options.id,
+      target: options.target,
+      resetPropsOnEnter: options.resetPropsOnEnter,
+      props: {
+        title: options.title,
+        content: options.content,
+        data: cloneStepProps(options).data,
+        overlay: options.overlay,
+        popover: options.popover,
+        indicator: options.indicator
+      },
+      behavior: options.behavior,
+      actions: [],
+      eventHandlers: [],
+      advanceAction: null,
+      previousAction: null,
+      cancelAction: null
+    });
+    return this.currentStep;
+  }
+  append(workflow) {
+    this.assertBuilding();
+    const drafts = workflow.steps.map(cloneWorkflowStepDraft);
+    const lastStep = drafts.at(-1);
+    if (!lastStep)
+      throw new Error("Cannot append a workflow without steps");
+    this.commitCurrentStep();
+    this.steps.push(...drafts.slice(0, -1));
+    this.currentStep = new WorkflowStepBuilder(this, lastStep);
+    return this.currentStep;
+  }
+  build() {
+    if (this.definition)
+      return this.definition;
+    this.commitCurrentStep();
+    this.definition = createWorkflowDefinition(this.name, this.options, this.steps);
+    return this.definition;
+  }
+  assertBuilding() {
+    if (this.definition)
+      throw new Error("WorkflowBuilder is already finished");
+  }
+  commitCurrentStep() {
+    if (!this.currentStep)
+      return;
+    this.steps.push(this.currentStep[STEP_BUILDER_INTERNAL]());
+    this.currentStep = null;
+  }
+}
+
+class WorkflowStepBuilder {
+  owner;
+  draft;
+  active = true;
+  constructor(owner, draft) {
+    this.owner = owner;
+    this.draft = draft;
+  }
+  step(options) {
+    this.assertActive();
+    return this.owner.step(options);
+  }
+  append(workflow) {
+    this.assertActive();
+    return this.owner.append(workflow);
+  }
+  build() {
+    this.assertActive();
+    return this.owner.build();
+  }
+  clickTarget() {
+    return this.do(({ target }) => {
+      target?.click();
+      return true;
+    });
+  }
+  focusTarget() {
+    return this.do(({ target }) => {
+      target?.focus();
+      return true;
+    });
+  }
+  wait(timeMs) {
+    this.assertActive();
+    assertTimingValue("timeMs", timeMs);
+    this.draft.actions.push(timeMs);
+    return this;
+  }
+  waitUntil(predicate, options = {}) {
+    this.assertActive();
+    const { interval, timeout } = waitOptions(options);
+    this.draft.actions.push(async (context) => {
+      const startedAt = Date.now();
+      let attempted = false;
+      while (true) {
+        throwIfAborted(context.signal);
+        const elapsed = Date.now() - startedAt;
+        if (attempted && elapsed >= timeout)
+          throw waitTimeoutError(timeout);
+        attempted = true;
+        if (await waitForPredicate(() => predicate(context), Math.max(0, timeout - elapsed), timeout, context.signal))
+          return true;
+        const remainingTime = timeout - (Date.now() - startedAt);
+        if (remainingTime <= 0)
+          throw waitTimeoutError(timeout);
+        await abortableDelay(Math.min(interval, remainingTime), context.signal);
+      }
+    });
+    return this;
+  }
+  waitUntilElement(selector, options) {
+    if (selector.length === 0)
+      throw new TypeError("selector must not be empty");
+    return this.waitUntil((context) => context.target.ownerDocument.querySelector(selector) !== null, options);
+  }
+  do(callback) {
+    this.assertActive();
+    this.draft.actions.push(callback);
+    return this;
+  }
+  beforeAdvance(callback) {
+    this.assertActive();
+    this.draft.advanceAction = callback;
+    return this;
+  }
+  beforePrevious(callback) {
+    this.assertActive();
+    this.draft.previousAction = callback;
+    return this;
+  }
+  beforeCancel(callback) {
+    this.assertActive();
+    this.draft.cancelAction = callback;
+    return this;
+  }
+  onTargetEvent(eventOrEvents, callback) {
+    this.assertActive();
+    const events = typeof eventOrEvents === "string" ? [eventOrEvents] : eventOrEvents;
+    if (events.length === 0)
+      throw new TypeError("events must not be empty");
+    for (const event of events) {
+      if (event.length === 0)
+        throw new TypeError("event name must not be empty");
+      this.draft.eventHandlers.push({
+        event,
+        callback
+      });
+    }
+    return this;
+  }
+  [STEP_BUILDER_INTERNAL]() {
+    this.active = false;
+    return cloneWorkflowStepDraft(this.draft);
+  }
+  assertActive() {
+    if (!this.active)
+      throw new Error(INACTIVE_STEP_ERROR);
+  }
+}
+
+// packages/core/src/config/types.ts
+class ConfigValidationError extends Error {
+  issues;
+  constructor(issues) {
+    const summary = issues.map((issue) => `  - ${issue.path}: ${issue.message}`).join(`
+`);
+    super(`Invalid workflow config (${issues.length} issue(s)):
+${summary}`);
+    this.name = "ConfigValidationError";
+    this.issues = issues;
+  }
+}
+
+// packages/core/src/config/validate.ts
+var TOP_LEVEL_KEYS = [
+  "name",
+  "cancellable",
+  "allowScroll",
+  "overlay",
+  "popover",
+  "indicator",
+  "animated",
+  "behavior",
+  "onStart",
+  "onCancel",
+  "onFinish",
+  "steps"
+];
+var STEP_KEYS = [
+  "id",
+  "target",
+  "resetPropsOnEnter",
+  "overlay",
+  "popover",
+  "indicator",
+  "behavior",
+  "title",
+  "content",
+  "data",
+  "actions",
+  "eventHandlers",
+  "advanceAction",
+  "previousAction",
+  "cancelAction"
+];
+var EVENT_HANDLER_KEYS = ["event", "action"];
+var ANIMATION_KEYS = ["duration", "easing"];
+var OVERLAY_KEYS = ["animated", "animation", "color", "opacity", "padding", "radius"];
+var INDICATOR_KEYS = ["animated", "animation", "disabled", "gap", "placementTryOrder"];
+var POPOVER_KEYS = [
+  "animated",
+  "animation",
+  "placementTryOrder",
+  "arrow",
+  "hideFooter",
+  "disablePreviousButton",
+  "hidePreviousButton",
+  "disableAdvanceButton",
+  "hideAdvanceButton",
+  "gap",
+  "keyboardShortcuts"
+];
+var POPOVER_ARROW_KEYS = [
+  "disabled",
+  "color",
+  "size",
+  "borderWidth",
+  "borderRadius",
+  "edgePadding",
+  "styleNonce",
+  "disableAutoStyles"
+];
+var KEYBOARD_SHORTCUT_KEYS = ["previous", "advance", "cancel"];
+var BEHAVIOR_KEYS = [
+  "allowInteraction",
+  "disableAutoFocus",
+  "disableAutoScroll",
+  "missingTargetStrategy",
+  "scroll",
+  "targetTimeout",
+  "overlayClick"
+];
+var SCROLL_KEYS = ["behavior", "block", "inline"];
+var BUILTIN_ACTION_KEYS = {
+  wait: ["type", "ms"],
+  waitUntilElement: ["type", "selector", "interval", "timeout"],
+  clickTarget: ["type"],
+  focusTarget: ["type"]
+};
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function defaultContentValidator(value) {
+  return typeof value === "string" ? null : "must be a string";
+}
+function validateWorkflowConfig(config, options = {}) {
+  const validateContent = options.validateContent ?? defaultContentValidator;
+  const issues = [];
+  validateWorkflowConfigShape(config, issues, validateContent);
+  if (issues.length > 0)
+    throw new ConfigValidationError(issues);
+  return config;
+}
+function validateWorkflowConfigShape(value, issues, validateContent) {
+  if (!isPlainObject(value)) {
+    issues.push({ path: "", message: "Workflow config must be a plain object" });
+    return;
+  }
+  assertNoUnknownKeys(value, TOP_LEVEL_KEYS, "", issues);
+  if (typeof value.name !== "string" || value.name.length === 0) {
+    issues.push({ path: "name", message: "name must be a non-empty string" });
+  }
+  validateOptionalBoolean("cancellable", value.cancellable, issues);
+  validateOptionalBoolean("allowScroll", value.allowScroll, issues);
+  validateOptionalBoolean("animated", value.animated, issues);
+  validateOverlayShape("overlay", value.overlay, issues);
+  validatePopoverShape("popover", value.popover, issues);
+  validateIndicatorShape("indicator", value.indicator, issues);
+  validateBehaviorShape("behavior", value.behavior, issues);
+  validateLifecycleActionRefShape("onStart", value.onStart, issues);
+  validateLifecycleActionRefShape("onCancel", value.onCancel, issues);
+  validateLifecycleActionRefShape("onFinish", value.onFinish, issues);
+  if (!Array.isArray(value.steps)) {
+    issues.push({ path: "steps", message: "steps must be an array" });
+    return;
+  }
+  const seenIds = new Map;
+  for (const [index, step] of value.steps.entries()) {
+    validateStepConfigShape(step, `steps[${index}]`, issues, validateContent);
+    if (isPlainObject(step) && typeof step.id === "string" && step.id.length > 0) {
+      const duplicate = seenIds.get(step.id);
+      if (duplicate === undefined)
+        seenIds.set(step.id, index);
+      else {
+        issues.push({
+          path: `steps[${index}].id`,
+          message: `id "${step.id}" is already used by steps[${duplicate}]. Step ids must be unique.`
+        });
+      }
+    }
+  }
+}
+function validateStepConfigShape(value, path, issues, validateContent) {
+  if (!isPlainObject(value)) {
+    issues.push({ path, message: "Step must be a plain object" });
+    return;
+  }
+  assertNoUnknownKeys(value, STEP_KEYS, path, issues);
+  if (typeof value.id !== "string" || value.id.length === 0) {
+    issues.push({
+      path: `${path}.id`,
+      message: "id must be a non-empty string, unique within the workflow"
+    });
+  }
+  if (typeof value.target !== "string" || value.target.length === 0) {
+    issues.push({
+      path: `${path}.target`,
+      message: "target must be a non-empty CSS selector string"
+    });
+  }
+  const titleError = validateContent(value.title, `${path}.title`);
+  if (titleError)
+    issues.push({ path: `${path}.title`, message: titleError });
+  const contentError = validateContent(value.content, `${path}.content`);
+  if (contentError)
+    issues.push({ path: `${path}.content`, message: contentError });
+  validateOptionalBoolean(`${path}.resetPropsOnEnter`, value.resetPropsOnEnter, issues);
+  validateOverlayShape(`${path}.overlay`, value.overlay, issues);
+  validatePopoverShape(`${path}.popover`, value.popover, issues);
+  validateIndicatorShape(`${path}.indicator`, value.indicator, issues);
+  validateBehaviorShape(`${path}.behavior`, value.behavior, issues);
+  validateDataShape(`${path}.data`, value.data, issues);
+  if (value.actions !== undefined) {
+    if (!Array.isArray(value.actions)) {
+      issues.push({ path: `${path}.actions`, message: "actions must be an array" });
+    } else {
+      for (const [index, action] of value.actions.entries()) {
+        validateStepActionRefShape(action, `${path}.actions[${index}]`, issues);
+      }
+    }
+  }
+  if (value.eventHandlers !== undefined) {
+    if (!Array.isArray(value.eventHandlers)) {
+      issues.push({ path: `${path}.eventHandlers`, message: "eventHandlers must be an array" });
+    } else {
+      for (const [index, handler] of value.eventHandlers.entries()) {
+        validateEventHandlerConfigShape(handler, `${path}.eventHandlers[${index}]`, issues);
+      }
+    }
+  }
+  validateTransitionActionRefShape(`${path}.advanceAction`, value.advanceAction, issues);
+  validateTransitionActionRefShape(`${path}.previousAction`, value.previousAction, issues);
+  validateTransitionActionRefShape(`${path}.cancelAction`, value.cancelAction, issues);
+}
+function validateEventHandlerConfigShape(value, path, issues) {
+  if (!isPlainObject(value)) {
+    issues.push({ path, message: "Event handler must be a plain object" });
+    return;
+  }
+  assertNoUnknownKeys(value, EVENT_HANDLER_KEYS, path, issues);
+  const event = value.event;
+  const eventIsValid = typeof event === "string" && event.length > 0 || Array.isArray(event) && event.length > 0 && event.every((entry) => typeof entry === "string" && entry.length > 0);
+  if (!eventIsValid) {
+    issues.push({
+      path: `${path}.event`,
+      message: "event must be a non-empty string or a non-empty array of non-empty strings"
+    });
+  }
+  validateStepActionRefShape(value.action, `${path}.action`, issues);
+}
+function validateStepActionRefShape(value, path, issues) {
+  if (typeof value === "function")
+    return;
+  if (isPlainObject(value) && typeof value.type === "string") {
+    validateBuiltinActionShape(value, path, issues);
+    return;
+  }
+  issues.push({
+    path,
+    message: 'must be a function, or a built-in action object with a known "type"'
+  });
+}
+function validateTransitionActionRefShape(path, value, issues) {
+  if (value === undefined)
+    return;
+  if (typeof value === "function")
+    return;
+  issues.push({
+    path,
+    message: "must be a function; built-in actions are not supported in this slot"
+  });
+}
+function validateLifecycleActionRefShape(path, value, issues) {
+  validateTransitionActionRefShape(path, value, issues);
+}
+function validateBuiltinActionShape(value, path, issues) {
+  const type = value.type;
+  const allowedKeys = BUILTIN_ACTION_KEYS[type];
+  if (!allowedKeys) {
+    issues.push({ path: `${path}.type`, message: `Unknown built-in action type: ${type}` });
+    return;
+  }
+  assertNoUnknownKeys(value, allowedKeys, path, issues);
+  switch (type) {
+    case "wait":
+      validateFiniteNonNegative(`${path}.ms`, value.ms, issues);
+      break;
+    case "waitUntilElement":
+      if (typeof value.selector !== "string" || value.selector.length === 0) {
+        issues.push({ path: `${path}.selector`, message: "selector must be a non-empty string" });
+      }
+      validateOptionalFiniteNonNegative(`${path}.interval`, value.interval, issues);
+      validateOptionalFiniteNonNegative(`${path}.timeout`, value.timeout, issues);
+      break;
+    case "clickTarget":
+    case "focusTarget":
+      break;
+  }
+}
+function validateFiniteNonNegative(path, value, issues) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    issues.push({ path, message: "must be a finite non-negative number" });
+  }
+}
+function validateOptionalFiniteNonNegative(path, value, issues) {
+  if (value === undefined)
+    return;
+  validateFiniteNonNegative(path, value, issues);
+}
+function validateOptionalBoolean(path, value, issues) {
+  if (value !== undefined && typeof value !== "boolean") {
+    issues.push({ path, message: "must be a boolean" });
+  }
+}
+function validateOptionalString(path, value, issues) {
+  if (value !== undefined && typeof value !== "string") {
+    issues.push({ path, message: "must be a string" });
+  }
+}
+function validateOptionalEnum(path, value, allowed, issues) {
+  if (value !== undefined && (typeof value !== "string" || !allowed.includes(value))) {
+    issues.push({ path, message: `must be one of: ${allowed.join(", ")}` });
+  }
+}
+function validateOptionalStringArray(path, value, issues, allowed) {
+  if (value === undefined)
+    return;
+  if (!Array.isArray(value)) {
+    issues.push({ path, message: "must be an array" });
+    return;
+  }
+  for (const [index, entry] of value.entries()) {
+    if (typeof entry !== "string" || allowed !== undefined && !allowed.includes(entry)) {
+      issues.push({
+        path: `${path}[${index}]`,
+        message: allowed ? `must be one of: ${allowed.join(", ")}` : "must be a string"
+      });
+    }
+  }
+}
+function validateAnimationShape(path, value, issues) {
+  if (value === undefined)
+    return;
+  if (!isPlainObject(value)) {
+    issues.push({ path, message: "must be an object" });
+    return;
+  }
+  assertNoUnknownKeys(value, ANIMATION_KEYS, path, issues);
+  validateFiniteNonNegative(`${path}.duration`, value.duration, issues);
+  if (typeof value.easing !== "string") {
+    issues.push({ path: `${path}.easing`, message: "must be a string" });
+  }
+}
+function validateBaseOptionsShape(path, value, issues) {
+  validateOptionalBoolean(`${path}.animated`, value.animated, issues);
+  validateAnimationShape(`${path}.animation`, value.animation, issues);
+}
+function validateOverlayShape(path, value, issues) {
+  if (value === undefined)
+    return;
+  if (!isPlainObject(value)) {
+    issues.push({ path, message: "must be an object" });
+    return;
+  }
+  assertNoUnknownKeys(value, OVERLAY_KEYS, path, issues);
+  validateBaseOptionsShape(path, value, issues);
+  validateOptionalString(`${path}.color`, value.color, issues);
+  if (value.opacity !== undefined && (typeof value.opacity !== "number" || !Number.isFinite(value.opacity) || value.opacity < 0 || value.opacity > 1)) {
+    issues.push({ path: `${path}.opacity`, message: "must be a finite number between 0 and 1" });
+  }
+  validateOptionalFiniteNonNegative(`${path}.padding`, value.padding, issues);
+  validateOptionalFiniteNonNegative(`${path}.radius`, value.radius, issues);
+}
+function validateIndicatorShape(path, value, issues) {
+  if (value === undefined)
+    return;
+  if (!isPlainObject(value)) {
+    issues.push({ path, message: "must be an object" });
+    return;
+  }
+  assertNoUnknownKeys(value, INDICATOR_KEYS, path, issues);
+  validateBaseOptionsShape(path, value, issues);
+  validateOptionalBoolean(`${path}.disabled`, value.disabled, issues);
+  validateOptionalFiniteNonNegative(`${path}.gap`, value.gap, issues);
+  validateOptionalStringArray(`${path}.placementTryOrder`, value.placementTryOrder, issues, [
+    "top",
+    "bottom",
+    "left",
+    "right"
+  ]);
+}
+function validatePopoverArrowShape(path, value, issues) {
+  if (value === undefined)
+    return;
+  if (!isPlainObject(value)) {
+    issues.push({ path, message: "must be an object" });
+    return;
+  }
+  assertNoUnknownKeys(value, POPOVER_ARROW_KEYS, path, issues);
+  validateOptionalBoolean(`${path}.disabled`, value.disabled, issues);
+  validateOptionalString(`${path}.color`, value.color, issues);
+  validateOptionalFiniteNonNegative(`${path}.size`, value.size, issues);
+  validateOptionalFiniteNonNegative(`${path}.borderWidth`, value.borderWidth, issues);
+  validateOptionalFiniteNonNegative(`${path}.borderRadius`, value.borderRadius, issues);
+  validateOptionalFiniteNonNegative(`${path}.edgePadding`, value.edgePadding, issues);
+  validateOptionalString(`${path}.styleNonce`, value.styleNonce, issues);
+  validateOptionalBoolean(`${path}.disableAutoStyles`, value.disableAutoStyles, issues);
+}
+function validateKeyboardShortcutsShape(path, value, issues) {
+  if (value === undefined)
+    return;
+  if (!isPlainObject(value)) {
+    issues.push({ path, message: "must be an object" });
+    return;
+  }
+  assertNoUnknownKeys(value, KEYBOARD_SHORTCUT_KEYS, path, issues);
+  for (const key of KEYBOARD_SHORTCUT_KEYS) {
+    validateOptionalStringArray(`${path}.${key}`, value[key], issues);
+  }
+}
+function validatePopoverShape(path, value, issues) {
+  if (value === undefined)
+    return;
+  if (!isPlainObject(value)) {
+    issues.push({ path, message: "must be an object" });
+    return;
+  }
+  assertNoUnknownKeys(value, POPOVER_KEYS, path, issues);
+  validateBaseOptionsShape(path, value, issues);
+  validateOptionalStringArray(`${path}.placementTryOrder`, value.placementTryOrder, issues, [
+    "top",
+    "bottom",
+    "left",
+    "right"
+  ]);
+  validatePopoverArrowShape(`${path}.arrow`, value.arrow, issues);
+  validateOptionalBoolean(`${path}.hideFooter`, value.hideFooter, issues);
+  validateOptionalBoolean(`${path}.disablePreviousButton`, value.disablePreviousButton, issues);
+  validateOptionalBoolean(`${path}.hidePreviousButton`, value.hidePreviousButton, issues);
+  validateOptionalBoolean(`${path}.disableAdvanceButton`, value.disableAdvanceButton, issues);
+  validateOptionalBoolean(`${path}.hideAdvanceButton`, value.hideAdvanceButton, issues);
+  validateOptionalFiniteNonNegative(`${path}.gap`, value.gap, issues);
+  validateKeyboardShortcutsShape(`${path}.keyboardShortcuts`, value.keyboardShortcuts, issues);
+}
+function validateScrollShape(path, value, issues) {
+  if (value === undefined)
+    return;
+  if (!isPlainObject(value)) {
+    issues.push({ path, message: "must be an object" });
+    return;
+  }
+  assertNoUnknownKeys(value, SCROLL_KEYS, path, issues);
+  validateOptionalEnum(`${path}.behavior`, value.behavior, ["auto", "smooth"], issues);
+  validateOptionalEnum(`${path}.block`, value.block, ["start", "center", "end", "nearest"], issues);
+  validateOptionalEnum(`${path}.inline`, value.inline, ["start", "center", "end", "nearest"], issues);
+}
+function validateBehaviorShape(path, value, issues) {
+  if (value === undefined)
+    return;
+  if (!isPlainObject(value)) {
+    issues.push({ path, message: "must be an object" });
+    return;
+  }
+  assertNoUnknownKeys(value, BEHAVIOR_KEYS, path, issues);
+  validateOptionalBoolean(`${path}.allowInteraction`, value.allowInteraction, issues);
+  validateOptionalBoolean(`${path}.disableAutoFocus`, value.disableAutoFocus, issues);
+  validateOptionalBoolean(`${path}.disableAutoScroll`, value.disableAutoScroll, issues);
+  validateOptionalEnum(`${path}.missingTargetStrategy`, value.missingTargetStrategy, ["wait", "skip", "error"], issues);
+  validateScrollShape(`${path}.scroll`, value.scroll, issues);
+  validateOptionalFiniteNonNegative(`${path}.targetTimeout`, value.targetTimeout, issues);
+  validateOptionalEnum(`${path}.overlayClick`, value.overlayClick, ["none", "advance", "cancel"], issues);
+}
+function validateDataShape(path, value, issues) {
+  if (value === undefined)
+    return;
+  if (!isPlainObject(value)) {
+    issues.push({ path, message: "data must be an object" });
+    return;
+  }
+  for (const [key, entry] of Object.entries(value)) {
+    const isPrimitive = entry === null || typeof entry === "string" || typeof entry === "number" || typeof entry === "boolean";
+    if (!isPrimitive) {
+      issues.push({
+        path: `${path}.${key}`,
+        message: "data values must be a string, number, boolean, or null"
+      });
+    }
+  }
+}
+function assertNoUnknownKeys(value, allowedKeys, path, issues) {
+  for (const key of Object.keys(value)) {
+    if (!allowedKeys.includes(key)) {
+      issues.push({ path: path ? `${path}.${key}` : key, message: `Unknown key: ${key}` });
+    }
+  }
+}
+
+// packages/core/src/config/from-config.ts
+function createWorkflowFromConfig(config, options = {}) {
+  const validated = validateWorkflowConfig(config, options);
+  const builder = new WorkflowBuilder(validated.name, {
+    cancellable: validated.cancellable,
+    allowScroll: validated.allowScroll,
+    overlay: validated.overlay,
+    popover: validated.popover,
+    indicator: validated.indicator,
+    animated: validated.animated,
+    behavior: validated.behavior,
+    onStart: validated.onStart,
+    onCancel: validated.onCancel,
+    onFinish: validated.onFinish
+  });
+  for (const [index, stepConfig] of validated.steps.entries()) {
+    applyStepConfig(builder, stepConfig, `steps[${index}]`);
+  }
+  const definition = builder.build();
+  return Object.freeze({ ...definition, source: deepFreezeClone(validated) });
+}
+function applyStepConfig(builder, stepConfig, path) {
+  const step = builder.step({
+    id: stepConfig.id,
+    target: stepConfig.target,
+    resetPropsOnEnter: stepConfig.resetPropsOnEnter,
+    overlay: stepConfig.overlay,
+    popover: stepConfig.popover,
+    indicator: stepConfig.indicator,
+    behavior: stepConfig.behavior,
+    title: stepConfig.title,
+    content: stepConfig.content,
+    data: stepConfig.data
+  });
+  for (const [index, actionRef] of (stepConfig.actions ?? []).entries()) {
+    applyStepActionRef(step, actionRef, `${path}.actions[${index}]`);
+  }
+  for (const [index, handler] of (stepConfig.eventHandlers ?? []).entries()) {
+    applyEventHandler(step, handler, `${path}.eventHandlers[${index}]`);
+  }
+  if (stepConfig.advanceAction)
+    step.beforeAdvance(stepConfig.advanceAction);
+  if (stepConfig.previousAction)
+    step.beforePrevious(stepConfig.previousAction);
+  if (stepConfig.cancelAction)
+    step.beforeCancel(stepConfig.cancelAction);
+}
+function applyStepActionRef(step, ref, path) {
+  if (typeof ref === "function") {
+    step.do(ref);
+    return;
+  }
+  applyBuiltinAction(step, ref, path);
+}
+function applyBuiltinAction(step, builtin, path) {
+  switch (builtin.type) {
+    case "wait":
+      step.wait(builtin.ms);
+      return;
+    case "waitUntilElement":
+      step.waitUntilElement(builtin.selector, {
+        interval: builtin.interval,
+        timeout: builtin.timeout
+      });
+      return;
+    case "clickTarget":
+      step.clickTarget();
+      return;
+    case "focusTarget":
+      step.focusTarget();
+      return;
+    default:
+      throw new Error(`Unknown built-in action type at ${path}`);
+  }
+}
+function applyEventHandler(step, handler, path) {
+  const action = resolveEventHandlerAction(handler.action, `${path}.action`);
+  const events = typeof handler.event === "string" ? [handler.event] : handler.event;
+  for (const event of events) {
+    step.onTargetEvent(event, async (_event, context) => {
+      await action(context);
+    });
+  }
+}
+function resolveEventHandlerAction(ref, path) {
+  if (typeof ref === "function")
+    return ref;
+  const scratch = new WorkflowBuilder("__config_event_handler_scratch__");
+  const scratchStep = scratch.step({ id: "scratch", target: "*", title: "", content: "" });
+  applyBuiltinAction(scratchStep, ref, path);
+  const [instruction] = scratch.build().steps[0]?.actions ?? [];
+  if (instruction === undefined) {
+    throw new Error(`Failed to resolve built-in action at ${path}`);
+  }
+  if (typeof instruction === "number") {
+    const delayMs = instruction;
+    return async (context) => {
+      await abortableDelay(delayMs, context.signal);
+      return true;
+    };
+  }
+  return instruction;
+}
+function deepFreezeClone(value, clones = new WeakMap, preserveReference = false) {
+  if (preserveReference)
+    return value;
+  if (Array.isArray(value)) {
+    const existing2 = clones.get(value);
+    if (existing2)
+      return existing2;
+    const clone2 = [];
+    clones.set(value, clone2);
+    for (const entry of value)
+      clone2.push(deepFreezeClone(entry, clones));
+    return Object.freeze(clone2);
+  }
+  if (value === null || typeof value !== "object")
+    return value;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== null && prototype !== Object.prototype)
+    return value;
+  const existing = clones.get(value);
+  if (existing)
+    return existing;
+  const clone = Object.create(prototype);
+  clones.set(value, clone);
+  for (const [key, entry] of Object.entries(value)) {
+    clone[key] = deepFreezeClone(entry, clones, key === "title" || key === "content");
+  }
+  return Object.freeze(clone);
+}
+export {
+  validateWorkflowConfig,
+  createWorkflowFromConfig,
+  ConfigValidationError
+};