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

package/dist/index.d.ts

@@ -1,201 +1,246 @@
-import { Plugin } from 'vite';
-
+import { Plugin } from "vite";
 /**
- * Enables generation of the `@wordpress/build`-style PHP layer next to the
- * built modules — `build.php`, `constants.php`, `pages.php`,
- * `pages/<slug>/page{,-wp-admin}.php`, `routes.php` and
- * `routes/registry.php`. A consuming plugin then needs no hand-written PHP
- * beyond `require_once __DIR__ . '/dist/build.php';`.
+ * Name of the PHP bridge's bootstrap, relative to the resolved `build.outDir`.
+ *
+ * Written by *both* halves of this module: `wpDevServerPhp` emits it into every
+ * build so a consumer's `require_once` is never a dead path, and `wpDevServer`
+ * writes the identical bytes on server start so a `dist/` that has never been
+ * built still bridges.
+ */
+export declare const DEV_SERVER_PHP_NAME = "dev-server.php";
+/**
+ * Enables the `@wordpress/build`-style PHP layer next to the built modules:
+ * `build.php` (the pages as data) and the `wp-boot/` classes it
+ * loads. A consuming plugin then needs no hand-written PHP beyond
+ * `require_once __DIR__ . '/dist/build.php';`.
  */
 interface WpAdminPagesPhpOptions {
-    /**
-     * Identifier prefix for every generated function, global and hook.
-     * Default: `wpPlugin.name` from the consumer's package.json, else its
-     * (de-scoped) package name. Dashes are underscored for PHP identifiers;
-     * the result must be a valid PHP identifier fragment.
-     */
-    prefix?: string;
-    /**
-     * Script Module id prefix — route modules are registered as
-     * `<handlePrefix>/routes/<page>/<route>/{content,route}`.
-     * Default: `wpPlugin.handlePrefix`, else `prefix`.
-     */
-    handlePrefix?: string;
-    /**
-     * Raw PHP expression for the URL of the build directory, interpolated
-     * into `constants.php` verbatim. Default `plugin_dir_url( __FILE__ )`
-     * (`build.php` and friends live in the build directory itself).
-     */
-    baseUrl?: string;
-    /** Text domain for the generated `__()` calls. Default `'default'`. */
-    textdomain?: string;
+  /**
+   * Project prefix: names the generated functions and the PHP namespace.
+   * Default: `wpPlugin.name` from the consumer's package.json, else its
+   * (de-scoped) package name. Dashes are underscored for PHP identifiers;
+   * the result must be a valid PHP identifier fragment.
+   */
+  prefix?: string;
+  /**
+   * Script Module id prefix — route modules are registered as
+   * `<handlePrefix>/routes/<page>/<route>/{content,route}`.
+   * Default: `wpPlugin.handlePrefix`, else `prefix`.
+   */
+  handlePrefix?: string;
+  /**
+   * Raw PHP expression for the URL of the build directory, interpolated
+   * into `build.php` verbatim and evaluated on first use. Default
+   * `plugin_dir_url( __FILE__ )` (`build.php` lives in the build directory).
+   */
+  baseUrl?: string;
+  /** Text domain for the menu title's `__()` call. Default `'default'`. */
+  textdomain?: string;
 }
 interface WpAdminPagesOptions {
-    /**
-     * Directory whose immediate subdirectories are pages. A subdirectory is
-     * a page when it contains a `content.{tsx,ts,jsx,js}` entry; a sibling
-     * `route.{tsx,ts,jsx,js}` is picked up when present, as are additional
-     * routes under `<page>/routes/<name>/`.
-     */
-    adminPagesDir: string;
-    /**
-     * Admin pages are Script Modules, so they only build in the module pass.
-     * In `'script'` mode (the default, matching the other plugins) this
-     * plugin contributes nothing.
-     */
-    buildType?: 'script' | 'module';
-    /**
-     * Generate the PHP registration layer. Presence enables it; every key
-     * is optional.
-     */
-    php?: WpAdminPagesPhpOptions;
-    /**
-     * Root whose `package.json` supplies the generated `version` and the
-     * `wpPlugin.name` / `wpPlugin.handlePrefix` defaults. Defaults to Vite's
-     * `root`, else `process.cwd()`.
-     */
-    projectRoot?: string;
+  /**
+   * Directory whose immediate subdirectories are pages. A subdirectory is
+   * a page when it contains a `content.{tsx,ts,jsx,js}` entry; a sibling
+   * `route.{tsx,ts,jsx,js}` is picked up when present, as are additional
+   * routes under `<page>/routes/<name>/`.
+   */
+  adminPagesDir: string;
+  /**
+   * Generate the PHP registration layer. Presence enables it; every key
+   * is optional.
+   */
+  php?: WpAdminPagesPhpOptions;
+  /**
+   * Root whose `package.json` supplies the `wpPlugin.name` /
+   * `wpPlugin.handlePrefix` defaults. Defaults to Vite's `root`, else
+   * `process.cwd()`.
+   */
+  projectRoot?: string;
+}
+/**
+ * Admin pages are Script Modules: they build in the `modules` environment
+ * (see `wpEnvironments`) and contribute nothing to `client`.
+ */
+export declare function wpAdminPages(options: WpAdminPagesOptions): Plugin;
+/** The build environment for classic scripts — Vite's default one. */
+export declare const SCRIPT_ENVIRONMENT = "client";
+/** The build environment for Script Modules. */
+export declare const MODULE_ENVIRONMENT = "modules";
+interface WpEnvironmentsOptions {
+  /**
+   * Substring matchers for entry source paths that are Script Modules — the
+   * same array `wpExternals` takes. An entry of `build.rollupOptions.input`
+   * whose (absolute) source path matches one builds in the `modules`
+   * environment; every other entry builds as a classic script.
+   *
+   * Example: `['/assets/js/modules/']`
+   */
+  moduleEntryMatchers?: string[];
 }
