Arrange files, folders, terminals and notes around the task you are working on. Edit with Micro inside a card, browse directories with Yazi, switch Markdown between source and rendered views, and keep repeatable shell commands one click away.
The extension appears as VSCICE — Spatial Workbench. Its extension ID is kimstitute.vscice-spatial-workspace.
Features
|
What you can do |
| A canvas that remembers |
Pan and zoom, resize cards, search, navigate with the minimap and restore your saved layout. |
| Spatial organization |
Move cards in named regions; use snapping, alignment guides, free-space placement and automatic column layouts. Undo up to 100 canvas changes. |
| Files and folders |
Open files in the native editor or edit inside a card with Micro. Browse with Yazi and send a file to the canvas with g, then c. |
| Markdown in context |
Switch between rendered previews and Micro editing in the same card. Preview saved text with tables, lists, fenced code and supported local images. |
| Terminals and launch buttons |
Use native terminal links or embedded PTY shells. Register a command and working directory; each button click launches a fresh terminal. |
| Notes and web pages |
Keep editable notes alongside your work. Add iframe-compatible pages or local development servers as browser cards. |
Browser compatibility: website embedding policies still apply. Many public sites refuse iframe embedding; use Open externally for those pages. Browser cards do not include a separate Chromium engine. Details →
Getting started
1. Build and install
You need VS Code 1.85+, Node.js 22+ and npm. The repository currently distributes source; prebuilt VSIX files are not included.
For Windows x64:
git clone https://github.com/kimstitute/spatial-workbench.git
cd spatial-workbench
npm ci
npm run check
npm test
npm run package
In VS Code, choose Extensions → … → Install from VSIX… and select vscice-spatial-workspace-0.4.2-win32-x64.vsix. Reload the window if prompted.
For Linux or Remote SSH, build on the target architecture and install on the remote extension host. See the Linux installation guide for native build prerequisites and packaging commands.
2. Create your workspace
- Open a project folder and run Spatial Workspace: Open Canvas from the command palette.
- Add a file, folder, note or terminal from the toolbar or Explorer context menu.
- Drag card headers to arrange them. Drag empty space to pan; use the wheel to zoom.
- Select related cards and choose 영역으로 묶기 to create a region.
- Add a command through ＋ 실행 버튼 to launch your development server or test runner.
The current UI uses Korean labels. The user guide explains common controls, and the keyboard reference lists shortcuts.
3. Enable editing inside cards
Install Micro and Yazi separately on the machine running the extension host. Put them on PATH or configure vscice.tui.microPath and vscice.tui.yaziPath with absolute executable paths. They are not bundled with the extension.
Choose Micro로 여기서 편집 on a file card or Yazi로 여기서 탐색 on a folder card. Micro uses Ctrl+S to save and Ctrl+Q to quit. See tool setup and Markdown behavior.
| Environment |
Current status |
| Windows x64 desktop |
Exercised locally, including PTY commands and Yazi file-to-card integration. |
| Linux x64 / ARM64, glibc |
Packaging and host execution paths implemented; end-to-end validation is pending. |
| Remote SSH |
Runs tools and file operations on the remote extension host; end-to-end validation is pending. |
| macOS / Alpine Linux |
No packaging path provided. |
| Browser-only VS Code |
Not supported by the current desktop/PTY architecture. |
Compatible editor forks have not all been tested. This is an early-stage extension; platform implementation should not be read as platform certification.
State and process behavior
Layouts live in .vscode/spatial-workspace.json in the first workspace folder, or in VS Code workspace state when no folder is open. Command registrations are stored separately in workspace state.
- Closing the canvas stops embedded shell terminals. Micro/Yazi sessions can reattach while the same extension host remains alive.
- Reloading the window does not guarantee TUI session recovery. Save your edits before reloading.
- Canvas undo restores layout changes; it does not undo file writes or command execution.
- File references use absolute URIs, so layouts are not automatically portable between machines.
See persistence and process lifetime for the complete behavior table.
Architecture
flowchart LR
Canvas["Canvas Webview<br/>Cards · Layout · History · xterm.js"]
Host["Workspace extension host<br/>State · Files · Tool discovery"]
Native["VS Code editors<br/>and native terminals"]
PTY["node-pty<br/>Shell · Micro · Yazi"]
Web["Sandboxed iframe<br/>Compatible web pages"]
Canvas <-->|Message bridge| Host
Host --> Native
Host <--> PTY
Canvas --> Web
| Path |
Responsibility |
src/ |
Commands, persisted state, PTY lifecycle, tool integration and content handling. |
media/ |
Canvas interface, geometry, regions, selection and undo/redo. |
scripts/ |
Asset vendoring, platform packaging and integration smoke checks. |
test/ |
Automated coverage for state, layout, message handling and integrations. |
docs/guide.md |
Complete setup, controls, implementation notes and limitations. |
Development
npm ci
node scripts/vendor.js
npm run check
npm test
Open the checkout in VS Code and press F5 → Run Spatial Workspace. Generated web assets and native dependencies are not tracked.
The automated suite currently contains 22 tests. Additional checks cover simulated Webview UI interactions and actual PTY/tool integration. UI tests use installed Windows Chrome and simulated extension APIs; they are not full Extension Host tests. See validation commands and prerequisites.
For bug reports, include the extension version, editor, OS/architecture, local or remote host, reproduction steps and expected behavior. Remove credentials, personal paths and private document contents from attachments.
Privacy and boundaries
Shell and TUI execution requires a trusted workspace and runs with the extension host user's permissions. No extension-authored analytics or telemetry is implemented; embedded sites and external tools have their own network behavior.
Keep real canvas state and command registrations private. They can contain absolute file paths, private URLs, notes or sensitive shell commands. The repository excludes local layouts, logs, environment files, downloaded tools and build artifacts. Security details and limitations →
Acknowledgments and license
Dependency licenses are recorded in Third-party notices.
Documentation structure was bootstrapped with readme-ai 0.6.3 in offline mode, then edited and checked against the implementation.
This project declares UNLICENSED. Publishing the source does not grant a general open-source license for the original code; third-party components retain their own licenses.
