@eightshift/frontend-libs-tailwind 4.0.0-beta.3 → 4.0.0-beta.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/CHANGELOG.md +30 -1
  2. package/README.md +149 -12
  3. package/bin/tw-sweep.mjs +35 -14
  4. package/bun/browser-css.mjs +487 -0
  5. package/bun/build.mjs +20 -1
  6. package/bun/cli-supervisor.mjs +171 -0
  7. package/bun/cli-worker.mjs +57 -0
  8. package/bun/cli.mjs +3 -49
  9. package/bun/css.mjs +126 -25
  10. package/bun/discovery.mjs +12 -1
  11. package/bun/editor-native.mjs +38 -0
  12. package/bun/editor-pure-jsx.mjs +88 -0
  13. package/bun/editor.mjs +33 -0
  14. package/bun/eightshift-discovery.mjs +102 -26
  15. package/bun/flat-publication.mjs +19 -184
  16. package/bun/index.mjs +14 -0
  17. package/bun/media.mjs +17 -5
  18. package/bun/plugin-capabilities.mjs +1 -0
  19. package/bun/preset.mjs +6 -4
  20. package/bun/publish.mjs +7 -4
  21. package/bun/release.mjs +56 -4
  22. package/bun/shared-fonts.mjs +140 -0
  23. package/bun/ssr.mjs +26 -12
  24. package/bun/structured-publication.mjs +66 -0
  25. package/bun/theme-build.mjs +130 -43
  26. package/bun/theme-discovery.mjs +113 -9
  27. package/bun/watch.mjs +32 -0
  28. package/bun/wordpress.mjs +49 -23
  29. package/eslint.config.mjs +22 -1
  30. package/linters/base.config.mjs +1 -0
  31. package/linters/tw-sweep-extract.mjs +5 -0
  32. package/package.json +5 -5
  33. package/scripts/components/link-section-editor.js +1 -0
  34. package/scripts/editor/editor.js +1 -0
  35. package/scripts/editor/registration.js +3 -0
  36. package/scripts/editor/store.js +7 -0
  37. package/test/bun-discovery.test.mjs +69 -0
  38. package/test/bun-publication.test.mjs +144 -0
  39. package/test/bun-theme-build.test.mjs +12 -0
  40. package/test/bun-wordpress.test.mjs +82 -0
  41. package/test/fixtures/theme-build-regressions.mjs +585 -0
