@codepress/codepress-engine 0.6.0 → 0.7.0

package/README.md

@@ -20,24 +20,48 @@ TypeScript-powered instrumentation for the CodePress visual editor. The package
 npm install @codepress/codepress-engine
 ```
 
-## SWC plugin (Next.js) usage
+### Next.js usage
 
 ```js
-// next.config.mjs (Next.js 14/15)
-import { createSWCPlugin } from "@codepress/codepress-engine/swc";
+// next.config.js
+const createSWCPlugin = require("@codepress/codepress-engine/swc");
+const CodePressWebpackPlugin = require("@codepress/codepress-engine/webpack-plugin");
 
-const nextConfig = {
+module.exports = {
+  // SWC plugin for code transformation (existing)
   experimental: {
-    swcPlugins: [
-      // Auto-detects repo/branch; no options required
-      createSWCPlugin(),
-    ],
+    swcPlugins: [createSWCPlugin()],
   },
-};
 
-export default nextConfig;
+  // Webpack plugin for production module mapping (new)
+  webpack: (config, { isServer, dev }) => {
+    config.plugins.push(new CodePressWebpackPlugin({ isServer, dev }));
+    return config;
+  },
+};
 ```
 
+### How it works
+
+The plugin:
+
+1. Automatically skips server builds (`isServer: true`) and dev builds (`dev: true`)
+2. Runs during webpack compilation for production client builds
+3. Builds a mapping: `{ 33: "react", 92: "react-dom", ... }`
+4. Injects `window.__CP_MODULE_MAP__` into the main bundle
+5. Enables O(1) module resolution instead of scanning all modules
+
+### Bundle size impact
+
+- Typical app (1000 modules): +3-4KB gzipped
+- Large app (3000 modules): +8-10KB gzipped
+
+### When to use
+
+- **Required**: Production builds where you need HMR to work
+- **Optional**: Development (already has named module IDs)
+- **Alternative**: Set `moduleIds: 'named'` in webpack config (larger bundle, exposes file structure)
+
 Note: When using ESM (`next.config.mjs`), prefer the named import above due to CJS interop. For CommonJS configs you can use:
 
 ```js
