Desktop Local surface

What it is

The Local tab is the part of the desktop app that is not the web app in a window. It knows about this machine: the DAW projects on its disk, the folders it watches, what has synced to it, and the audio it can play without a network.

Using it

The tabs across the top are System, App, Organisations, Admin and Links, centered like browser tabs. Teams stay on the left. The Aden mark there shows connection: it floats and spins while the backend session is coming up, then a green dot when you are connected. The speaker on the right shows what is playing on hover.

Windows: the caption buttons (minimize, maximize, close) sit on the far right. Close quits Aden. On macOS, close hides to the Dock and the menu bar.

Two surfaces side by side: on Links, the split control sits next to back, refresh and home. Any surface can pair with any other.

The window is a frame with the page inside it as a card. The rail on the left holds System, Aden and Links (hover one for its name), with search and ••• at its foot. Search opens the web app's palette on Aden and the desktop palette elsewhere. ••• is the app's own menu on every surface: update, App settings, language, sign out, and theme and zoom on its last line; a dot on it means an update is downloading or ready. The player sits at the bottom of System, inside the page; Aden and Links have none. The title bar keeps only the window buttons, the address controls and the sound indicator. On macOS the frame is translucent: the desktop shows through it, blurred, in light and dark mode. Frame opacity in App settings sets how much colour lies over that blur, from none to solid. Rail density in App settings makes the rail compact (48px, 32px buttons), default (56px, 40px) or roomy (64px, 44px); every rail button, pins included, follows it.

When Aden can't be reached, an offline button appears on the rail above Search, with an amber dot. Its tooltip says what still works (tracks on this Mac, synced files, cloud lists as last seen); clicking it checks again, and it goes away as soon as Aden answers.

Press ⌘S (Ctrl+S on Windows and Linux) for full page: the frame slides away and the page fills the window. Move the pointer to an edge to bring one piece back over the page: the top for the title bar and window buttons, the left for the rail. ⌘S again, or "Toggle full page" in ⌘K, brings the frame back. The choice is remembered.

The System and Links sidebars tuck away to a narrow rail: swipe left over one with two fingers, or right anywhere to bring it back. The edge follows your fingers and settles open or shut from where you let go and how fast. Inside the desktop app the Aden web app draws no card of its own, since the frame already holds the page in one. It takes the app's light or dark mode as soon as it loads: the page announces itself (aden-ready) once it is listening, and the shell answers with its theme.

The team switcher lives at the top of the sidebar on every surface: the web app's own on Aden, the shell's on System and Links, at the same inset and height, so switching surfaces moves nothing. Inside the desktop app the web sidebars skip their logo and search row, which the rail already has. Back and forward sit beside the traffic lights. The middle of the title bar is one field: on Aden and Links pages it shows the address, opens what you type if it is an address and searches anything else; on System it opens search (⌘K).

The sidebar shows Playlists as its own section under the pages, and hides it on Samples, where the folder browser already fills that column. The Collections block (Projects, Recent, Playlists) is hidden for now: Home lists projects and recent files. When shown, it folds from its header, and the cog beside it chooses whether every chip carries a label or only the open one, and compact or roomy rows. Projects starts with Add project, the same DAW picker as the Home tile. Beside the search box sits the filter, the same popover the web sidebar puts over its tracks: sorting, kind, DAW, file type, when it last changed and which folder it sits in, each a headed section with its own reset, and Clear all in the footer. DAWs and project file types show the installed DAW's own icon, or its drawn logo when it is not on this Mac.

A project in the sidebar is the same as on Home: right click for the same actions (components/projects/ProjectActions.tsx renders both), the cloud glyph when it belongs to a track, and hidden or other-team projects left out.

A bar at the bottom shows what is playing on every tab, with the queue behind its queue button. It is the web app's bar, the same components, not a copy of them: @aden/ui/components/player-bar holds the layout and the transport and @aden/ui/components/player-queue-panel holds the queue, and each app passes in what differs. The chevron opens the full player as a drawer above the bar, on every tab, capped to about two thirds of the window so a video never pushes the projects and recents off the screen; the same chevron closes it. It is not a second player, only a view of the one that owns the audio.

