loopwind 0.12.1 → 0.12.3

package/FONTS.md

@@ -1,160 +0,0 @@
-# Font Handling in loopwind
-
-loopwind has a two-part font system:
-1. **Font Data** (template-specific) - Actual font files loaded by Satori
-2. **Font Classes** (project-wide) - CSS font-family applied via `tw()`
-
-## Font Data (Loaded by Satori)
-
-Templates can bundle custom fonts or use the default font.
-
-### Default Font (No Setup Required)
-
-If a template doesn't specify fonts, **Noto Sans** is automatically fetched from jsDelivr CDN.
-
-### Custom Fonts (Template-Bundled)
-
-Templates can bundle their own fonts for:
-- **Brand-specific fonts** (e.g., company brand guidelines)
-- **Offline rendering** (no CDN dependency)
-- **Custom typography** (special display fonts)
-
-**Template Structure with Fonts:**
-
-```
-my-template/
-├── template.tsx
-└── fonts/
-    ├── Inter-Regular.woff
-    ├── Inter-Bold.woff
-    └── Playfair-Bold.woff
-```
-
-**Template with Custom Fonts:**
-
-```tsx
-export const meta = {
-  name: "my-template",
-  type: "image",
-  size: { width: 1200, height: 630 },
-  props: { title: "string" },
-  fonts: [
-    {
-      name: "Inter",
-      path: "fonts/Inter-Regular.woff",
-      weight: 400,
-      style: "normal"
-    },
-    {
-      name: "Inter",
-      path: "fonts/Inter-Bold.woff",
-      weight: 700,
-      style: "normal"
-    }
-  ]
-};
-
-export default function Template({ title, tw }) {
-  return (
-    <h1 style={tw('font-sans font-bold text-6xl')}>{title}</h1>
-  );
-}
-```
-
-**Supported Formats:**
-- ✅ **WOFF** (`.woff`) - Recommended
-- ✅ **WOFF2** (`.woff2`) - Best compression
-- ✅ **TTF** (`.ttf`) - Also supported
-- ✅ **OTF** (`.otf`) - Also supported
-
-## Font Classes (from loopwind.json)
-
-Use Tailwind font-family classes in templates. These reference the font stacks in `loopwind.json`:
-
-**loopwind.json:**
-```json
-{
-  "fonts": {
-    "sans": ["Inter", "system-ui", "-apple-system", "sans-serif"],
-    "serif": ["Georgia", "serif"],
-    "mono": ["JetBrains Mono", "Courier New", "monospace"]
-  }
-}
-```
-
-**Template usage:**
-```tsx
-export default function({ title, tw }) {
-  return (
-    <div style={tw('w-full h-full')}>
-      {/* Uses fonts.sans from loopwind.json */}
-      <h1 style={tw('font-sans text-6xl font-bold')}>
-        {title}
-      </h1>
-
-      {/* Uses fonts.mono from loopwind.json */}
-      <code style={tw('font-mono text-sm')}>
-        Hello World
-      </code>
-    </div>
-  );
-}
-```
-
-**Available classes:**
-- `font-sans` - Uses `fonts.sans` from loopwind.json (default: system-ui, -apple-system, sans-serif)
-- `font-serif` - Uses `fonts.serif` from loopwind.json (default: Georgia, serif)
-- `font-mono` - Uses `fonts.mono` from loopwind.json (default: monospace)
-
-## How It Works Together
-
-1. **Font data** is loaded from template's exported `meta` (or default Noto Sans)
-2. **Font classes** (`font-sans`) apply CSS `fontFamily` from `loopwind.json`
-3. The font name in CSS must match a loaded font for Satori to use it
-
-**Example:**
-
-```tsx
-// template.tsx - Loads the actual font files
-export const meta = {
-  name: "my-template",
-  // ...
-  fonts: [
-    { name: "Inter", path: "fonts/Inter-Regular.woff", weight: 400, style: "normal" },
-    { name: "Inter", path: "fonts/Inter-Bold.woff", weight: 700, style: "normal" }
-  ]
-};
-
-export default function Template({ title, tw }) {
-  return (
-    <h1 style={tw('font-sans font-bold')}>
-      {/* font-sans → fontFamily: "Inter, system-ui, sans-serif" */}
-      {/* Satori uses loaded "Inter" font from meta */}
-      {title}
-    </h1>
-  );
-}
-```
-
-```json
-// loopwind.json - Defines font stacks for CSS
-{
-  "fonts": {
-    "sans": ["Inter", "system-ui", "sans-serif"]
-  }
-}
-```
-
-## Fallback Behavior
-
-- If template fonts fail to load → falls back to Noto Sans from CDN
-- If `font-sans` used but no fonts defined → uses system font stack
-- If CSS font-family doesn't match loaded fonts → Satori uses fallback
-
-## Best Practices
-
-1. **For most templates:** Use default Noto Sans, no font setup needed
-2. **For branded templates:** Bundle custom fonts in template's `fonts/` folder
-3. **Use font classes:** `tw('font-sans')` instead of raw `fontFamily: 'Inter'`
-4. **Match names:** Ensure `loopwind.json` font names match template's loaded fonts
-5. **Include fallbacks:** Always include system fallbacks in font stacks

