fix(cli,themes): verify the icon import theme build emits

[AKnassa]

What this does

astryx theme build copies the icon-registry import from the theme source straight into the module it generates, and nothing checked that the copied specifier means anything from where the generated file lives. The build now verifies it before writing: the specifier is rewritten onto the compiled companion when one exists, kept with a warning when only the TypeScript source sits beside the output, and the build fails with a clear error when nothing can satisfy it.

One PR for two issues on purpose: both defects are the same emit step. #4620 is the symptom in the published themes (extensionless ./icons, so /built cannot load in Node or externalized SSR). #4621 is the symptom for self-built themes (the import points at a module the build never produces). A resolve check is the union of the two fixes, and either half alone would still have to decide the other's case.

What changed

• packages/cli/api/theme/build/build.mjs resolves the emitted specifier against the out dir before any file is written. Preference order is .mjs, then .js, then .cjs. .mjs wins deliberately: with a dual tsup build, .js is the CJS twin and hands consumers a second, distinct registry instance. A registry that exists only as TypeScript source beside the output is kept as written with a warning, since in-place builds are consumed through bundlers that resolve it. When nothing satisfies the import the build throws ERR_THEME_ICON_UNRESOLVED before writing anything, matching the existing stage-then-commit design. Bare package specifiers pass through untouched.
• Companion checks require the exact on-disk name. A case-insensitive filesystem (the macOS default) would otherwise let a mac build emit a specifier that fails on the Linux systems the artifact ships to.
• All seven theme packages now run tsup before astryx theme build, so the compiled registry exists when the specifier is verified, and check-fully-specified.mjs gates their dist the way it already gates core, lab, charts and richtext.
• The in-place warning also lands in the API receipt's warnings array, since the shared logger is silent for programmatic callers.
• 21 tests: the resolve ladder (parent-relative and nested specifiers, .cjs fallback, a directory named icons, fully-specified-but-missing, ladder order, exact case), plus e2e for the CLI error and exit code, the --json envelope code, watch-mode surviving the failure and recovering on the next change, and a spawned-Node proof that the emitted module actually loads.

How to check

The published-theme shape (was ERR_MODULE_NOT_FOUND before):

pnpm -F @astryxdesign/theme-neutral build
node --input-type=module -e "const m = await import('./packages/themes/neutral/dist/neutral.js'); console.log(m.neutralTheme.name, Object.keys(m.neutralIconRegistry).length)"
# neutral 26

The self-built shape (was a silently broken module before, now a clear failure):

astryx theme build src/myTheme.ts -o dist/theme.css
# Error: The generated theme module imports './icons', but no module satisfies it in dist/.
#        ... compile the icon registry into dist/ (tsup, esbuild, tsc) before running `theme build`,
#        or remove the theme's `icons` field.

Not included

The packaging defects the issues list as contributing factors (no type field in the theme packages, ./built mapping require to the ESM file) are left alone. With the specifier fixed the entry loads under both module systems on current Node, and flipping type would change how the existing CJS dist/source.js parses.

Fixes #4620
Fixes #4621

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
astryx	Ready	Preview	Aug 3, 2026 5:36pm

[github-actions]

PR Analysis Report

📚 Storybook Preview

View Storybook for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

🧪 Sandbox Preview

View Sandbox for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

No new or modified components detected.

Bundle Size Summary

No component packages changed.

Accessibility Audit

Status: No accessibility violations detected.

---

_{Generated by PR Enrichment workflow | Storybook | Sandbox | View full report}

[cixzhang]

Looks good from the implementation side — the resolver/checking approach makes sense and the focused theme smoke passes.

Before merge, could you please clean up two things:

• Rebase/resolve the current merge conflicts against main.
• Trim the changesets down to changelog-sized summaries. They currently read more like PR-body/root-cause notes; the changelog only needs the consumer-visible effect.

Thanks for the thorough test coverage here.