FlutDev

Part 4: Shorebird | The Science Behind Shorebird — How a .so File Becomes a Running App

noreply@blogger.com (Lokesh Jangid) — Thu, 14 May 2026 22:47:01 -0700

The Science Behind Shorebird — How a .so File Becomes a Running App

The Science Behind Shorebird

How replacing a file on disk makes a new button appear on screen. No code — just the underlying computer science, explained from first principles.

Chapter 1: What IS libapp.so?

Before understanding how patching works, you need to understand what libapp.so actually is. It's not "code" in the way you think of it.

Your Dart code is not interpreted

When you write Flutter in Dart, you write human-readable text:

ElevatedButton(
  onPressed: () => print("Hello"),
  child: Text("Click me"),
)

In debug mode, this text is compiled to an intermediate format and interpreted by the Dart VM on the fly — that's why hot reload works.

But in release mode (which is what users run), something completely different happens. The Dart compiler (gen_snapshot) converts your entire Dart program into native machine code — the same kind of binary instructions that C++ or Rust compiles to. This is called AOT (Ahead-of-Time) compilation.

📖

Analogy: Think of your Dart code as a recipe written in English. Debug mode is like having a chef who reads the recipe out loud and follows it step by step (slow, but flexible — you can change the recipe while cooking). Release mode is like translating the entire recipe into a robot's programming language and burning it onto a chip. The robot executes it at machine speed, but you can't change it without making a new chip.

The output of this compilation is libapp.so — a standard Linux shared library (ELF format) containing your entire app as machine code.

What's inside libapp.so

libapp.so contains exactly 4 things, stored as named symbols (like chapters in a book):

┌──────────────────────────────────────────────────────────────┐
│                    libapp.so (ELF file, ~3 MB)               │
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │  Symbol: kDartVmSnapshotData                            │ │
│  │  Contains: Dart VM initialization data                  │ │
│  │  (Type tables, class hierarchy, GC metadata)            │ │
│  │  Size: ~50 KB                                           │ │
│  └─────────────────────────────────────────────────────────┘ │
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │  Symbol: kDartVmSnapshotInstructions                    │ │
│  │  Contains: Core VM machine code                         │ │
│  │  (Garbage collector, object allocator, core runtime)    │ │
│  │  Size: ~200 KB                                          │ │
│  └─────────────────────────────────────────────────────────┘ │
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │  Symbol: kDartIsolateSnapshotData                       │ │
│  │  Contains: YOUR APP'S DATA                              │ │
│  │  - All string literals ("Click me", "Hello")            │ │
│  │  - All constant objects and values                      │ │
│  │  - The object graph (how objects reference each other)  │ │
│  │  - Class field layouts                                  │ │
│  │  Size: ~500 KB – 1.5 MB                                │ │
│  └─────────────────────────────────────────────────────────┘ │
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │  Symbol: kDartIsolateSnapshotInstructions               │ │
│  │  Contains: YOUR APP'S MACHINE CODE                      │ │
│  │  - Every function you wrote, compiled to ARM64/x86      │ │
│  │  - Every widget build() method                          │ │
│  │  - Every onPressed callback                             │ │
│  │  - Every calculation, every if/else branch              │ │
│  │  - All imported package code (provider, bloc, etc.)     │ │
│  │  Size: ~1 – 2 MB                                       │ │
│  └─────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘

Key Insight

libapp.so is a complete snapshot of your entire Dart program frozen into machine code + data. It contains everything — your widgets, your logic, your strings, your constants, and all the package code you imported. When you change one line of Dart, a new libapp.so is generated with different machine code in the instructions section and possibly different data in the data section.

Chapter 2: How Does a .so File Become a Running App?

When your app starts, the Flutter engine needs to turn that libapp.so file into an actual running application. This happens through a process called dynamic loading.

Step 1: The OS loads the file into memory

The Flutter engine calls a function called dlopen() — this is an operating system function that loads a .so file from disk into the process's memory space.

// This is literally the code in the Flutter engine:
handle_ = ::dlopen(path, RTLD_NOW);

// path = "/data/data/com.app/lib/arm64/libapp.so"
//    OR = "/data/data/com.app/files/shorebird_updater/patches/3/dlc.vmcode"
//
// The OS doesn't care which path — it loads whatever file is at that path.

📀

Analogy: Think of dlopen() like putting a CD into a CD player. The player doesn't care which CD you insert — it just reads whatever is on the disc. dlopen() doesn't care which .so file you give it — it just reads whatever is at that file path into memory. Shorebird works by swapping which CD is in the player before the music starts.

What does dlopen() actually do at the OS level?

1. Opens the file and reads the ELF header (first 64 bytes) to understand the file layout.

2. Memory-maps the file's sections. This means the OS creates virtual memory pages that point directly to the file on disk. The file isn't "copied" into RAM — instead, the OS sets up page table entries so that when the CPU accesses those memory addresses, the OS loads the corresponding bytes from the file on demand. This is called mmap().

3. Marks permissions: The instructions sections (machine code) are marked as executable memory — the CPU is allowed to jump to these addresses and execute them. The data sections are marked as read-only — the CPU can read them but not execute them.

4. Returns a handle — a pointer that the engine can use to look up symbols inside the loaded file.

Step 2: The engine finds the 4 symbols

After dlopen(), the engine uses dlsym() to find the 4 named sections:

// This is the actual code:
Resolve("kDartVmSnapshotData")             → memory address 0x7f8a001000
Resolve("kDartVmSnapshotInstructions")     → memory address 0x7f8a010000
Resolve("kDartIsolateSnapshotData")        → memory address 0x7f8a100000
Resolve("kDartIsolateSnapshotInstructions") → memory address 0x7f8a300000

dlsym() returns memory addresses — pointers to where each section was loaded in memory. These addresses point to raw bytes: machine code and data.

📚

Analogy: If dlopen() is opening a book, dlsym() is looking up a chapter by name in the table of contents. "kDartIsolateSnapshotInstructions" → "starts on page 300" (memory address 0x7f8a300000).

Step 3: The Dart VM uses these memory addresses directly

The Dart VM initialization looks roughly like this:

Dart_InitializeParams params;
params.vm_snapshot_data         = memory_address_of_kDartVmSnapshotData;
params.vm_snapshot_instructions = memory_address_of_kDartVmSnapshotInstructions;
Dart_Initialize(¶ms);

// Later, when creating your app's isolate:
Dart_CreateIsolateGroup(
    isolate_snapshot_data,          // address of kDartIsolateSnapshotData
    isolate_snapshot_instructions,  // address of kDartIsolateSnapshotInstructions
);

The Dart VM doesn't "read" these files like a text file. It directly executes the machine code in memory. The kDartIsolateSnapshotInstructions bytes ARE CPU instructions — the VM sets the CPU's instruction pointer to that memory address, and the CPU starts executing your compiled Dart code.

This is the fundamental insight

Your compiled Dart code IS machine code. It runs at the same speed as C++ or Rust code. The Dart VM doesn't interpret it — it directly jumps to the memory addresses where your compiled functions live. The .so file is literally a block of executable instructions + data that the CPU runs natively.

Chapter 3: The Swap — Why Shorebird Works

Now you understand: the .so file is loaded into memory by dlopen(path), symbols are found by dlsym(name), and the Dart VM executes the machine code at those memory addresses.

Shorebird works by changing one thing — the path argument to dlopen().

Without Shorebird (normal Flutter):

application_library_path = ["/data/app/com.app/lib/arm64/libapp.so"]
                                     │
                                     ▼ dlopen()
                              Loads ORIGINAL .so
                                     │
                                     ▼ dlsym("kDartIsolateSnapshotInstructions")
                              Points to ORIGINAL machine code
                                     │
                                     ▼ CPU executes
                              Your ORIGINAL Dart code runs
                              (the version from the Play Store)

With Shorebird (patched):

// shorebird.cc does this BEFORE the Dart VM starts:
application_library_path.clear();
application_library_path = ["/data/.../shorebird_updater/patches/3/dlc.vmcode"]
                                     │
                                     ▼ dlopen()
                              Loads PATCHED .so (dlc.vmcode)
                                     │
                                     ▼ dlsym("kDartIsolateSnapshotInstructions")
                              Points to PATCHED machine code
                                     │
                                     ▼ CPU executes
                              Your UPDATED Dart code runs
                              (with the new button, fixed bug, etc.)

That's the entire trick. The engine, the Dart VM, and the OS don't know or care that the file path changed. dlopen() loads whatever file is at whatever path you give it. The file has the same structure (ELF with 4 symbols), the same symbol names, and valid machine code inside. The CPU executes it exactly the same way.

🎵

Analogy: Imagine a music player that reads a file called song.mp3 from a folder. Normally, song.mp3 is "Yesterday" by The Beatles. But while the player is still loading (before it hits play), you swap the file with "Bohemian Rhapsody" by Queen. The player doesn't notice — it just reads the bytes and plays whatever song those bytes represent. The file format is the same (.mp3), the player doesn't check what the song is, it just plays what's there.

Shorebird does this exact swap — it changes which libapp.so file the Flutter engine loads, before the Dart VM starts playing your app.

Chapter 4: Why dlc.vmcode IS a Valid libapp.so

You might wonder — the patched file is reconstructed from a binary diff on the device. How can a "reconstructed" file work exactly like a "compiled" one?

Because bipatch reconstructs the file byte-for-byte identically. Here's the proof chain:

On the developer's machine:

1. You change Dart code and run shorebird patch

2. The Dart compiler produces a NEW libapp.so — a valid ELF file with all 4 symbols, containing your updated machine code

3. The CLI computes SHA256(new_libapp.so) → say it's "abc123..."

4. The CLI runs bidiff(old, new) → produces a compressed diff

5. The diff + the hash "abc123..." are uploaded to your server

On the user's phone:

1. The Rust updater downloads the compressed diff (150 KB)

2. It decompresses with zstd → gets the raw diff instructions

3. It applies bipatch(original_bundled_libapp.so + diff) → produces a file

4. It computes SHA256(produced_file) → say it's "abc123..."

5. It compares: "abc123..." == "abc123..." ✓ MATCH!

The SHA256 hash is a cryptographic guarantee. If even one single bit is different between the file on the developer's machine and the file reconstructed on the phone, the hashes would be completely different (SHA256 is designed this way — any change produces a totally different hash).

Since the hashes match, the file on the phone is bit-for-bit identical to the file the Dart compiler produced on the developer's machine. It IS a valid libapp.so. It contains the exact same ELF headers, the exact same symbol tables, the exact same machine code bytes. dlopen() loads it, dlsym() finds the symbols, the CPU executes the instructions. There's no difference.

dlc.vmcode IS libapp.so

The file extension is different (.vmcode vs .so) but the file contents are identical in structure. The OS doesn't care about the file extension — dlopen() reads the file contents, not the filename. You could name it potato.xyz and it would still load correctly as long as the bytes inside are a valid ELF shared library.

Chapter 5: What Happens to the Original?

An important detail: the original libapp.so bundled in the APK is never modified, never deleted, and never touched.

/data/app/com.example.app-XXXX/lib/arm64/libapp.so    ← ORIGINAL (read-only, inside APK)
                                                          Never changes. Always there.
                                                          Used as BASE for bipatch.

/data/data/com.example.app/files/shorebird_updater/
└── patches/3/dlc.vmcode                               ← PATCHED (read-write, created by updater)
                                                          Contains the new version.
                                                          What actually gets loaded.

The original stays for three reasons:

1. It's the base for bipatch. The binary diff says "copy bytes 0-50000 from the original." Without the original, the diff is useless. Every future patch is diffed against this same original.

2. It's the fallback. If every patch is bad (crash, hash mismatch, server rollback), the updater returns NULL from next_boot_patch_path(). The engine's default application_library_path still points to the original. The app boots with the original code. You can never be "stuck" — the unpatched app always works.

3. It's read-only. The APK is stored in a read-only partition. Android doesn't let apps modify their own APK. Shorebird works entirely within the app's writable data directory — it never touches the APK itself.

Chapter 6: The Engine Doesn't Know

This is the elegant part. The Flutter engine has no idea patching happened.

Look at what the engine sees:

// Engine's perspective:

// It has a list called application_library_path
// It contains one file path
// It calls dlopen() on that path
// It calls dlsym() to find 4 symbols
// It passes those memory addresses to the Dart VM
// The Dart VM runs

// The engine doesn't check:
//   ❌ Where the file came from
//   ❌ When the file was created
//   ❌ Whether the file was compiled or reconstructed
//   ❌ Whether the file matches the APK
//   ❌ Whether the bytes are "original" or "patched"

// The engine only checks:
//   ✅ Does the file exist at the path?
//   ✅ Does dlopen() succeed? (valid ELF format)
//   ✅ Does dlsym() find the 4 symbols?
//   ✅ Are the memory addresses valid?

Shorebird doesn't hack the engine, doesn't intercept any calls, doesn't modify any engine behavior. It simply changes one string (the file path) in a settings object before the engine reads it. The engine's normal code path handles everything else.

🏨

Analogy: Imagine a hotel concierge who gives directions to a restaurant. Normally they say "Go to Room 101 for dinner." Shorebird whispers to the concierge "Actually, say Room 205 tonight." The guest goes to Room 205, finds a beautifully set table with food, and has dinner. They don't know the room changed. The concierge doesn't know why the room changed. The hotel didn't renovate. Someone just moved the dinner to a different room, and told the concierge the new room number.

Chapter 7: What CAN and CAN'T Be Patched

Now that you understand the science, the limitations make sense:

✅ CAN be patched (changes to libapp.so)

Anything that exists as Dart code and compiles into libapp.so:

• UI changes: Adding/removing/modifying widgets. A new button, a different color, a redesigned screen — all of this is Dart code that compiles to machine instructions in kDartIsolateSnapshotInstructions.

• Business logic: Changing calculations, adding validation, modifying API calls — all Dart functions that compile to machine code.

• String changes: Changing text, error messages, labels — these are constants stored in kDartIsolateSnapshotData.

• Bug fixes: Fixing null pointer exceptions, off-by-one errors, wrong conditions — the fix changes the machine code instructions for that function.