package/HELPERS_DEMO.md

@@ -1,126 +0,0 @@
-# Image and Video Helpers - Simple Demo
-
-## ✅ What We Added
-
-Two new helpers for templates:
-- `image()` - Embed images (jpg, png, gif, webp, svg)
-- `video()` - Embed videos (mp4, mov, etc.) - auto-syncs to current frame
-
-## Usage
-
-### Images
-
-```tsx
-export default function Banner({ tw, image }) {
-  return (
-    <div style={tw('relative w-full h-full')}>
-      <img src={image('background.jpg')} />
-      <h1 style={tw('absolute top-10 left-10')}>Hello World</h1>
-    </div>
-  );
-}
-```
-
-**Props format:**
-```json
-{
-  "background": "./path/to/background.jpg"
-}
-```
-
-The renderer automatically detects props that end in image extensions and pre-loads them.
-
-### Videos (for video templates)
-
-```tsx
-export default function VideoOverlay({ tw, video, frame, title }) {
-  return (
-    <div style={tw('relative w-full h-full')}>
-      <img src={video('background.mp4')} />
-      <h1 style={tw('absolute top-10 left-10 text-white')}>{title}</h1>
-    </div>
-  );
-}
-```
-
-**How it works:**
-1. First render pass: Template calls `video('background.mp4')` → marks video as needed
-2. Pre-generation: Extracts all frames from video at template's FPS
-3. Actual render: Returns frame matching current template frame number
-4. Frames are cached in memory for fast access
-
-**Props format:**
-```json
-{
-  "title": "My Video",
-  "background": "./path/to/background.mp4"
-}
-```
-
-Then use the `video()` helper with the prop value.
-
-## Why This Is Simple
-
-- **No complex API** - Just `image('path')` and `video('path')`
-- **Auto-syncing** - Videos automatically match template frame
-- **Caching** - Frames extracted once, reused for all renders
-- **Works like QR codes** - Same discovery + pre-generation pattern
-- **No timeline controls** - Keep it simple, just background videos
-
-## Example: Video with Text Overlay
-
-```tsx
-// Template: _loopwind/templates/video-overlay/template.tsx
-export const meta = {
-  name: "video-overlay",
-  type: "video",
-  size: { width: 1920, height: 1080 },
-  video: { fps: 30, duration: 3 },
-  props: { title: "string", background: "string" }
-};
-
-export default function VideoOverlay({ tw, video, frame, progress, title }) {
-  // Animate title opacity
-  const opacity = progress < 0.2 ? progress / 0.2 : 1;
-
-  return (
-    <div style={tw('relative w-full h-full flex items-center justify-center')}>
-      {/* Background video - auto-syncs to current frame */}
-      <img
-        src={video('background')}
-        style={tw('absolute inset-0 w-full h-full object-cover')}
-      />
-
-      {/* Animated title */}
-      <h1
-        style={{
-          ...tw('text-6xl font-bold text-white'),
-          opacity
-        }}
-      >
-        {title}
-      </h1>
-    </div>
-  );
-}
-```
-
-```json
-// props.json
-{
-  "title": "Hello World",
-  "background": "./my-video.mp4"
-}
-```
-
-```bash
-# Render
-loopwind render video-overlay props.json --out output.mp4
-```
-
-This will:
-1. Extract frames from `my-video.mp4` at 30fps
-2. Render 90 frames (3s × 30fps) with animated title overlay
-3. Encode to MP4
-
-**Super fast and simple!** 🚀

