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

package/dist/index.d.ts

@@ -1,194 +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[];
-    /**
-     * 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
@@ -203,79 +255,212 @@ 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[];
-declare function wpExternals(options?: WpExternalsOptions): 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;
-    /** 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;
+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
+ * doing its own static dependency scan) without re-deriving `wpExternals`'
+ * 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[];
+  /** 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 wp(options?: WpOptions): Plugin[];
-
-declare function wpScriptDedupe(): Plugin;
-
+type MixinMap = Record<string, Record<string, string | number>>;
+export declare function wpCss(options?: WpCssOptions): Plugin[];
 /**
- * vite-plugin-wp-script-iife
+ * Name of the hot file, relative to the resolved `build.outDir`.
  *
- * 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.
+ * 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 function wpScriptIife(): Plugin;
-
+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;
+  /** 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;
+}
+/** 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[];
+}
+export declare function wpDevServer(options?: WpDevServerOptions): Plugin;
 /**
- * vite-plugin-wp-clean-css-chunks
+ * Emit `dist/dev-server.php` and its classes — the build-side half of the bridge.
  *
- * Deletes the empty `.js` shim Vite leaves next to a CSS-only entry.
+ * 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, 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.
  *
- * 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.
+ * 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 wpCleanCssChunks(): Plugin;
-
-declare function wpCssAssetInfo(): Plugin;
-
-export { DEFAULT_BUNDLED_PACKAGES, type ExternalNamespace, type WpAdminPagesOptions, type WpAdminPagesPhpOptions, type WpBlockStylesOptions, type WpBlocksOptions, type WpCopyAssetsOptions, type WpExternalsOptions, type WpOptions, wp, wpAdminPages, wpBlockStyles, wpBlocks, wpCleanCssChunks, wpCopyAssets, wpCssAssetInfo, wpExternals, wpScriptDedupe, wpScriptIife };
+export declare function wpDevServerPhp(options?: WpDevServerPhpOptions): Plugin;
+interface WpOptions {
+  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;
+}
+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>;
+}
+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 };