spaces-architecture

# Spaces Architecture ## Overview massCode использует систему Spaces для разделения функциональных областей. Это не просто UI tabs: у каждого space есть собственное состояние, свои правила обновления и свой способ синхронизации с данными в vault. ## Space Model - `code` — snippets, folders, tags - `notes` — notes, folders, tags, markdown-based flows - `math` — calculation sheets и состояние math notebook - `tools` — developer utilities Основные определения живут в `src/renderer/spaceDefinitions.ts`. ## Space State Storage - Состояние каждого space хранится в `__spaces__/{spaceId}/.state.yaml` внутри vault. - Runtime helpers: - `src/main/storage/providers/markdown/runtime/spaces.ts` - `src/main/storage/providers/markdown/runtime/spaceState.ts` - Директория `__spaces__/` — служебная часть vault для состояния spaces. ## Persistence Rules - Запись состояния spaces использует ту же debounce/flush инфраструктуру, что и `state.json`. - Не ломай совместимость с `pendingStateWriteByPath` и flush-on-exit поведением. - Если меняешь способ записи, учитывай сценарий завершения приложения до явного ручного flush. ## IPC Rules - Space-specific IPC handlers живут в `src/main/ipc/handlers/spaces.ts`. - Текущие math handlers: - `spaces:math:read` - `spaces:math:write` - Если добавляется новый `spaces:*` flow, он должен работать через общую модель состояния spaces, а не в обход неё. ## Space-Aware Sync - `system:storage-synced` обновляет активное пространство через `getActiveSpaceId()`. - Ожидаемое поведение: - `code` → refresh folders + snippets - `notes` → refresh notes + note folders - `math` → `reloadFromDisk()` через `useMathNotebook()` - `tools` → no-op - Изменения, которые уже сохранены в vault, должны вызывать `markPersistedStorageMutation()`, чтобы не создавать sync loops. ## Common Mistakes - Считать spaces только UI-концепцией и забывать, что у них есть собственное состояние и правила синхронизации. - Писать состояние space в обход общих markdown runtime helpers. - Добавлять mutation без `markPersistedStorageMutation()`. - Ломать согласованность между состоянием space, helpers и sync behavior.