Image Preview Plus

🇨🇳 中文文档

🖼️ A powerful VS Code extension for enhanced image preview — built for developers who need more than just viewing images.

📐 This project is fully developed following the SDD (Spec-Driven Development) methodology. Every feature goes through a structured workflow: Proposal → Design → Specs → Tasks → Implementation. All specification artifacts are preserved in the openspec/ directory for full traceability.

screenshot

preview screenshot

✨ Features

🔍 Enhanced Image Preview

Click on any PNG, JPG, or SVG file to open it with the enhanced previewer, replacing VS Code's built-in image viewer.

Toolbar Actions:

Feature	Description
🔎 Zoom	Zoom in, zoom out, fit to window, mouse wheel zoom
🔄 Rotate	Clockwise / counter-clockwise 90° rotation
↔️ Flip	Horizontal flip, vertical flip
🎨 Background	Checkerboard (default), white, black — great for transparent images
💧 Color Picker	Pixel-level color reading, HEX/RGB format, click to copy
📏 Ruler	Pixel rulers on top and left edges, synced with zoom level
📐 Grid	Semi-transparent grid overlay for UI measurement

Info Panel (bottom bar):

Format	Displayed Info
PNG/JPG	File name · Dimensions (W×H) · File size · Format · Color space · Bit depth · Alpha channel · File path (copy button)
SVG	File name · File size · Format · File path (copy button)

🖱️ Vue Hover Preview

Hover over an image path in .vue files to instantly preview the image with basic metadata — no need to leave your code.

Supported path patterns:

<template>
  <!-- Static src -->
  <img src="./assets/logo.png" />
</template>

<script>
  // import statement
  import logo from '@/assets/logo.png'
  // require call
  const bg = require('./assets/bg.jpg')
</script>

<style>
  /* CSS url() */
  .hero { background: url('./assets/pattern.png'); }
</style>

Path resolution:

Pattern	Supported
Relative path (./, ../)	✅
@/ alias (reads tsconfig.json / jsconfig.json)	✅
Dynamic binding (:src="variable")	❌

📦 Installation

From VSIX (Recommended)

1. Download the latest .vsix file from Releases
2. In VS Code, open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
3. Run Extensions: Install from VSIX...
4. Select the downloaded .vsix file

Or install via command line:

code --install-extension image-preview-plus-x.x.x.vsix

From Source

git clone https://github.com/<your-username>/vscode_image_preview_plus.git
cd vscode_image_preview_plus
npm install
npm run package
# Then install the generated .vsix file

🛠️ Development

Prerequisites

• Node.js >= 18
• VS Code >= 1.85.0

Setup

# Install dependencies
npm install

# Compile Extension Host code
npm run compile

# Bundle Webview resources
npm run build:webview

# Copy static assets
npm run copy:assets

Debug

1. Open this project in VS Code
2. Press F5 to launch the Extension Development Host
3. In the new VS Code window, open any image file to test

Build VSIX

npm run package

The .vsix file will be generated in the project root.

Project Structure

├── src/
│   ├── extension.ts                 # Extension entry point
│   ├── editor/
│   │   ├── imageEditorProvider.ts    # CustomReadonlyEditorProvider
│   │   └── webview/
│   │       ├── main.ts              # Webview entry
│   │       ├── canvas.ts            # Canvas rendering (zoom/rotate/flip)
│   │       ├── toolbar.ts           # Toolbar UI
│   │       ├── infoPanel.ts         # Info panel UI
│   │       ├── colorPicker.ts       # Color picker logic
│   │       ├── ruler.ts             # Ruler & grid overlay
│   │       └── styles.css           # Webview styles
│   ├── hover/
│   │   ├── vueHoverProvider.ts      # Vue file hover logic
│   │   └── pathResolver.ts          # Path resolution (relative + alias)
│   └── metadata/
│       ├── imageInfo.ts             # Unified metadata interface
│       ├── pngParser.ts             # PNG header parser (IHDR chunk)
│       └── jpgParser.ts             # JPG header parser (SOF marker)
├── package.json
└── tsconfig.json

� Spec-Driven Development (SDD)

This project is 100% developed using the SDD (Spec-Driven Development) methodology, powered by OpenSpec. Every feature is designed, specified, and implemented through a structured artifact workflow — no code is written before thinking is done.

Workflow

Proposal → Design → Specs → Tasks → Implementation

Phase	Artifact	Purpose
Proposal	proposal.md	Define why and what — motivation, scope, and capabilities
Design	design.md	Define how — technical decisions, architecture, tradeoffs
Specs	specs/*/spec.md	Define behavior — detailed requirements with scenarios
Tasks	tasks.md	Define work — implementation checklist derived from specs
Implementation	src/	Write code — guided by specs, verified against requirements

Artifact Directory

All SDD artifacts are preserved in the openspec/ directory:

openspec/
└── changes/
    └── image-preview-plus/
        ├── proposal.md                       # Why & what
        ├── design.md                         # How (7 key decisions)
        ├── tasks.md                          # 56 implementation tasks
        └── specs/
            ├── image-editor/spec.md          # Editor preview requirements
            ├── image-metadata/spec.md        # Metadata parsing requirements
            └── vue-hover-preview/spec.md     # Vue hover requirements

💡 Why SDD? By writing specs before code, every implementation decision is traceable, every requirement is verifiable, and the codebase stays aligned with its design intent. This is especially valuable for open-source projects where contributors need to understand why things are built the way they are.

�📋 Tech Stack

• Language: TypeScript
• VS Code API: CustomReadonlyEditorProvider, HoverProvider, Webview
• Rendering: HTML Canvas
• Bundler: esbuild (Webview), tsc (Extension Host)
• Dependencies: image-size (lightweight, pure JS, zero native deps)
• Dev Methodology: SDD (Spec-Driven Development) via OpenSpec

🤝 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

1. Fork the repository
2. Create your 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

MIT