[cowboyd]

What does this PR do?

Deep trees make layout's recursive generator delegation increasingly expensive due to the way JavaScript handles generator delegation. This change traverses child iterators with an explicit stack, so that externally the API remains exactly the same, but internally it is much more performant.

The performance issue is demonstrated by the rendering benchmarks added in #45, so no separate issue is needed. Tests cover a 20,000-level tree, adjacent text grouping, stable IDs, subtree layout, and early-return closing behavior.

Benchmark comparison

Ran the existing rendering benchmark suite before and after: 120 cases per version, sequentially on the same machine with identical dependencies and settings. Values below are end-to-end mean rendering times in milliseconds.

Initial render, 2,000 components:

Shape	Recursive (ms)	Iterator stack (ms)	Speedup
Grass	3.06	2.79	1.1×
Maple	3.32	2.88	1.2×
Bush	4.32	2.87	1.5×
Evergreen	68.92	3.22	21×
Sequoia	185.15	2.98	62×
Bamboo	189.57	3.01	63×

Mutation workloads, 2,000-component bamboo trees:

Workload	Recursive (ms)	Iterator stack (ms)	Speedup
Single value update	205.97	1.91	108×
Batch 100 updates	202.68	2.01	101×
Add one component	206.72	2.07	100×
Add 100-component subtree	206.69	2.25	92×

Type of change

• Bug fix
• Feature
• Refactor (no behavior change)
• Documentation
• Performance improvement
• Tests
• Chore (dependencies, CI, tooling)

Checklist

• All tests pass (pnpm test)
• Files are formatted (pnpm format)
• I have added/updated tests for my changes (if applicable)
• I have added a changeset

AI-generated code disclosure

• This PR includes AI-generated code

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/bombshell-dev/ui/@clack/ui@46

commit: ba1baa4

[jbolda]

(There was previous discussion between us so just making that clear that I am not just glossing over the content.)

The perf is worth it and it is in a place we can continue to iterate for more perf or improved ergonomics. Seems worthwhile to move forward with it.

[codspeed]

Merging this PR will regress 1 benchmark

⚡ 72 improved benchmarks
❌ 1 regressed benchmark
✅ 167 untouched benchmarks

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
❌	Memory	grass (100)	33.3 KB	616.9 KB	-94.61%
⚡	Walltime	bamboo (2000)	762.3 ms	10.8 ms	×71
⚡	Walltime	bamboo (2000)	762.1 ms	10.9 ms	×70
⚡	Walltime	bamboo (2000)	761.8 ms	11.3 ms	×68
⚡	Walltime	bamboo (2000)	763.5 ms	11.4 ms	×67
⚡	Walltime	sequoia (2000)	714.9 ms	10.9 ms	×66
⚡	Walltime	sequoia (2000)	714.4 ms	10.9 ms	×66
⚡	Walltime	sequoia (2000)	715.5 ms	11.7 ms	×61
⚡	Walltime	sequoia (2000)	716.8 ms	12.3 ms	×58
⚡	Walltime	bamboo (2000)	761.4 ms	16.3 ms	×47
⚡	Walltime	sequoia (2000)	714.1 ms	16.4 ms	×43
⚡	Walltime	bamboo (1000)	192.5 ms	7.1 ms	×27
⚡	Walltime	bamboo (1000)	192 ms	7.3 ms	×26
⚡	Walltime	bamboo (1000)	191.7 ms	7.4 ms	×26
⚡	Walltime	sequoia (1000)	181.2 ms	7.1 ms	×25
⚡	Walltime	sequoia (1000)	181.1 ms	7.2 ms	×25
⚡	Walltime	sequoia (1000)	181.3 ms	7.4 ms	×24
⚡	Walltime	evergreen (2000)	258.9 ms	11 ms	×24
⚡	Walltime	evergreen (2000)	256.4 ms	11.1 ms	×23
⚡	Walltime	bamboo (1000)	193.7 ms	8.4 ms	×23
...	...	...	...	...	...

ℹ️ Only the first 20 benchmarks are displayed. Go to the app to view all benchmarks.

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing layout-iterator-stack (ba1baa4) with main (c8f14d4)}