@pyreon/vite-plugin 0.18.0 → 0.20.0

package/src/index.ts

@@ -34,9 +34,32 @@
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
 import { dirname, join as pathJoin } from 'node:path'
-import { generateContext, transformDeferInline, transformJSX } from '@pyreon/compiler'
+import {
+  type CollapsibleSite,
+  generateContext,
+  scanCollapsibleSites,
+  transformDeferInline,
+  transformJSX,
+} from '@pyreon/compiler'
+import type { CollapseResolver } from './rocketstyle-collapse'
 import type { Plugin, ViteDevServer } from 'vite'
 
+// Lazy — the resolver module (and its `vite` SSR machinery) must NOT be
+// on the static import path of this cheap entry. It loads ONLY when
+// `pyreon({ collapse })` is enabled AND a collapsible site is scanned;
+// collapse-off consumers never pull it (bundle-budget + cold-load).
+let _createCollapseResolver:
+  | ((root: string) => Promise<CollapseResolver>)
+  | null = null
+async function loadCreateCollapseResolver(): Promise<
+  (root: string) => Promise<CollapseResolver>
+> {
+  if (!_createCollapseResolver) {
+    _createCollapseResolver = (await import('./rocketstyle-collapse')).createCollapseResolver
+  }
+  return _createCollapseResolver
+}
+
 // Virtual module ID for the HMR runtime
 const HMR_RUNTIME_ID = '\0pyreon/hmr-runtime'
 const HMR_RUNTIME_IMPORT = 'virtual:pyreon/hmr-runtime'
@@ -47,7 +70,7 @@ const HMR_RUNTIME_IMPORT = 'virtual:pyreon/hmr-runtime'
 const ISLANDS_REGISTRY_ID = '\0pyreon/islands-registry'
 const ISLANDS_REGISTRY_IMPORT = 'virtual:pyreon/islands-registry'
 
