loopwind 0.17.0 → 0.18.0

package/test-sdk-user-templates.mjs

@@ -0,0 +1,469 @@
+/**
+ * Test suite for user-generated templates
+ * - defineTemplateFromSource (code editor)
+ * - defineTemplateFromSchema (visual builder)
+ */
+
+import { defineTemplateFromSource, defineTemplateFromSchema, renderImage, renderVideo } from './dist/sdk/index.js';
+import React from 'react';
+import fs from 'fs/promises';
+
+const h = React.createElement;
+let passed = 0;
+let failed = 0;
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`✓ ${name}`);
+    passed++;
+  } catch (error) {
+    console.error(`✗ ${name}`);
+    console.error(`  ${error.message}`);
+    failed++;
+  }
+}
+
+async function asyncTest(name, fn) {
+  try {
+    await fn();
+    console.log(`✓ ${name}`);
+    passed++;
+  } catch (error) {
+    console.error(`✗ ${name}`);
+    console.error(`  ${error.message}`);
+    failed++;
+  }
+}
+
+console.log('Testing defineTemplateFromSource\n');
+
+// Test 1: Basic source template
+await asyncTest('Source: Basic image template', async () => {
+  const source = `
+export const meta = {
+  name: 'test',
+  type: 'image',
+  size: { width: 100, height: 100 }
+};
+
+export default ({ tw }) => {
+  const h = React.createElement;
+  return h('div', { style: tw('bg-blue-500 w-full h-full') });
+};
+  `;
+
+  const template = defineTemplateFromSource(source);
+  if (template.name !== 'test') throw new Error('Template name incorrect');
+  if (template.type !== 'image') throw new Error('Template type incorrect');
+
+  const png = await renderImage(template, {});
+  if (!Buffer.isBuffer(png)) throw new Error('Should return buffer');
+});
+
+// Test 2: Source template with props
+await asyncTest('Source: Template with props', async () => {
+  const source = `
+export const meta = {
+  name: 'with-props',
+  type: 'image',
+  size: { width: 200, height: 100 }
+};
+
+export default ({ tw, title }) => {
+  const h = React.createElement;
+  return h('div', { style: tw('flex flex-col bg-white p-4') },
+    h('h1', { style: tw('text-black') }, title)
+  );
+};
+  `;
+
+  const template = defineTemplateFromSource(source);
+  const png = await renderImage(template, { title: 'Hello' });
+  if (!Buffer.isBuffer(png)) throw new Error('Should return buffer');
+});
+
+// Test 3: Source template with config
+await asyncTest('Source: Template with config', async () => {
+  const source = `
+export const meta = {
+  name: 'with-config',
+  type: 'image',
+  size: { width: 200, height: 100 }
+};
+
+export default ({ tw }) => {
+  const h = React.createElement;
+  return h('div', { style: tw('bg-primary p-4') });
+};
+  `;
+
+  const template = defineTemplateFromSource(source, {
+    config: {
+      colors: { primary: '#ff0000' },
+    },
+  });
+
+  const svg = await renderImage(template, {}, { format: 'svg' });
+  const svgStr = svg.toString();
+  if (!svgStr.includes('#ff0000')) throw new Error('Config colors not applied');
+});
+
+// Test 4: Source video template
+await asyncTest('Source: Video template', async () => {
+  const source = `
+export const meta = {
+  name: 'video-test',
+  type: 'video',
+  size: { width: 100, height: 100 },
+  video: { fps: 2, duration: 0.5 }
+};
+
+export default ({ tw }) => {
+  const h = React.createElement;
+  return h('div', {
+    style: tw('bg-blue-500 w-full h-full enter-fade-in/0/500')
+  });
+};
+  `;
+
+  const template = defineTemplateFromSource(source);
+  if (template.type !== 'video') throw new Error('Should be video type');
+
+  const mp4 = await renderVideo(template, {});
+  if (!Buffer.isBuffer(mp4)) throw new Error('Should return buffer');
+  if (mp4.length === 0) throw new Error('Video should have content');
+});
+
+// Test 5: Invalid source - no meta
+test('Source: Error on missing meta', () => {
+  const source = `
+export default () => {
+  return React.createElement('div', {}, 'test');
+};
+  `;
+
+  try {
+    defineTemplateFromSource(source);
+    throw new Error('Should have thrown error');
+  } catch (error) {
+    if (!error.message.includes('meta')) throw new Error('Should mention meta');
+  }
+});
+
+// Test 6: Invalid source - no default export
+test('Source: Error on missing default export', () => {
+  const source = `
+export const meta = {
+  name: 'test',
+  size: { width: 100, height: 100 }
+};
+  `;
+
+  try {
+    defineTemplateFromSource(source);
+    throw new Error('Should have thrown error');
+  } catch (error) {
+    if (!error.message.includes('default')) throw new Error('Should mention default export');
+  }
+});
+
+console.log('\nTesting defineTemplateFromSchema\n');
+
+// Test 7: Basic schema template
+await asyncTest('Schema: Basic template', async () => {
+  const schema = {
+    name: 'basic-schema',
+    size: { width: 200, height: 100 },
+    elements: [
+      {
+        type: 'div',
+        className: 'bg-blue-500 w-full h-full',
+      },
+    ],
+  };
+
+  const template = defineTemplateFromSchema(schema);
+  if (template.name !== 'basic-schema') throw new Error('Name incorrect');
+
+  const png = await renderImage(template, {});
+  if (!Buffer.isBuffer(png)) throw new Error('Should return buffer');
+});
+
+// Test 8: Schema with text interpolation
+await asyncTest('Schema: Text interpolation', async () => {
+  const schema = {
+    name: 'with-text',
+    size: { width: 300, height: 150 },
+    elements: [
+      {
+        type: 'div',
+        className: 'flex flex-col bg-white p-4 w-full h-full',
+        children: [
+          {
+            type: 'h1',
+            className: 'text-black',
+            content: '{{title}}',
+          },
+        ],
+      },
+    ],
+  };
+
+  const template = defineTemplateFromSchema(schema);
+  const svg = await renderImage(template, { title: 'Test Title' }, { format: 'svg' });
+  // SVG renders text as paths, so we can't check for literal strings
+  // Just verify it renders without error and has content
+  if (!Buffer.isBuffer(svg)) throw new Error('Should return buffer');
+  if (svg.length === 0) throw new Error('Should have content');
+});
+
+// Test 9: Schema with nested children
+await asyncTest('Schema: Nested elements', async () => {
+  const schema = {
+    name: 'nested',
+    size: { width: 400, height: 200 },
+    elements: [
+      {
+        type: 'div',
+        className: 'flex flex-col w-full h-full bg-white p-4',
+        children: [
+          {
+            type: 'h1',
+            className: 'text-2xl font-bold',
+            content: '{{title}}',
+          },
+          {
+            type: 'p',
+            className: 'text-base',
+            content: '{{description}}',
+          },
+        ],
+      },
+    ],
+  };
+
+  const template = defineTemplateFromSchema(schema);
+  const svg = await renderImage(
+    template,
+    { title: 'Nested', description: 'Works!' },
+    { format: 'svg' }
+  );
+  // SVG renders text as paths, just verify it has content
+  if (!Buffer.isBuffer(svg)) throw new Error('Should return buffer');
+  if (svg.length === 0) throw new Error('Should have content');
+});
+
+// Test 10: Schema with config
+await asyncTest('Schema: With config', async () => {
+  const schema = {
+    name: 'with-config',
+    size: { width: 200, height: 100 },
+    config: {
+      colors: {
+        primary: '#00ff00',
+        background: '#ffffff',
+      },
+    },
+    elements: [
+      {
+        type: 'div',
+        className: 'bg-primary w-full h-full',
+      },
+    ],
+  };
+
+  const template = defineTemplateFromSchema(schema);
+  const svg = await renderImage(template, {}, { format: 'svg' });
+  const svgStr = svg.toString();
+  if (!svgStr.includes('#00ff00')) throw new Error('Primary color not applied');
+});
+
+// Test 11: Schema with multiple root elements
+await asyncTest('Schema: Multiple root elements', async () => {
+  const schema = {
+    name: 'multi-root',
+    size: { width: 400, height: 200 },
+    elements: [
+      {
+        type: 'div',
+        className: 'flex w-full h-full bg-white',
+        children: [
+          {
+            type: 'div',
+            className: 'flex-1 bg-red-500',
+            content: 'First',
+          },
+          {
+            type: 'div',
+            className: 'flex-1 bg-blue-500',
+            content: 'Second',
+          },
+        ],
+      },
+    ],
+  };
+
+  const template = defineTemplateFromSchema(schema);
+  const svg = await renderImage(template, {}, { format: 'svg' });
+  // SVG renders text as paths, just verify it has content
+  if (!Buffer.isBuffer(svg)) throw new Error('Should return buffer');
+  if (svg.length === 0) throw new Error('Should have content');
+});
+
+// Test 12: Schema video template
+await asyncTest('Schema: Video template', async () => {
+  const schema = {
+    name: 'video-schema',
+    type: 'video',
+    size: { width: 100, height: 100 },
+    video: { fps: 2, duration: 0.5 },
+    elements: [
+      {
+        type: 'div',
+        className: 'bg-purple-500 w-full h-full',
+      },
+    ],
+  };
+
+  const template = defineTemplateFromSchema(schema);
+  if (template.type !== 'video') throw new Error('Should be video type');
+
+  const mp4 = await renderVideo(template, {});
+  if (!Buffer.isBuffer(mp4)) throw new Error('Should return buffer');
+  if (mp4.length === 0) throw new Error('Video should have content');
+});
+
+// Test 13: Schema with img element
+await asyncTest('Schema: Image element with interpolation', async () => {
+  const schema = {
+    name: 'with-image',
+    size: { width: 400, height: 200 },
+    elements: [
+      {
+        type: 'div',
+        className: 'bg-white w-full h-full flex items-center justify-center',
+        children: [
+          {
+            type: 'img',
+            src: '{{imageUrl}}',
+            style: { width: '128px', height: '128px' },
+          },
+        ],
+      },
+    ],
+  };
+
+  const template = defineTemplateFromSchema(schema);
+  // Use a minimal valid 1x1 red PNG
+  const redPixel = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==';
+  const svg = await renderImage(
+    template,
+    { imageUrl: redPixel },
+    { format: 'svg' }
+  );
+  const svgStr = svg.toString();
+  if (!svgStr.includes('data:image/png')) throw new Error('Image src not interpolated');
+});
+
+// Test 14: Schema error - empty elements
+test('Schema: Error on empty elements', () => {
+  const schema = {
+    name: 'empty',
+    size: { width: 100, height: 100 },
+    elements: [],
+  };
+
+  try {
+    const template = defineTemplateFromSchema(schema);
+    // Try to render - should fail
+    renderImage(template, {});
+    throw new Error('Should have thrown error');
+  } catch (error) {
+    if (!error.message.includes('element')) throw new Error('Should mention elements');
+  }
+});
+
+// Test 15: Complex real-world schema
+await asyncTest('Schema: Complex real-world example', async () => {
+  const schema = {
+    name: 'og-card',
+    size: { width: 1200, height: 630 },
+    config: {
+      colors: {
+        primary: '#3b82f6',
+        secondary: '#8b5cf6',
+        background: '#ffffff',
+        text: '#1f2937',
+      },
+    },
+    elements: [
+      {
+        type: 'div',
+        className: 'flex w-full h-full bg-background',
+        children: [
+          {
+            type: 'div',
+            className: 'flex flex-col w-1/3 bg-primary p-8 justify-between',
+            children: [
+              {
+                type: 'h2',
+                className: 'text-2xl font-bold text-white',
+                content: '{{category}}',
+              },
+              {
+                type: 'p',
+                className: 'text-white/80',
+                content: '{{date}}',
+              },
+            ],
+          },
+          {
+            type: 'div',
+            className: 'flex flex-col flex-1 p-12 justify-center',
+            children: [
+              {
+                type: 'h1',
+                className: 'text-6xl font-bold text-text mb-4',
+                content: '{{title}}',
+              },
+              {
+                type: 'div',
+                className: 'w-24 h-2 bg-secondary mb-4',
+              },
+              {
+                type: 'p',
+                className: 'text-2xl text-text/70',
+                content: '{{description}}',
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  };
+
+  const template = defineTemplateFromSchema(schema);
+  const png = await renderImage(template, {
+    category: 'TECHNOLOGY',
+    date: 'March 2024',
+    title: 'The Future of AI',
+    description: 'Exploring next-generation artificial intelligence',
+  });
+
+  if (!Buffer.isBuffer(png)) throw new Error('Should return buffer');
+  if (png.length === 0) throw new Error('Image should have content');
+
+  // Save for visual inspection
+  await fs.writeFile('test-complex-schema.png', png);
+});
+
+// Summary
+console.log('\n' + '='.repeat(50));
+console.log(`Tests passed: ${passed}`);
+console.log(`Tests failed: ${failed}`);
+console.log('='.repeat(50));
+
+if (failed > 0) {
+  process.exit(1);
+}

package/website/.astro/integrations/_inox-tools_astro-when/types.d.ts

@@ -0,0 +1 @@
+import '@inox-tools/astro-when';

package/website/.astro/types.d.ts

@@ -1 +1,2 @@
 /// <reference types="astro/client" />
+/// <reference path="integrations/_inox-tools_astro-when/types.d.ts" />

package/website/DEPLOYMENT.md

@@ -0,0 +1,142 @@
+# Deployment Guide
+
+This documentation website is configured for deployment on **Cloudflare Pages/Workers** with hybrid rendering.
+
+## Quick Deploy
+
+```bash
+cd website
+
+# Install dependencies
+npm install
+
+# Build and deploy
+npm run deploy
+```
+
+## What's Included
+
+### 1. Dynamic OG Image Generation
+
+Every documentation page automatically generates its own Open Graph image using **loopwind SDK**.
+
+- **API Route**: `/api/og/[...slug].tsx`
+- **Format**: 1200x630 PNG
+- **Generation**: Pre-rendered at build time for known pages, generated on-demand for others
+- **Caching**: Immutable cache headers for optimal performance
+
+**Example URLs:**
+- `/api/og/sdk` → SDK page OG image
+- `/api/og/config` → Config page OG image
+- `/api/og/getting-started` → Getting Started OG image
+
+### 2. Cloudflare Workers Adapter
+
+- **File**: `astro.config.mjs`
+- **Adapter**: `@astrojs/cloudflare`
+- **Output**: Hybrid (SSG + SSR)
+- **Platform**: Cloudflare Workers with Assets
+
+### 3. Build Configuration
+
+The Vite config externalizes Node.js built-ins for Cloudflare compatibility:
+
+```javascript
+vite: {
+  ssr: {
+    external: ['node:fs', 'fs', 'path', etc.],
+    noExternal: ['loopwind'], // Bundle loopwind SDK
+  },
+}
+```
+
+## Deployment Steps
+
+### First Time Setup
+
+1. **Install Wrangler CLI** (if not already installed):
+   ```bash
+   npm install -g wrangler
+   ```
+
+2. **Login to Cloudflare**:
+   ```bash
+   npx wrangler login
+   ```
+
+3. **Build and Deploy**:
+   ```bash
+   npm run deploy
+   ```
+
+### Subsequent Deployments
+
+Just run:
+
+```bash
+npm run deploy
+```
+
+Or separately:
+
+```bash
+npm run build
+npm run cf:deploy
+```
+
+## Environment
+
+- **Node.js**: 18+ recommended
+- **Package Manager**: npm
+- **Platform**: Cloudflare Workers + Assets
+- **Build Time**: ~2-3 seconds
+
+## Performance
+
+- **Build**: ~2.7s
+- **OG Images**: Generated at build time (< 100ms each)
+- **Caching**: Immutable cache headers for all OG images
+- **CDN**: Cloudflare's global network
+
+## Verify Deployment
+
+After deployment, test:
+
+1. **Home page**: `https://your-domain.com`
+2. **OG image**: `https://your-domain.com/api/og/sdk`
+3. **API routes**: All `/api/*` routes should work
+
+## Troubleshooting
+
+### Build Fails
+
+- Check Node.js version (18+)
+- Run `npm install` to ensure dependencies are up to date
+- Check `npm run build` output for errors
+
+### OG Images Not Generating
+
+- Verify loopwind is installed: `npm list loopwind`
+- Check `/api/og/[...slug].tsx` is present
+- Test locally: `npm run dev` then visit `http://localhost:4321/api/og/sdk`
+
+### Cloudflare Deploy Fails
+
+- Ensure you're logged in: `npx wrangler whoami`
+- Check `wrangler.toml` configuration (should not exist for Pages)
+- Verify Cloudflare account has Pages enabled
+
+## Local Development
+
+```bash
+npm run dev
+# Visit: http://localhost:4321
+# Test OG: http://localhost:4321/api/og/sdk
+```
+
+## Documentation
+
+- [loopwind SDK Docs](/sdk)
+- [OG Images Setup](./OG_IMAGES.md)
+- [Cloudflare Astro Guide](https://developers.cloudflare.com/workers/framework-guides/web-apps/astro/)
+