Skip to content

offline navigations: reconstruct prefetched routes offline (11/13)#93646

Closed
feedthejim wants to merge 11 commits intofeedthejim/offline-navigations-hydrate-router-cachesfrom
feedthejim/offline-navigations-reconstruct-prefetched-routes
Closed

offline navigations: reconstruct prefetched routes offline (11/13)#93646
feedthejim wants to merge 11 commits intofeedthejim/offline-navigations-hydrate-router-cachesfrom
feedthejim/offline-navigations-reconstruct-prefetched-routes

Conversation

@feedthejim
Copy link
Copy Markdown
Contributor

@feedthejim feedthejim commented May 8, 2026

Stack Position

This is PR 11/13 in the compressed offline navigations stack. Chapter: Router record replay.

Review guide: https://gist.github.com/feedthejim/b3d9fe26a7c05655fd57adcce371b93d

Full Stack

  1. #93622 offline navigations: add gated build primitives (1/13)
  2. #93624 offline navigations: emit fallback manifest data (2/13)
  3. #93625 offline navigations: register pass-through worker (3/13)
  4. #93626 offline navigations: cache fallback artifacts (4/13)
  5. #93627 offline navigations: serve fallback document offline (5/13)
  6. #93630 offline navigations: add persistent navigation cache (6/13)
  7. #93631 offline navigations: replay exact-url navigations (7/13)
  8. #93635 offline navigations: handle exact-url eligibility and invalidation (8/13)
  9. #93640 offline navigations: persist router records (9/13)
  10. #93644 offline navigations: hydrate router cache from persisted records (10/13)
  11. #93646 offline navigations: reconstruct prefetched routes offline (11/13) current
  12. #93647 offline navigations: support dynamic route patterns (12/13)
  13. #93650 offline navigations: wire invalidation and reset APIs (13/13)

Context

The original offline navigations work was split into 25 staging PRs, which made the review surface too noisy. This compressed stack keeps the same first-usable feature at the tip, but groups the work by reviewer-facing behavior: build artifacts first, exact URL replay next, then route-record replay and invalidation.

The architecture boundary is intentional: the generated service worker keeps the app bootable by serving the fallback document, while the cache-components client router owns IndexedDB, replay eligibility, route reconstruction, visible misses, and invalidation.

Folded source PRs: None.

What This PR Does

  • Reconstructs a fully prefetched route from persisted router records when exact URL data is absent.
  • Uses the same cache-components route/segment/head data the regular router would use.
  • Keeps missing-record cases visible instead of synthesizing partial UI.

What Works After This PR

After this PR, a fully prefetched route can hard-load offline even if its original HTML document was never loaded.

What Intentionally Does Not Work Yet

Dynamic route pattern matching is still limited until the next PR.

Reviewer Focus

The handoff from persisted records to router state, exact-URL miss fallback, and destructive missing-record coverage.

Proof in This PR

  • Focused production e2e passed in Turbopack and webpack modes.
  • The suite includes reconstructs a fully prefetched route from persisted router records and the missing head-record miss case.
  • git diff --check canary..HEAD passed.
  • git diff --stat HEAD f60949e313 and git diff --name-status HEAD f60949e313 produced no output, so the compressed tip preserves the previous staging tip.
  • pnpm --filter=next build passed.
  • NEXT_TEST_MODE=start pnpm testheadless test/production/app-dir/offline-navigations/offline-navigations.test.ts passed, 12/12.
  • IS_WEBPACK_TEST=1 NEXT_TEST_MODE=start pnpm testheadless test/production/app-dir/offline-navigations/offline-navigations.test.ts passed, 12/12.

Deferred Coverage

Known dynamic route patterns are owned by PR 12/13.

@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 8, 2026

