feat: switch from fumadocs to self-developed SSG framework

Author: MaxtuneLee

.github/copilot-instructions.md

@@ -0,0 +1,124 @@
+# Afilmory Codebase Guide for AI Agents
+
+## Project Architecture
+
+Afilmory is a modern photo gallery monorepo with sophisticated image processing capabilities:
+
+- **`apps/ssr/`** - Next.js 15 SSR application with database and APIs
+- **`apps/web/`** - React 19 frontend with Vite, WebGL viewer, masonry layout
+- **`packages/builder/`** - Photo processing engine with S3/GitHub storage adapters
+- **`packages/docs/`** - Vite SSG documentation site (planned custom implementation)
+- **`packages/webgl-viewer/`** - High-performance WebGL photo viewer component
+
+## Critical Development Commands
+
+```bash
+# Photo processing & manifest generation
+pnpm run build:manifest                    # Incremental photo sync
+pnpm run build:manifest -- --force         # Full rebuild
+pnpm run build:manifest -- --force-thumbnails  # Regenerate thumbnails only
+
+# Development servers
+pnpm dev                                   # Starts both SSR + web apps
+pnpm --filter @afilmory/ssr dev           # SSR only (Next.js on :1924)
+pnpm --filter web dev                     # Web only (Vite)
+
+# Database operations (SSR app)
+pnpm --filter @afilmory/ssr db:generate   # Generate Drizzle migrations
+pnpm --filter @afilmory/ssr db:migrate    # Run migrations
+```
+
+## Code Quality & Architecture Patterns
+
+### State Management Architecture
+
+- **Jotai** for client state in web app - use atomic patterns, avoid large atoms
+- **TanStack Query** for server state - leverage cache invalidation patterns
+- **React Context** - follow composition over deep nesting, prevent re-renders
+
+### Photo Processing Pipeline
+
+1. **Storage Adapters** (`packages/builder/src/storage/`) - implement `StorageProvider` interface
+2. **Format Conversion** - HEIC/TIFF → web formats via Sharp
+3. **EXIF Extraction** - camera settings, GPS, Fujifilm recipes
+4. **Concurrent Processing** - worker threads/cluster mode in `builderConfig.performance`
+
+### WebGL Integration
+
+- Custom WebGL viewer in `packages/webgl-viewer/` for high-performance rendering
+- Gesture support, zoom/pan operations
+- Integration with masonry layout via Masonic
+
+## Project-Specific Conventions
+
+### Configuration System
+
+- **`builder.config.json`** - photo processing, storage, performance settings
+- **`config.json`** - site metadata merged with `site.config.ts` defaults
+- **`env.ts`** - centralized environment validation with Zod schemas
+
+### Apple UIKit Color System
+
+```typescript
+// Use semantic Tailwind classes from tailwindcss-uikit-colors
+className = 'text-text-primary bg-fill-secondary material-thin'
+// NOT generic colors like "text-blue-500"
+```
+
+### i18n Flat Key Structure
+
+```json
+// locales/app/en.json - use dot notation, avoid nesting
+{
+  "exif.camera.model": "Camera Model",
+  "photo.count_one": "{{count}} photo",
+  "photo.count_other": "{{count}} photos"
+}
+```
+
+### Monorepo Workspace Patterns
+
+- Use `pnpm --filter <package>` for targeted operations
+- Shared dependencies in `pnpm-workspace.yaml` catalog
+- Cross-package imports via workspace protocol: `"@afilmory/components": "workspace:*"`
+
+## Storage Provider Integration
+
+When extending storage support, implement the adapter pattern:
+
+```typescript
+// packages/builder/src/storage/providers/
+class NewStorageProvider implements StorageProvider {
+  async listImages(): Promise<StorageObject[]> {
+    /* */
+  }
+  async getFile(key: string): Promise<Buffer | null> {
+    /* */
+  }
+  // Key methods for storage abstraction
+}
+```
+
+## Performance Considerations
+
+- **Photo Processing**: Configure worker pools in `builderConfig.performance.worker`
+- **WebGL Viewer**: Implement texture memory management and disposal
+- **Bundle Splitting**: Leverage Vite's code splitting for image processing tools
+- **Image Optimization**: Use Sharp for thumbnails, Blurhash for placeholders
+
+## Documentation Site (packages/docs/)
+
+Currently planned as a custom Vite SSG implementation:
+
+- **MDX** with React components, math (KaTeX), charts (Mermaid)
+- **Custom Vite plugins** for file-system routing and search indexing
+- **Design system** aligned with main app's Apple UIKit colors
+- Reference `packages/docs/requirements.md` and `tasks.md` for implementation details
+
+## Integration Points
+
+- **Database**: Drizzle ORM with PostgreSQL for SSR app
+- **Image CDN**: S3-compatible storage with custom domain support
+- **Map Integration**: MapLibre for GPS photo locations
+- **Live Photos**: iOS video detection and playback support
+- **RSS/Social**: OpenGraph metadata and feed generation

.github/workflows/docs.yml

