@tachui/core 0.7.0-alpha1

package/src/modifiers/builder.ts

@@ -0,0 +1,1747 @@
+/**
+ * Modifier Builder Implementation
+ *
+ * Provides a fluent API for chaining modifiers on components,
+ * similar to SwiftUI's modifier system.
+ */
+
+import type { Signal } from '../reactive/types'
+import type { ComponentInstance, ComponentProps } from '../runtime/types'
+import type { StatefulBackgroundValue } from '../gradients/types'
+import type { ColorValue, TextShadowConfig } from './types'
+import type { FontAsset } from '../assets/FontAsset'
+import {
+  AnimationModifier,
+  AppearanceModifier,
+  InteractionModifier,
+  LayoutModifier,
+  LifecycleModifier,
+  ResizableModifier,
+} from './base'
+import { BackgroundModifier } from './background'
+import type { BorderStyle } from './border'
+import { borderBottom, borderLeft, borderRight, borderTop } from './border'
+import { css, cssProperty, cssVariable } from './css'
+import { alignItems, flexDirection, flexGrow, flexShrink, flexWrap, gap, justifyContent } from './flexbox'
+import { margin, marginBottom, marginHorizontal, marginLeft, marginRight, marginTop, marginVertical } from './margin'
+import {
+  padding,
+  paddingBottom,
+  paddingHorizontal,
+  paddingLeading,
+  paddingLeft,
+  paddingRight,
+  paddingTop,
+  paddingTrailing,
+  paddingVertical,
+} from './padding'
+// Import new multi-property modifiers
+import { height, maxHeight, maxWidth, minHeight, minWidth, size, width } from './size'
+import type {
+  AnimationModifierProps,
+  AppearanceModifierProps,
+  LayoutModifierProps,
+  ModifiableComponent,
+  Modifier,
+  ModifierBuilder,
+} from './types'
+import type { ResponsiveModifierBuilder, ResponsiveBreakpointBuilder } from './responsive/responsive-builder'
+import { ResponsiveModifierBuilderImpl } from './responsive/responsive-builder'
+import type { ResponsiveStyleConfig } from './responsive/types'
+import { createResponsiveModifier } from './responsive/responsive-modifier'
+import { createModifiableComponent } from './registry'
+import type {
+  FontStyle,
+  FontVariant,
+  FontWeight,
+  TextAlign,
+  TextDecoration,
+  TextTransform,
+} from './typography'
+import {
+  letterSpacing,
+  lineHeight,
+  overflow,
+  textAlign,
+  textDecoration,
+  textOverflow,
+  textTransform,
+  typography,
+  whiteSpace,
+} from './typography'
+import { cursor, display, overflowX, overflowY, position, zIndex } from './utility'
+import { 
+  IdModifier, 
+  DataModifier, 
+  AriaModifier, 
+  TabIndexModifier 
+} from './attributes'
+import {
+  LineClampModifier,
+  WordBreakModifier,
+  OverflowWrapModifier,
+  HyphensModifier,
+  BackgroundClipModifier
+} from './text'
+import {
+  BackdropFilterModifier
+} from './backdrop'
+import {
+  before as beforeModifier,
+  after as afterModifier
+} from './elements'
+import {
+  FilterModifier,
+  filter,
+  saturate,
+  // grayscale, // Unused - commented out to fix type-check
+  sepia,
+  hueRotate,
+  invert,
+  vintagePhoto,
+  blackAndWhite,
+  vibrant,
+  warmTone,
+  coolTone,
+  faded,
+  highKey,
+  lowKey,
+  softFocus,
+  highContrastMode,
+  subtleBlur,
+  darkModeInvert
+} from './filters'
+import {
+  textShadow,
+  shadow as shadowModifier,
+  shadows as shadowsModifier,
+  shadowPreset
+} from './shadows'
+import {
+  scale,
+  rotate,
+  translate,
+  perspective
+  // transform // Unused - commented out to fix type-check
+} from './transformations'
+import {
+  // cursor as cursorModifier, // Unused - commented out to fix type-check
+  hover as hoverModifier,
+  hoverEffect,
+  hoverWithTransition,
+  conditionalHover,
+  interactiveCursor,
+  draggableCursor,
+  textCursor,
+  disabledCursor,
+  loadingCursor,
+  helpCursor,
+  zoomCursor,
+  buttonHover,
+  cardHover,
+  linkHover,
+  imageHover
+} from './effects'
+import {
+  transition as transitionModifier,
+  transitions,
+  fadeTransition,
+  transformTransition,
+  colorTransition,
+  layoutTransition,
+  buttonTransition,
+  cardTransition,
+  modalTransition,
+  smoothTransition,
+  quickTransition,
+  slowTransition
+} from './transitions'
+import {
+  scroll as scrollModifier,
+  scrollBehavior,
+  overscrollBehavior,
+  overscrollBehaviorX,
+  overscrollBehaviorY,
+  scrollMargin,
+  scrollPadding,
+  scrollSnap
+} from './scroll'
+import { asHTML } from './as-html'
+import type { AsHTMLOptions } from './as-html'
+
+/**
+ * Concrete modifier builder implementation
+ */
+export class ModifierBuilderImpl<T extends ComponentInstance = ComponentInstance>
+  implements ModifierBuilder<T>
+{
+  private modifiers: Modifier[] = []
+
+  constructor(private component: T) {}
+
+  // Layout modifiers
+  frame(width?: number | string, height?: number | string): ModifierBuilder<T>
+  frame(options: LayoutModifierProps['frame']): ModifierBuilder<T>
+  frame(
+    widthOrOptions?: number | string | LayoutModifierProps['frame'],
+    height?: number | string
+  ): ModifierBuilder<T> {
+    let frameProps: LayoutModifierProps['frame']
+
+    if (typeof widthOrOptions === 'object') {
+      frameProps = widthOrOptions
+    } else {
+      frameProps = {}
+      if (widthOrOptions !== undefined) frameProps.width = widthOrOptions
+      if (height !== undefined) frameProps.height = height
+    }
+
+    this.modifiers.push(new LayoutModifier({ frame: frameProps }))
+    return this
+  }
+
+  // Padding is now handled by the new padding modifiers below
+
+  margin(value: number | string): ModifierBuilder<T>
+  margin(options: LayoutModifierProps['margin']): ModifierBuilder<T>
+  margin(valueOrOptions: number | string | LayoutModifierProps['margin']): ModifierBuilder<T> {
+    if (typeof valueOrOptions === 'number' || typeof valueOrOptions === 'string') {
+      this.modifiers.push(margin(valueOrOptions))
+    } else {
+      // Handle both LayoutModifierProps margin format and direct MarginOptions format
+      const marginOptions = valueOrOptions as any
+      
+      // Check if it's using vertical/horizontal pattern
+      if (marginOptions.vertical !== undefined || marginOptions.horizontal !== undefined) {
+        this.modifiers.push(margin({
+          vertical: marginOptions.vertical,
+          horizontal: marginOptions.horizontal
+        }))
+      } else if (marginOptions.top !== undefined || marginOptions.right !== undefined || 
+                 marginOptions.bottom !== undefined || marginOptions.left !== undefined) {
+        // Handle individual sides
+        this.modifiers.push(margin({
+          top: marginOptions.top,
+          right: marginOptions.right,
+          bottom: marginOptions.bottom,
+          left: marginOptions.left
+        }))
+      }
+    }
+    return this
+  }
+
+  layoutPriority(priority: number | Signal<number>): ModifierBuilder<T> {
+    this.modifiers.push(new LayoutModifier({ layoutPriority: priority }))
+    return this
+  }
+
+  // New multi-property modifiers
+  size(options: {
+    width?: number | string
+    height?: number | string
+    minWidth?: number | string
+    maxWidth?: number | string
+    minHeight?: number | string
+    maxHeight?: number | string
+  }): ModifierBuilder<T> {
+    this.modifiers.push(size(options))
+    return this
+  }
+
+  width(value: number | string): ModifierBuilder<T> {
+    this.modifiers.push(width(value))
+    return this
+  }
+
+  height(value: number | string): ModifierBuilder<T> {
+    this.modifiers.push(height(value))
+    return this
+  }
+
+  maxWidth(value: number | string): ModifierBuilder<T> {
+    this.modifiers.push(maxWidth(value))
+    return this
+  }
+
+  minWidth(value: number | string): ModifierBuilder<T> {
+    this.modifiers.push(minWidth(value))
+    return this
+  }
+
+  maxHeight(value: number | string): ModifierBuilder<T> {
+    this.modifiers.push(maxHeight(value))
+    return this
+  }
+
+  minHeight(value: number | string): ModifierBuilder<T> {
+    this.modifiers.push(minHeight(value))
+    return this
+  }
+
+  marginTop(value: number): ModifierBuilder<T> {
+    this.modifiers.push(marginTop(value))
+    return this
+  }
+
+  marginBottom(value: number): ModifierBuilder<T> {
+    this.modifiers.push(marginBottom(value))
+    return this
+  }
+
+  marginHorizontal(value: number): ModifierBuilder<T> {
+    this.modifiers.push(marginHorizontal(value))
+    return this
+  }
+
+  marginVertical(value: number): ModifierBuilder<T> {
+    this.modifiers.push(marginVertical(value))
+    return this
+  }
+
+  marginLeft(value: number): ModifierBuilder<T> {
+    this.modifiers.push(marginLeft(value))
+    return this
+  }
+
+  marginRight(value: number): ModifierBuilder<T> {
+    this.modifiers.push(marginRight(value))
+    return this
+  }
+
+  // Padding modifiers
+  padding(value: number): ModifierBuilder<T>
+  padding(options: any): ModifierBuilder<T>
+  padding(valueOrOptions: number | any): ModifierBuilder<T> {
+    if (typeof valueOrOptions === 'number') {
+      this.modifiers.push(padding(valueOrOptions))
+    } else {
+      this.modifiers.push(padding(valueOrOptions as any))
+    }
+    return this
+  }
+
+  paddingTop(value: number): ModifierBuilder<T> {
+    this.modifiers.push(paddingTop(value))
+    return this
+  }
+
+  paddingBottom(value: number): ModifierBuilder<T> {
+    this.modifiers.push(paddingBottom(value))
+    return this
+  }
+
+  paddingLeft(value: number): ModifierBuilder<T> {
+    this.modifiers.push(paddingLeft(value))
+    return this
+  }
+
+  paddingRight(value: number): ModifierBuilder<T> {
+    this.modifiers.push(paddingRight(value))
+    return this
+  }
+
+  paddingLeading(value: number): ModifierBuilder<T> {
+    this.modifiers.push(paddingLeading(value))
+    return this
+  }
+
+  paddingTrailing(value: number): ModifierBuilder<T> {
+    this.modifiers.push(paddingTrailing(value))
+    return this
+  }
+
+  paddingHorizontal(value: number): ModifierBuilder<T> {
+    this.modifiers.push(paddingHorizontal(value))
+    return this
+  }
+
+  paddingVertical(value: number): ModifierBuilder<T> {
+    this.modifiers.push(paddingVertical(value))
+    return this
+  }
+
+  // Typography modifiers
+  typography(options: {
+    size?: number | string
+    weight?: FontWeight
+    family?: string
+    lineHeight?: number | string
+    letterSpacing?: number | string
+    align?: TextAlign
+    transform?: TextTransform
+    decoration?: TextDecoration
+    variant?: FontVariant
+    style?: FontStyle
+    color?: string
+  }): ModifierBuilder<T> {
+    this.modifiers.push(typography(options))
+    return this
+  }
+
+  textAlign(value: 'left' | 'center' | 'right' | 'justify' | 'start' | 'end'): ModifierBuilder<T> {
+    this.modifiers.push(textAlign(value))
+    return this
+  }
+
+  textTransform(value: 'none' | 'uppercase' | 'lowercase' | 'capitalize'): ModifierBuilder<T> {
+    this.modifiers.push(textTransform(value))
+    return this
+  }
+
+  letterSpacing(value: number | string): ModifierBuilder<T> {
+    this.modifiers.push(letterSpacing(value))
+    return this
+  }
+
+  lineHeight(value: number | string): ModifierBuilder<T> {
+    this.modifiers.push(lineHeight(value))
+    return this
+  }
+
+  textOverflow(value: 'clip' | 'ellipsis' | 'fade' | string): ModifierBuilder<T> {
+    this.modifiers.push(textOverflow(value))
+    return this
+  }
+
+  whiteSpace(
+    value: 'normal' | 'nowrap' | 'pre' | 'pre-wrap' | 'pre-line' | 'break-spaces'
+  ): ModifierBuilder<T> {
+    this.modifiers.push(whiteSpace(value))
+    return this
+  }
+
+  overflow(value: 'visible' | 'hidden' | 'scroll' | 'auto'): ModifierBuilder<T> {
+    this.modifiers.push(overflow(value))
+    return this
+  }
+
+  // Border modifiers
+  borderTop(
+    width: number | Signal<number>,
+    color: string | Signal<string>,
+    style?: BorderStyle
+  ): ModifierBuilder<T> {
+    this.modifiers.push(borderTop(width, color, style))
+    return this
+  }
+
+  borderRight(
+    width: number | Signal<number>,
+    color: string | Signal<string>,
+    style?: BorderStyle
+  ): ModifierBuilder<T> {
+    this.modifiers.push(borderRight(width, color, style))
+    return this
+  }
+
+  borderBottom(
+    width: number | Signal<number>,
+    color: string | Signal<string>,
+    style?: BorderStyle
+  ): ModifierBuilder<T> {
+    this.modifiers.push(borderBottom(width, color, style))
+    return this
+  }
+
+  borderLeft(
+    width: number | Signal<number>,
+    color: string | Signal<string>,
+    style?: BorderStyle
+  ): ModifierBuilder<T> {
+    this.modifiers.push(borderLeft(width, color, style))
+    return this
+  }
+
+  // Flexbox modifiers
+
+  flexGrow(value: number): ModifierBuilder<T> {
+    this.modifiers.push(flexGrow(value))
+    return this
+  }
+
+  flexShrink(value: number): ModifierBuilder<T> {
+    this.modifiers.push(flexShrink(value))
+    return this
+  }
+
+  justifyContent(
+    value: 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly'
+  ): ModifierBuilder<T> {
+    this.modifiers.push(justifyContent(value))
+    return this
+  }
+
+  alignItems(
+    value: 'flex-start' | 'flex-end' | 'center' | 'stretch' | 'baseline'
+  ): ModifierBuilder<T> {
+    this.modifiers.push(alignItems(value))
+    return this
+  }
+
+  gap(value: number | string): ModifierBuilder<T> {
+    this.modifiers.push(gap(value))
+    return this
+  }
+
+  flexDirection(value: 'row' | 'row-reverse' | 'column' | 'column-reverse'): ModifierBuilder<T> {
+    this.modifiers.push(flexDirection(value))
+    return this
+  }
+
+  flexWrap(value: 'nowrap' | 'wrap' | 'wrap-reverse'): ModifierBuilder<T> {
+    this.modifiers.push(flexWrap(value))
+    return this
+  }
+
+  // Utility modifiers
+  cursor(
+    value:
+      | 'auto'
+      | 'default'
+      | 'pointer'
+      | 'text'
+      | 'wait'
+      | 'help'
+      | 'not-allowed'
+      | 'grab'
+      | 'grabbing'
+  ): ModifierBuilder<T> {
+    this.modifiers.push(cursor(value))
+    return this
+  }
+
+  overflowY(value: 'visible' | 'hidden' | 'scroll' | 'auto'): ModifierBuilder<T> {
+    this.modifiers.push(overflowY(value))
+    return this
+  }
+
+  overflowX(value: 'visible' | 'hidden' | 'scroll' | 'auto'): ModifierBuilder<T> {
+    this.modifiers.push(overflowX(value))
+    return this
+  }
+
+  position(value: 'static' | 'relative' | 'absolute' | 'fixed' | 'sticky'): ModifierBuilder<T> {
+    this.modifiers.push(position(value))
+    return this
+  }
+
+  zIndex(value: number): ModifierBuilder<T> {
+    this.modifiers.push(zIndex(value))
+    return this
+  }
+
+  display(
+    value: 'block' | 'inline' | 'inline-block' | 'flex' | 'inline-flex' | 'grid' | 'none'
+  ): ModifierBuilder<T> {
+    this.modifiers.push(display(value))
+    return this
+  }
+
+  // Raw CSS modifiers
+  css(properties: { [property: string]: string | number | undefined }): ModifierBuilder<T> {
+    this.modifiers.push(css(properties))
+    return this
+  }
+
+  cssProperty(property: string, value: string | number): ModifierBuilder<T> {
+    this.modifiers.push(cssProperty(property, value))
+    return this
+  }
+
+  cssVariable(name: string, value: string | number): ModifierBuilder<T> {
+    this.modifiers.push(cssVariable(name, value))
+    return this
+  }
+
+  textCase(value: 'none' | 'uppercase' | 'lowercase' | 'capitalize'): ModifierBuilder<T> {
+    this.modifiers.push(textTransform(value))
+    return this
+  }
+
+  textDecoration(value: 'none' | 'underline' | 'overline' | 'line-through'): ModifierBuilder<T> {
+    this.modifiers.push(textDecoration(value))
+    return this
+  }
+
+  // Phase 1 SwiftUI modifiers
+  offset(x: number | Signal<number>, y?: number | Signal<number>): ModifierBuilder<T> {
+    this.modifiers.push(
+      new LayoutModifier({
+        offset: {
+          x: typeof x === 'number' ? x : x,
+          y: typeof y === 'number' ? (y ?? 0) : (y ?? 0),
+        },
+      })
+    )
+    return this
+  }
+
+  clipped(): ModifierBuilder<T> {
+    this.modifiers.push(new AppearanceModifier({ clipped: true }))
+    return this
+  }
+
+  rotationEffect(
+    angle: number | Signal<number>,
+    anchor:
+      | 'center'
+      | 'top'
+      | 'topLeading'
+      | 'topTrailing'
+      | 'bottom'
+      | 'bottomLeading'
+      | 'bottomTrailing'
+      | 'leading'
+      | 'trailing' = 'center'
+  ): ModifierBuilder<T> {
+    this.modifiers.push(
+      new AnimationModifier({
+        rotationEffect: {
+          angle: typeof angle === 'number' ? angle : angle,
+          anchor,
+        },
+      })
+    )
+    return this
+  }
+
+  // Phase 2 SwiftUI modifiers
+  aspectRatio(
+    ratio?: number | Signal<number>,
+    contentMode: 'fit' | 'fill' = 'fit'
+  ): ModifierBuilder<T> {
+    this.modifiers.push(
+      new LayoutModifier({
+        aspectRatio: {
+          ratio: typeof ratio === 'number' ? ratio : ratio,
+          contentMode,
+        },
+      })
+    )
+    return this
+  }
+
+  fixedSize(horizontal: boolean = true, vertical: boolean = true): ModifierBuilder<T> {
+    this.modifiers.push(
+      new LayoutModifier({
+        fixedSize: {
+          horizontal,
+          vertical,
+        },
+      })
+    )
+    return this
+  }
+
+  clipShape(
+    shape: 'circle' | 'ellipse' | 'rect' | 'polygon',
+    parameters?: Record<string, any>
+  ): ModifierBuilder<T> {
+    this.modifiers.push(
+      new AppearanceModifier({
+        clipShape: {
+          shape,
+          parameters: parameters || {},
+        },
+      })
+    )
+    return this
+  }
+
+  overlay(
+    content: any,
+    alignment:
+      | 'center'
+      | 'top'
+      | 'bottom'
+      | 'leading'
+      | 'trailing'
+      | 'topLeading'
+      | 'topTrailing'
+      | 'bottomLeading'
+      | 'bottomTrailing' = 'center'
+  ): ModifierBuilder<T> {
+    this.modifiers.push(
+      new AnimationModifier({
+        overlay: {
+          content,
+          alignment,
+        },
+      })
+    )
+    return this
+  }
+
+  // Phase 3 SwiftUI modifiers - Critical Transform Modifiers
+  scaleEffect(
+    x: number | Signal<number>,
+    y?: number | Signal<number>,
+    anchor:
+      | 'center'
+      | 'top'
+      | 'topLeading'
+      | 'topTrailing'
+      | 'bottom'
+      | 'bottomLeading'
+      | 'bottomTrailing'
+      | 'leading'
+      | 'trailing' = 'center'
+  ): ModifierBuilder<T> {
+    this.modifiers.push(
+      new LayoutModifier({
+        scaleEffect: {
+          x,
+          y,
+          anchor,
+        },
+      })
+    )
+    return this
+  }
+
+  absolutePosition(x: number | Signal<number>, y: number | Signal<number>): ModifierBuilder<T> {
+    this.modifiers.push(
+      new LayoutModifier({
+        position: {
+          x,
+          y,
+        },
+      })
+    )
+    return this
+  }
+
+  // Appearance modifiers
+  foregroundColor(color: ColorValue): ModifierBuilder<T> {
+    this.modifiers.push(new AppearanceModifier({ foregroundColor: color }))
+    return this
+  }
+
+  backgroundColor(color: ColorValue): ModifierBuilder<T> {
+    this.modifiers.push(new AppearanceModifier({ backgroundColor: color }))
+    return this
+  }
+
+  background(value: StatefulBackgroundValue | Signal<string>): ModifierBuilder<T> {
+    this.modifiers.push(new BackgroundModifier({ background: value as StatefulBackgroundValue }))
+    return this
+  }
+
+  font(options: AppearanceModifierProps['font']): ModifierBuilder<T>
+  font(size: number | string): ModifierBuilder<T>
+  font(sizeOrOptions: number | string | AppearanceModifierProps['font']): ModifierBuilder<T> {
+    let fontProps: AppearanceModifierProps['font']
+
+    if (typeof sizeOrOptions === 'object') {
+      fontProps = sizeOrOptions
+    } else {
+      fontProps = sizeOrOptions !== undefined ? { size: sizeOrOptions } : {}
+    }
+
+    this.modifiers.push(new AppearanceModifier({ font: fontProps }))
+    return this
+  }
+
+  fontWeight(weight: NonNullable<AppearanceModifierProps['font']>['weight']): ModifierBuilder<T> {
+    this.modifiers.push(new AppearanceModifier({ font: { weight } }))
+    return this
+  }
+
+  fontSize(size: number | string | Signal<number> | Signal<string>): ModifierBuilder<T> {
+    this.modifiers.push(new AppearanceModifier({ font: { size } }))
+    return this
+  }
+
+  fontFamily(family: string | FontAsset | Signal<string | FontAsset>): ModifierBuilder<T> {
+    this.modifiers.push(new AppearanceModifier({ font: { family } }))
+    return this
+  }
+
+  opacity(value: number | Signal<number>): ModifierBuilder<T> {
+    this.modifiers.push(new AppearanceModifier({ opacity: value }))
+    return this
+  }
+
+  cornerRadius(radius: number | Signal<number>): ModifierBuilder<T> {
+    this.modifiers.push(new AppearanceModifier({ cornerRadius: radius }))
+    return this
+  }
+
+  border(width: number | Signal<number>, color?: ColorValue): ModifierBuilder<T>
+  border(options: AppearanceModifierProps['border']): ModifierBuilder<T>
+  border(
+    widthOrOptions: number | Signal<number> | AppearanceModifierProps['border'],
+    color?: ColorValue
+  ): ModifierBuilder<T> {
+    let borderProps: AppearanceModifierProps['border']
+
+    if (typeof widthOrOptions === 'object') {
+      borderProps = widthOrOptions
+    } else {
+      borderProps = {
+        style: 'solid',
+        ...(widthOrOptions !== undefined && { width: widthOrOptions }),
+        ...(color !== undefined && { color }),
+      }
+    }
+
+    this.modifiers.push(new AppearanceModifier({ border: borderProps }))
+    return this
+  }
+
+  borderWidth(width: number | Signal<number>): ModifierBuilder<T> {
+    this.modifiers.push(new AppearanceModifier({ border: { width } }))
+    return this
+  }
+
+  shadow(options: AppearanceModifierProps['shadow']): ModifierBuilder<T>
+  shadow(config: { x: number; y: number; blur: number; color: string; spread?: number; inset?: boolean }): ModifierBuilder<T>
+  shadow(optionsOrConfig: AppearanceModifierProps['shadow'] | { x: number; y: number; blur: number; color: string; spread?: number; inset?: boolean }): ModifierBuilder<T> {
+    // Check if it's the new ShadowConfig format (has x, y, blur properties)
+    if (optionsOrConfig && typeof optionsOrConfig === 'object' && 'x' in optionsOrConfig && 'y' in optionsOrConfig && 'blur' in optionsOrConfig) {
+      this.modifiers.push(shadowModifier(optionsOrConfig as any))
+    } else {
+      // Use the old AppearanceModifier format
+      this.modifiers.push(new AppearanceModifier({ shadow: optionsOrConfig as AppearanceModifierProps['shadow'] }))
+    }
+    return this
+  }
+
+  textShadow(config: TextShadowConfig): ModifierBuilder<T> {
+    this.modifiers.push(textShadow(config))
+    return this
+  }
+
+  // Additional shadow methods
+  shadows(configs: Array<{ x: number; y: number; blur: number; color: string; spread?: number; inset?: boolean }>): ModifierBuilder<T> {
+    this.modifiers.push(shadowsModifier(configs))
+    return this
+  }
+
+  shadowPreset(presetName: string): ModifierBuilder<T> {
+    this.modifiers.push(shadowPreset(presetName))
+    return this
+  }
+
+  // Visual Effects Modifiers (Phase 2 - Epic: Butternut)
+  blur(radius: number | Signal<number>): ModifierBuilder<T> {
+    this.modifiers.push(new AppearanceModifier({ blur: radius }))
+    return this
+  }
+
+  brightness(amount: number | Signal<number>): ModifierBuilder<T> {
+    this.modifiers.push(new AppearanceModifier({ brightness: amount }))
+    return this
+  }
+
+  contrast(amount: number | Signal<number>): ModifierBuilder<T> {
+    this.modifiers.push(new AppearanceModifier({ contrast: amount }))
+    return this
+  }
+
+  saturation(amount: number | Signal<number>): ModifierBuilder<T> {
+    this.modifiers.push(new AppearanceModifier({ saturation: amount }))
+    return this
+  }
+
+  hueRotation(angle: number | Signal<number>): ModifierBuilder<T> {
+    this.modifiers.push(new AppearanceModifier({ hueRotation: angle }))
+    return this
+  }
+
+  grayscale(amount: number | Signal<number>): ModifierBuilder<T> {
+    this.modifiers.push(new AppearanceModifier({ grayscale: amount }))
+    return this
+  }
+
+  colorInvert(amount: number | Signal<number> = 1.0): ModifierBuilder<T> {
+    this.modifiers.push(new AppearanceModifier({ colorInvert: amount }))
+    return this
+  }
+
+  dropShadow(shadow: string): ModifierBuilder<T> {
+    this.modifiers.push(new FilterModifier({ filter: { dropShadow: shadow } }))
+    return this
+  }
+
+  // Additional filter methods
+  filter(config: { blur?: number; brightness?: number; contrast?: number; saturate?: number; [key: string]: any } | string): ModifierBuilder<T> {
+    this.modifiers.push(filter(config))
+    return this
+  }
+
+  saturate(value: number): ModifierBuilder<T> {
+    this.modifiers.push(saturate(value))
+    return this
+  }
+
+  sepia(value: number): ModifierBuilder<T> {
+    this.modifiers.push(sepia(value))
+    return this
+  }
+
+  hueRotate(angle: string): ModifierBuilder<T> {
+    this.modifiers.push(hueRotate(angle))
+    return this
+  }
+
+  invert(value: number): ModifierBuilder<T> {
+    this.modifiers.push(invert(value))
+    return this
+  }
+
+  // Filter presets
+  vintagePhoto(sepiaAmount?: number, contrastAmount?: number): ModifierBuilder<T> {
+    this.modifiers.push(vintagePhoto(sepiaAmount, contrastAmount))
+    return this
+  }
+
+  blackAndWhite(contrastAmount?: number): ModifierBuilder<T> {
+    this.modifiers.push(blackAndWhite(contrastAmount))
+    return this
+  }
+
+  vibrant(saturationAmount?: number, contrastAmount?: number): ModifierBuilder<T> {
+    this.modifiers.push(vibrant(saturationAmount, contrastAmount))
+    return this
+  }
+
+  warmTone(hueShift?: string): ModifierBuilder<T> {
+    this.modifiers.push(warmTone(hueShift))
+    return this
+  }
+
+  coolTone(hueShift?: string): ModifierBuilder<T> {
+    this.modifiers.push(coolTone(hueShift))
+    return this
+  }
+
+  faded(contrastAmount?: number, saturationAmount?: number): ModifierBuilder<T> {
+    this.modifiers.push(faded(contrastAmount, saturationAmount))
+    return this
+  }
+
+  highKey(brightnessAmount?: number, contrastAmount?: number): ModifierBuilder<T> {
+    this.modifiers.push(highKey(brightnessAmount, contrastAmount))
+    return this
+  }
+
+  lowKey(brightnessAmount?: number, contrastAmount?: number): ModifierBuilder<T> {
+    this.modifiers.push(lowKey(brightnessAmount, contrastAmount))
+    return this
+  }
+
+  softFocus(blurAmount?: number): ModifierBuilder<T> {
+    this.modifiers.push(softFocus(blurAmount))
+    return this
+  }
+
+  highContrastMode(): ModifierBuilder<T> {
+    this.modifiers.push(highContrastMode())
+    return this
+  }
+
+  subtleBlur(): ModifierBuilder<T> {
+    this.modifiers.push(subtleBlur())
+    return this
+  }
+
+  darkModeInvert(): ModifierBuilder<T> {
+    this.modifiers.push(darkModeInvert())
+    return this
+  }
+
+  // Transform modifiers
+  scale(value: number | { x?: number; y?: number }): ModifierBuilder<T> {
+    this.modifiers.push(scale(value))
+    return this
+  }
+
+  rotate(angle: string): ModifierBuilder<T> {
+    this.modifiers.push(rotate(angle))
+    return this
+  }
+
+  translate(offset: { x?: number | string; y?: number | string }): ModifierBuilder<T> {
+    this.modifiers.push(translate(offset))
+    return this
+  }
+
+  perspective(value: number): ModifierBuilder<T> {
+    this.modifiers.push(perspective(value))
+    return this
+  }
+
+  // Hover and cursor effect modifiers
+  hover(styles: any, transition?: string | number): ModifierBuilder<T> {
+    this.modifiers.push(hoverModifier(styles, transition))
+    return this
+  }
+
+  hoverEffect(effect: 'automatic' | 'highlight' | 'lift' | 'scale', isEnabled?: boolean): ModifierBuilder<T> {
+    this.modifiers.push(hoverEffect(effect, isEnabled))
+    return this
+  }
+
+  hoverWithTransition(styles: any, duration: number = 200): ModifierBuilder<T> {
+    this.modifiers.push(hoverWithTransition(styles, duration))
+    return this
+  }
+
+  conditionalHover(effect: 'automatic' | 'highlight' | 'lift' | 'scale', isEnabled: boolean): ModifierBuilder<T> {
+    this.modifiers.push(conditionalHover(effect, isEnabled))
+    return this
+  }
+
+  // Cursor preset methods
+  interactiveCursor(): ModifierBuilder<T> {
+    this.modifiers.push(interactiveCursor())
+    return this
+  }
+
+  draggableCursor(): ModifierBuilder<T> {
+    this.modifiers.push(draggableCursor())
+    return this
+  }
+
+  textCursor(): ModifierBuilder<T> {
+    this.modifiers.push(textCursor())
+    return this
+  }
+
+  disabledCursor(): ModifierBuilder<T> {
+    this.modifiers.push(disabledCursor())
+    return this
+  }
+
+  loadingCursor(): ModifierBuilder<T> {
+    this.modifiers.push(loadingCursor())
+    return this
+  }
+
+  helpCursor(): ModifierBuilder<T> {
+    this.modifiers.push(helpCursor())
+    return this
+  }
+
+  zoomCursor(mode: 'in' | 'out' = 'in'): ModifierBuilder<T> {
+    this.modifiers.push(zoomCursor(mode))
+    return this
+  }
+
+  // Hover effect presets
+  buttonHover(): ModifierBuilder<T> {
+    this.modifiers.push(buttonHover())
+    return this
+  }
+
+  cardHover(): ModifierBuilder<T> {
+    this.modifiers.push(cardHover())
+    return this
+  }
+
+  linkHover(): ModifierBuilder<T> {
+    this.modifiers.push(linkHover())
+    return this
+  }
+
+  imageHover(): ModifierBuilder<T> {
+    this.modifiers.push(imageHover())
+    return this
+  }
+
+  // Transition modifiers
+  transition(
+    property: string = 'all',
+    duration: number = 300,
+    easing: string = 'ease',
+    delay: number = 0
+  ): ModifierBuilder<T> {
+    this.modifiers.push(transitionModifier(property, duration, easing, delay))
+    return this
+  }
+
+  transitions(config: any): ModifierBuilder<T> {
+    this.modifiers.push(transitions(config))
+    return this
+  }
+
+  // Transition presets
+  fadeTransition(duration: number = 200): ModifierBuilder<T> {
+    this.modifiers.push(fadeTransition(duration))
+    return this
+  }
+
+  transformTransition(duration: number = 300): ModifierBuilder<T> {
+    this.modifiers.push(transformTransition(duration))
+    return this
+  }
+
+  colorTransition(duration: number = 150): ModifierBuilder<T> {
+    this.modifiers.push(colorTransition(duration))
+    return this
+  }
+
+  layoutTransition(duration: number = 250): ModifierBuilder<T> {
+    this.modifiers.push(layoutTransition(duration))
+    return this
+  }
+
+  buttonTransition(): ModifierBuilder<T> {
+    this.modifiers.push(buttonTransition())
+    return this
+  }
+
+  cardTransition(): ModifierBuilder<T> {
+    this.modifiers.push(cardTransition())
+    return this
+  }
+
+  modalTransition(): ModifierBuilder<T> {
+    this.modifiers.push(modalTransition())
+    return this
+  }
+
+  smoothTransition(duration: number = 300): ModifierBuilder<T> {
+    this.modifiers.push(smoothTransition(duration))
+    return this
+  }
+
+  quickTransition(duration: number = 150): ModifierBuilder<T> {
+    this.modifiers.push(quickTransition(duration))
+    return this
+  }
+
+  slowTransition(duration: number = 500): ModifierBuilder<T> {
+    this.modifiers.push(slowTransition(duration))
+    return this
+  }
+
+  // Scroll modifiers
+  scroll(config: any): ModifierBuilder<T> {
+    this.modifiers.push(scrollModifier(config))
+    return this
+  }
+
+  scrollBehavior(value: 'auto' | 'smooth'): ModifierBuilder<T> {
+    this.modifiers.push(scrollBehavior(value))
+    return this
+  }
+
+  overscrollBehavior(value: 'auto' | 'contain' | 'none'): ModifierBuilder<T> {
+    this.modifiers.push(overscrollBehavior(value))
+    return this
+  }
+
+  overscrollBehaviorX(value: 'auto' | 'contain' | 'none'): ModifierBuilder<T> {
+    this.modifiers.push(overscrollBehaviorX(value))
+    return this
+  }
+
+  overscrollBehaviorY(value: 'auto' | 'contain' | 'none'): ModifierBuilder<T> {
+    this.modifiers.push(overscrollBehaviorY(value))
+    return this
+  }
+
+  scrollMargin(margin: number | string | { top?: number | string, right?: number | string, bottom?: number | string, left?: number | string }): ModifierBuilder<T> {
+    this.modifiers.push(scrollMargin(margin))
+    return this
+  }
+
+  scrollPadding(padding: number | string | { top?: number | string, right?: number | string, bottom?: number | string, left?: number | string }): ModifierBuilder<T> {
+    this.modifiers.push(scrollPadding(padding))
+    return this
+  }
+
+  scrollSnap(
+    type: 'none' | 'x mandatory' | 'y mandatory' | 'x proximity' | 'y proximity' | 'both mandatory' | 'both proximity',
+    align?: 'start' | 'end' | 'center',
+    stop?: 'normal' | 'always'
+  ): ModifierBuilder<T> {
+    this.modifiers.push(scrollSnap(type, align, stop))
+    return this
+  }
+
+  // Interaction modifiers
+  onTap(handler: (event: MouseEvent) => void): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ onTap: handler }))
+    return this
+  }
+
+  onHover(handler: (isHovered: boolean) => void): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ onHover: handler }))
+    return this
+  }
+
+  onMouseEnter(handler: (event: MouseEvent) => void): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ onMouseEnter: handler }))
+    return this
+  }
+
+  onMouseLeave(handler: (event: MouseEvent) => void): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ onMouseLeave: handler }))
+    return this
+  }
+
+  onMouseDown(handler: (event: MouseEvent) => void): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ onMouseDown: handler }))
+    return this
+  }
+
+  onMouseUp(handler: (event: MouseEvent) => void): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ onMouseUp: handler }))
+    return this
+  }
+
+  onDragStart(handler: (event: DragEvent) => void): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ onDragStart: handler }))
+    return this
+  }
+
+  onDragOver(handler: (event: DragEvent) => void): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ onDragOver: handler }))
+    return this
+  }
+
+  onDragLeave(handler: (event: DragEvent) => void): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ onDragLeave: handler }))
+    return this
+  }
+
+  onDrop(handler: (event: DragEvent) => void): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ onDrop: handler }))
+    return this
+  }
+
+  // Additional mouse events
+  onDoubleClick(handler: (event: MouseEvent) => void): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ onDoubleClick: handler }))
+    return this
+  }
+
+  onContextMenu(handler: (event: MouseEvent) => void): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ onContextMenu: handler }))
+    return this
+  }
+
+  // Focus events
+  onFocus(handler: (isFocused: boolean) => void): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ onFocus: handler }))
+    return this
+  }
+
+  onBlur(handler: (isFocused: boolean) => void): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ onBlur: handler }))
+    return this
+  }
+
+  // Keyboard events
+  onKeyPress(handler: (event: KeyboardEvent) => void): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ onKeyPress: handler }))
+    return this
+  }
+
+  onKeyDown(handler: (event: KeyboardEvent) => void): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ onKeyDown: handler }))
+    return this
+  }
+
+  onKeyUp(handler: (event: KeyboardEvent) => void): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ onKeyUp: handler }))
+    return this
+  }
+
+  // Scroll and wheel events
+  onScroll(handler: (event: Event) => void): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ onScroll: handler }))
+    return this
+  }
+
+  onWheel(handler: (event: WheelEvent) => void): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ onWheel: handler }))
+    return this
+  }
+
+  // Input events
+  onInput(handler: (event: InputEvent) => void): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ onInput: handler }))
+    return this
+  }
+
+  onChange(handler: (value: any, event?: Event) => void): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ onChange: handler }))
+    return this
+  }
+
+  // Clipboard events
+  onCopy(handler: (event: ClipboardEvent) => void): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ onCopy: handler }))
+    return this
+  }
+
+  onCut(handler: (event: ClipboardEvent) => void): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ onCut: handler }))
+    return this
+  }
+
+  onPaste(handler: (event: ClipboardEvent) => void): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ onPaste: handler }))
+    return this
+  }
+
+  // Selection events
+  onSelect(handler: (event: Event) => void): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ onSelect: handler }))
+    return this
+  }
+
+  // HTML and ARIA Attributes
+  id(value: string): ModifierBuilder<T> {
+    this.modifiers.push(new IdModifier({ id: value }))
+    return this
+  }
+
+  data(attributes: { [key: string]: string | number | boolean }): ModifierBuilder<T> {
+    this.modifiers.push(new DataModifier({ data: attributes }))
+    return this
+  }
+
+  aria(attributes: { [key: string]: string | number | boolean | undefined }): ModifierBuilder<T> {
+    this.modifiers.push(new AriaModifier({ aria: attributes }))
+    return this
+  }
+
+
+  tabIndex(value: number): ModifierBuilder<T> {
+    this.modifiers.push(new TabIndexModifier({ tabIndex: value }))
+    return this
+  }
+
+  // Text Modifiers
+  lineClamp(lines: number): ModifierBuilder<T> {
+    this.modifiers.push(new LineClampModifier({ lines }))
+    return this
+  }
+
+  wordBreak(value: 'normal' | 'break-all' | 'keep-all' | 'break-word'): ModifierBuilder<T> {
+    this.modifiers.push(new WordBreakModifier({ wordBreak: value }))
+    return this
+  }
+
+  overflowWrap(value: 'normal' | 'break-word' | 'anywhere'): ModifierBuilder<T> {
+    this.modifiers.push(new OverflowWrapModifier({ overflowWrap: value }))
+    return this
+  }
+
+  hyphens(value: 'none' | 'manual' | 'auto'): ModifierBuilder<T> {
+    this.modifiers.push(new HyphensModifier({ hyphens: value }))
+    return this
+  }
+
+  // Gradient Text Modifier
+  gradientText(gradient: string): ModifierBuilder<T> {
+    this.modifiers.push(new BackgroundClipModifier({
+      backgroundImage: gradient,
+      backgroundClip: 'text',
+      color: 'transparent',
+      webkitBackgroundClip: 'text',
+      webkitTextFillColor: 'transparent'
+    }))
+    return this
+  }
+
+  // Backdrop Filter Modifiers (Unified Implementation)
+  backdropFilter(config: { blur?: number; brightness?: number; contrast?: number; saturate?: number; [key: string]: any }, fallbackColor?: ColorValue): ModifierBuilder<T>
+  backdropFilter(cssValue: string, fallbackColor?: ColorValue): ModifierBuilder<T>
+  backdropFilter(value: { blur?: number; brightness?: number; contrast?: number; saturate?: number; [key: string]: any } | string, fallbackColor?: ColorValue): ModifierBuilder<T> {
+    this.modifiers.push(new BackdropFilterModifier({ 
+      backdropFilter: value,
+      ...(fallbackColor && { fallbackColor })
+    }))
+    return this
+  }
+
+  glassmorphism(intensity: 'subtle' | 'light' | 'medium' | 'heavy' = 'medium', customFallback?: ColorValue): ModifierBuilder<T> {
+    const presets = {
+      subtle: { config: { blur: 3, saturate: 1.05, brightness: 1.05 }, fallbackColor: 'rgba(255, 255, 255, 0.05)' },
+      light: { config: { blur: 8, saturate: 1.15, brightness: 1.1 }, fallbackColor: 'rgba(255, 255, 255, 0.1)' },
+      medium: { config: { blur: 16, saturate: 1.3, brightness: 1.15 }, fallbackColor: 'rgba(255, 255, 255, 0.15)' },
+      heavy: { config: { blur: 24, saturate: 1.5, brightness: 1.2 }, fallbackColor: 'rgba(255, 255, 255, 0.2)' }
+    }
+    const preset = presets[intensity]
+    this.modifiers.push(new BackdropFilterModifier({ 
+      backdropFilter: preset.config,
+      fallbackColor: customFallback || preset.fallbackColor
+    }))
+    return this
+  }
+
+  before(styles: { content: string; color?: string; [key: string]: any }): ModifierBuilder<T> {
+    this.modifiers.push(beforeModifier(styles))
+    return this
+  }
+
+  after(styles: { content: string; color?: string; [key: string]: any }): ModifierBuilder<T> {
+    this.modifiers.push(afterModifier(styles))
+    return this
+  }
+
+  disabled(isDisabled: boolean | Signal<boolean> = true): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ disabled: isDisabled }))
+    return this
+  }
+
+  draggable(isDraggable: boolean = true): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ draggable: isDraggable }))
+    return this
+  }
+
+  setAttribute(name: string, value: string): ModifierBuilder<T> {
+    // Create a custom modifier for setting arbitrary attributes
+    this.modifiers.push({
+      type: 'attribute',
+      priority: 50,
+      properties: { name, value },
+      apply: (_node, context) => {
+        if (context.element) {
+          context.element.setAttribute(name, value)
+        }
+        return undefined
+      },
+    })
+    return this
+  }
+
+  accessibilityLabel(label: string): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ accessibilityLabel: label }))
+    return this
+  }
+
+  // Phase 4 Advanced Gesture Modifiers (Epic: Butternut)
+
+  onLongPressGesture(options: {
+    minimumDuration?: number
+    maximumDistance?: number
+    perform: () => void
+    onPressingChanged?: (isPressing: boolean) => void
+  }): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ onLongPressGesture: options }))
+    return this
+  }
+
+  keyboardShortcut(
+    key: string,
+    modifiers: ('cmd' | 'ctrl' | 'shift' | 'alt' | 'meta')[],
+    action: () => void
+  ): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ 
+      keyboardShortcut: { key, modifiers, action } 
+    }))
+    return this
+  }
+
+  focused(binding: boolean | Signal<boolean>): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ focused: binding }))
+    return this
+  }
+
+  focusable(
+    isFocusable: boolean = true,
+    interactions?: ('activate' | 'edit')[]
+  ): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ 
+      focusable: { isFocusable, interactions } 
+    }))
+    return this
+  }
+
+  onContinuousHover(
+    coordinateSpace: 'local' | 'global',
+    perform: (location: { x: number; y: number } | null) => void
+  ): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ 
+      onContinuousHover: { coordinateSpace, perform } 
+    }))
+    return this
+  }
+
+  highPriorityGesture(
+    gesture: any,
+    including?: ('all' | 'subviews' | 'none')[]
+  ): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ 
+      highPriorityGesture: { gesture, including } 
+    }))
+    return this
+  }
+
+  simultaneousGesture(
+    gesture: any,
+    including?: ('all' | 'subviews' | 'none')[]
+  ): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ 
+      simultaneousGesture: { gesture, including } 
+    }))
+    return this
+  }
+
+  allowsHitTesting(enabled: boolean): ModifierBuilder<T> {
+    this.modifiers.push(new InteractionModifier({ allowsHitTesting: enabled }))
+    return this
+  }
+
+  // Animation modifiers
+  transform(value: string | Signal<string>): ModifierBuilder<T> {
+    this.modifiers.push(new AnimationModifier({ transform: value }))
+    return this
+  }
+
+  animation(options: AnimationModifierProps['animation']): ModifierBuilder<T> {
+    this.modifiers.push(new AnimationModifier({ animation: options }))
+    return this
+  }
+
+  // Lifecycle modifiers
+  onAppear(handler: () => void): ModifierBuilder<T> {
+    this.modifiers.push(new LifecycleModifier({ onAppear: handler }))
+    return this
+  }
+
+  onDisappear(handler: () => void): ModifierBuilder<T> {
+    this.modifiers.push(new LifecycleModifier({ onDisappear: handler }))
+    return this
+  }
+
+  task(
+    operation: () => Promise<void> | void,
+    options?: { id?: string; priority?: 'background' | 'userInitiated' | 'utility' | 'default' }
+  ): ModifierBuilder<T> {
+    this.modifiers.push(
+      new LifecycleModifier({
+        task: {
+          operation,
+          id: options?.id,
+          priority: options?.priority || 'default',
+        },
+      })
+    )
+    return this
+  }
+
+  refreshable(
+    onRefresh: () => Promise<void>,
+    isRefreshing?: boolean | Signal<boolean>
+  ): ModifierBuilder<T> {
+    this.modifiers.push(
+      new LifecycleModifier({
+        refreshable: {
+          onRefresh,
+          isRefreshing,
+        },
+      })
+    )
+    return this
+  }
+
+  // Custom modifier application
+  modifier(modifier: Modifier): ModifierBuilder<T> {
+    this.modifiers.push(modifier)
+    return this
+  }
+
+  // Resizable modifier for images
+  resizable(): ModifierBuilder<T> {
+    this.modifiers.push(new ResizableModifier({}))
+    return this
+  }
+
+  // Responsive Design Methods
+  
+  /**
+   * Add modifier to internal list (used by responsive builder)
+   */
+  addModifier(modifier: Modifier): void {
+    this.modifiers.push(modifier)
+    
+    // If the component is modifiable, automatically update its modifiers array
+    if ('modifiers' in this.component && Array.isArray((this.component as any).modifiers)) {
+      const modifiableComponent = this.component as any
+      modifiableComponent.modifiers = [...modifiableComponent.modifiers, modifier]
+    }
+  }
+
+  /**
+   * Get responsive builder interface for this builder
+   */
+  responsive(): ResponsiveModifierBuilder<T>
+  
+  /**
+   * Apply responsive styles with configuration object
+   */
+  responsive(config: ResponsiveStyleConfig): ModifierBuilder<T>
+  
+  responsive(config?: ResponsiveStyleConfig): ResponsiveModifierBuilder<T> | ModifierBuilder<T> {
+    if (config) {
+      // Apply the responsive modifier directly and return this builder
+      const modifier = createResponsiveModifier(config)
+      this.modifiers.push(modifier)
+      return this
+    } else {
+      // Return responsive builder for chaining
+      return new ResponsiveModifierBuilderImpl(this)
+    }
+  }
+
+  // Responsive Breakpoint Shorthand Properties
+  get base(): ResponsiveBreakpointBuilder<T> {
+    return new ResponsiveModifierBuilderImpl(this).base
+  }
+
+  get sm(): ResponsiveBreakpointBuilder<T> {
+    return new ResponsiveModifierBuilderImpl(this).sm
+  }
+  
+  get md(): ResponsiveBreakpointBuilder<T> {
+    return new ResponsiveModifierBuilderImpl(this).md
+  }
+  
+  get lg(): ResponsiveBreakpointBuilder<T> {
+    return new ResponsiveModifierBuilderImpl(this).lg
+  }
+  
+  get xl(): ResponsiveBreakpointBuilder<T> {
+    return new ResponsiveModifierBuilderImpl(this).xl
+  }
+  
+  get '2xl'(): ResponsiveBreakpointBuilder<T> {
+    return new ResponsiveModifierBuilderImpl(this)['2xl']
+  }
+
+  // HTML Content Rendering (Text components only)
+  asHTML(options?: AsHTMLOptions): ModifierBuilder<T> {
+    const modifier = asHTML(options)
+    this.modifiers.push(modifier)
+    return this
+  }
+
+  // Build the final component with all modifiers applied
+  build(): T {
+    // Check if this component is already modifiable (from withModifiers)
+    if ('modifiers' in this.component) {
+      // Update the existing modifiable component with new modifiers
+      const existingModifiable = this.component as ModifiableComponent
+      
+      // Only add modifiers that aren't already in the component's modifiers array
+      // This prevents duplicates when addModifier has already added them
+      const newModifiers = this.modifiers.filter(builderModifier => 
+        !existingModifiable.modifiers.some(existingModifier => 
+          existingModifier === builderModifier // Reference equality check
+        )
+      )
+      
+      existingModifiable.modifiers = [...existingModifiable.modifiers, ...newModifiers]
+      return this.component as T
+    } else {
+      // Create a new modifiable component with the accumulated modifiers using the proper factory
+      const modifiableComponent = createModifiableComponent(this.component as any, this.modifiers)
+      return modifiableComponent as unknown as T
+    }
+  }
+}
+
+/**
+ * Create a modifier builder for a component
+ */
+export function createModifierBuilder<T extends ComponentInstance>(
+  component: T
+): ModifierBuilder<T> {
+  return new ModifierBuilderImpl(component)
+}
+
+/**
+ * Apply modifiers to a component instance
+ */
+export function applyModifiers<T extends ComponentInstance>(
+  component: T,
+  modifiers: Modifier[]
+): ModifiableComponent<ComponentProps> {
+  return {
+    ...component,
+    modifiers,
+    modifierBuilder: createModifierBuilder(component) as any,
+  }
+}
+
+/**
+ * Utility functions for common modifier patterns
+ */
+export const modifierUtils = {
+  /**
+   * Create a padding modifier with all sides
+   */
+  paddingAll(value: number): Modifier {
+    return new LayoutModifier({ padding: value })
+  },
+
+  /**
+   * Create a padding modifier with horizontal/vertical values
+   */
+  paddingSymmetric(horizontal?: number, vertical?: number): Modifier {
+    return new LayoutModifier({
+      padding: {
+        left: horizontal,
+        right: horizontal,
+        top: vertical,
+        bottom: vertical,
+      },
+    })
+  },
+
+  /**
+   * Create a margin modifier with all sides
+   */
+  marginAll(value: number): Modifier {
+    return new LayoutModifier({ margin: value })
+  },
+
+  /**
+   * Create a font modifier with common presets
+   */
+  fontPreset(preset: 'title' | 'heading' | 'body' | 'caption'): Modifier {
+    const presets = {
+      title: { size: 32, weight: 'bold' as const },
+      heading: { size: 24, weight: '600' as const },
+      body: { size: 16, weight: 'normal' as const },
+      caption: { size: 12, weight: 'normal' as const },
+    }
+
+    return new AppearanceModifier({ font: presets[preset] })
+  },
+
+  /**
+   * Create a shadow modifier with common presets
+   */
+  shadowPreset(preset: 'small' | 'medium' | 'large'): Modifier {
+    const presets = {
+      small: { x: 0, y: 1, radius: 3, color: 'rgba(0,0,0,0.12)' },
+      medium: { x: 0, y: 4, radius: 6, color: 'rgba(0,0,0,0.15)' },
+      large: { x: 0, y: 10, radius: 25, color: 'rgba(0,0,0,0.15)' },
+    }
+
+    return new AppearanceModifier({ shadow: presets[preset] })
+  },
+
+  /**
+   * Create a transition modifier with common presets
+   */
+  transitionPreset(preset: 'fast' | 'normal' | 'slow'): Modifier {
+    const presets = {
+      fast: { duration: 150, easing: 'ease-out' },
+      normal: { duration: 300, easing: 'ease' },
+      slow: { duration: 500, easing: 'ease-in-out' },
+    }
+
+    return new AnimationModifier({ transition: presets[preset] })
+  },
+}