@plaudit/webpack-extensions 2.89.2 → 3.0.0-rc.2

package/CHANGELOG.md

@@ -5,49 +5,6 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [3.3.0] - 2026-03-16
-### Added
-- A few helper methods for tools that reference this package and care about the entrypoint resolution logic
-
-## [3.2.2] - 2026-03-16
-### Changed
-- Exposed additional aspects of the entrypoint resolution logic to tools that reference this package
-
-## [3.2.1] - 2026-03-16
-### Added
-- A function to expose standard flag sets to tools that reference this package
-
-## [3.2.0] - 2026-03-16
-### Added
-- Support for `Location-Encoding Filenames`
-  - This comes from version `2.86.0`
-- Support for standardized flag sets
-  - This comes from version `2.86.0`
-
-## [3.1.2] - 2026-03-06
-### Fixed
-- `defer` and `async` not being supported strategies in some pipelines
-  - This comes from version `2.85.3`
-
-## [3.1.1] - 2026-03-06
-### Fixed
-- Inlined scripts without any other path query parameters not being placed in the footer by default
-  - This comes from version `2.85.2`
-
-## [3.1.0] - 2026-03-05
-### Added
-- Support for inlining (and otherwise controlling the enqueuing of) assets
-  - This only applies to plain entrypoints and assets declared within block.json files at present
-  - This comes from version `2.85.0`
-
-## [3.0.1] - 2026-02-12
-### Added
-- Release version!
-
-## [3.0.0-rc.3] - 2026-02-12
-### Fixed
-- A missing dependency
-
 ## [3.0.0-rc.2] - 2026-02-12
 ### Fixed
 - A missing dependency
@@ -60,69 +17,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Legacy PostCSS features that have been integrated into modern CSS
 - `@extends` support
 
-## [2.89.2] - 2026-04-27
-### Fixed
-- An `ENOENT` error when the `srcDir` does not map to an actual directory on disk
-  - It now matches the behavior of manually-declared sources and exits due to not having anything to build
-
-## [2.89.1] - 2026-04-06
-### Fixed
-- The emitter for the Extensions v1 format including an extra path element
-
-## [2.89.0] - 2026-03-31
-### Changed
-- The block.json handling logic to use encoded location data in filenames that are enumerated within block.json
-- Inline scripts to not emit with a sourcemap outside of dev mode
-
-### Fixed
-- Unnecessary `.asset.php` files being emitted for inlined scripts
-
-## [2.88.2] - 2026-03-30
-### Fixed
-- The conflicting handle detection logic in block.json handling
-
-## [2.88.1] - 2026-03-30
-### Fixed
-- The paths in package.json that were broken after switching to dist
-
-## [2.88.0] - 2026-03-30
-### Added
-- Support for explicitly setting the handle for block assets
-
-## [2.87.1] - 2026-03-17
-### Changed
-- The `blockdir-loader.php` generation logic to use static wp_register_* calls like `plain-entrypoints-loader.php`
-
-## [2.87.0] - 2026-03-16
-### Added
-- Support for a directory-based `extensions` layout
-  - This only applies to sites using extensions v2 and higher
-
-### Internals
-- Backported the features from `3.2.x` and `3.3.0`
-
-## [2.86.0] - 2026-03-16
-### Added
-- Support for `Location-Encoding Filenames`
-- Support for standardized flag sets
-
-## [2.85.3] - 2026-03-06
-### Fixed
-- `defer` and `async` not being supported strategies in some pipelines
-
-## [2.85.2] - 2026-03-06
-### Fixed
-- Issues caused by trying to save a couple of cycles by using `hasAnyKeys` in place of checking the actual keys
-
-## [2.85.1] - 2026-03-06
-### Fixed
-- Inlined scripts without any other path query parameters not being placed in the footer by default
-
-## [2.85.0] - 2026-03-05
-### Added
-- Support for inlining (and otherwise controlling the enqueuing of) assets
-  - This only applies to plain entrypoints and assets declared within block.json files at present
-
 ## [2.84.1] - 2026-02-11
 ### Fixed
 - Typedef compatibility issues with Webpack 5.105.0

