# Countdown Ring — `countdown-ring@1.0.0`

A countdown where a thick ring sweeps down for every number, digits drop in under a mask, and the final word lands with a flash.

A countdown that counts with a ring. A thick arc sweeps away round a dial, one full sweep per number; at each tick the digit snaps out and the next drops in under a mask, a pulse leaves the ring and tick marks light up as they are passed. At zero the ring closes, flashes and the final word lands. Choose the number to start from (2 to 10), the final word (or none), the colours (electric, sunrise, lime or mono), the seconds per number and the backdrop colour.

- Kind: text; status: published; digest sha256:c731466575b271dcd109988125a3d66a21b0ee1861b648ad7bffd7d63231e4e1
- Role: Text scene (Canvas 2D): launch, stream-starting and event countdowns.
- Implementation: canvas2d; entry `src/countdown-ring.js`
- Files: https://aipixelwizard.com/registry/countdown-ring/1.0.0/<path> (`LICENSE`, `asset.json`, `demo.js`, `index.html`, `src/countdown-ring.js`)
- Manifest JSON: https://aipixelwizard.com/api/v1/visuals/countdown-ring/versions/1.0.0
- Runnable demo: https://aipixelwizard.com/registry/countdown-ring/1.0.0/index.html (open over http; it imports sibling packages by relative path)
- Dependencies (exact): `apw-runtime@1.0.0` (demo) — Demo harness. The reusable source has no dependencies.

## Exports
- `createCountdownRing({ from?, final?, theme?, per?, start?, fontFamily? }) => { draw(ctx, info, width, height), revealDuration }` — Canvas 2D countdown layer driven by info.time (seconds).
- `THEMES: { electric, sunrise, lime, mono }` — Ring, track, digit and glow colours.

## Parameters
- `from` (integer 2–10, default 5) — Count from
- `final` (text, default "GO") — Final word: Shown at zero. Leave empty for none.
- `theme` (select one of electric | sunrise | lime | mono, default "electric") — Theme
- `per` (number 0.5–1.5, default 1) — Seconds per number
- `background` (color, default "#0b1020") — Backdrop

## Composition
- Inputs: Canvas 2D context, info.time (seconds), width, height.
- Outputs: Draws the countdown on top of the canvas; does not clear it.
- Coordinates: Centred; the ring has a radius of 330 on a 1080 canvas and scales with the smaller side.
- Lighting: The ring glows in the theme colour; the demo adds a soft pool of it behind.
- Timing: Pure function of time; one number per `per` seconds after a 0.4 s start; revealDuration says when the final word has landed.
- Works with: kinetic-title, gradient-background
- Total length is 0.4 s + from × seconds per number + 0.9 s; the 8-second clip fits the defaults (5 numbers) with time to hold, and presets with more numbers shorten each one.

## Output and loop
- 1080×1080, 30 fps, 8 s, procedural
- Seamless loop: no — Not a loop: it counts down and ends on the final word (or an empty, closed ring).
- Verified 2026-10-08 in Chrome 154.0.8037.97 headless on Linux 7.0.0-38-generic (x64), Node 22.14.0 (Canvas 2D); deterministic: yes

## Use it
New project: Create the countdown once, then each frame draw your backdrop and call count.draw(ctx, { time: frame / fps }, width, height).

Existing project: Copy src/countdown-ring.js. Call draw on your existing 2D canvas after the rest of the frame.

Reuse ideas:
- Launch: Electric, five to go.
- Live stream: Sunrise, ten.
- Quick count-in: Lime, three.

## Limitations
- System fonts differ between computers; pass fontFamily and load the font first for identical renders.
- Counting down from more than ten, or at under half a second per number, will not fit the 8-second clip.

## 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).