[pawank925]

Closes #541.

Adds a server-rendered HTML demo page for the latest books in a collection (for client demos), following the access-control/data patterns of catalog.xml/opds.xml.

• GET/HEAD /v1/collections/{collection_id_or_name}/demo.html with ETag support
• backend/src/cms_backend/utils/demo_page.py builds a self-contained HTML page with Download/Browse links
• backend/tests/api/routes/test_collection_demo.py adds route tests (OPDS-style pattern)

I verified Python syntax; I couldn't run the full backend DB-backed test suite locally, but tests follow existing fixtures/patterns. Access control matches catalog/OPDS; happy to adjust (e.g. public/shareable access) per maintainer feedback.

[pawank925]

@benoit74

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.86%. Comparing base (0603f56) to head (edb928a).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #638      +/-   ##
==========================================
+ Coverage   81.66%   81.86%   +0.20%     
==========================================
  Files          86       87       +1     
  Lines        6135     6205      +70     
  Branches      781      791      +10     
==========================================
+ Hits         5010     5080      +70     
  Misses        892      892              
  Partials      233      233              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[pawank925]

@benoit74

[benoit74]

@pawank925 no need to ping me that much, if I don't reply it is only that I'm off or working on something more urgent

I'll park this PR aside because it misses the whole architecture solution ; I think it is mostly OK from CMS perspective but since I still don't know what the overall architecture will be, it is hard to confirm.

What I miss:

• this implementation means we will have one single kiwix-serve serving the "browse" part ; then since we might have multiple client collections at once, it means we need to enhance the catalog-retriever image to be able to retrieve multiple catalogs and "merge" them
• it is also a bit unclear on which server the download part will be possible ; not sure we want the LB or not
• I don't know if we want to just obfuscate the link to these demos or if we want to force clients to create an account on the CMS (pretty concerned it might raise frictions)

In the mean time @pawank925 would you mind to share screenshots of the demo page?

[pawank925]

@benoit74 really so sorry — I'll stop chasing and wait for you.

Screenshots below. They come from this PR's own build_collection_demo_html, called directly on synthetic entries: no backend, no database, no real client catalog. So they show the page, not the data.

One row per name+flavour, keeping only the latest published book, and there is no limit or pagination — a client with 80 titles gets 80 rows. Details is language · date · size · flavour. Download shows when the collection has a download_base_url, Browse when it has a view_base_url and the book isn't mid-transition: the iFixit row above has no Browse and the last row has no illustration, both real states.

This one is a defect in the PR, not in the data: at a 414px viewport the table measures 710px (document.documentElement.scrollWidth), so Details and both buttons fall off-screen and the page scrolls sideways. There's no responsive layout yet — say whether you want it here or in a follow-up.

Browse is per-collection, so a collection without view_base_url degrades to Download-only instead of dead buttons.

On your three points, from the CMS side only:

• one kiwix-serve for browse: the page just concatenates view_base_url + filename-without-.zim, so it inherits whatever browse ends up being and adds no endpoint of its own. Merging catalogs is upstream of this.
• where downloads live: same, download_base_url + subpath + filename, which is what opds.xml already emits. LB or not stays a collection property.
• obfuscate vs accounts: the page is gated by the same get_accessible_collection_ids as catalog.xml/opds.xml — anonymously you only ever see public collections, and a private one gives the 404 page. So "send a client a link, they have no CMS account" does not work today for a private collection, and making it work needs a deliberate exception (scoped token, signed URL, or the collection being public). I'd rather not invent that in this PR; it is the architecture call you're waiting on.

No action needed from you now — leaving it open and parked until the overall shape is decided.