What?

Adds an experimental widget build pipeline to @wordpress/build, following the same file-based discovery pattern as the existing routes/ support. This enables plugins to define widgets in a widgets/ directory and have them automatically discovered, bundled, and registered as WordPress script modules.

Closes #77576
Needed for #77616
Related: #74542

Why?

WordPress needs a standardized way to build and register widget-type components (self-contained UI units with metadata). This mirrors the pattern already established for routes and blocks, giving plugin authors a consistent file-based convention for widgets.

How?

New file: lib/widget-utils.mjs

• getAllWidgets( rootDir ) — returns widget directory names from widgets/
• getWidgetMetadata( rootDir, widgetName ) — reads and validates widget.json
• getWidgetFiles( widgetDirectory ) — detects render.*, widget.*, and render.scss entries

Modified: lib/build.mjs

• buildWidget( widgetName ) — dual-entry esbuild: render.min.js (ESM, with CSS) + widget.min.js (ESM), both with minified and non-minified variants
• buildAllWidgets() — discovers and builds all widgets in parallel
• generateWidgetRegistry( widgets, replacements ) — generates build/widgets/registry.php
• generateWidgetsPhp( widgets, replacements ) — generates build/widgets.php
• buildAll() — wired widget build phase + PHP generation
• watchMode() — added chokidar watcher for widgets/*/ files

New templates:

• widget-registry.php.template — PHP array with widget metadata
• widget-registration.php.template — registers script modules via wp_register_script_module()

Modified: build.php.template

• Conditionally loads widgets.php

Why two entries per widget?

Widgets use a dual-entry pattern similar to how blocks split block.json and edit.js:

• widget.json — static fields the host can filter, list, or register server-side before any JS loads (name, category, description).
• widget.ts — runtime schema that requires JS: translated strings via __(), typed attribute definitions coupled to the render component's props, example data. The build injects the render_module handle automatically.

This split avoids forcing the host to load every widget's JS just to enumerate what widgets exist, while preserving i18n and TypeScript type-safety for widgets that opt into attributes. See packages/wp-build/README.md → "Why two entries?" for the full rationale and a worked example.

Architecture parallel with routes

routes/              →  widgets/
  {name}/                 {name}/
    package.json            widget.json
    route.tsx               widget.ts
    stage.tsx               render.tsx

buildRoute()         →  buildWidget()
buildAllRoutes()     →  buildAllWidgets()
generateRoutesRegistry() → generateWidgetRegistry()
generateRoutesPhp()  →  generateWidgetsPhp()
getAllRoutes()       →  getAllWidgets()
getRouteMetadata()   →  getWidgetMetadata()
getRouteFiles()      →  getWidgetFiles()

Testing Instructions

This PR ships a minimal widgets/hello-world/ fixture at the repo root that exercises the pipeline end-to-end.

1. Run npm run build (or npx wp-build)
2. Look for 🧩 Phase 4: Building widgets... followed by ✔ Built widget hello-world
3. Verify the generated outputs:
   • build/widgets/hello-world/render.min.js + render.js
   • build/widgets/hello-world/render.min.asset.php
   • build/widgets/registry.php — contains entry with 'name' => 'wordpress/hello-world', 'has_render' => true, 'has_widget' => false
   • build/widgets.php — defines gutenberg_register_widget_modules() and registers wp/widgets/hello-world/render as a script module
   • build/build.php conditionally requires widgets.php
4. Watch mode: run npx wp-build --watch, edit widgets/hello-world/render.tsx, confirm only that widget rebuilds

The widgets/hello-world/ fixture is deliberately minimal and can be removed or replaced by consumers once their own widgets are defined.