Initial commit: add project files and README

2026-03-18 14:09:06 +08:00
commit f2fa697c68
25 changed files with 4034 additions and 0 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -0,0 +1,5 @@
+node_modules/
+dist/
+.vite/
+*.log
+.DS_Store
--- a/README.md
+++ b/README.md
@@ -0,0 +1,62 @@
+# XCSDD - API 文档查看器
+
+基于 React + TypeScript + Vite 构建的 API 文档查看和管理系统。
+
+## 技术栈
+
+- **前端框架**: React 18 + TypeScript
+- **构建工具**: Vite
+- **样式**: Tailwind CSS
+- **图标**: Lucide React
+
+## 功能特性
+
+- 文档树形导航
+- API 文档查看
+- 响应式布局
+- 美观的 UI 设计
+
+## 快速开始
+
+### 安装依赖
+
+```bash
+npm install
+```
+
+### 开发模式
+
+```bash
+npm run dev
+```
+
+### 构建生产版本
+
+```bash
+npm run build
+```
+
+### 预览构建结果
+
+```bash
+npm run preview
+```
+
+## 项目结构
+
+```
+├── src/
+│   ├── components/    # React 组件
+│   ├── docs/          # 文档文件
+│   ├── lib/           # 工具函数和类型定义
+│   ├── config.ts      # 配置文件
+│   ├── App.tsx        # 主应用组件
+│   └── main.tsx       # 入口文件
+├── dist/              # 构建输出
+├── index.html         # HTML 入口
+└── vite.config.ts     # Vite 配置
+```
+
+## License
+
+MIT
--- a/index.html
+++ b/index.html
@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>XCEngine API Docs</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
--- a/package-lock.json
+++ b/package-lock.json
--- a/package.json
+++ b/package.json
@@ -0,0 +1,28 @@
+{
+  "name": "xcengine-api-docs",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.511.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tailwind-merge": "^3.5.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^4.4.1",
+    "autoprefixer": "^10.4.21",
+    "playwright": "^1.58.2",
+    "postcss": "^8.5.3",
+    "tailwindcss": "^3.4.17",
+    "typescript": "~5.8.3",
+    "vite": "^6.3.5"
+  }
+}
--- a/postcss.config.js
+++ b/postcss.config.js
@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -0,0 +1,9 @@
+import { ApiDocViewer } from './components/ApiDocViewer'
+import { config } from './config'
+
+function App() {
+  document.title = config.projectName
+  return <ApiDocViewer />
+}
+
+export default App
--- a/src/components/ApiDocViewer.tsx
+++ b/src/components/ApiDocViewer.tsx
@@ -0,0 +1,80 @@
+import { useState, useEffect, useCallback } from 'react'
+import { DocTree } from './DocTree'
+import { DocContent } from './DocContent'
+import { parseMarkdown, buildFileTree } from '@/lib/parser'
+import type { DocFile, ParsedDoc } from '@/lib/types'
+import { config } from '@/config'
+
+const modules = import.meta.glob('../docs/**/*.md', { as: 'raw', eager: true })
+
+const DOCS_FILES: Record<string, string> = Object.fromEntries(
+  Object.entries(modules).map(([path, content]) => {
+    const relativePath = path.replace('../docs/', '')
+    return [relativePath, content as string]
+  })
+)
+
+export const ApiDocViewer = () => {
+  const [fileTree, setFileTree] = useState<DocFile[]>([])
+  const [selectedPath, setSelectedPath] = useState<string | undefined>()
+  const [currentDoc, setCurrentDoc] = useState<ParsedDoc | null>(null)
+
+  useEffect(() => {
+    const files = Object.keys(DOCS_FILES)
+    const tree = buildFileTree(files, '/')
+    setFileTree(tree)
+    
+    if (files.length > 0) {
+      setSelectedPath(files[0])
+    }
+  }, [])
+
+  useEffect(() => {
+    if (selectedPath) {
+      const content = DOCS_FILES[selectedPath]
+      if (content) {
+        const parsed = parseMarkdown(content)
+        setCurrentDoc(parsed)
+      }
+    }
+  }, [selectedPath])
+
+  const handleSelect = useCallback((file: DocFile) => {
+    if (!file.isDir) {
+      setSelectedPath(file.relativePath)
+    }
+  }, [])
+
+  const handleReferenceClick = useCallback((ref: string) => {
+    const normalizedRef = ref.replace('.md', '').replace(/^\.\.\//, '')
+    const allFiles = Object.keys(DOCS_FILES)
+    const match = allFiles.find(f => f.replace('.md', '') === normalizedRef)
+    if (match) {
+      setSelectedPath(match)
+    }
+  }, [])
+
+  return (
+    <div className="flex h-screen bg-[#1e1e1e]">
+      <aside className="w-64 bg-[#252526] border-r border-[#3c3c3c] flex flex-col">
+        <div className="p-3 border-b border-[#3c3c3c]">
+          <h2 className="text-sm font-semibold text-gray-200">{config.sidebarTitle}</h2>
+        </div>
+        <div className="flex-1 overflow-hidden">
+          <DocTree
+            files={fileTree}
+            selectedPath={selectedPath}
+            onSelect={handleSelect}
+          />
+        </div>
+      </aside>
+
+      <main className="flex-1 overflow-hidden">
+        <DocContent
+          doc={currentDoc}
+          onReferenceClick={handleReferenceClick}
+        />
+      </main>
+    </div>
+  )
+}
--- a/src/components/DocContent.tsx
+++ b/src/components/DocContent.tsx
@@ -0,0 +1,179 @@
+import { clsx } from 'clsx'
+import type { ParsedDoc, DocTable, DocCodeBlock } from '@/lib/types'
+
+interface DocContentProps {
+  doc: ParsedDoc | null
+  onReferenceClick: (ref: string) => void
+}
+
+export const DocContent = ({ doc, onReferenceClick }: DocContentProps) => {
+  if (!doc) {
+    return (
+      <div className="flex items-center justify-center h-full text-gray-500">
+        <p>Select a document from the sidebar</p>
+      </div>
+    )
+  }
+
+  return (
+    <div className="h-full overflow-auto p-6">
+      <div className="max-w-4xl mx-auto">
+        <h1 className="text-2xl font-bold text-white mb-4">{doc.title}</h1>
+
+        {doc.metadata.namespace && (
+          <div className="mb-4">
+            <span className="text-gray-400">Namespace: </span>
+            <code className="bg-gray-800 px-2 py-1 rounded text-blue-400">{doc.metadata.namespace}</code>
+          </div>
+        )}
+
+        {doc.metadata.package && (
+          <div className="mb-4">
+            <span className="text-gray-400">Package: </span>
+            <code className="bg-gray-800 px-2 py-1 rounded text-blue-400">{doc.metadata.package}</code>
+          </div>
+        )}
+
+        {doc.metadata.type && (
+          <div className="mb-4">
+            <span className="text-gray-400">Type: </span>
+            <span className="text-yellow-400">{doc.metadata.type}</span>
+          </div>
+        )}
+
+        {doc.metadata.inherits && (
+          <div className="mb-4">
+            <span className="text-gray-400">Inherits: </span>
+            <code className="bg-gray-800 px-2 py-1 rounded text-purple-400">{doc.metadata.inherits}</code>
+          </div>
+        )}
+
+        {doc.metadata.description && (
+          <p className="text-gray-300 mb-6">{doc.metadata.description}</p>
+        )}
+
+        {doc.sections.map((section, idx) => (
+          <Section
+            key={idx}
+            section={section}
+            onReferenceClick={onReferenceClick}
+          />
+        ))}
+
+        {doc.references.length > 0 && (
+          <div className="mt-8 pt-4 border-t border-gray-700">
+            <h3 className="text-lg font-semibold text-white mb-2">See Also</h3>
+            <ul className="space-y-1">
+              {doc.references.map((ref, idx) => (
+                <li key={idx}>
+                  <button
+                    onClick={() => onReferenceClick(ref)}
+                    className="text-blue-400 hover:text-blue-300 hover:underline"
+                  >
+                    {ref}
+                  </button>
+                </li>
+              ))}
+            </ul>
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
+
+interface SectionProps {
+  section: import('@/lib/types').DocSection
+  onReferenceClick: (ref: string) => void
+}
+
+const Section = ({ section, onReferenceClick }: SectionProps) => {
+  const HeadingTag = `h${Math.min(section.level + 1, 6)}` as keyof JSX.IntrinsicElements
+
+  return (
+    <section className="mb-6">
+      <HeadingTag className={clsx(
+        'font-semibold text-white mb-3',
+        section.level === 1 ? 'text-xl' : 'text-lg'
+      )}>
+        {section.title}
+      </HeadingTag>
+
+      <div className="space-y-3">
+        {section.content.map((item, idx) => {
+          if (item.type === 'table') {
+            return <TableContent key={idx} table={item.data as DocTable} />
+          }
+          if (item.type === 'code') {
+            return <CodeContent key={idx} code={item.data as DocCodeBlock} />
+          }
+          return <TextContent key={idx} text={item.data as string} onReferenceClick={onReferenceClick} />
+        })}
+      </div>
+    </section>
+  )
+}
+
+const TextContent = ({ text, onReferenceClick }: { text: string; onReferenceClick: (ref: string) => void }) => {
+  const renderText = () => {
+    const parts = text.split(/(@see\s+[^\s]+)/g)
+    return parts.map((part, idx) => {
+      const match = part.match(/@see\s+([^\s]+)/)
+      if (match) {
+        return (
+          <button
+            key={idx}
+            onClick={() => onReferenceClick(match[1])}
+            className="text-blue-400 hover:text-blue-300 hover:underline"
+          >
+            {part}
+          </button>
+        )
+      }
+      return <span key={idx}>{part}</span>
+    })
+  }
+
+  return <p className="text-gray-300">{renderText()}</p>
+}
+
+const TableContent = ({ table }: { table: DocTable }) => {
+  if (!table.headers.length || !table.rows.length) return null
+
+  return (
+    <div className="overflow-x-auto">
+      <table className="w-full border-collapse text-sm">
+        <thead>
+          <tr className="bg-gray-800">
+            {table.headers.map((header, idx) => (
+              <th key={idx} className="border border-gray-600 px-3 py-2 text-left text-gray-200 font-semibold">
+                {header}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {table.rows.map((row, rowIdx) => (
+            <tr key={rowIdx} className="hover:bg-gray-800/50">
+              {row.map((cell, cellIdx) => (
+                <td key={cellIdx} className="border border-gray-600 px-3 py-2 text-gray-300">
+                  {cell}
+                </td>
+              ))}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  )
+}
+
+const CodeContent = ({ code }: { code: DocCodeBlock }) => {
+  return (
+    <pre className="bg-gray-900 border border-gray-700 rounded-lg p-4 overflow-x-auto">
+      <code className={`language-${code.language || 'text'} text-sm text-gray-200`}>
+        {code.code}
+      </code>
+    </pre>
+  )
+}
--- a/src/components/DocTree.tsx
+++ b/src/components/DocTree.tsx
@@ -0,0 +1,97 @@
+import React, { useState } from 'react'
+import { ChevronRight, ChevronDown, Folder, FileText } from 'lucide-react'
+import { clsx } from 'clsx'
+import type { DocFile } from '@/lib/types'
+import { getDisplayName } from '@/lib/parser'
+
+interface DocTreeProps {
+  files: DocFile[]
+  selectedPath?: string
+  onSelect: (file: DocFile) => void
+}
+
+interface DocTreeNodeProps {
+  file: DocFile
+  level: number
+  selectedPath?: string
+  onSelect: (file: DocFile) => void
+}
+
+const DocTreeNode = React.memo(({ file, level, selectedPath, onSelect }: DocTreeNodeProps) => {
+  const [expanded, setExpanded] = useState(level === 0)
+
+  const isSelected = selectedPath === file.relativePath
+  const isDir = file.isDir
+
+  const handleClick = (e: React.MouseEvent) => {
+    e.stopPropagation()
+    if (isDir) {
+      setExpanded(!expanded)
+    } else {
+      onSelect(file)
+    }
+  }
+
+  return (
+    <div>
+      <div
+        className={clsx(
+          'flex items-center gap-2 py-1 px-2 rounded-md cursor-pointer transition-colors text-sm',
+          isSelected
+            ? 'bg-gray-600 text-white'
+            : 'hover:bg-gray-700 text-gray-300'
+        )}
+        onClick={handleClick}
+        style={{ paddingLeft: `${level * 16 + 8}px` }}
+      >
+        <span className="text-gray-400 shrink-0">
+          {isDir ? (
+            expanded ? <ChevronDown size={16} /> : <ChevronRight size={16} />
+          ) : (
+            <span className="w-4" />
+          )}
+        </span>
+
+        <span className="text-gray-400 shrink-0">
+          {isDir ? <Folder size={16} /> : <FileText size={16} />}
+        </span>
+
+        <span className="truncate">{getDisplayName(file.name)}</span>
+      </div>
+
+      {isDir && expanded && file.children && (
+        <div>
+          {file.children.map((child) => (
+            <DocTreeNode
+              key={child.relativePath}
+              file={child}
+              level={level + 1}
+              selectedPath={selectedPath}
+              onSelect={onSelect}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  )
+})
+
+DocTreeNode.displayName = 'DocTreeNode'
+
+export const DocTree = ({ files, selectedPath, onSelect }: DocTreeProps) => {
+  return (
+    <div className="select-none w-full h-full overflow-auto py-2">
+      <div className="space-y-1">
+        {files.map((file) => (
+          <DocTreeNode
+            key={file.relativePath}
+            file={file}
+            level={0}
+            selectedPath={selectedPath}
+            onSelect={onSelect}
+          />
+        ))}
+      </div>
+    </div>
+  )
+}
--- a/src/config.ts
+++ b/src/config.ts
@@ -0,0 +1,9 @@
+export interface DocConfig {
+  projectName: string
+  sidebarTitle: string
+}
+
+export const config: DocConfig = {
+  projectName: 'API Docs',
+  sidebarTitle: '文档目录',
+}
--- a/src/docs/authentication.md
+++ b/src/docs/authentication.md
@@ -0,0 +1,65 @@
+# 认证
+
+**类型**: module
+
+**描述**: 身份验证和授权相关接口。
+
+## 概述
+
+本 API 使用 Bearer Token 进行身份验证。所有请求都需要在 Header 中携带有效的 Token。
+
+## 登录
+
+### 请求
+
+```http
+POST /api/auth/login
+Content-Type: application/json
+
+{
+  "username": "user@example.com",
+  "password": "your-password"
+}
+```
+
+### 响应
+
+```json
+{
+  "token": "eyJhbGciOiJIUzI1NiIs...",
+  "expiresIn": 3600,
+  "user": {
+    "id": "123",
+    "name": "张三",
+    "email": "user@example.com"
+  }
+}
+```
+
+## 刷新 Token
+
+### 请求
+
+```http
+POST /api/auth/refresh
+Authorization: Bearer <current_token>
+```
+
+### 响应
+
+```json
+{
+  "token": "new_token_here",
+  "expiresIn": 3600
+}
+```
+
+## 错误码
+
+| 状态码 | 描述 |
+|--------|------|
+| 401 | 用户名或密码错误 |
+| 403 | 账户已被禁用 |
+| 429 | 请求过于频繁 |
+
+@see users.md
--- a/src/docs/errors.md
+++ b/src/docs/errors.md
@@ -0,0 +1,85 @@
+# 错误处理
+
+**类型**: module
+
+**描述**: API 错误响应格式和错误码定义。
+
+## 错误响应格式
+
+所有错误响应都遵循以下 JSON 格式：
+
+```json
+{
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "错误描述信息",
+    "details": {}
+  }
+}
+```
+
+## 常见错误码
+
+| 错误码 | HTTP 状态码 | 描述 |
+|--------|-------------|------|
+| VALIDATION_ERROR | 400 | 请求参数验证失败 |
+| UNAUTHORIZED | 401 | 未认证或 Token 无效 |
+| FORBIDDEN | 403 | 无权限访问 |
+| NOT_FOUND | 404 | 资源不存在 |
+| RATE_LIMITED | 429 | 请求频率超限 |
+| INTERNAL_ERROR | 500 | 服务器内部错误 |
+
+## 错误详情
+
+### VALIDATION_ERROR
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "请求参数验证失败",
+    "details": {
+      "email": "邮箱格式不正确",
+      "password": "密码长度至少为 8 位"
+    }
+  }
+}
+```
+
+### NOT_FOUND
+
+```json
+{
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "用户不存在",
+    "details": {
+      "resource": "User",
+      "id": "12345"
+    }
+  }
+}
+```
+
+## 重试策略
+
+当遇到 429 或 5xx 错误时，建议采用指数退避策略：
+
+```javascript
+async function fetchWithRetry(url, retries = 3) {
+  for (let i = 0; i < retries; i++) {
+    try {
+      const response = await fetch(url);
+      if (!response.ok && i < retries - 1) {
+        await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
+        continue;
+      }
+      return response;
+    } catch (e) {
+      if (i === retries - 1) throw e;
+    }
+  }
+}
+```
+
+@see authentication.md
--- a/src/docs/getting-started.md
+++ b/src/docs/getting-started.md
@@ -0,0 +1,28 @@
+# 入门指南
+
+**描述**: 欢迎使用 API 文档
+
+## 快速开始
+
+要开始使用本 API，请按照以下步骤操作：
+
+1. 获取 API 密钥
+2. 了解认证方式
+3. 调用接口
+
+## 系统要求
+
+| 要求 | 最低版本 |
+|------|----------|
+| HTTP | 1.1 |
+| TLS | 1.2 |
+
+## 示例代码
+
+```javascript
+const response = await fetch('/api/users');
+const data = await response.json();
+console.log(data);
+```
+
+@see authentication.md
--- a/src/docs/guide/installation.md
+++ b/src/docs/guide/installation.md
@@ -0,0 +1,19 @@
+# 安装指南
+
+## 环境要求
+
+- Node.js 18+
+- npm 9+
+
+## 安装步骤
+
+```bash
+npm install
+npm run dev
+```
+
+## 配置
+
+在 `.env` 文件中配置 API 地址。
+
+@see ../getting-started.md
--- a/src/docs/users.md
+++ b/src/docs/users.md
@@ -0,0 +1,112 @@
+# 用户管理
+
+**命名空间**: api
+
+**类型**: module
+
+**描述**: 用户 CRUD 操作接口。
+
+## 获取用户列表
+
+获取所有用户的列表，支持分页和筛选。
+
+### 请求
+
+```http
+GET /api/users?page=1&limit=20&status=active
+```
+
+### 查询参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| page | number | 页码，默认 1 |
+| limit | number | 每页数量，默认 20 |
+| status | string | 筛选状态：active, inactive, all |
+
+### 响应
+
+```json
+{
+  "data": [
+    {
+      "id": "1",
+      "name": "张三",
+      "email": "zhangsan@example.com",
+      "status": "active",
+      "createdAt": "2024-01-01T00:00:00Z"
+    }
+  ],
+  "pagination": {
+    "page": 1,
+    "limit": 20,
+    "total": 100,
+    "totalPages": 5
+  }
+}
+```
+
+## 创建用户
+
+### 请求
+
+```http
+POST /api/users
+Content-Type: application/json
+
+{
+  "name": "李四",
+  "email": "lisi@example.com",
+  "password": "secure-password"
+}
+```
+
+### 响应
+
+```json
+{
+  "id": "2",
+  "name": "李四",
+  "email": "lisi@example.com",
+  "status": "active",
+  "createdAt": "2024-01-15T00:00:00Z"
+}
+```
+
+## 获取单个用户
+
+### 请求
+
+```http
+GET /api/users/:id
+```
+
+### 路径参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| id | string | 用户 ID |
+
+## 更新用户
+
+### 请求
+
+```http
+PUT /api/users/:id
+Content-Type: application/json
+
+{
+  "name": "新名字",
+  "status": "inactive"
+}
+```
+
+## 删除用户
+
+### 请求
+
+```http
+DELETE /api/users/:id
+```
+
+@see authentication.md @see errors.md
--- a/src/index.css
+++ b/src/index.css
@@ -0,0 +1,36 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+:root {
+  --sidebar-opacity: 0.8;
+}
+
+body {
+  margin: 0;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;
+  background-color: #1e1e1e;
+  color: #d4d4d4;
+}
+
+code, pre {
+  font-family: 'Fira Code', 'Consolas', monospace;
+}
+
+::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+
+::-webkit-scrollbar-track {
+  background: #2d2d2d;
+}
+
+::-webkit-scrollbar-thumb {
+  background: #4a4a4a;
+  border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: #5a5a5a;
+}
--- a/src/lib/parser.ts
+++ b/src/lib/parser.ts
@@ -0,0 +1,236 @@
+import type { ParsedDoc, DocMetadata, DocSection, DocTable, DocCodeBlock } from './types'
+
+const METADATA_REGEX = /^\*\*([^\*]+)\*\*:\s*(.+)$/
+const TABLE_REGEX = /^\|(.+)\|$/
+const CODE_BLOCK_REGEX = /^```(\w*)$/
+const HEADING_REGEX = /^(#{1,6})\s+(.+)$/
+const HR_REGEX = /^---+$/
+const REFERENCE_REGEX = /@see\s+([^\s]+)/g
+
+export function parseMarkdown(content: string): ParsedDoc {
+  const lines = content.split('\n')
+  const result: ParsedDoc = {
+    title: '',
+    metadata: {},
+    sections: [],
+    references: [],
+  }
+
+  const references: string[] = []
+  let metadata: DocMetadata = {}
+  let sections: DocSection[] = []
+  let currentSection: DocSection | null = null
+  let currentContent: Array<{ type: 'text' | 'table' | 'code'; data: string | DocTable | DocCodeBlock }> = []
+  let inCodeBlock = false
+  let codeBlockLanguage = ''
+  let codeBlockLines: string[] = []
+  let tableBuffer: string[] = []
+  let inTable = false
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const trimmedLine = line.trim()
+
+    const refMatch = trimmedLine.match(REFERENCE_REGEX)
+    if (refMatch) {
+      let match
+      while ((match = REFERENCE_REGEX.exec(trimmedLine)) !== null) {
+        references.push(match[1])
+      }
+    }
+
+    const codeMatch = line.match(CODE_BLOCK_REGEX)
+    if (codeMatch) {
+      if (currentSection) {
+        currentSection.content = [...currentContent]
+        sections.push(currentSection)
+        currentSection = null
+      }
+      inCodeBlock = true
+      codeBlockLanguage = codeMatch[1] || ''
+      currentContent = []
+      continue
+    }
+
+    if (inCodeBlock) {
+      if (trimmedLine === '```') {
+        currentContent.push({
+          type: 'code',
+          data: { language: codeBlockLanguage, code: codeBlockLines.join('\n') },
+        } as { type: 'code'; data: DocCodeBlock })
+        codeBlockLines = []
+        codeBlockLanguage = ''
+        inCodeBlock = false
+        
+        if (!currentSection) {
+          currentSection = { title: '', level: 2, content: [] }
+        }
+      } else {
+        codeBlockLines.push(line)
+      }
+      continue
+    }
+
+    if (HR_REGEX.test(trimmedLine)) {
+      if (inTable && tableBuffer.length > 0) {
+        const table = parseTable(tableBuffer)
+        if (table) {
+          currentContent.push({ type: 'table', data: table })
+        }
+        tableBuffer = []
+        inTable = false
+      }
+      continue
+    }
+
+    if (!result.title && line.startsWith('# ')) {
+      result.title = line.slice(2).trim()
+      continue
+    }
+
+    const headingMatch = line.match(HEADING_REGEX)
+    if (headingMatch) {
+      if (currentSection) {
+        currentSection.content = [...currentContent]
+        sections.push(currentSection)
+      }
+      const level = headingMatch[1].length
+      const title = headingMatch[2].trim()
+      currentSection = { title, level, content: [] }
+      currentContent = []
+      inTable = false
+      tableBuffer = []
+      continue
+    }
+
+    const metaMatch = trimmedLine.match(METADATA_REGEX)
+    if (metaMatch) {
+      const key = metaMatch[1].toLowerCase()
+      const value = metaMatch[2].trim()
+      if (key === 'namespace') metadata.namespace = value
+      else if (key === 'description') metadata.description = value
+      else if (key === 'type') metadata.type = value
+      else if (key === 'inherits') metadata.inherits = value
+      else if (key === 'package') metadata.package = value
+      continue
+    }
+
+    const tableMatch = line.match(TABLE_REGEX)
+    if (tableMatch) {
+      const isSeparator = /^[\s|*-]+$/.test(trimmedLine.replace(/\|/g, '').trim())
+      if (!isSeparator) {
+        tableBuffer.push(trimmedLine)
+        inTable = true
+      } else {
+        inTable = true
+      }
+      continue
+    } else if (inTable && tableBuffer.length > 0) {
+      const table = parseTable(tableBuffer)
+      if (table) {
+        currentContent.push({ type: 'table', data: table })
+      }
+      tableBuffer = []
+      inTable = false
+    }
+
+    if (trimmedLine) {
+      currentContent.push({ type: 'text', data: trimmedLine })
+    }
+  }
+
+  if (currentSection) {
+    currentSection.content = [...currentContent]
+    sections.push(currentSection)
+  }
+
+  result.metadata = metadata
+  result.sections = sections
+  result.references = references
+
+  return result
+}
+
+function parseTable(tableLines: string[]): DocTable | null {
+  if (tableLines.length < 1) return null
+
+  const headers = tableLines[0].split('|').filter(h => h.trim()).map(h => h.trim())
+  const rows: string[][] = []
+
+  for (let i = 1; i < tableLines.length; i++) {
+    const line = tableLines[i]
+    const isSeparator = /^[\s|*-]+$/.test(line.replace(/\|/g, '').trim())
+    if (isSeparator) continue
+    
+    const cells = line.split('|').filter(c => c.trim()).map(c => c.trim())
+    if (cells.length > 0) {
+      rows.push(cells)
+    }
+  }
+
+  return { headers, rows }
+}
+
+export function getDisplayName(filename: string): string {
+  const name = filename.replace(/\.md$/, '')
+  return name
+}
+
+export function buildFileTree(files: string[], basePath: string): import('./types').DocFile[] {
+  const tree: Map<string, import('./types').DocFile> = new Map()
+
+  for (const file of files) {
+    const relativePath = file.split('/').filter(Boolean).join('/')
+    const parts = relativePath.split('/')
+
+    let currentPath = ''
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i]
+      const isLast = i === parts.length - 1
+      currentPath = currentPath ? `${currentPath}/${part}` : part
+
+      if (!tree.has(currentPath)) {
+        tree.set(currentPath, {
+          name: part,
+          path: `${basePath}/${currentPath}`,
+          relativePath: currentPath,
+          isDir: !isLast,
+          children: isLast ? undefined : [],
+        })
+      }
+
+      const parentPath = currentPath.split('/').slice(0, -1).join('/')
+      if (parentPath && tree.has(parentPath)) {
+        const parent = tree.get(parentPath)!
+        if (parent.children) {
+          const existing = parent.children.find(c => c.name === part)
+          if (!existing) {
+            parent.children.push(tree.get(currentPath)!)
+          }
+        }
+      }
+    }
+  }
+
+  const rootFiles: import('./types').DocFile[] = []
+  for (const [path, file] of tree) {
+    const parentPath = path.split('/').slice(0, -1).join('/')
+    if (!parentPath) {
+      rootFiles.push(file)
+    }
+  }
+
+  const sortFiles = (files: import('./types').DocFile[]): import('./types').DocFile[] => {
+    return files.sort((a, b) => {
+      if (a.isDir !== b.isDir) return a.isDir ? -1 : 1
+      return a.name.localeCompare(b.name)
+    }).map(f => {
+      if (f.children) {
+        f.children = sortFiles(f.children)
+      }
+      return f
+    })
+  }
+
+  return sortFiles(rootFiles)
+}
--- a/src/lib/types.ts
+++ b/src/lib/types.ts
@@ -0,0 +1,38 @@
+export interface DocFile {
+  name: string
+  path: string
+  relativePath: string
+  isDir: boolean
+  children?: DocFile[]
+}
+
+export interface DocMetadata {
+  namespace?: string
+  description?: string
+  type?: string
+  inherits?: string
+  package?: string
+}
+
+export interface DocTable {
+  headers: string[]
+  rows: string[][]
+}
+
+export interface DocCodeBlock {
+  language: string
+  code: string
+}
+
+export interface DocSection {
+  title: string
+  level: number
+  content: Array<{ type: 'text' | 'table' | 'code'; data: string | DocTable | DocCodeBlock }>
+}
+
+export interface ParsedDoc {
+  title: string
+  metadata: DocMetadata
+  sections: DocSection[]
+  references: string[]
+}
--- a/src/main.tsx
+++ b/src/main.tsx
@@ -0,0 +1,10 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import App from './App'
+import './index.css'
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+)
--- a/src/vite-env.d.ts
+++ b/src/vite-env.d.ts
@@ -0,0 +1 @@
+/// <reference types="vite/client" />
--- a/tailwind.config.js
+++ b/tailwind.config.js
@@ -0,0 +1,11 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: [
+    "./index.html",
+    "./src/**/*.{js,ts,jsx,tsx}",
+  ],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+}
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src"],
+  "references": [{ "path": "./tsconfig.node.json" }]
+}
--- a/tsconfig.node.json
+++ b/tsconfig.node.json
@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "skipLibCheck": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowSyntheticDefaultImports": true,
+    "strict": true
+  },
+  "include": ["vite.config.ts"]
+}
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -0,0 +1,16 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import path from 'path'
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+    },
+  },
+  server: {
+    port: 3001,
+    strictPort: false,
+  },
+})