edit | blame | history | raw

CODEGRAPH

Stable Modules

  • App entry and overlay state: src/Apptag/ContentView.swift
  • Reads user defaults for AppGrid display, theme, tag navigation, usage tips, and hotkeys.
  • Owns the AppGrid full-window background rendering.
  • Reuses the last complete AppLibrary snapshot before showing startup loading UI.
  • Calls AppGridCollectionView for AppKit grid rendering.

  • App library snapshot assembly: src/Apptag/AppLibraryController.swift

  • Scans apps, reconciles tags, runs SmartStart when needed, and assembles AppGrid/Quick Search snapshots.
  • Keeps the most recent in-process AppLibrarySnapshot so newly-created overlay views can render immediately while background refresh catches up.

  • AppGrid collection renderer: src/Apptag/AppGridCollectionView.swift

  • AppKit NSCollectionView implementation for grouped app layout, drag/drop, app ordering, bubbles, and the native split teaching-banner usage tips overlay.
  • Should not own full-screen AppGrid theme gradients; it receives theme only for derived glass readability.

  • AppGrid theme model: src/Apptag/AppGridTheme.swift

  • Central source for theme IDs, localization keys, preview swatches, full-screen background gradients, derived glass tone, and edit-mode contrast tokens.
  • Persistent key: appGridThemeID.

  • Settings surface: src/Apptag/PreferencesView.swift

  • Custom SwiftUI settings tabs.
  • Theme tab writes only appGridThemeID; it must not mutate tags, app ordering, or category data.
  • Can be opened with an initial target tab from AppKit/overlay notifications.

  • Defaults and migrations: src/Apptag/AppDefaults.swift

  • Registers first-run defaults.
  • Migrates legacy useDarkAppGrid=true to appGridThemeID=deepBlue when no new theme key exists.

  • Localization: src/Apptag/Localization/*.json

  • 29 language JSON files.
  • New user-visible settings keys must be present in all files.

QA Entrypoints

  • src/Scripts/theme_settings_qa.sh
  • Verifies 8 theme cases, Theme tab, legacy dark-grid UI removal, AppGrid-only rendering boundary, edit-mode default-theme override, migration path, and 29-language keys.
  • src/Scripts/appgrid_startup_loading_qa.sh
  • Verifies AppGrid startup loading uses last-snapshot reuse and delayed spinner instead of immediately exposing empty-state loading.
  • src/Scripts/macos14_availability_typecheck_qa.sh
  • Typechecks for macOS 14.0 compatibility.
  • src/Scripts/macos14_build_metadata_qa.sh
  • Verifies build metadata and deployment target.
  • src/Scripts/usage_tips_qa.sh
  • Verifies native usage tips overlay, split teaching-banner layout, theme-aware accent/readability, click-through protection, close action, ordered-list details, and 29-language coverage.
  • src/Scripts/tag_navigation_hover_scroll_qa.sh
  • Verifies tag hover scroll semantics remain guarded.
  • src/Scripts/tag_double_click_preferences_qa.sh
  • Verifies double-clicking a tag navigation item opens Preferences on the Tags tab while preserving single-click activation, hover scroll, and long-press reorder wiring.

Protected Behavior

  • Theme changes are visual preferences and must not change tag data, app ordering, notes, SmartStart/category scheme, quick search, drag/drop behavior, or import/export data.
  • AppGrid startup and repeated overlay creation must not immediately show a spinner just because a new ContentView starts with allApps.isEmpty; it should first reuse the last complete in-process snapshot and only show loading after a short delay if no snapshot is available.
  • Editing mode uses a temporary runtime theme override: regardless of the stored appGridThemeID, editing renders as the default light glass AppGrid and restores the stored theme when edit mode exits.
  • Individual AppGrid containers must remain a consistent translucent glass surface. They may use a derived light/dark glass tone for readability, but must not receive per-theme internal gradients.
  • Edit mode controls must use the runtime rendered theme, not the stored theme, so editing stays visually identical to the default light AppGrid.
  • Deep Blue and Black use dark glass. Bright Pink, Purple, Green, Blue, and Colorful themes use light glass to keep the theme bright and readable.
  • The default theme preserves the original light AppGrid background.
  • Legacy users with useDarkAppGrid=true must land on the deepBlue theme.
  • Tag navigation single-click must keep immediate scroll behavior. Hover must keep guarded auto-scroll. Long-press must keep tag reorder behavior. Double-click may open Preferences on the Tags tab but must not replace those existing behaviors.
  • Usage tips must remain a native AppKit overlay, not SwiftUI. The bottom teaching banner must consume its own click region so it never opens underlying apps; only arrow hit regions change pages.
  • Usage tips title/detail text must remain readable across the default, dark, and bright App Grid themes; all visible usage-tip copy must stay complete across 29 localization files.

Last updated: 2026-06-25, usage tips teaching banner visual optimization.