Since I maintain an app for debugging SwiftData storage, this eventually created a problem for me, as I use Core Data to load data dynamically from storage. Users started complaining about crashes when trying to open a database containing these types. Here is the story of what I discovered while investigating it.

The issue

Let’s look at the error occurring when we attempt to read the value from a property of this data type:

object.value(forKey: "icon")

The result is an exception:

NSInvalidArgumentException: No NSCoreDataCodableAdapter for name iconJSONAdapter found; (user info absent)

Initial Data Type Check

The first obvious place to start this investigation is to check the type of NSAttributeDescription in the storage. I expected this part to be straightforward, as Apple didn’t add any new types to Core Data this year, but the outcome was quite unexpected.

(lldb) po attribute.attributeType.rawValue
2200

The type of the attribute is an enum value represented as the UInt value 2200. Let’s see what that means:

// All of the primitive types...

    @available(macOS 10.6, *)
    case objectIDAttributeType = 2000

    @available(macOS 14.0, *)
    case compositeAttributeType = 2100
}

Wait, what? That doesn’t seem to correspond to any existing data types in Core Data so far. Does this mean that Apple developers extended Core Data privately for SwiftData purposes?

Let’s move forward and try to find out what this type is used for.

Investigating discovered Data Type

The first thing I noticed about this new type is that it also has a valueTransformerName, just like a transformable attribute. Let’s try to assign a dummy transformer for this type and see what happens.

ValueTransformer.setValueTransformer(
    DummyTransformer(),
    forName: NSValueTransformerName(transformerName)
)

Aaand… nothing changed. An attempt to read the value from this property still throws the same exception as before.

Let’s check what other information is available to us in the NSAttributeDescription:

1. The type of the description seems to be a private class: NSCodableAttributeDescription.
2. The list of all methods for this type is as follows:

• adapterName
• setAdapterName:
• decode:withRegistry:error:
• encode:withRegistry:error:

Based on that information and the exception text, we can assume that this new 2200 attribute type is “codable”, which stores codable types in a special way. Previously, Codable properties were either converted automatically into a composite type or simply serialized as JSON binary data. It seems that with this year’s release, they introduced one more mechanism to store Codable types.

Diving into the Details

Now, let’s investigate how this new type is decoded. The obvious assumption is that it calls “decode” from the attribute description when we try to access the value. Let’s put a symbolic breakpoint on it and see where we get.

-[NSCodableAttributeDescription decode:withRegistry:error:]

This leads us into the assembly code of the method implementation, which can be interpreted roughly like this:

@objc func decode(_ data: Data,
                  withRegistry registry: NSCoreDataCodableAdapterRegistry,
                  error outError: NSErrorPointer) -> Any? 
{
    // 1. Get adapter (transformer) name
    let adapterName = self.adapterName

    // Prepare temporary error holder
    var localError: NSError? = nil

    // 2. Call into registry to decode using the adapter
    //    This selector is: decodeWithData:withAdapterNamed:error:
    let decoded = registry.decodeWithData(data,
                                          withAdapterNamed: adapterName,
                                          error: &localError)

    // 3. If decoding failed...
    if decoded == nil {
        if let err = localError {
            // 3.1 Check if error is of private type "__NSCoreDataCodableError"
            if err.isKind(of: __NSCoreDataCodableError.self) {
                // 3.2 Throw Objective-C exception (CoreData uses this internally)
                NSException(name: err.exceptionName,
                            reason: err.localizedDescription,
                            userInfo: nil).raise()
            }
        }
    }

    // 4. If caller provided an error pointer, fill it
    if let outError = outError {
        outError.pointee = localError
    }

    // 5. Return the decoded object
    return decoded
}

Now we can see that the new type is using an extra registry to decode the provided codable data based on the adapter name.

That’s enough information to provide a fix: I can register a dummy decoder to get the original Data as a result. The app is now able to run the same data detection heuristics as it does for encoded binary data and show at least some data if possible.

Conclusion

It turns out that even “minor” SwiftData updates can trigger foundational changes in Core Data storage. While my workaround restores functionality for now, reverse engineering private classes always involves some guesswork.

If you have encountered this attribute type in your own debugging or have a better explanation for how the adapter registry functions, let me know in the discussion below.

Example

Let’s look at a simple app I started long ago but never finished, and now use as a playground for testing and debugging tools. It’s a Bento-style presentation editor that stores folders with canvases across two databases: local and iCloud.

To represent each list item and enable cross-device folder sharing while keeping per-device settings (like order and pinned state), I introduced auxiliary “list entry” models in the database.

With the schema in place, I can launch the app and create some test data to verify everything works. I can see when I add or edit items, but it’s often hard to confirm that deleted records are truly removed. For those cases, I need deeper visibility into my data.

Debugging the database

To make runtime inspection easy, I’ve packaged my app UI as a Swift package you can embed in any app. With just a few lines, you can present a live database inspector wherever it makes sense, for example, from a Debug menu:

import SwiftUI
import DataScoutCompanion

struct MyView: View {
    @State
    var isBrowserPresented: Bool = false
    var body: some View {
        /*
        Your UI implementation is here
        */
        .sheet(isPresented: $isBrowserPresented) {
            DatabaseBrowser()
        }
    }
}

And now, when I present the browser, it immediately displays all the database files my app has created:

Here, I can see the two stores that SwiftData generated from my container setup, and I can drill into either one for more details:

The first section shows every model in my schema, and even lets me preview each model’s structure as a visual schema:

Now let’s jump to the most interesting part: exploring the actual data.

I can select “PagesFolderListEntry” to see each entry and which folder it belongs to.

From there, I can tap on the folder and navigate directly to it:

Drilling down further, I can view all items stored in that folder:

This lets me quickly preview each item and verify that my canvas objects were saved with the correct structure:

