The open-source Arc replacement for macOS. Spaces, pinned tabs, split view, Little Windows and Arc's shortcuts on Chromium, with your Arc sidebar imported in one go.
Developing Cra
Notes for working on the code. How to send a change is in CONTRIBUTING.md; user-facing docs live in the help centre at crabrowser.app/help.
Build
scripts/build.sh # fetches CEF on first run, builds build/Cra.app
scripts/build.sh debug # debug build
scripts/run.sh # build if needed, then open; --rebuild [debug] forces a build
scripts/dev.sh # dev loop: debug CraDev.app, rebuilds + relaunches on save (~4 s)
scripts/dev.sh --once # build and launch CraDev.app once, logs in this terminal
just lists all of the scripts below with what each does (brew install just; the
justfile is one recipe per script). A recipe passes its arguments on, so
just build debug runs scripts/build.sh debug. CI calls the scripts directly, and so can
you.
Requirements: macOS 14+ on Apple silicon, Xcode 16+, CMake (brew install cmake), about
1 GB of disk for CEF and the build products.
scripts/fetch-cef.sh pins the CEF version and downloads it into vendor/cef (not
committed). It fetches Cra's own CEF build, made by scripts/build-cef.sh with H.264/AAC
and the patches in scripts/cef-patches and published as a cef-* release by
scripts/publish-cef.sh; CEF_URL points it at Spotify's stock build instead. A daily workflow (.github/workflows/cef-updates.yml) opens an
issue when a newer stable CEF is out; scripts/update-cef.sh moves the pin.
Layout
Sources/Cra— the app:App(delegate, key bindings),Services(sidebar store, persistence, import, updates, extensions, live folders),UI(sidebar, command bar, split view, windows, settings, onboarding)Sources/CraCEF— Objective-C++ bridge between Swift and CEFSources/CraHelper— Chromium subprocess executableSources/Cra/Services/WebKit— the WebKit page that DRM services open in (protected-media.md)Packages/CraCore— models and decisions with no AppKit or Chromium (the sidebar model, settings and the other data-folder files, Air Traffic Control, live folder data, key chords, space themes, Arc theme import, the favorites grid), visible in everySources/Crafile. The layer rules are in CLAUDE.mdTests/— the harnesses that compile production files against fakes, and the smoke testresources/— app icon, brand PNGs, the ad and tracker blocklist with its licence noticesscripts/— build, release, CEF and test tooling;scripts/clipsrecords release clipsdocs/arc-reverse-engineering.md— what was learned from Arc and howdocs/release.md— signing, notarization and the release workflowvendor/cef— CEF binary distribution (fetched, not committed)
Data lives in ~/Library/Application Support/Cra: the sidebar and archive as JSON,
keybindings.json, cached favicons, the logs and a Chromium profile folder. Delete it to
start over.
cra.log is Cra's own log: each tab's page opening, showing, loading, failing to load (with
the net error and the extension that set the proxy) and closing, and three seconds after a tab
comes on screen and its page has loaded, what the page holds (blank, visibility, element
and body child counts, painted for a first contentful paint, frameRate for the animation
frames it got in half a second, video for the first video's dropped/total frames) and where Cra put it (view size, window=covered when another
window hides it, display= the refresh rate of the display it is on). A visible page with
frameRate=0 was never asked to draw; frames without painted never reached the screen. chromium.log holds Chromium's warnings,
failed page loads and crashed renderers. Each launch keeps the last one's as *.previous.log.
Logs name sites by host only. Help ▸ Export Diagnostics… zips both with the GPU report,
the displays and their refresh rates, whether Stage Manager is on, the on-screen pages' state, settings, extensions and the last week's crash reports, with
addresses cut to their host; cra://debug?exportDiagnostics=<path> does the same without
the save panel.
Tests
scripts/test.sh # everything below except the smoke test, in seconds
scripts/test.sh core # only Packages/CraCore
scripts/test-folder-glyph.sh # folder emblems: layer projection, colors and Retina resolution
Tests/smoke-launch.sh # launches build/Cra.app three times, about 30 s
scripts/scenario.sh all # user journeys in build/Cra.app, about 6 minutes
scripts/scenario.sh sleep-tabs # one of them (Tests/Scenarios/<name>.scenario)
scripts/coverage.py # line coverage, and the changed-lines gate against origin/main
scripts/coverage.py --base <ref> # the same against another base (CI passes the PR's)
scripts/fuzz.sh # mutated importer fixtures under AddressSanitizer
scripts/mutate.py [word] # mutation testing of the pure code, about an hour; a word limits it
testing.md has the rules, the layers, the gates and how to write a scenario.
CI runs the same tests on every pull request and push to main (no CEF download), once, through
scripts/coverage.py plus scripts/lint.py, and the smoke test on the app it builds. A change
to Markdown or docs/ alone runs nothing.
Packages/CraCore(swift test --package-path Packages/CraCore): a package of its own, so its tests build withoutvendor/cef. Code that decides something without a window or a page belongs here, with a test: a layout rule, a mapping from Arc's or Chromium's files, a policy. Expected values for anything copied from Arc come from Arc's measurements indocs/arc-reverse-engineering.md; fixtures hold Arc's own JSON, trimmed to what is read.Fixtures/Modelholds data-folder files, current and older shapes, each with what Cra saved after loading it (recorded before the model moved here, #51).Tests/test-browser-manager.sh,scripts/test-floating-sidebar.sh,scripts/test-extension-popup-candidate.sh,scripts/test-extension-state.sh: compile a few production files withswiftcagainst fakes (Tests/BrowserManagerSupportstands in for CraCEF and the rest of the app). When the manager calls something new from the app, add a stub toAppServices.swift.scripts/test-store.sh: the realSidebarStore,AppCompositionand importers on aManualScheduler, against the made-up Arc and Chromium profiles inTests/Fixtures.scripts/test-policies.sh: the decisions pulled out of the window controllers (ExtensionLaunch,DevToolsToggle,FeatureFlags).scripts/test-folder-glyph.sh: the standalone folder component's real AppKit layers and image pixels: emblems follow the front panel's perspective, keep their colors and proportions, and update at 1x/Retina. No CEF or visible window; coverage uses the same harness asscripts/test.sh.scripts/test-perf.sh: the performance recorder on a real main run loop: injected stalls, hang files with asamplestack, the session marker, ownership, the recording switch (performance.md).scripts/lint.py: Cra's own rules (testing.md), checked byscripts/test.sh.Tests/smoke-launch.sh [app]: starts the app on a throwaway data folder with no pages, with a page opened, then with it restored, and quits it like ⌘Q after a settings write. It fails on a crash, a hang, an error exit or a new crash report, which is how aCHECKinside Chromium shows up. Its own data folder lets it run next to your daily Cra.
What none of these see: compositing (the sidebar blur), fullscreen spaces, and how real sites behave. Check those by hand, and say how in the PR.
Scenario hooks for a command file (cra://debug?…): checkStore=1 logs a fault per broken
sidebar link, pageJS=<js> runs script in the focused page, installExtension=<folder> and
removeExtension=<id>, extensionAction=<id>, fullscreen=1|0, appActive=1|0 (the sidebar drawn as if
Cra were in front or behind, e.g. the download bin's dimming), windowSize=1280x800,
snapshot=<ViewClass[,n]>&out=<png>, sleepTabs=<seconds> (the 10 tabs used last too), memoryPressure=warning|critical (one
memory-pressure sweep at that level, if Settings ▸ Tabs has it on), stall=<ms> (blocks the main
thread), perfReport=<path> (the recorder's perf.json now), systemAppearance=light|dark|system
(the appearance Auto space themes follow, without changing the Mac's), themeEditor=1 (Edit
Theme Color… for the focused space), relaunch=1, quit=1, and nowPlaying=state|toggle|next|previous|pip|dismiss (the sidebar player's
newest card, then a Cra nowPlaying[<label>] <host> playing=… prev=… next=… video=… pip=… line per card
on stdout; &label= tells checks apart).
Running a test instance
scripts/dev.sh builds a separate CraDev.app, including Sparkle, without a production
update feed or URL registrations. The script runs it on build/dev-data (set CRA_DATA_DIR
for another profile); opened directly from Finder, CraDev uses ~/Library/Application Support/CraDev, never the installed Cra's profile. Ad-hoc development builds use a mock
encryption key for fresh profiles; use test data and do not copy a daily browser profile
or real credentials into them.
The dev bundle records the CEF download source and Sparkle version. Changing either pin refreshes the bundled frameworks, including an engine rebuild with the same CEF version but a new release suffix. The watcher notices changes to both fetch scripts. Compilation happens before the running dev instance stops; bundle replacement happens only after it has quit. Quit any separately launched CraDev before starting another dev script, so it cannot overwrite a framework still in use.
Cra is single-instance and the installed copy receives every cra:// URL, so test a
build next to your daily Cra with its own data folder and a command file:
CRA_DATA_DIR=/tmp/cra-test CRA_COMMAND_FILE=/tmp/cra-test.cmd build/Cra.app/Contents/MacOS/Cra &
echo "cra://action/newTab" >> /tmp/cra-test.cmd
Every line appended to CRA_COMMAND_FILE is handled like a cra:// URL, including the
scripting hosts below.
To measure smoothness, add CRA_HITCH_LOG=/tmp/cra-hitch.log: every main-thread stall of
8 ms or more is logged (<seconds> stall <ms>), with each command-file line as a
mark between them. The main thread is also Chromium's browser UI thread, so a stall
there delays input and scrolling too. Compare builds by running the same command
script against each.
CRA_TEST_BACKGROUND=1 keeps a test instance behind whatever you are using: its windows
open at the back and it ignores every request to activate (Chromium's included). Launch it
with open -g -n --env … so macOS doesn't bring it forward either. Two command-file hooks
drive the sidebar without touching the pointer: cra://debug?swipe=-14,22 plays a space
swipe (22 trackpad samples of 14 pt) and cra://debug?scroll=30,30,150,700 scrolls the
scroll view at x 150, y 700 of the window (from its top left) 30 pt a frame for 30 frames.
Measure them with sample <pid> 6 1 and compare the main thread's busy time between builds.
Tidy Tabs needs Apple Intelligence. CRA_TIDY_FAKE_MODEL=1 stands in a model that groups by
site (after a 1.6 s pause), so a test instance on any Mac shows the button, the squiggle and the
groups, Tidy Tab Titles names a pinned tab after its title's first part and Tidy Downloads tidies a
download's file name by hand; CRA_TIDY_FAKE_MODEL=off (or preparing, ineligible) shows Settings ▸ Max as a Mac
without Apple Intelligence would. cra://debug?tidy=1 runs Tidy on the window's space without
hovering the divider, cra://debug?undoTidy=1 is ⌘Z's undo and cra://debug?settingsPane=max
opens Settings on a pane.
cra://debug?dragEnd=<text> ends a drag of the window's tab whose URL holds the text, let go
with nothing taking it, the way a drag out of the sidebar ends: outside every Cra window it opens
in a new Blank Window (&at=x,y picks the point, from the screen's top left).
cra://debug?blankMoveTo=<n> picks the nth space in the Blank Window's "Move to…".
cra://debug?browserWindows=<label> logs each browser window's kind (normal, blank, incognito),
space, tabs, open tab and frame; cra.log gets the kinds and counts only.
cra://debug?menuAt=315,24 opens the menu a click at that window point would open (the
developer-mode ⌄ here), and &button=right the context menu, a tab row's for instance.
&target=little aims at the newest Little Window instead (its profile chip, for one).
Posted mouse events don't reach Cra's views and the rows have no AX menu action, so this is
the way to check a menu without the pointer. The menu shows up on screen. While it's open,
it is an AXMenu child of the app: each item's AXMenuItemCmdChar, AXMenuItemCmdModifiers
and AXMenuItemMarkChar give its shortcut and checkmark, and AXCancel closes it (a posted
Esc doesn't). The first menu after a launch can close before AX sees it, so open it again.
The sidebar's tab list and space pager are AppKit (UI/Sidebar/List): rows are plain
layer-backed views rebuilt from the store when it changes, a swipe moves the pager's layers
and the window tint (PagedGradientView) in Core Animation, and SwiftUI keeps the favorites,
space header, top bar and dock.
Pages are embedded in their pane cards (EmbeddedPages.swift): Chromium's page views move
from their Chrome window into the card, like Arc and Dia, and the Chrome window stays behind
empty, click-through and never key. Pages go back into their window while DevTools is open.
CRA_EMBED_PAGES=0 (or defaults write dk.kildahl.cra embedPages -bool NO) keeps pages in
their own child windows, the hosting before 0.1.17, for comparing the two.
Cleaning up after test copies
A renamed test copy leaves files outside its own folder: a 300 MB–1 GB code sign clone in
the per-user temp folder when it's killed instead of quit, plus caches, preferences and
LaunchServices entries under its bundle id. Dozens of them filled a 460 GB disk. Give a
copy a bundle id starting with dk.kildahl.cra.test. (or another dk.kildahl.cra,
dk.kildahl.test., app.crabrowser. or dev.cra. id), quit it through its menu rather
than killing it, and delete it when you're done.
scripts/clean-test-leftovers.sh removes what's left: clones no process has open, the data
of test bundle ids that aren't running, Claude Code scratchpads of this repo that haven't
changed for a day, and LaunchServices entries of deleted Cra bundles. It never touches
the installed Cra's ids, CraClip, a running app or anything changed in the last hour. Use
--dry-run to see what it would do. In Claude Code it runs in the background at most every
30 minutes as a Stop hook (.claude/settings.json), and the log of the last run is
$(getconf DARWIN_USER_TEMP_DIR)cra-clean-test-leftovers.log.
Scripting hooks
Cra registers the cra:// scheme so it can be driven from a shell:
open "cra://action/newTab" # any action id from KeyBindings.swift
open "cra://commandbar?query=github" # open the command bar with text
open "cra://open?url=https://example.com&background=1"
open "cra://open?url=https://example.com&little=1" # in a Little Window
open "cra://open?url=https://example.com&space=<space id>" # in that space (its id in sidebar.json)
open "cra://import?source=arc&archive=1&settings=1" # headless import
open "cra://dismiss" # close sheets, command bar, find bar
Links from other apps and browsers only reach commandbar, dismiss and open with an
http(s) URL; pages inside Cra reach none of them. The rest (action, navigate, key,
import, debug) run scripts and DevTools Protocol commands, so they need either
defaults write dk.kildahl.cra scriptingURLs -bool YES or a test instance's
CRA_COMMAND_FILE. See AppDelegate.isUserFacing before adding a host.
Rendering calibration
open "cra://debug?lift=0&liftInactive=0.75&alpha=1&material=13&state=follows&appearance=dark"
changes the vibrancy parameters live (see Sources/Cra/UI/Tuning.swift). material is the
raw NSVisualEffectView.Material value, alpha scales the gradient opacity.
Brand assets
Logo sources are in brand/ (see brand/README.md). resources/brand/*.png are WebKit
renders of them (so the multiply blends survive) used by BrandMark, and
resources/AppIcon.icns is built from brand/cra-segments-icon.svg (render at 1024 px,
iconutil). The marketing site lives in a separate private repository.
Releasing
scripts/release.sh builds, signs with a Developer ID, notarizes, and packages a DMG and
zip into build/dist. Pushing a v* tag runs the same through GitHub Actions and
publishes a release. Releases with UI changes get short clips on the release notes first
(scripts/clips, .claude/skills/release-clips). See release.md for the
one-time certificate setup.