-declare function wpAdminPages(options: WpAdminPagesOptions): Plugin;
-
+export declare function wpEnvironments(options?: WpEnvironmentsOptions): Plugin;
 interface WpBlocksOptions {
-    blocksDir: string;
-    buildType?: 'script' | 'module';
-    /**
-     * Emit `blocks-manifest.php` (returns one PHP array of all block.json
-     * contents). Lets PHP use `wp_register_block_types_from_metadata_collection`
-     * (WP 6.7+) instead of N filesystem reads + JSON parses on every request.
-     * Default: `true`.
-     */
-    emitManifest?: boolean;
-    /**
-     * Block directory names (relative to `blocksDir`) to skip entirely —
-     * neither discovered as entries nor included in the manifest.
-     */
-    skip?: string[];
+  blocksDir: string;
+  /**
+   * Emit `blocks-manifest.php` (returns one PHP array of all block.json
+   * contents). Lets PHP use `wp_register_block_types_from_metadata_collection`
+   * (WP 6.7+) instead of N filesystem reads + JSON parses on every request.
+   * Default: `true`.
+   */
+  emitManifest?: boolean;
+  /**
+   * Block directory names (relative to `blocksDir`) to skip entirely —
+   * neither discovered as entries, copied, nor included in the manifest.
+   */
+  skip?: string[];
 }
-declare function wpBlocks(options: WpBlocksOptions): Plugin;
-
+/**
+ * Each block asset becomes an entry of the environment that builds its kind:
+ * `editorScript`/`script`/`viewScript` and the styles in `client`,
+ * `scriptModule`/`viewScriptModule` in `modules` (see `wpEnvironments`). The
+ * `block.json` copies and the manifest are emitted once, by `client`.
+ */
+export declare function wpBlocks(options: WpBlocksOptions): Plugin;
 interface WpBlockStylesOptions {
-    blocksStylesDir: string;
+  blocksStylesDir: string;
+  /**
+   * Output directory, relative to `outDir`, that every stylesheet lands
+   * under. Default: `'autoenqueue'` (`dist/autoenqueue/core/group.css`).
+   * `10up-toolkit` projects used `'blocks/autoenqueue'`; pass that to keep
+   * their PHP enqueue paths unchanged.
+   */
+  outputPrefix?: string;
 }
-declare function wpBlockStyles(options: WpBlockStylesOptions): Plugin;
-
+export declare function wpBlockStyles(options: WpBlockStylesOptions): Plugin;
 interface WpCopyAssetsOptions {
-    /** Source directory (default: `./assets`). */
-    copyAssetsDir: string;
-    /** Override the glob pattern (relative to `copyAssetsDir`). */
-    pattern?: string;
-    /** Only run during the script pass — module pass would emit duplicates. */
-    buildType?: 'script' | 'module';
+  /** Source directory, e.g. `./assets`. */
+  copyAssetsDir: string;
+  /** Override the glob pattern (relative to `copyAssetsDir`). */
+  pattern?: string;
 }
