# VizTyp

> **Local-first Yuque + real-time visual MrDoc**
> A personal and team knowledge management system based on [Typst](https://typst.app), rendered live via `typst.ts` WASM, with a Rust HTTP backend. SiYuan-style IDE layout, for Web and Tauri desktop.

[简体中文](./README.zh.md)

---

## 功能特性 / Features

### 📝 文档编辑

- **Typst 实时编辑** — CodeMirror 6 编辑器,思源风格主题,语法高亮
- **实时 SVG 预览** — typst.ts WASM 浏览器内编译,防抖渲染
- **多 Tab 管理** — 多文档并行编辑,未保存指示
- **查找替换** — CodeMirror 内置搜索面板(Ctrl+H)
- **文件 I/O** — 打开/保存 .typ 文件,导出 PDF/SVG(Web 下载 + Tauri 原生对话框)

### 📚 知识库管理

- **知识库 CRUD** — Workspace → KnowledgeBase → Document 三层结构
- **文档树导航** — KB 列表 → 文档两级树展开(类语雀)
- **草稿/发布分离** — `.typ.draft` sidecar 草稿,发布时提升 + 清除草稿
- **版本历史** — MrDoc 式完整快照,发布自动存档,一键恢复任意版本
- **文档标签** — 文档级标签,持久化存储
- **TOC 解耦** — 独立 TOC 树(借鉴语雀模式),不硬编码在文档内容中

### 🔍 搜索与发现

- **权限感知全文搜索** — 跨知识库搜索,预过滤用户可见 KB(借鉴 MrDoc)
- **跨标签搜索** — 在已打开 Tab 中即时搜索
- **可视化依赖图** — 手写 SVG,实时解析 `#include`/`#import`/`#image` 构建知识图谱
- **大纲导航** — Typst `#heading` 解析,点击跳转
- **编译诊断** — typst.ts 编译错误实时显示

### 👥 协作与权限

- **用户认证** — JWT 注册/登录,SHA-256 密码哈希
- **KB 可见性** — 4 级:public / private / specified / access_code
- **协作者角色** — reader(只读)/ writer(可写)/ admin(管理)
- **文档分享** — 独立于 KB 权限的单文档分享令牌(公开/访问码)
- **在线状态** — presence 轮询,状态栏显示在线协作者

### 🔌 系统扩展

- **插件系统** — 内置 TS 插件 + 钩子体系(onCompile/onSave/onPublish/onRender)
- **CSS/JS 片段** — CSS 动态注入页面样式,JS 配置型
- **命令面板** — Ctrl+K 模糊搜索所有命令
- **工作区导入导出** — JSON 含所有文档内容,一键备份/迁移
- **主题与设置** — light/dark/system 主题,字号/Tab/换行/防抖等可调

## 架构 / Architecture

```
┌─────────────────────────────────────────────────────────────┐
│  Frontend (Svelte 5 + Vite, Web + Tauri 共用)                │
│  ├── 文档编辑: Editor (CM6) + Preview (typst.ts SVG)         │
│  ├── 知识库: KB tree / Dependency graph / Search / History   │
│  ├── 协作: Login / Collaborators / Share / Presence         │
│  └── api/ (HTTP client: JWT Bearer auth)                     │
└─────────────────────────────────────────────────────────────┘
                          │ HTTP (port 7480)
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  Rust Backend (tokio + hyper)                                │
│  ├── 认证: JWT register/login + permission checks            │
│  ├── KB/Doc CRUD + draft/publish + version snapshots         │
│  ├── Tags + search + share tokens + collaborators           │
│  └── Storage: JSON files (workspace/users/versions/...)      │
└─────────────────────────────────────────────────────────────┘
```

**Web**: run backend manually (`yarn server:dev`), frontend via `VIZTYP_API_URL`.
**Desktop (Tauri)**: backend auto-launched as sidecar, cleaned up on exit.

## 快速开始 / Getting Started

```bash
yarn install
yarn workspace frontend install

# Desktop (recommended, auto sidecar)
yarn dev

# Web (backend separately)
yarn server:dev         # Rust backend (port 7480)
yarn frontend:dev       # Frontend (port 5173)

yarn frontend:check     # Type check (0 errors)
yarn build              # Desktop production build
```

**First run**: login/register screen appears. First user becomes **owner** (full access).

## 技术栈 / Tech Stack

| Layer | Choice |
|---|---|
| Frontend | Svelte 5 (runes) + Vite 8 + TypeScript ~6.0 |
| Editor | CodeMirror 6 (custom SiYuan theme) |
| Typst | typst.ts `0.7.0` (manual compiler + renderer) |
| Backend | Rust: tokio + hyper + serde + jsonwebtoken + sha2 |
| Desktop | Tauri v2 (auto sidecar) |

## 项目结构 / Project Structure

```
viztyp/
├── packages/frontend/src/
│   ├── lib/           # 编辑器/IDE/知识库/协作/插件 50+ 模块
│   │   ├── api/       # Rust 后端 HTTP 客户端
│   │   └── plugins/   # 内置插件 (word-count-pro, auto-outline)
│   └── typst/         # 默认欢迎文档
├── server/            # Rust HTTP 后端 (认证/KB/版本/搜索/分享/协作者)
├── src-tauri/         # Tauri v2 桌面外壳 (sidecar 启动)
├── typst-pkg/         # 自研 Typst 库 (viztyp)
├── scripts/           # 构建辅助 (build-sidecar.sh)
└── AGENTS.md          # 架构与设计文档 (bilingual)
```

## ⚙️ Implementation Notes

1. **`@codemirror/basic-setup` deprecated** → `basicSetup` from `codemirror` umbrella.
2. **typst.svelte `<Typst>` recompiles per keystroke** → manual `createTypstCompiler()` + `createTypstRenderer()`.
3. **Tauri v2 no `app.security.headers`** → COOP/COEP via Vite; desktop prod needs custom protocol handler (see `src-tauri/COOP_COEP_NOTES.md`).
4. **Rust backend** (user decision) → Web/Tauri share one HTTP API.

## 📜 License

MIT