1
# AI Collaboration Reference: Swup Routing & Persistent Boundaries
2

3
## Context & Rules
4

5
This project uses `@swup/astro` for client-side page transitions, but several UI regions are intentionally kept outside Swup replacement to preserve state.
6

7
- **Configuration Location**: Swup is configured in `astro.config.mjs`.
8
- **Current Swup Containers**: The replacement containers should remain:
9
  - `main`
10
  - `#toc`
11
  - `#sidebar-bottom`
12
  - `#mobile-toc-container`
13
- **Do Not Add These Containers Back**:
14
  - `#navbar-wrapper`
15
  - `#sidebar`
16
- **Why Navbar Is Persistent**: `#navbar-wrapper` contains persistent interactive UI, including the BGM player, language selector, search trigger, and theme/color controls. Replacing it through Swup can reset component state and break i18n updates.
17
- **Why Sidebar Is Persistent**: The left profile card should stay mounted. Only `#sidebar-sticky` is manually synchronized when the route crosses the Docs boundary.
18

19
### Sidebar Sync Rules
20
- **Logic Location**: `src/components/widget/SideBar.astro`.
21
- **Non-Docs -> Docs** and **Docs -> Non-Docs**: Fetch the target page HTML and replace only `#sidebar-sticky`.
22
- **Docs -> Docs**: Do not fetch or replace the whole sidebar. Instead, dispatch `docs-directory:update-url` (and `category-tree:update-url` for backward compatibility) with the new pathname.
23
- **Non-Docs -> Non-Docs**: Do not touch the sidebar.
24
- **Event Coalescing**: Swup and Astro can emit multiple events for one navigation. `SideBar.astro` uses `requestAnimationFrame` to coalesce events before comparing the previous and next path. Do not remove this without replacing it with equivalent deduplication.
25

26
### DocsDirectory URL Recalculation
27
- **Logic Location**: `src/components/widget/DocsDirectory.svelte`.
28
- **Expected Behavior**: On Docs internal navigation, the persistent `DocsDirectory` receives the new URL and recalculates active/expanded state using `expandActive(categories, nextUrl)`.
29
- **Important Rule**: Keep expansion based on the active path. Do not automatically expand every folder that has an `index.md`; `index.md` means the folder is readable, not that it should always be expanded.
30
- **Completion Event**: After recalculating and awaiting Svelte `tick()`, the root tree dispatches `docs-directory:updated` (and `category-tree:updated`).
31

32
### Mobile Docs Scroll Timing
33
- **Logic Location**: `src/layouts/Layout.astro`.
34
- **Anchor**: Mobile Docs pages scroll to `#swup-mobile-scroll-target`.
35
- **Critical Sequence**: For mobile Docs internal navigation, Swup automatic reset is disabled first, then `DocsDirectory` recalculates expansion, then `docs-directory:updated` (or `category-tree:updated`) triggers the final scroll. Scrolling before the tree expands will produce incorrect positioning.
36

37
### Language Switching Must Bypass Swup
38
- **Rule**: Language switch links must use `data-no-swup`.
39
- **Affected Areas**: Top language selector, post/doc language availability links, and fallback buttons such as "this article does not exist in this language, switch to another language".
40
- **Reason**: Language switching changes persistent i18n state across Navbar, Search, DisplaySettings, date picker text, and other UI. Treat language changes as full page navigations, not Swup transitions.