loopwind 0.9.1

package/TAILWIND.md

@@ -0,0 +1,228 @@
+# Using Tailwind Classes in Templates
+
+## Overview
+
+Templates can use Tailwind utility classes instead of writing inline styles! The `tw()` function is automatically provided to every template and converts Tailwind classes to inline styles that Satori can render.
+
+## Basic Usage
+
+```tsx
+export default function MyTemplate({ title, tw }) {
+  return (
+    <div style={tw('flex items-center justify-center w-full h-full bg-blue-500')}>
+      <h1 style={tw('text-6xl font-bold text-white')}>
+        {title}
+      </h1>
+    </div>
+  );
+}
+```
+
+## Combining with Custom Styles
+
+You can mix Tailwind classes with custom styles using the spread operator:
+
+```tsx
+export default function MyTemplate({ title, tw, config }) {
+  return (
+    <div
+      style={{
+        ...tw('flex flex-col p-20 text-white'),
+        background: `linear-gradient(135deg, ${config?.colors?.primary} 0%, ${config?.colors?.secondary} 100%)`,
+      }}
+    >
+      <h1 style={tw('text-8xl font-bold')}>{title}</h1>
+    </div>
+  );
+}
+```
+
+## Supported Tailwind Classes
+
+### Layout
+
+- **Display**: `flex`, `inline-flex`, `block`, `inline-block`, `hidden`
+- **Flex Direction**: `flex-row`, `flex-col`, `flex-row-reverse`, `flex-col-reverse`
+- **Justify**: `justify-start`, `justify-end`, `justify-center`, `justify-between`, `justify-around`
+- **Align**: `items-start`, `items-end`, `items-center`, `items-baseline`, `items-stretch`
+
+### Spacing
+
+- **Padding**: `p-{n}`, `px-{n}`, `py-{n}`, `pt-{n}`, `pb-{n}`, `pl-{n}`, `pr-{n}`
+- **Margin**: `m-{n}`, `mx-{n}`, `my-{n}`, `mt-{n}`, `mb-{n}`, `ml-{n}`, `mr-{n}`
+- **Gap**: `gap-{n}`, `gap-x-{n}`, `gap-y-{n}`
+- **Sizes**: 0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24, 32, 40, 48, 56, 64
+
+Examples:
+```tsx
+tw('p-4')      // padding: 1rem
+tw('px-8')     // paddingLeft: 2rem, paddingRight: 2rem
+tw('m-6')      // margin: 1.5rem
+tw('gap-4')    // gap: 1rem
+```
+
+### Sizing
+
+- **Width**: `w-{n}`, `w-full`, `w-screen`
+- **Height**: `h-{n}`, `h-full`, `h-screen`
+
+Examples:
+```tsx
+tw('w-full')   // width: 100%
+tw('h-64')     // height: 16rem
+```
+
+### Typography
+
+- **Font Size**: `text-xs`, `text-sm`, `text-base`, `text-lg`, `text-xl`, `text-2xl`, `text-3xl`, `text-4xl`, `text-5xl`, `text-6xl`, `text-7xl`, `text-8xl`, `text-9xl`
+- **Font Weight**: `font-thin`, `font-light`, `font-normal`, `font-medium`, `font-semibold`, `font-bold`, `font-extrabold`, `font-black`
+- **Text Align**: `text-left`, `text-center`, `text-right`
+
+Examples:
+```tsx
+tw('text-6xl')       // fontSize: 3.75rem
+tw('font-bold')      // fontWeight: 700
+tw('text-center')    // textAlign: center
+```
+
+### Borders
+
+- **Border Radius**: `rounded`, `rounded-sm`, `rounded-md`, `rounded-lg`, `rounded-xl`, `rounded-2xl`, `rounded-3xl`, `rounded-full`
+
+Examples:
+```tsx
+tw('rounded-lg')     // borderRadius: 0.5rem
+tw('rounded-full')   // borderRadius: 9999px
+```
+
+### Effects
+
+- **Opacity**: `opacity-{0-100}`
+
+Examples:
+```tsx
+tw('opacity-50')     // opacity: 0.5
+tw('opacity-90')     // opacity: 0.9
+```
+
+### Colors
+
+- **Static Colors**: `text-white`, `text-black`, `bg-white`, `bg-black`
+- **Config Colors**: `bg-primary`, `text-primary`, `bg-secondary`, etc. (from dsgn.json)
+
+Examples:
+```tsx
+// Using static colors
+tw('bg-black text-white')
+
+// Using config colors (from dsgn.json)
+tw('bg-primary text-secondary')
+```
+
+## Config Color Integration
+
+The `tw()` function automatically uses colors from your `dsgn.json`:
+
+```json
+{
+  "colors": {
+    "primary": "#667eea",
+    "secondary": "#764ba2",
+    "accent": "#3b82f6"
+  }
+}
+```
+
+```tsx
+// In your template
+<div style={tw('bg-primary text-white')}>
+  {/* background will be #667eea */}
+</div>
+```
+
+## Complete Example
+
+```tsx
+import React from 'react';
+
+export const meta = {
+  name: "social-card",
+  description: "A social media card",
+  size: { width: 1200, height: 630 },
+  props: { title: "string", description: "string" }
+};
+
+interface SocialCardProps {
+  title: string;
+  description: string;
+  tw?: (classes: string) => any;
+  config?: any;
+}
+
+export default function SocialCard({
+  title,
+  description,
+  tw = (c) => ({}),
+  config
+}: SocialCardProps) {
+  return (
+    <div style={tw('w-full h-full flex flex-col justify-center items-center bg-primary text-white p-16')}>
+      <h1 style={tw('text-6xl font-bold text-center mb-8')}>
+        {title}
+      </h1>
+      <p style={tw('text-2xl text-center opacity-90')}>
+        {description}
+      </p>
+    </div>
+  );
+}
+```
+
+## Fallback for Missing tw
+
+Always provide a fallback for the `tw` function in case it's not provided:
+
+```tsx
+export default function MyTemplate({
+  title,
+  tw = (classes: string) => ({})  // Fallback
+}: MyTemplateProps) {
+  // Now tw is always safe to use
+  return <div style={tw('flex items-center')}>{title}</div>;
+}
+```
+
+## Extending Tailwind Support
+
+The current implementation supports common Tailwind classes. To add more:
+
+1. Edit `src/lib/tailwind.ts`
+2. Add to `TAILWIND_MAP` or create a new parser function
+3. Rebuild the CLI
+
+Example adding a new utility:
+
+```typescript
+// In src/lib/tailwind.ts
+const TAILWIND_MAP = {
+  // ... existing classes
+  'shadow-lg': { boxShadow: '0 10px 15px rgba(0,0,0,0.1)' },
+  'shadow-xl': { boxShadow: '0 20px 25px rgba(0,0,0,0.15)' },
+};
+```
+
+## Benefits
+
+1. **Familiar Syntax**: Use the Tailwind classes you already know
+2. **Cleaner Code**: Less verbose than inline styles
+3. **Config Integration**: Automatic color mapping from dsgn.json
+4. **Type Safe**: TypeScript support with CSSProperties
+5. **Extensible**: Easy to add more utilities
+
+## Limitations
+
+- Satori doesn't support all CSS features (no animations, transforms are limited)
+- Pseudo-classes (hover, focus) don't work (Satori renders static images)
+- Some Tailwind utilities may not have equivalents yet
+
+For advanced styling needs, combine Tailwind classes with custom inline styles!

