Validate editor, review PRs, and extend features

.docs/summary-benches-markdown-bench-rs.md

@@ -0,0 +1,153 @@
+# File Summary: benches/markdown_bench.rs
+
+## File Path
+`benches/markdown_bench.rs`
+
+## Purpose
+Performance benchmarking suite using Criterion to measure markdown-to-HTML conversion speed in native Rust environment (non-WASM). Provides baseline performance metrics for optimization efforts and regression testing.
+
+## Key Components
+
+### Benchmark Configuration
+- **`criterion_group!(benches, benchmark_markdown)`** - Defines benchmark group
+- **`criterion_main!(benches)`** - Entry point for Criterion benchmark runner
+- Uses `#[bench]` harness = false in Cargo.toml to use Criterion instead of built-in benchmarking
+
+### Test Data
+- **`BENCHMARK_TEXT`** - Standardized markdown sample for consistent measurements
+  - Same content as `tests/web.rs` for cross-environment comparison
+  - Includes diverse markdown syntax:
+    - 3 levels of headings
+    - Bold and italic formatting
+    - Nested lists (unordered and ordered)
+    - Blockquotes
+    - Fenced code blocks with language specification
+    - Links
+    - Tables
+  - Represents realistic document complexity
+
+## Benchmark Functions
+
+### `benchmark_markdown(c: &mut Criterion)`
+**Purpose**: Measures raw markdown conversion performance
+
+**Implementation**:
+- Creates `Options::default()` outside timing loop (warm-up)
+- Uses `black_box()` to prevent compiler optimizations
+- Calls `markdown::to_html_with_options()` repeatedly
+- Criterion automatically:
+  - Determines optimal iteration count
+  - Calculates statistical metrics (mean, median, std dev)
+  - Detects performance regressions
+  - Generates detailed reports
+
+**Metrics Captured**:
+- Throughput (iterations per second)
+- Mean execution time
+- Standard deviation
+- Confidence intervals
+- Outlier detection
+
+## Dependencies
+- `criterion` (0.5) - Statistical benchmarking framework
+  - Provides `black_box()` to prevent optimization
+  - Handles warm-up, iteration counting, and statistical analysis
+  - Generates HTML reports with graphs
+- `markdown` - Same conversion library used in production code
+- `terraphim_editor` - Project crate (for potential future benchmarks)
+
+## Integration Points
+
+### Execution
+- **Command**: `cargo bench`
+- **Output**: Console summary + HTML report in `target/criterion/`
+- **Baseline Comparison**: Can save baselines for regression detection
+
+### CI/CD Integration
+- Can be integrated into automated performance testing
+- Baseline comparisons catch performance regressions
+- Results can be tracked over time
+
+## Notable Patterns
+
+### Black Box Pattern
+```rust
+markdown::to_html_with_options(black_box(BENCHMARK_TEXT), &options)
+```
+- Prevents compiler from optimizing away the actual work
+- Ensures realistic measurements
+- Forces full execution path
+
+### Options Reuse
+- Creates `Options::default()` once before benchmark
+- Avoids measuring allocation/initialization overhead
+- Focuses purely on conversion logic
+
+## Performance Characteristics
+
+### What This Measures
+- **Pure Rust Performance**: Native code without WASM overhead
+- **Conversion Algorithm Speed**: Core markdown parsing and HTML generation
+- **Baseline for WASM Comparison**: Compare against `tests/web.rs` benchmark
+
+### What This Doesn't Measure
+- WASM runtime overhead
+- DOM manipulation speed
+- Event handler latency
+- Browser-specific performance
+- Memory allocation patterns
+
+## Benchmark Results Interpretation
+
+### Typical Metrics
+- **Mean Time**: Average conversion time per iteration
+- **Throughput**: Conversions per second
+- **Variance**: Consistency of performance
+- **Outliers**: Anomalous measurements (GC, system interruption)
+
+### Comparison with Browser Tests
+- Native benchmarks typically faster than WASM + DOM updates
+- Browser test (`tests/web.rs`) measures end-to-end performance
+- This benchmark isolates conversion logic
+
+## Use Cases
+
+### Development Workflow
+1. **Optimization**: Measure impact of code changes
+2. **Regression Detection**: Catch performance degradation
+3. **Profiling Guide**: Identify hot paths for optimization
+4. **Algorithm Comparison**: Evaluate alternative implementations
+
+### Performance Goals
+- Establish baseline performance metrics
+- Set acceptable performance thresholds
+- Track performance trends over project lifetime
+- Validate optimization efforts
+
+## Technical Considerations
+
+### Benchmark Accuracy
+- Criterion runs multiple iterations for statistical significance
+- Outlier filtering removes anomalous measurements
+- Warm-up iterations prevent cold-start bias
+- Uses high-precision timers
+
+### Platform Variations
+- Performance varies by CPU, OS, and system load
+- Important to benchmark on target deployment platforms
+- Relative measurements more reliable than absolute
+
+### Optimization Considerations
+- Results guide optimization priorities
+- Helps identify whether WASM overhead or algorithm is bottleneck
+- Can benchmark individual functions by extracting them
+
+## Improvement Opportunities
+- Add benchmarks for different document sizes (small, medium, large, huge)
+- Benchmark individual markdown features separately
+- Add memory usage profiling
+- Compare different markdown crate options
+- Benchmark with different `Options` configurations
+- Add worst-case scenarios (deeply nested structures, very long lines)
+- Benchmark incremental updates vs full re-rendering
+- Profile allocation patterns

