edsger 0.36.2 → 0.37.0

package/dist/index.js

@@ -119,11 +119,15 @@ program
     .command('growth <productId>')
     .description('Run AI-powered growth analysis for a product')
     .option('-v, --verbose', 'Verbose output')
+    .option('-g, --guidance <text>', 'Human direction for the AI (themes, audience, tone, etc.)')
+    .option('--analysis-id <id>', 'Update an existing pending analysis instead of creating new')
     .action(async (productId, opts) => {
     try {
         await runGrowthAnalysis({
             growthAnalysis: productId,
             verbose: opts.verbose,
+            growthGuidance: opts.guidance,
+            growthAnalysisId: opts.analysisId,
         });
     }
     catch (error) {

package/dist/phases/app-store-generation/__tests__/screenshot-composer.test.js

@@ -15,8 +15,9 @@ function escapeHtml(str) {
 function mapDeviceFrame(frame) {
     switch (frame.toLowerCase()) {
         case 'iphone':
-        case 'ipad':
             return 'iphone';
+        case 'ipad':
+            return 'ipad';
         case 'macbook':
             return 'macbook';
         case 'browser':
@@ -25,13 +26,105 @@ function mapDeviceFrame(frame) {
             return 'iphone';
     }
 }
+const NAMED_COLORS = {
+    white: [255, 255, 255],
+    black: [0, 0, 0],
+    red: [255, 0, 0],
+    green: [0, 128, 0],
+    blue: [0, 0, 255],
+    yellow: [255, 255, 0],
+    cyan: [0, 255, 255],
+    magenta: [255, 0, 255],
+    gray: [128, 128, 128],
+    grey: [128, 128, 128],
+    orange: [255, 165, 0],
+    purple: [128, 0, 128],
+    pink: [255, 192, 203],
+};
+function parseColor(color) {
+    const s = color.trim().toLowerCase();
+    if (NAMED_COLORS[s]) {
+        return NAMED_COLORS[s];
+    }
+    const rgbMatch = /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/.exec(s);
+    if (rgbMatch) {
+        return [parseInt(rgbMatch[1]), parseInt(rgbMatch[2]), parseInt(rgbMatch[3])];
+    }
+    const hexMatch = /^#?([0-9a-f]{3,8})$/i.exec(s);
+    if (!hexMatch) {
+        return null;
+    }
+    const h = hexMatch[1];
+    if (h.length === 3) {
+        return [
+            parseInt(h[0] + h[0], 16),
+            parseInt(h[1] + h[1], 16),
+            parseInt(h[2] + h[2], 16),
+        ];
+    }
+    if (h.length >= 6) {
+        return [
+            parseInt(h.slice(0, 2), 16),
+            parseInt(h.slice(2, 4), 16),
+            parseInt(h.slice(4, 6), 16),
+        ];
+    }
+    return null;
+}
+function colorLuminance(color) {
+    const rgb = parseColor(color);
+    if (!rgb) {
+        return 1.0;
+    }
+    const toLinear = (c) => {
+        const s = c / 255;
+        return s <= 0.04045 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+    };
+    return (0.2126 * toLinear(rgb[0]) +
+        0.7152 * toLinear(rgb[1]) +
+        0.0722 * toLinear(rgb[2]));
+}
+function smoothstep(edge0, edge1, x) {
+    const t = Math.max(0, Math.min(1, (x - edge0) / (edge1 - edge0)));
+    return t * t * (3 - 2 * t);
+}
+function contrastStyles(textColor) {
+    const lum = colorLuminance(textColor);
+    const lightness = smoothstep(0.15, 0.65, lum);
+    const ch = Math.round(255 * (1 - lightness));
+    const certainty = Math.abs(lightness - 0.5) * 2;
+    const baseOverlay = 0.25 * lightness + 0.2 * (1 - lightness);
+    const baseShadow = 0.35 * lightness + 0.4 * (1 - lightness);
+    const baseShadowLight = 0.25 * lightness + 0.3 * (1 - lightness);
+    const scale = 0.5 + 0.5 * certainty;
+    const fmt = (alpha) => (alpha * scale).toFixed(2);
+    return {
+        overlayColor: `rgba(${ch},${ch},${ch},${fmt(baseOverlay)})`,
+        shadowColor: `rgba(${ch},${ch},${ch},${fmt(baseShadow)})`,
+        shadowColorLight: `rgba(${ch},${ch},${ch},${fmt(baseShadowLight)})`,
+    };
+}
+// Simulates getInterFontStyle() output for testing (without real base64 font data)
+const testFontStyle = `<style>
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: url(data:font/woff2;base64,TEST) format('woff2');
+}
+</style>`;
 function createCompositionHtml(framedScreenshotDataUrl, spec, targetWidth, targetHeight) {
     const isPortrait = targetHeight > targetWidth;
     const textColor = spec.text_color || '#ffffff';
+    const fontStyle = testFontStyle;
+    const fontFamily = `'Inter', -apple-system, BlinkMacSystemFont, 'SF Pro Display', 'Segoe UI', sans-serif`;
+    const { overlayColor, shadowColor, shadowColorLight } = contrastStyles(textColor);
     if (isPortrait) {
         return `<!DOCTYPE html>
 <html>
 <head>
+${fontStyle}
 <style>
   * { margin: 0; padding: 0; box-sizing: border-box; }
   body {
@@ -42,41 +135,64 @@ function createCompositionHtml(framedScreenshotDataUrl, spec, targetWidth, targe
     flex-direction: column;
     align-items: center;
     justify-content: flex-start;
-    font-family: -apple-system, BlinkMacSystemFont, 'SF Pro Display', 'Segoe UI', sans-serif;
+    font-family: ${fontFamily};
     overflow: hidden;
   }
   .text-area {
-    padding: ${Math.round(targetHeight * 0.06)}px ${Math.round(targetWidth * 0.08)}px;
+    padding: ${Math.round(targetHeight * 0.05)}px ${Math.round(targetWidth * 0.08)}px;
     text-align: center;
     flex-shrink: 0;
+    max-height: 28%;
+    position: relative;
+  }
+  .text-area::after {
+    content: '';
+    position: absolute;
+    inset: 0;
+    background: linear-gradient(to bottom, ${overlayColor} 0%, transparent 100%);
+    border-radius: inherit;
+    pointer-events: none;
   }
   .headline {
-    font-size: ${Math.round(targetWidth * 0.07)}px;
+    font-size: ${Math.round(targetWidth * 0.1)}px;
     font-weight: 800;
     color: ${textColor};
     line-height: 1.15;
     letter-spacing: -0.02em;
     margin-bottom: ${Math.round(targetHeight * 0.01)}px;
+    text-shadow: 0 2px 12px ${shadowColor};
+    position: relative;
+    z-index: 1;
+    display: -webkit-box;
+    -webkit-line-clamp: 3;
+    -webkit-box-orient: vertical;
+    overflow: hidden;
   }
   .subheadline {
-    font-size: ${Math.round(targetWidth * 0.035)}px;
+    font-size: ${Math.round(targetWidth * 0.05)}px;
     font-weight: 400;
     color: ${textColor};
     opacity: 0.85;
     line-height: 1.3;
+    text-shadow: 0 1px 8px ${shadowColorLight};
+    position: relative;
+    z-index: 1;
+    display: -webkit-box;
+    -webkit-line-clamp: 2;
+    -webkit-box-orient: vertical;
+    overflow: hidden;
   }
   .device-area {
     flex: 1;
     display: flex;
-    align-items: flex-start;
+    align-items: center;
     justify-content: center;
     overflow: hidden;
-    padding: 0 ${Math.round(targetWidth * 0.05)}px;
+    min-height: 0;
+    padding: 0 ${Math.round(targetWidth * 0.02)}px;
   }
   .device-area img {
-    max-width: 100%;
-    max-height: 100%;
-    object-fit: contain;
+    width: 92%;
   }
 </style>
 </head>
@@ -94,6 +210,7 @@ function createCompositionHtml(framedScreenshotDataUrl, spec, targetWidth, targe
     return `<!DOCTYPE html>
 <html>
 <head>
+${fontStyle}
 <style>
   * { margin: 0; padding: 0; box-sizing: border-box; }
   body {
@@ -102,41 +219,70 @@ function createCompositionHtml(framedScreenshotDataUrl, spec, targetWidth, targe
     background: ${spec.background_gradient};
     display: flex;
     align-items: center;
-    font-family: -apple-system, BlinkMacSystemFont, 'SF Pro Display', 'Segoe UI', sans-serif;
+    font-family: ${fontFamily};
     overflow: hidden;
   }
   .text-area {
-    width: 40%;
+    flex: 0 1 auto;
+    min-width: 28%;
+    max-width: 44%;
     padding: 0 ${Math.round(targetWidth * 0.04)}px;
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
     text-align: left;
+    position: relative;
+  }
+  .text-area::after {
+    content: '';
+    position: absolute;
+    inset: 0;
+    background: linear-gradient(to right, ${overlayColor} 0%, transparent 100%);
+    border-radius: inherit;
+    pointer-events: none;
   }
   .headline {
-    font-size: ${Math.round(targetWidth * 0.04)}px;
+    font-size: ${Math.round(targetWidth * 0.055)}px;
     font-weight: 800;
     color: ${textColor};
     line-height: 1.15;
     letter-spacing: -0.02em;
     margin-bottom: ${Math.round(targetHeight * 0.02)}px;
+    text-shadow: 0 2px 12px ${shadowColor};
+    position: relative;
+    z-index: 1;
+    display: -webkit-box;
+    -webkit-line-clamp: 3;
+    -webkit-box-orient: vertical;
+    overflow: hidden;
   }
   .subheadline {
-    font-size: ${Math.round(targetWidth * 0.02)}px;
+    font-size: ${Math.round(targetWidth * 0.028)}px;
     font-weight: 400;
     color: ${textColor};
     opacity: 0.85;
     line-height: 1.4;
+    text-shadow: 0 1px 8px ${shadowColorLight};
+    position: relative;
+    z-index: 1;
+    display: -webkit-box;
+    -webkit-line-clamp: 2;
+    -webkit-box-orient: vertical;
+    overflow: hidden;
   }
   .device-area {
-    width: 60%;
+    flex: 1 1 0;
+    min-width: 0;
     height: 100%;
     display: flex;
     align-items: center;
     justify-content: center;
     overflow: hidden;
-    padding: ${Math.round(targetHeight * 0.05)}px;
+    padding: ${Math.round(targetHeight * 0.03)}px;
   }
   .device-area img {
     max-width: 100%;
-    max-height: 100%;
+    max-height: 95%;
     object-fit: contain;
   }
 </style>
@@ -153,6 +299,132 @@ function createCompositionHtml(framedScreenshotDataUrl, spec, targetWidth, targe
 </html>`;
 }
 // ============================================================
+// colorLuminance + parseColor tests
+// ============================================================
+void describe('colorLuminance', () => {
+    void it('should return ~1.0 for white (#ffffff)', () => {
+        const lum = colorLuminance('#ffffff');
+        assert.ok(lum > 0.99, `White luminance should be ~1.0, got ${lum}`);
+    });
+    void it('should return ~0.0 for black (#000000)', () => {
+        const lum = colorLuminance('#000000');
+        assert.ok(lum < 0.01, `Black luminance should be ~0.0, got ${lum}`);
+    });
+    void it('should handle 3-digit hex (#fff)', () => {
+        const lum = colorLuminance('#fff');
+        assert.ok(lum > 0.99, `#fff luminance should be ~1.0, got ${lum}`);
+    });
+    void it('should handle hex without # prefix', () => {
+        const lum = colorLuminance('ff0000');
+        assert.ok(lum > 0.1 && lum < 0.3, `Red luminance should be ~0.21, got ${lum}`);
+    });
+    void it('should return 1.0 for invalid input (safe default)', () => {
+        assert.strictEqual(colorLuminance('notacolor'), 1.0);
+        assert.strictEqual(colorLuminance(''), 1.0);
+    });
+    void it('should calculate mid-range luminance for gray (#808080)', () => {
+        const lum = colorLuminance('#808080');
+        assert.ok(lum > 0.15 && lum < 0.25, `Gray luminance should be ~0.22, got ${lum}`);
+    });
+    void it('should parse rgb() format', () => {
+        const lum = colorLuminance('rgb(255, 0, 0)');
+        assert.ok(lum > 0.1 && lum < 0.3, `rgb red luminance should be ~0.21, got ${lum}`);
+    });
+    void it('should parse rgba() format', () => {
+        const lum = colorLuminance('rgba(255, 255, 255, 0.5)');
+        assert.ok(lum > 0.99, `rgba white luminance should be ~1.0, got ${lum}`);
+    });
+    void it('should parse named colors', () => {
+        assert.ok(colorLuminance('white') > 0.99, 'Named "white" should be ~1.0');
+        assert.ok(colorLuminance('black') < 0.01, 'Named "black" should be ~0.0');
+        assert.ok(colorLuminance('Red') > 0.1, 'Named "Red" (case insensitive) should parse');
+    });
+});
+// ============================================================
+// contrastStyles tests
+// ============================================================
+void describe('contrastStyles', () => {
+    void it('should return dark overlay for white text', () => {
+        const styles = contrastStyles('#ffffff');
+        assert.strictEqual(styles.overlayColor, 'rgba(0,0,0,0.25)');
+        assert.strictEqual(styles.shadowColor, 'rgba(0,0,0,0.35)');
+    });
+    void it('should return light overlay for black text', () => {
+        const styles = contrastStyles('#000000');
+        assert.strictEqual(styles.overlayColor, 'rgba(255,255,255,0.20)');
+        assert.strictEqual(styles.shadowColor, 'rgba(255,255,255,0.40)');
+    });
+    void it('should return dark overlay for light colors like #f0f0f0', () => {
+        const styles = contrastStyles('#f0f0f0');
+        assert.ok(styles.overlayColor.startsWith('rgba(0,0,0,'), 'Light gray text should get dark overlay');
+    });
+    void it('should return light overlay for dark colors like #333333', () => {
+        const styles = contrastStyles('#333333');
+        assert.ok(styles.overlayColor.startsWith('rgba(255,255,255,'), 'Dark gray text should get light overlay');
+    });
+    void it('should reduce overlay strength for mid-range text', () => {
+        // #aaaaaa has luminance ~0.40, right in the smoothstep transition zone
+        const midStyles = contrastStyles('#aaaaaa');
+        const midAlpha = parseFloat(midStyles.overlayColor.split(',')[3]);
+        const extremeAlpha = parseFloat(contrastStyles('#ffffff').overlayColor.split(',')[3]);
+        assert.ok(midAlpha < extremeAlpha, `Mid-range alpha ${midAlpha} should be less than extreme alpha ${extremeAlpha}`);
+    });
+    void it('should produce smooth channel gradient for mid-range text', () => {
+        // Mid-range text should produce a gray channel, not pure black or white
+        const styles = contrastStyles('#aaaaaa');
+        const ch = parseInt(styles.overlayColor.split('(')[1]);
+        assert.ok(ch > 10 && ch < 245, `Mid-range text should produce gray channel, got ${ch}`);
+    });
+    void it('should default to dark overlay for unparseable color', () => {
+        const styles = contrastStyles('invalid');
+        assert.strictEqual(styles.overlayColor, 'rgba(0,0,0,0.25)');
+    });
+    void it('should work with rgb() input', () => {
+        const styles = contrastStyles('rgb(255, 255, 255)');
+        assert.strictEqual(styles.overlayColor, 'rgba(0,0,0,0.25)');
+    });
+    void it('should work with named color input', () => {
+        const styles = contrastStyles('black');
+        assert.strictEqual(styles.overlayColor, 'rgba(255,255,255,0.20)');
+    });
+});
+// ============================================================
+// createCompositionHtml - Adaptive contrast
+// ============================================================
+void describe('createCompositionHtml - Adaptive contrast', () => {
+    const dataUrl = 'data:image/png;base64,x';
+    const baseSpec = {
+        feature_highlight: 'Test',
+        headline: 'Test',
+        subheadline: 'Sub',
+        background_gradient: 'linear-gradient(#000, #111)',
+        text_color: '#ffffff',
+        device_frame: 'iphone',
+        html_template: '<html></html>',
+    };
+    void it('should use dark overlay/shadow for white text (#ffffff)', () => {
+        const html = createCompositionHtml(dataUrl, baseSpec, 1290, 2796);
+        assert.ok(html.includes('rgba(0,0,0,0.25)'), 'White text should produce dark overlay');
+        assert.ok(html.includes('rgba(0,0,0,0.35)'), 'White text should produce dark text-shadow');
+    });
+    void it('should use light overlay/shadow for dark text (#1a1a1a)', () => {
+        const darkTextSpec = { ...baseSpec, text_color: '#1a1a1a' };
+        const html = createCompositionHtml(dataUrl, darkTextSpec, 1290, 2796);
+        assert.ok(html.includes('rgba(255,255,255,0.20)'), 'Dark text should produce light overlay');
+        assert.ok(html.includes('rgba(255,255,255,0.40)'), 'Dark text should produce light text-shadow');
+    });
+    void it('should use light overlay for landscape with dark text', () => {
+        const darkTextSpec = { ...baseSpec, text_color: '#000000' };
+        const html = createCompositionHtml(dataUrl, darkTextSpec, 1920, 1200);
+        assert.ok(html.includes('rgba(255,255,255,0.20)'), 'Landscape dark text should produce light overlay');
+    });
+    void it('should default to dark overlay when text_color is empty', () => {
+        const emptySpec = { ...baseSpec, text_color: '' };
+        const html = createCompositionHtml(dataUrl, emptySpec, 1290, 2796);
+        assert.ok(html.includes('rgba(0,0,0,0.25)'), 'Empty text_color defaults to #ffffff → dark overlay');
+    });
+});
+// ============================================================
 // escapeHtml tests
 // ============================================================
 void describe('escapeHtml', () => {
@@ -188,8 +460,8 @@ void describe('mapDeviceFrame', () => {
     void it('should map "iphone" to "iphone"', () => {
         assert.strictEqual(mapDeviceFrame('iphone'), 'iphone');
     });
-    void it('should map "ipad" to "iphone"', () => {
-        assert.strictEqual(mapDeviceFrame('ipad'), 'iphone');
+    void it('should map "ipad" to "ipad"', () => {
+        assert.strictEqual(mapDeviceFrame('ipad'), 'ipad');
     });
     void it('should map "macbook" to "macbook"', () => {
         assert.strictEqual(mapDeviceFrame('macbook'), 'macbook');
@@ -207,7 +479,7 @@ void describe('mapDeviceFrame', () => {
         assert.strictEqual(mapDeviceFrame('iPhone'), 'iphone');
     });
     void it('should be case insensitive for "iPad"', () => {
-        assert.strictEqual(mapDeviceFrame('iPad'), 'iphone');
+        assert.strictEqual(mapDeviceFrame('iPad'), 'ipad');
     });
     void it('should be case insensitive for "MacBook"', () => {
         assert.strictEqual(mapDeviceFrame('MacBook'), 'macbook');
@@ -269,10 +541,10 @@ void describe('createCompositionHtml - Portrait mode', () => {
         assert.ok(html.includes(`width: ${width}px`), 'Should set target width in body style');
         assert.ok(html.includes(`height: ${height}px`), 'Should set target height in body style');
     });
-    void it('should calculate headline font size as Math.round(width * 0.07)', () => {
+    void it('should calculate headline font size as Math.round(width * 0.10)', () => {
         const html = createCompositionHtml(dataUrl, spec, width, height);
-        const expectedFontSize = Math.round(width * 0.07);
-        assert.ok(html.includes(`font-size: ${expectedFontSize}px`), `Headline font size should be ${expectedFontSize}px (width * 0.07)`);
+        const expectedFontSize = Math.round(width * 0.1);
+        assert.ok(html.includes(`font-size: ${expectedFontSize}px`), `Headline font size should be ${expectedFontSize}px (width * 0.10)`);
     });
     void it('should use the specified text color', () => {
         const html = createCompositionHtml(dataUrl, spec, width, height);
@@ -306,22 +578,23 @@ void describe('createCompositionHtml - Landscape mode', () => {
     // Landscape: width > height
     const width = 1920;
     const height = 1200;
-    void it('should contain text-area at 40% width', () => {
+    void it('should use adaptive text-area width with min/max bounds', () => {
         const html = createCompositionHtml(dataUrl, spec, width, height);
-        assert.ok(html.includes('width: 40%'), 'Landscape text-area should be 40% width');
+        assert.ok(html.includes('min-width: 28%'), 'Landscape text-area should have min-width: 28%');
+        assert.ok(html.includes('max-width: 44%'), 'Landscape text-area should have max-width: 44%');
     });
-    void it('should contain device-area at 60% width', () => {
+    void it('should use flexible device-area that fills remaining space', () => {
         const html = createCompositionHtml(dataUrl, spec, width, height);
-        assert.ok(html.includes('width: 60%'), 'Landscape device-area should be 60% width');
+        assert.ok(html.includes('flex: 1 1 0'), 'Landscape device-area should flex to fill remaining space');
     });
-    void it('should NOT contain flex-direction: column for landscape', () => {
+    void it('should NOT use portrait body layout for landscape', () => {
         const html = createCompositionHtml(dataUrl, spec, width, height);
-        assert.ok(!html.includes('flex-direction: column'), 'Landscape mode should NOT use flex-direction: column');
+        assert.ok(!html.includes('justify-content: flex-start'), 'Landscape body should not use portrait-style vertical layout');
     });
-    void it('should calculate headline font size as Math.round(width * 0.04)', () => {
+    void it('should calculate headline font size as Math.round(width * 0.055)', () => {
         const html = createCompositionHtml(dataUrl, spec, width, height);
-        const expectedFontSize = Math.round(width * 0.04);
-        assert.ok(html.includes(`font-size: ${expectedFontSize}px`), `Landscape headline font size should be ${expectedFontSize}px (width * 0.04)`);
+        const expectedFontSize = Math.round(width * 0.055);
+        assert.ok(html.includes(`font-size: ${expectedFontSize}px`), `Landscape headline font size should be ${expectedFontSize}px (width * 0.055)`);
     });
     void it('should contain the headline and subheadline text', () => {
         const html = createCompositionHtml(dataUrl, spec, width, height);
@@ -338,6 +611,153 @@ void describe('createCompositionHtml - Landscape mode', () => {
     });
 });
 // ============================================================
+// createCompositionHtml - Font embedding
+// ============================================================
+void describe('createCompositionHtml - Font embedding', () => {
+    const spec = {
+        feature_highlight: 'Test',
+        headline: 'Test Headline',
+        subheadline: undefined,
+        background_gradient: 'linear-gradient(#000, #111)',
+        text_color: '#fff',
+        device_frame: 'iphone',
+        html_template: '<html></html>',
+    };
+    const dataUrl = 'data:image/png;base64,x';
+    void it('should embed @font-face declaration for Inter', () => {
+        const html = createCompositionHtml(dataUrl, spec, 1290, 2796);
+        assert.ok(html.includes("font-family: 'Inter'"), 'Should declare Inter in @font-face');
+        assert.ok(html.includes('font/woff2;base64,'), 'Should embed font as base64 WOFF2 data URI');
+    });
+    void it('should use Inter as primary font-family on body', () => {
+        const html = createCompositionHtml(dataUrl, spec, 1290, 2796);
+        assert.ok(html.includes("font-family: 'Inter', -apple-system"), 'Body font-family should start with Inter');
+    });
+    void it('should not reference external font CDN', () => {
+        const html = createCompositionHtml(dataUrl, spec, 1290, 2796);
+        assert.ok(!html.includes('fonts.googleapis.com'), 'Should not reference Google Fonts CDN');
+    });
+});
+// ============================================================
+// createCompositionHtml - Text readability protection
+// ============================================================
+void describe('createCompositionHtml - Text readability protection', () => {
+    const spec = {
+        feature_highlight: 'Test',
+        headline: 'Test Headline',
+        subheadline: 'Test Sub',
+        background_gradient: 'linear-gradient(#fff, #eee)',
+        text_color: '#ffffff',
+        device_frame: 'iphone',
+        html_template: '<html></html>',
+    };
+    const dataUrl = 'data:image/png;base64,x';
+    void it('should apply text-shadow on headline for portrait', () => {
+        const html = createCompositionHtml(dataUrl, spec, 1290, 2796);
+        assert.ok(html.includes('text-shadow: 0 2px 12px rgba(0,0,0,0.35)'), 'Headline should have text-shadow for readability');
+    });
+    void it('should apply text-shadow on subheadline for portrait', () => {
+        const html = createCompositionHtml(dataUrl, spec, 1290, 2796);
+        assert.ok(html.includes('text-shadow: 0 1px 8px rgba(0,0,0,0.25)'), 'Subheadline should have lighter text-shadow');
+    });
+    void it('should apply text-shadow on headline for landscape', () => {
+        const html = createCompositionHtml(dataUrl, spec, 1920, 1200);
+        assert.ok(html.includes('text-shadow: 0 2px 12px rgba(0,0,0,0.35)'), 'Landscape headline should have text-shadow');
+    });
+    void it('should include gradient overlay on text-area for portrait', () => {
+        const html = createCompositionHtml(dataUrl, spec, 1290, 2796);
+        assert.ok(html.includes('.text-area::after'), 'Portrait should have ::after pseudo-element on text-area');
+        assert.ok(html.includes('linear-gradient(to bottom, rgba(0,0,0,0.25)'), 'Portrait overlay should gradient top-to-bottom');
+    });
+    void it('should include gradient overlay on text-area for landscape', () => {
+        const html = createCompositionHtml(dataUrl, spec, 1920, 1200);
+        assert.ok(html.includes('.text-area::after'), 'Landscape should have ::after pseudo-element on text-area');
+        assert.ok(html.includes('linear-gradient(to right, rgba(0,0,0,0.25)'), 'Landscape overlay should gradient left-to-right');
+    });
+    void it('should set z-index on headline/subheadline above overlay', () => {
+        const html = createCompositionHtml(dataUrl, spec, 1290, 2796);
+        assert.ok(html.includes('z-index: 1'), 'Text elements should have z-index above the overlay');
+    });
+});
+// ============================================================
+// createCompositionHtml - Line clamping
+// ============================================================
+void describe('createCompositionHtml - Line clamping', () => {
+    const spec = {
+        feature_highlight: 'Test',
+        headline: 'Very Long Headline That Could Potentially Overflow',
+        subheadline: 'A subheadline that is also quite long and may overflow',
+        background_gradient: 'linear-gradient(#000, #111)',
+        text_color: '#fff',
+        device_frame: 'iphone',
+        html_template: '<html></html>',
+    };
+    const dataUrl = 'data:image/png;base64,x';
+    void it('should clamp headline to 3 lines in portrait', () => {
+        const html = createCompositionHtml(dataUrl, spec, 1290, 2796);
+        assert.ok(html.includes('-webkit-line-clamp: 3'), 'Portrait headline should be clamped to 3 lines');
+    });
+    void it('should clamp subheadline to 2 lines in portrait', () => {
+        const html = createCompositionHtml(dataUrl, spec, 1290, 2796);
+        assert.ok(html.includes('-webkit-line-clamp: 2'), 'Portrait subheadline should be clamped to 2 lines');
+    });
+    void it('should clamp headline to 3 lines in landscape', () => {
+        const html = createCompositionHtml(dataUrl, spec, 1920, 1200);
+        assert.ok(html.includes('-webkit-line-clamp: 3'), 'Landscape headline should be clamped to 3 lines');
+    });
+    void it('should use -webkit-box for line clamping', () => {
+        const html = createCompositionHtml(dataUrl, spec, 1290, 2796);
+        assert.ok(html.includes('display: -webkit-box'), 'Should use -webkit-box display for line clamping');
+        assert.ok(html.includes('-webkit-box-orient: vertical'), 'Should set -webkit-box-orient: vertical');
+    });
+});
+// ============================================================
+// createCompositionHtml - Portrait layout details
+// ============================================================
+void describe('createCompositionHtml - Portrait layout details', () => {
+    const spec = {
+        feature_highlight: 'Test',
+        headline: 'Test',
+        subheadline: undefined,
+        background_gradient: 'linear-gradient(#000, #111)',
+        text_color: '#fff',
+        device_frame: 'iphone',
+        html_template: '<html></html>',
+    };
+    const dataUrl = 'data:image/png;base64,x';
+    void it('should limit text-area max-height to 28%', () => {
+        const html = createCompositionHtml(dataUrl, spec, 1290, 2796);
+        assert.ok(html.includes('max-height: 28%'), 'Portrait text-area should have max-height: 28%');
+    });
+    void it('should center device vertically in device-area', () => {
+        const html = createCompositionHtml(dataUrl, spec, 1290, 2796);
+        assert.ok(html.includes('align-items: center') && html.includes('min-height: 0'), 'Device-area should center content vertically with min-height: 0');
+    });
+});
+// ============================================================
+// createCompositionHtml - Landscape layout details
+// ============================================================
+void describe('createCompositionHtml - Landscape layout details', () => {
+    const spec = {
+        feature_highlight: 'Test',
+        headline: 'Test',
+        subheadline: undefined,
+        background_gradient: 'linear-gradient(#000, #111)',
+        text_color: '#fff',
+        device_frame: 'browser',
+        html_template: '<html></html>',
+    };
+    const dataUrl = 'data:image/png;base64,x';
+    void it('should vertically center text inside text-area', () => {
+        const html = createCompositionHtml(dataUrl, spec, 1920, 1200);
+        assert.ok(html.includes('justify-content: center'), 'Text-area should vertically center its content');
+    });
+    void it('should prevent device-area overflow with min-width: 0', () => {
+        const html = createCompositionHtml(dataUrl, spec, 1920, 1200);
+        assert.ok(html.includes('min-width: 0'), 'Device-area should have min-width: 0 to prevent flex overflow');
+    });
+});
+// ============================================================
 // createCompositionHtml - HTML escaping
 // ============================================================
 void describe('createCompositionHtml - HTML escaping', () => {

package/dist/phases/app-store-generation/inter-font.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Inter font (variable weight) embedded as base64 WOFF2.
+ * Latin + Latin-ext subsets cover Western European languages.
+ * Font files are loaded from assets/ at runtime and cached in memory.
+ *
+ * Source: Google Fonts Inter v20, weights 100-900 (variable)
+ * Total size: ~130KB raw WOFF2 (Latin 47KB + Latin-ext 83KB)
+ *
+ * CJK limitation: Inter does not include Chinese, Japanese, or Korean
+ * glyphs. Text in these scripts falls back to the system font stack
+ * (-apple-system, BlinkMacSystemFont, etc.). To add CJK coverage,
+ * embed Noto Sans CJK subsets (~300-500KB per script), which is not
+ * included here to keep the composition payload reasonable.
+ */
+/**
+ * Returns a <style> block with @font-face declarations for Inter.
+ * Embed this in <head> to load Inter without any network requests.
+ * Font data is read from disk on first call and cached thereafter.
+ */
+export declare function getInterFontStyle(): string;