feat(image-gen): GPU-path speed/quality guidance + never generate at a garbage resolution

On a non-NPU device (GPU/mnn path) a full SD1.5 model is a hard trade the user must steer,
and the old UI let them fall into both traps: 8 steps → muddy; 512x512 → ~18 min on a
mid-tier GPU; 128x128 → 43s but GARBAGE (SD1.5 is incoherent below ~256 — it's not a
"smaller image", it's broken).

- New utils/imageGenAdvice: pure, data-driven rule (branch on backend as data) — advises
  only on the mnn path: raise steps (<20), lower size (>256, for speed), or raise size
  (<256, which is garbage not smaller). NPU/CoreML get no advice (fast + fixed-shape).
- New ImageGenAdviceCard in the image settings: reads settings live, renders the tips as
  the user moves the Steps/Size sliders. Design tokens + Feather icons + brand voice.
- Image Size slider floor raised 128 → 256 (128/192 only ever produced garbage for these
  models); description states the 256-fast / 512-detailed-but-slow trade.
- Generation floors width/height to 256 (Math.max) so a STALE persisted sub-256 setting
  can't reach the pipeline — the user never sees garbage, only "reduced size".

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: alichherawalla

src/components/GenerationSettingsModal/ImageGenAdviceCard.tsx

@@ -0,0 +1,100 @@
+import React from 'react';
+import { View, Text } from 'react-native';
+import Icon from 'react-native-vector-icons/Feather';
+import { useTheme, useThemedStyles } from '../../theme';
+import type { ThemeColors } from '../../theme';
+import { TYPOGRAPHY, SPACING } from '../../constants';
+import { useAppStore } from '../../stores';
+import { getImageGenAdvice } from '../../utils/imageGenAdvice';
+
+/**
+ * Advisory shown only for the GPU (mnn) image path — where the device has no compatible
+ * NPU, so a full SD1.5 model is a real speed/quality trade the user must steer:
+ *  - under 20 steps looks muddy,
+ *  - a large size is very slow on a mid-tier GPU.
+ * It reads settings live (so it appears/updates as the user moves the Steps/Size sliders)
+ * and derives what to show from the single pure rule in utils/imageGenAdvice.
+ *
+ * Design: tokens only (COLORS/SPACING/TYPOGRAPHY), Feather vector icons, weights <=400.
+ */
+export const ImageGenAdviceCard: React.FC = () => {
+  const styles = useThemedStyles(createStyles);
+  const { colors } = useTheme();
+  const { settings, downloadedImageModels, activeImageModelId } = useAppStore();
+  const backend = downloadedImageModels.find(m => m.id === activeImageModelId)?.backend;
+
+  const advice = getImageGenAdvice({
+    backend,
+    steps: settings.imageSteps ?? 0,
+    width: settings.imageWidth ?? 0,
+  });
+  if (!advice.show) return null;
+
+  return (
+    <View style={styles.card} testID="image-gen-advice">
+      <View style={styles.headerRow}>
+        <Icon name="cpu" size={14} color={colors.primary} style={styles.leadIcon} />
+        <Text style={styles.title}>Tips for your device</Text>
+      </View>
+      <Text style={styles.intro}>
+        This device generates on the GPU (no compatible NPU), so quality and speed depend on these settings.
+      </Text>
+      {advice.raiseSteps && (
+        <View style={styles.tipRow} testID="image-gen-advice-steps">
+          <Icon name="arrow-up-circle" size={13} color={colors.textSecondary} style={styles.tipIcon} />
+          <Text style={styles.tip}>Use 20 or more steps for good quality. Fewer steps look muddy.</Text>
+        </View>
+      )}
+      {advice.lowerSize && (
+        <View style={styles.tipRow} testID="image-gen-advice-size">
+          <Icon name="minimize-2" size={13} color={colors.textSecondary} style={styles.tipIcon} />
+          <Text style={styles.tip}>Try 256 for much faster generation with coherent results.</Text>
+        </View>
+      )}
+      {advice.raiseSize && (
+        <View style={styles.tipRow} testID="image-gen-advice-raise-size">
+          <Icon name="alert-triangle" size={13} color={colors.textSecondary} style={styles.tipIcon} />
+          <Text style={styles.tip}>Use at least 256. Below that the model produces garbled images, not smaller ones.</Text>
+        </View>
+      )}
+    </View>
+  );
+};
+
+const createStyles = (colors: ThemeColors) => ({
+  card: {
+    borderRadius: 12,
+    borderWidth: 1,
+    borderColor: colors.border,
+    backgroundColor: colors.surfaceLight,
+    padding: SPACING.md,
+    marginTop: SPACING.sm,
+  },
+  headerRow: {
+    flexDirection: 'row' as const,
+    alignItems: 'center' as const,
+    gap: SPACING.xs,
+  },
+  leadIcon: { marginTop: 1 },
+  title: {
+    ...TYPOGRAPHY.label,
+    color: colors.primary,
+  },
+  intro: {
+    ...TYPOGRAPHY.bodySmall,
+    color: colors.textSecondary,
+    marginTop: SPACING.xs,
+  },
+  tipRow: {
+    flexDirection: 'row' as const,
+    alignItems: 'flex-start' as const,
+    gap: SPACING.xs,
+    marginTop: SPACING.sm,
+  },
+  tipIcon: { marginTop: 2 },
+  tip: {
+    ...TYPOGRAPHY.bodySmall,
+    color: colors.text,
+    flex: 1,
+  },
+});

src/components/GenerationSettingsModal/ImageGenerationSection.tsx

@@ -7,6 +7,7 @@ import { useAppStore } from '../../stores';
 import { hardwareService } from '../../services';
 import { createStyles } from './styles';
 import { ImageQualityBasicSliders, ImageQualityAdvancedSliders } from './ImageQualitySliders';
+import { ImageGenAdviceCard } from './ImageGenAdviceCard';
 
 // ─── Image Model Picker ───────────────────────────────────────────────────────
 
@@ -325,6 +326,8 @@ export const ImageGenerationSection: React.FC = () => {
 
       <ImageQualityBasicSliders />
 
+      <ImageGenAdviceCard />
+
       <AdvancedToggle isExpanded={showAdvanced} onPress={() => setShowAdvanced(!showAdvanced)} testID="modal-image-advanced-toggle" />
 
       {showAdvanced && <ImageAdvancedSection />}

src/components/GenerationSettingsModal/ImageQualitySliders.tsx

@@ -42,9 +42,9 @@ export const ImageQualityBasicSliders: React.FC = () => {
       <SliderSetting
         testID="image-size"
         label="Image Size"
-        description="Output resolution (smaller = faster, larger = more detail)"
+        description="Output resolution. 256 is fastest with coherent results; 512 is most detailed but slow on GPU-only devices."
         value={settings.imageWidth ?? 256}
-        min={128} max={512} step={64}
+        min={256} max={512} step={64}
         formatValue={(v) => `${v}x${v}`}
         onChange={(value) => updateSettings({ imageWidth: value, imageHeight: value })}
       />

src/services/imageGenerationService.ts

@@ -447,8 +447,11 @@ class ImageGenerationService {
 
     const steps = params.steps || settings.imageSteps || 8;
     const guidanceScale = params.guidanceScale || settings.imageGuidanceScale || 2.0;
-    const imageWidth = settings.imageWidth || 256;
-    const imageHeight = settings.imageHeight || 256;
+    // Floor to 256: SD-class models render garbage (incoherent, not "smaller") below 256,
+    // so a stale sub-256 setting must never reach the pipeline. The slider min is also 256;
+    // this guards the persisted-value + programmatic paths so the user never sees garbage.
+    const imageWidth = Math.max(256, settings.imageWidth || 256);
+    const imageHeight = Math.max(256, settings.imageHeight || 256);
 
     const enhancedPrompt = await this._enhancePrompt(params, steps);
     logger.log('[ImageGen] enhanceImagePrompts setting:', settings.enhanceImagePrompts);

src/utils/imageGenAdvice.ts

@@ -0,0 +1,49 @@
+/**
+ * Advice for the GPU (mnn) image-generation path — the slow, quality-sensitive one used
+ * when the device has no compatible NPU. On a mid-tier GPU a full SD1.5 model is a hard
+ * speed/quality trade the user has to steer manually:
+ *  - too few steps look muddy (undercooked denoise),
+ *  - a large size is very slow (observed: 512x512 @ 22 steps ~= 18 min on a Snapdragon 765G).
+ * So when the active model runs on the GPU path, nudge the user toward the settings that
+ * matter. The NPU (qnn) and CoreML (ANE) paths are fast + fixed-shape, so no advice.
+ *
+ * Pure + data-driven: it branches on the backend AS DATA (not a Platform/device check),
+ * so it's unit-testable and the same rule drives the card on every surface.
+ */
+export interface ImageGenAdvice {
+  /** Surface the advisory card at all (any tip applies). */
+  show: boolean;
+  /** Steps are below the quality floor for the GPU path. */
+  raiseSteps: boolean;
+  /** Resolution is above the sweet spot → slow on a mid-tier GPU. */
+  lowerSize: boolean;
+  /** Resolution is below what SD1.5 can render coherently → garbage output. */
+  raiseSize: boolean;
+}
+
+/** Below this, GPU-path output is visibly undercooked (muddy). */
+export const QUALITY_STEP_FLOOR = 20;
+/**
+ * The usable sweet-spot resolution for SD1.5 on the GPU path. SD1.5 is trained at 512;
+ * 256 stays coherent while generating far faster, but BELOW 256 the model produces
+ * garbage (observed on-device: 128x128 was fast but incoherent). So 256 is both the
+ * "smaller = faster" target when the user is at 512, and the floor below which quality
+ * collapses.
+ */
+export const SWEET_SPOT_SIZE = 256;
+
+export function getImageGenAdvice(opts: {
+  backend?: string | null;
+  steps: number;
+  width: number;
+}): ImageGenAdvice {
+  // Only the mnn (GPU/CPU) path is slow + step/size-sensitive. qnn (NPU) / coreml (ANE)
+  // are fast and fixed-resolution, so tuning there isn't the same trade-off.
+  if (opts.backend !== 'mnn') {
+    return { show: false, raiseSteps: false, lowerSize: false, raiseSize: false };
+  }
+  const raiseSteps = opts.steps < QUALITY_STEP_FLOOR;
+  const lowerSize = opts.width > SWEET_SPOT_SIZE;
+  const raiseSize = opts.width > 0 && opts.width < SWEET_SPOT_SIZE;
+  return { show: raiseSteps || lowerSize || raiseSize, raiseSteps, lowerSize, raiseSize };
+}