feat(plugin-builder): always emit both css payloads with cssMeta

[cmorman89]

TL;DR

• Plugins built for css isolation were silently losing a large share of their styling: the inlined CSS export was corrupted when the module was evaluated (backslash escapes in Tailwind selectors were swallowed), so browsers dropped every variant, fraction, opacity and arbitrary-value rule. The payload was also incomplete — only un-layered utility rules, missing the theme variables, property registrations, keyframes and @import rules the stylesheet depends on.
• The builder now embeds the CSS so it survives verbatim (JSON serialization) and keeps the whole compiled stylesheet except the preflight (the host document already provides one).
• The build no longer makes a css-mode decision: every build emits both payloads — the full stylesheet file (linked under shadow isolation) and the inlined export (injected under css isolation) — plus a cssMeta capability list (supports: ['shadow', 'css']) so hosts know the inline payload is safe. inlineCss is deprecated and ignored; the isolation mode is purely a manifest choice.

Details

Corrupted embedding. The extracted CSS was written into the plugin module as a raw template literal, and template-literal evaluation swallows the backslash escapes Tailwind selectors rely on — roughly 40% of rules arrived invalid and were discarded by the browser, and some CSS could make the module fail to load. The export is now emitted through JSON serialization and reaches the runtime byte-for-byte.

Lossy extraction. Only the last utilities layer was kept, unwrapped — so injected rules escaped their cascade layers (overriding host styles document-wide) and lost their supporting theme variables, property registrations, keyframes and @import rules. Extraction now keeps the compiled stylesheet in its original order and structure and drops only the base layer (preflight).

One build, both modes. Previously the build's inlineCss setting had to agree with the manifest's isolation mode, and a mismatch shipped silently broken styling. The build now always emits both payloads and advertises them (export const cssMeta = { supports: ['shadow', 'css'] }): the manifest picks the mode, the artifact states which modes it can honor, and there is nothing left to mismatch. inlineCss remains accepted as a deprecated no-op. The plugin template drops its vite-side isolation wiring — the scaffold prompt writes a single value, uiConfig.isolation in the tool server config — and the README documents that a registered manifest's ui block is authoritative over it.

cssMeta collision guard. A module that exports its own cssMeta keeps it: the builder detects the export from the bundle chunk's export metadata rather than by regexing source text, so detection is reliable across minification, aliasing and const-to-var lowering. It then skips appending its default and warns the author to declare supports themselves. The decision is recomputed per build, so watch mode does not go stale.

Verification

• packages/plugin-builder: 17 unit tests and the test typecheck pass; lint clean.
• The cssMeta collision guard is exercised against real bundle shapes — const-to-var lowering, aliased exports, cssMeta-looking text inside string literals, and repeated watch-mode builds — by driving the generateBundle/writeBundle hooks directly.
• End-to-end on a sample plugin: the runtime CSS string previously lost all of its selector escapes and every layer/property/keyframe block; with this change it is identical to the compiled stylesheet minus the preflight (external @import rules included) and re-parses with zero errors.
• The export and cssMeta are emitted identically with inlineCss: true, inlineCss: false, and the option absent.

Relationship to the 1.4 line

The host-side compatibility mode ships on the release/1.4 maintenance line as a deploy-only hotfix (it rescues already-deployed plugins by rebuilding from their stylesheet — no rebuild required); its manifest flag (AppUIConfig.css_rebuild) lands there: #1664. This PR carries only the build-tool fix that makes future builds correct at the source, publishing on the main line. Host-side consumption of the cssMeta capability export is deliberately deferred: builds emitting it render correctly under the host's default path, so the marker is forward-looking metadata until a host chooses to read it.

Test Plan

• Build a plugin and verify the runtime export preserves escapes, layers, property registrations, keyframes and @import rules while dropping the preflight
• Verify the export and cssMeta capability list are emitted regardless of the deprecated inlineCss option
• Verify a module that exports its own cssMeta is not clobbered (warned instead), across minified/lowered bundle shapes
• Load a plugin built with this builder in a host under css isolation and confirm variant/fraction/arbitrary utilities, custom theme tokens, custom animations and @import webfonts apply — pending a host running the compatibility-mode consumer

🤖 Generated with Claude Code

https://claude.ai/code/session_01JpAEfftYG74jVAFhZ87EcD