Now for the main experiment: I close the browser, delete one of the folders in the app, then reopen the browser to inspect the database again. Here’s what I see:

It becomes immediately clear what went wrong: the cascade delete removed the folder and its entries, but left the canvas records orphaned. With this insight, I can now fix my delete rules to ensure all related objects are cleaned up properly.

Additional: Raw SQLite Support

Beyond SwiftData stores, DataScoutCompanion can inspect any raw SQLite file. If your app uses an SQLite wrapper, like GRDB.swift or FMDB, you can still mount and browse the tables directly in the same UI:

Conslusion

With the release of DataScoutCompanion, I’m offering a simple yet powerful way to bring data transparency directly into your app’s UI during development. I hope this tool makes it easier to inspect, debug, and understand your SwiftData (or raw SQLite) stores, and look forward at hearing your comments about it!

Not too long ago, Apple introduced a new database framework — SwiftData. It refines the Core Data experience and brings a more modern, Swift-native approach to data modeling and persistence. Since SwiftData is built on top of Core Data and SQLite, most of those older tools technically still work. But in my opinion, what they all lack is the same thing SwiftData brings to the table: simplicity.

That’s why I decided to build DataScout — a viewer designed specifically for debugging SwiftData apps. My goal was to create an interface that embraces the simplicity of SwiftData while still offering deep insights into your stored data.

In this article, you’ll get more than a feature tour — you’ll see the “why” and the “how” behind each decision. Every section is split into two parts: the design reasoning and the implementation details.

Database Discovery: Simulators, Apps, and More

💡 Design

Finding the right database should be as simple and frictionless as possible. To make that experience smooth, the app opens with a browser window front and center, helping users quickly locate the database file from all possible sources.

Here’s what’s available so far:

• A list of iOS simulators, with active ones and those containing data prioritized at the top
• A list of apps and app groups for the currently open simulator
• A folder list for any custom locations the user has added manually

This structure makes it possible to get to the data with as few clicks as possible. That said, I realize the interface might look a bit busy at first glance. If you have ideas on how to simplify it further without sacrificing usability, feel free to leave a comment — I’m always open to improving the experience in future updates.

🔧 How it works

At first, I considered using simctl to list simulators and apps, but quickly ran into limitations in sandboxed environments. So instead, I went with a straightforward folder scan approach. Users are prompted to grant access to their Library folder (I know, it’s a big ask, but the idea was to eventually support scanning installed databases on macOS too).

Once permission is granted, the app can detect all available simulators with data, making it easier to get a full overview and maybe even realize it’s time to clean things up.

Support for custom folders is handled similarly, and again, the sandbox plays a big role here: you can’t just open a .sqlite file directly when it’s in WAL mode, SwiftData needs access to accompanying -wal and -shm files. So, instead of letting users pick a file, it requires full access to the containing folder to ensure everything loads properly.

Your first look at an opened database

💡 Design

The window is structured to give both a high-level model's interface and access to more detailed information about its SQLite representation.

🔧 How it works

Most of the UI is built using SwiftUI, which makes it easy to iterate quickly and keep the layout declarative and predictable.

But the real workhorse here is the table view: it’s a fully custom, Metal-based renderer. That might sound like overkill for a database viewer, but it’s what allows the app to scroll through thousands of rows at a smooth 120 FPS, even on older Macs. I’ve covered more about this rendering approach in this article, so feel free to check that out if you’re curious about the performance side.

Data Models Overview

💡 Design

The left sidebar serves as the primary way to explore the structure of your database. At the top, you’ll see a list of SwiftData models, laid out in a way that mirrors how you’d recognize them in your project, typically named after your Swift files.

Each model entry includes:

• The number of stored entities
• Any inherited model types

This section aims to keep a balance between familiarity and depth: giving you just enough context without overwhelming detail.

Below the model list is a more technical view showing the raw SQLite tables. While most users will spend their time with the Swift-style models, this lower-level section is available for those moments when you need to debug something a bit closer to the details.

🔧 How it works

The model list is populated directly from the NSManagedObjectModel, making it a straightforward reflection of what SwiftData sees internally.
The table list is implemented by using SQLite directly to query all available tables in the database. It’s a fallback for users who want to inspect the raw schema or troubleshoot at the database level.

Inspecting the Content

Next, let’s take a look at the table view itself.

Relationships Navigation

💡 Design

At the top left, you’ll find the next layer of navigation: relationship breadcrumbs. On the root level, this simply shows that you’re viewing all instances of the selected entity. But this part becomes especially useful when exploring relationships between models — it acts as a path indicator as you drill down into related data.

Most other tools tend to show relationships in a separate split view, which can be informative, but (at least in my experience) makes it harder to understand the actual path you’re following through the data. I’ve heard positive feedback specifically about this breadcrumb approach, so I’m pretty happy with how it turned out.

🔧 How it works

The UI for this part is fairly straightforward. The real challenge lies in keeping everything in sync. Since all related datasets are held in memory, any change in the data (like updates or deletions) has to be propagated through all open views and relationships. That adds some behind-the-scenes complexity to what appears like a simple, fluid navigation experience.

Advanced Filtering with Predicate

💡 Design

Just below relations is the predicate filter, which lets you refine the dataset based on specific conditions.

The predicate system is designed to behave as closely as possible to what you’d expect from real SwiftData or Core Data filtering. That turned out to be quite a challenge, especially when handling complex expressions and supporting different data types.

Some data types still aren’t supported yet, but I’m actively working on expanding coverage as I go.

The predicate editor itself also tries to recreate the feel of Xcode. It highlights known symbols and offers autocompletions to help you write valid predicates more easily. While it may seem like a small detail, it took a lot of behind-the-scenes work to make it feel smooth and natural.

🔧 How it works

This part is arguably the most complex implementation in the entire app, maybe even the biggest single chunk of code. I explored at least five different approaches to achieve the most accurate and reliable behavior:

