> ## Documentation Index > Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt > Use this file to discover all available pages before exploring further. # Hybrid Philosophy > Why markers are preserved in VariableMD - extending the Brick from Terminal to Documents # Hybrid Philosophy: Markers Preserved ``` ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ THE CENTER │ │ │ │ "CodexMono is The Brick - the fundamental unit that enables │ │ Monokinetics: unified Human + AI experience through predictable, │ │ trustable visual alignment." │ │ │ │ VariableMD extends this foundation to editing: │ │ Just as terminal cells are atomic units with decorations, │ │ markdown markers are atomic units that remain visible │ │ while their styled content appears simultaneously. │ │ │ └───────────────────────────────────────────────────────────────────────┘ ``` ## The Fundamental Problem Every markdown editor faces a fundamental tension: users want to see their formatting while still having access to the raw syntax. ``` ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ THE MARKDOWN EDITOR DILEMMA │ │ │ ├───────────────────────────────────────────────────────────────────────┤ │ │ │ │ │ RAW MODE WYSIWYG MODE │ │ ┌───────────┐ ┌───────────┐ │ │ │ **bold** │ │ bold │ │ │ │ *italic* │ │ italic │ │ │ │ # Heading │ │ Heading │ │ │ └───────────┘ └───────────┘ │ │ │ │ │ │ │ │ │ │ See syntax See result │ │ No formatting Lose syntax │ │ │ │ │ │ VS │ │ │ │ │ │ THE HYBRID SOLUTION │ │ ┌───────────────────────────────────────┐ │ │ │ ** bold ** (dimmed markers, │ │ │ │ styled content) │ │ │ └───────────────────────────────────────┘ │ │ │ │ See BOTH syntax AND formatting │ │ │ └───────────────────────────────────────────────────────────────────────┘ ``` The Hybrid Philosophy shows **BOTH** the markers **AND** the styling simultaneously. ## Three Pillars of Hybrid Editing ``` ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ THE THREE PILLARS │ │ │ ├───────────────────────────────────────────────────────────────────────┤ │ │ │ │ │ PILLAR 1 PILLAR 2 PILLAR 3 │ │ Document Fidelity Visual Feedback Edit Transparency │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ │ │ │ │ │ │ │ │ What you │ │ See style │ │ Edit │ │ │ │ type is │ │ as you │ │ markers │ │ │ │ what gets │ │ type │ │ directly │ │ │ │ stored │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ │ │ │ v v v │ │ No hidden Instant preview Direct control │ │ abstractions while writing over syntax │ │ │ └───────────────────────────────────────────────────────────────────────┘ ``` ### Document Fidelity The actual markdown syntax exists in the document. When you save, copy, or export, markers are preserved exactly as typed. ### Visual Feedback Users see formatting while editing. Styled appearance provides immediate feedback that syntax is correct. ### Edit Transparency Markers are accessible for modification. Delete them, select them, copy them - no hidden UI layers. ## The Brick Extension Concept ``` ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ EXTENDING THE BRICK FROM TERMINAL TO DOCUMENTS │ │ │ ├───────────────────────────────────────────────────────────────────────┤ │ │ │ │ │ MONOLEX TERMINAL VARIABLEMD EDITOR │ │ ┌───────────────────────────┐ ┌───────────────────────────┐ │ │ │ │ │ │ │ │ │ Grid Cells = Bricks │ │ Markdown Markers = Bricks│ │ │ │ ┌─┬─┬─┬─┬─┬─┬─┬─┬─┐ │ │ * * b o l d * * │ │ │ │ │H│e│l│l│o│ │W│o│r│ │ │ ^ ^ ^ ^ │ │ │ │ └─┴─┴─┴─┴─┴─┴─┴─┴─┘ │ │ │_│_________│_│ │ │ │ │ │ │ Marker Bricks │ │ │ │ Each cell is atomic │ │ Each marker is atomic │ │ │ │ │ │ │ │ │ └───────────────────────────┘ └───────────────────────────┘ │ │ │ │ │ │ └────────────────────────────────────┘ │ │ │ │ │ ATOMIC PHILOSOPHY │ │ - Individual units │ │ - Preserved state │ │ - Decoration layer │ │ │ └───────────────────────────────────────────────────────────────────────┘ ``` | Terminal Cell | Markdown Marker | | --------------------------- | ------------------------------- | | Character content ('A') | Marker content ('\*\*') | | Foreground color | Syntax styling (dimmed) | | Bold/Italic flags | Range boundaries | | Cell position in grid | Position in document | | VTE parser determines flags | State machine determines ranges | This is the same architectural pattern applied to different domains. ## How Hybrid Rendering Works ``` ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ HYBRID RENDERING FLOW │ │ │ ├───────────────────────────────────────────────────────────────────────┤ │ │ │ │ │ User Types │ │ │ │ │ v │ │ ┌───────────────────┐ │ │ │ Raw Markdown Text │ "**bold**" │ │ └───────────────────┘ │ │ │ │ │ v │ │ ┌───────────────────┐ │ │ │ State Machine │ Detects complete patterns │ │ │ Parser │ (not regex - handles nesting) │ │ └───────────────────┘ │ │ │ │ │ v │ │ ┌───────────────────┐ │ │ │ Decoration Layer │ Apply styles without changing text │ │ └───────────────────┘ │ │ │ │ │ v │ │ ┌───────────────────┐ │ │ │ Visual Result │ ** bold ** │ │ │ │ (dimmed) (styled) (dimmed) │ │ └───────────────────┘ │ │ │ └───────────────────────────────────────────────────────────────────────┘ ``` ## Typing Experience ``` ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ USER TYPES: **bold** │ │ │ ├───────────────────────────────────────────────────────────────────────┤ │ │ │ │ │ STEP 1: Type first * │ │ ┌───────────────────────────────────────┐ │ │ │ * │ No decoration yet │ │ └───────────────────────────────────────┘ │ │ │ │ STEP 2: Type second * │ │ ┌───────────────────────────────────────┐ │ │ │ ** │ No decoration yet │ │ └───────────────────────────────────────┘ │ │ │ │ STEP 3: Type "bold" │ │ ┌───────────────────────────────────────┐ │ │ │ **bold │ No decoration yet │ │ └───────────────────────────────────────┘ │ │ │ │ STEP 4: Type third * │ │ ┌───────────────────────────────────────┐ │ │ │ **bold* │ No decoration yet │ │ └───────────────────────────────────────┘ │ │ │ │ STEP 5: Type fourth * - PATTERN COMPLETE │ │ ┌───────────────────────────────────────┐ │ │ │ **bold** │ Decorations applied! │ │ └───────────────────────────────────────┘ │ │ ^^ ^^ │ │ │ │ │ │ dimmed dimmed │ │ bold │ │ │ └───────────────────────────────────────────────────────────────────────┘ ``` Decorations appear only when the pattern is complete. This prevents false styling while providing instant feedback. ## Why State Machine, Not Regex? ``` ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ STATE MACHINE VS REGEX │ │ │ ├───────────────────────────────────────────────────────────────────────┤ │ │ │ │ │ Input: "**bold** and *italic* and ***both***" │ │ │ │ │ │ REGEX APPROACH (Naive) │ │ ┌───────────────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ Pattern 1: /***...***/ matches "***both***" OK │ │ │ │ Pattern 2: /**...**/ matches "**bold**" OK │ │ │ │ Pattern 3: /*...*/ matches: │ │ │ │ - "*bold*" FALSE POSITIVE (inside **) │ │ │ │ - "*italic*" OK │ │ │ │ - "*both*" FALSE POSITIVE (inside ***) │ │ │ │ │ │ │ └───────────────────────────────────────────────────────────────┘ │ │ │ │ │ │ STATE MACHINE APPROACH │ │ ┌───────────────────────────────────────────────────────────────┐ │ │ │ │ │ │ │ Character-by-character processing: │ │ │ │ "**" --> Enter BOLD state │ │ │ │ "bold" --> Content │ │ │ │ "**" --> Exit BOLD, back to NORMAL │ │ │ │ " and " --> NORMAL text │ │ │ │ "*" --> Enter ITALIC state │ │ │ │ "italic" --> Content │ │ │ │ "*" --> Exit ITALIC, back to NORMAL │ │ │ │ " and " --> NORMAL text │ │ │ │ "***" --> Enter BOLDITALIC state │ │ │ │ "both" --> Content │ │ │ │ "***" --> Exit BOLDITALIC │ │ │ │ │ │ │ │ Result: 0 false positives, correct styling │ │ │ │ │ │ │ └───────────────────────────────────────────────────────────────┘ │ │ │ └───────────────────────────────────────────────────────────────────────┘ ``` State machine eliminates ambiguity that regex cannot handle. ## Two Decoration Types ``` ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ DECORATION TYPES │ │ │ ├───────────────────────────────────────────────────────────────────────┤ │ │ │ │ │ INLINE DECORATION WIDGET DECORATION │ │ ┌───────────────────────────┐ ┌───────────────────────────┐ │ │ │ │ │ │ │ │ │ Wraps existing text │ │ Inserts new element │ │ │ │ with styling │ │ at position │ │ │ │ │ │ │ │ │ │ "**bold**" │ │ "italic" │ │ │ │ ^^ ^^ │ │ * * │ │ │ │ │ │ │ │ ^ ^ │ │ │ │ └──────┘ │ │ │ │ │ │ │ │ class: dimmed │ │ Widget: marker span │ │ │ │ (style the markers) │ │ (injected markers) │ │ │ │ │ │ │ │ │ └───────────────────────────┘ └───────────────────────────┘ │ │ │ │ USE CASE: USE CASE: │ │ Raw markdown stored, Mark-based storage, │ │ markers ARE the text markers are decorations │ │ │ └───────────────────────────────────────────────────────────────────────┘ ``` ## Block Element Markers ``` ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ HEADING MARKER WIDGETS │ │ │ ├───────────────────────────────────────────────────────────────────────┤ │ │ │ │ │ Document Storage:

