Editor System Architecture

Scope

The editor system defines the editing surface contract and adapter boundary for Prox OS apps. @prox-os/editor provides value types, document types, React primitives, Tiptap and CodeMirror adapters, Storybook examples, and integration notes for future media, commands, AI, collaboration, and persistence. Block Studio v0 uses BlockNote directly inside apps/os-shell while the longer-term block protocol is still being designed.

Position

Editor package owns the editing surface contract and adapters.
Apps own domain content and persistence.
AI, collaboration, storage, search, and audit are future integration layers.

The package should let apps add rich text, markdown, code snippets, prompts, comments, descriptions, and read-only previews without each app inventing a private editor stack.

Editor Value vs Document vs Domain Content

OsEditorValue describes the editable payload:

format;
raw value;
optional plain text;
optional HTML;
optional markdown;
metadata.

OsEditorDocument wraps a value with identity and document metadata:

id;
title and description;
provider;
created and updated timestamps;
author;
tags;
metadata.

Domain content still belongs to the app. A Dream entry, app description, founder memo, comment draft, or AI prompt can use an editor value without making the editor package own business meaning, save APIs, or permissions.

Provider and Adapter Strategy

Phase 1 providers:

tiptap for rich text and document-like editing;
codemirror for markdown, code, prompt, and structured text;
plain-text for simple comments and read-only previews.

Future provider labels are already represented in the contract:

lexical-future;
plate-future;
monaco-future;
custom.

This keeps the public API Prox-owned while allowing the implementation to change behind adapters.

Block Studio v0

Block Studio is the Studio Engine for Notion-like block work, local insertion, app blocks, and AI action blocks. v0 uses BlockNote because it fits the current product slice:

fast block editor setup;
default slash menu;
drag handles;
block nesting;
custom block direction;
React integration that can stay route-level lazy loaded.

BlockNote is a v0 engine choice, not a permanent schema lock. Future work should define a Prox Block Protocol: an OS-level block schema for paragraphs, tasks, app blocks, AI action blocks, connector blocks, weather blocks, projection cards, and future database or media blocks.

Longer-term evaluation remains open:

BlockSuite for docs plus whiteboard plus database collaboration;
Tiptap for lower-level control in a future @prox-os/editor foundation;
a future @prox-os/editor or @prox-os/block package when the block protocol has real callers.

The selection is about architecture fit and v0 product speed, not star counts.

Rich Text, Markdown, Code, Prompt

Surface	Phase 1 adapter	Responsibility
Rich text	Tiptap	Notes, descriptions, app content, document-like editing.
Markdown	CodeMirror	Memos, docs snippets, structured writing, preview placeholders.
Code	CodeMirror	JSON, JavaScript, TypeScript, and configuration snippets.
Prompt	CodeMirror	AI prompt drafts with variable chips and future AI assistance.
Comment	Native textarea	Lightweight notes without owning a thread system.

Why Not A Notion Clone

The goal is a reusable editing surface, not a complete product. Phase 1 avoids:

block databases;
page trees;
collaborative cursors;
file uploads;
embeds marketplace;
version history;
workflow automation;
full markdown / HTML / rich JSON conversion.

Those features need their own contracts and backend layers.

Content Safety Boundary

Rich text HTML must be treated carefully. Phase 1 avoids rendering arbitrary HTML through dangerouslySetInnerHTML. Preview components render safe text previews and adapter-owned editor output.

Future work should define:

sanitization policy for stored HTML;
external link policy with rel="noopener noreferrer";
URL interception with the OS runtime;
AI-generated content provenance metadata;
paste handling policy;
attachment and media upload policy.

Action Boundary

Editor actions align with @prox-os/actions:

save draft
copy markdown
insert media
ask AI
summarize selection
improve writing

The editor package emits intent and renders primitives. It does not execute permissions, audit, backend mutations, or AI tool calls.

Future Integrations

Media

Future media insertion should use @prox-os/media resources for images, embeds, external links, alt text, and provider metadata. The editor should emit insert intent; storage and permissions stay outside the editor package.

Slash Commands And Command Palette

Future slash commands can wrap @prox-os/command and @prox-os/actions. Selection-aware command execution should receive OsEditorSelectionSummary but the Shell should not own every editor internal route or command.

The current AI Control Plane split is:

Slash Menu = local insert
Cmd+K = global command
Alma = ambient observer
AI Entry = full-screen agent workflow for Studio creation

AI Editing

Future AI editing should support:

summarize selection;
improve writing;
rewrite tone;
generate outline;
review and apply proposed edits;
record provenance metadata.

AI output should not bypass user review, permissions, audit, or content safety.

Collaboration

Collaboration is a later product layer. Yjs, CRDT state, cursors, comments, suggestions, and version history should be evaluated under a future @prox-os/collaboration or document package, not hidden inside editor Phase 1.