Offline Navigations Review Guide

Status: compressed 13-PR review guide Audience: reviewers of the offline navigations PR stack Published gist: https://gist.github.com/feedthejim/b3d9fe26a7c05655fd57adcce371b93d

This guide is the human map for the compressed offline navigations stack. The resume router for future agents is .private-investigation/offline-navigations-resume.md.

Why This Exists

Offline navigations let a cache-components app keep useful navigation behavior when the network is unavailable. The feature is experimental and gated by experimental.offlineNavigations, which requires cacheComponents and implies useOffline.

The stack is intentionally one continuous sequence. The PR titles use:

offline navigations: <what it does> (n/13)

Architecture In One Minute

The service worker is deliberately boring. It owns document survival only: cache the generated fallback document and manifest, then serve that fallback document for same-origin document navigation network failures.

The service worker does not route, parse Flight, read IndexedDB, synthesize route data, or decide whether a route is cacheable. The client router owns replay semantics.

Cache Storage holds HTTP-shaped fallback artifacts. IndexedDB holds browser-private navigation records: exact URL payloads, route records, segment records, head records, durable epochs, and replay metadata.

On fallback boot, the client first tries an exact URL record. Later PRs hydrate the cache-components route and segment caches from durable records so a prefetched route can replay even if its original HTML document was never loaded. If the client cannot prove the persisted data is complete, fresh, compatible with the current build/deployment/schema, and valid for the current browser scope, it renders a visible miss instead of guessing.

PR Map

Chapter 0: Build Artifacts And Worker Boundary

#93622 offline navigations: add gated build primitives (1/13)
#93624 offline navigations: emit fallback manifest data (2/13)
#93625 offline navigations: register pass-through worker (3/13)
#93626 offline navigations: cache fallback artifacts (4/13)
#93627 offline navigations: serve fallback document offline (5/13)

Review focus: flag shape, generated artifacts, manifest data, service-worker registration, Cache Storage ownership, and the strict worker boundary.

Intentional limit: the worker can only get the app booted into the fallback document. It does not replay route data yet.

Chapter 1: Exact URL Replay

#93630 offline navigations: add persistent navigation cache (6/13)
#93631 offline navigations: replay exact-url navigations (7/13)
#93635 offline navigations: handle exact-url eligibility and invalidation (8/13)

Review focus: IndexedDB primitives, exact URL keys, payload serialization, same-browser replay, request-sensitive replay, freshness, build/schema guards, visible miss diagnostics, and exact URL invalidation.

Intentional limit: this chapter replays URLs that already have valid persisted data. It does not reconstruct a route from prefetched segment records.

Chapter 2: Router Record Replay

#93640 offline navigations: persist router records (9/13)
#93644 offline navigations: hydrate router cache from persisted records (10/13)
#93646 offline navigations: reconstruct prefetched routes offline (11/13)
#93647 offline navigations: support dynamic route patterns (12/13)
#93650 offline navigations: wire invalidation and reset APIs (13/13)

Review focus: durable route table shape, segment/head completeness, hydration order, route reconstruction, dynamic route matching from known routes, fail closed behavior when required records are missing, and durable invalidation mirroring regular router invalidation.

Intentional limit: broader output-export parity, dev simulation, custom miss UI, quota/lifecycle hardening, and large red-team matrices are follow-up work.

Folded Staging PRs

The original 25 draft PRs were staging slices. These PRs are superseded by the 13-PR review stack:

#93623 folded into #93622.
#93628 folded into #93627.
#93632 and #93634 folded into #93631.
#93636, #93637, #93638, and the remaining exact-URL proof from #93639 folded into #93635.
#93641 and #93642 folded into #93640.
#93651 and #93656 folded into #93650.

The branch refs can remain for audit, but reviewers should use the 13 PRs above.

First Usable Cut Line

At the top of this stack, the first usable experimental feature should cover:

flag/config behavior;
fallback document, manifest, generated service worker, and fallback artifact caching;
exact URL offline replay and visible misses;
same-browser request-sensitive replay plus explicit reset;
one fully prefetched route replay with exact URL data absent;
one known dynamic route replay;
missing route, segment, and head visible misses;
build, schema, and freshness guards;
router.refresh(), one mutation/server-action path, and app reset invalidation.

Deferred work:

output-export integration;
dev offline simulation;
custom cache-miss UI;
broad service-worker lifecycle and storage quota hardening;
broader request-shape, workspace, role, and red-team matrices;
docs and examples.

Review Rules

Review the PR claim, not the whole final feature, unless the PR body says the final feature should work at that point.
Every implementation PR should include the tests that prove its own claim.
Later tests may widen the matrix, but should not be the first proof that an earlier PR works.
The service worker should stay limited to document fallback.
The client router should own route semantics and cache-components replay.
Prefer a visible miss over stale, partial, wrong-route, wrong-build, or wrong-scope replay.
Personalized data that already reached this browser can replay while fresh, but app/session reset must make older records unreachable.

Verification Evidence

Compressed branch: work/offline-navigations-compressed-13

Original staging tip preserved: f60949e313

Final compressed tip after DCE cleanup: 474a9986c9

Local evidence gathered before publishing:

git diff --check canary..HEAD
git diff --stat HEAD f60949e313
git diff --name-status HEAD f60949e313
pnpm --filter=next build
pnpm exec jest --runInBand packages/next/src/server/config.test.ts packages/next/src/client/components/router-reducer/offline-navigation-cache.test.ts
NEXT_TEST_MODE=start pnpm testheadless test/production/app-dir/offline-navigations/offline-navigations.test.ts
IS_WEBPACK_TEST=1 NEXT_TEST_MODE=start pnpm testheadless test/production/app-dir/offline-navigations/offline-navigations.test.ts
NEXT_TEST_MODE=start pnpm testheadless test/production/app-dir/offline-navigations/offline-navigations.test.ts -t "does not emit offline navigation artifacts when disabled"
IS_WEBPACK_TEST=1 NEXT_TEST_MODE=start pnpm testheadless test/production/app-dir/offline-navigations/offline-navigations.test.ts -t "does not emit offline navigation artifacts when disabled"

Results:

final compressed tree matches the original staging tip, with no diff output;
git diff --check canary..HEAD passed;
pnpm --filter=next build passed;
focused config/cache unit tests passed, 33/33;
Turbopack production e2e passed, 12/12;
webpack production e2e passed, 12/12;
disabled production builds pass the artifact and client-chunk exclusion check in both Turbopack and webpack.

Per-PR Checklist

Title uses offline navigations: <what it does> (n/13).
Body includes the full ordered stack list and marks the current PR.
Body explains what works after the PR and what intentionally does not work yet.
Body includes reviewer focus, Proof in this PR, Deferred coverage, this review-guide link, and .
Tests live with the PR that claims the behavior.
The service worker never gains route semantics.
Any visible "done" claim is covered by the test or verification evidence in that PR.

feedthejim/offline-navigations-review-guide.md

Select an option

No results found