refactor(core): move report template out of core js output

Previously, core and report were tightly coupled at build time.

apps/report depends on @midscene/core because the report UI reuses core types, dump

structures, and helper logic. At the same time, the built core output needed

to inline the report HTML template.

This meant report had to build after core, but the final usable core output

still depended on report building first and writing HTML back into core dist.

The old flow scanned built core JS files, found magic strings such as

REPLACE_ME_WITH_REPORT_HTML, and replaced them with the full report HTML.

That flow was fragile and could repeatedly inject the template. Since report

HTML is large and apps/report may bundle an already-injected core dist, the

next report build could include the previous template inside the new template.

Writing that back into core again could cause recursive HTML growth.

This change separates responsibilities. apps/report now owns report template

generation and syncs apps/report/dist/index.html into core as a static asset:

packages/core/dist/report-template/index.html

@midscene/core no longer inlines the report template into its JS output and

no longer relies on magic string replacement. At runtime, core reads the

template from its own package asset when generating reports.

For bundled @midscene/core targets, static assets may not be included in the

final bundle. Those targets can inject the template through:

globalThis.__MIDSCENE_INTERNAL_REPORT_TEMPLATE_CONTENT__

Core reads this global first, before falling back to the local template file.

Internal bundle targets use a build plugin that replaces @midscene/core entries

with wrapper modules. The wrapper injects the report template first and then

re-exports the original core entry. This puts template injection into the

bundler module graph instead of rewriting final JS output.

Author: EAGzzyCSL

CONTRIBUTING.md

@@ -152,13 +152,13 @@ cd apps/playground && pnpm run dev
 cd apps/chrome-extension && pnpm run dev
 ```
 
-### `REPLACE_ME_WITH_REPORT_HTML` error in the report file
+### Missing report template errors
 
 `apps/report` is not standalone at runtime. Its built `index.html` template is
-injected back into `packages/core/dist` during build. If report UI changes do
-not show up, or you see `REPLACE_ME_WITH_REPORT_HTML` in the report file, the
-template injection is usually stale. Rebuild the entire workspace without Nx
-cache to fix it:
+synced into `packages/core/dist/report-template/index.html` during build. If
+report UI changes do not show up, or the runtime says the Midscene report
+template is missing, rebuild the entire workspace without Nx cache to refresh
+the synced template:
 
 ```sh
 # Rebuild the entire project without cache

apps/android-playground/package.json

