rad-coder 1.0.0

package/README.md

@@ -0,0 +1,253 @@
+# rad-coder
+
+A development environment for testing ResponsiveAds creative custom JavaScript with hot-reload.
+
+## Quick Start
+
+```bash
+npx rad-coder <creativeId>
+```
+
+Or with a full preview URL:
+
+```bash
+npx rad-coder https://studio.responsiveads.com/creatives/697b80fcc6e904025f5147a0/preview
+```
+
+## What It Does
+
+1. **Creates files** in your current directory:
+   - `custom.js` - Your custom JavaScript code
+   - `AGENTS.md` - Instructions for AI coding assistants (Copilot, Claude, etc.)
+
+2. **Fetches creative config** from ResponsiveAds Studio automatically
+
+3. **Starts a dev server** at `http://localhost:3000`
+
+4. **Opens your browser** with the test page showing your creative
+
+5. **Hot-reload** - Edit `custom.js`, save, and the browser automatically reloads
+
+## Usage
+
+### Basic Usage
+
+```bash
+# Create a new directory for your project
+mkdir my-creative
+cd my-creative
+
+# Start rad-coder with your creative ID
+npx rad-coder 697b80fcc6e904025f5147a0
+```
+
+### With AI Assistants
+
+The generated `AGENTS.md` file contains instructions for AI coding assistants. When using VS Code with Copilot or other AI tools, they can read this file to understand:
+
+- How to use the Radical API
+- Available lifecycle hooks (`onBeforeRender`, `onLoad`, `onRender`)
+- Component methods (Carousel, TextBox, etc.)
+- Best practices for ResponsiveAds creatives
+
+### Workflow
+
+1. Run `npx rad-coder <creativeId>`
+2. Edit `custom.js` in your favorite editor
+3. Save the file - browser auto-reloads
+4. See your changes applied to the creative instantly
+
+## Features
+
+- **Zero configuration** - Just provide a creative ID
+- **Auto-detection** - Extracts flowline, sizes, and settings from Studio
+- **Hot-reload** - Instant feedback when you save changes
+- **AI-ready** - Includes documentation for AI coding assistants
+- **Cross-platform** - Works on macOS, Linux, and Windows
+
+## Requirements
+
+- Node.js 18.0.0 or higher
+
+## How It Works
+
+rad-coder fetches your creative's configuration from the ResponsiveAds Studio preview page, extracts the flowline settings, and creates a local development environment. Your custom JavaScript is injected into the creative via the `customjs` config property.
+
+The server watches your `custom.js` file for changes and uses WebSocket to signal the browser to reload when you save.
+
+## API Reference
+
+See the generated `AGENTS.md` file for complete Radical API documentation, including:
+
+- Lifecycle hooks
+- Element manipulation
+- Carousel and TextBox components
+- Dynamic Content Optimization (DCO)
+- Analytics tracking
+
+## Development
+
+Instructions for developers who want to modify rad-coder itself.
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/nicatronTg/rad-coder.git
+cd rad-coder
+
+# Install dependencies
+npm install
+
+# Link the package globally for local testing
+npm link
+```
+
+### Testing Your Changes
+
+After making changes, test locally:
+
+```bash
+# Create a test directory
+mkdir /tmp/test-rad-coder
+cd /tmp/test-rad-coder
+
+# Run rad-coder (uses your linked local version)
+rad-coder 697b80fcc6e904025f5147a0
+
+# Or run directly without linking
+node /path/to/rad-coder/bin/cli.js 697b80fcc6e904025f5147a0
+```
+
+### Debug Mode
+
+Run the tool with Node.js debugger for step-through debugging:
+
+```bash
+# From the rad-coder repository directory:
+
+# Start with debugger (attach Chrome DevTools or VS Code)
+npm run debug -- 697b80fcc6e904025f5147a0
+
+# Start with debugger and break on first line
+npm run debug-brk -- 697b80fcc6e904025f5147a0
+
+# Or run directly with node inspect flags
+node --inspect bin/cli.js 697b80fcc6e904025f5147a0
+node --inspect-brk bin/cli.js 697b80fcc6e904025f5147a0
+```
+
+**Connecting to the debugger:**
+
+1. **Chrome DevTools**: Open `chrome://inspect` in Chrome, click "inspect" under Remote Target
+2. **VS Code**: Use the "Attach to Node Process" debug configuration, or add this to `.vscode/launch.json`:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Debug rad-coder",
+      "program": "${workspaceFolder}/bin/cli.js",
+      "args": ["697b80fcc6e904025f5147a0"],
+      "cwd": "/tmp/test-rad-coder"
+    }
+  ]
+}
+```
+
+**Available npm scripts:**
+
+| Script | Description |
+|--------|-------------|
+| `npm run dev -- <creativeId>` | Run via CLI (copies templates to cwd) |
+| `npm run server -- <creativeId>` | Run server directly (uses repo's templates dir for custom.js) |
+| `npm run debug -- <creativeId>` | Run CLI with debugger attached |
+| `npm run debug-brk -- <creativeId>` | Run CLI with debugger, break on first line |
+| `npm run debug:server -- <creativeId>` | Run server directly with debugger attached |
+
+**Difference between `dev` and `server`:**
+
+- `npm run dev` - Runs `bin/cli.js` which copies template files to user's directory, then starts the server. Use this to test the full npx experience.
+- `npm run server` - Runs `server/index.js` directly, using the `templates/` directory for `custom.js`. Use this when developing the server itself without needing to copy files.
+
+### Project Structure
+
+```
+rad-coder/
+├── bin/
+│   └── cli.js          # CLI entry point - handles file copying and starts server
+├── server/
+│   └── index.js        # Express server - fetches config, serves files, hot-reload
+├── public/
+│   └── test.html       # Test page - loads creative with custom JS
+├── templates/
+│   ├── custom.js       # Template copied to user's directory
+│   └── AGENTS.md       # AI agent instructions copied to user's directory
+└── package.json
+```
+
+### Key Files
+
+| File | Purpose |
+|------|---------|
+| `bin/cli.js` | Entry point when user runs `npx rad-coder`. Copies template files to user's directory and starts the server. |
+| `server/index.js` | Express server that fetches creative config from Studio, serves the test page, and handles hot-reload via WebSocket. |
+| `public/test.html` | The test page that loads the creative and injects custom JS via the Radical config. |
+| `templates/custom.js` | Template for the user's custom JS file. |
+| `templates/AGENTS.md` | Documentation for AI coding assistants. |
+
+### Modifying Creative Rendering
+
+The creative is rendered in `public/test.html`. Key areas:
+
+1. **Fetching config**: The page fetches `/api/config` which returns creative settings from Studio.
+
+2. **Loading custom JS**: The page fetches `/api/custom-js` which returns the user's `custom.js` content.
+
+3. **Radical config**: The creative is initialized with:
+   ```javascript
+   Radical.push([creativeId, {
+     flowline: config.flowlineId,
+     sizes: config.sizes,
+     isFluid: config.isFluid,
+     // ... other settings
+     config: { 
+       _default: { 
+         customjs: customJsCode  // User's custom JS injected here
+       } 
+     }
+   }]);
+   ```
+
+### Modifying Config Extraction
+
+Creative config is fetched from Studio in `server/index.js` in the `fetchCreativeConfig()` function. This parses the preview page HTML to extract:
+
+- `window.creativeId`
+- `window.flowlines` (array of flowline objects)
+
+The first flowline is selected by default. To change this behavior, modify the logic around line 150 in `server/index.js`.
+
+### Environment Variables
+
+When run via `npx`, the CLI sets these environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `RAD_CODER_USER_DIR` | User's current working directory (where `custom.js` lives) |
+| `RAD_CODER_PACKAGE_DIR` | Package installation directory (where `public/` lives) |
+
+### Unlinking
+
+When done testing, unlink the package:
+
+```bash
+npm unlink -g rad-coder
+```
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const fs = require('fs');
+
+// Get the package root directory
+const packageRoot = path.join(__dirname, '..');
+
+// Get user's current working directory
+const userDir = process.cwd();
+
+// Files to copy to user's directory on first run
+const filesToCopy = [
+  { template: 'custom.js', target: 'custom.js' },
+  { template: 'AGENTS.md', target: 'AGENTS.md' }
+];
+
+// Copy template files if they don't exist
+let filesCreated = false;
+filesToCopy.forEach(({ template, target }) => {
+  const targetPath = path.join(userDir, target);
+  if (!fs.existsSync(targetPath)) {
+    const templatePath = path.join(packageRoot, 'templates', template);
+    if (fs.existsSync(templatePath)) {
+      fs.copyFileSync(templatePath, targetPath);
+      console.log(` Created ${target}`);
+      filesCreated = true;
+    }
+  }
+});
+
+if (filesCreated) {
+  console.log('');
+}
+
+// Set environment variables for the server
+process.env.RAD_CODER_USER_DIR = userDir;
+process.env.RAD_CODER_PACKAGE_DIR = packageRoot;
+
+// Run the server
+require('../server/index.js');

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "rad-coder",
+  "version": "1.0.0",
+  "description": "Development environment for testing ResponsiveAds creative custom JS with hot-reload",
+  "bin": {
+    "rad-coder": "./bin/cli.js"
+  },
+  "scripts": {
+    "dev": "node bin/cli.js",
+    "server": "node server/index.js"
+  },
+  "files": [
+    "bin/",
+    "server/",
+    "public/",
+    "templates/"
+  ],
+  "keywords": [
+    "responsiveads",
+    "rad",
+    "ad",
+    "creative",
+    "testing",
+    "custom-js",
+    "hot-reload"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ResponsiveAds/rad-coder"
+  },
+  "author": "ResponsiveAds",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "chokidar": "^3.5.3",
+    "cors": "^2.8.5",
+    "express": "^4.18.2",
+    "open": "^9.1.0",
+    "ws": "^8.14.2"
+  }
+}

package/public/test.html

@@ -0,0 +1,297 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Ad Creative Tester</title>
+  <style>
+    * {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+    
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      background: #1a1a2e;
+      min-height: 100vh;
+    }
+    
+    .toolbar {
+      background: #16213e;
+      padding: 12px 20px;
+      display: flex;
+      align-items: center;
+      gap: 20px;
+      border-bottom: 1px solid #0f3460;
+    }
+    
+    .toolbar h1 {
+      color: #e94560;
+      font-size: 16px;
+      font-weight: 600;
+    }
+    
+    .toolbar .status {
+      color: #4ecca3;
+      font-size: 12px;
+      display: flex;
+      align-items: center;
+      gap: 6px;
+    }
+    
+    .toolbar .status::before {
+      content: '';
+      width: 8px;
+      height: 8px;
+      background: #4ecca3;
+      border-radius: 50%;
+      animation: pulse 2s infinite;
+    }
+    
+    @keyframes pulse {
+      0%, 100% { opacity: 1; }
+      50% { opacity: 0.5; }
+    }
+    
+    .toolbar .creative-info {
+      display: flex;
+      flex-direction: column;
+      gap: 2px;
+    }
+    
+    .toolbar .creative-id {
+      color: #a0a0a0;
+      font-size: 12px;
+      font-family: monospace;
+    }
+    
+    .toolbar .flowline-name {
+      color: #7ec8e3;
+      font-size: 11px;
+    }
+    
+    .toolbar .reload-btn {
+      margin-left: auto;
+      background: #0f3460;
+      color: #fff;
+      border: none;
+      padding: 8px 16px;
+      border-radius: 4px;
+      cursor: pointer;
+      font-size: 12px;
+    }
+    
+    .toolbar .reload-btn:hover {
+      background: #e94560;
+    }
+    
+    .ad-container {
+      padding: 20px;
+      display: flex;
+      justify-content: center;
+      align-items: flex-start;
+    }
+    
+    .ad-wrapper {
+      background: #fff;
+      border-radius: 8px;
+      overflow: hidden;
+      box-shadow: 0 10px 40px rgba(0,0,0,0.3);
+    }
+    
+    .inner-content {
+      width: 100%;
+      min-height: 300px;
+    }
+    
+    /* Toast notification for reload */
+    .toast {
+      position: fixed;
+      bottom: 20px;
+      right: 20px;
+      background: #4ecca3;
+      color: #1a1a2e;
+      padding: 12px 20px;
+      border-radius: 6px;
+      font-size: 14px;
+      font-weight: 500;
+      transform: translateY(100px);
+      opacity: 0;
+      transition: all 0.3s ease;
+    }
+    
+    .toast.show {
+      transform: translateY(0);
+      opacity: 1;
+    }
+  </style>
+</head>
+<body>
+  <div class="toolbar">
+    <h1>Ad Creative Tester</h1>
+    <span class="status">Hot-reload active</span>
+    <div class="creative-info">
+      <span class="creative-id" id="creative-id">Loading...</span>
+      <span class="flowline-name" id="flowline-name"></span>
+    </div>
+    <button class="reload-btn" onclick="location.reload()">Reload</button>
+  </div>
+  
+  <div class="ad-container">
+    <div class="ad-wrapper">
+      <div class="inner-content" id="ad-content">
+        <!-- Ad will be loaded here -->
+      </div>
+    </div>
+  </div>
+  
+  <div class="toast" id="toast">Reloading...</div>
+
+  <script>
+    // Fetch config with retry (server may still be fetching from studio)
+    async function fetchConfigWithRetry(maxRetries = 10, delay = 500) {
+      for (let i = 0; i < maxRetries; i++) {
+        try {
+          const response = await fetch('/api/config');
+          if (response.status === 503) {
+            // Server not ready yet, retry
+            console.log(`Config not ready, retrying (${i + 1}/${maxRetries})...`);
+            await new Promise(r => setTimeout(r, delay));
+            continue;
+          }
+          if (!response.ok) {
+            throw new Error(`HTTP ${response.status}`);
+          }
+          return await response.json();
+        } catch (error) {
+          if (i === maxRetries - 1) throw error;
+          console.log(`Fetch failed, retrying (${i + 1}/${maxRetries})...`);
+          await new Promise(r => setTimeout(r, delay));
+        }
+      }
+      throw new Error('Max retries exceeded');
+    }
+    
+    // Fetch config and initialize ad
+    async function init() {
+      try {
+        // Show loading state
+        document.getElementById('creative-id').textContent = 'Loading...';
+        
+        const config = await fetchConfigWithRetry();
+        
+        // Update UI
+        document.getElementById('creative-id').textContent = `ID: ${config.creativeId}`;
+        document.getElementById('flowline-name').textContent = `Flowline: ${config.flowlineName}`;
+        
+        // Initialize Radical ad (async - fetches custom JS code)
+        await loadAd(config);
+        
+        // Setup hot-reload WebSocket
+        setupHotReload();
+        
+      } catch (error) {
+        console.error('Failed to load config:', error);
+        document.getElementById('ad-content').innerHTML = 
+          '<p style="padding: 20px; color: red;">Failed to load configuration</p>';
+      }
+    }
+    
+    async function loadAd(config) {
+      const container = document.getElementById('ad-content');
+      const id = config.creativeId;
+      
+      // Create the ad insertion point
+      const ins = document.createElement('ins');
+      ins.id = `responsivead-${id}`;
+      container.innerHTML = '';
+      container.appendChild(ins);
+      
+      // Initialize Radical
+      window.Radical = window.Radical || [];
+      
+      // Fetch the custom JS code from server
+      let customJsCode = '';
+      try {
+        const response = await fetch('/api/custom-js');
+        const data = await response.json();
+        customJsCode = data.code || '';
+        console.log('Custom JS code loaded:', customJsCode.substring(0, 100) + '...');
+      } catch (error) {
+        console.error('Failed to load custom JS:', error);
+      }
+      
+      // Push the ad configuration with customjs as inline code string
+      Radical.push([id, {
+        https: true,
+        flowline: config.flowlineId,
+        sizes: config.sizes,
+        adSource: config.adSource,
+        tracking: false,
+        isFluid: config.isFluid,
+        screenshot: false,
+        crossOrigin: true,
+        flSource: config.flSource,
+        config: { 
+          _default: { 
+            selectedVariant: '', 
+            customjs: customJsCode  // Inline JS code string (not URL)
+          } 
+        }
+      }]);
+      
+      // Load the Radical script if not already loaded
+      if (!document.querySelector('script[src*="radical.min.js"]')) {
+        const script = document.createElement('script');
+        script.src = config.radicalScript;
+        document.body.appendChild(script);
+      }
+      
+      console.log('Ad loaded with customjs code injected');
+    }
+    
+    function setupHotReload() {
+      const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
+      const ws = new WebSocket(`${wsProtocol}//${location.host}`);
+      
+      ws.onopen = () => {
+        console.log('Hot-reload connected');
+      };
+      
+      ws.onmessage = (event) => {
+        const data = JSON.parse(event.data);
+        if (data.type === 'reload') {
+          showToast('Reloading...');
+          // Small delay to show the toast
+          setTimeout(() => {
+            location.reload();
+          }, 300);
+        }
+      };
+      
+      ws.onclose = () => {
+        console.log('Hot-reload disconnected, reconnecting...');
+        // Try to reconnect after a delay
+        setTimeout(setupHotReload, 2000);
+      };
+      
+      ws.onerror = (error) => {
+        console.error('WebSocket error:', error);
+      };
+    }
+    
+    function showToast(message) {
+      const toast = document.getElementById('toast');
+      toast.textContent = message;
+      toast.classList.add('show');
+      setTimeout(() => {
+        toast.classList.remove('show');
+      }, 2000);
+    }
+    
+    // Initialize on page load
+    init();
+  </script>
+</body>
+</html>

