feat(pack): support merge postcss config

[fireairforce]

Summary

Utoopack previously treated a discovered postcss.config.* file and inline styles.postcss as mutually exclusive. This prevented framework integrations from injecting plugins such as postcss-flexbugs-fixes without suppressing the user's own PostCSS configuration.

This change makes the two sources compose automatically in a single PostCSS pass: plugins from the discovered config run first, followed by plugins from styles.postcss. File-only and inline-only projects keep their existing behavior, and no new configuration option is introduced.

It also updates the config documentation and the with-postcss example to describe and demonstrate the merged behavior. The underlying Turbopack support was added in utooland/next.js#186.

Test Plan

• Added a snapshot test covering file and inline PostCSS configurations used together.
• Updated the PostCSS snapshots.

[github-actions]

📊 Performance Benchmark Report (with-antd)

Utoopack Performance Report

Report ID: utoopack_performance_report_20260824_081608
Generated: 2026-08-24 08:16:08
Trace File: trace_antd.json (0.4GB, 1.14M spans)
Test Project: examples/with-antd

---

Executive Summary

Metric	Value	Assessment
Total Wall Time	7,572.9 ms	Baseline
Total Thread Work (de-duped)	22,588.3 ms	Non-overlapping busy time
Effective Parallelism	3.0x	thread_work / wall_time
Working Threads	10	Threads with actual spans
Thread Utilization	29.8%	⚠️ Suboptimal
Total Spans	1,143,332	All B/E + X events
Meaningful Spans (>= 10us)	350,535	(30.7% of total)
Tracing Noise (< 10us)	792,797	(69.3% of total)

---

Build Phase Timeline

Shows when each build phase is active and how much CPU it consumes.
Self-Time is the time spent exclusively in that phase (excluding children).

Phase	Spans	Inclusive (ms)	Self-Time (ms)	Wall Range (ms)
Resolve	90,929	2,843.1	2,260.1	4,162.8
Parse	9,833	1,335.3	1,262.3	6,885.2
Analyze	223,791	14,373.1	10,162.8	6,777.1
Chunk	8,739	2,735.4	845.9	2,364.0
Codegen	11,055	1,441.7	1,345.8	2,030.7
Emit	33	50.8	25.4	10.7
Other	6,155	6,308.2	3,824.6	7,572.9

---

Workload Distribution by Diagnostic Tier

Category	Spans	Inclusive (ms)	% Work	Self-Time (ms)	% Self
P0: Scheduling & Resolution	317,538	17,617.1	78.0%	12,680.3	56.1%
P1: I/O & Heavy Tasks	2,906	135.5	0.6%	110.2	0.5%
P2: Architecture (Locks/Memory)	0	0.0	0.0%	0.0	0.0%
P3: Asset Pipeline	28,152	5,525.8	24.5%	3,467.4	15.4%
P4: Bridge/Interop	0	0.0	0.0%	0.0	0.0%
Other	1,939	5,809.2	25.7%	3,469.1	15.4%

---

Top 20 Tasks by Self-Time

Self-time is the exclusive duration: time spent in the task itself, not in sub-tasks.
This is the most accurate indicator of where CPU cycles are actually spent.

Self (ms)	Inclusive (ms)	Count	Avg Self (us)	P95 Self (ms)	Max Self (ms)	% Work	Task Name	Top Caller
5,509.1	7,429.6	141,235	39.0	0.1	36.4	24.4%	module	write all entrypoints to disk (1%)
2,377.2	2,480.4	14	169800.5	460.2	547.3	10.5%	save snapshot	persist (7%)
2,264.4	2,306.8	25,359	89.3	0.2	269.4	10.0%	analyze ecmascript module	module (60%)
1,459.9	3,680.3	48,701	30.0	0.0	6.9	6.5%	process module	module (19%)
1,418.7	1,519.2	50,932	27.9	0.0	8.1	6.3%	internal resolving	resolving (29%)
1,189.7	1,262.7	7,663	155.3	0.5	96.0	5.3%	parse ecmascript	process module (26%)
829.2	1,311.8	39,294	21.1	0.0	8.0	3.7%	resolving	module (29%)
780.2	780.2	5,782	134.9	0.6	100.8	3.5%	compute async module info	compute merged modules (0%)
757.8	757.8	8,620	87.9	0.4	4.6	3.4%	precompute code generation	generate merged code (47%)
650.8	2,539.1	6,923	94.0	0.1	42.3	2.9%	chunking	compute async chunks (0%)
608.0	1,853.7	1,672	363.6	0.9	268.7	2.7%	generate merged code	chunking (69%)
393.1	393.1	329	1194.9	1.5	243.1	1.7%	generate source map	code generation (83%)
352.4	687.5	172	2049.0	4.8	202.2	1.6%	emit code	generate merged code (34%)
325.4	462.2	3,795	85.7	0.0	145.5	1.4%	write all entrypoints to disk	None (0%)
195.0	290.8	2,106	92.6	0.2	40.5	0.9%	code generation	chunking (12%)
192.2	193.3	1,766	108.8	0.1	46.4	0.9%	compute async chunks	write all entrypoints to disk (0%)
109.5	109.5	6	18243.2	71.7	92.5	0.5%	blocking	save snapshot (67%)
86.0	86.0	695	123.7	0.0	26.1	0.4%	compute binding usage info	write all entrypoints to disk (1%)
72.6	72.6	2,168	33.5	0.0	5.8	0.3%	read file	parse ecmascript (91%)
51.8	51.8	1,927	26.9	0.0	11.4	0.2%	collect mergeable modules	compute merged modules (3%)

---

Critical Path Analysis

The longest sequential dependency chains that determine wall-clock time.
Focus on reducing the depth of these chains to improve parallelism.

Rank	Self-Time (ms)	Depth	Path
1	639.8	3	persist → save snapshot → blocking
2	471.0	3	chunking → generate merged code → emit code
3	290.2	4	chunking → generate merged code → emit code → generate source map
4	269.5	2	process module → analyze ecmascript module
5	96.0	2	process module → parse ecmascript

---

Batching Candidates

High-volume tasks dominated by a single parent. If the parent can batch them,
it drastically reduces scheduler overhead.

Task Name	Count	Top Caller (Attribution)	Avg Self	P95 Self	Total Self
No obvious batching candidates found	-	-	-	-	-

---

Duration Distribution

Range	Count	Percentage
<10us	792,797	69.3%
10us-100us	330,826	28.9%
100us-1ms	15,688	1.4%
1ms-10ms	3,909	0.3%
10ms-100ms	92	0.0%
>100ms	20	0.0%

---

Action Items

1. [P0] Focus on tasks with the highest Self-Time — these are where CPU cycles are actually spent.
2. [P0] Use Batching Candidates to identify callers that should use try_join or reduce #[turbo_tasks::function] granularity.
3. [P1] Check Build Phase Timeline for phases with disproportionate wall range vs. self-time (= serialization).
4. [P1] Inspect P95 Self (ms) for heavy monolith tasks. Focus on long-tail outliers, not averages.
5. [P1] Review Critical Paths — reducing the longest chain depth directly improves wall-clock time.
6. [P2] If Thread Utilization < 60%, investigate scheduling gaps (lock contention or deep dependency chains).

Report generated by Utoopack Performance Analysis Agent