-declare function wpCopyAssets(options: WpCopyAssetsOptions): Plugin;
-
+export declare function wpCopyAssets(options: WpCopyAssetsOptions): Plugin;
 interface ExternalNamespace {
-    /** Window global path, e.g. `wp` for `@wordpress/*`, `woo` for `@woo/*`. */
-    global: string;
-    /** Script-handle prefix used in `.asset.php`. `wp` → `wp-block-editor`. */
-    handlePrefix: string;
+  /** Window global path, e.g. `wp` for `@wordpress/*`, `woo` for `@woo/*`. */
+  global: string;
+  /** Script-handle prefix used in `.asset.php`. `wp` → `wp-block-editor`. */
+  handlePrefix: string;
 }
 interface WpExternalsOptions {
-    /**
-     * Project root used to resolve `@wordpress/*` (and other) package.jsons.
-     * Defaults to `process.cwd()`. Pass the absolute project root for
-     * deterministic resolution in monorepos / weird CWDs.
-     */
-    projectRoot?: string;
-    /**
-     * Additional namespaces to externalize. The metadata-driven path covers
-     * `@wordpress/*` automatically; this lets you add `woo`, `acme`, etc.
-     * as classic-script externals (no metadata read — global/handle config
-     * only).
-     */
-    externalNamespaces?: Record<string, ExternalNamespace>;
-    /**
-     * Non-scoped vendor externals (`react`, `jquery`, etc.). These don't
-     * carry WP metadata so we keep the hardcoded mapping. Pass `{}` to
-     * disable.
-     */
-    additionalExternals?: Record<string, {
-        global: string;
-        handle: string | null;
-    }>;
-    /**
-     * 'script' (default) rewrites `import { x } from '@wordpress/y'` into
-     * `const { x } = window.wp.y;` so the resulting bundle works as a
-     * classic <script>. `.asset.php` lists `wp-y`-style handles for
-     * `wp_register_script`.
-     *
-     * 'module' leaves ESM imports of Script-Module-eligible packages intact
-     * (resolved at runtime by WP's import map) for use with
-     * `wp_register_script_module` — required for the Interactivity API and
-     * Script Modules generally. `.asset.php` lists those specifiers under
-     * `module_dependencies` and includes `'type' => 'module'`. Script-only
-     * packages (`wpScript`, vendor globals) have no module form, so they're
-     * still rewritten to their `window.*` global with the classic handle
-     * recorded in `dependencies`.
-     */
-    buildType?: 'script' | 'module';
-    /**
-     * Substring matchers for file paths that should *always* be treated as
-     * `module`-mode regardless of the plugin-level `buildType`. Lets a
-     * single Vite dev server (which can only run one global mode at a time)
-     * still serve Script Module entries with their ESM imports intact.
-     *
-     * Example: `['/view.ts', '/view-module.ts', '/view-module.js']`
-     */
-    moduleEntryMatchers?: string[];
-    /**
-     * Substring matchers for entry *source* paths (the entry chunk's
-     * `facadeModuleId`) whose `.asset.php` should use the
-     * `@wordpress/build` shape:
-     *
-     *   'dependencies'        => classic script handles
-     *   'module_dependencies' => array( 'id' => …, 'import' => 'static'|'dynamic' )
-     *
-     * Entries that don't match keep the shape WordPress core reads when it
-     * registers a Script Module from `block.json`
-     * (`register_block_script_module_id()` passes `dependencies` straight
-     * into `wp_register_script_module()`), so module specifiers stay in
-     * `dependencies` there.
-     *
-     * `wp()` wires this automatically for `adminPagesDir`. Set it yourself
-     * when composing plugins by hand.
-     *
-     * Example: `['/assets/js/admin-pages/']`
-     */
-    wpBuildAssetMatchers?: string[];
-    /**
-     * Plugin-local Script Module namespaces — exact names or `prefix-*` globs.
-     * Imports matching `@<ns>/<anything>` are externalized as Script Modules:
-     * the ESM import is preserved (no global rewrite) and the specifier is
-     * recorded in the `.asset.php` dependency list.
-     *
-     * Example: `['ignite-wp-navigation', 'ignite-*']`
-     */
-    scriptModuleNamespaces?: string[];
-    /**
-     * Populated during the build with specifier → window global for every
-     * script-eligible external. `wpScriptIife` uses it to build a `require`
-     * shim for CJS deps, which Rolldown resolves at runtime rather than
-     * through the import rewrite.
-     */
-    globalsSink?: Map<string, string>;
-    /**
-     * Bare package names to **force-bundle**: their externalization is
-     * suppressed and their imports are rewritten to resolve against the
-     * installed package's ESM entry instead.
-     *
-     * The escape hatch for packages whose WP metadata does not match what
-     * WordPress core actually registers. Merges with (never replaces)
-     * `DEFAULT_BUNDLED_PACKAGES`.
-     *
-     * Bare names only — `@wordpress/dataviews/wp` and other subpath entries
-     * throw at config time, because force-bundling is a whole-package verdict.
-     *
-     * Example: `['@wordpress/icons', 'some-lying-package']`
-     */
-    bundle?: string[];
+  /**
+   * Project root used to resolve `@wordpress/*` (and other) package.jsons.
+   * Defaults to `process.cwd()`. Pass the absolute project root for
+   * deterministic resolution in monorepos / weird CWDs.
+   */
+  projectRoot?: string;
+  /**
+   * Additional namespaces to externalize. The metadata-driven path covers
+   * `@wordpress/*` automatically; this lets you add `woo`, `acme`, etc.
+   * as classic-script externals (no metadata read — global/handle config
+   * only).
+   */
+  externalNamespaces?: Record<string, ExternalNamespace>;
+  /**
+   * Non-scoped vendor externals (`react`, `jquery`, etc.). These don't
+   * carry WP metadata so we keep the hardcoded mapping. Pass `{}` to
+   * disable.
+   */
+  additionalExternals?: Record<string, {
+    global: string;
+    handle: string | null;
+  }>;
+  /**
+   * Source paths (substring matchers) of Script Module entries.
+   *
+   * The mode a file is transformed in normally follows the build
+   * environment (see `wpEnvironments`):
+   *
+   *   - `client` rewrites `import { x } from '@wordpress/y'` into
+   *     `const { x } = window.wp.y;` so the bundle works as a classic
+   *     <script>. `.asset.php` lists `wp-y`-style handles for
+   *     `wp_register_script`.
+   *   - `modules` leaves ESM imports of Script-Module-eligible packages
+   *     intact (resolved at runtime by WP's import map) for
+   *     `wp_register_script_module` — required for the Interactivity API and
+   *     Script Modules generally. `.asset.php` lists those specifiers and
+   *     includes `'type' => 'module'`. Script-only packages (`wpScript`,
+   *     vendor globals) have no module form, so they're still rewritten to
+   *     their `window.*` global with the classic handle recorded.
+   *
+   * In a build, `wp()` uses these matchers to send the matching entries of
+   * `build.rollupOptions.input` to the `modules` environment. The dev server
+   * is one environment serving both kinds, so there a file matching one is
+   * transformed in module mode and everything else in script mode;
+   * `wpDevServer` adds every block and admin-page Script Module it
+   * discovers.
+   *
+   * Example: `['/assets/js/modules/', '/view-module.ts']`
+   */
+  moduleEntryMatchers?: string[];
+  /**
+   * Substring matchers for entry *source* paths (the entry chunk's
+   * `facadeModuleId`) whose `.asset.php` should use the
+   * `@wordpress/build` shape:
+   *
+   *   'dependencies'        => classic script handles
+   *   'module_dependencies' => array( 'id' => …, 'import' => 'static'|'dynamic' )
+   *
+   * Entries that don't match keep the shape WordPress core reads when it
+   * registers a Script Module from `block.json`
+   * (`register_block_script_module_id()` passes `dependencies` straight
+   * into `wp_register_script_module()`), so module specifiers stay in
+   * `dependencies` there.
+   *
+   * `wp()` wires this automatically for `adminPagesDir`. Set it yourself
+   * when composing plugins by hand.
+   *
+   * Example: `['/assets/js/admin-pages/']`
+   */
+  wpBuildAssetMatchers?: string[];
+  /**
+   * Plugin-local Script Module namespaces — exact names or `prefix-*` globs.
+   * Imports matching `@<ns>/<anything>` are externalized as Script Modules:
+   * the ESM import is preserved (no global rewrite) and the specifier is
+   * recorded in the `.asset.php` dependency list.
+   *
+   * Example: `['acme-navigation', 'acme-*']`
+   */
+  scriptModuleNamespaces?: string[];
+  /**
+   * What to do with a `@wordpress/*` import whose package is not installed,
+   * so there is no metadata to read.
+   *
+   *   - `'bundle'` (default): leave it to Vite, which bundles it or fails
+   *     with a missing-module error. Install the packages you import.
+   *   - `'external'`: assume WordPress core provides it, the way
+   *     `@wordpress/dependency-extraction-webpack-plugin` (and so
+   *     `10up-toolkit` up to v7) always did. `@wordpress/interactivity` and
+   *     `@wordpress/interactivity-router` become Script Module imports;
+   *     every other package becomes `window.wp.<name>` with a `wp-<name>`
+   *     handle. Packages WordPress does not register, such as
+   *     `@wordpress/icons` and `@wordpress/dataviews`, are never assumed.
+   */
+  uninstalledWordPressPackages?: 'bundle' | 'external';
+  /**
+   * Populated during the build with specifier → window global for every
+   * script-eligible external. `wpScriptIife` uses it to build a `require`
+   * shim for CJS deps, which Rolldown resolves at runtime rather than
+   * through the import rewrite.
+   */
+  globalsSink?: Map<string, string>;
+  /**
+   * Bare package names to **force-bundle**: their externalization is
+   * suppressed and their imports are rewritten to resolve against the
+   * installed package's ESM entry instead.
+   *
+   * The escape hatch for packages whose WP metadata does not match what
+   * WordPress core actually registers. Merges with (never replaces)
+   * `DEFAULT_BUNDLED_PACKAGES`.
+   *
+   * Bare names only — `@wordpress/dataviews/wp` and other subpath entries
+   * throw at config time, because force-bundling is a whole-package verdict.
+   *
+   * Example: `['@wordpress/icons', 'some-lying-package']`
+   */
+  bundle?: string[];
 }
 /**
  * Packages that claim externalizability they don't have. Same rationale as
@@ -210,7 +255,7 @@ interface WpExternalsOptions {
  * enqueue the script at all. (`@wordpress/icons@11.x` dropped `wpScript`, so
  * without this list the behavior depends on which copy the resolver hoists.)
  */