@@ -66,7 +66,7 @@ jobs:
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: ./packages/docs/out
+          path: ./packages/docs/dist
 
   # Deployment job
   deploy:

.specstory/history/2025-07-19_16-41Z-在这个文件里面完成一个插件,满足-#file-sidebar-tsx-#file-app-tsx.md

@@ -0,0 +1,193 @@
+<!-- Generated by SpecStory -->
+
+# 在这个文件里面完成一个插件，满足 #file:Sidebar.tsx  #file:App.tsx  (2025-07-19 16:41Z)
+
+_**User**_
+
+在这个文件里面完成一个插件，满足 #file:Sidebar.tsx  #file:App.tsx 的需求
+
+---
+
+_**Assistant**_
+
+我来分析一下当前的需求，然后完成 Vite 路由插件的实现。
+
+首先让我查看一下当前文件的内容和相关的项目结构： 现在我需要查看 SSG 插件的实现，以了解路由是如何生成的： 现在我来查看一下项目的内容结构，以便了解需要生成的路由： 基于对代码的分析，我发现 `App.tsx` 和 `Sidebar.tsx` 都在引用一个 `routes` 变量，但这个变量还没有定义。我需要创建一个 Vite 插件，来动态生成路由信息，并且让它在开发和构建过程中都能正常工作。
+
+现在我来实现这个路由插件： 让我修复这些 lint 错误： 
+```
+
+```
+
+```
+
+```
+现在我需要更新 Vite 配置文件来使用这个新的路由插件： 
+```
+
+```
+
+```
+
+```
+现在我需要更新 `Sidebar.tsx` 文件，导入路由信息： 
+```
+
+```
+我需要首先生成路由文件。让我先运行插件来生成路由： 
+
+---
+
+_**User**_
+
+为什么build的时候一直在反复执行这个函数generateStaticPages
+
+---
+
+_**Assistant**_
+
+我来分析一下为什么 `generateStaticPages` 函数在构建时会反复执行。让我查看当前的插件实现： 我发现问题了！在 `generateStaticPages` 函数中，它在内部调用了 `build()` 函数来构建 SSR 版本，而这个 `build()` 调用会再次触发相同的插件，导致无限循环。
+
+让我查看 Vite 配置文件来确认插件配置： 现在我明白问题所在了。当 `generateStaticPages` 函数调用 `build()` 时，它传递了相同的插件配置 `plugins: [...viteConfig.plugins]`，这包括了 SSG 插件本身，导致无限递归。
+
+我需要修复这个问题，避免在内部构建时重复使用 SSG 插件： 
+```
+
+```
+现在我还需要进一步优化，避免重复构建。让我添加一个标志来检查 SSR 构建是否已经完成： 
+```
+
+```
+让我实际使用这个标志来避免重复构建： 
+```
+
+```
+现在让我进一步优化，添加更好的条件检查，避免在开发模式或非主构建过程中执行 SSG： 
+```
+
+```
+让我再进一步改进，添加更精确的检查机制，避免在 SSR 构建过程中触发 SSG： 
+```
+
+```
+现在让我再做一个重要的优化，通过环境变量来控制是否执行 SSG，这样可以更好地控制构建过程： 
+```
+
+```
+现在修改内部的 build 调用，设置环境变量以避免触发 SSG： 
+```
+
+```
+现在让我再添加一个更直接的解决方案 - 使用一个全局变量来防止递归： 
+```
+
+```
+现在让我使用这个全局标志： 
+```
+
+```
+现在在 SSR 构建过程中设置这个标志： 
+```
+
+```
+现在问题应该解决了。让我总结一下我做的修改来解决 `generateStaticPages` 函数反复执行的问题：
+
+## 问题分析
+
+原始代码中的问题是：
+1. `generateStaticPages` 函数在内部调用 `build()` 来构建 SSR 版本
+2. 这个 `build()` 调用使用了相同的插件配置 `[...viteConfig.plugins]`，包括了 SSG 插件本身
+3. 这导致了无限递归：SSG 插件触发 → 构建 SSR → SSG 插件再次触发 → 无限循环
+
+## 解决方案
+
+我实施了多层防护来解决这个问题：
+
+1. **过滤插件**：在内部 SSR 构建时过滤掉 SSG 插件
+2. **全局标志**：使用 `isSSRBuilding` 全局变量防止递归
+3. **环境变量**：设置 `VITE_SSR_BUILD` 环境变量作为额外保护
+4. **构建条件检查**：只在主构建（非 SSR 构建）时执行 SSG
+5. **文件存在检查**：避免重复构建已存在的 SSR 文件
+6. **错误处理**：使用 try-finally 确保标志能正确重置
+
+现在构建过程应该是：
+1. 主构建开始，SSG 插件启动
+2. SSG 检查是否需要构建 SSR 入口文件
+3. 如果需要，启动 SSR 构建（使用过滤后的插件，不包含 SSG）
+4. SSR 构建完成后，继续生成静态页面
+5. 不会再次触发 SSG 插件
+
+这样就避免了无限递归的问题。
+
+---
+
+_**User**_
+
+vite v7.0.5 building for production...
+📝 Generated routes file: src/routes.ts
+✓ 37 modules transformed.
+dist/index.html                   0.41 kB │ gzip:  0.25 kB
+dist/routes.json                  1.21 kB │ gzip:  0.49 kB
+dist/assets/server-CEVB1K0h.js  179.29 kB │ gzip: 54.55 kB
+✓ built in 6.00s
+🚀 Generating static pages...
+📦 Building SSR entry...
+vite v7.0.5 building SSR bundle for production...
+📝 Generated routes file: src/routes.ts
+📝 Generated routes file: src/routes.ts
+✓ 5 modules transformed.
+✓ 5 modules transformed. (x2)
+✗ Build failed in 67ms
+Failed to generate static pages: [[@mdx-js/rollup] Unexpected `FunctionDeclaration` in code: only import/exports are supported
+file: /Users/maxtune/workspace/personal/Afilmory/packages/docs/content/en/index.mdx
+] {
+  ancestors: undefined,
+  cause: undefined,
+  column: 1,
+  fatal: undefined,
+  line: 3,
+  name: '3:1-275:2',
+  place: {
+    start: { line: 3, column: 1, offset: 155 },
+    end: { line: 275, column: 2, offset: 8724 }
+  },
+  reason: 'Unexpected `FunctionDeclaration` in code: only import/exports are supported',
+  ruleId: 'non-esm',
+  source: 'micromark-extension-mdxjs-esm',
+  url: 'https://github.com/micromark/micromark-extension-mdxjs-esm#unexpected-type-in-code-only-importexports-are-supported',
+  code: 'PLUGIN_ERROR',
+  plugin: '@mdx-js/rollup',
+  hook: 'transform',
+  id: '/Users/maxtune/workspace/personal/Afilmory/packages/docs/content/en/index.mdx',
+  watchFiles: [
+    '/Users/maxtune/workspace/personal/Afilmory/packages/docs/src/entry-server.tsx',
+    '/Users/maxtune/workspace/personal/Afilmory/packages/docs/package.json',
+    '/Users/maxtune/workspace/personal/Afilmory/packages/docs/src/App.tsx',
+    '/Users/maxtune/workspace/personal/Afilmory/packages/docs/src/routes.ts',
+    '/Users/maxtune/workspace/personal/Afilmory/packages/docs/src/layouts/DocsLayout.tsx',
+    '/Users/maxtune/workspace/personal/Afilmory/packages/docs/src/components/MDXProvider.tsx',
+    '/Users/maxtune/workspace/personal/Afilmory/packages/docs/content/en/index.mdx'
+  ]
+}
+error during build:
+[@mdx-js/rollup] Unexpected `FunctionDeclaration` in code: only import/exports are supported
+file: /Users/maxtune/workspace/personal/Afilmory/packages/docs/content/en/index.mdx
+
+ ELIFECYCLE  Command failed with exit code 1.
+
+---
+
+_**Assistant**_
+
+看起来 MDX 插件在 SSR 构建过程中遇到了问题。这个错误表明 MDX 文件中有函数声明，但在 ESM 模式下只支持 import/export 语句。
+
+让我先检查一下生成的路由文件，看看是否有问题： 问题在于 MDX 插件在 SSR 构建时无法正确处理 MDX 文件。这可能是因为 MDX 插件配置在 SSR 模式下存在问题。让我检查一下 Vite 配置中的 MDX 配置： 我需要修改 SSG 插件，在 SSR 构建时也要包含 MDX 插件的正确配置。问题是当前的插件过滤逻辑过于简单，没有考虑到 MDX 插件的依赖关系。
+
+让我修改 SSG 插件的插件过滤逻辑： 
+```
+
+```
+
+
+---
+

