varrockbank · varrockbank · Jan 14, 2026 · Jan 12, 2026 · Jan 12, 2026 · Jan 12, 2026
diff --git a/API.md b/API.md
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -1,20 +1,20 @@
 # Claude Instructions for buffee
 
-**Documentation:** `docs/` folder
-- `docs/onboarding.md` — Getting started guide
-- `docs/api.md` — API surface reference
-- `docs/extensions.md` — Extension documentation
+**Full API reference: `docs/`** — Read these files for complete documentation:
+- `docs/api.txt` — Model, View, Span, Mode API
+- `docs/onboarding.md` — Getting started, sizing, keybindings
+- `docs/combinators.md` — Combinator documentation
 
 ## Quick Reference
 
 ```javascript
-BuffeeStatusLine(new Buffee(el, { rows: 20, cols: 80, s: 4 }));
+BuffeeStatusLine(new Buffee(el, { h: 20, w: 80, s: 4 }));
 
-editor.Model.s = "content";   // Set content
-editor.Model._;               // ["line1", "line2"]
-editor.View.set(5);           // Scroll to line index 5
-editor.Span.ins("text");      // Insert at cursor
-editor.Span.cursor({y:0,x:0});// Move cursor
+editor.Model._ = ["line1", "line2"];  // Set content (array of lines)
+editor.View.render();                 // Render after content changes
+editor.View.first = 5;                // Scroll to line index 5
+editor.Span.ins(["text"]);            // Insert at cursor
+editor.Span.cursor({y:0,x:0});        // Move cursor
 ```
 
 ## Required HTML Structure
@@ -28,6 +28,17 @@ See `web/template.html` for the required HTML structure. Missing any element wil
 - `samples/*.html` (all sample files)
 - `web/themes.html`
 
+## API Changes
+
+**When changing the Buffee API (config options, method names, namespaces), also update:**
+- `wrappers/react.jsx` - React component props and config
+- `wrappers/svelte.svelte` - Svelte component props and config
+- `wrappers/vue.js` - Vue component props and config
+- `docs/api.txt` - API reference
+- `web/getting-started.html` - Usage examples
+- `web/wrappers.html` - Wrapper documentation
+- `dev/changelog.txt` - Add entry for wrapper updates
+
 ## Cursor Model (Vim-style)
 
 - **Cursor sits ON a character**, not between characters
@@ -85,12 +96,12 @@ left with alt
 EXPECT cursor at 0,5
 ```
 
-## Extensions
+## Combinators
 
-Located in `extensions/`, tested in "Extensions" tab of `test/index.html`.
+Located in `combinators/`, tested in "Combinators" tab of `test/index.html`.
 
-**When adding an extension, also update:**
-- `web/extensions.html` (documentation)
+**When adding a combinator, also update:**
+- `web/combinators.html` (documentation)
 - `samples/index.html` (if adding a sample)
 
 | File | Function | Description |
@@ -103,6 +114,7 @@ Located in `extensions/`, tested in "Extensions" tab of `test/index.html`.
 | `tui.js` | `BuffeeTUI(editor)` | Text-based UI via text manipulation |
 | `ios.js` | `BuffeeIOS(editor)` | iOS touch/keyboard support |
 | `fileloader.js` | `BuffeeFileLoader(editor)` | File loading strategies |
+| `sanitize.js` | `BuffeeSanitize(editor)` | Tab/Unicode sanitization |
 | `ultrahighcapacity.js` | `BuffeeUltraHighCapacity(editor)` | 1B+ line support |
 | `treesitter.js` | `BuffeeTreeSitter(editor, opts)` | Tree-sitter integration |
 
@@ -139,7 +151,7 @@ GitHub Pages serves from root. CI screenshot tests run against these (see `snaps
 |------|---------|
 | `template.html` | Required HTML structure |
 | `getting-started.html` | Setup guide |
-| `extensions.html` | Extension documentation |
+| `combinators.html` | Combinator documentation |
 | `themes.html` | Theme showcase |
 | `comparison.html` | Editor comparison |
 | `performance.html` | Performance research |
