vim-sim 1.0.2 → 1.0.3

package/docs/config-system-improvements.md

@@ -0,0 +1,221 @@
+# Configuration System Improvements
+
+**Date**: 2026-02-15
+**Summary**: Enhanced vim-sim's configuration infrastructure to make behavioral differences from vanilla Vim more obvious, cleaner, and easier to edit programmatically.
+
+## Motivation
+
+During test suite review, we discovered that vim-sim's default behavior for `h` and `l` motions (wrapping to previous/next lines) differs from vanilla Vim (which stops at line boundaries). Rather than changing vim-sim's user-friendly default, we improved the configuration system to:
+
+1. Make all behavioral differences configurable
+2. Clearly document which settings differ from Vim
+3. Provide metadata for each option
+4. Enable easy switching between vim-sim and Vim defaults
+
+## Changes Made
+
+### 1. Enhanced `VimConfig` Interface
+
+Added motion behavior options:
+
+```typescript
+interface VimConfig {
+    // ... existing options ...
+
+    // Motion behavior options (NEW)
+    whichwrap: string;       // Keys that wrap to prev/next line
+    startofline: boolean;    // Move to first non-blank when changing lines
+    virtualedit: string;     // Allow cursor past end of line
+    wrapscan: boolean;       // Search wraps around end of file
+}
+```
+
+### 2. Added `VimConfigMetadata` Interface
+
+Every option now has comprehensive metadata:
+
+```typescript
+interface VimConfigMetadata {
+    description: string;            // What the option does
+    vimDefault: string | number | boolean;    // Vim's default
+    vimSimDefault: string | number | boolean; // vim-sim's default
+    category: 'display' | 'indentation' | 'search' | 'motion' | 'editing';
+    type: 'boolean' | 'number' | 'string';
+    differsFromVim: boolean;        // Flag for different defaults
+    validValues?: string[];         // For string options
+}
+```
+
+### 3. Created `CONFIG_METADATA` Constant
+
+Complete metadata for all 18 config options:
+
+```typescript
+export const CONFIG_METADATA: Record<VimConfigKey, VimConfigMetadata> = {
+    whichwrap: {
+        description: 'Keys that wrap to prev/next line (b,s,h,l,<,>,~)',
+        vimDefault: 'b,s',
+        vimSimDefault: 'h,l',
+        category: 'motion',
+        type: 'string',
+        differsFromVim: true,
+        validValues: ['b', 's', 'h', 'l', '<', '>', '[', ']', '~'],
+    },
+    // ... 17 more options ...
+};
+```
+
+### 4. Enhanced ConfigManager Methods
+
+Added helper methods:
+
+```typescript
+// Get metadata about an option
+configManager.getMetadata(key: VimConfigKey): VimConfigMetadata
+
+// Get all options that differ from Vim
+configManager.getDifferencesFromVim(): VimConfigKey[]
+
+// Get options by category
+configManager.getByCategory(category): VimConfigKey[]
+```
+
+### 5. Updated Motion Implementations
+
+Motion classes now respect `whichwrap` configuration:
+
+```typescript
+// h, l, Backspace, ArrowLeft, ArrowRight all check whichwrap
+function canWrap(state: State, key: 'h' | 'l' | 'b' | 's' | '<' | '>'): boolean {
+    const whichwrap = state.configManager?.get('whichwrap') ?? 'h,l';
+    const allowed = whichwrap.split(',').map(s => s.trim());
+    return allowed.includes(key);
+}
+```
+
+### 6. Integrated ConfigManager into State
+
+```typescript
+export class State {
+    constructor(
+        // ... existing properties ...
+        public configManager: ConfigManager | null = null
+    ) {}
+}
+
+// Initialized in createEmptyState()
+```
+
+### 7. Enhanced Web Demo Config Panel
+
+Updated `examples/web/public/app.tsx`:
+
+- Added motion behavior section
+- Marked options that differ from Vim with `*`
+- Added string input fields for `whichwrap` and `virtualedit`
+- Reorganized options by category
+- Added notice: "🔧 Options marked with * differ from vanilla Vim defaults"
+
+### 8. Created Comprehensive Documentation
+
+**`docs/vim-compatibility.md`**:
+- Configuration system overview
+- All differences from Vim explained
+- Rationale for each difference
+- Code examples for configuration
+- Pure Vim mode setup
+- Runtime configuration with `:set`
+- Configuration change listeners
+- Complete reference table
+
+## Options That Differ from Vim
+
+| Option | vim-sim | Vim | Reason |
+|--------|---------|-----|--------|
+| `whichwrap` | "h,l" | "b,s" | Modern UX: h/l wrapping expected by new users |
+| `tabstop` | 4 | 8 | Modern code style: 4-space indentation standard |
+| `shiftwidth` | 2 | 8 | Web development: 2-space indentation common |
+| `expandtab` | true | false | Consistency: spaces prevent tab/space mixing |
+| `autoindent` | true | false | Expected behavior in modern editors |
+| `hlsearch` | true | false | Visibility: highlighting improves usability |
+| `incsearch` | true | false | Feedback: incremental search is more intuitive |
+
+**Total**: 7 out of 18 options (38.9%) differ from Vim
+
+## Usage Examples
+
+### Check Differences
+
+```typescript
+import {Session} from 'vim-sim';
+
+const session = new Session();
+const diffs = session.configManager.getDifferencesFromVim();
+// ['whichwrap', 'tabstop', 'shiftwidth', 'expandtab', 'autoindent', 'hlsearch', 'incsearch']
+```
+
+### Switch to Pure Vim Mode
+
+```typescript
+import {CONFIG_METADATA} from 'vim-sim';
+
+const vimDefaults = Object.fromEntries(
+    Object.entries(CONFIG_METADATA).map(([key, meta]) => [key, meta.vimDefault])
+);
+session.configManager.setMultiple(vimDefaults);
+```
+
+### Query Option Metadata
+
+```typescript
+import {CONFIG_METADATA} from 'vim-sim';
+
+const meta = CONFIG_METADATA.whichwrap;
+console.log(meta.description);
+// "Keys that wrap to prev/next line (b=<BS>, s=<Space>, h=h, l=l, <=<Left>, >=<Right>)"
+
+console.log(`Vim: ${meta.vimDefault}, vim-sim: ${meta.vimSimDefault}`);
+// "Vim: b,s, vim-sim: h,l"
+```
+
+## Testing
+
+- All existing tests pass ✅
+- Default `whichwrap: "h,l"` maintains current behavior
+- Tests reflect vim-sim defaults, not vanilla Vim defaults
+- Behavior is now configurable without code changes
+
+## Files Changed
+
+1. **src/core/config-manager.ts** - Added options, metadata, helper methods
+2. **src/core/state.ts** - Added configManager property
+3. **src/motions/basic.ts** - Respect whichwrap configuration
+4. **src/index.ts** - Export CONFIG_METADATA
+5. **examples/web/public/app.tsx** - Enhanced config panel
+6. **docs/vim-compatibility.md** - Comprehensive documentation
+7. **docs/config-system-improvements.md** - This document
+
+## Benefits
+
+1. **Transparency**: Users can see exactly which options differ from Vim
+2. **Flexibility**: Easy switching between vim-sim and Vim behavior
+3. **Discoverability**: Metadata makes options self-documenting
+4. **Maintainability**: All defaults centralized and documented
+5. **User Experience**: Sensible defaults for modern users, pure Vim mode available
+6. **Programmatic Access**: UI can auto-generate config panels from metadata
+
+## Next Steps
+
+1. Add more Vim options (`scrolloff`, `timeoutlen`, `mouse`, etc.)
+2. Implement `:set` command parsing for all option types
+3. Add config presets (Vim mode, Modern mode, VSCode-like, etc.)
+4. Add config export/import functionality
+5. Create migration guide for users transitioning from Vim
+6. Add telemetry to track which options users customize most
+
+## Related
+
+- Original issue: h/l wrapping differs from Vim
+- Test suite review findings
+- Vim documentation: `vim_specs/options.txt`
+- Reference: `vim_specs/motion.txt` (whichwrap behavior)

