OpenParable
Skip to content
← Back to skills

Spaces Architecture

Development
spaces-architecture

Spaces Architecture is an Agent Skill for development published in the massCodeIO/massCode repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/massCodeIO/massCode/blob/HEAD/.agents/skills/spaces-architecture/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/spaces-architecture, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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.