@@ -148,7 +160,7 @@ GitHub Pages serves from root. CI screenshot tests run against these (see `snaps
 **assets/** (internal):
 - `reset.css` - CSS reset (web-specific)
 
-Templates: `extensions/_template.js`, `samples/_template.html`, `themes/_template.css`
+Templates: `combinators/_template.js`, `samples/_template.html`, `themes/_template.css`
 
 ## DOM Classes Reference
 
@@ -163,7 +175,6 @@ Templates: `extensions/_template.js`, `samples/_template.html`, `themes/_templat
 | `.buffee-layer-elements` | Overlay | TUI/Elementals overlay |
 | `.buffee-caret` | Cursor | Blinking cursor |
 | `.buffee-status` | Status bar | Bottom bar container |
-| `.buffee-clip` | `<textarea>` | Hidden, for clipboard |
 
 ## Keybindings Reference
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,18 +1,19 @@
 # Commits 
 
-## Scopes:
+## Directory structure
 
 web - github pages related stuff
 test - test related stuff 
-
-## Files 
-
 assets - for github pages assets 
+samples - examples
+theme - css themess 
+wrappers - Component wrappers in JavaScript UI frameworks
+resources - test files, mostly for load testing 
 
-## Extensions 
+## Combinators
 
-1. Add to extensions directory
-2. update web/extensions.html 
+1. Add to combinators directory
+2. update web/combinators.html
 
 ## Distributable
 

diff --git a/README.md b/README.md
@@ -9,7 +9,7 @@ Inspired by the experience of terminal interfaces and Vim, Buffee is a microlibr
 - tiny: ~2kb (gz+min) fooprint, low memory/CPU overhead
 - performant: rivals native editors like Vim - no slowdown on large files
 - hassle-free: no build step, no NPM, no dependencies
-- programmable: extensions, hackable internals, minimal API
+- programmable: combinators, hackable internals, minimal API
 - heavy-duty: ~70m SLOC file capacity, 1B+ in high-capacity mode 
 
 Yes - like Emacs, it includes a text editor too.
@@ -32,8 +32,7 @@ See [comparison](https://varrockbank.github.io/buffee/web/comparison.html) and [
 
 ## The Magic Trick
 
-The crux is maintaining a small DOM footprint. This is achieved by maintain a virtual viewport and being 
-smart in surgically rendering only what's changed. 
+The crux is maintaining a small DOM footprint. This is achieved by maintain a virtual viewport and being smart in surgically rendering only what's changed. 
 
 The zeitgeist of webdev is VDOM. This does not come free. VDOM libraries are bulkier than Buffee in its entirety because they deal with arbitrary trees. Buffee avoids this 
 with a predictable and narrowly constrained UI surface space. 
@@ -44,17 +43,31 @@ Finally, (V8) arrays, not being real arrays, prove miraculuously viable as a buf
 
 ## Usage
 
-### Font Requirements
+### Monowidth Character Handling
+
+Buffee's fixed-width grid layout requires all characters to occupy exactly one cell. This section covers common issues that break grid alignment.
+
+#### Font Requirements
 
 Buffee assumes monospace fonts having accurate CSS `ch` values. If this assumption breaks, the cursor position
-will be visually misaligned from true position. This is  evident with variable-width 
-text but some monospace fonts can cause "drift", fractions of a pixel per character, that accumulate numerical errors. 
+will be visually misaligned from true position. This is  evident with variable-width
+text but some monospace fonts can cause "drift", fractions of a pixel per character, that accumulate numerical errors.
 
 - **Good:** Menlo, Consolas, `monospace` (generic)
 - **Bad:** Monaco
 
 To test: type "A" 100+ times and move cursor to end. If misaligned, try a different font.
 
+#### Tab Sanitization
+
+Tab characters (`\t`) break grid alignment because browsers render them as variable-width. Buffee core does not sanitize input—if you set content containing tabs via `Model.s` or `Span.ins()`, they appear as-is.
+
+**Solutions:**
+- **BuffeeSanitize combinator** — Automatically converts tabs to spaces, removes zero-width characters, and normalizes multi-width Unicode spaces. See [Sanitize combinator](web/combinators.html#sanitize).
+- **Pre-sanitize** — Clean your text before passing to Buffee: `text.replace(/\t/g, '    ')`
+
+The keyboard controller already handles Tab key presses by inserting spaces (based on `Mode.s`), so typed tabs are not an issue—only programmatic content.
+
 ### CSS 
 
 [style.css](style.css) contains structural styles. Bring-your-own cursor and selection color: 
@@ -74,7 +87,6 @@ Editor instances attach to a root node having such structure:
 
 ```html
 <div class="buffee" id="editor">
-  <textarea class="buffee-clip" aria-hidden="true"></textarea>
   <div class="no-select buffee-pane">
     <!-- Can omit optional gutter rail -->
     <div class="buffee-rail"></div>
@@ -110,9 +122,9 @@ const editor = new Buffee(document.getElementById("editor"), {});
 Editor auto-fits to its container size. For fixed dimensions:
 
 ```javascript
-new Buffee(el, { rows: 20 });      // Fixed row count
-new Buffee(el, { cols: 80 });      // Fixed column width
-new Buffee(el, { rows: 20, cols: 80 }); // Both fixed
+new Buffee(el, { h: 20 });      // Fixed row count
+new Buffee(el, { w: 80 });      // Fixed column width
+new Buffee(el, { h: 20, w: 80 }); // Both fixed
 ```
 
 Container should have explicit height inherit some percentage from parent. 
@@ -125,24 +137,22 @@ Container should have explicit height inherit some percentage from parent.
 
 **View** `editor.View` represents the virtual viewport
 
-`editor.View._` is the buffer lines in view
-
 **Span** `editor.Span` represents a text selection. Cursors are the special case of this where the
 anchor and the head/dot are the same. Text editing operations are defined relative to this selection.
 
-The controller are keyboard event handlers which route to operations on the selection. In the future, the basic controller will be refactored out of Buffee.js as an Extension such that you will have to bring-your-own controller by default. e.g. a "vim normal mode controller".
+The controller are keyboard event handlers which route to operations on the selection. In the future, the basic controller will be refactored out of Buffee.js as a Combinator such that you will have to bring-your-own controller by default. e.g. a "vim normal mode controller".
 
-See: [API Reference](docs/api.md) | [Getting Started](docs/onboarding.md)
+See: [API Reference](docs/api.txt) | [Getting Started](docs/onboarding.md)
 
-## Extensibility
+## Combinators
 
-Extensions use the decorator pattern - pure functions that wrap the editor, being an editor instance themselves, meaning they can be combined:
+Combinators use the decorator pattern - pure functions that wrap the editor, being an editor instance themselves, meaning they can be combined:
 
 ```javascript
-// Single extension
+// Single combinator
 const editor = BuffeeHistory(new Buffee(container, config));
 
-// Multiple extensions (compose by nesting)
+// Multiple combinators (compose by nesting)
 const editor = BuffeeElementals(
   BuffeeSyntax(
     BuffeeHistory(
@@ -151,23 +161,24 @@ const editor = BuffeeElementals(
   )
 );
 
-// Extensions expose APIs on the editor instance
+// Combinators expose APIs on the editor instance
 editor.History.undo();
 editor.Syntax.setLanguage('javascript');
 editor.Elementals.addButton({ row: 0, col: 0, label: 'OK' });
 ```
 
-Available extensions:
+Available combinators:
 - **History** - Undo/redo with operation coalescing
-- **UndoTree** - Tree-based undo that preserves all branches
 - **Syntax** - Regex-based syntax highlighting
 - **Elementals** - DOM-based UI elements (buttons, inputs)
 - **TUI** - Terminal UI via text manipulation
 - **FileLoader** - Multiple strategies for large file loading
 - **UltraHighCapacity** - Gzip-compressed storage for 1B+ lines
 - **iOS** - Touch and on-screen keyboard support
+- **Sanitize** - Tab/Unicode normalization for programmatic content
 
-See: [Extensions](docs/extensions.md)
+See: [Dev Guide on Combinators](docs/combinators.md)
+See: [Combinator Gallery](web/combinators.html)
 
 ## Versioning