Skip to content

Commit 6b81a83

Browse files
ichoridclaude
andcommitted
fix(client): web runs skwasm single-threaded until Flutter fixes its FreeType race (Refs #808, #910)
Multi-threaded skwasm on Flutter 3.47.0 makes its FreeType lock a no-op, so text layout on the main thread races glyph drawing on the raster worker (flutter/flutter#193439; fix PR flutter/flutter#193801 unmerged). Fast Field zoom froze 7 of 8 local runs multi-threaded and 0 of 3 single-threaded. The build hook now passes forceSingleThreadedSkwasm:true in the loader config (kForceSingleThreadedSkwasm). COOP/COEP stay on, so going back is a one-line change. scripts/check_skwasm_single_thread.sh (run by client-gates, never failing) warns when the pinned Flutter version moves past 3.47.0 or the upstream fix merges; AGENTS.md, the Flutter version pins, the Caddyfile and the zoom-path code point at it so the next Flutter upgrade re-tests multi-threaded skwasm. Client 7.60.11. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 45866ea commit 6b81a83

13 files changed

Lines changed: 106 additions & 3 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ plugin). See `DEVELOPMENT.md` and `DEV_GUIDELINES.md`.
3636
- **No golden tests.** Golden/pixel-comparison tests are disabled project-wide — never write, update or restore them, even if a bead's acceptance criteria ask; use structural widget tests instead. See `.cursor/rules/no-golden-tests.mdc`.
3737
- **Rooms are General-only — there are no item threads, with one named exception: Request Questions.** Code mentioning `thread_item_id` / `threadItemId` / `_canAccessThread` / item participants is dormant machinery kept on purpose (marked `DORMANT(item-threads)`); the DB guard `beacon_room_message_general_only_guard` rejects every non-General row except a Request's own **Questions** scope (internally the lobby: `coordination_item` kind 7, D1/#526). Questions access is the one server policy `questions_access_levels` (m0254) — never re-implement it, and never let a General-only feature reference a Questions message (DB guard `reject_questions_message_reference`). Never design other features, access rules or reviews around item threads. See #192 and `docs/features/beacon_questions.md`.
3838
- **Web cache-buster must ship with every client version bump:** `packages/client/web/index.html`'s `flutter_bootstrap.js?v=<version>` query is a real, git-tracked source file (unlike `web/manifest.json`, which is deliberately `skip-worktree` and never needs committing) — it only gets rewritten to match `pubspec.yaml` when you actually run/build the app locally (`flutter run`/`flutter build web`; the `hook/build.dart` build hook does it, not `build_runner`). Before committing a version bump, run the app once and check `git status` for a resulting `web/index.html` diff, or hand-verify the `?v=` matches. A missed bump here means browsers keep serving a cached pre-fix JS bundle after a real fix ships — this has happened before (`git log -- packages/client/web/index.html` shows recurring catch-up `chore: sync web cache-buster` commits) and once made a landed bug fix look like it "didn't work."
39+
- **Upgrading Flutter re-opens #808:** the web build forces single-threaded skwasm (`kForceSingleThreadedSkwasm`, `packages/client/hook/build/versioned_web_assets.dart`) to dodge an upstream FreeType race on 3.47.0. After any Flutter version change, run `bash scripts/check_skwasm_single_thread.sh` and follow the comment on that constant to re-test multi-threaded skwasm.
3940

4041
## Product docs
4142

‎Caddyfile‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -214,6 +214,9 @@
214214
root * {$APP_ROOT:/srv/web}
215215
header Cache-Control "public, max-age=31536000, immutable"
216216
file_server
217+
# COOP/COEP keep the page cross-origin isolated so multi-threaded skwasm
218+
# can come back without a server change; the client currently forces
219+
# single-threaded skwasm (#808, kForceSingleThreadedSkwasm).
217220
header Cross-Origin-Opener-Policy "same-origin"
218221
header Cross-Origin-Embedder-Policy "credentialless"
219222
header Access-Control-Allow-Credentials "false"

‎Dockerfile.builder‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@
99
# + flutter_test.) CI builds web and runs VM / flutter_tester tests only.
1010
FROM debian:bookworm-slim
1111

12+
# Upgrading Flutter? Run scripts/check_skwasm_single_thread.sh: the web build
13+
# forces single-threaded skwasm on 3.47.0 (#808); re-test multi-threaded.
1214
ARG FLUTTER_VERSION=3.47.0
1315

1416
ENV FLUTTER_HOME=/sdks/flutter

‎Dockerfile.server‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@
55
# workspace pub get can solve analyzer 13 + flutter_test (test_api 0.7.12).
66
FROM ghcr.io/cirruslabs/flutter:3.44.0 AS build
77

8+
# Upgrading Flutter? Run scripts/check_skwasm_single_thread.sh: the web build
9+
# forces single-threaded skwasm on 3.47.0 (#808); re-test multi-threaded.
810
ARG FLUTTER_VERSION=3.47.0
911
ARG GIT_SHA=unknown
1012
ARG SERVER_VERSION=0.0.0

‎packages/client/hook/build/versioned_web_assets.dart‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,11 +81,26 @@ void _rewriteBootstrap(File file, {required String assetPrefix}) {
8181
}
8282
}
8383

