@birdinternet/wp-nested-patterns 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Doug Johnson
+
+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/README.md

@@ -0,0 +1,235 @@
+# wp-nested-patterns
+
+Compile WordPress block patterns that reference each other into flat,
+WP-ready output.
+
+WordPress's `core/pattern` block lets one pattern insert another by slug —
+but only at *render time*, and only in contexts the block editor actually
+supports. Reference a pattern from inside `core/post-template` (a query
+loop), for instance, and it silently fails to resolve. `wp-nested-patterns`
+solves this by resolving those references at **build time** instead: it
+walks your source patterns, inlines every `<!-- wp:pattern {"slug":"..."} /-->`
+reference into the referencing block tree, and writes out plain block markup
+that WordPress can render anywhere, including inside query loops. The
+runtime never sees a `wp:pattern` reference, so the render-context
+limitation goes away entirely.
+
+- **Recursive** — patterns can reference patterns, resolved depth-first, with cycle detection.
+- **Attribute overrides** — a reference can pass `srcAttributes` to override attributes on the resolved pattern's first top-level block, so one source pattern can serve multiple call sites (e.g. an inheriting query vs. a fixed-query variant).
+- **Validated output** — source and compiled markup are both checked for balanced HTML; a malformed pattern fails the build instead of producing a broken block WordPress can't parse.
+
+## Install
+
+```sh
+npm install @birdinternet/wp-nested-patterns
+```
+
+## Project layout
+
+`wp-nested-patterns` compiles a `src/` directory into a matching directory
+next to it — the same convention WordPress block themes already use:
+
+```
+your-theme/
+  src/
+    patterns/    *.php — Slug-headed patterns, referenceable via wp:pattern
+    templates/   *.html
+    parts/       *.html
+  patterns/      ← compiled output (generated — don't edit)
+  templates/     ← compiled output (generated — don't edit)
+  parts/         ← compiled output (generated — don't edit)
+```
+
+Each PHP pattern file needs a `Slug:` header, exactly like a normal WP block
+pattern:
+
+```php
+<?php
+/**
+ * Title: Card
+ * Slug: my-theme/card
+ * Categories: text
+ */
+?>
+<!-- wp:group -->
+<div class="wp-block-group"><!-- wp:paragraph --><p>Hello</p><!-- /wp:paragraph --></div>
+<!-- /wp:group -->
+```
+
+Reference it from any other pattern, template, or template part:
+
+```html
+<!-- wp:pattern {"slug":"my-theme/card"} /-->
+```
+
+Optionally override attributes on the resolved pattern's first top-level
+block (deep-merged, so unmentioned keys are preserved):
+
+```html
+<!-- wp:pattern {"slug":"my-theme/query","srcAttributes":{"queryId":1,"query":{"inherit":false}}} /-->
+```
+
+## Usage
+
+### Standalone CLI
+
+No build tool required:
+
+```sh
+npx @birdinternet/wp-nested-patterns --src src --dest . --watch
+```
+
+```
+Usage:
+  wp-nested-patterns [--src <dir>] [--dest <dir>] [--watch] [--config <file>]
+
+Options:
+  --src <dir>       Source directory containing patterns/templates/parts (default: "src")
+  --dest <dir>       Destination root the compiled dirs are written into (default: ".")
+  --watch, -w        Rebuild on every source change
+  --config, -c        Path to a config file exporting { srcRoot, destRoot, dirs }
+  --help, -h          Show this help
+```
+
+If `wp-nested-patterns.config.mjs` exists in the current directory it's
+loaded automatically — see [`wp-nested-patterns.config.example.mjs`](./wp-nested-patterns.config.example.mjs).
+
+Add it to `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "patterns:build": "wp-nested-patterns --src wp-content/themes/my-theme/src --dest wp-content/themes/my-theme",
+    "patterns:watch": "npm run patterns:build -- --watch"
+  }
+}
+```
+
+### Vite
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite';
+import wpNestedPatterns from '@birdinternet/wp-nested-patterns/vite';
+
+export default defineConfig({
+  plugins: [
+    wpNestedPatterns({
+      srcRoot: 'wp-content/themes/my-theme/src',
+      destRoot: 'wp-content/themes/my-theme',
+    }),
+  ],
+});
+```
+
+Compiles once at `buildStart` for production builds; under `vite dev`, it
+also watches `srcRoot` (via Vite's own file watcher) and recompiles on every
+change.
+
+### esbuild
+
+```js
+import * as esbuild from 'esbuild';
+import { wpNestedPatternsPlugin } from '@birdinternet/wp-nested-patterns/esbuild';
+
+await esbuild.build({
+  // ...your existing esbuild config
+  plugins: [
+    wpNestedPatternsPlugin({
+      srcRoot: 'wp-content/themes/my-theme/src',
+      destRoot: 'wp-content/themes/my-theme',
+      watch: true, // recompile on source changes while an esbuild context stays open
+    }),
+  ],
+});
+```
+
+Pattern source files aren't part of esbuild's module graph (they're PHP/HTML,
+not JS), so esbuild has no built-in way to watch them. With `watch: true` the
+plugin starts its own watcher for the lifetime of the build context; leave it
+`false` (the default) for one-shot builds.
+
+### webpack
+
+`wp-nested-patterns` ships as ESM. If your webpack config is CommonJS
+(`webpack.config.js` without `"type": "module"` in `package.json`), name the
+config file `webpack.config.mjs` — webpack loads that automatically — or
+`import()` the plugin dynamically. Otherwise:
+
+```js
+// webpack.config.mjs
+import { WpNestedPatternsWebpackPlugin } from '@birdinternet/wp-nested-patterns/webpack';
+
+export default {
+  // ...your existing webpack config
+  plugins: [
+    new WpNestedPatternsWebpackPlugin({
+      srcRoot: 'wp-content/themes/my-theme/src',
+      destRoot: 'wp-content/themes/my-theme',
+    }),
+  ],
+};
+```
+
+Compiles before every run and every watch rebuild, and registers `srcRoot`
+as a context dependency so `webpack --watch` triggers a rebuild when pattern
+source files change even though nothing in the JS graph imports them.
+
+### Programmatic API
+
+```js
+import { createCompiler } from '@birdinternet/wp-nested-patterns';
+
+const compiler = createCompiler({
+  srcRoot: 'wp-content/themes/my-theme/src',
+  destRoot: 'wp-content/themes/my-theme',
+});
+
+const fileCount = await compiler.build();
+```
+
+`compileMarkup(markup, slugMap)` is also exported for working with block
+markup strings directly, without touching the filesystem — see
+[`src/core.js`](./src/core.js).
+
+## Configuration
+
+All three adapters and the CLI's `--config` file accept the same options:
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `srcRoot` | *(required)* | Directory containing the source subdirectories. |
+| `destRoot` | *(required)* | Directory the compiled subdirectories are written into. |
+| `dirs` | `patterns` (.php, slugged), `templates` (.html), `parts` (.html) | Which subdirectories to compile, and how. |
+
+A custom `dirs` entry: `{ name, extensions, type: 'php' | 'html', registerSlugs }`.
+`type: 'php'` preserves everything before the first `?>` as a passthrough
+header. `registerSlugs: true` makes files in that directory resolvable as
+`wp:pattern` targets, keyed by their `Slug:` header (defaults to `true` only
+for a directory named `patterns`).
+
+## How it works
+
+Each source directory is parsed with
+`@wordpress/block-serialization-default-parser`. Every `wp:pattern` block is
+replaced with the resolved pattern's block tree (recursively — patterns may
+reference patterns), any `srcAttributes` are deep-merged into the resolved
+block's attributes, and the result is re-serialized to block comment markup.
+Both the source and the compiled output are checked for balanced HTML before
+being written, so a pattern with mismatched tags fails the build with a
+precise error rather than producing broken markup WordPress can't parse.
+
+## Testing
+
+```sh
+npm test
+```
+
+Runs the core resolution engine's unit tests plus end-to-end tests that
+actually invoke `vite.build()`/`createServer()`, `esbuild.build()`/`context()`,
+and `webpack()` with each adapter, asserting on the files they write to disk
+(including watch-mode recompilation).
+
+## License
+
+MIT

package/adapters/esbuild.js

@@ -0,0 +1,43 @@
+// esbuild plugin: compiles patterns once on every build (esbuild calls
+// onStart on the initial build and on every rebuild). esbuild has no
+// generic "watch this directory" hook for files outside the module graph,
+// so when `watch: true` is passed we additionally start our own chokidar
+// watcher that recompiles on source changes for the life of the build.
+import { createCompiler } from '../src/compiler.js';
+
+export function wpNestedPatternsPlugin(options = {}) {
+	const { watch = false, ...compilerOptions } = options;
+	const compiler = createCompiler(compilerOptions);
+
+	return {
+		name: 'wp-nested-patterns',
+		setup(build) {
+			build.onStart(async () => {
+				try {
+					await compiler.build();
+				} catch (e) {
+					return {
+						errors: [{ text: `wp-nested-patterns: ${e.message}` }],
+					};
+				}
+			});
+
+			if (!watch) return;
+
+			let watcher;
+			build.onStart(async () => {
+				if (watcher) return;
+				const { default: chokidar } = await import('chokidar');
+				watcher = chokidar.watch(compiler.options.srcRoot, { ignoreInitial: true });
+				watcher.on('all', () => {
+					compiler.build().catch((e) => {
+						console.error(`[wp-nested-patterns] FAILED: ${e.message}`);
+					});
+				});
+			});
+			build.onDispose(() => watcher?.close());
+		},
+	};
+}
+
+export default wpNestedPatternsPlugin;

package/adapters/vite.js

@@ -0,0 +1,76 @@
+// Vite plugin: compiles patterns once at build start, and again on every
+// source change while the dev server is running (using Vite's own watcher).
+import { realpathSync } from 'node:fs';
+import path from 'node:path';
+import { createCompiler } from '../src/compiler.js';
+
+// Vite's watcher reports realpaths (chokidar resolves symlinks), but a
+// plain path.resolve() does not — on macOS /var is itself a symlink to
+// /private/var, so os.tmpdir()-based paths mismatch unless both sides are
+// realpath'd before comparing. Falls back to the parent directory's
+// realpath for a file that no longer exists (e.g. an unlink event).
+function tryRealpath(p) {
+	try {
+		return realpathSync(p);
+	} catch {
+		try {
+			return path.join(realpathSync(path.dirname(p)), path.basename(p));
+		} catch {
+			return p;
+		}
+	}
+}
+
+export default function wpNestedPatterns(options = {}) {
+	const compiler = createCompiler(options);
+	let building = false;
+	let queued = false;
+	let logger = console;
+
+	async function runBuild(label) {
+		if (building) {
+			queued = true;
+			return;
+		}
+		building = true;
+		try {
+			const start = Date.now();
+			const n = await compiler.build();
+			const msg = `[wp-nested-patterns] compiled ${n} files in ${Date.now() - start}ms (${label})`;
+			if (logger.info) logger.info(msg); else logger.log(msg);
+		} catch (e) {
+			const msg = `[wp-nested-patterns] FAILED: ${e.message}`;
+			if (logger.error) logger.error(msg); else logger.log(msg);
+			throw e;
+		} finally {
+			building = false;
+			if (queued) {
+				queued = false;
+				await runBuild('rerun');
+			}
+		}
+	}
+
+	return {
+		name: 'wp-nested-patterns',
+
+		configResolved(config) {
+			logger = config.logger ?? console;
+		},
+
+		async buildStart() {
+			await runBuild('build');
+		},
+
+		configureServer(server) {
+			const { srcRoot } = compiler.options;
+			const watchRoot = tryRealpath(srcRoot);
+			server.watcher.add(srcRoot);
+			server.watcher.on('all', (event, file) => {
+				if (event === 'addDir' || event === 'unlinkDir') return;
+				if (!tryRealpath(file).startsWith(watchRoot)) return;
+				runBuild(`${event} ${file}`).catch(() => {});
+			});
+		},
+	};
+}

package/adapters/webpack.js

@@ -0,0 +1,36 @@
+// Webpack plugin: compiles patterns before every run (and every watch
+// rebuild), and registers the source directory as a context dependency so
+// webpack's own watcher triggers a rebuild when pattern source files change
+// even though nothing in the JS module graph imports them.
+import { createCompiler } from '../src/compiler.js';
+
+export class WpNestedPatternsWebpackPlugin {
+	constructor(options = {}) {
+		this.compiler = createCompiler(options);
+	}
+
+	apply(compiler) {
+		const { webpack } = compiler;
+		const run = async () => {
+			await this.compiler.build();
+		};
+
+		compiler.hooks.beforeRun.tapPromise('WpNestedPatternsWebpackPlugin', run);
+		compiler.hooks.watchRun.tapPromise('WpNestedPatternsWebpackPlugin', run);
+
+		compiler.hooks.thisCompilation.tap('WpNestedPatternsWebpackPlugin', (compilation) => {
+			const addDependency = () => compilation.contextDependencies.add(this.compiler.options.srcRoot);
+			const Compilation = webpack?.Compilation;
+			if (Compilation) {
+				compilation.hooks.processAssets.tap(
+					{ name: 'WpNestedPatternsWebpackPlugin', stage: Compilation.PROCESS_ASSETS_STAGE_ADDITIONAL },
+					addDependency,
+				);
+			} else {
+				compilation.hooks.additionalAssets.tap('WpNestedPatternsWebpackPlugin', addDependency);
+			}
+		});
+	}
+}
+
+export default WpNestedPatternsWebpackPlugin;

package/bin/cli.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// Standalone CLI. Usable directly (`node bin/cli.mjs`, or `npx wp-nested-patterns`)
+// with no build-tool integration required.
+import path from 'node:path';
+import { existsSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { createCompiler } from '../src/compiler.js';
+import { watchCompiler } from '../src/watch.js';
+
+function parseArgs(argv) {
+	const args = { watch: false, src: 'src', dest: '.', config: null };
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === '--watch' || a === '-w') args.watch = true;
+		else if (a === '--src') args.src = argv[++i];
+		else if (a === '--dest') args.dest = argv[++i];
+		else if (a === '--config' || a === '-c') args.config = argv[++i];
+		else if (a === '--help' || a === '-h') args.help = true;
+		else throw new Error(`Unknown argument: ${a}`);
+	}
+	return args;
+}
+
+function printHelp() {
+	console.log(`wp-nested-patterns — compile WordPress block patterns with nested wp:pattern references
+
+Usage:
+  wp-nested-patterns [--src <dir>] [--dest <dir>] [--watch] [--config <file>]
+
+Options:
+  --src <dir>      Source directory containing patterns/templates/parts (default: "src")
+  --dest <dir>      Destination root the compiled dirs are written into (default: ".")
+  --watch, -w       Rebuild on every source change
+  --config, -c      Path to a config file exporting { srcRoot, destRoot, dirs }
+                    (overrides --src/--dest; CLI flags still take precedence over the file)
+  --help, -h        Show this help
+
+If no --config is given, wp-nested-patterns.config.mjs in the current directory
+is loaded automatically when present.`);
+}
+
+async function loadConfigFile(file) {
+	const resolved = path.resolve(file);
+	const mod = await import(pathToFileURL(resolved).href);
+	return mod.default ?? mod;
+}
+
+async function main() {
+	const args = parseArgs(process.argv.slice(2));
+	if (args.help) {
+		printHelp();
+		return;
+	}
+
+	let config = {};
+	const defaultConfigPath = path.resolve('wp-nested-patterns.config.mjs');
+	if (args.config) {
+		config = await loadConfigFile(args.config);
+	} else if (existsSync(defaultConfigPath)) {
+		config = await loadConfigFile(defaultConfigPath);
+	}
+
+	const srcRoot = config.srcRoot ?? path.resolve(args.src);
+	const destRoot = config.destRoot ?? path.resolve(args.dest);
+	const compiler = createCompiler({ srcRoot, destRoot, dirs: config.dirs });
+
+	if (args.watch) {
+		console.log(`Watching ${path.relative(process.cwd(), srcRoot) || '.'}/...`);
+		await watchCompiler(compiler, {
+			onBuild: ({ label, count, ms }) => console.log(`[${label}] compiled ${count} files in ${ms}ms`),
+			onError: (e, label) => console.error(`[${label}] FAILED: ${e.message}`),
+		});
+	} else {
+		const start = Date.now();
+		try {
+			const n = await compiler.build();
+			console.log(`[build] compiled ${n} files in ${Date.now() - start}ms`);
+		} catch (e) {
+			console.error(`[build] FAILED: ${e.message}`);
+			process.exitCode = 1;
+		}
+	}
+}
+
+main().catch((e) => {
+	console.error(e.message);
+	process.exitCode = 1;
+});

package/index.js

@@ -0,0 +1,3 @@
+export { createCompiler } from './src/compiler.js';
+export { watchCompiler } from './src/watch.js';
+export { compileMarkup, resolveBlocks, serializeBlocks, assertBalanced, parseHeader, splitPhp, parse } from './src/core.js';

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@birdinternet/wp-nested-patterns",
+  "version": "0.1.0",
+  "description": "Compile WordPress block patterns that reference each other (wp:pattern) into flat, WP-ready output — as a standalone CLI or a Vite/esbuild/webpack plugin.",
+  "keywords": [
+    "wordpress",
+    "block-patterns",
+    "gutenberg",
+    "vite-plugin",
+    "esbuild-plugin",
+    "webpack-plugin"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/douglas-johnson/wp-nested-patterns.git"
+  },
+  "bugs": {
+    "url": "https://github.com/douglas-johnson/wp-nested-patterns/issues"
+  },
+  "homepage": "https://github.com/douglas-johnson/wp-nested-patterns#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "wp-nested-patterns": "bin/cli.mjs"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./vite": "./adapters/vite.js",
+    "./esbuild": "./adapters/esbuild.js",
+    "./webpack": "./adapters/webpack.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "src",
+    "adapters",
+    "index.js"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@wordpress/block-serialization-default-parser": "^5.45.0",
+    "chokidar": "^4.0.0"
+  },
+  "peerDependencies": {
+    "esbuild": ">=0.19.0",
+    "vite": ">=4.0.0",
+    "webpack": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "esbuild": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    },
+    "webpack": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.0",
+    "vite": "^5.4.20",
+    "webpack": "^5.94.0"
+  }
+}

package/src/compiler.js

@@ -0,0 +1,116 @@
+// Filesystem-facing directory compiler: builds a slug map from pattern
+// source files, then compiles each configured source directory into its
+// destination, resolving `wp:pattern` references via ./core.js.
+import { readFile, writeFile, mkdir, readdir, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { parseHeader, splitPhp, compileMarkup, parse } from './core.js';
+
+const DEFAULT_DIRS = [
+	{ name: 'patterns', extensions: ['.php'], type: 'php', registerSlugs: true },
+	{ name: 'templates', extensions: ['.html'], type: 'html' },
+	{ name: 'parts', extensions: ['.html'], type: 'html' },
+];
+
+function normalizeDirs(dirs) {
+	return dirs.map((dir) => ({
+		type: 'html',
+		registerSlugs: dir.name === 'patterns',
+		...dir,
+	}));
+}
+
+async function listFiles(dir, exts) {
+	if (!existsSync(dir)) return [];
+	const entries = await readdir(dir, { withFileTypes: true });
+	return entries
+		.filter((e) => e.isFile() && exts.some((ext) => e.name.endsWith(ext)))
+		.map((e) => path.join(dir, e.name));
+}
+
+async function loadSlugMap(srcRoot, dirs) {
+	const map = new Map();
+	for (const dir of dirs) {
+		if (!dir.registerSlugs) continue;
+		const files = await listFiles(path.join(srcRoot, dir.name), dir.extensions);
+		for (const file of files) {
+			const src = await readFile(file, 'utf8');
+			const header = parseHeader(src);
+			if (!header.Slug) {
+				throw new Error(`Pattern file ${file} has no Slug header`);
+			}
+			if (map.has(header.Slug)) {
+				const existing = map.get(header.Slug).file;
+				throw new Error(`Duplicate pattern slug "${header.Slug}" in ${file} (already defined in ${existing})`);
+			}
+			const { markup } = splitPhp(src);
+			map.set(header.Slug, { file, blocks: parse(markup) });
+		}
+	}
+	return map;
+}
+
+async function compileFile(srcFile, destFile, type, slugMap) {
+	const src = await readFile(srcFile, 'utf8');
+
+	let header = '';
+	let markup = src;
+	if (type === 'php') {
+		const split = splitPhp(src);
+		header = split.header;
+		markup = split.markup;
+	}
+
+	const compiled = compileMarkup(markup, slugMap, srcFile);
+	await writeFile(destFile, header + compiled);
+}
+
+/**
+ * Creates a compiler bound to a source root, destination root, and set of
+ * directory mappings. Call `.build()` to run one full compile pass.
+ *
+ * @param {object} options
+ * @param {string} options.srcRoot - directory containing the source dirs (e.g. `<theme>/src`)
+ * @param {string} options.destRoot - directory the compiled dirs are written into (e.g. `<theme>`)
+ * @param {Array<{name: string, extensions: string[], type?: 'php'|'html', registerSlugs?: boolean}>} [options.dirs]
+ *   Which subdirectories to compile. `name` is the subdirectory name (under both
+ *   srcRoot and destRoot). `type: 'php'` preserves everything before the first
+ *   `?>` as a passthrough header (e.g. the WP pattern-registration docblock).
+ *   `registerSlugs: true` makes files in that directory available as
+ *   `wp:pattern` reference targets, keyed by their `Slug:` header. Defaults to
+ *   the theme convention: `patterns` (.php, slugged), `templates` (.html), `parts` (.html).
+ */
+export function createCompiler(options) {
+	if (!options || !options.srcRoot || !options.destRoot) {
+		throw new Error('createCompiler requires { srcRoot, destRoot }');
+	}
+	const srcRoot = path.resolve(options.srcRoot);
+	const destRoot = path.resolve(options.destRoot);
+	const dirs = normalizeDirs(options.dirs || DEFAULT_DIRS);
+
+	async function build() {
+		const slugMap = await loadSlugMap(srcRoot, dirs);
+		let count = 0;
+		for (const dir of dirs) {
+			const srcDir = path.join(srcRoot, dir.name);
+			const destDir = path.join(destRoot, dir.name);
+			if (!existsSync(srcDir)) continue;
+			await mkdir(destDir, { recursive: true });
+			// remove stale files in dest that no longer exist in src
+			const srcNames = new Set((await listFiles(srcDir, dir.extensions)).map((f) => path.basename(f)));
+			for (const existing of await listFiles(destDir, dir.extensions)) {
+				if (!srcNames.has(path.basename(existing))) {
+					await rm(existing);
+				}
+			}
+			for (const srcFile of await listFiles(srcDir, dir.extensions)) {
+				const destFile = path.join(destDir, path.basename(srcFile));
+				await compileFile(srcFile, destFile, dir.type, slugMap);
+				count++;
+			}
+		}
+		return count;
+	}
+
+	return { build, options: { srcRoot, destRoot, dirs } };
+}

package/src/core.js

@@ -0,0 +1,202 @@
+// Pure block-markup engine: no filesystem access. Given a slug map of
+// available patterns, resolves `wp:pattern` references by inlining the
+// referenced pattern's blocks at the reference site (recursively, with
+// cycle detection).
+import { parse } from '@wordpress/block-serialization-default-parser';
+
+export { parse };
+
+export function parseHeader(src) {
+	const m = src.match(/\/\*\*([\s\S]*?)\*\//);
+	if (!m) return {};
+	const out = {};
+	for (const line of m[1].split('\n')) {
+		const mm = line.match(/^\s*\*\s*([\w ]+):\s*(.*?)\s*$/);
+		if (mm) out[mm[1].trim()] = mm[2];
+	}
+	return out;
+}
+
+export function splitPhp(src) {
+	const idx = src.indexOf('?>');
+	if (idx === -1) return { header: '', markup: src };
+	return { header: src.slice(0, idx + 2), markup: src.slice(idx + 2) };
+}
+
+function shortName(name) {
+	return name.startsWith('core/') ? name.slice(5) : name;
+}
+
+function serializeAttrs(attrs) {
+	if (!attrs || Object.keys(attrs).length === 0) return '';
+	return ' ' + JSON.stringify(attrs);
+}
+
+function isSelfClosing(block) {
+	return block.innerContent.length === 0 && block.innerBlocks.length === 0;
+}
+
+function serializeBlock(block) {
+	if (!block.blockName) {
+		return block.innerHTML || '';
+	}
+	const name = shortName(block.blockName);
+	const attrs = serializeAttrs(block.attrs);
+	if (isSelfClosing(block)) {
+		return `<!-- wp:${name}${attrs} /-->`;
+	}
+	let out = `<!-- wp:${name}${attrs} -->`;
+	let bIdx = 0;
+	for (const piece of block.innerContent) {
+		if (piece === null) {
+			out += serializeBlock(block.innerBlocks[bIdx++]);
+		} else {
+			out += piece;
+		}
+	}
+	out += `<!-- /wp:${name} -->`;
+	return out;
+}
+
+export function serializeBlocks(blocks) {
+	return blocks.map(serializeBlock).join('');
+}
+
+const VOID_HTML_TAGS = new Set([
+	'area', 'base', 'br', 'col', 'embed', 'hr', 'img',
+	'input', 'link', 'meta', 'source', 'track', 'wbr',
+]);
+
+// Counts non-void HTML tag opens vs. closes in a fragment.
+// A non-zero delta means a wrapper element opens or closes without its pair,
+// which produces malformed block markup that triggers WP block-recovery prompts.
+function htmlTagDelta(html) {
+	const delta = {};
+	for (const m of (html || '').matchAll(/<(\/?)([a-z][a-z0-9-]*)\b[^>]*?(\/?)>/gi)) {
+		const tag = m[2].toLowerCase();
+		if (VOID_HTML_TAGS.has(tag)) continue;
+		if (m[3] === '/') continue;
+		delta[tag] = (delta[tag] || 0) + (m[1] === '/' ? -1 : 1);
+	}
+	return delta;
+}
+
+function collectImbalances(block, trail, issues) {
+	if (!block.blockName) return;
+	const here = trail ? `${trail} > ${block.blockName}` : block.blockName;
+	for (const [tag, n] of Object.entries(htmlTagDelta(block.innerHTML))) {
+		if (n !== 0) issues.push({ path: here, tag, delta: n });
+	}
+	for (const child of block.innerBlocks) collectImbalances(child, here, issues);
+}
+
+export function assertBalanced(blocks, label) {
+	const issues = [];
+	for (const b of blocks) collectImbalances(b, '', issues);
+	if (issues.length === 0) return;
+	const lines = issues.map((i) => {
+		const verb = i.delta > 0
+			? `opened ${i.delta} more time(s) than closed`
+			: `closed ${-i.delta} more time(s) than opened`;
+		return `  ${i.path}: <${i.tag}> ${verb}`;
+	});
+	throw new Error(`malformed block markup in ${label}\n${lines.join('\n')}`);
+}
+
+function deepMerge(target, source) {
+	if (Array.isArray(source)) return source.slice();
+	if (source && typeof source === 'object' && target && typeof target === 'object' && !Array.isArray(target)) {
+		const out = { ...target };
+		for (const k of Object.keys(source)) {
+			out[k] = deepMerge(target[k], source[k]);
+		}
+		return out;
+	}
+	return source;
+}
+
+function firstRealBlockIndex(blocks) {
+	for (let i = 0; i < blocks.length; i++) {
+		if (blocks[i].blockName) return i;
+	}
+	return -1;
+}
+
+function resolvePatternBlock(block, slugMap, chain) {
+	const slug = block.attrs?.slug;
+	if (!slug) {
+		throw new Error(`wp:pattern with no slug (chain: ${chain.join(' → ') || '<root>'})`);
+	}
+	if (chain.includes(slug)) {
+		throw new Error(`Cycle in patterns: ${[...chain, slug].join(' → ')}`);
+	}
+	const target = slugMap.get(slug);
+	if (!target) {
+		throw new Error(`Unresolved wp:pattern slug "${slug}" (chain: ${[...chain, slug].join(' → ')})`);
+	}
+	const resolved = resolveBlocks(target.blocks, slugMap, [...chain, slug]);
+	const overrides = block.attrs?.srcAttributes;
+	if (overrides) {
+		const idx = firstRealBlockIndex(resolved);
+		if (idx === -1) {
+			throw new Error(`srcAttributes targeting pattern "${slug}" with no top-level block`);
+		}
+		resolved[idx] = {
+			...resolved[idx],
+			attrs: deepMerge(resolved[idx].attrs || {}, overrides),
+		};
+	}
+	return resolved;
+}
+
+function resolveInBlock(block, slugMap, chain) {
+	if (!block.blockName) return block;
+	const newInnerBlocks = [];
+	const newInnerContent = [];
+	let bIdx = 0;
+	for (const piece of block.innerContent) {
+		if (piece === null) {
+			const child = block.innerBlocks[bIdx++];
+			if (child.blockName === 'core/pattern') {
+				const resolved = resolvePatternBlock(child, slugMap, chain);
+				for (const r of resolved) {
+					if (r.blockName) {
+						newInnerBlocks.push(r);
+						newInnerContent.push(null);
+					} else {
+						newInnerContent.push(r.innerHTML || '');
+					}
+				}
+			} else {
+				newInnerBlocks.push(resolveInBlock(child, slugMap, chain));
+				newInnerContent.push(null);
+			}
+		} else {
+			newInnerContent.push(piece);
+		}
+	}
+	return { ...block, innerBlocks: newInnerBlocks, innerContent: newInnerContent };
+}
+
+export function resolveBlocks(blocks, slugMap, chain = []) {
+	const out = [];
+	for (const block of blocks) {
+		if (block.blockName === 'core/pattern') {
+			out.push(...resolvePatternBlock(block, slugMap, chain));
+		} else {
+			out.push(resolveInBlock(block, slugMap, chain));
+		}
+	}
+	return out;
+}
+
+// Resolves and re-serializes a single block-markup string against a slug map.
+// Throws if the source or compiled output has malformed (unbalanced) HTML.
+export function compileMarkup(markup, slugMap, label = 'source') {
+	const blocks = parse(markup);
+	assertBalanced(blocks, label);
+	const resolved = resolveBlocks(blocks, slugMap);
+	const compiled = serializeBlocks(resolved);
+	assertBalanced(parse(compiled), `compiled output of ${label}`);
+	return compiled;
+}

package/src/watch.js

@@ -0,0 +1,43 @@
+// Debounced filesystem watcher for a compiler created by ./compiler.js.
+// Serializes rebuilds: a change arriving mid-build is coalesced into a
+// single rerun after the in-flight build finishes, rather than piling up
+// concurrent builds.
+export async function watchCompiler(compiler, { onBuild, onError } = {}) {
+	const { default: chokidar } = await import('chokidar');
+
+	let running = false;
+	let queued = false;
+
+	const runOnce = async (label) => {
+		const start = Date.now();
+		try {
+			const n = await compiler.build();
+			onBuild?.({ label, count: n, ms: Date.now() - start });
+		} catch (e) {
+			onError?.(e, label);
+		}
+	};
+
+	const trigger = async (event, file) => {
+		if (running) {
+			queued = true;
+			return;
+		}
+		running = true;
+		await runOnce(file ? `${event} ${file}` : event);
+		running = false;
+		if (queued) {
+			queued = false;
+			await trigger('rerun');
+		}
+	};
+
+	await trigger('initial');
+
+	const watcher = chokidar.watch(compiler.options.srcRoot, { ignoreInitial: true });
+	watcher.on('all', trigger);
+
+	return {
+		close: () => watcher.close(),
+	};
+}