@feedthejim feedthejim force-pushed the feedthejim/offline-navigations-hydrate-router-caches branch from b18a178 to 6caa377 Compare May 8, 2026 08:18
@feedthejim feedthejim force-pushed the feedthejim/offline-navigations-reconstruct-prefetched-routes branch from 2be5937 to 5566f16 Compare May 8, 2026 08:18
@feedthejim feedthejim force-pushed the feedthejim/offline-navigations-hydrate-router-caches branch from 6caa377 to 221b216 Compare May 8, 2026 08:34
@feedthejim feedthejim force-pushed the feedthejim/offline-navigations-reconstruct-prefetched-routes branch from 5566f16 to a53b5ca Compare May 8, 2026 08:34
@feedthejim feedthejim force-pushed the feedthejim/offline-navigations-hydrate-router-caches branch from 221b216 to f670ded Compare May 8, 2026 17:46
@feedthejim feedthejim force-pushed the feedthejim/offline-navigations-reconstruct-prefetched-routes branch from a53b5ca to 61e7b42 Compare May 8, 2026 17:46
@feedthejim feedthejim changed the title (5/7) Reconstruct fully prefetched routes offline offline navigations: reconstruct prefetched routes offline (21/25) May 8, 2026
@github-actions
Copy link
Copy Markdown
Contributor

github-actions Bot commented May 8, 2026

Stats from current PR

🔴 1 regression

Metric Canary PR Change Trend
node_modules Size 505 MB 507 MB 🔴 +2.48 MB (+0%) ▁▁▁██
📊 All Metrics
📖 Metrics Glossary

Dev Server Metrics:

  • Listen = TCP port starts accepting connections
  • First Request = HTTP server returns successful response
  • Cold = Fresh build (no cache)
  • Warm = With cached build artifacts

Build Metrics:

  • Fresh = Clean build (no .next directory)
  • Cached = With existing .next directory

Change Thresholds:

  • Time: Changes < 50ms AND < 10%, OR < 2% are insignificant
  • Size: Changes < 1KB AND < 1% are insignificant
  • All other changes are flagged to catch regressions

⚡ Dev Server

Metric Canary PR Change Trend
Cold (Listen) 813ms 810ms ▁▅▅▃▅
Cold (Ready in log) 791ms 781ms ▆█▂▁▄
Cold (First Request) 1.273s 1.218s ▄▆▂▂▅
Warm (Listen) 811ms 811ms ▁▆▆▃▃
Warm (Ready in log) 785ms 787ms ▆█▂▂▄
Warm (First Request) 609ms 603ms ▇█▂▃▅
📦 Dev Server (Webpack) (Legacy)

📦 Dev Server (Webpack)

Metric Canary PR Change Trend
Cold (Listen) 811ms 811ms █████
Cold (Ready in log) 773ms 773ms ▇▇███
Cold (First Request) 3.139s 3.145s ▇▅▄██
Warm (Listen) 811ms 810ms █████
Warm (Ready in log) 772ms 773ms ▇▆▇██
Warm (First Request) 3.174s 3.167s ▅▃▃▇█

⚡ Production Builds

Metric Canary PR Change Trend
Fresh Build 4.931s 4.871s █▆▁▁▆
Cached Build 4.861s 4.857s ▆▅▁▄▅
📦 Production Builds (Webpack) (Legacy)

📦 Production Builds (Webpack)

Metric Canary PR Change Trend
Fresh Build 23.633s 23.812s ▅▆▅██
Cached Build 23.526s 23.799s ▄▄▆▆█
node_modules Size 505 MB 507 MB 🔴 +2.48 MB (+0%) ▁▁▁██
📦 Bundle Sizes

Bundle Sizes

⚡ Turbopack

Client

