Document layout composition pitfalls

[bcomnes]

Closes #232

The nested layouts section shows the correct pattern but does not warn about the ways it can silently go wrong. Four pitfalls trip up most users composing layouts for the first time:

1. Forgetting to forward scripts and styles to the base layout drops all CSS and JS bundles from the page with no error message.
2. Vars can be modified or extended before forwarding, which is useful for setting layout-specific flags that the root layout reads.
3. When the base layout uses page, pages, or workers, those params must also be forwarded explicitly.
4. Layout-specific CSS and JS bundles do not cascade automatically through nested layouts; parent layout assets must be imported explicitly.

This adds a "Layout composition pitfalls" subsection with concrete right/wrong examples for the forwarding cases, plus a pointer to the existing nested layout asset-import documentation for the required @import / import pattern.

[coveralls]

Coverage Report for CI Build 28264718223

Coverage decreased (-1.2%) to 91.469%

Details

• Coverage decreased (-1.2%) from the base build.
• Patch coverage: No coverable lines changed in this PR.
• 183 coverage regressions across 7 files.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

183 previously-covered lines in 7 files lost coverage.

File	Lines Losing Coverage	Coverage
index.js	110	82.0%
lib/identify-pages.js	51	87.03%
lib/build-pages/index.js	9	95.63%
lib/build-pages/page-builders/template-builder.js	5	93.63%
lib/build-pages/resolve-vars.js	4	87.22%
lib/build-copy/index.js	2	95.38%
lib/build-static/index.js	2	92.98%

---

Coverage Stats

Relevant Lines:	4070
Covered Lines:	3804
Line Coverage:	93.46%
Relevant Branches:	642
Covered Branches:	506
Branch Coverage:	78.82%
Branches in Coverage %:	Yes
Coverage Strength:	73.63 hits per line

---

💛 - Coveralls

[Copilot]

Pull request overview

Adds a new “Layout composition pitfalls” subsection to the README to warn about common silent failure modes when composing nested layouts.

Changes:

• Documented the need to explicitly forward scripts and styles to avoid silently dropping CSS/JS bundles.
• Added an example showing how to extend/modify vars before forwarding to a base layout.
• Added a checklist-style example calling out forwarding page, pages, and workers when the base layout relies on them.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[bcomnes]

I wonder if when rendering pages we should do a simple check for styles and clients to make sure those strings made it in the output and if not emit a warning.

[bcomnes]

This is mostly good I just want to take one more full pass in an ide before landing.