---
name: build-cdp-web-patches
description: Build, validate, save, share, and preview editable cdp-web patch graphs. Use when the user asks for a cdp-web patch, `.cdp` file, patch recipe, editable CDP graph, browser-based CDP chain, shareable CDP link, `#patch=` URL, or wants a CDP sound-design idea opened in the cdp-web frontend rather than only rendered to audio.
---

# Build CDP Web patches

Create native `cdp-web-patch` v1 documents and links for `https://cdp-web.app`. Prefer the bundled builders and validator over hand-authoring serialized patch JSON.

Resolve every path below relative to this `SKILL.md`; call that directory `<skill>`.

## 1. Check the environment

Run once per session:

```sh
node <skill>/scripts/check-env.mjs
```

Stop and relay its remediation if it fails. Building patches needs the `cdp-wasm` JavaScript catalog but does not need compiled WASM artifacts.

## 2. Discover catalog entries

Run `node <skill>/scripts/catalog.mjs` for compact catalog lines. Run it with IDs for full definitions and parameter ranges:

```sh
node <skill>/scripts/catalog.mjs blur.blur stretch.time wave
```

Inspect every effect and generator before using it. Never guess an ID, parameter name, range, input count, or envelope capability.

## 3. Choose an authoring mode

Write a small JSON authoring spec, then compile it to `.cdp`:

```sh
node <skill>/scripts/build-patch.mjs /tmp/my-patch-spec.json
```

The default output is `./cdp-patches/<name>.cdp`. The command validates it and prints its cdp-web share URL.

- Use `kind: "linear"` for one source followed by ordinary single-input effects. The builder inserts PVOC Analyse/Resynthesise adapters.
- Use `kind: "two-input"` for catalog effects with `inputs: 2`. The builder adapts both spectral branches.
- Use `kind: "graph"` for branches, layers, banks, Gather/Pick, breakpoint cables, raw transforms, or Faust. The builder inserts spectral adapters on ordinary graph edges by default.

Treat Faust as a cdp-web-only node type. `cdp-wasm` does not contain a Faust compiler or execute Faust DSP; these scripts only serialize and structurally validate Faust nodes. Compile, audition, and verify their DSP in cdp-web, which supplies `@grame/faustwasm`. Never report a Faust patch as render-validated until it has run there.

Read `references/patch-format-v1.md` before authoring graph mode or any nontrivial patch.

Example linear spec:

```json
{
  "kind": "linear",
  "name": "Ghost voice",
  "source": {
    "type": "url",
    "url": "https://example.org/audio/voice.wav",
    "name": "voice.wav"
  },
  "steps": [
    { "effect": "stretch.time", "values": { "factor": 3 } },
    { "effect": "blur.blur", "values": { "windows": 40 } }
  ]
}
```

Use generator sources when no hosted sound is needed:

```json
{ "type": "generator", "generatorId": "wave", "values": { "shape": "1", "freq": 220, "dur": 3 } }
```

## 4. Validate and share

Validate a new or existing native patch explicitly when needed:

```sh
node <skill>/scripts/validate-patch.mjs path/to/patch.cdp --shareable
node <skill>/scripts/patch-url.mjs path/to/patch.cdp
```

Always keep the `.cdp` file even when the requested deliverable is a link. Warn when a Source uses disk audio, and note the link length `build-patch.mjs` prints: links keep working when long, but past ~2.9 KB cdp-web can no longer render the QR code its share panel offers. A disk-picked sound does not travel; a portable sound Source needs an absolute HTTPS URL whose server permits browser CORS requests. Do not upload user audio without explicit authorization and a named destination.

## 5. Hand over the link verbatim

A share URL is a verbatim artifact, not text to reproduce. Its payload is commonly over a thousand base64url characters, and a single wrong, dropped, or added character makes the whole link undecodable — cdp-web opens an error in its log dock instead of the patch. Copy the exact line the scripts printed. Never retype a payload, reflow it across lines, shorten it with an ellipsis, or reconstruct one from an earlier message.

Verify the exact string before handing it over, whenever a link passes through a message, a file, or a summary:

```sh
node <skill>/scripts/verify-url.mjs "<the full URL you are about to send>"
node <skill>/scripts/verify-url.mjs "<url>" --patch path/to/patch.cdp
```

It decodes the link exactly as cdp-web does and fails loudly on a corrupt, truncated, wrapped, or hand-copied payload. `--patch` additionally confirms the link carries that `.cdp` and not an older one. On failure, regenerate with `patch-url.mjs` and copy the fresh line — never patch up the broken string.

## 6. Preview when possible

Return the `.cdp` path and a clickable share URL. If the user asks to open or preview it and browser-control capability is available, navigate that browser to the generated URL and verify that cdp-web loads the graph. Accept the confirmation dialog if cdp-web already has an autosaved patch. If browser control is unavailable, provide the URL without treating that as failure. Do not invoke an OS-level browser merely to satisfy previewing unless the user requested it.

## Output rules

- Preserve editable graph intent; do not replace the patch deliverable with a rendered WAV.
- Give every patch a concise `metadata.name`; add a description when the musical intent is non-obvious.
- Prefer absolute HTTPS Source URLs. Relative `audio/...` URLs are only for sounds bundled with the deployed cdp-web app.
- Keep values inside catalog ranges unless the user explicitly requests unlocked parameters.
- Describe Faust validation as structural only; require cdp-web for compilation and audio verification.
- Report validation warnings, the written file, node/cable counts, and the share link.
- Emit share links only as copied verbatim from `patch-url.mjs` or `build-patch.mjs` output, after `verify-url.mjs` has passed on the exact string.
- Use the sibling `cdp-sound-design` skill as well when the user also requests rendered audio, analysis-driven parameters, or listening-oriented iteration.