WebPub parsing improvements

[chocolatkey]

WebPub parsing has been lacking in the toolkit. This PR vastly improves WebPub parsing, especially exploded (not archived, but in a folder) WebPub parsing. A particular case that needed a lot of changes in WebPubs where the manifest is in a folder that is not the root of the publication, so you have resources with hrefs like ../audio/file.mp3. The sniffers have also gotten improvements for detecting WebPub and co.
(note: many changes by Claude Fable)

[Copilot]

Pull request overview

This PR improves Readium Web Publication (RWPM/WebPub) handling across the toolkit, with a focus on correctly parsing and serving “exploded” (directory-based) publications where the manifest may live in a subfolder and references resources via ../ HREFs. It also strengthens media type sniffing for RWPM-based formats and improves fetcher path handling (local + cloud).

Changes:

• Improve file:// URL ↔ filepath conversions (Windows drive handling, absolute file URL construction, directory-trailing-slash preservation).
• Implement robust parsing for bare RWPM manifests (local + HTTP), including exploded-layout HREF normalization and resource fetching (relative + absolute HTTP(S)).
• Add heavy sniffing for RWPM/WebPub + OPDS2 via JSON heuristics; tighten fetcher key/path resolution (File/S3/GCS) and add tests.

Reviewed changes

Copilot reviewed 33 out of 33 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
pkg/util/url/url.go	Fixes file URL ↔ filepath conversions (Windows drive paths; rooted file URLs; trailing “directory” slash semantics).
pkg/util/url/url_test.go	Adds regression tests for file URL ↔ filepath behavior.
pkg/parser/webpub/testdata/pdf/pdf.webpub	Adds PDF WebPub fixture (Git LFS pointer).
pkg/parser/webpub/testdata/audio/manifest.json	Adds audiobook RWPM manifest fixture.
pkg/parser/webpub/testdata/audio/manifest_notaudiobook.json	Adds negative audiobook conformance fixture.
pkg/parser/webpub/testdata/audio/manifest_noconform3.json	Adds audiobook conformance fixture variant (minimal metadata).
pkg/parser/webpub/testdata/audio/manifest_noconform2.json	Adds audiobook conformance fixture variant.
pkg/parser/webpub/testdata/audio/manifest_noconform1.json	Adds audiobook conformance fixture variant.
pkg/parser/webpub/testdata/audio/art_letters.audiobook	Adds audiobook package fixture (Git LFS pointer).
pkg/parser/webpub/parser.go	Implements improved RWPM/WebPub parsing (bare manifests, exploded layout normalization, service factories, conformance checks).
pkg/parser/webpub/parser_test.go	Adds end-to-end tests for bare manifests, exploded layouts, HTTP fetching, and service factories.
pkg/parser/webpub/fetcher.go	Adds a fetcher wrapper for bare manifests: relative resources via relative fetcher, absolute HTTP(S) via HTTP client.
pkg/mediatype/sniffer.go	Adds heavy OPDS2 sniffing via JSON; adds heavy RWPM/WebPub sniffing from JSON or manifest.json in packages.
pkg/mediatype/sniffer_test.go	Expands sniffer tests (RWPM/OPDS fixtures, invalid RWPM rejection, non-seekable stream behavior).
pkg/mediatype/sniffer_rwpm.go	Introduces RWPM JSON “duck-typing” helpers to avoid manifest↔mediatype circular dependencies.
pkg/mediatype/sniffer_context.go	Updates sniffer content handling to work with shared buffered file content (pointer semantics).
pkg/mediatype/sniffer_content.go	Changes file sniffer content to pointer-based sharing so buffering works for non-seekable files.
pkg/mediatype/mediatype_of.go	Reorders sniffers to ensure OPDS2 beats RWPM heuristics and RWPM beats generic archive sniffing.
pkg/manifest/transform.go	Adds manifest/link-tree HREF transformation helper to support exploded-layout normalization.
pkg/fetcher/fetcher_s3.go	Decodes HREF path + drops query/fragment for S3 key lookups.
pkg/fetcher/fetcher_http.go	Adds NewHTTPResource constructor for fetching a single absolute HTTP(S) URL.
pkg/fetcher/fetcher_gcs.go	Decodes HREF path + drops query/fragment for GCS object name lookups.
pkg/fetcher/fetcher_file.go	Hardens local path sandbox check to prevent prefix-collision escapes (e.g. pub vs pub-secret).
pkg/fetcher/fetcher_file_test.go	Adds regression test for prefix-collision directory escape.
pkg/fetcher/fetcher_file_relative.go	Adds local “web-style” relative resolution fetcher for exploded manifests.
pkg/fetcher/fetcher_file_relative_test.go	Adds tests for RelativeFileFetcher behavior (siblings, .., query/fragment dropping).
pkg/fetcher/fetcher_cloud_test.go	Adds tests ensuring S3/GCS lookups use decoded paths and drop query/fragment.
pkg/asset/asset_s3.go	Implements RelativePublicationAsset for S3 assets to support bare-manifest relative fetching.
pkg/asset/asset_publication.go	Introduces RelativePublicationAsset interface for assets that can serve resources relative to their own location.
pkg/asset/asset_http.go	Implements RelativePublicationAsset for HTTP assets (root-relative fetching).
pkg/asset/asset_gcs.go	Implements RelativePublicationAsset for GCS assets to support bare-manifest relative fetching.
pkg/asset/asset_file.go	Implements RelativePublicationAsset for file assets and fixes Windows drive handling in file URLs.
pkg/archive/archive.go	Uses file URL → filepath conversion when opening archives/exploded directories (improves Windows correctness).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 34 out of 34 changed files in this pull request and generated 2 comments.