@vulcn/engine 0.1.0 → 0.3.0

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,86 +17,579 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// index.ts
+// src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  BUILTIN_PAYLOADS: () => BUILTIN_PAYLOADS,
   BrowserNotFoundError: () => BrowserNotFoundError,
+  DRIVER_API_VERSION: () => DRIVER_API_VERSION,
+  DriverManager: () => DriverManager,
+  PLUGIN_API_VERSION: () => PLUGIN_API_VERSION,
+  PluginManager: () => PluginManager,
   Recorder: () => Recorder,
   Runner: () => Runner,
   SessionSchema: () => SessionSchema,
   StepSchema: () => StepSchema,
   checkBrowsers: () => checkBrowsers,
   createSession: () => createSession,
-  getPayload: () => getPayload,
-  getPayloadNames: () => getPayloadNames,
-  getPayloadsByCategory: () => getPayloadsByCategory,
+  driverManager: () => driverManager,
   installBrowsers: () => installBrowsers,
   launchBrowser: () => launchBrowser,
   parseSession: () => parseSession,
+  pluginManager: () => pluginManager,
   serializeSession: () => serializeSession
 });
 module.exports = __toCommonJS(index_exports);
 
-// session.ts
+// src/driver-manager.ts
+var import_node_path = require("path");
+var DriverManager = class {
+  drivers = /* @__PURE__ */ new Map();
+  defaultDriver = null;
+  /**
+   * Register a driver
+   */
+  register(driver, source = "builtin") {
+    this.validateDriver(driver);
+    this.drivers.set(driver.name, { driver, source });
+    if (this.drivers.size === 1) {
+      this.defaultDriver = driver.name;
+    }
+  }
+  /**
+   * Load a driver from npm or local path
+   */
+  async load(nameOrPath) {
+    let driver;
+    let source;
+    if (nameOrPath.startsWith("./") || nameOrPath.startsWith("../") || (0, import_node_path.isAbsolute)(nameOrPath)) {
+      const resolved = (0, import_node_path.isAbsolute)(nameOrPath) ? nameOrPath : (0, import_node_path.resolve)(process.cwd(), nameOrPath);
+      const module2 = await import(resolved);
+      driver = module2.default || module2;
+      source = "local";
+    } else {
+      const module2 = await import(nameOrPath);
+      driver = module2.default || module2;
+      source = "npm";
+    }
+    this.register(driver, source);
+  }
+  /**
+   * Get a loaded driver by name
+   */
+  get(name) {
+    return this.drivers.get(name)?.driver;
+  }
+  /**
+   * Get the default driver
+   */
+  getDefault() {
+    if (!this.defaultDriver) return void 0;
+    return this.get(this.defaultDriver);
+  }
+  /**
+   * Set the default driver
+   */
+  setDefault(name) {
+    if (!this.drivers.has(name)) {
+      throw new Error(`Driver "${name}" is not registered`);
+    }
+    this.defaultDriver = name;
+  }
+  /**
+   * Check if a driver is registered
+   */
+  has(name) {
+    return this.drivers.has(name);
+  }
+  /**
+   * Get all registered drivers
+   */
+  list() {
+    return Array.from(this.drivers.values());
+  }
+  /**
+   * Get driver for a session
+   */
+  getForSession(session) {
+    const driverName = session.driver;
+    const driver = this.get(driverName);
+    if (!driver) {
+      throw new Error(
+        `Driver "${driverName}" not found. Install @vulcn/driver-${driverName} or load it manually.`
+      );
+    }
+    return driver;
+  }
+  /**
+   * Start recording with a driver
+   */
+  async startRecording(driverName, config, options = {}) {
+    const driver = this.get(driverName);
+    if (!driver) {
+      throw new Error(`Driver "${driverName}" not found`);
+    }
+    return driver.recorder.start(config, options);
+  }
+  /**
+   * Execute a session
+   */
+  async execute(session, pluginManager2, options = {}) {
+    const driver = this.getForSession(session);
+    const findings = [];
+    const logger = this.createLogger(driver.name);
+    const ctx = {
+      session,
+      pluginManager: pluginManager2,
+      payloads: pluginManager2.getPayloads(),
+      findings,
+      addFinding: (finding) => {
+        findings.push(finding);
+        pluginManager2.addFinding(finding);
+        options.onFinding?.(finding);
+      },
+      logger,
+      options
+    };
+    return driver.runner.execute(session, ctx);
+  }
+  /**
+   * Validate driver structure
+   */
+  validateDriver(driver) {
+    if (!driver || typeof driver !== "object") {
+      throw new Error("Driver must be an object");
+    }
+    const d = driver;
+    if (typeof d.name !== "string" || !d.name) {
+      throw new Error("Driver must have a name");
+    }
+    if (typeof d.version !== "string" || !d.version) {
+      throw new Error("Driver must have a version");
+    }
+    if (!Array.isArray(d.stepTypes) || d.stepTypes.length === 0) {
+      throw new Error("Driver must define stepTypes");
+    }
+    if (!d.recorder || typeof d.recorder !== "object") {
+      throw new Error("Driver must have a recorder");
+    }
+    if (!d.runner || typeof d.runner !== "object") {
+      throw new Error("Driver must have a runner");
+    }
+  }
+  /**
+   * Create a scoped logger for a driver
+   */
+  createLogger(name) {
+    const prefix = `[driver:${name}]`;
+    return {
+      debug: (msg, ...args) => console.debug(prefix, msg, ...args),
+      info: (msg, ...args) => console.info(prefix, msg, ...args),
+      warn: (msg, ...args) => console.warn(prefix, msg, ...args),
+      error: (msg, ...args) => console.error(prefix, msg, ...args)
+    };
+  }
+};
+var driverManager = new DriverManager();
+
+// src/driver-types.ts
+var DRIVER_API_VERSION = 1;
+
+// src/plugin-manager.ts
+var import_promises = require("fs/promises");
+var import_node_fs = require("fs");
+var import_node_path2 = require("path");
+var import_yaml = __toESM(require("yaml"), 1);
 var import_zod = require("zod");
