loopwind 0.9.1

package/FONTS.md

@@ -0,0 +1,156 @@
+# Font Handling in dsgn
+
+dsgn 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/
+├── my-template.tsx
+├── meta.json
+└── fonts/
+    ├── Inter-Regular.woff
+    ├── Inter-Bold.woff
+    └── Playfair-Bold.woff
+```
+
+**Metadata with Custom Fonts:**
+
+```json
+{
+  "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"
+    }
+  ]
+}
+```
+
+**Supported Formats:**
+- ✅ **WOFF** (`.woff`) - Recommended
+- ✅ **WOFF2** (`.woff2`) - Best compression
+- ✅ **TTF** (`.ttf`) - Also supported
+- ✅ **OTF** (`.otf`) - Also supported
+
+## Font Classes (from dsgn.json)
+
+Use Tailwind font-family classes in templates. These reference the font stacks in `dsgn.json`:
+
+**dsgn.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 dsgn.json */}
+      <h1 style={tw('font-sans text-6xl font-bold')}>
+        {title}
+      </h1>
+
+      {/* Uses fonts.mono from dsgn.json */}
+      <code style={tw('font-mono text-sm')}>
+        Hello World
+      </code>
+    </div>
+  );
+}
+```
+
+**Available classes:**
+- `font-sans` - Uses `fonts.sans` from dsgn.json (default: system-ui, -apple-system, sans-serif)
+- `font-serif` - Uses `fonts.serif` from dsgn.json (default: Georgia, serif)
+- `font-mono` - Uses `fonts.mono` from dsgn.json (default: monospace)
+
+## How It Works Together
+
+1. **Font data** is loaded from template's `meta.json` (or default Noto Sans)
+2. **Font classes** (`font-sans`) apply CSS `fontFamily` from `dsgn.json`
+3. The font name in CSS must match a loaded font for Satori to use it
+
+**Example:**
+
+```json
+// Template meta.json - Loads the actual font files
+{
+  "fonts": [
+    { "name": "Inter", "path": "fonts/Inter-Regular.woff", "weight": 400 },
+    { "name": "Inter", "path": "fonts/Inter-Bold.woff", "weight": 700 }
+  ]
+}
+```
+
+```json
+// dsgn.json - Defines font stacks for CSS
+{
+  "fonts": {
+    "sans": ["Inter", "system-ui", "sans-serif"]
+  }
+}
+```
+
+```tsx
+// Template - Uses both
+export default function({ 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.json */}
+      {title}
+    </h1>
+  );
+}
+```
+
+## 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 `dsgn.json` font names match template's loaded fonts
+5. **Include fallbacks:** Always include system fallbacks in font stacks

package/HELPERS_DEMO.md

@@ -0,0 +1,134 @@
+# 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: _dsgn/templates/video-overlay/index.tsx
+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.mp4')}
+        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
+// meta.json
+{
+  "name": "video-overlay",
+  "type": "video",
+  "size": {
+    "width": 1920,
+    "height": 1080
+  },
+  "video": {
+    "fps": 30,
+    "duration": 3
+  }
+}
+```
+
+```json
+// props.json
+{
+  "title": "Hello World",
+  "background": "./my-video.mp4"
+}
+```
+
+```bash
+# Render
+dsgn 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

@@ -0,0 +1,286 @@
+# Project Structure
+
+## Overview
+
+**dsgn** 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 `dsgn` in your project, this is the structure:
+
+```
+my-project/
+├── dsgn/
+│   ├── templates/          # Installed templates (like node_modules)
+│   │   ├── banner-hero/
+│   │   │   ├── banner-hero.tsx
+│   │   │   └── meta.json
+│   │   └── product-card/
+│   │       ├── product-card.tsx
+│   │       └── meta.json
+│   └── outputs/            # Generated images/videos
+│       ├── banner-hero-1234567890.png
+│       └── product-card-1234567891.png
+├── dsgn.json              # Your project's design tokens (optional)
+└── package.json
+```
+
+### The CLI Package (this repo)
+
+```
+dsgn/
+├── 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 dsgn
+```
+
+This installs the CLI globally, making the `dsgn` command available anywhere.
+
+### 2. Project Usage
+
+```bash
+cd ~/my-project
+dsgn add banner-hero
+```
+
+This:
+1. Fetches template from registry: `https://design.unpeel.dev/r/banner-hero`
+2. Installs to: `~/my-project/dsgn/templates/banner-hero/`
+3. Creates structure if it doesn't exist
+
+### 3. Rendering
+
+```bash
+dsgn render banner-hero --props '{"title":"Hello"}'
+```
+
+This:
+1. Loads template from `dsgn/templates/banner-hero/`
+2. Loads config from `dsgn.json` (if exists)
+3. Renders with Satori
+4. Saves to `dsgn/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 `dsgn add banner-hero`, it:
+1. Fetches this JSON
+2. Writes files to `dsgn/templates/banner-hero/`
+3. Templates are now local and ready to use
+
+## Git Workflow
+
+### What to commit?
+
+**DO commit:**
+- `dsgn/templates/` - Your templates (like `node_modules` in some projects)
+- `dsgn.json` - Your design configuration
+
+**DON'T commit:**
+- `dsgn/outputs/` - Generated files (usually)
+
+Example `.gitignore`:
+
+```gitignore
+# Ignore generated outputs
+dsgn/outputs/
+
+# Keep templates (optional - depends on your workflow)
+# dsgn/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
+dsgn init
+
+# Install templates
+dsgn add banner-hero
+dsgn add product-card
+
+# Render images
+dsgn render banner-hero --props props.json
+```
+
+### Sharing with Team
+
+```bash
+# Developer 1
+git add dsgn/templates/
+git commit -m "Add banner template"
+git push
+
+# Developer 2
+git pull
+dsgn list  # See all templates
+dsgn render banner-hero --props '{"title":"Team Banner"}'
+```
+
+### CI/CD Pipeline
+
+```yaml
+# .github/workflows/generate-images.yml
+- name: Install dsgn
+  run: npm install -g dsgn
+
+- name: Generate images
+  run: |
+    dsgn render banner-hero --props props/hero.json
+    dsgn render product-card --props props/product.json
+
+- name: Upload artifacts
+  uses: actions/upload-artifact@v3
+  with:
+    path: dsgn/outputs/
+```
+
+## Future Enhancements
+
+### Template Versions
+
+```bash
+dsgn add banner-hero@2.0.0
+dsgn update banner-hero
+```
+
+### Template Marketplace
+
+```bash
+dsgn search "hero"
+dsgn add @company/custom-banner
+```
+
+### Global vs Local
+
+```bash
+# Install globally (like npm -g)
+dsgn add banner-hero --global
+
+# Install locally (default, like npm install)
+dsgn add banner-hero
+```
+
+This is the **Shadcn for design and marketing** - same philosophy of owning your code, but for design assets!