package/CHANGELOG.md CHANGED
@@ -8,6 +8,35 @@ This projects adheres to [Semantic Versioning](https://semver.org/) and [Keep a
8
8
 
9
9
  ## [4.0.0]
10
10
 
11
+ ### 4.0.0-beta.5
12
+
13
+ - Use ESLint 9 to satisfy the React lint plugin peer range without changing lint rules.
14
+ - Support stable UI Components 8 and explicitly allow 8.5.0-beta.1; validate locally against that exact published beta.
15
+
16
+ - Preserve generic PHP class extraction alongside the documented Tailwind helper patterns.
17
+ - ESLint 9 remains a known end-of-life risk; a major upgrade is deferred pending React plugin peer compatibility.
18
+
19
+ ### 4.0.0-beta.4
20
+
21
+ - **Breaking:** make structured directories the only built-in `defineThemeBuild` publication layout. Remove `publicationLayout` from configuration (all explicit values are rejected) and remove the legacy `flattenAssets` export. Migrate publication hooks from `outdir/flat` to the stable `publicationRoot` directory contract and nested relative aliases; fixed special outputs remain supported through `extraFiles`. Custom `publish` callbacks remain supported but must account for structured compiler URLs. Low-level build and prepared-tree packaging APIs retain their existing defaults.
22
+ - Omit unreferenced conventional structured entry stylesheet intermediates after generating hashed replacements; retain aliases, referenced styles, custom CSS and script paths. Cache synchronization, retention and rollback policy are unchanged.
23
+
24
+ - Default conventional theme editor builds to unified sharing; compatible PHP module-readiness integration is required.
25
+ - Add opt-in shared same-origin font publication, requiring UI Components 8.5.0-beta.1 and Eightshift Libs 14.0.0-alpha.3 shared-font support.
26
+ - Compile default SSR entries together as standalone CommonJS bundles; preserve sequential compilation for caller plugins and prevent implicit writes during compilation.
27
+ - Restart CLI watch workers on selected configuration, root package manifest and Bun lockfile changes, draining active work before replacement.
28
+ - Accept both verified generated Smart Image worker URL forms.
29
+ - Resolve externalized WordPress package exports and default globals from core scripts without requiring installed package metadata; remove the API-fetch peer requirement.
30
+ - Preserve isolated editor store IDs across projects without changing them on every rebuild.
31
+ - Compile JavaScript-imported frontend and admin CSS and load it with its importing module, preserving lazy boundaries; resolve Smart Image workers on each surface.
32
+ - Preserve relative asset URLs in nested release stylesheets and retain conditional shared-font rules in their original stylesheets.
33
+ - Preserve eager JavaScript discovery contexts and recognize escaped editor stylesheet patterns.
34
+ - Preserve CommonJS-style WordPress core exports instead of treating them as side-effect-only scripts.
35
+ - Publish local string image URLs in CSS `image-set()` declarations.
36
+ - Decode percent-encoded local CSS asset paths once, preserving query strings and fragments; report malformed path encoding clearly.
37
+ - Allow empty release stylesheets while continuing to reject missing files and empty JavaScript entries.
38
+ - Exit nonzero when a one-shot CLI build is interrupted, including during configuration loading.
39
+
11
40
  ### Changed
12
41
 
13
42
  - Show build/watch progress and total duration by default, with `--quiet` and `--verbose` output modes.
@@ -21,7 +50,7 @@ This projects adheres to [Semantic Versioning](https://semver.org/) and [Keep a
21
50
  - Improved browser bundle tree-shaking and WordPress dependency metadata.
22
51
  - Prevented unnecessary watch rebuilds on macOS.
23
52
  - Removed the experimental `editor.sharedPackages` option. Existing configurations must remove it or migrate to a supported sharing mode.
24
- - Added opt-in editor sharing modes: `native` shares lazy-loaded modules while preserving synchronous registration; `unified` also shares registration code and requires matching PHP module-readiness integration. Independent builds remain the default.
53
+ - **Breaking:** conventional theme builds now default to `unified` editor sharing, requiring matching PHP module-readiness integration (validated with eightshift-libs 14.0.0-alpha.2). The lower-level editor API still defaults to `independent`. Explicit editor presets retain their own sharing choice. `native` remains opt-in and shares lazy modules while keeping registration separate.
25
54
  - Added opt-in `editor.pureJsxGroups` to reduce chunk requests in unified production builds. Unsupported configurations, including source-map builds, fall back to ungrouped output.
26
55
 
27
56
  ## [3.5.0]
package/README.md CHANGED
@@ -18,7 +18,7 @@ The Webpack configuration and `webpack/*` imports have been removed. Projects mu
18
18
 
19
19
  The Bun helpers are not a drop-in replacement for Webpack. Start with the theme preset for the conventional Eightshift theme layout. Use the lower-level API below for other layouts.
20
20
 
21
- The conventional theme build requires a stable WordPress 7.0 or newer installation. Each build reads `wp-includes/version.php` before modifying output and fails if the version is missing, unrecognized, or too old. By default, the WordPress root is three directories above the theme root; set `EIGHTSHIFT_WP_ROOT` to its absolute path for other layouts. The public asset URL defaults to the theme's path under that root plus `/public/`. If that does not match the site's URL layout, set `publicPrefix` in `defineThemeBuild` or `EIGHTSHIFT_PUBLIC_PREFIX` in the environment to the root-relative public URL path, including its trailing slash (for example, `/wp-content/themes/example/public/`). The option takes precedence over the environment variable. The lower-level build API does not enforce this version check.
21
+ The conventional theme build requires a stable WordPress 7.0 or newer installation. Each build reads `wp-includes/version.php` before modifying output and fails if the version is missing, unrecognized, or too old. By default, the WordPress root is three directories above the theme root; set `EIGHTSHIFT_WP_ROOT` to its absolute path for other layouts. The public asset URL defaults to the theme's path under that root plus `/public/`. If that does not match the site's URL layout, set `publicPrefix` in `defineThemeBuild` or `EIGHTSHIFT_PUBLIC_PREFIX` in the environment to the root-relative public URL path, including its trailing slash (for example, `/wp-content/themes/example/public/`). The option takes precedence over the environment variable. The editor store ID is derived from this prefix and remains stable across rebuilds. Builds loaded together must use distinct public prefixes to avoid sharing a store. The lower-level build API does not enforce this version check.
22
22
 
23
23
  ### Migrate a conventional theme
24
24
 
@@ -54,6 +54,31 @@ The manifest maps the conventional `applicationBlocksFrontend`, `applicationBloc
54
54
 
55
55
  Successful default publication replaces the previous `public/` contents. Run only one build or publication per theme at a time; output directories are not locked against concurrent builds. The PHP manifest cache update is not coordinated with PHP cache rebuilds: if they overlap, stale asset URLs can remain until the next successful build or cache reset. Account for cached pages that may still request files removed by successful publication; retain old releases externally if needed. Verify block registration, editor controls and save/reload behavior, frontend styles and lazy assets, representative admin screens, script dependencies, browser console and asset URLs. Keep the previous Webpack build available for rollback until the new build is verified.
56
56
 
57
+ ### Editor default and PHP compatibility
58
+
59
+ `defineThemeBuild({ root })` uses unified editor sharing: registration and lazy editor modules share one ESM graph. It requires the PHP `eightshift-editor-v1` module-readiness integration, validated with `infinum/eightshift-libs` 14.0.0-alpha.2. Install compatible PHP integration before serving these assets, and enqueue editor JavaScript through `enqueue_block_editor_assets`. The build checks WordPress source compatibility but cannot certify which PHP integration is active at runtime. Without the readiness bootstrap, the generated module throws an explicit error; there is no automatic classic-script fallback.
60
+
61
+ Classic consumers that require registered blocks must await the readiness promise described below. This is a registration-semantics change, not a guaranteed startup speedup. Package import optimization and pure JSX grouping are separate settings; JSX grouping remains off by default.
62
+
63
+ For an explicit classic-registration fallback, provide the complete editor preset:
64
+
65
+ ```js
66
+ export default defineThemeBuild({
67
+ root: import.meta.dirname,
68
+ editor: {
69
+ entry: 'editor',
70
+ filename: 'applicationBlocksEditor.js',
71
+ sharing: 'independent',
72
+ discovery: {
73
+ filter: /application-blocks-editor\.js$/,
74
+ omitContexts: ({ pattern }) => ['styles-editor.css$', 'styles-editor\\.css$'].includes(pattern.source),
75
+ },
76
+ },
77
+ });
78
+ ```
79
+
80
+ Independent entries do not preserve shared module state across separately compiled bundles: context providers and consumers spanning those bundles need an explicit compatibility solution. Rebuild and deploy matching scripts and metadata together when changing modes. Supplying `editor` replaces the whole preset; an explicit editor object without `sharing` retains the lower-level independent default.
81
+
57
82
  ### Lower-level build API
58
83
 
59
84
  For a nonstandard project, run the following as a project-root `build.mjs`, adapting the paths to your project:
@@ -101,7 +126,7 @@ Run `bun run build.mjs`, add `--production` for minification, or `--watch` for a
101
126
 
102
127
  `build` requires named entries and an output directory. By default, it builds each entry separately as browser ESM with splitting and hashed filenames, writes `manifest.json` and an `<entry>/<entry>.asset.json` with dependencies and a version hash, and returns `{ outdir, entries }`. Integrate these files with your WordPress enqueue code; this package does not enqueue them. Output is staged and published only after success. An existing output directory must have the build's ownership marker, and output paths and trees cannot contain symlinks. Do not use a directory containing the project root. `buildOptions` can override Bun defaults such as `target`, `format`, `splitting`, `naming`, loaders and plugins; callers must ensure the resulting format matches their WordPress loading strategy. Entry points, output directory and write mode are controlled by the build API.
103
128
 
104
- For projects that prefer a validated configuration, `createPreset` and `buildPreset` are exported from `@eightshift/frontend-libs-tailwind/bun/preset.mjs`. Pass `wordpress: false`, `discovery: false`, `responsive: false` or `css: false` to disable the corresponding feature; discovery, responsive generation and CSS are opt-in. Configure CSS surfaces or pass a custom CSS callback. `buildOptions` accepts the same overrides as `build`. When an editor entry is enabled, `buildOptions.sourcemap` supports only `none` and `external`. The default `editor.sharing: 'independent'` keeps synchronous registration and lazy entries in separate bundles. Its lazy editor URLs use a build-wide query version derived from the registration and lazy bundles; changing either invalidates all lazy URLs. The opt-in sharing modes below change graph layout, and unified mode also changes registration timing.
129
+ For projects that prefer a validated configuration, `createPreset` and `buildPreset` are exported from `@eightshift/frontend-libs-tailwind/bun/preset.mjs`. Pass `wordpress: false`, `discovery: false`, `responsive: false` or `css: false` to disable the corresponding feature; discovery, responsive generation and CSS are opt-in. Configure CSS surfaces or pass a custom CSS callback. `buildOptions` accepts the same overrides as `build`. When an editor entry is enabled, `buildOptions.sourcemap` supports only `none` and `external`. The lower-level default `editor.sharing: 'independent'` keeps synchronous registration and lazy entries in separate bundles; the conventional theme preset instead defaults to unified sharing. Its lazy editor URLs use a build-wide query version derived from the registration and lazy bundles; changing either invalidates all lazy URLs. The opt-in sharing modes below change graph layout, and unified mode also changes registration timing.
105
130
 
106
131
  ### Native editor sharing (experimental, opt-in)
107
132
 
@@ -120,7 +145,7 @@ export default defineThemeBuild({
120
145
  sharing: 'native',
121
146
  discovery: {
122
147
  filter: /application-blocks-editor\.js$/,
123
- omitContexts: ({ pattern }) => pattern.source === 'styles-editor.css$',
148
+ omitContexts: ({ pattern }) => ['styles-editor.css$', 'styles-editor\\.css$'].includes(pattern.source),
124
149
  },
125
150
  },
126
151
  });
@@ -130,11 +155,11 @@ Native sharing preserves nested lazy imports and emits source maps when requeste
130
155
 
131
156
  This mode requires readable Bun entry metadata and rejects dynamic imports that Bun inlines into the current chunk: those can lose native module namespaces, and dynamic self-imports were observed to generate an undefined helper in Bun 1.4.4-canary.1. These cases fail the build rather than silently falling back to different semantics. Native output must remain JavaScript and source maps, as with the existing editor pipeline.
132
157
 
133
- Native sharing can substantially reduce total output while increasing the number of files requested by the editor. It does **not** guarantee faster startup or Webpack parity. Validate cold and warm editor loads, first-block rendering, options, custom plugins, worker URLs and module state before enabling it. No theme is opted in automatically. Remove `sharing: 'native'` to restore independent chunks and rebuild; do not mix outputs from the two modes.
158
+ Native sharing can substantially reduce total output while increasing the number of files requested by the editor. It does **not** guarantee faster startup or Webpack parity. Validate cold and warm editor loads, first-block rendering, options, custom plugins, worker URLs and module state before enabling it. No theme is opted into native sharing automatically. Set `sharing: 'independent'` explicitly to restore independent chunks, or remove the entire editor override to use the theme preset's unified default; rebuild and do not mix outputs from different modes.
134
159
 
135
- ### Unified editor graph (experimental, compatibility-changing)
160
+ ### Unified editor graph (theme default, compatibility-changing)
136
161
 
137
- `editor.sharing: 'unified'` builds registration and all lazy editor code in one native ESM graph. Unlike `native`, it can share dependency instances between registration and lazy consumers. It does **not** preserve synchronous classic-script registration. Keep it disabled until the matching Eightshift PHP module-readiness integration is installed and every dependent consumer has been checked.
162
+ `editor.sharing: 'unified'` builds registration and all lazy editor code in one native ESM graph. Unlike `native`, it can share dependency instances between registration and lazy consumers. It does **not** preserve synchronous classic-script registration. The conventional theme preset now selects this mode by default; install matching Eightshift PHP module-readiness integration and check dependent consumers before switching. Lower-level callers must still opt in explicitly.
138
163
 
139
164
  Use the native-sharing configuration above with `sharing: 'unified'`. Do not provide `editor.lazy` rewriting options; unified mode lets Bun discover native imports. It keeps the same lazy-transform rejection rules as native mode. Its JavaScript wrapper statically imports the editor graph and signals completion through `globalThis.eightshiftEditorModules.complete(import.meta.url)`. Generated editor asset metadata declares `format: 'module'` and `readiness: 'eightshift-editor-v1'`; frontend/admin and existing editor modes retain their previous metadata. Older classic-only PHP integration is incompatible.
140
165
 
@@ -171,13 +196,23 @@ A second native build compiles the original graph with bounded groups. Static na
171
196
 
172
197
  In an isolated production-release comparison using Bun 1.4.4-canary.1, 4 KiB grouping reduced startup theme-JavaScript requests from 34 to 16 while increasing gzip bytes from 307108 to 309447. After rendering a CTA block, requests fell from 37 to 19 and gzip bytes increased from 388459 to 390798. Both variants registered 33 theme blocks and rendered three editable CTA fields without browser errors. These measurements used a synthetic editor page with the PHP readiness bootstrap and disabled browser cache; WordPress core assets are excluded. The same-source Webpack reference used 10 startup requests / 287529 gzip bytes and 12 requests / 366641 gzip bytes after the CTA. These results do **not** establish a repeatable latency improvement or Webpack parity. Measure your own editor and lazy interactions before opting in. Remove `pureJsxGroups` or set it to `false` and rebuild to roll back; independent and native-lazy modes remain unchanged.
173
198
 
174
- The earlier `editor.sharedPackages` vendor-bridge experiment was removed. Existing experimental configurations must remove that option; it now fails configuration validation rather than silently changing initialization behavior. Use independent mode by default, or explicitly evaluate native/unified sharing with their compatibility requirements.
199
+ The earlier `editor.sharedPackages` vendor-bridge experiment was removed. Existing experimental configurations must remove that option; it now fails configuration validation rather than silently changing initialization behavior. The lower-level API retains independent mode by default; the theme preset uses unified mode with the PHP compatibility requirements above. Native sharing remains opt-in.
175
200
 
176
201
  ### Theme build and watch integration
177
202
 
178
203
  For `defineBuild` watch configurations with `ssr` or `publish` callbacks, explicitly set `watch.sources` or `watch.ignored`. Exclude every path those callbacks write inside the project root, including paths outside the preset output directory, to avoid rebuild loops.
179
204
 
180
- `defineThemeBuild` from `bun/theme-build.mjs` supplies the conventional theme layout and flat publication. `entries` replaces the complete entry map; `editor` replaces the editor preset or may be `false`. `responsive` accepts the preset's options or `false`. `css` accepts an async callback receiving `{ root, outdir, stage, responsive, require }` or `false`; `extraCss` still runs afterwards. `discovery` accepts a plugin factory receiving `{ root, setEditorWorker, getEditorWorker }` (also async) or `false`; with either override, callers must provide discovery compatible with their entry sources. `frontendStyles` applies only to default discovery. The built-in editor worker plugin runs before plugins returned by `createPlugins`; replace it via `media.editorWorker` when custom handling is needed. The returned plugin array is not modified. `ssr` replaces `buildSsr` or can be `false`; do not specify both. `publish` replaces the flat publisher with an async callback receiving the build state, or `false` leaves the intermediate build unpublished in `public/.build`. With custom or disabled publication, the SSR callback runs after the browser build and receives the build state and `mode: 'production'`.
205
+ `defineThemeBuild` from `bun/theme-build.mjs` supplies the conventional theme layout and structured publication. `entries` replaces the complete entry map; `editor` replaces the editor preset or may be `false`. `responsive` accepts the preset's options or `false`. `css` accepts an async callback receiving `{ root, outdir, stage, responsive, require }` or `false`; `extraCss` still runs afterwards. `discovery` accepts a plugin factory receiving `{ root, setEditorWorker, getEditorWorker }` (also async) or `false`; with either override, callers must provide discovery compatible with their entry sources. `frontendStyles` applies only to default discovery. The built-in worker plugin runs before plugins returned by `createPlugins`; it resolves worker URLs for frontend, admin and editor bundles using `publicPrefix` and structured surface directories. When used separately without a public prefix, it can use the configured editor script URL identifier. Replace it via `media.editorWorker` when custom handling is needed. The returned plugin array is not modified. `ssr` replaces `buildSsr` or can be `false`; do not specify both. `publish` replaces the structured publisher with an async callback receiving the build state, or `false` leaves the intermediate build unpublished in `public/.build`. With custom or disabled publication, the SSR callback runs after the browser build and receives the build state, `mode: 'production'`, and `outdir` pointing to `public/.build/ssr/production`.
206
+
207
+ ### Shared same-origin UI Components fonts (opt-in)
208
+
209
+ Set `sharedFonts: true` in `defineThemeBuild` only after installing compatible PHP shared-font integration (`infinum/eightshift-libs` 14.0.0-alpha.3) and a UI Components release containing `dist/assets/fonts-manifest.json` (`@eightshift/ui-components` 8.5.0-beta.1). These are the first published versions containing the shared-font contract; earlier releases do not provide it. Fonts remain required: this option changes their provider, not typography. The default is `false`, preserving standalone builds.
210
+
211
+ The current shared-provider contract supports WOFF2 only and rejects other manifest formats. The build verifies UI Components font bytes against their SHA-256 manifest, extracts matching compiled top-level `@font-face` rules from the published CSS, and stages `shared-fonts.json` plus `fonts/<sha256>.<extension>` alongside other assets. Unrelated or mixed-source faces, faces nested inside rules such as `@media`, `@supports` or `@layer`, and faces in separately loaded stylesheets remain in their original stylesheets. Extraction occurs before final stylesheet hashes are calculated. The default staged publisher is required; custom publication is rejected for this option. Missing manifests, integrity mismatches or no matching faces fail the build rather than silently omitting fonts.
212
+
213
+ Compatible Eightshift PHP integration must read the generated manifest and enqueue the required font declarations with same-origin URLs shared across participating themes/plugins. Deploy PHP support and the matching assets together. Existing consumers that embed their own font faces still download their own URLs until rebuilt with this integration. Separate frames still need declarations; browser caching can reuse common URLs when enabled. No remote CDN, database cache or shared-directory write is required.
214
+
215
+ The exported `prepareSharedFonts({ root, flatDir })` helper in `bun/shared-fonts.mjs` is also available for a custom build pipeline. Its historical `flatDir` parameter accepts the prepared publication tree (`publicationRoot`), including nested CSS. It mutates staged CSS and returns publication `extraFiles`/`aliases`; call it before hashing styles, and publish those additions atomically with the CSS. Do not run it directly on active public assets.
181
216
 
182
217
  ### Staged theme publication
183
218
 
@@ -219,6 +254,11 @@ are replaced on successful publication: they cannot preserve old browser session
219
254
  like content-hashed filenames. Additional manifest generation and automatic
220
255
  multi-release retention are not provided. Aliases join the primary manifest and
221
256
  PHP asset cache; consumers needing separate manifests must use custom publication.
257
+ The lower-level `packageRelease` keeps a stylesheet's hashed output in the same
258
+ release directory as its input, preserving relative asset and `@import` URLs.
259
+ Empty stylesheets are valid and retain their manifest entries; missing stylesheets
260
+ and missing or empty JavaScript entries still fail packaging.
261
+ Its `omit` option cannot remove a JavaScript entry targeted by a generated bootstrap.
222
262
 
223
263
  ### Optimizing package imports
224
264
 
@@ -258,15 +298,25 @@ export default defineThemeBuild({
258
298
  - `keys` optionally lists frontend importer keys, such as `components/video` or `custom/example`. Each must match a discovered `src/Blocks/{components,custom}/**/assets/index.js` file, and a key can belong to only one stylesheet group. When an importer is used, its stylesheet loads before the JavaScript; the load is shared between callers. A failed load rejects, removes the link, and can be retried. Without `keys`, the file is built and published but is not loaded automatically.
259
299
  - `href` optionally overrides the URL used by those importers. By default it points to the generated output; custom URLs must be deployed and kept in sync by the project. It has no effect without `keys`.
260
300
 
261
- The default flat publisher includes generated stylesheets in `public/` and its manifest; no alias is required for lazy loading. The output hash changes when compiled CSS changes, including rewritten asset URLs. CSS assets are copied with their own content-hashed names. Publication replaces `public/`, so cached older pages can request files no longer present; retain old releases externally if that matters. For a stable PHP manifest key, set an explicit `output` and an appropriate `aliases` entry. Custom publishers must preserve the CSS and the URL expected by the importer.
301
+ Frontend and admin CSS imported by JavaScript is compiled with Tailwind and loaded before the importing module executes. Styles imported by lazy modules remain unloaded until those modules are requested. Imported stylesheets that generate utilities also scan the generated frontend responsive class list when responsive generation is enabled. Direct imports already included unconditionally by the default conventional CSS compiler are not loaded twice; conditional imports and `@reference` do not suppress a separate JavaScript import. A direct import that matches a single-file keyed `extraCss` group uses the same stylesheet URL as the keyed loader; multi-file groups and CSS modules are compiled independently. Existing `frontendStyles` and other multi-file group contents are not automatically deduplicated against JavaScript imports. When a stylesheet imports CSS modules, Tailwind `@import` modifiers such as `source()`, `prefix()` and `theme()` are not supported there. Import that configured Tailwind entry separately and use `@reference`; unsupported combinations fail the build rather than producing incorrect styles.
302
+
303
+ The generated browser modules use top-level `await` and add stylesheet requests, which can affect startup or lazy-load timings. If a keyed `extraCss` load fails before its module is imported, the loader can retry; a failed JavaScript module evaluation can remain cached by the browser and may require a page reload. Custom build plugins must not bypass the theme CSS loader unless they also provide custom publication; unexpected Bun CSS output fails the build instead of being silently omitted.
304
+
305
+ The default structured publisher includes generated stylesheets in `public/` and its manifest; no alias is required for lazy loading. The output hash changes when compiled CSS changes, including rewritten asset URLs. CSS assets are copied with their own content-hashed names. Publication replaces `public/`, so cached older pages can request files no longer present; retain old releases externally if that matters. For a stable PHP manifest key, set an explicit `output` and an appropriate `aliases` entry. Custom publishers must preserve the CSS and the URL expected by the importer.
262
306
 
263
307
  The build regenerates discovery and CSS on each rebuild. Watch monitors the configured project paths, not `node_modules` or arbitrary external files by default; customize `watch.sources` for additional inputs. Default theme builds use production CSS processing, including Lightning CSS minification and its browser targets, even in watch mode. `extraCss` may also be an async hook receiving `{ root, stage, require }`, or `false` to disable it. Hooks are responsible for their own filenames and loading behavior. `frontendStyles` separately attaches existing URLs to keys; both automatic mechanisms require default discovery.
264
308
 
265
- Default flat publication requires frontend, admin and editor entries, an editor build, and CSS at the conventional filenames. It scans the conventional SSR source glob and expects matching outputs in `.bun-pilot/theme-build/ssr/production`. With default publication, custom `ssr` (or legacy `buildSsr`) callbacks receive `{ root, mode: 'production', outdir }`, where `outdir` is the absolute path to that SSR output directory. Callbacks must finish writing `<name>.js` files there before resolving, where `<name>` is the directory containing each conventional `assets-ssr` directory; `packageFlatRelease` reads those files from the same directory. Use `ssr: false` to omit SSR or supply custom publication for a different layout. Disabling responsive generation requires custom or disabled CSS. Custom publication is required when disabling CSS or the editor, or changing the entry set. With custom or disabled publication, intermediate output remains in `public/.build`; the project owns its publication and cleanup.
309
+ Default structured publication requires frontend, admin and editor entries, an editor build, and CSS at the conventional filenames. It scans the conventional SSR source glob and expects matching outputs in `.bun-pilot/theme-build/ssr/production`. With default publication, custom `ssr` (or legacy `buildSsr`) callbacks receive `{ root, mode: 'production', outdir }`, where `outdir` is the absolute path to that SSR output directory. Callbacks must finish writing `<name>.js` files there before resolving, where `<name>` is the directory containing each conventional `assets-ssr` directory; `packageFlatRelease` reads those files from the same directory. Use `ssr: false` to omit SSR or supply custom publication for a different layout. Disabling responsive generation requires custom or disabled CSS. Custom publication is required when disabling CSS or the editor, or changing the entry set. With custom or disabled publication, intermediate output remains in `public/.build`; the project owns its publication and cleanup.
310
+
311
+ The default SSR builder compiles all discovered entries together into standalone Node CJS bundles, without shared chunks or sourcemaps. Output filenames remain `<block-or-component-directory>.js`; duplicate names are rejected before compilation. Caller-supplied plugins retain one sequential compilation per entry to preserve their per-build lifecycle. Compilation omits Bun's `outdir` so it stays in memory (Bun 1.4.4 can write files when `outdir` is set even with `write: false`). All outputs are validated before explicit writes; compilation failures leave existing files untouched. Returned `outputs[].path` is the publication path, while `outputs[].output.path` is Bun's intermediate artifact path. `write: false` never creates the output directory. The low-level builder does not prune old files when entries are removed; the theme preset rebuilds its owned staging directory. Writes are sequential, not an atomic transaction for I/O failures. Multi-entry compilation can retain additional dependency definitions and change bundle bytes; it does not guarantee byte identity with separate compilations.
266
312
 
267
- WordPress externalization is enabled by default. Set `wpRoot` to the WordPress installation when using externalized `@wordpress/*` imports; export discovery reads its core scripts and requires compatible installed package metadata. The adapter also maps React and selected common dependencies to WordPress globals. Those globals and script handles must be available at runtime. Set `wordpress: false` to disable this adapter. For direct Bun integration, `wordpressPlugin({ projectRoot, wpRoot })` returns `{ plugin, dependencies, getEmittedDependencies }`; use a fresh adapter for each build and absolute paths. `dependencies` contains all resolved handles. Request a Bun metafile and pass it to `getEmittedDependencies(metafile)` to derive handles from every emitted output; invalid metadata falls back to all resolved handles. Some Bun versions can throw when reading `result.metafile` itself, so catch that access and fall back to `dependencies` too.
313
+ Externalized `@wordpress/*` browser imports do not require matching JavaScript packages in the theme or plugin. Their exports and default-global mappings come from the target WordPress installation. Packages deliberately bundled by the adapter, and packages used by SSR or builds with `wordpress: false`, still need to be installed. React, React DOM and `lodash-es` also retain their installed-package export-discovery requirements.
268
314
 
269
- `processCss` compiles the `files` array in order into one output file. Each item is a path or `{ file, scan, sources, scanFiles, removeSources }`: scanning is opt-in; `sources` adds Tailwind scanner source objects, `scanFiles` adds explicit candidate files, and `removeSources` removes exact source-rule strings (and fails if absent). Relative paths resolve from `projectDir`. Local URL assets are copied next to the CSS with content-hashed names. Production uses Lightning CSS and the `browsers` option (default `>= 0.25%`); the return value includes `outputFile` and discovered `dependencies`. Watch does not automatically use those dependencies. `responsive: {}` generates frontend and editor class lists from `src/**/manifest.json`, expanding responsive classes for `sm` and `md`; customize `breakpoints`, `manifestGlob`, and `output`. Pass the relevant generated list to CSS scanning, as above. The standalone `generateResponsiveClasses({ projectDir, ... })` is also exported from `bun/build.mjs`.
315
+ WordPress externalization is enabled by default. Set `wpRoot` to the WordPress installation when using externalized `@wordpress/*` imports; export discovery reads its core scripts without requiring installed package metadata. WordPress scripts without an export table are treated as side-effect-only dependencies: no exported global is required, and their handles are retained even when Bun erases the empty adapter. Resolved side-effect-only handles are retained conservatively, including when their importing code is later tree-shaken. The adapter also maps React and selected common dependencies to WordPress globals. Those globals and script handles must be available at runtime. Set `wordpress: false` to disable this adapter. For direct Bun integration, `wordpressPlugin({ projectRoot, wpRoot })` returns `{ plugin, dependencies, getEmittedDependencies }`; use a fresh adapter for each build and absolute paths. `dependencies` contains all resolved handles. Request a Bun metafile and pass it to `getEmittedDependencies(metafile)` to derive handles from every emitted output; invalid metadata falls back to all resolved handles. Some Bun versions can throw when reading `result.metafile` itself, so catch that access and fall back to `dependencies` too.
316
+
317
+ `processCss` compiles the `files` array in order into one output file. Each item is a path or `{ file, content, scan, sources, scanFiles, removeSources }`: optional `content` replaces the source text while `file` remains the base for imports; scanning is opt-in; `scan: 'auto'` scans only when the stylesheet requests utility generation; `sources` adds Tailwind scanner source objects, `scanFiles` adds explicit candidate files even when those paths are excluded from automatic scanning, and `removeSources` removes exact source-rule strings (and fails if absent). Relative paths resolve from `projectDir`. Local URL assets, including string URLs in `image-set()` and `-webkit-image-set()`, are copied next to the CSS with content-hashed names. Production uses Lightning CSS and the `browsers` option (default `>= 0.25%`); the return value includes `outputFile` and discovered `dependencies`. Watch does not automatically use those dependencies. `responsive: {}` generates frontend and editor class lists from `src/**/manifest.json`, expanding responsive classes for `sm` and `md`; customize `breakpoints`, `manifestGlob`, and `output`. Pass the relevant generated list to CSS scanning, as above. The standalone `generateResponsiveClasses({ projectDir, ... })` is also exported from `bun/build.mjs`.
318
+
319
+ The editor discovery transforms match parsed JavaScript call expressions, not comments, string contents or JSX text. Generated context bindings avoid identifiers already present in the source. Unsupported executable `require.context` arguments still fail the build.
270
320
 
271
321
  For Webpack context replacements, generate a module before building and import its named context in your application:
272
322
 
@@ -339,3 +389,90 @@ Eightshift Frontend Libs Tailwind is maintained and sponsored by
339
389
 
340
390
  ## License
341
391
  Eightshift Frontend Libs Tailwind [Eightshift](https://eightshift.com) and [Infinum](https://infinum.com). This is free software, and may be redistributed under the terms specified in the LICENSE file.
392
+
393
+ ### CLI watch process restarts
394
+
395
+ `eightshift-build watch` keeps ordinary source watching in the configured watcher.
396
+ It polls the selected config file and the working directory's `package.json`,
397
+ `bun.lock`, and `bun.lockb` for content changes (100 ms polling, 200 ms settling),
398
+ then drains the old worker before importing configuration in a fresh Bun process.
399
+ Missing files and atomic replacements are detected. Invalid configuration prints
400
+ its error and waits for another restart-input change instead of respawning in a loop.
401
+ A worker failure remains reflected in the supervisor's eventual exit status.
402
+
403
+ This is an explicit boundary, not dependency discovery. Nested dependency manifests,
404
+ installed library edits, imported config helpers, other lockfiles and environment
405
+ changes require manually stopping and starting the CLI. In particular, editing a
406
+ nested package's exports alone does not trigger a restart; changing a root restart
407
+ input afterward loads it fresh. Install transactions should finish before restarting.
408
+ Programmatic `defineBuild`/`watchBuild` behavior and custom watch options are unchanged.
409
+
410
+ SIGINT/SIGTERM request shutdown even during configuration loading. Interrupted
411
+ one-shot builds exit nonzero, including when stopped before the build begins.
412
+ The CLI waits
413
+ for config loading and the watcher's `stop()` promise; it never force-kills a slow
414
+ build or launches a concurrent replacement. A hung import or callback can therefore
415
+ hold shutdown indefinitely. Custom watchers must stop scheduling and drain all
416
+ work in `stop()`. Custom SSR/publication callbacks remain responsible for their own
417
+ transactional guarantees: process serialization does not provide rollback across
418
+ browser assets, SSR and custom publication. Reported build errors retain the
419
+ configured watcher's existing reporting/recovery behavior.
420
+
421
+ ### Structured publication (only built-in layout; breaking change)
422
+
423
+ Conventional `defineThemeBuild` publication retains compiler surface subdirectories
424
+ (`frontend/`, `admin/`, `editor/`, `css/`). Public manifest keys remain stable, but
425
+ their target URLs change. Consumers must resolve assets through the manifest rather
426
+ than assuming root-level filenames. The `publicationLayout` option has been removed:
427
+ remove it even when its value was `'structured'`. Explicit use is rejected rather
428
+ than silently ignored. The legacy `flattenAssets` implementation/export is removed.
429
+
430
+ Migrate `publication` hooks to use the provided `publicationRoot` for the prepared
431
+ public tree, not `resolve(outdir, 'flat')`. This is a stable directory contract:
432
+ the directory contains the collected nested outputs before packaging, and aliases
433
+ are relative to it. Its absolute path is staging-only; do not persist it or depend
434
+ on its basename. Enumerate nested files when needed and include their directory
435
+ names in aliases. `outdir` remains the compiler staging directory. Fixed UTM/player
436
+ outputs remain supported through `extraFiles: [{ source, destination }]` and aliases
437
+ mapping public manifest keys to those destinations.
438
+
439
+ Custom `publish` functions and `publish: false` remain supported and own publication,
440
+ but theme compiler URLs now always target structured surface directories. Custom
441
+ publishers must preserve those paths or explicitly implement their own relocation.
442
+ A `publication` hook is preferred for extending the built-in publisher. Low-level
443
+ `defineBuild`, `packageRelease` and `packageFlatRelease` remain layout-neutral and
444
+ keep their existing defaults. Despite their historical names, `packageFlatRelease`
445
+ and `publishFlatRelease` in `bun/flat-publication.mjs` operate on prepared trees,
446
+ including nested files; their API is retained for existing custom publishers.
447
+
448
+ Structured conventional CSS omits unreferenced stable entry styles only after the
449
+ same-directory hashed stylesheet and manifest are generated. Alias targets and
450
+ references in packaged files or generated wrappers retain the stable stylesheet;
451
+ queries, fragments and escaped names are considered conservatively. Custom `css`
452
+ callbacks retain their entry styles. Hooks that construct CSS URLs dynamically
453
+ must pin the stable path with an alias; static inspection cannot certify computed
454
+ URLs. Extra styles, script intermediates and source maps are not blanket-removed.
455
+ Low-level packagers can opt into this scoped behavior with
456
+ `removeUnreferencedStyles: true`; this is not a general unused-asset collector.
457
+
458
+ This default does not change cache synchronization, retention, rollback policy,
459
+ or active site configuration. The removed flat layout cannot be restored with a configuration option; keep the
460
+ previous complete release and its compatible tooling when deploying or rolling back.
461
+ Low-level builds and presets optionally accept `entryPublicPaths`, an object mapping
462
+ existing entry names to root-relative public URL prefixes ending in `/`. Omitted
463
+ entries continue using `buildOptions.publicPath`; editor output keeps its editor
464
+ builder URL contract. Shared fonts support nested stylesheet paths.
465
+
466
+ Local CSS asset URL pathnames are percent-decoded once before filesystem resolution.
467
+ Query strings and fragments are preserved on published URLs. Encode literal `%`
468
+ characters as `%25`; malformed pathname encoding fails with an explicit error.
469
+ Remote URLs are left unchanged.
470
+
471
+ ## Source formatting
472
+
473
+ Run `bun run lintJs bun bin linters scripts eslint.config.mjs` to check maintained
474
+ JavaScript sources. Add `--fix --fix-type layout,suggestion` to apply formatting
475
+ fixes. The repository configuration requires braces for control-flow statements,
476
+ blank lines before control flow and returns, and separation after blocks. These
477
+ rules also cover `.mjs` build helpers. Tests, packaged output, dependencies and
478
+ compiled output are excluded; the published consumer lint configuration is unchanged.
package/bin/tw-sweep.mjs CHANGED
@@ -34,16 +34,25 @@ function parseArgs(argv) {
34
34
  for (let i = 0; i < argv.length; i++) {
35
35
  const a = argv[i];
36
36
 
37
- if (a === '--entry') opts.entry = argv[++i];
38
- else if (a === '--include') opts.include = argv[++i].split(',').map((s) => s.trim());
39
- else if (a === '--exclude') opts.exclude = argv[++i].split(',').map((s) => s.trim());
40
- else if (a === '--ignore-file') opts.ignoreFile = argv[++i];
41
- else if (a === '--no-unknown') opts.unknown = false;
42
- else if (a === '--root-font-size') opts.rootFontSize = Number(argv[++i]);
43
- else if (a === '--write') opts.write = true;
44
- else if (a === '--check') opts.write = false;
45
- else if (a === '-h' || a === '--help') opts.help = true;
46
- else if (a.startsWith('--')) {
37
+ if (a === '--entry') {
38
+ opts.entry = argv[++i];
39
+ } else if (a === '--include') {
40
+ opts.include = argv[++i].split(',').map((s) => s.trim());
41
+ } else if (a === '--exclude') {
42
+ opts.exclude = argv[++i].split(',').map((s) => s.trim());
43
+ } else if (a === '--ignore-file') {
44
+ opts.ignoreFile = argv[++i];
45
+ } else if (a === '--no-unknown') {
46
+ opts.unknown = false;
47
+ } else if (a === '--root-font-size') {
48
+ opts.rootFontSize = Number(argv[++i]);
49
+ } else if (a === '--write') {
50
+ opts.write = true;
51
+ } else if (a === '--check') {
52
+ opts.write = false;
53
+ } else if (a === '-h' || a === '--help') {
54
+ opts.help = true;
55
+ } else if (a.startsWith('--')) {
47
56
  console.error(`Unknown flag: ${a}`);
48
57
  process.exit(EXIT_USAGE);
49
58
  } else {
@@ -96,7 +105,9 @@ function findDefaultEntry(cwd) {
96
105
 
97
106
  for (let dir = cwd; ; dir = resolve(dir, '..')) {
98
107
  for (const name of candidates) {
99
- if (importsTailwind(resolve(dir, name))) return resolve(dir, name);
108
+ if (importsTailwind(resolve(dir, name))) {
109
+ return resolve(dir, name);
110
+ }
100
111
  }
101
112
 
102
113
  const wpThemes = resolve(dir, 'wp-content/themes');
@@ -104,12 +115,16 @@ function findDefaultEntry(cwd) {
104
115
  if (existsSync(wpThemes)) {
105
116
  for (const theme of readdirSync(wpThemes)) {
106
117
  for (const name of candidates) {
107
- if (importsTailwind(resolve(wpThemes, theme, name))) return resolve(wpThemes, theme, name);
118
+ if (importsTailwind(resolve(wpThemes, theme, name))) {
119
+ return resolve(wpThemes, theme, name);
120
+ }
108
121
  }
109
122
  }
110
123
  }
111
124
 
112
- if (resolve(dir, '..') === dir) return null;
125
+ if (resolve(dir, '..') === dir) {
126
+ return null;
127
+ }
113
128
  }
114
129
  }
115
130
 
@@ -149,6 +164,7 @@ async function main() {
149
164
 
150
165
  if (args.help) {
151
166
  printHelp();
167
+
152
168
  return EXIT_OK;
153
169
  }
154
170
 
@@ -157,6 +173,7 @@ async function main() {
157
173
 
158
174
  if (!entryPath || !existsSync(entryPath)) {
159
175
  console.error(entryPath ? `Entry CSS not found: ${entryPath}` : "Could not locate a Tailwind CSS entry that imports 'tailwindcss'. Pass --entry <path>.");
176
+
160
177
  return EXIT_USAGE;
161
178
  }
162
179
 
@@ -166,6 +183,7 @@ async function main() {
166
183
  ignore = loadTwIgnore(args.ignoreFile, cwd).map((pattern) => new RegExp(pattern));
167
184
  } catch (error) {
168
185
  console.error(error.message);
186
+
169
187
  return EXIT_USAGE;
170
188
  }
171
189
 
@@ -179,7 +197,9 @@ async function main() {
179
197
  const found = new Set();
180
198
 
181
199
  for (const pattern of includes) {
182
- for (const m of await glob(pattern, { cwd, ignore: excludes, absolute: true })) found.add(m);
200
+ for (const m of await glob(pattern, { cwd, ignore: excludes, absolute: true })) {
201
+ found.add(m);
202
+ }
183
203
  }
184
204
 
185
205
  files = [...found].sort();
@@ -187,6 +207,7 @@ async function main() {
187
207
 
188
208
  if (files.length === 0) {
189
209
  process.stderr.write('No files matched.\n');
210
+
190
211
  return EXIT_OK;
191
212
  }
192
213