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.