# Silk Ribbons — `silk-ribbons@1.0.0`

Long ribbons of silk weaving across the frame, overlapping with soft seams and a moving highlight along each fold. Loops perfectly.

Long ribbons of silk drifting across the frame. Each ribbon is a smooth band whose centre line is a sum of sines, with its own width, colour and speed; where ribbons cross they overlap with a soft, slightly brighter seam, and a gentle highlight runs along each ribbon's fold. Every sine makes a whole number of cycles per loop, so the loop is exact. Choose the number of ribbons, the colours (dusk, ocean, gold or mono), how broad they are, how far they weave and the seed.

- Kind: background; status: published; digest sha256:b079934d7a89fc3146ae0aaeb9c6583e6d345e47826646d220460d365ee0232c
- Role: Shader background (three.js): an elegant flowing backdrop for titles, covers and calm scenes.
- Implementation: three; entry `src/silk-ribbons.js`
- Files: https://aipixelwizard.com/registry/silk-ribbons/1.0.0/<path> (`LICENSE`, `asset.json`, `demo.js`, `index.html`, `src/silk-ribbons.js`)
- Manifest JSON: https://aipixelwizard.com/api/v1/visuals/silk-ribbons/versions/1.0.0
- Runnable demo: https://aipixelwizard.com/registry/silk-ribbons/1.0.0/index.html (open over http; it imports sibling packages by relative path)
- Dependencies (exact): `three@0.185.1` (source) — Renderer and a full-screen shader material.; `apw-runtime@1.0.0` (demo) — Demo harness.

## Exports
- `createSilkRibbons({ ribbons?, palette?, width?, sway?, seed? }) => { scene, camera, setSize(width, height), update(time, loopSeconds), dispose() }` — The ribbons as one full-screen shader; render its scene with its camera, ideally through createBloomPass.
- `createBloomPass(renderer, { width, height, glow?, exposure?, grain? }) => { render(scene, camera, output?), dispose() }` — A small bloom with tone mapping and a fixed grain.
- `PALETTES: { dusk, ocean, gold, mono }` — Backdrop and ribbon colours.

## Parameters
- `ribbons` (integer 2–6, default 6) — Ribbons
- `palette` (select one of dusk | ocean | gold | mono, default "dusk") — Colours
- `width` (number 0.5–1.6, default 1) — Ribbon width
- `sway` (number 0.3–1.6, default 1) — Sway
- `seed` (integer 1–999, default 3) — Seed

## Composition
- Inputs: Time within the loop; the ribbons, colours, width, sway and seed.
- Outputs: A full-frame shader image through a bloom pass.
- Coordinates: Screen-centred, ±1 vertically; each ribbon's centre line is a function of x; ribbons are drawn back to front.
- Lighting: Self-lit; each ribbon is shaded across its width like a fold of silk, with brighter seams at its edges.
- Timing: update(time, loopSeconds) sets the loop phase; frames render in any order.
- Works with: kinetic-title, number-reveal
- No textures: the whole look is trigonometry, which is why it loops exactly.

## Output and loop
- 1080×1080, 30 fps, 12 s, procedural
- Seamless loop: yes — Every sine that moves a ribbon makes a whole number of cycles per loop, so the last frame meets the first.
- Verified 2026-10-08 in Chrome 154.0.8037.97 headless on Linux 7.0.0-38-generic (x64), Node 22.14.0 (WebGL 2 via SwiftShader (software)); deterministic: yes; loop check: Frame 0 vs end state (progress 1): mean |Δ| 0.0000, max |Δ| 0 of 255.

## Use it
New project: Create a WebGLRenderer, createSilkRibbons() and createBloomPass(renderer, { width, height }); call silk.setSize(w, h) and each frame silk.update(time, loopSeconds) then bloom.render(silk.scene, silk.camera).

Existing project: Copy src/silk-ribbons.js and render silk.scene with silk.camera into your own target.

Reuse ideas:
- Luxury title: Dusk, six ribbons.
- Cool and calm: Ocean, broad.
- Warm: Gold, slow sway.

## Limitations
- Ribbons are flat bands, not cloth: they do not fold over themselves.
- Many broad ribbons overlap into a solid wash of colour.

## License
MIT. Copyright (c) 2026 AI Pixel Wizard. Released under the MIT License. See LICENSE in this folder.

Provenance: Original code written for AI Pixel Wizard in October 2026, to the catalog quality bar (docs/QUALITY.md).