loopwind 0.9.1

package/README.md

@@ -0,0 +1,1020 @@
+# dsgn
+
+> The Shadcn for design and marketing. A template-based CLI tool for generating images and videos using React + Tailwind CSS + Satori.
+
+## Features
+
+- 🎨 **shadcn/ui Design System**: Beautiful, semantic colors out of the box (`text-primary`, `bg-card`, etc.)
+- ✨ **Template-based**: Install design templates like you install UI components
+- 🖼️ **Serverless Image Rendering**: Pure JavaScript rendering with Satori - works on Vercel, Netlify, Cloudflare Workers
+- 🎬 **Serverless Video Rendering**: WASM-based MP4 encoding - 12x faster than traditional approaches
+- 🎨 **Tailwind CSS Support**: Style templates with Tailwind utility classes + opacity modifiers (`bg-primary/50`)
+- 📱 **Built-in Helpers**: QR codes, image embedding, video backgrounds, template composition
+- ✅ **Smart Validation**: Automatic prop and template validation with helpful error messages
+- 🚀 **Framework-agnostic**: Works with Node, Bun, Deno, Laravel, Python, and more
+- 🤖 **Agent-friendly**: Machine-readable metadata for LLMs
+- 📦 **Easy installation**: `npx dsgn add template-name`
+- 🌐 **Pure JavaScript/WASM**: No native dependencies, works everywhere
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install -g dsgn
+```
+
+Or use with npx:
+
+```bash
+npx dsgn --help
+```
+
+### Install a Template
+
+Templates can be installed from multiple sources:
+
+#### 1. Official Registry (Coming Soon)
+
+```bash
+dsgn add banner-hero
+dsgn add og-image --registry https://custom-registry.com/r
+```
+
+#### 2. GitHub Repositories
+
+```bash
+# From a GitHub repo (looks for template.json in repo root)
+dsgn add github:username/repo
+
+# From a specific path in the repo
+dsgn add github:username/repo/templates/banner-hero
+
+# From an organization
+dsgn add github:myorg/design-templates/social-media/og-image
+```
+
+**How it works:**
+- Converts to raw GitHub URLs
+- Fetches `template.json` from the specified path
+- Downloads all referenced files
+- Uses `main` branch by default
+
+#### 3. Direct URLs
+
+```bash
+# Install from any publicly accessible URL
+dsgn add https://example.com/templates/my-template.json
+dsgn add https://cdn.example.com/templates/awesome-banner.json
+```
+
+**Requirements:**
+- URL must return JSON in the registry template format
+- Must be publicly accessible (no authentication)
+
+#### 4. Local Filesystem
+
+```bash
+# Relative path
+dsgn add ./my-templates/banner-hero
+dsgn add ../shared-templates/product-card
+
+# Absolute path
+dsgn add /Users/you/templates/social-card
+```
+
+**Use cases:**
+- Development and testing
+- Private templates
+- Shared team templates (monorepo)
+- Before publishing to registry
+
+Templates are installed to: `_dsgn/templates/<template>/` (customizable in `dsgn.json`)
+
+**Benefits:**
+- Templates are local to your project (like npm packages)
+- Different projects can use different template versions
+- Version controlled with your project
+- Easy to share within your team
+- Works offline once installed
+
+See `REGISTRY_SETUP.md` to create your own registry.
+
+### Render an Image
+
+```bash
+dsgn render banner-hero \
+  --props '{"title":"Hello World","subtitle":"Welcome to dsgn"}'
+```
+
+By default, images are saved to `dsgn/outputs/` in your current project.
+
+You can specify a custom output path:
+
+```bash
+dsgn render banner-hero \
+  --props '{"title":"Hello World","subtitle":"Welcome to dsgn"}' \
+  --out custom/path/banner.png
+```
+
+Or use a props file:
+
+```bash
+# props.json
+{
+  "title": "Hello World",
+  "subtitle": "Welcome to dsgn"
+}
+
+dsgn render banner-hero --props props.json --out banner.png
+```
+
+**Output formats:**
+
+```bash
+# PNG (default) - best for photos and complex gradients
+dsgn render banner-hero --props props.json --format png -o banner.png
+
+# SVG - scalable vector, smaller file size, perfect for template composition
+dsgn render banner-hero --props props.json --format svg -o banner.svg
+
+# WebP - modern format, smaller than PNG with similar quality
+dsgn render banner-hero --props props.json --format webp -o banner.webp
+
+# JPEG - smallest file size, good for photos
+dsgn render banner-hero --props props.json --format jpg -o banner.jpg
+```
+
+**SVG benefits with template composition:**
+- Smaller file size (typically 3-4x smaller than PNG)
+- Infinitely scalable without quality loss
+- Embedded templates remain as native SVG elements
+- Can be edited in design tools (Figma, Illustrator)
+
+### List Installed Templates
+
+```bash
+dsgn list
+```
+
+### Validate Templates
+
+```bash
+dsgn validate
+dsgn validate banner-hero
+```
+
+## SDK for Programmatic Use
+
+Use **dsgn** programmatically in your Next.js API routes, serverless functions, or Node.js applications!
+
+### Installation
+
+```bash
+npm install dsgn
+```
+
+### Quick Example
+
+```typescript
+import { defineTemplate, renderImage } from 'dsgn/sdk';
+
+// Define template programmatically
+const ogTemplate = defineTemplate({
+  name: 'og-image',
+  size: { width: 1200, height: 630 },
+  render: ({ tw, title, description }) => (
+    <div style={tw('flex flex-col w-full h-full bg-gradient-to-br from-blue-600 to-purple-700 p-12')}>
+      <h1 style={tw('text-6xl font-bold text-white')}>{title}</h1>
+      <p style={tw('text-2xl text-white/80')}>{description}</p>
+    </div>
+  ),
+});
+
+// Render to buffer
+const png = await renderImage(ogTemplate, {
+  title: 'Hello World',
+  description: 'Generated with dsgn SDK',
+});
+
+// Use in Next.js API route
+export default async function handler(req, res) {
+  const png = await renderImage(ogTemplate, req.query);
+  res.setHeader('Content-Type', 'image/png');
+  res.send(png);
+}
+```
+
+### Video Rendering
+
+```typescript
+import { defineTemplate, renderVideo } from 'dsgn/sdk';
+
+const introTemplate = defineTemplate({
+  name: 'intro-video',
+  type: 'video',
+  size: { width: 1920, height: 1080 },
+  video: { fps: 30, duration: 3 },
+  render: ({ tw, progress, title }) => {
+    const opacity = progress; // 0 to 1 animation
+
+    return (
+      <div style={tw('flex items-center justify-center w-full h-full bg-black')}>
+        <h1 style={{ ...tw('text-8xl font-bold text-white'), opacity }}>
+          {title}
+        </h1>
+      </div>
+    );
+  },
+});
+
+const mp4 = await renderVideo(introTemplate, { title: 'Welcome!' });
+```
+
+### Key Features
+
+- ✅ **No file system dependencies** - templates defined in code
+- ✅ **Returns buffers** - integrate with any framework or storage
+- ✅ **Serverless-first** - works on Vercel, Netlify, Cloudflare Workers
+- ✅ **Full TypeScript support** - type-safe props and templates
+- ✅ **Same Tailwind + shadcn/ui styling** - consistent with CLI
+
+### Use Cases
+
+- 🖼️ **Dynamic OG images** for blogs and marketing sites
+- 🎬 **Programmatic videos** for social media automation
+- 📧 **Email images** generated on-the-fly
+- 🎨 **User-generated content** like certificates, cards, badges
+- 🔄 **Batch processing** of images or videos
+
+### Example: Next.js API Route
+
+See the full example in [`examples/nextjs-api/`](examples/nextjs-api/)
+
+```typescript
+// pages/api/og-image.ts
+import { defineTemplate, renderImage } from 'dsgn/sdk';
+
+const template = defineTemplate({
+  name: 'og-image',
+  size: { width: 1200, height: 630 },
+  render: ({ tw, title }) => (
+    <div style={tw('flex items-center justify-center w-full h-full bg-white')}>
+      <h1 style={tw('text-6xl font-bold')}>{title}</h1>
+    </div>
+  ),
+});
+
+export default async function handler(req, res) {
+  const png = await renderImage(template, req.query);
+  res.setHeader('Content-Type', 'image/png');
+  res.setHeader('Cache-Control', 's-maxage=86400');
+  res.send(png);
+}
+```
+
+**Usage:**
+```
+https://yoursite.com/api/og-image?title=Hello+World
+```
+
+## shadcn/ui Design System
+
+dsgn uses **shadcn/ui's design system** by default! All templates have access to semantic color tokens:
+
+```tsx
+// Use shadcn colors in templates
+<div style={tw('bg-card border rounded-xl p-16')}>
+  <h1 style={tw('text-foreground font-bold')}>Title</h1>
+  <p style={tw('text-muted-foreground')}>Subtitle</p>
+</div>
+```
+
+**Supported shadcn classes:**
+- `text-primary`, `bg-secondary`, `text-muted-foreground`, `bg-card`, `border`, `bg-destructive`
+- **Opacity modifiers**: `bg-primary/50`, `text-muted-foreground/75`, `border/30`
+- **Dark mode ready**: Override colors in `dsgn.json`
+
+See `SHADCN_INTEGRATION.md` for complete documentation.
+
+## Configuration (dsgn.json)
+
+Templates automatically use your project's design tokens defined in `dsgn.json`. This allows generated images to match your brand colors and design system.
+
+### Initialize Config
+
+```bash
+dsgn init
+```
+
+This creates a `dsgn.json` file in your project:
+
+```json
+{
+  "colors": {
+    "primary": "#667eea",
+    "secondary": "#764ba2",
+    "background": "#ffffff",
+    "foreground": "#000000",
+    "muted": "#f3f4f6",
+    "accent": "#3b82f6",
+    "destructive": "#ef4444",
+    "border": "#e5e7eb"
+  },
+  "fonts": {
+    "sans": ["Inter", "system-ui", "sans-serif"],
+    "mono": ["JetBrains Mono", "monospace"]
+  },
+  "tokens": {
+    "borderRadius": {
+      "sm": "0.25rem",
+      "md": "0.5rem",
+      "lg": "1rem",
+      "xl": "1.5rem"
+    }
+  },
+  "defaults": {
+    "width": 1200,
+    "height": 630
+  }
+}
+```
+
+### Using Config in Templates
+
+Templates receive the config via props:
+
+```tsx
+export default function MyTemplate({ title, config }) {
+  const primaryColor = config?.colors?.primary || '#000';
+
+  return (
+    <div style={{ background: primaryColor }}>
+      {title}
+    </div>
+  );
+}
+```
+
+This ensures your generated images use the same colors as your Tailwind/Shadcn setup!
+
+## Using Tailwind Classes
+
+Templates can use Tailwind utility classes for styling! The `tw()` function is automatically provided:
+
+```tsx
+export default function MyTemplate({ title, tw }) {
+  return (
+    <div style={tw('flex items-center justify-center w-full h-full bg-primary text-white')}>
+      <h1 style={tw('text-6xl font-bold')}>
+        {title}
+      </h1>
+    </div>
+  );
+}
+```
+
+Combine with custom styles:
+
+```tsx
+<div
+  style={{
+    ...tw('flex flex-col p-20 text-white'),
+    background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
+  }}
+>
+  <h1 style={tw('text-8xl font-bold')}>{title}</h1>
+</div>
+```
+
+### Automatic Tailwind Config Support
+
+**dsgn automatically detects and uses your `tailwind.config.js`!**
+
+If you have a Tailwind project:
+
+```js
+// tailwind.config.js
+export default {
+  theme: {
+    extend: {
+      colors: {
+        primary: '#667eea',
+        brand: {
+          500: '#0ea5e9',
+          900: '#0c4a6e',
+        },
+      },
+      spacing: {
+        '72': '18rem',
+      },
+    },
+  },
+};
+```
+
+Your templates can use these values:
+
+```tsx
+<div style={tw('bg-primary text-white p-72')}>
+  <div style={tw('bg-brand-500')}>Custom brand color!</div>
+</div>
+```
+
+**Config priority:**
+1. `tailwind.config.js` (if exists)
+2. `dsgn.json` (fallback)
+3. Default Tailwind values
+
+**Supported classes:**
+- Layout: `flex`, `flex-col`, `items-center`, `justify-between`, etc.
+- Spacing: `p-4`, `px-8`, `m-6`, `gap-4`, etc.
+- Typography: `text-6xl`, `font-bold`, `text-center`, etc.
+- Colors: `bg-primary`, `text-brand-500`, etc. (from your config!)
+- Effects: `opacity-90`, `rounded-xl`, etc.
+- shadcn/ui colors: `bg-card`, `text-foreground`, `text-muted-foreground`
+- Opacity modifiers: `bg-primary/50`, `text-muted-foreground/75`
+
+**Note:** Tailwind v4 uses CSS variables instead of JS config. We're working on CSS parsing support. For now, use `dsgn.json` or `tailwind.config.js` (v3 format).
+
+## Fonts
+
+Templates can use **default fonts** (from CDN) or **bundle custom fonts** for brand-specific typography.
+
+### Default Fonts
+
+By default, templates use **Noto Sans** fetched from jsDelivr CDN. No setup required!
+
+### Custom Fonts
+
+Templates can bundle their own fonts (WOFF, WOFF2, TTF, OTF):
+
+```
+my-template/
+├── my-template.tsx
+├── meta.json
+└── fonts/
+    ├── CustomFont-Regular.woff
+    └── CustomFont-Bold.woff
+```
+
+**meta.json:**
+```json
+{
+  "name": "my-template",
+  "fonts": [
+    {
+      "name": "Custom Font",
+      "path": "fonts/CustomFont-Bold.woff",
+      "weight": 700,
+      "style": "normal"
+    }
+  ]
+}
+```
+
+**Template usage:**
+```tsx
+<h1 style={{ fontFamily: 'Custom Font', fontWeight: 700 }}>
+  Branded Typography
+</h1>
+```
+
+**Use cases:**
+- Brand-specific fonts (company guidelines)
+- Offline rendering (no CDN dependency)
+- Special display typography
+
+## Template Helpers
+
+Templates have access to built-in helper functions:
+
+- **`tw(classes)`** - Convert Tailwind classes to inline styles
+- **`qr(text, options?)`** - Generate QR codes from text/URLs
+- **`image(propKey)`** - Embed images as data URIs
+- **`video(propKey)`** - Embed video frames (for video templates)
+- **`template(name, props)`** - Embed other templates
+- **`config`** - Access dsgn.json configuration
+
+### QR Code Helper
+
+Generate QR codes from any text or URL using the `qr()` helper:
+
+```tsx
+export default function Template({ title, url, qr, tw }) {
+  return (
+    <div style={tw('flex flex-col items-center p-16')}>
+      <h1 style={tw('text-5xl font-bold mb-8')}>{title}</h1>
+
+      {/* QR code auto-generated from url prop */}
+      <img src={qr(url)} width={200} height={200} alt="QR Code" />
+
+      <p style={tw('text-xl mt-4')}>{url}</p>
+    </div>
+  );
+}
+```
+
+**Usage:**
+```bash
+dsgn render qr-card '{
+  "title": "Visit Our Website",
+  "url": "https://dsgncli.com"
+}'
+```
+
+**Customization:**
+```tsx
+// Custom size and error correction
+<img src={qr(url, {
+  width: 300,
+  margin: 2,
+  errorCorrectionLevel: 'H', // L, M, Q, H (higher = more error correction)
+  color: {
+    dark: '#000000',
+    light: '#FFFFFF'
+  }
+})} />
+```
+
+**How it works:**
+- All string props are automatically pre-generated as QR codes
+- Call `qr()` with any prop value (url, text, etc.)
+- Returns a data URI that can be used directly in `<img src={...} />`
+- Cached per render for performance
+
+**Use cases:**
+- Event tickets with QR codes
+- Business cards with contact info
+- Marketing materials with campaign URLs
+- Product labels with tracking codes
+
+### Image Helper
+
+Embed images (jpg, png, gif, webp, svg) as data URIs using the `image()` helper:
+
+```tsx
+export default function Banner({ background, tw, image }) {
+  return (
+    <div style={tw('relative w-full h-full')}>
+      <img src={image('background')} style={tw('absolute inset-0 w-full h-full object-cover')} />
+      <h1 style={tw('relative text-6xl font-bold text-white')}>Hello World</h1>
+    </div>
+  );
+}
+```
+
+**Props format:**
+```json
+{
+  "background": "./path/to/image.jpg"
+}
+```
+
+**Usage:**
+```bash
+dsgn render banner '{
+  "background": "./my-background.jpg"
+}'
+```
+
+**How it works:**
+- The renderer auto-detects props ending in image extensions (.jpg, .png, .gif, .webp, .svg)
+- Images are pre-loaded and converted to data URIs
+- Call `image('propKey')` to get the data URI for that prop
+- Works with any image format
+
+**Use cases:**
+- Background images in banners
+- Logos and brand elements
+- Product photos in cards
+- Avatar images
+
+### Video Helper
+
+For video templates, embed video frames synchronized to the current animation frame using the `video()` helper:
+
+```tsx
+export default function VideoOverlay({ background, title, tw, video, frame, progress }) {
+  const opacity = progress < 0.2 ? progress / 0.2 : 1;
+
+  return (
+    <div style={tw('relative w-full h-full')}>
+      {/* Background video - auto-syncs to current frame */}
+      <img
+        src={video('background')}
+        style={tw('absolute inset-0 w-full h-full object-cover')}
+      />
+
+      {/* Animated overlay */}
+      <h1
+        style={{
+          ...tw('relative text-8xl font-bold text-white'),
+          opacity
+        }}
+      >
+        {title}
+      </h1>
+    </div>
+  );
+}
+```
+
+**Props format:**
+```json
+{
+  "title": "My Video",
+  "background": "./my-video.mp4"
+}
+```
+
+**Usage:**
+```bash
+dsgn render video-overlay props.json --out output.mp4
+```
+
+**How it works:**
+1. First render detects video props (auto-detects .mp4, .mov, etc.)
+2. Extracts all frames at template's FPS
+3. Returns frame matching current template frame number
+4. Frames cached in memory for fast access
+
+**Use cases:**
+- Video backgrounds with text overlays
+- Adding titles/captions to existing videos
+- Combining multiple video sources
+- Dynamic watermarking
+
+### Template Composition Helper
+
+Embed one template inside another using the `template()` helper. This is perfect for creating composite designs where smaller templates are reused as building blocks.
+
+**Just call template() - no declaration needed:**
+```tsx
+export default function Template({ title, bannerTitle, bannerSubtitle, template, tw }) {
+  return (
+    <div style={tw('w-full h-full flex flex-col bg-slate-900 p-12')}>
+      <div style={tw('bg-white rounded-3xl p-10 flex flex-col')}>
+        <h1 style={tw('text-5xl font-bold mb-8')}>{title}</h1>
+
+        {/* Embed any template - auto-loaded on first render */}
+        <div style={tw('rounded-xl overflow-hidden flex')}>
+          {template('image', { title: bannerTitle, subtitle: bannerSubtitle })}
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+**Usage:**
+```bash
+dsgn render composite-card '{
+  "title": "Product Launch",
+  "bannerTitle": "New Release",
+  "bannerSubtitle": "Coming Soon"
+}'
+```
+
+**How it works:**
+- **No declaration needed** - just call `template('any-template-name')`
+- First render pass detects which templates are needed
+- All templates load in parallel automatically
+- Second render pass completes with loaded templates
+- Each template uses its own `meta.json` for sizing
+- Returns JSX directly (not a data URI)
+- Satori renders everything as a single SVG tree
+
+**Pass props directly:**
+```tsx
+{template('image', { title: 'Custom Title', subtitle: 'Custom Subtitle' })}
+{template('qr-card', { url: 'https://example.com', title: 'Scan Me' })}
+```
+
+**Use cases:**
+- Composite social media graphics with reusable headers/footers
+- Multi-panel infographics
+- Email templates with consistent branding elements
+- Product cards with embedded badges or labels
+- Presentations with reusable slide components
+
+## Template Structure
+
+Templates are TSX files with metadata. Each template can be either an **image** or a **video** template (not both).
+
+### Image Template
+
+```tsx
+export const meta = {
+  name: "banner-hero",
+  description: "Hero banner with shadcn design",
+  type: "image", // Optional, defaults to "image"
+  size: { width: 1600, height: 900 },
+  props: {
+    title: "string",
+    subtitle: "string?"
+  }
+};
+
+export default function Template({ title, subtitle, tw, qr, template }) {
+  return (
+    <div style={tw('w-full h-full flex flex-col justify-center p-20 bg-background')}>
+      <div style={tw('bg-card border rounded-xl p-16 flex flex-col')}>
+        <h1 style={tw('text-8xl font-bold text-foreground')}>{title}</h1>
+        {subtitle && (
+          <p style={tw('text-4xl text-muted-foreground/75')}>{subtitle}</p>
+        )}
+      </div>
+    </div>
+  );
+}
+```
+
+### Video Template
+
+```tsx
+export const meta = {
+  name: "animated-banner",
+  description: "Animated hero banner with shadcn design",
+  type: "video",
+  size: { width: 1600, height: 900 },
+  props: {
+    title: "string",
+    subtitle: "string?"
+  },
+  video: {
+    fps: 30,
+    duration: 3
+  }
+};
+
+export default function Template({ title, subtitle, frame, progress, tw, qr, template }) {
+  const opacity = Math.min(1, progress * 2);
+  const translateY = 20 - (progress * 20);
+
+  return (
+    <div style={tw('w-full h-full flex flex-col justify-center items-center bg-background p-20')}>
+      <div style={tw('bg-card border rounded-xl p-16 flex flex-col')}>
+        <h1
+          style={{
+            ...tw('text-9xl font-bold text-foreground'),
+            opacity,
+            transform: `translateY(${translateY}px)`
+          }}
+        >
+          {title}
+        </h1>
+        {subtitle && (
+          <p style={tw('text-5xl text-muted-foreground/75 mt-6')}>
+            {subtitle}
+          </p>
+        )}
+      </div>
+    </div>
+  );
+}
+```
+
+## Commands
+
+### `dsgn init`
+
+Initialize a `dsgn.json` config file with default design tokens.
+
+### `dsgn add <template>`
+
+Install a template from the registry.
+
+Options:
+- `-r, --registry <url>` - Custom registry URL
+
+### `dsgn list`
+
+List all installed templates with metadata.
+
+### `dsgn render <template>`
+
+Render a template to an image.
+
+Options:
+- `-p, --props <file>` - Props file (JSON)
+- `-o, --out <file>` - Output file path
+- `--format <format>` - Output format: png, svg, webp (default: png)
+- `--video` - Render as video (coming soon)
+
+### `dsgn validate [template]`
+
+Validate template metadata. If no template is specified, validates all installed templates.
+
+## Validation & Error Messages
+
+dsgn automatically validates templates and props before rendering, providing helpful error messages.
+
+### Automatic Validation
+
+```bash
+# Missing required props
+$ dsgn render banner-hero --props '{}'
+✖ Template validation failed
+  ✗ props: Missing required prop: "title"
+    → Add "title" to your props: --props '{"title":"value"}'
+
+# Wrong prop type
+$ dsgn render banner-hero --props '{"title":123}'
+✖ Template validation failed
+  ✗ props: Prop "title" should be a string, got number
+    → Change "title" to a string: "title": "value"
+```
+
+### Enhanced Satori Error Messages
+
+When rendering fails, dsgn provides clear suggestions:
+
+```bash
+$ dsgn render my-template --props props.json
+✖ Failed to render template
+
+Error: Satori requires explicit display: flex for containers with multiple children
+
+Suggestions:
+  • Add "flex" or "flex-col" to your Tailwind classes: tw("flex items-center")
+  • Or add display: flex directly: style={{ display: "flex", ...tw("...") }}
+  • Every <div> with 2+ children MUST have display: flex or display: none
+```
+
+See `VALIDATION.md` for complete validation documentation and troubleshooting.
+
+## Creating Custom Templates
+
+Templates are stored in your project's `dsgn/templates/` directory. You can create custom templates:
+
+1. Create a folder:
+
+```bash
+mkdir -p dsgn/templates/my-template
+```
+
+2. Create `meta.json`:
+
+```json
+{
+  "name": "my-template",
+  "description": "My custom template",
+  "type": "image",
+  "size": { "width": 1200, "height": 630 },
+  "props": {
+    "title": "string"
+  }
+}
+```
+
+3. Create `my-template.tsx`:
+
+```tsx
+export default function MyTemplate({ title }) {
+  return (
+    <div style={{
+      display: 'flex',
+      width: '100%',
+      height: '100%',
+      background: '#000',
+      color: '#fff',
+      justifyContent: 'center',
+      alignItems: 'center',
+      fontSize: '48px',
+      fontFamily: 'sans-serif',
+    }}>
+      {title}
+    </div>
+  );
+}
+```
+
+4. Validate and render:
+
+```bash
+dsgn validate my-template
+dsgn render my-template --props '{"title":"Hello"}' --out test.png
+```
+
+## Use Cases
+
+- 🎯 **OG Images**: Generate Open Graph images for websites
+- 📱 **Social Media**: Create social media graphics
+- 📧 **Email Headers**: Generate email banners
+- 🎨 **Marketing**: Automate marketing asset creation
+- 🤖 **AI Agents**: Let LLMs generate images programmatically
+
+## Video Support
+
+Video templates use `type: "video"` and support `frame` and `progress` props for animations.
+
+### ⚡ No Dependencies Required
+
+**dsgn uses pure JavaScript/WASM for video encoding** - works everywhere!
+
+✅ Works on **Vercel Edge Functions**
+✅ Works on **Netlify Functions**
+✅ Works on **Cloudflare Workers**
+✅ Works on **AWS Lambda**
+✅ Works **everywhere** (Docker, CI/CD, local)
+
+**12x faster than traditional approaches** - renders a 3-second video in ~2 seconds!
+
+### Creating Video Templates
+
+Video templates are similar to image templates but include `frame` and `progress` props for animations:
+
+```tsx
+export const meta = {
+  name: "my-video",
+  type: "video",
+  size: { width: 1200, height: 630 },
+  props: { title: "string" },
+  video: {
+    fps: 30,
+    duration: 3
+  }
+};
+
+export default function Template({ title, frame, progress, tw, qr, template }) {
+  return (
+    <div
+      style={{
+        ...tw('w-full h-full flex items-center justify-center'),
+        opacity: progress,
+        transform: `translateY(${20 - progress * 20}px)`
+      }}
+    >
+      <h1 style={tw('text-6xl font-bold')}>{title}</h1>
+    </div>
+  );
+}
+```
+
+### Rendering Videos
+
+```bash
+# Render to MP4
+dsgn render my-video '{"title":"Animated Title"}' -o output.mp4
+
+# With custom quality settings
+dsgn render my-video props.json --crf 18   # Higher quality (lower CRF = better quality)
+
+# Export frames only (for manual encoding)
+dsgn render my-video props.json --frames-only -o frames/
+```
+
+**How it works:**
+1. **SVG Generation**: All frames generated in parallel (~0.8s for 90 frames)
+2. **WASM Encoding**: Frames encoded to H.264 MP4 using pure JavaScript (~1.2s for 90 frames)
+3. **Total**: 3-second video renders in ~2 seconds on M1 Mac
+
+**Props available in video templates:**
+- `frame` - Current frame number (0 to totalFrames-1)
+- `progress` - Animation progress from 0 to 1
+- All standard helpers: `tw`, `qr`, `template`, `config`
+
+**Performance:**
+- **12x faster** than traditional approaches
+- 90 frames (3s @ 30fps) renders in ~2 seconds
+- ~60 frames per second rendering speed
+- Perfect for serverless environments with execution time limits
+
+## Documentation Website
+
+A full documentation website is available in the `website/` folder, built with Astro.
+
+**Local development:**
+
+```bash
+cd website
+npm install
+npm run dev
+```
+
+Open http://localhost:4321
+
+**Deployment:**
+
+The site is ready to deploy on Netlify, Vercel, or Cloudflare Pages. A `netlify.toml` is included for easy Netlify deployment.
+
+See `website/README.md` for more details.
+
+## Registry
+
+Templates are fetched from a registry (similar to shadcn/ui). The default registry is:
+
+```
+https://dsgncli.com/r
+```
+
+You can host your own registry and use it with:
+
+```bash
+dsgn add my-template --registry https://my-registry.com
+```
+
+## License
+
+MIT