• Running the code directly on the Swift toolchain
• Compiling it into a binary and linking it to the app for execution
• Mapping the string into NSPredicate directly
• Compiling it as WebAssembly (WASM)
• Running it inside a small custom virtual machine

Each of these had serious drawbacks that ultimately made them unfeasible.

So I settled on a simpler (in theory) but still quite ambitious solution: building a function that takes a string as input and outputs a Swift Predicate, which could then be used to initialize an NSPredicate.

This turned out to be a massive effort. It required a lot of utility classes and internal logic to make the parsing and construction reliable. The implementation also takes advantage of a new Swift 6 feature: Implicitly Opened Existentials, which made some of the generic work easier.

One of the trickier blockers was creating a KeyPath from a string input. Thankfully, since our predicates are constrained to NSObject, we can use selector-backed KeyPaths, which can be constructed from plain strings. That simplification was key to making the system work.

Let’s break down all the steps a string goes through to finally become an NSPredicate:

1. First, we validate that the code is actually correct. For the best accuracy, this step uses SourceKit diagnostics.
2. Then we parse the code into a syntax tree using SwiftSyntax.
3. Next, we expand the code using the Predicate macro implementation from Swift’s Foundation framework. This gives us the syntax tree of the predicate builder.
4. After that, we need to match all the build functions to their correct data types. Since Swift’s type inference is pretty advanced and not something you can easily replicate, we call SourceKit again to help out.
5. Now that we have both the tree and all the resolved types, we can rebuild those structures as a real Predicate instance.
6. And finally, we initialize the NSPredicate and use it to fetch the data.

It’s a long process, and one that sounds overkill until you try to actually support the full range of what NSPredicate can do. Some people might suggest it’d be easier to just map the string directly into an NSPredicate. I’ve tried that too, and honestly, I can’t recommend it. It breaks down quickly as soon as you need anything more than basic comparisons.

But just processing the string correctly is only half the problem. The other half is building a code editor that highlights the syntax and handles autocomplete in a way that feels familiar, ideally close to Xcode.

The simplest part is reconstructing the string with syntax highlights from the abstract syntax tree. But it quickly became clear that without showing known symbols, the experience felt incomplete and unpleasant.

That’s when I had to go back to digging through my research. The most straightforward idea was to enable SourceKit’s debug mode in Xcode and track all the logs while editing. It helps, but it also brings a lot of confusion — sometimes the info isn’t enough, and to really track known symbols, you need to gather data from several kinds of information. The most obvious one is autocomplete.

So the next challenge is: once you start building up a list of known symbols, how do you keep them up to date while editing the code?

A common approach is to store symbol offsets along with extra metadata. But what happens when the user edits something earlier in the line and the offsets shift? In that case, you need to reposition everything correctly, and even then, you run into edge cases. For example, if the start of the expression changes and a symbol should become invalid, sometimes the editor still highlights it anyway.

But after spending more time testing Xcode, I realized it does the same thing. It doesn’t always immediately remove highlights either. So I took that as a green light.

With all of that in mind, I built the editor to combine information from multiple sources and update it live as you type. It took some effort to get right, but now it feels much smoother and much closer to the kind of experience you’d expect.

One missing piece was matching Xcode’s autocomplete behavior. I ended up simplifying that down to a single rule: if the cursor is inside a method call declaration, show autocomplete suggestions filtered by the currently typed part of the name. It’s not perfect, but in most cases, it feels right, and from the user’s perspective, that’s good enough.

It might seem like overkill to put this much work into just the filtering feature. But I really wanted it to feel natural and intuitive. I didn’t want to throw an unfamiliar syntax at the user or expect them to remember obscure NSPredicate formats. And I definitely didn’t want to build one of those filters made up of dropdowns and toggles — it always ends up being clunky. For me, this felt like the only solution that made sense.

Smart Column Headers

💡 Design

Now we can see the full list of model properties displayed as table column headers.

At first glance, this part might seem pretty straightforward, but there’s actually quite a bit happening under the hood as well.

Visually, the headers are designed to mirror how SwiftData model properties appear in your code. But they also offer additional details on hover, offering a deeper layer of insight without cluttering the main view.

One of the more subtle but useful features here is property ordering. The table automatically prioritizes key information: identification fields come first (like IDs), followed by properties that are typically more informative, such as name or title. This makes it easier to quickly spot the most important fields in your data.

Another hidden detail is the accuracy of the displayed type names. Instead of showing low-level Core Data types, the table presents the actual types used in your Swift code. This helps keep the experience aligned with how you think about your models while working in Swift.

🔧 How it works

To determine the property order, it uses a small CoreML linear regression model that scores the relative importance of each property for the user. It’s a minor detail, but it really helps make large datasets easier to scan.

For the property types, the tool takes things a step further. Instead of relying on Core Data’s internal metadata, it analyzes the app’s compiled binary. When a database is opened from a specific simulator app and the tool can locate the corresponding binary, it can extract model metadata directly from it. That’s what allows it to show precise type names and match the visual structure of the model to how it’s written in your code.

The Data Previews

💡 Design

Now let’s finally look at the actual data. The values are pre-formatted for maximum readability, even if they’re stored as raw String or Data.

In the screenshot above, you can see a few examples:

• The UUID is highlighted with an emphasis on its numeric components.
• The name appears like a string literal, making it immediately obvious that it’s a plain string.
• The cells property is stored as raw NSData, but the format was recognized as JSON, so it’s highlighted and formatted accordingly.
• The background property is a composite type. In Core Data, that’s stored as an NSDictionary; in SQLite, it’s split into separate columns. But here, it’s shown as a clean type exactly like in the code.

This formatting logic is recursive, so even if a media type or composite value is deeply nested, the tool will still recognize it and present it in a human-friendly way.

