lexiolab_client (Flutter) #

The Flutter/Dart client SDK for LexioLab: it polls the environment manifest, caches bundles locally, formats ICU at runtime, and resolves labels.

Per the fallback invariant, the SDK performs no fallback logic — fallback is resolved at bundle build time and baked into the artifact it downloads.

The user-facing reference is docs/sdk-flutter.md. This file is about working on the package itself.

Deliberately outside the pnpm workspace (it is Dart, not Node) and outside the Node toolchain entirely.

Layout #

lib/lexiolab.dart     the runtime core's barrel — no Flutter anywhere below it
lib/lexiolab_flutter.dart    the Flutter layer: delegate, widgets, fonts
lib/src/icu/                 THE runtime ICU parser and formatter (ADR-0028)
lib/src/sync/                the manifest cycle, artifact fetch, fetch planning
lib/src/cache/               keys, records, the pointer-last store, eviction, file storage
lib/src/flutter/             scope + InheritedModel, LL, the delegate, widgets, fonts
lib/src/client.dart          the orchestrator
example/                     the demo app (see example/README.md)

The core imports no package:flutter, and only lib/src/flutter/ may reach for path_provider, package:http or dart:io. That is not a convention: test/layering_test.dart reads the import directives and fails the build. It is the Dart analogue of scripts/check-purity.ts for sdk-core.

Working on it #

Everything runs in the flutter compose service — a separate container from the Node dev one, because the Flutter SDK is ~2 GB and nothing else here needs it (ADR-0029). From the repository root:

make flutter-test     # flutter test
make flutter-check    # dart format --set-exit-if-changed + dart analyze --fatal-infos
make flutter-format   # dart format .
make flutter-sh       # a shell in the container

CI runs exactly those three commands, on the version pinned in .flutter-version. scripts/check-flutter-pin.ts fails pnpm check if that file, infra/flutter.Dockerfile and the CI job ever disagree.

Running the example on a device is the one host command, because the Android emulator and adb are on the host: make flutter-example. Note that flutter pub get writes absolute paths into .dart_tool/, so alternating between host and container needs a pub get on whichever side you are using; both make targets do it for you.

Tests #

158 of them, and each one breaks something on purpose:

• icu_conformance_test.dart — the cross-SDK contract (fixtures/icu-conformance.json), byte-identical to what @lexiolab/sdk-core produces. See docs/icu-conformance.md.
• client_test.dart — cold start with no network, cache newer than assets, 304, a changed hash, an interrupted write, a corrupt cache, offline, the rollback that removes the selected language, schema and min_sdk skew, segment lazy loading, apply modes.
• widget_test.dart — first-frame render from the snapshot, the placeholder-leading Arabic sentence (structural isolation plus geometry, not a golden image), a language switch, the manifest-fed picker, a font registered exactly once across 25 rebuilds, a font download failure.
• cache_test.dart — the key grammar, atomic writes against a real temp directory, and the eviction policy.
• icu_test.dart — what happens when a message or an argument is wrong.
• events_parity_test.dart — reads packages/shared/src/sdk/events.ts and fails if the LL_SDK_* tables diverge.
• layering_test.dart — the rule above.

test/helpers/harness.dart builds releases with real SHA-256 hashes, a stub fetch with a request recorder, a manual scheduler and a frozen clock — so no test needs a platform channel, a network or a real clock.