# Web Vim With Node Template Docs

Practical docs for the BrowserPod-powered Vim editor, filesystem bridge, terminal workflow, and learning tools.

Back to Template
Filter sections

## Overview

Web Vim With Node Template is a browser-based Vim workflow built on `vim-wasm` and BrowserPod. The editor is rendered on a canvas, files are stored in BrowserPod under `/vimamp`, and terminal commands are translated through a controlled shell layer.

- Vim engine: `vim-wasm` running in-browser.
- Runtime and filesystem: BrowserPod.
- Default workspace root: `/vimamp`.
- Training file: `/vimamp/vim-training.txt`.
- Default note file: `/vimamp/note.txt`.

## Quick Start

1. Open the template and choose `Editor` from the entry menu.
2. Open `View > Show Filetree` and select a file.
3. Edit in Vim, then run `:BPSave` to sync to BrowserPod.
4. Use `View > Show Terminal` to run Node/npm commands.
5. Use `File > Save As...` for explicit filename saves.

## Entry Menu

The entry screen supports keyboard-first navigation.

- `Editor`: starts full editor mode.
- `Help > Tutorial`: opens Learn mode.
- `Help > Cheat Sheet`: opens command reference page.
- `Help > Docs`: opens this documentation page.
- `Settings > Macros`: opens macro/keymap page.
- `Settings > Theme`: opens theme editor page.

## Filesystem Model

The template manages files in BrowserPod at `/vimamp`. The filetree and commands enforce this root to avoid path escapes.

- Root is fixed to `/vimamp`.
- Filetree is a left docked panel, not overlay.
- File operations (`mkdir`, `touch`, `mv`, `rm`) trigger refresh and keep tabs synchronized.
- Imports write into BrowserPod using binary-safe file handling.

## Vim Buffer Sync

Vim buffers and BrowserPod files are synced by explicit commands to avoid accidental writes.

- `:BPSave` writes active buffer to BrowserPod path.
- `:BPEdit /absolute/path` opens BrowserPod files by path.
- Save actions in menu call the same sync pipeline.

## Terminal Behavior

The visible terminal is a template shell UI that routes commands into BrowserPod. It is intended for project commands without requiring users to learn BrowserPod internals.

### Supported command families

- Native UI commands: `help`, `pwd`, `cd`, `ls`, `cat`, `open`, `save`, `mkdir`, `touch`, `mv`, `rm`.
- Pass-through commands: `npm ...`, `node <file.js>`.

### Intentional guardrails

- `node -e` is blocked in this command path.
- `npm exec` is blocked in this command path.
- Paths are constrained to `/vimamp`.

## Running Node Projects

Typical project flow in the template terminal:

    cd my-project
    npm install
    npm run dev -- --host 0.0.0.0 --port 4173

Some packages with native binaries can fail on WASM platform targets. If this happens, use package-specific WASM settings or alternate tooling that supports wasm32.

## Portal Preview URLs

BrowserPod app servers are exposed through portal URLs, not your host `localhost`.

- When a portal is emitted, the template logs `[portal] https://...`.
- Use `View > Open Last Portal` to open the latest BrowserPod app URL.
- The menu item stays disabled until a portal has been discovered.

## Theme and Appearance

- Theme editor page provides templates and per-token colors.
- Theme profile is stored in session and in BrowserPod config when available.
- Syntax highlighting can be toggled in `View`.
- Default font rendering is constrained to safe monospace settings.

## Learn Mode and Cheat Sheet

- Learn mode tracks session accuracy, keys, and errors.
- Lesson controls: previous, restart, next, exit.
- Cheat sheet page offers quick command filtering.

## Storage and Reset Notes

- BrowserPod files are persisted in browser storage, scoped per origin.
- Clearing site data for the active origin resets files and runtime state.
- Theme/session settings use browser session/local storage.

## Troubleshooting

### Terminal output missing for npm/node

- Refresh the page once after updates to shell bridge logic.
- Verify command is pass-through safe (`npm ...`, `node file.js`).

### Dev server runs but localhost is empty

- Use the portal URL reported by the template.
- Open it via `View > Open Last Portal`.

### Vim canvas text looks distorted

- Refresh so latest theme/font settings apply.
- Re-open editor from entry menu if needed.