feat: implement core routing architecture with hybrid strategy

[MyPrototypeWhat]

Summary

This PR implements the core routing architecture for Cherry Studio, with comprehensive research on Tab System + Router integration patterns.

Architecture Research

We identified a fundamental contradiction between URL Router design (single active view) and Tab system requirements (multiple views coexisting with state preservation). Three architecture approaches were documented:

Approach	Document	Status
Single HashRouter + Outlet + KeepAlive	architecture-single-outlet.md	Research Complete
Multi MemoryRouter Instances	architecture-multi-memory-router.md	Recommended & Implemented
MPA + Multi WebContents	architecture-mpa-webcontents.md	Research Complete

Key Requirements

Requirement	Priority	Description
No flicker on switch	P0	UI responds instantly on Tab switch
State preservation	P0	Scroll position, input content, etc.
Tab detach to window	P1	Similar to Chrome/VS Code
Tab attach (drag back)	P1	Drag window back to main tab bar
Memory control	P1	Support LRU eviction for inactive Tabs

Current Implementation

1. TanStack Router Integration

   • File-based routing structure (routes/__root.tsx, routes/index.tsx, routes/settings.tsx)
   • Auto-generated route tree (routeTree.gen.ts)
   • Fixed path configuration using resolve() for absolute paths

2. Multi MemoryRouter Architecture

   • TabRouter component with React 19 <Activity> for KeepAlive
   • Each Tab has independent MemoryRouter instance
   • State fully preserved on Tab switch

3. Tab State Management

   • useTabs hook with openTab API for Tab-level navigation
   • useNavigate for in-Tab navigation
   • Persisted via localStorage cache

4. Developer Documentation

   • routes/README.md - English developer guide
   • routes/README.zh-CN.md - Chinese developer guide

Files Changed

src/renderer/src/
├── routeTree.gen.ts                 # Auto-generated route tree
├── routes/
│   ├── __root.tsx                   # Root route (renders Outlet)
│   ├── index.tsx                    # Home page placeholder
│   ├── settings.tsx                 # Settings page placeholder
│   ├── README.md                    # Developer guide (EN)
│   └── README.zh-CN.md              # Developer guide (CN)
├── hooks/
│   └── useTabs.ts                   # Tab state management with openTab API
└── components/layout/
    ├── AppShell.tsx                 # Main layout (Sidebar + TabBar + Content)
    ├── TabRouter.tsx                # Tab router container (MemoryRouter + Activity)
    ├── architecture-single-outlet.md
    ├── architecture-multi-memory-router.md
    ├── architecture-mpa-webcontents.md
    └── router-planning.md

TODO List

Feature 1: Multi-Tab Core ✅

• TabRouter component with React 19.2 <Activity> for visibility control
• createMemoryHistory + createRouter per Tab instance
• useTabs hook enhancement with openTab API (add/remove/switch/update)
• Tab state types definition (Tab, TabType, OpenTabOptions)
• Developer documentation (README.md, README.zh-CN.md)

Feature 2: Route Pages (In Progress)

• Chat routes (/chat/$assistantId/$topicId)
• Settings routes placeholder (/settings)
• Knowledge base pages
• Notes pages
• Other feature pages

Feature 3: Tab Detach (Drag Out to Window)

• URL Query state serialization (path + scroll + form state)
• DetachedTabWindow component (read URL Query, init MemoryRouter)
• Main process window creation (BrowserWindow with query params)
• Drag event handling and window positioning

Feature 4: Tab Attach (Drag Back to Main)

• Drop zone detection on main window tab bar
• IPC state transfer protocol (tab:attach-request / tab:attach-response)
• Window close coordination after successful attach
• Tab insertion position handling

Feature 5: Memory Management

• LRU eviction strategy for inactive tabs
• State persistence before eviction (localStorage/IndexedDB)
• Lazy recovery on tab reactivation
• Memory usage monitoring

🤖 Generated with Claude Code

Co-Authored-By: Claude [email protected]

[0xfullex]

Note

This issue/comment/review was translated by Claude.

URL → DB: Listens to location.pathname and updates active tab's URL in SQLite

This is a typical Cache behavior, not a DB behavior. Interacting with the DB brings unnecessary complexity.

---

Original Content

URL → DB: Listens to location.pathname and updates active tab's URL in SQLite

这是个典型的 Cache 行为，而不是 db行为，和db交互，带来了没必要的复杂化

[MyPrototypeWhat]

URL → DB: Listens to location.pathname and updates active tab's URL in SQLite

This is a typical Cache behavior, not a DB behavior. Interacting with the DB brings unnecessary complexity.

Note

This issue/comment/review was translated by Claude.

The top tabs need to be stored so that when users reopen the application, these tabs are retained, similar to browser tabs. I was struggling between using db or cache... I'll change it.

---

Original Content

顶部的Tab是需要做存储的,这样用户重新打开应用会保留这些Tab,行为类似浏览器tab
在用db还是cache纠结了...我改一下

[0xfullex]

URL → DB: Listens to location.pathname and updates active tab's URL in SQLite\r\n> \r\n> > This is a typical Cache behavior, not a DB behavior. Interacting with the DB brings unnecessary complexity.\r\n> \r\n> > [!NOTE]\r\n> > This issue/comment/review was translated by Claude.\r\n> \r\n> > The top tabs need to be stored so that when users reopen the application, these tabs are retained, similar to browser tabs. I was struggling between using db or cache... I'll change it.\r\n> \r\n> > ---\r\n> >

\r\n> >

Original Content

\r\n> > 顶部的Tab是需要做存储的,这样用户重新打开应用会保留这些Tab,行为类似浏览器tab\r\n> > 在用db还是cache纠结了...我改一下\r\n> >

\r\n\r\n> [!NOTE]\r\n> This issue/comment/review was translated by Claude.\r\n\r\nYou can use cache with persist. This is a typical use case for cache data:\r\n- Active tab inherently doesn't need synchronization (each terminal may have its own active tab),\r\n- It doesn't matter if this state is reset or lost (users don't care or can easily reset it)\r\n\r\n---\r\n

\r\n

Original Content

\r\n\r\n用带persist的cache就行，这个是cache数据的典型用法之处：\r\n- active tab本来就是个无需同步（各个终端可能有用户自己的active），\r\n- 该状态重置或丢失了没有关系（用户不在意也可以easily重置的）\r\n\r\n

[0xfullex]

Note

This issue/comment/review was translated by Claude.

There are naming conventions for cache keys. I've updated ESLint, you can adjust it further.

---

Original Content

cache key的命名有规范，我更新了ESLint，可以再调整下

[MyPrototypeWhat]

Note

This issue/comment/review was translated by Claude.

There are naming conventions for cache keys. I've updated ESLint, you can adjust it further.

ok

---

Original Content

cache key的命名有规范，我更新了ESLint，可以再调整下

ok

[MyPrototypeWhat]

Note

This issue/comment/review was translated by Claude.

Testing TSR + Tab + Multi MemoryRouter + Keepalive

20251205-170641.mp4

---

Original Content

测试 TSR + Tab + Multi MemoryRouter + Keepalive

20251205-170641.mp4