package/USER-GUIDE.md

@@ -28,13 +28,7 @@
     * [Pattern 4: Block Editor Styles](#pattern-4-block-editor-styles)
 * [Reference](#reference)
   * [Root Options](#root-options)
-    * [Standard Flag Sets](#standard-flag-sets)
-  * [Location-Encoding Filenames](#location-encoding-filenames)
-    * [Enqueuing Location](#enqueuing-location)
-    * [Examples](#examples-1)
-      * [Block- and Plain-compatible](#block--and-plain-compatible)
   * [Per-Entrypoint Options](#per-entrypoint-options)
-    * [Path Queries](#path-queries)
     * [Boolean-form](#boolean-form)
     * [String-form](#string-form)
     * [Object-form](#object-form)
@@ -143,26 +137,81 @@ The config tells webpack **what** to build and **where** to load it in WordPress
 
 ```javascript
 module.exports = require("@plaudit/webpack-extensions/wordpress-scripts-wrapper")({
-	standard: '2026-03-16',
+	src: {
+	  // Build all blocks in src/blocks/
+		"blocks": true,
+    
+	  // Build block extensions from src/extensions/
+		"extensions": {directoryLayout: 'extensions'},
+
+	  // Auto-load in the head on frontend
+		"site/index-header.ts": {
+			locations: {
+				clientView: true,
+				registerScriptArgs: false
+			}
+		},
+    
+	  // Auto-load at the bottom of the body on frontend
+		"site/index-footer.ts": {
+			locations: {
+				clientView: true,
+				registerScriptArgs: 'lazy'
+			}
+		},
+	  // Auto-load in admin
+		"site/wp-admin.ts": {
+			locations: {
+				admin: true
+			}
+		},
+	  // Auto-load in admin
+		"site/wp-admin.pcss": {
+			locations: {
+				admin: true
+			}
+		},
+	  // Auto-load in the block editor
+		"site/block-editor.pcss": {
+			locations: {
+				clientEditor: true
+			}
+		},
+	  // Auto-load in the head on frontend
+		"site/public.pcss": {
+			locations: {
+				clientView: true
+			}
+		},
+	  // A script that can be enqueued via its handle, but is not autoloaded
+	  "site/manually-loaded.ts": {
+		  locations: "plaudit-theme/manually-loaded-script"
+	  }
+	},
+	useWebpackResourceFiltering: true, // Always use this!
+	extensionsVersion: 3,
+	plainEntrypointsVersion: 2,
+	srcDir: "src", // Always use this!
+	outputDir: "dist", // Always use this!
+	useUnifiedLoader: true, // Always use this!
 	variables: {
 		font_size: 16 // Required for pxAsRem to work; replace the 16 with your site's base font size
 	}
 });
 ```
-The `standard` key is shorthand to the standard set of flags as of the given date. See the [Standard Flag Sets](#standard-flag-sets) section for details.
 
 ### 2. Set Up Your File Structure
 
 **Blocks** (subdirectories with block.json):
-- **Config:** optional so long as the directory name is `blocks`; `'<dirname>': true` otherwise
+- **Config:** `'blocks': true`
 - **File Structure:** [See Here](#file-structure)
 
 **Extensions** (flat files that modify existing blocks):
-- **Config:** optional so long as the directory name is `extensions`; `'<dirname>': {directoryLayout: 'extensions'}` otherwise
+- **Config:** `'extensions': {directoryLayout: 'extensions'}`
 - **File Structure:** [See Here](#file-structure-1)
 
 **Other Files** (scripts, styles):
-- **Config:** Optional so long as you are using [Location-Encoding Filenames](#location-encoding-filenames); List each file that does not encode its own location in `src` object
+- **Config:** List each file individually in `src` object
 - **File Structure:** [See Here](#file-structure-2)
 
 ### 3. Include unified-loader.php in Your Plugin
@@ -216,7 +265,7 @@ After building, each asset gets a handle you can reference in PHP.
 **Best way:** Check the generated loader files after building:
 - `dist/blocks/blocks-loader.php`
 - `dist/extensions/extensions-loader.php`
-- The first argument of the `wp_register_script` and `wp_register_style` calls in `dist/plain-entrypoints-loader.php`
+- The first argument of the `wp_register_script` and `wp_register_style` calls in `dist/plain-entrypoints-loader.php` 
 
 ### Example: Manual Enqueue with Localization
 
@@ -303,106 +352,27 @@ src: {
 # Reference
 
 ## Root Options
-| Option                             | Type      | Default | Description                                                                                                                                                                                  |
-|------------------------------------|-----------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `standard`                         | `enum`    | -       | An identifier for the standard set of flags as of a given date. See the [Standards Flag Sets](#standard-flag-sets) section for values                                                        |
-| `src`                              | `object`  | `{}`    | Files/directories to process (see the next section for what you can put in here)                                                                                                             |
-| `srcDir`                           | `string`  | `""`    | Source directory (**Required** on new sites)                                                                                                                                                 |
-| `outputDir`                        | `string`  | `""`    | Output directory (**Required** on new sites)                                                                                                                                                 |
-| `useUnifiedLoader`                 | `boolean` | `false` | Generate unified-loader.php (always set to `true` on new sites!)                                                                                                                             |
-| `useWebpackResourceFiltering`      | `boolean` | `false` | Generates versioned copies of images, fonts, etc (always set to `true` on new sites!)                                                                                                        |
-| `plainEntrypointsVersion`          | `1\|2`    | `1`     | Use 2 for new sites                                                                                                                                                                          |
-| `extensionsVersion`                | `1\|2\|3` | `1`     | Use 3 for new sites                                                                                                                                                                          |
-| `verbose`                          | `boolean` | `false` | Verbose logging                                                                                                                                                                              |
-| `variables`                        | `object`  | Auto    | CSS/JS variables. If a variables.js file is present, this will automatically load from that file                                                                                             |
-| `onlyRunPostCSSOnPCSS`             | `boolean` | `false` | If true, the PostCSS processor will not be run on CSS files. This is true for all new sites and can be safely enabled on most sites if desired.                                              |
-| `assumeGlobalizedPlauditLibraries` | `boolean` | `true`  | **[Advanced]** When `false`, normally-externalized plaudit libraries will be included.<br>**DO NOT USE THIS. IF YOU SEE IT BEING USED, CONTACT JOSH**                                        |
-| `externals`                        | `object`  | -       | **[Advanced]** Allows dependencies to be marked as external. This prevents them from being included in the bundle under the assumption that they will be provided via an alternate mechanism |
-| `targetHandlePrefix`               | `string`  | Auto    | **[Legacy]** Prefix for handles. Auto-detected from composer.json if omitted. Do not set this unless absolutely necessary                                                                    |
-
-### Standard Flag Sets
-Each flag set is identified by the date that it was added to the standards set. Individual values can be overridden by specifying them in the config file
-
-**2026-03-13**
-```javascript
-{
-	useWebpackResourceFiltering: true,
-	extensionsVersion: 3,
-	plainEntrypointsVersion: 2,
-	srcDir: "src",
-	outputDir: "dist",
-	useUnifiedLoader: true,
-	onlyRunPostCSSOnPCSS: true,
-}
-```
-
----
-
-## Location-Encoding Filenames
-This section covers how asset emission locations can be encoded in filenames.
-While every common flag is accounted for in this schema, there are some things that cannot be encoded in filenames that will require enumeration in the `webpack.config.js` file's `src` object.
-
-Location-encoding filenames are composed of two or more `.`-separated segments (the file extension being one of those segments).
-The following is a brief list of notes followed by a breakdown of the individual segments:
-- The only required segments are the location and type segments (the type segment is the file extension).
-- So long as there is at least one location and type segment (the type segment MUST be last), "invalid" segments are allowed so that files can be given human-readable names
-- Each file can list any combination enqueuing locations
-- The first item is special in that, if it encodes a location, it can optionally be suffixed with a type override (see the [Enqueuing Location](#enqueuing-location) section for more details)
-
-Notes on how to read the following table:
-- Brackets in the token column mean "optional section"
-- `(-|=)` means "this can be either a dash or an equal sign"
-- Pipe-separated items in parentheses means "any one of these items can go here"
-
-| Name               | Token                                                       | Usage                                                                                                                                                    |
-|--------------------|-------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Enqueuing Location | `(enqueuing-location)[(-\|=)priority]`                      | This is a special section that is actually a collection of values. See the [Enqueuing Location](#enqueuing-location) section for more details            |
-| Type Override      | `script`, `style`, `script-module`                          | Can be used to override the detected of the asset. Must be the first token in the filename; if used directly, it is shorthand for `both-(Type Override)` |
-| Inline             | `inline[(-\|=)position]`, `strategy(-\|=)inline[-position]` | Indicates that the script should be inlined. `position` can be either `before` or `after`                                                                |
-| Strategy           | `lazy\|eager`, `strategy(-\|=)(lazy\|eager\|defer\|async)`  | Controls the loading strategy. Lazy and eager have shorthand while the remaining values must be prefixed with `strategy`                                 |
-| Fetch Priority     | `fetchpriority(-\|=)(low\|high\|auto)`                      | Controls the fetchpriority property; `auto` is the default                                                                                               |
-| In Footer          | `in-footer`, `in_footer`                                    | Sets the `in_footer` value to `true`; incompatible with `in-header`                                                                                      |
-| In Header          | `in-header`, `in_header`                                    | Sets the `in_footer` value to `false`; incompatible with `in-footer`                                                                                     |
-| Extension          | `([ps]?c\|sa)ss`, `m?[jt]sx?`                               | This determines the type unless it is overridden. This **MUST** be the last token in the name (it is the file extension)                                 |
-
-### Enqueuing Location
-If this is the first token, it can be suffixed with `-script`, `-style`, or `-script-module` to override the type.
-Specifying the type override alone is interpreted as `both-(Type Override)` for compatibility with how blocks expect assets to be named.
-
-Blocks do not support anything other than `view`, `editor`, and `both` (typically written as `script` or `style`).
-
-**Valid Values**:
-
-| Token                                     | Meaning                                                                                                                     |
-|-------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
-| `view`, `client-view`, `clientView`       | Enqueue the asset on the frontend (the part of the site seen by visitors)                                                   |
-| `editor`, `client-editor`, `clientEditor` | Enqueue the asset in the *display* portion of the block editor                                                              |
-| `both`                                    | Shorthand for `view.editor`                                                                                                 |
-| `block-assets`, `block-assets`            | Enqueue the asset in the *wrapper* portion of the block editor                                                              |
-| `admin`                                   | Enqueue the asset in the admin area                                                                                         |
-| `login`                                   | Enqueue the asset on the standard login page                                                                                |
-| `customizer`                              | Enqueue the asset in the legacy customizer interface                                                                        |
-| `analytics`                               | Enqueue the asset when analytics scripts have been accepted by the visitor (this "location" is unique to Plaudit's systems) |
-| `register`                                | Register the asset *without* enqueuing it anywhere (this is primarily useful when localizing the asset)                     |
-
-### Examples
-#### Block- and Plain-compatible
-- **A view script**: `view.ts`
-- **An editor script**: `editor.ts`
-- **A view and editor script**: `script.ts`
+| Option                             | Type      | Default      | Description                                                                                                                                                                                  |
+|------------------------------------|-----------|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `src`                              | `object`  | **Required** | Files/directories to process (see the next section for what you can put in here)                                                                                                             |
+| `srcDir`                           | `string`  | `""`         | Source directory (**Required** on new sites)                                                                                                                                                 |
+| `outputDir`                        | `string`  | `""`         | Output directory (**Required** on new sites)                                                                                                                                                 |
+| `useUnifiedLoader`                 | `boolean` | `false`      | Generate unified-loader.php (always set to `true` on new sites!)                                                                                                                             |
+| `useWebpackResourceFiltering`      | `boolean` | `false`      | Generates versioned copies of images, fonts, etc (always set to `true` on new sites!)                                                                                                        |
+| `plainEntrypointsVersion`          | `1\|2`    | `1`          | Use 2 for new sites                                                                                                                                                                          |
+| `extensionsVersion`                | `1\|2\|3` | `1`          | Use 3 for new sites                                                                                                                                                                          |
+| `verbose`                          | `boolean` | `false`      | Verbose logging                                                                                                                                                                              |
+| `variables`                        | `object`  | Auto         | CSS/JS variables. If a variables.js file is present, this will automatically load from that file                                                                                             |
+| `onlyRunPostCSSOnPCSS`             | `boolean` | `false`      | If true, the PostCSS processor will not be run on CSS files. This is true for all new sites and can be safely enabled on most sites if desired.                                              |
+| `assumeGlobalizedPlauditLibraries` | `boolean` | `true`       | **[Advanced]** When `false`, normally-externalized plaudit libraries will be included.<br>**DO NOT USE THIS. IF YOU SEE IT BEING USED, CONTACT JOSH**                                        |
+| `externals`                        | `object`  | -            | **[Advanced]** Allows dependencies to be marked as external. This prevents them from being included in the bundle under the assumption that they will be provided via an alternate mechanism |
+| `targetHandlePrefix`               | `string`  | Auto         | **[Legacy]** Prefix for handles. Auto-detected from composer.json if omitted. Do not set this unless absolutely necessary                                                                    |
 
 ---
 
 ## Per-Entrypoint Options
 This section covers the shared options for entrypoints. See the [Entrypoint Types](#entrypoint-types) section for options specific to individual types
 
-### Path Queries
-- These are URL-style queries added to the end of entrypoint *source* paths and are used to set entrypoint-specific properties in Plain and Block contexts.
-  - If you find yourself using these, consider switching to [Location-Encoding Filenames](#location-encoding-filenames)
-  - At present, this is only being used to configure inlining, but expansion to other systems is being considered
-  - The available options are: `strategy`, `inline`, `in_footer`, `fetchpriority`, `position`, and `handle`
-    - Handle is only available on blocks – declare the handle using the [Locations object](#the-locations-object)
-
 ### Boolean-form
 - This is only available if `outputDir` has been set
 - The only supported value is `true` and only works for `blocks` and `plain` entrypoints. It means that every value will have its default value
@@ -472,7 +442,7 @@ If you use both methods for the same entrypoint, the dependencies from the confi
 ## Entrypoint Types
 
 ### Blocks
-This was the first entrypoint type added, and, due to how it integrates with WordPress, it both has and needs the least amount of configuration.
+This was first entrypoint type added, and, due to how it integrates with WordPress, it both has and needs the least amount of configuration.
 In fact, under most circumstances, the proper configuration value is just `true`.
 
 #### File Structure
@@ -489,8 +459,7 @@ src/blocks/
 #### Notes
 - Blocks **should** be created with `pnpm @plaudit/scaffold create block`
 - template.php and setup.php files are automatically loaded; however, they can be manually specified if desired
-- Script and Style files **must** be specified using the `file:./<path here>[?path-query-here]` syntax in the appropriate keys. See [WordPress' `block.json` reference](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/) for further details
-  - The `[?path-query-here]` component is something that we added. You can see more details in its section [here](#path-queries)
+- Script and Style files **must** be specified using the `file:./<path here>` syntax in the appropriate keys. See [WordPress' `block.json` reference](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/) for further details
 
 #### Per-Entrypoint Options
 The `blocks` entrypoint type doesn't have any.
@@ -502,10 +471,8 @@ This is used to associate additional assets with blocks that are not in control
 [Specially named files](#file-naming) in a single subdirectory of `src`
 ```
 src/extensions/
-├─ core/paragraph/
-│  ├─ view.ts
-│  └─ editor.pcss
-└─ plaudit/block-library/accordion/style.pcss
+├── core-paragraph-view-script.ts
+└── core-paragraph-editor-style.pcss
 ```
 
 #### File Naming
@@ -516,12 +483,9 @@ Filenames **must** follow the pattern: `{kebab-case-block-name}-{type}.{ext}`
   - `script-module`, `view-script-module`
   - `setup` (this allows for PHP code to be loaded only when certain blocks are enabled and is intended for use in plugins, not themes)
 - `ext` **must** be for a [supported file type](#supported-file-types) and **should** correspond with the extension type (basically, don't enqueue a `.css` file as a script)
-- For convenience, everything before the `{type}` can be split into directories on the hyphens
-  - When using this format, the filenames must be [Location-Encoding Filenames](#location-encoding-filenames) or `setup.php`
-  - This is only available in extensions v2 and up
 
 #### Notes
-- To have a directory be treated as `extensions`, the config **must** include `directoryLayout: 'extensions'`
+- In order to have a directory be treated as `extensions`, the config **must** include `directoryLayout: 'extensions'`
 - Extensions **should** be created with `pnpm @plaudit/scaffold create extension`
 
 #### Per-Entrypoint Options

package/{dist → build}/plugins/EnhancedBlockJSONPlugin.d.ts

@@ -1,14 +1,12 @@
-import { Compilation } from "webpack";
-import type WebpackRemoveEmptyScriptsPlugin from "webpack-remove-empty-scripts";
 import { AbstractBiPhasicGroupAndEntryPlugin, EntryProvider } from "./AbstractBiPhasicGroupAndEntryPlugin";
-import { ParsedAssetsJson, BlockEntrypointInfo, FileSegmentBlockEntrypointInfo, VerifiedAdvancedOutputConfig, ParsedAssetJsonProvider, ScriptArgsObject, InlinedAsset } from "../shared";
+import { ParsedAssetsJson, BlockEntrypointInfo, FileSegmentBlockEntrypointInfo, VerifiedAdvancedOutputConfig, ParsedAssetJsonProvider } from "../shared";
 import type { VerifiedPlauditWordpressWebpackConfig } from "../utils/common-config-helpers";
-type WorkableBlockEntrypointInfo = Omit<FileSegmentBlockEntrypointInfo, 'originalValue' | 'pathQueryParameters'> & Partial<Pick<FileSegmentBlockEntrypointInfo, 'originalValue'>> & {
+import { Compilation } from "webpack";
+import type WebpackRemoveEmptyScriptsPlugin from "webpack-remove-empty-scripts";
+type WorkableBlockEntrypointInfo = Omit<FileSegmentBlockEntrypointInfo, 'originalValue'> & Partial<Pick<FileSegmentBlockEntrypointInfo, 'originalValue'>> & {
     outputPath: string;
     assetData: ParsedAssetsJson[string];
     hash: string;
-    scriptArgsObject: ScriptArgsObject | undefined;
-    inlinedAsset: InlinedAsset | undefined;
 };
 type CollatedWorkableBlockInfo = Record<string, {
     sourcePath?: string;
@@ -22,7 +20,6 @@ export declare class EnhancedBlockJSONPlugin extends AbstractBiPhasicGroupAndEnt
     constructor(config: VerifiedPlauditWordpressWebpackConfig, dest: VerifiedAdvancedOutputConfig, webpackRemoveEmptyScriptsPlugin: WebpackRemoveEmptyScriptsPlugin, context: string, entry: EntryProvider<BlockEntrypointInfo>);
     protected processAssets(compilation: Compilation, parsedAssetJsonProvider: ParsedAssetJsonProvider): Promise<void>;
     private emitBlockLoaderFile;
-    private callRegisterFunction;
     private transformBlocks;
     private static extractAssetSource;
     private static convertToScriptHandles;