Main Bundles
Canary PR Change
0-_gc56kf9tfo.js gzip 154 B N/A -
047ad-p-61fjn.js gzip 156 B N/A -
04hm05ar7kldw.js gzip 5.73 kB N/A -
0714gv_gbisrs.js gzip 70.8 kB N/A -
0cz1d0mv5g_q7.js gzip 39.4 kB 39.4 kB
0dvitrl5zg37g.js gzip 8.82 kB N/A -
0sf7ysou-72zd.js gzip 8.71 kB N/A -
11ny9t-iyn9yw.js gzip 154 B N/A -
157abun3hwc_s.js gzip 10.3 kB N/A -
1bhal_i5byhy7.js gzip 162 B N/A -
1elt1qium-r2m.css gzip 115 B 115 B
1jfwzy3ri2pyr.js gzip 154 B N/A -
1jj68jv9537mc.js gzip 13.8 kB N/A -
1jpaub6y8xlfr.js gzip 2.3 kB N/A -
1ot0mvscrc_uf.js gzip 233 B N/A -
2_m3xv2uq3sjc.js gzip 1.46 kB N/A -
224i1-g0lqvss.js gzip 49.5 kB N/A -
24y34mwgrkqp4.js gzip 8.78 kB N/A -
28lrkt28g7fpx.js gzip 155 B N/A -
2c-fd4y1zozz8.js gzip 8.79 kB N/A -
2d7416h_xd36x.js gzip 8.71 kB N/A -
2extn3odmmem_.js gzip 12.9 kB N/A -
2fyhyy7niw9r6.js gzip 7.61 kB N/A -
2lyuhit6rn8fy.js gzip 9.44 kB N/A -
2q0gr8wfr3jwl.js gzip 8.77 kB N/A -
2qmtk0zius6fd.js gzip 157 B N/A -
2t9e75oz6r0zp.js gzip 8.76 kB N/A -
2uku_olcn15b7.js gzip 8.79 kB N/A -
30r8mm-46bdqy.js gzip 220 B 220 B
3c03ks8ic59bl.js gzip 160 B N/A -
3c03yiy5ds-h6.js gzip 65.5 kB N/A -
3d0blqiuhma_c.js gzip 155 B N/A -
3inab2jybr4k9.js gzip 450 B N/A -
3jkm5tdjvaf_q.js gzip 13.1 kB N/A -
3mix8ikliw_bj.js gzip 169 B N/A -
3mt67agm5wp40.js gzip 10.6 kB N/A -
3saabek4kohwi.js gzip 10 kB N/A -
3x_ftwxjtc4jr.js gzip 152 B N/A -
3x0-g47j0wg_t.js gzip 154 B N/A -
40pcd44z40i4a.js gzip 156 B N/A -
4189xmby9yu1p.js gzip 13.6 kB N/A -
turbopack-02..93y4.js gzip 4.2 kB N/A -
turbopack-0m..eii3.js gzip 4.2 kB N/A -
turbopack-0t..cm46.js gzip 4.2 kB N/A -
turbopack-13..1jkn.js gzip 4.2 kB N/A -
turbopack-1m..-lpg.js gzip 4.18 kB N/A -
turbopack-1s..s1zo.js gzip 4.21 kB N/A -
turbopack-23..--2_.js gzip 4.2 kB N/A -
turbopack-28..zluk.js gzip 4.2 kB N/A -
turbopack-2a..kxyc.js gzip 4.2 kB N/A -
turbopack-2s..sur4.js gzip 4.2 kB N/A -
turbopack-2z..x5dq.js gzip 4.19 kB N/A -
turbopack-3h..65h_.js gzip 4.2 kB N/A -
turbopack-3s..rdjl.js gzip 4.2 kB N/A -
turbopack-3y..gfl4.js gzip 4.2 kB N/A -
0_i7nqgx23st7.js gzip N/A 10 kB -
05e40c15cx1dd.js gzip N/A 7.61 kB -
06puhytyxk31p.js gzip N/A 8.82 kB -
0cgwxw9wez5uz.js gzip N/A 155 B -
0m34gln_kt4fg.js gzip N/A 5.73 kB -
0rwd_euato9jf.js gzip N/A 53.4 kB -
0wjn_zvopg8j7.js gzip N/A 155 B -
14pebosrr9pmi.js gzip N/A 71.4 kB -
1g3q1ww01thnl.js gzip N/A 2.3 kB -
1hraqxuiymq6v.js gzip N/A 8.79 kB -
1l9un1sl77287.js gzip N/A 1.46 kB -
1oj2783a6mjmk.js gzip N/A 153 B -
1tu42mhgspxaj.js gzip N/A 152 B -
2_n5io6i3e7-d.js gzip N/A 65.6 kB -
21-eavqb1k_36.js gzip N/A 13.9 kB -
2147zgtf14z-q.js gzip N/A 234 B -
23bz3xsg-5-1s.js gzip N/A 8.71 kB -
25m28ppgv1r-l.js gzip N/A 156 B -
27441mytv7pbm.js gzip N/A 9.43 kB -
2cjkwjgm1zcfs.js gzip N/A 8.71 kB -
2feeljlwn03ka.js gzip N/A 156 B -
2scd8zaoyb8md.js gzip N/A 8.79 kB -
2st_qs6p_9us0.js gzip N/A 13.1 kB -
2zo2exm1d8qj1.js gzip N/A 13.6 kB -
31gszfpoi49o_.js gzip N/A 157 B -
3g88fx8gbrpbb.js gzip N/A 159 B -
3hn75zuxly9az.js gzip N/A 10.3 kB -
3hqh7m128tvsn.js gzip N/A 8.77 kB -
3hqti_t-zy1x4.js gzip N/A 449 B -
3k_ox9mqvj991.js gzip N/A 162 B -
3lwd3rbxfr02f.js gzip N/A 157 B -
3mnawenie1flm.js gzip N/A 8.76 kB -
3sxqvx3vn2_or.js gzip N/A 155 B -
3ubsozlu6zs38.js gzip N/A 10.6 kB -
41_yhm_31fcf8.js gzip N/A 155 B -
41mf-x3mmsxae.js gzip N/A 12.9 kB -
41ovqpfyyufzz.js gzip N/A 168 B -
43iwfqjnx1cy_.js gzip N/A 8.78 kB -
turbopack-0g..-9g6.js gzip N/A 4.2 kB -
turbopack-1b..n71_.js gzip N/A 4.2 kB -
turbopack-1e..hu78.js gzip N/A 4.2 kB -
turbopack-1g..7-n-.js gzip N/A 4.2 kB -
turbopack-1l..qd49.js gzip N/A 4.21 kB -
turbopack-1t..oruv.js gzip N/A 4.2 kB -
turbopack-2q..tzzk.js gzip N/A 4.2 kB -
turbopack-2s..khje.js gzip N/A 4.2 kB -
turbopack-31..xepd.js gzip N/A 4.2 kB -
turbopack-3q..wh7s.js gzip N/A 4.2 kB -
turbopack-3t..pfdy.js gzip N/A 4.2 kB -
turbopack-3y..qhsx.js gzip N/A 4.2 kB -
turbopack-41..nbac.js gzip N/A 4.18 kB -
turbopack-43..rc4q.js gzip N/A 4.2 kB -
Total 468 kB 473 kB ⚠️ +4.49 kB