• New Dart packages: Adding a new pub.dev package (that's pure Dart) — its code compiles into libapp.so.

❌ CANNOT be patched (changes outside libapp.so)

Anything that lives in the APK but NOT in libapp.so:

• Native code (Kotlin/Java/Swift/ObjC): These compile to separate .so or framework files, not into libapp.so. Shorebird doesn't touch those.

• AndroidManifest.xml / Info.plist: Permissions, activities, app metadata — these are APK/IPA level, not Dart.

• Assets (images, fonts, JSON files): These are bundled separately in the APK's assets folder, not compiled into libapp.so.

• Native plugin code: If a Flutter plugin has native Kotlin/Swift code, changing the plugin version might change that native code. libapp.so only contains the Dart side of plugins.

• Flutter engine itself: libflutter.so is a separate binary. Upgrading the Flutter engine version requires a new APK.

The simple rule

If you only changed .dart files → it can be patched.
If you changed anything else (native code, assets, manifest, plugins with native code, Flutter version) → you need a new release through the app store.

Chapter 8: Putting It All Together — The Full Picture

YOU (Developer)                    YOUR SERVER                  USER'S PHONE
─────────────                      ────────────                 ────────────

1. Write Dart code
   flutter build → gen_snapshot
   compiles to libapp.so
   (AOT machine code)
        │
        ▼
2. shorebird release
   Upload original libapp.so ──────►  Stored on server
                                      (the "base")
        │
        │   Users download your app
        │   from Play Store ───────────────────────►  APK installed
        │                                             Contains:
        │                                             • libflutter.so (engine+updater)
        │                                             • libapp.so (original Dart code)
        │                                             • shorebird.yaml (config)
        │
3. Change Dart code (add a button)
   Compile new libapp.so
   Download original from server
   bidiff(original, new) → diff
   zstd compress → tiny patch
        │
        ▼
4. shorebird patch
   Upload patch + SHA256 hash ─────►  Stored on server
                                      (the "patch")
        │
        │   User opens app
        │                    ◄─── shorebird.cc runs:
        │                          1. Init updater (Rust)
        │                          2. Check: any installed patch? → YES
        │                          3. Swap path to dlc.vmcode
        │                          4. Dart VM loads PATCHED code
        │                          5. User sees new button! ✓
        │
        │   Background thread:  ◄─── Also happening:
        │                          6. POST /patches/check
        │                    ◄──── 7. "No newer patch" → do nothing
        │                             (or download next patch for next launch)


═══════════════════════════════════════════════════════════════════════

The "magic" is entirely in step 3:

  shorebird.cc swaps the file path BEFORE the Dart VM starts.
  
  The Dart VM loads the file.
  dlopen() loads whatever file is at that path.
  The file is a valid libapp.so (verified by SHA256).
  The CPU executes the machine code inside.
  Your new button renders on screen.

There is no magic. Just a file path swap + verified binary reconstruction.

Summary — The Science in One Paragraph

Your Dart code compiles to native machine code stored in libapp.so. This file is loaded by dlopen() into the process's memory space, and the CPU directly executes the instructions inside. Shorebird creates a binary diff between the old and new libapp.so, compresses it, and sends the tiny diff to phones. On the phone, the Rust updater reconstructs the exact new libapp.so from the diff + the original (verified by SHA256 hash). Before the Dart VM starts, shorebird.cc changes the file path from the original to the reconstructed file. dlopen() loads the reconstructed file — which is byte-for-byte identical to what the compiler produced — and the CPU executes the updated machine code. The new button appears because its compiled ARM64 instructions are now in the memory that the CPU is executing from. Nothing was "injected" or "hacked" — the engine simply loaded a different (but structurally identical) file.

Part 3: Shorebird | shorebird.cc & updater.rs

noreply@blogger.com (Lokesh Jangid) — Thu, 14 May 2026 22:41:29 -0700

shorebird.cc & updater.rs — Complete Deep Dive

Line-by-line explanation of how these two files orchestrate the entire device-side patch loading, with visual flow diagrams for every function.

1. The Big Picture — Two Files, One Job

These two files are the entire "runtime" of Shorebird on a user's phone. Everything else (CLI, backend, diffing) happens elsewhere. On the device, it's just these two talking to each other:

┌──────────────────────────────────────────────────────────────────────────┐
│                           YOUR APP (APK/IPA)                            │
│                                                                         │
│  ┌─────────────────────────────┐    C FFI    ┌────────────────────────┐ │
│  │    shorebird.cc             │ ◄═══════════►│    updater.rs         │ │
│  │    (C++, in Flutter Engine) │   (function  │  (Rust, libupdater.a) │ │
│  │                             │    calls)    │                       │ │
│  │  "The Orchestrator"         │             │  "The Brain"           │ │
│  │  - Reads shorebird.yaml     │             │  - State management    │ │
│  │  - Calls Rust functions     │             │  - Network calls       │ │
│  │  - Swaps libapp.so path     │             │  - Patch download      │ │
│  │  - Starts Dart VM           │             │  - Diff inflation      │ │
│  └─────────────────────────────┘             │  - Hash verification   │ │
│                                              │   - Crash recovery     │ │
│  ┌─────────────────────────────┐             │  - Event reporting     │ │
│  │    libapp.so                │             └────────────────────────┘ │
│  │    (Your Dart code - AOT)   │                         │              │
│  │    OR                       │                         │              │
│  │    dlc.vmcode               │                         ▼              │
│  │    (Patched Dart code)      │             ┌────────────────────────┐ │
│  └─────────────────────────────┘             │    state.json          │ │
│                                              │    (on-device storage) │ │
│                                              └────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘

C++ shorebird.cc — "The Orchestrator"

298 lines. Lives inside the Flutter engine. Its job is to be the middleman between the Flutter engine's boot process and the Rust updater library. It reads config, calls Rust functions via C FFI, and modifies the engine's settings.application_library_path to load the patched binary.

Knows about: Flutter Settings object, file paths, shorebird.yaml content, engine lifecycle.

Does NOT know about: Network, patches, state, diffing, hashing.

RUST updater.rs — "The Brain"

3,665 lines. The complete updater logic. Manages all state, makes network calls, downloads patches, inflates diffs, verifies hashes, handles crash recovery, tracks boot lifecycle, and queues events.

Knows about: Everything patch-related — state, network, patches, hashes, events, lifecycle.

Does NOT know about: Flutter, Dart VM, Android, iOS, engine internals. It's a pure library.

2. The C FFI Bridge — How C++ Talks to Rust

shorebird.cc can't call Rust functions directly. It calls C functions (defined in c_api/engine.rs) which are thin wrappers around the Rust updater:: module:

C Function (called by shorebird.cc)	Rust Function (actual logic)	Purpose
`shorebird_init()`	`updater::init()`	Parse config, load state, crash recovery
`shorebird_next_boot_patch_path()`	`updater::next_boot_patch()`	Returns path to patched file (or NULL)
`shorebird_report_launch_start()`	`updater::report_launch_start()`	Records "we're booting this patch"
`shorebird_report_launch_success()`	`updater::report_launch_success()`	Marks patch as "booted OK"
`shorebird_report_launch_failure()`	`updater::report_launch_failure()`	Marks patch as "bad"
`shorebird_should_auto_update()`	`updater::should_auto_update()`	Reads auto_update from config
`shorebird_start_update_thread()`	`updater::start_update_thread()`	Spawns background download thread
`shorebird_validate_next_boot_patch()`	`updater::validate_next_boot_patch()`	Checks patch file integrity
`shorebird_free_string()`	deallocate	Frees strings returned by Rust

How the bridge works

Rust compiles updater.rs + c_api/engine.rs into a static library (libupdater.a). The #[no_mangle] pub extern "C" attribute tells Rust to export each function with C calling conventions. The engine's BUILD.gn links this .a file into libflutter.so. So when shorebird.cc calls shorebird_init(), it's a normal function call — no IPC, no JNI, no overhead. Just a direct jump into Rust-compiled machine code within the same binary.

3. shorebird.cc — Line by Line

3.1 The Call Chain (How We Get Here)

Android starts your app
    │
    ▼
FlutterActivity.onCreate()                          [Java]
    │
    ▼
FlutterJNI.nativeInit(shorebirdYaml, version, ...)  [Java → JNI]
    │
    ▼
FlutterMain::Init()                                  [C++, flutter_main.cc]
    │
    ▼
#if FLUTTER_RELEASE        ◄── Shorebird ONLY runs in release builds
    ConfigureShorebird(code_cache_path, app_storage_path,
                       settings, shorebird_yaml, version,
                       version_code);
#endif
    │
    ▼
settings.application_library_path is now modified (or not)
    │
    ▼
Dart VM starts, loads libapp.so from that path
    │
    ▼
main() runs in Dart ← either original or patched code

3.2 ConfigureShorebird() — The Main Function

There are actually two overloads of this function — one for Android (receives Flutter Settings&) and one for newer platforms (receives a ShorebirdConfigArgs struct). They do the same thing. I'll trace the Android one since that's what you use:

C++ L153 Create directory

auto shorebird_updater_dir_name = "shorebird_updater";
auto code_cache_dir = JoinPaths({code_cache_path, shorebird_updater_dir_name});
auto app_storage_dir = JoinPaths({app_storage_path, shorebird_updater_dir_name});
fml::CreateDirectory(GetCachesDirectory(), {shorebird_updater_dir_name}, kReadWrite);

Creates /data/data/com.app/cache/shorebird_updater/ and /data/data/com.app/files/shorebird_updater/. These directories store downloaded patches and state files. Created before calling Rust so the updater has a place to write.

C++ L165 Build AppParameters + call shorebird_init()

AppParameters app_parameters;
auto release_version = version + "+" + version_code;  // "1.0.0" + "1" = "1.0.0+1"
app_parameters.release_version = release_version.c_str();
app_parameters.code_cache_dir = code_cache_dir.c_str();
app_parameters.app_storage_dir = app_storage_dir.c_str();
app_parameters.original_libapp_paths = c_paths.data();    // path to bundled libapp.so
app_parameters.original_libapp_paths_size = c_paths.size();

init_result = shorebird_init(&app_parameters, ShorebirdFileCallbacks(),
                             shorebird_yaml.c_str());

Packs all the info the Rust updater needs into a C struct and calls shorebird_init(). The shorebird_yaml string is the raw YAML content of your shorebird.yaml file (read from flutter_assets by Java). This is where Rust takes over — see Section 4 for what happens inside.

C++ L199 iOS only: SetBaseSnapshot()

#if SHOREBIRD_USE_INTERPRETER
  SetBaseSnapshot(settings);
#endif

On iOS, Shorebird uses an interpreter-based approach. SetBaseSnapshot() captures the VM and isolate snapshot mappings from the original App.framework. These are passed to the Rust updater via FileCallbacks so it can read the original binary in memory (iOS doesn't allow direct file access to framework bundles the same way Android does).

On Android, this is skipped — the original libapp.so is directly accessible via its file path.

C++ L202 ⭐ THE KEY MOMENT: Ask for patch path + SWAP

char* c_active_path = shorebird_next_boot_patch_path();
if (c_active_path != NULL) {
    std::string active_path = c_active_path;
    shorebird_free_string(c_active_path);

    // ANDROID: Replace the library path entirely
    settings.application_library_path.clear();
    settings.application_library_path.emplace_back(active_path);

    // iOS: Insert at front (keep original for VM snapshot)
    // settings.application_library_path.insert(begin(), active_path);
} else {
    // No patch — use the original bundled libapp.so (do nothing)
}

This is the single most important code in all of Shorebird.

The engine has a list called application_library_path that tells the Dart VM which .so file to load. Normally it points to the bundled libapp.so inside the APK.

If the Rust updater returns a path (meaning a patch is installed), this code replaces that list with the patch file's path. When the Dart VM starts a few milliseconds later, it loads the patched file instead. Your updated Dart code runs without ever touching the Play Store.

If the updater returns NULL (no patch, or patch is bad), the list is unchanged — the original bundled libapp.so loads as normal.

C++ L225 Report launch start + start update thread

if (!init_result) {
    return;  // init failed (e.g., bad YAML) — don't touch anything
}

shorebird_report_launch_start();     // "We're about to boot patch N"

if (shorebird_should_auto_update()) {
    shorebird_start_update_thread(); // Background: check for NEXT patch
}

report_launch_start() tells the Rust updater "we are now booting with this patch." This is the safety mechanism — if the app crashes between this call and report_launch_success(), the next launch will detect it and roll back.

start_update_thread() spawns a Rust background thread that checks the server for a NEWER patch. This runs completely independently from the app — the Dart VM is already starting. If a new patch is found, it's downloaded for the next app launch (not the current one).

That's it for shorebird.cc

It's only ~70 lines of actual logic (the rest is iOS/Android differences, the FileCallbacks implementation, and a getauxval workaround for old Android NDKs). It does 5 things: (1) create directories, (2) call shorebird_init, (3) ask for patch path, (4) swap the library path, (5) start the background updater. Everything complex happens in Rust.

4. updater.rs — Line by Line

This is the 3,665-line Rust file that does all the heavy lifting. Let me break it into its logical sections:

4.1 Global State Architecture

┌──────────────────────────────────────────────────────────────┐
│                    updater.rs — Global State                 │
│                                                              │
│  ┌────────────────┐       ┌─────────────────────────────┐   │
│  │  UPDATE_CONFIG  │       │      UPDATER_STATE          │   │
│  │  (OnceLock)     │       │  (Mutex<Option<Box>>)       │   │
│  │                 │       │                             │   │
│  │  Set ONCE in    │       │  Set in init(), accessed    │   │
│  │  init(), never  │       │  via with_state() and       │   │
│  │  changes after  │       │  with_mut_state() which     │   │
│  │                 │       │  lock the mutex             │   │
│  │  Contains:      │       │                             │   │
│  │  - app_id       │       │  Contains:                  │   │
│  │  - base_url     │       │  - client_id                │   │
│  │  - channel      │       │  - patches lifecycle        │   │
│  │  - auto_update  │       │  - next_boot_patch          │   │
│  │  - storage_dir  │       │  - currently_booting_patch  │   │
│  │  - download_dir │       │  - last_booted_patch        │   │
│  │  - release_ver  │       │  - known_bad_patches        │   │
│  │  - libapp_path  │       │  - queued_events            │   │
│  └────────────────┘       └─────────────────────────────┘   │
│                                                              │
│  ┌────────────────┐                                          │
│  │ UPDATER_THREAD  │  Mutex<()> — ensures only one update    │
│  │ _LOCK           │  cycle runs at a time                   │
│  └────────────────┘                                          │
└──────────────────────────────────────────────────────────────┘

Why this architecture? The updater runs in two contexts simultaneously: (1) the engine thread calling init/next_boot_patch/report_launch_* during boot, and (2) the background update thread checking for new patches. The Mutex on UPDATER_STATE prevents data races. The OnceLock on UPDATE_CONFIG ensures config is set exactly once and never changes.

4.2 init() — First Function Called

shorebird_init() in C
    │
    ▼
updater::init(app_config, file_provider, yaml_string)
    │
    ├── 1. init_logging()                    — Sets up Android logcat / iOS NSLog
    │
    ├── 2. YamlConfig::from_yaml(yaml)       — Parses shorebird.yaml:
    │       {                                    app_id: "abc-123"
    │         app_id, base_url, channel,         base_url: "https://your-server.com"
    │         auto_update, patch_public_key,      channel: "stable"
    │         patch_verification                  auto_update: true
    │       }
    │
    ├── 3. libapp_path_from_settings()       — Finds the bundled libapp.so path
    │       (e.g., "/data/app/com.app/lib/arm64/libapp.so")
    │
    ├── 4. set_config()                      — Stores everything in UPDATE_CONFIG (OnceLock)
    │       If already set → return AlreadyInitialized (not an error)
    │       This merges app_config (paths from engine) + yaml_config (settings from yaml)
    │
    └── 5. handle_prior_boot_failure_if_necessary()    ← THE CRASH RECOVERY

4.3 handle_prior_boot_failure_if_necessary() — Crash Recovery

This is the function that makes Shorebird safe. It runs on EVERY app start, before any patch is loaded:

handle_prior_boot_failure_if_necessary()
    │
    ├── Load state from disk: state.json + patches/*/state.json
    │
    ├── Check: is "currently_booting_patch" set?
    │
    ├── NO → Return OK (last boot was clean, nothing to do)
    │
    └── YES → A previous boot CRASHED before report_launch_success()!
         │
         ├── Read crash details:
         │   - boot_started_at = when the boot started
         │   - file_ok = does the patch file still exist?
         │   - file_size = how big is it?
         │
         ├── state.record_boot_failure_for_patch(patch_number)
         │   └── Marks this patch as "Bad" with reason "CrashRecovery"
         │       └── It will NEVER be loaded again (even if server offers it)
         │
         └── state.queue_event(__patch_install_failure__)
             └── Queued to be sent to server on next successful network call
                 └── Message: "crash_recovery: patch 3 failed to boot
                              (detected_at=1714000000,
                               boot_started_at=1713999990,
                               file_ok=true,
                               file_size=3148000)"

Why this works

The trick is simple: before loading a patch, report_launch_start() writes "I'm about to boot patch N" to disk. After the Dart VM is fully running, report_launch_success() clears that flag. If the app crashes in between (bad Dart code, segfault, ANR kill), the flag stays on disk. Next launch, handle_prior_boot_failure sees the flag and says "that patch killed us — never load it again."

4.4 next_boot_patch() — Which File to Load?

shorebird_next_boot_patch_path() in C
    │
    ▼
updater::next_boot_patch()
    │
    ├── Lock UPDATER_STATE mutex
    │
    ├── state.next_boot_patch()
    │   │
    │   ├── Check patches lifecycle for latest "Installed" patch
    │   │   that is NOT in the "Bad" list
    │   │
    │   ├── Found? → Return PatchInfo { number: 3,
    │   │              path: "/data/.../shorebird_updater/patches/3/dlc.vmcode" }
    │   │
    │   └── Not found? → Return None
    │
    ├── If Some(patch) → convert path to C string, return pointer
    │
    └── If None → return NULL pointer

    ↓ Back in shorebird.cc:
    If non-NULL → swap application_library_path
    If NULL → keep original libapp.so

4.5 report_launch_start() — The Safety Net

shorebird_report_launch_start() in C     ← called ONCE per process (std::once_flag)
    │
    ▼
updater::report_launch_start()
    │
    ├── state.next_boot_patch() → get the patch we're about to boot
    │
    ├── state.set_running_patch(patch_number)
    │   └── In-memory only: "this process is running patch 3"
    │       (used by the Dart FFI: shorebird_current_boot_patch_number)
    │
    └── state.record_boot_start_for_patch(patch_number)
        └── WRITES TO DISK: sets "currently_booting_patch = 3"
            and "boot_started_at = now"
            └── This is the flag that handle_prior_boot_failure checks
                If we crash before report_launch_success(), this flag
                persists → next launch will see it → rollback

4.6 report_launch_success() — "We're Safe"

shorebird_report_launch_success()        ← called when Dart VM finishes booting
    │
    ▼
updater::report_launch_success()
    │
    ├── state.currently_booting_patch() → get patch 3
    │
    ├── state.last_successfully_booted_patch() → get patch 2 (previous)
    │
    ├── state.record_boot_success()
    │   └── WRITES TO DISK:
    │       - Clears "currently_booting_patch" (the safety flag)
    │       - Sets "last_successfully_booted_patch = 3"
    │       └── Now the crash recovery won't trigger for patch 3
    │
    ├── Did the patch number change? (3 != 2? Yes)
    │   └── Spawn a thread to report __patch_install_success__ event
    │       └── POST /api/v1/patches/events (fire-and-forget, in background)
    │
    └── Return OK

4.7 start_update_thread() — Background Check for Next Patch

shorebird_start_update_thread() in C
    │
    ▼
updater::start_update_thread()
    │
    └── std::thread::spawn(move || {
            let result = update(None);    ← calls the full update cycle
            // logs success or error, thread exits
        });

update(channel: None)
    │
    ├── Acquire UPDATER_THREAD_LOCK (only one update at a time)
    │   └── If already locked → return UpdateInProgress
    │
    └── update_internal()    ← see next section

4.8 update_internal() — The Full Update Cycle

This is the longest function — the complete check → download → install pipeline:

update_internal()
    │
    ├── ①  SEND QUEUED EVENTS (max 3)
    │      for event in state.copy_events(3):
    │          POST /api/v1/patches/events → { app_id, type, patch_number, ... }
    │      state.clear_events()
    │
    ├── ②  BUILD CHECK REQUEST
    │      PatchCheckRequest {
    │          app_id: "abc-123",
    │          release_version: "1.0.0+1",
    │          platform: "android",
    │          arch: "aarch64",
    │          channel: "stable",
    │          client_id: "device-uuid",
    │          patch_number: 2  (currently installed, if any)
    │      }
    │
    ├── ③  POST /api/v1/patches/check
    │      Response: {
    │          patch_available: true,
    │          patch: { number: 3, download_url: "https://...",
    │                   hash: "sha256...", hash_signature: null },
    │          rolled_back_patch_numbers: [1]
    │      }
    │
    ├── ④  PROCESS ROLLBACKS
    │      for num in rolled_back_patch_numbers:
    │          state.uninstall_patch(num)
    │          └── Deletes dlc.vmcode file + removes from lifecycle
    │
    ├── ⑤  DECIDE: Should we download?
    │      lifecycle.decide_start(patch_3, url, hash)
    │      │
    │      ├── KnownBad → SKIP (this patch crashed before, never retry)
    │      ├── AlreadyInstalled → SKIP (same number + same hash)
    │      ├── Resume {offset} → RESUME download from byte N
    │      ├── Complete → SKIP download (already downloaded, go to install)
    │      └── Download → START fresh download
    │
    ├── ⑥  DOWNLOAD (if needed)
    │      lifecycle.record_download_started(number, url, hash)
    │      download_to_path(url, cache/patches/3/download.bin, resume_offset)
    │      └── HTTP GET with Range header support
    │      Verify: actual_bytes == Content-Length (if provided)
    │      lifecycle.record_download_complete(number, total_bytes)
    │
    ├── ⑦  INSTALL
    │      install_downloaded_patch(&config, &patch, &download_path)
    │      │
    │      ├── inflate(download.bin, bundled_libapp, patches/3/dlc.vmcode)
    │      │   ├── Thread 1: zstd decompress (download.bin → pipe)
    │      │   └── Thread 2: bipatch(pipe + bundled_libapp → dlc.vmcode)
    │      │
    │      ├── check_hash(dlc.vmcode, expected_hash)
    │      │   ├── Match → Continue ✓
    │      │   └── Mismatch → Mark Bad(InstallHashMismatch), return error
    │      │
    │      ├── lifecycle.record_install_complete(number, file_size)
    │      │
    │      ├── lifecycle.promote_to_next_boot(number)
    │      │   └── WRITES TO DISK: "next_boot_patch = 3"
    │      │
    │      └── Queue __patch_download__ event for server
    │
    └── ⑧  DONE — Return UpdateStatus::UpdateInstalled
            Next time the app launches, shorebird_next_boot_patch_path()
            will return patches/3/dlc.vmcode

4.9 report_launch_failure() — Emergency Rollback

updater::report_launch_failure()     ← called by engine if Dart VM fails to start
    │
    ├── state.currently_booting_patch() → get patch 3
    │
    ├── state.record_boot_failure_for_patch(3)
    │   └── Marks patch 3 as Bad (same as crash recovery)
    │
    └── state.queue_event(__patch_install_failure__)
        └── Message: "engine_report: patch 3 failed to launch"

    After this, the engine will likely abort() the process.
    On next launch, handle_prior_boot_failure won't even see the
    currently_booting_patch flag (already cleared by record_boot_failure)
    but patch 3 is in the Bad list → next_boot_patch() skips it.

5. Complete Timeline — Everything in Order

Here's every function call from the moment the user taps your app icon to when they see the UI, with exact timing:

TIME     WHO              FUNCTION                         WHAT HAPPENS
─────    ─────            ─────────                        ─────────────
0ms      Android          Process created                  System spawns the app process
5ms      Java             FlutterActivity.onCreate()       Flutter Android embedding starts
10ms     Java → JNI       FlutterJNI.nativeInit()          Reads shorebird.yaml from assets
12ms     C++ (shorebird)  ConfigureShorebird()             Entry point
13ms     C++              CreateDirectory()                Creates shorebird_updater/ dirs
15ms     C++ → Rust       shorebird_init()                 Parses YAML, sets global config
16ms     Rust             init()                           
17ms     Rust             handle_prior_boot_failure()      Checks for crash flag on disk
         Rust             └── if flag set: mark bad        (takes ~1ms to read state.json)
18ms     C++ → Rust       shorebird_next_boot_patch_path() Asks "which .so to load?"
19ms     Rust             next_boot_patch()                Reads lifecycle, returns path or NULL
20ms     C++              ⭐ SWAP library path              settings.application_library_path = patch
22ms     C++ → Rust       shorebird_report_launch_start()  Writes "booting patch 3" to disk
23ms     C++ → Rust       shorebird_start_update_thread()  Spawns background Rust thread
25ms     C++ (Engine)     Dart VM starts                   Loads .so from application_library_path
         │                                                 (loads dlc.vmcode if patch, else libapp.so)
         │
50ms     Dart             main() runs                      YOUR patched Dart code executes!
         │                                                 ← User sees splash screen
         │
         │  Meanwhile, in the background Rust thread:
         │
25ms     Rust (bg)        update_internal()                Starts checking
26ms     Rust (bg)        send queued events               Reports pending __patch_install__ etc.
30ms     Rust (bg)        POST /patches/check              Asks server for newer patch
150ms    Rust (bg)        Response received                "patch 4 available at https://..."
200ms    Rust (bg)        decide_start()                   "Fresh download needed"
210ms    Rust (bg)        download_to_path()               Downloading patch 4 (~150 KB)
800ms    Rust (bg)        inflate()                        Decompress + bipatch → dlc.vmcode
900ms    Rust (bg)        check_hash()                     SHA256 verify ✓
910ms    Rust (bg)        promote_to_next_boot()           next_boot_patch = 4
         │
         │  Meanwhile, in the main thread:
         │
200ms    C++ (Engine)     DartIsolate created              Dart VM finished initializing
250ms    C++ → Rust       shorebird_report_launch_success() "Patch 3 booted OK" ✓
         Rust             └── Clears currently_booting flag
         Rust             └── Sends __patch_install_success__ event (background thread)
         │
300ms+   Dart             App is running normally          User interacts with the app
         │
         │  Next app launch: will boot patch 4 (not 3)

Notice the timing

The entire Shorebird overhead is ~15ms (from ConfigureShorebird entry to start_update_thread). The background download happens completely independently — the user never waits for it. They see the current patch immediately, and the next patch downloads silently for the next launch.

6. What's On Disk — The State Files

/data/data/com.example.app/
├── files/shorebird_updater/                    ← PERSISTENT (survives cache clear)
│   ├── state.json                              ← Global state
│   │   {
│   │     "client_id": "550e8400-e29b-41d4-a716-446655440000",
│   │     "release_version": "1.0.0+1"
│   │   }
│   │
│   ├── pointers.json                           ← Which patch to boot
│   │   {
│   │     "next_boot": 3,
│   │     "last_successfully_booted": 3,
│   │     "currently_booting": null,            ← null = safe state
│   │     "boot_started_at": null
│   │   }
│   │
│   └── patches/
│       ├── 2/
│       │   ├── state.json                      ← Patch lifecycle
│       │   │   { "status": "installed", "hash": "abc...", "size": 3148000 }
│       │   └── dlc.vmcode                      ← THE PATCHED libapp.so (3.1 MB)
│       │
│       └── 3/
│           ├── state.json
│           │   { "status": "installed", "hash": "def...", "size": 3149000 }
│           └── dlc.vmcode                      ← LATEST PATCH (loaded on boot)
│
└── cache/shorebird_updater/                    ← TEMPORARY (can be cleared)
    └── patches/
        └── 4/
            └── download.bin                    ← In-progress download (compressed diff)

───────────────────────────────────────────────────────
The ORIGINAL libapp.so is inside the APK at:
/data/app/com.example.app-XXXX/lib/arm64/libapp.so
This file is READ-ONLY (part of the APK). It's used as the
BASE for bipatch — the diff is applied against this file.

7. Complete Function Reference

shorebird.cc (C++ — 298 lines)

Function	Lines	Called By	Purpose
`ConfigureShorebird(args, patch_path)`	~50	Android flutter_main.cc	Main entry: init → get path → swap → start update
`ConfigureShorebird(settings, yaml, ...)`	~60	iOS/other platforms	Same logic, different parameter format
`SetBaseSnapshot(settings)`	~10	ConfigureShorebird (iOS)	Captures VM/isolate snapshot mappings for interpreter mode
`ShorebirdFileCallbacks()`	~8	ConfigureShorebird	Returns C function pointers for Rust to read the bundled binary
`FileCallbacksImpl::Open/Read/Seek/Close`	~20	Rust updater via FFI	In-memory file abstraction over snapshot mappings

updater.rs (Rust — 3,665 lines, 15 public functions)

Function	Called By	Thread	Purpose
`init()`	shorebird.cc via FFI	Main	Parse YAML, set config, crash recovery
`handle_prior_boot_failure()`	init()	Main	Detect + handle crashed patches
`next_boot_patch()`	shorebird.cc via FFI	Main	Return path to best available patch
`report_launch_start()`	shorebird.cc via FFI	Main	Write "booting patch N" safety flag to disk
`report_launch_success()`	Engine (after Dart VM boots)	Main	Clear safety flag, send success event
`report_launch_failure()`	Engine (on Dart VM failure)	Main	Mark patch bad, queue failure event
`should_auto_update()`	shorebird.cc via FFI	Main	Read auto_update from YAML config
`start_update_thread()`	shorebird.cc via FFI	Main→spawns BG	Spawn thread that calls update()
`update(channel)`	start_update_thread / Dart FFI	Background	Acquire lock, call update_internal
`update_internal()`	update()	Background	Full cycle: check→download→inflate→verify→install
`install_downloaded_patch()`	update_internal()	Background	inflate + hash check + promote
`inflate()`	install_downloaded_patch()	BG + spawns thread	Zstd decompress → bipatch → output
`check_hash()`	install_downloaded_patch()	Background	SHA256 verify reconstructed file
`roll_back_patches_if_needed()`	update_internal()	Background	Uninstall server-rolled-back patches
`validate_next_boot_patch()`	shorebird.cc via FFI	Main	Integrity check on patch file
`running_patch()`	Dart FFI	Any	Return which patch this process is running
`check_for_downloadable_update()`	Dart FFI	Isolate	Check server without downloading

Part 2: Shorebird | bidiff Algorithm & Zstd Compression

noreply@blogger.com (Lokesh Jangid) — Thu, 14 May 2026 22:34:49 -0700

A visual, byte-level explanation of how Shorebird computes the exact difference between two binaries and compresses it for efficient OTA delivery.

1. The Problem — Why Not Just Send the New File?

When you change Dart code and create a patch, two libapp.so files exist:

OLD libapp.so (3,146 KB)

← already on user's phone

NEW libapp.so (3,148 KB)

← contains your code changes

You could send the entire 3,148 KB new file. But here's the thing — when you change a few lines of Dart code, maybe 95-98% of the bytes are identical. The Dart compiler produces AOT machine code where most functions, the standard library, all your unchanged widgets, constants, and data structures remain byte-for-byte the same.

The question becomes: can we send ONLY the bytes that changed? That's what bidiff does.

2. bidiff — Binary Diff Algorithm

2.1 What is bidiff?

bidiff (version 1.0.0, created by Amos Wenger / fasterthanlime) is a binary delta encoding algorithm. It's conceptually similar to the famous bsdiff algorithm (used by Chrome, Firefox, and Android system updates) but written in Rust with a cleaner API.

It takes two byte sequences (old file + new file) and produces a compact set of instructions that describe how to transform the old file into the new file.

2.2 The Core Idea — Suffix Sorting

Step 1: Build a Suffix Array of the Old File

The algorithm sorts ALL possible suffixes (substrings starting at every byte position) of the old file. This creates an index that can find any byte pattern in the old file in O(log n) time.

Think of it like building a phone book — but instead of names, every "entry" is a position in the old file, and they're sorted by what bytes appear at that position.

Let's trace through a tiny example to see how it works:

🔬 Worked Example

OLD file: "Hello World! This is my Flutter app."

NEW file: "Hello World! This is my updated Flutter app!"

The algorithm scans the new file byte by byte, looking for the longest match in the old file:

OLD file bytes:

NEW file bytes:

■ Green = identical bytes at same position ■ Blue = new/inserted bytes ■ Red = bytes that exist in old but at different position

2.3 The Three Operations

bidiff encodes the diff as a stream of three operation types:

📋 COPY(old_offset, length)

"Copy length bytes from the OLD file starting at position old_offset."

This is the powerhouse operation. When the algorithm finds a sequence in the new file that matches somewhere in the old file, it encodes it as a COPY instead of storing the actual bytes. For libapp.so, COPY operations cover 90-98% of the new file.

➕ ADD(delta_bytes)

"Add these delta values byte-by-byte to the copied bytes."

Sometimes the new file is almost identical to a section in the old file, but with small byte-level differences (like a function offset shifting by a few bytes). ADD captures these "near misses" efficiently — instead of storing the full new bytes, it stores the difference between old and new bytes at each position.

🆕 INSERT(new_bytes)

"Insert these entirely new bytes that don't exist anywhere in the old file."

When you add a completely new function or string literal, those bytes have no match in the old file. They get encoded as raw INSERT operations. This is the most expensive operation but typically covers only 2-10% of the file.

2.4 The Diff for Our Example

Instruction 1:  COPY(offset=0, length=24)       → "Hello World! This is my "
                                                    ↑ 24 bytes from old file position 0

Instruction 2:  INSERT("updated ")               → "updated "
                                                    ↑ 8 new bytes (not in old file)

Instruction 3:  COPY(offset=24, length=11)       → "Flutter app"
                                                    ↑ 11 bytes from old file position 24

Instruction 4:  INSERT("!")                       → "!"
                                                    ↑ 1 new byte (replaces ".")

─────────────────────────────────────────────────────────
TOTAL DIFF SIZE:  3 offsets/lengths (maybe 12 bytes)
                + 9 bytes of new data
                = ~21 bytes to describe transformation

vs. sending entire new file = 44 bytes
vs. old file size           = 36 bytes

Savings: 52% reduction (and this gets MUCH better with larger files)

2.5 How It Scales to libapp.so (3 MB)

With a real libapp.so, the same principle applies at a massive scale:

Scenario	COPY %	ADD %	INSERT %	Diff Size
Change 1 line of Dart code	~99%	~0.5%	~0.5%	~30 KB
Change 10 files	~97%	~1.5%	~1.5%	~80 KB
Major refactor (50 files)	~90%	~5%	~5%	~300 KB
Complete rewrite	~40%	~10%	~50%	~1.5 MB

2.6 The DiffParams in Shorebird

// updater/patch/src/lib.rs
let diff_params = DiffParams::new(
    1,     // scan_block_size: minimum match length (1 byte granularity)
    None   // sort_partitions: auto (uses available CPU cores)
).unwrap();

bidiff::simple_diff_with_params(&older[..], &newer[..], &mut writer, &diff_params);

scan_block_size = 1 means the algorithm looks for matches at single-byte granularity — the most thorough (but slowest) setting. Since this runs on the developer's machine (not the phone), speed isn't critical.

Why bidiff over bsdiff?

bsdiff is the original (from 2003, by Colin Percival). bidiff is a Rust reimplementation with the same core algorithm (suffix array + binary diff) but with a cleaner streaming API, better memory efficiency, and native Rust integration. Shorebird chose it because the entire updater library is Rust, and bidiff integrates seamlessly with bipatch (the reverse operation).

3. bipatch — Applying the Diff on the Device

bipatch is the inverse of bidiff. It runs on the user's phone and reconstructs the new file from the old file + the diff instructions.

// On the device (Rust updater):
let mut reader = bipatch::Reader::new(
    diff_stream,     // the decompressed diff instructions
    old_file_reader  // seekable reader over the original bundled libapp.so
);

// reader now behaves like a Read stream that outputs the NEW file bytes
std::io::copy(&mut reader, &mut output_file);

bipatch processes the instruction stream sequentially:

1. Read instruction header → it's a COPY(offset=0, length=24)
2. Seek to byte 0 in the old file, read 24 bytes → write to output
3. Read next instruction → INSERT(8 bytes)
4. Read 8 bytes from the diff stream → write to output
5. Read next instruction → COPY(offset=24, length=11)
6. Seek to byte 24 in the old file, read 11 bytes → write to output
7. ...and so on until the diff stream is exhausted

The output is a byte-for-byte identical copy of the new libapp.so. The SHA256 hash is verified after reconstruction to guarantee this.

4. Zstd Compression — Making the Diff Even Smaller

4.1 What is Zstd?

Zstandard (zstd) is a real-time compression algorithm created by Yann Collet at Facebook/Meta in 2015. It's designed to provide high compression ratios at very fast speeds — both for compression and decompression.

It's used by: Linux kernel, Android system updates, databases (RocksDB, PostgreSQL), game engines (Unreal), and hundreds of other systems. It's essentially the modern replacement for both gzip (zlib) and Snappy.

4.2 How Zstd Works (Simplified)

Zstd combines three compression techniques:

① LZ77 — Find Repeated Patterns

Scans the data with a sliding window, looking for byte sequences that appeared earlier. When it finds a match, it replaces the repeated bytes with a (distance, length) reference: "Go back distance bytes and copy length bytes from there."

Example: In the diff instructions, many COPY operations have similar offset patterns. LZ77 captures this repetition.

② Finite State Entropy (FSE) — Smart Encoding

After LZ77, the stream of literals, match lengths, and offsets is encoded using Finite State Entropy (zstd's custom entropy coder, an alternative to Huffman coding). FSE assigns shorter bit patterns to more common values and longer patterns to rare values.

If the byte 0x00 appears 40% of the time in the diff, FSE might encode it as just 2 bits instead of 8.

③ Dictionary + Repeat Offsets

Zstd keeps track of the 3 most recent match offsets. Since consecutive matches often have similar offsets (common in structured binary data like ELF files), referencing a "repeat offset" costs almost nothing — sometimes just 1-2 bits.

4.3 Why Zstd Specifically?

✅ Why Shorebird chose Zstd

Decompression speed: ~1.5 GB/s on mobile ARM64 — near memory-copy speed. The phone decompresses a 150 KB patch in <1ms.

Compression ratio: 3-5x better than Snappy, comparable to gzip at similar speed.

Streaming support: Can decompress byte-by-byte without loading the entire file into memory. Critical for the pipe architecture.

Small decoder: The decompression code adds only ~30 KB to the binary size.

Alternatives considered

gzip/zlib: 2-3x slower decompression, ~20% worse compression.

brotli: 10-15% better compression, but 3x slower decompression. Good for web assets, overkill for mobile OTA.

lz4: 2x faster decompression, but 2x worse compression ratio. The diff would be larger.

No compression: The bidiff output has high entropy but still contains repetitive patterns (similar offset values, runs of zeros). Zstd captures 60-70% further reduction.

4.4 The Magic Bytes

// Every zstd compressed file starts with these 4 bytes:
const ZSTD_MAGIC: [u8; 4] = [0x28, 0xB5, 0x2F, 0xFD];

// The device validates this BEFORE attempting decompression:
fn validate_compressed_patch(patch_path: &Path) {
    let mut magic = [0u8; 4];
    file.read_exact(&mut magic);
    if magic != ZSTD_MAGIC {
        bail!("Not a valid zstd archive — download may be corrupt");
    }
}

This is a quick sanity check that prevents wasting CPU on garbage data (e.g., if the download was corrupted or a CDN served an error page instead of the patch file).

5. The Complete Pipeline — Putting It All Together

5.1 On Developer's Machine (Creating the Patch)

old libapp.so
3,146 KB

new libapp.so
3,148 KB

→

bidiff
suffix sort + diff

→

raw diff
~480 KB

→

zstd compress
level 3 (default)

→

patch.bin
~150 KB ✓

// updater/patch/src/lib.rs — the exact code
pub fn make_patch(older: Vec<u8>, newer: Vec<u8>, patch: &mut WS) {
    let (mut patch_r, mut patch_w) = pipe::pipe();    // in-memory pipe
    let diff_params = DiffParams::new(1, None).unwrap();

    // Thread 1: compute binary diff, write to pipe
    std::thread::spawn(move || {
        bidiff::simple_diff_with_params(&older, &newer, &mut patch_w, &diff_params).unwrap();
    });

    // Thread 2 (this thread): read diff from pipe, compress with zstd, write to output
    let compressor = ZstdCompressor::new();
    compressor.compress(&mut BufWriter::new(patch), &mut patch_r).unwrap();
}

Two threads run in parallel, connected by a pipe. Thread 1 produces diff bytes into the pipe, Thread 2 reads and compresses them. This is a producer-consumer pattern — the diff doesn't need to be fully computed before compression starts.

5.2 On User's Phone (Applying the Patch)

patch.bin
~150 KB (downloaded)

→

zstd decompress
<1ms on ARM64

→

raw diff
~480 KB

bundled libapp.so
from APK (3,146 KB)

→

bipatch
apply instructions

→

dlc.vmcode
3,148 KB ✓

// updater/library/src/updater.rs — the exact code
fn inflate(patch_path: &Path, base_reader: RS, output_path: &Path) {
    // Validate zstd magic bytes first
    validate_compressed_patch(patch_path);

    let compressed_patch_r = BufReader::new(File::open(patch_path));
    let output_file_w = File::create(output_path);

    let (patch_r, patch_w) = pipe::pipe();    // in-memory pipe

    // Thread 1: decompress zstd → write decompressed diff into pipe
    let decompress = ZstdDecompressor::new();
    std::thread::spawn(move || {
        decompress.copy(compressed_patch_r, patch_w);
    });

    // Thread 2 (this thread): read decompressed diff from pipe
    //                         + read original libapp.so from APK
    //                         → apply bipatch → write new libapp.so
    let mut fresh_r = bipatch::Reader::new(patch_r, base_reader);
    std::io::copy(&mut fresh_r, &mut BufWriter::new(output_file_w));
}

Same pipe architecture as the creation side, but reversed. Decompression and patching happen in parallel. The phone never needs to hold the entire decompressed diff in memory — it streams through the pipe.

5.3 Verification

fn check_hash(file_path: &Path, expected_hash: &str) -> Result<()> {
    let mut file = File::open(file_path)?;
    let mut hasher = Sha256::new();
    std::io::copy(&mut file, &mut hasher)?;
    let actual_hash = hex::encode(hasher.finalize());

    if actual_hash != expected_hash {
        bail!("Hash mismatch: expected {}, got {}", expected_hash, actual_hash);
    }
    Ok(())
}

After dlc.vmcode is written, the updater computes SHA256(dlc.vmcode) and compares it to the hash from the server. This guarantees the reconstructed file is byte-for-byte identical to what the developer built. Any corruption — in download, decompression, or patching — is caught.

6. Summary

Component	What It Does	Where It Runs	Speed
bidiff	Finds matching byte sequences between old & new file using suffix array. Outputs COPY/ADD/INSERT instructions.	Developer's machine	~2-5 seconds for 3 MB
zstd compress	Compresses the diff instructions using LZ77 + FSE entropy coding. Typically 60-70% further reduction.	Developer's machine	~50ms
zstd decompress	Reverses the compression. Streams byte-by-byte via pipe.	User's phone	<1ms for 150 KB
bipatch	Reads COPY/ADD/INSERT instructions, seeks in the original file, reconstructs the new file.	User's phone	~50-200ms for 3 MB
SHA256	Verifies the reconstructed file matches the expected hash.	User's phone	~20ms for 3 MB

The Key Insight

The combination of bidiff + zstd reduces a 3 MB file change to a ~150 KB download. The device reconstructs the full file using the original (already on the phone) as a reference. The entire process — download, decompress, patch, verify — takes under 2 seconds on a mid-range phone over a 4G connection.

Part 1: How Shorebird Actually Works — Complete Internal Flow Deep Dive

noreply@blogger.com (Lokesh Jangid) — Thu, 14 May 2026 22:27:44 -0700

Shorebird — Complete Internal Flow

Function-level deep dive: from flutter build to byte-level diffing to patch application on a real phone. Every function, every file, every byte transformation.

① Build & Release

② Diff & Patch Creation

③ Device: Boot & Load

④ Device: Update Cycle

⑤ Rollback & Recovery

⑥ Byte-Level Internals

⑦ Future Improvements

📦 Phase 1: Build & Release

What happens when you run shorebird release --platforms android

CLI Parse shorebird.yaml

release_command.dart → run()
Reads shorebird.yaml from project root. Extracts app_id. Resolves the Shorebird Flutter SDK revision to use. Calls shorebirdFlutter.installRevision() which downloads the prebuilt Shorebird Flutter SDK (this SDK contains the forked engine with libupdater.a already linked).

Flutter fork + Engine fork AOT Compilation

releaser.buildReleaseArtifacts()
Runs flutter build appbundle --release using the Shorebird Flutter fork. The Dart compiler (gen_snapshot) compiles your Dart code into AOT machine code:

Your Dart code → gen_snapshot → libapp.so (per architecture)

This produces 3 files for Android:
• libapp.so (arm) — ~3.5 MB
• libapp.so (aarch64) — ~3.1 MB
• libapp.so (x86_64) — ~3.2 MB

These files contain ALL your Dart code compiled to native machine instructions. They're the ONLY files that change between patches.

Engine fork Engine is Already Baked In

The APK/AAB contains:
• libflutter.so — The Flutter engine (Shorebird's fork, with libupdater.a statically linked inside)
• libapp.so — Your Dart code (the AOT snapshot from Step 2)
• flutter_assets/shorebird.yaml — Config (app_id, base_url, channel, auto_update)

Key: libflutter.so never changes between patches. Only libapp.so changes. The engine + updater Rust library is baked in once.

CLI → Backend Upload

codePushClientWrapper.createRelease()
1. POST /api/v1/apps/{appId}/releases → creates release record (version, flutter_revision)
2. For each arch: POST /api/v1/apps/{appId}/releases/{id}/artifacts → uploads libapp.so + SHA256 hash
3. PATCH /api/v1/apps/{appId}/releases/{id} → sets status to "active"

The original libapp.so files are stored on the server. They're needed later to compute the binary diff when you create a patch.

Result

Your app is now on the Play Store/App Store. Every user has the original libapp.so bundled inside their APK. The engine (libflutter.so) contains the Rust updater which will check for patches on every app launch.

🔬 Phase 2: Diff & Patch Creation

What happens when you change code and run shorebird patch --platforms android

CLI → Backend Download Original

patcher → downloadReleaseArtifact()
Downloads the original libapp.so (per-arch) from your backend. This is the exact binary that's bundled inside the APK your users have. It's needed as the "base" for binary diffing.

Flutter fork Build New libapp.so

patcher.buildPatchArtifact()
Rebuilds your Dart code using the exact same Flutter revision as the original release. This is critical — the Dart compiler must match exactly. Produces a new libapp.so with your code changes.

updater/patch Binary Diff — The Core Algorithm

artifactManager.createDiff() → calls the Rust patch binary
updater/patch/src/lib.rs → make_patch()

Step 1: Binary Diff (bidiff)
bidiff::simple_diff_with_params(&old_bytes, &new_bytes, &mut writer, &params)
This computes a byte-level binary diff between the old and new libapp.so. The bidiff algorithm finds matching byte sequences and encodes the differences as a series of copy + insert operations. Output: an uncompressed diff (maybe 200KB–2MB).

Step 2: Zstd Compression
ZstdCompressor::new().compress(&mut output, &mut diff_bytes)
The diff is piped through zstd compression (via a separate thread + pipe for parallelism). Output: a compressed .patch file.

old libapp.so (3.1 MB)

new libapp.so (3.1 MB)

→ bidiff →

raw diff (~500 KB)

→ zstd →

patch.bin (50–200 KB)

CLI Compute Hash of FINAL result

The CLI computes SHA256(new_libapp.so) — the hash of the final uncompressed patched file, NOT the compressed diff. This hash is uploaded to the server and later used by devices to verify the patch was applied correctly.

CLI → Backend Upload & Promote

codePushClientWrapper.publishPatch()
1. POST /api/v1/apps/{id}/patches → creates patch record (gets auto-incremented patch number)
2. POST /api/v1/apps/{id}/patches/{id}/artifacts → uploads compressed diff per-arch + hash
3. POST /api/v1/apps/{id}/patches/promote → links patch to "stable" channel

Now any device checking /patches/check with this app_id + version + channel will receive this patch.

📱 Phase 3: Device Boot & Patch Loading

What happens inside the user's phone when they open the app

Engine Android System Loads the Process

Android loads the APK → FlutterActivity starts → FlutterJNI.nativeInit() called → reads shorebird.yaml from flutter_assets/ → passes it to native C++ code.

Engine ConfigureShorebird()

engine/shell/common/shorebird/shorebird.cc

Creates the shorebird_updater/ directory in the app's cache + storage paths. Builds AppParameters struct with:
• release_version: "1.0.0+1"
• code_cache_dir: OS cache directory
• app_storage_dir: persistent storage
• original_libapp_paths: pointer to the bundled libapp.so path

Then calls → shorebird_init(&app_parameters, file_callbacks, yaml)

Updater (Rust) shorebird_init()

updater/library/src/updater.rs

1. Parses shorebird.yaml → extracts app_id, base_url, channel, auto_update
2. Sets global UpdateConfig (once per process, guarded by OnceLock)
3. Loads state.json from storage dir (or creates fresh if corrupt/missing)
4. Crash recovery: calls handle_prior_boot_failure_if_necessary() — if currently_booting_patch is set (meaning last boot crashed), marks that patch as Bad with reason crash_recovery

Updater shorebird_next_boot_patch_path()

Engine asks: "Which libapp.so should I load?"

Updater checks the PatchLifecycle state on disk:
• If a patch is installed and not bad → returns path: /data/data/com.app/shorebird_updater/patches/3/dlc.vmcode
• If no patch installed → returns NULL (use original bundled libapp.so)

Engine Swap the library path

This is the magic line:

// Android (non-interpreter mode):
settings.application_library_path.clear();
settings.application_library_path.emplace_back(active_path);

// iOS (interpreter mode):
settings.application_library_path.insert(
    settings.application_library_path.begin(), active_path);

The engine replaces (or prepends) the default libapp.so path with the patched file's path. The Dart VM then loads the patched file instead of the original. This is how the updated Dart code runs without reinstalling the app.

Updater shorebird_report_launch_start()

Called exactly once per process (std::once_flag). Sets currently_booting_patch = next_boot_patch in the state file AND records a boot timestamp. If the process crashes before report_launch_success() is called, the next launch will detect currently_booting_patch is still set → crash recovery triggers → patch marked bad.

Engine Start Background Update

If auto_update: true in shorebird.yaml:
shorebird_start_update_thread() → spawns a Rust background thread that runs the full update cycle (Panel 4). The app is already running with the current patch — the update downloads the NEXT patch for the NEXT boot.

Timeline

All of this happens in ~10-50ms during app startup. The user sees their splash screen normally. The patch is loaded BEFORE the Dart VM starts — so when main() runs, it's already running the patched code.

🔄 Phase 4: Background Update Cycle

The Rust updater thread checking for and downloading a new patch

Updater update_internal() — Send queued events first

Before checking for updates, sends any queued events (max 3) from previous sessions:
for event in state.copy_events(3) { send_patch_event(event, &config); }
Events like __patch_download__, __patch_install__, __patch_install_failure__.

Updater → Backend POST /api/v1/patches/check

PatchCheckRequest::new(&config, &client_id, current_patch_number)
Sends: { app_id, release_version, platform, arch, channel, client_id, patch_number }

Server responds with:

{ "patch_available": true,
  "patch": { "number": 3, "download_url": "https://...", "hash": "sha256...", "hash_signature": null },
  "rolled_back_patch_numbers": [2] }

Updater Process Rollbacks

roll_back_patches_if_needed()
For each patch number in rolled_back_patch_numbers:
state.uninstall_patch(patch_number) — deletes the installed dlc.vmcode file and removes the patch from the lifecycle state. If the currently booted patch is in this list, the next boot will fall back to the previous good patch (or base release).

Updater decide_start() — Should we download?

The lifecycle state machine decides:
• Skip(KnownBad): This patch was previously tried and failed → don't re-download
• Skip(AlreadyInstalled): Same patch number + same hash already installed → no-op
• Resume {offset}: Previous download was interrupted → resume from byte offset
• Download: Fresh download
• Complete: Already downloaded but not yet installed → skip to install

Updater Download Compressed Diff

download_to_path()
Downloads from patch.download_url using ureq HTTP client. Supports HTTP Range headers for resume. Downloads to: {cache}/patches/{N}/download.bin

Verifies: if server sent Content-Length header, checks actual downloaded bytes match. On mismatch → uninstall + error.

Updater install_downloaded_patch()

inflate(download_path, base_reader, output_path)
updater/library/src/updater.rs

This is the reverse of the diff process, running on the user's phone:

1. Validate: Check first 4 bytes are zstd magic (0x28, 0xB5, 0x2F, 0xFD)
2. Create pipe: In-memory pipe connecting decompression thread to patching thread
3. Thread 1 (decompression): ZstdDecompressor.copy(compressed_file → pipe_writer)
4. Thread 2 (patching): bipatch::Reader::new(pipe_reader, original_libapp_reader) — reads decompressed diff + original bundled libapp.so, outputs the new patched libapp.so
5. Write: Patched bytes → {storage}/patches/{N}/dlc.vmcode

downloaded .patch (150 KB)

→ zstd decompress →

raw diff (500 KB)

+ bundled libapp.so (3 MB) → bipatch →

new libapp.so (3.1 MB) = dlc.vmcode

Updater check_hash() — Verify Integrity

Computes SHA256(dlc.vmcode) and compares against patch.hash from the server.
• Match: Patch is valid. Transition to Installed state.
• Mismatch: Mark patch as Bad(InstallHashMismatch). This is usually caused by the developer building the patch with a different Dart compiler version than the release.

Updater promote_to_next_boot()

Sets next_boot_patch = patch_number in the lifecycle state. Queues a __patch_download__ event. The patch is now ready. On the next app launch, Step 3 will return this patch's path instead of the original.

Key Insight

The dlc.vmcode file IS a complete libapp.so — not a diff. The device reconstructs the full binary from the diff + original. The engine loads it exactly like it would load the bundled version.

🔄 Phase 5: Rollback & Recovery

A. Automatic Crash Recovery (Client-Side)

🔴 Scenario: Patch 3 crashes the app

Boot 1: App starts → shorebird_init() → loads patch 3 → report_launch_start() writes currently_booting_patch=3, boot_started_at=timestamp → 💥 CRASH (process dies before report_launch_success())

Boot 2: App restarts → shorebird_init() → handle_prior_boot_failure_if_necessary() sees currently_booting_patch=3 is still set → calls record_boot_failure_for_patch(3) → marks patch 3 as Bad(CrashRecovery) → queues __patch_install_failure__ event with message "crash_recovery: patch 3 failed to boot" → next_boot_patch_path() returns patch 2 (or NULL for base) → App boots safely

B. Server-Side Rollback

🟡 Developer rolls back patch 3 via CMS/CLI

Developer calls: POST /api/v1/apps/{id}/patches/3/rollback

Next device check: POST /patches/check response now includes "rolled_back_patch_numbers": [3]

On device: roll_back_patches_if_needed([3]) → state.uninstall_patch(3) → deletes patches/3/dlc.vmcode + removes from lifecycle state → next_boot_patch() now returns patch 2 (or base)

Next app launch: Engine loads patch 2 (or base release). Patch 3 is gone.

C. Un-Rollback (Re-enable)

🟢 Developer un-rolls-back patch 3

Developer calls: DELETE /api/v1/apps/{id}/patches/3/rollback

Next device check: Server now offers patch 3 again in /patches/check response. rolled_back_patch_numbers no longer includes 3.

On device: Normal update cycle — downloads patch 3 again, inflates, verifies, installs for next boot.

Caveat: If the device had marked patch 3 as Bad(CrashRecovery) locally, the decide_start() function will return Skip(KnownBad) and refuse to re-download. The device's local "known bad" state takes precedence over the server.

D. State Files on Device

/data/data/com.example.app/files/shorebird_updater/
├── state.json                    ← { client_id, release_version }
├── pointers.json                 ← { next_boot: 3, last_booted: 2 }
└── patches/
    ├── 2/
    │   ├── state.json            ← { status: "installed", hash: "...", size: 3100000 }
    │   └── dlc.vmcode            ← THE ACTUAL PATCHED libapp.so (3.1 MB)
    └── 3/
        ├── state.json            ← { status: "bad", reason: "crash_recovery" }
        └── (dlc.vmcode deleted)

/data/data/com.example.app/cache/shorebird_updater/
└── patches/
    └── 3/
        └── download.bin          ← Compressed diff (temp, deleted after install)

🔬 Phase 6: Byte-Level Internals

What is libapp.so?

An ELF shared library containing the Dart AOT snapshot. It has two key sections:
• _kDartVmSnapshotInstructions: Compiled machine code (ARM64/x86 instructions)
• _kDartIsolateSnapshotData: Dart heap data (objects, constants, strings)

When you change Dart code, both sections change. The instruction offsets shift, constant pools update, and new functions appear or existing ones change. But much of the file stays identical (standard library code, unchanged widgets, etc.).

The bidiff Algorithm

How it finds similarities

bidiff uses a suffix-sort-based algorithm (similar to bsdiff) to find matching byte sequences between old and new files. It produces a stream of operations:

• COPY(offset, length): "Copy length bytes from the old file starting at offset"
• INSERT(bytes): "Insert these new bytes that don't exist in the old file"
• ADD(delta): "Add these delta bytes to the copied bytes" (for near-matches)

For typical Dart code changes, 90-98% of libapp.so is identical. bidiff captures this efficiently.

Size Comparison (Real Numbers)

┌──────────────────────┬────────────┬──────────────────────┐
│       Artifact       │    Size    │        Notes         │
├──────────────────────┼────────────┼──────────────────────┤
│ original libapp.so   │  3,146 KB  │ Full AOT snapshot    │
│ new libapp.so        │  3,148 KB  │ After Dart changes   │
│ raw bidiff output    │   ~500 KB  │ Uncompressed diff    │
│ zstd compressed      │  50-200 KB │ What device downloads│
│ dlc.vmcode (output)  │  3,148 KB  │ Full reconstructed   │
└──────────────────────┴────────────┴──────────────────────┘

Compression ratio: 3,148 KB → 150 KB = ~95% reduction

The Pipe-Based Inflate Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     DEVICE (Rust, two threads)                  │
│                                                                 │
│  Thread 1 (decompress):                                         │
│  ┌──────────────┐    ┌──────────┐    ┌─────────────┐           │
│  │ download.bin  │───▶│  zstd    │───▶│ pipe_writer │──────┐    │
│  │ (compressed)  │    │ decomp   │    └─────────────┘      │    │
│  └──────────────┘    └──────────┘                    ┌─────┘    │
│                                                      │ in-memory│
│  Thread 2 (patch + write):                           │ pipe     │
│  ┌──────────────┐    ┌─────────────┐  ┌──────────┐  │          │
│  │ bundled      │───▶│ bipatch     │◀─│pipe_reader│◀─┘          │
│  │ libapp.so    │    │ ::Reader    │  └──────────┘              │
│  │ (original)   │    │             │                            │
│  └──────────────┘    └──────┬──────┘                            │
│                             │                                   │
│                      ┌──────▼──────┐                            │
│                      │ dlc.vmcode  │  ← Full patched libapp.so  │
│                      │ (output)    │  ← SHA256 verified         │
│                      └─────────────┘                            │
└─────────────────────────────────────────────────────────────────┘

🚀 Future Improvements for Self-Hosted

📊 Staged Rollouts MEDIUM

Roll out patches to a percentage of users (1% → 10% → 50% → 100%). The /patches/check endpoint uses client_id to deterministically assign users to a rollout bucket: hash(client_id) % 100 < rollout_percentage. Add a rollout_percentage column to channel_patches table.

🔐 Code Signing EASY

The updater already supports patch_public_key in shorebird.yaml and hash_signature in the patch response. Generate an RSA keypair, sign SHA256(dlc.vmcode) with your private key during patch creation, store signature in hash_signature. Device verifies with embedded public key. Prevents server compromise from pushing malicious patches.

🌍 CDN for Patch Distribution EASY

Put a CDN (CloudFront, Cloudflare) in front of your /storage/ path. Patches are immutable (same URL = same content), so cache-forever headers work perfectly. Reduces latency from 200ms to 20ms globally. The download_url in /patches/check already points to a full URL — just make it a CDN URL.

📱 Forced Update Support MEDIUM

Add a force_update: true flag to /patches/check response. The Dart-side shorebird_code_push package checks this and shows a full-screen "Updating..." overlay, blocking the app until the patch downloads and installs. Requires a small Dart wrapper + backend flag per patch.

🔄 Delta Patches (Patch-to-Patch) HARD

Currently: diff is always against the original release libapp.so. Improvement: diff against the last patch's output instead. If a user has patch 2 installed and patch 3 is available, the diff between patch 2's output and patch 3's output is much smaller than original→3. Requires server-side diffing at promote time, per-patch-chain artifacts, and updater changes to select the right base.

📈 Real-time Analytics Dashboard MEDIUM

WebSocket-based live counter of downloads/installs per patch. Show a real-time map of where patches are being installed (from IP geolocation of /patches/events). Add aggregation tables (hourly/daily rollups) for fast historical queries. Add percentile tracking: "What % of users are on the latest patch?"

🧪 A/B Testing via Channels MEDIUM

Create channels like experiment_a and experiment_b. Assign users to channels deterministically based on client_id hash. Each channel gets a different patch (e.g., different UI layout). Measure install counts per channel. The channel infrastructure already exists — you just need the assignment logic and analytics comparison view.

⏱ Automatic Rollback on Error Rate HARD

Monitor the ratio of __patch_install_failure__ to __patch_install__ events per patch. If failure rate exceeds a threshold (e.g., >5% in 30 minutes), automatically insert into rolled_back_patches and alert the developer. This turns your self-hosted backend into a canary deployment system.

📦 Multi-App Orchestration EASY

If you have multiple apps (Univest Production, UAT, DEV), add a promotion pipeline: patch tested on DEV → promoted to UAT → promoted to Production. Each stage is a different app_id with its own channels. Add a CMS feature to "promote" a patch from one app's channel to another app.

🔒 Patch Expiry / Kill Switch EASY

Add an expires_at field to patches. After expiry, /patches/check stops serving it. For kill switch: a special "patch 0" that forces the device back to the base release. Implement as a patch with number=0 and no diff — the updater sees it's "installed" and returns NULL from next_boot_patch_path().

🗜 Brotli Compression Alternative MEDIUM

zstd is optimized for speed. Brotli achieves 10-20% better compression at the cost of slower compression (fine for server-side). This means smaller downloads. Requires forking the updater to add brotli support alongside zstd, using a magic-byte header to detect the format. Decompression speed is similar.

📋 Patch Notes in App EASY

Add a notes field to the /patches/check response. The Dart shorebird_code_push package exposes it. Developers show a "What's new" dialog after update. Already partially supported — just needs the backend to include patch.notes in the check response and a small Dart wrapper.

🍎 SwiftUI Interview Questions & Answers

noreply@blogger.com (Lokesh Jangid) — Mon, 23 Feb 2026 22:16:00 -0800

A comprehensive guide covering everything from fundamentals to advanced SwiftUI concepts — structured point by point with visual diagrams.

1. What is SwiftUI?

Q: What is SwiftUI and when was it introduced?

SwiftUI is Apple's modern declarative UI framework introduced at WWDC 2019 (iOS 13+). It allows developers to build user interfaces for all Apple platforms — iOS, macOS, watchOS, and tvOS — using a single, unified Swift codebase.

✅ Key Advantages

┌─────────────────────────────────────────────────────────────┐
│                    SwiftUI Advantages                        │
├─────────────────────┬───────────────────────────────────────┤
│ Declarative Syntax  │ Describe WHAT the UI looks like,      │
│                     │ not HOW to build it step by step       │
├─────────────────────┼───────────────────────────────────────┤
│ Live Preview        │ See real-time UI changes in Xcode     │
│                     │ without recompiling the entire app     │
├─────────────────────┼───────────────────────────────────────┤
│ Less Code           │ Achieve complex layouts with far       │
│                     │ fewer lines than UIKit                 │
├─────────────────────┼───────────────────────────────────────┤
│ Multi-Platform      │ One codebase targets iOS, macOS,       │
│                     │ watchOS, and tvOS                      │
├─────────────────────┼───────────────────────────────────────┤
│ Built-in Animation  │ Add smooth animations with simple      │
│                     │ modifiers and state changes            │
├─────────────────────┼───────────────────────────────────────┤
│ Auto Accessibility  │ Default accessibility support baked    │
│                     │ in without extra configuration         │
└─────────────────────┴───────────────────────────────────────┘

💻 Basic SwiftUI Example

import SwiftUI

struct ContentView: View {
    var body: some View {
        VStack {
            Image(systemName: "globe")
                .imageScale(.large)
                .foregroundColor(.accentColor)
            Text("Hello, SwiftUI!")
                .font(.title)
                .bold()
        }
        .padding()
    }
}

2. SwiftUI vs UIKit

Q: What are the key differences between SwiftUI and UIKit?

┌─────────────────────────────────────────────────────────────────┐
│                   SwiftUI  vs  UIKit                             │
├──────────────────────┬──────────────────┬───────────────────────┤
│     Feature          │    SwiftUI       │       UIKit            │
├──────────────────────┼──────────────────┼───────────────────────┤
│ Paradigm             │ Declarative      │ Imperative             │
│ Language             │ Swift only       │ Swift / Objective-C    │
│ iOS Support          │ iOS 13+          │ iOS 2+                 │
│ UI Tool              │ Code / Preview   │ Storyboard / Code      │
│ State Mgmt           │ Built-in (@State)│ Manual                 │
│ Layout               │ Stacks, Grids    │ Auto Layout            │
│ Learning Curve       │ Lower (modern)   │ Higher (legacy)        │
│ Maturity             │ Growing          │ Very Mature            │
│ Animations           │ Simple modifiers │ Complex API            │
│ Cross-Platform       │ Yes              │ iOS only               │
└──────────────────────┴──────────────────┴───────────────────────┘

⚠️ When to Choose UIKit Over SwiftUI

Supporting iOS 12 or earlier
Highly complex, performance-critical interfaces
Using legacy Objective-C codebases
Needing more fine-grained control over the render cycle

3. Declarative vs Imperative UI

Q: What is the difference between declarative and imperative UI programming?

                    IMPERATIVE (UIKit)
    ┌────────────────────────────────────────────┐
    │  Step 1: Create a UILabel                  │
    │  Step 2: Set text = "Hello"                │
    │  Step 3: Set font, color, frame            │
    │  Step 4: Add to view hierarchy             │
    │  Step 5: Manually update when data changes │
    │  Step 6: Manage lifecycle yourself         │
    └────────────────────────────────────────────┘
              ↓ "Tell me HOW to do it"

                    DECLARATIVE (SwiftUI)
    ┌────────────────────────────────────────────┐
    │  Describe: "I want a bold Text saying      │
    │   'Hello', red foreground, large font."    │
    │                                            │
    │  SwiftUI handles rendering + updates       │
    │  automatically when data changes           │
    └────────────────────────────────────────────┘
              ↓ "Tell me WHAT you want"

// ✅ SwiftUI — Declarative
Text("Hello, \(name)!")
    .font(.title)
    .foregroundColor(.red)

// ❌ UIKit — Imperative equivalent
let label = UILabel()
label.text = "Hello, \(name)!"
label.font = UIFont.systemFont(ofSize: 24)
label.textColor = .red
view.addSubview(label)
// + Auto Layout constraints...

4. The View Protocol

Q: What is the View protocol in SwiftUI and why are views struct types?

Every visible element in SwiftUI conforms to the View protocol. It requires a single computed property:

protocol View {
    associatedtype Body: View
    var body: Self.Body { get }
}

Why Struct (Value Type) Instead of Class?

┌──────────────────────────────────────────────────────────┐
│              Struct  vs  Class for Views                  │
├──────────────────────┬───────────────────────────────────┤
│       Struct ✅       │          Class ❌                 │
├──────────────────────┼───────────────────────────────────┤
│ Value type (copied)  │ Reference type (shared)           │
│ No inheritance       │ Inheritance adds complexity       │
│ Thread-safe by nature│ Needs manual synchronization      │
│ Lightweight          │ Heavier (heap allocation)         │
│ Immutable body       │ Mutable state = harder to reason  │
│ SwiftUI re-creates   │ Lifecycle management required     │
│ them cheaply         │                                   │
└──────────────────────┴───────────────────────────────────┘

struct MyView: View {
    var title: String

    var body: some View {
        Text(title)
            .font(.headline)
            .padding()
    }
}

5. Layout System: VStack, HStack, ZStack

Q: Explain SwiftUI's layout containers.

┌──────────────────────────────────────────────────────────┐
│                 SwiftUI Layout Containers                 │
│                                                           │
│  VStack (Vertical)      HStack (Horizontal)              │
│  ┌──────────┐           ┌────────────────────┐           │
│  │  [Item1] │           │ [Item1][Item2][Item3] │         │
│  │  [Item2] │           └────────────────────┘           │
│  │  [Item3] │                                             │
│  └──────────┘           ZStack (Layered / Z-axis)        │
│                         ┌──────────────────┐             │
│                         │  Background      │             │
│                         │    ┌──────┐      │             │
│                         │    │ Text │      │             │
│                         │    └──────┘      │             │
│                         └──────────────────┘             │
└──────────────────────────────────────────────────────────┘

// VStack — vertical arrangement
VStack(alignment: .leading, spacing: 10) {
    Text("Title").font(.title)
    Text("Subtitle").font(.subheadline)
    Button("Tap Me") { }
}

// HStack — horizontal arrangement
HStack(spacing: 16) {
    Image(systemName: "star.fill")
    Text("Favorites")
    Spacer()        // pushes content to edges
    Badge(count: 3)
}

// ZStack — layer on top of each other
ZStack {
    Color.blue.ignoresSafeArea()        // background layer
    Image("banner")                      // middle layer
    Text("Overlay Text")                 // top layer
        .foregroundColor(.white)
}

Lazy Variants (Performance)

// Use LazyVStack / LazyHStack for large data sets
// They only render views that are currently visible

ScrollView {
    LazyVStack {
        ForEach(0..<1000) { index in
            Text("Row \(index)")
        }
    }
}

6. State Management: @State

Q: What is @State and when should you use it?

@State is a property wrapper that lets SwiftUI manage a value locally within a single view. When the value changes, SwiftUI automatically re-renders the body.

         @State Flow Diagram
    ┌─────────────────────────┐
    │       SwiftUI View       │
    │                          │
    │  @State var count = 0   │◄──── SwiftUI owns & manages
    │           │              │
    │           ▼              │
    │     body re-renders     │
    │     when count changes  │
    └─────────────────────────┘
              │
              ▼
    User taps button → count += 1 → View updates

struct CounterView: View {
    @State private var count = 0      // 1. Declare state

    var body: some View {
        VStack(spacing: 20) {
            Text("Count: \(count)")   // 2. Read state
                .font(.largeTitle)

            Button("Increment") {
                count += 1            // 3. Mutate state → auto re-render
            }
            .buttonStyle(.borderedProminent)
        }
    }
}

🔑 Key Rules for @State

Always declare @State as private
Only use inside the view that owns the data
For sharing across views → use @Binding
For complex objects → use @StateObject

7. @Binding

Q: What is @Binding and how does it differ from @State?

@Binding creates a two-way connection between a parent view's state and a child view. The child can read and write the value without owning it.

       @State / @Binding Relationship

    Parent View                   Child View
    ┌──────────────────┐         ┌──────────────────┐
    │ @State var       │         │ @Binding var      │
    │  isOn = false    │────────►│  isOn: Bool       │
    │                  │◄────────│                   │
    │  (owns the data) │  sync   │  (references data)│
    └──────────────────┘         └──────────────────┘
            │                             │
            └─────── Both update ─────────┘
                  the same source of truth

// Parent — owns the state
struct ParentView: View {
    @State private var isToggled = false

    var body: some View {
        ToggleView(isOn: $isToggled)    // $ creates a Binding
    }
}

// Child — receives a binding
struct ToggleView: View {
    @Binding var isOn: Bool             // Does NOT own the data

    var body: some View {
        Toggle("Enable Feature", isOn: $isOn)
    }
}

8. @ObservedObject & @StateObject

Q: What is the difference between @StateObject and @ObservedObject?

Both work with ObservableObject classes, but differ in ownership and lifecycle.

┌─────────────────────────────────────────────────────────────┐
│           @StateObject  vs  @ObservedObject                  │
├──────────────────────────┬──────────────────────────────────┤
│      @StateObject ✅      │      @ObservedObject             │
├──────────────────────────┼──────────────────────────────────┤
│ VIEW creates the object  │ Object injected from outside      │
│ VIEW owns the object     │ View does NOT own it              │
│ Persists across re-draws │ May be re-created on re-draw      │
│ Use in CREATING view     │ Use in RECEIVING view             │
│                          │                                   │
│ @StateObject var vm =    │ @ObservedObject var vm:           │
│   ViewModel()            │   ViewModel                       │
└──────────────────────────┴──────────────────────────────────┘

// Observable class
class UserViewModel: ObservableObject {
    @Published var username = "John"
    @Published var score = 0

    func incrementScore() {
        score += 1
    }
}

// ✅ Use @StateObject in the view that CREATES the object
struct ProfileView: View {
    @StateObject private var viewModel = UserViewModel()

    var body: some View {
        VStack {
            Text("User: \(viewModel.username)")
            Text("Score: \(viewModel.score)")
            Button("Add Score") { viewModel.incrementScore() }
            ScoreBoard(viewModel: viewModel)   // pass down
        }
    }
}

// ✅ Use @ObservedObject in views that RECEIVE the object
struct ScoreBoard: View {
    @ObservedObject var viewModel: UserViewModel

    var body: some View {
        Text("Current Score: \(viewModel.score)")
    }
}

9. @EnvironmentObject

Q: What is @EnvironmentObject and when should you use it?

@EnvironmentObject allows you to share data across many views in the hierarchy without passing it explicitly through each child.

         @EnvironmentObject — Shared Data Across Tree

              App Level
           ┌──────────────┐
           │  AppState    │  ◄── injected with .environmentObject()
           └──────┬───────┘
                  │ available to ALL descendants
        ┌─────────▼──────────┐
        │    HomeView        │
        └───────┬────────────┘
         ┌──────▼──────┐
         │  SettingsView│  ← can access AppState directly
         └─────┬────────┘
               │
         ┌─────▼────────┐
         │  UserProfile │  ← can also access AppState directly
         └──────────────┘
         No need to pass through each level! ✅

// 1. Define the shared model
class AppState: ObservableObject {
    @Published var isLoggedIn = false
    @Published var currentUser = ""
}

// 2. Inject at the root
@main
struct MyApp: App {
    @StateObject var appState = AppState()

    var body: some Scene {
        WindowGroup {
            ContentView()
                .environmentObject(appState)   // inject here
        }
    }
}

// 3. Use anywhere in the hierarchy
struct ProfileView: View {
    @EnvironmentObject var appState: AppState  // no passing needed

    var body: some View {
        Text("Hello, \(appState.currentUser)")
    }
}

10. Data Flow Architecture

Q: How does data flow work in SwiftUI?

              SwiftUI Data Flow — Unidirectional

    ┌──────────────────────────────────────────────┐
    │                                              │
    │   User Action (tap, swipe, input)            │
    │          │                                   │
    │          ▼                                   │
    │   State/Model Changes                        │
    │  (@State, @Published, etc.)                  │
    │          │                                   │
    │          ▼                                   │
    │   SwiftUI detects change                     │
    │          │                                   │
    │          ▼                                   │
    │   View body re-evaluated                     │
    │          │                                   │
    │          ▼                                   │
    │   Diff computed (minimal updates)            │
    │          │                                   │
    │          ▼                                   │
    │   UI Updated on screen                       │
    │          │                                   │
    │          └────────────────────────────────── │
    │                     ↑ cycle repeats           │
    └──────────────────────────────────────────────┘

11. Property Wrappers Comparison

Q: Can you summarize all SwiftUI property wrappers?

┌──────────────────────────────────────────────────────────────────────┐
│               SwiftUI Property Wrappers — Quick Reference             │
├────────────────────┬─────────────────────────┬───────────────────────┤
│   Wrapper          │      Purpose             │     Use When          │
├────────────────────┼─────────────────────────┼───────────────────────┤
│ @State             │ Local value storage      │ Simple local UI state │
│ @Binding           │ Two-way reference        │ Pass state to child   │
│ @StateObject       │ Owns ObservableObject    │ Creating a VM in view │
│ @ObservedObject    │ References Observable    │ Receiving a VM        │
│ @EnvironmentObject │ Shared across hierarchy  │ App-wide shared data  │
│ @Environment       │ System values            │ colorScheme, locale   │
│ @Published         │ Observable property      │ Inside ObservableObj  │
│ @AppStorage        │ UserDefaults binding     │ Persist user prefs    │
│ @SceneStorage      │ Scene-specific storage   │ Per-scene state       │
│ @FetchRequest      │ CoreData query           │ CoreData integration  │
└────────────────────┴─────────────────────────┴───────────────────────┘

// @Environment — reading system values
struct ThemeAwareView: View {
    @Environment(\.colorScheme) var colorScheme

    var body: some View {
        Text("Mode: \(colorScheme == .dark ? "Dark" : "Light")")
    }
}

// @AppStorage — UserDefaults made easy
struct SettingsView: View {
    @AppStorage("isDarkMode") var isDarkMode = false

    var body: some View {
        Toggle("Dark Mode", isOn: $isDarkMode)
    }
}

12. Animations in SwiftUI

Q: How do you implement animations in SwiftUI?

SwiftUI supports two styles of animation: implicit and explicit.

        Implicit Animation
        ─────────────────
        Attach .animation() to a view.
        Any state change affecting that view is animated.

        Explicit Animation
        ──────────────────
        Wrap state change in withAnimation { }.
        Only that specific change is animated.

// Implicit Animation
struct ImplicitAnimationView: View {
    @State private var scale = 1.0

    var body: some View {
        Circle()
            .frame(width: 100, height: 100)
            .scaleEffect(scale)
            .animation(.spring(response: 0.5, dampingFraction: 0.6), value: scale)
            .onTapGesture { scale = scale == 1.0 ? 1.5 : 1.0 }
    }
}

// Explicit Animation
struct ExplicitAnimationView: View {
    @State private var isExpanded = false

    var body: some View {
        VStack {
            Rectangle()
                .frame(width: isExpanded ? 300 : 100,
                       height: isExpanded ? 300 : 100)

            Button("Toggle") {
                withAnimation(.easeInOut(duration: 0.4)) {
                    isExpanded.toggle()   // only this change animates
                }
            }
        }
    }
}

Animation Types

┌──────────────────────────────────────────────┐
│          SwiftUI Animation Curves            │
├──────────────────┬───────────────────────────┤
│ .linear          │ Constant speed             │
│ .easeIn          │ Starts slow, ends fast     │
│ .easeOut         │ Starts fast, ends slow     │
│ .easeInOut       │ Slow → fast → slow         │
│ .spring(...)     │ Bouncy, natural feel        │
│ .interpolating   │ Custom timing curve         │
│   SpringAnim     │                            │
└──────────────────┴───────────────────────────┘

Transitions (for appearing/disappearing views)

if isVisible {
    Text("Hello!")
        .transition(.asymmetric(
            insertion: .slide,
            removal: .opacity
        ))
}

13. NavigationView & NavigationStack

Q: How does navigation work in SwiftUI? What is NavigationStack?

     NavigationStack (iOS 16+)   ← Preferred modern approach
     ┌──────────────────────────────────────────┐
     │  NavigationStack(path: $navPath) {       │
     │    ContentView()                          │
     │      .navigationDestination(for: ...) {} │
     │  }                                        │
     └──────────────────────────────────────────┘
                      │
                      ▼
     Push → [Root] → [Detail] → [SubDetail]
     Pop  ← [Root] ← [Detail] ← [SubDetail]

// Modern Navigation (iOS 16+)
struct AppNavigationView: View {
    @State private var path = NavigationPath()

    var body: some View {
        NavigationStack(path: $path) {
            List(items) { item in
                NavigationLink(value: item) {
                    Text(item.name)
                }
            }
            .navigationTitle("Items")
            .navigationDestination(for: Item.self) { item in
                ItemDetailView(item: item)
            }
        }
    }
}

// Programmatic Navigation
Button("Go to Detail") {
    path.append(selectedItem)   // push
}

Button("Go Back") {
    path.removeLast()           // pop
}

Button("Go to Root") {
    path.removeLast(path.count) // pop all
}

14. List & ForEach

Q: What is the difference between List and ForEach in SwiftUI?

┌────────────────────────────────────────────────┐
│           List  vs  ForEach                    │
├───────────────────────┬────────────────────────┤
│         List          │       ForEach          │
├───────────────────────┼────────────────────────┤
│ Full scroll container │ Just iterates views    │
│ Provides separators   │ No built-in styling    │
│ Built-in swipe-delete │ Used inside containers │
│ Selection support     │ More flexible          │
│ Auto cell styling     │ Pure view builder      │
└───────────────────────┴────────────────────────┘

struct FruitListView: View {
    @State private var fruits = ["Apple", "Banana", "Cherry"]

    var body: some View {
        List {
            ForEach(fruits, id: \.self) { fruit in
                Text(fruit)
            }
            .onDelete { indexSet in
                fruits.remove(atOffsets: indexSet)
            }
            .onMove { from, to in
                fruits.move(fromOffsets: from, toOffset: to)
            }
        }
        .toolbar {
            EditButton()
        }
    }
}

Identifiable Protocol

// ✅ Always use Identifiable for proper diffing
struct Product: Identifiable {
    let id = UUID()
    var name: String
    var price: Double
}

List(products) { product in
    ProductRow(product: product)
}

15. View Modifiers

Q: What are view modifiers and how do they work?

Modifiers return a new modified view — they don't mutate the original. Order matters!

        Modifier Chain — Order Matters!

  Text("Hello")
       │
       ▼
  .padding()        → adds padding around text
       │
       ▼
  .background(.blue) → blue covers the padded area
       │
       ▼
  .cornerRadius(10)  → rounds the blue background

  vs.

  Text("Hello")
  .background(.blue) → blue only behind the text (no padding)
  .padding()         → padding outside the blue box
  .cornerRadius(10)  → rounds nothing visible here

Text("SwiftUI")
    .font(.title)
    .fontWeight(.bold)
    .foregroundColor(.white)
    .padding(.horizontal, 20)
    .padding(.vertical, 10)
    .background(Color.blue)
    .clipShape(RoundedRectangle(cornerRadius: 12))
    .shadow(color: .black.opacity(0.3), radius: 8, x: 0, y: 4)

16. Custom ViewModifier

Q: How do you create a reusable custom ViewModifier?

// 1. Define the modifier
struct CardStyle: ViewModifier {
    var backgroundColor: Color = .white

    func body(content: Content) -> some View {
        content
            .padding()
            .background(backgroundColor)
            .cornerRadius(12)
            .shadow(color: .black.opacity(0.1), radius: 6, x: 0, y: 3)
    }
}

// 2. Add a View extension for clean syntax
extension View {
    func cardStyle(background: Color = .white) -> some View {
        modifier(CardStyle(backgroundColor: background))
    }
}

// 3. Use it anywhere
struct SomeView: View {
    var body: some View {
        VStack {
            Text("Card Title").font(.headline)
            Text("Card subtitle goes here")
        }
        .cardStyle(background: .white)   // ✅ Clean reusable modifier
    }
}

17. @ViewBuilder

Q: What is @ViewBuilder and when do you use it?

@ViewBuilder is a result builder that lets functions return multiple views from a single closure — the same mechanism SwiftUI itself uses for body.

// Without @ViewBuilder — can only return ONE view
func simpleHeader() -> some View {
    Text("Title")  // must be a single view
}

// With @ViewBuilder — can return MULTIPLE views conditionally
@ViewBuilder
func dynamicContent(isLoggedIn: Bool) -> some View {
    if isLoggedIn {
        Text("Welcome Back!")          // ← multiple views based on condition
        Button("Logout") { }
    } else {
        Text("Please Log In")
        Button("Login") { }
    }
}

// Custom container using @ViewBuilder
struct Card<Content: View>: View {
    let title: String
    @ViewBuilder let content: () -> Content   // accepts view builder closure

    var body: some View {
        VStack(alignment: .leading) {
            Text(title).font(.headline)
            Divider()
            content()                          // renders whatever is passed
        }
        .padding()
        .background(.white)
        .cornerRadius(10)
    }
}

// Usage
Card(title: "Profile") {
    Text("Name: John")
    Text("Age: 30")
    Image(systemName: "person.circle")
}

18. GeometryReader

Q: What is GeometryReader and when should you use it?

GeometryReader gives you access to the size and coordinate space of the parent container, enabling responsive and proportional layouts.

    GeometryReader Concept:
    ┌──────────────────────────────────────────┐
    │         Parent Container                  │
    │                                           │
    │   GeometryReader { geometry in            │
    │     ┌──────────────────────────────┐      │
    │     │ geometry.size.width  = 375   │      │
    │     │ geometry.size.height = 800   │      │
    │     │ geometry.frame(in: .local)   │      │
    │     │ geometry.frame(in: .global)  │      │
    │     └──────────────────────────────┘      │
    │                                           │
    └──────────────────────────────────────────┘

struct ResponsiveView: View {
    var body: some View {
        GeometryReader { geometry in
            VStack {
                // 60% width, 30% height of the available space
                Rectangle()
                    .fill(Color.blue)
                    .frame(
                        width: geometry.size.width * 0.6,
                        height: geometry.size.height * 0.3
                    )

                Text("Width: \(Int(geometry.size.width))")
                Text("Height: \(Int(geometry.size.height))")
            }
        }
    }
}

⚠️ Caution: GeometryReader expands to fill available space. Use it only when you truly need size information — prefer frame(), overlay(), and background() for most layout tasks.

19. Combine & SwiftUI

Q: How does SwiftUI integrate with the Combine framework?

       Combine + SwiftUI Integration

  Data Source ──► Publisher ──► Subscriber ──► View Update
   (Network,         (Just,        (sink,       (body
    Timer,           Future,      assign,       re-renders)
    User input)      PassthroughSubject)  onReceive)

import Combine
import SwiftUI

class SearchViewModel: ObservableObject {
    @Published var query = ""
    @Published var results: [String] = []

    private var cancellables = Set<AnyCancellable>()

    init() {
        // Debounce search input — wait 300ms after last keystroke
        $query
            .debounce(for: .milliseconds(300), scheduler: DispatchQueue.main)
            .removeDuplicates()
            .sink { [weak self] text in
                self?.performSearch(query: text)
            }
            .store(in: &cancellables)
    }

    func performSearch(query: String) {
        // Simulate async search
        results = query.isEmpty ? [] : ["Result for '\(query)'"]
    }
}

struct SearchView: View {
    @StateObject private var viewModel = SearchViewModel()

    var body: some View {
        VStack {
            TextField("Search...", text: $viewModel.query)
                .textFieldStyle(.roundedBorder)
                .padding()

            List(viewModel.results, id: \.self) { result in
                Text(result)
            }
        }
    }
}

20. UIKit ↔ SwiftUI Interoperability

Q: How do you use UIKit components in SwiftUI and vice versa?

     SwiftUI  ←──────────────────────► UIKit

     UIViewRepresentable                UIHostingController
     ┌──────────────────────┐           ┌───────────────────────┐
     │ Wraps a UIKit view   │           │ Wraps a SwiftUI view  │
     │ for use in SwiftUI   │           │ for use in UIKit      │
     │                      │           │                       │
     │ makeUIView()         │           │ let vc =              │
     │ updateUIView()       │           │   UIHostingController │
     │ Coordinator (delegate│           │   (rootView: MyView())│
     │  pattern)            │           └───────────────────────┘
     └──────────────────────┘

// UIKit → SwiftUI: Wrap UIKit view with UIViewRepresentable
struct UIKitMapView: UIViewRepresentable {
    @Binding var region: MKCoordinateRegion

    func makeUIView(context: Context) -> MKMapView {
        let mapView = MKMapView()
        mapView.delegate = context.coordinator
        return mapView
    }

    func updateUIView(_ mapView: MKMapView, context: Context) {
        mapView.setRegion(region, animated: true)
    }

    func makeCoordinator() -> Coordinator {
        Coordinator(self)
    }

    class Coordinator: NSObject, MKMapViewDelegate {
        var parent: UIKitMapView
        init(_ parent: UIKitMapView) { self.parent = parent }
    }
}

// SwiftUI → UIKit: Wrap SwiftUI view with UIHostingController
class MyViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
        let swiftUIView = MySwiftUIView()
        let hostingController = UIHostingController(rootView: swiftUIView)
        addChild(hostingController)
        view.addSubview(hostingController.view)
        hostingController.didMove(toParent: self)
    }
}

21. Async/Await in SwiftUI

Q: How do you use async/await for data fetching in SwiftUI?

// ViewModel with async data loading
class ArticleViewModel: ObservableObject {
    @Published var articles: [Article] = []
    @Published var isLoading = false
    @Published var errorMessage: String?

    func loadArticles() async {
        isLoading = true
        defer { isLoading = false }

        do {
            let url = URL(string: "https://api.example.com/articles")!
            let (data, _) = try await URLSession.shared.data(from: url)
            articles = try JSONDecoder().decode([Article].self, from: data)
        } catch {
            errorMessage = error.localizedDescription
        }
    }
}

// View using .task modifier (preferred over .onAppear for async)
struct ArticleListView: View {
    @StateObject private var viewModel = ArticleViewModel()

    var body: some View {
        Group {
            if viewModel.isLoading {
                ProgressView("Loading...")
            } else if let error = viewModel.errorMessage {
                Text("Error: \(error)").foregroundColor(.red)
            } else {
                List(viewModel.articles) { article in
                    Text(article.title)
                }
            }
        }
        .task {
            // .task is auto-cancelled when view disappears ✅
            await viewModel.loadArticles()
        }
    }
}

.task vs .onAppear

┌──────────────────────────────────────────────────────┐
│            .task  vs  .onAppear                      │
├─────────────────────────┬────────────────────────────┤
│         .task           │       .onAppear            │
├─────────────────────────┼────────────────────────────┤
│ Native async support    │ Synchronous by default     │
│ Auto-cancels on disappear│ Runs every appearance     │
│ Preferred for async ops │ Good for simple triggers   │
│ iOS 15+                 │ All iOS versions           │
└─────────────────────────┴────────────────────────────┘

22. MVVM Architecture

Q: How do you implement MVVM pattern in SwiftUI?

           MVVM in SwiftUI

  ┌─────────────────────────────────────────────────────┐
  │                                                     │
  │   MODEL              VIEW MODEL           VIEW      │
  │ ┌─────────┐        ┌──────────────┐    ┌────────┐  │
  │ │  Data   │◄──────►│@Published    │◄──►│SwiftUI │  │
  │ │ Struct  │        │ properties   │    │ View   │  │
  │ │  or     │        │              │    │        │  │
  │ │ Entity  │        │ Business     │    │@State  │  │
  │ └─────────┘        │  Logic       │    │@StateObj│ │
  │                    │              │    │        │  │
  │                    │ ObservableObj│    │        │  │
  │                    └──────────────┘    └────────┘  │
  │                                                     │
  │  Data / Persistence    Logic Layer     UI Layer     │
  └─────────────────────────────────────────────────────┘

// MODEL
struct User: Codable, Identifiable {
    let id: UUID
    var name: String
    var email: String
}

// VIEW MODEL
class UserListViewModel: ObservableObject {
    @Published var users: [User] = []
    @Published var isLoading = false

    private let service: UserService

    init(service: UserService = UserService()) {
        self.service = service
    }

    func fetchUsers() async {
        await MainActor.run { isLoading = true }
        users = await service.getUsers()
        await MainActor.run { isLoading = false }
    }
}

// VIEW
struct UserListView: View {
    @StateObject private var viewModel = UserListViewModel()

    var body: some View {
        NavigationStack {
            List(viewModel.users) { user in
                Text(user.name)
            }
            .navigationTitle("Users")
            .overlay { if viewModel.isLoading { ProgressView() } }
            .task { await viewModel.fetchUsers() }
        }
    }
}

23. Performance Optimization

Q: How do you optimize SwiftUI view performance?

    Performance Optimization Techniques

    1. EQUATABLE VIEWS
    ┌─────────────────────────────────────────┐
    │ struct MyView: View, Equatable { ... }  │
    │ .equatable()  ← skip re-render if equal │
    └─────────────────────────────────────────┘

    2. LAZY CONTAINERS (for large lists)
    ┌─────────────────────────────────────────┐
    │ LazyVStack, LazyHStack, LazyVGrid       │
    │ Only renders visible views              │
    └─────────────────────────────────────────┘

    3. PROPER IDENTIFIERS
    ┌─────────────────────────────────────────┐
    │ Use stable IDs for ForEach              │
    │ Avoid id: \.self on mutable objects     │
    └─────────────────────────────────────────┘

    4. @MainActor for UI updates
    ┌─────────────────────────────────────────┐
    │ Ensure UI updates happen on main thread  │
    └─────────────────────────────────────────┘

// ✅ Prefer let over @State when data doesn't change
struct StaticRow: View {
    let title: String   // not @State — no re-render overhead
    var body: some View { Text(title) }
}

// ✅ Use .id() to force complete re-creation when needed
ScrollView {
    LazyVStack {
        ForEach(items) { item in
            ItemView(item: item)
        }
    }
}

// ✅ Split large views into smaller components
// — SwiftUI only re-renders the affected subtree
struct OptimizedList: View {
    @StateObject var vm = ListViewModel()

    var body: some View {
        List(vm.items) { item in
            ItemRow(item: item)     // separated component
        }
    }
}

24. Accessibility in SwiftUI

Q: How does SwiftUI support accessibility?

SwiftUI provides built-in accessibility support that automatically maps standard views to accessibility traits. You can also customize it with dedicated modifiers.

struct AccessibleView: View {
    @State private var isFavorite = false

    var body: some View {
        VStack {
            // Image with meaningful accessibility label
            Image(systemName: isFavorite ? "heart.fill" : "heart")
                .accessibilityLabel(isFavorite ? "Remove from favorites" : "Add to favorites")

            Button(action: { isFavorite.toggle() }) {
                Text("Toggle Favorite")
            }
            // Group elements as single accessible unit
            .accessibilityElement(children: .combine)
            .accessibilityHint("Double tap to toggle the favorite state")
            .accessibilityAddTraits(.isButton)

            // Custom accessibility value
            ProgressView(value: 0.7)
                .accessibilityValue("70 percent complete")
        }
    }
}

25. Common Interview Traps & Tips

Q: What are some common SwiftUI gotchas interviewers test?

⚠️ Common Traps

┌─────────────────────────────────────────────────────────────────┐
│                    Interview Gotchas                             │
├─────────────────────┬───────────────────────────────────────────┤
│  Topic              │   Common Mistake                          │
├─────────────────────┼───────────────────────────────────────────┤
│ @State              │ Using it in a ViewModel (should be in     │
│                     │ the View only, not ObservableObject)      │
├─────────────────────┼───────────────────────────────────────────┤
│ @StateObject vs     │ Using @ObservedObject when the View       │
│ @ObservedObject     │ creates the object (causes data loss      │
│                     │ on re-render)                             │
├─────────────────────┼───────────────────────────────────────────┤
│ Modifier Order      │ Forgetting that .padding() before         │
│                     │ .background() behaves differently         │
├─────────────────────┼───────────────────────────────────────────┤
│ GeometryReader      │ Overusing it — causes unexpected          │
│                     │ layout behavior; prefer other tools       │
├─────────────────────┼───────────────────────────────────────────┤
│ List identity       │ Using id: \.self on mutable objects       │
│                     │ causes incorrect diff updates             │
├─────────────────────┼───────────────────────────────────────────┤
│ @EnvironmentObject  │ Forgetting to inject it at the root       │
│                     │ causes a crash at runtime                 │
├─────────────────────┼───────────────────────────────────────────┤
│ .task vs .onAppear  │ Using .onAppear with async code instead   │
│                     │ of .task (task auto-cancels properly)     │
└─────────────────────┴───────────────────────────────────────────┘

🎯 Top Tips for SwiftUI Interviews

Always explain WHY, not just WHAT — interviewers want reasoning behind choices
Know the property wrapper lifecycle deeply (@StateObject vs @ObservedObject is a very common question)
Be able to draw the data flow — one-directional, reactive, state → UI
Mention backward compatibility — SwiftUI features have different iOS version requirements
Talk about MVVM naturally — it's the de-facto pattern for SwiftUI
Mention .task for async — shows you know modern concurrency integration
Discuss testing — ViewInspector, Preview-driven development, ViewModel unit tests

📚 Quick Revision Summary

┌──────────────────────────────────────────────────────────────┐
│                  SwiftUI Mental Model                         │
│                                                               │
│  UI = f(State)                                                │
│                                                               │
│  ┌──────────┐    changes    ┌──────────┐    renders          │
│  │  State   │ ────────────► │ SwiftUI  │ ────────────► UI    │
│  │ @State   │               │ Engine   │                     │
│  │ @Published│              │ (diffing)│                     │
│  │ @Binding │               └──────────┘                     │
│  └──────────┘                                                 │
│                                                               │
│  Views are value types (structs) — cheap to re-create        │
│  State lives outside the view — owned by SwiftUI             │
│  Data flows down (one-way), events flow up (actions)         │
└──────────────────────────────────────────────────────────────┘

🏷️ Tags

SwiftUI iOS Swift Apple Mobile Development Interview Prep UIKit Xcode MVVM Combine Async/Await

📝 Last updated: 2025 | Covers iOS 13 → iOS 17+ SwiftUI features