-declare const DEFAULT_BUNDLED_PACKAGES: string[];
+export declare const DEFAULT_BUNDLED_PACKAGES: string[];
 /**
  * Config `resolveExternal` needs to make its verdict, extracted so the
  * resolver can be reused outside `wpExternals()` itself (e.g. a dev server
@@ -218,215 +263,204 @@ declare const DEFAULT_BUNDLED_PACKAGES: string[];
  * option defaults.
  */
 interface ResolveExternalOptions {
-    /** Project root used to resolve `@wordpress/*` package.jsons. */
-    projectRoot: string;
-    /** Vendor external map (`react`, `jquery`, …). Defaults to `DEFAULT_VENDOR`. */
-    vendorExternals?: Record<string, {
-        global: string;
-        handle: string | null;
-    }>;
-    /** Config-driven classic-script namespaces (`@woo/*`, etc.). */
-    externalNamespaces?: Record<string, ExternalNamespace>;
-    /** Script Module namespaces — exact names or `prefix-*` globs. */
-    scriptModuleNamespaces?: string[];
-    /** Bare package names to force-bundle (never externalized). */
-    bundledPackages?: ReadonlySet<string> | string[];
+  /** Project root used to resolve `@wordpress/*` package.jsons. */
+  projectRoot: string;
+  /** Vendor external map (`react`, `jquery`, …). Defaults to `DEFAULT_VENDOR`. */
+  vendorExternals?: Record<string, {
+    global: string;
+    handle: string | null;
+  }>;
+  /** Config-driven classic-script namespaces (`@woo/*`, etc.). */
+  externalNamespaces?: Record<string, ExternalNamespace>;
+  /** Script Module namespaces — exact names or `prefix-*` globs. */
+  scriptModuleNamespaces?: string[];
+  /** Bare package names to force-bundle (never externalized). */
+  bundledPackages?: ReadonlySet<string> | string[];
+  /** See `WpExternalsOptions.uninstalledWordPressPackages`. Default: `'bundle'`. */
+  uninstalledWordPressPackages?: 'bundle' | 'external';
+}
+export declare function wpExternals(options?: WpExternalsOptions): Plugin[];
+interface WpCssOptions {
+  /**
+   * Globs, relative to the Vite root, of the files whose `@custom-media`,
+   * `@custom-selector` and `@define-mixin` definitions every stylesheet can
+   * use. 10up-toolkit read `assets/css/globals/` and `assets/css/mixins/`.
+   */
+  globals?: string[];
+  /**
+   * Mixins defined in JS: name → declarations. `@mixin <name>;` inserts them.
+   * A function is called again whenever the globals are reread.
+   */
+  mixins?: MixinMap | (() => MixinMap);
+  /**
+   * Browserslist query for the compile targets. Default: the project's own
+   * browserslist config, or browserslist's `defaults`.
+   */
+  browserslist?: string | string[];
+  /**
+   * The directory whose files are copied into the output directory, keeping
+   * their paths (`wp()`'s `copyAssetsDir`). On the dev server, a relative
+   * `url()` that points at `<outDir>/images/logo.svg` is served from
+   * `<assetsDir>/images/logo.svg`. `wp()` sets it.
+   */
+  assetsDir?: string;
 }
