spb/zyquo-atlas Public License

1<!--2  README.md3  Zyquo Atlas4  Author: Simon-Pierre Boucher5  Mail: contact@spboucher.ai6-->78<div align="center">910<img src="assets/app-icon.png" width="168" height="168" alt="Zyquo Atlas app icon" />1112# Zyquo Atlas1314### The AI-native macOS web browser — every surface, intelligent.1516*A fast, radically customizable, privacy-first browser where AI is woven into the omnibox,17the page, your selection, and your tabs — powered by **your** keys across **12 providers** and **169 models**.*1819<br/>2021[![Release](https://img.shields.io/github/v/release/spboucher-ai/zyquo-atlas?sort=semver&label=release&color=1FA9A0)](https://github.com/spboucher-ai/zyquo-atlas/releases/latest)22[![Platform](https://img.shields.io/badge/platform-macOS%2013%2B-4E63E0)](https://www.apple.com/macos/)23[![Swift](https://img.shields.io/badge/Swift-5.9-orange?logo=swift&logoColor=white)](https://swift.org)24[![WebKit](https://img.shields.io/badge/engine-WebKit%20(WKWebView)-1FA9A0)](https://webkit.org)25[![Universal](https://img.shields.io/badge/binary-Universal%20(arm64%20%2B%20x86__64)-4E63E0)](#-building-from-source)26[![Notarized](https://img.shields.io/badge/Gatekeeper-Notarized%20Developer%20ID-2FA36B?logo=apple&logoColor=white)](#-installation)27[![Downloads](https://img.shields.io/github/downloads/spboucher-ai/zyquo-atlas/total?color=1FA9A0)](https://github.com/spboucher-ai/zyquo-atlas/releases)28[![License](https://img.shields.io/badge/license-Proprietary-lightgrey)](LICENSE)2930<br/>3132[**⬇︎ Download the latest .dmg**](https://github.com/spboucher-ai/zyquo-atlas/releases/latest/download/ZyquoAtlas.dmg) &nbsp;·&nbsp; [Features](#-features) &nbsp;·&nbsp; [Screenshots](#-screenshots) &nbsp;·&nbsp; [Install](#-installation) &nbsp;·&nbsp; [Build](#-building-from-source)3334</div>3536---3738## 📑 Table of Contents3940- [Overview](#-overview)41- [Screenshots](#-screenshots)42- [Features](#-features)43  - [Browser core](#browser-core)44  - [AI everywhere](#ai-everywhere)45  - [Massive customization](#massive-customization)46  - [Privacy &amp; security](#privacy--security)47  - [Keyboard shortcuts](#keyboard-shortcuts)48- [Supported AI providers &amp; models](#-supported-ai-providers--models)49- [Requirements](#-requirements)50- [Installation](#-installation)51- [Usage](#-usage)52- [Building from source](#-building-from-source)53- [Architecture](#-architecture)54- [Verification](#-verification)55- [Roadmap](#-roadmap)56- [Contributing](#-contributing)57- [License](#-license)58- [Author](#-author)5960---6162## 🧭 Overview6364**Zyquo Atlas** is a native macOS web browser built in **Swift + SwiftUI** on Apple's65**WebKit (`WKWebView`)** engine — compiled entirely with the Swift Package Manager and the66command-line toolchain, **without the Xcode IDE**. It is the web-browser member of the67**Zyquo** family.6869Unlike browsers that bolt a chatbot onto a sidebar, Atlas weaves AI into every surface —70the omnibox, the current page, your text selection, and across your open tabs — and it does71so on **your** terms: you bring your own API keys, stored in a machine-bound, AES-256-GCM72encrypted vault (no Keychain), and page content is sent to a provider **only** when you73invoke an AI action.7475- **~8,300 lines** of Swift across **58 files**, zero build warnings.76- **12 AI providers · 169 models** — the same catalog and provider layer as Zyquo Cloud.77- **Universal** (Apple Silicon + Intel), **Developer ID–signed, notarized, and stapled**.7879---8081## 📸 Screenshots8283<div align="center">8485**Customizable start page — flagship light theme**8687<img src="assets/screenshot-startpage.png" width="820" alt="Zyquo Atlas start page (light theme)" />8889<br/><br/>9091**Live browsing with the bookmarks bar**9293<img src="assets/screenshot-browsing.png" width="820" alt="Zyquo Atlas rendering a web page with the bookmarks bar" />9495<br/><br/>9697**Midnight dark theme with left vertical tabs**9899<img src="assets/screenshot-dark.png" width="820" alt="Zyquo Atlas dark theme with left vertical tab sidebar" />100101</div>102103---104105## ✨ Features106107Every feature below is implemented in this repository — nothing aspirational.108109### Browser core110111- 🗂️ **Real multi-tab WKWebView browsing** — each tab owns its web view and navigation112  state, with a determinate progress bar, back/forward/reload/stop, and links that open in113  new tabs (`target=_blank`, ⌘-click, `window.open`).114- 📌 **Tab pinning**, **background-tab suspension** (dims + frees memory), and **session115  restore** per profile on relaunch.116- ↕️ **Top horizontal tabs OR a left vertical tab sidebar** (Arc-style) — switch live.117- 🧭 **Smart omnibox** — resolves your input into **navigate** (URL), **web search**, or118  **Ask AI**, with a security indicator and reader toggle.119- 🕵️ **Private windows** (⌘⇧N) using a non-persistent data store — no history, no session,120  no saved data.121- 📖 **Reader mode** — a clean, themeable article view with an optional AI summary at the top.122- ⬇️ **Downloads** — routed to `~/Downloads` with live progress, reveal-in-Finder, and open.123- 🔎 **Find-in-page** (⌘F) — native WebKit find with next/previous and wrap.124- ⭐ **Favorites** — a toggleable bookmarks bar, a full manager (edit title/URL/tags/notes,125  show-on-bar), search, and **Netscape HTML import/export** (interchange with other browsers).126- 🕘 **Full-text history** — searchable, grouped by day, with delete-range/clear controls.127- 👤 **Profiles** — a persistent personal profile and a private profile, each with isolated128  WebKit data stores.129130### AI everywhere131132- 💬 **Chat-with-page sidebar** — a per-tab, multi-turn conversation grounded in the page's133  extracted content, with an in-panel **model picker across all 169 models**.134- ⚡ **Quick actions** — one-click **Summarize**, **Key points**, and **Translate**, plus135  long-page **map-reduce** summarization for articles that exceed the model's context.136- 🖱️ **Selection floating toolbar** — select any text on a page and get **Explain /137  Summarize / Translate / Rewrite / Ask** right at the cursor.138- 🔮 **Ask AI from the omnibox** — get a streamed, grounded answer without leaving the page.139- 🪟 **Multi-tab reasoning** — "compare these open tabs" gathers several pages and answers140  across them.141- 🎚️ **Per-action model tiers** — pick a fast/cheap model for quick actions and a strong one142  for deep chat; choices persist.143- 🧱 **Grounded &amp; injection-safe** — page content is extracted with Mozilla Readability in144  an isolated JavaScript world (visible text only), wrapped as untrusted data in every145  prompt, and streamed responses **cancel automatically on navigation**.146147### Massive customization148149- 🎨 **Theming engine** — **10 built-in themes** (light &amp; dark, including the flagship150  teal-indigo *Atlas Light* and *Midnight*), plus a **custom theme editor** (native color151  wells for accent / background / chrome) that applies **live**.152- 🖼️ **Backgrounds** — solid, gradient, or image behind the chrome and start page.153- 🧩 **Layout** — top or left tabs, **compact/comfortable density**, bookmarks-bar toggle,154  and a **UI-size slider**.155- 🏠 **Customizable start page** — greeting, a prominent search / Ask-AI box, and a favorites156  grid.157- 💾 **Per-profile persistence** and **theme import/export** as small JSON files.158159### Privacy &amp; security160161- 🔐 **Encrypted key vault** — API keys are stored with **AES-256-GCM** (CryptoKit),162  bound to the machine via `IOPlatformUUID` + HKDF, in `~/Library/Application163  Support/ZyquoAtlas/vault.zq` — **not** the Keychain, decrypted on demand and never logged.164- 🛡️ **Content leaves the device only on a user-invoked AI action**, always to the provider165  you chose, via your own key — **never to Zyquo**.166- 🧯 **Prompt-injection hardening** — extraction drops hidden/`aria-hidden`/off-screen text;167  page content is delimited and labelled untrusted; the AI layer has no navigation or tool168  access, so even a hostile page can only produce a bad summary, never an action.169- 🍎 **Hardened Runtime, Developer ID–signed, notarized &amp; stapled** — `spctl` reports170  *Notarized Developer ID*.171172### Keyboard shortcuts173174| Shortcut | Action | Shortcut | Action |175|---|---|---|---|176| `⌘T` | New tab | `⌘Y` | History |177| `⌘W` | Close tab | `⌥⌘B` | Bookmarks manager |178| `⌘L` | Focus omnibox | `⌘⇧J` | Downloads |179| `⌘⇧A` | Toggle AI sidebar | `⌘⇧N` | Private window |180| `⌘F` | Find in page | `⌘1`–`⌘8`, `⌘9` | Switch tab / last tab |181| `⌘D` | Bookmark page | `⌥Space` | Quick AI ask |182| `⌘R` | Reload | `⌘[` / `⌘]` | Back / forward |183| `⌘,` | Customize | | |184185---186187## 🤖 Supported AI providers &amp; models188189Atlas speaks to **12 providers** and ships a catalog of **169 chat models**, calling each190provider exactly as Zyquo Cloud does (OpenAI-compatible or native Anthropic Messages API,191streaming SSE, reasoning-token aware). Bring your own key per provider.192193| Provider | Provider | Provider |194|---|---|---|195| OpenAI | Anthropic (Claude) | xAI (Grok) |196| Mistral | Google Gemini | Alibaba Qwen (DashScope) |197| DeepSeek | Kimi (Moonshot) | Perplexity |198| Together AI | DeepInfra | Cerebras |199200Every provider/model was live-verified end-to-end — see [Verification](#-verification).201202---203204## 💻 Requirements205206- **macOS 13.0 (Ventura) or later** — Apple Silicon or Intel.207- An **API key** for at least one supported provider to use the AI features (browsing works208  without any key).209- To build from source: the **Swift 5.9+ toolchain** (Command Line Tools or Xcode).210211---212213## 📦 Installation2142151. **[Download `ZyquoAtlas.dmg`](https://github.com/spboucher-ai/zyquo-atlas/releases/latest/download/ZyquoAtlas.dmg)** from the latest release.2162. Open the DMG and **drag *Zyquo Atlas* into Applications**.2173. Launch it. The app is **notarized by Apple**, so Gatekeeper opens it without warnings.2184. Add your API keys in **Customize / Settings** (or import them) to enable AI features.219220> Verify authenticity yourself: `spctl -a -vv "/Applications/Zyquo Atlas.app"` →221> `source=Notarized Developer ID`.222223---224225## 🚀 Usage226227- **Browse** — type a URL or search terms in the omnibox; press Enter.228- **Ask AI** — click **Ask AI** in the omnibox, or open the sidebar with `⌘⇧A`, to ask about229  the current page with cited, grounded answers.230- **Summarize** — open the AI sidebar and hit **Summarize** (works on long articles via231  map-reduce), or use **Reader mode** for a clean read + summary.232- **Selection actions** — select text on any page and choose **Explain / Translate / Rewrite233  / Ask** from the floating toolbar.234- **Compare tabs** — open several pages and click **Compare tabs** in the sidebar.235- **Customize** — press `⌘,` to switch themes, move tabs to a left sidebar, tune density, and236  edit a custom theme with live preview.237238---239240## 🛠️ Building from source241242Zyquo Atlas builds with the Swift Package Manager — **no Xcode project required**.243244```sh245git clone https://github.com/spboucher-ai/zyquo-atlas.git246cd zyquo-atlas247248make dev       # release build → dist/Zyquo Atlas.app (ad-hoc signed), for local iteration249make run       # build + launch250make test      # run the test suite251make icon      # regenerate AppIcon.icns from assets/icon/zyquo-atlas.svg252253# Distribution (requires a Developer ID certificate + notarytool profile):254make release   # universal (arm64 + x86_64), Developer ID signed, notarized, stapled255make dmg       # signed + notarized + stapled dist/ZyquoAtlas.dmg256```257258Dependencies: Apple frameworks only — **SwiftUI, WebKit, CryptoKit, AppKit, Foundation,259Combine, Security, IOKit** — plus Apple's **swift-markdown**. Mozilla **Readability**260(Apache-2.0) is vendored for content extraction. No third-party HTTP libraries.261262---263264## 🏗️ Architecture265266```267Sources/ZyquoAtlas/268├── App/            @main entry, scene + commands, per-window state, app environment269├── DesignSystem/   ZyquoTheme tokens · AtlasTheme + 10 built-in themes · ThemeEngine270├── Models/         Tab · Profile · Bookmark · HistoryEntry · AIModel · Message · …271├── Browser/        WebView (WKWebView wrapper) · TabManager · ProfileStore ·272│                   OmniIntent · DownloadManager273├── Content/        ContentExtractor + Readability.js + AtlasExtractor.js · PageContext ·274│                   Chunker   (isolated WKContentWorld, visible-text-only)275├── AI/             AIService (streaming, cancel-on-nav) · AIActions · Summarizer276├── Providers/      ProviderProtocol · OpenAICompatibleClient · AnthropicClient · Registry277├── Services/       ModelCatalog (169) · SecureKeyStore (AES-256-GCM) · StreamingService (SSE)278├── Features/       BookmarksService · HistoryService279├── ViewModels/     KeyVaultStore280└── Views/          Browser chrome, AI sidebar + selection toolbar, feature panels281```282283---284285## ✅ Verification286287A built-in harness (`--verify`) exercises the real stack — content extraction, then a288grounded summarize across **every one of the 169 models**, the full AI-action matrix, and289cancel-on-navigation / privacy invariants — against live APIs.290291**Latest result: 183 / 183 checks green.** Full table in292[`docs/VERIFICATION.md`](docs/VERIFICATION.md).293294---295296## 🗺️ Roadmap297298Planned enhancements (tracked in [`docs/PLAN.md`](docs/PLAN.md)):299300- Tab groups / "spaces" and drag-to-reorder301- Hover thumbnail previews for tabs and links302- AI writing assist that types back into web text fields303- Opt-in auto-summaries and link hover-summaries304- Inline source-link and section-citation chips in answers305- A menu-bar quick-ask extra306307---308309## 🤝 Contributing310311Issues and feature suggestions are welcome via312[GitHub Issues](https://github.com/spboucher-ai/zyquo-atlas/issues). This is a source-available313project (see [License](#-license)); please open an issue to discuss substantial changes before314submitting a pull request.315316Engineering standards: Swift 5.9+, zero warnings, every source file carries the project317header, design tokens over magic numbers, and the provider layer stays byte-compatible with318the Zyquo family.319320---321322## 📄 License323324Copyright © 2026 Simon-Pierre Boucher. **All rights reserved.** The source is public for325reference and transparency; the compiled app (the notarized `.dmg`) is free for personal use.326See [`LICENSE`](LICENSE). Vendored Mozilla Readability and swift-markdown are Apache-2.0.327328---329330## 👤 Author331332<div align="center">333334**Simon-Pierre Boucher**335336📧 [contact@spboucher.ai](mailto:contact@spboucher.ai)337338<br/>339340*Part of the **Zyquo** family — Cloud · Local · Agent · Atlas.*341342<sub>Built with Swift, SwiftUI &amp; WebKit — no Xcode IDE. 🗺️</sub>343344</div>345