# Previews

> Previews is a fast, lightweight, edge-native HTML preview and multi-page web app hosting service built on Cloudflare Workers, Cloudflare D1 (SQLite metadata), and Cloudflare R2 (asset storage).

Previews enables developers and automated coding agents to publish static web projects to isolated subdomains (`<slug>.previews.kartikarora.me`), manage immutable version histories, view unified diffs across versions, and secure previews with optional password protection.

## Documentation

- [How Previews Works](/how-it-works.md): Comprehensive guide to Previews architecture, immutable versioning, edge routing, plain-text diffing, and password authentication.
- [Full Documentation](/llms-full.txt): Complete aggregated documentation, API reference, and architecture details in a single markdown document.

## Core Features & Architecture

- [Immutable Versioning](/how-it-works.md#immutable-versioning): Every publish creates an incremented version (v1, v2, v3...) stored at deterministic R2 keys (`projects/<slug>/versions/<n>/<path>`).
- [Password Protection](/how-it-works.md#password-protection): Optional per-project password protection with HMAC-SHA256 signed session cookies valid for 7 days.
- [Plain-Text Diff Viewer](/how-it-works.md#plain-text-diff-viewer): Plain-text unified diffs between any two versions (`/<versionA>..<versionB>`, e.g. `/1..2`).
- [Subdomain Isolation](/how-it-works.md#subdomain-isolation): Each project is served from its own isolated subdomain with clean relative asset resolution.
- [Mutable Slugs](/how-it-works.md#mutable-slugs): Project slugs can be changed at any time with immediate edge routing updates.

## API Reference

- [List Projects](/how-it-works.md#api-reference): `GET /api/projects` - Retrieve all preview projects for the authenticated user.
- [Create Project](/how-it-works.md#api-reference): `POST /api/projects` - Create a new preview project with optional password and HTML document.
- [Publish Version](/how-it-works.md#api-reference): `POST /api/projects/:slug/versions` or `POST /api/projects/:slug/edit` - Publish a new version to an existing preview.
- [Get Usage Analytics](/how-it-works.md#api-reference): `GET /api/projects/:slug/usage` - Retrieve view counts, request rates, and bandwidth metrics.