-declare function wpExternals(options?: WpExternalsOptions): Plugin[];
-
+type MixinMap = Record<string, Record<string, string | number>>;
+export declare function wpCss(options?: WpCssOptions): Plugin[];
 /**
  * Name of the hot file, relative to the resolved `build.outDir`.
  *
  * Exported because the generated PHP bridge has to spell the same name, and a
  * drifting constant here is a silently dead dev server there.
  */
-declare const HOT_FILE_NAME = ".wp-vite-dev.json";
-/**
- * Name of the generated PHP bridge, relative to the resolved `build.outDir`.
- *
- * Written by *both* halves of this module: `wpDevServerPhp` emits it into every
- * build so a consumer's `require_once` is never a dead path, and `wpDevServer`
- * writes the identical bytes on server start so a `dist/` that has never been
- * built still bridges.
- */
-declare const DEV_SERVER_PHP_NAME = "dev-server.php";
+export declare const HOT_FILE_NAME = ".wp-vite-dev.json";
 interface WpDevServerOptions {
-    /** Blocks directory — same value `wpBlocks` gets. Enables block discovery. */
-    blocksDir?: string;
-    /** Per-block stylesheet directory — same value `wpBlockStyles` gets. */
-    blocksStylesDir?: string;
-    /** Admin pages directory — same value `wpAdminPages` gets. */
-    adminPagesDir?: string;
-    /** Block directory names to skip, mirroring `wpBlocks`' `skip`. */
-    skip?: string[];
-    /**
-     * The mode this server's config maps to — the same `buildType` the build
-     * plugins get. Only the entries declared in `build.rollupOptions.input`
-     * need it; blocks and admin pages carry their own verdict from discovery.
-     * Default: `'script'`, which is what a dual-pass consumer's serve-mode
-     * config resolves to.
-     */
-    buildType?: 'script' | 'module';
-    /** Write `blocks-manifest.php` into `outDir`. Default: `true`. */
-    emitManifest?: boolean;
-    /**
-     * Root used to resolve `@wordpress/*` package.jsons during the dependency
-     * scan. Must match `wpExternals`' `projectRoot` or the two disagree about
-     * what is external. Defaults to `process.cwd()`.
-     */
-    projectRoot?: string;
-    /**
-     * The rest of `wpExternals`' externalization config, so the dev scan
-     * reaches the same verdicts the build does. `wp()` forwards these.
-     */
-    externalNamespaces?: ResolveExternalOptions['externalNamespaces'];
-    additionalExternals?: ResolveExternalOptions['vendorExternals'];
-    scriptModuleNamespaces?: string[];
-    bundledPackages?: string[];
-    /**
-     * Live array shared with `wpExternals`' `moduleEntryMatchers`. The plugin
-     * *pushes* every discovered module-pass entry path into it during
-     * `configResolved`, which is what makes one dev server serve both passes
-     * correctly — see the note on `syncModuleEntryMatchers()`.
-     */
-    moduleEntryMatchers?: string[];
-    /**
-     * Entry source paths whose sidecar uses the `@wordpress/build` shape,
-     * mirroring `wpExternals`' option of the same name. `wp()` wires
-     * `adminPagesDir` in automatically.
-     */
-    wpBuildAssetMatchers?: string[];
-    /** Depth limit for the static import walk. Default: 24. */
-    maxScanDepth?: number;
-    /**
-     * Identifier prefix for `dev-server.php`'s functions and script handles.
-     * Defaults to `wpPlugin.name`, else the de-scoped `name`, from the
-     * package.json at Vite's `root` — else `'wp-vite'`.
-     */
-    phpPrefix?: string;
+  /** Blocks directory — same value `wpBlocks` gets. Enables block discovery. */
+  blocksDir?: string;
+  /** Per-block stylesheet directory — same value `wpBlockStyles` gets. */
+  blocksStylesDir?: string;
+  /** Per-block stylesheet output prefix — same value `wpBlockStyles` gets. */
+  blockStylesPrefix?: string;
+  /** Admin pages directory — same value `wpAdminPages` gets. */
+  adminPagesDir?: string;
+  /** Block directory names to skip, mirroring `wpBlocks`' `skip`. */
+  skip?: string[];
+  /** Write `blocks-manifest.php` into `outDir`. Default: `true`. */
+  emitManifest?: boolean;
+  /**
+   * Root used to resolve `@wordpress/*` package.jsons during the dependency
+   * scan. Must match `wpExternals`' `projectRoot` or the two disagree about
+   * what is external. Defaults to `process.cwd()`.
+   */
+  projectRoot?: string;
+  /**
+   * The rest of `wpExternals`' externalization config, so the dev scan
+   * reaches the same verdicts the build does. `wp()` forwards these.
+   */
+  externalNamespaces?: ResolveExternalOptions['externalNamespaces'];
+  additionalExternals?: ResolveExternalOptions['vendorExternals'];
+  scriptModuleNamespaces?: string[];
+  bundledPackages?: string[];
+  uninstalledWordPressPackages?: ResolveExternalOptions['uninstalledWordPressPackages'];
+  /**
+   * Live array shared with `wpExternals`' `moduleEntryMatchers`. An entry of
+   * `build.rollupOptions.input` matching one is served as a Script Module,
+   * as it builds in the `modules` environment. The plugin also *pushes*
+   * every Script Module entry it discovers into it during `configResolved`,
+   * which is what makes one dev server serve both kinds of entry correctly —
+   * see the note on `syncModuleEntryMatchers()`.
+   */
+  moduleEntryMatchers?: string[];
+  /**
+   * Entry source paths whose sidecar uses the `@wordpress/build` shape,
+   * mirroring `wpExternals`' option of the same name. `wp()` wires
+   * `adminPagesDir` in automatically.
+   */
+  wpBuildAssetMatchers?: string[];
+  /** Depth limit for the static import walk. Default: 24. */
+  maxScanDepth?: number;
+  /**
+   * Project prefix for `dev-server.php`: its PHP namespace, script handle,
+   * constant and filter.
+   * Defaults to `wpPlugin.name`, else the de-scoped `name`, from the
+   * package.json at Vite's `root` — else `'wp-vite'`.
+   */
+  phpPrefix?: string;
 }
 /** `wpDevServerPhp`'s options — the build-side half of the bridge. */
 interface WpDevServerPhpOptions {
-    /** Identifier prefix. Same default as `wpDevServer`'s option of the same name. */
-    phpPrefix?: string;
-    /** Root whose package.json supplies the prefix default. Defaults to Vite's `root`. */
-    projectRoot?: string;
+  /** Identifier prefix. Same default as `wpDevServer`'s option of the same name. */
+  phpPrefix?: string;
+  /** Root whose package.json supplies the prefix default. Defaults to Vite's `root`. */
+  projectRoot?: string;
 }
 /** What the hot file contains. Consumed by the generated PHP bridge. */
 interface WpDevServerHotFile {
-    /** Scheme + host + port the browser should fetch assets from. No trailing slash. */
-    origin: string;
-    /** Vite's `base`, with its leading and trailing slash intact (`/` by default). */
-    base: string;
-    /** Names of the plugins in the resolved config that PHP has to react to. */
-    plugins: string[];
+  /** Scheme + host + port the browser should fetch assets from. No trailing slash. */
+  origin: string;
+  /** Vite's `base`, with its leading and trailing slash intact (`/` by default). */
+  base: string;
+  /** Names of the plugins in the resolved config that PHP has to react to. */
+  plugins: string[];
 }
