# AGENTS.md

## Commands

- `npm run dev` — start Vite dev server (port 80 in Docker)
- `npm run build` — production build to `dist/`
- `npm run preview` — preview production build

No test, lint, typecheck, or formatter scripts are configured.

## Architecture

Single-page Vue 3 app (JavaScript, no TypeScript). UI library is Element Plus, state via Pinia, routing via vue-router, i18n via vue-i18n (en-US, zh-CN).

### Path alias

`@` maps to `src/`. All internal imports use this alias.

### gRPC-Web API layer

Backend communication uses ConnectRPC (gRPC-Web). Generated protobuf code comes from the npm package `@yoresee-doc/sdk-node` (ESM/Connect build), pinned to tag `v0.1.0` in `package.json` (`git+https://git.yoresee.cc/YoreseeDoc/yoresee_doc_sdk_node.git#v0.1.0`). No local codegen required.

- `src/services/grpc_client.js` — transport, client instances, `unaryCall` wrapper, `messages` re-export
- `src/services/api/*.js` — domain API functions that wrap `unaryCall` with protobuf request/response mappers
- `src/services/api/shared.js` — common helpers (`unaryCall`, `messages`, mappers like `mapDocument`, `mapAttachment`)
- `src/config/baseUrl.js` — `API_BASE_URL` (from `VITE_API_BASE_URL` env or `window.location.origin`), `GRPC_WEB_ENDPOINT` (defaults to `/grpc`)

### Key libraries

- **Rich text editors**: TipTap (collaborative, Yjs-backed), EasyMDE (Markdown), Vditor, CodeMirror
- **Collaborative editing**: Yjs + y-websocket
- **Diff rendering**: `diff` + `diff2html`
- **Mind maps**: markmap-lib / markmap-view
- **Spreadsheets**: x-data-spreadsheet

### Environment

- `VITE_API_BASE_URL` — REST/gRPC base (default: `http://localhost:8080` via `.env`)
- `VITE_GRPC_WEB_ENDPOINT` — gRPC endpoint path (default: `/grpc`)
- Dark mode is the default; toggled via `localStorage` key `darkMode`/`theme`

## Conventions

- Components are Vue SFCs using `<script setup>`
- Router meta `requiresAuth: true` guards authenticated routes; `titleKey` drives i18n page titles
- Auth token stored in `localStorage` as `token`; user info as JSON in `userInfo`
- gRPC requests must include headers from `buildHeaders()` (Authorization + accept-language)
- i18n keys are namespaced (e.g., `document.settings.title`, `navigation.home`)