Skip to content

FUTURE_macwmfx_Implementation.md

Latest commit

 

History

History
473 lines (341 loc) · 7.06 KB

FUTURE_macwmfx_Implementation.md

File metadata and controls

473 lines (341 loc) · 7.06 KB
Raw

Alright — below is a complete, implementation-oriented design package for macwmfx.

No branding, no vendor ideology. This is written like a real compositor / WM effects engine spec.

1. macwmfx.json — Schema Design

Declarative, layered, reloadable. Think picom + sway + kwin rules, but for Quartz / CA.

1.1 Top-Level Schema

{
  "$schema": "https://macwmfx.dev/schema/v1.json",

  "global": { },
  "themes": { },
  "rules": [ ],
  "effects": { },
  "animations": { },
  "debug": { }
}

1.2 Global Settings

"global": {
  "enabled": true,
  "scale": 1.0,
  "animationSpeed": 1.0,
  "vsync": true,
  "liveReload": true,
  "backend": "quartz"
}

1.3 Window Rules (Core of the system)

"rules": [
  {
    "match": {
      "app": "com.apple.Terminal",
      "role": "main",
      "focused": true
    },
    "apply": {
      "theme": "glass-heavy",
      "effects": ["blur", "shadow", "border"],
      "animationProfile": "snappy"
    }
  }
]

Match Targets

  • app
  • bundleId
  • windowTitle
  • role
  • focused
  • workspace
  • display
  • floating
  • grouped

1.4 Effects Definitions

"effects": {
  "blur": {
    "radius": 30,
    "saturation": 1.2,
    "tint": "#00000022",
    "noise": 0.04
  },

  "shadow": {
    "radius": 40,
    "offset": [0, -12],
    "color": "#00000088"
  },

  "border": {
    "width": 2,
    "color": "#88c0d0",
    "radius": 14
  }
}

1.5 Animations

"animations": {
  "snappy": {
    "duration": 0.18,
    "curve": "easeOut",
    "spring": false
  },

  "springy": {
    "spring": true,
    "mass": 1,
    "damping": 14,
    "stiffness": 160
  }
}

1.6 Themes

"themes": {
  "minimal": { },
  "glass-heavy": { },
  "brutalist": { },
  "retro": { }
}

Themes override effects + colors + geometry.

2. Category → Quartz / CoreAnimation Mapping

Below is how each visual category maps to real primitives.

2.1 Geometry & Shape

Primitives

  • CALayer.cornerRadius
  • CAShapeLayer.mask
  • CGPathCreateWithRoundedRect
  • CAConstraintLayoutManager

Implementation ideas

  • Inject a root CALayer above each window’s content
  • Apply a mask layer for non-rectangular shapes
  • Animate geometry via CABasicAnimation
  • Use multiple layers for asymmetric corners

2.2 Borders & Frames

Primitives

  • CAShapeLayer.strokeColor
  • lineWidth
  • strokeEnd (animated borders)
  • CAGradientLayer

Implementation ideas

  • Border is a sibling layer to content
  • Animated borders via stroke animations
  • Multi-layer borders for glow stacks
  • Blend modes via compositingFilter

2.3 Shadows & Depth

Primitives

  • CALayer.shadowRadius
  • shadowPath
  • shadowOpacity
  • shadowColor

Implementation ideas

  • Replace default shadow with custom shadow layer
  • Animate shadow based on focus
  • Multi-shadow stacks via layered CALayers
  • Fake depth via opacity + blur radius

2.4 Blur & Transparency

Primitives

  • CAFilter (Gaussian blur)
  • CABackdropLayer
  • NSVisualEffectView (if embedding)
  • compositingFilter

Implementation ideas

  • Backdrop blur layer inserted behind content
  • Region-based blur via masks
  • Noise overlay via bitmap layer
  • Variable blur via gradient mask

2.5 Chrome & Controls

Primitives

  • Custom CALayer chrome strip
  • CATextLayer
  • Hit-testing via transparent overlay
  • Event forwarding

Implementation ideas

  • Hide native chrome
  • Rebuild chrome entirely in CALayer
  • Custom control hit-regions
  • Animate chrome independently of content

2.6 Content Framing

Primitives

  • Insets via layout constraints
  • Inner shadows via inverted shadow masks
  • Edge fade via gradient mask

Implementation ideas

  • Insert inner container layer
  • Content clipped to rounded rect
  • Scroll edge glow via animated gradients

2.7 Motion & Animation

Primitives

  • CAAnimationGroup
  • CASpringAnimation
  • CATransaction
  • CAMediaTimingFunction

Implementation ideas

  • Central animation scheduler
  • Interruptible animations via layer presentation state
  • Per-window animation profiles
  • Global speed scaling

2.8 Focus & State

Primitives

  • Layer opacity
  • Saturation filters
  • Glow layers
  • Z-position

Implementation ideas

  • Focus state toggles effect stack
  • Background windows dimmed via saturation filter
  • Active window lifted via z-position + shadow
  • Cursor proximity via event tap

2.9 Grouping & Relationships

Primitives

  • Shared parent CALayer
  • Group masks
  • Connector layers

Implementation ideas

  • Create virtual “group layer”
  • Attach windows as sublayers
  • Shared blur / glass backdrop
  • Animated regrouping

2.10 Z-Order & Spatial Effects

Primitives

  • zPosition
  • Perspective transforms
  • Depth fog via gradient overlays

Implementation ideas

  • Faux-3D stacking
  • Parallax transforms
  • Atmospheric depth via opacity curves

2.11 Color & Themes

Primitives

  • CIColorControls
  • Tint overlays
  • Color matrices

Implementation ideas

  • Palette injection
  • Live theme switching
  • Wallpaper-aware color sampling

2.12 Filters & Post-Processing

Primitives

  • Core Image filters
  • Layer filters
  • Compositing filters

Implementation ideas

  • Per-window filter chains
  • Debug visualizers
  • Retro modes via scanline textures

3. Preset Configurations

3.1 Minimal

{
  "effects": {
    "shadow": { "radius": 12, "opacity": 0.2 },
    "border": { "width": 1, "color": "#444444" }
  },
  "animations": {
    "default": { "duration": 0.12 }
  }
}

3.2 Glass-Heavy

{
  "effects": {
    "blur": {
      "radius": 40,
      "saturation": 1.3,
      "noise": 0.06
    },
    "shadow": {
      "radius": 50,
      "offset": [0, -18]
    }
  }
}

3.3 Brutalist

{
  "effects": {
    "border": {
      "width": 4,
      "color": "#ffffff"
    },
    "shadow": {
      "radius": 0
    }
  },
  "animations": {
    "default": { "duration": 0 }
  }
}

3.4 Retro

{
  "effects": {
    "filters": {
      "scanlines": true,
      "grain": 0.12,
      "chromaticAberration": 0.04
    }
  }
}

4. High-Level Implementation Architecture

Suggested components

macwmfxd
├── Rule Engine
├── Window Tracker (AX / CGS)
├── Layer Injector
├── Effect Graph Builder
├── Animation Scheduler
├── Config Loader (live reload)
└── Debug Overlay

Core trick

  • Every window becomes a CALayer tree
  • Native drawing untouched
  • Effects are layered around content
  • Config → effect graph → layer mutations

Final framing

macwmfx is:

  • not a theme engine
  • not a UI framework
  • not an app

It is a compositor-level visual rules engine that treats windows as material objects.

If you want next:

  • I can design the effect graph DSL
  • map exact private SkyLight entry points
  • or help you prototype a single effect pipeline (blur + mask + shadow) cleanly

You’re designing something real — and this spec is viable.