If the data is too large to fit into the table, you can click the cell to open an expanded, formatted preview right in place.

In some cases, even if the preview isn’t fully implemented yet, the app still recognizes the format. That means the underlying detection logic is already in place, and full preview support will be added in future updates.

If a property is a relationship, it’s styled with a distinct background to highlight that it’s clickable. It also shows a brief summary of the referenced entity to give you quick context.

Clicking the reference lets you drill down into that related data, and the breadcrumb at the top updates to reflect the navigation path. You can also jump back to any previous point in the path by clicking its segment.

🔧 How it works

After the data is fetched from the database, it’s passed to the Rust-based core of the app, which is optimized to handle the extra processing needed for a smooth and readable preview.

Most types have a pre-defined appearance and can be directly transformed into attributed strings. But for more complex cases, where the raw value isn’t very informative, the pre-processor runs additional checks to detect known formats. For example, it can tokenize JSON for syntax highlighting.

It’s also responsible for merging metadata from multiple sources, like type information extracted from the compiled binary or scoring hints from the linear regression model, to build previews in a meaningful way.

Event Console

💡 Design

Finally, at the bottom of the screen, we have the console, where you can see a timeline of events related to the table, along with how long each step took.

The first event you’ll usually see is the initial analysis phase I mentioned earlier, where extra data type information is collected. Then comes the event showing how long it took to load the data, followed by the time needed to recognize and format the data entries.

There’s also a dedicated tab showing the full process of building the predicate, broken down step by step.

All the steps from the Predicate section described earlier are logged here, and each one can be expanded to see the exact result of that stage.

🔧 How it works

Technically, there’s nothing too complex about this part, it’s just a simple SwiftUI List. However, despite its simplicity, it doesn't perform as well as expected. Sometimes, scrolling lags, and the expanding functionality breaks intermittently. At this point, there are only two viable solutions: either move this component to the Rust-based part of the UI or wait for Apple to improve the List. In macOS 15.4.1, there has been noticeable progress; scrolling lag has almost disappeared, but I still hope they’ll address the expansion issue as well.

Live Updates

💡 Design

When the user interacts with the app in the simulator and the data changes, the updates are reflected in real-time within DataScout. Changes to Core Data are highlighted, making it easy to pinpoint where the change occurred while continuously displaying relevant information. This simple yet effective approach is what I’ve opted for so far.

🔧 How it works

This feature is fairly straightforward. It processes the most recent transactions, walks through the displayed data, and updates it accordingly. By leveraging additional indexing of IDs, it quickly identifies modified objects and refreshes their values along with the timestamp of the last modification. The table then triggers a blink animation based on the updated timestamp, visually highlighting the changes.

Bonus: Extra Databases

Since the table view and data recognition are implemented as independent components, I can also connect it directly to SQLite for scenarios where Core Data isn’t used. This retains the data format recognition and relationship navigation features but loses the ability to track recent transactions, as the storage configuration can vary. As a result, the app won’t highlight changes in the UI in this case. While there are opportunities to build more advanced solutions for this later, my backlog is already quite full. For this integration, the app uses Turso’s libsql instead of standard SQLite, offering additional features while maintaining compatibility with SQLite.

I’ve also implemented an alternative presentation mode for NoSQL data structures, though currently, this UI is only used for one additional database format, which was popular in Flutter — Hive. I added it in an effort to broaden the app’s audience, particularly for Flutter developers, but it hasn’t garnered much attention. In the future, I plan to repurpose this UI for other NoSQL databases commonly used in mobile development.

🔧 How it works

In the code, I had to provide an alternative tree view for the content, in addition to the table format, and I think this could be useful for other scenarios as well, such as reusing it for the console.

Regarding the database itself, since the original implementation is based on Dart, I re-implemented a specific part for reading the data in Rust and adjusted the logic to improve the accuracy of recognizing unknown types. However, I’m still struggling to gather any feedback from Flutter developers. In hindsight, it might not have been worth the effort.

Bonus: Work in Progress and Future Ideas

The last thing I want to mention is the future direction of the app.

While it’s already packed with useful functionality, there are still some basic features missing that could be critical for certain users. I’m currently evaluating the best ways to integrate these into the UI. Some of these features include:

• Setting the sorting order
• Adding missing data types for Predicate
• Displaying the schema visually
• Showing images within the table UI
• Handling encrypted databases
• Implementing a simple search for text entries

These features will be added as soon as I find a way to seamlessly integrate them into the app’s existing style, keeping the approach simple and close to the code representation.

Besides that, there are also some larger plans I’m still researching, such as:

• Linking the database from a physical iPhone (or even Android) using a local network and an extra SDK for debugging. This feature is partially functional in my test builds but is currently blocked by the specifics of SQLite storage (due to shared memory corruption during transfer when the database is in WAL mode). I’ve also vibe coded an SDK for initial testing (Disclaimer: the vibe of this code is still rough, mostly suitable for prototyping. Only a small part has been polished so far, but I plan to refine it soon). The initial approach doesn’t seem viable for SQLite, so I’m planning to implement another SDK using the libSQL replication feature instead.
• Editing data is a major topic, but could be tricky, especially when data is heavily formatted for better representation or when it’s linked via a network.
• Auto-detecting Queries used in the app views and showing them as a list, following the list of models. This one is complex and will require adding some missing features to the Predicate (like variables), but it should be achievable.

Conclusion

DataScout started out as my personal playground for experimenting with SwiftSyntax, SourceKit, CoreML, Rust, and more. Along the way, I built features like relationship breadcrumbs, live updates, Metal-powered tables, and smart predicate parsing — each one driven by the goal of making database inspection feel as natural and code-like as possible.

But beyond my own sandbox, I’ve seen real value in the app. Features like in-place data previews, custom type highlighting, and breadcrumb navigation have already helped me and a few users.