package/docs/vim-compatibility.md

@@ -0,0 +1,246 @@
+# Vim Compatibility & Configuration
+
+vim-sim aims to be a faithful Vim implementation while providing sensible defaults for modern development. This document explains how vim-sim's defaults differ from vanilla Vim and how to configure behavior.
+
+## Philosophy
+
+vim-sim follows these principles:
+
+1. **Configurable by default** - All behavior differences are controlled through the config system
+2. **Modern defaults** - Default settings optimized for modern workflows
+3. **Vim compatibility mode** - Easy switching to pure Vim behavior
+4. **Clear documentation** - All differences are documented and marked
+
+## Configuration System
+
+vim-sim uses a comprehensive configuration system that mirrors Vim's options:
+
+```typescript
+import {Session, ConfigManager, CONFIG_METADATA} from 'vim-sim';
+
+const session = new Session();
+
+// Get current config
+const config = session.configManager.getAll();
+
+// Set individual options
+session.configManager.set('whichwrap', 'b,s');  // Vim default
+session.configManager.set('whichwrap', 'h,l');  // vim-sim default
+
+// Set multiple options
+session.configManager.setMultiple({
+    number: true,
+    relativenumber: true,
+    expandtab: false,  // Use tabs instead of spaces
+});
+
+// Check which options differ from Vim
+const differences = session.configManager.getDifferencesFromVim();
+console.log('Options that differ from Vim:', differences);
+
+// Get metadata about an option
+const metadata = session.configManager.getMetadata('whichwrap');
+console.log(metadata.description);
+console.log('Vim default:', metadata.vimDefault);
+console.log('vim-sim default:', metadata.vimSimDefault);
+```
+
+## Key Differences from Vanilla Vim
+
+### Motion Behavior
+
+#### `whichwrap` (Default: `"h,l"` | Vim: `"b,s"`)
+
+**vim-sim default**: The `h` and `l` keys wrap to the previous/next line at line boundaries.
+
+**Vim default**: Only `<BS>` and `<Space>` wrap; `h` and `l` stop at line boundaries.
+
+**Rationale**: Modern users expect horizontal navigation to wrap across lines, similar to arrow keys in most editors. This makes vim-sim more intuitive for new users while remaining easily configurable.
+
+**To use Vim behavior**:
+```typescript
+session.configManager.set('whichwrap', 'b,s');
+```
+
+**Available values**:
+- `b` - `<BS>` wraps in Normal and Visual mode
+- `s` - `<Space>` wraps in Normal and Visual mode
+- `h` - `h` wraps in Normal and Visual mode (vim-sim default includes this)
+- `l` - `l` wraps in Normal and Visual mode (vim-sim default includes this)
+- `<` - `<Left>` wraps in Normal and Visual mode
+- `>` - `<Right>` wraps in Normal and Visual mode
+- `[` - `<Left>` wraps in Insert and Replace mode
+- `]` - `<Right>` wraps in Insert and Replace mode
+
+Combine with commas: `"h,l,<,>"` allows h, l, and arrow keys to wrap.
+
+### Indentation
+
+#### `tabstop` (Default: `4` | Vim: `8`)
+
+**Rationale**: Modern code styles typically use 4-space indentation rather than 8.
+
+#### `shiftwidth` (Default: `2` | Vim: `8`)
+
+**Rationale**: 2-space indentation is common in JavaScript, TypeScript, and web development.
+
+#### `expandtab` (Default: `true` | Vim: `false`)
+
+**Rationale**: Spaces are more consistent across editors and environments. This prevents tab/space mixing issues.
+
+#### `autoindent` (Default: `true` | Vim: `false`)
+
+**Rationale**: Auto-indentation is expected behavior in modern editors.
+
+### Search
+
+#### `hlsearch` (Default: `true` | Vim: `false`)
+
+**Rationale**: Highlighting search matches improves visibility and usability.
+
+#### `incsearch` (Default: `true` | Vim: `false`)
+
+**Rationale**: Incremental search provides immediate feedback, improving the search experience.
+
+## Pure Vim Mode
+
+To configure vim-sim with vanilla Vim defaults:
+
+```typescript
+const vimDefaults = {
+    // Motion behavior
+    whichwrap: 'b,s',
+    startofline: true,
+    virtualedit: '',
+
+    // Indentation
+    tabstop: 8,
+    shiftwidth: 8,
+    expandtab: false,
+    autoindent: false,
+    smartindent: false,
+
+    // Search
+    hlsearch: false,
+    incsearch: false,
+    wrapscan: true,
+    ignorecase: false,
+    smartcase: false,
+
+    // Display
+    number: false,
+    relativenumber: false,
+    wrap: true,
+    cursorline: false,
+
+    // Editing
+    undolevels: 1000,
+    clipboard: '',
+};
+
+session.configManager.setMultiple(vimDefaults);
+```
+
+Or use the convenience helper:
+
+```typescript
+import {CONFIG_METADATA} from 'vim-sim';
+
+// Set all options to their Vim defaults
+const vimDefaults = Object.fromEntries(
+    Object.entries(CONFIG_METADATA).map(([key, meta]) => [key, meta.vimDefault])
+);
+session.configManager.setMultiple(vimDefaults);
+```
+
+## Configuration Metadata
+
+Every config option includes metadata accessible via `CONFIG_METADATA`:
+
+```typescript
+import {CONFIG_METADATA} from 'vim-sim';
+
+const option = CONFIG_METADATA.whichwrap;
+
+console.log(option.description);      // Full description
+console.log(option.vimDefault);       // Vim's default value
+console.log(option.vimSimDefault);    // vim-sim's default value
+console.log(option.category);         // Option category
+console.log(option.type);             // Value type
+console.log(option.differsFromVim);   // true if defaults differ
+console.log(option.validValues);      // Array of valid values (for strings)
+```
+
+## Runtime Configuration
+
+Options can be changed at runtime using `:set` commands (in command mode):
+
+```
+:set number           " Enable line numbers
+:set nonumber         " Disable line numbers
+:set tabstop=4        " Set tab stop to 4
+:set whichwrap=h,l    " Allow h and l to wrap
+```
+
+## Listening to Configuration Changes
+
+Subscribe to configuration changes:
+
+```typescript
+// Listen to specific option
+const unsubscribe = session.configManager.onChange('number', (key, value) => {
+    console.log(`${key} changed to ${value}`);
+    // Update UI, refresh display, etc.
+});
+
+// Listen to all changes
+session.configManager.onChange('*', (key, value) => {
+    console.log(`Any option changed: ${key} = ${value}`);
+});
+
+// Unsubscribe when done
+unsubscribe();
+```
+
+## Reference: All Options
+
+| Option | Category | Type | vim-sim | Vim | Differs |
+|--------|----------|------|---------|-----|---------|
+| `number` | display | boolean | false | false | ❌ |
+| `relativenumber` | display | boolean | false | false | ❌ |
+| `wrap` | display | boolean | true | true | ❌ |
+| `cursorline` | display | boolean | false | false | ❌ |
+| `tabstop` | indentation | number | 4 | 8 | ✅ |
+| `shiftwidth` | indentation | number | 2 | 8 | ✅ |
+| `expandtab` | indentation | boolean | true | false | ✅ |
+| `autoindent` | indentation | boolean | true | false | ✅ |
+| `smartindent` | indentation | boolean | false | false | ❌ |
+| `ignorecase` | search | boolean | false | false | ❌ |
+| `smartcase` | search | boolean | false | false | ❌ |
+| `hlsearch` | search | boolean | true | false | ✅ |
+| `incsearch` | search | boolean | true | false | ✅ |
+| `wrapscan` | search | boolean | true | true | ❌ |
+| `whichwrap` | motion | string | "h,l" | "b,s" | ✅ |
+| `startofline` | motion | boolean | true | true | ❌ |
+| `virtualedit` | motion | string | "" | "" | ❌ |
+| `undolevels` | editing | number | 1000 | 1000 | ❌ |
+| `clipboard` | editing | string | "" | "" | ❌ |
+
+**Total**: 8 options differ from vanilla Vim (marked with ✅)
+
+## Future Options
+
+Planned options for future releases:
+
+- `scrolloff` - Lines of context around cursor
+- `sidescroll` - Columns to scroll horizontally
+- `timeoutlen` - Time to wait for key sequence
+- `mouse` - Mouse support
+- `background` - Dark or light background
+- And more...
+
+## See Also
+
+- [Official Vim Documentation](../vim_specs/) - Complete Vim option reference
+- [vim_specs/options.txt](../vim_specs/options.txt) - All Vim options
+- [vim_specs/motion.txt](../vim_specs/motion.txt) - Motion behavior documentation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vim-sim",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "A complete Vim editor simulation engine for Node.js with 85%+ test coverage. Implements motions, operators, visual mode, text objects, macros, marks, undo/redo tree, spell checking, and more.",
   "keywords": [
     "vim",