wallpapers.crosspoint-plugin

CrossPoint wallpaper catalog plugin backed by the public ReadMe.club wallpaper gallery.

Version 0.1.3 uses one plugin package for both baseline and enhanced CrossPoint firmware. Stock firmware uses an embedded catalog snapshot and the normal native list UI; capability-aware firmware prefers the live catalog index and enables thumbnails, grid/list layouts, preview, settings, and progressive caching.

Dual-mode compatibility

• Baseline plugin firmware: uses the embedded browse.lists snapshot and standard native list UI. Users can browse the release-time catalog picker, page through wallpapers, and download selected images directly into /.sleep.
• Capability-aware/enhanced firmware: the same package prefers the live browse.lists_url index and automatically enables thumbnail-backed grid/list layouts, configurable grid dimensions and row highlighting, image preview, SAVED indicators, plugin settings, and progressive image caching.
• Touch-capable enhanced devices: expose the touch-only Hide pagination buttons setting. When pagination is hidden, swipe up moves to the next visible batch and swipe down moves to the previous visible batch; crossing a catalog-page boundary advances to Next or Previous. Touch preview provides on-screen Close/Save controls, while physical-button behavior remains unchanged.
• Enhanced-only fields are declarative capabilities. Firmware that does not support them ignores them and continues using the baseline behavior from the same plugin package.
• The embedded lists remain a fallback if the live catalog index cannot be fetched.
• Both embedded and dynamic catalog indexes are produced from the same generator inputs so they do not need separate manual maintenance.

Install with Plugin Hub

Plugin Hub is the preferred installation and update path.

1. Enable the device plugin system if it is not already enabled.
2. Open Plugins and launch Plugin Hub.
3. Open the Community catalog and refresh it if needed.
4. Find Wallpaper Downloader v0.1.3 and choose Install or Update.
5. Open Wallpaper Downloader from the device Plugins UI after installation.

Plugin Hub discovers the published plugin release and handles the installable payload. The versioned GitHub release ZIP remains available as a manual fallback.

Repository layout

wallpapers.crosspoint-plugin/
├── wallpapers.crosspoint-plugin/   # installable Plugin Hub payload
│   ├── manifest.json
│   ├── device.json                  # generated by tools/build_catalog.py
│   ├── README.md
│   └── DETAILS.md
├── catalogs/                        # generated native browse pages; committed/published
├── tools/
│   └── build_catalog.py
├── tests/
│   └── test_build_catalog.py
└── README.md

The direct child wallpapers.crosspoint-plugin/ follows the Plugin Hub standalone repository convention. Development tooling and generated source material stay outside the installable payload.

Catalogs generated

A normal build creates:

• Random Mix
• Latest
• Popular
• X3
• X4 / X4 Pro / X4C
• Picco
• Seeed reTerminal Sticky
• Paper Pro Move
• Category · Custom
• Category · Dark
• Category · Light
• Category · Minimalist
• Category · Other
• Category · Pop Culture
• recent monthly curated packs

Device catalogs use ReadMe.club's public fits filters. The X4 family list currently combines the X4 and X4 Pro compatibility filters because the site does not expose a separate X4C filter.

Native catalog rows

Baseline CrossPoint's native generic catalog browser renders these as text rows. Enhanced firmware can use the same item metadata for thumbnails and grid/list layouts. Each generated item maps:

• title → wallpaper title
• author → synthesized Category · uploader · downloads
• id → ReadMe.club wallpaper UUID
• url → ReadMe.club tracked original-download endpoint

Additional metadata such as thumbnail URL, dimensions, source device, upload time, category, and source format is retained in every generated record. Capability-aware firmware uses the thumbnail metadata directly for the enhanced on-device UI.

Pagination

CrossPoint displays at most 16 catalog items per page and determines whether another page exists by receiving one additional look-ahead item. The generator writes static pages using the same convention as the existing CrossPoint dictionary catalog:

• page 1: items 0..16 — 16 visible + one look-ahead
• page 2: items 16..32
• final page: no extra item

The look-ahead entry becomes the first visible entry on the next page, so no wallpaper is skipped.

Generate catalogs

Requires Python 3.10+ and only the standard library.

Full production refresh:

python tools/build_catalog.py

Fast live smoke run that only reads the first page of each ReadMe.club listing:

python tools/build_catalog.py --max-pages 1

Useful options:

--workers N        concurrent ReadMe.club requests
--timeout SEC      request timeout
--retries N        request attempts
--random-count N   number of items in Random Mix
--random-seed TEXT deterministic Random Mix seed
--pack-months N    number of recent monthly packs
--raw-base URL     public catalog base written into device.json

A full build replaces catalogs/, regenerates wallpapers.crosspoint-plugin/device.json, and writes catalogs/index.json with build statistics.

Hosted assets and cache seed

Generated binary assets are published on the hosted-assets branch using deterministic two-character ID shards. High-quality 1-bit BMP previews live under thumbs/<shard>/<wallpaper-id>.bmp; device-ready converted wallpapers live under wallpapers/<shard>/<wallpaper-id>.bmp when ReadMe.club marks the source as needs_conversion. For example, wallpaper c6a82de5-d681-44ea-99f7-f9805afed042 uses shard c6.

Firmware with plugin-catalog image caching can also use a prebuilt thumbnail seed instead of fetching every first-view thumbnail individually. The seed builder takes up to the first 100 wallpapers from every generated catalog, globally de-duplicates overlapping wallpaper IDs, downloads their thumbnails, and converts them to the same persistent cache filename/layout used by CrossPoint.

The rolling seed is published as a separate pre-release so it does not replace the normal semantic-versioned Plugin Hub release:

• ZIP: https://github.com/jadehawk/wallpapers.crosspoint-plugin/releases/download/cache-seed/wallpaper-cache-seed.zip
• build summary: https://github.com/jadehawk/wallpapers.crosspoint-plugin/releases/download/cache-seed/wallpaper-cache-seed.json

The ZIP contains a .cache/ directory. Extract it into the installed Wallpaper Downloader plugin directory so the result is <plugin>/.cache/. Existing cached images with matching names can be overwritten safely; images outside the seed continue to fill incrementally as catalogs are browsed.

To build the seed locally, install Pillow and run:

python -m pip install "Pillow>=11,<13"
python tools/build_cache_seed.py --limit-per-catalog 100

The GitHub Actions workflow runs a lightweight ReadMe.club inventory check every 3 hours. It compares the reported source total/pages and the newest public wallpaper IDs with the committed catalogs snapshot. When that probe detects a change, the catalogs and live catalogs/index.json are refreshed, missing hosted thumbnail/converted-wallpaper BMPs are added, and the rolling cache seed is rebuilt. Enhanced firmware sees catalog-navigation changes from the live index immediately. The production wallpapers.crosspoint-plugin/device.json is intentionally not rewritten by the automated refresh: its embedded browse.lists snapshot changes only with a plugin release, preserving baseline compatibility. A manual catalog build regenerates that static snapshot from the same catalog specs when preparing a new release.

Tests

python -m unittest discover -s tests -v

The tests cover gallery-data parsing, native row metadata, sensitive-content filtering, CrossPoint page look-ahead behavior, monthly-pack link extraction, month rollover, catalog serialization, and the 8 KiB device.json limit.

Publishing

For Plugin Hub automatic discovery, the repository should be public, carry the crosspoint-plugin GitHub topic, and publish a stable GitHub Release whose tag matches the three-part version in wallpapers.crosspoint-plugin/manifest.json.

The generated catalogs themselves are referenced from the repository's main branch so catalog refreshes can update wallpaper listings without requiring a plugin version bump.