@wordpress/build 0.5.1-next.ba3aee3a2.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+## 0.6.0 (2026-01-16)
+
+### Breaking Changes
+
+- Renamed generated PHP files to avoid `index.php` naming conflicts:
+  - `build/index.php` → `build/build.php`
+  - `build/modules/index.php` → `build/modules/registry.php`
+  - `build/scripts/index.php` → `build/scripts/registry.php`
+  - `build/styles/index.php` → `build/styles/registry.php`
+  - `build/routes/index.php` → `build/routes/registry.php`
+- All generated page functions now include the `{{PREFIX}}` (from `wpPlugin.name`) at the beginning:
+  - `register_my_page_route()` → `my_plugin_register_my_page_route()`
+  - `my_page_render_page()` → `my_plugin_my_page_render_page()`
+  - And similarly for all other page functions
+- Route registration now uses named functions instead of anonymous closures, allowing third-party developers to unhook them
+
 ## 0.4.0 (2025-11-26)
 
 ## 0.3.0 (2025-11-12)

package/README.md

@@ -248,15 +248,17 @@ WP-Admin mode integrates within the standard WordPress admin interface (keeping
 
 ```php
 add_submenu_page(
-	'themes.php',                              // Parent menu
-	__( 'My Page', 'my-plugin' ),             // Page title
-	__( 'My Page', 'my-plugin' ),             // Menu title
-	'edit_theme_options',                      // Capability
-	'my-admin-page-wp-admin',                  // Menu slug (simple)
-	'my_admin_page_wp_admin_render_page'       // Callback from generated PHP
+	'themes.php',                                      // Parent menu
+	__( 'My Page', 'my-plugin' ),                     // Page title
+	__( 'My Page', 'my-plugin' ),                     // Menu title
+	'edit_theme_options',                              // Capability
+	'my-admin-page-wp-admin',                          // Menu slug (simple)
+	'my_plugin_my_admin_page_wp_admin_render_page'     // Callback from generated PHP (prefixed)
 );
 ```
 
+Note: The callback function name is prefixed with your plugin name (from `wpPlugin.name` in root `package.json`). For example, if your plugin name is `my-plugin`, the function will be `my_plugin_my_admin_page_wp_admin_render_page`.
+
 The page slug is `my-admin-page-wp-admin` (your page ID + `-wp-admin`). WordPress routes all requests to this callback, and the JavaScript router handles internal navigation.
 
 **Deep linking with the `p` query parameter:**
@@ -274,7 +276,7 @@ When the page loads, the JavaScript boot system reads the `p` parameter and navi
 Full-page mode takes over the entire admin screen with a custom sidebar:
 
 ```php
-add_menu_page( 'Title', 'Menu', 'capability', 'my-admin-page', 'my_admin_page_render_page', 'icon', 20 );
+add_menu_page( 'Title', 'Menu', 'capability', 'my-admin-page', 'my_plugin_my_admin_page_render_page', 'icon', 20 );
 ```
 
 **Init Modules:**
@@ -364,7 +366,7 @@ The built tool generates several files in the `build/` directory, but the primar
 Make sure to include the generated PHP file in your plugin file.
 
 ```php
-require_once plugin_dir_path( __FILE__ ) . 'build/index.php';
+require_once plugin_dir_path( __FILE__ ) . 'build/build.php';
 ```
 
 ## Routes (Experimental)
@@ -470,7 +472,7 @@ The `canvas()` function controls which canvas is rendered:
 The build system generates:
 - `build/routes/{route-name}/content.js` - Bundled stage/inspector/canvas components
 - `build/routes/{route-name}/route.js` - Bundled lifecycle hooks (if present)
-- `build/routes/index.php` - Route registry data
+- `build/routes/registry.php` - Route registry data
 - `build/routes.php` - Route registration logic
 
 The boot package in Gutenberg will automatically use these routes and make them available.

package/lib/build.mjs

@@ -17,6 +17,7 @@ import rtlcss from 'rtlcss';
 import cssnano from 'cssnano';
 import babel from 'esbuild-plugin-babel';
 import { camelCase } from 'change-case';
+import { NodePackageImporter } from 'sass-embedded';
 
 /**
  * Internal dependencies
@@ -29,6 +30,7 @@ import {
 import {
 	generatePhpFromTemplate,
 	getPhpReplacements,
+	renderTemplateToString,
 } from './php-generator.mjs';
 import { getPackageInfo, getPackageInfoFromFile } from './package-utils.mjs';
 import { createWordpressExternalsPlugin } from './wordpress-externals-plugin.mjs';
@@ -107,26 +109,59 @@ const wordpressExternalsPlugin = createWordpressExternalsPlugin(
 	HANDLE_PREFIX
 );
 
-const styleBundlingPlugins = [
-	// Handle CSS modules (.module.css and .module.scss)
-	sassPlugin( {
-		embedded: true,
-		filter: /\.module\.(css|scss)$/,
-		transform: postcssModules( {
-			generateScopedName: '[name]__[local]__[hash:base64:5]',
+/**
+ * Get SASS options for the given working directory.
+ *
+ * Uses NodePackageImporter from sass-embedded for resolving package imports
+ * (like @wordpress/base-styles) which works with any package manager (npm, pnpm, yarn).
+ *
+ * @param {string} workingDir - The directory where we're working (for NodePackageImporter).
+ * @return {Object} SASS options object with importers and loadPaths.
+ */
+function getSassOptions( workingDir ) {
+	return {
+		importers: [ new NodePackageImporter( workingDir ) ],
+		// loadPaths for resolving @wordpress/base-styles imports and local base-styles imports
+		loadPaths: [
+			// Package's own node_modules (for pnpm isolated deps)
+			path.join( workingDir, 'node_modules' ),
+			// Root node_modules (for npm hoisted deps)
+			path.join( ROOT_DIR, 'node_modules' ),
+			// For local imports like @use "mixins"
+			path.join( PACKAGES_DIR, 'base-styles' ),
+		],
+	};
+}
+
+/**
+ * Create style bundling plugins with the given working directory.
+ *
+ * @param {string} workingDir - The directory where we're working (for NodePackageImporter).
+ * @return {object[]} Array of esbuild plugins for handling CSS/SCSS.
+ */
+function createStyleBundlingPlugins( workingDir ) {
+	const sassOptions = getSassOptions( workingDir );
+	return [
+		// Handle CSS modules (.module.css and .module.scss)
+		sassPlugin( {
+			embedded: true,
+			filter: /\.module\.(css|scss)$/,
+			transform: postcssModules( {
+				generateScopedName: '[name]__[local]__[hash:base64:5]',
+			} ),
+			type: 'style',
+			...sassOptions,
 		} ),
-		type: 'style',
-		loadPaths: [ 'node_modules', path.join( PACKAGES_DIR, 'base-styles' ) ],
-	} ),
-	// Handle regular CSS/SCSS files
-	// Note: .module.css and .module.scss already handled by plugin above
-	sassPlugin( {
-		embedded: true,
-		filter: /\.(css|scss)$/,
-		type: 'style',
-		loadPaths: [ 'node_modules', path.join( PACKAGES_DIR, 'base-styles' ) ],
-	} ),
-];
+		// Handle regular CSS/SCSS files
+		// Note: .module.css and .module.scss already handled by plugin above
+		sassPlugin( {
+			embedded: true,
+			filter: /\.(css|scss)$/,
+			type: 'style',
+			...sassOptions,
+		} ),
+	];
+}
 
 /**
  * Normalize path separators for cross-platform compatibility.
@@ -193,56 +228,36 @@ function transformPhpContent( content, transforms ) {
 function momentTimezoneAliasPlugin() {
 	return {
 		name: 'moment-timezone-alias',
-		async setup( build ) {
-			const { createRequire } = await import( 'module' );
-			const require = createRequire( import.meta.url );
-
-			// Cached paths - resolved lazily on first use
-			let preBuiltBundlePath;
-			let momentTimezoneUtilsPath;
-			const resolvePaths = () => {
-				if ( preBuiltBundlePath ) {
-					return;
-				}
-				preBuiltBundlePath = require.resolve(
-					'moment-timezone/builds/moment-timezone-with-data-1970-2030'
-				);
-				momentTimezoneUtilsPath = require.resolve(
-					'moment-timezone/moment-timezone-utils.js'
-				);
-			};
+		setup( build ) {
+			// Alias path that esbuild will resolve
+			const aliasPath =
+				'moment-timezone/builds/moment-timezone-with-data-1970-2030.js';
 
 			// Redirect main moment-timezone files to pre-built bundle
 			build.onResolve(
-				{ filter: /^moment-timezone\/moment-timezone$/ },
-				() => {
-					resolvePaths();
-					return { path: preBuiltBundlePath };
-				}
-			);
-
-			// For utils, we need to load it but ensure it works with the pre-built bundle.
-			// The utils file tries to require('./') which would load index.js.
-			// We need to make sure it gets the pre-built bundle instead.
-			build.onResolve(
-				{ filter: /^moment-timezone\/moment-timezone-utils$/ },
-				() => {
-					resolvePaths();
-					return { path: momentTimezoneUtilsPath };
-				}
+				{ filter: /^moment-timezone\/moment-timezone\.js$/ },
+				( { importer, resolveDir, kind } ) =>
+					build.resolve( aliasPath, {
+						importer,
+						resolveDir,
+						kind,
+					} )
 			);
 
 			// Intercept the require('./') call inside moment-timezone-utils
 			// and redirect it to the pre-built bundle.
-			build.onResolve( { filter: /^\.\/$/ }, ( args ) => {
-				if (
-					args.importer &&
-					args.importer.includes( 'moment-timezone-utils' )
-				) {
-					resolvePaths();
-					return { path: preBuiltBundlePath };
+			build.onResolve(
+				{ filter: /^\.\/$/ },
+				( { importer, resolveDir, kind } ) => {
+					if ( importer.includes( 'moment-timezone-utils' ) ) {
+						return build.resolve( aliasPath, {
+							importer,
+							resolveDir,
+							kind,
+						} );
+					}
 				}
-			} );
+			);
 		},
 	};
 }
@@ -729,7 +744,7 @@ async function generateModuleRegistrationPhp( modules, replacements ) {
 	await Promise.all( [
 		generatePhpFromTemplate(
 			'module-registry.php.template',
-			path.join( BUILD_DIR, 'modules', 'index.php' ),
+			path.join( BUILD_DIR, 'modules', 'registry.php' ),
 			{ ...replacements, '{{MODULES}}': modulesArray }
 		),
 		generatePhpFromTemplate(
@@ -762,7 +777,7 @@ async function generateScriptRegistrationPhp( scripts, replacements ) {
 	await Promise.all( [
 		generatePhpFromTemplate(
 			'script-registry.php.template',
-			path.join( BUILD_DIR, 'scripts', 'index.php' ),
+			path.join( BUILD_DIR, 'scripts', 'registry.php' ),
 			{ ...replacements, '{{SCRIPTS}}': scriptsArray }
 		),
 		generatePhpFromTemplate(
@@ -810,7 +825,7 @@ async function generateStyleRegistrationPhp( styles, replacements ) {
 	await Promise.all( [
 		generatePhpFromTemplate(
 			'style-registry.php.template',
-			path.join( BUILD_DIR, 'styles', 'index.php' ),
+			path.join( BUILD_DIR, 'styles', 'registry.php' ),
 			{ ...replacements, '{{STYLES}}': stylesArray }
 		),
 		generatePhpFromTemplate(
@@ -822,14 +837,14 @@ async function generateStyleRegistrationPhp( styles, replacements ) {
 }
 
 /**
- * Generate main index.php that loads both modules and scripts.
+ * Generate main build.php that loads both modules and scripts.
  *
  * @param {Record<string, string>} replacements PHP template replacements.
  */