-declare function wpDevServer(options?: WpDevServerOptions): Plugin;
+export declare function wpDevServer(options?: WpDevServerOptions): Plugin;
 /**
- * Emit `dist/dev-server.php` — the build-side half of the bridge.
+ * Emit `dist/dev-server.php` and its classes — the build-side half of the bridge.
  *
  * Its own plugin, `apply: 'build'`, for one reason: the consumer's PHP holds a
  * single unconditional `require_once __DIR__ . '/dist/dev-server.php'`, and
  * that line has to be true of *every* build — a block plugin with no admin
- * pages, a theme with nothing but a stylesheet entry, the module pass of a
- * dual-pass build. Hanging the emission off `wpAdminPages` (which owns the rest
+ * pages, a theme with nothing but a stylesheet entry, a plugin with nothing
+ * but Script Modules. Emitted by the `client` environment only, which every
+ * build has (see `wpEnvironments`). Hanging the emission off `wpAdminPages` (which owns the rest
  * of the generated PHP) or off `wpExternals` (which owns the sidecars the
  * bridge reads) would have made it conditional on something unrelated.
  *
  * The file itself is inert in a built site: nothing writes a hot file next to
  * it, so it returns after one `file_exists()`.
  */
-declare function wpDevServerPhp(options?: WpDevServerPhpOptions): Plugin;
-
+export declare function wpDevServerPhp(options?: WpDevServerPhpOptions): Plugin;
 interface WpOptions {
-    /** Build mode for sub-plugins. Default: `'script'`. */
-    buildType?: 'script' | 'module';
-    blocksDir?: string;
-    blocksStylesDir?: string;
-    copyAssetsDir?: string;
-    adminPagesDir?: string;
-    /**
-     * Per-plugin escape hatches. Pass `false` to disable; pass an object
-     * to merge extra options into the sub-plugin. Nested wins on conflict.
-     */
-    blocks?: Partial<WpBlocksOptions> | false;
-    blockStyles?: Partial<WpBlockStylesOptions> | false;
-    copyAssets?: Partial<WpCopyAssetsOptions> | false;
-    adminPages?: Partial<WpAdminPagesOptions> | false;
-    externals?: WpExternalsOptions | false;
-    /**
-     * The `apply: 'serve'` dev-server bridge — hot file, dev `.asset.php`
-     * sidecars, blocks metadata, and the bare-specifier escape that keeps
-     * Script Module entries servable. Included by default and completely inert
-     * in a build; pass `false` to leave dev alone, or an object to override its
-     * options (the directories and externals config are wired from the
-     * top-level keys automatically).
-     */
-    devServer?: WpDevServerOptions | false;
-    /** Disable the auto-included script-IIFE helper. Default: enabled in script mode. */
-    iife?: false;
-    /**
-     * Disable the auto-included per-entry module duplication. Default: enabled
-     * in script mode. Without it, a module two script entries share becomes a
-     * shared chunk each entry `import`s — invalid as a classic script.
-     */
-    scriptDedupe?: false;
-    /** Disable the auto-included CSS-only-chunk cleanup. Default: always enabled. */
-    cleanCssChunks?: false;
-    /** Disable the auto-included CSS-only-entry `.asset.php` sidecars. Default: always enabled. */
-    cssAssetInfo?: false;
+  blocksDir?: string;
+  blocksStylesDir?: string;
+  copyAssetsDir?: string;
+  adminPagesDir?: string;
+  /**
+   * Per-plugin escape hatches. Pass `false` to disable; pass an object
+   * to merge extra options into the sub-plugin. Nested wins on conflict.
+   */
+  blocks?: Partial<WpBlocksOptions> | false;
+  blockStyles?: Partial<WpBlockStylesOptions> | false;
+  copyAssets?: Partial<WpCopyAssetsOptions> | false;
+  adminPages?: Partial<WpAdminPagesOptions> | false;
+  externals?: WpExternalsOptions | false;
+  /**
+   * The `apply: 'serve'` dev-server bridge — hot file, dev `.asset.php`
+   * sidecars, blocks metadata, and the bare-specifier escape that keeps
+   * Script Module entries servable. Included by default and completely inert
+   * in a build; pass `false` to leave dev alone, or an object to override its
+   * options (the directories and externals config are wired from the
+   * top-level keys automatically).
+   */
+  devServer?: WpDevServerOptions | false;
+  /**
+   * Compile CSS with Lightning CSS instead of PostCSS, with project-wide
+   * globals (custom media, custom selectors, mixins) every stylesheet can use
+   * without importing them. Off unless set; see `wpCss`.
+   */
+  css?: WpCssOptions;
+  /** Disable the auto-included script-IIFE helper (classic scripts only). Default: enabled. */
+  iife?: false;
+  /**
+   * Disable the auto-included per-entry module duplication (classic scripts
+   * only). Default: enabled. Without it, a module two script entries share becomes a
+   * shared chunk each entry `import`s — invalid as a classic script.
+   */
+  scriptDedupe?: false;
+  /** Disable the auto-included CSS-only-chunk cleanup. Default: always enabled. */
+  cleanCssChunks?: false;
+  /** Disable the auto-included CSS-only-entry `.asset.php` sidecars. Default: always enabled. */
+  cssAssetInfo?: false;
+  /**
+   * Disable the auto-included guard that keeps byte-identical CSS entries
+   * from collapsing into one emitted file. Default: always enabled.
+   */
+  cssEntryGuard?: false;
 }