Home opens on your projects, searchable from the box beside the section with the same filter popover next to it. Recent carries it too, next to its Synced toggle: it replaced the strip of format chips, which could only ever filter by extension. A file's row menu has Add to Aden as a submenu: new version of a track, track documents, album documents (each a picker with covers, the web's own picker rows), or team files straight away. Each tile is a real project file with the icon Finder gives it, so an .flp and an .als are told apart at a glance. Click one to open it in its DAW.

The filter itself is components/shell/LocalFilterDropdown.tsx over lib/local-filters.ts (one state shape, one applyLocalFilters), built from @aden/ui/components/filter-sections: the section heading, grid item, choice grid and Clear all the web's track, album and playlist filters already use. Those primitives moved out of apps/web/components/entity-list/ so both apps render the one implementation; the web file now only supplies its translations.

• New project is the first tile. It launches an app on an empty session: every DAW opens on a blank project when started with no document, so starting one is launching the app. With one music app installed it goes straight there; with several it opens a searchable list showing each app's own icon, and Choose an app… at the bottom takes anything the scan missed.
• The gear holds everything about how the list is built: Show as (rows or tiles) and Where to look (across the machine by default, most recent first, or one folder you pick). Search sits beside the heading it filters, not at the far edge.
• A zipped session is a project. A .zip holding an .flp, an .als or any other session file is listed under the name of the file inside it, so the producer who zips everything before sending it still sees their work. A zip of samples is not listed. Opening one shows it in Finder or Explorer rather than unpacking it.
• A project open in your DAW right now carries a green dot and "Open", on Home and in the sidebar.
• A project's menu (hover a tile) opens it in its DAW, shows it in Finder, starts or links a track, or sends it as a transfer.
  • Start track (projects not linked yet) puts the project's card at the front of Suggested and scrolls to it: the same card an export gets, with the title, status, tags, audio export and folder choice.
  • Link to a track opens Files, Folders with the track picker for the project's folder already open. It used to land on Files, Projects, where the picker never mounted, so nothing appeared.
  • Send as a transfer zips the project's folder and gives you a link that expires in 30 days. It shows the folder's file count first, and when that count says the folder holds little more than the project file it names your DAW's collect-all export ("File > Collect All and Save" and so on) and tells you to run that first. A project file points at its audio by absolute path: zip it alone and it opens on the other machine with everything missing.

The sidebar lists your last few projects under the navigation, the way the web app lists tracks in its own. Clicking one opens it in its DAW.

Recent is under the projects, and it is everything: bounces, sessions, zips, whatever moved on this disk lately. Other files join when their name says they belong to a release: a royalty statement, a banner, a cover or the music video, so you can add them to a track from the same list. A bounce, the session it came from and the zip you sent a collaborator are one afternoon's work, so they are one list. Synced narrows it to the folders Aden syncs (the team folder and every track folder), which is "what changed in the work I share"; the chips filter it by format, several at a time. Clicking a row plays it (or opens it, for a session), and the artwork is the play button: the icon crossfades in on hover where your eye already is. Add to queue and Show in Finder sit at the end of the row, and right-clicking gives the same actions in words plus Copy path. Its gear holds Show as (rows or columns) and which folders it reads: left alone it reads Music, Downloads and Desktop, which for most people is every audio file on the machine and almost none of it theirs. Add a folder and it reads that one instead; add one under Skip to keep a sample library or a cloud mirror out.

The full player lives in the bar's drawer, not on Home: cover on the left, then the title, the actions and the waveform in one column beside it. A/B and the loudness readout sit in the top-right rail, and the transport is one symmetrical row — shuffle, previous, back 15s, play, forward 15s, next, repeat. Clicking the waveform plays from there, even on a launch where nothing has loaded yet.

Hovering the loudness readout explains M, S and I; clicking it opens EQ, speed, pitch and mono. That is the web player's own panel, not a copy: the desktop hands its audio element to the shared audio store, so both surfaces run the same graph and the same controls.

It has no History or Browse tabs any more: history was a list nobody opened, and Browse pointed at a folder that Recent now covers. The queue is not here either: it lives in the bottom bar, the way it does on the web.

