@bamboocss/types 1.30.1 → 1.32.0

package/dist/composition.d.ts

@@ -1,4 +1,5 @@
-import type { CompositionStyleObject } from './system-types'
+import type { Nested } from './conditions'
+import type { CssVarProperties, SystemProperties } from './style-props'
 
 interface Token<T> {
   value: T
@@ -10,217 +11,34 @@ interface Recursive<T> {
 }
 
 /* -----------------------------------------------------------------------------
- * Text styles
+ * Mixins
  * -----------------------------------------------------------------------------*/
 
-type TextStyleProperty =
-  | 'color'
-  | 'direction'
-  | 'font'
-  | 'fontFamily'
-  | 'fontFeatureSettings'
-  | 'fontKerning'
-  | 'fontLanguageOverride'
-  | 'fontOpticalSizing'
-  | 'fontPalette'
-  | 'fontSize'
-  | 'fontSizeAdjust'
-  | 'fontStretch'
-  | 'fontStyle'
-  | 'fontSynthesis'
-  | 'fontVariant'
-  | 'fontVariantAlternates'
-  | 'fontVariantCaps'
-  | 'fontVariantLigatures'
-  | 'fontVariantNumeric'
-  | 'fontVariantPosition'
-  | 'fontVariationSettings'
-  | 'fontWeight'
-  | 'hangingPunctuation'
-  | 'hypens'
-  | 'hyphenateCharacter'
-  | 'hyphenateLimitChars'
-  | 'letterSpacing'
-  | 'lineBreak'
-  | 'lineHeight'
-  | 'quotes'
-  | 'overflowWrap'
-  | 'tabSize'
-  | 'textAlign'
-  | 'textAlignLast'
-  | 'textBox'
-  | 'textBoxEdge'
-  | 'textBoxTrim'
-  | 'textCombineUpright'
-  | 'textDecoration'
-  | 'textDecorationColor'
-  | 'textDecorationLine'
-  | 'textDecorationSkip'
-  | 'textDecorationSkipBox'
-  | 'textDecorationSkipInk'
-  | 'textDecorationSkipInset'
-  | 'textDecorationStyle'
-  | 'textDecorationThickness'
-  | 'textEmphasis'
-  | 'textEmphasisColor'
-  | 'textEmphasisPosition'
-  | 'textEmphasisStyle'
-  | 'textIndent'
-  | 'textJustify'
-  | 'textOrientation'
-  | 'textOverflow'
-  | 'textRendering'
-  | 'textShadow'
-  | 'textStroke'
-  | 'textStrokeColor'
-  | 'textStrokeWidth'
-  | 'textTransform'
-  | 'textUnderlineOffset'
-  | 'textUnderlinePosition'
-  | 'textWrap'
-  | 'textWrapMode'
-  | 'textWrapStyle'
-  | 'unicodeBidi'
-  | 'verticalAlign'
-  | 'whiteSpace'
-  | 'wordBreak'
-  | 'wordSpacing'
-  | 'writingMode'
-
-export type TextStyle = CompositionStyleObject<TextStyleProperty>
-
-export type TextStyles = Recursive<Token<TextStyle>>
-
-/* -----------------------------------------------------------------------------
- * Layer styles
- * -----------------------------------------------------------------------------*/
-
-type LogicalPlacement = 'Inline' | 'Block' | 'InlineStart' | 'InlineEnd' | 'BlockStart' | 'BlockEnd'
-
-type PhysicalPlacement = 'Top' | 'Right' | 'Bottom' | 'Left'
-
-type Placement = PhysicalPlacement | LogicalPlacement
-
-type Radius =
-  | `Top${'Right' | 'Left'}`
-  | `Bottom${'Right' | 'Left'}`
-  | `Start${'Start' | 'End'}`
-  | `End${'Start' | 'End'}`
-
-type LayerStyleProperty =
-  | 'aspectRatio'
-  | 'background'
-  | 'backgroundColor'
-  | 'backgroundImage'
-  | 'border'
-  | 'borderColor'
-  | 'borderImage'
-  | 'borderImageOutset'
-  | 'borderImageRepeat'
-  | 'borderImageSlice'
-  | 'borderImageSource'
-  | 'borderImageWidth'
-  | 'borderRadius'
-  | 'borderStyle'
-  | 'borderWidth'
-  | `border${Placement}`
-  | `border${Placement}Color`
-  | `border${Placement}Style`
-  | `border${Placement}Width`
-  | 'borderRadius'
-  | `border${Radius}Radius`
-  | 'boxShadow'
-  | 'boxShadowColor'
-  | 'clipPath'
-  | 'color'
-  | 'contain'
-  | 'content'
-  | 'contentVisibility'
-  | 'cursor'
-  | 'display'
-  | 'filter'
-  | 'backdropFilter'
-  | 'height'
-  | 'width'
-  | 'minHeight'
-  | 'minWidth'
-  | 'maxHeight'
-  | 'maxWidth'
-  | `margin${Placement}`
-  | 'inset'
-  | `inset${LogicalPlacement}`
-  | Lowercase<PhysicalPlacement>
-  | 'isolation'
-  | 'mask'
-  | 'maskClip'
-  | 'maskComposite'
-  | 'maskImage'
-  | 'maskMode'
-  | 'maskOrigin'
-  | 'maskPosition'
-  | 'maskRepeat'
-  | 'maskSize'
-  | 'mixBlendMode'
-  | 'objectFit'
-  | 'objectPosition'
-  | 'opacity'
-  | 'outline'
-  | 'outlineColor'
-  | 'outlineOffset'
-  | 'outlineStyle'
-  | 'outlineWidth'
-  | 'overflow'
-  | 'overflowX'
-  | 'overflowY'
-  | 'padding'
-  | `padding${Placement}`
-  | 'pointerEvents'
-  | 'position'
-  | 'resize'
-  | 'transform'
-  | 'transition'
-  | 'visibility'
-  | 'willChange'
-  | 'zIndex'
-  | 'backgroundBlendMode'
-  | 'backgroundAttachment'
-  | 'backgroundClip'
-  | 'backgroundOrigin'
-  | 'backgroundPosition'
-  | 'backgroundRepeat'
-  | 'backgroundSize'
-
-export type LayerStyle = CompositionStyleObject<LayerStyleProperty>
-
-export type LayerStyles = Recursive<Token<LayerStyle>>
-
-/* -----------------------------------------------------------------------------
- * Motion styles
- * -----------------------------------------------------------------------------*/
-
-type AnimationStyleProperty =
-  | 'animation'
-  | 'animationComposition'
-  | 'animationDelay'
-  | 'animationDirection'
-  | 'animationDuration'
-  | 'animationFillMode'
-  | 'animationIterationCount'
-  | 'animationName'
-  | 'animationPlayState'
-  | 'animationTimingFunction'
-  | 'animationRange'
-  | 'animationRangeStart'
-  | 'animationRangeEnd'
-  | 'animationTimeline'
-  | 'transformOrigin'
-
-export type AnimationStyle = CompositionStyleObject<AnimationStyleProperty>
-
-export type AnimationStyles = Recursive<Token<AnimationStyle>>
+/**
+ * A named bundle of declarations, applied by name through the `mixin` style property.
+ *
+ * This was three theme keys — `textStyles`, `layerStyles` and `animationStyles` — with three
+ * `define*` helpers, three spec artifacts and three style properties, all running through the
+ * same registration and differing only in which css properties the value was allowed to set.
+ *
+ * That partition was not a guard worth three concepts. It was arbitrary at the edges (`color`
+ * was legal in both a text style and a layer style, `transform` in a layer style but
+ * `transformOrigin` only in an animation style), and it cost something real in the middle: a
+ * bundle wanting a font *and* a border had to be split across two keys and applied twice,
+ * because neither key would accept the other's half.
+ *
+ * What the three allowlists did buy was rejecting a property that does not exist, and that is
+ * kept here rather than thrown away with them — which is why this is not simply
+ * `SystemStyleObject`. That type unions in an index signature so a style object can carry an
+ * arbitrary selector or at-rule, and an index signature accepts anything, including a typo.
+ * `TextStyleProperty` once listed `hypens` instead of `hyphens` and nothing could notice; under
+ * an index signature nothing would notice again. Conditions and nested selectors still work,
+ * because `Nested` supplies those keys itself.
+ */
+export type Mixin = Nested<SystemProperties & CssVarProperties>
+
+export type Mixins = Recursive<Token<Mixin>>
 
 export interface CompositionStyles {
-  textStyles: TextStyles
-  layerStyles: LayerStyles
-  animationStyles: AnimationStyles
+  mixins: Mixins
 }

package/dist/conditions.d.ts

@@ -58,7 +58,6 @@ export type Condition = string
 
 export type ConditionalValue<V> =
   | V
-  | Array<V | null>
   | {
       [K in keyof Conditions]?: ConditionalValue<V>
     }

package/dist/config.d.ts

@@ -24,24 +24,50 @@ export interface Patterns {
   [pattern: string]: PatternConfig
 }
 
-export interface PresetCore {
-  /**
-   * The css selectors or media queries shortcuts.
-   * @example `{ hover: "&:hover" }`
-   */
-  conditions: Conditions
+/**
+ * Everything emitted at the document level rather than against a class.
+ *
+ * These were four top-level keys — `globalCss`, `globalFontface`, `globalPositionTry` and
+ * `globalVars`. Grouping them is not only tidier: `globalVars` was the one of the four that
+ * `PresetCore` never listed, so it kept its `extend` wrapper in the *resolved* config while
+ * its three siblings lost theirs. One key cannot disagree with itself that way.
+ */
+export interface GlobalCore {
   /**
    * The global styles for your project.
    */
-  globalCss: GlobalStyleObject
+  css: GlobalStyleObject
   /**
    * The global fontface for your project.
    */
-  globalFontface?: GlobalFontface
+  fontface?: GlobalFontface
   /**
    * The global custom position try fallback option
    */
-  globalPositionTry?: GlobalPositionTry
+  positionTry?: GlobalPositionTry
+  /**
+   * The css variables for your project.
+   */
+  vars?: GlobalVarsDefinition
+}
+
+interface ExtendableGlobal {
+  css?: ExtendableGlobalStyleObject
+  fontface?: ExtendableGlobalFontface
+  positionTry?: ExtendableGlobalPositionTry
+  vars?: ExtendableGlobalVars
+}
+
+export interface PresetCore {
+  /**
+   * The css selectors or media queries shortcuts.
+   * @example `{ hover: "&:hover" }`
+   */
+  conditions: Conditions
+  /**
+   * Styles, fontfaces, position-try fallbacks and css variables emitted at the document level.
+   */
+  global: GlobalCore
   /**
    * Used to generate css utility classes for your project.
    */
@@ -58,10 +84,6 @@ export interface PresetCore {
    * Common styling or layout patterns for your project.
    */
   patterns: Record<string, PatternConfig>
-  /**
-   * Multiple themes for your project.
-   */
-  themes?: ThemeVariantsMap
 }
 
 interface ExtendablePatterns {
@@ -125,17 +147,6 @@ interface ExtendableGlobalPositionTry {
   extend?: GlobalPositionTry | undefined
 }
 
-export interface ThemeVariant extends Pick<Theme, 'tokens' | 'semanticTokens'> {}
-
-export interface ThemeVariantsMap {
-  [name: string]: ThemeVariant
-}
-
-interface ExtendableThemeVariantsMap {
-  [name: string]: ThemeVariantsMap | ThemeVariant | undefined
-  extend?: ThemeVariantsMap | undefined
-}
-
 export interface ExtendableOptions {
   /**
    * The css selectors or media queries shortcuts.
@@ -143,17 +154,9 @@ export interface ExtendableOptions {
    */
   conditions?: ExtendableConditions
   /**
-   * The global styles for your project.
+   * Styles, fontfaces, position-try fallbacks and css variables emitted at the document level.
    */
-  globalCss?: ExtendableGlobalStyleObject
-  /**
-   * The global fontface for your project.
-   */
-  globalFontface?: ExtendableGlobalFontface
-  /**
-   * The global custom position try fallback option
-   */
-  globalPositionTry?: ExtendableGlobalPositionTry
+  global?: ExtendableGlobal
   /**
    * Used to generate css utility classes for your project.
    */
@@ -170,14 +173,6 @@ export interface ExtendableOptions {
    * Common styling or layout patterns for your project.
    */
   patterns?: ExtendablePatterns
-  /**
-   * The css variables for your project.
-   */
-  globalVars?: ExtendableGlobalVars
-  /**
-   * The theme variants for your project.
-   */
-  themes?: ExtendableThemeVariantsMap
 }
 
 export interface ImportMapInput {
@@ -257,6 +252,19 @@ interface FileSystemOptions {
    * @default 'info'
    */
   logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent'
+  /**
+   * Show only the log types matching this pattern, at debug level.
+   *
+   * Log types are namespaced — `vite:transform`, `tokens:unresolved`, `prune:tokens`,
+   * `config` — so `'prune:*'` follows one subsystem without raising `logLevel` and
+   * un-silencing everything else.
+   *
+   * The matcher already existed and was reachable only through the `BAMBOO_DEBUG`
+   * environment variable, which put it out of reach of a checked-in config.
+   *
+   * @example 'vite:*, prune:tokens'
+   */
+  logFilter?: string
 }
 
 interface CssgenOptions {
@@ -290,121 +298,14 @@ interface CssgenOptions {
    */
   minify?: boolean
   /**
-   * Whether to drop token css variables that nothing in the generated css can reach.
-   *
-   * The token layer declares every token in the theme, and an app typically uses a small
-   * fraction of them, so this is usually the largest single saving in render-blocking css.
-   *
-   * The same walk also drops an `@property` registration for a custom property the finished
-   * stylesheet neither declares nor reads. A preset registers what its utilities compose —
-   * filters, gradients, transforms, transitions — and ships the whole set regardless of what
-   * the app draws, so an app using none of them carries all of it for nothing. Registrations
-   * declared through `globalVars` are yours and are never removed.
-   *
-   * It is opt-in because reachability cannot be proven for every reference. `token()`,
-   * `token()` and `token.value()` calls are read out of the source, as is any literal
-   * `var(--x)` written by hand — and each form is resolved through a constant or a template
-   * literal the extractor can follow, not only through a path spelled out at the call. Three
-   * things stay invisible: a token named by a path assembled from a value that only exists at
-   * runtime, one referenced only from a stylesheet outside `include`, and one used by a
-   * separate package consuming the output as design tokens. Use `staticCss` to keep those.
-   *
-   * Both forms are a risk, which is a change. `token()` used to hand javascript a literal for
-   * a plain token, so a path it could not resolve cost nothing; it now returns `var(--x)` for
-   * *every* token. Only `token.value()` returns a literal, and only for a token that has one.
-   * So a path this pass cannot read is a declaration that has to survive whichever form asked
-   * for it.
-   *
-   * A custom property declared by `globalCss` or `globalVars` is not one of these cases:
-   * the declaration ships whether or not anything in the stylesheet reads it, so whatever
-   * it references is kept alongside it.
-   *
-   * The cost of that is bluntness. Because `token()` can name any token, a project that
-   * reaches for one from javascript keeps *every* token declaration — on the default preset
-   * that is 468 names against the 68 the old, narrower exemption kept, and a token layer of
-   * 442 declarations rather than 2. It used to cover only virtual tokens, tokens carrying a
-   * condition, and the positive counterpart each negative token pins through
-   * `calc(var(--spacing-4) * -1)`.
-   *
-   * The exemption is skipped entirely for a project that never reaches for a token from
-   * javascript. The tokens artifact is generated into the project rather than installed, so
-   * the import is written in your own source and a scan of `include` finds it — a call, or an
-   * import of any module the artifact could be. That is the whole saving, and it is
-   * all-or-nothing: a project with one caller keeps every declaration.
-   *
-   * The scan reads `include`, which scopes style extraction rather than everything that may
-   * import — so a script, a config, or a sibling workspace package that calls `token()` is
-   * not covered, nor is a binding renamed away from `token`, as in `const t = token`. Both
-   * are rare and neither reports itself: the declaration goes and the call returns a `var()`
-   * nothing declares. Setting this to `false` keeps every declaration if you are in that
-   * position.
-   *
-   * Setting this to `false` keeps every token declaration, but still drops the `@property`
-   * registrations. Those are not tokens — nothing hands one to javascript and none appear
-   * in the `token()` surface — so the reachability problem above does not apply to them,
-   * and opting out of token pruning should not mean shipping a preset's whole filter and
-   * gradient set for nothing.
-   *
-   * @default true
-   */
-  pruneUnusedTokens?: boolean | 'strict'
-  /**
-   * Drop `@keyframes` rules nothing can reach.
-   *
-   * A preset declares every animation it offers and an app uses a handful, so the rest
-   * are dead weight in the stylesheet that blocks first paint. Only keyframes the theme
-   * declares are ever removed — one emitted by `globalCss` is left alone.
-   *
-   * A name is kept when any declaration in the generated css names it, and when it
-   * appears anywhere under `include`, which covers an animation assembled at runtime or
-   * applied through an inline `style` rather than through bamboo. That textual fallback
-   * is deliberately over-inclusive: keeping an unused keyframe costs bytes, dropping a
-   * used one breaks the animation.
-   *
-   * @default true
-   */
-  pruneUnusedKeyframes?: boolean
-  /**
-   * Whether to drop the parts of the reset that style elements your source never renders.
-   *
-   * Two thirds of the reset is bound to specific elements — 41 of them, covering `table`,
-   * `pre`, `kbd`, `optgroup` and the rest of the long tail. The reset is a fixed size, so it
-   * dominates a small stylesheet: a third of one sandbox's css here and four fifths of
-   * another's, of which 13% and 34% respectively is for elements those projects never render.
-   *
-   * A selector list loses only the parts naming unrendered elements, so a rule shared between
-   * `button` and `::file-selector-button` keeps the half that still applies. `html` and `body`
-   * are never removed.
-   *
-   * Off by default, and it cannot be made safe by default. Unlike the token and keyframe
-   * passes there is nothing to prove this against: an element rendered by a dependency's
-   * component, by `dangerouslySetInnerHTML`, or by markdown is invisible to a scan of your own
-   * source. What you get wrong is an element quietly losing its reset — no error, no warning.
-   * Reach for it when you control the markup and have measured that it pays.
-   *
-   * The blind spot to check first is your own entry template. The scan reads `include`, and
-   * `include` conventionally covers components rather than markup — a glob rooted at `./src`
-   * does not match `index.html`, so an element appearing only there is dropped. Add the
-   * template to `include` to cover it — the scan reads any file listed, not only ones the
-   * parser understands, and reads it from disk rather than from the build's parsed copy, so
-   * a single-file component's markup survives the transform to tsx.
-   *
-   * A scoped reset is handled: `preflight: { scope: '.app' }` writes `.app table`, and the
-   * scope is stripped before an element is read out. `bamboo cssgen preflight` prunes too.
-   *
-   * @default false
+   * What to drop from the generated stylesheet. See `PruneOptions`.
    */
-  prunePreflight?: boolean
+  prune?: PruneOptions
   /**
    * The root selector for the css variables.
    * @default ':where(:root, :host)'
    */
   cssVarRoot?: string
-  /**
-   * Whether to use `lightningcss` instead of `postcss` for css optimization.
-   * @default false
-   */
-  lightningcss?: boolean
   /**
    * Browserslist query to target specific browsers.
    * @see https://www.npmjs.com/package/browserslist
@@ -434,7 +335,7 @@ interface CodegenOptions {
    * This is useful if want to shorten the class names or css variables.
    * @default false
    */
-  hash?: boolean | { cssVar: boolean; className: boolean }
+  hash?: boolean | { cssVar?: boolean; className?: boolean }
   /**
    * Change generated typescript definitions to be more strict for property having a token or utility.
    */
@@ -459,8 +360,21 @@ interface CodegenOptions {
    */
   outExtension?: 'mjs' | 'js'
   /**
-   * Whether to force consistent type extensions for generated typescript .d.ts files.
-   * If set to `true` and `outExtension` is set to `mjs`, the generated typescript .d.ts files will have the extension `.d.mts`.
+   * Emit `.d.mts` declarations beside `.mjs`, and import them by their `.mjs` specifier.
+   *
+   * Off by default, which looks like the wrong default and is not. `moduleResolution:
+   * bundler` — Vite, Next, and most of what consumes this — resolves a directory import
+   * like `styled-system/css` by probing `index.ts`, `index.tsx`, `index.d.ts`, `index.js`.
+   * That list has no `.d.mts` in it, so turning this on makes every such import fail with
+   * `TS2307: Cannot find module`. It is for `node16`/`nodenext` consumers, who need the
+   * extensions to agree and who import by full specifier anyway.
+   *
+   * So this is a real fork in resolution behaviour rather than a flag with a correct
+   * setting, which is why it survived an attempt to delete it: making it unconditional
+   * broke every bundler-mode project in this repo.
+   *
+   * Only meaningful when `outExtension` is `mjs`.
+   *
    * @default false
    */
   forceConsistentTypeExtension?: boolean
@@ -468,46 +382,252 @@ interface CodegenOptions {
 
 interface PresetOptions {
   /**
-   * Used to create reusable config presets for your project or team.
+   * The complete list of presets, in order. Reusable across a project or team.
+   *
+   * Authoritative: what you write is what is loaded. Import `defaultPresets` to keep the
+   * defaults alongside your own.
+   *
+   * ```ts
+   * import { defaultPresets } from '@bamboocss/dev/presets'
+   * presets: [...defaultPresets, myPreset]
+   * ```
+   *
+   * Leaving it unset loads `defaultPresets`. Setting it to `[]` loads nothing — which is
+   * what the removed `eject: true` meant. Previously neither was true of a config that
+   * merely *listed* a preset: doing so kept `@bamboocss/preset-base` and silently dropped
+   * `@bamboocss/preset-bamboo`, so `presets` was neither additive nor replacing.
    */
   presets?: (string | Preset | Promise<Preset>)[]
 }
 
-export interface HooksOptions {
-  hooks?: Partial<BambooHooks>
-}
-
-export interface BambooPlugin extends HooksOptions {
+/**
+ * A named set of hooks.
+ *
+ * The name is the point. Hooks used to be registrable two ways — here, and as a bare
+ * `hooks` key on the config — with the config's own set treated as a nameless plugin
+ * appended last. That gave one mechanism two spellings and an ordering rule you had to
+ * know, while every diagnostic about a hook had a name to print for one of them and not
+ * the other. Your own hooks are now a plugin like any other, so ordering is just the order
+ * of this array.
+ */
+export interface BambooPlugin {
   name: string
+  hooks?: Partial<BambooHooks>
 }
 
 export interface PluginsOptions {
   plugins?: BambooPlugin[]
 }
 
-export interface Config
-  extends
-    ExtendableOptions,
-    CssgenOptions,
-    CodegenOptions,
-    FileSystemOptions,
-    PresetOptions,
-    HooksOptions,
-    PluginsOptions {
-  /**
-   * Whether to opt-out of the defaults config presets: [`@bamboocss/preset-base`, `@bamboocss/preset-bamboo`]
-   * @default 'false'
+/**
+ * What to drop from the generated stylesheet, and how to account for it.
+ *
+ * These were three top-level options — `pruneUnusedTokens`, `pruneUnusedKeyframes` and
+ * `prunePreflight` — which disagreed with each other on all three of naming, default and
+ * value type. Grouping them is what makes one default reading of "prune" possible.
+ */
+export interface PruneOptions {
+  /**
+   * How to decide which token css variables to keep.
+   *
+   * The token layer declares every token in the theme, and an app typically uses a small
+   * fraction of them, so this is usually the largest single saving in render-blocking css.
+   *
+   * - `off` keeps every token declaration.
+   * - `reachable` keeps what the generated css reaches. Because `token()` can name any
+   *   token, a project that calls it from javascript *anywhere* keeps every declaration —
+   *   on the default preset that is 468 names against the 68 a narrower exemption kept, and
+   *   a token layer of 442 declarations rather than 2. The exemption is skipped entirely for
+   *   a project that never reaches for a token from javascript, so the saving is
+   *   all-or-nothing: one caller keeps every declaration.
+   * - `accounted` reads the token paths out of your source and keeps only those. `token()`
+   *   and `token.value()` calls are resolved through a constant or a template literal the
+   *   extractor can follow, not only through a path spelled at the call, as is any literal
+   *   `var(--x)` written by hand.
+   *
+   * Under `accounted`, a path the build cannot follow makes the keep set fall back to
+   * `reachable`'s blanket keep rather than silently dropping a declaration — which is why
+   * `unresolvedPath` exists, and why setting it to `error` is what makes `accounted` worth
+   * asking for: it guarantees you are shipping the exact set rather than the fallback.
+   *
+   * A template literal is bounded rather than declined: `` token(`colors.${shade}`) `` cannot
+   * say which token it wants, but it says which it *cannot*, so the `colors` category is kept
+   * and nothing else. That covers the commonest dynamic read outright. What it does not cover
+   * is a path with no static head — `token(key)`, `token('colors.' + shade)` — and there
+   * `keepTokens` is the answer.
+   *
+   * Three things stay invisible to `accounted`: a token named by a path assembled from a
+   * value that only exists at runtime, one referenced only from a stylesheet outside
+   * `include`, and one used by a separate package consuming the output as design tokens. The
+   * scan reads `include`, which scopes style extraction rather than everything that may
+   * import — so a script, a config, or a sibling workspace package that calls `token()` is
+   * not covered, nor is a binding renamed away from `token`, as in `const t = token`. Name
+   * them with `keepTokens`.
+   *
+   * A custom property declared by `global.css` or `global.vars` is not one of these cases:
+   * the declaration ships whether or not anything in the stylesheet reads it, so whatever it
+   * references is kept alongside it.
+   *
+   * @default 'reachable'
+   */
+  tokens?: 'off' | 'reachable' | 'accounted'
+  /**
+   * Token paths to keep whatever the build can see, as exact names or `*` patterns.
+   *
+   * ```ts
+   * prune: { tokens: 'accounted', keepTokens: ['colors.*'] }
+   * ```
+   *
+   * This is the bound the build could not infer, written by hand. It exists because the
+   * fallback is otherwise total: **one** reference the accounting cannot follow keeps every
+   * declaration in the project, so a codebase with a single `token(key)` in it gets the same
+   * stylesheet as one that never prunes — and the codebases that reach for `token()` most are
+   * exactly the ones that end up there. Naming the category those dynamic reads land in is a
+   * far smaller answer than keeping everything, and it is the same answer the build already
+   * derives for itself from a template literal's static head.
+   *
+   * So under `accounted` this does two things: it keeps what it matches, and it stands in for
+   * what could not be followed, in place of the blanket keep. Saying `keepTokens: ['colors.*']`
+   * is saying *the reads you cannot follow land in `colors`* — an assertion about your own
+   * code, which is why nothing infers it for you. Declines are still reported, so you can see
+   * what you are covering; `unresolvedPath: 'error'` still fails, because asserting every path
+   * resolves and declaring a bound for the ones that do not are contradictory requests.
+   *
+   * Under `reachable` it is additive only, for a token nothing in the stylesheet references
+   * and no javascript here reads — one consumed by a sibling package, or by css outside
+   * `include`. It is inert under `tokens: 'off'`, which keeps everything already.
+   *
+   * Patterns match the dotted token *path*, anchored and case-sensitively, with `*` standing
+   * for any run of characters and a leading `!` excluding. `colors.*` keeps every colour,
+   * `colors.brand.*` one palette, `colors.red.300` one token, `['colors.*', '!colors.legacy.*']`
+   * every colour but one palette.
+   *
+   * The path, not the css variable: a token is `fontSizes.3xl` and its declaration is
+   * `--font-sizes-3xl`, so `font-sizes.*` — the natural thing to write after reading
+   * `styles.css` — matches nothing at all. A pattern matching no token is reported, and names
+   * the spelling that would have worked, because keeping nothing is otherwise silent in a build
+   * whose whole job here is dropping things.
+   *
+   * This replaces `staticCss` as the way to keep a category alive. `staticCss` emits utility
+   * *classes* — keeping the colours meant shipping a rule per colour to hold the declarations
+   * up, which is a larger stylesheet than the pruning saved.
+   */
+  keepTokens?: string[]
+  /**
+   * What to do about a token path `accounted` cannot follow.
+   *
+   * A path spelled at the call resolves; one assembled at runtime does not. An unfollowable
+   * path is what forces `accounted` back onto the blanket keep — unless `keepTokens` names
+   * the bound — so this decides whether that happens quietly, loudly, or not at all.
+   *
+   * - `off` falls back and says nothing.
+   * - `warn` falls back and reports what it could not follow.
+   * - `error` fails the build, so the fallback can never ship unnoticed.
+   *
+   * Inert under `tokens: 'off'` and `tokens: 'reachable'`, which run no accounting pass.
+   *
+   * `error` and `keepTokens` do not combine: one asserts every path resolves, the other
+   * declares where the ones that do not will land. A project that cannot make the first
+   * assertion wants `warn`, which still prints every reference being covered.
+   *
+   * Named for what it checks rather than `strict`, which already means something unrelated
+   * here: `strictTokens` and `strictPropertyValues` narrow generated *typescript*, and
+   * neither implies nor is implied by this.
+   *
+   * @default 'warn'
+   */
+  unresolvedPath?: 'off' | 'warn' | 'error'
+  /**
+   * Drop an `@property` registration the finished stylesheet neither declares nor reads.
+   *
+   * A preset registers what its utilities compose — filters, gradients, transforms,
+   * transitions — and ships the whole set regardless of what the app draws, so an app using
+   * none of them carries all of it for nothing.
+   *
+   * Its own flag rather than a side effect of `tokens`, which is what it used to be: the
+   * registrations were dropped even under the old `tokens: false`, so an option documented
+   * as keeping every token declaration quietly removed something else. These are not tokens
+   * — nothing hands one to javascript and none appear in the `token()` surface — so the
+   * reachability problem that makes `tokens` cautious does not apply to them.
+   *
+   * Registrations declared through `global.vars` are yours and are never removed.
+   *
+   * @default true
    */
-  eject?: boolean
+  propertyRegistrations?: boolean
   /**
-   * The validation strictness to use when validating the config.
-   * - When set to 'none', no validation will be performed.
-   * - When set to 'warn', warnings will be logged when validation fails.
-   * - When set to 'error', errors will be thrown when validation fails.
+   * Drop `@keyframes` rules nothing can reach.
+   *
+   * A preset declares every animation it offers and an app uses a handful, so the rest
+   * are dead weight in the stylesheet that blocks first paint. Only keyframes the theme
+   * declares are ever removed — one emitted by `global.css` is left alone.
+   *
+   * A name is kept when any declaration in the generated css names it, and when it
+   * appears anywhere under `include`, which covers an animation assembled at runtime or
+   * applied through an inline `style` rather than through bamboo. That textual fallback
+   * is deliberately over-inclusive: keeping an unused keyframe costs bytes, dropping a
+   * used one breaks the animation.
+   *
+   * @default true
+   */
+  keyframes?: boolean
+  /**
+   * Whether to drop the parts of the reset that style elements your source never renders.
+   *
+   * Two thirds of the reset is bound to specific elements — 41 of them, covering `table`,
+   * `pre`, `kbd`, `optgroup` and the rest of the long tail. The reset is a fixed size, so it
+   * dominates a small stylesheet: a third of one sandbox's css here and four fifths of
+   * another's, of which 13% and 34% respectively is for elements those projects never render.
+   *
+   * A selector list loses only the parts naming unrendered elements, so a rule shared between
+   * `button` and `::file-selector-button` keeps the half that still applies. `html` and `body`
+   * are never removed.
+   *
+   * Off by default, and it cannot be made safe by default. Unlike the token and keyframe
+   * passes there is nothing to prove this against: an element rendered by a dependency's
+   * component, by `dangerouslySetInnerHTML`, or by markdown is invisible to a scan of your own
+   * source. What you get wrong is an element quietly losing its reset — no error, no warning.
+   * Reach for it when you control the markup and have measured that it pays.
+   *
+   * The blind spot to check first is your own entry template. The scan reads `include`, and
+   * `include` conventionally covers components rather than markup — a glob rooted at `./src`
+   * does not match `index.html`, so an element appearing only there is dropped. Add the
+   * template to `include` to cover it — the scan reads any file listed, not only ones the
+   * parser understands, and reads it from disk rather than from the build's parsed copy, so
+   * a single-file component's markup survives the transform to tsx.
+   *
+   * A scoped reset is handled: `preflight: { scope: '.app' }` writes `.app table`, and the
+   * scope is stripped before an element is read out. `bamboo cssgen preflight` prunes too.
+   *
+   * @default false
+   */
+  preflight?: boolean
+}
+
+export interface Config
+  extends ExtendableOptions, CssgenOptions, CodegenOptions, FileSystemOptions, PresetOptions, PluginsOptions {
+  /**
+   * What to do when the config does not validate.
+   *
+   * - `off` performs no validation.
+   * - `warn` logs what failed.
+   * - `error` throws.
+   *
+   * This grades opinions about a config that still builds. Two checks are not that, run
+   * ahead of it, and answer to nothing here: a retired token spelling, which is output that
+   * is already broken; and an option that has been removed, which is proof the config
+   * predates the version reading it. Both throw at any setting, including `off`.
+   *
+   * A removed option throws rather than warns because a warning is not a signal anything
+   * acts on. Removals ship in minor versions, so a warning is what an automated dependency
+   * upgrade merges without a person reading it — while the option itself is silent in every
+   * other way, reverting to the default and taking the assertion it asked for with it. An
+   * unknown key is a different case and still tolerated: it may be forward-compatible, a
+   * setting for a version not installed yet. A *removed* key can only be backward.
    *
    * @default 'warn'
    */
-  validation?: 'none' | 'warn' | 'error'
+  validation?: 'off' | 'warn' | 'error'
 }
 
 export interface Preset extends ExtendableOptions, PresetOptions {
@@ -556,8 +676,10 @@ export interface PrefixOptions {
 type ReqConf = Required<UserConfig>
 
 export type ConfigPath = Exclude<
-  | Exclude<NonNullable<Keys<ReqConf>>, 'theme'>
+  | Exclude<NonNullable<Keys<ReqConf>>, 'theme' | 'global' | 'prune'>
   | PathIn<ReqConf, 'theme'>
+  | PathIn<ReqConf, 'global'>
+  | PathIn<ReqConf, 'prune'>
   | PathIn<ReqConf, 'patterns'>
   | PathIn<ReqConf, 'staticCss'>
   | (string & {}),

package/dist/index.d.ts

@@ -6,7 +6,6 @@ export type * from './hooks'
 export type * from './hooks-api'
 export type * from './logger'
 export type * from './parser'
-export type * from './parts'
 export type * from './pattern'
 export type * from './recipe'
 export type * from './reporter'

package/dist/logger.d.ts

@@ -8,6 +8,11 @@ export interface LogEntry {
 
 export interface LoggerInterface {
   level: 'debug' | 'info' | 'warn' | 'error' | 'silent'
+  /**
+   * Comma-separated globs over the namespaced log type. Non-empty shows only matching types,
+   * at debug level, whatever `level` is set to.
+   */
+  filter: string
   print(data: any): void
   onLog?: (entry: LogEntry) => void
   warn: (type: string, data: any) => void

package/dist/pattern.d.ts

@@ -12,6 +12,14 @@ export type PatternProperty =
 
 export interface PatternHelpers {
   map: (value: any, fn: (value: string) => string | undefined) => any
+  /**
+   * The css variable reference for a token path, or `fallback` when the path names no token.
+   *
+   * `token('spacing.4', '4')` is `var(--spacing-4)` where that token exists and `'4'` where it
+   * does not — so a pattern can accept either a token name or a raw css value without knowing
+   * the theme.
+   */
+  token: (path: string, fallback?: string) => string | undefined
   isCssUnit: (value: any) => boolean
   isCssVar: (value: any) => boolean
   isCssFunction: (value: any) => boolean
@@ -49,13 +57,21 @@ export interface PatternConfig<T extends PatternProperties = PatternProperties>
    */
   deprecated?: boolean | string
   /**
-   * Whether to only generate types for the specified properties.
-   * This will disallow css properties
-   */
-  strict?: boolean
-  /**
-   * @experimental
-   * Disallow certain css properties for this pattern
+   * Which css properties this pattern accepts alongside its own `properties`.
+   *
+   * - `all` accepts any css property.
+   * - `none` accepts only the pattern's declared `properties`.
+   * - `{ except }` accepts any css property but the ones listed.
+   *
+   * One option because these were two — `strict: true` for "none" and an `@experimental`
+   * `blocklist` for "all but these" — and the pair had an unrepresentable combination that
+   * silently did nothing: the blocklist is applied only to the type that lists css
+   * properties, which `strict: true` does not emit, so setting both dropped the blocklist.
+   *
+   * Types only. Nothing strips a blocked property at runtime — one passed anyway reaches
+   * `transform` and emits css.
+   *
+   * @default 'all'
    */
-  blocklist?: LiteralUnion<CssProperty>[]
+  cssProps?: 'all' | 'none' | { except: LiteralUnion<CssProperty>[] }
 }

package/dist/recipe.d.ts

@@ -38,7 +38,7 @@ type RecipeVariantMap<T extends RecipeVariantRecord> = {
 
 export interface RecipeRuntimeFn<T extends RecipeVariantRecord> extends RecipeVariantFn<T> {
   __type: RecipeSelection<T>
-  variantKeys: (keyof T)[]
+  /** Each variant and the values it accepts. `Object.keys` it for the variant names. */
   variantMap: RecipeVariantMap<T>
   raw: (props?: RecipeSelection<T>) => SystemStyleObject
   config: RecipeConfig<T>
@@ -138,7 +138,7 @@ export interface SlotRecipeRuntimeFn<
   T extends SlotRecipeVariantRecord<S>,
 > extends SlotRecipeVariantFn<S, T> {
   raw: (props?: RecipeSelection<T>) => Record<S, SystemStyleObject>
-  variantKeys: (keyof T)[]
+  /** Each variant and the values it accepts. `Object.keys` it for the variant names. */
   variantMap: RecipeVariantMap<T>
   /** The config this recipe was created from. */
   config: SlotRecipeDefinition<S, T>

package/dist/spec.d.ts

@@ -5,9 +5,7 @@ export type SpecType =
   | 'conditions'
   | 'keyframes'
   | 'semantic-tokens'
-  | 'text-styles'
-  | 'layer-styles'
-  | 'animation-styles'
+  | 'mixins'
   | 'color-palette'
   | 'themes'
 
@@ -103,34 +101,14 @@ export interface KeyframeSpec {
   data: KeyframeSpecDefinition[]
 }
 
-export interface TextStyleSpecDefinition extends Examples {
+export interface MixinSpecDefinition extends Examples {
   name: string
   description?: string
 }
 
-export interface TextStyleSpec {
-  type: 'text-styles'
-  data: TextStyleSpecDefinition[]
-}
-
-export interface LayerStyleSpecDefinition extends Examples {
-  name: string
-  description?: string
-}
-
-export interface LayerStyleSpec {
-  type: 'layer-styles'
-  data: LayerStyleSpecDefinition[]
-}
-
-export interface AnimationStyleSpecDefinition extends Examples {
-  name: string
-  description?: string
-}
-
-export interface AnimationStyleSpec {
-  type: 'animation-styles'
-  data: AnimationStyleSpecDefinition[]
+export interface MixinSpec {
+  type: 'mixins'
+  data: MixinSpecDefinition[]
 }
 
 export interface ColorPaletteSpec {
@@ -173,9 +151,7 @@ export type SpecFile =
   | PatternSpec
   | ConditionSpec
   | KeyframeSpec
-  | TextStyleSpec
-  | LayerStyleSpec
-  | AnimationStyleSpec
+  | MixinSpec
   | ColorPaletteSpec
   | ThemesSpec
 
@@ -186,9 +162,7 @@ export interface SpecTypeMap {
   patterns: PatternSpec
   conditions: ConditionSpec
   keyframes: KeyframeSpec
-  'text-styles': TextStyleSpec
-  'layer-styles': LayerStyleSpec
-  'animation-styles': AnimationStyleSpec
+  mixins: MixinSpec
   'color-palette': ColorPaletteSpec
   themes: ThemesSpec
 }

package/dist/style-props.d.ts

@@ -1,5 +1,5 @@
 import type { ConditionalValue } from './conditions'
-import type { PropertiesFallback } from './csstype'
+import type { Properties } from './csstype'
 import type { PropertyValue } from './prop-type'
 
 type String = string & {}
@@ -9,7 +9,7 @@ type Number = number & {}
  * Shadowed export (in CLI): DO NOT REMOVE
  * -----------------------------------------------------------------------------*/
 
-type CssProperties = PropertiesFallback<String | Number>
+type CssProperties = Properties<String | Number>
 
 export type CssVarProperties = {
   [key in `--${string}`]?: ConditionalValue<string | number>

package/dist/system-types.d.ts

@@ -1,5 +1,5 @@
 import type { ConditionalValue, Nested } from './conditions'
-import type { AtRule, Globals, PropertiesFallback } from './csstype'
+import type { AtRule, Globals, Properties } from './csstype'
 import type { SystemProperties, CssVarProperties } from './style-props'
 
 type String = string & {}
@@ -63,9 +63,9 @@ export interface ModernCssProperties {
     | String
 }
 
-export type CssProperty = keyof PropertiesFallback
+export type CssProperty = keyof Properties
 
-export interface CssProperties extends PropertiesFallback<String | Number>, CssVarProperties, ModernCssProperties {}
+export interface CssProperties extends Properties<String | Number>, CssVarProperties, ModernCssProperties {}
 
 export interface CssKeyframes {
   [name: string]: {

package/dist/theme.d.ts

@@ -1,4 +1,4 @@
-import type { AnimationStyles, LayerStyles, TextStyles } from './composition'
+import type { Mixins } from './composition'
 import type { RecipeConfig, SlotRecipeConfig } from './recipe'
 import type { CssKeyframes } from './system-types'
 import type { SemanticTokens, Tokens } from './tokens'
@@ -39,17 +39,9 @@ export interface Theme {
    */
   semanticTokens?: SemanticTokens
   /**
-   * The typography styles for your project.
+   * Named bundles of declarations, applied by name through the `mixin` style property.
    */
-  textStyles?: TextStyles
-  /**
-   * The layer styles for your project.
-   */
-  layerStyles?: LayerStyles
-  /**
-   * The animation styles for your project.
-   */
-  animationStyles?: AnimationStyles
+  mixins?: Mixins
   /**
    * Multi-variant style definitions for your project.
    * Useful for defining component styles.
@@ -71,9 +63,28 @@ export interface Theme {
    * The color palette configuration for your project.
    */
   colorPalette?: ColorPaletteOptions
+  /**
+   * Alternate token sets, selectable at runtime.
+   *
+   * Was a top-level `themes`, one character from `theme` and impossible for TypeScript to
+   * tell apart — both spellings were valid keys, so the typo resolved to a different
+   * feature rather than to an error. A variant is part of the theme, so it lives in it.
+   */
+  variants?: ThemeVariantsMap
 }
 
-interface PartialTheme extends Omit<Theme, 'recipes' | 'slotRecipes'> {
+export interface ThemeVariant extends Pick<Theme, 'tokens' | 'semanticTokens'> {}
+
+export interface ThemeVariantsMap {
+  [name: string]: ThemeVariant
+}
+
+interface ExtendableThemeVariantsMap {
+  [name: string]: ThemeVariantsMap | ThemeVariant | undefined
+  extend?: ThemeVariantsMap | undefined
+}
+
+interface PartialTheme extends Omit<Theme, 'recipes' | 'slotRecipes' | 'variants'> {
   /**
    * Multi-variant style definitions for your project.
    * Useful for defining component styles.
@@ -87,8 +98,13 @@ interface PartialTheme extends Omit<Theme, 'recipes' | 'slotRecipes'> {
    * The color palette configuration for your project.
    */
   colorPalette?: Partial<ColorPaletteOptions>
+  /**
+   * Alternate token sets, selectable at runtime.
+   */
+  variants?: ExtendableThemeVariantsMap
 }
 
-export interface ExtendableTheme extends Theme {
+export interface ExtendableTheme extends Omit<Theme, 'variants'> {
+  variants?: ExtendableThemeVariantsMap
   extend?: PartialTheme | undefined
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bamboocss/types",
-  "version": "1.30.1",
+  "version": "1.32.0",
   "description": "The types for css bamboo",
   "homepage": "https://bamboocss.com",
   "license": "MIT",
@@ -32,7 +32,7 @@
     "ncp": "2.0.0",
     "pkg-types": "2.3.0",
     "ts-morph": "28.0.0",
-    "@bamboocss/extractor": "1.30.1"
+    "@bamboocss/extractor": "1.32.0"
   },
   "scripts": {
     "dev": "tsx scripts/watch.ts",

package/dist/parts.d.ts

@@ -1,7 +0,0 @@
-export interface Part {
-  selector: string
-}
-
-export interface Parts {
-  [key: string]: Part
-}