-declare function wp(options?: WpOptions): Plugin[];
-
-declare function wpScriptDedupe(): Plugin;
-
-/**
- * vite-plugin-wp-script-iife
- *
- * Wraps each script-mode entry chunk in an IIFE post-write — esbuild/oxc's
- * minifier would otherwise inline a plain intro/outro IIFE for var-heavy
- * bodies, defeating the global-scope isolation needed when WP enqueues
- * these as classic <script> tags.
- *
- * It is also the gate that guarantees the output *is* a valid classic script:
- * every chunk is parsed before it's wrapped, and one that doesn't compile fails
- * the build instead of shipping a file the browser cannot load. The two causes
- * worth diagnosing by name are a live `import`/`export` statement (a shared
- * chunk Rolldown refused to duplicate) and an `import.meta` reference (Vite's
- * dynamic-import preload helper). The `import.meta` members that helper touches
- * are rewritten to classic-script-safe expressions through an injected
- * `define`, so the failure only fires for cases the define can't reach.
- *
- * Only run this in script mode. Module-mode entries (`wp_register_script_module`)
- * must stay as bare ESM for WP's import map to resolve them at runtime.
- */
-
+export declare function wp(options?: WpOptions): Plugin[];
+export declare function wpScriptDedupe(): Plugin;
 interface WpScriptIifeOptions {
-    /**
-     * Specifier → window global, used to shim `require()` for CJS dependencies
-     * whose `require` Rolldown resolves at runtime rather than through
-     * `wpExternals`' import rewrite.
-     *
-     * `wp()` passes `wpExternals`' `globalsSink` automatically.
-     */
-    globals?: Map<string, string>;
+  /**
+   * Specifier → window global, used to shim `require()` for CJS dependencies
+   * whose `require` Rolldown resolves at runtime rather than through
+   * `wpExternals`' import rewrite.
+   *
+   * `wp()` passes `wpExternals`' `globalsSink` automatically.
+   */
+  globals?: Map<string, string>;
 }
