zdymak 0.7.0 → 0.13.0

package/src/screenshots.mjs

@@ -1,66 +1,118 @@
-/**
- * Multi-device store-screenshot generator. For each configured device group and each of its screenshot
- * targets, renders one still per scene (in the chosen style, at the target's exact dimensions) and writes a
- * store-safe **no-alpha PNG**. Scenes whose capture is missing for a device are skipped gracefully, so an
- * app configures only the devices it actually ships.
- */
-import fs from 'node:fs';
-import path from 'node:path';
-import { renderStill } from './still.mjs';
-import { rgbPngBuffer } from './png.mjs';
-import { IMAGE_TARGETS } from './specs.mjs';
-import { inferFrame } from './frames.mjs';
-import { buildFeatureGraphic } from './graphic.mjs';
-
-/** Resolve a concrete [w,h] for a screenshot target: explicit override → spec w/h → first accepted size. */
-export function targetSize(spec, override) {
-  if (override) return override;
-  if (spec.w && spec.h) return [spec.w, spec.h];
-  if (spec.accepts?.length) return spec.accepts[0];
-  throw new Error('screenshot target has no resolvable size');
-}
-
-/** Build every screenshot for one resolved device group → array of written file paths. */
-export async function buildDeviceScreenshots({ device, brand, theme, outDir }) {
-  const written = [];
-  for (const shot of device.screenshots || []) {
-    const spec = IMAGE_TARGETS[shot.target];
-    if (!spec) throw new Error(`Unknown image target "${shot.target}" (device: ${device.name})`);
-    const [W, H] = targetSize(spec, shot.size);
-    const frame = shot.frame || inferFrame(shot.target); // device bezel for the `framed` style
-    // Infer the style from the target: a framed device (phone/tablet/watch) → 'framed'; a frameless
-    // target (Mac/desktop) → 'premium' (window on the matte). Overridable per shot (e.g. Watch → 'bleed').
-    const style = shot.style || (frame ? 'framed' : 'premium');
-
-    // Feature graphic (Play banner) is a single branded image, not a per-scene shot.
-    if (spec.graphic) {
-      const hero = device.scenes.find((s) => fs.existsSync(s.image));
-      if (!hero) continue;
-      const outFile = path.join(outDir, `${shot.target}.png`);
-      await buildFeatureGraphic({ W, H, brand, theme: shot.theme || theme, heroPath: hero.image, outFile, frame: frame || 'android' });
-      written.push({ file: outFile, W, H, style: 'graphic' });
-      continue;
-    }
-
-    const dir = path.join(outDir, shot.target);
-    fs.mkdirSync(dir, { recursive: true });
-
-    let n = 0;
-    for (const scene of device.scenes) {
-      if (!fs.existsSync(scene.image)) continue; // graceful: this device lacks this scene's capture
-      n++;
-      const still = await renderStill(style, {
-        W, H,
-        imgPath: scene.image,
-        caption: { title: scene.title || '', sub: scene.sub || '' },
-        brand,
-        theme: shot.theme || theme,
-        frame,
-      });
-      const file = path.join(dir, `${String(n).padStart(2, '0')}-${scene.id || n}.png`);
-      fs.writeFileSync(file, rgbPngBuffer(still));
-      written.push({ file, W, H, style });
-    }
-  }
-  return written;
-}
+/**
+ * Multi-device store-screenshot generator. For each configured device group and each of its screenshot
+ * targets, renders one still per scene (in the chosen style, at the target's exact dimensions) and writes a
+ * store-safe **no-alpha PNG**. Scenes whose capture is missing for a device are skipped gracefully, so an
+ * app configures only the devices it actually ships.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { renderStill } from './still.mjs';
+import { rgbPngBuffer } from './png.mjs';
+import { IMAGE_TARGETS } from './specs.mjs';
+import { inferFrame } from './frames.mjs';
+import { buildFeatureGraphic, buildAppIcon } from './graphic.mjs';
+import { validateImage } from './validate.mjs';
+
+/**
+ * Apply a locale's caption table to a scene list. A scene the locale doesn't translate keeps its base
+ * caption — a store shot with the source-language headline beats a missing slot — and the caller reports
+ * the fallbacks rather than hiding them.
+ */
+export function localizeScenes(scenes, table) {
+  if (!table) return scenes;
+  return scenes.map((s) => {
+    const t = table[s.id];
+    return t ? { ...s, title: t.title ?? s.title, sub: t.sub ?? s.sub } : s;
+  });
+}
+
+/** Scene ids in `scenes` that this locale's table doesn't translate (used for the fallback report). */
+export function untranslatedScenes(scenes, table) {
+  if (!table) return [];
+  return scenes.filter((s) => !table[s.id]).map((s) => s.id);
+}
+
+/**
+ * Localized brand lines for the feature graphic, from the reserved `$brand` key of a caption table
+ * (`{ "$brand": { "tagline": "…" } }`). Only the wordmark copy is localizable — colours/logo are global.
+ */
+export function localizeBrand(brand, table) {
+  const b = table?.$brand;
+  if (!b) return brand;
+  const { name, tagline, endline, endsub } = b;
+  return {
+    ...brand,
+    ...(name !== undefined && { name }),
+    ...(tagline !== undefined && { tagline }),
+    ...(endline !== undefined && { endline }),
+    ...(endsub !== undefined && { endsub }),
+  };
+}
+
+/** Resolve a concrete [w,h] for a screenshot target: explicit override → spec w/h → first accepted size. */
+export function targetSize(spec, override) {
+  if (override) return override;
+  if (spec.w && spec.h) return [spec.w, spec.h];
+  if (spec.accepts?.length) return spec.accepts[0];
+  throw new Error('screenshot target has no resolvable size');
+}
+
+/** Build every screenshot for one resolved device group → array of written file paths. */
+export async function buildDeviceScreenshots({ device, brand, theme, outDir, force }) {
+  const written = [];
+  for (const shot of device.screenshots || []) {
+    const spec = IMAGE_TARGETS[shot.target];
+    if (!spec) throw new Error(`Unknown image target "${shot.target}" (device: ${device.name})`);
+    const [W, H] = targetSize(spec, shot.size);
+    const frame = shot.frame || inferFrame(shot.target); // device bezel for the `framed` style
+    // Infer the style from the target: a framed device (phone/tablet/watch) → 'framed'; a frameless
+    // target (Mac/desktop) → 'premium' (window on the matte). Overridable per shot (e.g. Watch → 'bleed').
+    const style = shot.style || (frame ? 'framed' : 'premium');
+
+    // The app icon is a branded square built from brand.logo — and the only target that keeps alpha.
+    if (spec.icon) {
+      const outFile = path.join(outDir, `${shot.target}.png`);
+      await buildAppIcon({ W, H, brand, theme: shot.theme || theme, outFile });
+      validateImage({ file: outFile, destination: spec, size: [W, H], force });
+      written.push({ file: outFile, W, H, style: 'icon' });
+      continue;
+    }
+
+    // Feature graphic (Play banner) is a single branded image, not a per-scene shot.
+    if (spec.graphic) {
+      const hero = device.scenes.find((s) => fs.existsSync(s.image));
+      if (!hero) continue;
+      const outFile = path.join(outDir, `${shot.target}.png`);
+      await buildFeatureGraphic({ W, H, brand, theme: shot.theme || theme, heroPath: hero.image, outFile, frame: frame || 'android' });
+      validateImage({ file: outFile, destination: spec, size: [W, H], force });
+      written.push({ file: outFile, W, H, style: 'graphic' });
+      continue;
+    }
+
+    // `dir` lets two shots of the SAME target coexist — e.g. a styled `play-phone/` for the website and a
+    // plain `play-phone-plain/` for the Play upload, which would otherwise overwrite each other.
+    const dir = path.join(outDir, shot.dir || shot.target);
+
+    let n = 0;
+    for (const scene of device.scenes) {
+      if (!fs.existsSync(scene.image)) continue; // graceful: this device lacks this scene's capture
+      if (!n) fs.mkdirSync(dir, { recursive: true }); // only once we have something to put in it
+      n++;
+      const still = await renderStill(style, {
+        W, H,
+        // `caption: false` renders the app interface alone — what Google Play asks for on store
+        // screenshots ("no additional text, graphics, or backgrounds that are not part of the interface").
+        caption: shot.caption === false ? { title: '', sub: '' } : { title: scene.title || '', sub: scene.sub || '' },
+        imgPath: scene.image,
+        brand,
+        theme: shot.theme || theme,
+        frame,
+      });
+      const file = path.join(dir, `${String(n).padStart(2, '0')}-${scene.id || n}.png`);
+      fs.writeFileSync(file, rgbPngBuffer(still));
+      validateImage({ file, destination: spec, size: [W, H], force });
+      written.push({ file, W, H, style });
+    }
+  }
+  return written;
+}

