# Introduction

Learn what nokap is, why it exists, and how it works under the hood. This page provides a high-level overview of nokap's design philosophy and architecture, giving you the foundational context you'll need before diving into screenshots, PDFs, and the CLI. By the end, you'll understand how nokap communicates with Chrome and why that approach keeps things fast and dependency-free.

## What Is nokap?

**nokap** is a lightweight Python package that captures screenshots and PDFs from web pages using headless Chrome via the [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) (CDP). It communicates directly with Chrome over WebSockets so no Selenium, no Playwright, or no browser driver binaries needed.

## Why Use nokap?

If you need to:

- Convert HTML tables or reports to images for embedding in documents
- Generate PDFs from web pages with precise control over page size and margins
- Capture specific elements using CSS selectors
- Produce retina-quality (2×, 3×) screenshots
- Automate web page captures without heavyweight browser automation frameworks

…then nokap is the right tool.

## How It Works

nokap's architecture is intentionally simple:

1.  **Launch**: Finds and starts headless Chrome with a random debugging port
2.  **Connect**: Opens a WebSocket to Chrome's CDP endpoint
3.  **Capture**: Creates a tab, navigates, waits, then calls `Page.captureScreenshot` or `Page.printToPDF`
4.  **Cleanup**: Closes the tab; Chrome stays running for reuse until [nokap.close()](../reference/close.md#nokap.close) or process exit

The entire package has two runtime dependencies: [`websockets`](https://pypi.org/project/websockets/) and [`click`](https://pypi.org/project/click/) (for the CLI).

## Key Features

| Feature | Details |
|----|----|
| **Image formats** | PNG, JPEG, WebP |
| **PDF generation** | Configurable page size, margins, orientation |
| **CSS selectors** | Capture specific elements (or union of multiple) |
| **Zoom/scale** | Produce retina-quality (2×, 3×) images |
| **Expand/padding** | Add whitespace around captured elements |
| **Local HTML** | Render HTML strings or local `.html` files |
| **Viewport control** | Set width/height for responsive layouts |
| **Custom User-Agent** | Override the browser UA string |
| **CLI** | `nokap webshot` and `nokap from-html` commands |
| **Auto-cleanup** | Chrome process managed via `atexit` |
| **Jupyter-safe** | Works in notebooks (no event loop conflicts) |
| **Sandbox-friendly** | Runs in macOS agent sandboxes with `chrome-headless-shell` |

## Next Steps

You now have a clear picture of what nokap is, how it communicates with Chrome, and what it can do. The architecture is intentionally minimal (a direct WebSocket connection to Chrome's DevTools Protocol) which keeps things fast, predictable, and free of heavyweight dependencies.

- [Installation](installation.md): Get nokap set up on your system
- [Quick Start](quick-start.md): Your first screenshot in 30 seconds

Once nokap is installed and Chrome is discoverable on your system, you'll be ready to capture your first screenshot in just a few lines of code.