@eightshift/frontend-libs-tailwind 4.0.0-beta.4 → 4.0.0-beta.6

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.
package/CHANGELOG.md CHANGED
@@ -8,13 +8,39 @@ 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.6
12
+
13
+ - Add the boolean `removeUnreferencedStyles` option to `defineThemeBuild` so custom CSS callbacks can opt into removing unreferenced entry stylesheet originals after generating hashed replacements. Existing defaults remain unchanged; aliases and detected references retain originals. Custom or disabled publishers cannot use this option.
14
+ - Document the cleanup opt-in and the requirement to pin dynamically constructed stable CSS URLs with aliases; extra styles, lazy CSS, source maps and CSS compilation remain unchanged.
15
+
16
+ ### 4.0.0-beta.5
17
+
18
+ - Use ESLint 9 to satisfy the React lint plugin peer range without changing lint rules.
19
+ - Support stable UI Components 8 and explicitly allow 8.5.0-beta.1; validate locally against that exact published beta.
20
+
21
+ - Preserve generic PHP class extraction alongside the documented Tailwind helper patterns.
22
+ - ESLint 9 remains a known end-of-life risk; a major upgrade is deferred pending React plugin peer compatibility.
23
+
11
24
  ### 4.0.0-beta.4
12
25
 
26
+ - **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.
27
+ - 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.
28
+
13
29
  - Default conventional theme editor builds to unified sharing; compatible PHP module-readiness integration is required.
14
30
  - 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.
15
31
  - Compile default SSR entries together as standalone CommonJS bundles; preserve sequential compilation for caller plugins and prevent implicit writes during compilation.
16
32
  - Restart CLI watch workers on selected configuration, root package manifest and Bun lockfile changes, draining active work before replacement.
17
33
  - Accept both verified generated Smart Image worker URL forms.
34
+ - Resolve externalized WordPress package exports and default globals from core scripts without requiring installed package metadata; remove the API-fetch peer requirement.
35
+ - Preserve isolated editor store IDs across projects without changing them on every rebuild.
36
+ - Compile JavaScript-imported frontend and admin CSS and load it with its importing module, preserving lazy boundaries; resolve Smart Image workers on each surface.
37
+ - Preserve relative asset URLs in nested release stylesheets and retain conditional shared-font rules in their original stylesheets.
38
+ - Preserve eager JavaScript discovery contexts and recognize escaped editor stylesheet patterns.
39
+ - Preserve CommonJS-style WordPress core exports instead of treating them as side-effect-only scripts.
40
+ - Publish local string image URLs in CSS `image-set()` declarations.
41
+ - Decode percent-encoded local CSS asset paths once, preserving query strings and fragments; report malformed path encoding clearly.
42
+ - Allow empty release stylesheets while continuing to reject missing files and empty JavaScript entries.
43
+ - Exit nonzero when a one-shot CLI build is interrupted, including during configuration loading.
18
44
 
19
45
  ### Changed
20
46
 
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
 
@@ -71,7 +71,7 @@ export default defineThemeBuild({
71
71
  sharing: 'independent',
72
72
  discovery: {
73
73
  filter: /application-blocks-editor\.js$/,
74
- omitContexts: ({ pattern }) => pattern.source === 'styles-editor.css$',
74
+ omitContexts: ({ pattern }) => ['styles-editor.css$', 'styles-editor\\.css$'].includes(pattern.source),
75
75
  },
76
76
  },
77
77
  });
@@ -145,7 +145,7 @@ export default defineThemeBuild({
145
145
  sharing: 'native',
146
146
  discovery: {
147
147
  filter: /application-blocks-editor\.js$/,
148
- omitContexts: ({ pattern }) => pattern.source === 'styles-editor.css$',
148
+ omitContexts: ({ pattern }) => ['styles-editor.css$', 'styles-editor\\.css$'].includes(pattern.source),
149
149
  },
150
150
  },
151
151
  });
@@ -202,17 +202,17 @@ The earlier `editor.sharedPackages` vendor-bridge experiment was removed. Existi
202
202
 
203
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.
204
204
 
