loopwind 0.25.6 → 0.25.8

package/plans/SDK.md

@@ -0,0 +1,797 @@
+# Loopwind SDK
+
+> **Open Source**: MIT licensed. A programmatic library for rendering images and videos from JSX templates.
+
+## Overview
+
+The Loopwind ecosystem has three parts:
+
+| Component | Description | Use Case |
+|-----------|-------------|----------|
+| **SDK** (this doc) | Programmatic library | Self-hosted rendering in your app |
+| **CLI** | Command-line tool | Local development, template authoring |
+| **Platform** | Hosted API service | Publish templates, get render URLs |
+
+**SDK is for self-hosted rendering.** If you want hosted rendering with URLs like `api.loopwind.dev/r/abc123?title=Hello`, see [PLATFORM.md](./PLATFORM.md).
+
+---
+
+## Vision
+
+A JavaScript/TypeScript library for rendering images and videos from JSX. No config files, no folder structure - just functions.
+
+```typescript
+import { render } from 'loopwind';
+
+// Define a template - receives `tw` function as prop
+const OGImage = ({ title, subtitle, tw }) => (
+  <div style={tw("w-full h-full flex flex-col items-center justify-center bg-gradient-to-r from-blue-500 to-purple-600")}>
+    <h1 style={tw("text-white text-6xl font-bold")}>{title}</h1>
+    <p style={tw("text-white/80 text-2xl mt-4")}>{subtitle}</p>
+  </div>
+);
+
+// Render to PNG
+const png = await render(OGImage, {
+  props: { title: 'Hello World', subtitle: 'Welcome' },
+  width: 1200,
+  height: 630,
+  format: 'png',
+});
+
+// Write to file or return as response
+await fs.writeFile('og.png', png);
+```
+
+---
+
+## Template Composition
+
+Templates are just functions. Compose them like regular React components:
+
+```typescript
+import { render } from 'loopwind';
+
+// Layout template
+const Layout = ({ children, background = 'white', tw }) => (
+  <div style={{ ...tw("w-full h-full flex items-center justify-center p-12"), background }}>
+    {children}
+  </div>
+);
+
+// Card component
+const Card = ({ children, tw }) => (
+  <div style={tw("bg-white rounded-2xl shadow-xl p-8")}>
+    {children}
+  </div>
+);
+
+// Composed template - tw is passed through
+const BlogOG = ({ title, author, avatar, tw }) => (
+  <Layout background="linear-gradient(135deg, #667eea 0%, #764ba2 100%)" tw={tw}>
+    <Card tw={tw}>
+      <div style={tw("flex items-center gap-6")}>
+        <img src={avatar} style={tw("w-16 h-16 rounded-full")} />
+        <div>
+          <h1 style={tw("text-3xl font-bold text-gray-900")}>{title}</h1>
+          <p style={tw("text-gray-600 mt-1")}>by {author}</p>
+        </div>
+      </div>
+    </Card>
+  </Layout>
+);
+
+// Render the composed template
+const png = await render(BlogOG, {
+  props: {
+    title: 'Building with Loopwind',
+    author: 'Jane Doe',
+    avatar: 'https://example.com/avatar.jpg',
+  },
+  width: 1200,
+  height: 630,
+  format: 'png',
+});
+```
+
+---
+
+## Video Rendering
+
+Animate templates over time using the `frame` prop:
+
+```typescript
+import { render } from 'loopwind';
+
+// Animated template - receives frame info
+const AnimatedIntro = ({ title, frame, tw }) => {
+  const { progress } = frame;
+
+  // Animate based on progress (0 to 1)
+  const opacity = Math.min(progress * 2, 1);
+  const translateY = 50 * (1 - progress);
+
+  return (
+    <div style={tw("w-full h-full flex items-center justify-center bg-black")}>
+      <h1
+        style={{
+          ...tw("text-white text-6xl font-bold"),
+          opacity,
+          transform: `translateY(${translateY}px)`,
+        }}
+      >
+        {title}
+      </h1>
+    </div>
+  );
+};
+
+// Render to video
+const mp4 = await render(AnimatedIntro, {
+  props: { title: 'Welcome' },
+  width: 1920,
+  height: 1080,
+  format: 'mp4',
+  fps: 30,
+  duration: 3, // seconds
+});
+```
+
+---
+
+## API Reference
+
+### `render(template, options)`
+
+Renders a template function to an image or video.
+
+```typescript
+const result = await render(MyTemplate, {
+  // Props passed to template
+  props: { title: 'Hello', subtitle: 'World' },
+
+  // Dimensions
+  width: 1200,
+  height: 630,
+
+  // Output format
+  format: 'png',  // 'png' | 'svg' | 'jpg' | 'webp' | 'mp4' | 'gif'
+
+  // Video options (only for mp4/gif)
+  fps: 30,
+  duration: 5,    // seconds
+
+  // Quality
+  quality: 90,    // JPEG/WebP quality (1-100)
+  crf: 23,        // Video quality (0-51, lower = better)
+
+  // Fonts
+  fonts: [
+    { name: 'Inter', data: interFontBuffer, weight: 400 },
+    { name: 'Inter', data: interBoldBuffer, weight: 700 },
+  ],
+
+  // Debug mode (shows bounding boxes)
+  debug: false,
+});
+```
+
+### `createRenderer(options)`
+
+Create a reusable renderer with preset options (fonts, defaults):
+
+```typescript
+import { createRenderer } from 'loopwind';
+
+const render = createRenderer({
+  fonts: [
+    { name: 'Inter', data: interFont, weight: 400 },
+    { name: 'Inter', data: interBold, weight: 700 },
+  ],
+  defaults: {
+    width: 1200,
+    height: 630,
+  },
+});
+
+// Now render without specifying fonts each time
+const png = await render(OGImage, {
+  props: { title: 'Hello' },
+  format: 'png',
+});
+```
+
+---
+
+## TypeScript Types
+
+Full type definitions for templates and rendering:
+
+```typescript
+import type {
+  Template,
+  TemplateProps,
+  RenderOptions,
+  RenderResult,
+  RendererConfig,
+  TwFunction,
+  FrameInfo,
+} from 'loopwind';
+
+// Template function type
+type Template<P extends TemplateProps = TemplateProps> = (props: P & {
+  tw: TwFunction;
+  frame?: FrameInfo;
+  image?: (name: string) => string;
+}) => JSX.Element;
+
+// Props must be JSON-serializable
+interface TemplateProps {
+  [key: string]: string | number | boolean | null | undefined |
+                 string[] | number[] | TemplateProps | TemplateProps[];
+}
+
+// tw() function signature
+type TwFunction = (classes: string) => React.CSSProperties;
+
+// Frame info for video templates
+interface FrameInfo {
+  index: number;       // Current frame (0-based)
+  total: number;       // Total frames
+  progress: number;    // 0 to 1
+  time: number;        // Current time in seconds
+  fps: number;         // Frames per second
+  duration: number;    // Total duration in seconds
+}
+
+// Render options
+interface RenderOptions<P extends TemplateProps = TemplateProps> {
+  props: P;
+  width?: number;       // Default: from template meta or 1200
+  height?: number;      // Default: from template meta or 630
+  format?: 'png' | 'jpg' | 'webp' | 'svg' | 'mp4' | 'gif';
+
+  // Image quality (jpg, webp)
+  quality?: number;     // 1-100, default: 90
+
+  // Video options (mp4, gif)
+  fps?: number;         // Default: 30
+  duration?: number;    // Seconds
+  crf?: number;         // 0-51, default: 23
+
+  // Fonts (if not using createRenderer)
+  fonts?: FontConfig[];
+
+  // Debug mode
+  debug?: boolean;
+}
+
+// Font configuration
+interface FontConfig {
+  name: string;
+  data: ArrayBuffer | Buffer;
+  weight?: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+  style?: 'normal' | 'italic';
+}
+
+// Renderer configuration
+interface RendererConfig {
+  colors?: Record<string, string>;
+  fonts?: FontsConfig;
+  tokens?: TokensConfig;
+  defaults?: {
+    width?: number;
+    height?: number;
+    format?: string;
+  };
+  templates?: Record<string, Template>;
+}
+
+// Render result
+type RenderResult = Buffer | Uint8Array;
+```
+
+**Using types in your templates:**
+
+```typescript
+import type { Template, TwFunction, FrameInfo } from 'loopwind';
+
+interface BlogOGProps {
+  title: string;
+  author: string;
+  publishedAt?: string;
+  tags?: string[];
+}
+
+const BlogOG: Template<BlogOGProps> = ({ title, author, publishedAt, tags, tw }) => (
+  <div style={tw("w-full h-full bg-white p-12")}>
+    <h1 style={tw("text-5xl font-bold")}>{title}</h1>
+    <p style={tw("text-xl text-gray-600 mt-4")}>by {author}</p>
+    {tags && (
+      <div style={tw("flex gap-2 mt-4")}>
+        {tags.map(tag => (
+          <span key={tag} style={tw("bg-gray-100 px-3 py-1 rounded-full text-sm")}>
+            {tag}
+          </span>
+        ))}
+      </div>
+    )}
+  </div>
+);
+```
+
+---
+
+## Error Handling
+
+The SDK throws typed errors for different failure scenarios:
+
+```typescript
+import { render, RenderError, ValidationError, FontError } from 'loopwind';
+
+try {
+  const png = await render(MyTemplate, {
+    props: { title: 'Hello' },
+    format: 'png',
+  });
+} catch (error) {
+  if (error instanceof ValidationError) {
+    // Invalid props, missing required fields, etc.
+    console.error('Validation failed:', error.message);
+    console.error('Field:', error.field);
+    console.error('Expected:', error.expected);
+  } else if (error instanceof FontError) {
+    // Font loading failed
+    console.error('Font error:', error.message);
+    console.error('Font name:', error.fontName);
+  } else if (error instanceof RenderError) {
+    // Rendering failed (Satori/resvg error)
+    console.error('Render failed:', error.message);
+    console.error('Stage:', error.stage); // 'jsx' | 'svg' | 'rasterize' | 'encode'
+  } else {
+    // Unknown error
+    throw error;
+  }
+}
+```
+
+**Error types:**
+
+| Error | When | Properties |
+|-------|------|------------|
+| `ValidationError` | Invalid props, dimensions, format | `field`, `expected`, `received` |
+| `FontError` | Font file missing, corrupt, or unsupported | `fontName`, `fontPath` |
+| `RenderError` | JSX/SVG/rasterization/encoding failed | `stage`, `cause` |
+| `TimeoutError` | Render exceeded time limit | `timeout`, `elapsed` |
+| `ImageFetchError` | External image failed to load | `url`, `status`, `cause` |
+
+**Handling external image errors:**
+
+```typescript
+import { render, ImageFetchError } from 'loopwind';
+
+try {
+  const png = await render(CardWithImage, {
+    props: {
+      title: 'Hello',
+      imageUrl: 'https://example.com/broken.jpg'  // 404
+    },
+    format: 'png',
+  });
+} catch (error) {
+  if (error instanceof ImageFetchError) {
+    console.error(`Failed to fetch ${error.url}: ${error.status}`);
+    // Optionally render without the image
+    const fallback = await render(CardWithImage, {
+      props: { title: 'Hello', imageUrl: null },
+      format: 'png',
+    });
+  }
+}
+```
+
+**Timeouts:**
+
+```typescript
+const png = await render(MyTemplate, {
+  props: { title: 'Hello' },
+  format: 'png',
+  timeout: 30000,  // 30 seconds max
+});
+```
+
+---
+
+## Template Registry (Optional)
+
+For convenience, you can register templates by name:
+
+```typescript
+import { createRenderer } from 'loopwind';
+
+// Define templates
+const templates = {
+  'og-image': ({ title, tw }) => (
+    <div style={tw("w-full h-full bg-blue-500 flex items-center justify-center")}>
+      <h1 style={tw("text-white text-6xl")}>{title}</h1>
+    </div>
+  ),
+
+  'blog-card': ({ title, author, tw }) => (
+    <div style={tw("w-full h-full bg-white p-12")}>
+      <h1 style={tw("text-4xl font-bold")}>{title}</h1>
+      <p style={tw("text-gray-600")}>by {author}</p>
+    </div>
+  ),
+};
+
+const render = createRenderer({ templates });
+
+// Render by name
+const png = await render('og-image', { props: { title: 'Hello' }, format: 'png' });
+const jpg = await render('blog-card', { props: { title: 'Post', author: 'Jane' }, format: 'jpg' });
+```
+
+---
+
+## Framework Integration
+
+### Next.js API Route
+
+```typescript
+// app/api/og/route.ts
+import { render } from 'loopwind';
+
+const OGImage = ({ title, tw }) => (
+  <div style={tw("w-full h-full bg-black flex items-center justify-center")}>
+    <h1 style={tw("text-white text-6xl")}>{title}</h1>
+  </div>
+);
+
+export async function GET(request: Request) {
+  const { searchParams } = new URL(request.url);
+  const title = searchParams.get('title') || 'Hello';
+
+  const png = await render(OGImage, {
+    props: { title },
+    width: 1200,
+    height: 630,
+    format: 'png',
+  });
+
+  return new Response(png, {
+    headers: { 'Content-Type': 'image/png' },
+  });
+}
+```
+
+### Express
+
+```typescript
+import express from 'express';
+import { render } from 'loopwind';
+
+const OGImage = ({ title, tw }) => (
+  <div style={tw("w-full h-full bg-blue-500 flex items-center justify-center")}>
+    <h1 style={tw("text-white text-6xl")}>{title}</h1>
+  </div>
+);
+
+const app = express();
+
+app.get('/og', async (req, res) => {
+  const { title } = req.query;
+
+  const png = await render(OGImage, {
+    props: { title },
+    width: 1200,
+    height: 630,
+    format: 'png',
+  });
+
+  res.type('image/png').send(png);
+});
+```
+
+### Cloudflare Workers
+
+```typescript
+import { render } from 'loopwind/edge';
+
+const OGImage = ({ title, tw }) => (
+  <div style={tw("w-full h-full bg-gradient-to-r from-purple-500 to-pink-500 flex items-center justify-center")}>
+    <h1 style={tw("text-white text-6xl font-bold")}>{title}</h1>
+  </div>
+);
+
+export default {
+  async fetch(request: Request) {
+    const url = new URL(request.url);
+    const title = url.searchParams.get('title') || 'Hello';
+
+    const png = await render(OGImage, {
+      props: { title },
+      width: 1200,
+      height: 630,
+      format: 'png',
+    });
+
+    return new Response(png, {
+      headers: {
+        'Content-Type': 'image/png',
+        'Cache-Control': 'public, max-age=86400',
+      },
+    });
+  },
+};
+```
+
+---
+
+## Shared Components Library
+
+Build a library of reusable components:
+
+```typescript
+// components/base.tsx
+export const Gradient = ({ from, to, children, tw }) => (
+  <div
+    style={{
+      ...tw("w-full h-full flex items-center justify-center"),
+      background: `linear-gradient(135deg, ${from}, ${to})`,
+    }}
+  >
+    {children}
+  </div>
+);
+
+export const Card = ({ children, tw }) => (
+  <div style={tw("bg-white rounded-2xl shadow-2xl p-8")}>
+    {children}
+  </div>
+);
+
+export const Avatar = ({ src, tw }) => (
+  <img src={src} style={tw("w-16 h-16 rounded-full")} />
+);
+
+// templates/blog-og.tsx
+import { Gradient, Card, Avatar } from './components/base';
+
+export const BlogOG = ({ title, author, avatar, tw }) => (
+  <Gradient from="#667eea" to="#764ba2" tw={tw}>
+    <Card tw={tw}>
+      <div style={tw("flex items-center gap-4")}>
+        <Avatar src={avatar} tw={tw} />
+        <div>
+          <h1 style={tw("text-3xl font-bold")}>{title}</h1>
+          <p style={tw("text-gray-500")}>by {author}</p>
+        </div>
+      </div>
+    </Card>
+  </Gradient>
+);
+```
+
+---
+
+## Configuration
+
+Define custom colors and fonts in `createRenderer()`. Same structure as `loopwind.json`:
+
+```typescript
+import { createRenderer } from 'loopwind';
+
+const render = createRenderer({
+  // Custom colors for tw()
+  colors: {
+    primary: '#18181b',
+    'primary-foreground': '#fafafa',
+    secondary: '#f4f4f5',
+    'secondary-foreground': '#18181b',
+    background: '#ffffff',
+    foreground: '#09090b',
+    muted: '#f4f4f5',
+    'muted-foreground': '#71717a',
+    accent: '#f4f4f5',
+    'accent-foreground': '#18181b',
+    destructive: '#ef4444',
+    'destructive-foreground': '#fafafa',
+    border: '#e4e4e7',
+    card: '#ffffff',
+    'card-foreground': '#09090b',
+  },
+
+  // Fonts - simple (system fonts, uses bundled Inter for rendering)
+  fonts: {
+    sans: ['Inter', 'system-ui', 'sans-serif'],
+    mono: ['JetBrains Mono', 'monospace'],
+  },
+
+  // OR fonts with custom font files
+  fonts: {
+    sans: {
+      family: ['Inter', 'system-ui', 'sans-serif'],
+      files: [
+        { data: interRegular, weight: 400 },
+        { data: interBold, weight: 700 },
+      ],
+    },
+    mono: {
+      family: ['JetBrains Mono', 'monospace'],
+      files: [
+        { data: jetbrainsMono, weight: 400 },
+      ],
+    },
+  },
+
+  // Design tokens
+  tokens: {
+    borderRadius: {
+      sm: '0.25rem',
+      md: '0.375rem',
+      lg: '0.5rem',
+      xl: '0.75rem',
+    },
+  },
+
+  // Defaults
+  defaults: {
+    width: 1200,
+    height: 630,
+  },
+});
+
+// Now custom colors work in tw()
+const OGImage = ({ title, tw }) => (
+  <div style={tw("w-full h-full bg-primary flex items-center justify-center")}>
+    <h1 style={tw("text-primary-foreground text-6xl")}>{title}</h1>
+    <p style={tw("text-muted-foreground text-2xl")}>Powered by loopwind</p>
+  </div>
+);
+```
+
+**CLI vs SDK fonts:**
+
+| | CLI (`loopwind.json`) | SDK (`createRenderer`) |
+|---|---|---|
+| Simple | `"sans": ["Inter", "sans-serif"]` | Same |
+| With files | `{ "path": "./fonts/Inter.woff", "weight": 400 }` | `{ data: fontBuffer, weight: 400 }` |
+
+CLI uses file paths, SDK uses binary data (ArrayBuffer). Colors and tokens are identical.
+
+---
+
+## The `tw()` Function
+
+Templates receive `tw` as a prop. It converts Tailwind classes to inline styles:
+
+```typescript
+// tw() returns a style object
+const MyTemplate = ({ tw }) => (
+  <div style={tw("flex items-center justify-center p-4 bg-blue-500 rounded-lg")}>
+    Hello
+  </div>
+);
+
+// Equivalent to:
+const MyTemplate = () => (
+  <div style={{
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: 16,
+    backgroundColor: '#3b82f6',
+    borderRadius: 8,
+  }}>
+    Hello
+  </div>
+);
+```
+
+**Combining with custom styles:**
+
+```typescript
+const AnimatedBox = ({ opacity, tw }) => (
+  <div
+    style={{
+      ...tw("w-32 h-32 bg-blue-500 rounded-lg"),
+      opacity,  // Custom style merged in
+    }}
+  >
+    Hello
+  </div>
+);
+```
+
+**Dynamic classes:**
+
+```typescript
+const Button = ({ primary, tw }) => (
+  <div style={tw(`
+    px-6 py-3 rounded-lg font-bold
+    ${primary ? 'bg-blue-500 text-white' : 'bg-gray-200 text-gray-800'}
+  `)}>
+    Click me
+  </div>
+);
+```
+
+---
+
+## Installation
+
+```bash
+npm install loopwind
+```
+
+### Requirements
+
+- Node.js 18+
+- For video: FFmpeg (optional, for faster encoding)
+
+### Bundle Size
+
+| Import | Size | Use Case |
+|--------|------|----------|
+| `loopwind` (full) | ~2MB | All formats including video |
+| `loopwind/image` | ~500KB | PNG, SVG, JPG, WebP only |
+| `loopwind/svg` | ~150KB | SVG only (no rasterization) |
+
+---
+
+## Comparison with Satori
+
+Loopwind wraps Satori with additional features:
+
+| Feature | Satori | Loopwind |
+|---------|--------|----------|
+| JSX → SVG | ✅ | ✅ |
+| SVG → PNG | ❌ | ✅ (via resvg) |
+| Tailwind via tw() | ❌ | ✅ |
+| Video rendering | ❌ | ✅ (mp4, gif) |
+| Animation | ❌ | ✅ (frame prop) |
+| Font loading | Manual | Built-in helpers |
+
+---
+
+## Edge Runtime Support
+
+For edge runtimes (Cloudflare Workers, Vercel Edge), use the edge-compatible build:
+
+```typescript
+import { render } from 'loopwind/edge';
+```
+
+**Limitations in edge:**
+- PNG/WebP/JPG work (via WASM)
+- Video (mp4/gif) requires Node.js runtime
+- Bundle size ~2MB (may exceed free tier limits)
+
+---
+
+## SDK vs CLI vs Platform
+
+| | SDK | CLI | Platform |
+|---|---|---|---|
+| **What** | npm library | Command-line tool | Hosted API service |
+| **Install** | `npm install loopwind` | `npm install -g loopwind` | Sign up at loopwind.dev |
+| **Use case** | Self-hosted rendering | Local development | URL-based rendering |
+| **Templates** | Pass as functions | `.loopwind/` folder | Publish from CLI |
+| **Config** | `createRenderer({...})` | `loopwind.json` | Stored with templates |
+| **Rendering** | Your server | Your machine | loopwind.dev servers |
+
+**When to use what:**
+
+- **SDK**: You want to render images/videos in your own app (Next.js API route, Express server, etc.)
+- **CLI**: You're authoring templates locally, testing, or rendering one-off images/videos
+- **Platform**: You want simple render URLs (`?title=Hello`) without running your own server
+
+**Platform uses SDK internally.** When you publish a template and call the render URL, the platform uses the SDK to do the actual rendering.
+
+---
+
+## Related
+
+- [PLATFORM.md](./PLATFORM.md) - Hosted render API (publish templates, get render URLs)
+- [loopwind CLI](../README.md) - CLI tool for local development