codeplay-common 4.7.2 → 4.7.4

package/files/take-screen-image.js

@@ -5,14 +5,34 @@
 //node take-screen-image.js --oppo-existing       //Used if we already took the screenshot and those oppo screenshots are not there then execute this to resize the screenshot for Oppo store.
 
 
+/*
+  1) run this "node take-screen-image.js"
+
+  2) After take all screenshot do the following
+     Execute the following in codex
+        Execute this AGENTS\Commands\AI-Screenshot text generation.txt
+
+  3) Execute the following
+        node take-screen-image.js --reframe-existing
+        node take-screen-image.js --reframe-existing --screenshots 6,7
+*/
+
+
 const fs = require('node:fs');
 const path = require('node:path');
 const readline = require('node:readline/promises');
 const { spawn, spawnSync } = require('node:child_process');
 const sharp = require('sharp');
+const { frameStyles, createFrameSamples } = require('./scripts-screenshot/screenshot/frame-samples.js');
+const {
+  getDecorationSeed,
+  createPromotionalDecorations,
+  getPromotionalDecorationStyles,
+} = require('./scripts-screenshot/screenshot/background-decorations.js');
 
 const screenshotDirectory = path.join(__dirname, 'Auto-Screenshot', 'Store-image-Screenshot');
 const inFrameDirectory = path.join(__dirname, 'Auto-Screenshot', 'Store-image-Frame');
+const uploadDirectory = path.join(__dirname, 'Auto-Screenshot', 'Store-upload');
 const autoScreenshotDirectory = path.join(__dirname, 'Auto-Screenshot');
 const aiAssetsDirectory = path.join(__dirname, 'AI-Assets');
 const amazonAssetsDirectory = path.join(aiAssetsDirectory, 'Amazon-Assets');