package/PROJECT_STRUCTURE.md

@@ -1,284 +0,0 @@
-# Project Structure
-
-## Overview
-
-**loopwind** is a global CLI tool that operates on project-local templates and outputs.
-
-Think of it like:
-- **Global CLI**: Like `npm` or `git` - installed once, used everywhere
-- **Local templates**: Like `node_modules` - each project has its own
-- **Local outputs**: Generated assets stay with the project
-
-## Directory Structure
-
-### Your Project
-
-When you use `loopwind` in your project, this is the structure:
-
-```
-my-project/
-├── _loopwind/
-│   ├── templates/          # Installed templates (like node_modules)
-│   │   ├── banner-hero/
-│   │   │   └── template.tsx    # Contains export const meta + component
-│   │   └── product-card/
-│   │       └── template.tsx
-│   └── outputs/            # Generated images/videos
-│       ├── banner-hero.png
-│       └── product-card.png
-├── loopwind.json              # Your project's design tokens (optional)
-└── package.json
-```
-
-### The CLI Package (this repo)
-
-```
-loopwind/
-├── src/
-│   ├── cli.ts                    # Main CLI entry point
-│   ├── commands/                 # Command implementations
-│   │   ├── add.ts               # Install templates
-│   │   ├── list.ts              # List templates
-│   │   ├── render.ts            # Render images
-│   │   ├── validate.ts          # Validate templates
-│   │   └── init.ts              # Initialize config
-│   ├── lib/
-│   │   ├── constants.ts         # Paths and constants
-│   │   ├── utils.ts             # Utility functions
-│   │   ├── installer.ts         # Registry fetching
-│   │   ├── renderer.ts          # Satori rendering
-│   │   └── config.ts            # Config handling
-│   └── types/
-│       ├── template.ts          # Template types
-│       └── config.ts            # Config types
-├── dist/                        # Compiled output
-├── package.json
-├── tsconfig.json
-└── README.md
-```
-
-## How It Works
-
-### 1. Global Installation
-
-```bash
-npm install -g loopwind
-```
-
-This installs the CLI globally, making the `loopwind` command available anywhere.
-
-### 2. Project Usage
-
-```bash
-cd ~/my-project
-loopwind add banner-hero
-```
-
-This:
-1. Fetches template from registry: `https://design.unpeel.dev/r/banner-hero`
-2. Installs to: `~/my-project/loopwind/templates/banner-hero/`
-3. Creates structure if it doesn't exist
-
-### 3. Rendering
-
-```bash
-loopwind render banner-hero --props '{"title":"Hello"}'
-```
-
-This:
-1. Loads template from `loopwind/templates/banner-hero/`
-2. Loads config from `loopwind.json` (if exists)
-3. Renders with Satori
-4. Saves to `loopwind/outputs/banner-hero-{timestamp}.png`
-
-## Why This Architecture?
-
-### Global CLI
-
-**Benefits:**
-- Install once, use everywhere
-- Always up to date
-- Consistent tooling across projects
-
-**Like:**
-- `npm` - global tool, local packages
-- `git` - global tool, local repos
-- `tsc` - global TypeScript compiler
-
-### Local Templates
-
-**Benefits:**
-- Version controlled with your project
-- Different projects can use different template versions
-- Team members get the same templates
-- No dependency on external registry at runtime
-
-**Like:**
-- `node_modules` - dependencies live with the project
-- `.next` - build artifacts live with the project
-
-### Local Outputs
-
-**Benefits:**
-- Generated assets stay with the project
-- Easy to commit to git (if desired)
-- No confusion about where files are
-- Works well with build processes
-
-## Template Registry
-
-Templates live online (like npm registry):
-
-```
-https://design.unpeel.dev/r/banner-hero
-```
-
-Returns:
-
-```json
-{
-  "name": "banner-hero",
-  "version": "1.0.0",
-  "description": "A hero banner",
-  "files": [
-    {
-      "path": "banner-hero.tsx",
-      "content": "..."
-    },
-    {
-      "path": "meta.json",
-      "content": "..."
-    }
-  ]
-}
-```
-
-When you run `loopwind add banner-hero`, it:
-1. Fetches this JSON
-2. Writes files to `loopwind/templates/banner-hero/`
-3. Templates are now local and ready to use
-
-## Git Workflow
-
-### What to commit?
-
-**DO commit:**
-- `loopwind/templates/` - Your templates (like `node_modules` in some projects)
-- `loopwind.json` - Your design configuration
-
-**DON'T commit:**
-- `loopwind/outputs/` - Generated files (usually)
-
-Example `.gitignore`:
-
-```gitignore
-# Ignore generated outputs
-loopwind/outputs/
-
-# Keep templates (optional - depends on your workflow)
-# loopwind/templates/
-```
-
-Some teams prefer to commit templates (reproducibility), others prefer to install them (like npm packages).
-
-## Comparison to Other Tools
-
-### Like Shadcn
-
-- Registry-based templates
-- Install to your project
-- You own the code
-- Customize freely
-
-### Like npm
-
-- Global CLI tool
-- Project-local dependencies (templates)
-- Registry for discovery
-- Semantic versioning
-
-### Like Tailwind
-
-- Config file for customization
-- Design tokens approach
-- Build-time generation
-- Framework agnostic
-
-## Common Workflows
-
-### Starting a New Project
-
-```bash
-mkdir my-project
-cd my-project
-
-# Initialize config
-loopwind init
-
-# Install templates
-loopwind add banner-hero
-loopwind add product-card
-
-# Render images
-loopwind render banner-hero --props props.json
-```
-
-### Sharing with Team
-
-```bash
-# Developer 1
-git add loopwind/templates/
-git commit -m "Add banner template"
-git push
-
-# Developer 2
-git pull
-loopwind list  # See all templates
-loopwind render banner-hero --props '{"title":"Team Banner"}'
-```
-
-### CI/CD Pipeline
-
-```yaml
-# .github/workflows/generate-images.yml
-- name: Install loopwind
-  run: npm install -g loopwind
-
-- name: Generate images
-  run: |
-    loopwind render banner-hero --props props/hero.json
-    loopwind render product-card --props props/product.json
-
-- name: Upload artifacts
-  uses: actions/upload-artifact@v3
-  with:
-    path: loopwind/outputs/
-```
-
-## Future Enhancements
-
-### Template Versions
-
-```bash
-loopwind add banner-hero@2.0.0
-loopwind update banner-hero
-```
-
-### Template Marketplace
-
-```bash
-loopwind search "hero"
-loopwind add @company/custom-banner
-```
-
-### Global vs Local
-
-```bash
-# Install globally (like npm -g)
-loopwind add banner-hero --global
-
-# Install locally (default, like npm install)
-loopwind add banner-hero
-```
-
-This is the **Shadcn for design and marketing** - same philosophy of owning your code, but for design assets!