@webikon/webentor-codemods 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Webentor Codemods Changelog
 
+## 0.3.0
+
+- Add the `starter-2.1.1` migration (theme **2.1.0 → 2.1.1**, **Acorn 6 / Laravel
+  13**) — the first **package-scoped** migration (`appliesTo.package:
+  webentor-starter`), selectable by id or `--package webentor-starter`. It does
+  **not** bump `webentor-core`.
+  - `deps.yml` (JSON): rewrites the theme's `composer.json` `roots/acorn` to `^6.0`.
+    This is the complete dependency delta from the 2.1.0 baseline — `roots/acorn` is
+    the only change; `webikon/webentor-core` stays `^0.15` (it already covers the
+    transparent `0.15.1` patch). Scoped to `composer.json` (the project root
+    `composer.json` has no `roots/acorn`), value-is-string guarded, idempotent.
+  - Changelog sync prepends the `2.1.1` block to the project root `changelog.md`
+    (marker `### 2.1.1`) and the theme `web/app/themes/*/changelog.md` (marker
+    `### Version 2.1.1`), matching the coupled starter + theme `2.1.1` bump.
+  - The Acorn 6 `.env` runtime changes (pin `CACHE_PREFIX`/`SESSION_COOKIE`/
+    `REDIS_PREFIX` to preserve caches/sessions; rename `MAIL_ENCRYPTION` →
+    `MAIL_SCHEME`) are a documented manual step (see the migration README).
+
+## 0.2.0
+
+- **New capability — changelog sync.** A migration can now declare a `changelog`
+  block (in `index.json`) that prepends a release's version section to a consumer
+  project's root `changelog.md` and theme `web/app/themes/*/changelog.md`, under the
+  `# … Changelog` H1, so they stay up to date and match the stack. Idempotent (skips
+  if the version heading is already present), additive (never clobbers existing
+  entries), and conservative (missing targets are reported, not created). It's plain
+  Markdown insertion (`lib/changelog.mjs`), not ast-grep. The `0.13.0` migration
+  syncs the `2.0.7` blocks and `0.15.0` syncs the `2.1.0` blocks, so a range run
+  (`run --since …`) accumulates the full history.
+- Add the `0.15.0` migration (webentor-core 0.13 → 0.15 — the **Vite 8 / Rolldown**
+  toolchain move), with two automated rule sets plus one documented manual step:
+  - `deps.yml` (JSON): rewrites the theme's `package.json` + `composer.json` to the
+    0.15.0 baseline — `webentor-core` `^0.15`, `vite` `^8`, `@roots/vite-plugin`
+    `^2.2.0`, `@vitejs/plugin-react` `^6`, `laravel-vite-plugin` `^3`,
+    `@webikon/webentor-configs` `^1.1.0`. This is the complete dependency delta from
+    the 0.13.0 baseline (only the Vite-8 toolchain ranges changed).
+  - `app-glob-vite8.yml` (TS): adds `{ eager: true, query: '?url', import: 'default' }`
+    to the static-asset `import.meta.glob(['../images/**', '../fonts/**'])` in
+    `resources/scripts/app.ts` (a bare glob no longer emits assets under Rolldown).
+    Conservative — only the single-argument asset glob matches; unrelated globs and
+    the already-migrated form are untouched.
+  - The `vite.config.js` WordPress-externals rewrite (now
+    `...wordpressExternals(command)` from `@webikon/webentor-configs/vite`) is too
+    project-specific to codemod safely and is documented as a manual before→after in
+    `migrations/0.15.0/README.md`.
+
 ## 0.1.0
 
 - Initial release of `@webikon/webentor-codemods` — a reusable, ast-grep–powered

package/README.md

@@ -37,23 +37,71 @@ applying, rebuild the theme and clear caches (`wp acorn optimize:clear`).
 
 ## Available migrations
 
-Migrations are **named by the webentor-core version** they bring you to — the id
-*is* the target version, so "run the 0.13.0 codemod" reads literally.
-
-| id | core | what |
+| id | scope | what |
 | --- | --- | --- |