-async function generateMainIndexPhp( replacements ) {
+async function generateMainBuildPhp( replacements ) {
 	await generatePhpFromTemplate(
-		'index.php.template',
-		path.join( BUILD_DIR, 'index.php' ),
+		'build.php.template',
+		path.join( BUILD_DIR, 'build.php' ),
 		replacements
 	);
 }
@@ -862,10 +877,10 @@ async function generateRoutesRegistry( routes, replacements ) {
 		} )
 		.join( ',\n' );
 
-	// Generate single global registry at build/routes/index.php
+	// Generate single global registry at build/routes/registry.php
 	await generatePhpFromTemplate(
 		'route-registry.php.template',
-		path.join( BUILD_DIR, 'routes', 'index.php' ),
+		path.join( BUILD_DIR, 'routes', 'registry.php' ),
 		{ ...replacements, '{{ROUTES}}': routeEntries }
 	);
 }
@@ -883,11 +898,35 @@ async function generateRoutesPhp( routes, replacements ) {
 		return;
 	}
 
-	// Generate routes.php from template
+	// Get unique pages from routes
+	const pages = [ ...new Set( routes.map( ( route ) => route.page ) ) ];
+
+	// Generate page-specific functions for each page
+	const pageFunctionsPromises = pages.map( async ( pageSlug ) => {
+		const pageSlugUnderscore = pageSlug.replace( /-/g, '_' );
+		const pageReplacements = {
+			...replacements,
+			'{{PAGE_SLUG}}': pageSlug,
+			'{{PAGE_SLUG_UNDERSCORE}}': pageSlugUnderscore,
+		};
+		return renderTemplateToString(
+			'routes-page-functions.php.template',
+			pageReplacements
+		);
+	} );
+
+	const pageFunctions = await Promise.all( pageFunctionsPromises );
+	const pageRouteFunctionsCode = pageFunctions.join( '\n' );
+
+	// Generate routes.php from template with injected page functions
 	await generatePhpFromTemplate(
 		'routes-registration.php.template',
 		path.join( BUILD_DIR, 'routes.php' ),
-		{ ...replacements, '{{HANDLE_PREFIX}}': HANDLE_PREFIX }
+		{
+			...replacements,
+			'{{HANDLE_PREFIX}}': HANDLE_PREFIX,
+			'{{PAGE_ROUTE_FUNCTIONS}}': pageRouteFunctionsCode,
+		}
 	);
 }
 