package/src/specs.mjs

@@ -1,88 +1,123 @@
-/**
- * Store spec matrix — the single source of truth for every store's asset requirements.
- *
- * VERIFY before each release: store forms change. Sources are cited inline; re-check the Apple and
- * Google help pages when a submission bounces on dimensions.
- */
-
-/** Video targets that produce an actual .mp4 file. */
-export const VIDEO_TARGETS = {
-  'appstore-preview': {
-    store: 'App Store',
-    label: 'App Store App Preview (iPhone 6.5" + 6.9")',
-    w: 886,
-    h: 1920,
-    fps: 30,
-    codec: 'h264',
-    profile: 'high',
-    level: '4.0', // Apple requires High @ 4.0 for App Previews
-    minSec: 15,
-    maxSec: 30,
-    slot: 'App Store Connect → your app → (localization) → App Previews. One 886×1920 file fills BOTH the 6.5" and 6.9" slots.',
-    // Apple: https://developer.apple.com/help/app-store-connect/reference/app-preview-specifications/
-  },
-  'play-promo': {
-    store: 'Google Play',
-    label: 'Google Play promo video (portrait 1080×1920 → upload to YouTube)',
-    w: 1080,
-    h: 1920,
-    fps: 30,
-    codec: 'h264',
-    profile: 'high',
-    level: '4.1', // 1080×1920@30 needs level ≥4.1
-    minSec: null,
-    maxSec: null,
-    slot: 'Play does NOT take a file: upload this to YouTube, then paste the URL in Play Console → Main store listing → Preview video.',
-    // Google: https://support.google.com/googleplay/android-developer/answer/9866151
-  },
-  'social-reel': {
-    store: 'Web / Social',
-    label: 'Device-framed promo reel (1080×1920) — website, X/IG/TikTok, or YouTube for Play',
-    w: 1080,
-    h: 1920,
-    fps: 30,
-    codec: 'h264',
-    profile: 'high',
-    level: '4.1',
-    minSec: null,
-    maxSec: null,
-    style: 'reel', // ← device bezel + brand background + logo bookends (buildReel, not buildVideo)
-    slot: 'For your website, X / Instagram / TikTok, or YouTube (Play listing). NOT the App Store App Preview slot — the device bezel is rejected there.',
-  },
-  'premium-reel': {
-    store: 'Web / Social',
-    label: 'Premium Apple-style reel (1080×1920) — matte + vignette + label pills + palette-aware cuts',
-    w: 1080,
-    h: 1920,
-    fps: 30,
-    codec: 'h264',
-    profile: 'high',
-    level: '4.1',
-    minSec: null,
-    maxSec: null,
-    style: 'premium', // ← the Apple editing-vocabulary preset (buildPremium); themeable via `theme`
-    slot: 'The "one device, many apps" marketing reel for web/social/YouTube. Full-bleed screens on a brand matte (no bezel) — but the label pill/matte make it a marketing asset, not an App Store App Preview.',
-  },
-};
-
-/** Screenshot / graphic targets that produce still images (v0.2 — dimensions locked in now). */
-export const IMAGE_TARGETS = {
-  'appstore-iphone-6.9': { store: 'App Store', w: 1320, h: 2868, alpha: false, format: 'png', label: 'iPhone 6.9" (largest — Apple scales down for smaller iPhones)' },
-  'appstore-iphone-6.5': { store: 'App Store', accepts: [[1242, 2688], [1284, 2778]], alpha: false, format: 'png', label: 'iPhone 6.5" (accepts 1242×2688 or 1284×2778)' },
-  'appstore-ipad-13': { store: 'App Store', w: 2064, h: 2752, alpha: false, format: 'png', label: 'iPad 13" (largest iPad class)' },
-  'appstore-watch': { store: 'App Store', accepts: [[422, 514], [410, 502], [416, 496], [396, 484], [368, 448], [312, 390]], alpha: false, format: 'png', label: 'Apple Watch (any one accepted size; alpha NOT allowed)' },
-  'appstore-mac': { store: 'Mac App Store', w: 2880, h: 1800, alpha: false, format: 'png', label: 'Mac (2880×1800, 16:10 landscape — largest required class)' },
-  'play-phone': { store: 'Google Play', w: 1080, h: 1920, alpha: false, format: 'png', label: 'Play phone (9:16, min 1080px, no alpha)' },
-  'play-tablet': { store: 'Google Play', w: 2560, h: 1440, alpha: false, format: 'png', label: 'Play tablet (16:9, 1080–7680px, no alpha)' },
-  'play-feature-graphic': { store: 'Google Play', w: 1024, h: 500, alpha: false, format: 'png', graphic: true, label: 'Play feature graphic (1024×500, no alpha) — brand banner, not a per-scene shot' },
-  'play-icon': { store: 'Google Play', w: 512, h: 512, alpha: true, format: 'png', label: 'Play app icon (32-bit PNG, alpha OK)' },
-};
-
-/** Resolve a video target by id, throwing a helpful error listing valid ids. */
-export function videoTarget(id) {
-  const t = VIDEO_TARGETS[id];
-  if (!t) {
-    throw new Error(`Unknown video target "${id}". Valid: ${Object.keys(VIDEO_TARGETS).join(', ')}`);
-  }
-  return t;
-}
+/**
+ * Store spec matrix — the single source of truth for every store's asset requirements.
+ *
+ * VERIFY before each release: store forms change. Sources are cited inline; re-check the Apple and
+ * Google help pages when a submission bounces on dimensions.
+ */
+
+/** Video targets that produce an actual .mp4 file. */
+export const VIDEO_TARGETS = {
+  'appstore-preview': {
+    store: 'App Store',
+    label: 'App Store App Preview (iPhone — one file fills 6.9" / 6.5" / 6.3" / 6.1")',
+    w: 886,
+    h: 1920,
+    fps: 30,
+    codec: 'h264',
+    profile: 'high',
+    level: '4.0', // Apple's wording is "up to High Profile Level 4.0" — a ceiling, not a mandate
+    minSec: 15,
+    maxSec: 30,
+    maxBytes: 500 * 1024 * 1024,
+    noFrame: true, // Apple rejects a device bezel in the App Preview slot
+    slot: 'App Store Connect → your app → (localization) → App Previews. One 886×1920 file covers the 6.9", 6.5", 6.3" and 6.1" iPhone families. Up to 3 previews per family.',
+    // Apple: https://developer.apple.com/help/app-store-connect/reference/app-preview-specifications/
+  },
+  'appstore-preview-ipad': {
+    store: 'App Store',
+    label: 'App Store App Preview (iPad 13" / 12.9" / 11" / 10.5")',
+    w: 1200,
+    h: 1600,
+    fps: 30,
+    codec: 'h264',
+    profile: 'high',
+    level: '4.0',
+    minSec: 15,
+    maxSec: 30,
+    maxBytes: 500 * 1024 * 1024,
+    noFrame: true,
+    slot: 'App Store Connect → App Previews (iPad). NOTE the iPad preview is 1200×1600 — NOT the 2064×2752 of the iPad screenshot slot.',
+    // Apple: https://developer.apple.com/help/app-store-connect/reference/app-preview-specifications/
+  },
+  'appstore-preview-mac': {
+    store: 'Mac App Store',
+    label: 'App Store App Preview (Mac — landscape only)',
+    w: 1920,
+    h: 1080,
+    fps: 30,
+    codec: 'h264',
+    profile: 'high',
+    level: '4.0',
+    minSec: 15,
+    maxSec: 30,
+    maxBytes: 500 * 1024 * 1024,
+    noFrame: true,
+    slot: 'App Store Connect → App Previews (Mac). Landscape only, same as Apple TV.',
+    // Apple: https://developer.apple.com/help/app-store-connect/reference/app-preview-specifications/
+  },
+  'play-promo': {
+    store: 'Google Play',
+    label: 'Google Play promo video (portrait 1080×1920 → upload to YouTube)',
+    w: 1080,
+    h: 1920,
+    fps: 30,
+    codec: 'h264',
+    profile: 'high',
+    level: '4.1', // 4.0 would also fit (8160 MBs); 4.1 is the safe, universally-decoded choice for 1080p
+    minSec: null,
+    maxSec: null,
+    slot: 'Play does NOT take a file: upload this to YouTube, then paste the URL in Play Console → Main store listing → Preview video.',
+    // Google: https://support.google.com/googleplay/android-developer/answer/9866151
+  },
+  'social-reel': {
+    store: 'Web / Social',
+    label: 'Device-framed promo reel (1080×1920) — website, X/IG/TikTok, or YouTube for Play',
+    w: 1080,
+    h: 1920,
+    fps: 30,
+    codec: 'h264',
+    profile: 'high',
+    level: '4.1',
+    minSec: null,
+    maxSec: null,
+    style: 'reel', // ← device bezel + brand background + logo bookends (buildReel, not buildVideo)
+    slot: 'For your website, X / Instagram / TikTok, or YouTube (Play listing). NOT the App Store App Preview slot — the device bezel is rejected there.',
+  },
+  'premium-reel': {
+    store: 'Web / Social',
+    label: 'Premium Apple-style reel (1080×1920) — matte + vignette + label pills + palette-aware cuts',
+    w: 1080,
+    h: 1920,
+    fps: 30,
+    codec: 'h264',
+    profile: 'high',
+    level: '4.1',
+    minSec: null,
+    maxSec: null,
+    style: 'premium', // ← the Apple editing-vocabulary preset (buildPremium); themeable via `theme`
+    slot: 'The "one device, many apps" marketing reel for web/social/YouTube. Full-bleed screens on a brand matte (no bezel) — but the label pill/matte make it a marketing asset, not an App Store App Preview.',
+  },
+};
+
+/** Screenshot / graphic targets that produce still images (v0.2 — dimensions locked in now). */
+export const IMAGE_TARGETS = {
+  'appstore-iphone-6.9': { store: 'App Store', w: 1320, h: 2868, accepts: [[1320, 2868], [1290, 2796], [1260, 2736]], alpha: false, format: 'png', label: 'iPhone 6.9" (largest — Apple scales down for smaller iPhones; also accepts 1290×2796 and 1260×2736)' },
+  'appstore-iphone-6.5': { store: 'App Store', accepts: [[1242, 2688], [1284, 2778]], alpha: false, format: 'png', label: 'iPhone 6.5" (accepts 1242×2688 or 1284×2778)' },
+  'appstore-ipad-13': { store: 'App Store', w: 2064, h: 2752, alpha: false, format: 'png', label: 'iPad 13" (largest iPad class)' },
+  'appstore-watch': { store: 'App Store', accepts: [[422, 514], [410, 502], [416, 496], [396, 484], [368, 448], [312, 390]], alpha: false, format: 'png', label: 'Apple Watch (any one accepted size; alpha NOT allowed)' },
+  'appstore-mac': { store: 'Mac App Store', w: 2880, h: 1800, alpha: false, format: 'png', label: 'Mac (2880×1800, 16:10 landscape — largest required class)' },
+  'play-phone': { store: 'Google Play', w: 1080, h: 1920, alpha: false, format: 'png', label: 'Play phone (9:16; store minimum is 320px per side, 1080+ for promotion eligibility; max 2:1; no alpha)' },
+  'play-tablet': { store: 'Google Play', w: 2560, h: 1440, alpha: false, format: 'png', label: 'Play tablet (16:9, 1080–7680px, no alpha)' },
+  'play-wear': { store: 'Google Play', w: 1080, h: 1080, alpha: false, format: 'png', label: 'Play Wear OS (1:1 square, 384–3840px, no alpha)' },
+  'play-feature-graphic': { store: 'Google Play', w: 1024, h: 500, alpha: false, format: 'png', graphic: true, label: 'Play feature graphic (1024×500, no alpha) — brand banner, not a per-scene shot' },
+  'play-icon': { store: 'Google Play', w: 512, h: 512, alpha: true, format: 'png', graphic: true, icon: true, maxBytes: 1024 * 1024, label: 'Play app icon (512×512, 32-bit PNG — the one asset where alpha is allowed; ≤1MB). Built from brand.logo.' },
+};
+
+/** Resolve a video target by id, throwing a helpful error listing valid ids. */
+export function videoTarget(id) {
+  const t = VIDEO_TARGETS[id];
+  if (!t) {
+    throw new Error(`Unknown video target "${id}". Valid: ${Object.keys(VIDEO_TARGETS).join(', ')}`);
+  }
+  return t;
+}