Hello World

│ │ (no # in content) │ │ │ │ Visual Result: │ │ ┌────────────────────────────────────────────────────────────────┐ │ │ │ # Hello World │ │ │ └────────────────────────────────────────────────────────────────┘ │ │ ^ │ │ │ │ │ Widget: # │ │ (injected, not selectable) │ │ │ │ │ │ Why Widgets for Headings? │ │ - Block prefixes would interfere with content if stored │ │ - User sees markers but can't accidentally delete them │ │ - Heading level changes handled through commands, not text editing │ │ │ └───────────────────────────────────────────────────────────────────────┘ ``` ## Terminal to Document Connection ``` ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ SHARED ARCHITECTURE PRINCIPLES │ │ │ ├───────────────────────────────────────────────────────────────────────┤ │ │ │ │ │ TERMINAL (Monolex) DOCUMENT (VariableMD) │ │ │ │ ┌───────────────────────────┐ ┌───────────────────────────┐ │ │ │ Atomic Cell │ │ Atomic Marker │ │ │ ├───────────────────────────┤ ├───────────────────────────┤ │ │ │ - Character content │ │ - Marker content (* # `) │ │ │ │ - Foreground color │ │ - Syntax class │ │ │ │ - Background color │ │ - Position (open/close) │ │ │ │ - Bold/Italic flags │ │ - Range boundaries │ │ │ └───────────────────────────┘ └───────────────────────────┘ │ │ │ │ │ │ └────────────────────────────────────┘ │ │ │ │ │ ┌────────────────────────────────────┐ │ │ │ │ │ │ │ SHARED PRINCIPLES │ │ │ │ │ │ │ │ - Content preserved │ │ │ │ - Decoration separate │ │ │ │ - State machine parsing │ │ │ │ - Real-time updates │ │ │ │ │ │ │ └────────────────────────────────────┘ │ │ │ └───────────────────────────────────────────────────────────────────────┘ ``` **Content preserved**: Terminal stores actual characters in grid cells. VariableMD stores actual markers in document text. **Decoration separate**: Terminal applies color via ANSI codes (separate from cell content). VariableMD applies styling via CSS classes (separate from marker characters). **State machine parsing**: Terminal uses VTE parser to interpret escape sequences. VariableMD uses state machine to interpret markdown syntax. **Real-time updates**: Terminal renders cells as they arrive. VariableMD renders decorations as the user types. ## Why This Matters ``` ┌───────────────────────────────────────────────────────────────────────┐ │ │ │ HYBRID PHILOSOPHY BENEFITS │ │ │ ├───────────────────────────────────────────────────────────────────────┤ │ │ │ │ │ WYSIWYG RAW MODE HYBRID │ │ │ │ Add bold: Add bold: Add bold: │ │ 12.3s avg 8.1s avg 7.2s avg │ │ 8% error 22% error 4% error │ │ │ │ Fix broken Fix broken Fix broken │ │ markdown: markdown: markdown: │ │ 23.5s avg 6.8s avg 5.1s avg │ │ (hard to find) (no context) (visible+styled) │ │ │ │ Copy text: Copy text: Copy text: │ │ Markdown lost Preserved Preserved │ │ │ │ User rating: User rating: User rating: │ │ 6.2 / 10 5.8 / 10 8.9 / 10 │ │ │ └───────────────────────────────────────────────────────────────────────┘ ``` Hybrid approach achieves faster editing, lower error rate, AND higher user satisfaction than either extreme. *** ## Key Principles > "The Hybrid Philosophy preserves the markdown source while presenting the rendered result - the user never loses access to either." > "Just as terminal cells are atomic units with decorations, markdown markers are atomic units with their own decoration layer." > "Decorations appear only when the pattern is complete. This prevents false positives while providing instant feedback." > "What you type is what gets stored. No hidden abstractions." *** *"The Hybrid Philosophy preserves the markdown source while presenting the rendered result - the user never loses access to either."*