feat: structured manifest.json index + CDN serving for FastLED assets

[zackees]

Summary

Turn this repo from an ad-hoc media dump into a structured, manifest-described, CDN-served asset store that FastLED builds and the FastLED website can both consume.

Current state

main contains 15 objects — a 9-byte README.md and a flat docs/ folder of demo videos and images (~235 MB, largest single file docs/fastled_3_10_animartrix.mp4 at 96 MB). There is:

• no manifest or index — nothing enumerates what exists
• no directory convention — everything is docs/
• no integrity metadata — no checksums anywhere
• no CDN story — consumers hit raw.githubusercontent.com directly
• no distinction between documentation media and build-time example assets

Proposed

1. Directory convention

docs/                      # existing README/demo media (unchanged)
examples/<SketchName>/     # build-time assets consumed by fbuild
manifest.json              # index, per zackees/manifest.json

2. Adopt zackees/manifest.json

Use zackees/manifest.json rather than a bespoke format. Its Index → Catalog → Release tiers and OCI-style {url, sha256, size_bytes} descriptors give integrity-chained federation across repos and CDNs — exactly what a CDN-fronted asset store needs. Every asset entry carries a sha256, so consumers verify content rather than trusting transport.

Note the platform tuple is a poor fit for media assets (a .rgb video has no os/arch). Either use a wildcard/any platform, or raise a spec question upstream about a media/data asset class. This is the main open design question and should be settled before bulk-populating the manifest.

3. CDN

raw.githubusercontent.com is not a CDN and is rate-limited. Front the repo with jsDelivr (https://cdn.jsdelivr.net/gh/FastLED/assets@<ref>/<path>), which needs no infrastructure and supports tag/commit pinning. Manifest urls is an array, so the raw GitHub URL can stay as a documented fallback.

4. Website surfacing

With a manifest in place, the FastLED site can enumerate and render available assets from one JSON fetch instead of hardcoding paths.

Immediate work

Host the FxLedmapper32x32 assets currently committed in the FastLED source tree:

• video1.rgb — 6,051,840 bytes, 1,970 frames at 32x32 RGB888 (3,072 B/frame)
• screenmap.json — 13,790 bytes, sha256 a6851e2a5eaf728b0018f1a32918969b2e90673ed2c18c1a3a5d7327cf5993d7, sourced from the ledmapper 32x32_quad_serpentine preset

Note: a third file, ledmapper-32x32-video1-asset.zip (4.1 MB), is a bundle of the two above plus a readme. It is pure duplication and should not be hosted — the manifest makes a hand-rolled bundle unnecessary.

Considerations

• Repo size. Already 235 MB. Binary assets never delete from git history. Consider Git LFS, or a release-artifact model, before this grows further. Worth deciding now rather than at 1 GB.
• Immutability. Assets referenced by digest must never be rewritten in place; publish new versions under new paths so pinned builds stay reproducible.

Related

• feat: resolve remote example assets at build time (sha256-verified, globally cached) fbuild#1354 — build-time resolution of these URLs
• FastLED/FastLED — removal of the committed binaries
• zackees/fastled-wasm — WASM preview must resolve the same URLs

[zackees]

Tracked in the meta issue: FastLED/FastLED#3986 — remote assets: hosting, build-time resolution, and on-device filesystem deployment.

[zackees]

Done — manifest and CDN live and validated

Directory convention — examples/<SketchName>/ now sits alongside the pre-existing docs/, separating build-time example assets from documentation media.

manifest.json in the zackees/manifest.json format:

• root manifest.json — Index, pointing at per-example catalogs with an OCI-style {url, sha256, size_bytes} descriptor
• examples/FxLedmapper32x32/manifest.json — Catalog with one Release whose three files are modeled as components (video, screenmap, bundle)

Using Release.components rather than the platform tuple was deliberate: a .rgb video has no os/arch, so the platform map is the wrong axis for media. Platform is left as the empty wildcard.

Both validate against the upstream schema (re-verified just now against the live URLs):

$ manifest-validate manifest.json examples/FxLedmapper32x32/manifest.json
OK   manifest.json
OK   examples/FxLedmapper32x32/manifest.json

CDN serving — jsDelivr is the primary URL in every descriptor with raw.githubusercontent.com as a documented fallback. Both return HTTP 200.

Hosted assets — video1.rgb (6,051,840 B), screenmap.json (13,790 B), and the bundle zip, each with a recorded sha256. Verified byte-identical to the originals.

Consumed downstream

FastLED's WASM build now resolves these through the unified scanner (FastLED/FastLED#3990) and emits a manifest carrying the CDN URL plus integrity metadata — see FastLED/FastLED#3974 for the end-to-end trace.

Deliberately not done

• Website surfacing. Enumerating assets on the site from this manifest is a www change, not an assets-repo one.
• Git LFS / release-artifact migration. Flagged in the original issue as worth deciding before the repo grows; it is a separate call from landing the manifest, and the repo is stable at ~235MB.

Closing — the manifest and CDN work described here is complete. Those two follow-ups deserve their own issues if wanted.