package/src/statusbar.mjs

@@ -0,0 +1,163 @@
+/**
+ * Synthetic status bar for captures that reserve the inset but don't contain the system UI.
+ *
+ * WHY: an Android Compose instrumentation capture (`captureToImage()`) grabs the APP's window only. An
+ * edge-to-edge app still pads for the status bar, so the shot carries an empty band where the clock and
+ * battery should be — the system UI lives in a separate window and never lands in the PNG. iOS XCUITest
+ * captures the whole screen, so its shots already have one; this closes the gap.
+ *
+ * Google asks for exactly this state: "Edit excess elements in the notification bar before submitting. Do
+ * not show service providers or notifications. The battery, WiFi, and cell service logos should be full."
+ * (Play Console Help — preview assets.) Android ships SystemUI *demo mode* for the same purpose; drawing
+ * the bar at compose time gets the identical result without re-capturing.
+ *
+ * Nothing is ever drawn over app pixels: the band is detected as a run of IDENTICAL rows at the top, and
+ * the bar is painted only inside it.
+ */
+import { createCanvas, loadImage } from '@napi-rs/canvas';
+import { roundRectPath, font } from './canvas.mjs';
+
+/** 9:41 — Apple's keynote time, and the de-facto marketing convention on both stores. */
+const DEFAULT_TIME = '9:41';
+
+/**
+ * Height in px of the uniform band at the top of an image, or 0 if there isn't a plausible one.
+ * Bounded to 2–15% of the height: below that it's a coincidence (one flat row), above it the image is
+ * mostly empty and we'd be guessing.
+ */
+export function detectBlankBand(ctx, W, H) {
+  const data = ctx.getImageData(0, 0, W, Math.ceil(H * 0.16)).data;
+  const at = (x, y) => { const i = (y * W + x) * 4; return [data[i], data[i + 1], data[i + 2]]; };
+  const [r0, g0, b0] = at(0, 0);
+  const same = (c) => Math.abs(c[0] - r0) <= 3 && Math.abs(c[1] - g0) <= 3 && Math.abs(c[2] - b0) <= 3;
+  const step = Math.max(1, Math.floor(W / 64)); // sample the row rather than reading every pixel
+  let y = 0;
+  const maxY = Math.floor(H * 0.15);
+  for (; y < maxY; y++) {
+    let uniform = true;
+    for (let x = 0; x < W; x += step) {
+      if (!same(at(x, y))) { uniform = false; break; }
+    }
+    if (!uniform) break;
+  }
+  return y >= H * 0.02 ? y : 0;
+}
+
+/** Perceived luminance → pick glyph colour that reads on the band it sits in. */
+const isLight = ([r, g, b]) => (0.299 * r + 0.587 * g + 0.114 * b) / 255 > 0.6;
+
+/**
+ * Paint a clean status bar into the band: time on the left, cell + wifi + full battery on the right.
+ * Vector-drawn (no font/icon assets), scaled to the band so it looks native at any density.
+ */
+export function drawStatusBar(ctx, W, bandH, { time = DEFAULT_TIME, color = '#0b0b0a', cellular = true } = {}) {
+  // Sit low enough in the strip to clear a device's corner radius, and inset far enough horizontally
+  // that the clock and the battery aren't chewed by the rounded corners of the screen cutout.
+  const cy = bandH * 0.62;
+  const fs = Math.round(bandH * 0.36);
+  const pad = Math.round(W * 0.08);
+
+  ctx.save();
+  ctx.fillStyle = color;
+  ctx.textBaseline = 'middle';
+  ctx.textAlign = 'left';
+  ctx.font = font(fs, '600'); // the registered brand/system face, same as every other caption
+  ctx.fillText(time, pad, cy);
+
+  // ── right cluster, laid out right-to-left ──
+  const u = bandH * 0.3; // glyph unit
+  let x = W - pad;
+
+  // Battery: rounded body, nub, full fill.
+  const bw = u * 1.85;
+  const bh = u * 0.92;
+  const r = bh * 0.28;
+  x -= bw;
+  const by = cy - bh / 2;
+  ctx.globalAlpha = 0.55;
+  ctx.lineWidth = Math.max(1, bh * 0.1);
+  ctx.strokeStyle = color;
+  roundRectPath(ctx, x, by, bw, bh, r);
+  ctx.stroke();
+  roundRectPath(ctx, x + bw + bh * 0.08, cy - bh * 0.16, bh * 0.12, bh * 0.32, bh * 0.06); // nub
+  ctx.fill();
+  ctx.globalAlpha = 1;
+  const inset = bh * 0.16;
+  roundRectPath(ctx, x + inset, by + inset, bw - inset * 2, bh - inset * 2, r * 0.6); // full charge
+  ctx.fill();
+
+  // Wi-Fi: three arcs + dot.
+  x -= u * 1.5;
+  ctx.lineWidth = Math.max(1, u * 0.16);
+  ctx.strokeStyle = color;
+  ctx.lineCap = 'round';
+  for (let i = 2; i >= 1; i--) {
+    ctx.beginPath();
+    ctx.arc(x, cy + u * 0.42, u * 0.34 * i, Math.PI * 1.25, Math.PI * 1.75);
+    ctx.stroke();
+  }
+  ctx.beginPath();
+  ctx.arc(x, cy + u * 0.34, u * 0.12, 0, Math.PI * 2);
+  ctx.fill();
+
+  // Cell signal: four full bars, drawn LEFT-to-right from this anchor, so the anchor must clear the
+  // wifi glyph by the bars' full width (1.44u) plus a gap — not the 1.9u that had them touching. A Wi-Fi-only tablet
+  // showing signal bars is a detail that's simply false, and Google asks for a status bar that reflects
+  // the device ("do not show service providers"), not a decorative one.
+  if (cellular) {
+    x -= u * 2.6;
+    const bars = 4;
+    const bwid = u * 0.22;
+    const gap = u * 0.14;
+    for (let i = 0; i < bars; i++) {
+      const h = u * (0.3 + i * 0.22);
+      roundRectPath(ctx, x + i * (bwid + gap), cy + u * 0.5 - h, bwid, h, bwid * 0.35);
+      ctx.fill();
+    }
+  }
+  ctx.restore();
+}
+
+/**
+ * If the capture reserves an empty status-bar band, fill it with a clean bar. Returns the canvas either
+ * way, so callers can use it unconditionally.
+ *
+ * `mode`: 'auto' (default — only when a band is detected) · true (force, using a 6% band) · false (skip).
+ */
+export function withStatusBar(canvas, mode = 'auto', opts = {}) {
+  if (mode === false) return canvas;
+  const ctx = canvas.getContext('2d');
+  const { width: W, height: H } = canvas;
+  // A (near-)square capture is a watch face. Watches have no marketing status bar, and their corners fall
+  // outside a round display — auto-detection would otherwise paint glyphs into the bezel. `true` still
+  // forces one, for the rare square phone-ish capture.
+  if (mode === 'auto' && Math.abs(W - H) / Math.max(W, H) < 0.1) return canvas;
+  const detected = mode === true ? Math.round(H * 0.06) : detectBlankBand(ctx, W, H);
+  if (!detected) return canvas;
+  // Detection says WHETHER to draw; it must not decide how big. A sparse screen can leave a 200px band
+  // and a dense one 90px — scaling the bar to that gives every screen a different-sized clock, which
+  // reads as a mistake the moment two of them sit in the same reel. Real status bars are ~4% of height.
+  const band = Math.min(detected, Math.round(H * 0.052)); // ≈48dp, a real status bar's height
+  const px = ctx.getImageData(0, 0, 1, 1).data;
+  drawStatusBar(ctx, W, band, { ...opts, color: opts.color || (isLight(px) ? '#0b0b0a' : '#f5f5f4') });
+  return canvas;
+}
+
+/**
+ * Load a capture with the status bar already painted in — the single entry point every renderer uses, so
+ * a still and the video built from the same PNG can't disagree about whether the bar is there.
+ */
+export async function loadCapture(imgPath, theme, frame) {
+  const img = await loadImage(imgPath);
+  const mode = theme?.statusBar ?? 'auto';
+  if (mode === false) return img;
+  const c = createCanvas(img.width, img.height);
+  c.getContext('2d').drawImage(img, 0, 0);
+  // Cellular is inferred: tablets in our frame set are Wi-Fi models, and a landscape capture is a
+  // tablet/desktop class. `statusBarCellular` overrides it for a cellular tablet.
+  const inferred = !/ipad|tablet/.test(String(frame || '')) && img.height >= img.width;
+  return withStatusBar(c, mode, {
+    time: theme?.statusBarTime,
+    cellular: theme?.statusBarCellular ?? inferred,
+  });
+}