feat: add spaces, space-aware sync, and Math Notebook migration (#692)

Author: antonreshetov

AGENTS.md

@@ -78,10 +78,41 @@ Composables get a `use` prefix. The file name matches the exported function name
 ### D. System & IPC
 
 - **File System/System Ops:** Use `ipc.invoke('channel:action', data)`.
-- **Channels:** `fs:*`, `system:*`, `db:*`, `main-menu:*`, `prettier:*`.
+- **Channels:** `fs:*`, `system:*`, `db:*`, `main-menu:*`, `prettier:*`, `spaces:*`.
 - **Renderer:** Access Electron only via `src/renderer/electron.ts`.
 
-### E. Localization
+### E. Spaces Architecture
+
+massCode uses a **Spaces** system to organize different functional areas:
+
+| Space | ID | Description |
+|-------|----|-------------|
+| Code | `code` | Main snippet management (folders, snippets, tags) |
+| Tools | `tools` | Developer utilities (converters, generators) |
+| Math | `math` | Math Notebook with calculation sheets |
+
+**Space Definitions:** `src/renderer/spaceDefinitions.ts` — `SpaceId`, `getSpaceDefinitions()`, `getActiveSpaceId()`.
+
+**Space State Persistence (Markdown Engine):**
+- Each space can store its state in `__spaces__/{spaceId}/.state.yaml` inside the vault.
+- Runtime utilities: `src/main/storage/providers/markdown/runtime/spaces.ts` — `ensureSpaceDirectory()`, `getSpaceStatePath()`.
+- Generic YAML read/write: `src/main/storage/providers/markdown/runtime/spaceState.ts` — `readSpaceState<T>()`, `writeSpaceState()`.
+- Space state writes use the same debounce/flush infrastructure as `state.json` (`pendingStateWriteByPath` in `constants.ts`), so they flush automatically on app exit.
+- `__spaces__/` directory exists **only in markdown engine**. When engine is `sqlite`, spaces fall back to `electron-store`.
+
+**Space IPC Channels:**
+- `spaces:math:read` — read Math Notebook state (auto-migrates from electron-store on first read in markdown mode).
+- `spaces:math:write` — persist Math Notebook state.
+- Handlers: `src/main/ipc/handlers/spaces.ts`.
+
+**Space-Aware Sync:**
+- `system:storage-synced` event dispatches refresh based on `getActiveSpaceId()`:
+  - `code` / `null` → refresh folders + snippets
+  - `math` → `reloadFromDisk()` via `useMathNotebook()`
+  - `tools` → no-op (no vault data)
+- Mutable operations must call `markPersistedStorageMutation()` to prevent sync loops.
+
+### F. Localization
 
 - **Primary Language:** English (EN) is the base language. All new keys **MUST** be added to `src/main/i18n/locales/en_US/` first.
 - **Strictly No Hardcoding:** Never use hardcoded strings in templates or logic. Always use the localization system.

src/main/ipc/handlers/spaces.ts

@@ -0,0 +1,78 @@
+import type { MathNotebookStore } from '../../store/types'
+import { ipcMain } from 'electron'
+import {
+  ensureSpaceDirectory,
+  getSpaceStatePath,
+} from '../../storage/providers/markdown/runtime/spaces'
+import {
+  readSpaceState,
+  writeSpaceState,
+} from '../../storage/providers/markdown/runtime/spaceState'
+import { store } from '../../store'
+
+function getVaultPath(): string | null {
+  return store.preferences.get('storage.vaultPath') as string | null
+}
+
+function isMarkdownEngine(): boolean {
+  return store.preferences.get('storage.engine') === 'markdown'
+}
+
+export function registerSpacesHandlers() {
+  ipcMain.handle('spaces:math:read', () => {
+    if (!isMarkdownEngine()) {
+      return {
+        sheets: store.mathNotebook.get('sheets') ?? [],
+        activeSheetId: store.mathNotebook.get('activeSheetId') ?? null,
+      } satisfies MathNotebookStore
+    }
+
+    const vaultPath = getVaultPath()
+    if (!vaultPath) {
+      return {
+        sheets: [],
+        activeSheetId: null,
+      } satisfies MathNotebookStore
+    }
+
+    ensureSpaceDirectory(vaultPath, 'math')
+    const statePath = getSpaceStatePath(vaultPath, 'math')
+    const state = readSpaceState<MathNotebookStore>(statePath)
+
+    if (state) {
+      return {
+        sheets: Array.isArray(state.sheets) ? state.sheets : [],
+        activeSheetId: state.activeSheetId ?? null,
+      } satisfies MathNotebookStore
+    }
+
+    // Migration: read from electron-store, write to vault
+    const legacy: MathNotebookStore = {
+      sheets: store.mathNotebook.get('sheets') ?? [],
+      activeSheetId: store.mathNotebook.get('activeSheetId') ?? null,
+    }
+
+    if (legacy.sheets.length > 0) {
+      writeSpaceState(statePath, legacy)
+    }
+
+    return legacy
+  })
+
+  ipcMain.handle('spaces:math:write', (_, data: MathNotebookStore) => {
+    if (!isMarkdownEngine()) {
+      store.mathNotebook.set('sheets', data.sheets)
+      store.mathNotebook.set('activeSheetId', data.activeSheetId)
+      return
+    }
+
+    const vaultPath = getVaultPath()
+    if (!vaultPath) {
+      return
+    }
+
+    ensureSpaceDirectory(vaultPath, 'math')
+    const statePath = getSpaceStatePath(vaultPath, 'math')
+    writeSpaceState(statePath, data)
+  })
+}

src/main/ipc/index.ts

@@ -4,6 +4,7 @@ import { registerDBHandlers } from './handlers/db'
 import { registerDialogHandlers } from './handlers/dialog'
 import { registerFsHandlers } from './handlers/fs'
 import { registerPrettierHandlers } from './handlers/prettier'
+import { registerSpacesHandlers } from './handlers/spaces'
 import { registerSystemHandlers } from './handlers/system'
 import { registerThemeHandlers } from './handlers/theme'
 
@@ -18,4 +19,5 @@ export function registerIPC() {
   registerPrettierHandlers()
   registerFsHandlers()
   registerThemeHandlers()
+  registerSpacesHandlers()
 }

src/main/storage/providers/markdown/runtime/constants.ts

@@ -4,14 +4,21 @@ export const META_DIR_NAME = '.masscode'
 export const STATE_FILE_NAME = 'state.json'
 export const INBOX_DIR_NAME = 'inbox'
 export const TRASH_DIR_NAME = 'trash'
-export const FOLDER_META_FILE_NAME = '.masscode-folder.yml'
+export const SPACES_DIR_NAME = '__spaces__'
+export const META_FILE_NAME = '.meta.yaml'
+export const SPACE_STATE_FILE_NAME = '.state.yaml'
+export const LEGACY_FOLDER_META_FILE_NAME = '.masscode-folder.yml'
 
 export const INBOX_RELATIVE_PATH = `${META_DIR_NAME}/${INBOX_DIR_NAME}`
 export const TRASH_RELATIVE_PATH = `${META_DIR_NAME}/${TRASH_DIR_NAME}`
 export const LEGACY_INBOX_RELATIVE_PATH = INBOX_DIR_NAME
 export const LEGACY_TRASH_RELATIVE_PATH = TRASH_DIR_NAME
 
-export const RESERVED_ROOT_NAMES = new Set([INBOX_DIR_NAME, TRASH_DIR_NAME])
+export const RESERVED_ROOT_NAMES = new Set([
+  INBOX_DIR_NAME,
+  TRASH_DIR_NAME,
+  SPACES_DIR_NAME,
+])
 export const NEW_LINE_SPLIT_RE = /\r?\n/
 export const SEARCH_DIACRITICS_RE = /[\u0300-\u036F]/g
 export const SEARCH_WORD_RE = /[\p{L}\p{N}_]+/gu

src/main/storage/providers/markdown/runtime/index.ts

@@ -2,17 +2,25 @@
 export {
   INBOX_DIR_NAME,
   INVALID_NAME_CHARS_RE,
+  LEGACY_FOLDER_META_FILE_NAME,
   META_DIR_NAME,
+  META_FILE_NAME,
   peekRuntimeCache,
+  SPACE_STATE_FILE_NAME,
+  SPACES_DIR_NAME,
   TRASH_DIR_NAME,
   WINDOWS_RESERVED_NAME_RE,
 } from './constants'
 
 // Normalizers
-export { normalizeFlag } from './normalizers'
+export { normalizeFlag, normalizeFolderOrderIndices } from './normalizers'
 
 // Parser
-export { writeFolderMetadataFile } from './parser'
+export {
+  readYamlObjectFile,
+  writeFolderMetadataFile,
+  writeYamlObjectFile,
+} from './parser'
 
 // Paths
 export {
@@ -42,6 +50,20 @@ export {
   writeSnippetToFile,
 } from './snippets'
 
+// Spaces
+export {
+  ensureSpaceDirectory,
+  getSpaceDirPath,
+  getSpaceStatePath,
+} from './spaces'
+
+// Space State
+export {
+  readSpaceState,
+  writeSpaceState,
+  writeSpaceStateImmediate,
+} from './spaceState'
+
 // State
 export {
   createDefaultState,

src/main/storage/providers/markdown/runtime/normalizers.ts

@@ -1,3 +1,4 @@
+import type { FolderRecord } from '../../../contracts'
 import type { MarkdownFolderUIState } from './types'
 
 export function normalizeNumber(value: unknown, fallback = 0): number {
@@ -60,3 +61,30 @@ export function normalizeFolderUiState(
 
   return normalized
 }
+
+export function normalizeFolderOrderIndices(folders: FolderRecord[]): void {
+  const childrenByParent = new Map<number | null, FolderRecord[]>()
+
+  for (const folder of folders) {
+    const siblings = childrenByParent.get(folder.parentId)
+    if (siblings) {
+      siblings.push(folder)
+    }
+    else {
+      childrenByParent.set(folder.parentId, [folder])
+    }
+  }
+
+  for (const siblings of childrenByParent.values()) {
+    siblings.sort((a, b) => {
+      if (a.orderIndex !== b.orderIndex) {
+        return a.orderIndex - b.orderIndex
+      }
+      return a.id - b.id
+    })
+
+    for (let i = 0; i < siblings.length; i++) {
+      siblings[i].orderIndex = i
+    }
+  }
+}