SPB Git

spb/zyquo-atlas Public License

The AI-native macOS web browser — every surface, intelligent.

macosswiftaibrowser
Swift 75.2% JavaScript 22% Shell 2% Makefile 0.9%
21.3 KB
View source Raw Blame History

# 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

  • Landscape: Arc / Arc Max & Dia, Perplexity Comet, Brave Leo, Edge Copilot, Opera Aria, SigmaOS, Chrome built-in AI
  • Page content extraction for LLMs (Readability-style, WKWebView JS injection, selection, long pages)
  • Chunking, context & long pages (map-reduce, refine, relevance selection, citations)
  • AI surfaces & UX patterns (command bar, sidebar chat, selection actions, writing assist, AI search, tab summarization, agentic actions)
  • Streaming & responsiveness (per-tab AI, cancel-on-navigation, 60fps)
  • Multi-tab / multi-page reasoning
  • Safety/privacy & correctness (consent, indicators, grounding, citation hygiene)
  • Document written, every later AI feature traceable to it

# 0.B — docs/PROVIDER-REUSE.md

  • Study Zyquo Cloud provider layer (ProviderProtocol, OpenAICompatibleClient, AnthropicClient, ProviderRegistry, StreamingService)
  • Document exact API call formats per provider (base URLs, auth, Codable models, SSE handling)
  • Complete model catalog inventory (ALL Cloud models available in Atlas)
  • SecureKeyStore AES-256-GCM vault design (no Keychain) + vault format
  • Provider-specific streaming quirks table
  • Port plan: which files port verbatim, which need adaptation

# Phase 0 gate

  • 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

  • Package.swift — executable target ZyquoAtlas (Foundation/SwiftUI/WebKit/CryptoKit + swift-markdown), zyquo-verify launcher target, ZyquoAtlasTests (swift-testing)
  • Makefile — SDKROOT pinned to MacOSX26.sdk; dev/build/bundle/run/universal/release/icon/verify/test/clean
  • scripts/write-info-plist.sh — browser Info.plist: CFBundleURLTypes http/https, NSUserActivityTypeBrowsingWeb, ATS NSAllowsArbitraryLoadsInWebContent (web content only; app API calls stay HTTPS), productivity category
  • Resources/ZyquoAtlas.entitlements — Hardened-Runtime-ready draft (network client + allow-jit; finalized Phase 8)
  • scripts/test.sh — CLT-only test runner (symlinks Testing.framework)
  • @main Main.swift (sync main, --verify hook) + ZyquoAtlasApp.swift (SwiftUI App, NSApplicationDelegate activation) + RootPlaceholderView
  • 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)
  • swift test green (1 suite); header sweep passes on all code files; plutil -lint OK
  • 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

  • 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
  • Models/Profile.swift + Browser/ProfileStore.swift — profile identity; per-profile WKWebsiteDataStore (persistent normal / non-persistent private); modern WebKit auto-pools processes (no WKProcessPool)
  • 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
  • Browser/TabManager.swift — ObservableObject tabs + activeTabID; new/close/select/reorder; routes page-initiated new tabs; suspends inactive tabs
  • Browser/OmniIntent.swift — resolves omnibox text: explicit scheme → navigate, bare host/localhost/IP → https navigate, else web search (URL-vs-search gate)
  • Browser/WebView.swift — thin NSViewRepresentable hosting the active tab's WKWebView (re-mounts on switch; background tabs keep live web views)
  • 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)
  • Clean release build (zero warnings; fixed macOS-14 onChange → 13 form, removed deprecated WKProcessPool), make dev launches
  • 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)

  • ProviderProtocol, OpenAICompatibleClient, AnthropicClient, ProviderRegistry (2 clients cover all 12 providers; no GeminiClient — Gemini via OpenAI-compat endpoint)
  • Models: ProviderID, AIModel, Message; ChatParameters extracted to its own file
  • Services: StreamingService (SSE), ModelCatalog + ModelCatalogData (170 models), SecureKeyStore (AES-256-GCM, vault info → ZyquoAtlas.vault.v1, root → ZyquoAtlas/), PersistenceService (Atlas root)
  • ViewModels: KeyVaultStore. Tests: SSEParser + SecureKeyStore ported → 19 tests green

