VizTyp

Local-first Yuque + real-time visual MrDoc A personal and team knowledge management system based on Typst, rendered live via typst.ts WASM, with a Rust HTTP backend. SiYuan-style IDE layout, for Web and Tauri desktop.

简体中文

---

功能特性 / 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

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