PolyForm

A Spatial Computing IDE for Visual Programming

PolyForm is a VS Code extension that transforms your editor into an infinite canvas where you can write, execute, and visualize code in a spatial environment. Think Excalidraw meets Jupyter Notebooks.

📑 Table of Contents

• Features
• Quick Start
• Screenshots
• Architecture → Full Documentation
• Environment Detection → Full Documentation
• Development
• Customization
• Security
• Troubleshooting
• Roadmap
• Contributing
• License
• Acknowledgments
• Contact

✨ Features

• Infinite Canvas: Pan, zoom, and organize your code spatially using the Tldraw engine
• Executable Code Nodes: Write and run JavaScript and Python code directly on the canvas
• Real-time Execution: See output instantly in a terminal-style display below each code node
• Excalidraw Aesthetic: Hand-drawn, sketch-like styling with the Virgil font
• Polyglot Support: Switch between languages with a dropdown selector
• Resizable Nodes: Adjust code blocks to fit your workflow
• Syntax Highlighting: Powered by Prism.js for clear, readable code

🚀 Quick Start

Prerequisites

• VS Code 1.60.0 or higher
• Node.js (for JavaScript execution)
• Python 3 (for Python execution)

Installation

From Source

1. Clone the repository:

   git clone https://github.com/yourusername/polyform.git
   cd polyform
   

2. Install dependencies:

   npm install
   

3. Compile the extension:

   npm run compile
   

4. Open in VS Code and press F5 to launch the Extension Development Host

Usage

1. Create a new file with the .canvas extension (e.g., myproject.canvas)
2. Click the + Code Node button in the bottom-right corner
3. Write your code in the editor
4. Select the language (JavaScript or Python) from the dropdown
5. Click Run to execute
6. See the output appear below the code block

📸 Screenshots

JavaScript Execution

console.log("Hello World");
// Output: Hello World

Python Execution

a = 5
b = 6
print(f"{a} + {b} = {a + b}")
# Output: 11

🏗️ Architecture

PolyForm uses a dual-environment architecture:

• Webview (React): Renders the infinite canvas and code nodes
• Extension Host (Node.js): Executes code using system interpreters

Communication happens via VS Code's postMessage API. See ARCHITECTURE.md for detailed technical documentation.

🌍 Environment Detection

PolyForm automatically detects and uses your project's development environment:

Python Virtual Environments

• ✅ VS Code Python extension's selected interpreter
• ✅ Workspace virtual environments (venv, .venv, env)
• ✅ VIRTUAL_ENV environment variable
• ✅ Falls back to system python3

Node.js Local Modules

• ✅ Local node_modules/.bin/node
• ✅ Falls back to system node

Working Directory: Code runs with your workspace folder as the working directory, allowing you to import local modules and packages.

See ENVIRONMENT_DETECTION.md for complete documentation and examples.

🛠️ Development

Project Structure

PolyForm/
├── src/
│   ├── extension.ts              # Extension entry point
│   ├── PolyFormEditorProvider.ts # Webview & execution handler
│   └── webview/
│       ├── index.tsx             # Webview entry point
│       ├── App.tsx               # Canvas component
│       └── shapes/
│           └── CodeShape.tsx     # Code node implementation
├── dist/                         # Compiled output
├── package.json                  # Extension manifest
└── webpack.config.js             # Build configuration

Build Commands

# Compile TypeScript
npm run compile

# Watch mode (auto-recompile on changes)
npm run watch

# Run extension in debug mode
# Press F5 in VS Code

Adding New Languages

See ARCHITECTURE.md for a step-by-step guide on adding support for Ruby, Go, Rust, or any other language with a CLI interpreter.

🎨 Customization

Styling

The Excalidraw aesthetic is achieved through:

• Virgil font for hand-drawn text
• Rough borders with box-shadow: 4px 4px 0px [#000](https://github.com/hridesh-net/polyform/issues/000)
• Tldraw CSS overrides in src/webview/tldraw-styles.css

Code Editor

The code editor uses react-simple-code-editor with Prism.js. To customize:

1. Change theme: Import a different Prism theme in CodeShape.tsx
2. Adjust font: Modify the fontFamily in editor options
3. Add languages: Import Prism language components

🔒 Security

⚠️ Warning: PolyForm executes code directly on your system without sandboxing.

Risks:

• File system access
• Network requests
• System commands

Recommendations:

• Only run code you trust
• Consider using Docker for isolation
• Review code before execution

See ARCHITECTURE.md for detailed security information.

🐛 Troubleshooting

Code Node Not Executing

1. Verify the interpreter is installed:

   node --version
   python3 --version
   

2. Check the Debug Console (View → Debug Console) for errors

3. Open Webview Developer Tools:

   • Command Palette → "Developer: Open Webview Developer Tools"

Canvas Not Loading

1. Reload the window: Ctrl+R / Cmd+R
2. Check for compilation errors: npm run compile
3. Verify all dependencies are installed: npm install

Syntax Highlighting Not Working

Ensure Prism language components are imported in CodeShape.tsx:

import 'prismjs/components/prism-javascript';
import 'prismjs/components/prism-python';

🗺️ Roadmap

• [ ] Multi-file projects (import/export between nodes)
• [ ] Package manager integration (npm, pip)
• [ ] Debugger support (breakpoints, step-through)
• [ ] Collaborative editing (live sharing)
• [ ] Cloud execution (serverless functions)
• [ ] More languages (Ruby, Go, Rust, etc.)
• [ ] LSP integration (IntelliSense, autocomplete)
• [ ] Export to Jupyter Notebook
• [ ] Canvas templates (algorithms, data structures)

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Tldraw - Infinite canvas engine
• Excalidraw - Design inspiration
• Prism.js - Syntax highlighting
• react-simple-code-editor - Code input component

📧 Contact

• Author: Hridesh Sharma
• Email: hridesh.khandal@gmail.com
• GitHub: @hridesh-net

Built with ❤️ for visual thinkers and creative coders