package/TEMPLATE_SOURCES.md

@@ -0,0 +1,363 @@
+# Installing Templates from Different Sources
+
+## Overview
+
+dsgn supports installing templates from multiple sources:
+
+1. **Official Registry** (default)
+2. **Direct URLs**
+3. **GitHub Repositories**
+4. **Local Filesystem**
+
+## 1. Official Registry (Default)
+
+Install templates from the official dsgn registry at `https://dsgncli.com/r`
+
+```bash
+dsgn add banner-hero
+dsgn add product-card
+dsgn add social-og-image
+```
+
+**How it works:**
+- Fetches from: `https://dsgncli.com/r/banner-hero`
+- Returns JSON with template files
+- Installs to: `dsgn/templates/banner-hero/`
+
+### Custom Registry
+
+Use a different registry:
+
+```bash
+dsgn add banner-hero --registry https://my-registry.com/templates
+```
+
+## 2. Direct URLs
+
+Install a template from any publicly accessible URL:
+
+```bash
+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)
+
+**Example template JSON:**
+
+```json
+{
+  "name": "my-template",
+  "version": "1.0.0",
+  "description": "My custom template",
+  "files": [
+    {
+      "path": "my-template.tsx",
+      "content": "import React from 'react';\n\nexport default function..."
+    },
+    {
+      "path": "meta.json",
+      "content": "{\"name\":\"my-template\"...}"
+    }
+  ]
+}
+```
+
+## 3. GitHub Repositories
+
+Install templates directly from GitHub repos:
+
+```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
+
+**Example repo structure:**
+
+```
+username/repo/
+├── template.json          # Required
+├── banner-hero.tsx
+└── meta.json
+```
+
+Or with path:
+
+```
+username/repo/
+└── templates/
+    └── banner-hero/
+        ├── template.json  # Required
+        ├── banner-hero.tsx
+        └── meta.json
+```
+
+**template.json format:**
+
+```json
+{
+  "name": "banner-hero",
+  "version": "1.0.0",
+  "description": "Hero banner template",
+  "files": [
+    {
+      "path": "banner-hero.tsx",
+      "content": "..."
+    },
+    {
+      "path": "meta.json",
+      "content": "..."
+    }
+  ]
+}
+```
+
+## 4. Local Filesystem
+
+Install templates from your 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
+```
+
+**Requirements:**
+- Directory must contain `template.json` or `meta.json`
+- All template files should be in the directory
+
+**Example local structure:**
+
+```
+my-templates/banner-hero/
+├── meta.json           # Required (or template.json)
+├── banner-hero.tsx
+└── assets/
+    └── logo.png
+```
+
+**Use cases:**
+- Development and testing
+- Private templates
+- Shared team templates (monorepo)
+- Before publishing to registry
+
+## Template Format
+
+All sources must provide templates in this format:
+
+```typescript
+interface RegistryTemplate {
+  name: string;
+  version: string;
+  description: string;
+  files: Array<{
+    path: string;      // Relative path within template folder
+    content: string;   // File contents
+  }>;
+}
+```
+
+## Examples
+
+### Example 1: Company Templates on GitHub
+
+```bash
+# Install from company repo
+dsgn add github:mycompany/design-templates/marketing/hero-banner
+
+# Result: Installs to dsgn/templates/hero-banner/
+```
+
+### Example 2: Local Development
+
+```bash
+# Create template locally
+mkdir -p my-template
+cd my-template
+
+# Create files...
+# (banner.tsx, meta.json, etc.)
+
+# Install from local
+cd ../my-project
+dsgn add ../my-template
+
+# Test it
+dsgn render banner --props props.json
+```
+
+### Example 3: Direct URL
+
+```bash
+# Install from CDN
+dsgn add https://cdn.mycompany.com/templates/v2/social-card.json
+
+# Install from gist (if formatted correctly)
+dsgn add https://gist.githubusercontent.com/user/id/raw/template.json
+```
+
+### Example 4: Custom Registry
+
+```bash
+# Team's private registry
+dsgn add product-card --registry https://templates.mycompany.com/api
+
+# Alternative registry
+dsgn add banner --registry https://awesome-templates.dev/registry
+```
+
+## Creating Shareable Templates
+
+### For GitHub
+
+1. Create a repo with your templates:
+
+```
+my-templates/
+├── README.md
+└── templates/
+    ├── banner-hero/
+    │   ├── template.json
+    │   ├── banner-hero.tsx
+    │   └── meta.json
+    └── product-card/
+        ├── template.json
+        ├── product-card.tsx
+        └── meta.json
+```
+
+2. Share installation command:
+
+```bash
+dsgn add github:username/my-templates/templates/banner-hero
+```
+
+### For Direct URL
+
+1. Host template JSON on a CDN or static site
+2. Ensure CORS headers allow access
+3. Share the URL:
+
+```bash
+dsgn add https://my-cdn.com/templates/banner.json
+```
+
+### For Local Sharing (Teams)
+
+1. Create templates in shared monorepo:
+
+```
+company-monorepo/
+├── apps/
+├── packages/
+└── design-templates/
+    ├── banner/
+    ├── card/
+    └── hero/
+```
+
+2. Team members install with relative paths:
+
+```bash
+dsgn add ../../design-templates/banner
+```
+
+## Security Considerations
+
+### URLs
+- Only download from trusted sources
+- Review template code before using
+- URLs should use HTTPS
+
+### GitHub
+- Templates from public repos only
+- Review repository before installing
+- Check template contents
+
+### Local
+- Most secure option
+- Full control over template code
+- Good for development/testing
+
+## Troubleshooting
+
+### "Failed to fetch template"
+
+**Registry:**
+- Check template name spelling
+- Verify registry is accessible
+- Try custom registry with `--registry`
+
+**URL:**
+- Ensure URL is publicly accessible
+- Check URL returns valid JSON
+- Verify CORS headers
+
+**GitHub:**
+- Check repo and path exist
+- Ensure `template.json` exists
+- Verify repo is public
+- Branch must be `main`
+
+**Local:**
+- Check path is correct
+- Ensure `meta.json` or `template.json` exists
+- Verify file permissions
+
+### "Template already installed"
+
+Delete existing template and reinstall:
+
+```bash
+rm -rf dsgn/templates/banner-hero
+dsgn add github:user/repo/banner-hero
+```
+
+## Advanced: Publishing Your Own Registry
+
+Create a registry server that responds to:
+
+```
+GET /your-template
+```
+
+Returns:
+
+```json
+{
+  "name": "your-template",
+  "version": "1.0.0",
+  "description": "...",
+  "files": [...]
+}
+```
+
+Users can install with:
+
+```bash
+dsgn add your-template --registry https://your-registry.com
+```
+
+See `ROADMAP.md` for future registry features (versioning, search, marketplace).
+
+---
+
+**Pro tip:** Start with local development, then move to GitHub for sharing, and eventually publish to the official registry!

package/_dsgn/templates/banner-hero/banner-hero.tsx

@@ -0,0 +1,57 @@
+
+export const meta = {
+  name: "banner-hero",
+  description: "A hero banner with shadcn design system",
+  type: "image",
+  size: {
+    width: 1600,
+    height: 900
+  },
+  props: {
+    title: "string",
+    subtitle: "string?",
+    image: "string?"
+  }
+};
+
+interface BannerHeroProps {
+  title: string;
+  subtitle?: string;
+  image?: string;
+  config?: any;
+  tw?: (classes: string) => any;
+}
+
+export default function BannerHero({
+  title,
+  subtitle,
+  image,
+  config,
+  tw = (classes: string) => ({})
+}: BannerHeroProps) {
+  return (
+    <div style={tw('w-full h-full flex flex-col justify-center p-20 bg-background')}>
+      <div style={tw('bg-card rounded-xl p-16 border flex flex-col')}>
+        <h1 style={tw('text-8xl font-bold mb-5 text-foreground')}>
+          {title}
+        </h1>
+
+        {subtitle && (
+          <p style={tw('text-4xl text-muted-foreground')}>
+            {subtitle}
+          </p>
+        )}
+
+        {image && (
+          <img
+            src={image}
+            style={{
+              ...tw('rounded-lg mt-10'),
+              width: '192px',
+            }}
+          />
+        )}
+      </div>
+    </div>
+  );
+}

package/_dsgn/templates/banner-hero/meta.json

@@ -0,0 +1,14 @@
+{
+  "name": "banner-hero",
+  "description": "A hero banner with shadcn design system",
+  "type": "image",
+  "size": {
+    "width": 1600,
+    "height": 900
+  },
+  "props": {
+    "title": "string",
+    "subtitle": "string?",
+    "image": "string?"
+  }
+}

package/_dsgn/templates/composite-card/meta.json

@@ -0,0 +1,16 @@
+{
+  "name": "composite-card",
+  "description": "Card that embeds other templates",
+  "type": "image",
+  "size": {
+    "width": 1200,
+    "height": 800
+  },
+  "props": {
+    "title": "string",
+    "subtitle": "string?",
+    "qrUrl": "string?",
+    "bannerTitle": "string?",
+    "bannerSubtitle": "string?"
+  }
+}

package/_dsgn/templates/composite-card/template.tsx

@@ -0,0 +1,44 @@
+
+// Template metadata is defined in meta.json
+
+export default function Template({ title, subtitle, qrUrl, bannerTitle, bannerSubtitle, template, qr, tw }) {
+  return (
+    <div style={tw('w-full h-full flex flex-col bg-gradient-to-br from-slate-900 to-slate-800 p-12')}>
+      {/* Main Content */}
+      <div style={tw('bg-white rounded-3xl p-10 flex flex-col shadow-2xl')}>
+        {/* Title */}
+        <h1 style={tw('text-5xl font-bold text-gray-900 mb-3')}>
+          {title}
+        </h1>
+
+        {subtitle && (
+          <p style={tw('text-2xl text-gray-600 mb-8')}>
+            {subtitle}
+          </p>
+        )}
+
+        {/* Embedded Template - pass props directly, uses template's own meta.json for size */}
+        <div style={tw('mb-8 rounded-xl overflow-hidden flex')}>
+          {template('image', { title: bannerTitle, subtitle: bannerSubtitle })}
+        </div>
+
+        {/* QR Code if URL provided */}
+        {qrUrl && (
+          <div style={tw('flex items-center gap-6')}>
+            <div style={tw('bg-gray-100 p-4 rounded-xl flex')}>
+              <img
+                src={qr(qrUrl)}
+                width={120}
+                height={120}
+                alt="QR Code"
+              />
+            </div>
+            <p style={tw('text-lg text-gray-700 font-mono flex-1')}>
+              {qrUrl}
+            </p>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}