Wisp VS Code Extension Seed

Purpose: starter resources for building a pure TypeScript VS Code extension that emulates Wisp/Helix-style modal editing without depending on the wi executable.

This directory is intended to be copied into a new repository.

Features

• Helix/Wisp-style normal, insert, and select modes.
• Word, WORD, line, file, goto, search, surround, match, diagnostic, and visible word jump motions.
• Shared search state for /, ?, *, s, n, and N.
• Command-mode write/quit combinations such as :w, :wa, :q, :wq, and :wqa!.
• Native VS Code integration with zero runtime dependencies.

Screenshot/GIF TODO: add a short Marketplace-friendly demo before public release.

Goals

• Implement a useful Helix/Wisp motion emulator for VS Code.
• Keep the modal editing core testable without VS Code APIs.
• Use VS Code only as an adapter for document text, selections, edits, diagnostics, commands, and UI.
• Prefer correctness for core motions over broad feature coverage.
• Keep the implementation dependency-light, auditable, performant, and secure.

Recommended architecture

src/core/        Pure TypeScript editor model, motions, commands, replay tests.
src/vscode/      VS Code extension adapter. Not included in this seed yet.
fixtures/        JSON replay cases shared by tests and future integration harnesses.
docs/            Specs and implementation guidance.

Core rule:

VS Code APIs must not leak into src/core.

The VS Code adapter should:

1. read document text and selections from VS Code,
2. convert them into EditorState,
3. dispatch a core command/key,
4. apply returned edits/selections back to VS Code.

Suggested setup

npm install
npm test
npm run typecheck
npm audit

The current project has no runtime dependencies. Development dependencies are limited to TypeScript, Node type definitions, and Vitest for fixture-backed tests.

Current core status

The pure TypeScript core currently includes:

• normal, insert, and select modes
• h, j, k, l, arrow-equivalent movement, and delegated ctrl-u / ctrl-d page movement
• w, b, e word motions and W, B, E WORD motions with line-boundary behavior
• count prefixes for core motions, including multi-digit counts
• x, %, gg, G, ge, gh, gl, gs, gw line/file/jump motions
• d delete and c change edits
• match/surround foundation: mm, ms<char>, mi<char>, ma<char>, md<char>, mr<from><to>
• textobjects for miw/maw, miW/maW, and mip/maP
• search foundation for /, ?, *, s, n, N with shared query state
• prefix tracking for command sequences such as g g / space ? across keypresses in the VS Code adapter
• selection normalization with clamping, sorting, and overlap merging
• replay fixtures and invariant tests for edge cases
• extension prototype with status bar/QuickPick prefix hints, keybindings, command delegation, diagnostics navigation, viewport reveal on cursor jumps
• visible word jump labels for gw using VS Code decorations

Important docs

• docs/ENGINEER_HANDOFF.md: start here.
• docs/SELECTION_MODEL.md: selection semantics.
• docs/MOTION_SPEC.md: motion behavior.
• docs/COMMAND_MATRIX.md: key/command priority table.
• docs/VSCODE_ADAPTER.md: extension integration notes.
• docs/ADAPTER_SMOKE_CHECKLIST.md: manual extension smoke checks.
• docs/PUBLISHING_CHECKLIST.md: release/readiness checklist.
• CHANGELOG.md: unreleased change log.
• SECURITY.md: security policy placeholder.

MVP scope

Implement first:

• modes: normal, insert, select
• motions: h, j, k, l, arrows, w, b, e, W, B, E, x, %, gg, G, ge, gh, gl, gs, gw
• edits: d, c
• prefixes: g, space, [, ]
• delegates: diagnostics, definition, references, rename, code actions, comment toggle

Defer:

• exact Wisp picker UI
• configurable Opinionated Wisp Mode vs standard Helix mode toggle
• full snippet anchors
• tree-sitter
• external wi process integration