poveste 0.1.2 → 0.2.0

package/src/node/preview.ts

@@ -1,57 +1,40 @@
 import type { Context } from './context.js'
-import http from 'node:http'
-import connect from 'connect'
-import sirv from 'sirv'
+import { preview } from 'vite'
+
+export interface StartPreviewOptions {
+  port?: number
+  host?: string | boolean
+  open?: boolean
+}
 
 interface ReturnPayload {
   baseUrl: string
+  printUrls: () => void
   close: () => Promise<void>
 }
 
-export async function startPreview(port: number | null, ctx: Context): Promise<ReturnPayload> {
-  const app = connect()
-
-  app.use(
-    ctx.resolvedViteConfig.base,
-    sirv(ctx.config.outDir, {
-      dev: true,
-      etag: true,
-      single: true,
-    }),
-  )
-
-  let finalPort = port ?? 6006
-
-  const httpServer = http.createServer(app)
-
-  return new Promise((resolve, reject) => {
-    function onError(e: Error & { code?: string }) {
-      if (e.code === 'EADDRINUSE') {
-        httpServer.listen(++finalPort)
-      }
-      else {
-        reject(e)
-      }
-    }
+export async function startPreview(options: StartPreviewOptions, ctx: Context): Promise<ReturnPayload> {
+  const port = options.port ?? 6006
+  const server = await preview({
+    root: ctx.root,
+    base: ctx.resolvedViteConfig.base,
+    configFile: false,
+    build: {
+      outDir: ctx.config.outDir,
+    },
+    preview: {
+      port,
+      host: options.host,
+      open: options.open,
+      strictPort: false,
+    },
+  })
 
-    httpServer.on('error', onError)
+  const baseUrl = server.resolvedUrls?.local[0] ?? `http://localhost:${port}${ctx.resolvedViteConfig.base}`
 
-    httpServer.listen(finalPort, () => {
-      httpServer.off('error', onError)
-      const baseUrl = `http://localhost:${finalPort}${ctx.resolvedViteConfig.base}`
-      resolve({
-        baseUrl,
-        close: () => new Promise((resolve, reject) => {
-          httpServer.close((err) => {
-            if (err) {
-              reject(err)
-            }
-            else {
-              resolve()
-            }
-          })
-        }),
-      })
-    })
-  })
+  return {
+    baseUrl,
+    printUrls: () => server.printUrls(),
+    close: () => server.close(),
+  }
 }

package/src/node/style-isolation/__tests__/entry-css-merger.spec.ts

@@ -0,0 +1,126 @@
+import type { OutputBundle } from 'rollup'
+import { describe, expect, it } from 'vitest'
+import { entryCssMergerPlugin } from '../entry-css-merger.js'
+import { USER_CSS_MARK_END, USER_CSS_MARK_START } from '../vite-plugin.js'
+
+function fakeChunk(name: string, importedCss: string[], code = '', extra: Partial<any> = {}) {
+  return {
+    type: 'chunk' as const,
+    name,
+    fileName: `${name}.js`,
+    code,
+    isEntry: true,
+    viteMetadata: { importedCss: new Set(importedCss), importedAssets: new Set() },
+    facadeModuleId: null,
+    moduleIds: [],
+    imports: [],
+    dynamicImports: [],
+    exports: [],
+    map: null,
+    modules: {},
+    ...extra,
+  } as any
+}
+
+function fakeAsset(fileName: string, source: string) {
+  return { type: 'asset' as const, fileName, source, name: fileName, needsCodeReference: false } as any
+}
+
+function mark(css: string): string {
+  return `${USER_CSS_MARK_START}\n${css}\n${USER_CSS_MARK_END}\n`
+}
+
+describe('entry-css-merger', () => {
+  it('produces one CSS asset per entry chunk', async () => {
+    const plugin = entryCssMergerPlugin()
+    const bundle: OutputBundle = {
+      'bundle-main.js': fakeChunk('bundle-main', ['route1.css', 'route2.css']),
+      'bundle-sandbox.js': fakeChunk('bundle-sandbox', ['sandbox-route.css']),
+      'route1.css': fakeAsset('route1.css', 'a {}'),
+      'route2.css': fakeAsset('route2.css', 'b {}'),
+      'sandbox-route.css': fakeAsset('sandbox-route.css', 'c {}'),
+    }
+    await (plugin.generateBundle as any).call({ emitFile: () => '' }, {}, bundle)
+
+    const cssAssets = Object.values(bundle).filter(a => a.type === 'asset' && a.fileName.endsWith('.css'))
+    expect(cssAssets).toHaveLength(2)
+    const mainCss = cssAssets.find(a => a.fileName === 'bundle-main.css')
+    const sandboxCss = cssAssets.find(a => a.fileName === 'bundle-sandbox.css')
+    expect(mainCss?.source).toContain('a {}')
+    expect(mainCss?.source).toContain('b {}')
+    expect(sandboxCss?.source).toContain('c {}')
+  })
+
+  it('wraps marked user CSS in @scope on the main entry when isolation is enabled', async () => {
+    const plugin = entryCssMergerPlugin({
+      isolateStyles: true,
+      scopeRoot: '.__poveste-render-story',
+      mainEntryName: 'bundle-main',
+    })
+    const bundle: OutputBundle = {
+      'bundle-main.js': fakeChunk('bundle-main', ['user.css', 'chrome.css']),
+      'user.css': fakeAsset('user.css', mark('body { color: red }')),
+      'chrome.css': fakeAsset('chrome.css', '@scope (.poveste-app-root) { .x {} }'),
+    }
+    await (plugin.generateBundle as any).call({ emitFile: () => '' }, {}, bundle)
+
+    const main = Object.values(bundle).find(a => a.type === 'asset' && a.fileName === 'bundle-main.css') as any
+    expect(main.source).toContain('@scope (.__poveste-render-story)')
+    expect(main.source).toContain('color: red')
+    expect(main.source).toContain('@scope (.poveste-app-root)')
+    expect(main.source).not.toContain(USER_CSS_MARK_START)
+  })
+
+  it('strips markers without wrapping on the sandbox entry', async () => {
+    const plugin = entryCssMergerPlugin({
+      isolateStyles: true,
+      scopeRoot: '.__poveste-render-story',
+      mainEntryName: 'bundle-main',
+    })
+    const bundle: OutputBundle = {
+      'bundle-sandbox.js': fakeChunk('bundle-sandbox', ['user.css']),
+      'user.css': fakeAsset('user.css', mark('body { color: red }')),
+    }
+    await (plugin.generateBundle as any).call({ emitFile: () => '' }, {}, bundle)
+
+    const sandbox = Object.values(bundle).find(a => a.type === 'asset' && a.fileName === 'bundle-sandbox.css') as any
+    expect(sandbox.source).toContain('body')
+    expect(sandbox.source).toContain('color: red')
+    expect(sandbox.source).not.toContain('@scope')
+    expect(sandbox.source).not.toContain(USER_CSS_MARK_START)
+  })
+
+  it('attributes CSS from transitively-imported chunks (e.g. vendor)', async () => {
+    const plugin = entryCssMergerPlugin()
+    const main = fakeChunk('bundle-main', ['app.css'], '', { imports: ['vendor.js'], isEntry: true })
+    main.fileName = 'bundle-main.js'
+    const vendor = { ...fakeChunk('vendor', ['vendor.css']), isEntry: false, fileName: 'vendor.js' }
+    const bundle: OutputBundle = {
+      'bundle-main.js': main,
+      'vendor.js': vendor,
+      'app.css': fakeAsset('app.css', '.app {}'),
+      'vendor.css': fakeAsset('vendor.css', '.vendor {}'),
+    }
+    await (plugin.generateBundle as any).call({ emitFile: () => '' }, {}, bundle)
+    const mainCss = Object.values(bundle).find(a => a.type === 'asset' && a.fileName === 'bundle-main.css') as any
+    expect(mainCss.source).toContain('.app')
+    expect(mainCss.source).toContain('.vendor')
+  })
+
+  it('strips markers without wrapping when isolation is disabled', async () => {
+    const plugin = entryCssMergerPlugin({
+      isolateStyles: false,
+      scopeRoot: '.__poveste-render-story',
+      mainEntryName: 'bundle-main',
+    })
+    const bundle: OutputBundle = {
+      'bundle-main.js': fakeChunk('bundle-main', ['user.css']),
+      'user.css': fakeAsset('user.css', mark('body { color: red }')),
+    }
+    await (plugin.generateBundle as any).call({ emitFile: () => '' }, {}, bundle)
+
+    const main = Object.values(bundle).find(a => a.type === 'asset' && a.fileName === 'bundle-main.css') as any
+    expect(main.source).not.toContain('@scope')
+    expect(main.source).not.toContain(USER_CSS_MARK_START)
+  })
+})

package/src/node/style-isolation/__tests__/transforms.spec.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from 'vitest'
+import { isGlobalImport, wrapChromeCss, wrapUserCss } from '../transforms.js'
+
+describe('wrapUserCss', () => {
+  it('wraps a single rule in @scope (.scope-root)', () => {
+    const out = wrapUserCss('body { color: red }', { scopeRoot: '.__poveste-render-story' })
+    expect(out).toContain('@scope (.__poveste-render-story)')
+    expect(out).toContain('body')
+    expect(out).toContain('color: red')
+  })
+
+  it('rewrites :root → :scope inside the scope', () => {
+    const out = wrapUserCss(':root { --color-primary: blue }', {
+      scopeRoot: '.__poveste-render-story',
+    })
+    expect(out).toContain(':scope')
+    expect(out).not.toContain(':root')
+    expect(out).toContain('--color-primary: blue')
+  })
+
+  it('leaves :scope alone (idempotent)', () => {
+    const out = wrapUserCss(':scope { color: red }', {
+      scopeRoot: '.__poveste-render-story',
+    })
+    expect(out).toContain(':scope')
+    expect(out).not.toContain(':scope:scope')
+  })
+
+  it('hoists @import outside the @scope block', () => {
+    const css = `@import url('https://fonts.googleapis.com/css2?family=Foo');\nbody { color: red }`
+    const out = wrapUserCss(css, { scopeRoot: '.__poveste-render-story' })
+    expect(out.indexOf('@import')).toBeLessThan(out.indexOf('@scope'))
+  })
+
+  it('does not double-wrap CSS that already starts with @scope', () => {
+    const input = wrapUserCss('body { color: red }', { scopeRoot: '.__poveste-render-story' })
+    const out = wrapUserCss(input, { scopeRoot: '.__poveste-render-story' })
+    const occurrences = (out.match(/@scope/g) ?? []).length
+    expect(occurrences).toBe(1)
+  })
+})
+
+describe('wrapChromeCss', () => {
+  it('wraps in @scope (root) to (lower)', () => {
+    const out = wrapChromeCss('body { color: red }', {
+      scopeRoot: '.poveste-app-root',
+      scopeLower: '.__poveste-render-story',
+    })
+    expect(out).toContain('@scope (.poveste-app-root) to (.__poveste-render-story)')
+    expect(out).toContain('body')
+  })
+
+  it('hoists @import to the top, outside @scope', () => {
+    const css = `@import url('reset.css');\nbody { color: red }`
+    const out = wrapChromeCss(css, {
+      scopeRoot: '.poveste-app-root',
+      scopeLower: '.__poveste-render-story',
+    })
+    const importIdx = out.indexOf('@import')
+    const scopeIdx = out.indexOf('@scope')
+    expect(importIdx).toBeGreaterThanOrEqual(0)
+    expect(scopeIdx).toBeGreaterThan(importIdx)
+  })
+
+  it('hoists @font-face above @scope', () => {
+    const css = `@font-face { font-family: A; src: url('a.woff2') }\nbody { font-family: A }`
+    const out = wrapChromeCss(css, {
+      scopeRoot: '.poveste-app-root',
+      scopeLower: '.__poveste-render-story',
+    })
+    expect(out.indexOf('@font-face')).toBeLessThan(out.indexOf('@scope'))
+  })
+
+  it('preserves an arbitrary scopeLower selector in the @scope prelude', () => {
+    const out = wrapChromeCss('body { color: red }', {
+      scopeRoot: '.poveste-app-root',
+      scopeLower: '.__poveste-render-story:not(.__poveste-render-custom-controls)',
+    })
+    expect(out).toContain('@scope (.poveste-app-root) to (.__poveste-render-story:not(.__poveste-render-custom-controls))')
+  })
+})
+
+describe('isGlobalImport', () => {
+  it('returns true for ids ending in ?global', () => {
+    expect(isGlobalImport('/abs/path/foo.css?global')).toBe(true)
+    expect(isGlobalImport('foo.css?global&bar')).toBe(true)
+  })
+  it('returns false otherwise', () => {
+    expect(isGlobalImport('/abs/path/foo.css')).toBe(false)
+    expect(isGlobalImport('foo.css?inline')).toBe(false)
+  })
+})

package/src/node/style-isolation/__tests__/vite-plugin.spec.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest'
+import { GLOBAL_LAYER_QUERY } from '../selectors.js'
+import { USER_CSS_MARK_START, userCssScopePlugin } from '../vite-plugin.js'
+
+function transform(id: string, code = 'body { color: red }', enabled = true) {
+  const plugin = userCssScopePlugin({ enabled })
+  return (plugin.transform as any).call({}, code, id) as { code: string } | null
+}
+
+describe('userCssScopePlugin', () => {
+  it('marks user CSS so the merger can wrap it per entry', () => {
+    expect(transform('/project/src/poveste.css')?.code).toContain(USER_CSS_MARK_START)
+  })
+
+  it('marks style blocks of single-file components', () => {
+    expect(transform('/project/src/Foo.vue?vue&type=style&index=0&lang.css')?.code).toContain(USER_CSS_MARK_START)
+  })
+
+  it('leaves chrome CSS alone', () => {
+    expect(transform('/project/node_modules/@poveste/app/dist/style.css')).toBeNull()
+    expect(transform('/project/node_modules/@poveste/controls/dist/index.es.css')).toBeNull()
+  })
+
+  it('leaves non-CSS alone', () => {
+    expect(transform('/project/src/main.ts')).toBeNull()
+  })
+
+  it('leaves ?global imports unscoped', () => {
+    expect(transform('/project/src/tokens.css?global')).toBeNull()
+  })
+
+  it('leaves globalStyles files unscoped — they belong to the chrome page', () => {
+    expect(transform(`/project/src/tokens.css?${GLOBAL_LAYER_QUERY}`)).toBeNull()
+  })
+
+  it('does nothing when isolation is disabled', () => {
+    expect(transform('/project/src/poveste.css', 'body {}', false)).toBeNull()
+  })
+})

package/src/node/style-isolation/entry-css-merger.ts

@@ -0,0 +1,133 @@
+import type { OutputBundle } from 'rollup'
+import type { Plugin as VitePlugin } from 'vite'
+import { STORY_SCOPE_ROOT } from './selectors.js'
+import { wrapUserCss } from './transforms.js'
+import { USER_CSS_MARK_END, USER_CSS_MARK_START } from './vite-plugin.js'
+
+export interface EntryCssMergerOptions {
+  isolateStyles: boolean
+  scopeRoot?: string
+  mainEntryName?: string
+}
+
+export function entryCssMergerPlugin(opts: EntryCssMergerOptions = { isolateStyles: false }): VitePlugin {
+  const scopeRoot = opts.scopeRoot ?? STORY_SCOPE_ROOT
+  const mainEntryName = opts.mainEntryName ?? 'bundle-main'
+  return {
+    name: 'poveste:style-isolation:entry-css-merger',
+    apply: 'build',
+    enforce: 'post',
+    generateBundle(_options, bundle: OutputBundle) {
+      function collectChunkCss(entryFileName: string, entryName: string, acc: Map<string, string[]>) {
+        const seen = new Set<string>()
+        const queue = [entryFileName]
+        let head = 0
+        while (head < queue.length) {
+          const cur = queue[head++]
+          if (seen.has(cur)) continue
+          seen.add(cur)
+          const c = bundle[cur]
+          if (!c || c.type !== 'chunk') continue
+          const meta = (c as any).viteMetadata
+          if (meta?.importedCss) {
+            for (const cssName of meta.importedCss as Set<string>) {
+              const list = acc.get(cssName) ?? []
+              if (!list.includes(entryName)) list.push(entryName)
+              acc.set(cssName, list)
+            }
+          }
+          for (const imp of c.imports ?? []) queue.push(imp)
+          for (const imp of c.dynamicImports ?? []) queue.push(imp)
+        }
+      }
+
+      const cssAssetUsedBy = new Map<string, string[]>()
+      for (const [fileName, chunk] of Object.entries(bundle)) {
+        if (chunk.type !== 'chunk' || !chunk.isEntry) continue
+        collectChunkCss(fileName, chunk.name, cssAssetUsedBy)
+      }
+
+      const mergedByEntry = new Map<string, string[]>()
+      for (const [cssName, entries] of cssAssetUsedBy) {
+        const asset = bundle[cssName]
+        if (!asset || asset.type !== 'asset') continue
+        const source = typeof asset.source === 'string'
+          ? asset.source
+          : new TextDecoder().decode(asset.source as Uint8Array)
+        for (const entryName of entries) {
+          const list = mergedByEntry.get(entryName) ?? []
+          list.push(source)
+          mergedByEntry.set(entryName, list)
+        }
+        delete bundle[cssName]
+      }
+
+      for (const [entryName, sources] of mergedByEntry) {
+        const fileName = `${entryName}.css`
+        const merged = sources.join('\n')
+        const finalSource = entryName === mainEntryName && opts.isolateStyles
+          ? wrapMarkedUserCss(merged, scopeRoot)
+          : stripMarkers(merged)
+        bundle[fileName] = {
+          type: 'asset',
+          fileName,
+          name: fileName,
+          source: finalSource,
+          needsCodeReference: false,
+        } as any
+      }
+
+      // Re-point CSS metadata: entries claim their own merged file; non-entry
+      // chunks (vendor, route splits) drop their importedCss because the
+      // assets they referenced were merged into the entry's CSS and deleted.
+      // Without this, Vite's runtime preload helper 404s on the missing
+      // per-chunk CSS files.
+      const entryCssByEntryName = new Map<string, string>()
+      for (const [, chunk] of Object.entries(bundle)) {
+        if (chunk.type !== 'chunk' || !chunk.isEntry) continue
+        if (mergedByEntry.has(chunk.name)) {
+          entryCssByEntryName.set(chunk.name, `${chunk.name}.css`)
+        }
+      }
+      for (const [, chunk] of Object.entries(bundle)) {
+        if (chunk.type !== 'chunk') continue
+        const meta = (chunk as any).viteMetadata
+        if (!meta?.importedCss) continue
+        if (chunk.isEntry && entryCssByEntryName.has(chunk.name)) {
+          meta.importedCss = new Set([entryCssByEntryName.get(chunk.name)!])
+        }
+        else {
+          meta.importedCss = new Set()
+        }
+      }
+    },
+  }
+}
+
+function stripMarkers(css: string): string {
+  return css.split(USER_CSS_MARK_START).join('').split(USER_CSS_MARK_END).join('')
+}
+
+export function wrapMarkedUserCss(css: string, scopeRoot: string): string {
+  let out = ''
+  let cursor = 0
+  while (cursor < css.length) {
+    const start = css.indexOf(USER_CSS_MARK_START, cursor)
+    if (start === -1) {
+      out += css.slice(cursor)
+      break
+    }
+    out += css.slice(cursor, start)
+    const end = css.indexOf(USER_CSS_MARK_END, start + USER_CSS_MARK_START.length)
+    if (end === -1) {
+      out += css.slice(start + USER_CSS_MARK_START.length)
+      break
+    }
+    const inner = css.slice(start + USER_CSS_MARK_START.length, end).trim()
+    if (inner.length > 0) {
+      out += `${wrapUserCss(inner, { scopeRoot })}\n`
+    }
+    cursor = end + USER_CSS_MARK_END.length
+  }
+  return out
+}

package/src/node/style-isolation/global-styles.ts

@@ -0,0 +1,37 @@
+import type { Plugin as VitePlugin } from 'vite'
+import { resolve } from 'pathe'
+import { GLOBAL_LAYER_QUERY, USER_GLOBALS_LAYER } from './selectors.js'
+
+const VIRTUAL_ID = 'virtual:$poveste-global-styles'
+const RESOLVED_ID = `\0${VIRTUAL_ID}`
+
+export interface GlobalStylesPluginOptions {
+  files: string[]
+  rootDir: string
+}
+
+export function globalStylesPlugin(opts: GlobalStylesPluginOptions): VitePlugin {
+  return {
+    name: 'poveste:style-isolation:global-styles',
+    resolveId(id) {
+      if (id === VIRTUAL_ID) return RESOLVED_ID
+    },
+    load(id) {
+      if (id !== RESOLVED_ID) return null
+      return opts.files
+        .map(f => `import ${JSON.stringify(`${resolve(opts.rootDir, f)}?${GLOBAL_LAYER_QUERY}`)}`)
+        .join('\n')
+    },
+    transform(code, id) {
+      if (!id.includes(`?${GLOBAL_LAYER_QUERY}`)) return null
+      return {
+        code: `@layer ${USER_GLOBALS_LAYER} {\n${code}\n}\n`,
+        map: null,
+      }
+    },
+  }
+}
+
+export function getGlobalStylesVirtualId(): string {
+  return VIRTUAL_ID
+}

package/src/node/style-isolation/index.ts

@@ -0,0 +1,5 @@
+export * from './entry-css-merger.js'
+export * from './global-styles.js'
+export * from './scope-chrome.js'
+export * from './transforms.js'
+export * from './vite-plugin.js'

package/src/node/style-isolation/scope-chrome.ts

@@ -0,0 +1,42 @@
+import type { Plugin as VitePlugin } from 'vite'
+import { APP_SCOPE_ROOT, DEFAULTS_LAYER, STORY_SCOPE_BOUNDARY } from './selectors.js'
+import { wrapChromeCss } from './transforms.js'
+import { isChromeCss } from './vite-plugin.js'
+
+export interface ChromeCssScopePluginOptions {
+  enabled: boolean
+}
+
+export function chromeCssScopePlugin(opts: ChromeCssScopePluginOptions): VitePlugin {
+  return {
+    name: 'poveste:style-isolation:chrome-css',
+    transform(code, id) {
+      if (!opts.enabled) return null
+      if (isMainChromeCss(id)) {
+        return { code: wrapChromeCss(code, { scopeRoot: APP_SCOPE_ROOT, scopeLower: STORY_SCOPE_BOUNDARY }), map: null }
+      }
+      if (isSandboxChromeCss(id)) {
+        // Sandbox chrome defaults coexist with user CSS inside the iframe.
+        // @layer makes user's unlayered rules win the cascade.
+        return { code: `@layer ${DEFAULTS_LAYER} {\n${code}\n}\n`, map: null }
+      }
+      return null
+    },
+  }
+}
+
+// Stylesheets loaded only by the chrome page (bundle-main).
+function isMainChromeCss(id: string): boolean {
+  if (!isChromeCss(id)) return false
+  const cleaned = id.split('?')[0]
+  return /(?:poveste-app|@poveste\/app)\/(?:dist\/style\.css|dist\/bundled\/[^/]+\.css|src\/app\/style\/main\.(?:css|pcss))$/.test(cleaned)
+}
+
+// Stylesheets loaded into the sandbox iframe — must coexist with user CSS,
+// so they get a cascade-layer wrap rather than an @scope wrap.
+function isSandboxChromeCss(id: string): boolean {
+  if (!isChromeCss(id)) return false
+  const cleaned = id.split('?')[0]
+  return /\/(?:poveste-app|@poveste\/app)\/(?:dist|src)\/.*\bsandbox\.css$/.test(cleaned)
+    || /\/(?:poveste-controls|@poveste\/controls)\/dist\/index\.es\.css$/.test(cleaned)
+}

package/src/node/style-isolation/selectors.ts

@@ -0,0 +1,16 @@
+// Centralised CSS scope-root class names used by the style-isolation
+// pipeline. Keep in sync with the runtime markers applied in
+// poveste-app (App.vue's `poveste-app-root` wrapper, GenericRenderStory's
+// `__poveste-render-story` class, sandbox.ts's body class).
+
+export const APP_SCOPE_ROOT = '.poveste-app-root'
+export const STORY_SCOPE_ROOT = '.__poveste-render-story'
+// Custom-controls panels carry both classes (.__poveste-render-story and
+// .__poveste-render-custom-controls) but render inside the chrome panel,
+// so the @scope boundary must keep them in chrome scope.
+export const STORY_SCOPE_BOUNDARY = '.__poveste-render-story:not(.__poveste-render-custom-controls)'
+export const DEFAULTS_LAYER = 'poveste-defaults'
+export const USER_GLOBALS_LAYER = 'poveste-user-globals'
+// Import query `globalStyles` files carry so the user-CSS plugin leaves them
+// alone — they belong in the chrome page, not inside the story scope.
+export const GLOBAL_LAYER_QUERY = 'poveste-global-layer'

package/src/node/style-isolation/transforms.ts

@@ -0,0 +1,90 @@
+import { Buffer } from 'node:buffer'
+import { transform as lightningcssTransform } from 'lightningcss'
+
+export interface WrapOptions {
+  scopeRoot: string
+}
+
+export interface WrapWithLowerOptions {
+  scopeRoot: string
+  scopeLower: string
+}
+
+export function wrapUserCss(css: string, opts: WrapOptions): string {
+  const trimmed = css.trimStart()
+  if (trimmed.startsWith('@scope')) {
+    return css
+  }
+  const { hoisted, remainder } = extractHoistableAtRules(css)
+  const body = remainder.includes(':root')
+    ? rewriteRootToScope(remainder)
+    : remainder
+  const hoistedBlock = hoisted.length > 0 ? `${hoisted.join('\n')}\n` : ''
+  return `${hoistedBlock}@scope (${opts.scopeRoot}) {\n${body}\n}\n`
+}
+
+export function wrapChromeCss(css: string, opts: WrapWithLowerOptions): string {
+  const trimmed = css.trimStart()
+  if (trimmed.startsWith('@scope (')) {
+    return css
+  }
+  const { hoisted, remainder } = extractHoistableAtRules(css)
+  // Rewrite `:root` to `:scope` so source-level `@scope (:root) to (...)`
+  // rules nest correctly under the outer scope; without this, the inner
+  // `:root` resolves to the document root which is outside the outer scope.
+  const body = remainder.includes(':root')
+    ? rewriteRootToScope(remainder)
+    : remainder
+  const hoistedBlock = hoisted.length > 0 ? `${hoisted.join('\n')}\n` : ''
+  return `${hoistedBlock}@scope (${opts.scopeRoot}) to (${opts.scopeLower}) {\n${body}\n}\n`
+}
+
+export function isGlobalImport(id: string): boolean {
+  const q = id.indexOf('?')
+  if (q === -1) return false
+  const parts = id.slice(q + 1).split('&')
+  return parts.includes('global') || parts.some(p => p.startsWith('global='))
+}
+
+function rewriteRootToScope(css: string): string {
+  const processed = lightningcssTransform({
+    filename: 'user.css',
+    code: Buffer.from(css, 'utf8'),
+    minify: false,
+    visitor: {
+      Selector(selector) {
+        for (const part of selector) {
+          if (part.type === 'pseudo-class' && (part as any).kind === 'root') {
+            ;(part as any).kind = 'scope'
+          }
+        }
+        return selector
+      },
+    },
+  })
+  return Buffer.from(processed.code).toString('utf8')
+}
+
+// Top-level at-rule extraction. Anchored to line start with optional leading
+// whitespace; covers the formatted output produced by Vite/PostCSS. Inputs
+// with rules on the same line as other rules, or strings/comments containing
+// `;`/`}`, are not handled — these are extremely rare in practice and would
+// only mis-classify within a generated poveste-app or vendor stylesheet.
+const HOIST_SEMI_RE = /^[ \t]*@(?:import|charset|namespace)\s[^;]+;[ \t]*\n?/gm
+const HOIST_FONT_FACE_RE = /^[ \t]*@font-face\s*\{[^}]*\}[ \t]*\n?/gm
+
+function extractHoistableAtRules(css: string): { hoisted: string[], remainder: string } {
+  const hoisted: string[] = []
+  let remainder = css
+
+  remainder = remainder.replace(HOIST_SEMI_RE, (match) => {
+    hoisted.push(match.trim())
+    return ''
+  })
+  remainder = remainder.replace(HOIST_FONT_FACE_RE, (match) => {
+    hoisted.push(match.trim())
+    return ''
+  })
+
+  return { hoisted, remainder }
+}