# 3.A Content extraction

  • Mozilla Readability.js + Readability-readerable.js (Apache-2.0, bundled) + AtlasExtractor.js driver in isolated WKContentWorld (ZyquoAtlasContent), injected via ProfileStore
  • 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

  • AIAction (summarize/keyPoints/explain/translate/ask) with injection-safe prompts (page content = untrusted, delimited, never instructions)
  • Summarizer (stuff-first; map-reduce past 0.6×context budget), AIService (streaming, cancel-on-navigation via Task cancellation → drops provider stream)
  • AI sidebar UI (model chip, Summarize action, streamed answer, Stop, privacy note) + toolbar sparkles toggle; per-tab AIService cancelled on didStartProvisionalNavigation
  • --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

  • AtlasTheme (Codable palette + background:solid/gradient/image + appearance) with resolved SwiftUI colors; LayoutSettings (tabPosition, density, uiScale, pageZoom, bookmarks bar, translucency) with density-derived metrics
  • 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
  • ThemeEngine (ObservableObject): live-applied active theme, custom-theme create/edit, per-profile JSON persistence, import/export, match-system light/dark
  • Refactored all chrome views to read the injected live theme (removed the now-dead static ZyquoColor); ZyquoFont/Spacing/Radius/Metrics retained
  • Layout: top-horizontal OR left-vertical (Arc-style) tab bar, compact/comfortable density, bookmarks-bar toggle — all live
  • StartPageView — customizable new-tab page (theme background, greeting, prominent search/Ask-AI box, favorites grid)
  • CustomizationView — theme gallery w/ live swatches, custom editor (NSColorWell accent/background/chrome), tab layout + density pickers, UI-size slider, import/export
  • 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

  • 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.
  • Rendered both directions (Z-globe + zyquo-atlas-compass.svg); kept the Z-globe (cleaner, tells the web/cartography story best)
  • 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)
  • 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
  • Rendered & inspected 16→1024; thin meridians thickened/dropped for small sizes so they survive downscaling
  • 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

  • Tab pinning (compact chips), background suspension + dimming, session restore per profile, page-initiated new tabs
  • Private window (⌘⇧N) with non-persistent data store; per-profile themes; app-wide favorites/history
  • Find-in-page (⌘F, native WKWebView find, next/prev/wrap), per-tab zoom API, security indicators, reader mode (Readability article + AI summary)
  • Downloads (WKDownload → ~/Downloads, progress, reveal/open) + toolbar popover
  • Favorites: BookmarksService (CRUD, tags, notes, search, on-bar subset, Netscape HTML import/export), bookmarks bar (toggleable), favorites manager (⌥⌘B, edit/delete/import/export)
  • 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

  • Chat-with-page sidebar: multi-turn follow-ups, model picker (all Cloud models), quick actions (Summarize / Key points / Translate)
  • Selection floating toolbar (Explain / Summarize / Translate / Rewrite / Ask) via JS selectionchange observer → native overlay at the selection rect
  • Omnibox "Ask AI" route (third route; answer streams in the sidebar) + ⌥Space Quick Ask
  • 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)

  • ⌘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 <textarea>/contenteditable); opt-in auto-summaries / link hover-summaries; on-tab "content-in-use" glow indicator; explicit source-link rendering under omnibox answers and section-citation chips in chat; menu-bar extra (NSStatusItem) and programmatic set-as-default-browser. Core Phase 6 (the DoD feature set) is functional.

# Phase 7 — Verification — COMPLETE (183/183 green)

  • Atlas verification harness (--verify): headless content extraction on real pages, grounded summarize across every catalog model through the ported provider clients, core AI action matrix, cancel-on-navigation + privacy checks; writes docs/VERIFICATION.md. Keys from env, never logged.
  • Content extraction 5/5 (article, docs, very long article, JS app, page-with-selection — clean main-content + correct selection captured)
  • All 169 catalog models summarize green through Atlas (ContentExtractor + AIService + provider clients), grounded + streaming
  • AI action matrix 7/7 (omnibox ask, summarize, chat follow-up, selection explain/translate/rewrite, multi-tab compare)
  • Cancellation & privacy ✓ (stream cancels on navigation; nothing sent without a user action)