Server

Middleware
Canary PR Change
middleware-b..fest.js gzip 716 B 715 B
Total 716 B 715 B ✅ -1 B
Build Details
Build Manifests
Canary PR Change
_buildManifest.js gzip 429 B 433 B
Total 429 B 433 B ⚠️ +4 B

📦 Webpack

Client

Main Bundles
Canary PR Change
2258-HASH.js gzip 61.1 kB N/A -
2266-HASH.js gzip 4.69 kB N/A -
3317.HASH.js gzip 169 B N/A -
4866-HASH.js gzip 5.64 kB N/A -
9e302639-HASH.js gzip 62.7 kB N/A -
framework-HASH.js gzip 59.5 kB 59.5 kB
main-app-HASH.js gzip 255 B 254 B
main-HASH.js gzip 39.9 kB 39.9 kB
webpack-HASH.js gzip 1.68 kB 1.68 kB
175fd0fd-HASH.js gzip N/A 62.7 kB -
2596-HASH.js gzip N/A 5.63 kB -
34-HASH.js gzip N/A 65.4 kB -
5691.HASH.js gzip N/A 169 B -
9156-HASH.js gzip N/A 4.68 kB -
Total 236 kB 240 kB ⚠️ +4.26 kB
Polyfills
Canary PR Change
polyfills-HASH.js gzip 39.4 kB 39.4 kB
Total 39.4 kB 39.4 kB
Pages
Canary PR Change
_app-HASH.js gzip 193 B 193 B
_error-HASH.js gzip 181 B 182 B
css-HASH.js gzip 334 B 332 B
dynamic-HASH.js gzip 1.79 kB 1.81 kB
edge-ssr-HASH.js gzip 255 B 255 B
head-HASH.js gzip 351 B 348 B
hooks-HASH.js gzip 385 B 384 B
image-HASH.js gzip 580 B 580 B
index-HASH.js gzip 257 B 259 B
link-HASH.js gzip 2.51 kB 2.52 kB
routerDirect..HASH.js gzip 318 B 319 B
script-HASH.js gzip 387 B 386 B
withRouter-HASH.js gzip 316 B 316 B
1afbb74e6ecf..834.css gzip 106 B 106 B
Total 7.97 kB 7.99 kB ⚠️ +19 B

Server

Edge SSR
Canary PR Change
edge-ssr.js gzip 126 kB 126 kB
page.js gzip 275 kB 273 kB 🟢 2.14 kB (-1%)
Total 401 kB 399 kB ✅ -2.36 kB
Middleware
Canary PR Change
middleware-b..fest.js gzip 615 B 615 B
middleware-r..fest.js gzip 155 B 155 B
middleware.js gzip 44.4 kB 44.5 kB
edge-runtime..pack.js gzip 842 B 842 B
Total 46.1 kB 46.1 kB ⚠️ +47 B
Build Details
Build Manifests
Canary PR Change
_buildManifest.js gzip 719 B 717 B
Total 719 B 717 B ✅ -2 B
Build Cache
Canary PR Change
0.pack gzip 4.45 MB 4.5 MB 🔴 +53.1 kB (+1%)
index.pack gzip 114 kB 117 kB 🔴 +2.98 kB (+3%)
index.pack.old gzip 113 kB 116 kB 🔴 +2.81 kB (+2%)
Total 4.68 MB 4.74 MB ⚠️ +58.9 kB

🔄 Shared (bundler-independent)

Runtimes
Canary PR Change
app-page-exp...dev.js gzip 349 kB 355 kB 🔴 +5.35 kB (+2%)
app-page-exp..prod.js gzip 194 kB 198 kB 🔴 +4.01 kB (+2%)
app-page-tur...dev.js gzip 349 kB 354 kB 🔴 +5.36 kB (+2%)
app-page-tur..prod.js gzip 194 kB 198 kB 🔴 +4.01 kB (+2%)
app-page-tur...dev.js gzip 345 kB 351 kB 🔴 +5.29 kB (+2%)
app-page-tur..prod.js gzip 192 kB 196 kB 🔴 +4 kB (+2%)
app-page.run...dev.js gzip 346 kB 351 kB 🔴 +5.31 kB (+2%)
app-page.run..prod.js gzip 192 kB 196 kB 🔴 +4 kB (+2%)
app-route-ex...dev.js gzip 77.5 kB 77.5 kB
app-route-ex..prod.js gzip 52.9 kB 52.9 kB
app-route-tu...dev.js gzip 77.6 kB 77.6 kB
app-route-tu..prod.js gzip 52.9 kB 52.9 kB
app-route-tu...dev.js gzip 77.2 kB 77.2 kB
app-route-tu..prod.js gzip 52.7 kB 52.7 kB
app-route.ru...dev.js gzip 77.1 kB 77.1 kB
app-route.ru..prod.js gzip 52.7 kB 52.7 kB
dist_client_...dev.js gzip 324 B 324 B
dist_client_...dev.js gzip 326 B 326 B
dist_client_...dev.js gzip 318 B 318 B
dist_client_...dev.js gzip 317 B 317 B
pages-api-tu...dev.js gzip 44.3 kB 44.3 kB
pages-api-tu..prod.js gzip 33.8 kB 33.8 kB
pages-api.ru...dev.js gzip 44.3 kB 44.3 kB
pages-api.ru..prod.js gzip 33.7 kB 33.7 kB
pages-turbo....dev.js gzip 53.7 kB 53.7 kB
pages-turbo...prod.js gzip 39.4 kB 39.4 kB
pages.runtim...dev.js gzip 53.6 kB 53.6 kB
pages.runtim..prod.js gzip 39.3 kB 39.3 kB
server.runti..prod.js gzip 63.2 kB 63.2 kB
use-cache-pr...dev.js gzip 69.7 kB 69.7 kB
use-cache-pr...dev.js gzip 69.7 kB 69.7 kB
use-cache-pr...dev.js gzip 68 kB 68 kB
use-cache-pr...dev.js gzip 68 kB 68 kB
Total 3.36 MB 3.4 MB ⚠️ +37.3 kB
📝 Changed Files (9 files)

