메뉴
Load before building or modifying any SwiftUI view. Ensemble UI/UX conventions: navigation behavior, tab management, visual design specs, loading/error states, performance optimization, iOS 15 compatibility, DetailLoader pattern.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
Canonical Ensemble behavior policy router. Load before changing app behavior, playback, queue, offline/connectivity, downloads, sync/refresh, mutations, platform UI behavior, or verification expectations; update the relevant policy reference when implementation changes or clarifies behavior.
Plex Media Server API reference. Load when implementing or debugging Plex API integration.
Load before designing features, adding services, or touching multiple packages. Compact ownership, dependency, and subsystem rules for Ensemble.
Load when adding a ViewModel, view, CoreData entity, hub, music source, playlist mutation, or sync trigger. Step-by-step recipes with code patterns.
Load when locating files, adding files, or checking package ownership. Compact map plus discovery commands; use rg for live file lists.
Active Ensemble limitations, watchlist items, and fragile areas. Use when investigating bugs, planning work, or touching known-risk behavior.
| name | ui-conventions |
| description | Load before building or modifying any SwiftUI view. Ensemble UI/UX conventions: navigation behavior, tab management, visual design specs, loading/error states, performance optimization, iOS 15 compatibility, DetailLoader pattern. |
These are core design decisions that must be maintained throughout the app.
MainTabView.handleTabTap() for referenceUISelectionFeedbackGeneratorList editing for visible tab reordering and simple tap actions for add/remove. Do not reintroduce custom row-frame preference keys, section drop delegates, or insertion-index drag math for tab sorting unless native list editing is proven insufficient.NavigationCoordinator.visibleTabs synced from MainTabView for fallback logicRootView creates the NavigationCoordinator for that scene/window and injects it with .environmentObject(...). Do not read DependencyContainer.shared.navigationCoordinator from screen or component code for user-driven navigation, or multiple iPad/macOS windows will mirror each other's pushes..inline on top-level browse/search screens; let the title appear large at rest and collapse naturally as content scrolls..searchable only while that tab is the active root screen, except for the short native tab handoff window where outgoing Search must keep its search controller mounted to avoid relayout before the destination appears. Collapse/remove search chrome before pushing detail or after switching away so stale UISearchController state doesn't leak padding, keyboard state, or toolbar behavior into pushed views or other tabs. Use SwiftUI's dismissSearch environment action to collapse search; do not force keyboard dismissal with UIApplication.sendAction(...).ensemble://media/v1/... links resolve through EnsemblePermalinkResolver into typed scene-local destinations and never auto-play. Song destinations open the matched album; failed matches route to Search with a toast.pendingNavigation to defer until sheet dismisses. RootView owns the Now Playing presenter dismissal handoff; do not add screen-local asyncAfter timers in MainTabView or SidebarView to wait for the sheet animation.visibleTabs.first ?? .homeNavigationCoordinator.pathSnapshot(for:), setPath(_:for:), and the EnsembleUI pathBinding(for:) extension instead of adding new per-tab switch statements in root views. Use NavigationDestinationFactory for tab/destination view routing, and use NavigationCoordinator.targetTab(for:) plus SidebarSelection.selection(for:fallback:) for destination-to-root selection mapping.NavigationStack with NavigationLink(value:) and typed pathsNestedNavigationLink only as the root NavigationView bridge for coordinator-driven entry into a tab or hidden More destination. Media browse/detail relationship pushes should still go through NavigationCoordinator.routeLink(to:) so they append to the current root or More stack; purely local utility drill-ins can use native NavigationLink(destination:).NestedNavigationLink mounted even when its path is empty. If the hidden link is inserted only after the coordinator path becomes non-empty, SwiftUI sees an already-active link and detail pushes cut instead of animating.NavigationCoordinator.routeLink(to:) instead of local #available branches or inline destination closures. routeLink(to:) should push through the scene-local coordinator path, not nested NavigationLink(value:), so links inside More-tab destinations can keep drilling into albums, artists, playlists, and related items. When the caller already has a concrete Album, Artist, or Playlist, route to .albumDetail(...), .artistDetail(...), or .playlistDetail(...) instead of ID-only loaders. Context menu navigation actions should use routeFromMenu(to:) or navigateFromMenu(to:) so path updates happen after native menu dismissal.NavigationCoordinator.routeLink(to:) without an explicit in: tab unless they are intentionally leaving the current stack. This keeps More-tab drill-in and iOS 15 recursive fallback navigation on the same stack as the current surface.@available(iOS 16.0, *) checks.miniPlayerBottomSpacing(...) from View+Extensions.swift instead of ad-hoc per-screen spacer blocksTrackListLayoutMetrics for standard row height, leading insets, divider alignment/color, native separator color, and default mini-player clearance instead of repeating 68/54/16/140/70/52 or raw separator alpha across screens. Native table rows and compact SwiftUI track/search rows should share these metrics so Artist pages, Media Detail pages, and Songs/Search rows do not drift.TrackListLayoutMetrics.rowInterItemSpacing and rowHorizontalPadding for compact sheet rows, drag-order surfaces, and lightweight action pickers instead of introducing standalone 12/16 spacing constantsTrackListLayoutMetrics spacing tokens unless the layout truly needs its own card-scale rhythm.page swipes so panels are complete before selection commits, while keeping high-frequency playback/lyrics work scoped to the active card or explicitly always-visible viewport cards.NowPlayingPanelCard / NowPlayingDetailPanel instead of instantiating those cards directly per layout. Single-panel, carousel, wide, and external-display layouts may own different containers, pickers, and sizing, but card selection and per-card flags should stay centralized so visual/control changes land once..task(id:) cancellation for state-owned delayed indicators such as short loading spinners. Do not store manual Task properties just to cancel/restart view-local loading-state swaps.ScrollView/TabView native gesture arbitration. Native scroll phase observation may drive view-only affordances such as temporarily disabling lyric blur and recentering after user-driven scroll; on older OS versions without native scroll-phase support, keep timed lyrics unblurred instead of adding detector shims. Do not reintroduce UIKit/AppKit drag or scroll-wheel detector probes, paging-pan failure wiring, competing SwiftUI drag recognizers, offset-reader scroll detection, or ViewModel-level timed scroll suppression unless a current simulator repro proves native behavior is broken and the smaller owner-scoped fix is documented..task(id:) sequences keyed by measured text/container width. Do not build recursive DispatchQueue.main.asyncAfter chains for view-owned animation loops.TrackListLayoutMetrics.detailHorizontalPadding for downloads/settings/manual utility rows instead of hardcoding fresh edge values.MediaTrackList in an extra outer horizontal padding layer for normal full-width track lists; the rows already own their horizontal inset through TrackListLayoutMetricsTrackListLayoutMetrics.rowInterItemSpacing and rowHorizontalPadding for repeated Play/Shuffle-style button rows and lightweight status banners in media/detail screensTrackRowInteractionModel to resolve per-track context-menu availability, recent-playlist gating, and favorite state for native table paths and compact standalone track rows. UIKit table menus should be built through NativeMediaTableActionBuilder; keep row swipes owned by MediaTrackList/native table delegates so card and shelf interfaces do not inherit row gestures.TextField alert, while profile-name, playlist creation, and album/favorites/artists/songs filters use normal .sheet presentation.keyboardSafeEditorPresentation(...) full-screen workaround for playlist rename or other short text-input flows..sheet flows and reuse TextInputView for the keyboard-heavy text field. Album, artist, and detail context menus should keep metadata sheet state beside their add-to-playlist/delete presenters. Do not route these editors through root presenters or hide/restore parent navigation/search chrome around them; interactive sheet dismissal with a focused keyboard can otherwise race UIKit chrome updates and recreate the iOS 26 feedback loop.auxiliaryPresentationSheets(...) and addAccountPresentationSheet() from the active root shell (MainTabView or SidebarView). Do not duplicate profile/download/add-account .sheet wiring per root shell or add onDismiss handlers that race the binding setter's native dismissal path.MacAuxiliaryWindowScaffold at about 420pt max width, and compose macOS content with EnsembleUtilityScreenScaffold/EnsembleUtilityCardSection instead of raw List rows when the screen is menu-like.TextInputView, and short utility sheets should use .nativeSheetNavigationContainer() for the iOS 16+/macOS 13+ NavigationStack path plus the iOS 15/macOS 12 NavigationView fallback. Do not reintroduce custom sheet headers or full-screen keyboard presenters unless a current simulator/hardware repro proves native sheet dismissal is broken.onDismiss; do not use arbitrary DispatchQueue.main.asyncAfter delays to wait for sheet teardown.UIApplication.sendEvent swizzles or GCKeyboard monitors for hardware shortcuts. Use native SwiftUI commands/keyboard shortcuts where the platform supports them, and leave iOS text input events on the responder chain.NestedNavigationLink Pattern (in MainTabView.swift):
struct NestedNavigationLink: View {
let path: [NavigationCoordinator.Destination]
let destinationBuilder: (NavigationCoordinator.Destination) -> AnyView
var body: some View {
if let first = path.first {
NavigationLink(destination: destinationBuilder(first)) {
EmptyView()
}
}
}
}
Feature Detection Pattern:
if #available(iOS 16.0, macOS 13.0, *) {
NavigationStack(path: $coordinator.homePath) { ... }
} else {
NavigationView {
NestedNavigationLink(path: coordinator.homePath) { ... }
}
}
TabView unless there's a compelling reasonMainTabView hides root chrome directly from active phone StageFlow landscape geometry. Do not reintroduce preference/notification bridges or delayed immersive-mode clear timers for this path..sidebarAdaptable tab view style when availableTrackListLayoutMetrics.rootMiniPlayerBottomLift(safeAreaBottom:tabBarBottomClearance:). Root geometry already ends at the safe-area boundary, so convert the native tab bar's window-bottom clearance into root coordinates by subtracting the bottom safe-area inset before adding the shared visual gap. With no tab bar, apply no additional root lift; the safe area is already preserved by the root frame. The floating MiniPlayer adds no transparent bottom padding of its own. The existing UIKit tab-container probe provides the tab-bar measurement across iOS 15 and newer. Use TrackListLayoutMetrics.detailMiniPlayerBottomLift(safeAreaBottom:) for registered split/detail panes. Do not add per-screen mini-player offsets or publish root mini-player geometry from pushed destination content. iPadOS mini-player placement should resolve from root-space coordinates centered on the active content viewport: root bounds when the sidebar is closed, and root bounds minus the frozen visible leading sidebar metric when the sidebar is open. Destination views and pushed detail content must not influence root mini-player placement; only sidebar visibility/width, root rotation/size, keyboard suppression, and Now Playing presentation should move or hide the persistent shell. A missing sidebar preference during a SwiftUI navigation render pass is not a sidebar-close signal; the split owner's explicit sidebar registration should switch between the root viewport and sidebar-adjusted content viewport. Keep the persistent root mini player in the RootSceneLayerHost overlay across iPhone, iPadOS, and macOS so it shares the root view's rotation and safe-area coordinate space. On iOS 26+, keep the persistent iPadOS root mini-player shell on native Liquid Glass, but do not give it a shared glass-effect identity for unrelated navigation; Now Playing handoff animation should remain explicit.UIDevice.current.userInterfaceIdiom == .phone), even though iPad shares os(iOS).MainTabView is on a StageFlow-capable tab. StageFlow-capable tabs pushed from More, such as Albums when hidden from the tab bar, must be detected from the More navigation path and handled by the same root policy.MainTabView owns StageFlow activation, root tab-bar/mini-player suppression, and the single rotation-support token. Browse screens consume EnvironmentValues.isStageFlowActive; they may hide local navigation/search chrome for StageFlow, but must not add per-screen tab-bar hiding, GeometryReader rotation detection, UIScreen height clamps, or stageFlowRotationSupport(...) calls.NSButton/NSMenu so the control does not show a pull-down chevron.Previous, Play/Pause, and Next) rather than relying on SF Symbol inference.NowPlayingWidePanelLayout, NowPlayingDetailPanel, and NowPlayingBackdrop; keep platform-specific code limited to presentation chrome such as dismissal, dark presentation, and the visualization consumer. Wide dual-pane Now Playing surfaces show one controls card on the left, so the right detail panel must not repeat lyrics transport controls or the track-title header.NowPlayingWidePanelLayout should center its constrained content for wide Now Playing surfaces such as the iPad sheet, macOS viewport, and AirPlay external display. Compact carousel callers keep their existing paging layout.NowPlayingBackdrop handles edge-to-edge artwork/aurora bleed. Do not put .windowResizability(.contentMinSize) on the main scene; SwiftUI can refit the root window to transient NPV content. RootView owns the main window's minimum frame and temporary window-toolbar suppression while viewport Now Playing is active. Prefer SwiftUI toolbar visibility APIs for macOS 13+; do not toggle NSToolbar.isVisible, force contentMinSize, or call NSWindow.setFrame from the viewport path. Do not add leaf-level titlebar or traffic-light padding constants, screen-level toolbar-item hiding, or fake full-window sheet shims.RootView owns software-keyboard visibility for root chrome. The mini player and its reserved clearance should be hidden while the software keyboard is visible, then fade back in after keyboard dismissal; leaf text-entry screens should not move or offset the mini player locally.NavigationSplitView as a stable two-column sidebar/detail shell on iPadOS/macOS. Their browse list + selected detail split lives inside the detail host so switching sections does not recreate the app sidebar or reset its scroll state.SidebarView, outside the section-owned split subtree, so selection survives detail host rebuilds, compact collapse/expand, and detail pushes.NSEvent monitors to swallow sidebar shortcuts, or walk NSSplitView/NSSplitViewController internals to force non-collapsible sidebar state.SettingsManager for one-off values. Cache specific settings such as accentColor in @State, listen to settingsManager.objectWillChange, and assign only when the projected value actually changes. Do not add a DispatchQueue.main.async hop around those snapshot updates; settings mutations are readable synchronously from the notification.PlaylistViewModel publishers should merge those publishers into one invalidation stream and keep one rebuild handler, so the cache-preservation policy stays centralized.LargeScreenPlaceholderView for empty right-pane states such as "Select an Artist".EnsembleToolbarLeadingSpacer before the action group. Do this as a toolbar-level alignment spacer, not as column-width math or screen-level toolbar delegate proxying.EnsembleBrowseToolbar for sort/filter/overflow action groups so iOS trailing placement and macOS search-spacer placement stay consistent. Use EnsembleBrowseFilterButton for active-filter badges instead of rebuilding the badge per screen.NSTrackingSeparatorToolbarItem. Do not proxy SwiftUI's private toolbar delegate from a screen-level view; that can collapse or drop existing SwiftUI toolbar items. If toolbar tracking is needed, introduce a dedicated macOS toolbar coordinator at the window/root split level.NSWindow resize constraints to the root scene/window shell. Do not add screen-level NSViewRepresentable bridges that hide every toolbar item or force contentMinSize while a leaf presentation is active.MediaDetailSurface / artworkBackedToolbarBleed() so Artist and album/playlist details share the same backdrop/chrome owner even when their header layouts differ..toolbarBackground(...) or native container behavior; NavigationBarAppearanceConfigurator and root-level UIKit appearance proxy mutation are iOS 15-only fallbacks and must remain no-ops on modern iOS so UIKit appearance mutation does not fight native chrome behavior.updateUIView / didMoveToWindow lifecycle ownership and keep retry state only after a native controller is found. Do not add next-runloop DispatchQueue.main.async probes to wait for tab-bar, mini-player inset, or iOS 15 navigation-bar hierarchy setup.NSViewRepresentable update/lifecycle/layout callbacks. Do not add DispatchQueue.main.asyncAfter retries to wait for toolbar or window attachment; keep the coordinator idempotent and let native view lifecycle retry.PinManager.$pinnedItems and derive state from the emitted snapshot. Do not add objectWillChange plus DispatchQueue.main.async delays to wait for the manager's stored value to catch up.SongsTrackListHost on large screens, with adaptive artist/album metadata columns when width allows. iPad hosts rows in MediaTrackList/UITableView; macOS hosts rows in the AppKit NSTableView backend. Keep row actions resolved through TrackRowInteractionModel so UIKit/AppKit behavior stays aligned. Do not use TrackSwipeContainer or reintroduce a column-customization table for Songs unless explicitly requested.NativeTrackListConfiguration / NativeTrackListSection when they need the shared host. Keep direct MediaTrackList use for compact iPhone or self-scrolling table-header cases where the UIKit table owns the header/footer.MediaTrackList/QueueTableView UIKit tables, MacNativeTrackTableView AppKit tables, AirPlayButton, Metal aurora surfaces, the global toast window, native share-sheet/AppKit menu hosts, iOS15TabBarHider, and the iOS 15 mini-player safe-area inset bridge. These should be simplified only when replacing them with an equivalent native owner, not with SwiftUI gesture/layout shims.updateUIView / updateNSView through main-queue hops.trackListRuntimeObservation(activeDownloadRatingKeys:availabilityGeneration:). Do not duplicate the OfflineDownloadService.$activeDownloadRatingKeys + TrackAvailabilityResolver.$availabilityGeneration onReceive pair in each large view.nowPlayingTrackListObservation(...) and keep only projected @State values such as current track id or recent playlist title/id. Do not observe the full NowPlayingViewModel from these large surfaces..measuredWidth(onChange:) and keep a guarded state assignment in the caller, rather than duplicating background GeometryReader blocks.init, initialize local @State projections from those managers, and subscribe to focused publishers instead of repeatedly reaching into DependencyContainer.shared from body modifiers.NotificationCenter events should fan them into a typed event publisher and route through one handler, so payload parsing, toast cleanup, and cached-list refresh policy do not drift across receivers..task(id:) with SwiftUI cancellation, then assign guarded @State results. Do not add manual GCD token counters or DispatchQueue.main.async hops to wait for stale layout/search computations to settle.SyncCoordinator.isOffline, with guarded @State updates instead of observing the whole singleton object.lessThanOrEqual constraints, or mixed title/artist/album lengths, duration strings, or download state will shift columns per row.MediaTrackList on iOS/iPadOS and SongsTrackListHost/AppKit table host on macOS) instead of reintroducing TrackListView or hand-built compact track rows, so wide metadata columns, context menus, and native row actions stay aligned.TrackRow/TrackSwipeContainer stack for compact iPhone lists. Compact Songs should keep its current MediaTrackList path with genre chips, native row swipe actions, and existing mini-player spacing.GenreFilterHeader as a sticky top safeAreaInset on SongsTrackListHost, with a matching native table topContentInset, instead of wrapping the table in a parent VStack. This keeps genre chips pinned during normal row scrolling, lets the navigation/search chrome collapse from the native table's scroll, lets the chip inset follow the table's top rubber-band stretch, and keeps section headers below the chips while the native table owns rows/actions. macOS Songs should embed genre chips as native table header content so they scroll away with the songs list instead of staying pinned above the table. Let the compact MediaTrackList extend through the top and bottom safe-area container edges so content can bleed behind toolbar and tab-bar chrome while the table's own bottom inset keeps final rows reachable. Keep compact indexed Songs' ScrollIndex overlay outside that bleeding table so it stays aligned to the same safe-area viewport and default bottom-chrome placement as Albums/Artists. Compact indexed Songs should keep one MediaTrackList as the row owner and drive section jumps through that overlay. Keep its native table section headers visually aligned with EnsembleBrowseSectionHeader. Do not enable UITableView's built-in section index for this surface; on iOS 26 it anchors to the table's adjusted frame, draws a tracking background, and can sit below floating headers..refreshable { ... } directly to the native vertical scroll owner for every visible content state, including empty/error states that mention pull-to-refresh. Also attach .refreshCommand { ... } with the default "Refresh" title, which publishes through the scene-focused refresh action so macOS View > Refresh and iPadOS keyboard/menu commands invoke the active screen's same async refresh action without requiring a child control to hold focus.loadHubs() unconditionally from HomeView.task.MediaTrackList, MacNativeTrackTableView, AirPlay, Metal, toast window, iOS 15 tab/mini-player bridges, native share/menu hosts). Treat any new safe-area compensation, delayed layout task, custom scroll detector, or root-chrome mutation as suspect until a current simulator or macOS repro proves native behavior is broken.AuroraVisualizationView should use the shared MetalAuroraSurface renderer when Metal is available, with the Canvas path kept as the compatibility fallback.activeContentMaxWidth when the caller provides it.AuroraVisualizationView with .rootBackdrop in RootSceneLayerHost. Do not move the live aurora into only the detail column or create a second root aurora renderer.Detail-surface playback actions use native Liquid Glass button styles on iOS 26+/macOS 26+ with explicit .buttonBorderShape(.capsule) so Play/Shuffle/Radio keep capsule geometry and native press feedback across platforms. Primary actions such as Play use accent-tinted interactive glass plus the native tint environment with white foreground text/icons on both iOS and macOS. Secondary actions such as Shuffle and Radio use neutral interactive glass. Now Playing's primary play/pause control uses neutral native interactive glass with .buttonBorderShape(.circle) and primary foreground, so it keeps press feedback without using the app accent color. Keep older OS fallbacks routed through the shared action-row owners.
Disabled detail-surface playback action labels should use primary text color and let the native disabled state dim the control. Do not force onAccent/white foreground on disabled primary actions, because macOS glass turns the disabled fill neutral gray.
Do not wrap Liquid Glass control groups in .chromelessMediaControlButton() on macOS. That helper applies .buttonStyle(.plain) and will suppress native glass rendering and press interaction. Apply borderless/plain styling only to the specific non-glass controls that need it.
Buttons that open a sheet or modal must end with an ellipsis (…) — this is the Apple HIG convention signalling that the action requires further input before completing:
Button("Add to Playlist…") { showingPlaylistSheet = true }
Button("Rename…") { showingRenameSheet = true }
Button("Create Playlist…") { showingCreateSheet = true }
Button("Play") { play() }
Button("Remove", role: .destructive) { remove() }
Use the actual ellipsis character … (U+2026), not three dots ....
ProfileToolbarButton (28×28pt circular profile image) is owned by MainTabView and attached once to each visible tab root-content wrapper plus the root More wrapper. On iOS 16+, keep it mounted at that root owner instead of toggling it from navigation path emptiness, so it returns with the native root toolbar during pops; iOS 15 may still path-gate the fallback NavigationView item to avoid inherited toolbar leakage. Place it after other root actions in the trailing stack. Do not add it inside individual screens, or it will remount during pop transitions and can leak into pushed More destinations.ProfileToolbarButton placed in sidebar toolbar, replacing the previous gear iconProfileView via AuxiliaryPresentation.profile (formerly .settings)NavigationCoordinator.openProfileFromActiveScene(fallback:); RootView registers its window-scoped coordinator as the active auxiliary command coordinator on appear/scene activation so ⌘, opens Profile in the active scene instead of the legacy shared coordinator.AVRoutePickerView for AirPlay, MPRemoteCommandCenter for lock screen)EnsemblePlatformFeaturePolicy when the same feature can render natively in multiple ways.EnsembleCore client. Watch UI should stay compact, text-first, and shallow: pins first on Home, then library category rows (Albums, Artists, Playlists, Recently Added), then detail track lists. Source settings should use a lightweight account → server → library toggle list plus an explicit selected-library sync action, not the full iOS/macOS profile UI. Keep Now Playing as a persistent top-right toolbar button and let it switch between watch-local playback and phone remote control. Do not import EnsembleUI or the iOS playback dependency graph.ToolbarItemPlacement.topBarTrailing). Do not use .primaryAction for this, because Apple places watchOS primary actions beneath the navigation bar and reveals them by scrolling. For watchOS 8/9 compatibility, use the local watchNowPlayingToolbar() fallback overlay in WatchRootView.installGlobalToastWindow(toastCenter:) in EnsembleAppToastHostView in individual screens; call deps.toastCenter.show(...) and let the global host render itUIWindow to solve ordinary root layout issues.didMoveToWindow lifecycle. Do not add DispatchQueue.main.async retries to wait for windowScene; the probe view owns scene attachment.SettingsManager.trackSwipeLayout (2 leading slots, 2 trailing slots)SettingsManager through their coordinator dependencies instead of reaching back into DependencyContainer.shared from delegate callbacks.Play Next, Play Last, Add to Playlist…, favorite toggleMediaTrackList swipe delegates for UIKit-backed track lists; do not bring back the deleted SwiftUI TrackSwipeContainer layer for new rows.MediaMenuCatalog. New track, album, artist, playlist, or merged-playlist menus should use the catalog for action order, section grouping, and destructive/editing gating; parent views should add only local handlers such as queue removal, MiniPlayer shuffle/repeat, or pinned unpin behavior.TrackActionsContextMenu for standalone SwiftUI track cards/menus outside native table rows, including feed cards, mini-player long-press menus, and queue/history fallback rows. It renders the shared catalog and lets the parent inject only navigation, playlist-picker presentation, or removal handlers.PlaylistActionPresentationHost and .playlistActionPresentation(request:nowPlayingVM:); menus and row actions should request the shared host instead of owning a local sheet payload.contextMenu on album/artist/playlist cards/rows to mirror detail-view actionsPlay, Shuffle, Play Next, Play Last, Radio, Add to Playlist…, Pin/UnpinPlay, Shuffle, Radio, Pin/UnpinPlay, Shuffle, Play Next, Play Last, Pin/Unpin, plus (for non-smart playlists) Rename…, Edit Playlist, DeletePlay, Shuffle, Play Next, Play Last, Pin/Unpin (non-destructive only)GenreFilterHeader for browse and detail genre filter rows. Do not place GenreChipBar directly in screens; the header owns the shared spacing and optional supplementary content such as merged-playlist source chips.pinnedViews, sticky overlays, or scroll-offset/safe-area shims.GlassEffectContainer content, not as padding outside the container, so the glass material is not clipped by the container or native table header. Do not add clipShape before glassEffect; pass the intended shape to glassEffect(_:in:) and let the native effect own its rendering bounds.EnsembleDesign for semantic UI values instead of introducing new raw literals for repeatable roles.EnsembleDesign.Color.accent / Color.accentColor so macOS follows Apple's accent policy: explicit System Settings accent colors override the app accent, while Multicolor lets the app-provided accent show. Do not pass SettingsManager.accentColor.color directly into ambient custom surfaces such as artwork washes, aurora, toast accents, utility row icons, sidebar adornments, or Now Playing chrome; reserve the stored setting for establishing the app accent environment and for actual accent picker swatches.TrackListLayoutMetrics for track rows and ArtworkCornerRadius for media artwork. These bridge into EnsembleDesign instead of being replaced by unrelated literals.EnsembleScaffold for larger adaptive patterns, such as shared empty/loading/error states.FilterSheet directly with native .sheet(...) on iPhone, iPadOS, and macOS. Do not reintroduce toolbar popovers or a custom filter presentation wrapper unless a current simulator repro proves native sheets are broken.LargeScreenBrowseSplitView with EnsembleScaffold.BrowseSplit.Configuration presets instead of repeating raw pane width, breakpoint, and resize-handle values per screen.LargeScreenBrowseSplitView owns browse-split width measurement and resize clamping. Keep its geometry local to the shell; child browse/detail screens should not add their own column-width math or forced max-height wrappers to correct split layout.LargeScreenBrowseSplitView collapses to a single inner pane, the selected detail must expose the shared back toolbar item that clears selection and returns to the browse list.EnsembleScaffold.DetailSurface and render through MediaDetailSurface helpers rather than inventing parallel detail surface constants.EnsembleScaffold.ArtistDetail.MacAuxiliaryWindowScaffold plus EnsembleScaffold.AuxiliaryWindow.Configuration presets so scene sizing and in-window content width stay in sync. For menu-like rows, use EnsembleAdaptiveUtilityScaffold when a screen needs iOS grouped-list and macOS card-section variants; use EnsembleUtilityScreenScaffold, EnsembleUtilityCardSection, EnsembleUtilityCardRow, and EnsembleUtilityCardDivider for the macOS card body so macOS avoids bordered List chrome. Filter sheets are an exception: keep FilterSheet on the native form/navigation sheet path across iPhone, iPadOS, and macOS instead of maintaining a separate macOS card shell. Current migrated utility examples include Logs, account detail, playlist create/edit, and text-input sheets.EnsembleStateScaffold. Use the default full-screen presentation for standalone states and .compactFooter for track-list/table-footer states.EnsembleLibraryEmptyStateScaffold instead of rebuilding that decision tree per screen.EnsembleStateActionLabel; account setup/authentication surfaces should use EnsembleScaffold.AccountSetup for PIN, card, row, and sheet sizing.EnsembleUtilitySectionHeader, EnsembleUtilityIcon, EnsembleUtilityInlineStatusRow, EnsembleUtilityTextStack, EnsembleUtilityRowLabel, and EnsembleScaffold.UtilityRow for section headers, icon lanes, thumbnail dimensions, nested status indentation, and compact text/status spacing.EnsembleBrowseToolbar; keep screen-owned actions as small button/menu helpers and let the scaffold own platform placement and spacing.EnsembleDetailToolbarLeadingSpacer; ordinary root/action toolbars should use EnsembleToolbarLeadingSpacer; large-screen browse detail panes are marked by LargeScreenBrowseSplitView so detail spacers are suppressed in dual-pane mode.EnsembleBrowseSectionHeader, and large-screen browse selection rows should use EnsembleScaffold.BrowseSelection / browseSelectionBackground(isSelected:). Native indexed track section headers should not paint their own background; leave the surrounding scroll/table surface visible so adjacent Liquid Glass and material effects are not visually clipped.EnsembleContentSectionHeader so title weight, color, and disclosure icons stay aligned across Feed, Search, and library sections.MediaActionLabel so icons, ellipses, and verb choices stay consistent across rows, cards, shelves, and detail surfaces.EnsembleDesign.Icon for app/navigation/action intent. Keep account/profile person symbols separate from artist/music symbols; artist-facing UI uses EnsembleDesign.Icon.artist/artists.EnsembleScaffold family (Sidebar, ScrollIndex, BrowseSplit, TrackSwipe, Waveform, Marquee, LogViewer, Toast, etc.) instead of local raw sizes.EnsembleScaffold.MediaCard and EnsembleScaffold.Chip; hub cards, playlist chips, merged-source chips, and download status chips should avoid local padding/font/radius literals unless the component has a documented one-off layout reason.EnsembleDesign.Material.Role or a documented local composition when the surface is too specialized, such as artwork-reactive mini-player backgrounds.EnsembleDesign.Material.Role so the semantic material policy stays centralized.EnsembleScaffold.MiniPlayer material role and corner-radius tokens. Keep separate semantic roles for mini-player and popover, but keep their fallback glass values aligned unless a deliberate material retune is requested.EnsembleDesign.Material.Role.sidebar.chromeBackgroundAlpha(auroraEnabled:), instead of local alpha literals.scripts/design_token_audit.sh as a non-blocking inventory before and after broad sweeps; it reports literal counts and the largest screen/component hotspots.EnsembleDesign.Effect / component bridge tokens for shared card/detail depth; StageFlow keeps its own tuned 3D shadows.BlurredArtworkBackground, but the blur must be bitmap-backed through ArtworkBlurRenderer or an explicit preBlurredImage; do not apply live SwiftUI .blur to large artwork layers.MediaDetailView and DownloadTargetDetailView must use ArtworkDetailBackground for the blurred header image so dark/light overlay behavior stays identical across detail screens. The wash should cross-fade artwork changes using EnsembleScaffold.DetailSurface.backgroundFadeDuration instead of swapping the blurred layer abruptly during navigation or cached artwork loads.MediaDetailSurface so MediaDetailView and DownloadTargetDetailView do not drift on spacing, wide-layout behavior, or light/dark presentation. Artwork-backed detail screens that need content to pass under translucent titlebar/toolbar chrome should set contentBleedsUnderTopChrome: true on MediaDetailSurface instead of adding local .ignoresSafeArea(edges: .top) modifiers.MediaDetailSurface.LoadingState or keep the shared header/table shell mounted with a compact footer loader during initial data fetches. On macOS, keep the detail root top-aligned, let AppKit own native table safe-area/content insets and clip views, use a bottom spacer row for mini-player clearance, let the AppKit backend use a deterministic wide-header row height, preload the initial album/playlist track snapshot in loaders before mounting the shared detail table, and publish virtual collection filtered snapshots before clearing their loading state so the first table layout already has its final rows; do not force the native table host itself to infinite height as a reflow workaround.artworkBackedToolbarBleed() from the surface owner so artwork and scrolling content can remain visible behind native translucent toolbar chrome. Collapsing toolbar material and iOS 26 top scroll-edge effects should follow the shared collapsing-title state; do not drive Artist detail toolbar visibility from a separate hero GeometryReader preference, because nested route lifetimes can leave transient hero measurements in the view tree after a push. On iOS 15, UIKit navigation-bar fallback probes must restore default appearance only when they still own the active bar appearance, so a source detail route cannot overwrite the destination route after a push settles. On macOS 26+, hide only the window-toolbar background and let ArtworkDetailBackground use backgroundExtensionEffect() so Liquid Glass can sample the artwork wash. On pre-26 macOS, leave the toolbar background native/visible for readability instead of forcing transparent chrome. Keep the main macOS window on the native titlebar style, keep AppKit scroll/clip views transparent, and do not add titlebar drag bridges or AppKit toolbar proxies to leaf views.SongsTrackListHost table footers on macOS. AppKit should own the native track table scroll; related album content in a table footer should be a non-scrolling adaptive grid, while horizontal shelves belong in SwiftUI-owned vertical scroll surfaces such as Feed.ScrollView, not on each horizontal shelf. Do not add outer DragGesture/scroll-idle detectors around the Feed ScrollView to defer hub updates, and do not attach foregroundScrollActivity() to horizontal hub shelves. Hidden Feed refreshes can wait until visibility returns, but visible hub snapshots should apply directly and let native scrolling own gesture arbitration. Do not force Feed's root ScrollView under the macOS toolbar with local safe-area padding; that clips the first row on launch.MediaDetailSurface.Header with MediaDetailSurface.SymbolArtwork so compact and large-screen headers inherit the same fluid resizing behavior as media detail screens.MediaDetailSurface.ActionLabel, repeated compact Play/Shuffle action strips should use MediaDetailSurface.ActionRow/PlaybackActionRow, wide metadata-column headers should use AdaptivePlaybackActionRow, nested compact sections should use CompactPlaybackActionRow, and icon-only actions such as Radio should use IconActionLabel so filled/accent, secondary action, spacing, disabled state, and chromeless button treatment stay aligned across media detail variants.EnsembleDesign.Typography for repeatable roles; only keep local font styles when the component has a documented rendering reason..lineLimit(1) or MarqueeText for auto-scrolling long titlesAlbumDetailLoader, ArtistDetailLoader, PlaylistDetailLoader for hub-to-detail navigationProgressView with descriptive textEnsembleStateScaffold with the relevant sync/setup prompt.Async loading wrappers for smooth hub-to-detail navigation:
Three loaders in EnsembleUI/Sources/Screens/Details/:
AlbumDetailLoader -- Loads full album data by ratingKeyArtistDetailLoader -- Loads full artist data by ratingKeyPlaylistDetailLoader -- Loads full playlist data by ratingKeyEach follows this pattern:
struct AlbumDetailLoader: View {
let albumId: String // ratingKey from HubItem
@State private var album: Album?
@State private var isLoading = true
@State private var error: Error?
var body: some View {
if let album = album {
AlbumDetailView(album: album, nowPlayingVM: nowPlayingVM)
} else if isLoading {
ProgressView() + "Loading album..."
} else if let error = error {
ErrorView(error: error)
} else {
"Album not found"
}
}
.task {
album = try await deps.libraryRepository.fetchAlbum(ratingKey: albumId)
}
}
Benefits:
LazyVGrid, LazyVStack, and lazy image loading via NukeCoreDataStack.performBackgroundTaskArtworkImageRequest.resized(...) so local cached originals and remote responses are downsampled before display instead of decoding full-size artwork during navigation or scrolling.