Looking ahead, I’ll keep adding missing pieces. My guiding principle remains the same: keep the UI simple, stay close to how you write code, and never hide useful information behind too many menus.

If you’ve enjoyed this walkthrough or have ideas for DataScout, drop a comment or reach out. Your feedback will help shape the next updates and keep this tool both useful and easy to use.

A little backstory on how I ended up deciding to spice up my app with Rust: A few months ago, I was working on a simple app to display the contents of a database while debugging. The goal was to quickly spot errors while implementing cloud sync. I planned to spend just a couple of evenings on it, but things took an unexpected turn.

SwiftUI’s Table had pretty poor performance. My first idea was to replace it with NSTableView, but to my surprise, it turned out to be just as limited and unstable. At that point, this issue completely captured my attention—I had already decided to turn this into a proper, polished app that I could submit to the App Store. But optimizing old and buggy table views didn’t seem like the most exciting challenge.

Then it hit me: with no looming deadlines, I could explore new technical horizons. A challenging idea emerged — why not seek out the fastest UI library from an unexpected language and find a way to integrate it into my app?

After a bit of searching, egui caught my attention. Unlike traditional UI frameworks, egui uses an immediate mode approach, meaning the UI is redrawn every frame instead of maintaining persistent state objects. This meant I didn’t have to worry about managing state updates, and the UI rebuilding process seemed incredibly fast. So, I decided to give egui a shot.

Now, let’s move on to the core idea I want to explore: keeping the high-level structure of the app in SwiftUI for ease of handling while isolating egui in a specific, performance-sensitive part. The goal is to establish a smooth and convenient way to communicate between Swift and Rust.

As an example, we’ll build a simple chat window where the active conversation can be switched from the Swift side. The full source code will be linked at the end of the article.

I’ll be following the same steps in this article as I do when implementing the sample app.

Disclaimer: This article does not cover all related topics in detail, but it provides links to documentation where you can find more information. It assumes you have a basic understanding of macOS development with SwiftUI, some experience with Rust, and a fundamental knowledge of GPU programming. The focus will be on guiding you through the high-level steps rather than explaining every concept from scratch.

Building the bridge

At first, I attempted to establish communication using a simple FFI, but the data transfer implementation proved time-consuming and fraught with memory management challenges. Ultimately, I turned to the swift-bridge library to simplify the process. Let’s follow the same approach here.

Let’s begin by creating a library package for our Rust UI:

cargo init --lib --name smooth-ui

Next, modify the Cargo.toml to configure it as a static library:

[lib]
name = "embed"
crate-type = ["staticlib"]

I recommend setting up the swift-bridge dependency in a separate Swift package from this article, though you can choose an alternative method that suits your workflow. After setting up the dependency, create a file to define the interface visible to Swift:

#[swift_bridge::bridge]
mod ffi {
    extern "Rust" {
    }
}

I’ve also included a build script in the project that you can reference and copy into your own work.

Tip: If you’re new to this setup, I strongly recommend implementing a simple “Hello World” function and calling it from Swift first. This approach will help you gain confidence and clarity before diving into more complex implementations.

Creating the Renderer

With our project configured, we can now create our Renderer responsible for handling graphics rendering for the UI:

pub struct Renderer {
    device: wgpu::Device,
    queue: wgpu::Queue,
    surface: wgpu::Surface<'static>,
    config: wgpu::SurfaceConfiguration,

    // The rest will come on egui part
}

Let’s define the renderer’s interface with three key functions essential for this tutorial:

impl Renderer {

    // layer_ptr is the pointer to our CAMetalLayer from AppKit/UIKit side
    pub fn new(layer_ptr: *mut std::ffi::c_void, width: u32, height: u32) -> Self {
        let descriptor = wgpu::InstanceDescriptor {
            backends: wgpu::Backends::METAL,
            ..Default::default()
        };
        let instance = wgpu::Instance::new(&descriptor);
        // Create a surface with our metal layer, passed from the swift side
        let surface = unsafe {
            instance.create_surface_unsafe(wgpu::SurfaceTargetUnsafe::CoreAnimationLayer(layer_ptr)).unwrap()
        };

        // The rest of the setup from https://sotrh.github.io/learn-wgpu/beginner/tutorial2-surface/#state-new
        // Or check the final source code for the complete picture
    } 

    pub fn resize(&mut self, width: u32, height: u32) {
        // The implementation from https://sotrh.github.io/learn-wgpu/beginner/tutorial2-surface/#resize
    }

    pub fn render(&mut self, time: f64) {
        // Check https://sotrh.github.io/learn-wgpu/beginner/tutorial2-surface/#render 
        // Or final source code for the complete picture with egui
    }
}

For those unfamiliar with GPU programming, I recommend following the wgpu tutorial to implement the remaining setup process based on your specific requirements. The critical aspect here is configuring the surface for our Metal layer.

Now, we’ll add this interface to the FFI module to enable access from Swift code:

use super::renderer::Renderer;

use std::ffi::c_void;

#[swift_bridge::bridge]
mod ffi {
    extern "Rust" {
        type Renderer;

        #[swift_bridge(init)]
        fn new(layer_ptr: *mut c_void, width: u32, height: u32) -> Renderer;

        fn resize(&mut self, width: u32, height: u32);

        fn render(&mut self, time: f64);
    }
}

Key points to note:

• The implementation focuses on setting up a Metal-based rendering surface
• Detailed setup can be referenced in the suggested tutorials
• The FFI module provides a clean interface for Swift interaction

Implementing the Swift Renderer

Let’s start by creating an NSView backed by CAMetalLayer to display our Rust-generated UI:

import Metal
import AppKit
import SmoothUI // The package generated with swift-bridge

@MainActor
final class SmoothNSView: NSView {
    
