@kohi9noor/hotloop 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kohinoor nimes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli.js

@@ -0,0 +1,556 @@
+#!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/logger.ts
+var timestamp, logger;
+var init_logger = __esm({
+  "src/logger.ts"() {
+    timestamp = () => (/* @__PURE__ */ new Date()).toLocaleTimeString();
+    logger = {
+      info: (msg) => {
+        console.log(
+          `\x1B[36m[hotloop]\x1B[0m \x1B[90m${timestamp()}\x1B[0m ${msg}`
+        );
+      },
+      success: (msg) => {
+        console.log(
+          `\x1B[32m[hotloop]\x1B[0m \x1B[90m${timestamp()}\x1B[0m ${msg}`
+        );
+      },
+      warn: (msg) => {
+        console.warn(
+          `\x1B[33m[hotloop]\x1B[0m \x1B[90m${timestamp()}\x1B[0m ${msg}`
+        );
+      },
+      error: (msg) => {
+        console.error(
+          `\x1B[31m[hotloop]\x1B[0m \x1B[90m${timestamp()}\x1B[0m ${msg}`
+        );
+      }
+    };
+  }
+});
+
+// src/server.ts
+var server_exports = {};
+__export(server_exports, {
+  HmrServer: () => HmrServer
+});
+import { WebSocketServer, WebSocket } from "ws";
+var HmrServer;
+var init_server = __esm({
+  "src/server.ts"() {
+    init_logger();
+    HmrServer = class {
+      wss;
+      clients = /* @__PURE__ */ new Set();
+      constructor(port) {
+        this.wss = new WebSocketServer({ port }, () => {
+          logger.info(`HMR Server running on ws://localhost:${port}`);
+        });
+        this.wss.on("connection", (ws) => {
+          this.clients.add(ws);
+          ws.on("close", () => {
+            this.clients.delete(ws);
+          });
+        });
+      }
+      broadcast(message) {
+        const data = JSON.stringify(message);
+        this.clients.forEach((client) => {
+          if (client.readyState === WebSocket.OPEN) {
+            client.send(data);
+          }
+        });
+      }
+      reload() {
+        this.broadcast({ type: "reload" });
+      }
+      close() {
+        this.wss.close();
+      }
+    };
+  }
+});
+
+// src/builder.ts
+var builder_exports = {};
+__export(builder_exports, {
+  ExtensionBuilder: () => ExtensionBuilder
+});
+import * as esbuild from "esbuild";
+import * as fs from "fs/promises";
+import * as path from "path";
+var ExtensionBuilder;
+var init_builder = __esm({
+  "src/builder.ts"() {
+    init_logger();
+    ExtensionBuilder = class {
+      constructor(cwd = process.cwd()) {
+        this.cwd = cwd;
+      }
+      async build(entries) {
+        const start = Date.now();
+        try {
+          logger.info(`Building ${entries.length} entry(ies)...`);
+          for (const entry of entries) {
+            const inputPath = path.join(this.cwd, entry.input);
+            const outputPath = path.join(this.cwd, entry.output);
+            const outputDir = path.dirname(outputPath);
+            await fs.mkdir(outputDir, { recursive: true });
+            await esbuild.build({
+              entryPoints: [inputPath],
+              bundle: true,
+              format: "iife",
+              target: "es2020",
+              outfile: outputPath,
+              sourcemap: false,
+              logLevel: "silent"
+            });
+            logger.success(`${entry.input} \u2192 ${entry.output}`);
+          }
+          const elapsed = Date.now() - start;
+          logger.success(
+            `Compilation complete (${entries.length} files) in ${elapsed}ms`
+          );
+        } catch (error) {
+          logger.error(`Build failed: ${error}`);
+          throw error;
+        }
+      }
+      async copy(files) {
+        for (const { src, dest } of files) {
+          const srcPath = path.join(this.cwd, src);
+          const destPath = path.join(this.cwd, dest);
+          const destDir = path.dirname(destPath);
+          await fs.mkdir(destDir, { recursive: true });
+          await fs.copyFile(srcPath, destPath);
+        }
+      }
+      async writeManifest(options) {
+        const srcPath = path.join(this.cwd, options.src);
+        const destPath = path.join(this.cwd, options.dest);
+        const destDir = path.dirname(destPath);
+        const raw = await fs.readFile(srcPath, "utf-8");
+        const manifest = JSON.parse(raw);
+        if (options.injectHmr) {
+          const hmrScript = options.hmrScript || "content/hmr.js";
+          const hmrMatches = options.hmrMatches || ["<all_urls>"];
+          const hmrRunAt = options.hmrRunAt || "document_start";
+          const existing = Array.isArray(manifest.content_scripts) ? manifest.content_scripts : [];
+          const alreadyInjected = existing.some((entry) => {
+            const scripts = entry.js || [];
+            return Array.isArray(scripts) && scripts.includes(hmrScript);
+          });
+          if (!alreadyInjected) {
+            existing.push({
+              matches: hmrMatches,
+              js: [hmrScript],
+              run_at: hmrRunAt
+            });
+          }
+          manifest.content_scripts = existing;
+        }
+        await fs.mkdir(destDir, { recursive: true });
+        await fs.writeFile(destPath, JSON.stringify(manifest, null, 2), "utf-8");
+      }
+    };
+  }
+});
+
+// src/watcher.ts
+var watcher_exports = {};
+__export(watcher_exports, {
+  FileWatcher: () => FileWatcher
+});
+import * as fs2 from "fs";
+var FileWatcher;
+var init_watcher = __esm({
+  "src/watcher.ts"() {
+    init_logger();
+    FileWatcher = class {
+      constructor(watchDir, onChange) {
+        this.watchDir = watchDir;
+        this.onChange = onChange;
+      }
+      watchers = [];
+      debounceTimer = null;
+      debounceDelay = 300;
+      start() {
+        const watch2 = (dir) => {
+          const watcher = fs2.watch(dir, { recursive: true }, async (_, file) => {
+            if (!file) return;
+            if (String(file).includes("node_modules")) return;
+            if (String(file).includes("dist")) return;
+            if (this.debounceTimer) clearTimeout(this.debounceTimer);
+            this.debounceTimer = setTimeout(async () => {
+              try {
+                await this.onChange();
+              } catch (error) {
+                logger.error(`Build error: ${error}`);
+              }
+            }, this.debounceDelay);
+          });
+          this.watchers.push(watcher);
+        };
+        watch2(this.watchDir);
+        logger.info(`Watching ${this.watchDir} for changes`);
+      }
+      stop() {
+        this.watchers.forEach((w) => w.close());
+        if (this.debounceTimer) clearTimeout(this.debounceTimer);
+      }
+    };
+  }
+});
+
+// src/config.ts
+var config_exports = {};
+__export(config_exports, {
+  loadConfig: () => loadConfig,
+  validateConfig: () => validateConfig
+});
+import * as path2 from "path";
+import { pathToFileURL } from "url";
+async function loadConfig(cwd) {
+  const configPath = path2.join(cwd, "hotloop.config.js");
+  const configUrl = pathToFileURL(configPath).href;
+  try {
+    const module = await import(configUrl);
+    return module.default;
+  } catch (error) {
+    throw new Error(
+      `Failed to load hotloop.config.js: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+function validateConfig(config) {
+  if (!config.entries || config.entries.length === 0) {
+    throw new Error("No entries configured. Provide at least one entry point.");
+  }
+  config.entries.forEach((entry) => {
+    if (!entry.input || !entry.output) {
+      throw new Error("Each entry must have input and output properties.");
+    }
+  });
+}
+var init_config = __esm({
+  "src/config.ts"() {
+  }
+});
+
+// src/index.ts
+init_logger();
+init_server();
+init_builder();
+init_watcher();
+init_config();
+async function runBuild(cwd, options) {
+  const { loadConfig: loadConfig2, validateConfig: validateConfig2 } = await Promise.resolve().then(() => (init_config(), config_exports));
+  const { HmrServer: HmrServer2 } = await Promise.resolve().then(() => (init_server(), server_exports));
+  const { ExtensionBuilder: ExtensionBuilder2 } = await Promise.resolve().then(() => (init_builder(), builder_exports));
+  const { FileWatcher: FileWatcher2 } = await Promise.resolve().then(() => (init_watcher(), watcher_exports));
+  const config = await loadConfig2(cwd);
+  validateConfig2(config);
+  if (config.manifest && options?.injectHmr === false) {
+    config.manifest = { ...config.manifest, injectHmr: false };
+  }
+  const outDir = config.outDir || "dist";
+  const buildOutDir = config.buildOutDir || outDir;
+  const replaceOutDir = (target) => {
+    const normalized = target.replace(/\\/g, "/");
+    const prefix = `${outDir.replace(/\\/g, "/")}/`;
+    if (normalized.startsWith(prefix)) {
+      return normalized.replace(prefix, `${buildOutDir}/`);
+    }
+    return target;
+  };
+  if (options?.watch === false && buildOutDir !== outDir) {
+    config.entries = config.entries.map((entry) => ({
+      ...entry,
+      output: replaceOutDir(entry.output)
+    }));
+    if (config.manifest) {
+      config.manifest = {
+        ...config.manifest,
+        dest: replaceOutDir(config.manifest.dest)
+      };
+    }
+    if (config.assets) {
+      config.assets = config.assets.map((asset) => ({
+        ...asset,
+        dest: replaceOutDir(asset.dest)
+      }));
+    }
+    if (config.copy) {
+      config.copy = config.copy.map((asset) => ({
+        ...asset,
+        dest: replaceOutDir(asset.dest)
+      }));
+    }
+  }
+  const port = config.port || 3e3;
+  const watchDir = config.watchDir || "src";
+  const server = options?.watch === false ? null : new HmrServer2(port);
+  const builder = new ExtensionBuilder2(cwd);
+  await builder.build(config.entries);
+  if (config.manifest) {
+    await builder.writeManifest(config.manifest);
+  }
+  if (config.assets) {
+    await builder.copy(config.assets);
+  }
+  if (config.copy) {
+    await builder.copy(config.copy);
+  }
+  if (options?.watch === false) {
+    return;
+  }
+  const watcher = new FileWatcher2(watchDir, async () => {
+    config.onBuildStart?.();
+    try {
+      await builder.build(config.entries);
+      if (config.manifest) {
+        await builder.writeManifest(config.manifest);
+      }
+      if (config.assets) {
+        await builder.copy(config.assets);
+      }
+      if (config.copy) {
+        await builder.copy(config.copy);
+      }
+      server?.reload();
+    } catch (error) {
+      logger.error(`Build failed: ${error}`);
+    }
+    config.onBuildEnd?.();
+  });
+  watcher.start();
+  process.on("SIGINT", () => {
+    logger.info("Shutting down");
+    watcher.stop();
+    server?.close();
+    process.exit(0);
+  });
+}
+async function startDevServer(cwd = process.cwd()) {
+  await runBuild(cwd, { watch: true, injectHmr: true });
+}
+async function buildOnce(cwd = process.cwd()) {
+  await runBuild(cwd, { watch: false, injectHmr: false });
+}
+
+// src/scaffold.ts
+init_logger();
+import * as fs3 from "fs/promises";
+import * as path3 from "path";
+async function scaffold(options) {
+  const { projectName: projectName2, targetDir } = options;
+  try {
+    logger.info(`Creating project: ${projectName2}`);
+    await fs3.mkdir(path3.join(targetDir, "src", "background"), {
+      recursive: true
+    });
+    await fs3.mkdir(path3.join(targetDir, "src", "content"), {
+      recursive: true
+    });
+    await fs3.mkdir(path3.join(targetDir, "src", "ui"), { recursive: true });
+    const manifest = {
+      manifest_version: 3,
+      name: projectName2,
+      version: "1.0.0",
+      description: "A Chrome extension built with Hotwire",
+      permissions: ["tabs"],
+      background: {
+        service_worker: "background/index.js"
+      },
+      action: {
+        default_popup: "ui/popup.html",
+        default_title: projectName2
+      }
+    };
+    await fs3.writeFile(
+      path3.join(targetDir, "src", "manifest.json"),
+      JSON.stringify(manifest, null, 2)
+    );
+    const backgroundScript = `console.log("Background script loaded");
+
+chrome.runtime.onInstalled.addListener(() => {
+  console.log("Extension installed");
+});
+`;
+    await fs3.writeFile(
+      path3.join(targetDir, "src", "background", "index.ts"),
+      backgroundScript
+    );
+    const popupHtml = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${projectName2}</title>
+  <link rel="stylesheet" href="popup.css">
+</head>
+<body>
+  <h1>${projectName2}</h1>
+  <p>Extension ready</p>
+  <script src="popup.js"></script>
+</body>
+</html>
+`;
+    await fs3.writeFile(
+      path3.join(targetDir, "src", "ui", "popup.html"),
+      popupHtml
+    );
+    const popupCss = `body {
+  width: 400px;
+  padding: 16px;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  background: #f5f5f5;
+}
+
+h1 {
+  margin: 0 0 12px 0;
+  font-size: 18px;
+  color: #333;
+}
+
+p {
+  margin: 0;
+  color: #666;
+  font-size: 14px;
+}
+`;
+    await fs3.writeFile(
+      path3.join(targetDir, "src", "ui", "popup.css"),
+      popupCss
+    );
+    const popupScript = `document.addEventListener("DOMContentLoaded", () => {
+  console.log("Popup loaded");
+});
+`;
+    await fs3.writeFile(
+      path3.join(targetDir, "src", "ui", "popup.ts"),
+      popupScript
+    );
+    const configFile = `export default {
+  port: 3000,
+  watchDir: "src",
+  outDir: "dist",
+  buildOutDir: "build",
+  entries: [
+    { input: "src/background/index.ts", output: "dist/background/index.js" },
+    { input: "src/ui/popup.ts", output: "dist/ui/popup.js" },
+  ],
+  manifest: {
+    src: "src/manifest.json",
+    dest: "dist/manifest.json",
+    injectHmr: true,
+    hmrScript: "content/hmr.js",
+    hmrMatches: ["<all_urls>"],
+    hmrRunAt: "document_start",
+  },
+  assets: [
+    { src: "src/ui/popup.html", dest: "dist/ui/popup.html" },
+    { src: "src/ui/popup.css", dest: "dist/ui/popup.css" },
+  ],
+};
+`;
+    await fs3.writeFile(path3.join(targetDir, "hotwire.config.js"), configFile);
+    const packageJson = {
+      name: projectName2,
+      version: "1.0.0",
+      description: `A Chrome extension: ${projectName2}`,
+      type: "module",
+      scripts: {
+        dev: "hotwire dev",
+        build: "hotwire build"
+      },
+      devDependencies: {
+        "@types/chrome": "^0.1.37",
+        typescript: "^5.9.3"
+      }
+    };
+    await fs3.writeFile(
+      path3.join(targetDir, "package.json"),
+      JSON.stringify(packageJson, null, 2)
+    );
+    const tsconfig = {
+      compilerOptions: {
+        target: "ES2020",
+        module: "ESNext",
+        lib: ["ES2020"],
+        skipLibCheck: true,
+        esModuleInterop: true,
+        resolveJsonModule: true,
+        strict: true
+      },
+      include: ["src"]
+    };
+    await fs3.writeFile(
+      path3.join(targetDir, "tsconfig.json"),
+      JSON.stringify(tsconfig, null, 2)
+    );
+    const gitignore = `node_modules/
+dist/
+build/
+*.log
+.DS_Store
+`;
+    await fs3.writeFile(path3.join(targetDir, ".gitignore"), gitignore);
+    logger.success(`Project created at ${targetDir}`);
+    logger.info("Next steps:");
+    logger.info(`  cd ${projectName2}`);
+    logger.info(`  npm install`);
+    logger.info(`  npm run dev`);
+  } catch (error) {
+    logger.error(`Scaffolding failed: ${error}`);
+    throw error;
+  }
+}
+
+// src/cli.ts
+init_logger();
+import * as path4 from "path";
+import * as fs4 from "fs/promises";
+var command = process.argv[2];
+var projectName = process.argv[3];
+if (command === "dev") {
+  logger.info("Starting Dev Server");
+  startDevServer(process.cwd());
+} else if (command === "build") {
+  logger.info("Building extension (no HMR)");
+  buildOnce(process.cwd());
+} else if (command === "init") {
+  if (!projectName) {
+    logger.error("Project name required: hotwire init <project-name>");
+    process.exit(1);
+  }
+  const targetDir = path4.join(process.cwd(), projectName);
+  fs4.mkdir(targetDir, { recursive: true }).then(() => scaffold({ projectName, targetDir })).catch((error) => {
+    logger.error(`Init failed: ${error}`);
+    process.exit(1);
+  });
+} else {
+  console.log(`
+  Hotloop - Hot Module Reloading for Chrome Extensions
+
+  Usage:
+    hotloop init <name>   Create a new project
+    hotloop dev           Start the dev server
+    hotloop build         Build once (no HMR)
+
+  Examples:
+    hotloop init my-extension
+    hotloop dev
+    hotloop build
+  `);
+}

package/dist/index.js

@@ -0,0 +1,357 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/logger.ts
+var timestamp, logger;
+var init_logger = __esm({
+  "src/logger.ts"() {
+    timestamp = () => (/* @__PURE__ */ new Date()).toLocaleTimeString();
+    logger = {
+      info: (msg) => {
+        console.log(
+          `\x1B[36m[hotloop]\x1B[0m \x1B[90m${timestamp()}\x1B[0m ${msg}`
+        );
+      },
+      success: (msg) => {
+        console.log(
+          `\x1B[32m[hotloop]\x1B[0m \x1B[90m${timestamp()}\x1B[0m ${msg}`
+        );
+      },
+      warn: (msg) => {
+        console.warn(
+          `\x1B[33m[hotloop]\x1B[0m \x1B[90m${timestamp()}\x1B[0m ${msg}`
+        );
+      },
+      error: (msg) => {
+        console.error(
+          `\x1B[31m[hotloop]\x1B[0m \x1B[90m${timestamp()}\x1B[0m ${msg}`
+        );
+      }
+    };
+  }
+});
+
+// src/server.ts
+var server_exports = {};
+__export(server_exports, {
+  HmrServer: () => HmrServer
+});
+import { WebSocketServer, WebSocket } from "ws";
+var HmrServer;
+var init_server = __esm({
+  "src/server.ts"() {
+    init_logger();
+    HmrServer = class {
+      wss;
+      clients = /* @__PURE__ */ new Set();
+      constructor(port) {
+        this.wss = new WebSocketServer({ port }, () => {
+          logger.info(`HMR Server running on ws://localhost:${port}`);
+        });
+        this.wss.on("connection", (ws) => {
+          this.clients.add(ws);
+          ws.on("close", () => {
+            this.clients.delete(ws);
+          });
+        });
+      }
+      broadcast(message) {
+        const data = JSON.stringify(message);
+        this.clients.forEach((client) => {
+          if (client.readyState === WebSocket.OPEN) {
+            client.send(data);
+          }
+        });
+      }
+      reload() {
+        this.broadcast({ type: "reload" });
+      }
+      close() {
+        this.wss.close();
+      }
+    };
+  }
+});
+
+// src/builder.ts
+var builder_exports = {};
+__export(builder_exports, {
+  ExtensionBuilder: () => ExtensionBuilder
+});
+import * as esbuild from "esbuild";
+import * as fs from "fs/promises";
+import * as path from "path";
+var ExtensionBuilder;
+var init_builder = __esm({
+  "src/builder.ts"() {
+    init_logger();
+    ExtensionBuilder = class {
+      constructor(cwd = process.cwd()) {
+        this.cwd = cwd;
+      }
+      async build(entries) {
+        const start = Date.now();
+        try {
+          logger.info(`Building ${entries.length} entry(ies)...`);
+          for (const entry of entries) {
+            const inputPath = path.join(this.cwd, entry.input);
+            const outputPath = path.join(this.cwd, entry.output);
+            const outputDir = path.dirname(outputPath);
+            await fs.mkdir(outputDir, { recursive: true });
+            await esbuild.build({
+              entryPoints: [inputPath],
+              bundle: true,
+              format: "iife",
+              target: "es2020",
+              outfile: outputPath,
+              sourcemap: false,
+              logLevel: "silent"
+            });
+            logger.success(`${entry.input} \u2192 ${entry.output}`);
+          }
+          const elapsed = Date.now() - start;
+          logger.success(
+            `Compilation complete (${entries.length} files) in ${elapsed}ms`
+          );
+        } catch (error) {
+          logger.error(`Build failed: ${error}`);
+          throw error;
+        }
+      }
+      async copy(files) {
+        for (const { src, dest } of files) {
+          const srcPath = path.join(this.cwd, src);
+          const destPath = path.join(this.cwd, dest);
+          const destDir = path.dirname(destPath);
+          await fs.mkdir(destDir, { recursive: true });
+          await fs.copyFile(srcPath, destPath);
+        }
+      }
+      async writeManifest(options) {
+        const srcPath = path.join(this.cwd, options.src);
+        const destPath = path.join(this.cwd, options.dest);
+        const destDir = path.dirname(destPath);
+        const raw = await fs.readFile(srcPath, "utf-8");
+        const manifest = JSON.parse(raw);
+        if (options.injectHmr) {
+          const hmrScript = options.hmrScript || "content/hmr.js";
+          const hmrMatches = options.hmrMatches || ["<all_urls>"];
+          const hmrRunAt = options.hmrRunAt || "document_start";
+          const existing = Array.isArray(manifest.content_scripts) ? manifest.content_scripts : [];
+          const alreadyInjected = existing.some((entry) => {
+            const scripts = entry.js || [];
+            return Array.isArray(scripts) && scripts.includes(hmrScript);
+          });
+          if (!alreadyInjected) {
+            existing.push({
+              matches: hmrMatches,
+              js: [hmrScript],
+              run_at: hmrRunAt
+            });
+          }
+          manifest.content_scripts = existing;
+        }
+        await fs.mkdir(destDir, { recursive: true });
+        await fs.writeFile(destPath, JSON.stringify(manifest, null, 2), "utf-8");
+      }
+    };
+  }
+});
+
+// src/watcher.ts
+var watcher_exports = {};
+__export(watcher_exports, {
+  FileWatcher: () => FileWatcher
+});
+import * as fs2 from "fs";
+var FileWatcher;
+var init_watcher = __esm({
+  "src/watcher.ts"() {
+    init_logger();
+    FileWatcher = class {
+      constructor(watchDir, onChange) {
+        this.watchDir = watchDir;
+        this.onChange = onChange;
+      }
+      watchers = [];
+      debounceTimer = null;
+      debounceDelay = 300;
+      start() {
+        const watch2 = (dir) => {
+          const watcher = fs2.watch(dir, { recursive: true }, async (_, file) => {
+            if (!file) return;
+            if (String(file).includes("node_modules")) return;
+            if (String(file).includes("dist")) return;
+            if (this.debounceTimer) clearTimeout(this.debounceTimer);
+            this.debounceTimer = setTimeout(async () => {
+              try {
+                await this.onChange();
+              } catch (error) {
+                logger.error(`Build error: ${error}`);
+              }
+            }, this.debounceDelay);
+          });
+          this.watchers.push(watcher);
+        };
+        watch2(this.watchDir);
+        logger.info(`Watching ${this.watchDir} for changes`);
+      }
+      stop() {
+        this.watchers.forEach((w) => w.close());
+        if (this.debounceTimer) clearTimeout(this.debounceTimer);
+      }
+    };
+  }
+});
+
+// src/config.ts
+var config_exports = {};
+__export(config_exports, {
+  loadConfig: () => loadConfig,
+  validateConfig: () => validateConfig
+});
+import * as path2 from "path";
+import { pathToFileURL } from "url";
+async function loadConfig(cwd) {
+  const configPath = path2.join(cwd, "hotloop.config.js");
+  const configUrl = pathToFileURL(configPath).href;
+  try {
+    const module = await import(configUrl);
+    return module.default;
+  } catch (error) {
+    throw new Error(
+      `Failed to load hotloop.config.js: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+function validateConfig(config) {
+  if (!config.entries || config.entries.length === 0) {
+    throw new Error("No entries configured. Provide at least one entry point.");
+  }
+  config.entries.forEach((entry) => {
+    if (!entry.input || !entry.output) {
+      throw new Error("Each entry must have input and output properties.");
+    }
+  });
+}
+var init_config = __esm({
+  "src/config.ts"() {
+  }
+});
+
+// src/index.ts
+init_logger();
+init_server();
+init_builder();
+init_watcher();
+init_config();
+async function runBuild(cwd, options) {
+  const { loadConfig: loadConfig2, validateConfig: validateConfig2 } = await Promise.resolve().then(() => (init_config(), config_exports));
+  const { HmrServer: HmrServer2 } = await Promise.resolve().then(() => (init_server(), server_exports));
+  const { ExtensionBuilder: ExtensionBuilder2 } = await Promise.resolve().then(() => (init_builder(), builder_exports));
+  const { FileWatcher: FileWatcher2 } = await Promise.resolve().then(() => (init_watcher(), watcher_exports));
+  const config = await loadConfig2(cwd);
+  validateConfig2(config);
+  if (config.manifest && options?.injectHmr === false) {
+    config.manifest = { ...config.manifest, injectHmr: false };
+  }
+  const outDir = config.outDir || "dist";
+  const buildOutDir = config.buildOutDir || outDir;
+  const replaceOutDir = (target) => {
+    const normalized = target.replace(/\\/g, "/");
+    const prefix = `${outDir.replace(/\\/g, "/")}/`;
+    if (normalized.startsWith(prefix)) {
+      return normalized.replace(prefix, `${buildOutDir}/`);
+    }
+    return target;
+  };
+  if (options?.watch === false && buildOutDir !== outDir) {
+    config.entries = config.entries.map((entry) => ({
+      ...entry,
+      output: replaceOutDir(entry.output)
+    }));
+    if (config.manifest) {
+      config.manifest = {
+        ...config.manifest,
+        dest: replaceOutDir(config.manifest.dest)
+      };
+    }
+    if (config.assets) {
+      config.assets = config.assets.map((asset) => ({
+        ...asset,
+        dest: replaceOutDir(asset.dest)
+      }));
+    }
+    if (config.copy) {
+      config.copy = config.copy.map((asset) => ({
+        ...asset,
+        dest: replaceOutDir(asset.dest)
+      }));
+    }
+  }
+  const port = config.port || 3e3;
+  const watchDir = config.watchDir || "src";
+  const server = options?.watch === false ? null : new HmrServer2(port);
+  const builder = new ExtensionBuilder2(cwd);
+  await builder.build(config.entries);
+  if (config.manifest) {
+    await builder.writeManifest(config.manifest);
+  }
+  if (config.assets) {
+    await builder.copy(config.assets);
+  }
+  if (config.copy) {
+    await builder.copy(config.copy);
+  }
+  if (options?.watch === false) {
+    return;
+  }
+  const watcher = new FileWatcher2(watchDir, async () => {
+    config.onBuildStart?.();
+    try {
+      await builder.build(config.entries);
+      if (config.manifest) {
+        await builder.writeManifest(config.manifest);
+      }
+      if (config.assets) {
+        await builder.copy(config.assets);
+      }
+      if (config.copy) {
+        await builder.copy(config.copy);
+      }
+      server?.reload();
+    } catch (error) {
+      logger.error(`Build failed: ${error}`);
+    }
+    config.onBuildEnd?.();
+  });
+  watcher.start();
+  process.on("SIGINT", () => {
+    logger.info("Shutting down");
+    watcher.stop();
+    server?.close();
+    process.exit(0);
+  });
+}
+async function startDevServer(cwd = process.cwd()) {
+  await runBuild(cwd, { watch: true, injectHmr: true });
+}
+async function buildOnce(cwd = process.cwd()) {
+  await runBuild(cwd, { watch: false, injectHmr: false });
+}
+export {
+  ExtensionBuilder,
+  FileWatcher,
+  HmrServer,
+  buildOnce,
+  loadConfig,
+  startDevServer,
+  validateConfig
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@kohi9noor/hotloop",
+  "version": "1.3.0",
+  "description": "Minimal, framework-free development tool for small-scale browser extensions. TypeScript, HMR, and Node module support—nothing else.",
+  "author": "kohi9noor",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "hotloop": "dist/cli.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kohi9noor/hotloop"
+  },
+  "keywords": [
+    "browser-extension",
+    "chrome-extension",
+    "hmr",
+    "hot-module-reloading",
+    "typescript",
+    "esbuild",
+    "development-tool"
+  ],
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --external:ws --external:esbuild --external:fs --external:fs/promises --external:path --external:child_process --external:url --outdir=dist && esbuild src/cli.ts --bundle --platform=node --format=esm --external:ws --external:esbuild --external:fs --external:fs/promises --external:path --external:child_process --external:url --outfile=dist/cli.js",
+    "prepare": "npm run build"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "ws": "^8.19.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.2",
+    "esbuild": "^0.27.3",
+    "typescript": "^5.9.3"
+  }
+}

package/readme.md

@@ -0,0 +1,187 @@
+# Hotloop
+
+Minimal development tooling for browser extensions.
+
+TypeScript. HMR. Node modules.  
+No frameworks. No plugin circus.
+
+---
+
+## Why Hotloop Exists
+
+Most extension tooling assumes you're building a mini web app.
+
+They integrate Vite pipelines, plugin systems, framework layers, and opinionated structures. That’s great for complex extensions with routing, heavy UI, or framework-driven architecture.
+
+But what if you're not?
+
+What if:
+
+- You're building a small extension with 2–5 focused features
+- You want clean architecture
+- You want TypeScript
+- You want fast rebuilds
+- You want node module support
+- But you **don’t** want React, Vue, or framework assumptions
+
+Hotloop is built for that.
+
+It gives you modern development essentials without pushing you into a frontend framework ecosystem.
+
+It doesn’t try to define your architecture.  
+It just improves your development loop.
+
+---
+
+## Philosophy
+
+Hotloop is built around one idea:
+
+You should be able to write vanilla extension code  
+with proper engineering discipline  
+without importing half the frontend world.
+
+You get:
+
+- TypeScript for safety
+- esbuild for speed
+- HMR for fast iteration
+- Node module support
+- A single config file
+- No framework lock-in
+
+That’s it.
+
+If you want routing systems, plugin ecosystems, or integrated framework support, tools like WXT or CRXJS are excellent choices.
+
+Hotloop intentionally stays smaller.
+
+---
+
+## Comparison
+
+| Feature               | Hotloop          | WXT                        | CRXJS                   |
+| --------------------- | ---------------- | -------------------------- | ----------------------- |
+| TypeScript Support    | ✅               | ✅                         | ✅                      |
+| Hot Module Reloading  | ✅               | ✅                         | ✅                      |
+| Node Module Support   | ✅               | ✅                         | ✅                      |
+| Build System          | esbuild          | Vite                       | Vite                    |
+| Framework Assumptions | ❌               | Optional                   | Optional                |
+| Plugin Ecosystem      | ❌               | ✅                         | ✅                      |
+| Config Complexity     | Minimal          | Moderate                   | Moderate                |
+| Best For              | Small extensions | Structured / scalable apps | Chrome-focused projects |
+
+Hotloop does less on purpose.
+
+---
+
+## Getting Started
+
+### Create a New Project
+
+Scaffold a new extension project using `npx`:
+
+```bash
+npx hotloop init my-extension
+cd my-extension
+npm install
+```
+
+Then start development:
+
+```bash
+npm run dev
+```
+
+### Install in an Existing Project
+
+Install as a dev dependency:
+
+```bash
+npm install --save-dev hotloop
+```
+
+Add scripts to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "dev": "hotloop dev",
+    "build": "hotloop build"
+  }
+}
+```
+
+Run:
+
+```bash
+npm run dev
+```
+
+Build for production:
+
+```bash
+npm run build
+```
+
+Load the `dist` directory as an unpacked extension.
+
+Configuration
+
+Create a hotloop.config.js in your project root:
+
+export default {
+entries: [
+{ input: "src/background/index.ts", output: "dist/background/index.js" },
+{ input: "src/content/index.ts", output: "dist/content/index.js" },
+{ input: "src/ui/popup.ts", output: "dist/ui/popup.js" },
+],
+
+manifest: {
+src: "src/manifest.json",
+dest: "dist/manifest.json",
+
+    // Injects HMR client only in development mode
+    hmrMatches: ["<all_urls>"],
+
+},
+
+copy: [
+{ src: "src/ui/popup.html", dest: "dist/ui/popup.html" },
+{ src: "src/ui/popup.css", dest: "dist/ui/popup.css" },
+],
+
+port: 8000,
+};
+
+That’s the entire configuration surface.
+
+No plugin arrays.
+No layered overrides.
+No framework presets.
+
+## Features
+
+**Entry Points** – Bundle background scripts, content scripts, and UI scripts independently.
+
+**Manifest Handling** – Copies and optionally injects development scripts during dev mode.
+
+**Hot Module Reloading** – WebSocket-based HMR improves iteration speed without full extension reload cycles.
+
+**Node Modules** – Import npm packages compatible with browser environments.
+
+**Fast Builds** – Powered by esbuild for near-instant rebuilds.
+
+## What Hotloop Is Not
+
+- Not a UI framework
+- Not a plugin platform
+- Not an opinionated architecture
+- Not a meta-framework
+
+It’s a dev loop optimizer for vanilla extensions.
+
+## License
+
+MIT
+