Merge origin/main into refactor/topview-retirement

- Settings window removal (#16489): drop SettingsApp's host mount; the settings
  page now renders inside the main window, already host-covered.
- Composer focus-restore (#16733): reimplement over the popup track — add
  ConfirmPopupProps.focusOnClose (Radix onCloseAutoFocus + preventDefault) and
  route WebSearchButton through it, replacing the afterClose + requestAnimationFrame
  focus race.
- Re-apply the window.toast/window.modal -> toast/popup codemod onto upstream's
  moved/renamed files (Appearance/Dependencies/System settings, MCP, paintings,
  knowledge) and SystemSettings' new call sites.

Author: 0xfullex

DESIGN.md

@@ -604,15 +604,14 @@ Source: `Switch` and `DescriptionSwitch` from `@cherrystudio/ui` (`packages/ui/s
 - **Top chrome height**: `var(--app-top-chrome-height)` = 44px. Use this for the main window tab bar and any standalone macOS window top drag area that should visually align with the main app chrome.
 - **Navbar content height**: `var(--navbar-height)` defaults to `var(--app-top-chrome-height)` for the fixed top-menu layout. Only override it for inner content calculations that intentionally do not include a top navbar.
 - Settings-style floating windows with a transparent macOS shell must keep the outer top inset tied to `var(--app-top-chrome-height)` instead of hard-coded pixel classes such as `h-11` or `h-[50px]`.
-- **Settings window sizing** (standalone settings window only): sized to 80% of the main window with a hard floor of 760×560 and a 1280px max width, centered on the main window. The 760×560 floor keeps the ~200px sidebar plus the detail column usable when the user shrinks the main window; the 1280px ceiling prevents 2K/4K displays from stretching settings into empty space. Canonical implementation: `SettingsWindowService` in `src/main/services/SettingsWindowService.ts`.
 
 ### Settings Panel Layout
 
-Settings pages (both the in-app `/settings` route and the standalone settings window) share the same two-column shape:
+Settings pages use the same two-column shape:
 
 | Column | Width | Composition |
 |---|---|---|
-| Left submenu | `var(--settings-width)` (200px in the standalone window, 250px default in `responsive.css`) | `PageHeader` (title) → `Scrollbar` → `MenuList` of grouped `MenuItem` rows |
+| Left submenu | `var(--settings-width)` (250px default in `responsive.css`) | `PageHeader` (title) → `Scrollbar` → `MenuList` of grouped `MenuItem` rows |
 | Right detail | `flex-1` | Page-owned content |
 
 Submenu composition rules:

docs/references/command/README.md

@@ -102,8 +102,7 @@ keeps only `ShortcutPreferenceKey` + `ResolvedShortcut`.
 | `menus.tsx` | `CommandContextMenu` — renders Cherry UI or a native popup based on `menu.presentation_mode` |
 
 Mount `<ContextKeyProvider><CommandProvider>` once per renderer window — every
-window root mounts it: `windows/main/MainApp.tsx`,
-`windows/settings/SettingsApp.tsx`, and `windows/subWindow/SubWindowApp.tsx`.
+window root mounts it: `windows/main/MainApp.tsx` and `windows/subWindow/SubWindowApp.tsx`.
 
 ### Preferences
 

docs/references/knowledge/experiment/knowledge-technical-design.md

@@ -157,9 +157,7 @@ A vector base's `knowledge_base.embeddingModelId` / `dimensions` must be valid t
 
 ### 6.1 search() wiring and retrieval tuning
 
-`searchMode` / `hybridAlpha` / `documentCount` / `threshold` are all **base-level configuration** (`knowledge_base` columns) for now; `search()` reads them from the base row (result cap `documentCount ?? 10`).
-
-> **Decision note (2026-06-10)**: `hybridAlpha` describes whether a base's corpus leans lexical or semantic — a stable property of the base, not something the model should guess per call — so it stays a base column with the RagConfig slider (configurable only in hybrid mode; cleared when `searchMode` moves away). `threshold` only applies to relevance-scored hits (vector mode, or after rerank) and is a no-op for BM25/RRF ranking scores (`applyRelevanceThreshold` in `utils/search.ts`). Researched and decided, but **deferred to a later PR**: `topK` / `threshold` become per-call knobs (`KnowledgeSearchOptions`, exposed through `kb__search` arguments and REST `top_k`), and the `documentCount` column is removed with them. That refactor was implemented during PR A's development and then deliberately carved out to keep PR A reviewable; it will be re-done on top of the merged PR A in the per-call-tuning PR — the paragraph above records the agreed design so nothing depends on any developer-local state.
+`documentCount` and `threshold` are the base-level retrieval tuning columns left; `search()` reads `documentCount` from the base row as the result cap (`documentCount ?? 10`) and applies `threshold` as a relevance cutoff on scored hits (`applyRelevanceThreshold` in `utils/search.ts` — it filters vector-mode or post-rerank relevance scores and is a no-op for BM25/RRF ranking scores). Retrieval mode is derived at runtime: bases with a completed vector config use hybrid retrieval, and bases without an embedding model fall back to BM25.
 
 ### 6.2 Legacy result shape mapping
 
@@ -185,5 +183,5 @@ A vector base's `knowledge_base.embeddingModelId` / `dimensions` must be valid t
   - Startup-recovery cross-cancellation: a crash-recovered delete-subtree job and the `recoverDeletingItems` re-enqueue get different idempotency keys and cancel each other via roots-intersection (`jobTouchesSubtree`); cancel only jobs whose roots are fully covered by the current job's roots.
   - Hybrid search runs its two lanes as independent read snapshots; a rebuild committing between them can transiently return both copies of a chunk — close with a shared read transaction or a second dedupe by material id + unit index.
   - The per-base index driver's `close()` no longer needs to take a write mutex: better-sqlite3 uses one synchronous, persistent connection and per-base writes are serialized by `KnowledgeLockManager.withBaseMutationLock(baseId)`, so there is no driver-level async write mutex to race — shutdown safety rests on JobManager draining before the store service stops.
-  - Retrieval-surface follow-ups (PR C): the `searchMode` `default`→`vector` rename is externally visible through the gateway's pass-through base entity, and a permanent open failure (legacy layout) currently maps to a retryable 503.
+  - Retrieval-surface follow-ups (PR C): permanent open failure for a legacy layout currently maps to a retryable 503.
 - PR A's full test matrix and risk notes live in this repo's test suites (`src/main/features/knowledge/**/__tests__`) and the PR #15973 description.

docs/references/knowledge/knowledge-service.md

@@ -165,7 +165,7 @@ Current persisted `knowledge_base` columns include:
 
 - `groupId`: nullable group assignment; `null` means ungrouped.
 - `embeddingModelId`: the embedding model; `null` for BM25-only bases.
-- `dimensions`: positive embedding vector width for vector-capable bases; `null` for BM25-only completed bases (no embedding model) and for failed migrated bases with unknown dimensions. On a completed base it is paired with `embeddingModelId` — both set, or both `null` with `searchMode` forced to `bm25` (enforced by the DB CHECK and the entity schema).
+- `dimensions`: positive embedding vector width for vector-capable bases; `null` for BM25-only completed bases (no embedding model) and for failed migrated bases with unknown dimensions. On a completed base it is paired with `embeddingModelId` — both set, or both `null` for BM25-only retrieval (enforced by the DB CHECK and the entity schema).
 - `status`: `completed` for runnable bases, `failed` for recoverable base-level migration failures.
 - `error`: nullable `KnowledgeBaseErrorCode`; currently `missing_embedding_model` for recoverable failed bases.
 
@@ -260,11 +260,12 @@ Search is executed by `KnowledgeService.search(baseId, query)`:
 
 1. Reject failed bases.
 2. Reject queries without searchable tokens.
-3. Resolve the base's `searchMode` (`vector` / `bm25` / `hybrid`) and embed the query — skipped for `bm25`, which is lexical only.
-4. Call `KnowledgeIndexStore.search` on the base's per-base index store with an over-fetched candidate limit (`topK × overfetch`, capped). The store runs the BM25 lane (`search_text_fts`, with a LIKE fallback for short CJK tokens), the brute-force vector lane, or fuses both with RRF (`hybridAlpha`).
+3. Derive the retrieval mode from the base config and embed the query only for embedding-backed bases. Bases without an embedding model search BM25 only; embedding-backed bases use hybrid retrieval.
+4. Call `KnowledgeIndexStore.search` on the base's per-base index store with an over-fetched candidate limit (`topK × overfetch`, capped). The store runs the BM25 lane (`search_text_fts`, with a LIKE fallback for short CJK tokens) or fuses BM25 and brute-force vector results with RRF.
 5. Filter results whose source items are missing, outside the base, or `deleting`, then trim to `documentCount ?? 10`.
 6. Rerank when `base.rerankModelId` is configured.
-7. Apply relevance threshold (a no-op for `ranking`-kind scores) and assign ranks.
+7. Apply `threshold` only to results whose `scoreKind` is `relevance`; BM25/hybrid `ranking` scores pass through.
+8. Assign ranks.
 
 Current `KnowledgeSearchResult` includes:
 

docs/references/renderer-architecture.md

@@ -60,7 +60,7 @@ Target layout (in-flight directories pending migration are listed in §8):
 
 ```text
 src/renderer/
-├── windows/      # App      — per-window entry roots (MainApp/SettingsApp/SubWindowApp) + shell
+├── windows/      # App      — per-window entry roots (MainApp/SubWindowApp) + shell
 ├── routes/       # App      — route definitions
 ├── pages/        # App      — cross-domain shell pages only (domain pages live in features)
 ├── features/     # Domain   — one business domain per dir

docs/references/window-manager/window-manager-usage.md

@@ -12,7 +12,7 @@ In `types.ts`:
 export enum WindowType {
   Main = 'main',
   // ... existing types
-  Settings = 'settings',  // <-- add your new type
+  MyWindow = 'myWindow',  // <-- add your new type
 }
 ```
 
@@ -21,11 +21,11 @@ export enum WindowType {
 In `windowRegistry.ts`:
 
 ```typescript
-WINDOW_TYPE_REGISTRY[WindowType.Settings] = {
-  type: WindowType.Settings,
+WINDOW_TYPE_REGISTRY[WindowType.MyWindow] = {
+  type: WindowType.MyWindow,
   lifecycle: 'singleton',
-  htmlPath: 'settings.html',
-  // preload omitted → defaults to 'preload.js'
+  htmlPath: 'windows/myWindow/index.html',
+  // preload omitted → defaults to 'index.js'
   // showMode omitted → defaults to 'auto'
   windowOptions: {
     ...DEFAULT_WINDOW_CONFIG,
@@ -46,31 +46,31 @@ import { WindowType } from '@main/core/window/types'
 const wm = application.get('WindowManager')
 
 // open() is lifecycle-aware — handles singleton reuse, pool recycle, etc.
-const windowId = wm.open(WindowType.Settings)
+const windowId = wm.open(WindowType.MyWindow)
 ```
 
 ### 4. Inject domain behavior via `onWindowCreatedByType`
 
 ```typescript
 // In your domain service's onInit():
 const wm = application.get('WindowManager')
-wm.onWindowCreatedByType(WindowType.Settings, ({ window, id }) => {
+wm.onWindowCreatedByType(WindowType.MyWindow, ({ window, id }) => {
   // Store the windowId for later use
-  this.settingsWindowId = id
+  this.myWindowId = id
 
   // Attach event listeners BEFORE content loads
   window.on('closed', () => {
-    this.settingsWindowId = undefined
+    this.myWindowId = undefined
   })
 })
 ```
 
 The example above uses **destructuring**. An equivalent using the `mw` shorthand (useful when the callback body is long or accesses many fields):
 
 ```typescript
-wm.onWindowCreatedByType(WindowType.Settings, (mw) => {
-  this.settingsWindowId = mw.id
-  mw.window.on('closed', () => { this.settingsWindowId = undefined })
+wm.onWindowCreatedByType(WindowType.MyWindow, (mw) => {
+  this.myWindowId = mw.id
+  mw.window.on('closed', () => { this.myWindowId = undefined })
 })
 ```
 
@@ -83,30 +83,30 @@ The `onWindowCreated` event is the canonical hook for domain services to inject
 ### The Pattern
 
 ```typescript
-@Injectable('SettingsService')
+@Injectable('MyWindowService')
 @ServicePhase(Phase.WhenReady)
-export class SettingsService extends BaseService {
-  private settingsWindowId: string | undefined
+export class MyWindowService extends BaseService {
+  private myWindowId: string | undefined
 
   protected override onInit(): void {
     const wm = application.get('WindowManager')
 
-    wm.onWindowCreatedByType(WindowType.Settings, ({ window, id }) => {
+    wm.onWindowCreatedByType(WindowType.MyWindow, ({ window, id }) => {
       // 1. Store the windowId
-      this.settingsWindowId = id
+      this.myWindowId = id
 
       // 2. Attach listeners BEFORE content loads
       window.once('ready-to-show', () => {
-        this.sendInitialConfig(window)
+        this.sendInitialData(window)
       })
 
       window.on('closed', () => {
-        this.settingsWindowId = undefined
+        this.myWindowId = undefined
       })
     })
 
-    wm.onWindowDestroyedByType(WindowType.Settings, () => {
-      this.settingsWindowId = undefined
+    wm.onWindowDestroyedByType(WindowType.MyWindow, () => {
+      this.myWindowId = undefined
     })
   }
 }
@@ -130,7 +130,7 @@ For subscriptions that only care about a single window type (the typical consume
 It's tempting to attach listeners inline after `wm.open()` returns, since the ID is right there:
 
 ```typescript
-const id = wm.open(WindowType.Settings)
+const id = wm.open(WindowType.MyWindow)
 const window = wm.getWindow(id)!
 window.on('blur', this.hideIfUnpinned)
 window.once('closed', () => { this.windowId = null })
@@ -151,9 +151,9 @@ The `onWindowCreatedByType` / `onWindowDestroyedByType` listeners receive a `Man
 **Destructuring (recommended default, short callback):**
 
 ```typescript
-wm.onWindowCreatedByType(WindowType.Settings, ({ window, id }) => {
-  this.settingsWindowId = id
-  window.on('closed', () => { this.settingsWindowId = undefined })
+wm.onWindowCreatedByType(WindowType.MyWindow, ({ window, id }) => {
+  this.myWindowId = id
+  window.on('closed', () => { this.myWindowId = undefined })
 })
 ```
 
@@ -199,6 +199,19 @@ WindowManager exposes four lifecycle methods, arranged in two layers:
 
 **Why `destroy()` is not a consumer API.** On non-pooled windows (default and singleton) `close()` falls through to the same `destroyWindow()` call — there is no behavioral difference. On pooled windows, `destroy()` bypasses the pool, which is almost never what a consumer actually wants; the correct API for "stop the whole pool" is `suspendPool(type)`, which destroys idle windows and prevents further recycling without touching in-use windows.
 
+### Consumer-loaded windows (`htmlPath: ''`)
+
+A registry entry with `htmlPath: ''` is **consumer-loaded**: WM wires the window (preload, behavior, bounds, lifecycle) but loads no content — the domain service loads it after `open()`. For hidden, one-shot surfaces rendering *generated* content (print / PDF, offscreen render).
+
+```typescript
+const id = wm.open(WindowType.MyPrintSurface)          // WM wires; loads nothing
+const win = wm.getWindow(id)                           // the sanctioned handle to load into
+await win?.webContents.loadURL(generatedHtmlDataUrl)   // consumer owns content + show + close()
+// ... await 'did-finish-load', e.g. webContents.printToPDF(), then wm.close(id)
+```
+
+`getWindow(id)` is the one exception to "consumers only call `open()` / `close()`" — use it only for `webContents` loading (payload encoding is the consumer's call). Main-initiated `loadURL` / `loadFile` is not blocked by WM's navigation guards (those only intercept renderer-initiated navigation).
+
 ### Domain-Key-to-WindowId Mapping
 
 For window types that are keyed by domain data (e.g., a topic-specific window), the domain service maintains its own mapping:

electron.vite.config.ts

@@ -25,6 +25,11 @@ const isProd = process.env.NODE_ENV === 'production'
 // pruned from production packages, the packaged app would fail at runtime with
 // MODULE_NOT_FOUND (no test catches this). See docs/references/api-gateway/README.md.
 const mainExternalDependencies = Object.keys(pkg.dependencies)
+const mainExternalModules = ['bufferutil', 'utf-8-validate', 'electron', ...mainExternalDependencies]
+
+export const isMainExternalModule = (id: string) => {
+  return mainExternalModules.some((moduleId) => id === moduleId || id.startsWith(`${moduleId}/`))
+}
 
 export default defineConfig({
   main: {
@@ -51,7 +56,7 @@ export default defineConfig({
     build: {
       lib: { entry: resolve(__dirname, 'src/main/main.ts') },
       rollupOptions: {
-        external: ['bufferutil', 'utf-8-validate', 'electron', ...mainExternalDependencies],
+        external: isMainExternalModule,
         output: {
           manualChunks: undefined, // 彻底禁用代码分割 - 返回 null 强制单文件打包
           inlineDynamicImports: true // 内联所有动态导入，这是关键配置
@@ -145,7 +150,6 @@ export default defineConfig({
       rollupOptions: {
         input: {
           index: resolve(__dirname, 'src/renderer/windows/main/index.html'),
-          settings: resolve(__dirname, 'src/renderer/windows/settings/index.html'),
           quickAssistant: resolve(__dirname, 'src/renderer/windows/quickAssistant/index.html'),
           selectionToolbar: resolve(__dirname, 'src/renderer/windows/selection/toolbar/index.html'),
           selectionAction: resolve(__dirname, 'src/renderer/windows/selection/action/index.html'),

migrations/sqlite-drizzle/0018_aberrant_shinobi_shaw.sql

@@ -0,0 +1,52 @@
+PRAGMA foreign_keys=OFF;--> statement-breakpoint
+CREATE TABLE `__new_knowledge_base` (
+	`id` text PRIMARY KEY NOT NULL,
+	`name` text NOT NULL,
+	`group_id` text,
+	`dimensions` integer,
+	`embedding_model_id` text,
+	`status` text NOT NULL,
+	`error` text,
+	`rerank_model_id` text,
+	`file_processor_id` text,
+	`chunk_size` integer NOT NULL,
+	`chunk_overlap` integer NOT NULL,
+	`chunk_strategy` text DEFAULT 'structured' NOT NULL,
+	`chunk_separator` text DEFAULT '\n\n' NOT NULL,
+	`threshold` real,
+	`document_count` integer,
+	`created_at` integer NOT NULL,
+	`updated_at` integer NOT NULL,
+	FOREIGN KEY (`group_id`) REFERENCES `group`(`id`) ON UPDATE no action ON DELETE set null,
+	FOREIGN KEY (`embedding_model_id`) REFERENCES `user_model`(`id`) ON UPDATE no action ON DELETE no action,
+	FOREIGN KEY (`rerank_model_id`) REFERENCES `user_model`(`id`) ON UPDATE no action ON DELETE set null,
+	CONSTRAINT "knowledge_base_chunk_strategy_check" CHECK("__new_knowledge_base"."chunk_strategy" IN ('structured', 'delimiter')),
+	CONSTRAINT "knowledge_base_status_check" CHECK("__new_knowledge_base"."status" IN ('completed', 'failed')),
+	CONSTRAINT "knowledge_base_status_error_check" CHECK(
+        (
+          "__new_knowledge_base"."status" = 'completed'
+          AND "__new_knowledge_base"."error" IS NULL
+          AND (
+            (
+              "__new_knowledge_base"."embedding_model_id" IS NOT NULL
+              AND "__new_knowledge_base"."dimensions" IS NOT NULL
+              AND "__new_knowledge_base"."dimensions" > 0
+            )
+            OR (
+              "__new_knowledge_base"."embedding_model_id" IS NULL
+              AND "__new_knowledge_base"."dimensions" IS NULL
+            )
+          )
+        )
+        OR (
+          "__new_knowledge_base"."status" = 'failed'
+          AND "__new_knowledge_base"."error" IS NOT NULL
+          AND length(trim("__new_knowledge_base"."error")) > 0
+        )
+      )
+);
+--> statement-breakpoint
+INSERT INTO `__new_knowledge_base`("id", "name", "group_id", "dimensions", "embedding_model_id", "status", "error", "rerank_model_id", "file_processor_id", "chunk_size", "chunk_overlap", "chunk_strategy", "chunk_separator", "threshold", "document_count", "created_at", "updated_at") SELECT "id", "name", "group_id", "dimensions", "embedding_model_id", "status", "error", "rerank_model_id", "file_processor_id", "chunk_size", "chunk_overlap", "chunk_strategy", "chunk_separator", "threshold", "document_count", "created_at", "updated_at" FROM `knowledge_base`;--> statement-breakpoint
+DROP TABLE `knowledge_base`;--> statement-breakpoint
+ALTER TABLE `__new_knowledge_base` RENAME TO `knowledge_base`;--> statement-breakpoint
+PRAGMA foreign_keys=ON;