# Rolling Number Counter — `rolling-counter@1.1.0`

A number that counts up like a mechanical odometer, every digit rolling into place.

Show off a big number the satisfying way: digits roll like a car's odometer from a starting value to your target, slowing down as they arrive. Add a prefix like $ or a suffix like + or 'users', choose the colour and how long it counts. Great for milestones, stats and results.

- Kind: text; status: published; digest sha256:8aef2813305461b0ad6ffd82c09e36322f72efdc241642d078fd6c4458fb075c
- Role: Foreground number layer (Canvas 2D).
- Implementation: canvas2d; entry `src/rolling-counter.js`
- Files: https://aipixelwizard.com/registry/rolling-counter/1.1.0/<path> (`LICENSE`, `asset.json`, `demo.js`, `index.html`, `src/rolling-counter.js`)
- Manifest JSON: https://aipixelwizard.com/api/v1/visuals/rolling-counter/versions/1.1.0
- Runnable demo: https://aipixelwizard.com/registry/rolling-counter/1.1.0/index.html (open over http; it imports sibling packages by relative path)
- Dependencies (exact): `apw-runtime@1.0.0` (demo) — Demo harness. src/rolling-counter.js has no dependencies.

## Exports
- `createRollingCounter({ from?, to?, delay?, duration?, ease?, prefix?, suffix?, separator?, color?, fontFamily?, weight?, size?, x?, y?, align? }) => { draw(ctx, info, width, height), valueAt(t) }` — Canvas 2D odometer driven by info.time (seconds).

## Parameters
- `from` (integer 0–999999999, default 0) — Start at
- `to` (integer 0–999999999, default 1250000) — Count to
- `countSeconds` (number 0.5–10, default 3) — Counting time (s)
- `ease` (select one of outExpo | outCubic | inOutCubic | linear, default "outExpo") — Feel
- `prefix` (text, default "$") — Before the number
- `suffix` (text, default "") — After the number
- `separator` (boolean, default true) — Thousands commas
- `color` (color, default "#ffffff") — Colour
- `background` (color, default "#101418") — Background

## Composition
- Inputs: Canvas 2D context, info.time (seconds), width, height.
- Outputs: Draws the number on the canvas. Does not clear it.
- Coordinates: Centre point as fractions of width/height; size as a fraction of the shorter side.
- Lighting: None.
- Timing: Pure function of time; valueAt(t) gives the exact value at any moment.
- Works with: gradient-background, spring-motion, kinetic-title, particle-tunnel
- Prefix and suffix are treated as private and are not stored in shared packs unless you choose to include them.

## Output and loop
- 1080×1080, 30 fps, 5 s, procedural
- Seamless loop: no — Counts once and holds the final number.
- Verified 2026-10-03 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 counter once; each frame draw your background then counter.draw(ctx, { time: frame / fps }, width, height).

Existing project: Copy src/rolling-counter.js and call draw from your existing frame loop where the number should appear.

Reuse ideas:
- Combine with Soft Moving Gradient and a spring pop-in label (see Minimal Animated Number Reveal).
- Use valueAt(t) alone to drive a progress bar or a 3D bar chart.
- Place several counters (x/y options) for a stats grid.

## Limitations
- Whole numbers only (no decimals).

## 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. Uses the viewer's system font. Demo and typography rebuilt in October 2026 to the catalog quality bar (docs/QUALITY.md).