@10up/wp-vite-plugins 1.0.0-alpha.3 → 1.0.0-alpha.4

package/LICENSE

@@ -0,0 +1,338 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
+ <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Lesser General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                    GNU GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term "modification".)  Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+  1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+  2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) You must cause the modified files to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    b) You must cause any work that you distribute or publish, that in
+    whole or in part contains or is derived from the Program or any
+    part thereof, to be licensed as a whole at no charge to all third
+    parties under the terms of this License.
+
+    c) If the modified program normally reads commands interactively
+    when run, you must cause it, when started running for such
+    interactive use in the most ordinary way, to print or display an
+    announcement including an appropriate copyright notice and a
+    notice that there is no warranty (or else, saying that you provide
+    a warranty) and that users may redistribute the program under
+    these conditions, and telling the user how to view a copy of this
+    License.  (Exception: if the Program itself is interactive but
+    does not normally print such an announcement, your work based on
+    the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+    a) Accompany it with the complete corresponding machine-readable
+    source code, which must be distributed under the terms of Sections
+    1 and 2 above on a medium customarily used for software interchange; or,
+
+    b) Accompany it with a written offer, valid for at least three
+    years, to give any third party, for a charge no more than your
+    cost of physically performing source distribution, a complete
+    machine-readable copy of the corresponding source code, to be
+    distributed under the terms of Sections 1 and 2 above on a medium
+    customarily used for software interchange; or,
+
+    c) Accompany it with the information you received as to the offer
+    to distribute corresponding source code.  (This alternative is
+    allowed only for noncommercial distribution and only if you
+    received the program in object code or executable form with such
+    an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+  5. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+  6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+  7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+  9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+  10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+                            NO WARRANTY
+
+  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License along
+    with this program; if not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+    Gnomovision version 69, Copyright (C) year name of author
+    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+  `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+  <signature of Moe Ghoul>, 1 April 1989
+  Moe Ghoul, President of Vice
+
+This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.

package/README.md

@@ -7,18 +7,34 @@ A focused set of Vite plugins that handle what WordPress projects actually need:
 ## Install
 
 ```sh
-npm install --save-dev @10up/wp-vite-plugins
+npm install --save-dev @10up/wp-vite-plugins@alpha
 ```
 
-Requires Node ≥ 20.11 and Vite ^8 (Rolldown-powered).
+1.0 is in alpha, published under the `alpha` dist-tag. Requires Node `^22.18.0 || ^24.11.0 || >=26` and Vite 8 (Rolldown-powered).
 
 ### Coming from `10up-toolkit`?
 
-[Migrating a wp-scaffold project from `10up-toolkit`](./docs/migrating-from-toolkit.md) is a step-by-step playbook for converting an existing project — either as a bundler-only swap, or as a full toolchain replacement with Vite+.
+[Migrating from `10up-toolkit`](./docs/migrating-from-toolkit.md) walks a wp-scaffold project over to Vite+ and these plugins, and the [migration field notes](./docs/migration-field-notes.md) collect what real migrations ran into.
 
 ### Vite+ / Rolldown compatibility
 
-The plugins use only Rolldown-implemented plugin APIs, so they work unchanged with [Vite+](https://viteplus.dev) — `vp dev`, `vp build`, and `vp build --mode modules` read the same `vite.config.ts` and produce identical output to plain `vite` commands. The test suite runs under `vp test` (Vitest) as well.
+The plugins use only Rolldown-implemented plugin APIs, so they work unchanged with [Vite+](https://viteplus.dev) — `vp dev` and `vp build` read the same `vite.config.ts` as plain `vite` commands and produce identical output. The test suite runs under `vp test` (Vitest) as well.
+
+In a Vite+ project, pin `vite` to the Vite+ core with an npm override, as `vp migrate` does. Without it, npm installs a second, plain Vite next to Vite+, and `vp` refuses to run against it. The `vite` peer range is `^8.0.0 || ^1.0.0`: Vite 8, or `@voidzero-dev/vite-plus-core` 1.x under the `vite` alias (Vite never had a stable 1.x). Without the second half, npm marks the override invalid and refuses to upgrade a lockfile to a newer Vite+:
+
+```json
+{
+	"devDependencies": {
+		"@10up/wp-vite-plugins": "^1.0.0-alpha.4",
+		"vite-plus": "^1.6.0"
+	},
+	"overrides": {
+		"vite": "npm:@voidzero-dev/vite-plus-core@^1.6.0"
+	}
+}
+```
+
+This repository builds, lints, formats and tests itself with Vite+ (`vp pack`, `vp check`, `vp test`).
 
 ## Quick start
 
@@ -44,20 +60,20 @@ That single call wires up:
 - **`wpBlocks`** — discovers every `block.json`, turns `file:` references into Rollup entries, copies `block.json` + sibling PHP into `dist/`, and emits `blocks-manifest.php` (WP 6.7+).
 - **`wpBlockStyles`** — emits each stylesheet under `blocksStylesDir` as its own CSS entry for selective PHP enqueueing.
 - **`wpCopyAssets`** — copies images / fonts / SVG from `copyAssetsDir` to `dist/`.
-- **`wpAdminPages`** — builds `@wordpress/boot` admin pages from `adminPagesDir` in the module pass (`content` / `route` entries, `loader.js` anchor, per-page `content.css`), and optionally generates the whole `@wordpress/build`-style PHP registration layer.
-- **`wpExternals`** — rewrites `@wordpress/*` imports against `window.wp.*` (or preserves them as ESM in module mode) and emits `<entry>.asset.php` dependency sidecars.
-- **`wpScriptDedupe`** _(auto, script mode)_ — gives every script-mode entry a private copy of the modules it imports, so no entry has to `import` a shared chunk (a classic script can't).
-- **`wpScriptIife`** _(auto)_ — wraps script-mode entries in an IIFE so they enqueue cleanly as classic `<script>` tags, defines `import.meta` away, and fails the build on output that isn't valid as a classic script.
+- **`wpCss`** _(when `css` is set)_ — compiles CSS with Lightning CSS and gives every stylesheet the project's custom media, custom selectors and mixins without an `@import`. Relative `url()`s work in the build and on the dev server.
+- **`wpAdminPages`** — builds `@wordpress/boot` admin pages from `adminPagesDir` as Script Modules (`content` / `route` entries, `loader.js` anchor, per-page `content.css`), and optionally generates the whole `@wordpress/build`-style PHP registration layer.
+- **`wpExternals`** — rewrites `@wordpress/*` imports against `window.wp.*` (or preserves them as ESM for Script Modules) and emits `<entry>.asset.php` dependency sidecars.
+- **`wpScriptDedupe`** _(auto, classic scripts)_ — gives every classic-script entry a private copy of the modules it imports, so no entry has to `import` a shared chunk (a classic script can't).
+- **`wpScriptIife`** _(auto, classic scripts)_ — wraps classic-script entries in an IIFE so they enqueue cleanly as classic `<script>` tags, defines `import.meta` away, and fails the build on output that isn't valid as a classic script.
 - **`wpCleanCssChunks`** _(auto)_ — deletes the empty JS shims Vite leaves next to CSS-only entries.
 - **`wpCssAssetInfo`** _(auto)_ — emits an `.asset.php` sidecar for CSS-only entries, which `wpExternals` can't write for them (there's no JS chunk to walk).
+- **`wpEnvironments`** _(auto)_ — builds classic scripts and Script Modules as two Vite build environments into one `dist/`; see [below](#classic-scripts-and-script-modules).
+- **`wpCssEntryGuard`** _(auto)_ — keeps CSS-only entries whose output is byte-identical (two empty stylesheets, say) from collapsing into one emitted file, which would 404 the other.
 
 ## Wrapper options
 
 ```ts
 wp({
-  // Build mode for all sub-plugins. Default: 'script'.
-  buildType: 'script', // or 'module'
-
   // Top-level shortcuts — pass a directory to enable the plugin.
   blocksDir:       './includes/blocks',
   blocksStylesDir: './assets/css/blocks',
@@ -70,56 +86,48 @@ wp({
   copyAssets:  { pattern: '**/*.{png,svg}' },
   adminPages:  { php: {} }, // `php` turns on PHP generation; see docs/wp-admin-pages.md
   externals: {
-    scriptModuleNamespaces: ['ignite-*'],
+    scriptModuleNamespaces: ['acme-*'],
     additionalExternals:    { myLib: { global: 'MyLib', handle: 'my-lib' } },
+    moduleEntryMatchers:    ['/assets/js/modules/'], // your own Script Module entries
   },
 
   // Helper opt-outs.
-  scriptDedupe:   false, // disable wpScriptDedupe (script mode only)
-  iife:           false, // disable wpScriptIife (script mode only)
+  scriptDedupe:   false, // disable wpScriptDedupe (classic scripts only)
+  iife:           false, // disable wpScriptIife (classic scripts only)
   cleanCssChunks: false, // disable wpCleanCssChunks (always on by default)
 });
 ```
 
 `externals` is always included unless you pass `externals: false`. The other four are included only when their directory option is provided (top-level or nested). See [docs/wp.md](./docs/wp.md) for the full inclusion and option-merging rules.
 
-## Dual-pass builds (script + module)
-
-For projects that ship both classic scripts and Script Modules, dispatch on Vite's `mode`:
+## Classic scripts and Script Modules
 
-```ts
-export default defineConfig(({ mode }) => ({
-  plugins: [
-    wp({
-      buildType: mode === 'modules' ? 'module' : 'script',
-      blocksDir: './includes/blocks',
-    }),
-  ],
-}));
-```
-
-Run the two passes separately: `vite build` (default script mode) and `vite build --mode modules`. The module pass is safe to run unconditionally — when no block declares a `scriptModule` / `viewScriptModule` (and no other module entries are configured), `wpBlocks` turns it into a no-op build instead of letting Rollup error on empty input.
-
-Or let the bundled CLI drive both passes, one command per task — it cleans `dist/` exactly once and keeps the passes from deleting each other's output:
+One `vp build` builds both. `wp()` declares two [Vite build environments](https://vite.dev/guide/api-environment) — `client` for classic scripts (`window.wp.*`, IIFEs) and `modules` for Script Modules (ESM, bare `@wordpress/*` specifiers for WordPress's import map) — and builds them into one `dist/`:
 
 ```jsonc
 {
   "scripts": {
-    "dev": "wp-vite dev", // one dev server, both passes; see below
-    "build": "wp-vite build", // script pass, then module pass; fails fast
-    "watch": "wp-vite watch" // both passes watched in a single process
+    "build": "vp build",          // both environments; dist/ emptied once
+    "watch": "vp build --watch",  // each environment rebuilds on its own
+    "dev": "vp dev"               // one dev server serves both; see below
   }
 }
 ```
 
-→ [Full documentation](./docs/cli.md)
+Block assets go where their `block.json` field says (`viewScriptModule` → `modules`), admin pages are always Script Modules, and your own `build.rollupOptions.input` entries are classic scripts unless their path matches `externals.moduleEntryMatchers`:
+
+```ts
+wp({ externals: { moduleEntryMatchers: ['/assets/js/modules/'] } })
+```
+
+A project with no Script Modules skips the `modules` environment. Because the build is one cache-aware command, `vp run --cache build` replays `dist/` when nothing changed. → [Details](./docs/wp.md#classic-scripts-and-script-modules)
 
 ## Dev server
 
-`wp-vite dev` starts a real Vite dev server for a WordPress install — instant transforms, native ESM in the browser, HMR — and writes the one file PHP needs to know about it:
+`vp dev` starts a real Vite dev server for a WordPress install — instant transforms, native ESM in the browser, HMR — and writes the one file PHP needs to know about it:
 
 ```sh
-wp-vite dev
+vp dev
 ```
 
 ```
@@ -138,7 +146,7 @@ if ( file_exists( __DIR__ . '/dist/dev-server.php' ) ) {
 
 `dev-server.php` is generated by every build (and by the dev server on start). Cold, it costs one `file_exists()`. Hot, it repoints every classic script (`script_loader_src` + a `type="module"` stamp), every Script Module (`script_module_loader_src`, WP 6.5+) and every stylesheet enqueued out of `dist/` at the running server, and enqueues Vite's HMR client. **No other PHP changes** — your registration code doesn't know the difference.
 
-One server handles both passes: a classic entry gets the `window.wp.*` rewrite, a Script Module entry keeps its bare `@wordpress/*` specifiers for WordPress's runtime import map. The plugin is included by `wp()` by default, is `apply: 'serve'`, and costs a build nothing.
+One server handles both kinds of entry: a classic entry gets the `window.wp.*` rewrite, a Script Module entry keeps its bare `@wordpress/*` specifiers for WordPress's runtime import map. The plugin is included by `wp()` by default, is `apply: 'serve'`, and costs a build nothing.
 
 `@vitejs/plugin-react` gets React Fast Refresh for free — no extra config. When the hot file reports the plugin, `dev-server.php` attaches its preamble to the Vite client handle, ahead of every component module.
 
@@ -151,6 +159,7 @@ The wrapper is just sugar. Every plugin is exported on its own for finer control
 ```ts
 import { defineConfig } from 'vite';
 import {
+  wpEnvironments,
   wpBlocks,
   wpBlockStyles,
   wpCopyAssets,
@@ -163,15 +172,18 @@ import {
 
 export default defineConfig({
   plugins: [
-    wpBlocks({ blocksDir: './includes/blocks', buildType: 'script' }),
+    // The `client` + `modules` build environments. Without it only `client`
+    // exists, and Script Module entries never build.
+    wpEnvironments(),
+    wpBlocks({ blocksDir: './includes/blocks' }),
     wpBlockStyles({ blocksStylesDir: './assets/css/blocks' }),
     wpCopyAssets({ copyAssetsDir: './assets' }),
-    // Module pass only — a no-op with buildType: 'script'. Composed by hand,
-    // it needs a matching `wpBuildAssetMatchers` entry on wpExternals.
-    wpAdminPages({ adminPagesDir: './assets/js/admin-pages', buildType: 'module' }),
-    wpExternals({ buildType: 'script' }),
-    // Script mode only, and in this order: dedupe partitions the graph, the
-    // IIFE wrapper vets the result. Composed by hand, wpScriptIife gets no
+    // Composed by hand, it needs a matching `wpBuildAssetMatchers` entry on
+    // wpExternals.
+    wpAdminPages({ adminPagesDir: './assets/js/admin-pages' }),
+    ...wpExternals({ wpBuildAssetMatchers: ['/assets/js/admin-pages/'] }),
+    // Classic scripts only (each applies to `client` alone), in this order:
+    // dedupe partitions the graph, the IIFE wrapper vets the result. Composed by hand, wpScriptIife gets no
     // `globals` map, so Rolldown's runtime `require()` of an external has
     // nothing to resolve against — pass wpExternals' `globalsSink` through
     // both if any dependency reaches an external from CommonJS.
@@ -186,8 +198,8 @@ export default defineConfig({
 
 Two runnable consumer projects live under [`examples/`](./examples/README.md), each with a WordPress Playground blueprint for end-to-end verification:
 
-- [`examples/minimal-block-plugin`](./examples/minimal-block-plugin) — one plugin, one block, single-pass build.
-- [`examples/scaffold-monorepo`](./examples/scaffold-monorepo) — a full [10up/wp-scaffold](https://github.com/10up/wp-scaffold)-style monorepo (classic theme, block theme, mu-plugin) building through npm workspaces, including a dual-pass Script Module build.
+- [`examples/minimal-block-plugin`](./examples/minimal-block-plugin) — one plugin, one block.
+- [`examples/scaffold-monorepo`](./examples/scaffold-monorepo) — a full [10up/wp-scaffold](https://github.com/10up/wp-scaffold)-style monorepo (classic theme, block theme, mu-plugin) building through npm workspaces, including Interactivity API Script Modules and `@wordpress/boot` admin pages.
 
 ## Plugins
 
@@ -215,7 +227,6 @@ Scans `blocksDir` for `block.json` files. For each one:
 | Option | Type | Default | Notes |
 | --- | --- | --- | --- |
 | `blocksDir` | `string` | (required) | Root directory containing `block.json` files. |
-| `buildType` | `'script' \| 'module'` | `'script'` | Which `block.json` fields to discover as entries. |
 | `emitManifest` | `boolean` | `true` | Emit `blocks-manifest.php`. |
 | `skip` | `string[]` | `[]` | Block directory names (relative to `blocksDir`) to skip entirely. |
 
@@ -238,26 +249,27 @@ The sidecar comes in two shapes, chosen per entry, because WordPress core and bo
 
 For every entry, `version` now hashes the chunk code *and* its extracted CSS, and dependencies are unioned across the entry chunk and every chunk it imports, so shared chunks don't lose deps. See the [sidecar reference](./docs/wp-externals.md#the-assetphp-sidecar) and its [breaking-change note](./docs/wp-externals.md#breaking-change-pre-10).
 
-For non-`@wordpress/*` packages, a hardcoded vendor map covers `react`, `react-dom`, `jquery`, `lodash`, `moment`. Pass `additionalExternals` to extend or replace that map.
+For non-`@wordpress/*` packages, a hardcoded vendor map covers `react`, `react-dom`, `jquery`, `lodash`, `lodash-es`, `moment`. Pass `additionalExternals` to extend or replace that map.
 
 **Options**
 
 | Option | Type | Default | Notes |
 | --- | --- | --- | --- |
 | `projectRoot` | `string` | `process.cwd()` | Resolution root for `@wordpress/*` package metadata. |
-| `buildType` | `'script' \| 'module'` | `'script'` | Controls import rewriting strategy. |
 | `externalNamespaces` | `Record<string, ExternalNamespace>` | `{}` | Add classic-script externals for namespaces like `@woo/*`. |
 | `additionalExternals` | `Record<string, { global, handle }>` | (vendor map) | Override the non-scoped vendor externals. |
-| `moduleEntryMatchers` | `string[]` | `[]` | File path substrings that should be treated as module-mode regardless of `buildType`. |
+| `moduleEntryMatchers` | `string[]` | `[]` | Path substrings of Script Module entries: built in `modules` (via `wp()`), served in module mode by the dev server. |
 | `wpBuildAssetMatchers` | `string[]` | `[]` | Entry source-path substrings whose `.asset.php` uses the `@wordpress/build` shape. |
 | `scriptModuleNamespaces` | `string[]` | `[]` | Plugin-local Script Module namespaces (exact or `prefix-*` glob). |
 | `globalsSink` | `Map<string, string>` | — | Out-param, filled with specifier → window global so `wpScriptIife` can shim `require()` for CJS deps. Wired automatically by `wp()`. |
+| `bundle` | `string[]` | `[]` | Bare package names to bundle instead of externalizing, on top of the default (`@wordpress/icons`). |
+| `uninstalledWordPressPackages` | `'bundle' \| 'external'` | `'bundle'` | `'external'` assumes WordPress provides a `@wordpress/*` package that isn't installed. |
 
 ### `wpAdminPages(options)`
 
 → [Full documentation](./docs/wp-admin-pages.md)
 
-Builds [`@wordpress/boot`](https://github.com/WordPress/gutenberg/tree/trunk/packages/boot)-powered admin pages (WP 6.9+ Script Module admin screens) as part of the **module pass**, replacing a separate esbuild pipeline. Every immediate subdirectory of `adminPagesDir` with a `content` entry is a page:
+Builds [`@wordpress/boot`](https://github.com/WordPress/gutenberg/tree/trunk/packages/boot)-powered admin pages (WordPress 7.0+, or the Gutenberg plugin) as Script Modules, in the same `vp build`, replacing a separate esbuild pipeline. Every immediate subdirectory of `adminPagesDir` with a `content` entry is a page:
 
 ```
 dist/modules/<page>/
@@ -272,16 +284,15 @@ dist/modules/<page>/
 
 Entries containing JSX must use `.jsx` / `.tsx` — Vite doesn't parse JSX out of `.js`.
 
-Pass `php: {}` and the plugin also generates the `@wordpress/build`-style PHP layer next to the modules — `build.php`, `constants.php`, `pages.php`, `pages/<slug>/page{,-wp-admin}.php`, `routes.php`, `routes/registry.php` — so a consuming plugin needs no hand-written PHP beyond `require_once __DIR__ . '/dist/build.php';`. Per-page `page.json` covers titles, menu registration, init modules, modes and REST preload. See [the reference](./docs/wp-admin-pages.md#generated-php); `AbstractBootAdminPage` stays a supported alternative.
+Pass `php: {}` and the plugin also emits the `@wordpress/build`-style PHP layer next to the modules — `build.php` (the pages as data) and the `wp-boot/` classes it loads (from [`10up/wp-boot`](../wp-boot)) — so a consuming plugin needs no hand-written PHP beyond `require_once __DIR__ . '/dist/build.php';`. Per-page `page.json` covers titles, menu registration, init modules, modes and REST preload. See [the reference](./docs/wp-admin-pages.md#generated-php); `AbstractBootAdminPage` stays a supported alternative.
 
 **Options**
 
 | Option | Type | Default | Notes |
 | --- | --- | --- | --- |
 | `adminPagesDir` | `string` | (required) | Directory whose immediate subdirectories are pages. |
-| `buildType` | `'script' \| 'module'` | `'script'` | No-op in script mode; pages are Script Modules. |
 | `php` | `WpAdminPagesPhpOptions` | (off) | Presence enables PHP generation (`prefix`, `handlePrefix`, `baseUrl`, `textdomain`). |
-| `projectRoot` | `string` | Vite's `root` | `package.json` supplying the generated version / prefix defaults. |
+| `projectRoot` | `string` | Vite's `root` | Root whose `package.json` supplies the generated PHP's prefix defaults. |
 
 Via `wp({ adminPagesDir })` the pages directory is also fed to `wpExternals`' `wpBuildAssetMatchers` so page sidecars get the `@wordpress/build` shape; set that option yourself when composing the plugins by hand.
 
@@ -296,6 +307,7 @@ Every stylesheet under `blocksStylesDir` becomes a dedicated CSS entry under `di
 | Option | Type | Default | Notes |
 | --- | --- | --- | --- |
 | `blocksStylesDir` | `string` | (required) | Directory of per-block stylesheets. |
+| `outputPrefix` | `string` | `'autoenqueue'` | Directory under `dist/` the stylesheets land in. `'blocks/autoenqueue'` keeps a `10up-toolkit` project's paths. |
 
 ### `wpCopyAssets(options)`
 
@@ -309,19 +321,33 @@ Copies static assets (images, fonts, SVG) from `copyAssetsDir` to `dist/`, prese
 | --- | --- | --- | --- |
 | `copyAssetsDir` | `string` | (required) | Source directory. |
 | `pattern` | `string` | `**/*.{jpg,jpeg,png,gif,webp,avif,ico,svg,eot,ttf,woff,woff2,otf}` | Glob, relative to `copyAssetsDir`. |
-| `buildType` | `'script' \| 'module'` | `'script'` | Only runs in script mode (to avoid double-emission on dual-pass builds). |
+
+### `wpCss(options?)`
+
+→ [Full documentation](./docs/wp-css.md)
+
+Compiles every stylesheet with Lightning CSS, in place of the PostCSS stack `10up-toolkit` ran. The `@custom-media`, `@custom-selector` and `@define-mixin` definitions in the `globals` files reach every stylesheet without an `@import`, and local `@import`s are inlined. Relative `url()`s are kept relative to the built file, and on the dev server they point at the copied file's source. Use it through `wp({ css })`, which also passes `copyAssetsDir`.
+
+**Options**
+
+| Option | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `globals` | `string[]` | `[]` | Globs of the globals files, relative to the Vite root. |
+| `mixins` | `MixinMap \| () => MixinMap` | none | Mixins defined in JS: name → declarations. |
+| `browserslist` | `string \| string[]` | the project's config | The compile targets. |
+| `assetsDir` | `string` | `wp()`'s `copyAssetsDir` | Source of the files copied into `dist/`, for dev-server urls. |
 
 ### `wpScriptDedupe()`
 
 → [Full documentation](./docs/wp-script-dedupe.md)
 
-Duplicates every statically shared module into each script-mode entry (webpack's behavior), so Rolldown never leaves an entry importing a shared chunk — invalid in a classic `<script>`. Also inlines Rolldown's CJS interop runtime and wpExternals' CJS global shims, which are injected too late to partition. Script mode + `vite build` only. No options.
+Duplicates every statically shared module into each classic-script entry (webpack's behavior), so Rolldown never leaves an entry importing a shared chunk — invalid in a classic `<script>`. Also inlines Rolldown's CJS interop runtime and wpExternals' CJS global shims, which are injected too late to partition. `client` environment + build only. No options.
 
 ### `wpScriptIife(options?)`
 
 → [Full documentation](./docs/wp-script-iife.md)
 
-Wraps each script-mode entry chunk in an IIFE in `writeBundle`. Avoids global-scope leaks when WP enqueues bundles as classic `<script>` tags. Injects the `import.meta.url` / `import.meta.resolve` `define` script mode needs, and fails the build — for the whole pass, before anything is written — if a chunk still holds a live `import`/`export` statement or an `import.meta` reference.
+Wraps each classic-script entry chunk in an IIFE in `writeBundle`. Avoids global-scope leaks when WP enqueues bundles as classic `<script>` tags. Injects the `import.meta.url` / `import.meta.resolve` `define` classic scripts need, and fails the build — before any chunk is wrapped — if a chunk still holds a live `import`/`export` statement or an `import.meta` reference.
 
 | Option | Type | Default | Notes |
 | --- | --- | --- | --- |