@@ -76,12 +100,13 @@ Optional options for the Babel plugin (all are optional; omit to use auto-detect
 
 Entry points exposed by the package:
 
-| Export                               | Description                        |
-| ------------------------------------ | ---------------------------------- |
-| `@codepress/codepress-engine/babel`  | Compiled Babel plugin (CommonJS)   |
-| `@codepress/codepress-engine/swc`    | SWC plugin factory & WASM helpers  |
-| `@codepress/codepress-engine/server` | Fastify development server factory |
-| `@codepress/codepress-engine/cli`    | CLI used by the `codepress` binary |
+| Export                                       | Description                              |
+| -------------------------------------------- | ---------------------------------------- |
+| `@codepress/codepress-engine/babel`          | Compiled Babel plugin (CommonJS)         |
+| `@codepress/codepress-engine/swc`            | SWC plugin factory & WASM helpers        |
+| `@codepress/codepress-engine/webpack-plugin` | Webpack plugin for production module map |
+| `@codepress/codepress-engine/server`         | Fastify development server factory       |
+| `@codepress/codepress-engine/cli`            | CLI used by the `codepress` binary       |
 
 ---
 
@@ -184,6 +209,7 @@ The helper automatically selects the correct WASM binary based on detected Next.
 ## Additional references
 
 - `INSTALL.md` – linking the package locally & publishing guidance
+- `MODULE_MAP_INTEGRATION.md` – detailed guide for webpack plugin integration and troubleshooting
 - `scripts/build-swc.mjs` – rebuild the WASM binaries (requires Rust toolchain)
 - `tests/` – examples of mocking git, fetch, and file IO when validating the plugin
 

package/dist/webpack-plugin.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Webpack plugin that injects a module ID → name mapping for CodePress HMR
+ *
+ * This plugin runs during webpack compilation and builds a mapping from numeric
+ * module IDs (used in production) to human-readable module names. The mapping
+ * is injected into the main bundle as window.__CP_MODULE_MAP__.
+ *
+ * @example
+ * // next.config.js
+ * const CodePressWebpackPlugin = require('@codepress/codepress-engine/webpack-plugin');
+ *
+ * module.exports = {
+ *   webpack: (config, { isServer, dev }) => {
+ *     config.plugins.push(new CodePressWebpackPlugin({ isServer, dev }));
+ *     return config;
+ *   }
+ * };
+ */
+import type { Compiler } from 'webpack';
+export interface CodePressWebpackPluginOptions {
+    /**
+     * Whether this is a server-side build (Next.js specific)
+     * Plugin will skip if true
+     */
+    isServer?: boolean;
+    /**
+     * Whether this is a development build
+     * Plugin will skip if true (dev already has named IDs)
+     */
+    dev?: boolean;
+}
+export default class CodePressWebpackPlugin {
+    /**
+     * The name of the plugin
+     */
+    readonly name = "CodePressWebpackPlugin";
+    private readonly options;
+    /**
+     * @param options - Plugin options for conditional execution
+     */
+    constructor(options?: CodePressWebpackPluginOptions);
+    /**
+     * Apply the plugin to the webpack compiler
+     */
+    apply(compiler: Compiler): void;
+    /**
+     * Process compilation assets and inject module map
+     */
+    private processAssets;
+    /**
+     * Build a mapping of module IDs to normalized paths
+     */
+    private buildModuleMap;
+    /**
+     * Normalize a module path to a human-readable format
+     *
+     * @param resourcePath - The absolute path to the module
+     * @param context - The webpack context (project root)
+     * @returns Normalized path or null if path should be excluded
+     */
+    private normalizePath;
+    /**
+     * Generate the inline script that injects the module map
+     */
+    private generateMapScript;
+    /**
+     * Find the main bundle and inject the map script
+     *
+     * @returns true if injection succeeded, false otherwise
+     */
+    private injectIntoMainBundle;
+}
+export { CodePressWebpackPlugin };

package/dist/webpack-plugin.js

@@ -0,0 +1,172 @@
+"use strict";
+/**
+ * Webpack plugin that injects a module ID → name mapping for CodePress HMR
+ *
+ * This plugin runs during webpack compilation and builds a mapping from numeric
+ * module IDs (used in production) to human-readable module names. The mapping
+ * is injected into the main bundle as window.__CP_MODULE_MAP__.
+ *
+ * @example
+ * // next.config.js
+ * const CodePressWebpackPlugin = require('@codepress/codepress-engine/webpack-plugin');
+ *
+ * module.exports = {
+ *   webpack: (config, { isServer, dev }) => {
+ *     config.plugins.push(new CodePressWebpackPlugin({ isServer, dev }));
+ *     return config;
+ *   }
+ * };
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CodePressWebpackPlugin = void 0;
+class CodePressWebpackPlugin {
+    /**
+     * @param options - Plugin options for conditional execution
+     */
+    constructor(options = {}) {
+        /**
+         * The name of the plugin
+         */
+        this.name = 'CodePressWebpackPlugin';
+        this.options = options;
+    }
+    /**
+     * Apply the plugin to the webpack compiler
+     */
+    apply(compiler) {
+        // Skip if this is a server build or dev build
+        if (this.options.isServer) {
+            console.log('[CodePress] Skipping module map (server-side build)');
+            return;
+        }
+        if (this.options.dev) {
+            console.log('[CodePress] Skipping module map (dev build has named IDs)');
+            return;
+        }
+        compiler.hooks.thisCompilation.tap(this.name, (compilation) => {
+            compilation.hooks.processAssets.tap({
+                name: this.name,
+                // Run during the ADDITIONS stage to ensure all assets are present
+                stage: compilation.constructor.PROCESS_ASSETS_STAGE_ADDITIONS,
+            }, () => {
+                this.processAssets(compilation, compiler);
+            });
+        });
+    }
+    /**
+     * Process compilation assets and inject module map
+     */
+    processAssets(compilation, compiler) {
+        const moduleMap = this.buildModuleMap(compilation, compiler);
+        if (Object.keys(moduleMap).length === 0) {
+            console.warn('[CodePress] No modules found to map');
+            return;
+        }
+        console.log('[CodePress] Built module map with', Object.keys(moduleMap).length, 'entries');
+        const mapScript = this.generateMapScript(moduleMap);
+        const injected = this.injectIntoMainBundle(compilation, mapScript);
+        if (!injected) {
+            console.warn('[CodePress] Could not find main bundle to inject module map');
+        }
+    }
+    /**
+     * Build a mapping of module IDs to normalized paths
+     */
+    buildModuleMap(compilation, compiler) {
+        const moduleMap = {};
+        compilation.modules.forEach((module) => {
+            if (!module.id) {
+                return;
+            }
+            // Type assertion: webpack modules can have a resource property
+            const moduleWithResource = module;
+            if (!moduleWithResource.resource) {
+                return;
+            }
+            const id = String(module.id);
+            const normalizedPath = this.normalizePath(moduleWithResource.resource, compiler.context);
+            if (normalizedPath) {
+                moduleMap[id] = normalizedPath;
+            }
+        });
+        return moduleMap;
+    }
+    /**
+     * Normalize a module path to a human-readable format
+     *
+     * @param resourcePath - The absolute path to the module
+     * @param context - The webpack context (project root)
+     * @returns Normalized path or null if path should be excluded
+     */
+    normalizePath(resourcePath, context) {
+        let path = resourcePath;
+        // Handle node_modules
+        if (path.includes('node_modules')) {
+            // Extract package name (handles scoped packages like @foo/bar)
+            const packageMatch = path.match(/node_modules\/(@[^/]+\/[^/]+|[^/]+)/);
+            if (!packageMatch) {
+                return null;
+            }
+            const packageName = packageMatch[1];
+            // Extract subpath within the package (e.g., react/jsx-runtime)
+            const subPathMatch = path.match(/node_modules\/[^/]+(?:\/[^/]+)?\/(.+)/);
+            if (subPathMatch && subPathMatch[1]) {
+                const subPath = subPathMatch[1]
+                    .replace(/\\/g, '/')
+                    .replace(/\.(jsx?|tsx?|mjs|cjs)$/, '');
+                return `${packageName}/${subPath}`;
+            }
+            return packageName;
+        }
+        // Handle app code - make relative to context
+        path = path
+            .replace(context, '.')
+            .replace(/\\/g, '/') // Normalize Windows paths
+            .replace(/\.(jsx?|tsx?|mjs|cjs)$/, ''); // Remove extension
+        return path;
+    }
+    /**
+     * Generate the inline script that injects the module map
+     */
+    generateMapScript(moduleMap) {
+        const json = JSON.stringify(moduleMap);
+        return `(function(){if(typeof window!=="undefined"){window.__CP_MODULE_MAP__=${json};console.log("[CodePress] Loaded module map with",Object.keys(window.__CP_MODULE_MAP__).length,"entries");}})();`;
+    }
+    /**
+     * Find the main bundle and inject the map script
+     *
+     * @returns true if injection succeeded, false otherwise
+     */
+    injectIntoMainBundle(compilation, mapScript) {
+        // Find the main client bundle
+        // Matches patterns like: main-abc123.js, static/chunks/main-abc123.js
+        const mainAsset = compilation
+            .getAssets()
+            .find((asset) => asset.name.match(/^(static\/chunks\/main-|main-)[a-f0-9]+\.js$/));
+        if (!mainAsset) {
+            return false;
+        }
+        const { name } = mainAsset;
+        const source = mainAsset.source;
+        const originalSource = source.source();
+        const originalSourceStr = typeof originalSource === 'string'
+            ? originalSource
+            : Buffer.isBuffer(originalSource)
+                ? originalSource.toString('utf-8')
+                : String(originalSource);
+        // Update the asset with the prepended map script
+        compilation.updateAsset(name, {
+            source: () => mapScript + '\n' + originalSourceStr,
+            size: () => mapScript.length + originalSourceStr.length,
+        });
+        console.log('[CodePress] Injected module map into', name);
+        return true;
+    }
+}
+exports.default = CodePressWebpackPlugin;
+exports.CodePressWebpackPlugin = CodePressWebpackPlugin;
+// CommonJS compatibility
+module.exports = CodePressWebpackPlugin;
+module.exports.CodePressWebpackPlugin = CodePressWebpackPlugin;
+module.exports.default = CodePressWebpackPlugin;
+//# sourceMappingURL=webpack-plugin.js.map