-var import_yaml = require("yaml");
-var StepSchema = import_zod.z.discriminatedUnion("type", [
-  import_zod.z.object({
-    id: import_zod.z.string(),
-    type: import_zod.z.literal("navigate"),
-    url: import_zod.z.string(),
-    timestamp: import_zod.z.number()
+
+// src/plugin-types.ts
+var PLUGIN_API_VERSION = 1;
+
+// src/plugin-manager.ts
+var ENGINE_VERSION = "0.2.0";
+var VulcnConfigSchema = import_zod.z.object({
+  version: import_zod.z.string().default("1"),
+  plugins: import_zod.z.array(
+    import_zod.z.object({
+      name: import_zod.z.string(),
+      config: import_zod.z.record(import_zod.z.unknown()).optional(),
+      enabled: import_zod.z.boolean().default(true)
+    })
+  ).optional(),
+  settings: import_zod.z.object({
+    browser: import_zod.z.enum(["chromium", "firefox", "webkit"]).optional(),
+    headless: import_zod.z.boolean().optional(),
+    timeout: import_zod.z.number().optional()
+  }).optional()
+});
+var PluginManager = class {
+  plugins = [];
+  config = null;
+  initialized = false;
+  /**
+   * Shared context passed to all plugins
+   */
+  sharedPayloads = [];
+  sharedFindings = [];
+  /**
+   * Load configuration from vulcn.config.yml
+   */
+  async loadConfig(configPath) {
+    const paths = configPath ? [configPath] : [
+      "vulcn.config.yml",
+      "vulcn.config.yaml",
+      "vulcn.config.json",
+      ".vulcnrc.yml",
+      ".vulcnrc.yaml",
+      ".vulcnrc.json"
+    ];
+    for (const path of paths) {
+      const resolved = (0, import_node_path2.isAbsolute)(path) ? path : (0, import_node_path2.resolve)(process.cwd(), path);
+      if ((0, import_node_fs.existsSync)(resolved)) {
+        const content = await (0, import_promises.readFile)(resolved, "utf-8");
+        const parsed = path.endsWith(".json") ? JSON.parse(content) : import_yaml.default.parse(content);
+        this.config = VulcnConfigSchema.parse(parsed);
+        return this.config;
+      }
+    }
+    this.config = { version: "1", plugins: [], settings: {} };
+    return this.config;
+  }
+  /**
+   * Load all plugins from config
+   */
+  async loadPlugins() {
+    if (!this.config) {
+      await this.loadConfig();
+    }
+    const pluginConfigs = this.config?.plugins || [];
+    for (const pluginConfig of pluginConfigs) {
+      if (pluginConfig.enabled === false) continue;
+      try {
+        const loaded = await this.loadPlugin(pluginConfig);
+        this.plugins.push(loaded);
+      } catch (err) {
+        console.error(
+          `Failed to load plugin ${pluginConfig.name}:`,
+          err instanceof Error ? err.message : String(err)
+        );
+      }
+    }
+  }
+  /**
+   * Load a single plugin
+   */
+  async loadPlugin(config) {
+    const { name, config: pluginConfig = {} } = config;
+    let plugin;
+    let source;
+    if (name.startsWith("./") || name.startsWith("../") || (0, import_node_path2.isAbsolute)(name)) {
+      const resolved = (0, import_node_path2.isAbsolute)(name) ? name : (0, import_node_path2.resolve)(process.cwd(), name);
+      const module2 = await import(resolved);
+      plugin = module2.default || module2;
+      source = "local";
+    } else if (name.startsWith("@vulcn/")) {
+      const module2 = await import(name);
+      plugin = module2.default || module2;
+      source = "npm";
+    } else {
+      const module2 = await import(name);
+      plugin = module2.default || module2;
+      source = "npm";
+    }
+    this.validatePlugin(plugin);
+    let resolvedConfig = pluginConfig;
+    if (plugin.configSchema) {
+      try {
+        resolvedConfig = plugin.configSchema.parse(pluginConfig);
+      } catch (err) {
+        throw new Error(
+          `Invalid config for plugin ${name}: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+    return {
+      plugin,
+      config: resolvedConfig,
+      source,
+      enabled: true
+    };
+  }
+  /**
+   * Validate plugin structure
+   */
+  validatePlugin(plugin) {
+    if (!plugin || typeof plugin !== "object") {
+      throw new Error("Plugin must be an object");
+    }
+    const p = plugin;
+    if (typeof p.name !== "string" || !p.name) {
+      throw new Error("Plugin must have a name");
+    }
+    if (typeof p.version !== "string" || !p.version) {
+      throw new Error("Plugin must have a version");
+    }
+    const apiVersion = p.apiVersion || 1;
+    if (apiVersion > PLUGIN_API_VERSION) {
+      throw new Error(
+        `Plugin requires API version ${apiVersion}, but engine supports ${PLUGIN_API_VERSION}`
+      );
+    }
+  }
+  /**
+   * Add a plugin programmatically (for testing or dynamic loading)
+   */
+  addPlugin(plugin, config = {}) {
+    this.validatePlugin(plugin);
+    this.plugins.push({
+      plugin,
+      config,
+      source: "custom",
+      enabled: true
+    });
+  }
+  /**
+   * Initialize all plugins (call onInit hooks)
+   */
+  async initialize() {
+    if (this.initialized) return;
+    for (const loaded of this.plugins) {
+      if (loaded.plugin.payloads) {
+        const payloads = typeof loaded.plugin.payloads === "function" ? await loaded.plugin.payloads() : loaded.plugin.payloads;
+        this.sharedPayloads.push(...payloads);
+      }
+    }
+    await this.callHook("onInit", (hook, ctx) => hook(ctx));
+    this.initialized = true;
+  }
+  /**
+   * Destroy all plugins (call onDestroy hooks)
+   */
+  async destroy() {
+    await this.callHook("onDestroy", (hook, ctx) => hook(ctx));
+    this.plugins = [];
+    this.sharedPayloads = [];
+    this.sharedFindings = [];
+    this.initialized = false;
+  }
+  /**
+   * Get all loaded payloads
+   */
+  getPayloads() {
+    return this.sharedPayloads;
+  }
+  /**
+   * Get all collected findings
+   */
+  getFindings() {
+    return this.sharedFindings;
+  }
+  /**
+   * Add a finding (used by detectors)
+   */
+  addFinding(finding) {
+    this.sharedFindings.push(finding);
+  }
+  /**
+   * Add payloads (used by loaders)
+   */
+  addPayloads(payloads) {
+    this.sharedPayloads.push(...payloads);
+  }
+  /**
+   * Clear findings (for new run)
+   */
+  clearFindings() {
+    this.sharedFindings = [];
+  }
+  /**
+   * Get loaded plugins
+   */
+  getPlugins() {
+    return this.plugins;
+  }
+  /**
+   * Check if a plugin is loaded by name
+   */
+  hasPlugin(name) {
+    return this.plugins.some((p) => p.plugin.name === name);
+  }
+  /**
+   * Create base context for plugins
+   */
+  createContext(pluginConfig) {
+    const engineInfo = {
+      version: ENGINE_VERSION,
+      pluginApiVersion: PLUGIN_API_VERSION
+    };
+    return {
+      config: pluginConfig,
+      engine: engineInfo,
+      payloads: this.sharedPayloads,
+      findings: this.sharedFindings,
+      logger: this.createLogger("plugin"),
+      fetch: globalThis.fetch
+    };
+  }
+  /**
+   * Create scoped logger for a plugin
+   */
+  createLogger(name) {
+    const prefix = `[${name}]`;
+    return {
+      debug: (msg, ...args) => console.debug(prefix, msg, ...args),
+      info: (msg, ...args) => console.info(prefix, msg, ...args),
+      warn: (msg, ...args) => console.warn(prefix, msg, ...args),
+      error: (msg, ...args) => console.error(prefix, msg, ...args)
+    };
+  }
+  /**
+   * Call a hook on all plugins sequentially
+   */
+  async callHook(hookName, executor) {
+    for (const loaded of this.plugins) {
+      const hook = loaded.plugin.hooks?.[hookName];
+      if (hook) {
+        const ctx = this.createContext(loaded.config);
+        ctx.logger = this.createLogger(loaded.plugin.name);
+        try {
+          await executor(hook, ctx);
+        } catch (err) {
+          console.error(
+            `Error in plugin ${loaded.plugin.name}.${hookName}:`,
+            err instanceof Error ? err.message : String(err)
+          );
+        }
+      }
+    }
+  }
+  /**
+   * Call a hook and collect results
+   */
+  async callHookCollect(hookName, executor) {
+    const results = [];
+    for (const loaded of this.plugins) {
+      const hook = loaded.plugin.hooks?.[hookName];
+      if (hook) {
+        const ctx = this.createContext(loaded.config);
+        ctx.logger = this.createLogger(loaded.plugin.name);
+        try {
+          const result = await executor(
+            hook,
+            ctx
+          );
+          if (result !== null && result !== void 0) {
+            if (Array.isArray(result)) {
+              results.push(...result);
+            } else {
+              results.push(result);
+            }
+          }
+        } catch (err) {
+          console.error(
+            `Error in plugin ${loaded.plugin.name}.${hookName}:`,
+            err instanceof Error ? err.message : String(err)
+          );
+        }
+      }
+    }
+    return results;
+  }
+  /**
+   * Call a hook that transforms a value through the pipeline
+   */
+  async callHookPipe(hookName, initial, executor) {
+    let value = initial;
+    for (const loaded of this.plugins) {
+      const hook = loaded.plugin.hooks?.[hookName];
+      if (hook) {
+        const ctx = this.createContext(loaded.config);
+        ctx.logger = this.createLogger(loaded.plugin.name);
+        try {
+          value = await executor(
+            hook,
+            value,
+            ctx
+          );
+        } catch (err) {
+          console.error(
+            `Error in plugin ${loaded.plugin.name}.${hookName}:`,
+            err instanceof Error ? err.message : String(err)
+          );
+        }
+      }
+    }
+    return value;
+  }
+};
+var pluginManager = new PluginManager();
+
+// src/session.ts
+var import_zod2 = require("zod");
+var import_yaml2 = require("yaml");
+var StepSchema = import_zod2.z.discriminatedUnion("type", [
+  import_zod2.z.object({
+    id: import_zod2.z.string(),
+    type: import_zod2.z.literal("navigate"),
+    url: import_zod2.z.string(),
+    timestamp: import_zod2.z.number()
   }),
-  import_zod.z.object({
-    id: import_zod.z.string(),
-    type: import_zod.z.literal("click"),
-    selector: import_zod.z.string(),
-    position: import_zod.z.object({ x: import_zod.z.number(), y: import_zod.z.number() }).optional(),
-    timestamp: import_zod.z.number()
+  import_zod2.z.object({
+    id: import_zod2.z.string(),
+    type: import_zod2.z.literal("click"),
+    selector: import_zod2.z.string(),
+    position: import_zod2.z.object({ x: import_zod2.z.number(), y: import_zod2.z.number() }).optional(),
+    timestamp: import_zod2.z.number()
   }),
-  import_zod.z.object({
-    id: import_zod.z.string(),
-    type: import_zod.z.literal("input"),
-    selector: import_zod.z.string(),
-    value: import_zod.z.string(),
-    injectable: import_zod.z.boolean().optional().default(true),
-    timestamp: import_zod.z.number()
+  import_zod2.z.object({
+    id: import_zod2.z.string(),
+    type: import_zod2.z.literal("input"),
+    selector: import_zod2.z.string(),
+    value: import_zod2.z.string(),
+    injectable: import_zod2.z.boolean().optional().default(true),
+    timestamp: import_zod2.z.number()
   }),
-  import_zod.z.object({
-    id: import_zod.z.string(),
-    type: import_zod.z.literal("keypress"),
-    key: import_zod.z.string(),
-    modifiers: import_zod.z.array(import_zod.z.string()).optional(),
-    timestamp: import_zod.z.number()
+  import_zod2.z.object({
+    id: import_zod2.z.string(),
+    type: import_zod2.z.literal("keypress"),
+    key: import_zod2.z.string(),
+    modifiers: import_zod2.z.array(import_zod2.z.string()).optional(),
+    timestamp: import_zod2.z.number()
   }),
-  import_zod.z.object({
-    id: import_zod.z.string(),
-    type: import_zod.z.literal("scroll"),
-    selector: import_zod.z.string().optional(),
-    position: import_zod.z.object({ x: import_zod.z.number(), y: import_zod.z.number() }),
-    timestamp: import_zod.z.number()
+  import_zod2.z.object({
+    id: import_zod2.z.string(),
+    type: import_zod2.z.literal("scroll"),
+    selector: import_zod2.z.string().optional(),
+    position: import_zod2.z.object({ x: import_zod2.z.number(), y: import_zod2.z.number() }),
+    timestamp: import_zod2.z.number()
   }),
-  import_zod.z.object({
-    id: import_zod.z.string(),
-    type: import_zod.z.literal("wait"),
-    duration: import_zod.z.number(),
-    timestamp: import_zod.z.number()
+  import_zod2.z.object({
+    id: import_zod2.z.string(),
+    type: import_zod2.z.literal("wait"),
+    duration: import_zod2.z.number(),
+    timestamp: import_zod2.z.number()
   })
 ]);
-var SessionSchema = import_zod.z.object({
-  version: import_zod.z.string().default("1"),
-  name: import_zod.z.string(),
-  recordedAt: import_zod.z.string(),
-  browser: import_zod.z.enum(["chromium", "firefox", "webkit"]).default("chromium"),
-  viewport: import_zod.z.object({
-    width: import_zod.z.number(),
-    height: import_zod.z.number()
+var SessionSchema = import_zod2.z.object({
+  version: import_zod2.z.string().default("1"),
+  name: import_zod2.z.string(),
+  recordedAt: import_zod2.z.string(),
+  browser: import_zod2.z.enum(["chromium", "firefox", "webkit"]).default("chromium"),
+  viewport: import_zod2.z.object({
+    width: import_zod2.z.number(),
+    height: import_zod2.z.number()
   }),
-  startUrl: import_zod.z.string(),
-  steps: import_zod.z.array(StepSchema)
+  startUrl: import_zod2.z.string(),
+  steps: import_zod2.z.array(StepSchema)
 });
 function createSession(options) {
   return {
@@ -108,14 +603,14 @@ function createSession(options) {
   };
 }
 function parseSession(yaml) {
-  const data = (0, import_yaml.parse)(yaml);
+  const data = (0, import_yaml2.parse)(yaml);
   return SessionSchema.parse(data);
 }
 function serializeSession(session) {
-  return (0, import_yaml.stringify)(session, { lineWidth: 0 });
+  return (0, import_yaml2.stringify)(session, { lineWidth: 0 });
 }
 
-// browser.ts
+// src/browser.ts
 var import_playwright = require("playwright");
 var import_node_child_process = require("child_process");
 var import_node_util = require("util");
@@ -228,16 +723,18 @@ async function checkBrowsers() {
   return results;
 }
 
-// recorder.ts
+// src/recorder.ts
 var Recorder = class _Recorder {
   /**
    * Start a new recording session
    * Opens a browser window for the user to interact with
    */
-  static async start(startUrl, options = {}) {
+  static async start(startUrl, options = {}, config = {}) {
+    const manager = config.pluginManager ?? pluginManager;
     const browserType = options.browser ?? "chromium";
     const viewport = options.viewport ?? { width: 1280, height: 720 };
     const headless = options.headless ?? false;
+    await manager.initialize();
     const { browser } = await launchBrowser({
       browser: browserType,
       headless
@@ -258,18 +755,61 @@ var Recorder = class _Recorder {
       stepCounter++;
       return `step_${String(stepCounter).padStart(3, "0")}`;
     };
-    steps.push({
+    const baseRecordContext = {
+      startUrl,
+      browser: browserType,
+      page,
+      engine: { version: "0.2.0", pluginApiVersion: 1 },
+      payloads: manager.getPayloads(),
+      findings: manager.getFindings(),
+      logger: {
+        debug: console.debug.bind(console),
+        info: console.info.bind(console),
+        warn: console.warn.bind(console),
+        error: console.error.bind(console)
+      },
+      fetch: globalThis.fetch
+    };
+    await manager.callHook("onRecordStart", async (hook, ctx) => {
+      const recordCtx = { ...baseRecordContext, ...ctx };
+      await hook(recordCtx);
+    });
+    const initialStep = {
       id: generateStepId(),
       type: "navigate",
       url: startUrl,
       timestamp: 0
-    });
-    _Recorder.attachListeners(page, steps, startTime, generateStepId);
+    };
+    const transformedInitialStep = await _Recorder.transformStep(
+      initialStep,
+      manager,
+      baseRecordContext
+    );
+    if (transformedInitialStep) {
+      steps.push(transformedInitialStep);
+    }
+    _Recorder.attachListeners(
+      page,
+      steps,
+      startTime,
+      generateStepId,
+      manager,
+      baseRecordContext
+    );
     return {
       async stop() {
         session.steps = steps;
+        let finalSession = session;
+        for (const loaded of manager.getPlugins()) {
+          const hook = loaded.plugin.hooks?.onRecordEnd;
+          if (hook) {
+            const ctx = manager.createContext(loaded.config);
+            const recordCtx = { ...baseRecordContext, ...ctx };
+            finalSession = await hook(finalSession, recordCtx);
+          }
+        }
         await browser.close();
-        return session;
+        return finalSession;
       },
       getSteps() {
         return [...steps];
@@ -279,8 +819,34 @@ var Recorder = class _Recorder {
       }
     };
   }
-  static attachListeners(page, steps, startTime, generateStepId) {
+  /**
+   * Transform a step through plugin hooks
+   * Returns null if the step should be filtered out
+   */
+  static async transformStep(step, manager, baseContext) {
+    let transformedStep = step;
+    for (const loaded of manager.getPlugins()) {
+      const hook = loaded.plugin.hooks?.onRecordStep;
+      if (hook) {
+        const ctx = manager.createContext(loaded.config);
+        const recordCtx = { ...baseContext, ...ctx };
+        transformedStep = await hook(transformedStep, recordCtx);
+      }
+    }
+    return transformedStep;
+  }
+  static attachListeners(page, steps, startTime, generateStepId, manager, baseContext) {
     const getTimestamp = () => Date.now() - startTime;
+    const addStep = async (step) => {
+      const transformed = await _Recorder.transformStep(
+        step,
+        manager,
+        baseContext
+      );
+      if (transformed) {
+        steps.push(transformed);
+      }
+    };
     page.on("framenavigated", (frame) => {
       if (frame === page.mainFrame()) {
         const url = frame.url();
@@ -288,7 +854,7 @@ var Recorder = class _Recorder {
         if (steps.length > 0 && lastStep.type === "navigate" && lastStep.url === url) {
           return;
         }
-        steps.push({
+        addStep({
           id: generateStepId(),
           type: "navigate",
           url,
@@ -298,12 +864,12 @@ var Recorder = class _Recorder {
     });
     page.exposeFunction(
       "__vulcn_record",
-      (event) => {
+      async (event) => {
         const timestamp = getTimestamp();
         switch (event.type) {
           case "click": {
             const data = event.data;
-            steps.push({
+            await addStep({
               id: generateStepId(),
               type: "click",
               selector: data.selector,
@@ -314,7 +880,7 @@ var Recorder = class _Recorder {
           }
           case "input": {
             const data = event.data;
-            steps.push({
+            await addStep({
               id: generateStepId(),
               type: "input",
               selector: data.selector,
@@ -326,7 +892,7 @@ var Recorder = class _Recorder {
           }
           case "keypress": {
             const data = event.data;
-            steps.push({
+            await addStep({
               id: generateStepId(),
               type: "keypress",
               key: data.key,
@@ -463,163 +1029,156 @@ var Recorder = class _Recorder {
   }
 };
 
-// payloads.ts
-var BUILTIN_PAYLOADS = {
-  "xss-basic": {
-    name: "xss-basic",
-    category: "xss",
-    description: "Basic XSS payloads with script tags and event handlers",
-    payloads: [
-      '<script>alert("XSS")</script>',
-      '<img src=x onerror=alert("XSS")>',
-      '"><script>alert("XSS")</script>',
-      "javascript:alert('XSS')",
-      '<svg onload=alert("XSS")>'
-    ],
-    detectPatterns: [
-      /<script[^>]*>alert\(/i,
-      /onerror\s*=\s*alert\(/i,
-      /onload\s*=\s*alert\(/i,
-      /javascript:alert\(/i
-    ]
-  },
-  "xss-event": {
-    name: "xss-event",
-    category: "xss",
-    description: "XSS via event handlers",
-    payloads: [
-      '" onfocus="alert(1)" autofocus="',
-      "' onmouseover='alert(1)'",
-      '<body onload=alert("XSS")>',
-      "<input onfocus=alert(1) autofocus>",
-      "<marquee onstart=alert(1)>"
-    ],
-    detectPatterns: [
-      /onfocus\s*=\s*["']?alert/i,
-      /onmouseover\s*=\s*["']?alert/i,
-      /onload\s*=\s*["']?alert/i,
-      /onstart\s*=\s*["']?alert/i
-    ]
-  },
-  "xss-svg": {
-    name: "xss-svg",
-    category: "xss",
-    description: "XSS via SVG elements",
-    payloads: [
-      '<svg/onload=alert("XSS")>',
-      "<svg><script>alert(1)</script></svg>",
-      "<svg><animate onbegin=alert(1)>",
-      "<svg><set onbegin=alert(1)>"
-    ],
-    detectPatterns: [
-      /<svg[^>]*onload\s*=/i,
-      /<svg[^>]*>.*<script>/i,
-      /onbegin\s*=\s*alert/i
-    ]
-  },
-  "sqli-basic": {
-    name: "sqli-basic",
-    category: "sqli",
-    description: "Basic SQL injection payloads",
-    payloads: [
-      "' OR '1'='1",
-      "' OR '1'='1' --",
-      "1' OR '1'='1",
-      "admin'--",
-      "' UNION SELECT NULL--"
-    ],
-    detectPatterns: [
-      /sql.*syntax/i,
-      /mysql.*error/i,
-      /ORA-\d{5}/i,
-      /pg_query/i,
-      /sqlite.*error/i,
-      /unclosed.*quotation/i
-    ]
-  },
-  "sqli-error": {
-    name: "sqli-error",
-    category: "sqli",
-    description: "SQL injection payloads to trigger errors",
-    payloads: ["'", "''", "`", '"', "')", `'"`, "1' AND '1'='2", "1 AND 1=2"],
-    detectPatterns: [
-      /sql.*syntax/i,
-      /mysql.*error/i,
-      /ORA-\d{5}/i,
-      /postgresql.*error/i,
-      /sqlite.*error/i,
-      /quoted.*string.*properly.*terminated/i
-    ]
-  },
-  "sqli-blind": {
-    name: "sqli-blind",
-    category: "sqli",
-    description: "Blind SQL injection payloads",
-    payloads: [
-      "1' AND SLEEP(5)--",
-      "1; WAITFOR DELAY '0:0:5'--",
-      "1' AND (SELECT COUNT(*) FROM information_schema.tables)>0--"
-    ],
-    detectPatterns: [
-      // Blind SQLi is detected by timing, not content
-    ]
-  }
-};
-function getPayload(name) {
-  return BUILTIN_PAYLOADS[name];
-}
-function getPayloadNames() {
-  return Object.keys(BUILTIN_PAYLOADS);
-}
-function getPayloadsByCategory(category) {
-  return Object.values(BUILTIN_PAYLOADS).filter((p) => p.category === category);
-}
-
-// runner.ts
+// src/runner.ts
 var Runner = class _Runner {
   /**
-   * Execute a session with security payloads
+   * Execute a session with security payloads from plugins
+   *
+   * @param session - The recorded session to replay
+   * @param options - Runner configuration
+   * @param config - Plugin manager configuration
    */
-  static async execute(session, payloadNames, options = {}) {
+  static async execute(session, options = {}, config = {}) {
+    const manager = config.pluginManager ?? pluginManager;
     const browserType = options.browser ?? session.browser ?? "chromium";
     const headless = options.headless ?? true;
     const startTime = Date.now();
-    const findings = [];
     const errors = [];
     let payloadsTested = 0;
+    await manager.initialize();
+    manager.clearFindings();
+    const payloads = manager.getPayloads();
+    if (payloads.length === 0) {
+      return {
+        findings: [],
+        stepsExecuted: session.steps.length,
+        payloadsTested: 0,
+        duration: Date.now() - startTime,
+        errors: [
+          "No payloads loaded. Add a payload plugin or configure payloads."
+        ]
+      };
+    }
     const { browser } = await launchBrowser({
       browser: browserType,
       headless
     });
     const context = await browser.newContext({ viewport: session.viewport });
     const page = await context.newPage();
+    const baseRunContext = {
+      session,
+      page,
+      browser: browserType,
+      headless,
+      engine: { version: "0.2.0", pluginApiVersion: 1 },
+      payloads: manager.getPayloads(),
+      findings: manager.getFindings(),
+      logger: {
+        debug: console.debug.bind(console),
+        info: console.info.bind(console),
+        warn: console.warn.bind(console),
+        error: console.error.bind(console)
+      },
+      fetch: globalThis.fetch
+    };
+    await manager.callHook("onRunStart", async (hook, ctx) => {
+      const runCtx = { ...baseRunContext, ...ctx };
+      await hook(runCtx);
+    });
+    const eventFindings = [];
+    let currentDetectContext = null;
+    const dialogHandler = async (dialog) => {
+      if (currentDetectContext) {
+        const findings = await manager.callHookCollect(
+          "onDialog",
+          async (hook, ctx) => {
+            const detectCtx = {
+              ...currentDetectContext,
+              ...ctx
+            };
+            return hook(dialog, detectCtx);
+          }
+        );
+        eventFindings.push(...findings);
+      }
+      try {
+        await dialog.dismiss();
+      } catch {
+      }
+    };
+    const consoleHandler = async (msg) => {
+      if (currentDetectContext) {
+        const findings = await manager.callHookCollect("onConsoleMessage", async (hook, ctx) => {
+          const detectCtx = { ...currentDetectContext, ...ctx };
+          return hook(msg, detectCtx);
+        });
+        eventFindings.push(...findings);
+      }
+    };
+    page.on("dialog", dialogHandler);
+    page.on("console", consoleHandler);
     try {
       const injectableSteps = session.steps.filter(
         (step) => step.type === "input" && step.injectable !== false
       );
       const allPayloads = [];
-      for (const name of payloadNames) {
-        const payload = BUILTIN_PAYLOADS[name];
-        if (payload) {
-          for (const value of payload.payloads) {
-            allPayloads.push({ name, value });
-          }
+      for (const payloadSet of payloads) {
+        for (const value of payloadSet.payloads) {
+          allPayloads.push({ payloadSet, value });
         }
       }
       for (const injectableStep of injectableSteps) {
-        for (const payload of allPayloads) {
+        for (const { payloadSet, value: originalValue } of allPayloads) {
           try {
-            const finding = await _Runner.replayWithPayload(
+            let transformedPayload = originalValue;
+            for (const loaded of manager.getPlugins()) {
+              const hook = loaded.plugin.hooks?.onBeforePayload;
+              if (hook) {
+                const ctx = manager.createContext(loaded.config);
+                const runCtx = { ...baseRunContext, ...ctx };
+                transformedPayload = await hook(
+                  transformedPayload,
+                  injectableStep,
+                  runCtx
+                );
+              }
+            }
+            currentDetectContext = {
+              ...baseRunContext,
+              config: {},
+              step: injectableStep,
+              payloadSet,
+              payloadValue: transformedPayload,
+              stepId: injectableStep.id
+            };
+            await _Runner.replayWithPayload(
               page,
               session,
               injectableStep,
-              payload.name,
-              payload.value
+              transformedPayload
             );
-            if (finding) {
-              findings.push(finding);
+            const afterFindings = await manager.callHookCollect("onAfterPayload", async (hook, ctx) => {
+              const detectCtx = {
+                ...currentDetectContext,
+                ...ctx
+              };
+              return hook(detectCtx);
+            });
+            const reflectionFinding = await _Runner.checkReflection(
+              page,
+              injectableStep,
+              payloadSet,
+              transformedPayload
+            );
+            const allFindings = [...afterFindings, ...eventFindings];
+            if (reflectionFinding) {
+              allFindings.push(reflectionFinding);
+            }
+            for (const finding of allFindings) {
+              manager.addFinding(finding);
               options.onFinding?.(finding);
             }
+            eventFindings.length = 0;
             payloadsTested++;
           } catch (err) {
             errors.push(`${injectableStep.id}: ${String(err)}`);
@@ -627,73 +1186,94 @@ var Runner = class _Runner {
         }
       }
     } finally {
+      page.off("dialog", dialogHandler);
+      page.off("console", consoleHandler);
+      currentDetectContext = null;
       await browser.close();
     }
-    return {
-      findings,
+    let result = {
+      findings: manager.getFindings(),
       stepsExecuted: session.steps.length,
       payloadsTested,
       duration: Date.now() - startTime,
       errors
     };
+    for (const loaded of manager.getPlugins()) {
+      const hook = loaded.plugin.hooks?.onRunEnd;
+      if (hook) {
+        const ctx = manager.createContext(loaded.config);
+        const runCtx = { ...baseRunContext, ...ctx };
+        result = await hook(result, runCtx);
+      }
+    }
+    return result;
   }
-  static async replayWithPayload(page, session, targetStep, payloadName, payloadValue) {
-    await page.goto(session.startUrl);
+  /**
+   * Execute with explicit payloads (legacy API, for backwards compatibility)
+   */
+  static async executeWithPayloads(session, payloads, options = {}) {
+    const manager = new PluginManager();
+    manager.addPayloads(payloads);
+    return _Runner.execute(session, options, { pluginManager: manager });
+  }
+  /**
+   * Replay session steps with payload injected at target step
+   */
+  static async replayWithPayload(page, session, targetStep, payloadValue) {
+    await page.goto(session.startUrl, { waitUntil: "domcontentloaded" });
     for (const step of session.steps) {
-      if (step.type === "navigate") {
-        await page.goto(step.url);
-      } else if (step.type === "click") {
-        await page.click(step.selector, { timeout: 5e3 });
-      } else if (step.type === "input") {
-        const value = step.id === targetStep.id ? payloadValue : step.value;
-        await page.fill(step.selector, value, { timeout: 5e3 });
-      } else if (step.type === "keypress") {
-        const modifiers = step.modifiers ?? [];
-        for (const mod of modifiers) {
-          await page.keyboard.down(mod);
-        }
-        await page.keyboard.press(step.key);
-        for (const mod of modifiers.reverse()) {
-          await page.keyboard.up(mod);
+      try {
+        if (step.type === "navigate") {
+          await page.goto(step.url, { waitUntil: "domcontentloaded" });
+        } else if (step.type === "click") {
+          await page.click(step.selector, { timeout: 5e3 });
+        } else if (step.type === "input") {
+          const value = step.id === targetStep.id ? payloadValue : step.value;
+          await page.fill(step.selector, value, { timeout: 5e3 });
+        } else if (step.type === "keypress") {
+          const modifiers = step.modifiers ?? [];
+          for (const mod of modifiers) {
+            await page.keyboard.down(
+              mod
+            );
+          }
+          await page.keyboard.press(step.key);
+          for (const mod of modifiers.reverse()) {
+            await page.keyboard.up(mod);
+          }
         }
+      } catch {
       }
       if (step.id === targetStep.id) {
-        const finding = await _Runner.checkForVulnerability(
-          page,
-          targetStep,
-          payloadName,
-          payloadValue
-        );
-        if (finding) {
-          return finding;
-        }
+        await page.waitForTimeout(100);
+        break;
       }
     }
-    return void 0;
   }
-  static async checkForVulnerability(page, step, payloadName, payloadValue) {
-    const payload = BUILTIN_PAYLOADS[payloadName];
-    if (!payload) return void 0;
+  /**
+   * Basic reflection check - fallback when no detection plugin is loaded
+   */
+  static async checkReflection(page, step, payloadSet, payloadValue) {
     const content = await page.content();
-    for (const pattern of payload.detectPatterns) {
+    for (const pattern of payloadSet.detectPatterns) {
       if (pattern.test(content)) {
         return {
-          type: payload.category,
-          severity: payload.category === "xss" ? "high" : "critical",
-          title: `${payload.category.toUpperCase()} vulnerability detected`,
-          description: `Payload was reflected in page content`,
+          type: payloadSet.category,
+          severity: _Runner.getSeverity(payloadSet.category),
+          title: `${payloadSet.category.toUpperCase()} vulnerability detected`,
+          description: `Payload pattern was reflected in page content`,
           stepId: step.id,
           payload: payloadValue,
           url: page.url(),
-          evidence: content.match(pattern)?.[0]
+          evidence: content.match(pattern)?.[0]?.slice(0, 200)
         };
       }
     }
     if (content.includes(payloadValue)) {
       return {
-        type: payload.category,
+        type: payloadSet.category,
         severity: "medium",
-        title: `Potential ${payload.category.toUpperCase()} - payload reflection`,
+        title: `Potential ${payloadSet.category.toUpperCase()} - payload reflection`,
         description: `Payload was reflected in page without encoding`,
         stepId: step.id,
         payload: payloadValue,
@@ -702,23 +1282,44 @@ var Runner = class _Runner {
     }
     return void 0;
   }
+  /**
+   * Determine severity based on vulnerability category
+   */
+  static getSeverity(category) {
+    switch (category) {
+      case "sqli":
+      case "command-injection":
+      case "xxe":
+        return "critical";
+      case "xss":
+      case "ssrf":
+      case "path-traversal":
+        return "high";
+      case "open-redirect":
+        return "medium";
+      default:
+        return "medium";
+    }
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  BUILTIN_PAYLOADS,
   BrowserNotFoundError,
+  DRIVER_API_VERSION,
+  DriverManager,
+  PLUGIN_API_VERSION,
+  PluginManager,
   Recorder,
   Runner,
   SessionSchema,
   StepSchema,
   checkBrowsers,
   createSession,
-  getPayload,
-  getPayloadNames,
-  getPayloadsByCategory,
+  driverManager,
   installBrowsers,
   launchBrowser,
   parseSession,
+  pluginManager,
   serializeSession
 });
 //# sourceMappingURL=index.cjs.map