.docs/summary-build-sh.md

@@ -0,0 +1,133 @@
+# File Summary: build.sh
+
+## File Path
+`build.sh`
+
+## Purpose
+Production build orchestration script that coordinates the full build pipeline: compiling Rust to WASM, bundling JavaScript, and assembling an NPM-ready package with examples for all module formats.
+
+## Build Pipeline
+
+### Step 1: WASM Compilation
+```bash
+wasm-pack build --target web
+```
+- Compiles Rust to WASM for web target
+- Generates `pkg/` directory with:
+  - `terraphim_editor_bg.wasm` (compiled module)
+  - `terraphim_editor.js` (JavaScript bindings)
+  - `package.json` (auto-generated)
+
+### Step 2: NPM Dependencies
+```bash
+npm install
+```
+- Installs Vite and plugins
+- Required for JavaScript bundling step
+
+### Step 3: Vite Build
+```bash
+npm run build
+```
+- Runs `vite build` (configured in `vite.config.js`)
+- Produces multi-format library bundles in `dist/`
+- Creates ESM, UMD, and IIFE variants
+
+### Step 4: Package Assembly
+```bash
+rm -rf package
+mkdir -p package/dist/{js,css,wasm}
+```
+- Cleans previous package output
+- Creates directory structure for npm package
+
+### Step 5: Artifact Copying
+```bash
+cp -r dist/* package/dist/
+cp -r public/wasm/* package/dist/wasm/
+cp -r public/js/config.js package/dist/js/
+cp -r public/css/terraphim-editor.css package/dist/css/
+cp README.md LICENSE package/
+```
+- Consolidates all build artifacts into `package/`
+- Includes WASM binaries, JS bundles, CSS, and metadata files
+
+### Step 6: Package.json Generation
+```bash
+VERSION=$(grep '^version' Cargo.toml | head -1 | cut -d '"' -f 2)
+cat > package/package.json << EOL
+...
+EOL
+```
+- Extracts version from `Cargo.toml` (single source of truth)
+- Generates npm-compatible `package.json`
+- Defines entry points for all module formats
+- Specifies exports map and peer dependencies
+
+### Step 7: Example File Generation
+Creates three example HTML files demonstrating different module formats:
+- `example-esm.html` — ES module with import map
+- `example-umd.html` — Universal module with global variable
+- `example-iife.html` — Immediately-invoked function expression
+
+Each example shows:
+- How to include the library
+- How to initialize the editor
+- Container setup
+- WASM URL configuration
+
+## Output Structure
+```
+package/
+├── dist/
+│   ├── js/
+│   │   ├── terraphim-editor.mjs (ESM)
+│   │   ├── terraphim-editor.umd.js (UMD)
+│   │   ├── terraphim-editor.iife.js (IIFE)
+│   │   ├── terraphim-editor.d.ts (TypeScript)
+│   │   └── config.js
+│   ├── css/
+│   │   └── terraphim-editor.css
+│   └── wasm/
+│       └── terraphim_editor_bg.wasm
+├── package.json
+├── README.md
+├── LICENSE
+└── example-*.html (3 files)
+```
+
+## Key Features
+
+### Version Synchronization
+- Single version source in `Cargo.toml`
+- Automatically propagated to npm package
+- Prevents version mismatch between Rust and JS
+
+### Module Format Support
+- **ESM**: Modern bundlers (Webpack, Rollup, Vite)
+- **UMD**: Node.js, RequireJS, browser globals
+- **IIFE**: Direct CDN/script tag usage
+
+### Complete Examples
+- Each module format has working example
+- Shows integration best practices
+- Demonstrates async initialization pattern
+
+## Integration Notes
+- Run after code changes to prepare for publishing
+- Output in `package/` ready for `npm publish`
+- Examples can be tested directly in browser
+
+## Error Handling
+- No explicit error checking (relies on command failures)
+- Commands fail fast (bash default behavior)
+- Should add `set -e` for explicit fail-fast
+
+## Improvement Opportunities
+- Add `set -e` for strict error handling
+- Add `set -x` option for debugging
+- Validate `pkg/` existence before copying
+- Add checksum/integrity verification
+- Generate TypeScript declaration files
+- Add build artifact size reporting
+- Implement incremental builds (skip unchanged steps)