@@ -21,6 +41,13 @@ const playstoreAssetsDirectory = path.join(aiAssetsDirectory, 'Playstore-Assets'
 const capacitorConfigPath = path.join(__dirname, 'capacitor.config.json');
 const amazonIconPath = path.join(__dirname, 'resources', 'icon-only.png');
 const temporaryDirectory = path.join(__dirname, 'agent-temp');
+const screenshotCopyPath = path.join(__dirname, 'scripts-screenshot', 'screenshot', 'screenshot-copy.json');
+const screenshotInfoPath = path.join(__dirname, 'scripts-screenshot', 'screenshot', 'screenshot-info.json');
+let selectedFrameStyles = { android: 'graphite', ios: 'midnight' };
+let frameCaptureSequence = 0;
+let screenshotCopyConfig;
+const missingScreenshotCopyWarnings = new Set();
+const frameTimeBase = Date.now();
 const amazonAssetDefinitions = [
   { fileName: 'icon-1280x720.png', type: 'icon', width: 1280, height: 720 },
   { fileName: 'background-image-1920x1080.png', type: 'background-image', width: 1920, height: 1080 },
@@ -146,7 +173,7 @@ const deviceProfiles = [
     name: 'ipad',
     label: 'iPad 13-inch App Store viewport',
     outputDirectory: 'iPad',
-    frameType: 'tablet',
+    frameType: 'ipad',
     width: 1032,
     height: 1376,
     deviceScaleFactor: 2,
@@ -462,6 +489,8 @@ function parseArguments() {
     samsungAssets: false,
     dryRun: false,
     frameExisting: false,
+    reframeExisting: false,
+    refreshInfo: '',
     vivoExisting: false,
     oppoExisting: false,
     help: false,
@@ -470,6 +499,9 @@ function parseArguments() {
     deleteNames: '',
     prefix: '',
     profiles: '',
+    screenshots: '',
+    androidFrame: '',
+    iosFrame: '',
   };
 
   for (let index = 0; index < args.length; index += 1) {
@@ -483,6 +515,11 @@ function parseArguments() {
       options.dryRun = true;
     } else if (argument === '--frame-existing') {
       options.frameExisting = true;
+    } else if (argument === '--reframe-existing') {
+      options.reframeExisting = true;
+    } else if (argument === '--refresh-info') {
+      options.refreshInfo = args[index + 1] || '';
+      index += 1;
     } else if (argument === '--vivo-existing') {
       options.vivoExisting = true;
     } else if (argument === '--oppo-existing') {
@@ -501,6 +538,15 @@ function parseArguments() {
     } else if (argument === '--profiles') {
       options.profiles = args[index + 1] || '';
       index += 1;
+    } else if (argument === '--screenshots') {
+      options.screenshots = args[index + 1] || '';
+      index += 1;
+    } else if (argument === '--android-frame') {
+      options.androidFrame = args[index + 1] || '';
+      index += 1;
+    } else if (argument === '--ios-frame') {
+      options.iosFrame = args[index + 1] || '';
+      index += 1;
     } else {
       throw new Error(`Unknown argument: ${argument}`);
     }
@@ -540,8 +586,12 @@ function printHelp() {
   console.log('Usage:');
   console.log('  node take-screen-image.js');
   console.log('  node take-screen-image.js --profiles iphone,ipad');
+  console.log('  node take-screen-image.js --android-frame graphite --ios-frame titanium');
   console.log('  node take-screen-image.js --prefix home --profiles android-phone,ipad');
   console.log('  node take-screen-image.js --frame-existing');
+  console.log('  node take-screen-image.js --reframe-existing --profiles android-phone,iphone');
+  console.log('  node take-screen-image.js --reframe-existing --screenshots 1,2');
+  console.log('  node take-screen-image.js --refresh-info 1');
   console.log('  node take-screen-image.js --vivo-existing');
   console.log('  node take-screen-image.js --oppo-existing');
   console.log('  node take-screen-image.js --amazon-assets');
@@ -551,6 +601,74 @@ function printHelp() {
   console.log('  node take-screen-image.js --delete 3,4,5');
   console.log('');
   console.log('A normal capture automatically creates any missing Amazon, Samsung, and Play Store assets.');
+  console.log('Frame defaults: Android graphite (A), iPhone midnight (D).');
+}
+
+async function chooseFrameStyles(options) {
+  const choices = { android: options.androidFrame, ios: options.iosFrame };
+  const defaults = { android: 'graphite', ios: 'midnight' };
+  const aliases = {
+    android: { a: 'graphite', b: 'cobalt', 1: 'graphite', 2: 'cobalt' },
+    ios: { c: 'titanium', d: 'midnight', 1: 'titanium', 2: 'midnight' },
+  };
+  const canPrompt = process.stdin.isTTY && !options.prefix;
+  const terminal = canPrompt ? readline.createInterface({ input: process.stdin, output: process.stdout }) : null;
+
+  try {
+    for (const platform of ['android', 'ios']) {
+      if (!choices[platform] && terminal) {
+        const names = Object.values(frameStyles[platform]).map((style) => style.label);
+        choices[platform] = await terminal.question(
+          `${platform === 'ios' ? 'iPhone' : 'Android'} frame (${names.join(' / ')}), Enter for ${defaults[platform]}: `,
+        );
+      }
+      choices[platform] = (choices[platform] || defaults[platform]).trim().toLowerCase();
+      choices[platform] = aliases[platform][choices[platform]] || choices[platform];
+      if (!frameStyles[platform][choices[platform]]) {
+        throw new Error(`Unknown ${platform} frame: ${choices[platform]}. Choose ${Object.keys(frameStyles[platform]).join(' or ')}.`);
+      }
+    }
+  } finally {
+    if (terminal) terminal.close();
+  }
+
+  console.log(`Frame selection: Android ${choices.android}, iPhone ${choices.ios}.`);
+  return choices;
+}
+
+async function prepareFrameSelection(options) {
+  if (process.stdin.isTTY) {
+    const samplePaths = await createFrameSamples(autoScreenshotDirectory);
+    for (const samplePath of samplePaths) console.log(`Frame choices: ${samplePath}`);
+  }
+  selectedFrameStyles = await chooseFrameStyles(options);
+}
+
+function getFrameDisplayTime(platform) {
+  const time = new Date(frameTimeBase + frameCaptureSequence * 60000);
+  frameCaptureSequence += 1;
+  if (platform === 'ipad') {
+    const weekdays = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+    const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+    return `${String(time.getHours()).padStart(2, '0')}:${String(time.getMinutes()).padStart(2, '0')} `
+      + `${weekdays[time.getDay()]} ${time.getDate()} ${months[time.getMonth()]}`;
+  }
+  const hour = platform === 'ios' ? (time.getHours() % 12 || 12) : time.getHours();
+  return `${String(hour).padStart(2, '0')}:${String(time.getMinutes()).padStart(2, '0')}`;
+}
+
+function getFrameBatteryPercentage() {
+  try {
+    const deviceId = getConnectedDevice();
+    const batteryDetails = runAdb(['-s', deviceId, 'shell', 'dumpsys', 'battery']);
+    const level = Number(batteryDetails.match(/^\s*level:\s*(\d+)/m)?.[1]);
+
+    if (Number.isInteger(level) && level >= 0 && level <= 100) return level;
+  } catch {
+    // Existing screenshots can still be framed when no Android device is connected.
+  }
+
+  return 75;
 }
 
 function deleteMatchingImages(input) {
@@ -585,10 +703,92 @@ function deleteMatchingImages(input) {
   }
 
   scanDirectory(autoScreenshotDirectory);
+  removeScreenshotRecords(nameSet);
   console.log(`Deleted ${deletedFiles.length} matching image(s) from ${autoScreenshotDirectory}.`);
   for (const filePath of deletedFiles) console.log(`Deleted: ${filePath}`);
 }
 
+function readScreenshotRecordSource(filePath) {
+  if (!fs.existsSync(filePath)) return { screenshots: {} };
+
+  try {
+    const source = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return source && typeof source === 'object' ? source : { screenshots: {} };
+  } catch (error) {
+    throw new Error(`Cannot reconcile invalid JSON file ${filePath}: ${error.message}`);
+  }
+}
+
+function removeScreenshotRecords(names) {
+  for (const [filePath, label] of [
+    [screenshotCopyPath, 'screenshot copy'],
+    [screenshotInfoPath, 'screenshot information'],
+  ]) {
+    const source = readScreenshotRecordSource(filePath);
+    const screenshots = source.screenshots && typeof source.screenshots === 'object'
+      ? source.screenshots
+      : {};
+    const removedNames = [];
+
+    for (const name of names) {
+      if (!Object.hasOwn(screenshots, name)) continue;
+      delete screenshots[name];
+      removedNames.push(name);
+    }
+
+    if (!removedNames.length) continue;
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, `${JSON.stringify({ ...source, screenshots }, null, 2)}\n`);
+    console.log(
+      `Removed stale ${label} record(s) ${removedNames.join(', ')} from ${filePath}.`,
+    );
+  }
+
+  screenshotCopyConfig = undefined;
+}
+
+function getCapturedScreenshotNames() {
+  const capturedNames = new Set();
+
+  if (!fs.existsSync(screenshotDirectory)) return capturedNames;
+
+  const scanDirectory = (directory) => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const entryPath = path.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        scanDirectory(entryPath);
+      } else if (/\.(?:png|jpe?g|webp)$/i.test(entry.name)) {
+        capturedNames.add(path.parse(entry.name).name);
+      }
+    }
+  };
+
+  scanDirectory(screenshotDirectory);
+  return capturedNames;
+}
+
+function reconcileScreenshotRecords() {
+  const capturedNames = getCapturedScreenshotNames();
+  const configuredNames = new Set();
+
+  for (const filePath of [screenshotCopyPath, screenshotInfoPath]) {
+    const source = readScreenshotRecordSource(filePath);
+    const screenshots = source.screenshots && typeof source.screenshots === 'object'
+      ? source.screenshots
+      : {};
+    Object.keys(screenshots).forEach((name) => configuredNames.add(name));
+  }
+
+  const staleNames = new Set(
+    [...configuredNames].filter((name) => !capturedNames.has(name)),
+  );
+  removeScreenshotRecords(staleNames);
+
+  if (!staleNames.size) {
+    console.log('Screenshot metadata and copy records match the captured screenshots.');
+  }
+}
+
 function selectProfiles(input) {
   const orientation = getConfiguredOrientation();
   const names = input
@@ -750,6 +950,266 @@ async function capturePageSnapshot(client) {
         return canvas.toDataURL('image/png');
       };
 
+      const normalizeUiText = (value) => String(value || '')
+        .replace(/\\s+/g, ' ')
+        .trim();
+
+      const isVisible = (element) => {
+        if (!element) return false;
+        const style = getComputedStyle(element);
+        const bounds = element.getBoundingClientRect();
+        return style.display !== 'none'
+          && style.visibility !== 'hidden'
+          && Number(style.opacity || 1) > 0
+          && bounds.width > 0
+          && bounds.height > 0
+          && bounds.bottom > 0
+          && bounds.right > 0
+          && bounds.top < innerHeight
+          && bounds.left < innerWidth;
+      };
+
+      const isSafeUiText = (value) => {
+        const text = normalizeUiText(value);
+        if (text.length < 2 || text.length > 110) return false;
+        if (/(?:https?:\\/\\/|www\\.|@|(?:^|\\s)[a-z]:\\\\)/i.test(text)) return false;
+        if (/\\.(?:jpe?g|png|webp|gif|heic|zip|pdf|mp4|mov)(?:\\s|$)/i.test(text)) return false;
+        const digitCount = (text.match(/\\d/g) || []).length;
+        return digitCount <= Math.max(4, Math.floor(text.length * 0.25));
+      };
+
+      const collectUiText = (root, selector, limit) => {
+        if (!root) return [];
+        const values = [];
+        const seen = new Set();
+        for (const element of root.querySelectorAll(selector)) {
+          if (!isVisible(element)) continue;
+          const value = normalizeUiText(
+            element.getAttribute('aria-label')
+              || element.getAttribute('title')
+              || element.textContent,
+          );
+          const key = value.toLowerCase();
+          if (!isSafeUiText(value) || seen.has(key)) continue;
+          seen.add(key);
+          values.push(value);
+          if (values.length >= limit) break;
+        }
+        return values;
+      };
+
+      const getElementLabel = (element) => {
+        const explicitLabel = normalizeUiText(
+          element.getAttribute('aria-label') || element.getAttribute('title'),
+        );
+        if (isSafeUiText(explicitLabel)) return explicitLabel;
+
+        const labelRoot = element.matches('input, select, textarea')
+          ? element.closest('label, .item-content, .input')
+          : element;
+        const preferredLabel = labelRoot?.querySelector(
+          '.item-title, .button-label, strong, .dialog-button-text',
+        );
+        const textRoot = preferredLabel || labelRoot || element;
+        const clone = textRoot.cloneNode(true);
+        clone.querySelectorAll('small, .item-subtitle, svg, img').forEach((child) => child.remove());
+        const text = normalizeUiText(clone.textContent);
+        return isSafeUiText(text) ? text : '';
+      };
+
+      const getElementContext = (element) => {
+        if (element.closest('.dialog, .popup, .sheet-modal, .popover, .actions-modal')) return 'overlay';
+        if (element.closest('.navbar')) return 'navbar';
+        if (element.closest('.toolbar')) return 'toolbar';
+        return 'content';
+      };
+
+      const getStableClasses = (element) => [...element.classList]
+        .filter((className) => !/^(?:active-state|ripple-wave|focus-visible)$/.test(className))
+        .slice(0, 12);
+
+      const collectButtons = (root, limit) => {
+        if (!root) return [];
+        const records = [];
+        const seen = new Set();
+        const selector = 'button, a.button, [role="button"], .list-button, .dialog-button';
+        for (const element of root.querySelectorAll(selector)) {
+          if (!isVisible(element)) continue;
+          const label = getElementLabel(element);
+          if (!label) continue;
+          const context = getElementContext(element);
+          const key = [label.toLowerCase(), context, element.id].join('|');
+          if (seen.has(key)) continue;
+          seen.add(key);
+          const classes = getStableClasses(element);
+          const classText = classes.join(' ');
+          const prominence = /(?:button-fill|primary|main-action|save-all)/i.test(classText)
+            ? 'primary'
+            : /(?:button-large|dialog-button-bold)/i.test(classText)
+              ? 'major'
+              : /(?:button-outline|secondary)/i.test(classText)
+                ? 'secondary'
+                : 'standard';
+          records.push({
+            label,
+            id: element.id || '',
+            context,
+            prominence,
+            disabled: Boolean(element.disabled || element.getAttribute('aria-disabled') === 'true'),
+            selected: element.getAttribute('aria-pressed') === 'true'
+              || element.getAttribute('aria-selected') === 'true'
+              || element.classList.contains('tab-link-active'),
+            classes,
+          });
+          if (records.length >= limit) break;
+        }
+        return records;
+      };
+
+      const collectInputs = (root, limit) => {
+        if (!root) return [];
+        const records = [];
+        for (const element of root.querySelectorAll('input, select, textarea')) {
+          if (!isVisible(element) || element.type === 'hidden' || element.type === 'file') continue;
+          const labelRoot = element.closest('label, .item-content, .input');
+          const description = collectUiText(
+            labelRoot,
+            'small, .item-subtitle, .item-after',
+            1,
+          )[0] || '';
+          const record = {
+            label: getElementLabel(element),
+            id: element.id || '',
+            name: normalizeUiText(element.name),
+            type: element.tagName.toLowerCase() === 'select' ? 'select' : element.type || 'text',
+            context: getElementContext(element),
+            disabled: Boolean(element.disabled),
+            description,
+          };
+          if (element.type === 'checkbox' || element.type === 'radio') {
+            record.checked = Boolean(element.checked);
+            const safeValue = normalizeUiText(element.value);
+            if (isSafeUiText(safeValue)) record.value = safeValue;
+          } else if (element.tagName.toLowerCase() === 'select') {
+            const selectedText = normalizeUiText(element.selectedOptions?.[0]?.textContent);
+            if (isSafeUiText(selectedText)) record.selectedOption = selectedText;
+          }
+          records.push(record);
+          if (records.length >= limit) break;
+        }
+        return records;
+      };
+
+      const visiblePages = [...document.querySelectorAll('.page')].filter(isVisible);
+      const activePage = visiblePages.find((page) => page.classList.contains('page-current'))
+        || visiblePages[visiblePages.length - 1]
+        || null;
+      const overlaySelector = [
+        '.dialog.modal-in',
+        '.popup.modal-in',
+        '.sheet-modal.modal-in',
+        '.popover.modal-in',
+        '.actions-modal.modal-in',
+        '.login-screen.modal-in',
+      ].join(',');
+      const visibleOverlays = [...document.querySelectorAll(overlaySelector)].filter(isVisible);
+      const activeOverlay = visibleOverlays[visibleOverlays.length - 1] || null;
+      const overlayType = activeOverlay
+        ? ['dialog', 'popup', 'sheet-modal', 'popover', 'actions-modal', 'login-screen']
+          .find((className) => activeOverlay.classList.contains(className)) || 'overlay'
+        : '';
+      const textSelector = [
+        'h1', 'h2', 'h3',
+        '.title', '.dialog-title', '.dialog-text',
+        'legend', 'strong', '.t-output-choice-heading',
+        '.item-title', '.item-subtitle', '.item-after',
+        'label', 'button', '[role="button"]',
+        'p', 'small', 'option:checked',
+      ].join(',');
+      const pageHeadings = collectUiText(
+        activePage,
+        'h1, h2, h3, .navbar .title, .t-section-heading, .headTitle',
+        10,
+      );
+      const pageControls = collectUiText(
+        activePage,
+        'button, [role="button"], label, .item-title, .item-subtitle, .list-button, option:checked',
+        30,
+      );
+      const overlayText = collectUiText(activeOverlay, textSelector, 35);
+      const pageButtons = collectButtons(activePage, 40);
+      const overlayButtons = collectButtons(activeOverlay, 20);
+      const pageInputs = collectInputs(activePage, 30);
+      const overlayInputs = collectInputs(activeOverlay, 25);
+      const f7Route = activePage?.f7Page?.route
+        || activePage?.f7Page?.router?.currentRoute
+        || null;
+      const framework7Route = f7Route ? {
+        url: normalizeUiText(f7Route.url),
+        path: normalizeUiText(f7Route.path || f7Route.route?.path),
+        name: normalizeUiText(f7Route.name || f7Route.route?.name),
+        params: Object.keys(f7Route.params || {}),
+        query: Object.keys(f7Route.query || {}),
+      } : null;
+      const screenInfo = {
+        documentTitle: normalizeUiText(document.title),
+        route: {
+          pathname: location.pathname,
+          hash: location.hash,
+          framework7: framework7Route,
+        },
+        page: activePage ? {
+          dataName: activePage.getAttribute('data-name') || '',
+          id: activePage.id || '',
+          classes: getStableClasses(activePage),
+          navbarTitle: collectUiText(activePage, '.navbar .title', 1)[0] || '',
+          headings: pageHeadings,
+          sections: collectUiText(
+            activePage,
+            'h1, h2, h3, legend, .t-section-heading, .t-output-choice-heading, .headTitle',
+            20,
+          ),
+          descriptions: collectUiText(
+            activePage,
+            'p, small, .item-subtitle, .item-after, .t-settings-footnote',
+            30,
+          ),
+          controls: pageControls,
+          buttons: pageButtons,
+          primaryButtons: pageButtons.filter((button) => (
+            button.prominence === 'primary' || button.prominence === 'major'
+          )),
+          inputs: pageInputs,
+          obscuredByOverlay: Boolean(activeOverlay),
+        } : null,
+        overlay: activeOverlay ? {
+          type: overlayType,
+          id: activeOverlay.id || '',
+          classes: getStableClasses(activeOverlay),
+          title: collectUiText(activeOverlay, '.dialog-title, .navbar .title, h1, h2, h3', 1)[0] || '',
+          sections: collectUiText(
+            activeOverlay,
+            'h1, h2, h3, legend, strong, .t-section-heading, .t-output-choice-heading',
+            20,
+          ),
+          visibleText: overlayText,
+          buttons: overlayButtons,
+          primaryButtons: overlayButtons.filter((button) => (
+            button.prominence === 'primary' || button.prominence === 'major'
+          )),
+          inputs: overlayInputs,
+        } : null,
+        theme: document.documentElement.classList.contains('theme-dark')
+          || document.body.classList.contains('theme-dark')
+          ? 'dark'
+          : 'light',
+        viewport: {
+          width: innerWidth,
+          height: innerHeight,
+          devicePixelRatio,
+        },
+      };
+
       const serializeDocument = async (sourceDocument) => {
         const clonedRoot = sourceDocument.documentElement.cloneNode(true);
         const originalElements = [
@@ -892,6 +1352,7 @@ async function capturePageSnapshot(client) {
       return {
         html: '<!doctype html>' + html,
         scrollY,
+        screenInfo,
       };
     })()`,
     awaitPromise: true,
@@ -1190,17 +1651,27 @@ async function waitForReplayLayout(client, snapshot) {
 
 function getFrameAdornment(frameType) {
   if (frameType === 'iphone') {
-    return '<div class="dynamic-island"></div>';
+    return '';
   }
 
   if (frameType === 'android-phone') {
-    return '<div class="camera-dot"></div>';
+    return '';
   }
 
   if (frameType === 'tablet') {
     return '<div class="tablet-camera"></div>';
   }
 
+  if (frameType === 'ipad') {
+    return `<div class="ipad-camera-array" aria-hidden="true">
+      <span class="ipad-sensor ipad-sensor-large"></span>
+      <span class="ipad-sensor ipad-sensor-large"></span>
+      <span class="ipad-sensor ipad-sensor-lens"></span>
+      <span class="ipad-sensor ipad-sensor-small"></span>
+      <span class="ipad-sensor ipad-sensor-large"></span>
+    </div><div class="ipad-side-button" aria-hidden="true"></div>`;
+  }
+
   if (frameType === 'tv' || frameType === 'apple-tv') {
     return '<div class="tv-stand"></div>';
   }
@@ -1220,10 +1691,167 @@ function getFrameAdornment(frameType) {
   return '<div class="xr-status"></div>';
 }
 
-function createStoreDeviceFrameHtml(profile, screenshotBuffer, imageWidth, imageHeight, canvasWidth, canvasHeight, imageFormat) {
+async function getScreenshotBarStyle(screenshotBuffer, edge = 'top') {
+  const metadata = await sharp(screenshotBuffer).metadata();
+  const { data, info } = await sharp(screenshotBuffer)
+    .extract({
+      left: 0,
+      top: edge === 'bottom' ? metadata.height - 1 : 0,
+      width: 1,
+      height: 1,
+    })
+    .removeAlpha()
+    .raw()
+    .toBuffer({ resolveWithObject: true });
+  const color = [data[0], data[1], data[2]];
+  const luminance = color
+    .map((value) => value / 255)
+    .map((value) => (value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4))
+    .reduce((total, value, index) => total + value * [0.2126, 0.7152, 0.0722][index], 0);
+
+  if (info.channels < 3) {
+    throw new Error('Unable to read the screenshot starting pixel color.');
+  }
+
+  return {
+    background: `rgb(${color.join(', ')})`,
+    foreground: luminance > 0.179 ? '#050505' : '#ffffff',
+  };
+}
+
+function getScreenshotCopy(screenshotFileName) {
+  screenshotCopyConfig ||= readJsonAssetSource(screenshotCopyPath);
+  const screenshotKey = path.parse(screenshotFileName).name;
+  const configuredCopy = screenshotCopyConfig.screenshots?.[screenshotKey];
+
+  if (!configuredCopy || typeof configuredCopy !== 'object') return null;
+
+  const title = cleanAssetCopy(configuredCopy.title, 56);
+  const subtitle = cleanAssetCopy(configuredCopy.subtitle, 110);
+  const features = Array.isArray(configuredCopy.features)
+    ? configuredCopy.features
+      .map((feature) => cleanAssetCopy(feature, 28))
+      .filter(Boolean)
+      .slice(0, 3)
+    : [];
+
+  if (!title && !subtitle && !features.length) return null;
+
+  return { title, subtitle, features };
+}
+
+function createScreenshotCopyMarkup(screenshotCopy) {
+  if (!screenshotCopy) return '';
+
+  const featureMarkup = screenshotCopy.features
+    .map((feature) => `<span>${escapeHtml(feature)}</span>`)
+    .join('');
+
+  return `<section class="promo-copy">
+    ${screenshotCopy.title ? `<h1>${escapeHtml(screenshotCopy.title)}</h1>` : ''}
+    ${screenshotCopy.subtitle ? `<p>${escapeHtml(screenshotCopy.subtitle)}</p>` : ''}
+    ${featureMarkup ? `<div class="promo-features">${featureMarkup}</div>` : ''}
+  </section>`;
+}
+
+function rgbToHsl(red, green, blue) {
+  const values = [red, green, blue].map((value) => value / 255);
+  const maximum = Math.max(...values);
+  const minimum = Math.min(...values);
+  const lightness = (maximum + minimum) / 2;
+  const delta = maximum - minimum;
+  if (!delta) return { hue: 230, saturation: 0, lightness };
+
+  const saturation = delta / (1 - Math.abs(2 * lightness - 1));
+  let hue;
+  if (maximum === values[0]) hue = 60 * (((values[1] - values[2]) / delta) % 6);
+  else if (maximum === values[1]) hue = 60 * ((values[2] - values[0]) / delta + 2);
+  else hue = 60 * ((values[0] - values[1]) / delta + 4);
+  return { hue: (hue + 360) % 360, saturation, lightness };
+}
+
+async function getPromotionalPalette(screenshotBuffer, screenshotFileName) {
+  const { data, info } = await sharp(screenshotBuffer)
+    .resize(36, 36, { fit: 'fill' })
+    .removeAlpha()
+    .raw()
+    .toBuffer({ resolveWithObject: true });
+  const colorBuckets = new Map();
+
+  for (let index = 0; index < data.length; index += info.channels) {
+    const red = data[index];
+    const green = data[index + 1];
+    const blue = data[index + 2];
+    const hsl = rgbToHsl(red, green, blue);
+    if (hsl.lightness < 0.1 || hsl.lightness > 0.94 || hsl.saturation < 0.12) continue;
+    const key = `${Math.round(red / 24)},${Math.round(green / 24)},${Math.round(blue / 24)}`;
+    const bucket = colorBuckets.get(key) || {
+      count: 0, red: 0, green: 0, blue: 0, saturation: 0, lightness: 0,
+    };
+    bucket.count += 1;
+    bucket.red += red;
+    bucket.green += green;
+    bucket.blue += blue;
+    bucket.saturation += hsl.saturation;
+    bucket.lightness += hsl.lightness;
+    colorBuckets.set(key, bucket);
+  }
+
+  let selectedColor = { red: 85, green: 70, blue: 232 };
+  let selectedScore = -1;
+  for (const bucket of colorBuckets.values()) {
+    const saturation = bucket.saturation / bucket.count;
+    const lightness = bucket.lightness / bucket.count;
+    const score = bucket.count * (0.55 + saturation * 1.8)
+      * (1 - Math.abs(lightness - 0.55) * 0.7);
+    if (score <= selectedScore) continue;
+    selectedScore = score;
+    selectedColor = {
+      red: Math.round(bucket.red / bucket.count),
+      green: Math.round(bucket.green / bucket.count),
+      blue: Math.round(bucket.blue / bucket.count),
+    };
+  }
+
+  const seed = getDecorationSeed(path.parse(screenshotFileName).name);
+  const sourceHsl = rgbToHsl(selectedColor.red, selectedColor.green, selectedColor.blue);
+  const hue = Math.round((sourceHsl.hue + (seed % 25) - 12 + 360) % 360);
+  const secondaryHue = (hue + [38, 56, 142, 205][seed % 4]) % 360;
+  const saturation = Math.max(58, Math.min(82, Math.round(sourceHsl.saturation * 100)));
+
+  return {
+    seed,
+    accent: `hsl(${hue} ${saturation}% 46%)`,
+    accentSoft: `hsla(${hue} ${saturation}% 55% / 0.2)`,
+    secondary: `hsl(${secondaryHue} 70% 54%)`,
+    secondarySoft: `hsla(${secondaryHue} 72% 58% / 0.18)`,
+    backgroundStart: `hsl(${hue} 68% 97%)`,
+    backgroundMiddle: `hsl(${(hue + 14) % 360} 58% 93%)`,
+    backgroundEnd: `hsl(${secondaryHue} 62% 88%)`,
+    text: `hsl(${hue} 35% 17%)`,
+    mutedText: `hsl(${hue} 18% 38%)`,
+  };
+}
+
+function createStoreDeviceFrameHtml(
+  profile,
+  screenshotBuffer,
+  imageWidth,
+  imageHeight,
+  canvasWidth,
+  canvasHeight,
+  imageFormat,
+  displayTime,
+  batteryPercentage,
+  statusBarStyle,
+  navigationBarStyle,
+  screenshotCopy,
+  palette,
+) {
   const screenshotDataUrl = `data:image/${imageFormat === 'jpeg' ? 'jpeg' : 'png'};base64,${screenshotBuffer.toString('base64')}`;
-  const screenWidth = Math.floor(Math.min(canvasWidth - 160, (canvasHeight - 180) * imageWidth / imageHeight));
-  const accent = profile.name === 'oppo-store' ? '#76e4c2' : '#9daaff';
+  const availableDeviceHeight = screenshotCopy ? canvasHeight * 0.64 : canvasHeight - 180;
+  const screenWidth = Math.floor(Math.min(canvasWidth - 160, availableDeviceHeight * imageWidth / imageHeight));
+  const frameStyle = frameStyles.android[selectedFrameStyles.android];
 
   return `<!doctype html>
 <html>
@@ -1235,34 +1863,67 @@ function createStoreDeviceFrameHtml(profile, screenshotBuffer, imageWidth, image
     body {
       display: grid;
       place-items: center;
-      background: radial-gradient(ellipse at 50% 43%, #24344d 0%, #101b2d 47%, #070e1a 100%);
+      position: relative;
+      background:
+        radial-gradient(circle at 12% 16%, ${palette.accentSoft}, transparent 32%),
+        radial-gradient(circle at 88% 84%, ${palette.secondarySoft}, transparent 34%),
+        linear-gradient(145deg, ${palette.backgroundStart}, ${palette.backgroundMiddle} 52%, ${palette.backgroundEnd});
     }
     body::before {
       content: '';
       position: absolute;
-      width: 82%;
-      height: 62%;
-      border-radius: 50%;
-      background: ${accent};
-      opacity: 0.11;
-      filter: blur(90px);
+      inset: 0;
+      opacity: 0.16;
+      background-image: radial-gradient(${palette.accent} 1px, transparent 1px);
+      background-size: 28px 28px;
+      mask-image: linear-gradient(135deg, black, transparent 42%, transparent 64%, black);
     }
+    ${getPromotionalDecorationStyles()}
+    .promo-copy {
+      position: absolute;
+      z-index: 2;
+      top: 4.5%;
+      right: 7%;
+      left: 7%;
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      color: ${palette.text};
+      text-align: center;
+      font-family: Arial, sans-serif;
+    }
+    .promo-copy h1 { max-width: 900px; margin: 0; font-size: clamp(42px, 5.6vw, 72px); line-height: 1.02; letter-spacing: -0.035em; }
+    .promo-copy p { max-width: 850px; margin: 2.1% 0 0; color: ${palette.mutedText}; font-size: clamp(22px, 2.5vw, 32px); line-height: 1.35; }
+    .promo-features { display: flex; flex-wrap: wrap; justify-content: center; gap: 12px; margin-top: 2.4%; }
+    .promo-features span { padding: 10px 17px; border: 1px solid ${palette.accentSoft}; border-radius: 999px; background: rgba(255,255,255,0.72); color: ${palette.accent}; box-shadow: 0 8px 24px rgba(15,23,42,0.08); font: 700 clamp(16px, 1.8vw, 23px)/1 Arial, sans-serif; }
+    body.has-copy .device { position: absolute; bottom: 3.5%; left: 50%; transform: translateX(-50%); }
     .device {
       position: relative;
       z-index: 1;
       width: ${screenWidth + 48}px;
       padding: 34px 18px 20px;
-      border: 6px solid #8d99ac;
+      border: 6px solid ${frameStyle.edge};
       border-radius: 48px;
-      background: linear-gradient(135deg, #404c60, #111925 35%, #070c15 72%, #59657a);
+      background: ${frameStyle.outer};
       box-shadow: 0 38px 85px rgba(0, 0, 0, 0.58), 0 0 0 2px rgba(255, 255, 255, 0.19) inset;
     }
     .screen {
+      display: flex;
+      flex-direction: column;
       width: ${screenWidth}px;
+      aspect-ratio: ${imageWidth} / ${imageHeight};
+      overflow: hidden;
       background: #fff;
       box-shadow: 0 0 0 2px #03060c;
     }
-    .screen img { display: block; width: 100%; height: auto; }
+    .screen img { display: block; width: 100%; height: 0; min-height: 0; flex: 1 1 0; object-fit: fill; }
+    .phone-statusbar { position: relative; flex: none; height: 5%; display: flex; align-items: center; background: ${statusBarStyle.background}; color: ${statusBarStyle.foreground}; font-family: Arial, sans-serif; }
+    .status-time { margin-left: 5%; font-size: ${Math.max(11, Math.round(screenWidth * 0.03))}px; white-space: nowrap; }
+    .android-statusbar { height: 4%; font-family: Roboto, Arial, sans-serif; }
+    .android-notification { width: 3.4%; height: 46%; margin-left: 2%; }
+    .android-status-icons { width: 32%; height: 58%; margin-left: auto; margin-right: 4%; }
+    .android-navigation { position: absolute; z-index: 2; right: 0; bottom: 0; left: 0; height: 2.2%; display: grid; place-items: center; background: transparent; }
+    .gesture-pill { width: 40%; height: 14%; border-radius: 999px; background: ${navigationBarStyle.foreground}; }
     .camera {
       position: absolute;
       top: 11px;
@@ -1285,19 +1946,112 @@ function createStoreDeviceFrameHtml(profile, screenshotBuffer, imageWidth, image
     }
   </style>
 </head>
-<body>
+<body class="${screenshotCopy ? 'has-copy' : ''}">
+  ${createPromotionalDecorations(palette)}
+  ${createScreenshotCopyMarkup(screenshotCopy)}
   <main class="device">
     <div class="camera"></div>
-    <div class="screen"><img src="${screenshotDataUrl}" /></div>
+    <div class="screen">${getPhoneStatusBar('android', displayTime, batteryPercentage)}<img src="${screenshotDataUrl}" /><div class="android-navigation"><div class="gesture-pill"></div></div></div>
     <div class="side-button"></div>
   </main>
 </body>
 </html>`;
 }
 
-function createDeviceFrameHtml(profile, screenshotBuffer, imageWidth = profile.width, imageHeight = profile.height, imageFormat = 'png') {
+function getPhoneStatusBar(platform, time, batteryPercentage = null) {
+  const batteryLevel = Number.isInteger(batteryPercentage) ? batteryPercentage : 75;
+
+  if (platform === 'ios') {
+    return `<div class="phone-statusbar ios-statusbar">
+      <span class="status-time">${time}</span>
+      <div class="dynamic-island"></div>
+      <svg viewBox="0 0 90 28" aria-hidden="true">
+        <circle cx="5" cy="14" r="2" fill="currentColor" opacity="0.35"></circle><circle cx="13" cy="14" r="2" fill="currentColor" opacity="0.35"></circle>
+        <circle cx="21" cy="14" r="2" fill="currentColor" opacity="0.35"></circle><circle cx="29" cy="14" r="2" fill="currentColor" opacity="0.35"></circle>
+        <path d="M36 10 Q46 2 56 10 M39 14 Q46 8 53 14 M44 18 Q46 16 48 18" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round"></path>
+        <rect x="61" y="7" width="22" height="15" rx="4" fill="none" stroke="currentColor" stroke-width="1.5" opacity="0.65"></rect>
+        <rect x="64" y="10" width="16" height="9" rx="2" fill="currentColor"></rect>
+        <rect x="85" y="12" width="2" height="5" rx="1" fill="currentColor" opacity="0.65"></rect>
+      </svg>
+    </div>`;
+  }
+
+  if (platform === 'ipad') {
+    const batteryFillWidth = Math.max(2, Math.round(24 * batteryLevel / 100));
+    return `<div class="phone-statusbar ipad-statusbar">
+      <span class="status-time">${time}</span>
+      <svg class="ipad-status-icons" viewBox="0 0 130 28" aria-hidden="true">
+        <g fill="currentColor">
+          <rect x="2" y="19" width="3" height="5" rx="1"></rect>
+          <rect x="7" y="15" width="3" height="9" rx="1"></rect>
+          <rect x="12" y="11" width="3" height="13" rx="1"></rect>
+          <rect x="17" y="7" width="3" height="17" rx="1"></rect>
+        </g>
+        <path d="M28 10 Q38 2 48 10 M31 14 Q38 8 45 14 M36 18 Q38 16 40 18" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round"></path>
+        <circle cx="38" cy="21" r="1.7" fill="currentColor"></circle>
+        <text x="54" y="20" font-size="12" font-weight="600" fill="currentColor">${batteryLevel}%</text>
+        <rect x="88" y="6" width="32" height="17" rx="4" fill="none" stroke="currentColor" stroke-width="1.6"></rect>
+        <rect x="91" y="9" width="${batteryFillWidth}" height="11" rx="2" fill="currentColor" opacity="0.72"></rect>
+        <rect x="122" y="11" width="3" height="7" rx="1.5" fill="currentColor"></rect>
+      </svg>
+    </div>`;
+  }
+
+  const batteryFillWidth = Math.max(2, Math.round(30 * batteryLevel / 100));
+
+  return `<div class="phone-statusbar android-statusbar">
+    <span class="status-time">${time}</span>
+    <svg class="android-notification" viewBox="0 0 24 24" aria-hidden="true">
+      <circle cx="12" cy="12" r="9.5" fill="none" stroke="currentColor" stroke-width="1.8"></circle>
+      <circle cx="8" cy="10" r="1.3" fill="currentColor"></circle>
+      <circle cx="12" cy="8" r="1.3" fill="currentColor"></circle>
+      <circle cx="16" cy="10" r="1.3" fill="currentColor"></circle>
+      <path d="M7.5 14 Q12 18 16.5 14" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"></path>
+    </svg>
+    <svg class="android-status-icons" viewBox="0 0 200 28" aria-hidden="true">
+      <g fill="currentColor">
+        <rect x="1" y="20" width="5" height="5" rx="1"></rect><rect x="8" y="16" width="5" height="9" rx="1"></rect>
+        <rect x="15" y="12" width="5" height="13" rx="1"></rect><rect x="22" y="8" width="5" height="17" rx="1"></rect><rect x="29" y="4" width="5" height="21" rx="1"></rect>
+        <rect x="43" y="20" width="5" height="5" rx="1"></rect><rect x="50" y="16" width="5" height="9" rx="1"></rect>
+        <rect x="57" y="12" width="5" height="13" rx="1"></rect><rect x="64" y="8" width="5" height="17" rx="1"></rect><rect x="71" y="4" width="5" height="21" rx="1"></rect>
+      </g>
+      <path d="M86 9 Q99 -1 112 9 M90 14 Q99 7 108 14 M95 19 Q99 16 103 19" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round"></path>
+      <circle cx="99" cy="22" r="2" fill="currentColor"></circle>
+      <text x="108" y="24" font-size="7" font-weight="700" fill="currentColor">6</text>
+      <rect x="121" y="4" width="39" height="21" rx="5" fill="none" stroke="currentColor" stroke-width="2"></rect>
+      <rect x="125" y="8" width="${batteryFillWidth}" height="13" rx="2" fill="currentColor" opacity="0.65"></rect>
+      <rect x="162" y="10" width="3" height="9" rx="1.5" fill="currentColor"></rect>
+      <text x="169" y="21" font-size="13" font-weight="500" fill="currentColor">${batteryLevel}%</text>
+    </svg>
+  </div>`;
+}
+
+function createDeviceFrameHtml(
+  profile,
+  screenshotBuffer,
+  imageWidth = profile.width,
+  imageHeight = profile.height,
+  imageFormat = 'png',
+  displayTime = '',
+  batteryPercentage = null,
+  statusBarStyle = null,
+  navigationBarStyle = null,
+  screenshotCopy = null,
+  palette,
+) {
   const screenshotDataUrl = `data:image/${imageFormat === 'jpeg' ? 'jpeg' : 'png'};base64,${screenshotBuffer.toString('base64')}`;
   const aspectRatio = `${imageWidth} / ${imageHeight}`;
+  const phonePlatform = profile.frameType === 'iphone' ? 'ios' : profile.frameType === 'android-phone' ? 'android' : null;
+  const statusBarPlatform = profile.frameType === 'ipad' ? 'ipad' : phonePlatform;
+  const phoneStyle = phonePlatform && frameStyles[phonePlatform][selectedFrameStyles[phonePlatform]];
+  const phoneStatusBar = statusBarPlatform
+    ? getPhoneStatusBar(statusBarPlatform, displayTime, batteryPercentage)
+    : '';
+  const phoneNavigation = phonePlatform === 'android'
+    ? '<div class="android-navigation"><div class="gesture-pill"></div></div>'
+    : statusBarPlatform === 'ios' || statusBarPlatform === 'ipad'
+      ? `<div class="ios-navigation${statusBarPlatform === 'ipad' ? ' ipad-navigation' : ''}"><div class="ios-gesture-pill"></div></div>`
+      : '';
 
   return `<!doctype html>
 <html>
@@ -1311,22 +2065,33 @@ function createDeviceFrameHtml(profile, screenshotBuffer, imageWidth = profile.w
       place-items: center;
       position: relative;
       background:
-        radial-gradient(circle at 14% 18%, rgba(45, 213, 255, 0.24), transparent 30%),
-        radial-gradient(circle at 86% 82%, rgba(196, 255, 61, 0.16), transparent 28%),
-        linear-gradient(145deg, #111827 0%, #070b12 52%, #020409 100%);
+        radial-gradient(circle at 12% 16%, ${palette.accentSoft}, transparent 32%),
+        radial-gradient(circle at 88% 84%, ${palette.secondarySoft}, transparent 34%),
+        linear-gradient(145deg, ${palette.backgroundStart}, ${palette.backgroundMiddle} 52%, ${palette.backgroundEnd});
       font-family: Arial, sans-serif;
     }
     body::before {
       content: '';
       position: absolute;
       inset: 0;
-      opacity: 0.18;
-      background-image:
-        linear-gradient(rgba(255,255,255,0.045) 1px, transparent 1px),
-        linear-gradient(90deg, rgba(255,255,255,0.045) 1px, transparent 1px);
-      background-size: 7vw 7vw;
-      mask-image: linear-gradient(to bottom, transparent, black 28%, black 72%, transparent);
+      opacity: 0.16;
+      background-image: radial-gradient(${palette.accent} 0.8px, transparent 0.8px);
+      background-size: clamp(18px, 2.2vw, 34px) clamp(18px, 2.2vw, 34px);
+      mask-image: linear-gradient(135deg, black, transparent 42%, transparent 64%, black);
+    }
+    ${getPromotionalDecorationStyles()}
+    .promo-copy {
+      position: absolute;
+      z-index: 4;
+      display: flex;
+      flex-direction: column;
+      color: ${palette.text};
+      font-family: Arial, sans-serif;
     }
+    .promo-copy h1 { margin: 0; font-size: clamp(24px, 5.4vw, 82px); line-height: 1.02; letter-spacing: -0.04em; }
+    .promo-copy p { margin: 1.8vh 0 0; color: ${palette.mutedText}; font-size: clamp(14px, 2.1vw, 34px); line-height: 1.35; }
+    .promo-features { display: flex; flex-wrap: wrap; gap: clamp(6px, 0.9vw, 16px); margin-top: 2vh; }
+    .promo-features span { padding: clamp(6px, 0.75vw, 13px) clamp(9px, 1.2vw, 20px); border: 1px solid ${palette.accentSoft}; border-radius: 999px; background: rgba(255,255,255,0.72); color: ${palette.accent}; box-shadow: 0 0.5vh 1.8vh rgba(15,23,42,0.08); font-size: clamp(11px, 1.45vw, 23px); font-weight: 700; line-height: 1; }
     .device {
       position: relative;
       z-index: 1;
@@ -1338,10 +2103,13 @@ function createDeviceFrameHtml(profile, screenshotBuffer, imageWidth = profile.w
         0 0 0 1px rgba(255, 255, 255, 0.18) inset,
         0 0 5vh rgba(45, 213, 255, 0.12);
     }
+    .device:not(.android-phone):not(.iphone) {
+      box-sizing: content-box;
+    }
     .screen {
       position: relative;
       width: 100%;
-      height: 87%;
+      height: 100%;
       overflow: hidden;
       background: #f5f7fc;
       box-shadow: 0 0 0 1px rgba(0, 0, 0, 0.95) inset;
@@ -1355,14 +2123,86 @@ function createDeviceFrameHtml(profile, screenshotBuffer, imageWidth = profile.w
     }
     .device.android-phone,
     .device.iphone {
-      height: 100%;
-      padding: 1.25%;
+      height: 84%;
+      padding: 2.5%;
       border-radius: clamp(24px, 8vw, 70px);
     }
-    .device.android-phone .screen,
-    .device.iphone .screen {
-      border-radius: clamp(19px, 6.7vw, 60px);
+    ${phoneStyle ? `
+    .device.${profile.frameType} {
+      background: ${phoneStyle.outer};
+      border-color: ${phoneStyle.edge};
+      border-radius: calc(84vh * ${imageWidth / imageHeight * phoneStyle.radius / 340});
+      box-shadow: 0 4vh 9vh rgba(0, 0, 0, 0.48), 0 0 0 0.55vw ${phoneStyle.inner} inset;
+    }
+    .device.${profile.frameType} .screen {
+      display: flex;
+      flex-direction: column;
+      height: 100%;
+      border-radius: calc(84vh * ${imageWidth / imageHeight * phoneStyle.radius / 340} - 2.5vw - clamp(2px, 0.45vw, 9px));
     }
+    .device.${profile.frameType} .screen img {
+      flex: 1 1 0;
+      min-height: 0;
+      object-fit: fill;
+    }` : ''}
+    .phone-statusbar {
+      position: relative;
+      z-index: 2;
+      flex: none;
+      height: 5%;
+      display: flex;
+      align-items: center;
+      font-family: Arial, sans-serif;
+    }
+    .status-time {
+      margin-left: 5%;
+      font-size: clamp(11px, 3vw, 40px);
+      white-space: nowrap;
+    }
+    .ios-statusbar { background: ${statusBarStyle?.background || 'transparent'}; color: ${statusBarStyle?.foreground || '#050505'}; font-weight: 700; }
+    .ios-statusbar svg { width: 27%; height: 62%; margin-left: auto; margin-right: 3%; }
+    .ios-statusbar .dynamic-island {
+      position: absolute;
+      top: 22%;
+      left: 50%;
+      width: 25%;
+      height: 56%;
+      transform: translateX(-50%);
+      border-radius: 999px;
+      background: #000;
+    }
+    .android-statusbar { height: 4%; background: ${statusBarStyle?.background || 'transparent'}; color: ${statusBarStyle?.foreground || '#050505'}; font-family: Roboto, Arial, sans-serif; }
+    .android-notification { width: 3.4%; height: 46%; margin-left: 2%; }
+    .android-status-icons { width: 32%; height: 58%; margin-left: auto; margin-right: 4%; }
+    .android-navigation {
+      position: absolute;
+      z-index: 2;
+      right: 0;
+      bottom: 0;
+      left: 0;
+      height: 2.2%;
+      display: grid;
+      place-items: center;
+      background: transparent;
+    }
+    .gesture-pill { width: 40%; height: 14%; border-radius: 999px; background: ${navigationBarStyle?.foreground || '#7a7b7c'}; }
+    .ios-navigation {
+      position: relative;
+      z-index: 2;
+      flex: none;
+      height: 2.2%;
+      display: grid;
+      place-items: center;
+      background: ${navigationBarStyle?.background || 'transparent'};
+    }
+    .ios-gesture-pill {
+      width: 36%;
+      height: clamp(3px, 0.42vw, 8px);
+      border-radius: 999px;
+      background: ${navigationBarStyle?.foreground || '#050505'};
+    }
+    .ipad-navigation { height: 1.8%; }
+    .ipad-navigation .ios-gesture-pill { width: 24%; }
     .camera-dot {
       position: absolute;
       z-index: 3;
@@ -1395,6 +2235,85 @@ function createDeviceFrameHtml(profile, screenshotBuffer, imageWidth = profile.w
     .device.tablet .screen {
       border-radius: clamp(13px, 2.5vw, 38px);
     }
+    .device.ipad {
+      height: 86%;
+      padding: 4.1%;
+      border: clamp(2px, 0.34vw, 7px) solid #9da3ad;
+      border-radius: clamp(32px, 5.2vw, 84px);
+      background: linear-gradient(145deg, #24272c 0%, #0b0c0e 22%, #050506 70%, #17191c 100%);
+      box-shadow:
+        0 4vh 9vh rgba(0, 0, 0, 0.62),
+        0 0 0 clamp(1px, 0.16vw, 3px) rgba(230, 233, 238, 0.42) inset,
+        0 0 0 clamp(3px, 0.45vw, 9px) rgba(0, 0, 0, 0.82) inset;
+    }
+    .device.ipad .screen {
+      display: flex;
+      flex-direction: column;
+      border: clamp(2px, 0.25vw, 5px) solid #181a1e;
+      border-radius: clamp(20px, 3.4vw, 55px);
+      background: #000;
+      box-shadow: 0 0 0 1px rgba(255,255,255,0.05), 0 0 1.4vh rgba(0,0,0,0.9) inset;
+    }
+    .device.ipad .screen img {
+      flex: 1 1 0;
+      min-height: 0;
+      height: 0;
+      object-fit: fill;
+    }
+    .ipad-statusbar {
+      height: 3.2%;
+      background: ${statusBarStyle?.background || 'transparent'};
+      color: ${statusBarStyle?.foreground || '#050505'};
+      font-weight: 700;
+    }
+    .ipad-statusbar .status-time {
+      margin-left: 2.2%;
+      font-size: clamp(9px, 1.18vw, 22px);
+    }
+    .ipad-status-icons {
+      width: 17%;
+      height: 58%;
+      margin-left: auto;
+      margin-right: 1.8%;
+    }
+    .ipad-camera-array {
+      position: absolute;
+      z-index: 3;
+      top: 1.05%;
+      left: 50%;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      gap: clamp(4px, 0.62vw, 12px);
+      width: 18%;
+      height: 1.65%;
+      transform: translateX(-50%);
+    }
+    .ipad-sensor {
+      display: block;
+      flex: none;
+      border-radius: 50%;
+      background: #020304;
+      box-shadow: 0 0 0 1px rgba(29,33,39,0.9), 0 0 0.35vh rgba(0,0,0,0.85) inset;
+    }
+    .ipad-sensor-large { width: clamp(5px, 1vw, 17px); aspect-ratio: 1; }
+    .ipad-sensor-small { width: clamp(3px, 0.38vw, 7px); aspect-ratio: 1; }
+    .ipad-sensor-lens {
+      width: clamp(4px, 0.62vw, 11px);
+      aspect-ratio: 1;
+      background: radial-gradient(circle at 38% 35%, #355e8a, #07101d 42%, #010205 75%);
+      box-shadow: 0 0 0 1px #121a26, 0 0 0.45vh rgba(42,110,202,0.45);
+    }
+    .ipad-side-button {
+      position: absolute;
+      top: 7.6%;
+      right: -0.45%;
+      width: 0.45%;
+      height: 7.8%;
+      border-radius: 0 999px 999px 0;
+      background: linear-gradient(90deg, #4c5159, #a9afb7 58%, #555b64);
+      box-shadow: 0 0.3vh 0.7vh rgba(0,0,0,0.5);
+    }
     .device.apple-watch {
       height: 82%;
       padding: 2.2%;
@@ -1526,11 +2445,51 @@ function createDeviceFrameHtml(profile, screenshotBuffer, imageWidth = profile.w
       background: #6fe8ff;
       box-shadow: 0 0 1.8vh #2dd5ff;
     }
+    @media (orientation: portrait) {
+      body.has-copy .promo-copy { top: 4%; right: 7%; left: 7%; align-items: center; text-align: center; }
+      body.has-copy .promo-copy h1 { max-width: 90%; }
+      body.has-copy .promo-copy p { max-width: 86%; }
+      body.has-copy .promo-features { justify-content: center; }
+      body.has-copy .device,
+      body.has-copy .device.android-phone,
+      body.has-copy .device.iphone,
+      body.has-copy .device.tablet,
+      body.has-copy .device.apple-watch {
+        position: absolute;
+        bottom: 3%;
+        left: 50%;
+        width: auto;
+        height: 68%;
+        transform: translateX(-50%);
+      }
+    }
+    @media (orientation: landscape) {
+      body.has-copy .promo-copy { top: 50%; left: 5%; width: 31%; transform: translateY(-50%); }
+      body.has-copy .promo-copy h1 { font-size: clamp(28px, 4.4vw, 84px); }
+      body.has-copy .promo-copy p { font-size: clamp(16px, 1.7vw, 32px); }
+      body.has-copy .device,
+      body.has-copy .device.tv,
+      body.has-copy .device.apple-tv,
+      body.has-copy .device.laptop,
+      body.has-copy .device.xr,
+      body.has-copy .device.apple-vision-pro {
+        position: absolute;
+        top: 50%;
+        right: 3%;
+        left: auto;
+        width: 60%;
+        height: auto;
+        max-height: 84%;
+        transform: translateY(-50%);
+      }
+    }
   </style>
 </head>
-<body>
+<body class="${phonePlatform ? 'phone-frame' : ''} ${screenshotCopy ? 'has-copy' : ''}">
+  ${createPromotionalDecorations(palette)}
+  ${createScreenshotCopyMarkup(screenshotCopy)}
   <main class="device ${profile.frameType}">
-    <div class="screen"><img src="${screenshotDataUrl}" /></div>
+    <div class="screen">${phoneStatusBar}<img src="${screenshotDataUrl}" />${phoneNavigation}</div>
     ${getFrameAdornment(profile.frameType)}
   </main>
 </body>
@@ -1570,6 +2529,88 @@ function readJsonAssetSource(filePath) {
   }
 }
 
+function getScreenshotSourceDetails(screenInfo) {
+  const pageDirectory = path.join(__dirname, 'src', 'pages');
+  const routesPath = path.join(__dirname, 'src', 'js', 'routes.js');
+  const pageName = String(screenInfo?.page?.dataName || '').trim();
+  const pageId = String(screenInfo?.page?.id || '').trim();
+  const escapePattern = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const pageFiles = [];
+
+  if (fs.existsSync(pageDirectory) && (pageName || pageId)) {
+    for (const fileName of fs.readdirSync(pageDirectory).filter((name) => /\.(?:f7|html)$/i.test(name))) {
+      const filePath = path.join(pageDirectory, fileName);
+      const source = fs.readFileSync(filePath, 'utf8');
+      const hasPageName = pageName
+        && new RegExp(`data-name=["']${escapePattern(pageName)}["']`).test(source);
+      const hasPageId = pageId
+        && new RegExp(`id=["']${escapePattern(pageId)}["']`).test(source);
+      if (hasPageName || hasPageId) {
+        pageFiles.push(path.relative(__dirname, filePath).replace(/\\/g, '/'));
+      }
+    }
+  }
+
+  const routeCandidates = [];
+  if (fs.existsSync(routesPath)) {
+    const routesSource = fs.readFileSync(routesPath, 'utf8');
+    const staticImports = new Map();
+    const staticImportPattern = /import\s+([A-Za-z_$][\w$]*)\s+from\s+["']\.\.\/pages\/([^"']+)["']/g;
+    let match;
+    while ((match = staticImportPattern.exec(routesSource))) {
+      staticImports.set(match[1], `src/pages/${match[2]}`);
+    }
+
+    const routeBlockPattern = /\{\s*path:\s*["']([^"']+)["']([\s\S]*?)\n\s*\},/g;
+    while ((match = routeBlockPattern.exec(routesSource))) {
+      const routePath = match[1];
+      const block = match[2];
+      const dynamicPage = block.match(/import\(["']\.\.\/pages\/([^"']+)["']\)/)?.[1];
+      const componentName = block.match(/component:\s*([A-Za-z_$][\w$]*)/)?.[1];
+      const pageFile = dynamicPage
+        ? `src/pages/${dynamicPage}`
+        : staticImports.get(componentName) || '';
+      const normalizedPageFile = pageFile.replace(/\\/g, '/');
+      const routeMatchesPage = normalizedPageFile
+        && pageFiles.some((candidate) => candidate.toLowerCase() === normalizedPageFile.toLowerCase());
+      const framework7Path = screenInfo?.route?.framework7?.path;
+      const framework7Url = screenInfo?.route?.framework7?.url;
+      if (routeMatchesPage || routePath === framework7Path || routePath === framework7Url) {
+        routeCandidates.push({ path: routePath, pageFile: normalizedPageFile });
+      }
+    }
+  }
+
+  return {
+    pageFiles,
+    routesFile: fs.existsSync(routesPath) ? 'src/js/routes.js' : '',
+    routeCandidates,
+  };
+}
+
+function saveScreenshotInfo(screenshotFileName, screenInfo) {
+  const screenshotKey = path.parse(screenshotFileName).name;
+  const source = readJsonAssetSource(screenshotInfoPath);
+  const screenshots = source.screenshots && typeof source.screenshots === 'object'
+    ? source.screenshots
+    : {};
+
+  screenshots[screenshotKey] = {
+    schemaVersion: 2,
+    fileName: screenshotFileName,
+    capturedAt: new Date().toISOString(),
+    ...screenInfo,
+    source: getScreenshotSourceDetails(screenInfo),
+  };
+
+  fs.mkdirSync(path.dirname(screenshotInfoPath), { recursive: true });
+  fs.writeFileSync(
+    screenshotInfoPath,
+    `${JSON.stringify({ version: 2, screenshots }, null, 2)}\n`,
+  );
+  console.log(`Saved screenshot information: ${screenshotInfoPath} (${screenshotKey})`);
+}
+
 function collectProjectUiPhrases() {
   const phrases = [];
   const pageDirectory = path.join(__dirname, 'src', 'pages');
@@ -2171,24 +3212,48 @@ async function captureFramedScreenshot(
   profile,
   screenshotFileName,
   skipExisting = false,
+  outputRootDirectory = inFrameDirectory,
 ) {
   if (profile.screenshotOnly) return false;
 
-  const framedProfileDirectory = path.join(inFrameDirectory, profile.outputDirectory);
-  const framedScreenshotPath = path.join(framedProfileDirectory, screenshotFileName);
+  const outputExtension = profile.outputExtension || path.extname(screenshotFileName).slice(1) || 'png';
+  const outputFileName = `${path.parse(screenshotFileName).name}.${outputExtension}`;
+  const framedProfileDirectory = path.join(outputRootDirectory, profile.outputDirectory);
+  const framedScreenshotPath = path.join(framedProfileDirectory, outputFileName);
 
   if (skipExisting && fs.existsSync(framedScreenshotPath)) {
     console.log(`Skipped existing framed screenshot: ${framedScreenshotPath}`);
     return false;
   }
 
-  const originalImageMetadata = profile.storeRequirements
-    ? await sharp(screenshotBuffer).metadata()
-    : null;
+  const originalImageMetadata = await sharp(screenshotBuffer).metadata();
   const hasCustomFrameSize = Boolean(profile.framedWidth && profile.framedHeight);
   const frameWidth = profile.framedWidth || profile.width;
   const frameHeight = profile.framedHeight || profile.height;
   const frameScaleFactor = hasCustomFrameSize ? 1 : profile.deviceScaleFactor;
+  const phonePlatform = profile.frameType === 'iphone' ? 'ios' : profile.frameType === 'android-phone' ? 'android' : null;
+  const statusBarPlatform = profile.frameType === 'ipad' ? 'ipad' : phonePlatform;
+  const displayTime = statusBarPlatform ? getFrameDisplayTime(statusBarPlatform) : '';
+  const batteryPercentage = statusBarPlatform === 'android' || statusBarPlatform === 'ipad'
+    ? getFrameBatteryPercentage()
+    : null;
+  const statusBarStyle = statusBarPlatform
+    ? await getScreenshotBarStyle(screenshotBuffer)
+    : null;
+  const navigationBarStyle = statusBarPlatform
+    ? await getScreenshotBarStyle(screenshotBuffer, 'bottom')
+    : null;
+  const screenshotCopy = getScreenshotCopy(screenshotFileName);
+  const promotionalPalette = await getPromotionalPalette(screenshotBuffer, screenshotFileName);
+  const screenshotKey = path.parse(screenshotFileName).name;
+
+  if (!screenshotCopy && !missingScreenshotCopyWarnings.has(screenshotKey)) {
+    missingScreenshotCopyWarnings.add(screenshotKey);
+    console.warn(
+      `No promotional copy configured for screenshot ${screenshotKey}; `
+      + `add it to ${screenshotCopyPath}.`,
+    );
+  }
 
   await client.send('Emulation.setDeviceMetricsOverride', {
     width: frameWidth,
@@ -2207,9 +3272,16 @@ async function captureFramedScreenshot(
     html: profile.name === 'vivo-store' || profile.name === 'oppo-store'
       ? createStoreDeviceFrameHtml(
         profile, screenshotBuffer, originalImageMetadata.width, originalImageMetadata.height,
-        frameWidth, frameHeight, originalImageMetadata.format,
+        frameWidth, frameHeight, originalImageMetadata.format, displayTime,
+        batteryPercentage, statusBarStyle, navigationBarStyle,
+        screenshotCopy, promotionalPalette,
       )
-      : createDeviceFrameHtml(profile, screenshotBuffer, frameWidth, frameHeight),
+      : createDeviceFrameHtml(
+        profile, screenshotBuffer, originalImageMetadata.width, originalImageMetadata.height,
+        originalImageMetadata.format,
+        displayTime, batteryPercentage, statusBarStyle, navigationBarStyle,
+        screenshotCopy, promotionalPalette,
+      ),
   });
   await client.send('Runtime.evaluate', {
     expression: `new Promise((resolve) => {
@@ -2331,25 +3403,10 @@ async function captureScreenshotSet(
   selectedProfiles,
   fileNameInput,
 ) {
-  const storeProfile = selectedProfiles.find((profile) => profile.storeRequirements);
-  if (storeProfile) {
-    const profileDirectory = path.join(screenshotDirectory, storeProfile.outputDirectory);
-    const existingImageCount = fs.existsSync(profileDirectory)
-      ? fs.readdirSync(profileDirectory, { withFileTypes: true })
-        .filter((entry) => entry.isFile() && /\.(png|jpe?g|webp)$/i.test(entry.name))
-        .length
-      : 0;
-
-    if (existingImageCount >= storeProfile.storeRequirements.maxImages) {
-      throw new Error(
-        `${storeProfile.label} already contains ${existingImageCount} images; the store allows a maximum of ${storeProfile.storeRequirements.maxImages}.`,
-      );
-    }
-  }
-
   console.log('Capturing the current rendered page and resolved native data...');
   const snapshot = await capturePageSnapshot(deviceClient);
   const screenshotFileName = getScreenshotFileName(fileNameInput, selectedProfiles);
+  saveScreenshotInfo(screenshotFileName, snapshot.screenInfo);
 
   for (const profile of selectedProfiles) {
     await captureProfile(replayClient, snapshot, profile, screenshotFileName);
@@ -2358,11 +3415,23 @@ async function captureScreenshotSet(
   console.log(`Responsive screenshot set completed: ${screenshotFileName}`);
 }
 
-async function frameExistingScreenshots(selectedProfiles) {
+async function frameExistingScreenshots(
+  selectedProfiles,
+  overwriteExisting = false,
+  screenshotNames = '',
+  outputRootDirectory = inFrameDirectory,
+) {
   let replayBrowser;
   let replayClient;
   let framedCount = 0;
   let failedCount = 0;
+  const selectedScreenshotNames = new Set(
+    screenshotNames
+      .split(',')
+      .map((name) => path.parse(name.trim()).name)
+      .filter(Boolean),
+  );
+  const foundScreenshotNames = new Set();
 
   try {
     replayBrowser = await launchReplayBrowser();
@@ -2376,12 +3445,17 @@ async function frameExistingScreenshots(selectedProfiles) {
       }
 
       const screenshotFiles = fs.readdirSync(profileDirectory, { withFileTypes: true })
-        .filter((entry) => entry.isFile() && /\.png$/i.test(entry.name))
+        .filter((entry) => entry.isFile() && /\.(?:png|jpe?g|webp)$/i.test(entry.name))
         .map((entry) => entry.name)
+        .filter((fileName) => (
+          !selectedScreenshotNames.size
+          || selectedScreenshotNames.has(path.parse(fileName).name)
+        ))
         .sort((first, second) => first.localeCompare(second, undefined, { numeric: true }));
 
       for (const screenshotFileName of screenshotFiles) {
         const screenshotPath = path.join(profileDirectory, screenshotFileName);
+        foundScreenshotNames.add(path.parse(screenshotFileName).name);
 
         try {
           const wasCreated = await captureFramedScreenshot(
@@ -2389,7 +3463,8 @@ async function frameExistingScreenshots(selectedProfiles) {
             fs.readFileSync(screenshotPath),
             profile,
             screenshotFileName,
-            true,
+            !overwriteExisting,
+            outputRootDirectory,
           );
           if (wasCreated) framedCount += 1;
         } catch (error) {
@@ -2410,6 +3485,14 @@ async function frameExistingScreenshots(selectedProfiles) {
 
   console.log(`Existing screenshot framing completed: ${framedCount} created.`);
 
+  const missingScreenshotNames = [...selectedScreenshotNames]
+    .filter((name) => !foundScreenshotNames.has(name));
+  if (missingScreenshotNames.length) {
+    throw new Error(
+      `Requested screenshot(s) were not found for the selected profiles: ${missingScreenshotNames.join(', ')}.`,
+    );
+  }
+
   if (failedCount) {
     throw new Error(`${failedCount} existing screenshot(s) could not be framed.`);
   }
@@ -2598,6 +3681,7 @@ async function getInteractiveOptions(options) {
     || options.dryRun
     || options.amazonAssets
     || options.samsungAssets
+    || options.refreshInfo
     || options.vivoExisting
     || options.oppoExisting
   ) {
@@ -2644,6 +3728,10 @@ async function main() {
 
   options = await getInteractiveOptions(options);
 
+  if (!options.dryRun && !options.refreshInfo) {
+    reconcileScreenshotRecords();
+  }
+
   if (options.amazonAssets) {
     let amazonBrowser;
     let amazonClient;
@@ -2678,6 +3766,10 @@ async function main() {
     return;
   }
 
+  if (options.vivoExisting || options.oppoExisting) {
+    await prepareFrameSelection(options);
+  }
+
   if (options.vivoExisting) {
     await createVivoAssetsFromExistingScreenshots();
     return;
@@ -2688,17 +3780,26 @@ async function main() {
     return;
   }
 
-  if (!options.dryRun) {
-    await createMissingStoreAssets();
-  }
-
   const selectedProfiles = selectProfiles(options.profiles);
 
-  if (options.frameExisting) {
-    await frameExistingScreenshots(selectedProfiles);
+  if (!options.dryRun && !options.refreshInfo) {
+    await prepareFrameSelection(options);
+  }
+
+  if (options.frameExisting || options.reframeExisting) {
+    await frameExistingScreenshots(
+      selectedProfiles,
+      options.reframeExisting,
+      options.screenshots,
+      options.reframeExisting ? uploadDirectory : inFrameDirectory,
+    );
     return;
   }
 
+  if (!options.dryRun && !options.refreshInfo) {
+    await createMissingStoreAssets();
+  }
+
   const interactiveMode = process.stdin.isTTY && !options.prefix && !options.dryRun;
   const deviceId = getConnectedDevice();
   const appId = getAppId();
@@ -2737,6 +3838,20 @@ async function main() {
       return;
     }
 
+    if (options.refreshInfo) {
+      const screenshotKey = sanitizeName(
+        options.refreshInfo.trim().replace(/\.(png|jpe?g)$/i, ''),
+        '',
+      );
+      if (!screenshotKey) {
+        throw new Error('Provide a screenshot name after --refresh-info, for example: --refresh-info 1');
+      }
+      const snapshot = await capturePageSnapshot(deviceClient);
+      saveScreenshotInfo(`${screenshotKey}.png`, snapshot.screenInfo);
+      console.log(`Screenshot information refreshed without creating images: ${screenshotKey}`);
+      return;
+    }
+
     fs.mkdirSync(screenshotDirectory, { recursive: true });
     replayBrowser = await launchReplayBrowser();
     replayClient = await createReplayPage(replayBrowser);