Architecture#

SwiftBrowser runs SwiftUI apps in the browser so iOS development does not require a Mac for day-to-day iteration. The invariant everything else protects: an app's source imports SwiftUI and compiles unchanged for both iOS and the browser.

Examples/Counter/Sources/*.swift      the app: plain SwiftUI, no SwiftBrowser imports
        │                                      │
        │ swift build --swift-sdk wasm          │ xcrun swiftc -typecheck (macOS CI)
        ▼                                      ▼
Sources/SwiftUI (shim module)            Apple's real SwiftUI
  view tree → element tree → ops
        │
        ▼  docs/ops-protocol.md
Web/ (TypeScript renderer)   or   headless JSON Lines (wasmtime, CI snapshots)

Pieces#

• Sources/SwiftUI: a SwiftPM library target literally named SwiftUI. It implements an API-compatible subset of SwiftUI (see the compatibility matrix in the README), state storage, and a reconciler that diffs element trees into ops. It has no dependency on Foundation or JavaScriptKit, so it also builds natively on Linux for fast unit tests.
• Examples/Counter: the first app. Its sources are compiled two ways: into a Wasm executable against the shim, and type-checked against Apple's SwiftUI on a macOS runner so the shim can never drift from the real API.
• Web/: a Vite + TypeScript project. It instantiates the Wasm module with a WASI shim, applies ops to the DOM inside an iPhone-shaped frame styled with iOS design tokens, and forwards taps back to Swift.
• scripts/: build-wasm.sh builds the example for Wasm and copies it into Web/public/; snapshot-test.sh runs the example headless under wasmtime and diffs against Examples/Counter/__snapshots__/.

Why this shape#

• Emitting ops instead of touching the DOM keeps the Swift core testable without a browser and lets the renderer be swapped (a canvas renderer with a faithful SwiftUI layout pass is the Phase 2 option).
• The package is only ever built for Wasm and Linux. Building it on macOS would collide with the system SwiftUI module, which is intentional: on Apple platforms the app uses the real thing.

Phase 2 notes#

• Keyed children. ForEach gives its children identities. Both the mounted tree and the reconciler match keyed children by identity, so a row keeps its @State and its element id across inserts, removes and reorders, and a reorder becomes a single insert (move) op.
• Navigation. NavigationStack keeps the pushed screens in a @State array inside its own view struct, so it survives re-renders like any state. The runtime wraps the root and each pushed view in a navscreen element, lifts navigationTitle into the screen's props, supplies the push handler for NavigationLink and the pop handler for the screen, and puts a matching dismiss into the environment.
• Environment. Values flow down during reconciliation. @Environment properties are found by reflection, like @State, and resolved before the view's body runs. .environment(_:_:) and style modifiers write into the same context.
• Observation. A render pass runs inside withObservationTracking; a change to any observed property marks the tree dirty, and the next event (or the end of the current one) re-renders. Mutations outside events, such as from timers or tasks, are not yet driven to the screen.
• Hot reload. The runtime can snapshot primitive @State values keyed by each view's path (position and type from the root) and restore them from the SB_STATE environment variable at the next boot. Values whose path or type no longer matches are dropped silently.

Phase 3 notes#

• Layout lives in the renderer. The Swift side still emits only the element tree. The renderer's layout engine (Web/src/layout) implements SwiftUI's propose-and-report protocol per element kind, measures text with the real font, and positions every element absolutely. Keeping layout in TypeScript avoids a synchronous Swift-to-JavaScript measurement bridge, keeps the module runnable under wasmtime with no custom imports, and lets the engine be unit-tested in Node with a deterministic text measurer.
• Skipping unchanged views. A node re-runs its body when it is dirty (its own state or an observed value changed). When its parent re-runs it receives a new view value; if that value and the environment it receives are the same as last time, it is skipped with its subtree, like SwiftUI does for views whose stored properties are equal (docs/ops-protocol.md, "Phase 16"). Which of the runtime's protocols a view conforms to is worked out once per type (_ViewTraits), not cast for on every pass ("Phase 17").
• Animation. withAnimation records a transaction on the main actor; the render pass it causes stamps its commit with the animation and the renderer animates every frame and style change in that pass. .animation(_:value:) is a styled wrapper whose mounted node remembers the last value and bumps an animationToken prop when it changes; only that subtree animates. Transitions are a style field read when the element is inserted or removed inside an animated commit. A pass that moves an element whose frame is still tweening (a custom Layout or a GeometryReader answering the animated pass a frame later) retargets the tween from where the element is drawn to its new frame, in the time the tween had left; it never leaves the old tween drawing a stale frame.
• Sheets. .sheet mounts the content as a second child of the presenting node while presented, so its state survives, but emits it as a root-level sheet element after the app's tree. Its handler flips the binding; the content's environment carries a matching dismiss.
• Dynamic Type. Fonts travel as text-style names and the renderer resolves them against Apple's Dynamic Type table for the current size, which arrives through the environment event like the color scheme.

Phase 4 notes#

• Executor. Swift concurrency on Wasm has no event loop of its own. The shim installs a cooperative executor through the ExecutorFactory SPI (the same route JavaScriptKit takes on Swift 6.4): jobs queue until the host calls sb_run_jobs, and sleeps become timers against a clock the host sets. The browser passes real time; headless mode jumps a virtual clock from timer to timer, so timer-driven apps snapshot deterministically. Native test processes never install it, because the test runner drives the main actor itself.
• Stable state storage. A long-lived task captures the view value it was started from. State boxes therefore share one persistent storage object across re-renders instead of copying values, so a closure captured before a re-render still writes to the live value.
• Tabs and pickers. The runtime flattens the content into options, reading tag, tabItem and ForEach ids through the wrapper views, and emits one tab element per option (all mounted, one selected) or the option labels on a picker.
• Value-based navigation. navigationDestination(for:) registers a builder on the enclosing stack's node while the root screen reconciles; path screens are placeholders resolved right after, so a value appended to the path binding becomes a screen in the same pass.
• GeometryReader. The renderer reports the laid-out size through a geometry event only when it changes; the node stores it and the content re-renders with the real size, so the loop converges in one extra pass.

Foundation#

The shim imports Foundation and apps link the wasm SDK's swift-corelibs Foundation, with ICU's locale data trimmed to the app's languages by the CLI (see packages/cli/src/icu.ts and docs/ops-protocol.md, "Phase 11"). What corelibs lacks on WASI lives in Sources/FoundationBridge: Timer and RunLoop, a UserDefaults the browser persists, a Bundle over the staged resources, URLSession and AsyncImage over the page's fetch, and the viewer's Locale. An app file says import Foundation and nothing else, so the same file compiles against Apple's SDKs. Earlier phases had a lean mode on FoundationEssentials plus a small formatting layer; Phase 14 removed it (README, "Phase 14"). Phase 15 trimmed further (docs/ops-protocol.md, "Phase 15", with a breakdown of where the bytes go and why dead-code elimination keeps them); a small app is 17.4 MB, 4.5 MB with brotli. The sizes below are from the lean era and remain a fair picture of what each piece costs before trimming.

SwiftData#

Sources/SwiftData is SwiftData over the page's IndexedDB (docs/ops-protocol.md, "Phase 18"). The store is in Swift memory for the run, handed in at launch (SB_SWIFTDATA) and written back save by save (swiftdata ops), because SwiftData's API is synchronous and IndexedDB's is not: fetching from memory keeps context.fetch and @Query synchronous, as on iOS. @Model and #Predicate are compiler plugins (Sources/SwiftDataMacros, swift-syntax), so only apps that import SwiftData pay for them; the CLI links the module when a source imports it.

Files#

An app's home directory (/data, HOME) is an in-memory WASI directory the page fills from IndexedDB before the module starts and writes back after any event or executor run that wrote to a file (docs/ops-protocol.md, "Phase 19"). Nothing in the protocol changes: the page notices writes by watching the WASI calls that can change a file, then diffs the tree against what it last saved.

Bitmaps#

UIImage, CGImage and Core Image's CIImage hold recipes, never pixels (docs/ops-protocol.md, "Bitmaps and Core Image"): an image file's bytes (or a generator's pixel buffer, such as a QR code's modules) plus the filter steps to run. Swift reads sizes from file headers, so UIImage(data:) stays synchronous as on iOS; the page decodes the file with the browser and runs the steps in TypeScript (Web/src/imageOps.ts) at the size the image is shown. No image codec is compiled into the module. UIImage and CGImage are in the shim because SwiftUI re-exports them on iOS; Sources/CoreImage is linked only into apps that import it.