-declare function wpScriptIife(options?: WpScriptIifeOptions): Plugin;
-
-/**
- * vite-plugin-wp-clean-css-chunks
- *
- * Deletes the empty `.js` shim Vite leaves next to a CSS-only entry.
- *
- * Vite's Rollup-driven model treats every entry as a JS module that may
- * pull in CSS via side-effect imports. For an entry whose source IS a CSS
- * file (e.g. each per-block stylesheet produced by wpBlockStyles), Vite
- * still emits a tiny empty `.js` chunk that just imports the `.css`.
- * Useless for WP enqueueing.
- */
-
-declare function wpCleanCssChunks(): Plugin;
-
-declare function wpCssAssetInfo(): Plugin;
-
-export { DEFAULT_BUNDLED_PACKAGES, DEV_SERVER_PHP_NAME, type ExternalNamespace, HOT_FILE_NAME, type WpAdminPagesOptions, type WpAdminPagesPhpOptions, type WpBlockStylesOptions, type WpBlocksOptions, type WpCopyAssetsOptions, type WpDevServerHotFile, type WpDevServerOptions, type WpDevServerPhpOptions, type WpExternalsOptions, type WpOptions, type WpScriptIifeOptions, wp, wpAdminPages, wpBlockStyles, wpBlocks, wpCleanCssChunks, wpCopyAssets, wpCssAssetInfo, wpDevServer, wpDevServerPhp, wpExternals, wpScriptDedupe, wpScriptIife };
+export declare function wpScriptIife(options?: WpScriptIifeOptions): Plugin;
+export declare function wpCleanCssChunks(): Plugin;
+export declare function wpCssAssetInfo(): Plugin;
+export declare function wpCssEntryGuard(): Plugin;
+export type { ExternalNamespace, MixinMap, WpAdminPagesOptions, WpAdminPagesPhpOptions, WpBlockStylesOptions, WpBlocksOptions, WpCopyAssetsOptions, WpCssOptions, WpDevServerHotFile, WpDevServerOptions, WpDevServerPhpOptions, WpEnvironmentsOptions, WpExternalsOptions, WpOptions, WpScriptIifeOptions };