SwiftUIShaders AGENTS.md

AGENTS.md: architecture for coding agents

This file is for an AI agent (Claude Code, Codex, etc.) asked to use, extend, modify, or rebuild these shaders. It explains exactly how the package is wired so you can work without re-deriving the conventions.

What this package is

• A SwiftPM library, SwiftUIShaders, with two source files:
  • Sources/SwiftUIShaders/Shaders/SwiftUIShaders.metal: 41 [[ stitchable ]] SwiftUI fragment shaders plus 5 shared helper functions. This is the source of truth.
  • Sources/SwiftUIShaders/ShaderEffects.swift: one typed View modifier per shader, plus two private ViewModifiers (_StaticShaderEffect, _AnimatedShaderEffect) that do the actual layerEffect plumbing.
• No third-party dependencies. No app code. The bcs_ prefix is just a namespace (it originated as "book cover shaders").

How SwiftUI Metal shader effects work (the mental model)

SwiftUI exposes three shader entry points on View: .colorEffect, .layerEffect, and .distortionEffect. Every shader here is a layerEffect, because they all need to sample neighboring pixels (blur, displacement, refraction). A layerEffect Metal function has this fixed signature shape:

[[ stitchable ]] half4 bcs_name(
    float2 position,        // pixel being computed (SwiftUI supplies this)
    SwiftUI::Layer layer,   // the source view, sample it with layer.sample(coord) (SwiftUI supplies this)
    float2 size,            // view size in pixels  <- first user argument
    float time,             // seconds, for animation (only on animated shaders)
    float param1,           // ...effect-specific knobs
    ...
) { ... }

position and layer are provided by SwiftUI automatically. Everything after layer is provided in order by the Swift call, via Shader.Argument values (.float, .float2, .color, …). The arguments must match the Metal parameter order exactly.

At runtime the shaders live in a compiled default.metallib inside the package's resource bundle. You reach them with: