[pdcruze]

What happened

An app built with flutter build web --no-web-resources-cdn still loaded its engine from Google's CDN. Every load, returning visits included, began with a cache: "no-store" Range: bytes=0-0 request to www.gstatic.com/flutter-canvaskit/<engineRevision>/<variant>.js before the engine download could start (175 ms in a production trace), and the engine then came from gstatic anyway. The canvaskit/ files the build deploys were never requested, so the service worker never cached them.

Root cause

Flutter records the flag as "useLocalCanvasKit": true in _flutter.buildConfig. extractFlutterBuildInfo only read engineRevision and builds, so the flag never reached bootstrap.js, and loadCanvasKit always probes the CDN when an engine revision is present. Because the probe is no-store, it is a network round trip on every load, and where gstatic.com is blocked or slow it can hold the loading screen for up to two 8 s attempts before falling back. The repo's own example is affected: CONTRIBUTING.md builds it with --no-web-resources-cdn.

Serving the engine locally exposed a second, latent problem. For the canvaskit renderer, cleanup's keep-set kept canvaskit/chromium/canvaskit.wasm but pruned canvaskit/chromium/canvaskit.js, the pair getCanvasKitVariant loads on Chromium-class browsers. While the engine came from the CDN the missing half went unnoticed; loaded locally, the script is gone, and on hosts with an SPA rewrite the request is answered with index.html and the app never starts.

The fix

• Generator (Dart): FlutterBuildInfo.useLocalCanvasKit, parsed from buildConfig (false when absent). injectBootstrapConfig emits "useLocalCanvasKit": true only when set, so output for CDN builds is byte-identical. The generator's summary prints which source the bootstrap will use.
• Bootstrap (TS): BuildConfig.useLocalCanvasKit?; loadCanvasKit returns canvaskit/ straight away when it is set, and the pipeline passes it in. CDN-first behaviour is unchanged for every other build.
• Cleanup: the canvaskit renderer's keep-set lists both files of the Chromium variant.
• Categorisation is unchanged: CanvasKit variants stay Optional, so in a local build the one variant the browser picks is cached on first load.
• bootstrap_template.dart regenerated with npm run build:all; README, docs/architecture.md, docs/bootstrap-pipeline.md, CLAUDE.md and the categoriser comment describe the local path; CHANGELOG entry under Unreleased.

Verification

• Vitest: 276 pass. The 3 new tests fail with the fix reverted.
• Dart: format and analyzer clean, 108 tests pass including integration. A new generate() test over a synthetic CanvasKit build fails without the keep-set fix; the new integration test compares bootstrap.js with whatever the example's flutter_bootstrap.js recorded, so it holds for builds with and without the flag.
• Playwright: 17/17 in Chromium, against the example built both with and without --no-web-resources-cdn. With the local build and the keep-set unfixed, "page loads without errors" and the wedged-queue boot test fail on the missing chromium/canvaskit.js.
• npm run verify: committed Dart assets match the build output.
• Chromium 152, example built with --no-web-resources-cdn: before, the one-byte probe and then canvaskit.js and canvaskit.wasm from gstatic; after, no gstatic request, both from canvaskit/.
• A Firebase Hosting deployment with sw pinned to this branch: the bootstrap logs Using local: canvaskit/ (built with --no-web-resources-cdn), no request goes to gstatic, and the engine loads from the origin and then from the service worker's cache on later loads.