    var metalLayer: CAMetalLayer {
        layer as! CAMetalLayer
    }
    
    override init(frame frameRect: NSRect) {
        super.init(frame: frameRect)
        wantsLayer = true
    }
    
    override func makeBackingLayer() -> CALayer {
        CAMetalLayer()
    }
}

Next, we’ll create a renderer controller to manage view callbacks:

import Metal
import AppKit
import SmoothUI

@MainActor
final class SmoothRendererController: NSObject {
    private weak var view: SmoothNSView!
    private var displayLink: CADisplayLink!
    
    private var renderer: Renderer!
    
    deinit {
        MainActor.assumeIsolated {
            displayLink.invalidate()
        }
    }
    
    func initialize(view: SmoothNSView, size: CGSize, scale: CGFloat) {
        self.view = view
        
        let layer = view.metalLayer
        layer.framebufferOnly = true
        layer.pixelFormat = .bgra8Unorm_srgb
        layer.drawableSize = size
        layer.contentsScale = scale
        
        let rawPointer = Unmanaged.passUnretained(layer).toOpaque()
        renderer = Renderer(
            rawPointer,
            UInt32(max(size.width, 100.0) * scale),
            UInt32(max(size.height, 100.0) * scale)
        )
    }
    
    func start(view: SmoothNSView) {
        let link = view.displayLink(target: self, selector: #selector(render))
        link.add(to: .main, forMode: .common)
        self.displayLink = link
    }
    
    @objc
    func render(displayLink: CADisplayLink) {
        renderer.render(
            Date.now.timeIntervalSince1970
        )
    }
    
    func resize(to size: CGSize, scale: CGFloat) {
        guard size.width > 0 && size.height > 0 else {
            return
        }
        renderer.resize(
            UInt32(size.width * scale),
            UInt32(size.height * scale)
        )
    }
}

To integrate with SwiftUI, we’ll create an NSViewRepresentable wrapper:

import SwiftUI
import AppKit

struct SmoothView: View {
    
    @Environment(\.displayScale)
    var displayScale
    
    var body: some View {
        GeometryReader { proxy in
            SmoothNSViewRepresentable(
                size: proxy.size,
                scale: displayScale
            )
        }
    }
}

private struct SmoothNSViewRepresentable: NSViewRepresentable {
    let size: CGSize
    let scale: CGFloat
    
    func makeNSView(context: Context) -> SmoothNSView {
        let view = SmoothNSView(frame: .zero)
        context.coordinator.initialize(view: view, size: size, scale: scale)
        context.coordinator.start(view: view)
        return view
    }
    
    func updateNSView(_ nsView: SmoothNSView, context: Context) {
        context.coordinator.resize(to: size, scale: scale)
    }
    
    func makeCoordinator() -> SmoothRendererController {
        SmoothRendererController()
    }
}

Finally, we can embed the view in our app’s UI:

import SwiftUI

struct ChatListView: View {
    
    var body: some View {
        NavigationSplitView {
            List {
                Text("Chat 1")
                Text("Chat 2")
            }
        } detail: {
            SmoothView()
        }
    }
}

At this point, running the project should set up rendering for SmoothView on the Rust side and display it within the SwiftUI view hierarchy.

Tip: If you’re new to GPU programming, I recommend implementing a simple triangle rendering from the wgpu documentation before proceeding further. This will help you understand the basic rendering concepts and setup.

Render Our first egui label

Let’s add the necessary dependencies to your Cargo.toml:

wgpu = "23.0"
egui = "0.30.0"
egui_wgpu_backend = "0.33.0"

A quick note on the backend: While I’m using egui_wgpu_backend for this tutorial, my experience with it has been nuanced. In my database project, I ultimately developed a custom rendering backend because the existing implementation didn't meet my performance requirements.

The standard egui_wgpu_backend seemed primarily optimized for WebGL, and I found its Metal rendering performance less than ideal. On Metal, a single frame was taking around 10 milliseconds, which wasn't acceptable for my use case. Through a custom implementation, I managed to reduce frame rendering time to just 1-2 milliseconds.

This performance optimization journey is a fascinating topic in itself. I’m considering open-sourcing my custom implementation in the future, which could be the subject of a separate, in-depth article. For now, we’ll proceed with the standard egui_wgpu_backend to demonstrate the core integration.

Let’s update our Renderer struct with additional properties for egui:

pub struct Renderer {
    // wgpu
    // ...

