spaces-architecture

name: spaces-architecture description: Use when working on massCode spaces such as code, notes, math, or tools, especially when changing their state, behavior, synchronization, or spaces IPC channels.

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.