diff --git a/.changepacks/changepack_log_lazy_transform_css.json b/.changepacks/changepack_log_lazy_transform_css.json new file mode 100644 index 000000000..290df71ac --- /dev/null +++ b/.changepacks/changepack_log_lazy_transform_css.json @@ -0,0 +1,10 @@ +{ + "changes": { + "bindings/devup-ui-binding/package.json": "Patch", + "bindings/devup-ui-wasm/package.json": "Patch", + "packages/next-plugin/package.json": "Patch", + "packages/webpack-plugin/package.json": "Patch" + }, + "note": "Serialize the CSS a transform returns only when it is read: a read after later transforms or setting changes still returns the sheet as that transform left it. The Next.js loader and prewarm never read it, and the Webpack loader reads it only when it writes it, so single-CSS builds no longer serialize the whole sheet after every module. The output is byte-identical.", + "date": "2026-11-15T00:00:00.000Z" +} diff --git a/bindings/devup-ui-binding/src/output.rs b/bindings/devup-ui-binding/src/output.rs index 48a85f9ac..2c46a7c42 100644 --- a/bindings/devup-ui-binding/src/output.rs +++ b/bindings/devup-ui-binding/src/output.rs @@ -3,6 +3,7 @@ use napi::{Env, Result}; use napi_derive::napi; use crate::value::binding_error; +use devup_ui_binding_core::LazyCss; /// Materialized native output with an explicitly consumable payload. #[napi(js_name = "Output")] @@ -42,7 +43,7 @@ impl NativeOutput { /// Copy changed CSS, using undefined for absence. #[napi(getter)] pub fn css(&self, env: Env) -> Result> { - Ok(self.live(env)?.css.clone().into()) + Ok(self.live(env)?.css.as_ref().map(LazyCss::get).into()) } /// Copy the optional stylesheet filename. #[napi(getter, js_name = "cssFile")] diff --git a/bindings/devup-ui-wasm/src/lib.rs b/bindings/devup-ui-wasm/src/lib.rs index 067b5abb6..817dbc9dc 100644 --- a/bindings/devup-ui-wasm/src/lib.rs +++ b/bindings/devup-ui-wasm/src/lib.rs @@ -54,7 +54,7 @@ pub struct Output { map: Option, css_file: Option, updated_base_style: bool, - css: Option, + css: Option, dependencies: Vec, } @@ -132,7 +132,7 @@ impl Output { #[wasm_bindgen(getter, js_name = "css")] #[must_use] pub fn css(&self) -> Option { - self.css.clone() + self.css.as_ref().map(binding_core::LazyCss::get) } /// Files read through the module resolver, for the bundler to watch diff --git a/bindings/devup-ui-wasm/src/reservation/tests.rs b/bindings/devup-ui-wasm/src/reservation/tests.rs index 1d27f337e..3741b4178 100644 --- a/bindings/devup-ui-wasm/src/reservation/tests.rs +++ b/bindings/devup-ui-wasm/src/reservation/tests.rs @@ -375,7 +375,7 @@ fn resolved_token_keys_are_reserved_before_real_output() -> TestResult { ), &option, )?; - let css = output.css.ok_or("expected token CSS")?; + let css = output.css.ok_or("expected token CSS")?.get(); assert!(css.contains("width:var(--size)")); assert!(css.contains("box-shadow:var(--card)")); assert!(!css.contains("$size")); diff --git a/libs/binding/src/css_cache.rs b/libs/binding/src/css_cache.rs index 61e005049..c6fdda54f 100644 --- a/libs/binding/src/css_cache.rs +++ b/libs/binding/src/css_cache.rs @@ -83,6 +83,7 @@ impl Deref for SheetGuard<'_> { impl DerefMut for SheetGuard<'_> { fn deref_mut(&mut self) -> &mut StyleSheet { + crate::lazy_css::settle(&self.0); invalidate_css(); &mut self.0 } diff --git a/libs/binding/src/lazy_css.rs b/libs/binding/src/lazy_css.rs new file mode 100644 index 000000000..a4ac7fdec --- /dev/null +++ b/libs/binding/src/lazy_css.rs @@ -0,0 +1,77 @@ +//! The CSS a transform returns, serialized only when the host reads it. +//! +//! Most hosts never read it, and serializing the shared base after every +//! transform is quadratic over a single-CSS build. The value is still the sheet +//! as that transform left it: the sheet, and every setting a serialization +//! reads, changes only after the one unread result has been serialized. + +use css::atom_hoist::{AtomModeGuard, is_suppressed}; +use sheet::StyleSheet; +use std::sync::{Arc, Mutex, MutexGuard, PoisonError, Weak}; + +use crate::css_cache::cached_css; +use crate::with_style_sheet; + +struct Pending { + bucket: Option, + import_main_css: bool, + /// Whether the transform suppressed atom mode while it committed. + suppressed: bool, + value: Mutex>, +} + +/// The latest transform result, which alone can describe the current sheet. +static PENDING: Mutex> = Mutex::new(Weak::new()); + +fn lock(mutex: &Mutex) -> MutexGuard<'_, T> { + mutex.lock().unwrap_or_else(PoisonError::into_inner) +} + +impl Pending { + /// The value, serializing `sheet` under the transform's atom mode on the first call. + fn value(&self, sheet: &StyleSheet) -> String { + lock(&self.value) + .get_or_insert_with(|| { + let _mode = AtomModeGuard::exact(self.suppressed); + cached_css(sheet, self.bucket.as_deref(), self.import_main_css) + }) + .clone() + } +} + +/// CSS of a transform, serialized on its first read. +pub struct LazyCss(Arc); + +impl LazyCss { + /// Defer serializing `bucket` (the shared base when `None`) of the sheet as it stands. + pub(crate) fn defer(bucket: Option<&str>, import_main_css: bool) -> Self { + let pending = Arc::new(Pending { + bucket: bucket.map(str::to_string), + import_main_css, + suppressed: is_suppressed(), + value: Mutex::default(), + }); + *lock(&PENDING) = Arc::downgrade(&pending); + Self(pending) + } + + /// The CSS of the sheet as the transform left it. + #[must_use] + pub fn get(&self) -> String { + with_style_sheet(|sheet| self.0.value(sheet)) + } +} + +/// Serialize the unread result of the latest transform before `sheet`, or a +/// setting its serialization reads, changes. A dropped result costs nothing. +pub(crate) fn settle(sheet: &StyleSheet) { + let pending = std::mem::take(&mut *lock(&PENDING)).upgrade(); + if let Some(pending) = pending { + pending.value(sheet); + } +} + +/// Settle before a setting that serializations read changes. +pub(crate) fn settle_live() { + with_style_sheet(settle); +} diff --git a/libs/binding/src/lib.rs b/libs/binding/src/lib.rs index a7d7a4c23..616c26440 100644 --- a/libs/binding/src/lib.rs +++ b/libs/binding/src/lib.rs @@ -1,6 +1,7 @@ //! Host-neutral binding orchestration; JavaScript values belong to the host adapter. mod css_cache; +mod lazy_css; mod output; mod reservation; mod resolver_state; @@ -10,6 +11,7 @@ pub use css::slot_reservation::unreserved_slot_count as get_unreserved_class_slo pub use css::{get_prefix, set_custom_shorthands as register_shorthands_internal, set_prefix}; pub use css_cache::{SheetCell, SheetGuard}; pub use extractor::{has_devup_ui, has_devup_ui_with}; +pub use lazy_css::LazyCss; pub use output::{CssOptions, ExtractionMode, Output, SourceMapMode, code_extract}; pub use reservation::{ReservationInput, reserve_class_slots_internal}; pub use resolver_state::{ResolverRequest, ResolverState, check_resolved_path, resolved_module}; @@ -47,8 +49,8 @@ where f(&mut guard) } -/// Mutably borrow the live stylesheet for a change that forgets the -/// serializations itself, and only when it changed the sheet. +/// Mutably borrow the live stylesheet for a change that settles the unread CSS +/// and forgets the serializations itself, and only when it changed the sheet. fn with_style_sheet_untracked(f: F) -> R where F: FnOnce(&mut StyleSheet) -> R, @@ -61,13 +63,19 @@ where /// Hoist atoms shared by `threshold` routes, or stop hoisting with `None`. pub fn set_atom_hoist(threshold: Option) { - css::atom_hoist::set_atom_hoist(threshold); - invalidate_css(); + change_setting(|| css::atom_hoist::set_atom_hoist(threshold)); } /// Restore the routes each file reaches, which plan atom hoisting. pub fn import_file_routes_internal(map: HashMap>) { - css::file_routes::set_file_routes(map); + change_setting(|| css::file_routes::set_file_routes(map)); +} + +/// Change a setting that serializations read: the unread CSS of the latest +/// transform is serialized before, and every serialization forgotten after. +fn change_setting(change: impl FnOnce()) { + lazy_css::settle_live(); + change(); invalidate_css(); } @@ -78,7 +86,7 @@ fn error_text(error: impl std::fmt::Display) -> String { /// Restore the sheet and its frozen atom plan together. pub fn import_sheet_internal(sheet: StyleSheet) { - css::atom_hoist::restore_atom_plan(sheet.atom_plan.clone()); + change_setting(|| css::atom_hoist::restore_atom_plan(sheet.atom_plan.clone())); with_style_sheet_mut(|global_sheet| *global_sheet = sheet); } @@ -120,8 +128,7 @@ pub fn export_file_map_internal() -> Result { /// Restore canonical bucket identities decoded by a host adapter. pub fn import_canonical_map_internal(map: HashMap) { - set_canonical_map(map); - invalidate_css(); + change_setting(|| set_canonical_map(map)); } /// Export canonical bucket identities in path order. @@ -154,14 +161,16 @@ pub fn remove_file_internal(filename: &str) -> bool { /// Clear production build state, retaining theme registries, shorthands and debug. /// The host adapter separately clears its resolver handle. pub fn reset_build_state_internal() { - css::slot_reservation::reset(); - css::class_map::reset_class_map(); - css::file_map::reset_file_map(); - css::file_map::reset_canonical_map(); - css::file_routes::set_file_routes(HashMap::new()); - css::atom_hoist::set_atom_hoist(None); - css::atom_hoist::restore_atom_plan(None); - css::set_prefix(None); + change_setting(|| { + css::slot_reservation::reset(); + css::class_map::reset_class_map(); + css::file_map::reset_file_map(); + css::file_map::reset_canonical_map(); + css::file_routes::set_file_routes(HashMap::new()); + css::atom_hoist::set_atom_hoist(None); + css::atom_hoist::restore_atom_plan(None); + css::set_prefix(None); + }); with_style_sheet_mut(|sheet| *sheet = StyleSheet::default()); } diff --git a/libs/binding/src/output.rs b/libs/binding/src/output.rs index bdc3466da..8533eb798 100644 --- a/libs/binding/src/output.rs +++ b/libs/binding/src/output.rs @@ -4,7 +4,8 @@ use extractor::{ extract_without_source_map, }; -use crate::css_cache::{cached_css, invalidate_css}; +use crate::css_cache::invalidate_css; +use crate::lazy_css::{LazyCss, settle}; use crate::with_style_sheet_untracked; /// Whether extraction generates a source map. @@ -47,14 +48,14 @@ pub struct Output { pub css_file: Option, /// Whether shared base CSS changed. pub updated_base_style: bool, - /// Changed CSS, absent when the stylesheet is unchanged. - pub css: Option, + /// Changed CSS, serialized on its first read; absent when the stylesheet is unchanged. + pub css: Option, /// Files read through the module resolver. pub dependencies: Vec, } impl Output { - /// Commit extracted styles to their existing bucket and materialize changed CSS. + /// Commit extracted styles to their existing bucket, deferring the changed CSS. pub fn new(output: ExtractOutput, filename: String, options: CssOptions) -> Self { // Use the bucket identity (single-importer collapse) so the sheet's CSS // naming + property bucket + emitted chunk match the canonical class names @@ -65,6 +66,7 @@ impl Output { let canonical_filename = canonical(&filename); let global = options.single_css || is_global(&filename); with_style_sheet_untracked(|sheet| { + settle(sheet); let planned = sheet.atom_plan.is_some(); // Global CSS belongs to the raw SOURCE file, never its collapsed bucket. let default_collected = sheet.rm_global_css(&filename, global); @@ -91,8 +93,7 @@ impl Output { if !collected && !default_collected { None } else { - Some(cached_css( - sheet, + Some(LazyCss::defer( if global { None } else { diff --git a/libs/binding/tests/css.rs b/libs/binding/tests/css.rs index fd9f2d9a2..54b7e88f5 100644 --- a/libs/binding/tests/css.rs +++ b/libs/binding/tests/css.rs @@ -42,6 +42,6 @@ fn numbered_css_selects_its_file_when_other_files_exist() -> Result<(), String> let selected = devup_ui_binding_core::get_css(Some(7), false); // Then: only the same file CSS returned by that transform is selected. - assert_eq!(Some(selected), red.css); + assert_eq!(Some(selected), red.css.map(|css| css.get())); Ok(()) } diff --git a/libs/binding/tests/css_cache.rs b/libs/binding/tests/css_cache.rs index 71dff1ae7..6d5a9f8c8 100644 --- a/libs/binding/tests/css_cache.rs +++ b/libs/binding/tests/css_cache.rs @@ -48,7 +48,7 @@ fn css_is_reused_until_an_extraction_changes_the_sheet() -> Result<(), String> { let changed = get_css(None, false); // Then: the unchanged sheet reads the same, the changed one holds both. - assert_eq!(red.css.as_deref(), Some(first.as_str())); + assert_eq!(red.css.map(|css| css.get()), Some(first.clone())); assert_eq!(again, first); assert!(!first.contains("blue")); assert!(changed.contains("red") && changed.contains("blue")); diff --git a/libs/binding/tests/lazy_css.rs b/libs/binding/tests/lazy_css.rs new file mode 100644 index 000000000..a7760b2ae --- /dev/null +++ b/libs/binding/tests/lazy_css.rs @@ -0,0 +1,116 @@ +use std::collections::{HashMap, HashSet}; + +use css::atom_hoist::AtomModeGuard; +use devup_ui_binding_core::{ + ExtractionMode, Output, SourceMapMode, code_extract, import_file_routes_internal, + reset_state_internal, set_atom_hoist, with_style_sheet, +}; +use extractor::ExtractOption; +use serial_test::serial; + +fn extract(filename: &str, code: &str, single_css: bool) -> Result { + code_extract( + (filename, code), + ExtractOption { + package: "@devup-ui/react".to_string(), + css_dir: "df".to_string(), + single_css, + ..ExtractOption::default() + }, + ExtractionMode { + source_map: SourceMapMode::Skip, + resolver: None, + resolver_check: None, + import_main_css_in_css: false, + }, + ) +} + +fn view(color: &str) -> String { + format!( + "import {{ Box }} from '@devup-ui/react'; export const view = ;" + ) +} + +/// The base as a fresh serialization writes it now, under the given atom mode. +fn fresh_base(single_css: bool) -> String { + let _mode = AtomModeGuard::new(single_css); + with_style_sheet(|sheet| sheet.create_css(None, false)) +} + +#[test] +#[serial] +fn css_read_at_once_is_the_sheet_the_transform_left() -> Result<(), String> { + // Given: a transform that added a style. + reset_state_internal(|| {}); + let output = extract("red.tsx", &view("red"), true)?; + let expected = fresh_base(true); + + // When: its CSS is read twice before anything else changes. + let css = output.css.ok_or("expected CSS")?; + + // Then: both reads are the serialization of that sheet. + assert_eq!(css.get(), expected); + assert_eq!(css.get(), expected); + Ok(()) +} + +#[test] +#[serial] +fn css_read_after_another_transform_is_the_sheet_its_transform_left() -> Result<(), String> { + // Given: a transform whose CSS is not read yet. + reset_state_internal(|| {}); + let red = extract("red.tsx", &view("red"), true)?; + let expected = fresh_base(true); + + // When: another transform changes the sheet before the read. + let blue = extract("blue.tsx", &view("blue"), true)?; + let red = red.css.ok_or("expected CSS")?.get(); + + // Then: the late read still holds only what the first transform saw. + assert_eq!(red, expected); + assert!(!red.contains("blue")); + assert!(blue.css.ok_or("expected CSS")?.get().contains("blue")); + Ok(()) +} + +#[test] +#[serial] +fn a_dropped_result_is_never_serialized() -> Result<(), String> { + // Given: a transform whose result is released unread. + reset_state_internal(|| {}); + drop(extract("red.tsx", &view("red"), true)?); + + // When: another transform changes the sheet. + let blue = extract("blue.tsx", &view("blue"), true)?; + + // Then: its own CSS holds both styles. + let css = blue.css.ok_or("expected CSS")?.get(); + assert!(css.contains("red") && css.contains("blue")); + Ok(()) +} + +#[test] +#[serial] +fn css_read_after_an_atom_setting_changes_keeps_the_transform_mode() -> Result<(), String> { + // Given: atom hoisting over two routes, and a per-file transform unread. + reset_state_internal(|| {}); + import_file_routes_internal(HashMap::from([( + "shared.tsx".to_string(), + HashSet::from([0, 1]), + )])); + set_atom_hoist(Some(2)); + let shared = extract("shared.tsx", &view("red"), false)?; + let expected = with_style_sheet(|sheet| sheet.create_css(Some("shared.tsx"), false)); + + // When: a single-CSS transform suppresses atom mode, then hoisting stops. + let single = extract("single.tsx", &view("blue"), true)?; + let single_expected = fresh_base(true); + set_atom_hoist(None); + + // Then: each late read is serialized in the mode of its own transform. + assert_eq!(shared.css.ok_or("expected CSS")?.get(), expected); + assert_eq!(single.css.ok_or("expected CSS")?.get(), single_expected); + reset_state_internal(|| {}); + Ok(()) +} diff --git a/libs/css/src/atom_hoist.rs b/libs/css/src/atom_hoist.rs index 940eb6e38..16195344f 100644 --- a/libs/css/src/atom_hoist.rs +++ b/libs/css/src/atom_hoist.rs @@ -22,7 +22,12 @@ pub struct AtomModeGuard { impl AtomModeGuard { pub fn new(single_css: bool) -> Self { - let previous = SUPPRESSED.with(|state| state.replace(state.get() || single_css)); + Self::exact(is_suppressed() || single_css) + } + + /// Suppress atom mode exactly when `suppressed`, whatever encloses the guard. + pub fn exact(suppressed: bool) -> Self { + let previous = SUPPRESSED.with(|state| state.replace(suppressed)); Self { previous, thread_bound: PhantomData, @@ -30,6 +35,11 @@ impl AtomModeGuard { } } +/// Whether a guard suppresses atom mode on this thread. +pub fn is_suppressed() -> bool { + SUPPRESSED.with(Cell::get) +} + impl Drop for AtomModeGuard { fn drop(&mut self) { SUPPRESSED.with(|state| state.set(self.previous)); @@ -158,6 +168,24 @@ mod tests { restore_atom_plan(None); } + #[test] + #[serial] + fn exact_suppression_ignores_the_enclosing_mode() { + // Given + set_atom_hoist(Some(2)); + let _outer = AtomModeGuard::new(true); + // When + { + let _inner = AtomModeGuard::exact(false); + // Then + assert!(!is_suppressed()); + assert!(is_atom_hoist()); + } + assert!(is_suppressed()); + assert!(!is_atom_hoist()); + set_atom_hoist(None); + } + #[test] #[serial] fn suppression_restores_after_error_and_unwind_without_freezing() { diff --git a/packages/next-plugin/src/__tests__/loader.test.ts b/packages/next-plugin/src/__tests__/loader.test.ts index 15b5a008a..037dde7cf 100644 --- a/packages/next-plugin/src/__tests__/loader.test.ts +++ b/packages/next-plugin/src/__tests__/loader.test.ts @@ -305,6 +305,42 @@ describe('devupUILoader', () => { }) }) + it('never reads the CSS the engine serializes on demand', async () => { + const asyncCallback = mock() + const readCss = mock(() => 'css') + const t = { + getOptions: () => ({ + package: 'package', + cssDir: 'cssFile', + watch: false, + singleCss: true, + defaultClassMap: {}, + defaultFileMap: {}, + defaultSheet: {}, + }), + async: mock().mockReturnValue(asyncCallback), + resourcePath: 'index.tsx', + addDependency: mock(), + } + codeExtractSpy.mockReturnValue({ + code: 'code', + get css() { + return readCss() + }, + free: mock(), + map: undefined, + cssFile: 'devup-ui.css', + updatedBaseStyle: true, + [Symbol.dispose]: mock(), + }) + devupUILoader.bind(asLoaderContext(t))(Buffer.from('code'), 'index.tsx') + + await waitFor(() => { + expect(asyncCallback).toHaveBeenCalledWith(null, 'code', null) + }) + expect(readCss).not.toHaveBeenCalled() + }) + it('extracts a file that reaches Devup UI only through a project module', async () => { const source = `import { Box } from './ui' export const a = ` diff --git a/packages/next-plugin/src/coordinator.ts b/packages/next-plugin/src/coordinator.ts index 3f6670ed7..f5e9145d1 100644 --- a/packages/next-plugin/src/coordinator.ts +++ b/packages/next-plugin/src/coordinator.ts @@ -93,14 +93,19 @@ interface ExtractOutputSnapshot extends Omit { css?: string } -/** Copy every WASM-backed getter once, then release its Rust allocation. */ +/** + * Copy every WASM-backed getter once, then release its Rust allocation. The + * engine serializes `css` only when it is read, so a caller that never uses it + * passes `withCss = false`. + */ export function takeExtractOutput( output: ReturnType, + withCss = true, ): ExtractOutputSnapshot { try { return { code: output.code, - css: output.css, + css: withCss ? output.css : undefined, cssFile: output.cssFile, map: output.map, updatedBaseStyle: output.updatedBaseStyle, diff --git a/packages/next-plugin/src/loader.ts b/packages/next-plugin/src/loader.ts index c9c5c2d35..521274058 100644 --- a/packages/next-plugin/src/loader.ts +++ b/packages/next-plugin/src/loader.ts @@ -232,6 +232,7 @@ const devupUILoader: RawLoaderDefinitionFunction = true, importAliases, ), + false, ) const { code, diff --git a/packages/next-plugin/src/plugin.ts b/packages/next-plugin/src/plugin.ts index 4ec180fb6..83f8634ae 100644 --- a/packages/next-plugin/src/plugin.ts +++ b/packages/next-plugin/src/plugin.ts @@ -484,6 +484,7 @@ export function DevupUI( true, importAliases as unknown as Record, ), + false, ) if (extractStartedAt !== undefined) { prewarmExtractMs += performance.now() - extractStartedAt diff --git a/packages/webpack-plugin/src/loader.ts b/packages/webpack-plugin/src/loader.ts index ee4db747f..3b7cbfa33 100644 --- a/packages/webpack-plugin/src/loader.ts +++ b/packages/webpack-plugin/src/loader.ts @@ -102,11 +102,14 @@ const devupUILoader: RawLoaderDefinitionFunction = 'code' | 'css' | 'map' | 'cssFile' | 'updatedBaseStyle' | 'dependencies' > try { + const cssFile = output.cssFile snapshot = { code: output.code, - css: output.css, + // The engine serializes the CSS only when it is read; watch mode + // never writes it + css: cssFile && !watch ? output.css : undefined, map: output.map, - cssFile: output.cssFile, + cssFile, updatedBaseStyle: output.updatedBaseStyle, dependencies: output.dependencies, }