205
- `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
206
 
207
207
  ### Shared same-origin UI Components fonts (opt-in)
208
208
 
209
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
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 `@font-face` rules from the published CSS, and stages `shared-fonts.json` plus `fonts/<sha256>.<extension>` alongside other assets. Unrelated or mixed-source faces remain untouched. 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.
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
212
 
213
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
214
 
215
- The exported `prepareSharedFonts({ root, flatDir })` helper in `bun/shared-fonts.mjs` is also available for a custom build pipeline. It mutates staged flat 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.
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.
216
216
 
217
217
  ### Staged theme publication
218
218
 
@@ -254,6 +254,11 @@ are replaced on successful publication: they cannot preserve old browser session
254
254
  like content-hashed filenames. Additional manifest generation and automatic
255
255
  multi-release retention are not provided. Aliases join the primary manifest and
256
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.
257
262
 
258
263
  ### Optimizing package imports
259
264
 
@@ -293,17 +298,25 @@ export default defineThemeBuild({
293
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.
294
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`.
295
300
 
296
- 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.
297
306
 
298
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.
299
308
 
300
- 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.
301
310
 
302
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.
303
312
 
304
- 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.
314
+
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.
305
316
 
306
- `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`.
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.
307
320
 
308
321
  For Webpack context replacements, generate a module before building and import its named context in your application:
309
322
 
@@ -394,7 +407,9 @@ nested package's exports alone does not trigger a restart; changing a root resta
394
407
  input afterward loads it fresh. Install transactions should finish before restarting.
395
408
  Programmatic `defineBuild`/`watchBuild` behavior and custom watch options are unchanged.
396
409
 
397
- SIGINT/SIGTERM request shutdown even during configuration loading. The CLI waits
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
398
413
  for config loading and the watcher's `stop()` promise; it never force-kills a slow
399
414
  build or launches a concurrent replacement. A hung import or callback can therefore
400
415
  hold shutdown indefinitely. Custom watchers must stop scheduling and drain all
@@ -402,3 +417,69 @@ work in `stop()`. Custom SSR/publication callbacks remain responsible for their
402
417
  transactional guarantees: process serialization does not provide rollback across
403
418
  browser assets, SSR and custom publication. Reported build errors retain the
404
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 by default. With the default publisher, set
453
+ `defineThemeBuild({ root, css: customCss, removeUnreferencedStyles: true })` to opt
454
+ custom CSS into the same scoped cleanup, or set `removeUnreferencedStyles: false`
455
+ to retain originals with the conventional compiler. The option must be a boolean
456
+ and cannot be supplied with custom or disabled `publish`. It does not change CSS
457
+ compilation, order, hashed stylesheet contents, or `extraCss` handling. Install a
458
+ library version `4.0.0-beta.6` or newer before enabling it; beta.5 ignores it.
459
+ Hooks that construct CSS URLs dynamically
460
+ must pin the stable path with an alias; static inspection cannot certify computed
461
+ URLs. Extra styles, script intermediates and source maps are not blanket-removed.
462
+ Low-level packagers can opt into this scoped behavior with
463
+ `removeUnreferencedStyles: true`; this is not a general unused-asset collector.
464
+
465
+ This default does not change cache synchronization, retention, rollback policy,
466
+ or active site configuration. The removed flat layout cannot be restored with a configuration option; keep the
467
+ previous complete release and its compatible tooling when deploying or rolling back.
468
+ Low-level builds and presets optionally accept `entryPublicPaths`, an object mapping
469
+ existing entry names to root-relative public URL prefixes ending in `/`. Omitted
470
+ entries continue using `buildOptions.publicPath`; editor output keeps its editor
471
+ builder URL contract. Shared fonts support nested stylesheet paths.
472
+
473
+ Local CSS asset URL pathnames are percent-decoded once before filesystem resolution.
474
+ Query strings and fragments are preserved on published URLs. Encode literal `%`
475
+ characters as `%25`; malformed pathname encoding fails with an explicit error.
476
+ Remote URLs are left unchanged.
477
+
478
+ ## Source formatting
479
+
480
+ Run `bun run lintJs bun bin linters scripts eslint.config.mjs` to check maintained
481
+ JavaScript sources. Add `--fix --fix-type layout,suggestion` to apply formatting
482
+ fixes. The repository configuration requires braces for control-flow statements,
483
+ blank lines before control flow and returns, and separation after blocks. These
484
+ rules also cover `.mjs` build helpers. Tests, packaged output, dependencies and
485
+ 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