-export type CompatFramework = 'react' | 'preact' | 'vue' | 'solid'
+export type CompatFramework = 'react' | 'preact' | 'vue' | 'solid' | 'svelte'
 
 export interface PyreonPluginOptions {
   /**
@@ -60,6 +83,7 @@ export interface PyreonPluginOptions {
    * pyreon({ compat: "react" })   // react + react-dom → @pyreon/react-compat
    * pyreon({ compat: "vue" })     // vue → @pyreon/vue-compat
    * pyreon({ compat: "solid" })   // solid-js → @pyreon/solid-compat
+   * pyreon({ compat: "svelte" })  // svelte + svelte/store → @pyreon/svelte-compat
    * pyreon({ compat: "preact" })  // preact + hooks + signals → @pyreon/preact-compat
    */
   compat?: CompatFramework
@@ -105,6 +129,45 @@ export interface PyreonPluginOptions {
    * hydrateIslandsAuto()
    */
   islands?: boolean
+
+  /**
+   * P0 — opt-in compile-time rocketstyle wrapper collapse. `true` uses
+   * the default provider/theme/mode wiring (PyreonUI + theme +
+   * useMode from @pyreon/ui-core / @pyreon/ui-theme). Pass an object to
+   * override. OFF by default (zero behaviour change). When on, the
+   * plugin SSR-resolves every literal-prop call site of a candidate
+   * component (real component, light + dark) and the compiler collapses
+   * the 5-layer wrapper mount into a single `_rsCollapse` cloneNode.
+   * Only the CLIENT graph is collapsed — the SSR graph keeps the normal
+   * mount (and the resolver itself uses SSR render).
+   *
+   * @example pyreon({ collapse: true })
+   * @example pyreon({ collapse: { components: ['Button', 'Badge'] } })
+   */
+  collapse?: boolean | PyreonCollapseOptions
+}
+
+export interface PyreonCollapseOptions {
+  /**
+   * Import sources whose components may collapse. Default:
+   * `['@pyreon/ui-components']`. The compiler's AST scan only considers
+   * a call site whose component was imported from one of these sources;
+   * the conservative bail catalogue + the SSR resolver are the real
+   * gate beyond that.
+   */
+  sources?: string[]
+  /**
+   * Optional local-name allowlist applied AFTER the source scan
+   * (e.g. `['Button']`). Omit to collapse every collapsible component
+   * from the configured sources.
+   */
+  components?: string[]
+  /** Override the theme/mode provider. Default PyreonUI@@pyreon/ui-core. */
+  provider?: { name: string; source: string }
+  /** Override the theme object. Default theme@@pyreon/ui-theme. */
+  theme?: { name: string; source: string }
+  /** Override the live mode accessor. Default useMode@@pyreon/ui-core. */
+  mode?: { name: string; source: string }
 }
 
 // ── Compat alias maps ─────────────────────────────────────────────────────────
@@ -134,6 +197,13 @@ const COMPAT_ALIASES: Record<CompatFramework, Record<string, string>> = {
     'solid-js/jsx-runtime': '@pyreon/solid-compat/jsx-runtime',
     'solid-js/jsx-dev-runtime': '@pyreon/solid-compat/jsx-runtime',
   },
+  svelte: {
+    svelte: '@pyreon/svelte-compat',
+    'svelte/store': '@pyreon/svelte-compat/store',
+    'svelte/internal': '@pyreon/svelte-compat',
+    'svelte/jsx-runtime': '@pyreon/svelte-compat/jsx-runtime',
+    'svelte/jsx-dev-runtime': '@pyreon/svelte-compat/jsx-runtime',
+  },
 }
 
 /**
@@ -218,6 +288,7 @@ function getCompatTarget(compat: CompatFramework | undefined, id: string): strin
     if (compat === 'preact') return '@pyreon/preact-compat/jsx-runtime'
     if (compat === 'vue') return '@pyreon/vue-compat/jsx-runtime'
     if (compat === 'solid') return '@pyreon/solid-compat/jsx-runtime'
+    if (compat === 'svelte') return '@pyreon/svelte-compat/jsx-runtime'
   }
   return undefined
 }
@@ -260,7 +331,60 @@ export default function pyreonPlugin(options?: PyreonPluginOptions): Plugin {
   // module is harmless if the user has no `island()` calls. Opt out only if
   // you have a specific reason.
   const islandsEnabled = options?.islands !== false
+
+  // ── P0 rocketstyle-collapse config (opt-in) ───────────────────────────────
+  const collapseOpt = options?.collapse
+  const collapseEnabled = collapseOpt === true || (collapseOpt != null && collapseOpt !== false)
+  const collapseUserCfg: PyreonCollapseOptions =
+    collapseOpt && collapseOpt !== true ? collapseOpt : {}
+  const collapseProvider = collapseUserCfg.provider ?? {
+    name: 'PyreonUI',
+    source: '@pyreon/ui-core',
+  }
+  const collapseTheme = collapseUserCfg.theme ?? { name: 'theme', source: '@pyreon/ui-theme' }
+  const collapseMode = collapseUserCfg.mode ?? { name: 'useMode', source: '@pyreon/ui-core' }
+  const collapseSources = new Set(collapseUserCfg.sources ?? ['@pyreon/ui-components'])
+  const collapseComponentFilter = collapseUserCfg.components
+    ? (n: string) => collapseUserCfg.components!.includes(n)
+    : null
+  // Lazily created on first client-graph transform; one Vite SSR server
+  // reused for every resolve in the build. Disposed in closeBundle.
+  let collapseResolver: import('./rocketstyle-collapse').CollapseResolver | null = null
+  let collapseResolverInit: Promise<
+    import('./rocketstyle-collapse').CollapseResolver | null
+  > | null = null
+
+  /**
+   * Lazily spin ONE programmatic Vite SSR server (bound to the project's
+   * own vite config) the first time a client-graph module actually has a
+   * collapsible call site. Memoized via `collapseResolverInit` so
+   * concurrent transforms share the single server. Returns null if the
+   * server fails to start (graceful — every call site then keeps its
+   * normal rocketstyle mount).
+   */
+  function ensureCollapseResolver(): Promise<
+    import('./rocketstyle-collapse').CollapseResolver | null
+  > {
+    if (collapseResolver) return Promise.resolve(collapseResolver)
+    if (collapseResolverInit) return collapseResolverInit
+    collapseResolverInit = loadCreateCollapseResolver()
+      .then((create) => create(projectRoot))
+      .then((r) => {
+        collapseResolver = r
+        return r
+      })
+      .catch(() => null)
+    return collapseResolverInit
+  }
+
   let isBuild = false