84+
/// SINGLE-THREADED SKWASM WORKAROUND (#808) — RE-CHECK ON EVERY FLUTTER UPGRADE.
85+
///
86+
/// Multi-threaded skwasm (Flutter 3.47.0) makes its FreeType lock a no-op, so
87+
/// text layout on the main thread races glyph drawing on the raster worker:
88+
/// the Field froze in 7 of 8 local fast-zoom runs (TENTURA-CLIENT-5C, #910).
89+
/// Upstream: flutter/flutter#193439, fix PR flutter/flutter#193801 (unmerged
90+
/// when this was pinned). Single-threaded skwasm froze 0 of 3 runs.
91+
///
92+
/// After a Flutter upgrade, run `scripts/check_skwasm_single_thread.sh`. When
93+
/// the new Flutter contains the upstream fix, set this to false, rebuild with
94+
/// `--wasm`, rerun the #808 fast-zoom repro and the Field perf bench, and
95+
/// update the pinned version in that script. COOP/COEP headers stay on in
96+
/// Caddy, so switching back needs no server change.
97+
const kForceSingleThreadedSkwasm = true;
98+
8499
String _loaderConfigSource(String assetPrefix) {
85100
final prefix = jsonEncode(assetPrefix);
86101
final canvasKitPrefix = jsonEncode('${assetPrefix}canvaskit/');
87102
return '''
88-
{entrypointBaseUrl:new URL($prefix,document.baseURI).toString(),canvasKitBaseUrl:new URL($canvasKitPrefix,document.baseURI).toString(),assetBase:new URL($prefix,document.baseURI).toString()}''';
103+
{entrypointBaseUrl:new URL($prefix,document.baseURI).toString(),canvasKitBaseUrl:new URL($canvasKitPrefix,document.baseURI).toString(),assetBase:new URL($prefix,document.baseURI).toString(),forceSingleThreadedSkwasm:$kForceSingleThreadedSkwasm}''';
89104
}
90105

91106
void _rewriteIndexHtml(File file, {required String assetPrefix}) {

‎packages/client/lib/design_system/components/tentura_avatar.dart‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -383,6 +383,8 @@ class ProfileAvatarInitials extends StatelessWidget {
383383
onContainer: scheme.onSecondaryContainer,
384384
)
385385
: context.palette.avatarHueFor(key);
386+
// #808: a size that changes every frame means new FreeType work every
387+
// frame; see kForceSingleThreadedSkwasm (hook/build/versioned_web_assets.dart).
386388
final fontSize = size * 0.38;
387389
return ColoredBox(
388390
color: swatch.container,

‎packages/client/lib/features/constellation/ui/widget/constellation_body.dart‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2603,6 +2603,12 @@ class _OverviewDot extends StatelessWidget {
26032603
/// A [kConstellationDistrictMarkerDiameter] circle of the person's initials on
26042604
/// screen whatever the camera scale, ringed in the first own-tag colour (no
26052605
/// ring without a tag), centred in the node's own scene box.
2606+
///
2607+
/// #808: these markers re-lay out ~30 initials paragraphs per zoom frame, which
2608+
/// is what triggers the multi-threaded skwasm FreeType race; the web build runs
2609+
/// skwasm single-threaded for now (see kForceSingleThreadedSkwasm in
2610+
/// hook/build/versioned_web_assets.dart). Re-test fast zoom here after a
2611+
/// Flutter upgrade.
26062612
class _DistrictMarker extends StatelessWidget {
26072613
const _DistrictMarker({
26082614
required this.spec,

‎packages/client/pubspec.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ name: tentura
22
description: 'Social network for communities'
33
publish_to: 'none'
44

5-
version: 7.60.10
5+
version: 7.60.11
66

77
environment:
88
sdk: ^3.12.0

‎packages/client/test/hook/versioned_web_assets_test.dart‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,9 @@ void main() {
6767
contains('assetBase:new URL("$prefix",document.baseURI)'),
6868
);
6969
expect(bootstrap, isNot(contains('_flutter.loader.load();')));
70+
// #808: skwasm runs single-threaded until the upstream FreeType lock
71+
// fix ships (see kForceSingleThreadedSkwasm).
72+
expect(bootstrap, contains('forceSingleThreadedSkwasm:true'));
7073

7174
final index = File('${dir.path}/index.html').readAsStringSync();
7275
expect(index, contains('href="${prefix}icons/Icon-192.png"'));

‎packages/client/web/index.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -143,7 +143,7 @@
143143
})();
144144
</script>
145145

146-
<script src="flutter_bootstrap.js?v=7.60.10" async=""></script>
146+
<script src="flutter_bootstrap.js?v=7.60.11" async=""></script>
147147

148148
<script>
149149
if ('serviceWorker' in navigator) {

0 commit comments

Comments
 (0)