package/server/index.js

@@ -0,0 +1,346 @@
+const express = require('express');
+const cors = require('cors');
+const { WebSocketServer } = require('ws');
+const chokidar = require('chokidar');
+const path = require('path');
+const fs = require('fs');
+const http = require('http');
+
+// ============================================================
+// Directory Configuration
+// ============================================================
+
+// When run via npx, these are set by bin/cli.js
+// When run directly for development, use defaults
+const userDir = process.env.RAD_CODER_USER_DIR || process.cwd();
+const packageDir = process.env.RAD_CODER_PACKAGE_DIR || path.join(__dirname, '..');
+
+// ============================================================
+// CLI Argument Parsing
+// ============================================================
+
+const input = process.argv[2];
+
+if (!input) {
+  console.error('\n Usage: npx rad-coder <creativeId or previewUrl>\n');
+  console.error(' Examples:');
+  console.error('   npx rad-coder 697b80fcc6e904025f5147a0');
+  console.error('   npx rad-coder https://studio.responsiveads.com/creatives/697b80fcc6e904025f5147a0/preview\n');
+  process.exit(1);
+}
+
+/**
+ * Extract creative ID from URL or use directly
+ */
+function extractCreativeId(input) {
+  // If it's a URL, extract the ID
+  const urlMatch = input.match(/creatives\/([a-f0-9]+)/i);
+  return urlMatch ? urlMatch[1] : input;
+}
+
+const creativeId = extractCreativeId(input);
+
+// ============================================================
+// Fetch Creative Config from Studio Preview Page
+// ============================================================
+
+let creativeConfig = null;
+
+/**
+ * Fetch and parse creative configuration from studio preview page
+ */
+async function fetchCreativeConfig(creativeId) {
+  const previewUrl = `https://studio.responsiveads.com/creatives/${creativeId}/preview`;
+  
+  console.log(` Fetching creative config from studio...`);
+  console.log(` URL: ${previewUrl}\n`);
+  
+  try {
+    const response = await fetch(previewUrl);
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+    
+    const html = await response.text();
+    
+    // Extract window.creativeId
+    const creativeIdMatch = html.match(/window\.creativeId\s*=\s*['"]([^'"]+)['"]/);
+    const extractedCreativeId = creativeIdMatch ? creativeIdMatch[1] : creativeId;
+    
+    // Extract flowlines - try multiple patterns
+    let flowlines;
+    
+    // First try: Look for flowlinesString variable (cleaner JSON)
+    const flowlinesStringMatch = html.match(/var\s+flowlinesString\s*=\s*\('(\[[\s\S]*?\])'\)/);
+    if (flowlinesStringMatch) {
+      try {
+        // The string has escaped single quotes, replace them
+        const jsonStr = flowlinesStringMatch[1].replace(/\\'/g, "'");
+        flowlines = JSON.parse(jsonStr);
+      } catch (parseErr) {
+        // Continue to next method
+      }
+    }
+    
+    // Second try: Look for window.flowlines = JSON.parse(flowlinesString)
+    // In this case, extract from the initial assignment
+    if (!flowlines) {
+      const flowlinesMatch = html.match(/window\.flowlines\s*=\s*(\[[\s\S]*?\]);[\s\n]/);
+      if (flowlinesMatch) {
+        try {
+          // Try to clean up escaped quotes
+          let jsonStr = flowlinesMatch[1];
+          jsonStr = jsonStr.replace(/\\'/g, "'");
+          flowlines = JSON.parse(jsonStr);
+        } catch (parseErr) {
+          // Continue to next method
+        }
+      }
+    }
+    
+    // Third try: Use a more robust extraction by finding balanced brackets
+    if (!flowlines) {
+      const startMarker = 'window.flowlines = [';
+      const startIdx = html.indexOf(startMarker);
+      if (startIdx !== -1) {
+        let bracketCount = 0;
+        let inString = false;
+        let escapeNext = false;
+        let endIdx = startIdx + startMarker.length - 1;
+        
+        for (let i = startIdx + startMarker.length - 1; i < html.length; i++) {
+          const char = html[i];
+          
+          if (escapeNext) {
+            escapeNext = false;
+            continue;
+          }
+          
+          if (char === '\\') {
+            escapeNext = true;
+            continue;
+          }
+          
+          if (char === '"' && !inString) {
+            inString = true;
+          } else if (char === '"' && inString) {
+            inString = false;
+          }
+          
+          if (!inString) {
+            if (char === '[') bracketCount++;
+            if (char === ']') bracketCount--;
+            
+            if (bracketCount === 0) {
+              endIdx = i + 1;
+              break;
+            }
+          }
+        }
+        
+        try {
+          let jsonStr = html.substring(startIdx + startMarker.length - 1, endIdx);
+          jsonStr = jsonStr.replace(/\\'/g, "'");
+          flowlines = JSON.parse(jsonStr);
+        } catch (parseErr) {
+          throw new Error(`Failed to parse flowlines JSON: ${parseErr.message}`);
+        }
+      }
+    }
+    
+    if (!flowlines) {
+      throw new Error('Could not find or parse window.flowlines in preview page');
+    }
+    
+    if (!flowlines || flowlines.length === 0) {
+      throw new Error('No flowlines found for this creative');
+    }
+    
+    // Select first flowline by default
+    const fl = flowlines[0];
+    
+    // Extract sizes from flowline.flowline.sizes or fluidLayouts
+    let sizes = [];
+    if (fl.flowline && fl.flowline.sizes) {
+      sizes = fl.flowline.sizes;
+    } else if (fl.fluidLayouts) {
+      sizes = fl.fluidLayouts.map(l => `${l.width}x${l.height}`);
+    }
+  
+    
+    return {
+      creativeId: extractedCreativeId,
+      flowlineId: fl._id || fl.id,
+      flowlineName: fl.name || 'Unknown',
+      sizes: sizes,
+      isFluid: fl.fullyFluid || false,
+      adSource: '//publish.responsiveads.com/ads/',
+      flSource: '//publish.responsiveads.com/flowlines/',
+      radicalScript: 'https://publish.responsiveads.com/libs/radical.r8.min.js',
+      server: {
+        port: 3000,
+        host: 'localhost'
+      },
+      // Store all flowlines for reference
+      allFlowlines: flowlines.map(f => ({
+        id: f._id || f.id,
+        name: f.name,
+        sizes: f.flowline?.sizes || [],
+        isFluid: f.fullyFluid
+      }))
+    };
+    
+  } catch (error) {
+    console.error(`\n Failed to fetch creative config: ${error.message}\n`);
+    process.exit(1);
+  }
+}
+
+// ============================================================
+// Express Server Setup
+// ============================================================
+
+const app = express();
+const server = http.createServer(app);
+
+// WebSocket server for hot-reload
+const wss = new WebSocketServer({ server });
+
+// Track connected clients
+const clients = new Set();
+
+wss.on('connection', (ws) => {
+  clients.add(ws);
+  console.log('Browser connected for hot-reload');
+  
+  ws.on('close', () => {
+    clients.delete(ws);
+    console.log('Browser disconnected');
+  });
+});
+
+// Broadcast reload message to all connected browsers
+function broadcastReload() {
+  const message = JSON.stringify({ type: 'reload' });
+  clients.forEach((client) => {
+    if (client.readyState === 1) { // WebSocket.OPEN
+      client.send(message);
+    }
+  });
+}
+
+// Enable CORS for all origins (needed for cross-origin script loading)
+app.use(cors());
+
+// Serve static files from public directory (in package)
+app.use(express.static(path.join(packageDir, 'public')));
+
+// Serve the custom JS code as a JSON response (for injection into Radical config)
+// Custom JS is in user's directory
+app.get('/api/custom-js', (req, res) => {
+  const customJsPath = path.join(userDir, 'custom.js');
+  
+  // Set headers to prevent caching
+  res.set({
+    'Cache-Control': 'no-store, no-cache, must-revalidate, proxy-revalidate',
+    'Pragma': 'no-cache',
+    'Expires': '0'
+  });
+  
+  if (fs.existsSync(customJsPath)) {
+    const code = fs.readFileSync(customJsPath, 'utf-8');
+    res.json({ code });
+  } else {
+    res.json({ code: '// custom.js not found - create custom.js in your current directory' });
+  }
+});
+
+// Serve dynamically fetched config as JSON for the test page
+app.get('/api/config', (req, res) => {
+  if (!creativeConfig) {
+    res.status(503).json({ error: 'Config not yet loaded' });
+    return;
+  }
+  res.json(creativeConfig);
+});
+
+// Watch for changes in custom.js (in user's directory)
+const customJsWatchPath = path.join(userDir, 'custom.js');
+const watcher = chokidar.watch(customJsWatchPath, {
+  persistent: true,
+  ignoreInitial: true
+});
+
+watcher.on('change', (filePath) => {
+  console.log(`\n File changed: ${path.basename(filePath)}`);
+  console.log(' Reloading browsers...\n');
+  broadcastReload();
+});
+
+watcher.on('error', (error) => {
+  console.error('Watcher error:', error);
+});
+
+// ============================================================
+// Start Server
+// ============================================================
+
+async function start() {
+  console.log('\n========================================');
+  console.log(' RAD Coder - ResponsiveAds Creative Tester');
+  console.log('========================================\n');
+  
+  // Fetch creative config from studio
+  creativeConfig = await fetchCreativeConfig(creativeId);
+  
+  console.log(' Creative Config:');
+  console.log(` - Creative ID: ${creativeConfig.creativeId}`);
+  console.log(` - Flowline: ${creativeConfig.flowlineName}`);
+  console.log(` - Flowline ID: ${creativeConfig.flowlineId}`);
+  console.log(` - Sizes: ${creativeConfig.sizes.join(', ')}`);
+  console.log(` - Is Fluid: ${creativeConfig.isFluid}`);
+  
+  if (creativeConfig.allFlowlines.length > 1) {
+    console.log(`\n Available Flowlines (${creativeConfig.allFlowlines.length}):`);
+    creativeConfig.allFlowlines.forEach((fl, i) => {
+      const marker = i === 0 ? ' (selected)' : '';
+      console.log(`   ${i + 1}. ${fl.name}${marker}`);
+    });
+  }
+  
+  const { port, host } = creativeConfig.server;
+  
+  server.listen(port, host, async () => {
+    console.log(`\n Server running at: http://${host}:${port}`);
+    console.log(` Test page: http://${host}:${port}/test.html`);
+    console.log(`\n Working directory: ${userDir}`);
+    console.log(' Edit custom.js and save to hot-reload\n');
+    console.log(' Press Ctrl+C to stop\n');
+    
+    // Small delay to ensure server is fully ready before opening browser
+    await new Promise(resolve => setTimeout(resolve, 500));
+    
+    // Auto-open browser
+    try {
+      const open = (await import('open')).default;
+      await open(`http://${host}:${port}/test.html`);
+      console.log(' Browser opened automatically\n');
+    } catch (err) {
+      console.log(' Could not auto-open browser:', err.message);
+      console.log(` Please open http://${host}:${port}/test.html manually\n`);
+    }
+  });
+}
+
+start();
+
+// Graceful shutdown
+process.on('SIGINT', () => {
+  console.log('\n Shutting down...');
+  watcher.close();
+  wss.close();
+  server.close(() => {
+    console.log(' Server stopped\n');
+    process.exit(0);
+  });
+});

package/templates/AGENTS.md

@@ -0,0 +1,372 @@
+# RAD Agents Guide
+
+You are an agent writing only JS for a responsive creative. The creative was build using responsiveAds editor. ResponsiveSds is online editor which helps designers build creatives, but they have an option to add some customJS. You are responsible for writing this customJS.
+
+To do this you can only edit the `custom.js` file in this directory. When you edit and save this file the creative will be automatically loaded on the test page: http://localhost:3000/test.html. The code you wrote in `custom.js` will be applied to the creative.
+
+Use modern JS standards and code practices.
+
+We can use custom in situations when we want to add extra interactivity to our responsive creative. Use the Radical API to access elements added from the editor, update their behavior, and add custom functionalities to your ad.
+
+You can use all available JavaScript functions to manipulate element position and size. This is usually done by changing the DOM element CSS `style` property. All elements in creative are positioned absolutely with inline styles set by our rendering script.
+
+---
+
+# Radical API Reference for ResponsiveAds
+
+This document outlines the specific implementation patterns and lifecycle hooks for the Radical API. Use this guide to programmatically control elements, manage dynamic data (DCO), and handle cross-window interactions in ResponsiveAds creatives.
+
+## 1. Initializing the Controller
+
+Every script must first reference the ad instance and its container.
+
+```javascript
+var rad = Radical.getAdByWindow(window);
+var container = rad.getContainer();
+```
+
+## 2. Core Lifecycle Hooks
+
+These hooks are critical for ensuring code executes in the correct order.
+
+### rad.onBeforeRender(arg)
+
+The Data Injection Layer. Runs after the config is loaded but before elements are created in the DOM.
+
+Use for: Swapping text, images, and click-through URLs (DCO).  
+Key Property: `arg.elementDefs` contains the blueprint for every element.
+
+```javascript
+rad.onBeforeRender(function(arg) {
+    // Dynamically update a textbox
+    arg.elementDefs.headlineID.textboxWidget.text = "Custom Value";
+    
+    // Update an image source
+    arg.elementDefs.heroImageID.image.src = "https://example.com/image.jpg";
+    
+    // Update a click-through URL
+    arg.elementDefs.ctaID.onClick[0].data.url = "https://landingpage.com";
+});
+```
+
+### rad.onLoad(callback)
+
+The Event Registration Layer. Runs once the ad flow is loaded.
+
+Use for: Adding DOM event listeners (click, touchstart, window events).  
+Benefit: Prevents duplicate listeners during ad resize/re-render.
+
+```javascript
+rad.onLoad(function() {
+    window.addEventListener('message', function(e) { 
+        console.log("External Data:", e.data); 
+    });
+});
+```
+
+### rad.onRender(callback)
+
+The Post-Layout Layer. Runs after elements are physically positioned.
+
+Use for: Initializing carousels, GSAP animations, or grabbing domNode references.  
+Note: Fires multiple times on browser resize.
+
+```javascript
+rad.onRender(function() {
+    var element = rad.getElementById('e1');
+    if (element) {
+        element.domNode.style.borderRadius = "10px";
+    }
+});
+```
+
+### container.onVisibilityChange(callback)
+
+The Performance & Policy Layer.
+
+Use for: Pausing video or audio when the ad scrolls out of view.
+
+```javascript
+container.onVisibilityChange(function(isVisible) {
+    if (!isVisible) {
+        // Stop all active media
+        pauseAllVideo();
+    }
+});
+```
+
+## 3. Component Interaction
+
+### Carousels
+
+Access carousel-specific methods via `rad.getElementById('ID')`.
+
+Method | Description
+--- | ---
+animateToSlide(index) | Smoothly transitions to a specific slide.
+getVisibleSlideIndex() | Returns current index (0-based).
+slideChangeCallback(fn) | Triggers a function when the slide changes.
+getSlides() | Returns an array of all slide objects.
+
+### Textbox
+
+To update text post-render, use the helper method to ensure layout recalculation:
+
+```javascript
+var txt = rad.getElementById('text1');
+txt.updateContent("New Text");
+// rad.updateElementStyles handles the necessary updateShrink() internally
+rad.updateElementStyles(txt.domNode, { opacity: 1 });
+```
+
+## 4. Advanced Patterns
+
+### Dynamic Content Optimization (DCO)
+
+Retrieve parameters passed via the Ad Tag URL or Query String:
+
+```javascript
+var options = rad.getAdTagOptions();
+var dealerId = options.dealer_id || "default_001";
+```
+
+### Analytics Tracking
+
+Trigger custom tracking events for reporting:
+
+```javascript
+rad.sendAnalyticsEvent({
+    e: 'interact.scroll', 
+    v: 50, // Value (e.g., 50% scrolled)
+    elId: 'scrolling_container'
+});
+```
+
+### Cross-Origin Detection
+
+Check if the ad can communicate with the top-level window (parent page):
+
+```javascript
+if (!container.isCrossOrigin()) {
+    var parentDoc = container.getAdWindow().top.document;
+    // Safe to interact with parent window
+}
+```
+
+## 5. Summary Checklist for AI Agents
+
+- DCO logic? Use `onBeforeRender` to modify `arg.elementDefs`.
+- Visual tweaks? Use `onRender` with `rad.getElementById('ID').domNode`.
+- Click listeners? Use `onLoad` to prevent duplicates.
+- Hiding elements? Use `rad.updateElementStyles(el, { visible: false })`.
+
+---
+
+# Best Practices
+
+When it comes to best practices for using the Radical API, you should keep a few things in mind. Here are some best practices to follow.
+
+## Use updateElementStyles
+
+When it comes to updating the visibility of an element, you should use the `rad.updateElementStyles` method. This method is more efficient and easier to use than updating the style attribute directly. The problem with updating the style attribute directly is that for certain elements (like Textbox), you also need to call the `updateShrink()` method to make the Textbox visible. `rad.updateElementStyles` handles this for you.
+
+---
+
+# Components
+
+In this guide, we will take a look at different components a creative can have and how Radical API can help you manage them.
+
+You can add Custom JavaScript to your creatives if you want to access and control the elements added from the editor.
+
+## Carousel
+
+Carousels are a great way to display multiple images or videos in a single ad unit. You can use the Radical API to create and manage carousels in your creatives.
+
+Name | Description
+--- | ---
+animateToSlide(index: number): void | Use this method to animate the carousel to a specific slide. The method takes a single argument, which is the index of the slide you want to animate to.
+animateToSlideIndex(index: number): void | Use this method to animate the carousel to a specific slide. The method takes a single argument, which is the index of the slide you want to animate to.
+getCarouselPlayUUID(): string | Use this method to get the UUID of the carousel play event.
+getElementDataSource(): string | A Carousel component can have a data source. Users can add this data source from the editor. This method returns the data source of the carousel.
+getSlides(): Carousel Slide[] | Use this method to get all the slides in the carousel.
+getElementDataSource(): ElementDataSource | Use this method to get the data source of the carousel.
+getVisibleSlideIndex(): number | Use this method to get the index of the currently visible slide.
+moveToSlide(index: number): void; | Use this method to move the carousel to a specific slide. The method takes a single argument, which is the index of the slide you want to move to. This method does not animate the transition.
+nextSlide(): void; | Use this method to move the carousel to the next slide. It will use the first slide if the current slide is the last one.
+onRender(callback: (arg: any) => void): void; | Use this method to register a callback that will be called when the carousel is rendered.
+pause(): void; | Use this method to pause the carousel.
+previousSlide(): void | Use this method to move the carousel to the previous slide. It will use the last slide if the current slide is the first one.
+removeSlide(index: number): void | Use this method to remove a slide from the carousel. The method takes a single argument, which is the index of the slide you want to remove.
+rendered(): boolean | Use this method to check if the carousel is rendered.
+resume(): void | Use this method to resume the carousel.
+setPausedCarouselAfterSlideChange(paused: boolean): void | Use this method to set whether the carousel should be paused after a slide change.
+setVisibleSlide(index: number): void; | Use this method to set the visible slide of the carousel. The method takes a single argument, which is the index of the slide you want to set as visible.
+setVisibleSlideIndex(index: number): void; | Use this method to set the visible slide of the carousel. The method takes a single argument, which is the index of the slide you want to set as visible.
+slideChangeCallback(callback: (arg: any) => void): void; | Use this method to register a callback that will be called when the slide changes.
+updated(): boolean; | Use this method to check if the carousel is updated.
+
+## TextBox
+
+Textboxes are used to display text in your creatives. They are added from the editor but you can edit them using the API.
+
+Name | Description
+--- | ---
+updateShrink(): string | Use this method to update the text element. Any changes to the text element will be reflected in the DOM.
+updateContent(text: string): void | Use this method to update the content of the textbox. The method takes a single argument, which is the content you want to update.
+
+---
+
+# Radical API
+
+Radical API is a set of methods and properties that you can use to manage your creatives. You can use the API to access and control the elements in your creatives.
+
+## RAD object
+
+Our rendering library called Radical exposes some helper functions you can you while working on your creative you can access them by initializing the `rad` object by calling
+
+```javascript
+var rad = Radical.getAdByWindow(window);
+```
+
+The majority of functions available on the object are used internally by Radical, but a couple of them will come in handy when working with the creative.
+
+```javascript
+rad.onRender(onAdRender);
+
+function onAdRender() {
+  console.log('rendered');
+}
+```
+
+This is called after all the elements in the creation are rendered and positioned by the Radical. Use the onLoad event to add DOM event listeners (click, mouse enter, mouse leave, ...) because onRender is called multiple times when you resize the ad, and the listeners would be added multiple times.
+
+```javascript
+rad.onLoad(onAdLoaded);
+```
+
+This is called after the flowline for the creative was loaded but before the render. This is a good place to add any DOM event listeners, as this is called only once.
+
+```javascript
+rad.onBeforeRender(onBeforeRender);
+```
+
+This event returns elements object with all the properties it they will render. You have an option to change these properties before the rendere here. Just update the object. The object is composed of keys that are element ID-s and values that are corresponding properties.
+
+```javascript
+var sizes = rad.getMergedContent().sizes;
+```
+
+An array of all layout sizes we can render from. In the case of Fully-fluid format, this array is empty.
+
+```javascript
+var layoutSize = rad.getRenderedSize();
+```
+
+Size object of the layout currently rendering.
+
+```javascript
+var element = rad.getElementById('e2');
+```
+
+You can use `getElementById` to get an element reference, make sure you are calling this inside `onRender` callback. Check boilerplate code, for example. `getElementById` returns an object with `domNode` property pointing to actual DOM element and some other information about the element. Some elements, like the video, also contain useful functions to control the element.
+
+---
+
+# All Functions
+
+You can follow the Custom JavaScript Guide to learn how to use the Radical API in your creatives.
+
+Name | Description
+--- | ---
+addGlobalEventListener(event: string, callback: (arg: any) => void) | Adds a global event listener to the creative. The event listener will be triggered when the specified event occurs in the creative.
+animationTime(time: number) | Sets the animation time of the creative to the specified time in milliseconds.
+callTrackerURL(url: string) | Call the specified tracker URL.
+clearElements(elements: HTMLElement[]) | Clears the specified elements from the creative.
+condeHideAd() | Hides the creative.
+createLightboxContainer() | Creates a lightbox container.
+creativeTimeSpent() | Returns the time spent on the creative in milliseconds.
+domEventHandler(event: string, callback: (arg: any) => void) | Adds a DOM event listener to the creative. The event listener will be triggered when the specified event occurs in the creative.
+forceRender() | Forces the creative to render.
+generateUUID() | Generates a UUID.
+getActiveConfig() | Returns the active config of the creative.
+getAdContent() | Returns the ad content of the creative.
+getAdRenderer() | Returns the ad renderer of the creative.
+getAdTagOptions() | Returns the ad tag options of the creative.
+getAdVersion() | Returns the ad version of the creative.
+getAnimationTimeline() | Returns the animation timeline of the creative.
+getAssets() | Returns the assets of the creative.
+getConfig() | Returns the config of the creative.
+getContainer() | Returns the container of the creative.
+getCookie(name: string) | Returns the value of the specified cookie.
+getCurrentMediaquery() | Returns the current media query of the creative.
+getDataLayer() | Returns the data layer of the creative.
+getDeviceInfo() | Returns the device info of the creative.
+getElementById(id: string) | Returns the element with the specified ID.
+getElementChildren(element: HTMLElement) | Returns the children of the specified element.
+getElementStyles(element: HTMLElement) | Returns the styles of the specified element.
+getExtension(extensionType: string) | Returns the extension of the specified type.
+getFormatLayouts() | Returns the format layouts of the creative.
+getLbNro() | Returns the lightbox number of the creative.
+getMergedContent() | Returns the merged content of the creative.
+getRenderedSize() | Returns the rendered size of the creative.
+getSizeFilter() | Returns the size filter of the creative.
+getState() | Returns the state of the creative.
+getUUID() | Returns the UUID of the creative.
+getUserInfo() | Returns the user info of the creative.
+getVisibleElementChildren(element: HTMLElement) | Returns the visible children of the specified element.
+hideCreative() | Hides the creative.
+isAdContentAvailable() | Returns true if the ad content is available, otherwise false.
+isOpenStateAdObj() | Returns true if the ad object is in open state, otherwise false.
+onAdContentAvailable(callback: (arg: any) => void) | Adds a callback to be triggered when the ad content is available.
+onAdHover(callback: (arg: any) => void) | Adds a callback to be triggered when the ad is hovered.
+onAnimationProgress(callback: (arg: any) => void) | Adds a callback to be triggered when the animation progresses.
+onBeforeRender(callback: (arg: any) => void) | Adds a callback to be triggered before the creative is rendered.
+onCarouselFirstSlide(callback: (arg: any) => void) | Adds a callback to be triggered when the carousel is on the first slide.
+onCarouselLastSlide(callback: (arg: any) => void) | Adds a callback to be triggered when the carousel is on the last slide.
+onCarouselMiddleSlide(callback: (arg: any) => void) | Adds a callback to be triggered when the carousel is on the middle slide.
+onClick(callback: (arg: any) => void) | Adds a callback to be triggered when the creative is clicked.
+onCountdownFinished(callback: (arg: any) => void) | Adds a callback to be triggered when the countdown finishes.
+onElementHover(callback: (arg: any) => void) | Adds a callback to be triggered when an element is hovered.
+onElementMouseOut(callback: (arg: any) => void) | Adds a callback to be triggered when the mouse leaves an element.
+onLoad(callback: (arg: any) => void) | Adds a callback to be triggered when the creative is loaded.
+onMediaEnded(callback: (arg: any) => void) | Adds a callback to be triggered when the media ends.
+onMediaPause(callback: (arg: any) => void) | Adds a callback to be triggered when the media is paused.
+onMediaPlaying(callback: (arg: any) => void) | Adds a callback to be triggered when the media is playing.
+onPreviewVideoEnd(callback: (arg: any) => void) | Adds a callback to be triggered when the preview video ends.
+onPreviewVideoStart(callback: (arg: any) => void) | Adds a callback to be triggered when the preview video starts.
+onRender(callback: (arg: any) => void) | Adds a callback to be triggered when the creative is rendered.
+onVideoEnd(callback: (arg: any) => void) | Adds a callback to be triggered when the video ends.
+onVideoMuted(callback: (arg: any) => void) | Adds a callback to be triggered when the video is muted.
+onVideoPause(callback: (arg: any) => void) | Adds a callback to be triggered when the video is paused.
+onVideoPlay(callback: (arg: any) => void) | Adds a callback to be triggered when the video is played.
+onVideoTimeUpdate(callback: (arg: any) => void) | Adds a callback to be triggered when the video time is updated.
+onVideoUnMuted(callback: (arg: any) => void) | Adds a callback to be triggered when the video is unmuted.
+onVideoUnableToAutoplay(callback: (arg: any) => void) | Adds a callback to be triggered when the video is unable to autoplay.
+pauseAnimation() | Pauses the animation of the creative.
+playAnimation() | Plays the animation of the creative.
+previewPageForceRender() | Forces the creative to render the preview page.
+refreshInteractionDisable() | Disables the refresh interaction of the creative.
+removeGlobalEventListener(event: string, callback: (arg: any) => void) | Removes the specified global event listener from the creative.
+renderElement(element: HTMLElement) | Renders the specified element in the creative.
+renderElementWithStyles(element: HTMLElement, styles: any) | Renders the specified element in the creative with the specified styles.
+restartAnimation() | Restarts the animation of the creative.
+seekAnimation(time: number) | Seeks the animation of the creative to the specified time in milliseconds.
+sendAdformAnalyticsEvent(event: string, data: any) | Sends an Adform analytics event with the specified event and data.
+sendAnalyticsEvent(event: string) | Sends an analytics event with the specified event.
+setConfig(config: any) | Sets the config of the creative to the specified config.
+setCookie(name: string, value: string, options: any) | Sets the specified cookie with the specified value and options.
+setCustomTracker(tracker: any) | Sets the custom tracker of the creative to the specified tracker.
+setLbNro(nro: number) | Sets the lightbox number of the creative to the specified number.
+setProgressAnimation(progress: number) | Sets the progress of the animation of the creative to the specified progress.
+setResponsiveMode(mode: string) | Sets the responsive mode of the creative to the specified mode.
+setSizeFilter(filter: any) | Sets the size filter of the creative to the specified filter.
+setState(state: any) | Sets the state of the creative to the specified state.
+setVideoInViewPercetage(percentage: number) | Sets the percentage of the video in view to the specified percentage.
+start() | Starts the creative.
+startAnimation() | Starts the animation of the creative.
+stopAnimation() | Stops the animation of the creative.
+updateAgTagOptions(options: any) | Updates the ad tag options of the creative to the specified options.
+updateAnimationTimeline(timeline: any, time: number) | Updates the animation timeline of the creative to the specified timeline and time.
+updateCustomCSS(css: string) | Updates the custom CSS of the creative to the specified CSS.
+updateCustomJs(js: string) | Updates the custom JavaScript of the creative to the specified JavaScript.
+updateElementStyles(element: HTMLElement, styles: any) | Updates the styles of the specified element to the specified styles.

package/templates/custom.js

@@ -0,0 +1,40 @@
+/**
+ * [CustomJS] Ad Creative
+ * Animates the QR code image in from the right side after the creative loads.
+ */
+
+(function () {
+  'use strict';
+
+  var rad = Radical.getAdByWindow(window);
+  var animated = false;
+
+  rad.onRender(function () {
+    var qrElement = rad.getElementById('f5');
+    if (!qrElement || !qrElement.domNode) return;
+
+    var node = qrElement.domNode;
+
+    if (!animated) {
+      animated = true;
+
+      // Read the original transform set by Radical (e.g. "translateX(-50%)")
+      var originalTransform = getComputedStyle(node).transform || node.style.transform;
+
+      // Start off-screen to the right
+      node.style.transition = 'none';
+      node.style.transform = 'translateX(100%)';
+      node.style.opacity = '0';
+
+      // Force reflow so the start position takes effect
+      void node.offsetWidth;
+
+      // Animate to original position
+      node.style.transition = 'transform 0.8s cubic-bezier(0.25, 0.46, 0.45, 0.94), opacity 0.8s ease';
+      setTimeout(function () {
+        node.style.transform = originalTransform;
+        node.style.opacity = '1';
+      }, 300);
+    }
+  });
+})();