Improve App Viewer catalogue browsing and app details

[saltedlolly]

Important

This is a Draft for visual and local testing.

It is based on the Viewer hardening completed in #797.

#799 must merge before this Viewer can be deployed. That PR updates the Pages build to publish the catalogue provenance and new Viewer assets used here, including readme-images.js, dots@64x64.svg, and github-logo.svg.

This PR deliberately contains no Tronbyt Server connection, “Add Tronbyt Server”, or “Add to Tronbyt” functionality. Server integration remains separate.

Why open this as a Draft now?

This Draft gives maintainers something concrete to inspect and test while #799 is under review. It also demonstrates why the Pages changes in #799 are required before these Viewer improvements can be deployed safely.

The scope is limited to catalogue browsing, app details, author pages, README presentation, feedback links, performance, and navigation.

Catalogue discovery

• Searches app folder names, display names, summaries, descriptions, authors, categories, and manifest tags.
• Changes the default ordering from alphabetical to Last Updated.
• Retains alphabetical and publication-date sorting as alternatives.
• Allows category, display, tag, search, sort, and broken-app filters to be combined.
• Adds display filters for:
  • Standard / 1x
  • Wide / 2x
  • Square
• Uses the correct available screenshot for each selected display.
• Shows a removable, non-editable tag pill inside the search control when arriving from a detail-page tag.
• Removes the redundant tags dropdown.
• Adds a Hide broken apps preference.
• Filters the complete matching catalogue before applying display batching, ensuring valid results are not hidden because they were outside the currently rendered batch.

Catalogue presentation

• Improved responsive design - optimized App Viewer for a better mobile and tablet experience.
• Uses three columns on desktop, two columns on viable wide-phone and small-tablet widths, and one column on narrow phones.
• Uses the shorter App Viewer heading when the full Tronbyt App Viewer heading would not fit.
• Adds consistent Standard, Wide, and Square preview proportions.
• Shows a 2X badge in Standard view when a Wide/2x version is supported.
• Display a compact warning icon beside the app title for broken apps - icon tooltip says Broken app.
• Uses custom pixel-font tooltips for the Wide/2x badge, broken-app warning, and GitHub source icon.

Two-column responsive catalogue	One-column 390px catalogue

Loading and performance

• Initially renders 60 applications.
• Automatically loads the next 60 before the user reaches the bottom using an IntersectionObserver with an advance loading margin.
• Retains an accessible Load more fallback where IntersectionObserver is unavailable.
• Loads catalogue images lazily and decodes them asynchronously.
• Debounces catalogue searches by 150ms.
• Avoids creating a Bootstrap tooltip instance for every catalogue card.
• Limits the number of cards and images in the document instead of rendering the entire catalogue immediately.

Navigation and state restoration

• Preserves search text, category, display, sorting, selected tag, broken-app visibility, loaded batch count, and catalogue scroll position in the catalogue URL.
• Records the current catalogue state before following an image, title, or View Details link.
• Restores the previous position in the catalogue when returning from the app view.
• Preserves useful Back/Forward navigation without persistently storing catalogue data.

App details

• Places the app description immediately below its title.
• Adds a compact metadata layout for author, update interval, publication date, last-updated date, and supported displays.
• Prevents narrow layouts from wrapping metadata one character at a time.
• Makes authors link to generated author pages.
• Makes display capabilities link back to their matching catalogue filters.
• Displays every available preview in a proportional gallery:
  • 64×32
  • 128×64
  • 64×64
• Gives the Wide preview more space where appropriate while preserving the native aspect ratio of every display.
• Adds clickable tag pills above a clearly separated README section.
• Adds a responsive footer containing Back to Apps, Report Issue, and a standalone GitHub source icon.

README handling

• Recognizes mixed-case README filenames such as README.MD and ReadMe.md while preserving the real filename. (This fixed displaying missing README content for six affected apps including jsondisplay.)
• Normalizes relative README image paths.
• Converts GitHub blob image links to their corresponding raw asset URLs.
• Classifies screenshots using exact supported device dimensions and integer scales rather than loose aspect-ratio guesses.
• Applies the optional dot-matrix treatment only to genuine device screenshots, not ordinary README illustrations.
• Resizes README device screenshots to approximately the same useful size as their corresponding detail-page preview.
• Applies referrerpolicy="no-referrer" to external README images.
• Continues sanitizing rendered Markdown through DOMPurify.

Author pages

