@schalkneethling/miyagi-core 4.2.0 → 4.3.1

package/dist/js/iframe.js

@@ -1 +1 @@
-customElements.define("accordion-tabs",class extends HTMLElement{#e;#t;#s;#i;#n;static get observedAttributes(){return["breakpoint","current"]}constructor(){super()}connectedCallback(){if(!this.closest("code")){if(this.content=[],this.hasAttribute("breakpoint")){const e=this.getAttribute("breakpoint"),t=parseInt(e,10);let s;s=e.endsWith("rem")?t*parseInt(window.getComputedStyle(document.documentElement).fontSize,10):e.endsWith("em")?t*parseInt(window.getComputedStyle(this).fontSize,10):t,this.#t=s}window.requestAnimationFrame(()=>{this.details=Array.from(this.children),this.details.forEach((e,t)=>{const s=e.querySelector("summary");e.open&&(this.index=t),this.content.push({title:s.textContent,content:[...s.parentElement.children].filter(e=>1===e.nodeType&&e!==s)})});let e=!1;this.#i=new ResizeObserver(t=>{if(e)for(const e of t)this.#r(e.borderBoxSize[0].inlineSize);e=!0}),this.#r(this.clientWidth,()=>{this.#i.observe(this)})})}}attributeChangedCallback(e,t,s){"current"===e&&(this.index=parseInt(s,10),this.#r(this.clientWidth))}disconnectedCallback(){this.#i&&this.#i.disconnect()}async#r(e,t){!this.#t||e<this.#t?(await this.#o(),this.#s="accordion"):(await this.#a(),this.#s="tabs"),t&&t()}#o(){return this.#e||(this.#e=new e(this)),"tabs"===this.#s?(this.#c(),this.#e.setElements(),this.#e.elements.forEach(e=>this.appendChild(e))):this.#e.render(),!0}async#a(){this.#c(),this.#n?(this.#n.index="number"==typeof this.index?this.index:0,this.#n.setElements()):this.#n=new t(this);const[e,s]=this.#n.elements;return this.appendChild(e),s.forEach(e=>{this.appendChild(e)}),await this.#n.render(!1)}#c(){Array.from(this.children).forEach(e=>this.removeChild(e))}});class e{constructor(e){this.AccordionTabs=e,this.elements=this.AccordionTabs.details,this.elements.forEach((e,t)=>{e.querySelector("summary").addEventListener("click",({target:e})=>{requestAnimationFrame(()=>{this.#d(e.closest("details"),t)})})}),this.render()}setElements(){this.elements.forEach((e,t)=>{this.AccordionTabs.content[t].content.forEach(t=>e.appendChild(t)),e.open=t===this.AccordionTabs.index})}render(){this.elements.forEach((e,t)=>{e.open=t===this.AccordionTabs.index})}#d(e,t){e.open?(this.elements.forEach(t=>{e!==t&&(t.open=!1)}),this.AccordionTabs.index=t):this.AccordionTabs.index=null}}class t{#h;#l=[];#b=[];#u;constructor(e){this.#h=e,this.elements=this.getElements(),this.index="number"==typeof this.#h.index?this.#h.index:0,this.#u=new s(this)}getElements(){const e=document.createElement("ol"),t=[];return this.#h.content.forEach(({title:s,content:i},n)=>{const r=document.createElement("button"),o=document.createElement("li"),a=document.createElement("div"),c=crypto.randomUUID(),d=`tab-${c}`,h=`panel-${c}`;e.setAttribute("role","tablist"),o.setAttribute("role","presentation"),r.textContent=s,r.type="button",r.id=d,r.setAttribute("aria-selected",n===this.index?"true":"false"),r.setAttribute("tabindex",n===this.index?0:-1),r.setAttribute("aria-controls",h),r.setAttribute("role","tab"),this.#l.push(r),o.appendChild(r),e.appendChild(o),i.forEach(e=>{a.appendChild(e)}),a.id=h,a.hidden=this.index!==n,a.setAttribute("role","tabpanel"),a.setAttribute("tabindex","0"),a.setAttribute("aria-labelledby",d),t.push(a),this.#b.push(a)}),[e,t]}setElements(){this.elements[1].forEach((e,t)=>{this.#h.content[t].content.forEach(t=>e.appendChild(t))})}setActiveTab(e){this.#h.index=this.index=e,this.render()}async render(e=!0){return this.elements[1].forEach((e,t)=>{e.hidden=t!==this.index}),await this.#u.render(e)}}class s{#m;#p;constructor(e){this.#m=e,this.#p=Array.from(this.#m.elements[0].querySelectorAll("button")),this.#p.forEach(e=>{e.addEventListener("click",this.#T.bind(this)),e.addEventListener("keydown",this.#A.bind(this))})}#T({currentTarget:e}){this.#m.setActiveTab(this.#p.indexOf(e))}#A(e){const{dir:t}=e.target.closest("[dir]")||document.documentElement;let s=!1;switch(e.key){case"ArrowLeft":"rtl"===t?this.#f():this.#w(),s=!0;break;case"ArrowRight":"rtl"===t?this.#w():this.#f(),s=!0;break;case"Home":this.#m.setActiveTab(0),s=!0;break;case"End":this.#m.setActiveTab(this.#p.length-1),s=!0}s&&(e.stopPropagation(),e.preventDefault())}#f(){this.#m.setActiveTab(this.#m.index===this.#p.length-1?0:this.#m.index+1)}#w(){this.#m.setActiveTab(0===this.#m.index?this.#p.length-1:this.#m.index-1)}render(e=!0){return this.#p.forEach((t,s)=>{s===this.#m.index?(t.setAttribute("aria-selected","true"),t.removeAttribute("tabindex"),e&&t.focus()):(t.setAttribute("aria-selected","false"),t.setAttribute("tabindex",-1))}),new Promise(e=>setTimeout(e,1e3))}}new WebSocket(`ws://${document.location.host}`).onmessage=async e=>{"reloadParent"===e.data?parent.window.location.reload():window.location.reload()};function i(e){return["INPUT","SELECT","TEXTAREA"].includes(e)}window.location.pathname.startsWith("/component?")&&window.location.href.indexOf("&embedded=true")>=0&&window.self===window.top&&(window.location=new URL(window.location).replace("&embedded=true","")),document.addEventListener("DOMContentLoaded",function(){const e=Array.from(document.querySelectorAll(".Component-file")),t=document.querySelector(".Styleguide");e.length>0&&import("./_iframe-links-DdifIr4P.js").then(t=>{t.default(e)}).catch(e=>console.error(e)),document.querySelector(".Code")&&import("./_prism-By3NMwUd.js"),t&&import("./index-BKDKaBC6.js").then(e=>new e.default(t)).catch(e=>console.error(e)),document.querySelector(".js-openMockData")&&import("./_mock-data-Dypo4Bl_.js")}),document.addEventListener("keyup",e=>{const{path:t,originalTarget:s,target:n,key:r}=e,o=t?t[0]:s||n;((e,t)=>!i(e.tagName)&&"f"===t)(o,r)?parent.window.dispatchEvent(new CustomEvent("searchTriggered")):((e,t)=>!i(e.tagName)&&"g"===t)(o,r)&&parent.window.dispatchEvent(new CustomEvent("gotoTriggered"))});
+customElements.define("accordion-tabs",class extends HTMLElement{#e;#t;#n;#i;#s;static get observedAttributes(){return["breakpoint","current"]}constructor(){super()}connectedCallback(){if(!this.closest("code")){if(this.content=[],this.hasAttribute("breakpoint")){const e=this.getAttribute("breakpoint"),t=parseInt(e,10);let n;n=e.endsWith("rem")?t*parseInt(window.getComputedStyle(document.documentElement).fontSize,10):e.endsWith("em")?t*parseInt(window.getComputedStyle(this).fontSize,10):t,this.#t=n}window.requestAnimationFrame(()=>{this.details=Array.from(this.children),this.details.forEach((e,t)=>{const n=e.querySelector("summary");e.open&&(this.index=t),this.content.push({title:n.textContent,content:[...n.parentElement.children].filter(e=>1===e.nodeType&&e!==n)})});let e=!1;this.#i=new ResizeObserver(t=>{if(e)for(const e of t)this.#r(e.borderBoxSize[0].inlineSize);e=!0}),this.#r(this.clientWidth,()=>{this.#i.observe(this)})})}}attributeChangedCallback(e,t,n){"current"===e&&(this.index=parseInt(n,10),this.#r(this.clientWidth))}disconnectedCallback(){this.#i&&this.#i.disconnect()}async#r(e,t){!this.#t||e<this.#t?(await this.#o(),this.#n="accordion"):(await this.#a(),this.#n="tabs"),t&&t()}#o(){return this.#e||(this.#e=new e(this)),"tabs"===this.#n?(this.#c(),this.#e.setElements(),this.#e.elements.forEach(e=>this.appendChild(e))):this.#e.render(),!0}async#a(){this.#c(),this.#s?(this.#s.index="number"==typeof this.index?this.index:0,this.#s.setElements()):this.#s=new t(this);const[e,n]=this.#s.elements;return this.appendChild(e),n.forEach(e=>{this.appendChild(e)}),await this.#s.render(!1)}#c(){Array.from(this.children).forEach(e=>this.removeChild(e))}});class e{constructor(e){this.AccordionTabs=e,this.elements=this.AccordionTabs.details,this.elements.forEach((e,t)=>{e.querySelector("summary").addEventListener("click",({target:e})=>{requestAnimationFrame(()=>{this.#d(e.closest("details"),t)})})}),this.render()}setElements(){this.elements.forEach((e,t)=>{this.AccordionTabs.content[t].content.forEach(t=>e.appendChild(t)),e.open=t===this.AccordionTabs.index})}render(){this.elements.forEach((e,t)=>{e.open=t===this.AccordionTabs.index})}#d(e,t){e.open?(this.elements.forEach(t=>{e!==t&&(t.open=!1)}),this.AccordionTabs.index=t):this.AccordionTabs.index=null}}class t{#h;#l=[];#b=[];#u;constructor(e){this.#h=e,this.elements=this.getElements(),this.index="number"==typeof this.#h.index?this.#h.index:0,this.#u=new n(this)}getElements(){const e=document.createElement("ol"),t=[];return this.#h.content.forEach(({title:n,content:i},s)=>{const r=document.createElement("button"),o=document.createElement("li"),a=document.createElement("div"),c=crypto.randomUUID(),d=`tab-${c}`,h=`panel-${c}`;e.setAttribute("role","tablist"),o.setAttribute("role","presentation"),r.textContent=n,r.type="button",r.id=d,r.setAttribute("aria-selected",s===this.index?"true":"false"),r.setAttribute("tabindex",s===this.index?0:-1),r.setAttribute("aria-controls",h),r.setAttribute("role","tab"),this.#l.push(r),o.appendChild(r),e.appendChild(o),i.forEach(e=>{a.appendChild(e)}),a.id=h,a.hidden=this.index!==s,a.setAttribute("role","tabpanel"),a.setAttribute("tabindex","0"),a.setAttribute("aria-labelledby",d),t.push(a),this.#b.push(a)}),[e,t]}setElements(){this.elements[1].forEach((e,t)=>{this.#h.content[t].content.forEach(t=>e.appendChild(t))})}setActiveTab(e){this.#h.index=this.index=e,this.render()}async render(e=!0){return this.elements[1].forEach((e,t)=>{e.hidden=t!==this.index}),await this.#u.render(e)}}class n{#m;#p;constructor(e){this.#m=e,this.#p=Array.from(this.#m.elements[0].querySelectorAll("button")),this.#p.forEach(e=>{e.addEventListener("click",this.#T.bind(this)),e.addEventListener("keydown",this.#f.bind(this))})}#T({currentTarget:e}){this.#m.setActiveTab(this.#p.indexOf(e))}#f(e){const{dir:t}=e.target.closest("[dir]")||document.documentElement;let n=!1;switch(e.key){case"ArrowLeft":"rtl"===t?this.#w():this.#A(),n=!0;break;case"ArrowRight":"rtl"===t?this.#A():this.#w(),n=!0;break;case"Home":this.#m.setActiveTab(0),n=!0;break;case"End":this.#m.setActiveTab(this.#p.length-1),n=!0}n&&(e.stopPropagation(),e.preventDefault())}#w(){this.#m.setActiveTab(this.#m.index===this.#p.length-1?0:this.#m.index+1)}#A(){this.#m.setActiveTab(0===this.#m.index?this.#p.length-1:this.#m.index-1)}render(e=!0){return this.#p.forEach((t,n)=>{n===this.#m.index?(t.setAttribute("aria-selected","true"),t.removeAttribute("tabindex"),e&&t.focus()):(t.setAttribute("aria-selected","false"),t.setAttribute("tabindex",-1))}),new Promise(e=>setTimeout(e,1e3))}}let i,s=250;function r(e){const t=function(e){return"reloadParent"===e?"parent":"string"==typeof e&&0===e.length?"iframe":null}(e);return t||function(e){try{return JSON.parse(e).scope||"iframe"}catch{return"iframe"}}(e)}function o(){i=new WebSocket(`${"https:"===window.location.protocol?"wss":"ws"}://${window.location.host}/__miyagi_ws`),i.onopen=()=>{s=250},i.onmessage=e=>{"parent"!==r(e.data)?window.location.reload():parent.window.location.reload()},i.onerror=()=>{i.close()},i.onclose=()=>{!function(){const e=Math.floor(100*Math.random()),t=Math.min(s+e,5e3);s=Math.min(2*s,5e3),window.setTimeout(()=>{o()},t)}()}}o();function a(e){return["INPUT","SELECT","TEXTAREA"].includes(e)}window.location.pathname.startsWith("/component?")&&window.location.href.indexOf("&embedded=true")>=0&&window.self===window.top&&(window.location=new URL(window.location).replace("&embedded=true","")),document.addEventListener("DOMContentLoaded",function(){const e=Array.from(document.querySelectorAll(".Component-file")),t=document.querySelector(".Styleguide");e.length>0&&import("./_iframe-links-DdifIr4P.js").then(t=>{t.default(e)}).catch(e=>console.error(e)),document.querySelector(".Code")&&import("./_prism-By3NMwUd.js"),t&&import("./index-BKDKaBC6.js").then(e=>new e.default(t)).catch(e=>console.error(e)),document.querySelector(".js-openMockData")&&import("./_mock-data-Dypo4Bl_.js")}),document.addEventListener("keyup",e=>{const{path:t,originalTarget:n,target:i,key:s}=e,r=t?t[0]:n||i;((e,t)=>!a(e.tagName)&&"f"===t)(r,s)?parent.window.dispatchEvent(new CustomEvent("searchTriggered")):((e,t)=>!a(e.tagName)&&"g"===t)(r,s)&&parent.window.dispatchEvent(new CustomEvent("gotoTriggered"))});

package/frontend/assets/js/_socket.js

@@ -1,9 +1,82 @@
-const ws = new WebSocket(`ws://${document.location.host}`);
+const SOCKET_PATH = "/__miyagi_ws";
+const INITIAL_RETRY_DELAY_MS = 250;
+const MAX_RETRY_DELAY_MS = 5000;
 
-ws.onmessage = async (message) => {
-	if (message.data === "reloadParent") {
+let retryDelay = INITIAL_RETRY_DELAY_MS;
+let websocket;
+
+function getWebSocketUrl() {
+	const protocol = window.location.protocol === "https:" ? "wss" : "ws";
+	return `${protocol}://${window.location.host}${SOCKET_PATH}`;
+}
+
+function triggerReload(scope) {
+	if (scope === "parent") {
 		parent.window.location.reload();
-	} else {
-		window.location.reload();
+		return;
+	}
+
+	window.location.reload();
+}
+
+function parseLegacyScope(messageData) {
+	if (messageData === "reloadParent") {
+		return "parent";
 	}
-};
+
+	if (typeof messageData === "string" && messageData.length === 0) {
+		return "iframe";
+	}
+
+	return null;
+}
+
+function parseJsonScope(messageData) {
+	try {
+		const parsed = JSON.parse(messageData);
+		return parsed.scope || "iframe";
+	} catch {
+		return "iframe";
+	}
+}
+
+function parseScope(messageData) {
+	const legacyScope = parseLegacyScope(messageData);
+	if (legacyScope) {
+		return legacyScope;
+	}
+
+	return parseJsonScope(messageData);
+}
+
+function scheduleReconnect() {
+	const jitter = Math.floor(Math.random() * 100);
+	const delay = Math.min(retryDelay + jitter, MAX_RETRY_DELAY_MS);
+	retryDelay = Math.min(retryDelay * 2, MAX_RETRY_DELAY_MS);
+
+	window.setTimeout(() => {
+		connect();
+	}, delay);
+}
+
+function connect() {
+	websocket = new WebSocket(getWebSocketUrl());
+
+	websocket.onopen = () => {
+		retryDelay = INITIAL_RETRY_DELAY_MS;
+	};
+
+	websocket.onmessage = (message) => {
+		triggerReload(parseScope(message.data));
+	};
+
+	websocket.onerror = () => {
+		websocket.close();
+	};
+
+	websocket.onclose = () => {
+		scheduleReconnect();
+	};
+}
+
+connect();

package/lib/config.js

@@ -70,5 +70,29 @@ function getCliArgs(args) {
 
 	cliArgs.build = buildArgs;
 
+	if (
+		cliArgs.watchReport !== undefined ||
+		cliArgs.watchReportFormat !== undefined ||
+		cliArgs.watchReportNoColor !== undefined
+	) {
+		cliArgs.watch = cliArgs.watch || {};
+		cliArgs.watch.report = cliArgs.watch.report || {};
+
+		if (cliArgs.watchReport !== undefined) {
+			cliArgs.watch.report.enabled = cliArgs.watchReport;
+			delete cliArgs.watchReport;
+		}
+
+		if (cliArgs.watchReportFormat !== undefined) {
+			cliArgs.watch.report.format = cliArgs.watchReportFormat;
+			delete cliArgs.watchReportFormat;
+		}
+
+		if (cliArgs.watchReportNoColor !== undefined) {
+			cliArgs.watch.report.useColors = !cliArgs.watchReportNoColor;
+			delete cliArgs.watchReportNoColor;
+		}
+	}
+
 	return cliArgs;
 }

package/lib/default-config.js

@@ -97,6 +97,64 @@ export default {
 			},
 			watchConfigFile: true,
 		},
+		watch: {
+			enabled: true,
+			backend: "chokidar",
+			sources: [],
+			ignore: {
+				defaults: true,
+				patterns: [],
+			},
+			behavior: {
+				debounceMs: 60,
+				coalesceWindowMs: 120,
+				awaitWriteFinish: {
+					enabled: true,
+					stabilityThresholdMs: 200,
+					pollIntervalMs: 50,
+				},
+			},
+			reload: {
+				enabled: true,
+				rules: {
+					template: "iframe",
+					data: "parent",
+					docs: "parent",
+					schema: "iframe",
+					componentAsset: "none",
+					globalCss: "none",
+					globalJs: "none",
+					unknown: "parent",
+				},
+			},
+			socket: {
+				reconnect: {
+					enabled: true,
+					initialDelayMs: 250,
+					maxDelayMs: 5000,
+					jitter: true,
+				},
+				heartbeat: {
+					enabled: true,
+					intervalMs: 30000,
+				},
+			},
+			report: {
+				enabled: true,
+				onStart: true,
+				format: "summary",
+				destination: "stdout",
+				useColors: true,
+			},
+			configFile: {
+				enabled: true,
+			},
+			debug: {
+				logEvents: false,
+				logDecisions: false,
+				logResolvedSources: false,
+			},
+		},
 		schema: {
 			ajv: AJV,
 			verbose: false,

package/lib/init/args.js

@@ -14,6 +14,19 @@ export default yargs(hideBin(process.argv))
 				"Logging additional information — helpful mainly in case of errors.",
 			type: "boolean",
 		},
+		"watch-report": {
+			description: "Enable watch report output on startup.",
+			type: "boolean",
+		},
+		"watch-report-format": {
+			description: "Set watch report format.",
+			type: "string",
+			choices: ["pretty", "summary", "json"],
+		},
+		"watch-report-no-color": {
+			description: "Disable colors in watch report output.",
+			type: "boolean",
+		},
 	})
 	.command("build", "Creates a static build of all your components", {
 		folder: {

package/lib/init/config.js

@@ -39,6 +39,30 @@ function sanitizePath(path) {
 	return sanitizedPath;
 }
 
+/**
+ * Keep watch paths relative-friendly (do not strip leading slash),
+ * but normalize common user input like "./foo/"
+ * @param {string} watchPath
+ * @returns {string}
+ */
+function sanitizeWatchPath(watchPath) {
+	if (typeof watchPath !== "string") {
+		return watchPath;
+	}
+
+	let sanitizedPath = watchPath;
+
+	if (sanitizedPath.startsWith("./")) {
+		sanitizedPath = sanitizedPath.slice(2);
+	}
+
+	if (sanitizedPath.endsWith("/")) {
+		sanitizedPath = sanitizedPath.slice(0, -1);
+	}
+
+	return sanitizedPath;
+}
+
 /**
  * @param {string|Array} strOrArr - file path or array of file paths
  * @returns {Array} the given file path in an array or simply the given array
@@ -47,6 +71,195 @@ function arrayfy(strOrArr) {
 	return Array.isArray(strOrArr) ? strOrArr : [strOrArr];
 }
 
+/**
+ * @param {object} merged
+ * @returns {object[]}
+ */
+function getDefaultWatchSources(merged) {
+	const sources = [];
+	const sourceByPath = new Set();
+
+	const addSource = (source) => {
+		if (!source || typeof source.path !== "string" || source.path.length === 0) {
+			return;
+		}
+
+		const key = `${source.type}:${source.path}`;
+		// Deduplicate watch targets; While calling add on Set will dedup,
+		// we need a conditional to avoid adding duplicates to the `sources` array.
+		if (sourceByPath.has(key)) {
+			return;
+		}
+
+		sourceByPath.add(key);
+		sources.push(source);
+	};
+
+	if (merged.components.folder) {
+		addSource({
+			id: "components",
+			type: "dir",
+			path: sanitizeWatchPath(merged.components.folder),
+			recursive: true,
+		});
+	}
+
+	if (merged.docs?.folder) {
+		addSource({
+			id: "docs",
+			type: "dir",
+			path: sanitizeWatchPath(merged.docs.folder),
+			recursive: true,
+			optional: true,
+		});
+	}
+
+	for (const folder of merged.assets.folder || []) {
+		addSource({
+			id: `assets-folder-${folder}`,
+			type: "dir",
+			path: sanitizeWatchPath(path.join(merged.assets.root, folder)),
+			recursive: true,
+			optional: true,
+		});
+	}
+
+	const localCssFiles = [...(merged.assets.css || []), ...(merged.assets.shared?.css || [])]
+		.filter((filePath) => !filePath.startsWith("http://"))
+		.filter((filePath) => !filePath.startsWith("https://"))
+		.filter((filePath) => !filePath.startsWith("://"));
+
+	for (const cssFile of localCssFiles) {
+		addSource({
+			id: `assets-css-${cssFile}`,
+			type: "file",
+			path: sanitizeWatchPath(path.join(merged.assets.root, cssFile)),
+			optional: true,
+		});
+	}
+
+	const localJsFiles = [...(merged.assets.js || []), ...(merged.assets.shared?.js || [])]
+		.map((entry) => entry.src || entry)
+		.filter((filePath) => typeof filePath === "string")
+		.filter((filePath) => !filePath.startsWith("http://"))
+		.filter((filePath) => !filePath.startsWith("https://"))
+		.filter((filePath) => !filePath.startsWith("://"));
+
+	for (const jsFile of localJsFiles) {
+		addSource({
+			id: `assets-js-${jsFile}`,
+			type: "file",
+			path: sanitizeWatchPath(path.join(merged.assets.root, jsFile)),
+			optional: true,
+		});
+	}
+
+	if (merged.userFileName && merged.watch?.configFile?.enabled) {
+		addSource({
+			id: "config-file",
+			type: "file",
+			path: sanitizeWatchPath(merged.userFileName),
+			optional: true,
+		});
+	}
+
+	return sources;
+}
+
+/**
+ * @param {object} watchConfig
+ * @returns {object[]}
+ */
+function normalizeWatchSources(watchConfig) {
+	if (!Array.isArray(watchConfig.sources) || watchConfig.sources.length === 0) {
+		return [];
+	}
+
+	return watchConfig.sources
+		.map((source, index) => {
+			if (!source || typeof source.path !== "string" || source.path.length === 0) {
+				return null;
+			}
+
+			const type = source.type === "file" ? "file" : "dir";
+
+			return {
+				id: source.id || `source-${index + 1}`,
+				type,
+				path: sanitizeWatchPath(source.path),
+				recursive: source.recursive !== false,
+				optional: source.optional === true,
+			};
+		})
+		.filter(Boolean);
+}
+
+/**
+ * Applies legacy watch-related config keys to watch config
+ * while preserving explicit new watch config values.
+ * @param {object} merged
+ * @param {object} userConfig
+ */
+function applyLegacyWatchCompatibility(merged, userConfig) {
+	merged.watch.configFile = merged.watch.configFile || { enabled: true };
+	merged.watch.configFile.enabled =
+		typeof merged.watch.configFile.enabled === "boolean"
+			? merged.watch.configFile.enabled
+			: merged.ui.watchConfigFile;
+
+	merged.watch.reload = merged.watch.reload || {};
+	merged.watch.reload.enabled =
+		typeof merged.watch.reload.enabled === "boolean"
+			? merged.watch.reload.enabled
+			: merged.ui.reload;
+
+	const userReloadRules = userConfig.watch?.reload?.rules || {};
+	merged.watch.reload.rules = {
+		...defaultUserConfig.watch.reload.rules,
+		...(merged.watch.reload.rules || {}),
+		componentAsset:
+			userReloadRules.componentAsset ??
+			(merged.ui.reloadAfterChanges.componentAssets
+				? "iframe"
+				: defaultUserConfig.watch.reload.rules.componentAsset),
+		globalCss:
+			userReloadRules.globalCss ??
+			(merged.ui.reloadAfterChanges.componentAssets
+				? "iframe"
+				: defaultUserConfig.watch.reload.rules.globalCss),
+		globalJs:
+			userReloadRules.globalJs ??
+			(merged.ui.reloadAfterChanges.componentAssets
+				? "iframe"
+				: defaultUserConfig.watch.reload.rules.globalJs),
+	};
+
+	merged.watch.ignore = merged.watch.ignore || {};
+	merged.watch.ignore.patterns = [
+		...(merged.watch.ignore.patterns || []),
+		...(merged.components.ignores || []),
+	].filter((entry) => typeof entry === "string");
+	merged.watch.ignore.patterns = [...new Set(merged.watch.ignore.patterns)];
+}
+
+/**
+ * Normalizes and validates new watch config values.
+ * @param {object} merged
+ */
+function normalizeAndValidateWatchConfig(merged) {
+	if (merged.watch?.backend === "node-watch") {
+		throw new Error(
+			'`watch.backend="node-watch"` is no longer supported. Please use `watch.backend="chokidar"`. See https://docs.miyagi.dev/configuration/options/ for migration details.',
+		);
+	}
+
+	merged.watch.backend = "chokidar";
+	merged.watch.sources = normalizeWatchSources(merged.watch);
+	if (merged.watch.sources.length === 0) {
+		merged.watch.sources = getDefaultWatchSources(merged);
+	}
+}
+
 /**
  *
  * @param {object} root0
@@ -335,6 +548,9 @@ export default (userConfig = {}) => {
 		merged.lint.logLevel = defaultUserConfig.lint.logLevel;
 	}
 
+	applyLegacyWatchCompatibility(merged, config);
+	normalizeAndValidateWatchConfig(merged);
+
 	return merged;
 };