feat: add web (wasmJs) target with FormattedString refactor (#226)

* refactor: replace StringResource/runBlocking with FormattedString sealed class

Introduce FormattedString sealed class (Literal, Resource, Plural, Concat)
to defer string resolution to the UI layer, eliminating all runBlocking and
getStringBlocking usage that blocked the JS event loop on wasmJs.

Key changes:
- All user-facing string fields (cardName, agencyName, routeName,
  stationName, subscriptionName, warning, emptyStateMessage, etc.) now
  return FormattedString instead of String
- Remove StringResource interface, DefaultStringResource, TestStringResource,
  and all getStringBlocking platform actuals
- Remove ObfuscatedTrip and TripObfuscator (unused)
- Update FareBotUiTree/ListItem/HeaderListItem to use FormattedString
- Update all ~100 transit modules to use FormattedString(Res.string.xxx)
- For @serializable types (Station, TransitBalance), use @transient
  formattedName/formattedStationName fields alongside serializable String fields
- Update App.kt, HelpScreen, TripMapScreen, CardViewModel, HistoryViewModel
- Update all test files to use assertFormattedEquals() helper and
  assertResourceEquals() for resource key comparison
- wasmJs and JVM targets compile and tests pass

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: add wasmJs target to all KMP modules

Add wasmJs { browser() } target to the root build.gradle.kts so all
KMP subprojects automatically get a WebAssembly compilation target.
Guard the compose.desktop.currentOs injection to only apply when the
jvm target exists. Add sqldelight-web-worker-driver to the version
catalog for future use.

Convert getStringBlocking/getPluralStringBlocking to expect/actual
since runBlocking is unavailable on wasmJs. Provide wasmJs actual
implementations for all expect declarations in the base module:
ResourceAccessor, BundledDatabaseDriverFactory, SystemLocale, and
GetStringBlocking.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat(web): add wasmJs platform actuals for app module

Provide wasmJs actual implementations for the three expect declarations
in the app module:
- DeviceRegion: reads navigator.language to extract country code
- CardsMapScreen: no-op (platformHasCardsMap = false), matching JVM
- TripMapScreen: no-op composable, matching JVM

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat(web): add web app shell with entry point, DI graph, and localStorage persistence

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor: extract PN533 protocol to commonMain, add WebUSB transport stub

Move pure-logic PN533 files (PN533.kt, PN533CardInfo.kt, PN533CardTransceiver.kt,
PN533CommunicateThruTransceiver.kt, PN533ClassicTechnology.kt, PN533UltralightTechnology.kt)
from jvmMain to commonMain so they can be used on all Kotlin targets.

Create a PN533Transport interface in commonMain with PN533Exception and
PN533CommandException. Rename the usb4java implementation to Usb4JavaPN533Transport
(stays in jvmMain). Add a WebUsbPN533Transport stub in wasmJsMain as a placeholder
for future WebUSB JS interop.

Replace String.format() calls with multiplatform-compatible hex formatting.
Remove Thread.sleep(10) from PN533.resetMode() (not available in commonMain,
negligible delay).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix up web

* feat(web): implement WebUSB NFC scanning, file picker, and MDST resource loading

Replaces stub implementations with working WebUSB PN533 transport (card
detection via poll loop), browser file picker for JSON/binary import, and
synchronous XHR-based MDST resource loading for wasmJs. Updates tests to
use runTest instead of runBlocking for wasmJs compatibility. Adds web
build step to CI and updates CLAUDE.md to reflect web target and
FormattedString conventions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude <claude@codebutler.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: 3 people

.devcontainer/Dockerfile

@@ -10,6 +10,9 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
   bash python3 locales make \
   iptables ipset iproute2 dnsutils aggregate jq nano vim tmux \
   build-essential libncurses-dev libz-dev libc6-dev \
+  bc coreutils findutils diffutils patch gawk sed grep file tree \
+  xz-utils bzip2 gzip tar zip rsync socat netcat-openbsd openssh-client \
+  htop lsof strace \
   && apt-get clean && rm -rf /var/lib/apt/lists/* \
   && ln -sf /bin/bash /bin/sh \
   && sed -i '/en_US.UTF-8/s/^# //' /etc/locale.gen && locale-gen

.github/workflows/ci.yml

@@ -12,7 +12,7 @@ concurrency:
 
 jobs:
   build-and-test:
-    name: Build & Test (JVM + Android)
+    name: Build & Test (JVM + Android + Web)
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -38,6 +38,9 @@ jobs:
       - name: Build Desktop
         run: ./gradlew :app:desktop:assemble
 
+      - name: Build Web
+        run: ./gradlew :app:web:wasmJsBrowserDistribution
+
   ios:
     name: Build & Test (iOS)
     runs-on: nscloud-macos-sequoia-arm64-6x14

.gitignore

@@ -37,6 +37,7 @@ gradle/gradle-daemon-jvm.properties
 
 # Git worktrees
 .worktrees/
+worktrees/
 
 # Generated review pages
 scripts/card-image-review.html

CLAUDE.md

@@ -2,7 +2,7 @@
 
 ## Project Overview
 
-FareBot is a Kotlin Multiplatform (KMP) Android/iOS app for reading NFC transit cards. It is being ported from/aligned with [Metrodroid](https://github.com/metrodroid/metrodroid).
+FareBot is a Kotlin Multiplatform (KMP) Android/iOS/Web app for reading NFC transit cards. It is being ported from/aligned with [Metrodroid](https://github.com/metrodroid/metrodroid). The web target uses Kotlin/Wasm (wasmJs) with WebUSB for NFC reader support.
 
 **Metrodroid source code is in the `metrodroid/` directory in this repo.** Always use this local copy for comparisons and porting — do not fetch from GitHub.
 
@@ -32,10 +32,11 @@ When porting code from Metrodroid: **do a faithful port**. Do not simplify, abbr
 
 - `ImmutableByteArray` → `ByteArray`
 - `Parcelize`/`Parcelable` → `kotlinx.serialization.Serializable`
-- `Localizer.localizeString(R.string.x)` → `stringResource.getString(Res.string.x)`
+- `Localizer.localizeString(R.string.x)` → `FormattedString(Res.string.x)`
 - `Timestamp`/`TimestampFull`/`Daystamp` → `kotlinx.datetime.Instant`
 - `TransitData` → `TransitInfo`
 - `CardTransitFactory` → `TransitFactory<CardType, TransitInfoType>`
+- `String` (user-facing) → `FormattedString` (sealed class in `base/util/`)
 
 Do NOT:
 - Skip features "for later"
@@ -57,24 +58,30 @@ Do NOT make speculative changes hoping they fix the issue. Each failed guess was
 
 ### 5. All code in commonMain unless it requires OS APIs
 
-Write all code in `src/commonMain/kotlin/`. Only use `androidMain` or `iosMain` for code that directly interfaces with platform APIs (NFC hardware, file system, UI system dialogs). No Objective-C. Tests use `kotlin.test`.
+Write all code in `src/commonMain/kotlin/`. Only use `androidMain`, `iosMain`, or `wasmJsMain` for code that directly interfaces with platform APIs (NFC hardware, file system, UI system dialogs, WebUSB). No Objective-C. Tests use `kotlin.test`.
 
-### 6. Use StringResource for all user-facing strings
+### 6. Use FormattedString for all user-facing strings
+
+All user-facing strings use the `FormattedString` sealed class, which defers string resolution to the UI layer (avoiding `runBlocking` that blocks the JS event loop on wasmJs).
 
-All user-facing strings must go through Compose Multiplatform resources:
 - Define strings in `src/commonMain/composeResources/values/strings.xml`
-- For UI labels in `TransitInfo.getInfo()`, use `ListItem(Res.string.xxx, value)` or `HeaderListItem(Res.string.xxx)` directly
-- For dynamic string formatting, use `runBlocking { getString(Res.string.xxx) }`
-- Legacy pattern: Pass `StringResource` to factories — still works but not required for new code
+- Use `FormattedString(Res.string.xxx)` for resource-backed strings
+- Use `FormattedString("literal")` for dynamic/computed strings
+- Use `FormattedString(Res.string.xxx, arg1, arg2)` for formatted strings
+- Use `FormattedString.plural(Res.plurals.xxx, count, args...)` for plurals
+- Concatenate with `+` operator: `FormattedString("a") + FormattedString("b")`
+
+The UI resolves strings via `@Composable formattedString.resolve()` or `suspend formattedString.resolveAsync()`.
 
 Example patterns:
 ```kotlin
-// Preferred for static labels
-ListItem(Res.string.card_type, cardType)
-HeaderListItem(Res.string.card_details)
+// In transit modules — return FormattedString, not String
+override val cardName: FormattedString get() = FormattedString(Res.string.card_name)
+override val warning: FormattedString? get() = FormattedString(Res.string.some_warning, count)
 
-// For dynamic values
-val formatted = runBlocking { getString(Res.string.balance_format) }
+// For ListItem/HeaderListItem
+ListItem(Res.string.card_type, value)
+HeaderListItem(Res.string.card_details)
 ```
 
 Do NOT hardcode English strings in Kotlin files.
@@ -103,32 +110,29 @@ Do NOT claim work is complete without verification.
 
 ### 9. Preserve context across sessions
 
-Key project state is in:
-- `/Users/eric/.claude/plans/` — implementation plans (check newest first)
-- `/Users/eric/Code/farebot/REMAINING-WORK.md` — tracked remaining work
-- Session transcripts in `/Users/eric/.claude/projects/-Users-eric-Code-farebot/`
-
-When continuing from a previous session, read these files to recover context rather than starting from scratch.
+When continuing from a previous session, check for implementation plans and session transcripts in `~/.claude/` to recover context rather than starting from scratch.
 
 ## Build Commands
 
 ```bash
-./gradlew allTests          # Run all tests
-./gradlew assemble          # Full build (Android + iOS frameworks)
+./gradlew allTests                    # Run all tests
+./gradlew assemble                    # Full build (Android + iOS + Web)
 ./gradlew :app:android:assembleDebug  # Android only
+./gradlew :app:web:wasmJsBrowserDistribution  # Web (Wasm) only
 ```
 
 ## Module Structure
 
 - `base/` — Core utilities, MDST reader, ByteArray extensions (`:base`)
 - `card/` — Shared card abstractions (`:card`)
-- `card/*/` — Card type implementations: classic, desfire, felica, ultralight, iso7816, cepas, vicinity (`:card:*`)
+- `card/*/` — Card type implementations: classic, desfire, felica, ultralight, iso7816, cepas, china, ksx6924, vicinity (`:card:*`)
 - `transit/` — Shared transit abstractions: Trip, Station, TransitInfo, TransitCurrency (`:transit`)
 - `transit/*/` — Transit system implementations, one per system (`:transit:*`)
 - `transit/serialonly/` — Identification-only systems (serial number + reason, matches Metrodroid's `serialonly/`)
 - `app/` — KMP app framework: UI, ViewModels, DI, platform code (`:app`)
 - `app/android/` — Android app shell: Activities, manifest, resources (`:app:android`)
 - `app/desktop/` — Desktop app shell (`:app:desktop`)
+- `app/web/` — Web app shell: Kotlin/Wasm entry point, WebUSB NFC support, localStorage persistence (`:app:web`)
 - `app/ios/` — iOS app shell: Swift entry point, assets, config (Xcode project, not a Gradle module)
 - `tools/mdst/` — JVM CLI for MDST station databases: lookup, dump, compile (`:tools:mdst`)
 
@@ -137,9 +141,16 @@ When continuing from a previous session, read these files to recover context rat
 1. Create `transit/{name}/build.gradle.kts`
 2. Add `include(":transit:{name}")` to `settings.gradle.kts`
 3. Add `api(project(":transit:{name}"))` to `app/build.gradle.kts`
-4. Register factory in `TransitFactoryRegistry.kt` (Android)
-5. Register factory in `MainViewController.kt` (iOS, non-Classic cards only)
-6. Add string resources in `composeResources/values/strings.xml`
+4. Register factory in `TransitFactoryRegistryBuilder.kt` (shared, used by all platforms)
+5. Add string resources in `composeResources/values/strings.xml`
+
+## CI
+
+GitHub Actions (`.github/workflows/ci.yml`). Runs tests and builds on push/PR.
+
+## Development Environment
+
+A devcontainer is available (`.devcontainer/`) with Android SDK, JDK 25, and sandboxed networking. This is the default environment for Claude Code.
 
 ## Agent Teams
 

Makefile

@@ -1,7 +1,7 @@
 IOS_DEVICE_ID := $(shell xcrun xctrace list devices 2>/dev/null | grep -v Simulator | grep -E '\([0-9A-F-]+\)$$' | grep -v Mac | head -1 | grep -oE '[0-9A-F]{8}-[0-9A-F]{16}')
 IOS_APP_PATH = $(shell ls -d ~/Library/Developer/Xcode/DerivedData/FareBot-*/Build/Products/Debug-iphoneos/FareBot.app 2>/dev/null | head -1)
 
-.PHONY: android android-install ios ios-sim ios-install desktop test clean help
+.PHONY: android android-install ios ios-sim ios-install desktop web web-run test clean help
 
 ## Android
 
@@ -31,6 +31,14 @@ ios-install: ios ## Build and install on connected iOS device
 desktop: ## Run macOS desktop app (experimental)
 	./gradlew :app:desktop:run
 
+## Web
+
+web: ## Build web app (experimental, WebAssembly)
+	./gradlew :app:web:wasmJsBrowserDistribution
+
+web-run: ## Run web app dev server with hot reload
+	./gradlew :app:web:wasmJsBrowserDevelopmentRun
+
 ## Tests
 
 test: ## Run all tests

README.md

@@ -2,7 +2,7 @@
 
 Read your remaining balance, recent trips, and other information from contactless public transit cards using your NFC-enabled Android or iOS device.
 
-FareBot is a [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform.html) app built with [Compose Multiplatform](https://www.jetbrains.com/compose-multiplatform/), targeting Android (NFC), iOS (CoreNFC), and macOS (experimental, via PC/SC smart card readers or PN533 raw USB NFC controllers).
+FareBot is a [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform.html) app built with [Compose Multiplatform](https://www.jetbrains.com/compose-multiplatform/), targeting Android (NFC), iOS (CoreNFC), macOS (experimental, via PC/SC smart card readers or PN533 raw USB NFC controllers), and Web (experimental, via WebAssembly).
 
 ## Platform Compatibility
 
@@ -184,6 +184,7 @@ Some MIFARE Classic cards require encryption keys to read. You can obtain keys u
 * **Android:** NFC-enabled device running Android 6.0 (API 23) or later
 * **iOS:** iPhone 7 or later with iOS support for CoreNFC
 * **macOS** (experimental): Mac with a PC/SC-compatible NFC smart card reader (e.g., ACR122U), a PN533-based USB NFC controller (e.g., SCL3711), or a Sony RC-S956 (PaSoRi) USB NFC reader
+* **Web** (experimental): Any modern browser with WebAssembly support. Card data can be imported from JSON files exported by other platforms. NFC reading via WebUSB is planned but not yet implemented.
 
 ## Building
 
@@ -201,6 +202,8 @@ $ make              # show all targets
 | `make ios-sim` | Build iOS app for simulator |
 | `make ios-install` | Build and install on connected iOS device (auto-detects device) |
 | `make desktop` | Run macOS desktop app (experimental) |
+| `make web` | Build web app (experimental, WebAssembly) |
+| `make web-run` | Run web app dev server with hot reload |
 | `make test` | Run all tests |
 | `make clean` | Clean all build artifacts |
 
@@ -257,6 +260,7 @@ Compatible with [Zed](https://zed.dev/docs/dev-containers), VS Code (Remote - Co
 - `app/android/` — Android app shell (Activities, manifest, resources)
 - `app/ios/` — iOS app shell (Swift entry point, assets, config)
 - `app/desktop/` — macOS desktop app (experimental, PC/SC + PN533 + RC-S956 USB NFC)
+- `app/web/` — Web app (experimental, WebAssembly via Kotlin/Wasm)
 
 ## Written By
 

app/build.gradle.kts

@@ -47,6 +47,7 @@ kotlin {
         }
         commonTest.dependencies {
             implementation(kotlin("test"))
+            implementation(libs.kotlinx.coroutines.test)
         }
         commonMain.dependencies {
             implementation(libs.compose.runtime)

app/desktop/build.gradle.kts

@@ -6,6 +6,8 @@ plugins {
 }
 
 kotlin {
+    jvmToolchain(25)
+
     sourceSets {
         jvmMain.dependencies {
             implementation(project(":app"))

app/desktop/src/jvmMain/kotlin/com/codebutler/farebot/desktop/DesktopAppGraph.kt

@@ -1,8 +1,6 @@
 package com.codebutler.farebot.desktop
 
 import app.cash.sqldelight.driver.jdbc.sqlite.JdbcSqliteDriver
-import com.codebutler.farebot.base.util.DefaultStringResource
-import com.codebutler.farebot.base.util.StringResource
 import com.codebutler.farebot.card.serialize.CardSerializer
 import com.codebutler.farebot.persist.CardKeysPersister
 import com.codebutler.farebot.persist.CardPersister
@@ -70,10 +68,6 @@ abstract class DesktopAppGraph : AppGraph {
     @SingleIn(AppScope::class)
     fun provideTransitFactoryRegistry(): TransitFactoryRegistry = createTransitFactoryRegistry()
 
-    @Provides
-    @SingleIn(AppScope::class)
-    fun provideStringResource(): StringResource = DefaultStringResource()
-
     @Provides
     @SingleIn(AppScope::class)
     fun provideCardScanner(): CardScanner = DesktopCardScanner()

app/desktop/src/jvmMain/kotlin/com/codebutler/farebot/desktop/PN533ReaderBackend.kt

@@ -23,13 +23,13 @@
 package com.codebutler.farebot.desktop
 
 import com.codebutler.farebot.card.nfc.pn533.PN533
-import com.codebutler.farebot.card.nfc.pn533.PN533Transport
+import com.codebutler.farebot.card.nfc.pn533.Usb4JavaPN533Transport
 
 /**
  * NXP PN533 reader backend (e.g., SCM SCL3711).
  */
 class PN533ReaderBackend(
-    transport: PN533Transport? = null,
+    transport: Usb4JavaPN533Transport? = null,
 ) : PN53xReaderBackend(transport) {
     override val name: String = "PN533"