package/dist/webpack-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webpack-plugin.js","sourceRoot":"","sources":["../src/webpack-plugin.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AA2BH,MAAqB,sBAAsB;IAQzC;;OAEG;IACH,YAAY,UAAyC,EAAE;QAVvD;;WAEG;QACa,SAAI,GAAG,wBAAwB,CAAC;QAQ9C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED;;OAEG;IACI,KAAK,CAAC,QAAkB;QAC7B,8CAA8C;QAC9C,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;YAC1B,OAAO,CAAC,GAAG,CAAC,qDAAqD,CAAC,CAAC;YACnE,OAAO;QACT,CAAC;QAED,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;YACrB,OAAO,CAAC,GAAG,CAAC,2DAA2D,CAAC,CAAC;YACzE,OAAO;QACT,CAAC;QAED,QAAQ,CAAC,KAAK,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,WAAwB,EAAE,EAAE;YACzE,WAAW,CAAC,KAAK,CAAC,aAAa,CAAC,GAAG,CACjC;gBACE,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,kEAAkE;gBAClE,KAAK,EAAG,WAAW,CAAC,WAAkC,CAAC,8BAA8B;aACtF,EACD,GAAG,EAAE;gBACH,IAAI,CAAC,aAAa,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;YAC5C,CAAC,CACF,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACK,aAAa,CAAC,WAAwB,EAAE,QAAkB;QAChE,MAAM,SAAS,GAAG,IAAI,CAAC,cAAc,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;QAE7D,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxC,OAAO,CAAC,IAAI,CAAC,qCAAqC,CAAC,CAAC;YACpD,OAAO;QACT,CAAC;QAED,OAAO,CAAC,GAAG,CACT,mCAAmC,EACnC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,EAC7B,SAAS,CACV,CAAC;QAEF,MAAM,SAAS,GAAG,IAAI,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;QACpD,MAAM,QAAQ,GAAG,IAAI,CAAC,oBAAoB,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;QAEnE,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,OAAO,CAAC,IAAI,CAAC,6DAA6D,CAAC,CAAC;QAC9E,CAAC;IACH,CAAC;IAED;;OAEG;IACK,cAAc,CAAC,WAAwB,EAAE,QAAkB;QACjE,MAAM,SAAS,GAAc,EAAE,CAAC;QAEhC,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,MAAqB,EAAE,EAAE;YACpD,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;gBACf,OAAO;YACT,CAAC;YAED,+DAA+D;YAC/D,MAAM,kBAAkB,GAAG,MAA+C,CAAC;YAC3E,IAAI,CAAC,kBAAkB,CAAC,QAAQ,EAAE,CAAC;gBACjC,OAAO;YACT,CAAC;YAED,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YAC7B,MAAM,cAAc,GAAG,IAAI,CAAC,aAAa,CAAC,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;YAEzF,IAAI,cAAc,EAAE,CAAC;gBACnB,SAAS,CAAC,EAAE,CAAC,GAAG,cAAc,CAAC;YACjC,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;;;;;OAMG;IACK,aAAa,CAAC,YAAoB,EAAE,OAAe;QACzD,IAAI,IAAI,GAAG,YAAY,CAAC;QAExB,sBAAsB;QACtB,IAAI,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;YAClC,+DAA+D;YAC/D,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,qCAAqC,CAAC,CAAC;YACvE,IAAI,CAAC,YAAY,EAAE,CAAC;gBAClB,OAAO,IAAI,CAAC;YACd,CAAC;YAED,MAAM,WAAW,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;YAEpC,+DAA+D;YAC/D,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,uCAAuC,CAAC,CAAC;YACzE,IAAI,YAAY,IAAI,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;gBACpC,MAAM,OAAO,GAAG,YAAY,CAAC,CAAC,CAAC;qBAC5B,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;qBACnB,OAAO,CAAC,wBAAwB,EAAE,EAAE,CAAC,CAAC;gBACzC,OAAO,GAAG,WAAW,IAAI,OAAO,EAAE,CAAC;YACrC,CAAC;YAED,OAAO,WAAW,CAAC;QACrB,CAAC;QAED,6CAA6C;QAC7C,IAAI,GAAG,IAAI;aACR,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;aACrB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,0BAA0B;aAC9C,OAAO,CAAC,wBAAwB,EAAE,EAAE,CAAC,CAAC,CAAC,mBAAmB;QAE7D,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACK,iBAAiB,CAAC,SAAoB;QAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QACvC,OAAO,wEAAwE,IAAI,kHAAkH,CAAC;IACxM,CAAC;IAED;;;;OAIG;IACK,oBAAoB,CAAC,WAAwB,EAAE,SAAiB;QACtE,8BAA8B;QAC9B,sEAAsE;QACtE,MAAM,SAAS,GAAG,WAAW;aAC1B,SAAS,EAAE;aACX,IAAI,CAAC,CAAC,KAAY,EAAE,EAAE,CACrB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,8CAA8C,CAAC,CACjE,CAAC;QAEJ,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,OAAO,KAAK,CAAC;QACf,CAAC;QAED,MAAM,EAAE,IAAI,EAAE,GAAG,SAAS,CAAC;QAC3B,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC;QAChC,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;QACvC,MAAM,iBAAiB,GACrB,OAAO,cAAc,KAAK,QAAQ;YAChC,CAAC,CAAC,cAAc;YAChB,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAC;gBAC/B,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAClC,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;QAE/B,iDAAiD;QACjD,WAAW,CAAC,WAAW,CAAC,IAAI,EAAE;YAC5B,MAAM,EAAE,GAAG,EAAE,CAAC,SAAS,GAAG,IAAI,GAAG,iBAAiB;YAClD,IAAI,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,GAAG,iBAAiB,CAAC,MAAM;SACtC,CAAC,CAAC;QAErB,OAAO,CAAC,GAAG,CAAC,sCAAsC,EAAE,IAAI,CAAC,CAAC;QAC1D,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAvLD,yCAuLC;AAGQ,wDAAsB;AAE/B,yBAAyB;AACzB,MAAM,CAAC,OAAO,GAAG,sBAAsB,CAAC;AACxC,MAAM,CAAC,OAAO,CAAC,sBAAsB,GAAG,sBAAsB,CAAC;AAC/D,MAAM,CAAC,OAAO,CAAC,OAAO,GAAG,sBAAsB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codepress/codepress-engine",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "packageManager": "pnpm@10.22.0",
   "description": "CodePress engine - Babel and SWC plug-ins",
   "main": "./dist/index.js",
@@ -36,6 +36,11 @@
       "require": "./dist/esbuild-plugin.js",
       "default": "./dist/esbuild-plugin.js"
     },
+    "./webpack-plugin": {
+      "types": "./dist/webpack-plugin.d.ts",
+      "require": "./dist/webpack-plugin.js",
+      "default": "./dist/webpack-plugin.js"
+    },
     "./swc/wasm": "./swc/codepress_engine.v42.wasm",
     "./swc/wasm-v42": "./swc/codepress_engine.v42.wasm",
     "./swc/wasm-v26": "./swc/codepress_engine.v26.wasm",
@@ -101,6 +106,7 @@
     "@types/jest": "^30.0.0",
     "@types/node": "^22.9.0",
     "@types/node-fetch": "^2.6.11",
+    "@types/webpack": "^5.28.5",
     "esbuild": "^0.24.0",
     "babel-jest": "^30.2.0",
     "eslint": "^9.37.0",