@@ -1092,7 +1131,7 @@ async function transpilePackage( packageName ) {
 	const plugins = [
 		needsEmotionPlugin && emotionPlugin,
 		externalizeAllExceptCssPlugin,
-		...styleBundlingPlugins,
+		...createStyleBundlingPlugins( packageDir ),
 	].filter( Boolean );
 
 	if ( packageJson.main ) {
@@ -1226,10 +1265,7 @@ async function compileStyles( packageName ) {
 				plugins: [
 					sassPlugin( {
 						embedded: true,
-						loadPaths: [
-							'node_modules',
-							path.join( PACKAGES_DIR, 'base-styles' ),
-						],
+						...getSassOptions( packageDir ),
 						async transform( source ) {
 							// Process with autoprefixer for LTR version
 							const ltrResult = await postcss( [
@@ -1332,12 +1368,6 @@ async function buildRoute( routeName ) {
 	// Ensure output directory exists
 	await mkdir( outputDir, { recursive: true } );
 
-	// Copy package.json
-	await copyFile(
-		path.join( routeDir, 'package.json' ),
-		path.join( outputDir, 'package.json' )
-	);
-
 	const files = getRouteFiles( routeDir );
 
 	// Build route.js if it exists
@@ -1414,7 +1444,7 @@ async function buildRoute( routeName ) {
 						[],
 						true // Generate asset file for minified build
 					),
-					...styleBundlingPlugins,
+					...createStyleBundlingPlugins( routeDir ),
 				],
 			} ),
 			esbuild.build( {
@@ -1432,7 +1462,7 @@ async function buildRoute( routeName ) {
 						[],
 						false // Skip asset file for non-minified build
 					),
-					...styleBundlingPlugins,
+					...createStyleBundlingPlugins( routeDir ),
 				],
 			} ),
 		] );
@@ -1635,7 +1665,7 @@ async function buildAll( baseUrlExpression ) {
 		baseUrlExpression
 	);
 	await Promise.all( [
-		generateMainIndexPhp( phpReplacements ),
+		generateMainBuildPhp( phpReplacements ),
 		generateModuleRegistrationPhp( modules, phpReplacements ),
 		generateScriptRegistrationPhp( scripts, phpReplacements ),
 		generateStyleRegistrationPhp( styles, phpReplacements ),
@@ -1644,13 +1674,14 @@ async function buildAll( baseUrlExpression ) {
 		generateRoutesPhp( routes, phpReplacements ),
 		generatePagesPhp( pageData, phpReplacements ),
 	] );
+	console.log( '   ✔ Generated build/build.php' );
 	console.log( '   ✔ Generated build/modules.php' );
-	console.log( '   ✔ Generated build/modules/index.php' );
+	console.log( '   ✔ Generated build/modules/registry.php' );
 	console.log( '   ✔ Generated build/scripts.php' );
-	console.log( '   ✔ Generated build/scripts/index.php' );
+	console.log( '   ✔ Generated build/scripts/registry.php' );
 	console.log( '   ✔ Generated build/styles.php' );
-	console.log( '   ✔ Generated build/styles/index.php' );
-	console.log( '   ✔ Generated build/version.php' );
+	console.log( '   ✔ Generated build/styles/registry.php' );
+	console.log( '   ✔ Generated build/constants.php' );
 	console.log( '   ✔ Generated build/routes.php' );
 	if ( pageData.length > 0 ) {
 		console.log( '   ✔ Generated build/pages.php' );
@@ -1663,7 +1694,6 @@ async function buildAll( baseUrlExpression ) {
 			);
 		}
 	}
-	console.log( '   ✔ Generated build/index.php' );
 
 	const totalTime = Date.now() - startTime;
 	console.log(
@@ -1933,6 +1963,7 @@ async function main() {
 				default: 'plugin_dir_url( __FILE__ )',
 			},
 		},
+		strict: false,
 	} );
 
 	const baseUrlExpression = values[ 'base-url' ];

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/build",
-	"version": "0.5.1-next.ba3aee3a2.0",
+	"version": "0.6.0",
 	"description": "Build tool for WordPress plugins.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -48,7 +48,8 @@
 		"moment-timezone": "^0.5.40",
 		"postcss": "8.4.38",
 		"postcss-modules": "6.0.1",
-		"rtlcss": "4.3.0"
+		"rtlcss": "4.3.0",
+		"sass-embedded": "^1.97.2"
 	},
 	"devDependencies": {
 		"@types/node": "^20.17.10"
@@ -76,5 +77,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "67d2e486fcd40c753591cf911ca0659132f519ca"
+	"gitHead": "50c4c0f51e4797c217946ce42adfaa5eb026f33f"
 }

package/templates/module-registration.php.template

@@ -13,8 +13,8 @@ if ( ! function_exists( '{{PREFIX}}_register_script_modules' ) ) {
 	function {{PREFIX}}_register_script_modules() {
 		// Load build constants
 		$build_constants = require __DIR__ . '/constants.php';
-		$modules_dir = __DIR__ . '/modules';
-		$modules_file = $modules_dir . '/index.php';
+		$modules_dir     = __DIR__ . '/modules';
+		$modules_file    = $modules_dir . '/registry.php';
 
 		if ( ! file_exists( $modules_file ) ) {
 			return;

package/templates/page-wp-admin.php.template

@@ -12,10 +12,10 @@
 
 // Global storage for {{PAGE_SLUG}} routes and menu items
 global ${{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_routes, ${{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_menu_items;
-${{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_routes = array();
+${{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_routes     = array();
 ${{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_menu_items = array();
 
-if ( ! function_exists( 'register_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_route' ) ) {
+if ( ! function_exists( '{{PREFIX}}_register_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_route' ) ) {
 	/**
 	 * Register a route for the {{PAGE_SLUG}}-wp-admin page.
 	 *
@@ -23,7 +23,7 @@ if ( ! function_exists( 'register_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_route' ) ) {
 	 * @param string|null $content_module Script module ID for content (stage/inspector).
 	 * @param string|null $route_module   Script module ID for route lifecycle hooks.
 	 */
-	function register_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_route( $path, $content_module = null, $route_module = null ) {
+	function {{PREFIX}}_register_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_route( $path, $content_module = null, $route_module = null ) {
 		global ${{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_routes;
 
 		$route = array( 'path' => $path );
@@ -38,7 +38,7 @@ if ( ! function_exists( 'register_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_route' ) ) {
 	}
 }
 
-if ( ! function_exists( 'register_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_menu_item' ) ) {
+if ( ! function_exists( '{{PREFIX}}_register_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_menu_item' ) ) {
 	/**
 	 * Register a menu item for the {{PAGE_SLUG}}-wp-admin page.
 	 * Note: Menu items are registered but not displayed in single-page mode.
@@ -48,7 +48,7 @@ if ( ! function_exists( 'register_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_menu_item' )
 	 * @param string $to        Route path to navigate to.
 	 * @param string $parent_id Optional. Parent menu item ID.
 	 */
-	function register_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_menu_item( $id, $label, $to, $parent_id = '' ) {
+	function {{PREFIX}}_register_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_menu_item( $id, $label, $to, $parent_id = '' ) {
 		global ${{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_menu_items;
 
 		$menu_item = array(
@@ -65,36 +65,36 @@ if ( ! function_exists( 'register_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_menu_item' )
 	}
 }
 
-if ( ! function_exists( 'get_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_routes' ) ) {
+if ( ! function_exists( '{{PREFIX}}_get_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_routes' ) ) {
 	/**
 	 * Get all registered routes for the {{PAGE_SLUG}}-wp-admin page.
 	 *
 	 * @return array Array of route objects.
 	 */
-	function get_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_routes() {
+	function {{PREFIX}}_get_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_routes() {
 		global ${{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_routes;
 		return ${{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_routes ?? array();
 	}
 }
 
-if ( ! function_exists( 'get_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_menu_items' ) ) {
+if ( ! function_exists( '{{PREFIX}}_get_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_menu_items' ) ) {
 	/**
 	 * Get all registered menu items for the {{PAGE_SLUG}}-wp-admin page.
 	 *
 	 * @return array Array of menu item objects.
 	 */
-	function get_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_menu_items() {
+	function {{PREFIX}}_get_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_menu_items() {
 		global ${{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_menu_items;
 		return ${{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_menu_items ?? array();
 	}
 }
 
-if ( ! function_exists( '{{PAGE_SLUG_UNDERSCORE}}_wp_admin_preload_data' ) ) {
+if ( ! function_exists( '{{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_preload_data' ) ) {
 	/**
 	 * Preload REST API data for the {{PAGE_SLUG}}-wp-admin page.
 	 * Automatically called during page rendering.
 	 */
-	function {{PAGE_SLUG_UNDERSCORE}}_wp_admin_preload_data() {
+	function {{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_preload_data() {
 		// Define paths to preload - same for all pages
 		$preload_paths = array(
 			'/?_fields=description,gmt_offset,home,name,site_icon,site_icon_url,site_logo,timezone_string,url,page_for_posts,page_on_front,show_on_front',
@@ -120,14 +120,14 @@ if ( ! function_exists( '{{PAGE_SLUG_UNDERSCORE}}_wp_admin_preload_data' ) ) {
 	}
 }
 
-if ( ! function_exists( '{{PAGE_SLUG_UNDERSCORE}}_wp_admin_enqueue_scripts' ) ) {
+if ( ! function_exists( '{{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_enqueue_scripts' ) ) {
 	/**
 	 * Enqueue scripts and styles for the {{PAGE_SLUG}}-wp-admin page.
 	 * Hooked to admin_enqueue_scripts.
 	 *
 	 * @param string $hook_suffix The current admin page.
 	 */
-	function {{PAGE_SLUG_UNDERSCORE}}_wp_admin_enqueue_scripts( $hook_suffix ) {
+	function {{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_enqueue_scripts( $hook_suffix ) {
 		// Check all possible ways this page can be accessed:
 		// 1. Menu page via admin.php?page={{PAGE_SLUG}}-wp-admin (plugin)
 		// 2. Direct file via {{PAGE_SLUG}}.php (Core) - screen ID will be '{{PAGE_SLUG}}'
@@ -148,10 +148,10 @@ if ( ! function_exists( '{{PAGE_SLUG_UNDERSCORE}}_wp_admin_enqueue_scripts' ) )
 		do_action( '{{PAGE_SLUG}}-wp-admin_init' );
 
 		// Preload REST API data
-		{{PAGE_SLUG_UNDERSCORE}}_wp_admin_preload_data();
+		{{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_preload_data();
 
 		// Get all registered routes
-		$routes = get_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_routes();
+		$routes = {{PREFIX}}_get_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_routes();
 
 		// Get boot module asset file for dependencies
 		$asset_file = __DIR__ . '/../../modules/boot/index.min.asset.php';
@@ -221,13 +221,13 @@ if ( ! function_exists( '{{PAGE_SLUG_UNDERSCORE}}_wp_admin_enqueue_scripts' ) )
 	}
 }
 
-if ( ! function_exists( '{{PAGE_SLUG_UNDERSCORE}}_wp_admin_render_page' ) ) {
+if ( ! function_exists( '{{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_render_page' ) ) {
 	/**
 	 * Render the {{PAGE_SLUG}}-wp-admin page.
 	 * Call this function from add_menu_page or add_submenu_page.
 	 * This renders within the normal WordPress admin interface.
 	 */
-	function {{PAGE_SLUG_UNDERSCORE}}_wp_admin_render_page() {
+	function {{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_render_page() {
 		?>
 		<style>
 			/* Critical styles to prevent layout shifts - inlined for immediate application */
@@ -288,5 +288,5 @@ if ( ! function_exists( '{{PAGE_SLUG_UNDERSCORE}}_wp_admin_render_page' ) ) {
 }
 
 // Hook the enqueue function to admin_enqueue_scripts
-add_action( 'admin_enqueue_scripts', '{{PAGE_SLUG_UNDERSCORE}}_wp_admin_enqueue_scripts' );
+add_action( 'admin_enqueue_scripts', '{{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_enqueue_scripts' );
 

package/templates/page.php.template

@@ -9,10 +9,10 @@
 
 // Global storage for {{PAGE_SLUG}} routes and menu items
 global ${{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_routes, ${{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_menu_items;
-${{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_routes = array();
+${{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_routes     = array();
 ${{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_menu_items = array();
 
-if ( ! function_exists( 'register_{{PAGE_SLUG_UNDERSCORE}}_route' ) ) {
+if ( ! function_exists( '{{PREFIX}}_register_{{PAGE_SLUG_UNDERSCORE}}_route' ) ) {
 	/**
 	 * Register a route for the {{PAGE_SLUG}} page.
 	 *
@@ -20,7 +20,7 @@ if ( ! function_exists( 'register_{{PAGE_SLUG_UNDERSCORE}}_route' ) ) {
 	 * @param string|null $content_module Script module ID for content (stage/inspector).
 	 * @param string|null $route_module   Script module ID for route lifecycle hooks.
 	 */
-	function register_{{PAGE_SLUG_UNDERSCORE}}_route( $path, $content_module = null, $route_module = null ) {
+	function {{PREFIX}}_register_{{PAGE_SLUG_UNDERSCORE}}_route( $path, $content_module = null, $route_module = null ) {
 		global ${{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_routes;
 
 		$route = array( 'path' => $path );
@@ -35,7 +35,7 @@ if ( ! function_exists( 'register_{{PAGE_SLUG_UNDERSCORE}}_route' ) ) {
 	}
 }
 
-if ( ! function_exists( 'register_{{PAGE_SLUG_UNDERSCORE}}_menu_item' ) ) {
+if ( ! function_exists( '{{PREFIX}}_register_{{PAGE_SLUG_UNDERSCORE}}_menu_item' ) ) {
 	/**
 	 * Register a menu item for the {{PAGE_SLUG}} page.
 	 *
@@ -45,7 +45,7 @@ if ( ! function_exists( 'register_{{PAGE_SLUG_UNDERSCORE}}_menu_item' ) ) {
 	 * @param string $parent_id   Optional. Parent menu item ID.
 	 * @param string $parent_type Optional. Parent type: 'drilldown' or 'dropdown'.
 	 */
-	function register_{{PAGE_SLUG_UNDERSCORE}}_menu_item( $id, $label, $to, $parent_id = '', $parent_type = '' ) {
+	function {{PREFIX}}_register_{{PAGE_SLUG_UNDERSCORE}}_menu_item( $id, $label, $to, $parent_id = '', $parent_type = '' ) {
 		global ${{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_menu_items;
 
 		$menu_item = array(
@@ -66,36 +66,36 @@ if ( ! function_exists( 'register_{{PAGE_SLUG_UNDERSCORE}}_menu_item' ) ) {
 	}
 }
 
-if ( ! function_exists( 'get_{{PAGE_SLUG_UNDERSCORE}}_routes' ) ) {
+if ( ! function_exists( '{{PREFIX}}_get_{{PAGE_SLUG_UNDERSCORE}}_routes' ) ) {
 	/**
 	 * Get all registered routes for the {{PAGE_SLUG}} page.
 	 *
 	 * @return array Array of route objects.
 	 */
-	function get_{{PAGE_SLUG_UNDERSCORE}}_routes() {
+	function {{PREFIX}}_get_{{PAGE_SLUG_UNDERSCORE}}_routes() {
 		global ${{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_routes;
 		return ${{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_routes ?? array();
 	}
 }
 
-if ( ! function_exists( 'get_{{PAGE_SLUG_UNDERSCORE}}_menu_items' ) ) {
+if ( ! function_exists( '{{PREFIX}}_get_{{PAGE_SLUG_UNDERSCORE}}_menu_items' ) ) {
 	/**
 	 * Get all registered menu items for the {{PAGE_SLUG}} page.
 	 *
 	 * @return array Array of menu item objects.
 	 */
-	function get_{{PAGE_SLUG_UNDERSCORE}}_menu_items() {
+	function {{PREFIX}}_get_{{PAGE_SLUG_UNDERSCORE}}_menu_items() {
 		global ${{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_menu_items;
 		return ${{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_menu_items ?? array();
 	}
 }
 
-if ( ! function_exists( '{{PAGE_SLUG_UNDERSCORE}}_preload_data' ) ) {
+if ( ! function_exists( '{{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_preload_data' ) ) {
 	/**
 	 * Preload REST API data for the {{PAGE_SLUG}} page.
 	 * Automatically called during page rendering.
 	 */
-	function {{PAGE_SLUG_UNDERSCORE}}_preload_data() {
+	function {{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_preload_data() {
 		// Define paths to preload - same for all pages
 		$preload_paths = array(
 			'/?_fields=description,gmt_offset,home,name,site_icon,site_icon_url,site_logo,timezone_string,url,page_for_posts,page_on_front,show_on_front',
@@ -121,12 +121,12 @@ if ( ! function_exists( '{{PAGE_SLUG_UNDERSCORE}}_preload_data' ) ) {
 	}
 }
 
-if ( ! function_exists( '{{PAGE_SLUG_UNDERSCORE}}_render_page' ) ) {
+if ( ! function_exists( '{{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_render_page' ) ) {
 	/**
 	 * Render the {{PAGE_SLUG}} page.
 	 * Call this function from add_menu_page or add_submenu_page.
 	 */
-	function {{PAGE_SLUG_UNDERSCORE}}_render_page() {
+	function {{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_render_page() {
 		// Load build constants
 		$build_constants = require __DIR__ . '/../../constants.php';
 
@@ -153,11 +153,11 @@ if ( ! function_exists( '{{PAGE_SLUG_UNDERSCORE}}_render_page' ) ) {
 		}
 
 		// Preload REST API data
-		{{PAGE_SLUG_UNDERSCORE}}_preload_data();
+		{{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_preload_data();
 
 		// Get all registered routes and menu items
-		$menu_items = get_{{PAGE_SLUG_UNDERSCORE}}_menu_items();
-		$routes = get_{{PAGE_SLUG_UNDERSCORE}}_routes();
+		$menu_items = {{PREFIX}}_get_{{PAGE_SLUG_UNDERSCORE}}_menu_items();
+		$routes = {{PREFIX}}_get_{{PAGE_SLUG_UNDERSCORE}}_routes();
 
 		// Get boot module asset file for dependencies
 		$asset_file = __DIR__ . '/../../modules/boot/index.min.asset.php';
@@ -312,19 +312,19 @@ if ( ! function_exists( '{{PAGE_SLUG_UNDERSCORE}}_render_page' ) ) {
 	}
 }
 
-if ( ! function_exists( '{{PAGE_SLUG_UNDERSCORE}}_intercept_render' ) ) {
+if ( ! function_exists( '{{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_intercept_render' ) ) {
 	/**
 	 * Intercept admin_init to render the page early.
 	 * This bypasses the default WordPress admin template.
 	 */
-	function {{PAGE_SLUG_UNDERSCORE}}_intercept_render() {
+	function {{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_intercept_render() {
 		// phpcs:ignore WordPress.Security.NonceVerification.Recommended
 		if ( isset( $_GET['page'] ) && '{{PAGE_SLUG}}' === $_GET['page'] ) {
-			{{PAGE_SLUG_UNDERSCORE}}_render_page();
+			{{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_render_page();
 			exit;
 		}
 	}
 }
 
 // Hook the interceptor to admin_init
-add_action( 'admin_init', '{{PAGE_SLUG_UNDERSCORE}}_intercept_render' );
+add_action( 'admin_init', '{{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_intercept_render' );

package/templates/routes-page-functions.php.template

@@ -0,0 +1,22 @@
+// Page-specific route registration functions for {{PAGE_SLUG}}
+if ( ! function_exists( '{{PREFIX}}_register_{{PAGE_SLUG_UNDERSCORE}}_page_routes' ) ) {
+	/**
+	 * Register routes for {{PAGE_SLUG}} page (full-page mode).
+	 */
+	function {{PREFIX}}_register_{{PAGE_SLUG_UNDERSCORE}}_page_routes() {
+		global ${{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_routes_data;
+		{{PREFIX}}_register_page_routes( ${{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_routes_data, '{{PREFIX}}_register_{{PAGE_SLUG_UNDERSCORE}}_route' );
+	}
+}
+add_action( '{{PAGE_SLUG}}_init', '{{PREFIX}}_register_{{PAGE_SLUG_UNDERSCORE}}_page_routes' );
+
+if ( ! function_exists( '{{PREFIX}}_register_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_page_routes' ) ) {
+	/**
+	 * Register routes for {{PAGE_SLUG}} page (wp-admin mode).
+	 */
+	function {{PREFIX}}_register_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_page_routes() {
+		global ${{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_routes_data;
+		{{PREFIX}}_register_page_routes( ${{PREFIX}}_{{PAGE_SLUG_UNDERSCORE}}_routes_data, '{{PREFIX}}_register_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_route' );
+	}
+}
+add_action( '{{PAGE_SLUG}}-wp-admin_init', '{{PREFIX}}_register_{{PAGE_SLUG_UNDERSCORE}}_wp_admin_page_routes' );

package/templates/routes-registration.php.template

@@ -8,14 +8,14 @@
  */
 
 // Load routes registry
-$routes_file = __DIR__ . '/routes/index.php';
+$routes_file = __DIR__ . '/routes/registry.php';
 if ( ! file_exists( $routes_file ) ) {
 	return;
 }
 
 $routes = require $routes_file;
 
-// Group routes by page
+// Group routes by page and store in globals for page-specific functions
 $routes_by_page = array();
 foreach ( $routes as $route ) {
 	$page_slug = $route['page'];
@@ -25,11 +25,24 @@ foreach ( $routes as $route ) {
 	$routes_by_page[ $page_slug ][] = $route;
 }
 
-// Helper function to register routes for a page
-$register_routes_callback = function ( $page_routes, $page_slug_underscore, $register_function_name ) {
-	return function () use ( $page_routes, $page_slug_underscore, $register_function_name ) {
+// Store routes data in globals for each page
+foreach ( $routes_by_page as $page_slug => $page_routes ) {
+	$page_slug_underscore = str_replace( '-', '_', $page_slug );
+	$global_name = '{{PREFIX}}_' . $page_slug_underscore . '_routes_data';
+	$GLOBALS[ $global_name ] = $page_routes;
+}
+
+if ( ! function_exists( '{{PREFIX}}_register_page_routes' ) ) {
+	/**
+	 * Generic helper function to register routes for a page.
+	 *
+	 * @param array  $page_routes           Array of route data for the page.
+	 * @param string $register_function_name Name of the function to call for registering each route.
+	 */
+	function {{PREFIX}}_register_page_routes( $page_routes, $register_function_name ) {
 		// Load build constants
 		$build_constants = require __DIR__ . '/constants.php';
+
 		foreach ( $page_routes as $route ) {
 			$content_handle = null;
 			$route_handle = null;
@@ -71,22 +84,8 @@ $register_routes_callback = function ( $page_routes, $page_slug_underscore, $reg
 				call_user_func( $register_function_name, $route['path'], $content_handle, $route_handle );
 			}
 		}
-	};
-};
-
-// Register hooks for both full-page and wp-admin modes
-foreach ( $routes_by_page as $page_slug => $page_routes ) {
-	$page_slug_underscore = str_replace( '-', '_', $page_slug );
-
-	// Register all routes for full-page mode (page.php)
-	add_action(
-		"{$page_slug}_init",
-		$register_routes_callback( $page_routes, $page_slug_underscore, "register_{$page_slug_underscore}_route" )
-	);
-
-	// Register all routes for wp-admin mode (page-wp-admin.php)
-	add_action(
-		"{$page_slug}-wp-admin_init",
-		$register_routes_callback( $page_routes, $page_slug_underscore, "register_{$page_slug_underscore}_wp_admin_route" )
-	);
+	}
 }
+
+// Page-specific route registration functions
+{{PAGE_ROUTE_FUNCTIONS}}

package/templates/script-registration.php.template

@@ -59,7 +59,7 @@ if ( ! function_exists( '{{PREFIX}}_register_package_scripts' ) ) {
 		$extension       = defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ? '.js' : '.min.js';
 
 		$scripts_dir  = __DIR__ . '/scripts';
-		$scripts_file = $scripts_dir . '/index.php';
+		$scripts_file = $scripts_dir . '/registry.php';
 
 		if ( ! file_exists( $scripts_file ) ) {
 			return;

package/templates/style-registration.php.template

@@ -49,7 +49,7 @@ if ( ! function_exists( '{{PREFIX}}_register_package_styles' ) ) {
 		$suffix          = SCRIPT_DEBUG ? '' : '.min';
 
 		$styles_dir  = __DIR__ . '/styles';
-		$styles_file = $styles_dir . '/index.php';
+		$styles_file = $styles_dir . '/registry.php';
 
 		if ( ! file_exists( $styles_file ) ) {
 			return;