@notis_ai/cli 0.2.5 → 0.2.6

package/src/runtime/app-platform.js

@@ -9,12 +9,13 @@
 import { spawn } from 'node:child_process';
 import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, rmSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { gunzipSync } from 'node:zlib';
 
 import { usageError } from './errors.js';
 import { validateArtifactBoundary, validateProjectBoundary } from './app-boundary-validator.js';
+import { readAppChangelog } from './app-changelog.js';
 
 const NOTIS_DIR = '.notis';
 const STATE_FILE = join(NOTIS_DIR, 'state.json');
@@ -35,6 +36,7 @@ export const NOTIS_APP_CATEGORIES = [
   'Product & Engineering',
   'Personal',
 ];
+export const MIN_LISTING_SCREENSHOTS = 3;
 const SOURCE_COPY_EXCLUDES = new Set([
   'node_modules',
   '.notis',
@@ -236,7 +238,7 @@ export function detectProjectWarnings(projectDir, appConfig = null) {
   if (appConfig) {
     try {
       const listing = inspectListingReadiness(projectDir, appConfig);
-      warnings.push(...listing.warnings);
+      warnings.push(...listing.errors, ...listing.warnings);
     } catch (error) {
       warnings.push(error instanceof Error ? error.message : String(error));
     }
@@ -291,11 +293,10 @@ function pngDimensions(buffer) {
   };
 }
 
-function imageAssetMeta(projectDir, relPath, { maxBytes, recommendedRatio = 1.6 }) {
+function imageAssetMeta(projectDir, relPath, { maxBytes }) {
   const fullPath = join(projectDir, relPath);
   const content = readFileSync(fullPath);
   const dimensions = pngDimensions(content);
-  const ratio = dimensions?.height ? dimensions.width / dimensions.height : null;
   const errors = [];
   const warnings = [];
 
@@ -305,10 +306,10 @@ function imageAssetMeta(projectDir, relPath, { maxBytes, recommendedRatio = 1.6
   if (content.length > maxBytes) {
     errors.push(`${relPath} must be ${Math.round(maxBytes / 1024 / 1024)} MB or smaller.`);
   }
-  if (ratio !== null && (ratio < 1.3 || ratio > 1.9)) {
-    errors.push(`${relPath} should be close to a 16:10 aspect ratio.`);
-  } else if (ratio !== null && Math.abs(ratio - recommendedRatio) > 0.08) {
-    warnings.push(`${relPath} is not 2000x1250; 16:10 PNG is recommended.`);
+  if (!dimensions) {
+    errors.push(`${relPath} is not a valid PNG file.`);
+  } else if (dimensions.width !== 2000 || dimensions.height !== 1250) {
+    errors.push(`${relPath} must be exactly 2000x1250 pixels.`);
   }
 
   return {
@@ -346,33 +347,135 @@ export function discoverMetadataAssets(projectDir) {
   };
 }
 
+function normalizeConfiguredScreenshots(appConfig = null) {
+  if (!Array.isArray(appConfig?.screenshots) || appConfig.screenshots.length === 0) {
+    return null;
+  }
+  if (appConfig.screenshots.length > 6) {
+    throw usageError('Configure at most six listing screenshots.');
+  }
+
+  const seenPaths = new Set();
+  return appConfig.screenshots.map((entry, index) => {
+    const path = typeof entry?.path === 'string' ? entry.path.trim().replace(/\\/g, '/') : '';
+    const alt = typeof entry?.alt === 'string' ? entry.alt.trim() : '';
+    const route = typeof entry?.route === 'string' ? entry.route.trim() : '';
+    const scenario = typeof entry?.scenario === 'string' ? entry.scenario.trim() : '';
+    const focus = typeof entry?.focus === 'string' ? entry.focus.trim() : '';
+    const theme = typeof entry?.theme === 'string' ? entry.theme.trim().toLowerCase() : '';
+    if (!/^metadata\/screenshot-\d+\.png$/i.test(path)) {
+      throw usageError(`screenshots[${index}].path must match metadata/screenshot-N.png.`);
+    }
+    const expectedPath = `metadata/screenshot-${index + 1}.png`;
+    if (path !== expectedPath) {
+      throw usageError(`screenshots[${index}].path must be ${expectedPath} so capture order stays stable.`);
+    }
+    if (seenPaths.has(path)) {
+      throw usageError(`Duplicate listing screenshot path: ${path}`);
+    }
+    if (theme && theme !== 'light' && theme !== 'dark') {
+      throw usageError(`screenshots[${index}].theme must be light or dark.`);
+    }
+    seenPaths.add(path);
+    return {
+      path,
+      alt,
+      route: route || null,
+      scenario: scenario || null,
+      focus: focus || null,
+      theme: theme || 'light',
+    };
+  });
+}
+
+/** Resolve listing screenshot files in their configured editorial order. */
+export function resolveListingScreenshots(projectDir, appConfig = null) {
+  const discovered = discoverMetadataAssets(projectDir).screenshots;
+  const configured = normalizeConfiguredScreenshots(appConfig);
+  if (!configured) {
+    return discovered.map((asset) => ({
+      ...asset,
+      alt: null,
+      route: null,
+      scenario: null,
+      focus: null,
+      theme: 'light',
+    }));
+  }
+
+  const byPath = new Map(discovered.map((asset) => [asset.path.replace(/\\/g, '/'), asset]));
+  return configured.map((entry) => {
+    const asset = byPath.get(entry.path);
+    if (!asset) {
+      return {
+        ...entry,
+        content_type: 'image/png',
+        bytes: null,
+        width: null,
+        height: null,
+        errors: [`${entry.path} is configured but the file does not exist.`],
+        warnings: [],
+      };
+    }
+    return { ...asset, ...entry };
+  });
+}
+
 export function inspectListingReadiness(projectDir, appConfig = null) {
   const config = appConfig || {};
   const warnings = [];
   const errors = [];
-  const metadata = discoverMetadataAssets(projectDir);
+  const screenshots = resolveListingScreenshots(projectDir, config);
+  const metadata = { screenshots };
   const categories = normalizeCategories(config.categories || []);
+  const changelog = readAppChangelog(projectDir);
+  errors.push(...changelog.errors);
+
+  const packagePath = join(projectDir, 'package.json');
+  if (!existsSync(packagePath)) {
+    errors.push('package.json is required for Store publication.');
+  } else {
+    try {
+      const packageJson = JSON.parse(readFileSync(packagePath, 'utf-8'));
+      const notisAppVersion = String(packageJson.notisAppVersion || '').trim();
+      if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(notisAppVersion)) {
+        errors.push('package.json must include a semver `notisAppVersion` (for example, "0.1.0").');
+      }
+    } catch {
+      errors.push('package.json must contain valid JSON for Store publication.');
+    }
+  }
 
   if (!String(config.tagline || '').trim()) {
-    warnings.push('Listing tagline missing in notis.config.ts.');
+    errors.push('Listing tagline missing in notis.config.ts.');
   }
   if (categories.length === 0) {
-    warnings.push(`Listing category missing in notis.config.ts. Use one of: ${NOTIS_APP_CATEGORIES.join(', ')}.`);
+    errors.push(`Listing category missing in notis.config.ts. Use one of: ${NOTIS_APP_CATEGORIES.join(', ')}.`);
   }
-  if (metadata.screenshots.length < 3) {
-    warnings.push(`Listing screenshots: ${metadata.screenshots.length}/3 minimum in metadata/screenshot-N.png. Run \`notis apps screenshot\` to generate them.`);
+  if (metadata.screenshots.length < MIN_LISTING_SCREENSHOTS) {
+    errors.push(`Listing screenshots: ${metadata.screenshots.length}/${MIN_LISTING_SCREENSHOTS} minimum in metadata/screenshot-N.png. Run \`notis apps screenshot\` to generate them.`);
   }
   for (const screenshot of metadata.screenshots) {
     errors.push(...screenshot.errors);
     warnings.push(...screenshot.warnings);
+    if (!screenshot.alt) {
+      errors.push(`${screenshot.path} is missing descriptive alt text in notis.config.ts -> screenshots.`);
+    }
   }
 
   return {
-    ready: errors.length === 0 && Boolean(config.tagline) && categories.length > 0 && metadata.screenshots.length >= 1,
+    ready:
+      errors.length === 0 &&
+      Boolean(String(config.tagline || '').trim()) &&
+      categories.length > 0 &&
+      metadata.screenshots.length >= MIN_LISTING_SCREENSHOTS &&
+      metadata.screenshots.every((screenshot) => Boolean(screenshot.alt)) &&
+      changelog.entries.length > 0,
     warnings,
     errors,
     metadata,
     categories,
+    changelog,
   };
 }
 
@@ -606,9 +709,15 @@ export function generateManifest(appConfig, projectDir) {
 
   const databases = appConfig.databases || [];
   const categories = normalizeCategories(appConfig.categories || []);
-  const metadata = discoverMetadataAssets(projectDir);
+  const metadata = { screenshots: resolveListingScreenshots(projectDir, appConfig) };
   const appSlug = safeKebab(appConfig.name);
   const displayTitle = appConfig.title || appConfig.displayName || appConfig.name;
+  const skills = (Array.isArray(appConfig.skills) ? appConfig.skills : []).map((skill) => ({
+    key: skill.key,
+    path: String(skill.path || '').replace(/^\.\/+/, ''),
+    name: skill.name,
+    description: skill.description || null,
+  }));
   const listingMedia = {
     screenshots: metadata.screenshots.map((screenshot) => ({
       path: screenshot.path,
@@ -616,8 +725,27 @@ export function generateManifest(appConfig, projectDir) {
       width: screenshot.width,
       height: screenshot.height,
       bytes: screenshot.bytes,
+      alt: screenshot.alt || null,
+      theme: screenshot.theme || 'light',
     })),
   };
+  const changelog = readAppChangelog(projectDir);
+  if (changelog.exists && changelog.errors.length > 0) {
+    throw usageError(changelog.errors.join('\n'));
+  }
+  const latestChangelogEntry = changelog.entries[0] || null;
+  const legacyVersionNotes = latestChangelogEntry?.body
+    || appConfig.versionNotes
+    || appConfig.version_notes
+    || null;
+  let releaseVersion = null;
+  try {
+    const packageJson = JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf-8'));
+    releaseVersion = String(packageJson.notisAppVersion || '').trim() || null;
+  } catch {
+    // Store readiness reports missing or malformed package metadata. Ordinary
+    // development builds remain usable without a Store release version.
+  }
 
   return {
     version: 1,
@@ -632,14 +760,23 @@ export function generateManifest(appConfig, projectDir) {
       tagline: appConfig.tagline || null,
       categories,
       author: appConfig.author || null,
-      version_notes: appConfig.versionNotes || appConfig.version_notes || null,
+      release_version: releaseVersion,
+      version_notes: legacyVersionNotes,
     },
     listing: {
       title: displayTitle,
       tagline: appConfig.tagline || null,
       categories,
       author: appConfig.author || null,
-      version_notes: appConfig.versionNotes || appConfig.version_notes || null,
+      version_notes: legacyVersionNotes,
+      ...(changelog.exists
+        ? {
+            changelog: {
+              source_path: changelog.source_path,
+              entries: changelog.entries,
+            },
+          }
+        : {}),
       media: listingMedia,
     },
     metadata: listingMedia,
@@ -650,9 +787,47 @@ export function generateManifest(appConfig, projectDir) {
     },
     databases,
     tools: appConfig.tools || [],
+    skills,
+    onboarding: appConfig.onboarding || null,
   };
 }
 
+export function resolveConfiguredAppSkills(appConfig, projectDir) {
+  const configured = Array.isArray(appConfig.skills) ? appConfig.skills : [];
+  const projectRoot = resolve(projectDir);
+  const seenKeys = new Set();
+
+  return configured.map((skill, index) => {
+    const key = typeof skill?.key === 'string' ? skill.key.trim() : '';
+    const sourcePath = typeof skill?.path === 'string' ? skill.path.trim() : '';
+    const name = typeof skill?.name === 'string' ? skill.name.trim() : '';
+    if (!key || !sourcePath || !name) {
+      throw usageError(`skills[${index}] must define non-empty key, path, and name values.`);
+    }
+    if (seenKeys.has(key)) {
+      throw usageError(`Duplicate app skill key: ${key}`);
+    }
+    seenKeys.add(key);
+
+    const absolutePath = resolve(projectRoot, sourcePath);
+    const relativePath = relative(projectRoot, absolutePath).replace(/\\/g, '/');
+    if (!relativePath || relativePath.startsWith('../') || relativePath === '..') {
+      throw usageError(`App skill path must stay inside the project: ${sourcePath}`);
+    }
+    if (!existsSync(absolutePath) || !statSync(absolutePath).isFile()) {
+      throw usageError(`App skill entrypoint not found: ${sourcePath}`);
+    }
+
+    return {
+      key,
+      path: relativePath,
+      name,
+      description: typeof skill.description === 'string' ? skill.description.trim() : null,
+      skill_md: readFileSync(absolutePath, 'utf8'),
+    };
+  });
+}
+
 /**
  * Build the app bundle: generate entry file, run `vite build`, package into .notis/output/.
  */
@@ -695,10 +870,14 @@ export function readManifest(projectDir) {
 
 function copyMetadataAssets(projectDir) {
   const metadataDir = join(projectDir, METADATA_DIR);
+  const outputMetadataDir = join(projectDir, OUTPUT_DIR, METADATA_DIR);
+  // Vite clears the bundle directory, not sibling listing media. Always make
+  // the packaged metadata an exact reflection of the source tree so removed
+  // placeholders can never survive into a later deploy.
+  rmSync(outputMetadataDir, { recursive: true, force: true });
   if (!existsSync(metadataDir)) {
     return;
   }
-  const outputMetadataDir = join(projectDir, OUTPUT_DIR, METADATA_DIR);
   mkdirSync(outputMetadataDir, { recursive: true });
   for (const entry of readdirSync(metadataDir, { withFileTypes: true })) {
     if (!entry.isFile()) continue;

package/src/runtime/desktop-auth.js

@@ -0,0 +1,93 @@
+import { CliError, EXIT_CODES } from './errors.js';
+
+function isPidRunning(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM';
+  }
+}
+
+function quoteShellArgument(value) {
+  return `'${String(value).replace(/'/g, `'"'"'`)}'`;
+}
+
+function defaultDesktopAppName(apiBase) {
+  try {
+    return new URL(apiBase).hostname === 'api-beta.notis.ai' ? 'Notis Beta' : 'Notis';
+  } catch {
+    return 'Notis';
+  }
+}
+
+export function getDesktopAuthRecovery(runtime) {
+  const desktopRunning = isPidRunning(runtime.desktopPid);
+  const appName = runtime.desktopAppName || defaultDesktopAppName(runtime.apiBase);
+  let command = 'Start the Notis desktop app';
+  if (process.platform === 'darwin') {
+    command = `open -a ${quoteShellArgument(appName)}`;
+  }
+
+  return {
+    desktopRunning,
+    appName,
+    hints: [
+      {
+        command,
+        reason: desktopRunning
+          ? `Bring ${appName} forward so it can renew CLI authentication, then retry`
+          : `Start ${appName} to renew expired CLI authentication, then retry`,
+      },
+      {
+        command: 'notis doctor',
+        reason: 'Retry the auth and API checks after the desktop app is ready',
+      },
+    ],
+  };
+}
+
+export function createExpiredAuthError(runtime) {
+  if (runtime.credentialSource === 'env') {
+    return new CliError({
+      code: 'auth_expired',
+      message: 'NOTIS_JWT is expired',
+      exitCode: EXIT_CODES.auth,
+      details: { credential_source: 'env' },
+      hints: [
+        {
+          command: 'Set NOTIS_JWT to a fresh token',
+          reason: 'The explicit environment credential overrides desktop-managed auth',
+        },
+      ],
+    });
+  }
+
+  const recovery = getDesktopAuthRecovery(runtime);
+  return new CliError({
+    code: 'auth_expired',
+    message: 'Notis CLI authentication has expired',
+    exitCode: EXIT_CODES.auth,
+    details: {
+      credential_source: 'desktop',
+      desktop_running: recovery.desktopRunning,
+      desktop_app_name: recovery.appName,
+    },
+    hints: recovery.hints,
+  });
+}
+
+export function createInvalidAuthHints(runtime) {
+  if (runtime?.credentialSource === 'env') {
+    return [
+      {
+        command: 'Set NOTIS_JWT to a fresh token',
+        reason: 'The explicit environment credential was rejected',
+      },
+    ];
+  }
+  return getDesktopAuthRecovery(runtime || {}).hints;
+}

package/src/runtime/profiles.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { CliError, EXIT_CODES } from './errors.js';
+import { getDesktopAuthRecovery } from './desktop-auth.js';
 
 export const CONFIG_DIR = join(homedir(), '.notis');
 export const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
@@ -37,6 +38,9 @@ export function normalizeConfig(rawConfig = {}) {
           typeof profile.access_expires_at === 'number' ? profile.access_expires_at : undefined,
         refresh_expires_at:
           typeof profile.refresh_expires_at === 'number' ? profile.refresh_expires_at : undefined,
+        desktop_app_name:
+          typeof profile.desktop_app_name === 'string' ? profile.desktop_app_name : undefined,
+        desktop_pid: typeof profile.desktop_pid === 'number' ? profile.desktop_pid : undefined,
       };
     }
 
@@ -65,6 +69,9 @@ export function normalizeConfig(rawConfig = {}) {
           typeof raw.access_expires_at === 'number' ? raw.access_expires_at : undefined,
         refresh_expires_at:
           typeof raw.refresh_expires_at === 'number' ? raw.refresh_expires_at : undefined,
+        desktop_app_name:
+          typeof raw.desktop_app_name === 'string' ? raw.desktop_app_name : undefined,
+        desktop_pid: typeof raw.desktop_pid === 'number' ? raw.desktop_pid : undefined,
       },
     },
   };
@@ -199,34 +206,30 @@ export function resolveRuntimeProfile(globalOptions = {}, { requireAuth = true }
   const timeoutMs = resolveTimeoutMs(globalOptions);
 
   if (requireAuth && !jwt) {
+    const recovery = getDesktopAuthRecovery({
+      apiBase,
+      desktopAppName: profile.desktop_app_name,
+      desktopPid: profile.desktop_pid,
+    });
     throw new CliError({
       code: 'auth_missing',
       message: `No JWT configured for profile ${profileName}`,
       exitCode: EXIT_CODES.auth,
-      hints: [
-        {
-          command: 'Open the Notis desktop app and sign in',
-          reason: 'Set NOTIS_JWT or sign in through the Notis desktop app',
-        },
-      ],
+      hints: recovery.hints,
     });
   }
 
-  // An explicit NOTIS_JWT is a complete credential override: use it verbatim and do
-  // NOT attempt a stored-profile dev_portal token refresh (whose refresh_token may be
-  // stale or belong to a different session). Without this, a long-lived shell with an
-  // expired profile refresh_token fails every command with invalid_grant even though
-  // the supplied NOTIS_JWT is valid.
+  // An explicit NOTIS_JWT is a complete credential override. Use it verbatim
+  // and never replace it with a token later synced by the desktop profile.
   const usingEnvJwt = Boolean(process.env.NOTIS_JWT);
   return {
     config,
     profileName,
     apiBase,
     jwt,
-    authMode: usingEnvJwt ? 'jwt' : profile.auth_mode,
-    refreshToken: usingEnvJwt ? undefined : profile.refresh_token,
-    accessExpiresAt: usingEnvJwt ? undefined : profile.access_expires_at,
-    refreshExpiresAt: usingEnvJwt ? undefined : profile.refresh_expires_at,
+    credentialSource: usingEnvJwt ? 'env' : 'profile',
+    desktopAppName: usingEnvJwt ? undefined : profile.desktop_app_name,
+    desktopPid: usingEnvJwt ? undefined : profile.desktop_pid,
     agentMode,
     nonInteractive,
     outputMode,
@@ -234,6 +237,25 @@ export function resolveRuntimeProfile(globalOptions = {}, { requireAuth = true }
   };
 }
 
+export function getJwtExpiration(jwt) {
+  if (typeof jwt !== 'string' || !jwt) {
+    return null;
+  }
+  try {
+    const parts = jwt.split('.');
+    if (parts.length !== 3) return null;
+    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+    return typeof payload.exp === 'number' ? payload.exp : null;
+  } catch {
+    return null;
+  }
+}
+
+export function isJwtExpired(jwt, nowSeconds = Math.floor(Date.now() / 1000)) {
+  const expiration = getJwtExpiration(jwt);
+  return expiration !== null && expiration <= nowSeconds;
+}
+
 export function workspacePath(appId) {
   return join(WORKSPACE_DIR, appId);
 }

package/src/runtime/store-screenshot.js

@@ -0,0 +1,138 @@
+import sharp from 'sharp';
+import { fileURLToPath } from 'node:url';
+
+const STORE_SCREENSHOT_ASPECT = 16 / 10;
+const SHARED_BACKDROP_PATH = fileURLToPath(
+  new URL('./assets/store-screenshot-dark.png', import.meta.url),
+);
+
+const ACCENT_PALETTES = {
+  blue: { glow: '#4f7cff', glow2: '#274690' },
+  violet: { glow: '#9b87f5', glow2: '#5038a1' },
+  emerald: { glow: '#34d399', glow2: '#176b55' },
+  amber: { glow: '#f2a94a', glow2: '#8b4f20' },
+  rose: { glow: '#fb7185', glow2: '#8f3048' },
+  sky: { glow: '#38bdf8', glow2: '#176887' },
+  fuchsia: { glow: '#d946ef', glow2: '#772786' },
+  teal: { glow: '#2dd4bf', glow2: '#176e68' },
+};
+
+const ACCENT_NAMES = Object.keys(ACCENT_PALETTES);
+
+function stableHash(value) {
+  let hash = 2166136261;
+  for (const character of String(value || 'notis-app')) {
+    hash ^= character.codePointAt(0);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+
+export function resolveStoreScreenshotAccent(accent, seed = 'notis-app') {
+  if (accent && ACCENT_PALETTES[accent]) {
+    return accent;
+  }
+  return ACCENT_NAMES[stableHash(seed) % ACCENT_NAMES.length];
+}
+
+export function storeScreenshotLayout(width = 2000, height = 1250) {
+  const horizontalInset = Math.max(48, Math.round(width * 0.06));
+  const verticalInset = Math.max(40, Math.round(height * 0.06));
+  let cardWidth = width - horizontalInset * 2;
+  let cardHeight = Math.round(cardWidth / STORE_SCREENSHOT_ASPECT);
+  const maximumCardHeight = height - verticalInset * 2;
+  if (cardHeight > maximumCardHeight) {
+    cardHeight = maximumCardHeight;
+    cardWidth = Math.round(cardHeight * STORE_SCREENSHOT_ASPECT);
+  }
+  const cardLeft = Math.round((width - cardWidth) / 2);
+  const cardTop = Math.round((height - cardHeight) / 2) - Math.round(height * 0.008);
+  return {
+    width,
+    height,
+    cardWidth,
+    cardHeight,
+    cardLeft,
+    cardTop,
+    radius: Math.max(18, Math.round(width * 0.016)),
+  };
+}
+
+async function backdropImage(layout) {
+  return sharp(SHARED_BACKDROP_PATH)
+    .resize(layout.width, layout.height, { fit: 'cover', position: 'centre' })
+    .png()
+    .toBuffer();
+}
+
+function roundedRectSvg(width, height, radius, { fill = '#ffffff', stroke = null } = {}) {
+  const strokeAttribute = stroke
+    ? ` fill="none" stroke="${stroke}" stroke-width="2"`
+    : ` fill="${fill}"`;
+  return Buffer.from(
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}"><rect x="1" y="1" width="${width - 2}" height="${height - 2}" rx="${radius}" ry="${radius}"${strokeAttribute}/></svg>`,
+  );
+}
+
+/**
+ * Composite a truthful browser capture into the deterministic Store frame.
+ * The source pixels are only resized/cropped; the app UI is never redrawn.
+ */
+export async function composeStoreScreenshot({
+  inputPath,
+  outputPath,
+  width = 2000,
+  height = 1250,
+  accent = null,
+  seed = 'notis-app',
+  focused = false,
+  theme = 'light',
+}) {
+  const resolvedTheme = theme === 'dark' ? 'dark' : 'light';
+  const layout = storeScreenshotLayout(width, height);
+  const resolvedAccent = resolveStoreScreenshotAccent(accent, seed);
+
+  const roundedCapture = await sharp(inputPath)
+    .resize(layout.cardWidth, layout.cardHeight, {
+      fit: 'cover',
+      position: focused ? 'top' : 'centre',
+    })
+    .composite([{
+      input: roundedRectSvg(layout.cardWidth, layout.cardHeight, layout.radius),
+      blend: 'dest-in',
+    }])
+    .png()
+    .toBuffer();
+
+  const border = roundedRectSvg(
+    layout.cardWidth,
+    layout.cardHeight,
+    layout.radius,
+    { stroke: resolvedTheme === 'dark' ? '#FFFFFF2A' : '#0F172A22' },
+  );
+
+  await sharp(await backdropImage(layout))
+    .composite([
+      { input: roundedCapture, left: layout.cardLeft, top: layout.cardTop },
+      { input: border, left: layout.cardLeft, top: layout.cardTop },
+    ])
+    .png({
+      compressionLevel: 9,
+      adaptiveFiltering: true,
+    })
+    .toFile(outputPath);
+
+  return {
+    mode: 'framed',
+    accent: resolvedAccent,
+    focused: Boolean(focused),
+    theme: resolvedTheme,
+    card: {
+      left: layout.cardLeft,
+      top: layout.cardTop,
+      width: layout.cardWidth,
+      height: layout.cardHeight,
+      radius: layout.radius,
+    },
+  };
+}