@@ -15,6 +15,7 @@
     "react-dom": "18.3.1"
   },
   "devDependencies": {
+    "@midscene/report": "workspace:*",
     "@rsbuild/core": "^1.6.15",
     "@rsbuild/plugin-less": "^1.5.0",
     "@rsbuild/plugin-node-polyfill": "1.4.2",

apps/android-playground/rsbuild.config.ts

@@ -9,6 +9,7 @@ import { pluginWorkspaceDev } from 'rsbuild-plugin-workspace-dev';
 import { version as playgroundVersion } from '../../packages/playground/package.json';
 import {
   commonIgnoreWarnings,
+  createCoreReportTemplateReplacementPlugin,
   createPlaygroundCopyPlugin,
 } from '../../scripts/rsbuild-utils.ts';
 
@@ -63,6 +64,9 @@ export default defineConfig({
     pluginNodePolyfill(),
     pluginLess(),
     pluginSvgr(),
+    createCoreReportTemplateReplacementPlugin({
+      appDir: __dirname,
+    }),
     createPlaygroundCopyPlugin(
       path.join(__dirname, 'dist'),
       path.join(__dirname, '../../packages/android-playground/static'),

apps/chrome-extension/rsbuild.config.ts

@@ -7,7 +7,10 @@ import { pluginSvgr } from '@rsbuild/plugin-svgr';
 import { pluginTypeCheck } from '@rsbuild/plugin-type-check';
 import { pluginWorkspaceDev } from 'rsbuild-plugin-workspace-dev';
 import { version } from '../../packages/visualizer/package.json';
-import { commonIgnoreWarnings } from '../../scripts/rsbuild-utils.ts';
+import {
+  commonIgnoreWarnings,
+  createCoreReportTemplateReplacementPlugin,
+} from '../../scripts/rsbuild-utils.ts';
 
 export default defineConfig({
   tools: {
@@ -119,6 +122,9 @@ export default defineConfig({
     pluginNodePolyfill(),
     pluginLess(),
     pluginSvgr(),
+    createCoreReportTemplateReplacementPlugin({
+      appDir: __dirname,
+    }),
     pluginTypeCheck(),
     pluginWorkspaceDev({
       projects: {

apps/computer-playground/package.json

@@ -15,6 +15,7 @@
     "react-dom": "18.3.1"
   },
   "devDependencies": {
+    "@midscene/report": "workspace:*",
     "@rsbuild/core": "^1.6.15",
     "@rsbuild/plugin-less": "^1.5.0",
     "@rsbuild/plugin-node-polyfill": "1.4.2",

apps/computer-playground/rsbuild.config.ts

@@ -9,6 +9,7 @@ import { pluginWorkspaceDev } from 'rsbuild-plugin-workspace-dev';
 import { version as playgroundVersion } from '../../packages/playground/package.json';
 import {
   commonIgnoreWarnings,
+  createCoreReportTemplateReplacementPlugin,
   createPlaygroundCopyPlugin,
 } from '../../scripts/rsbuild-utils.ts';
 
@@ -63,6 +64,9 @@ export default defineConfig({
     pluginNodePolyfill(),
     pluginLess(),
     pluginSvgr(),
+    createCoreReportTemplateReplacementPlugin({
+      appDir: __dirname,
+    }),
     createPlaygroundCopyPlugin(
       path.join(__dirname, 'dist'),
       path.join(__dirname, '../../packages/computer-playground/static'),

apps/playground/package.json

@@ -18,6 +18,7 @@
     "react-dom": "18.3.1"
   },
   "devDependencies": {
+    "@midscene/report": "workspace:*",
     "@midscene/web": "workspace:*",
     "@rsbuild/core": "^1.6.15",
     "@rsbuild/plugin-less": "^1.5.0",

apps/playground/rsbuild.config.ts

@@ -9,6 +9,7 @@ import { pluginWorkspaceDev } from 'rsbuild-plugin-workspace-dev';
 import { version as playgroundVersion } from '../../packages/playground/package.json';
 import {
   commonIgnoreWarnings,
+  createCoreReportTemplateReplacementPlugin,
   createPlaygroundCopyPlugin,
 } from '../../scripts/rsbuild-utils.ts';
 
@@ -23,6 +24,9 @@ export default defineConfig({
     pluginLess(),
     pluginNodePolyfill(),
     pluginSvgr(),
+    createCoreReportTemplateReplacementPlugin({
+      appDir: __dirname,
+    }),
     createPlaygroundCopyPlugin(
       path.join(__dirname, 'dist'),
       path.join(__dirname, '../../packages/playground/static'),

apps/report/package.json

@@ -13,6 +13,16 @@
     "generate-demo": "node scripts/generate-demo-report.mjs",
     "e2e": "node scripts/generate-demo-report.mjs && node ../../packages/cli/bin/midscene ./e2e/"
   },
+  "nx": {
+    "targets": {
+      "build": {
+        "outputs": [
+          "{projectRoot}/dist",
+          "{workspaceRoot}/packages/core/dist/report-template"
+        ]
+      }
+    }
+  },
   "dependencies": {
     "@ant-design/icons": "^5.3.1",
     "@midscene/core": "workspace:*",

apps/report/rsbuild.config.ts

@@ -1,4 +1,3 @@
-import assert from 'node:assert';
 import fs from 'node:fs';
 import path from 'node:path';
 import { defineConfig } from '@rsbuild/core';
@@ -8,7 +7,10 @@ import { pluginReact } from '@rsbuild/plugin-react';
 import { pluginSvgr } from '@rsbuild/plugin-svgr';
 import { pluginTypeCheck } from '@rsbuild/plugin-type-check';
 import { pluginWorkspaceDev } from 'rsbuild-plugin-workspace-dev';
-import { commonIgnoreWarnings } from '../../scripts/rsbuild-utils.ts';
+import {
+  commonIgnoreWarnings,
+  createReportTemplateSyncPlugin,
+} from '../../scripts/rsbuild-utils.ts';
 
 // Read all JSON files from test-data directory
 const testDataDir = path.join(__dirname, 'test-data');
@@ -24,88 +26,17 @@ const allTestData = jsonFiles.map((file) => {
   };
 });
 
-// put back the report template to the core package
-// this is a workaround for the circular dependency issue
-// ERROR: This repository uses pkg in bundler mode. It is necessary to declare @midscene/report in the dependency; otherwise, it may cause packaging order issues and thus lead to the failure of report injection
-const copyReportTemplate = () => ({
-  name: 'copy-report-template',
-  setup(api: {
-    onAfterBuild: (arg0: ({ compiler }: { compiler: any }) => void) => void;
-  }) {
-    api.onAfterBuild(({ compiler }) => {
-      const magicString = 'REPLACE_ME_WITH_REPORT_HTML';
-      const replacedMark = '/*REPORT_HTML_REPLACED*/';
-      const regExpForReplace = /\/\*REPORT_HTML_REPLACED\*\/.*/;
-
-      // read the template file
-      const srcPath = path.join(__dirname, 'dist', 'index.html');
-      const tplFileContent = fs
-        .readFileSync(srcPath, 'utf-8')
-        .replaceAll(magicString, '');
-      assert(
-        !tplFileContent.includes(magicString),
-        'magic string should not be in the template file',
-      );
-      const finalContent = `${replacedMark}${JSON.stringify(tplFileContent)}`;
-
-      // find the core package
-      const corePkgDir = path.join(__dirname, '..', '..', 'packages', 'core');
-      const corePkgJson = JSON.parse(
-        fs.readFileSync(path.join(corePkgDir, 'package.json'), 'utf-8'),
-      );
-      assert(
-        corePkgJson.name === '@midscene/core',
-        'core package name is not @midscene/core',
-      );
-      const corePkgDistDir = path.join(corePkgDir, 'dist');
-
-      // traverse all .js files and inject (or update) the template
-      const jsFiles = fs.readdirSync(corePkgDistDir, { recursive: true });
-      let replacedCount = 0;
-      for (const file of jsFiles) {
-        if (
-          typeof file === 'string' &&
-          (file.endsWith('.js') || file.endsWith('.mjs'))
-        ) {
-          const filePath = path.join(corePkgDistDir, file.toString());
-          const fileContent = fs.readFileSync(filePath, 'utf-8');
-          if (fileContent.includes(replacedMark)) {
-            assert(
-              regExpForReplace.test(fileContent),
-              'a replaced mark is found but cannot match',
-            );
-
-            const replacedContent = fileContent.replace(
-              regExpForReplace,
-              () => finalContent,
-            );
-            fs.writeFileSync(filePath, replacedContent);
-            replacedCount++;
-            console.log(`Template updated in file ${filePath}`);
-          } else if (fileContent.includes(magicString)) {
-            const magicStringCount = (
-              fileContent.match(new RegExp(magicString, 'g')) || []
-            ).length;
-            assert(
-              magicStringCount === 1,
-              'magic string shows more than once in the file, cannot process',
-            );
-            const replacedContent = fileContent.replace(
-              `'${magicString}'`,
-              () => finalContent, // there are some $- code in the tpl, so we have to use a function as the second argument
-            );
-            fs.writeFileSync(filePath, replacedContent);
-            replacedCount++;
-            console.log(`Template injected into ${filePath}`);
-          }
-        }
-      }
-      if (replacedCount === 0) {
-        throw new Error('No html template found in the core package');
-      }
-    });
-  },
-});
+const reportTemplatePath = path.join(__dirname, 'dist', 'index.html');
+const coreReportTemplatePath = path.join(
+  __dirname,
+  '..',
+  '..',
+  'packages',
+  'core',
+  'dist',
+  'report-template',
+  'index.html',
+);
 
 export default defineConfig({
   html: {
@@ -163,7 +94,11 @@ export default defineConfig({
     pluginLess(),
     pluginNodePolyfill(),
     pluginSvgr(),
-    copyReportTemplate(),
+    createReportTemplateSyncPlugin({
+      srcPath: reportTemplatePath,
+      destPath: coreReportTemplatePath,
+      pluginName: 'sync-report-template-to-core',
+    }),
     pluginTypeCheck(),
     pluginWorkspaceDev({
       projects: {