# Zyquo Atlas — Phase Plan & Progress ## Pre-Phase-0 — Provider key verification (done 2026-07-30) All 12 provider API keys were verified through Zyquo Cloud's Phase 7 harness — the exact production provider clients Atlas will port. **202/202 tests green** (live `/models` diff, chat completion on every catalog model, streaming, vision). Full table: `../zyquo-cloud/docs/VERIFICATION.md`. Keys live in `zyquo-cloud/.env.keys` (gitignored). Toolchain finding (2026-07-30): the CLT's default `MacOSX.sdk` → macOS 27.0 beta SDK, whose SwiftUI requires the `SwiftUIMacros` compiler plugin that CLT does not ship — every SwiftUI compile fails ("plugin for module 'SwiftUIMacros' not found"). Fix verified on a minimal repro: build with `SDKROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX26.5.sdk`. Atlas's Makefile must pin this SDKROOT for all builds (Phase 1). ## Phase 0 — Research (IN PROGRESS) ### 0.A — docs/AI-BROWSER-RESEARCH.md - [x] Landscape: Arc / Arc Max & Dia, Perplexity Comet, Brave Leo, Edge Copilot, Opera Aria, SigmaOS, Chrome built-in AI - [x] Page content extraction for LLMs (Readability-style, WKWebView JS injection, selection, long pages) - [x] Chunking, context & long pages (map-reduce, refine, relevance selection, citations) - [x] AI surfaces & UX patterns (command bar, sidebar chat, selection actions, writing assist, AI search, tab summarization, agentic actions) - [x] Streaming & responsiveness (per-tab AI, cancel-on-navigation, 60fps) - [x] Multi-tab / multi-page reasoning - [x] Safety/privacy & correctness (consent, indicators, grounding, citation hygiene) - [x] Document written, every later AI feature traceable to it ### 0.B — docs/PROVIDER-REUSE.md - [x] Study Zyquo Cloud provider layer (ProviderProtocol, OpenAICompatibleClient, AnthropicClient, ProviderRegistry, StreamingService) - [x] Document exact API call formats per provider (base URLs, auth, Codable models, SSE handling) - [x] Complete model catalog inventory (ALL Cloud models available in Atlas) - [x] SecureKeyStore AES-256-GCM vault design (no Keychain) + vault format - [x] Provider-specific streaming quirks table - [x] Port plan: which files port verbatim, which need adaptation ### Phase 0 gate - [x] Both documents complete → Phase 0 done, phase summary written here **Phase 0 summary (2026-07-30):** Both research docs complete. `docs/AI-BROWSER-RESEARCH.md` synthesizes the 2026 landscape (Arc/Dia, Comet, Leo, Edge, Opera, SigmaOS, Chrome, ChatGPT Atlas), the Defuddle+Readability extraction pipeline with a 4-tier fallback ladder, the stuff-first long-context calculus (map-reduce only for small models/multi-tab), the full AI-UX surface set with a feature→pattern traceability table, 60fps streaming + cancel-on-navigation, and an injection-safe privacy model. `docs/PROVIDER-REUSE.md` maps Zyquo Cloud's 2-client provider layer, 170-model catalog, and AES-256-GCM vault to a verbatim/adapt port plan (no GeminiClient — Gemini uses the OpenAI-compat endpoint). Key decisions: Atlas is read-oriented (not agentic); BYO-key + all Cloud models is the differentiator; extraction quality is the product. Toolchain pinned to SDK 26.5. **Phase 0 gate PASSED.** ## Phase 1 — Project Setup (No Xcode IDE) — COMPLETE - [x] `Package.swift` — executable target `ZyquoAtlas` (Foundation/SwiftUI/WebKit/CryptoKit + swift-markdown), `zyquo-verify` launcher target, `ZyquoAtlasTests` (swift-testing) - [x] `Makefile` — SDKROOT pinned to MacOSX26.sdk; `dev`/`build`/`bundle`/`run`/`universal`/`release`/`icon`/`verify`/`test`/`clean` - [x] `scripts/write-info-plist.sh` — browser Info.plist: `CFBundleURLTypes` http/https, `NSUserActivityTypeBrowsingWeb`, ATS `NSAllowsArbitraryLoadsInWebContent` (web content only; app API calls stay HTTPS), productivity category - [x] `Resources/ZyquoAtlas.entitlements` — Hardened-Runtime-ready draft (network client + allow-jit; finalized Phase 8) - [x] `scripts/test.sh` — CLT-only test runner (symlinks Testing.framework) - [x] `@main` `Main.swift` (sync main, `--verify` hook) + `ZyquoAtlasApp.swift` (SwiftUI App, NSApplicationDelegate activation) + `RootPlaceholderView` - [x] Clean release build (24s, zero warnings), `make dev` assembles + ad-hoc signs `Zyquo Atlas.app`, launches and renders a window (verified by screenshot: teal→indigo gradient, "Zyquo Atlas", hidden title bar) - [x] `swift test` green (1 suite); header sweep passes on all code files; `plutil -lint` OK - [x] `README.md` build docs **Phase 1 summary (2026-07-30):** SPM project builds and launches as `Zyquo Atlas.app` without Xcode. Toolchain pinned to SDK 26 in the Makefile (SDK 27's SwiftUI macros need Xcode). Browser Info.plist registers http/https URL schemes + browsing-web activity and sets the correct ATS posture (arbitrary loads only inside WKWebView content). `@main` uses a synchronous entry with a `--verify` hook so the Phase 7 harness can run headlessly on the ported provider clients. Verify/test targets and a CLT-only test runner are wired. All files carry the mandatory header. **Phase 1 gate PASSED** (buildable, launchable, single window; browser core is Phase 2). ## Phase 2 — Architecture + Browser Core — COMPLETE - [x] `DesignSystem/ZyquoTheme.swift` — Atlas teal-indigo tokens (Phase 4.1 base): background/surface/accent #1FA9A0 + indigo #4E63E0/accentSubtle/text/border/status; typography 13.5/1.45, spacing 4–32, radii 6/10/14; light flagship + dark derived via dynamic NSColor - [x] `Models/Profile.swift` + `Browser/ProfileStore.swift` — profile identity; per-profile WKWebsiteDataStore (persistent normal / non-persistent private); modern WebKit auto-pools processes (no WKProcessPool) - [x] `Models/Tab.swift` — owns one WKWebView, KVO-publishes url/title/progress/loading/back/forward/secure; WKNavigationDelegate (progress lifecycle) + WKUIDelegate (new tab on target=_blank/⌘-click, window.close); background-tab suspend/restore - [x] `Browser/TabManager.swift` — ObservableObject tabs + activeTabID; new/close/select/reorder; routes page-initiated new tabs; suspends inactive tabs - [x] `Browser/OmniIntent.swift` — resolves omnibox text: explicit scheme → navigate, bare host/localhost/IP → https navigate, else web search (URL-vs-search gate) - [x] `Browser/WebView.swift` — thin NSViewRepresentable hosting the active tab's WKWebView (re-mounts on switch; background tabs keep live web views) - [x] Views: `BrowserWindowView` (tab strip + toolbar + content), `ToolbarView` (back/forward/reload-or-stop/omnibox/new-tab + determinate progress bar), `OmniboxView` (security glyph + URL/search), `TabBarView` (active tint, hover close, loading spinner) - [x] Clean release build (zero warnings; fixed macOS-14 onChange → 13 form, removed deprecated WKProcessPool), `make dev` launches - [x] 7 tests green (OmniIntent URL-vs-search + smoke); header sweep + coherence pass; folders match Phase 2 layout **PHASE GATE verified (2026-07-30):** launched `Zyquo Atlas.app`; a tab navigated to and **rendered the live DuckDuckGo page** (screenshot), omnibox showed `🔒 https://duckduckgo.com/` with lock indicator, back/forward/reload/stop + new-tab controls present, titled closable tab chip, links open in new tabs via WKUIDelegate, omnibox resolves URL vs search (unit-tested). **Phase 2 gate PASSED** — ready for Phase 3 (AI everywhere). Note: an AppleScript `quit`-by-name collision caused one benign clean exit during testing (no crash log); app is stable on normal launch. ## Phase 3 — AI Everywhere — GATE PASSED (summarize end-to-end) ### 3.0 Provider layer (ported verbatim from Zyquo Cloud) - [x] ProviderProtocol, OpenAICompatibleClient, AnthropicClient, ProviderRegistry (2 clients cover all 12 providers; no GeminiClient — Gemini via OpenAI-compat endpoint) - [x] Models: ProviderID, AIModel, Message; ChatParameters extracted to its own file - [x] Services: StreamingService (SSE), ModelCatalog + ModelCatalogData (170 models), SecureKeyStore (AES-256-GCM, vault info → ZyquoAtlas.vault.v1, root → ZyquoAtlas/), PersistenceService (Atlas root) - [x] ViewModels: KeyVaultStore. Tests: SSEParser + SecureKeyStore ported → 19 tests green ### 3.A Content extraction - [x] Mozilla Readability.js + Readability-readerable.js (Apache-2.0, bundled) + AtlasExtractor.js driver in isolated WKContentWorld (ZyquoAtlasContent), injected via ProfileStore - [x] PageContext (title/url/markdown/selection/headings/quality/tokens), fallback ladder, visible-text-only (hidden/aria-hidden/opacity:0 stripped → injection-safe), heading-aware Chunker ### 3.B AI actions + summarize - [x] AIAction (summarize/keyPoints/explain/translate/ask) with injection-safe prompts (page content = untrusted, delimited, never instructions) - [x] Summarizer (stuff-first; map-reduce past 0.6×context budget), AIService (streaming, cancel-on-navigation via Task cancellation → drops provider stream) - [x] AI sidebar UI (model chip, Summarize action, streamed answer, Stop, privacy note) + toolbar sparkles toggle; per-tab AIService cancelled on didStartProvisionalNavigation - [x] `--load-vault` seeds encrypted vault from env (all 12 providers seeded); `--selftest-summarize` headless harness **PHASE GATE verified (2026-07-30):** `ZyquoAtlas --selftest-summarize https://en.wikipedia.org/wiki/Cartography --provider openai` loaded the live article, extracted it (quality=reader, 9210 words, ~17K tokens, 27 headings, not truncated), chose the `stuff` plan, and **streamed an accurate, grounded summary + key takeaways** from a real Cloud model (gpt-5.2-chat-latest) — the exact ContentExtractor + Summarizer + AIService + ported provider client the GUI calls. GUI builds/launches with the AI sidebar; vault seeded. **Phase 3 gate PASSED.** Notes: running the unsigned bundle from ~/Desktop triggers a macOS Desktop-access TCC prompt (gone once notarized/installed in Phase 8); Readability output includes some Wikipedia nav chrome (extraction-quality tuning tracked for Phase 7's extraction suite). ## Phase 4 — Design System, Theming Engine & UI — GATE PASSED - [x] `AtlasTheme` (Codable palette + background:solid/gradient/image + appearance) with resolved SwiftUI colors; `LayoutSettings` (tabPosition, density, uiScale, pageZoom, bookmarks bar, translucency) with density-derived metrics - [x] 10 built-in themes (flagship **Atlas Light** = Phase 4.1 base spec, Atlas Dark, Cartographer, Meridian, Terra, Slate, Rose Quartz, Midnight, Nocturne, Aurora) — light & dark, some gradient backgrounds - [x] `ThemeEngine` (ObservableObject): live-applied active theme, custom-theme create/edit, per-profile JSON persistence, import/export, match-system light/dark - [x] Refactored all chrome views to read the injected live theme (removed the now-dead static ZyquoColor); ZyquoFont/Spacing/Radius/Metrics retained - [x] Layout: **top-horizontal OR left-vertical (Arc-style) tab bar**, compact/comfortable density, bookmarks-bar toggle — all live - [x] `StartPageView` — customizable new-tab page (theme background, greeting, prominent search/Ask-AI box, favorites grid) - [x] `CustomizationView` — theme gallery w/ live swatches, custom editor (NSColorWell accent/background/chrome), tab layout + density pickers, UI-size slider, import/export - [x] Base light theme matches 4.1 spec; dark derived; motion (150ms fades, layout transitions) **PHASE GATE verified (2026-07-30):** launched from /tmp (avoids the ~/Desktop TCC prompt). Screenshots confirm: (1) **flagship Atlas Light** — crisp off-white chrome, teal omnibox focus ring, start page with Ask-AI chip + favorites grid; (2) **Midnight dark theme + left vertical tabs** loaded from the persisted JSON on relaunch — proving live theme-switch, the top/left layout system, dark-theme derivation, and per-profile persistence. Build clean (zero warnings), 19 tests green, headers present, no dead code. **Phase 4 gate PASSED** — this is the UI contract for Phase 6. Deferred to Phase 6 (built on their services): full favorites manager, history view, downloads, reader mode. ## Phase 5 — App Icon (ultra-legendary "atlas" icon) — COMPLETE - [x] `assets/icon/zyquo-atlas.svg` — Big Sur squircle (family superellipse), teal→indigo gradient (#22C3B8→#1FA9A0→#4E63E0), thin globe/meridian arcs framing the bold near-white family Z (deep-indigo contour under white face) so the Z diagonal reads as a route across the map; compass-north waypoint accent; one soft top light. viewBox 0 0 1024 1024. - [x] Rendered both directions (Z-globe + `zyquo-atlas-compass.svg`); kept the **Z-globe** (cleaner, tells the web/cartography story best) - [x] `zyquo-atlas-small.svg` (16/32 slots — simplified, caret-free Z + faint globe hint) and `zyquo-atlas-template.svg` (monochrome menu-bar glyph: Z + globe ring) - [x] `scripts/generate-icon.sh` (rsvg-convert) → PNGs 16→1024 incl @2x → AppIcon.iconset → `iconutil -c icns` → `Resources/AppIcon.icns`; menu-bar template PNGs @1x/@2x; wired to `make icon` - [x] Rendered & inspected 16→1024; thin meridians thickened/dropped for small sizes so they survive downscaling - [x] Embedded `.icns` in the bundle (CFBundleIconFile=AppIcon); **verified showing in the Dock** — clearly a sibling of Cloud/Local/Agent, distinct teal-indigo + globe **Phase 5 summary (2026-07-30):** The teal-indigo "atlas" icon exists as SVG source of truth, builds to a complete `.icns`, and renders beautifully at every size (verified at 512, 64, 32, and Dock size). It reuses the exact family squircle + Z monogram + lighting for unmistakable kinship while telling the browser/exploration story via the globe meridians and compass accent. Menu-bar template + small variant derived from the same design. **Phase 5 complete.** ## Phase 6 — Features — COMPLETE (core), with documented deferrals ### Browser core - [x] Tab **pinning** (compact chips), background **suspension** + dimming, **session restore** per profile, page-initiated new tabs - [x] **Private window** (⌘⇧N) with non-persistent data store; per-profile themes; app-wide favorites/history - [x] **Find-in-page** (⌘F, native WKWebView find, next/prev/wrap), per-tab zoom API, security indicators, **reader mode** (Readability article + AI summary) - [x] **Downloads** (WKDownload → ~/Downloads, progress, reveal/open) + toolbar popover - [x] **Favorites**: BookmarksService (CRUD, tags, notes, search, on-bar subset, Netscape HTML import/export), bookmarks bar (toggleable), favorites manager (⌥⌘B, edit/delete/import/export) - [x] **History**: HistoryService (visit coalescing, full-text search, group-by-day, delete-range/clear), history view (⌘Y) with **ask-AI-about-history** (titles/hosts only, on demand) ### AI everywhere - [x] **Chat-with-page** sidebar: multi-turn follow-ups, model picker (all Cloud models), quick actions (Summarize / Key points / Translate) - [x] **Selection floating toolbar** (Explain / Summarize / Translate / Rewrite / Ask) via JS selectionchange observer → native overlay at the selection rect - [x] **Omnibox "Ask AI"** route (third route; answer streams in the sidebar) + **⌥Space Quick Ask** - [x] **Multi-tab compare** (gathers open tabs' PageContext), **per-action default model** (fast/standard/deep tiers), injection-safe prompts, privacy note ### Native shortcuts (AtlasCommands, focused-scene routed) - [x] ⌘T, ⌘W, ⌘L, ⌘⇧A, ⌘F, ⌘D, ⌘Y, ⌘⇧N, ⌘1–8/⌘9, ⌥Space, ⌘R, ⌘[ / ⌘], ⌘, , ⌥⌘B, ⌘⇧J — via a per-window WindowState published as a focused-scene value **Verified (2026-07-30):** launched with a seeded bookmarks bar — screenshot confirms the bookmarks bar (Wikipedia, Hacker News), the enriched toolbar (reader, downloads, customize, AI buttons), and the new **Tabs**/**Atlas** command menus. Build clean (zero warnings), 19 tests green, headers present, naming coherent, no dead code. **Deferred to a follow-up pass (documented, not silently dropped):** tab-groups/"spaces" and drag-reorder gesture; hover **thumbnail** previews; per-site zoom persistence + content-blocking hooks; AI **writing-assist with in-field replacement** (the selection-toolbar Rewrite covers rewriting selected text, but not typing back into `