• NOTE: This was added in previous PR. Groups apps around author: field in manifest.
• Generates dedicated author pages and links to them from app metadata.
• Shows the author’s app count and catalogue cards using the same responsive layouts, preview handling, badges, and broken-app indicators as the main catalogue.
• Preserves navigation back to the catalogue.

Reporting and source links

• Renames Report Broken to Report Issue, allowing it to be used more flexibly for bugs, feedback, and suggestions.
• Prefills the GitHub issue title with the selected app.
• Prefills the issue body with the app folder or validated GitHub folder link.
• Keeps Report Issue disabled for apps already marked as broken and exposes an Already Reported hover/focus explanation.
• Adds the included GitHub icon as a standalone link to the app’s source folder, positioned to the right of Report Issue.
• Opens issue and source links in a new tab with rel="noopener".

Catalogue freshness and provenance

• Fetches apps.json, broken-app data, and catalogue-meta.json with cache: "no-cache" so a new page load revalidates the deployed snapshot.
• Uses only page-lifetime memory caching for catalogue data.
• Validates catalogue provenance before constructing GitHub source links.
• Requires provenance schema version 1, a canonical github.com/<owner>/<repo> identity, and a full hexadecimal commit.
• Supports the official repository and forks without silently assuming that missing or malformed provenance belongs to tronbyt/apps.
• Omits the GitHub source icon when trustworthy provenance is unavailable instead of linking to a guessed repository.
• Treats the catalogue commit as build information only.

The Viewer remains a static snapshot. Its contents update after a successful Pages deployment, not on a timer. A fork with failed or disabled Pages deployments may therefore remain stale.

Generated metadata

The generator now exposes the information required by the revised interface, including:

• Square-display support and 64×64 preview paths.
• Manifest-declared broken state and reason.
• Mixed-case README filenames.
• Author slugs and display metadata used by detail and author pages.

A clean generation produced 1,095 app detail pages and 597 author pages.

Preview locally

Node.js 20 or newer is required.

After checking out this Draft, run:

cd app-viewer
npm ci
npm test
npm run build
npm run serve

Then open:

http://localhost:8888/app-viewer/

Useful pages and checks include:

• Select Standard / 1x, Wide / 2x, and Square from the Display filter.
• Combine a tag, search term, category, display, and sort order.
• Scroll past the first 60 results to test automatic loading.
• Open an app after loading several batches and use Back to Apps to test state and scroll restoration.
• Open an author from an app’s metadata.
• Open details/americanmapbook.html to inspect all three preview layouts and README screenshot sizing.
• Open details/jsondisplay.html to verify its mixed-case README is displayed.
• Open a manifest-marked broken app to inspect its reason and disabled reporting control.

npm run build generates local catalogue, detail-page, and author-page output for the preview. These generated files are development output and should not be committed as part of this PR.

Stop the local server with Ctrl+C when finished.

Deliberately excluded

This PR does not include:

• The Add Tronbyt Server connection flow.
• Add to Tronbyt buttons.
• Server URL validation or saved server records.
• Connection or installation modals.
• Tronbyt Server API integration.
• Integration-only CSS or tests.
• The Pages workflow changes from Prepare App Viewer Pages builds for catalogue and server integration #799.
• Generated apps.json.
• A development app-viewer/apps symlink.
• .devcontainer/devcontainer-lock.json.
• Any changes to Tronbyt Server.

This UI-only Draft can be reviewed and tested independently of the later Viewer/server integration.

Validation

• npm test — 12/12 tests pass.
• node --check main.js passes.
• git diff --check passes.
• Clean generated-site smoke test passes.
• Generated 1,095 detail pages and 597 author pages.
• Pages artifact contains all required local scripts, styles, and icons when tested with Prepare App Viewer Pages builds for catalogue and server integration #799’s build checks.
• Generated artifact was checked for accidental development symlinks, local/LAN URLs, credentials, and test secrets.
• Chrome catalogue-return testing restored an exact 7,688px position after loading 180 cards and settling fonts.

Automated coverage includes:

• Generated metadata escaping inherited from Harden App Viewer metadata generation #797.
• Mixed-case README discovery.
• Saving and restoring catalogue navigation state.
• Official and fork provenance validation without unsafe repository guessing.
• Composed searching, filtering, sorting, broken-app visibility, and display selection.
• README screenshot classification.
• GitHub blob image URL normalization.

[saltedlolly]

@tavdog I appreciate this PR is a lot of changes. If it makes reviewing easier, I can split it up into smaller ones.