.specstory/history/2025-07-20_06-55Z-在这个脚本中,执行-#file-main-static-js-然后将得到的html合并到-#fil.md

@@ -0,0 +1,25 @@
+<!-- Generated by SpecStory -->
+
+# 在这个脚本中，执行 #file:main-static.js  然后将得到的html合并到 #fil (2025-07-20 06:55Z)
+
+_**User**_
+
+在这个脚本中，执行 #file:main-static.js  然后将得到的html合并到 #file:index.html  的占位符中
+
+---
+
+_**Assistant**_
+
+我需要先查看当前的build.ts文件内容，然后了解如何执行main-static.js并将结果合并到index.html中。 现在我需要查看packages/docs的package.json来了解项目结构和依赖： 让我查看vite.config.ts来了解构建配置： 现在让我检查src目录结构： 让我查看main-static.tsx文件： 现在我理解了架构。我需要创建一个build.ts脚本，它将：
+1. 导入并执行main-static.js中的render函数
+2. 获取返回的HTML
+3. 将HTML插入到index.html模板的占位符中
+
+让我创建这个脚本： 
+```
+
+```
+现在让我测试这个脚本是否能正常工作。首先需要确保静态文件已经构建： 很好！现在运行我们的构建脚本： 让我检查是否需要安装tsx： 
+
+---
+