editor

Module: Editor

Generated by Cicadas Bootstrap on 2026-03-22.

Purpose

The editor package (@aprovan/patchwork-editor) provides a markdown editing system with embedded code block management, AI-driven edit sessions, file tree navigation, and diff previews. It bridges the gap between natural-language content (markdown) and executable widget code by extracting code blocks, enabling edits, and reconciling changes back into the markdown source.

Interfaces

Exports:

• <MarkdownEditor> — TipTap-based WYSIWYG markdown editor with toolbar
• <MarkdownPreview> — Read-only/editable markdown viewer with frontmatter support
• <CodePreview> — Syntax-highlighted code display (Shiki) with copy-to-clipboard
• <CodeBlockExtension> — TipTap node extension for interactive code blocks
• <WidgetPreview> — Iframe-based compiled widget preview with error boundary
• <ServicesInspector> — Debug panel showing available service signatures
• <EditModal> — Full edit session UI: file tree + code view + diff preview + save
• <SaveConfirmDialog> — Diff review before saving
• useEditSession() — State machine hook managing the edit lifecycle
• extractCodeBlocks() — Parse markdown to extract code blocks with metadata
• applyDiff() — Apply unified diff format to code content

Dependencies:

• @tiptap/react, @tiptap/starter-kit, tiptap-markdown — Rich text editing
• shiki — Syntax highlighting
• @aprovan/patchwork-compiler — For compilation and VFS in edit sessions

Subsystems

Markdown Editing

• MarkdownEditor.tsx — Full WYSIWYG editor built on TipTap with markdown serialization
• MarkdownPreview.tsx — Lightweight viewer that separates YAML frontmatter from body content
• CodeBlockExtension.tsx — Custom TipTap node with language selector dropdown

Code Management

• lib/code-extractor.ts — Parses markdown to extract code blocks with language, filename, and region metadata; reconstructs projects from extracted blocks
• lib/diff.ts — Unified diff parsing and application; sanitizes diff markers
• CodePreview.tsx — Renders code with Shiki highlighting and copy button

Edit Sessions

• edit/useEditSession.ts — State machine: idle → requesting → compiling → previewing → confirming → saving; tracks edit history with rollback support
• edit/EditModal.tsx — Orchestrator component: FileTree sidebar, CodeBlockView main area, EditHistory panel
• edit/FileTree.tsx — Hierarchical file browser with search, type filtering, rename/delete
• edit/CodeBlockView.tsx — Side-by-side original vs. edited code with diff highlighting
• edit/SaveConfirmDialog.tsx — Final diff review before committing changes
• edit/EditHistory.tsx — Timeline of edit operations with rollback capability
• edit/MediaPreview.tsx — Preview for non-code files (images, etc.)

Utilities

• lib/vfs.ts — VFS helpers using IndexedDB for project persistence in the editor
• lib/utils.ts — General editor utilities

Key Decisions

• Markdown as the source of truth: Code lives inside markdown code blocks; the editor extracts, modifies, and re-embeds code rather than maintaining separate source files.
• State machine for edit sessions: The useEditSession hook enforces a strict lifecycle (request → compile → preview → save) preventing partial or inconsistent edits.
• TipTap over alternatives: Chosen for its extensibility (custom node views for code blocks) and built-in markdown serialization.