| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| |
| # Reference Settings — full reverse-engineer (2026-06-23) |
| |
| > Archived on 2026-07-13. This reverse-engineering snapshot is provenance, not the current Settings contract. |
| |
| Cross-checked by 4 parallel Explore agents on the extracted bundle at |
| `/tmp/qoder-asar/out/renderer/assets/`. |
| |
| This note captures the reference's Settings module so future Maka PRs can |
| align without re-doing the dig. Naming hygiene applies: do not surface |
| the reference product name in code, commits, or end-user copy. |
| |
| --- |
| |
| ## 1. Shell shape |
| |
| Settings is a **full-pane modal** that takes over the workspace area. It |
| is NOT a small overlay sheet. |
| |
| - `role="dialog"` + `aria-modal="true"` |
| - Marker attributes: `data-modal="agents-settings"`, |
| `data-canvas-dialog="true"`, `data-settings-layout="page"` |
| - Outer shell: |
| ``` |
| flex h-full min-h-0 w-full flex-col overflow-hidden bg-background select-none |
| ``` |
| - The rest of the chat surface stays visible behind a subtle backdrop; |
| the modal does not float over a blurred mask — it occupies the canvas. |
| |
| ### Two-rail layout |
| |
| | Region | Width / sizing | Notes | |
| |----------|--------------------------------------|------------------------------------------| |
| | Nav rail | `w-[256px] shrink-0` | Left side, `bg-transparent`, full height | |
| | Content | `flex-1 min-w-0 overflow-hidden` | Right side, scrolls on the inner column | |
| | Gap | `var(--agents-content-area-gap)` 4px | Margin between rail and content plate | |
| |
| Content pane class: `agents-settings-wide-content`: |
| ```css |
| .agents-settings-wide-content { |
| background: var(--agents-content-area-bg); |
| margin: var(--agents-content-area-gap) |
| var(--agents-content-area-gap) |
| var(--agents-content-area-gap) 0; |
| border-radius: var(--agents-content-area-radius); /* 6px */ |
| } |
| ``` |
| |
| Content body inner wrapper (where the page lives): |
| ``` |
| mx-auto min-h-[200px] max-w-3xl pb-16 pt-10 |
| ``` |
| `max-w-3xl` = 48rem / 768px. That's the optical reading column for any |
| settings page body. |
| |
| ### Responsive |
| |
| | Breakpoint | Behavior | |
| |------------|-------------------------------------------------------| |
| | ≥ 1200px | Two-rail (256px rail + content) | |
| | 900–1199 | Two-rail, tightened | |
| | < 900px | Compact: rail collapses; header shows back-arrow + title | |
| |
| --- |
| |
| ## 2. Nav rail |
| |
| The rail is a flat vertical list (no group headings — purely flat). |
| |
| ### Items shown to the end user (in order) |
| |
| 1. `preferences` — **Preferences** (the big aggregator) |
| 2. `profile` — Profile / account |
| 3. `system` — **System** (intentionally near-empty placeholder) |
| 4. `keyboard` — Keyboard shortcuts |
| 5. `vm` — Secure workspace / VM mode |
| 6. `experimental` — Experimental flags |
| 7. `permissions` — System capability toggles |
| 8. `connector` — Integrations / connectors |
| 9. `appshot` — App snapshot (macOS only, gated by `platforms: ["darwin"]`) |
| |
| ### Hidden / dev-only tabs |
| |
| `appearance` (handled via the Preferences page itself), `privacy`, |
| `debug`, `hiddenConnector`, `awareness`, `appUpdate`, `models`, |
| `customModels`, `commands`, `agents`, `worktrees`, `quickpick`, |
| `voiceInput`, `wechat`, `beta`, `channels`, `legokit`, `archived` — all |
| `exposed: false`. |
| |
| Tab registry lives in `index-C02cm0ok.js` around offset ~213400 (look |
| for `Su=[]`). |
| |
| ### Nav-row recipe |
| |
| ```html |
| <!-- inactive --> |
| <button class="squircle-md text-text-secondary/80 |
| hover:bg-[var(--settings-nav-row-selected-bg)] |
| hover:text-text/80"> |
| <Icon size=… /> |
| <span>Label</span> |
| </button> |
| |
| <!-- active --> |
| <button class="squircle-md |
| bg-[var(--settings-nav-row-selected-bg)] |
| text-text/80"> |
| … |
| </button> |
| ``` |
| |
| - Icon library: Lucide |
| - Active state is a **fill** (not border / left-bar), with |
| `--settings-nav-row-selected-bg` = `var(--color-fill-secondary)` |
| - Typography: text-sm (14px), normal weight at rest; no weight bump on |
| active (color/background carry the state) |
| - Padding (educated from sibling rows): `px-4 py-3` |
| - Gap between glyph + label: `gap-3` |
| - Border radius: `squircle-md` (custom corner, not pure rounded-md) |
| |
| --- |
| |
| ## 3. Per-tab content inventory |
| |
| ### 3.1 Preferences (the kitchen sink) |
| |
| Globals offset ~76380–80000. This single tab carries the bulk of the |
| end-user controls: |
| |
| | Control | Type | Notes | |
| |----------------------------------|-----------------|-------------------------------------------------------------| |
| | Language | select | UI locale | |
| | Extended Thinking | switch | Bigger reasoning budget, disables streaming | |
| | Launch at Login (autoLaunch) | switch | Auto-start | |
| | Close Window Behavior | radio / select | Ask / Minimize-to-tray / Quit | |
| | Desktop Notifications | switch | Native OS notifications | |
| | Sound Notifications | switch | Audio on task completion | |
| | Include Co-Authored-By | switch | Adds `Co-authored-by:` trailer to git commits | |
| | Quick Switch (Ctrl/Cmd+Tab) | radio | Workspaces vs Agents | |
| | Auto-advance after archive | radio | Next / Prev / Close | |
| | Default Mode (new agent) | radio | Agent / Plan | |
| | Preview Mode (artifactPreview) | radio | New window / Right sidebar | |
| | Expand tool calls by default | switch | Tool-block collapsed vs expanded | |
| | Show tool steps in IM channels | switch | Whether bot-reply surfaces include tool-call sub-steps | |
| | Tool execution limit | number input | Soft pause when one turn exceeds N tool calls | |
| | Keep System Awake (preventSleep) | switch | While Agent works | |
| | Network Proxy | proxy block | System / Manual; URL input + test button + scheme validation | |
| | Chat Settings (sub-section) | composite | Theme brightness, interface style, glass effects, font face, font size, chat width | |
| |
| **Key insight**: reference does NOT split "system-level" toggles |
| (autoLaunch / preventSleep / notifications / proxy / closeWindowAction) |
| into a separate System tab. They live alongside chat/agent toggles in |
| ONE long Preferences page. |
| |
| ### 3.2 System |
| |
| Title only. No fields. Placeholder for future use. The page exists in |
| the nav but its body is intentionally empty / "to be defined." Confirmed |
| by walking the bundle. |
| |
| ### 3.3 Profile |
| |
| Two sections: |
| - **Avatar**: glyph (first char or emoji) + background color (preset |
| palette of ~11 tones) |
| - **Account & Subscription**: email (copy), Account UID (copy), |
| product UUID (copy), subscription tier (read-only), pricing-page link, |
| logout |
| |
| ### 3.4 Appearance (`appearance` i18n key — actually rendered inside |
| Preferences in production) |
| |
| | Control | Type | Options | |
| |--------------------------|----------|-----------------------------------------------------------------| |
| | Interface theme | select | System pref / Light / Dark / Light Glass / Light Clear (win) / Dark Glass / Dark Clear (win) / Classic Dark / Parchment Light / Parchment Dark / From editors | |
| | Light variant | select | Per-mode theme | |
| | Dark variant | select | Per-mode theme | |
| | Workspace icon in sidebar| switch | Project glyph in the sidebar workspace list | |
| | Always expand to-do list | switch | Full vs compact to-do view | |
| |
| ### 3.5 Keyboard |
| |
| - Search field across all shortcuts |
| - Per-action row with primary + alternative binding |
| - "Reset all to defaults" |
| - Categories: General / Chats (workspaces) / Agents |
| - General: Show shortcuts / Open settings / Toggle sidebar / Undo archive |
| - Chats: Quick switch |
| - Agents: Create new task / Search all tasks / Search in current task / |
| Prev tab / Next tab / Focus input / Toggle input focus / Send / New line |
| |
| ### 3.6 VM (Secure workspace) |
| |
| Brief description: "dedicated space on your computer for running tasks |
| — faster, more reliable, on-device." Enable/disable toggle. |
| |
| ### 3.7 Experimental |
| |
| Beta feature toggles. Per-flag rows; roster managed in the renderer |
| component, not visible as a literal array in the bundle. |
| |
| ### 3.8 Permissions |
| |
| "System permissions QoderWork needs on this Mac." Capability rows |
| (filesystem / network / mic / screen recording / accessibility) with |
| "granted / not granted" status and a "request" CTA. |
| |
| ### 3.9 Connector |
| |
| Integrations with external apps. Builtin connectors / market connectors |
| / custom connectors. Each row: brand glyph, status, enable toggle, |
| "configure" button. |
| |
| ### 3.10 App Snapshot |
| |
| macOS-only. Frontmost-app screenshot capture for chat context. Needs |
| Accessibility + Screen Recording perms. Permission status row + capture |
| preview. |
| |
| --- |
| |
| ## 4. Repeating visual patterns inside a page |
| |
| Reference does NOT use bordered card containers around groups of |
| controls. The default presentation is a **flat row list inside the |
| `max-w-3xl` column**. |
| |
| ### 4.0 Content-column padding — WAWQAQ msg `2c810f2d` 2026-06-23 |
| |
| WAWQAQ called out the left/right whitespace as visibly wider in |
| reference than in Maka. Concrete numbers from a second RE pass: |
| |
| - The content column is `mx-auto max-w-3xl pt-10 pb-16` (= 768px wide, |
| 40px top, 64px bottom). No explicit `px-N` is applied inside the |
| column — the side whitespace comes from the column NOT filling the |
| right pane. |
| - At the typical desktop window width (~1280px viewport, 256px nav |
| rail), the right pane is ~1024px. A 768px centered column leaves |
| ~128px of whitespace on each side. That's the "wider padding" effect. |
| - Inside each row, padding is `px-5 py-4` (20px / 16px). Rows do NOT |
| carry their own border, background plate, or shadow — separation is |
| pure spacing. |
| |
| **Maka delta found 2026-06-23**: |
| - `.settingsStructuredPage` had `gap: 16px` but NO `max-width` / `margin: 0 auto` — rows stretched to fill the right pane. Fixed to `max-width: 768px; margin: 0 auto; padding: 40px 24px 64px`. |
| - `.settingsFormRow` had `border-bottom: 1px solid var(--border)` and `padding: 6px 0` — both wrong. Reference uses spacing-only and `px-5 py-4`. Fixed to `padding: 16px 20px`, no border-bottom. |
| - `.settingsRow` was sharing `.providerCard` chrome (bordered, tinted, lifted). Provider cards keep their chrome (they ARE cards); `.settingsRow` flattened to a flex row. |
| - Label was 12px / 600 weight; bumped to 14px / 500. Sub-text 11px → 12px. Matches reference `text-sm font-medium` + `text-xs text-text-quaternary`. |
| |
| ### 4.1 Row |
| |
| ``` |
| flex items-center gap-3 px-4 py-3 /* group */ |
| ├── label column |
| │ ├── truncate text-sm font-medium text-text (title) |
| │ └── mt-0.5 truncate text-xs text-text-quaternary (hint) |
| └── control (right-aligned) |
| ``` |
| |
| - No border / no card background per row by default |
| - Visual separation between rows is achieved by spacing alone (no |
| border-bottom) |
| - Hover state moves via the parent `.group` (e.g., shows a kebab menu) |
| |
| ### 4.2 Sub-section heading inside a tab |
| |
| ``` |
| text-sm font-semibold text-text |
| mb-4 |
| ``` |
| |
| ### 4.3 Switch |
| |
| - ~20×20px wrapper, `rounded-md` |
| - On: `bg-primary/20 ring-1 ring-primary/40 scale-[0.97]` |
| - Off: subtle gray fill (`bg-gray-100 dark:bg-neutral-600`) with inset shadow |
| - Transition: `transition-all duration-200` |
| |
| ### 4.4 Input |
| |
| ``` |
| w-full px-3 py-2 text-sm bg-background border rounded-md |
| border-border-tertiary/80 |
| focus:outline-none focus:ring-2 focus:ring-primary/50 |
| ``` |
| - Error: `border-error-border` |
| - Password / icon suffix: `pr-9` |
| |
| ### 4.5 Button |
| |
| - Primary: `bg-primary text-primary-foreground` |
| - Secondary: `bg-muted text-foreground` |
| - Outline: `border border-border text-foreground hover:bg-muted` |
| - Destructive: `text-error hover:bg-error-bg` |
| - Icon-only sizes: `size-7 rounded-md` (28px square), `size-8 rounded-full` (32 round) |
| |
| ### 4.6 Chip / badge |
| |
| ``` |
| rounded bg-fill-tertiary px-1.5 py-0.5 text-[10px] font-medium text-text-tertiary |
| ``` |
| |
| ### 4.7 Content scroll |
| |
| The page body owns its scroll: |
| ``` |
| min-h-0 flex-1 overflow-y-auto scrollbar-none |
| ``` |
| Custom scrollbar is hidden. The inner content column has |
| `pb-16` bottom padding so the last row never hugs the modal edge. |
| |
| --- |
| |
| ## 5. Tokens used inside Settings |
| |
| | Token | Value | |
| |----------------------------------|----------------------------------------------------------------| |
| | `--agents-content-area-bg` | `var(--color-bg-container)` | |
| | `--agents-content-area-gap` | `4px` | |
| | `--agents-content-area-radius` | `12px` | |
| | `--agents-layout-bg` | `var(--surface-canvas)` (flat neutral shell — **DO NOT** paint a 172deg gradient here, see warning below) | |
| | `--settings-nav-row-selected-bg` | `var(--color-fill-secondary)` | |
| |
| > ⚠️ **DO NOT paint a 172deg gradient on the layout/shell background.** |
| > |
| > The RE notes here historically said `--agents-layout-bg` is |
| > `linear-gradient(172deg, var(--color-fill-tertiary) 19.61%, var(--color-bg-container) 81.35%)`. That value was an **artifact of the bundle CSS we copied**, not what the live reference product actually paints. |
| > WAWQAQ has called this out four times in a row (msgs `1e693dee` / |
| > `5d3b10e5` / `486b5611` / `4a1b8c13`) — "谁让你他妈的用渐变的啊？ |
| > 参考实现就没有啊". Every time we re-added the gradient because |
| > some atlas/RE note claimed it was canon. |
| > |
| > Source-side enforcement: `apps/desktop/src/main/__tests__/chat-chrome-no-gradient-contract.test.ts` fails if any of `.appFrame`, `html[data-os="darwin"] .maka-session-panel`, or the floating panel reintroduces a gradient / border-right / smaller-than-12px radius. If a future RE iteration finds a *new* place where the reference product genuinely does paint a gradient, please update the contract test with the new exception in the same PR, don't silently lift the assertion. |
| > |
| > Use a **flat neutral shell** (`var(--surface-canvas)`) behind the |
| > white content surface. Do not collapse the shell to the same white |
| > as the content card: that removes the visible lower radius and lets |
| > the bug come back even without a border or gradient. |
| > |
| > Rendered-pixel enforcement: after capturing |
| > `sidebar-long-sessions/light-1280-motion`, run |
| > `npm --workspace @maka/desktop run screenshots:chat-chrome:check`. |
| > It verifies the actual PNG has a visible shell/content delta, no dark |
| > one-pixel seam, and readable bottom surface corners. |
| > |
| > Surface radius is **12px** (was historically noted as 6px). 6px was |
| > geometrically there but optically invisible — bottom corners of the |
| > floating content card didn't read against a same-color shell. |
| |
| Color tokens consumed inside settings: |
| - `--color-text` (primary text) |
| - `--color-text-secondary` |
| - `--color-text-tertiary` (hints) |
| - `--color-text-quaternary` (de-emphasized) |
| - `--color-border` (strong divider) |
| - `--color-border-tertiary` (input borders) |
| - `--color-fill-secondary` (active row fill) |
| - `--color-fill-tertiary` (chip background) |
| - `--color-bg-container` (page surface) |
| - `--color-primary`, `--color-primary/20`, `--color-primary/40` (focus, switch on, ring) |
| |
| --- |
| |
| ## 6. Routing, state, behaviors |
| |
| - Active tab is stored in the URL: `?view=settings&tab=preferences`. |
| No localStorage for the active tab — round-tripping the URL restores |
| the page. |
| - Deeplink scheme: external triggers can deep-link to a specific tab: |
| `qoder-work://settings/preferences`. Maka's equivalent could be |
| `maka://settings/<tab>`. |
| - Default tab when opened with no `tab` param: `preferences`. |
| - Modal close is escape-key + click-outside backdrop; focus is trapped |
| inside `[role="dialog"]`. |
| - Telemetry: `settings_tab_view` fires when a tab is selected; |
| `settings_heartbeat` ticks every 300s with a feature-flag snapshot. |
| - Saves: per-control, no explicit batch / "save" button visible. |
| Renderer dispatches IPC writes per change; toasts surface failures. |
| |
| --- |
| |
| ## 7. Implications for Maka |
| |
| This RE matters because WAWQAQ's ask — "add a 系统设置 section" — is |
| ALMOST CORRECT but the deeper truth from the reference is: |
| |
| **Reference does NOT scatter system-level toggles into their own |
| narrow pages.** It collapses them into ONE long `Preferences` page, |
| and reserves a near-empty `system` tab for future expansion. |
| |
| Maka today has 17 nav items in Settings (some of them — `网络`, |
| `健康`, `开放网关`, `语音模型`, `每日回顾`, `记忆` — are single-purpose |
| pages that mirror exactly the "wasteful single-purpose page" pattern |
| WAWQAQ flagged for `网络`). |
| |
| The closer-to-reference move is to **consolidate**, not add another |
| section. Concrete proposal: |
| |
| ### Proposed consolidated Maka Settings nav (target: ~9 items) |
| |
| | Group | Item | Holds | |
| |-------------|-------------|------------------------------------------------------------| |
| | 基础 | 通用 | Aggregator: 隐身模式, 启动行为, 新对话模式, 默认模型, 通知, 网络代理, 保持唤醒, 自动更新, 关闭窗口行为 | |
| | 基础 | 外观 | 个性化 + theme + palette + font (merge 主题 + 个性化) | |
| | AI | 模型 | Provider connections + OAuth + per-model config | |
| | AI | 记忆与回顾 | Merge `记忆` + `每日回顾` | |
| | AI | 语音与网关 | Merge `语音模型` + `开放网关` | |
| | 集成 | 机器人对话 | Telegram / WeChat / Slack bot config | |
| | 集成 | 联网搜索 | Tavily provider config | |
| | 数据/系统 | 数据 | Export / import / wipe | |
| | 数据/系统 | 权限与能力 | Capability toggles + filesystem allowlist | |
| | 其他 | 健康 | Diagnostic / status / logs | |
| | 其他 | 关于 | Version + license + acknowledgements | |
| |
| Specifically: **drop the standalone `网络` page; move proxy into 通用**. |
| That's the minimum WAWQAQ asked for, but ride the same PR to merge |
| `主题 + 个性化` into `外观` per reference, since 外观 is reference's |
| canonical name for that grouping. |
| |
| ### Settings page-body recipe to copy |
| |
| For ANY settings page body, switch to: |
| - `max-w-3xl mx-auto pt-10 pb-16` inner column |
| - Flat row list (`flex items-center gap-3 px-4 py-3` per row) |
| - `text-sm font-medium` title + `text-xs text-text-quaternary` hint |
| - No bordered card around row groups |
| - Sub-section heading: `text-sm font-semibold mb-4` |
| - Switches / inputs / chips per §4 above |
| |
| This is the visual "reference 真好看" pattern WAWQAQ asked us to study — |
| the page is uncluttered because rows have NO chrome, only spacing. |
| |
| --- |
| |
| ## 8. PR plan suggestion |
| |
| Two PRs, ship in sequence: |
| |
| **PR-SETTINGS-ALIGN-IA-0** — Information architecture consolidation |
| - Drop standalone `网络` page; fold proxy into a "网络代理" sub-section of 通用 |
| - Merge `主题 + 个性化` → `外观` |
| - Merge `记忆 + 每日回顾` → `记忆与回顾` |
| - Merge `语音模型 + 开放网关` → `语音与网关` |
| - Update SETTINGS_NAV + section render switch + all deeplinks (`maka://settings/...`) |
| - Pin via contract test: nav id allowlist + deeplink mapping |
| |
| **PR-SETTINGS-PAGE-BODY-0** — Visual pattern conversion |
| - Convert every page body from `settingsStructuredPage / SettingRow` |
| card chrome to the flat-row + `max-w-3xl` recipe |
| - Add `.maka-settings-row`, `.maka-settings-page` primitives in styles.css |
| - Sweep all SettingsPage components to use them |
| |
| Tackle them in this order so the IA stops shifting while we're polishing |
| the bodies. |
