docs(lighthouse): MkDocs handbook, PWA/offline, accuracy ledger#78
Merged
Conversation
Adds mkdocs.yml (Material for MkDocs) over the existing docs/ tree, and replaces pages.yml with a combined web.yml: the wasm demo at /, rustdoc at /api/, and the new MkDocs handbook at /docs/, all deployed together. The existing <5MiB gzip wasm size budget (scripts/wasm_size_budget.sh) now also gates PRs, not just push-to-main. The wasm demo gains PWA/offline support: manifest.webmanifest, a real icon.svg (replacing the inline-SVG-only favicon for install-icon purposes), and a stale-while-revalidate sw.js service worker. New docs/accuracy-ledger.md maps every known approximation/divergence to an explicit disposition (Remediated / No-stricter-oracle-available / Deferred / Out-of-scope), extracted from docs/STATUS.md's existing dashboard content -- the "why" companion to that pass-count scoreboard. One item is honestly flagged as not-yet-implemented (a SNES-appropriate Holy-Mapperel-style regression net for the unit-test-only coprocessor boards) rather than overclaimed. docs/DOCUMENTATION_INDEX.md refreshed: was still stamped v0.4.0, linked a SALVAGE_MANIFEST.md that doesn't exist, and undercounted the ADR directory. Second release of the RustyNES-parity roadmap (to-dos/VERSION-PLAN.md). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
|
Warning You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again! |
There was a problem hiding this comment.
Pull request overview
This PR introduces a consolidated GitHub Pages build/deploy pipeline that publishes three artifacts together (wasm demo at /, rustdoc at /api/, and a new Material for MkDocs handbook at /docs/), adds PWA/offline support to the wasm demo, and documents known accuracy residuals in a dedicated “accuracy ledger” page.
Changes:
- Add MkDocs (Material) configuration over the existing
docs/tree and publish it under/docs/. - Replace the previous Pages workflow with a combined
web.ymlbuild that also enforces the existing<5MiBgzip wasm size budget on PRs. - Add PWA/offline assets (manifest, icon, service worker) and wire them into the wasm demo entry page; update documentation index + changelog accordingly.
Reviewed changes
Copilot reviewed 13 out of 14 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
to-dos/VERSION-PLAN.md |
Marks “Lighthouse” as in progress and itemizes the deliverables added by this PR. |
scripts/wasm_size_budget.sh |
Adds a gzip-based wasm/JS size budget gate script (with optional brotli reporting). |
README.md |
Updates the Pages badge text to reflect demo + rustdoc + docs. |
mkdocs.yml |
Adds Material for MkDocs configuration and curated navigation for the docs/ tree. |
docs/frontend.md |
Updates hosted demo deployment reference from pages.yml to web.yml. |
docs/DOCUMENTATION_INDEX.md |
Refreshes version stamp and index links; adds references to new docs/ledger pages. |
docs/accuracy-ledger.md |
Adds a new ledger mapping known residuals/validation gaps to explicit dispositions. |
crates/rustysnes-frontend/web/sw.js |
Adds a stale-while-revalidate service worker for the wasm demo. |
crates/rustysnes-frontend/web/manifest.webmanifest |
Adds a web app manifest for PWA install metadata. |
crates/rustysnes-frontend/web/index.html |
Wires in manifest/icon/service worker registration and trunk copy-file directives. |
crates/rustysnes-frontend/web/icon.svg |
Adds an SVG app icon used by the manifest/apple-touch-icon. |
CHANGELOG.md |
Documents the new docs site + PWA/offline + accuracy ledger under Unreleased. |
.github/workflows/web.yml |
New combined workflow to build wasm + rustdoc + MkDocs and deploy as one Pages artifact. |
.github/workflows/pages.yml |
Removes the old Pages workflow superseded by web.yml. |
Comment on lines
+59
to
+61
| concurrency: | ||
| group: pages-${{ github.ref }} | ||
| cancel-in-progress: ${{ github.event_name != 'push' }} |
Owner
Author
There was a problem hiding this comment.
Fixed in 26e58eb: cancel-in-progress now reads github.event_name == 'push', matching the stated intent (cancel stale main pushes, let PR size-budget checks finish).
Comment on lines
+41
to
+49
| const network = fetch(request) | ||
| .then((response) => { | ||
| if (response && response.ok) { | ||
| cache.put(request, response.clone()); | ||
| } | ||
| return response; | ||
| }) | ||
| .catch(() => cached); | ||
| return cached || network; |
Owner
Author
There was a problem hiding this comment.
Fixed in 26e58eb: the catch handler now falls back to a synthetic 503 Response when both the network fetch fails and nothing is cached yet, instead of resolving to undefined.
…llback Copilot review: web.yml's cancel-in-progress was inverted relative to its own comment (PR runs got cancelled mid-flight; stale main pushes didn't). Fixed to cancel-in-progress: github.event_name == 'push', matching stated intent. sw.js's fetch handler could resolve respondWith() to undefined on a truly offline first visit (network fails AND nothing cached yet) since .catch(() => cached) returned undefined in that case. Now falls back to a synthetic 503 Response instead. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
mkdocs.yml(Material for MkDocs) over the existingdocs/tree.pages.ymlwith a combinedweb.yml: wasm demo at/, rustdoc at/api/, MkDocs handbook at/docs/, one deployment. The existing<5MiBgzip size budget (scripts/wasm_size_budget.sh) now also gates PRs (build-only, no deploy), not just push-to-main.manifest.webmanifest, a realicon.svg, a stale-while-revalidatesw.jsservice worker.docs/accuracy-ledger.md— every known approximation/divergence mapped to an explicit disposition, extracted fromdocs/STATUS.md's existing dashboard content.docs/DOCUMENTATION_INDEX.mdrefresh (was stampedv0.4.0, linked a nonexistentSALVAGE_MANIFEST.md, undercounted the ADR directory).to-dos/VERSION-PLAN.md).Type of change
Acceptance criteria
web.yml/mkdocs.ymlvalid YAML;manifest.webmanifestvalid JSON;wasm_size_budget.shpassesbash -nweb.yml'sbuildjob actually succeeds on this PR (first real exercise of the MkDocs build + size-budget gate)Notes for reviewer
docs/accuracy-ledger.mdhonestly flags one item as not-yet-implemented (a Holy-Mapperel-style regression net for the 3 unit-test-only coprocessor boards) rather than claiming something that isn't scoped in any release yet.