feat(build): accept an input stylesheet, and warn on an @apply that is dropped

`input` names an authored stylesheet the build processes and emits with the
utilities, so component CSS goes through the same pipeline instead of living
in a `preflights` string the engine never reads. It is emitted AFTER the
utilities, so a rule written by hand beats a utility of equal specificity --
which is the reason to have written it.

A utility `@apply` cannot generate, or a `theme()` path that resolves to
nothing, is reported with the file it came from rather than passed through
in silence.

And until a sheet is moved over, `@apply` in a preflight now says it will not
reach the browser. It was shipped verbatim as an unknown at-rule and dropped
there, with nothing in the build to suggest why the styles were missing.

Closes #24

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: glennmichael123

packages/toolkit/src/engine/build.ts

@@ -2,6 +2,7 @@ import type { CssConfig } from './types'
 import { CSSGenerator } from './generator'
 import { resolveSafelist } from './safelist'
 import { Scanner } from './scanner'
+import { containsApply, processStylesheet } from './stylesheet'
 import { collectStyles } from './style/collect'
 import { resetStyles } from './style/registry'
 import { CompileClassTransformer } from './transformer-compile-class'
@@ -64,9 +65,34 @@ export async function build(config: CssConfig): Promise<BuildResult> {
     }
   }
 
+  // A preflight is shipped verbatim, so an `@apply` in one reaches the
+  // browser as an unknown at-rule and is dropped there without a word. Say so
+  // rather than leaving the author to find it in devtools.
+  if (config.includePreflight !== false) {
+    for (const preflight of config.preflights) {
+      if (containsApply(preflight.getCSS())) {
+        console.warn('⚠️  @apply in a preflight is not expanded and will not reach the browser. Put the CSS in the `input` stylesheet instead.')
+        break
+      }
+    }
+  }
+
   // Preflight CSS is now added by generator.toCSS()
   let css = generator.toCSS(config.includePreflight !== false, config.minify)
 
+  // The authored stylesheet goes after the utilities, so a rule written by
+  // hand beats a utility of equal specificity -- which is the reason to have
+  // written it there.
+  if (config.input) {
+    const source = await Bun.file(config.input).text()
+    const processed = processStylesheet(source, generator, config.theme)
+    for (const utility of processed.unknownUtilities)
+      console.warn(`⚠️  @apply ${utility}: not a utility this config generates (${config.input})`)
+    for (const path of processed.unknownThemePaths)
+      console.warn(`⚠️  theme(${path}): no such value in the theme (${config.input})`)
+    css += `\n${processed.css}`
+  }
+
   // Styles declared through the `css.create()` API live in modules, not in
   // class attributes, so the scanner never sees them. Evaluating those modules
   // registers their atomic rules; append the result after the utilities so a

packages/toolkit/src/engine/types.ts

@@ -130,6 +130,15 @@ export interface CssConfig {
    * Enabled by default; see `CodeStringsConfig` in the parser.
    */
   codeStrings?: CodeStringsConfig
+  /**
+   * An authored stylesheet to process and emit alongside the utilities.
+   *
+   * Its `@apply` expands to the declarations the named utilities produce and
+   * its `theme()` reads the registered theme, so component CSS goes through
+   * the same pipeline as everything else instead of living in a `preflights`
+   * string the engine never reads. Nesting is passed through as written.
+   */
+  input?: string
   /** Generate :root CSS variables from theme colors (e.g., --monokai-bg: #2d2a2e) */
   cssVariables?: boolean
   /**