    // egui
    context: egui::Context,
    raw_input: egui::RawInput,
    egui_rpass: RenderPass
}

Now, we’ll modify the initialization function to set up egui:

pub fn new(layer_ptr: *mut std::ffi::c_void, width: u32, height: u32, display_scale: f32) -> Self {
    // Setup wgpu
    // ...

    // Setup egui
    let context = egui::Context::default();
    let raw_input = egui::RawInput {
        viewport_id: egui::ViewportId::ROOT,
        viewports: std::iter::once((egui::ViewportId::ROOT, egui::ViewportInfo {  
            native_pixels_per_point: Some(display_scale),
            focused: Some(true),
            ..Default::default() 
        })).collect(),
        predicted_dt: 1.0 / 120.0, // Setup according to your needs
        focused: true,
        system_theme: None,
        max_texture_side: Some(wgpu::Limits::default().max_texture_dimension_2d as usize),
        ..Default::default()
    };
    let egui_rpass = RenderPass::new(&device, tex_format, 1);

    // ...
}

The rendering function involves two critical steps:

1. Updating the UI state
2. Sending the rendered UI to the GPU

Here’s an overview of the rendering process:

pub fn render(&mut self, time: f64) {
    
    let device = &self.device;
    let queue = &self.queue;
    let surface = &self.surface;

    let ctx = &self.context;
    let egui_rpass = &mut self.egui_rpass;
    
    // Setup the input for the egui
    self.raw_input.time = Some(time);

    let rect = egui::Rect::from_min_size(
        egui::Pos2::ZERO, 
        egui::vec2(
            self.config.width as f32 / ctx.pixels_per_point(), 
            self.config.height as f32 / ctx.pixels_per_point()
        )
    );
    self.raw_input.screen_rect = Some(rect);

    // Run a single layout pass
    let full_output = ctx.run(self.raw_input.take(), |ctx| {
        egui::CentralPanel::default().show(&ctx, |ui| {
            ui.label("Hello, world!");
        });
    });

    // Prepare resources for rendering
    let paint_jobs = ctx.tessellate(full_output.shapes, ctx.pixels_per_point());

    // Handle rendering routines
    let frame = surface.get_current_texture().expect("Failed to get next frame");
    let view = frame.texture.create_view(&wgpu::TextureViewDescriptor::default());

    let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
        label: Some("Render Encoder"),
    });

    let screen_descriptor = ScreenDescriptor {
        physical_width: self.config.width,
        physical_height: self.config.height,
        scale_factor: ctx.pixels_per_point(),
    };
    let tdelta: egui::TexturesDelta = full_output.textures_delta;

    egui_rpass
        .add_textures(&device, &queue, &tdelta)
        .expect("add texture ok");

    egui_rpass.update_buffers(&device, &queue, &paint_jobs, &screen_descriptor);

    // Execute all render passes.
    egui_rpass
        .execute(
            &mut encoder,
            &view,
            &paint_jobs,
            &screen_descriptor,
            Some(wgpu::Color::BLACK),
        )
        .unwrap();

    // Submit commands to the GPU
    self.queue.submit(Some(encoder.finish()));

    // Present the frame
    frame.present();

    // Clean up resources after using
    egui_rpass.remove_textures(tdelta).unwrap();
}

When implemented correctly, you’ll see your first egui label rendered within the SwiftUI view.

This marks our first significant milestone, but there’s still much to explore and optimize in the integration process.

Crafting a Native-Feeling User Interface

Our initial implementation was functional, but now it’s time to refine the UI to make it more user-friendly and system-integrated. Both implementations of SwiftUI and Rust parts can be checked here and here.

Now it looks better, but something is still bothering me as a macOS user. I want to see the SF font in my UI, just like in the rest of the system, so let’s set up system fonts.

For this purpose, I found a handy library in Rust:

font-kit = "0.14.2"

Now we can extend our egui setup with font configurations:

// Setup egui
let context = egui::Context::default();

let display_font_data = load_font_data_by_name("SF Pro Text Medium");

if let Ok(display_font_data) = display_font_data {

    let mut fonts = egui::FontDefinitions::default();

    let display_font_data = Arc::new(egui::FontData::from_owned(display_font_data));
    fonts.font_data.insert("SF-Pro-Text-Medium".to_owned(), display_font_data);

    let display_family = egui::FontFamily::Name("SF-Pro-Text".into());
    fonts.families.insert(display_family.clone(), vec!["SF-Pro-Text-Medium".to_owned()]);

    context.set_fonts(fonts);
    
    context.all_styles_mut(|style| {
        let text_styles: BTreeMap<_, _> = [
            (egui::TextStyle::Heading, egui::FontId::new(11.0, display_family.clone())),
            (egui::TextStyle::Body, egui::FontId::new(13.0, display_family.clone())),

            (egui::TextStyle::Button, egui::FontId::new(14.0, display_family.clone())),
            (egui::TextStyle::Small, egui::FontId::new(10.0, display_family.clone())),
        ].into();
        
        style.text_styles = text_styles;
    });
}

Now the result looks much better, and as a bonus, it can display SF Symbols.

Connecting Input/Output

We’ve reached the most challenging part of our integration. Handling input and output can be complex, as the state provided by egui might conflict with the state requested by the SwiftUI view. However, I’ve developed a compromise that should work.

Let’s start by creating input events for mouse interactions on the Rust side:

pub enum InputEvent {
    PointerMoved(f32, f32),
    MouseWheel(f32, f32),
    LeftMouseDown(f32, f32, bool),
    RightMouseDown(f32, f32, bool),
    WindowFocused(bool),
    // And the rest of the events for keyboard if needed
}

impl Into<Event> for InputEvent {
   
    fn into(self) -> Event {
        match self {
            InputEvent::PointerMoved(x, y) => Event::PointerMoved(egui::Pos2::new(x, y)),
            InputEvent::MouseWheel(x, y) => Event::MouseWheel { unit: egui::MouseWheelUnit::Point, delta: egui::vec2(x, y), modifiers: Modifiers::default() },
            InputEvent::LeftMouseDown(x, y, pressed) => Event::PointerButton { pos: egui::Pos2::new(x, y), button: egui::PointerButton::Primary, pressed, modifiers: Modifiers::default() },
            InputEvent::RightMouseDown(x, y, pressed) => Event::PointerButton { pos: egui::Pos2::new(x, y), button: egui::PointerButton::Secondary, pressed, modifiers: Modifiers::default() },
            InputEvent::WindowFocused(focused) => Event::WindowFocused(focused),
        }
    }
}

Now, we’ll update our render function to handle input events before updating the UI:

pub fn render(&mut self, time: f64, input_events: Vec<InputEvent>, /* other arguments */) {
    
    // Out previous input setup
    self.raw_input.events = input_events.into_iter().map(|e| e.into()).collect();

    // Update the UI and render the result
}

Important Note: Remember to add these events to the FFI to make them visible to Swift. The full FFI setup can be intricate, so I recommend checking the complete implementation for detailed specifics.

Now, let’s return to the Swift project and create a new NSView for input handling. Our SmoothNSView will inherit from this custom view:

class InputOutputHandlingView: NSView {
    
    private var trackingArea: NSTrackingArea?
    private var gatheredEvents: [InputEvent] = []
    