+  // Collapse is build-only by design: the resolver computes each site's
+  // class from a SEPARATE nested Vite SSR server's module graph and caches
+  // it. In dev that frozen class would NOT react to the user's theme-source
+  // HMR edits — strictly worse than the normal mount, which IS reactive.
+  // So dev keeps the normal mount; we surface that ONCE so an opted-in
+  // consumer running `vite dev` isn't left wondering why nothing collapsed.
+  let warnedDevCollapse = false
   let projectRoot = ''
 
   // ── Cross-module signal export registry ─────────────────────────────────
@@ -364,6 +488,16 @@ export default function pyreonPlugin(options?: PyreonPluginOptions): Plugin {
       }
     },
 
+    // Tear down the one programmatic Vite SSR server the collapse
+    // resolver holds (created lazily on first client-graph transform).
+    async closeBundle() {
+      if (collapseResolver) {
+        await collapseResolver.dispose()
+        collapseResolver = null
+        collapseResolverInit = null
+      }
+    },
+
     // ── Virtual module + compat alias resolution ─────────────────────────────
     async resolveId(id, importer) {
       if (id === HMR_RUNTIME_IMPORT) return HMR_RUNTIME_ID
@@ -409,7 +543,13 @@ export default function pyreonPlugin(options?: PyreonPluginOptions): Plugin {
       // In compat mode, skip Pyreon's reactive JSX transform but apply
       // attribute renames (className → class, htmlFor → for) so source code
       // that uses React-style attribute names works correctly.
-      if (compat === 'react' || compat === 'preact' || compat === 'vue' || compat === 'solid') {
+      if (
+        compat === 'react' ||
+        compat === 'preact' ||
+        compat === 'vue' ||
+        compat === 'solid' ||
+        compat === 'svelte'
+      ) {
         if (compat === 'react' || compat === 'preact') {
           const transformed = transformCompatAttributes(code)
           if (transformed !== code) return { code: transformed, map: null }
@@ -453,7 +593,77 @@ export default function pyreonPlugin(options?: PyreonPluginOptions): Plugin {
       // (both build --ssr and dev `ssrLoadModule`). The compiler emits plain
       // `h()` calls in that mode so `runtime-server` can render to a string.
       const isSsr = transformOptions?.ssr === true
-      const result = transformJSX(sourceForJsx, id, { ssr: isSsr, knownSignals })
+
+      // ── P0 rocketstyle-collapse (opt-in, CLIENT graph only) ────────────
+      // Never collapse the SSR graph: renderToString needs the real
+      // VNode tree, AND the resolver itself SSR-renders the component —
+      // collapsing the SSR graph would be circular. Resolve every
+      // scanned literal-prop site once (real component, light + dark)
+      // and hand the compiler a key→emission map; the compiler's AST
+      // bail catalogue is the real gate, an unresolved key just falls
+      // back to the normal mount.
+      let collapseRocketstyle:
+        | NonNullable<Parameters<typeof transformJSX>[2]>['collapseRocketstyle']
+        | undefined
+      if (collapseEnabled && !isBuild && !isSsr && !warnedDevCollapse) {
+        warnedDevCollapse = true
+        this.info(
+          '[Pyreon] collapse is build-only — `vite dev` keeps the normal rocketstyle mount so theme-source edits stay HMR-reactive. Production `vite build` collapses the literal-prop sites.',
+        )
+      }
+      if (collapseEnabled && isBuild && !isSsr) {
+        const scanned: CollapsibleSite[] = scanCollapsibleSites(
+          sourceForJsx,
+          id,
+          collapseSources,
+        ).filter((s) => !collapseComponentFilter || collapseComponentFilter(s.componentName))
+        if (scanned.length > 0) {
+          const resolver = await ensureCollapseResolver()
+          if (resolver) {
+            const sites = new Map<
+              string,
+              {
+                templateHtml: string
+                lightClass: string
+                darkClass: string
+                rules: string[]
+                ruleKey: string
+              }
+            >()
+            const candidates = new Set<string>()
+            for (const s of scanned) {
+              const resolved = await resolver.resolve({
+                component: { name: s.importedName, source: s.source },
+                props: s.props,
+                childrenText: s.childrenText,
+                config: {
+                  provider: collapseProvider,
+                  theme: collapseTheme,
+                  mode: collapseMode,
+                },
+              })
+              if (!resolved) continue
+              candidates.add(s.componentName)
+              sites.set(s.key, {
+                templateHtml: resolved.templateHtml,
+                lightClass: resolved.lightClass,
+                darkClass: resolved.darkClass,
+                rules: resolved.rules,
+                ruleKey: resolved.key,
+              })
+            }
+            if (sites.size > 0) {
+              collapseRocketstyle = { candidates, sites, mode: collapseMode }
+            }
+          }
+        }
+      }
+
+      const result = transformJSX(sourceForJsx, id, {
+        ssr: isSsr,
+        knownSignals,
+        ...(collapseRocketstyle ? { collapseRocketstyle } : {}),
+      })
       // Surface compiler warnings in the terminal
       for (const w of result.warnings) {
         this.warn(`${w.message} (${id}:${w.line}:${w.column})`)
@@ -468,7 +678,15 @@ export default function pyreonPlugin(options?: PyreonPluginOptions): Plugin {
         output = injectSignalNames(output)
       }
 
-      return { code: output, map: null }
+      // R12: surface the compiler's V3 source map so stack traces /
+      // breakpoints in Pyreon components resolve to the right source line
+      // (the JS backend now emits one; substitutions shift line counts, so
+      // `map: null` previously mislocated every frame app-wide). Exact in
+      // build; in dev the small extra HMR / signal-name injections aren't
+      // re-mapped (still vastly better than no map). The native backend
+      // emits no map yet (its own scoped follow-up) → `null`, unchanged
+      // behaviour for that path.
+      return { code: output, map: result.map ?? null }
     },
 
     // ── SSR dev middleware ───────────────────────────────────────────────────
@@ -745,7 +963,40 @@ function injectHmr(code: string, moduleId: string): string {
     lines.push(`  import.meta.hot.dispose(() => __hmr_dispose(${escapedId}));`)
   }
 
-  lines.push(`  import.meta.hot.accept();`)
+  // Self-accept the module, then drive Pyreon's HMR coordinator.
+  //
+  // The OLD code emitted a bare `import.meta.hot.accept()` (no callback):
+  // Vite re-evaluated the module but NOTHING re-rendered the mounted tree,
+  // AND the self-accept suppressed Vite's full-reload fallback — so a
+  // component/JSX edit produced a silently-stale UI until a MANUAL refresh.
+  //
+  // Now: the accept callback hands the FRESH module namespace Vite already
+  // re-evaluated straight to `globalThis.__pyreon_hmr_swap__` (registered
+  // by `@pyreon/router` in a dev browser — zero import coupling, same
+  // pattern as the perf-harness counter sink), keyed by THIS module's id.
+  // The coordinator finds every active matched route record whose lazy
+  // `_hmrId` matches and swaps in the new component, re-rendering ONLY
+  // that subtree IN PLACE (no page reload → `__pyreon_hmr_registry__`
+  // survives → `__hmr_signal` restores module-scope signal values).
+  //
+  // Using the namespace Vite passes (not a re-run of the lazy thunk)
+  // sidesteps the stale-`?t=` trap: the dynamic-import thunk lives in the
+  // virtual routes module, which is NOT invalidated when this leaf route
+  // self-accepts — re-importing it would return the OLD module.
+  //
+  // `__pyreon_hmr_swap__` returns falsy when the edit was outside the
+  // active route tree (nested non-route component, unrelated route,
+  // signal-only module) OR no coordinator is registered (plain
+  // `@pyreon/runtime-dom` app, or module loaded before any router
+  // mounted). Then `import.meta.hot.invalidate()` → Vite propagates → an
+  // AUTOMATIC full reload. Either way the user never refreshes by hand.
+  lines.push(`  import.meta.hot.accept((__m) => {`)
+  lines.push(`    const __s = globalThis.__pyreon_hmr_swap__;`)
+  lines.push(
+    `    if (typeof __s === "function" && __m && __s(${escapedId}, __m)) return;`,
+  )
+  lines.push(`    import.meta.hot.invalidate();`)
+  lines.push(`  });`)
   lines.push(`}`)
 
   output = `${output}\n\n${lines.join('\n')}\n`

package/src/rocketstyle-collapse.ts

@@ -0,0 +1,199 @@
+/**
+ * P0 — build-time rocketstyle-collapse resolver.
+ *
+ * For a collapsible call site (`<Button state="primary" size="md">Save</Button>`
+ * — every dimension prop a string literal, children static text) this
+ * resolves the FULL rocketstyle/styler pipeline ONCE by SSR-rendering the
+ * REAL component, light AND dark, and returns: the resolved styler class
+ * per mode, the styler rule text, and a class-stripped `_tpl` template.
+ *
+ * The render runs through a programmatic Vite SSR server bound to the
+ * CONSUMER's own `vite.config` — so module resolution is identical to
+ * the app's real build (workspace `bun` condition, app aliases,
+ * app-local relative imports, whatever). Parity with the runtime-mounted
+ * class is then guaranteed BY CONSTRUCTION: it is literally the same
+ * `renderToString` + `@pyreon/styler` code path the client uses, and
+ * styler's FNV-1a class hashing is identical in SSR and DOM (styler's
+ * hydration contract). No reimplementation, no closure re-execution, no
+ * drift (RFC decision 2).
+ *
+ * Every failure returns `null` (graceful bail → the call site keeps its
+ * normal rocketstyle mount). Correct-but-slow is acceptable; wrong
+ * output is not.
+ */
+import type { InlineConfig, ViteDevServer } from 'vite'
+
+// Inline FNV-1a (same algorithm as @pyreon/styler/hash) — avoids pulling
+// the styler module graph into the vite-plugin's cheap entry path.
+function fnv1a(str: string): string {
+  let h = 2166136261
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i)
+    h = Math.imul(h, 16777619)
+  }
+  return (h >>> 0).toString(36)
+}
+
+export interface CollapseImportSpec {
+  /** Imported binding name, e.g. `PyreonUI` / `theme` / `useMode`. */
+  name: string
+  /** Module specifier, e.g. `@pyreon/ui-core` / `@pyreon/ui-theme`. */
+  source: string
+}
+
+export interface CollapseConfig {
+  /** Theme/mode provider component. Default: PyreonUI from @pyreon/ui-core. */
+  provider: CollapseImportSpec
+  /** Theme object. Default: theme from @pyreon/ui-theme. */
+  theme: CollapseImportSpec
+  /** Live mode accessor — emitted into the collapsed site for dual-emit. */
+  mode: CollapseImportSpec
+}
+
+export const DEFAULT_COLLAPSE_CONFIG: CollapseConfig = {
+  provider: { name: 'PyreonUI', source: '@pyreon/ui-core' },
+  theme: { name: 'theme', source: '@pyreon/ui-theme' },
+  mode: { name: 'useMode', source: '@pyreon/ui-core' },
+}
+
+export interface ResolveInput {
+  /** The collapsible component's import. */
+  component: CollapseImportSpec
+  /** Literal dimension/HTML props, e.g. `{ state: 'primary', size: 'md' }`. */
+  props: Record<string, string>
+  /** Static text children (empty ⇒ no children). */
+  childrenText: string
+  config: CollapseConfig
+}
+
+export interface ResolvedCollapse {
+  /** Element HTML with the root `class="..."` removed (the `_tpl` template). */
+  templateHtml: string
+  lightClass: string
+  darkClass: string
+  /** Pre-resolved styler rule text (full snapshot) for `injectRules`. */
+  rules: string[]
+  /** FNV over the rule set — `injectRules` idempotency + cross-site dedupe. */
+  key: string
+}
+
+const FIRST_CLASS_RE = /^(\s*<[a-zA-Z][\w-]*)([^>]*?)\sclass="([^"]*)"([^>]*>)/
+
+/** Strip the FIRST element's `class="..."`, returning [stripped, class]. */
+export function stripRootClass(html: string): { stripped: string; cls: string } | null {
+  const m = FIRST_CLASS_RE.exec(html)
+  if (!m) return null
+  const stripped = html.replace(FIRST_CLASS_RE, '$1$2$4')
+  return { stripped, cls: m[3] ?? '' }
+}
+
+/**
+ * Pure extraction half — given the two rendered HTML strings and the
+ * styler rule snapshot, derive the ResolvedCollapse (or null on a shape
+ * the slice doesn't collapse). Separated for direct unit-testing without
+ * spinning Vite.
+ */
+export function deriveCollapse(
+  lightHtml: string,
+  darkHtml: string,
+  rules: string[],
+): ResolvedCollapse | null {
+  const light = stripRootClass(lightHtml)
+  const dark = stripRootClass(darkHtml)
+  if (!light || !dark || !light.cls || !dark.cls) return null
+  // The structural template must be identical between modes (only the
+  // class differs). Divergent markup ⇒ not a simple single-root
+  // collapsible — bail.
+  if (light.stripped !== dark.stripped) return null
+  return {
+    templateHtml: light.stripped.trim(),
+    lightClass: light.cls,
+    darkClass: dark.cls,
+    rules,
+    key: fnv1a(rules.join('\u0000')),
+  }
+}
+
+export interface CollapseResolver {
+  resolve(input: ResolveInput): Promise<ResolvedCollapse | null>
+  dispose(): Promise<void>
+}
+
+/**
+ * Create a resolver backed by ONE programmatic Vite SSR server bound to
+ * `projectRoot`'s vite config. Reused across every call site in a build;
+ * `dispose()` at buildEnd. Module loads are cached by Vite's own SSR
+ * module graph (provider/theme/component import once).
+ */
+export async function createCollapseResolver(projectRoot: string): Promise<CollapseResolver> {
+  const { createServer } = (await import('vite')) as typeof import('vite')
+  const inline: InlineConfig = {
+    // No `configFile` override — Vite auto-loads the project's own
+    // vite.config from `root`, so module resolution (workspace `bun`
+    // condition, app aliases) matches the real build exactly.
+    root: projectRoot,
+    server: { middlewareMode: true },
+    appType: 'custom',
+    logLevel: 'silent',
+    optimizeDeps: { noDiscovery: true, include: [] },
+  }
+  let server: ViteDevServer | null = await createServer(inline)
+
+  // Resolved-bundle cache — identical input must hit the same result
+  // without a second double-render (deterministic by construction).
+  const cache = new Map<string, ResolvedCollapse | null>()
+
+  async function load(spec: string): Promise<Record<string, unknown>> {
+    return (await server!.ssrLoadModule(spec)) as Record<string, unknown>
+  }
+
+  return {
+    async resolve(input) {
+      const ck = JSON.stringify([
+        input.component,
+        input.props,
+        input.childrenText,
+        input.config.provider,
+        input.config.theme,
+      ])
+      if (cache.has(ck)) return cache.get(ck) ?? null
+      try {
+        if (!server) return null
+        const rs = await load('@pyreon/runtime-server')
+        const core = await load('@pyreon/core')
+        const styler = await load('@pyreon/styler')
+        const prov = await load(input.config.provider.source)
+        const thm = await load(input.config.theme.source)
+        const comp = await load(input.component.source)
+        const renderToString = rs.renderToString as (n: unknown) => Promise<string>
+        const h = core.h as (t: unknown, p: unknown, ...c: unknown[]) => unknown
+        const Provider = prov[input.config.provider.name]
+        const themeVal = thm[input.config.theme.name]
+        const Component = comp[input.component.name]
+        const sheet = styler.sheet as { getStyleRules(): readonly string[] }
+        if (typeof Component !== 'function' || Provider == null || themeVal == null) {
+          cache.set(ck, null)
+          return null
+        }
+        const childArgs = input.childrenText ? [input.childrenText] : []
+        const node = (mode: string) =>
+          h(Provider, { theme: themeVal, mode }, h(Component, input.props, ...childArgs))
+        const lightHtml = await renderToString(node('light'))
+        const darkHtml = await renderToString(node('dark'))
+        const rules = sheet.getStyleRules().slice()
+        const result = deriveCollapse(lightHtml, darkHtml, rules)
+        cache.set(ck, result)
+        return result
+      } catch {
+        cache.set(ck, null)
+        return null
+      }
+    },
+    async dispose() {
+      const s = server
+      server = null
+      cache.clear()
+      if (s) await s.close()
+    },
+  }
+}

package/src/tests/rocketstyle-collapse-dev.test.ts

@@ -0,0 +1,119 @@
+import { join } from 'node:path'
+import { describe, expect, it, vi } from 'vitest'
+
+// Collapse is BUILD-ONLY by design. The resolver freezes each site's class
+// from a SEPARATE nested Vite-SSR module graph and caches it; in `vite dev`
+// that frozen class would NOT react to the user's theme-source HMR edits —
+// strictly worse than the normal mount, which IS reactive. So `command:
+// 'serve'` keeps the normal rocketstyle mount, the resolver never boots,
+// and the plugin surfaces the build-only contract ONCE via `this.info`.
+//
+// The resolver is mocked here with a deterministic stub (no Vite, no
+// workspace `lib/`) PURELY so the bisect is faithful LOCALLY: with the
+// `&& isBuild` gate removed, serve-mode transform would enter the collapse
+// block, call the (stub) resolver, and emit `__rsCollapse(` — failing the
+// `.not.toContain('__rsCollapse(')` assertion. The real-Vite-SSR resolver
+// is exercised (unmocked) by the build-mode specs in the sibling
+// `rocketstyle-collapse.test.ts`.
+vi.mock('../rocketstyle-collapse', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../rocketstyle-collapse')>()
+  return {
+    ...actual,
+    createCollapseResolver: vi.fn(async () => ({
+      resolve: vi.fn(async () => ({
+        templateHtml: '<button>Save</button>',
+        lightClass: 'pyr-stub-light',
+        darkClass: 'pyr-stub-dark',
+        rules: ['.pyr-stub-light{color:red}', '.pyr-stub-dark{color:blue}'],
+        key: 'stub-key',
+      })),
+      dispose: vi.fn(async () => {}),
+    })),
+  }
+})
+
+// Imported AFTER vi.mock (hoisted) so the plugin's lazy
+// `import('./rocketstyle-collapse')` resolves to the stub.
+const { default: pyreon } = await import('../index')
+const { createCollapseResolver } = await import('../rocketstyle-collapse')
+
+type Ctx = {
+  warn: (msg: string) => void
+  info: (msg: string) => void
+  resolve: (id: string, importer?: string, opts?: { skipSelf: boolean }) => Promise<null>
+  infos: string[]
+}
+type Plugin = ReturnType<typeof pyreon>
+
+function makeCtx(): Ctx {
+  const infos: string[] = []
+  return { warn: () => {}, info: (m) => infos.push(m), resolve: async () => null, infos }
+}
+function configure(plugin: Plugin, command: 'serve' | 'build'): void {
+  ;(plugin.config as unknown as (u: Record<string, unknown>, e: { command: string }) => void)(
+    { root: '/tmp/does-not-matter' },
+    { command },
+  )
+}
+async function transform(
+  plugin: Plugin,
+  c: Ctx,
+  code: string,
+  id: string,
+): Promise<{ code: string } | undefined> {
+  const hook = plugin.transform as unknown as (
+    this: Ctx,
+    c: string,
+    i: string,
+    o?: { ssr?: boolean },
+  ) => Promise<{ code: string } | undefined>
+  return hook.call(c, code, id, { ssr: false })
+}
+
+const ID = join('/tmp', 'CollapseProbeDev.tsx')
+const SRC = `
+import { Button } from '@pyreon/ui-components'
+export const Save = () => <Button state="primary" size="medium">Save</Button>`
+
+describe('pyreon({ collapse }) — dev (serve) keeps the normal mount; build collapses', () => {
+  it('command:serve → NO __rsCollapse, normal mount, resolver never even constructed, one-time dev info', async () => {
+    const plugin = pyreon({ collapse: true })
+    configure(plugin, 'serve')
+    const c = makeCtx()
+
+    const out1 = await transform(plugin, c, SRC, ID)
+    // THE contract: dev keeps the normal rocketstyle mount. Bisect-load-
+    // bearing — drop the `&& isBuild` gate and the (stub) resolver boots +
+    // emits `__rsCollapse(` here, failing this line.
+    expect(out1?.code).not.toContain('__rsCollapse(')
+    expect(out1?.code).not.toContain('__rsSheet.injectRules(')
+    // Resolver (a nested Vite SSR server in production) is NEVER even
+    // constructed in serve mode — zero per-dev-process orphan server.
+    expect(createCollapseResolver).not.toHaveBeenCalled()
+    // One-time, actionable dev info so an opted-in `vite dev` consumer
+    // isn't left wondering why nothing collapsed.
+    expect(c.infos.filter((m) => m.includes('collapse is build-only'))).toHaveLength(1)
+
+    // A SECOND transform must NOT re-emit the info (once per plugin instance).
+    await transform(plugin, c, SRC, ID)
+    expect(c.infos.filter((m) => m.includes('collapse is build-only'))).toHaveLength(1)
+
+    // closeBundle is a guaranteed no-op in serve mode.
+    await (plugin.closeBundle as unknown as () => Promise<void>)()
+  })
+
+  it('command:build (same source, stub resolver) → DOES collapse — proves the gate is the only difference', async () => {
+    const plugin = pyreon({ collapse: true })
+    configure(plugin, 'build')
+    const c = makeCtx()
+
+    const out = await transform(plugin, c, SRC, ID)
+    // Same component, same props — only `command` differs. Build collapses.
+    expect(out?.code).toContain('__rsCollapse(')
+    expect(out?.code).toContain('__rsSheet.injectRules(')
+    // No build-only dev info in build mode.
+    expect(c.infos.filter((m) => m.includes('collapse is build-only'))).toHaveLength(0)
+
+    await (plugin.closeBundle as unknown as () => Promise<void>)()
+  })
+})