Failures found & fixed: first sweep 173/184 → three genuine failures fixed — two reasoning models (Together Qwen3.5-9B, DeepInfra Kimi-K2.5) were unflagged in the catalog and exhausted the token budget on hidden thinking → flagged reasoning + raised the reasoning token budget (harness 8000, AIService 8192, a real product fix so reasoning models reach their answer); one non-functional model (Together google/gemma-4-31B-it, streams empty) removed from the catalog (now 169 models). Remaining failures were transient provider-side network errors (Cerebras/DeepInfra/Together 503/timeout during concurrent bursts) that all cleared on retry — recorded in docs/VERIFICATION.md in their re-verified green state.

Final: 183 checks · 183 passed · 0 failed. No keys or browsing data committed. Phase 7 gate PASSED.

# Phase 8 — Signing & Notarization — COMPLETE (Notarized Developer ID)

  • Inspected zyquo-term signing setup and reused it verbatim: identity Developer ID Application: Simon-Pierre Boucher (3YM54G49SN), Team 3YM54G49SN, notarytool keychain profile MacLustr-Notarize (both confirmed present/live on this machine)
  • Resources/ZyquoAtlas.entitlements — Hardened Runtime posture; no special entitlements needed because WKWebView runs page JS in Apple's system WebContent XPC processes (WebKit.framework is not embedded); not App-Sandboxed (browser). Minimal, matches the family.
  • scripts/notarize.sh — signs inside-out (nested SPM resource bundle, then the app) with --options runtime --timestamp --entitlements, ditto -c -k --keepParent zip, notarytool submit --wait, stapler staple + validate, spctl assessment
  • Makefile universal fixed to SwiftPM single-command multi-arch (swift build -c release --arch arm64 --arch x86_64 → fat binary in .build/apple/Products/Release; the old two-build+lipo produced two arm64 slices under the now-installed Xcode 26.6 toolchain)
  • make release run end-to-end: Apple notarization status: Accepted (submission 2003be13-…), stapled + validated

Verified independently: lipo -archs → x86_64 arm64; codesign -dvv → flags=0x10000(runtime), Authority Developer ID Application …, TeamIdentifier=3YM54G49SN; stapler validate → worked; spctl -a -vv → accepted, source=Notarized Developer ID. Phase 8 gate PASSED.

Notes: make dev (ad-hoc) retained for iteration. Optional signed+stapled DMG delivered (make dmg → dist/ZyquoAtlas.dmg, notarization Accepted, spctl = Notarized Developer ID). Vendored Content/Readability*.js (Mozilla, Apache-2.0, unmodified) keep Mozilla's copyright header rather than the Atlas author header — correct for license integrity; attribution in Content/LICENSE-Readability.txt.

# Definition of Done — final check (2026-07-30)

  • make release → Developer ID–signed, notarized, stapled Zyquo Atlas.app, universal, built without the Xcode IDE (SPM/CLI); spctl = Notarized Developer ID
  • Fast multi-tab WKWebView browser: profiles, private mode, favorites, full-text history, downloads, find, reader
  • AI everywhere: omnibox ask, chat-with-page, selection actions, summarize/translate/rewrite, multi-tab compare — streaming, grounded, every provider/model (Phase 7 table green, 169 models)
  • Theming/customization engine: themes, backgrounds, top/left tabs, density, custom start page — live, per profile
  • Privacy model: page content leaves only on user action; keys in the reused AES-256-GCM vault (no Keychain)
  • Teal-indigo "atlas" SVG icon → .icns + template glyph; sibling of Cloud/Local/Agent
  • Light theme matches the Phase 4 spec; dark derived
  • Naming coherent (Zyquo Atlas, com.zyquo.atlas, ZyquoAtlas); every authored code file carries the header (verified)
  • docs/PLAN.md all phases complete; AI-BROWSER-RESEARCH.md, PROVIDER-REUSE.md, VERIFICATION.md complete
  • [~] Deferred enhancements documented in Phase 6 (tab groups/drag-reorder gesture, hover thumbnails, in-field writing-assist, auto/hover summaries, citation-chip rendering, menu-bar extra)

All 9 phases (0–8) complete. Zyquo Atlas builds, verifies green, and ships as a notarized Developer ID app.