-| `0.13.0` | 0.12 → 0.13 | WP 7.0 iframe editor-asset enqueue change (`app/setup.php`) + the full dependency bump set (`package.json` + `composer.json`) |
+| `0.13.0` | core 0.12 → 0.13 | WP 7.0 iframe editor-asset enqueue change (`app/setup.php`) + the full dependency bump set (`package.json` + `composer.json`) + changelog sync (2.0.7) |
+| `0.15.0` | core 0.13 → 0.15 | Vite 8 / Rolldown: dependency bumps (`package.json` + `composer.json`) + the static-asset `import.meta.glob` fix (`resources/scripts/app.ts`) + changelog sync (2.1.0). The `vite.config.js` externals rewrite is a documented manual step. |
 
 See each migration's `migrations/<id>/README.md` for before/after detail.
 
+### Naming convention
+
+A migration's `id` encodes the **package** it upgrades and the **target version**:
+
+- **webentor-core** migrations use the **bare core version** — `0.13.0`, `0.15.0`.
+  Core is the primary package (it's the default for `run --since`), so "run the
+  0.13.0 codemod" reads literally. These also set `appliesTo.package: "webentor-core"`.
+- **Other packages** use a **`<package>-<version>`** prefix — e.g. `starter-2.1.1`
+  for a webentor-starter-only release that doesn't bump core. These set
+  `appliesTo.package` accordingly (e.g. `"webentor-starter"`).
+
+This keeps the two numbering schemes from colliding (core `0.x` vs starter `2.x`)
+and makes a migration's package obvious from its id.
+
+#### Package-scoped runs
+
+A migration can be **changelog-only / tooling-only** — it needs *either* ast-grep
+`rules` *or* a `changelog` block, not both, so a starter release with no code
+rewrites is valid. Select package-scoped migrations the same way as core ones:
+
+```sh
+# by id (any package)
+pnpm dlx @webikon/webentor-codemods run starter-2.1.1
+
+# by version range — note --package (defaults to webentor-core)
+pnpm dlx @webikon/webentor-codemods run --since 2.1.0 --package webentor-starter --apply
+```
+
+## Changelog sync
+
+Besides code rewrites, a migration can keep a consumer project's **changelogs**
+up to date with the stack. A project generated from the starter has a root
+`changelog.md` and a theme `web/app/themes/<theme>/changelog.md` that mirror the
+Webentor baseline — running a migration prepends that release's version block to
+them (under the `# … Changelog` H1), so they read exactly like the stack's.
+
+- **Idempotent:** if the version heading is already present, the file is skipped.
+- **Additive:** the block is inserted above existing entries; nothing is removed.
+  Project-specific entries you added stay put.
+- **Conservative:** if a target changelog isn't found, it's reported and skipped
+  (never created from scratch).
+- Runs as part of `run <id>` / `run --since …` — dry-run prints the block it would
+  insert; `--apply` writes it. Running a version *range* accumulates each release's
+  block in order.
+
+This is plain Markdown insertion (not ast-grep — headings don't parse cleanly as a
+syntax tree), implemented in `lib/changelog.mjs`.
+
 ## How it's built
 
 ```
 migrations/
-  index.json                     registry (id = version, title, appliesTo range, rule files)
-  <version>/                     e.g. 0.13.0
+  index.json                     registry (id, title, appliesTo {package,from,to}, rules, changelog)
+  <id>/                          e.g. 0.13.0 (core) or starter-2.1.1 (starter)
     rules/*.yml                  ast-grep rewrite rule(s), applied in order; one .yml
                                  may hold several rules as `---`-separated documents
+    changelog/*.md               (optional) version blocks prepended to consumer
+                                 changelogs (root + theme), declared in index.json
     README.md                    what/why + before→after
   __fixtures__/<version>/
     before/  after/              golden project subtrees (drive the tests); each holds
@@ -61,17 +109,27 @@ migrations/
                                  package.json, composer.json
     customized/                  (optional) a subtree that must NOT change (no-op guard)
 bin/webentor-codemods.mjs        the CLI runner (wraps the bundled ast-grep)
+lib/changelog.mjs                the changelog-sync step (plain Markdown insertion)
 ```
 
 ### Adding a future migration
 
-1. Create `migrations/<version>/rules/<rule>.yml` ast-grep rule(s) with a `fix`.
-   Rules can target multiple languages (PHP, JSON, …) — ast-grep dispatches each
-   rule to the files matching its `language`. JSON dependency rules use
+0. Pick an `id` per the naming convention above — bare version for core
+   (`0.16.0`), `<package>-<version>` for anything else (`starter-2.1.1`).
+1. (Optional) Create `migrations/<id>/rules/<rule>.yml` ast-grep rule(s) with a
+   `fix`. Rules can target multiple languages (PHP, JSON, …) — ast-grep dispatches
+   each rule to the files matching its `language`. JSON dependency rules use
    `files:` globs to scope to `package.json` / `composer.json`.
-2. Add `before/` + `after/` (and optional `customized/`) fixture subtrees under
-   `migrations/__fixtures__/<version>/`.
-3. Register it in `migrations/index.json` (`id` = the version, `appliesTo`, `rules`).
+2. (If you added rules) add `before/` + `after/` (and optional `customized/`)
+   fixture subtrees under `migrations/__fixtures__/<id>/`.
+3. (Optional) To sync changelogs, drop the version block(s) in
+   `migrations/<id>/changelog/*.md` and add a `changelog` array to the index entry:
+   `[{ "entry": "changelog/root.md", "target": "changelog.md", "marker": "### <ver>" }, …]`.
+   The `marker` is the block's first heading and is used for the idempotency check.
+   A migration needs *either* `rules` *or* `changelog` — a changelog-only /
+   tooling-only migration (e.g. a starter release with no core bump) is valid.
+4. Register it in `migrations/index.json` (`id`, `appliesTo` {`package`, `from`,
+   `to`}, optional `rules`, optional `changelog`).
 
 The runner and the test suite are generic — no code changes needed. Migrations
 are **idempotent** (re-running is a no-op) and **conservative** (anything that

package/bin/webentor-codemods.mjs

@@ -18,8 +18,9 @@
 import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join, resolve, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { applyChangelogStep } from '../lib/changelog.mjs';
 
 const require = createRequire(import.meta.url);
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
@@ -114,7 +115,10 @@ function runMigration(migration, { targetPath, apply }) {
   const bin = astGrepBin();
   const migDir = join(MIGRATIONS_DIR, migration.id);
   const rules = migration.rules ?? [];
-  if (!rules.length) fail(`migration "${migration.id}" declares no rules`);
+  const changelog = migration.changelog ?? [];
+  if (!rules.length && !changelog.length) {
+    fail(`migration "${migration.id}" declares no rules`);
+  }
 
   console.log(
     `\n▶ ${migration.id}${apply ? ' (apply)' : ' (dry-run — pass --apply to write)'}`,
@@ -134,6 +138,27 @@ function runMigration(migration, { targetPath, apply }) {
       anyError = true;
     }
   }
+
+  // Changelog sync (not an ast-grep rule — prepend version blocks if missing).
+  for (const step of changelog) {
+    const results = applyChangelogStep(migDir, step, { root: targetPath, apply });
+    for (const r of results) {
+      const where = r.status === 'missing' ? r.file : relative(targetPath, r.file) || r.file;
+      if (r.status === 'updated') {
+        console.log(`\nchangelog[${step.marker}] → ${where}${apply ? ' (written)' : ''}:`);
+        console.log(
+          r.preview
+            .split('\n')
+            .map((l) => `   + ${l}`)
+            .join('\n'),
+        );
+      } else if (r.status === 'unchanged') {
+        console.log(`changelog[${step.marker}] → ${where}: already present, skipped`);
+      } else {
+        console.log(`changelog[${step.marker}]: ${where} — ${r.reason} (skipped)`);
+      }
+    }
+  }
   return !anyError;
 }
 

package/lib/changelog.mjs

@@ -0,0 +1,87 @@
+/**
+ * Changelog sync - the one codemod step that isn't an ast-grep rewrite.
+ *
+ * A consumer project inherits its root `changelog.md` and theme `changelog.md`
+ * from the starter, so they are meant to mirror the Webentor baseline changelogs.
+ * This prepends a release's version block to those files (under the H1 heading) so
+ * a consumer's changelog stays up to date, same as the stack.
+ *
+ * Markdown is a poor fit for ast-grep (headings split the marker from inline text),
+ * so this is plain, deterministic string work: insert-if-missing, idempotent,
+ * additive (never clobbers existing entries).
+ */
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Return `existing` with `entryBlock` inserted after the first H1, or `null` if
+ * `marker` (the entry's version heading) is already present (no change).
+ */
+export function syncChangelog(existing, entryBlock, marker) {
+  const wanted = marker.trim();
+  const alreadyThere = existing.split('\n').some((l) => l.trim() === wanted);
+  if (alreadyThere) return null;
+
+  const block = entryBlock.replace(/\n+$/, '');
+  const lines = existing.split('\n');
+  const h1 = lines.findIndex((l) => /^#\s+/.test(l));
+
+  if (h1 === -1) {
+    // No H1: prepend the block at the very top.
+    return block + '\n\n' + existing.replace(/^\n+/, '');
+  }
+  const head = lines.slice(0, h1 + 1).join('\n');
+  const rest = lines.slice(h1 + 1).join('\n').replace(/^\n+/, '');
+  return head + '\n\n' + block + '\n\n' + rest;
+}
+
+/**
+ * Minimal path resolver supporting a whole-segment `*` wildcard (no partial or
+ * recursive globs). Enough for `changelog.md` and `web/app/themes/*\/changelog.md`.
+ * Returns existing paths only.
+ */
+export function resolveTargets(root, pattern) {
+  let dirs = [root];
+  const segs = pattern.split('/').filter(Boolean);
+  segs.forEach((seg, i) => {
+    const last = i === segs.length - 1;
+    const next = [];
+    for (const d of dirs) {
+      if (!existsSync(d)) continue;
+      if (seg === '*') {
+        for (const e of readdirSync(d, { withFileTypes: true })) {
+          if (last ? e.isFile() : e.isDirectory()) next.push(join(d, e.name));
+        }
+      } else {
+        const p = join(d, seg);
+        if (existsSync(p)) next.push(p);
+      }
+    }
+    dirs = next;
+  });
+  return dirs;
+}
+
+/**
+ * Apply one changelog step against `root`. Returns a per-file result list:
+ *   { file, status: 'updated' | 'unchanged' | 'missing', preview? }
+ * Writes only when `apply` is true.
+ */
+export function applyChangelogStep(migrationDir, step, { root, apply }) {
+  const entryPath = join(migrationDir, step.entry);
+  if (!existsSync(entryPath)) {
+    return [{ file: step.target, status: 'missing', reason: 'entry not found: ' + entryPath }];
+  }
+  const entryBlock = readFileSync(entryPath, 'utf8');
+  const targets = resolveTargets(root, step.target);
+  if (!targets.length) {
+    return [{ file: step.target, status: 'missing', reason: 'no matching file in project' }];
+  }
+  return targets.map((file) => {
+    const existing = readFileSync(file, 'utf8');
+    const updated = syncChangelog(existing, entryBlock, step.marker);
+    if (updated === null) return { file, status: 'unchanged' };
+    if (apply) writeFileSync(file, updated);
+    return { file, status: 'updated', preview: entryBlock.replace(/\n+$/, '') };
+  });
+}

package/migrations/0.13.0/README.md

@@ -97,3 +97,14 @@ major (8), `typescript` major (6), `lint-staged` major (17 — needs Node 22).
   0.12 → 0.13 upgrade; adjust by hand if you intentionally run newer.
 
 After applying, run `pnpm install` + `composer update` to refresh the lockfiles.
+
+## 3. Changelog sync
+
+Prepends the `2.0.7` version block to the project's changelogs so they match the
+stack:
+
+- `changelog.md` (project root) ← `changelog/root.md` (marker `### 2.0.7`)
+- `web/app/themes/*/changelog.md` ← `changelog/theme.md` (marker `### Version 2.0.7`)
+
+Idempotent (skipped if the heading is already present) and additive (inserted under
+the `# … Changelog` H1, above existing entries).

package/migrations/0.13.0/changelog/root.md

@@ -0,0 +1,8 @@
+### 2.0.7
+
+- WordPress 7.0 / PHP 8.4 compatibility
+- Allow `roots/wordpress` `^7.0` (constraint widened to `^6.5 || ^7.0`)
+- Bump bundled theme to `2.0.7` (`webentor-core` `^0.13`)
+- Editor assets: move editor canvas styles (`editor.css`, `button.style.css`) from `enqueue_block_editor_assets` to `enqueue_block_assets` (`is_admin()` guarded) so WP 7.0's iframed editor styles the canvas correctly.
+- Update theme dependencies to the 0.13.0 baseline, including majors `@wordpress/components` 35, `@wordpress/icons` 14, `stylelint` 17 (+ `stylelint-config-recommended` 18), `@types/wordpress__block-editor` 15, `prettier-plugin-tailwindcss` 0.8.
+- Existing projects can apply the editor enqueue change **and** the dependency bumps via the `0.13.0` codemod (`pnpm dlx @webikon/webentor-codemods run 0.13.0`).

package/migrations/0.13.0/changelog/theme.md

@@ -0,0 +1,7 @@
+### Version 2.0.7
+
+- Bump `webentor-core` to `^0.13` (WordPress 7.0 / PHP 8.4 block-editor deprecation fixes).
+- Enqueue theme block-editor styles on `enqueue_block_assets` (guarded by `is_admin()`) instead of `enqueue_block_editor_assets`, so WordPress routes them into the editor iframe correctly (fixes "added to the iframe incorrectly" on WP 7.0). Styles remain off the public frontend.
+- Update `@wordpress/*` dev dependencies to latest stable (block-editor/blocks 15.21, components 35, block-library 9.48, i18n 6.21, icons 14, dependency-extraction 6.48), `@10up/block-components` 1.22.2, `@alpinejs/intersect` 3.15.12.
+- Update dev tooling, including majors: `stylelint` 17 + `stylelint-config-recommended` 18, `@types/wordpress__block-editor` 15, `prettier-plugin-tailwindcss` 0.8 (plus `typescript-eslint` 8.61, `prettier` 3.8, `postcss` 8.5, `tailwindcss` 4.3). ESLint 10, React 19, Vite 8, TypeScript 6, lint-staged 17 held back.
+- All theme dependency bumps for 0.13.0 are reproducible in existing projects via `pnpm dlx @webikon/webentor-codemods run 0.13.0`.

package/migrations/0.15.0/README.md

@@ -0,0 +1,130 @@
+# `0.15.0` — upgrade a consumer theme to webentor-core 0.15.0 (Vite 8 / Rolldown)
+
+**Applies to:** consumer themes moving `webentor-core` `0.13.x` → `0.15.0`. This is
+the **Vite 8 / Rolldown** toolchain migration. (Coming from an older baseline? Run
+the `0.13.0` codemod first.)
+
+Run from your project root:
+
+```sh
+pnpm dlx @webikon/webentor-codemods run 0.15.0          # preview (dry-run)
+pnpm dlx @webikon/webentor-codemods run 0.15.0 --apply  # apply
+```
+
+Then apply the **manual `vite.config.js` change** below, reinstall, rebuild, and
+clear caches:
+
+```sh
+# in the theme dir
+pnpm install && composer update
+pnpm build
+wp acorn optimize:clear
+```
+
+This migration has two automated rule sets — a **dependency** bump set
+(`package.json` + `composer.json`) and a **static-asset glob** fix
+(`resources/scripts/app.ts`) — plus one **manual** `vite.config.js` step.
+
+## 1. Dependencies (`rules/deps.yml`, JSON)
+
+Rewrites the theme's dependency ranges to the **0.15.0 baseline**. This is the
+complete delta from the 0.13.0 baseline (theme 2.0.7) — only the Vite-8 toolchain
+ranges and the `webentor-core` bump changed. Each rule matches a dependency by its
+exact key (value-is-string guarded) and is scoped to `package.json` /
+`composer.json` via `files:`.
+
+| manifest | dependency | → range |
+|---|---|---|
+| package.json + composer.json | webentor-core | `^0.15.0` / `^0.15` |
+| package.json | `vite` (major 7→8) | `^8.0.0` |
+| package.json | `@roots/vite-plugin` (major 1→2) | `^2.2.0` |
+| package.json | `@vitejs/plugin-react` (major 5→6) | `^6.0.0` |
+| package.json | `laravel-vite-plugin` (major 2→3) | `^3.0.0` |
+| package.json | `@webikon/webentor-configs` (1.0→1.1, adds the `/vite` export) | `^1.1.0` |
+
+- **Idempotent:** re-running rewrites to the same range → no diff.
+- **Baseline caveat:** the fix pins the 0.15.0 ranges, so a project already *ahead*
+  within a major would be set back to it. Expected for a 0.13 → 0.15 upgrade.
+
+After applying, run `pnpm install` + `composer update` to refresh the lockfiles.
+
+## 2. Static-asset glob (`rules/app-glob-vite8.yml`, TS)
+
+On Vite 7 a bare `import.meta.glob(['../images/**', '../fonts/**'])` registered
+static assets into the build manifest. On Vite 8 / Rolldown a bare glob no longer
+emits them, so `asset()` lookups for images/fonts (e.g. block-preview thumbnails)
+404. The call must become eager and resolve each match to its versioned URL:
+
+```ts
+// before
+import.meta.glob(['../images/**', '../fonts/**']);
+
+// after
+import.meta.glob(['../images/**', '../fonts/**'], {
+  eager: true,
+  query: '?url',
+  import: 'default',
+});
+```
+
+- **Conservative:** only the single-argument asset glob (its array contains an
+  `images`/`fonts` pattern) is matched. The already-migrated two-argument form and
+  any unrelated `import.meta.glob` (e.g. a module glob) are left untouched. A glob
+  with customized paths won't match — migrate it by hand using the above.
+
+## Changelog sync
+
+Prepends the `2.1.0` version block to the project's changelogs so they match the
+stack:
+
+- `changelog.md` (project root) ← `changelog/root.md` (marker `### 2.1.0`)
+- `web/app/themes/*/changelog.md` ← `changelog/theme.md` (marker `### Version 2.1.0`)
+
+Idempotent (skipped if the heading is already present) and additive (inserted under
+the `# … Changelog` H1, above existing entries). If you've customized a changelog,
+your entries are preserved.
+
+## 3. `vite.config.js` — WordPress externals (manual)
+
+This step is **not** codemodded — `vite.config.js` is too project-specific to
+rewrite safely. Apply it by hand. The WordPress externals interop (the
+`@wordpress/*` → `wp.*` / React shims) now lives in `@webikon/webentor-configs/vite`
+as `wordpressExternals(command)`, and the config must become a function of
+`{ command }` so it can pick the dev vs build strategy:
+
+```diff
+  import { v4wp } from '@kucrut/vite-for-wp';
+- import { wp_scripts } from '@kucrut/vite-for-wp/plugins';
+  import { wordpressThemeJson } from '@roots/vite-plugin';
+  import tailwindcss from '@tailwindcss/vite';
+- import react from '@vitejs/plugin-react';
++ import { wordpressExternals } from '@webikon/webentor-configs/vite';
+  import { glob } from 'glob';
+  import { defineConfig, normalizePath } from 'vite';
+
+- export default defineConfig({
++ export default defineConfig(({ command }) => ({
+    base: '/app/themes/<your-theme>/public/build/',
+    // …
+    plugins: [
+      // …
+-     wp_scripts(),
+-     react({ jsxRuntime: 'classic' }),
++     // WordPress externals (@wordpress/* -> wp.*, react -> window.React) — hybrid per
++     // command: roots wordpressPlugin + interop shims for build, kucrut wp_scripts()
++     // for the dev server. See @webikon/webentor-configs/vite.
++     ...wordpressExternals(command),
+      // …
+    ],
+    // …
+- });
++ }));
+```
+
+Reference: the starter theme's `vite.config.js` at theme 2.1.0.
+
+## Relationship to `update-webentor-packages-in-project`
+
+This codemod's `webentor-core` bump overlaps with the
+`update-webentor-packages-in-project` flow; that's intentional — the `0.15.0`
+codemod is the self-contained "bring me to 0.15.0" unit (deps + code changes).

package/migrations/0.15.0/changelog/root.md

@@ -0,0 +1,11 @@
+### 2.1.0
+
+- Bump `webentor-core` to `^0.15` (from `^0.13`). This pulls in the `0.14.0` and `0.14.1` core releases as well:
+  - `0.14.0`: extensible `l-section` background settings + first-class overlay feature (opacity/color), new JS/PHP extension filters, and a fix for the "Hidden" responsive display on sections. Available transparently to consumers via core.
+  - `0.14.1`: frontend `wp-i18n` dependency declared on block frontend scripts (fixes a "wp is not defined" error on front-end slider blocks).
+  - `0.15.0`: Vite 8 / Rolldown build toolchain.
+- **Vite 8 / Rolldown toolchain migration** (requires consumer action):
+  - Theme dependency bumps: `vite` `^8`, `@roots/vite-plugin` `^2.2.0`, `@vitejs/plugin-react` `^6`, `laravel-vite-plugin` `^3`, `@webikon/webentor-configs` `^1.1.0`.
+  - `vite.config.js`: WordPress externals now come from `@webikon/webentor-configs/vite` (`...wordpressExternals(command)`), and `defineConfig` takes a `({ command }) => ({ … })` function so it can pick the dev vs build externals strategy.
+  - `resources/scripts/app.ts`: the static-asset `import.meta.glob(['../images/**', '../fonts/**'])` now needs `{ eager: true, query: '?url', import: 'default' }` — a bare glob no longer emits assets under Rolldown.
+- Existing projects can apply the dependency bumps and the `app.ts` change via the `0.15.0` codemod (`pnpm dlx @webikon/webentor-codemods run 0.15.0`); the `vite.config.js` rewrite is a documented manual step in that codemod's README.

package/migrations/0.15.0/changelog/theme.md

@@ -0,0 +1,8 @@
+### Version 2.1.0
+
+- Bump `webentor-core` to `^0.15` (from `^0.13`), which also brings the `0.14.0` overlay/`l-section` extensibility work and the `0.14.1` frontend `wp-i18n` fix transparently via core.
+- **Vite 8 / Rolldown toolchain migration:**
+  - Dependency bumps: `vite` `^8`, `@roots/vite-plugin` `^2.2.0`, `@vitejs/plugin-react` `^6`, `laravel-vite-plugin` `^3`, `@webikon/webentor-configs` `^1.1.0`.
+  - `vite.config.js`: replace the local `wp_scripts()` + `react()` plugins with `...wordpressExternals(command)` from `@webikon/webentor-configs/vite`, and wrap the config as `defineConfig(({ command }) => ({ … }))`.
+  - `resources/scripts/app.ts`: the static-asset glob now uses `import.meta.glob([...], { eager: true, query: '?url', import: 'default' })` so Rolldown versions images/fonts into the manifest.
+- All theme dependency bumps and the `app.ts` change are reproducible in existing projects via `pnpm dlx @webikon/webentor-codemods run 0.15.0`; apply the `vite.config.js` change by hand (documented in the codemod README).

package/migrations/0.15.0/rules/app-glob-vite8.yml

@@ -0,0 +1,32 @@
+# Vite 8 / Rolldown static-asset glob fix (resources/scripts/app.ts, TS).
+#
+# On Vite 7 a bare `import.meta.glob(['../images/**', '../fonts/**'])` was enough to
+# register static assets into the build manifest. On Vite 8 / Rolldown a bare glob
+# no longer emits them — the call must be eager and resolve each match to its
+# versioned URL, i.e. `{ eager: true, query: '?url', import: 'default' }`. Without
+# this, asset() lookups for images/fonts (e.g. block-preview thumbnails) 404.
+#
+# Matches the single-argument asset glob only (the argument array must contain an
+# `images`/`fonts` pattern), so unrelated `import.meta.glob` calls and the
+# already-migrated two-argument form are left untouched (idempotent + conservative).
+# A customized glob (different paths) won't match — migrate it by hand per the README.
+id: app-asset-glob-vite8
+language: typescript
+files: ['**/resources/scripts/app.ts']
+rule:
+  pattern: import.meta.glob($ARR)
+  has:
+    field: arguments
+    has:
+      kind: array
+      stopBy: end
+      has:
+        kind: string
+        stopBy: end
+        regex: 'images|fonts'
+fix: |-
+  import.meta.glob($ARR, {
+    eager: true,
+    query: '?url',
+    import: 'default',
+  })

package/migrations/0.15.0/rules/deps.yml

@@ -0,0 +1,83 @@
+# Dependency bumps for the webentor-core 0.15.0 upgrade (Vite 8 / Rolldown).
+#
+# Baseline = the 0.13.0 starter (theme 2.0.7). This is the COMPLETE
+# `git diff starter-v2.0.7 -- <theme>/{package,composer}.json` dependency delta
+# to the 0.15.0 baseline — only the Vite-8 toolchain ranges and the webentor-core
+# bump changed; everything else carried over from 0.13.0 unchanged and is therefore
+# absent here (run the 0.13.0 codemod first if coming from an older baseline).
+#
+# Same shape as the 0.13.0 deps rules: one rule per dependency, matched by its
+# exact key (anchored regex) with a value-is-string guard (so a config object that
+# shares a key is never clobbered), rewritten to the 0.15.0 baseline range
+# regardless of the consumer's current value. `files:` scopes npm rules to
+# package.json and the composer rule to composer.json. `name`/`version` are never
+# touched.
+id: deps-roots-vite-plugin
+language: json
+files: ['**/package.json']
+rule:
+  kind: pair
+  all:
+    - has: { field: key, regex: '^"@roots/vite-plugin"$' }
+    - has: { field: value, kind: string }
+fix: '"@roots/vite-plugin": "^2.2.0"'
+---
+id: deps-vitejs-plugin-react
+language: json
+files: ['**/package.json']
+rule:
+  kind: pair
+  all:
+    - has: { field: key, regex: '^"@vitejs/plugin-react"$' }
+    - has: { field: value, kind: string }
+fix: '"@vitejs/plugin-react": "^6.0.0"'
+---
+id: deps-webentor-configs
+language: json
+files: ['**/package.json']
+rule:
+  kind: pair
+  all:
+    - has: { field: key, regex: '^"@webikon/webentor-configs"$' }
+    - has: { field: value, kind: string }
+fix: '"@webikon/webentor-configs": "^1.1.0"'
+---
+id: deps-laravel-vite-plugin
+language: json
+files: ['**/package.json']
+rule:
+  kind: pair
+  all:
+    - has: { field: key, regex: '^"laravel-vite-plugin"$' }
+    - has: { field: value, kind: string }
+fix: '"laravel-vite-plugin": "^3.0.0"'
+---
+id: deps-vite
+language: json
+files: ['**/package.json']
+rule:
+  kind: pair
+  all:
+    - has: { field: key, regex: '^"vite"$' }
+    - has: { field: value, kind: string }
+fix: '"vite": "^8.0.0"'
+---
+id: deps-webentor-core-npm
+language: json
+files: ['**/package.json']
+rule:
+  kind: pair
+  all:
+    - has: { field: key, regex: '^"@webikon/webentor-core"$' }
+    - has: { field: value, kind: string }
+fix: '"@webikon/webentor-core": "^0.15.0"'
+---
+id: deps-webentor-core-composer
+language: json
+files: ['**/composer.json']
+rule:
+  kind: pair
+  all:
+    - has: { field: key, regex: '^"webikon/webentor-core"$' }
+    - has: { field: value, kind: string }
+fix: '"webikon/webentor-core": "^0.15"'