    override var acceptsFirstResponder: Bool {
        true
    }
    
    func draingEvents() -> RustVec<InputEvent> {
        // Collect events into rust vector and remove all currently gathered events
    }
    
    // Install tracking area every time the view was resized
    // To track the pointer movement
    override func updateTrackingAreas() {
        super.updateTrackingAreas()
        
        if let trackingArea {
            removeTrackingArea(trackingArea)
        }
        
        let options: NSTrackingArea.Options = [
            .mouseEnteredAndExited,
            .mouseMoved,
            .activeInKeyWindow
        ]
        let trackingArea = NSTrackingArea(rect: bounds, options: options, owner: self, userInfo: nil)
        addTrackingArea(trackingArea)
        
        self.trackingArea = trackingArea
    }

    // MARK: - Movement tracking
    
    override func mouseEntered(with event: NSEvent) {
        // Map into our InputEvent and add to gatheredEvents
    }
    
    override func mouseMoved(with event: NSEvent) {
        // Map into our InputEvent and add to gatheredEvents
    }
    
    override func mouseExited(with event: NSEvent) {
        // Map into our InputEvent and add to gatheredEvents
    }
    
    // MARK: - Mouse Button and Scroll Events
    
    override func mouseDown(with event: NSEvent) {
        // Map into our InputEvent and add to gatheredEvents
        super.mouseDown(with: event)
    }
    
    override func mouseUp(with event: NSEvent) {
        // Map into our InputEvent and add to gatheredEvents
        super.mouseUp(with: event)
    }
    
    override func mouseDragged(with event: NSEvent) {
        // Map into our InputEvent and add to gatheredEvents
        super.mouseDragged(with: event)
    }
    
    override func rightMouseDown(with event: NSEvent) {
        // Map into our InputEvent and add to gatheredEvents
        super.rightMouseDown(with: event)
    }
    
    override func rightMouseUp(with event: NSEvent) {
        // Map into our InputEvent and add to gatheredEvents
        super.rightMouseUp(with: event)
    }
    
    override func rightMouseDragged(with event: NSEvent) {
        // Map into our InputEvent and add to gatheredEvents
        super.rightMouseDragged(with: event)
    }
    
    override func scrollWheel(with event: NSEvent) {
        // Map into our InputEvent and add to gatheredEvents
        super.scrollWheel(with: event)
    }
}

With this implementation, we can now gather input events from the view and pass them to the renderer:

@objc
func render(displayLink: CADisplayLink) {
    let events = view.draingEvents()
    renderer.render(
        displayLink.timestamp,
        events,
        controller
    )
}

Now we can scroll our chat and observe the smooth scrolling in action.

However, there is still one crucial detail missing: our system doesn’t react to what is happening inside the view. To address this, we need to develop a way to connect the output. Let’s use cursor switch events as an example.

We’ll start by creating additional structures on the Rust side:

pub struct OutputState {
    cursor_icon: CursorIcon,
}

pub enum CursorIcon {
    Default,
    PointingHand,
    ResizeHorizontal,
    ResizeVertical,
    Text,
}

impl From<egui::CursorIcon> for CursorIcon {
    
    fn from(cursor_icon: egui::CursorIcon) -> Self {
        match cursor_icon {
            egui::CursorIcon::Default => Self::Default,
            egui::CursorIcon::PointingHand => Self::PointingHand,
            egui::CursorIcon::ResizeHorizontal | egui::CursorIcon::ResizeColumn => Self::ResizeHorizontal,
            egui::CursorIcon::ResizeVertical | egui::CursorIcon::ResizeRow => Self::ResizeVertical,
            egui::CursorIcon::Text => Self::Text,
            default => {
                println!("Unsupported cursor icon: {:?}", default);
                Self::Default
            }
        }
    }
}

Next, we’ll update the render function to return this state after rendering the UI:

    pub fn render(&mut self, /* other arguments */) -> OutputState {
        
        // Updating UI and rendering

        OutputState::new(full_output.platform_output.cursor_icon.into())
    }

The FFI module should be updated accordingly. If you encounter any issues with this part, you can refer to this FFI module implementation for guidance.

Now we can add output handling to our InputOutputHandlingView:

func handle(output: OutputState) {
    let setCursor = output.get_cursor_icon()
    let newCursor = cursorToNSCursor(setCursor)
    
    if currentCursor != newCursor {
        if let activeCursor = currentCursor {
            activeCursor.pop()
            currentCursor = nil
        }
        
        newCursor.push()
        currentCursor = newCursor
    }
}

func resetCursor() {
    if let activeCursor = currentCursor {
        activeCursor.pop()
        currentCursor = nil
    }
}

Next, connect the result of rendering to this handler:

@objc
func render(displayLink: CADisplayLink) {
    let events = view.draingEvents()
    let state = renderer.render(
        displayLink.timestamp,
        events,
        controller
    )
    view.handle(output: state)
}

And that’s it. When you run the project, you’ll now be able to see the cursor switch when pointing at text. However, you won’t yet be able to copy text, as that would require implementing additional output handling. This concludes the core implementation of integrating egui with SwiftUI.

Conclusion

In this article, I’ve provided a basic overview of the mechanisms involved, but many details are still left out. This should serve as a good starting point for you to implement these concepts on your own. If you spot any errors or have suggestions for improving my implementation, I would be grateful to hear your thoughts. Let’s evolve this into something even better together! And a big thank you if you’ve made it this far!

Open points

• I’m still considering how to wrap this into a utility library with a more convenient interface. If you have any ideas, I’d love to hear them!
• Additionally, the architecture might feel a bit tricky, as both the SwiftUI and Rust parts essentially need their own “view” and “controller” layers. If you have thoughts on how to improve this aspect, feel free to share.

The full source code can be found here.