From 81a62402ef6f8900ff092366121a9b7a4263ba52 Mon Sep 17 00:00:00 2001
From: Natsuu <natsukawa247@outlook.com>
Date: Fri, 27 Feb 2026 17:18:25 +0800
Subject: Restructure docs into manual/development and add implementation docs
 (#94)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary by Sourcery

Restructure documentation into separate manual and development sections,
introduce detailed internal implementation docs for auth/Java/mod
loaders, and update site navigation, landing page links, and MDX tooling
(Mermaid, card styling) to match the new structure and tech stack.

Enhancements:
- Enable Mermaid rendering support in the docs app and add a reusable
Mermaid React component.
- Refine Docs page rendering by customizing Card styling and removing
redundant in-page titles/descriptions rendered by the layout.
- Align docs source configuration and routing comments with the new
manual-based default paths.

Documentation:
- Split user-facing docs under a new manual section and move contributor
content into a dedicated development section for both English and
Chinese.
- Add comprehensive internal implementation documentation covering
authentication, Java management, mod loader/version merging, event bus,
and architecture patterns in both English and Chinese.
- Update existing feature docs (mod loaders, Java, authentication) and
getting-started/troubleshooting pages to be more conceptual, pointing to
implementation docs for technical details.
- Refresh architecture docs to reflect the React/Zustand frontend stack
and add Mermaid-based architecture diagrams.
- Adjust navigation labels, home-page CTAs, and doc links to target the
new manual/development structure and routes.

---------

Co-authored-by: 简律纯 <i@jyunko.cn>
---
 .../docs/content/en/features/authentication.mdx    | 266 ---------------------
 1 file changed, 266 deletions(-)
 delete mode 100644 packages/docs/content/en/features/authentication.mdx

(limited to 'packages/docs/content/en/features/authentication.mdx')

diff --git a/packages/docs/content/en/features/authentication.mdx b/packages/docs/content/en/features/authentication.mdx
deleted file mode 100644
index b6fc4ba..0000000
--- a/packages/docs/content/en/features/authentication.mdx
+++ /dev/null
@@ -1,266 +0,0 @@
----
-title: Authentication
-description: Microsoft OAuth and offline authentication in DropOut
----
-
-# Authentication
-
-DropOut supports two authentication methods: Microsoft Account (for official Minecraft) and Offline Mode (for testing and offline play).
-
-## Microsoft Authentication
-
-### Overview
-
-DropOut uses the **Device Code Flow** for Microsoft authentication, which:
-- Doesn't require a redirect URL (no browser integration)
-- Works on any device with a browser
-- Provides a simple code-based authentication
-- Fully compliant with Microsoft OAuth 2.0
-
-### Authentication Process
-
-The authentication chain consists of multiple steps:
-
-1. **Device Code** → User authorization
-2. **MS Token** → Access + refresh tokens
-3. **Xbox Live** → Xbox token + UHS
-4. **XSTS** → Security token
-5. **Minecraft** → Game access token
-6. **Profile** → Username + UUID
-
-#### Step 1: Device Code Request
-1. Click "Login with Microsoft"
-2. DropOut requests a device code from Microsoft
-3. You receive:
-   - User code (e.g., `A1B2-C3D4`)
-   - Verification URL (usually `https://microsoft.com/link`)
-   - Device code (used internally)
-
-#### Step 2: User Authorization
-1. Visit the verification URL in any browser
-2. Enter the user code
-3. Sign in with your Microsoft account
-4. Authorize DropOut to access your Minecraft profile
-
-#### Step 3: Token Exchange
-- DropOut polls Microsoft for authorization completion
-- Once authorized, receives an access token and refresh token
-- Refresh token is stored for future logins
-
-#### Step 4: Xbox Live Authentication
-- Microsoft token is exchanged for Xbox Live token
-- Retrieves User Hash (UHS) for next step
-
-#### Step 5: XSTS Authorization
-- Xbox Live token is used to get XSTS token
-- This token is specific to Minecraft services
-
-#### Step 6: Minecraft Login
-- XSTS token is exchanged for Minecraft access token
-- Uses endpoint: `/launcher/login`
-
-#### Step 7: Profile Fetching
-- Retrieves your Minecraft username
-- Fetches your UUID
-- Checks if you own Minecraft
-
-### Token Management
-
-**Access Token:**
-- Short-lived (typically 1 hour)
-- Used for game authentication
-- Automatically refreshed when expired
-
-**Refresh Token:**
-- Long-lived (typically 90 days)
-- Stored securely in `accounts.json`
-- Used to obtain new access tokens
-
-**Auto-refresh:**
-```rust
-// Automatic refresh when token expires
-if account.expires_at < current_time {
-    refresh_full_auth(&account).await?;
-}
-```
-
-### Security Considerations
-
-- Tokens are stored in platform-specific app data directory
-- HTTPS only for all API calls
-- No credentials stored (only tokens)
-- User-Agent header required (bypasses MS WAF)
-
-### Troubleshooting Microsoft Login
-
-**"Device code expired"**
-- Codes expire after 15 minutes
-- Start the login process again
-
-**"Authorization pending"**
-- Normal during the waiting phase
-- Complete authorization in the browser
-
-**"Invalid token"**
-- Token may have expired
-- Log out and log back in
-
-**"You don't own Minecraft"**
-- Verify your Microsoft account owns Minecraft Java Edition
-- Check at https://www.minecraft.net/profile
-
-## Offline Authentication
-
-### Overview
-
-Offline mode creates a local account that doesn't require internet connectivity or a Microsoft account. This is useful for:
-- Testing and development
-- Playing without internet
-- LAN multiplayer
-- Mod development
-
-### Creating an Offline Account
-
-1. Click "Offline Mode" in the login screen
-2. Enter a username (3-16 characters)
-3. Click "Create Account"
-
-### How It Works
-
-**UUID Generation:**
-```rust
-// Deterministic UUID v3 from username
-let uuid = generate_offline_uuid(&username);
-```
-
-- Uses UUID v3 (namespace-based)
-- Deterministic: same username = same UUID
-- No network requests
-
-**Authentication:**
-- Returns `"null"` as access token
-- Minecraft accepts null token in offline mode
-- Username and UUID stored locally
-
-### Limitations
-
-- Cannot join online servers
-- No skin support
-- No cape support
-- No Microsoft account features
-
-### Use Cases
-
-**Development:**
-```bash
-# Testing mod development
-cargo tauri dev
-# Use offline mode to test quickly
-```
-
-**LAN Play:**
-- Join LAN worlds without authentication
-- Host LAN worlds
-
-**Offline Play:**
-- Singleplayer without internet
-- No authentication required
-
-## Account Management
-
-### Switching Accounts
-
-Currently, DropOut supports one active account at a time. Multi-account support is planned.
-
-**To switch accounts:**
-1. Log out of current account
-2. Log in with new account
-
-### Account Storage
-
-Accounts are stored in `accounts.json`:
-
-```json
-{
-  "current_account_id": "uuid-here",
-  "accounts": [
-    {
-      "id": "uuid",
-      "type": "Microsoft",
-      "username": "PlayerName",
-      "access_token": "...",
-      "refresh_token": "...",
-      "expires_at": 1234567890
-    }
-  ]
-}
-```
-
-### Deleting Accounts
-
-To remove an account:
-1. Open Settings
-2. Navigate to Accounts
-3. Click "Log Out"
-4. Or manually delete `accounts.json`
-
-## API Reference
-
-### Tauri Commands
-
-**Start Microsoft Login:**
-```typescript
-const { user_code, verification_uri } = await invoke('start_microsoft_login');
-```
-
-**Complete Microsoft Login:**
-```typescript
-const account = await invoke('complete_microsoft_login', { deviceCode });
-```
-
-**Offline Login:**
-```typescript
-const account = await invoke('offline_login', { username: 'Player' });
-```
-
-**Logout:**
-```typescript
-await invoke('logout');
-```
-
-**Get Current Account:**
-```typescript
-const account = await invoke('get_current_account');
-```
-
-### Events
-
-**Authentication Status:**
-```typescript
-listen('auth-status', (event) => {
-  console.log(event.payload); // "logged_in" | "logged_out"
-});
-```
-
-## Best Practices
-
-### For Players
-
-1. **Use Microsoft Account** for official servers
-2. **Keep tokens secure** - don't share accounts.json
-3. **Refresh tokens regularly** by logging in
-4. **Use offline mode** only for testing
-
-### For Developers
-
-1. **Handle token expiration** gracefully
-2. **Implement retry logic** for network failures
-3. **Cache account data** to reduce API calls
-4. **Validate tokens** before game launch
-
-## Future Enhancements
-
-- **Multi-account support**: Switch between accounts easily
-- **Account profiles**: Save per-account settings
-- **Auto-login**: Remember last account
-- **Token encryption**: Enhanced security for stored tokens
-- 
cgit v1.2.3-70-g09d2