Files with changes:

  • app-page-exp..ntime.dev.js
  • app-page-exp..time.prod.js
  • app-page-tur..ntime.dev.js
  • app-page-tur..time.prod.js
  • app-page-tur..ntime.dev.js
  • app-page-tur..time.prod.js
  • app-page.runtime.dev.js
  • app-page.runtime.prod.js
  • server.runtime.prod.js
View diffs
app-page-exp..ntime.dev.js
failed to diff
app-page-exp..time.prod.js
failed to diff
app-page-tur..ntime.dev.js
failed to diff
app-page-tur..time.prod.js
failed to diff
app-page-tur..ntime.dev.js
failed to diff
app-page-tur..time.prod.js
failed to diff
app-page.runtime.dev.js
failed to diff
app-page.runtime.prod.js
failed to diff
server.runtime.prod.js

Diff too large to display

📎 Tarball URL
https://vercel-packages.vercel.app/next/commits/a9369076eb4f9451d87911affba25262e42ae3a6/next

Commit: a936907

@feedthejim feedthejim force-pushed the feedthejim/offline-navigations-reconstruct-prefetched-routes branch from 61e7b42 to a936907 Compare May 8, 2026 20:30
@feedthejim feedthejim force-pushed the feedthejim/offline-navigations-hydrate-router-caches branch from f670ded to 3507830 Compare May 8, 2026 20:30
@feedthejim feedthejim changed the title offline navigations: reconstruct prefetched routes offline (21/25) offline navigations: reconstruct prefetched routes offline (11/13) May 8, 2026
@feedthejim feedthejim force-pushed the feedthejim/offline-navigations-reconstruct-prefetched-routes branch from a936907 to 483e081 Compare May 8, 2026 23:27
@feedthejim feedthejim force-pushed the feedthejim/offline-navigations-hydrate-router-caches branch 2 times, most recently from fafaefd to 729b785 Compare May 9, 2026 00:05
@feedthejim feedthejim force-pushed the feedthejim/offline-navigations-reconstruct-prefetched-routes branch 2 times, most recently from 29d0490 to d3a3108 Compare May 10, 2026 15:41
@feedthejim feedthejim force-pushed the feedthejim/offline-navigations-hydrate-router-caches branch from 003cef8 to 5bdc788 Compare May 10, 2026 15:59
@feedthejim feedthejim force-pushed the feedthejim/offline-navigations-reconstruct-prefetched-routes branch from d3a3108 to 9682004 Compare May 10, 2026 15:59
@feedthejim feedthejim force-pushed the feedthejim/offline-navigations-hydrate-router-caches branch from 5bdc788 to 5d7a3d7 Compare May 10, 2026 17:16
@feedthejim feedthejim force-pushed the feedthejim/offline-navigations-reconstruct-prefetched-routes branch from 9682004 to 235cdb4 Compare May 10, 2026 17:16
@feedthejim feedthejim force-pushed the feedthejim/offline-navigations-hydrate-router-caches branch from 5d7a3d7 to 3912e67 Compare May 10, 2026 17:42
@feedthejim feedthejim force-pushed the feedthejim/offline-navigations-reconstruct-prefetched-routes branch from 235cdb4 to 2b33f40 Compare May 10, 2026 17:42
@feedthejim feedthejim force-pushed the feedthejim/offline-navigations-hydrate-router-caches branch from 2b33f40 to a05b5dc Compare May 10, 2026 18:45
@feedthejim
Copy link
Copy Markdown
Contributor Author

Closing this draft because the stack was compressed into the router-cache based 10-PR sequence. The exact-url replay slice was removed; reconstruction now lands in the fallback bootstrap PR.

@feedthejim feedthejim closed this May 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant