---
name: wallive-backdrop-shader
description: Guide agents and advanced users to create soft Wallive Dynamic Island ambient glow shader packages using Wallive's controlled Metal function contract. Use when Codex needs to write, adapt, validate, or apply a Wallive Island glow package, especially requests about atmospheric glow, room-light effects, music-reactive parameters, shader packages, or using the local `wallive-skills wallive-backdrop-shader` CLI.
---

# Wallive Backdrop Shader

## Overview

Create Wallive Island ambient glow shaders as controlled functions, not full Metal programs. This skill intentionally creates outside-the-Island atmosphere only. Wallive owns the Metal prelude, vertex/fragment wrapper, uniforms, blending, clipping, render quality tiers, and fallback behavior.

## Workflow

1. Read `references/shader-contract.md` before writing or converting shader code.
2. Always target outside ambient glow:
   - Set package `mode` to `glow`.
   - Write exactly one `glowShader`.
   - Do not write `backdropShader`.
   - Do not create effects intended to appear inside the Island shell.
   - Set optional package `renderQuality` to `soft`, `balanced`, or `sharp`. Prefer `balanced` for atmospheric shaders that need clearer sampling; use `sharp` sparingly.
3. Write only:

```metal
float4 islandCustomGlow(float2 frag, float2 uv, constant GlowUniforms& u) {
    return float4(0.2, 0.5, 1.0, 0.35);
}
```

4. Do not include `#include`, `using namespace metal`, `vertex`, `fragment`, `[[stage_in]]`, texture/sampler declarations, or custom uniforms.
5. Package the result as JSON using the schema in `references/shader-contract.md`.
6. Validate before applying:

```bash
npm exec --package @wallive/agent-skills -- wallive-skills wallive-backdrop-shader validate --package path/to/package.json
```

7. Apply locally:

```bash
npm exec --package @wallive/agent-skills -- wallive-skills wallive-backdrop-shader apply --package path/to/package.json
```

Applied packages are installed into Wallive's local shader catalog, so the app's Settings window can list them in the Island Effects shader picker.

## Visual Rules

- Make the effect read as soft environmental light around the Island, not as visible objects.
- Avoid particles, sparks, lightning, plasma bolts, rain, snow, confetti, grids, waveform bars, or sharp moving shapes.
- Return transparent alpha for empty areas. Full alpha turns the Island into a flat card.
- Use `u.bass` for thickness/reach, `u.mid` for gentle activity, `u.beat` for slow brightness breathing, and `u.treble` only for subtle hue variation.
- Use `sdRoundedBox(...)` or edge falloff so effects respect the Island shape and never read as rectangular blocks.
- Keep detail broad enough for the chosen ambient-glow render quality. Prefer slow gradients, soft halos, color drift, and wide falloff.

## Resources

- `references/shader-contract.md`: function contract, uniforms, package JSON, and conversion rules.
- `assets/soft-aurora-glow.package.json`: test package with a soft outside-only aurora glow.

## CLI

Use the npm-published helper CLI. Do not assume the user has the Wallive source repository checked out.

```bash
npm exec --package @wallive/agent-skills -- wallive-skills install --target ~/.ai/skills
npm exec --package @wallive/agent-skills -- wallive-skills wallive-backdrop-shader validate --package /absolute/path/to/package.json
npm exec --package @wallive/agent-skills -- wallive-skills wallive-backdrop-shader apply --package /absolute/path/to/package.json
```

If the skill is already installed locally and you want to apply its bundled aurora example, resolve the package from the installed skill directory:

```bash
SKILL_DIR="$HOME/.ai/skills/wallive-backdrop-shader"
npm exec --package @wallive/agent-skills -- wallive-skills wallive-backdrop-shader apply --package "$SKILL_DIR/assets/soft-aurora-glow.package.json"
```