feat: let modules ship CSS that reaches the host's Tailwind build

[antosubash]

Problem

A wheel-installed module could only contribute Tailwind @source class-scanning — there was no mechanism to ship real CSS. Apps worked around it by hand-editing the host stylesheet; smpy_gis carries:

@import "../../modules/gis/gis/static/tokens.css";

which breaks entirely once the module is pip-installed, is never regenerated by gen-pages, and has no defined ordering against Tailwind's layers.

What this does

A module may now ship two optional stylesheets beside pages/, auto-detected exactly like pages are — no hook, no config:

File	Imported as	For
theme.css	unlayered	@theme tokens, @custom-variant, @font-face
styles.css	layer(components)	component rules, keyframes, vendor CSS

The split is load-bearing rather than stylistic: a @theme block inside a cascade layer is inert and registers no tokens, while unlayered CSS outranks every Tailwind utility — a module shipping a bare .card { padding: 0 } would silently beat p-4. One file cannot satisfy both, so each file has exactly one job and the footgun becomes structurally impossible. SM022/SM023 catch authors who put a rule in the wrong one.

gen-pages emits the imports through a per-module Vite alias (#module/<pkg>/styles.css), so generated CSS never contains ../../../.venv/lib/python3.12/site-packages/<pkg>/styles.css. Emission follows module discovery order (topological by depends_on), so a dependent module can override its dependency's styles.

Implementation notes

• New simple_module_hosting/assets.py — manifest.py was already at the repo's 300-line cap.
• New modules.assets.json is purely additive; modules.manifest.json keeps its exact {name: pages_dir} shape because vite.config.ts is scaffolded into every downstream app (smpy_gis, smpy_saas, laco_wiki_python, smpy_pagebuilder) and changing the value shape would break them all at once. The new file also covers CSS-only modules, which never appear in the pages manifest.
• The in-repo @source glob widens from pages/** to ** so classes used in module CSS are scanned.
• All Vite/stylesheet changes are mirrored into the scaffold templates.

Verification

The design rested on two unverified resolver claims, so both were settled with a throwaway Tailwind 4.2.4 spike before any production code: resolve.alias does govern CSS @import (the @tailwindcss/vite CSS resolver is built from {...config.resolve, …} in both code paths), and absolute @source paths do scan correctly.

test_module_css_build.py then drives a real npm run build and asserts .dashboard-stat-grid — declared only in modules/dashboard/dashboard/styles.css and referenced by no TSX anywhere — reaches the bundle. It can only get there via the alias. Confirmed from a fully cleaned dist/, and the rule lands inside @layer components with block order properties → theme → base → components → utilities.

make lint and make test are green (1538 passed, 2 skipped). make doctor reports no new diagnostics; its pre-existing SM020/SM003 findings are untouched by this branch.

Docs

docs/module-authoring.md § Styling, the module-layout tree and diagnostic list in CLAUDE.md, and the scaffold README template.

https://claude.ai/code/session_01RotaWUR7nhG5JwV59B1Znh

[cloudflare-workers-and-pages]

Deploying simple-module-python with    Cloudflare Pages

Latest commit:	df75da8
Status:	✅  Deploy successful!
Preview URL:	https://8a88873d.simple-module-python.pages.dev
Branch Preview URL:	https://worktree-module-css-packagin.simple-module-python.pages.dev

View logs

[antosubash]

Code review

Found 3 issues. All are fixed in 4cd528d.

1. The SM022/SM023 scanner treated braces inside quoted strings as structural, so content: "{" desynced the depth counter for the rest of the file. Every later top-level construct then read as nested and was silently dropped — swallowing exactly the misplaced @theme that SM022 exists to catch. Verified: .icon { content: "{"; } followed by a top-level @theme returned zero diagnostics. The mirror case, a "}" in a string, closed a block early and produced a phantom SM023 on a stray quote character.

simple_module_python/framework/core/simple_module_core/diagnostics/_css.py

Lines 60 to 63 in de45e03

	buf_line = 1
	for ch in text:
	if ch == "{":
	if depth == 0:

2. The scaffold template used existsSync + readFileSync for modules.assets.json, while the host copy of the same file used try/catch. Commit e955afd deliberately replaced that pattern (TOCTOU + double syscall) in host/client_app/vite.config.ts; new code should not reintroduce it. Both copies now match.

simple_module_python/framework/cli/simple_module_cli/templates/host/client_app/vite.config.ts

Lines 86 to 88 in de45e03

	const assetsPath = path.resolve(__dirname, 'modules.assets.json');
	if (fs.existsSync(assetsPath)) {
	const assets = JSON.parse(fs.readFileSync(assetsPath, 'utf-8')) as Record<string, ModuleAsset>;

3. The alias-sort comment stated a rationale that isn't true. Vite matches a string find on exact equality or a /-bounded prefix (importee.startsWith(pattern + "/")), so #module/gis could never have shadowed #module/gis_extra in any order. The sort is kept for deterministic ordering and the comment now says that instead.

simple_module_python/host/client_app/vite.config.ts

Lines 80 to 82 in de45e03

	}
	// Longest `find` first, so `#module/gis` cannot shadow `#module/gis_extra`.
	moduleAliases.sort((a, b) => b.find.length - a.find.length);

Checked and found clean: CLAUDE.md compliance (300-line cap, dataclass over Pydantic, no framework/* → modules/* import, SM022/SM023 continuing sequentially from SM021), asset ordering and dedup in assets.py, and the @source widening — no earlier commit had deliberately chosen the narrower pages/** form.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[antosubash]

Code review — convergence rounds 2-4

Ran the branch back through review until a full pass came back clean. Three further rounds, each finding a real defect in _top_level_preludes, all fixed. Round 4 found nothing.

Round 2 — unmatched quote silently disabled the lint. The string handling in 4cd528d fixed brace-in-a-string but opened a worse hole: an unmatched quote left the scanner inside a string forever, so every later brace stopped counting and all remaining findings vanished. Triggered by an ordinary typo, and by the lone apostrophe in an unquoted url(data:image/svg+xml,...it's...) token. The pre-fix scanner handled both correctly by ignoring quotes entirely, so this was a regression. Fixed in 04df96a, then properly in a65f0cb — bounding strings at newlines was not enough, because a closing brace on the stray quote's own line was still eaten. A quote now opens a string only if its partner appears before end-of-line, which is the rule CSS itself applies.

Round 3 — the same-line lookahead was O(n²). A run of \' defeats each forward scan, so the scan walked the whole line, advanced one character, and repeated. Measured 9KB 0.30s, 31KB 3.0s, 58KB 10.5s. doctor runs this over every installed module including third-party ones, so a minified or vendored stylesheet could stall CI. Fixed in df75da8 by consuming CSS escape pairs outside strings — which is also more correct, since Tailwind selectors rely on escapes (.mt-\[773px\]). Now 390KB in 0.025s.

Also fixed: the widened @source glob matched any directory under modules/<name>/, so a module's sibling tests/ was scanned too. Confirmed on a real build that a class used only under tests/ reached the production bundle. Excluded via @source not (verified supported in the installed Tailwind), with a build check proving the package-dir class is still picked up, the tests-dir one is not, and module-shipped CSS still reaches the bundle.

Known limitation, documented in both styles.css files: a module's Python package must not itself be named tests, or that exclusion would skip the package too. No glob can distinguish a package directory from a sibling, and tests is not a viable package name regardless — it collides with pytest collection.

Verification on the final commit: 1545 Python tests pass, make ci-python-lint clean, 300-line cap satisfied (the scanner's tokenising tests were split into test_css_scanner.py by responsibility rather than squeezed under), make doctor reports no SM022/SM023 findings, and all 13 CI checks pass including E2E smoke and Perf guards.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}