Files is everything about this team on this machine, and it asks one question first. Sync and Files used to be two tabs answering the same question: Sync owned the folder and the tracks, Files owned the list of files inside it, and neither made sense without the other.

Until the team has a folder on this Mac, that question is the only thing on the page: pick a folder, and Aden keeps this team's projects there and pushes your changes back as you save. Everything below it needs that folder to exist, so nothing below it is shown yet.

Once it is set, one card holds the folder: the path (click it to open in Finder), what the folder holds (bytes and files, measured by walking it, per team), how many track folders are linked to that team, when it last synced, and what is being synced. The size is the folder as it is on disk, not the sum of what sync downloaded: that number ignored files pulled by another Mac, put there by hand, or linked in place, and read as 47 MB for a folder holding a 795 MB project. main/folder-size.ts walks it (no symlinks, depth 24, 200,000 files, cached a minute, dropped when a sync run writes), behind sync_get_folder_size. A track card's own "126 files, 795 MB in Aden" is the cloud total from track_projects, which is why it says in Aden. Sync now sits in the same card, and its dropdown holds everything else about that folder: what gets synced, Live sync, Sync settings, Change folder and Stop syncing this folder. It used to be a folder row, a separate controls row and a status line under that: three places to look for one thing, with an Open button next to a path people already read as a link.

Under it, two tabs, because tracks and files are two lists of the same folder and stacking them meant scrolling a screen of files to reach the board:

• Tracks is the board and the linked folders, with the same Filter and Display controls the web app's entity lists have: multi-select status, DAW and on-this-Mac facets beside a Display popover for the view and the sort. It was one single-value status select buried inside Display. Layouts are Recent (one row per track in date sections, the default), Board, List and Table. Display toggles which properties show (status, on this Mac, BPM and key, files, size, DAW, updated) and groups Board and List by status or by On this Mac vs In the cloud; the choices persist per Mac. Every cover is a play button: the newest audio in the track's folder when it is on this Mac, otherwise its final or latest version streamed from Aden. A track with audio in Aden also gets a visible play button beside its cover (from the audio_url the track list already returns), since the hover alone hid it. A streamed version draws the waveform the API stores with it, as on mobile, instead of downloading the file to decode it. R2's CORS rule does not list the desktop's origins, so src/main/storage-cors.ts adds Access-Control-Allow-Origin to R2 GET responses in the app window and the player loads them with crossOrigin. Without it the EQ/LUFS graph heard silence and streamed versions played muted. Sync to this Mac on a card makes that track a folder inside the team folder, pulls down whatever the cloud already has for it, and pushes what you save in it from then on; the card then reads On this Mac and a toast says how many files landed. Pressing it again stops syncing and unlinks the folder, leaving the files. Add file copies files into that folder, and is only offered once the track has one. Each card says whether the track is on this device: a green dot with the folder's name, or "In the cloud only". The status is not repeated on the card, because the column it sits in is the status.

  One control answers that question, and it reads both halves of "local": the folder mapping the main process owns (track_folder_list) and the projects watcher this screen keeps in localStorage. The card used to carry two, a cloud-download icon by the title driven by the first and a button driven by the second, so a track with a linked folder showed a green check beside a "Sync to this Mac" button, and one with the watcher on but no folder showed a cloud icon beside "Synced". Open a track and Compare is there: pick two versions and hear them against each other, the same panel, picker, meters and audio engine the web app uses. Track folders below it are folders you already have, each linked to one track. Add folder picks one and then asks which track it is, with No track yet, create one in the same dialog. Dropping an .flp or .als on the app asks the same question.

• Files is everything Aden has for this team, whether or not it is on this Mac. A monitor icon means the file is here, a cloud icon means it is not. Search it, filter to On this Mac or In the cloud, and each row can be downloaded, shown in Finder, or removed from the disk (the cloud copy stays). Recently synced, Watched folders and Storage on this device are collapsed under it.

Match local exports to tracks, the one-off import that turns a folder of MP3/WAV exports into final versions, lives in Settings under Import, and in the command palette.

Samples is the sample libraries (see the sample-libraries spec). AI DAW is the local MCP bridge.

Scale the app with Cmd/Ctrl and +, - or 0, or from Zoom in the team switcher. It scales every Aden window and survives a restart.