@ckeditor/ckeditor5-dev-manual-server 61.0.0 → 61.2.0

package/README.md

@@ -10,8 +10,8 @@ More information about development tools packages can be found at the following
 
 ## Loading translations
 
-Pass a language code to `manualTestsPlugin()` to load and combine that language's TypeScript translation files from the configured
-package paths. The selected language becomes the default UI and content language for editors and contexts created by manual tests.
+Pass a language code to `manualTestsPlugin()` to load and combine that language's TypeScript translation files from the configured package paths. The selected language becomes the default UI and content language for editors and contexts created by manual tests.
+
 An explicit language in an editor or context configuration still takes precedence.
 
 ```ts
@@ -23,6 +23,29 @@ manualTestsPlugin( {
 
 For example, start the manual test server in Polish using `CK_LANGUAGE=pl pnpm manual`.
 
+## Preserving production CSS order
+
+Vite may order extracted stylesheets differently from their source imports in multi-page production builds. Add `preserveCssImportOrderPlugin()` to keep the CSS cascade consistent with the bundled development server:
+
+```ts
+import { defineConfig } from 'vite';
+import {
+	manualTestsPlugin,
+	preserveCssImportOrderPlugin
+} from '@ckeditor/ckeditor5-dev-manual-server';
+
+export default defineConfig( {
+	plugins: [
+		preserveCssImportOrderPlugin(),
+		manualTestsPlugin( {
+			paths: [ 'packages/*' ]
+		} )
+	]
+} );
+```
+
+The plugin enables Rolldown's strict module execution order in development and production, which can increase the generated bundle size. During production builds, it additionally rewrites plain CSS imports into ordered JavaScript side effects.
+
 ## Changelog
 
 See the [`CHANGELOG.md`](https://github.com/ckeditor/ckeditor5-dev/blob/master/packages/ckeditor5-dev-manual-server/CHANGELOG.md) file.

package/dist/index.d.ts

@@ -3,6 +3,7 @@
 * For licensing, see LICENSE.md.
 */
 export { manualTestsPlugin, type ManualTestsPluginOptions } from "./manual-test-plugin/plugin.js";
+export { preserveCssImportOrderPlugin } from "./preserve-css-import-order-plugin/plugin.js";
 export { ckDebugPlugin } from "./debug-plugin/plugin.js";
 export { refreshPlugin } from "./refresh-plugin/plugin.js";
 export { rawSvgPlugin } from "./svg-plugin/plugin.js";

package/dist/index.js

@@ -1,6 +1,7 @@
 import { existsSync, globSync, readFileSync, realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { basename, isAbsolute, posix, relative, resolve } from "node:path";
+import { createHash } from "node:crypto";
 //#region src/utils.ts
 /**
 * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
@@ -183,10 +184,7 @@ function manualTestsPlugin(options) {
 		name: "ckeditor5-manual-tests",
 		config(config = {}) {
 			workspaceRoot = resolve(config.root || process.cwd());
-			return {
-				input: getManualBuildInputs(),
-				build: { rolldownOptions: { output: { strictExecutionOrder: true } } }
-			};
+			return { input: getManualBuildInputs() };
 		},
 		configResolved(config) {
 			workspaceRoot = config.root;
@@ -199,7 +197,6 @@ function manualTestsPlugin(options) {
 				rewriteCatalogRequest(request, getManualCatalogPublicPath());
 				next();
 			});
-			keepManualHtmlSourceFresh(server.environments.client.bundledDev?.memoryFiles, getManualPages, workspaceRoot);
 		},
 		resolveId(source) {
 			if (source == MANUAL_ENTRIES_VIRTUAL_ID) return resolvedVirtualModuleId;
@@ -248,77 +245,6 @@ function manualTestsPlugin(options) {
 	};
 }
 /**
-* Keeps the served manual test HTML in sync with the source file while the dev server runs.
-*
-* Under `experimental.bundledDev`, Vite serves each manual test's HTML from an in-memory bundle
-* produced by the rolldown dev engine. That engine emits the HTML output only during the initial
-* build and never regenerates it when the source `.html` changes: its bundle state reports no
-* stale output for HTML entries, `devEngine.invalidate()` throws on a non-JS module, and even a
-* forced full build leaves the HTML memory file untouched (verified against Vite 8.2.1). A `.html`
-* edit still triggers a full page reload, so without this the browser reloads into the same stale
-* HTML until the server is restarted.
-*
-* The built-in-memory HTML rewrites the entry script, injects the asset tags and manual chrome,
-* and copies the source `<head>` — all inside `<head>`. The markup after `</head>` is a verbatim
-* copy of the source. So on every request we keep the freshly built `<head>` and splice in the
-* current post-`</head>` markup read from disk. Splicing unconditionally (rather than only after a
-* detected change) also covers sources that changed between the initial build and the first request
-* for the page, and it is idempotent for unchanged sources. This reflects edits to the test body
-* without re-running Vite's HTML transform or parsing the document. Any edit that would change
-* what belongs in `<head>` is not picked up this way and still needs a server restart, because
-* reproducing it would require re-running the build pipeline the dev engine refuses to run for HTML
-* entries. That covers edits confined to the `<head>` (styles, meta, extra scripts) as well as
-* adding or removing `<ck-manual-header>` in the body: toggling it changes the injected header
-* chrome (`<meta>` and the component script) in `<head>`, so the chrome only updates after a
-* restart even though the body splice already reflects the element itself.
-*
-* When `bundledDev` is not enabled the store is absent and this is a no-op: Vite's normal dev
-* pipeline already serves fresh HTML on every request.
-*/
-function keepManualHtmlSourceFresh(memoryFiles, getManualPages, workspaceRoot) {
-	if (!memoryFiles) return;
-	const getBundledFile = memoryFiles.get.bind(memoryFiles);
-	memoryFiles.get = (filePath) => {
-		const file = getBundledFile(filePath);
-		if (!file || !getManualPages().has(toPublicSpecifier(filePath))) return file;
-		try {
-			const sourceFilePath = resolve(workspaceRoot, stripLeadingSlash(filePath));
-			const freshHtml = composeFreshManualHtml(file.source, readFileSync(sourceFilePath, "utf8"));
-			return freshHtml == null ? file : { source: freshHtml };
-		} catch {
-			return file;
-		}
-	};
-}
-/**
-* Combines the freshly built `<head>` (asset tags and injected manual chrome) with the current
-* post-`</head>` markup from the source file. Returns `null` when either document is missing a
-* `</head>`, so the caller can fall back to the built output.
-*/
-function composeFreshManualHtml(builtHtml, sourceHtml) {
-	const builtHeadEnd = findHeadCloseTagIndex(builtHtml);
-	const sourceHeadEnd = findHeadCloseTagIndex(sourceHtml);
-	if (builtHeadEnd == -1 || sourceHeadEnd == -1) return null;
-	return builtHtml.slice(0, builtHeadEnd + 7) + sourceHtml.slice(sourceHeadEnd + 7);
-}
-/**
-* Finds the index of the `</head>` closing tag, or `-1` when the document has none. A `</head>`
-* literal may also appear earlier inside a `<head>` comment or an inline script string, so of all
-* the occurrences preceding the `<body>` tag the last one is taken. Without a `<body>` tag (or
-* when every occurrence follows it) the first occurrence wins, matching the pre-heuristic
-* behavior for such malformed documents.
-*/
-function findHeadCloseTagIndex(html) {
-	const firstHeadCloseIndex = /<\/head>/i.exec(html)?.index ?? -1;
-	const bodyMatch = /<body[\s>]/i.exec(html);
-	if (!bodyMatch) return firstHeadCloseIndex;
-	const headClosePattern = /<\/head>/gi;
-	let lastHeadCloseIndex = -1;
-	let match;
-	while ((match = headClosePattern.exec(html)) && match.index < bodyMatch.index) lastHeadCloseIndex = match.index;
-	return lastHeadCloseIndex == -1 ? firstHeadCloseIndex : lastHeadCloseIndex;
-}
-/**
 * Injection contract for the `<ck-manual-header>` component, added to `<head>` only when the
 * page source contains the element:
 * - a `<meta>` carrying the package name and the base-aware catalog href the component reads;
@@ -374,6 +300,78 @@ function parseRequestUrl(requestUrl) {
 	return URL.parse(requestUrl || "", "http://localhost");
 }
 //#endregion
+//#region src/preserve-css-import-order-plugin/plugin.ts
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+const INJECTED_CSS_VIRTUAL_ID_PREFIX = "\0virtual:ckeditor5-preserve-css-import-order:";
+const INJECTED_CSS_VIRTUAL_ID_SUFFIX = ".js";
+const CSS_FILE_REGEXP = /^[^?#]+\.css$/;
+/**
+* Preserves the source execution order of CSS imports in manual development and production builds.
+*
+* Vite extracts imported CSS into assets and orders those assets by the generated chunk graph.
+* In a multi-page build that order may differ from the source module execution order, changing
+* the cascade between CKEditor stylesheets. This is a known Vite limitation:
+* https://github.com/vitejs/vite/issues/4890.
+*
+* Until Vite handles this natively (https://github.com/vitejs/vite/pull/22541), plain CSS imports
+* in production builds are replaced with virtual JavaScript modules. Each module loads the
+* processed CSS through Vite's `?inline` query and appends it as a `<style>` side effect.
+* Rolldown's `strictExecutionOrder` keeps both these production effects and Vite's native bundled
+* development CSS effects in source order.
+*
+* Query-bearing CSS imports retain their explicit Vite semantics and pass through unchanged.
+*/
+function preserveCssImportOrderPlugin() {
+	let rewriteCssImports = false;
+	const cssFilePaths = /* @__PURE__ */ new Map();
+	return {
+		name: "ckeditor5-preserve-css-import-order",
+		config(_config, { command }) {
+			rewriteCssImports = command == "build";
+			return { build: { rolldownOptions: { output: { strictExecutionOrder: true } } } };
+		},
+		resolveId: {
+			order: "pre",
+			filter: { id: CSS_FILE_REGEXP },
+			async handler(source, importer, options) {
+				if (!rewriteCssImports) return null;
+				const resolved = await this.resolve(source, importer, {
+					...options,
+					skipSelf: true
+				});
+				if (!resolved || resolved.external) return null;
+				const cssIdHash = createHash("sha256").update(resolved.id).digest("hex");
+				const virtualId = `${INJECTED_CSS_VIRTUAL_ID_PREFIX}${cssIdHash}${INJECTED_CSS_VIRTUAL_ID_SUFFIX}`;
+				cssFilePaths.set(virtualId, resolved.id);
+				return virtualId;
+			}
+		},
+		load: {
+			filter: { id: new RegExp(`^${INJECTED_CSS_VIRTUAL_ID_PREFIX}`) },
+			handler(id) {
+				const cssFilePath = cssFilePaths.get(id);
+				if (!cssFilePath) return null;
+				return {
+					code: createCssInjectionModule(cssFilePath),
+					moduleSideEffects: true
+				};
+			}
+		}
+	};
+}
+function createCssInjectionModule(cssFilePath) {
+	return `
+import css from ${JSON.stringify(`${cssFilePath}?inline`)};
+
+const style = document.createElement( 'style' );
+style.textContent = css;
+document.head.appendChild( style );
+`;
+}
+//#endregion
 //#region src/debug-plugin/plugin.ts
 /**
 * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
@@ -423,7 +421,6 @@ function refreshPlugin() {
 		configureServer(server) {
 			const { bundledDev } = server.environments.client;
 			wrapBundledDevClientSend(bundledDev);
-			wrapBundledDevFullReloads(bundledDev, server.config.root);
 		},
 		hotUpdate({ file, modules }) {
 			if (file.endsWith(".manual.html")) return modules;
@@ -444,31 +441,6 @@ function wrapBundledDevClientSend(bundledDev) {
 		return setupIfNeeded(client, clientId);
 	};
 }
-function wrapBundledDevFullReloads(bundledDev, workspaceRoot) {
-	const handleHmrOutput = bundledDev.handleHmrOutput.bind(bundledDev);
-	bundledDev.handleHmrOutput = (client, files, hmrOutput) => {
-		if (hmrOutput.type != "FullReload") return handleHmrOutput(client, files, hmrOutput);
-		if (!shouldShowManualRefreshPrompt(files)) {
-			reloadClientAfterLatestBuildOutput(bundledDev, client, files, workspaceRoot);
-			return;
-		}
-		ensureLatestBuildOutput(bundledDev);
-		client.send({
-			type: "custom",
-			event: MANUAL_REFRESH_EVENT_NAME
-		});
-	};
-}
-async function reloadClientAfterLatestBuildOutput(bundledDev, client, files, workspaceRoot) {
-	try {
-		await bundledDev.devEngine.ensureLatestBuildOutput();
-	} catch {}
-	const htmlFile = files.find((file) => isHtmlFile(file));
-	client.send({
-		type: "full-reload",
-		path: htmlFile ? toPublicFilePath(htmlFile, workspaceRoot) : void 0
-	});
-}
 function ensureLatestBuildOutput(bundledDev) {
 	try {
 		bundledDev.devEngine.ensureLatestBuildOutput().catch(() => {});
@@ -527,4 +499,4 @@ function rawSvgPlugin() {
 * For licensing, see LICENSE.md.
 */
 //#endregion
-export { ckDebugPlugin, manualTestsPlugin, rawSvgPlugin, refreshPlugin, stringifyValues };
+export { ckDebugPlugin, manualTestsPlugin, preserveCssImportOrderPlugin, rawSvgPlugin, refreshPlugin, stringifyValues };

package/dist/preserve-css-import-order-plugin/plugin.d.ts

@@ -0,0 +1,22 @@
+/**
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md.
+*/
+import type { Plugin } from "vite";
+/**
+* Preserves the source execution order of CSS imports in manual development and production builds.
+*
+* Vite extracts imported CSS into assets and orders those assets by the generated chunk graph.
+* In a multi-page build that order may differ from the source module execution order, changing
+* the cascade between CKEditor stylesheets. This is a known Vite limitation:
+* https://github.com/vitejs/vite/issues/4890.
+*
+* Until Vite handles this natively (https://github.com/vitejs/vite/pull/22541), plain CSS imports
+* in production builds are replaced with virtual JavaScript modules. Each module loads the
+* processed CSS through Vite's `?inline` query and appends it as a `<style>` side effect.
+* Rolldown's `strictExecutionOrder` keeps both these production effects and Vite's native bundled
+* development CSS effects in source order.
+*
+* Query-bearing CSS imports retain their explicit Vite semantics and pass through unchanged.
+*/
+export declare function preserveCssImportOrderPlugin(): Plugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-dev-manual-server",
-  "version": "61.0.0",
+  "version": "61.2.0",
   "description": "Used to extend Vite to create a manual test server for CKEditor 5.",
   "keywords": [],
   "author": "CKSource (http://cksource.com/)",
@@ -25,6 +25,6 @@
   ],
   "dependencies": {
     "@ckeditor/ckeditor5-inspector": "^5.0.1",
-    "vite": "^8.2.1"
+    "vite": "^8.2.2"
   }
 }