zdymak 0.7.0 → 0.13.0

package/src/frames.mjs

@@ -1,168 +1,186 @@
-/**
- * Device frames for the `framed` screenshot style — an iPhone bezel (Dynamic Island), an iPad bezel, or a
- * round Apple-Watch ring, with the capture drawn inside. The screen rect follows the capture's OWN aspect,
- * so nothing is cropped. Ported from a production store-asset pipeline; pure rendering.
- *
- * (Mac captures are already windowed — traffic-light title bar — so Mac uses the plain premium still; no
- *  extra window frame is drawn here.)
- */
-import { roundRectPath } from './canvas.mjs';
-
-/** Cover-fit an image into a rect (preserve aspect, crop overflow). */
-function drawInto(ctx, img, x, y, w, h) {
-  const sAspect = img.height / img.width;
-  let dw = w;
-  let dh = w * sAspect;
-  if (dh < h) {
-    dh = h;
-    dw = h / sAspect;
-  }
-  ctx.drawImage(img, x + (w - dw) / 2, y + (h - dh) / 2, dw, dh);
-}
-
-/** iPhone: dark unibody, thin uniform bezel, centred Dynamic Island. */
-export function drawPhoneFrame(ctx, img, cx, cy, screenW) {
-  const screenH = screenW * (img.height / img.width);
-  const bezel = Math.round(screenW * 0.032);
-  const bodyW = screenW + bezel * 2;
-  const bodyH = screenH + bezel * 2;
-  const bodyX = Math.round(cx - bodyW / 2);
-  const bodyY = Math.round(cy - bodyH / 2);
-  const sx = bodyX + bezel;
-  const sy = bodyY + bezel;
-
-  ctx.save();
-  ctx.shadowColor = 'rgba(0,0,0,0.4)';
-  ctx.shadowBlur = Math.round(screenW * 0.09);
-  ctx.shadowOffsetY = Math.round(screenW * 0.035);
-  roundRectPath(ctx, bodyX, bodyY, bodyW, bodyH, Math.round(screenW * 0.155));
-  ctx.fillStyle = '#0b0b0a';
-  ctx.fill();
-  ctx.restore();
-
-  ctx.save();
-  roundRectPath(ctx, sx, sy, screenW, screenH, Math.round(screenW * 0.135));
-  ctx.clip();
-  drawInto(ctx, img, sx, sy, screenW, screenH);
-  ctx.restore();
-
-  const iw = Math.round(screenW * 0.3);
-  const ih = Math.round(screenW * 0.085);
-  roundRectPath(ctx, Math.round(sx + (screenW - iw) / 2), Math.round(sy + bezel * 1.1), iw, ih, ih / 2);
-  ctx.fillStyle = '#050505';
-  ctx.fill();
-  return { bodyH };
-}
-
-/** Android (Pixel-neutral): dark unibody, uniform bezel, centred punch-hole camera. */
-export function drawAndroidPhoneFrame(ctx, img, cx, cy, screenW) {
-  const screenH = screenW * (img.height / img.width);
-  const bezel = Math.round(screenW * 0.035);
-  const bodyW = screenW + bezel * 2;
-  const bodyH = screenH + bezel * 2;
-  const bodyX = Math.round(cx - bodyW / 2);
-  const bodyY = Math.round(cy - bodyH / 2);
-  const sx = bodyX + bezel;
-  const sy = bodyY + bezel;
-
-  ctx.save();
-  ctx.shadowColor = 'rgba(0,0,0,0.4)';
-  ctx.shadowBlur = Math.round(screenW * 0.09);
-  ctx.shadowOffsetY = Math.round(screenW * 0.035);
-  roundRectPath(ctx, bodyX, bodyY, bodyW, bodyH, Math.round(screenW * 0.13));
-  ctx.fillStyle = '#0b0b0a';
-  ctx.fill();
-  ctx.restore();
-
-  ctx.save();
-  roundRectPath(ctx, sx, sy, screenW, screenH, Math.round(screenW * 0.105));
-  ctx.clip();
-  drawInto(ctx, img, sx, sy, screenW, screenH);
-  ctx.restore();
-
-  // Centred punch-hole camera near the top edge.
-  ctx.beginPath();
-  ctx.arc(sx + screenW / 2, sy + bezel * 1.6, Math.round(screenW * 0.018), 0, Math.PI * 2);
-  ctx.fillStyle = '#050505';
-  ctx.fill();
-  return { bodyH };
-}
-
-/** iPad: dark unibody, tight even bezel, gentler corners, no island. */
-export function drawIpadFrame(ctx, img, cx, cy, screenW) {
-  const screenH = screenW * (img.height / img.width);
-  const bezel = Math.round(screenW * 0.024);
-  const bodyW = screenW + bezel * 2;
-  const bodyH = screenH + bezel * 2;
-  const bodyX = Math.round(cx - bodyW / 2);
-  const bodyY = Math.round(cy - bodyH / 2);
-  const sx = bodyX + bezel;
-  const sy = bodyY + bezel;
-
-  ctx.save();
-  ctx.shadowColor = 'rgba(0,0,0,0.36)';
-  ctx.shadowBlur = Math.round(screenW * 0.06);
-  ctx.shadowOffsetY = Math.round(screenW * 0.024);
-  roundRectPath(ctx, bodyX, bodyY, bodyW, bodyH, Math.round(screenW * 0.05));
-  ctx.fillStyle = '#0b0b0a';
-  ctx.fill();
-  ctx.restore();
-
-  ctx.save();
-  roundRectPath(ctx, sx, sy, screenW, screenH, Math.round(screenW * 0.035));
-  ctx.clip();
-  drawInto(ctx, img, sx, sy, screenW, screenH);
-  ctx.restore();
-  return { bodyH };
-}
-
-/** Apple Watch: round dark unibody, thin ring, a crown nub; the square capture is clipped to the circle. */
-export function drawWatchFrame(ctx, img, cx, cy, diameter) {
-  const screenR = diameter / 2;
-  const bezel = Math.round(diameter * 0.05);
-  const bodyR = screenR + bezel;
-
-  ctx.save();
-  ctx.shadowColor = 'rgba(0,0,0,0.4)';
-  ctx.shadowBlur = Math.round(diameter * 0.08);
-  ctx.shadowOffsetY = Math.round(diameter * 0.03);
-  ctx.beginPath();
-  ctx.arc(cx, cy, bodyR, 0, Math.PI * 2);
-  ctx.fillStyle = '#0b0b0a';
-  ctx.fill();
-  ctx.restore();
-
-  // Crown nub on the right edge.
-  const crownW = Math.round(diameter * 0.03);
-  const crownH = Math.round(diameter * 0.12);
-  roundRectPath(ctx, cx + bodyR - Math.round(crownW * 0.35), cy - crownH / 2, crownW, crownH, Math.round(crownW * 0.5));
-  ctx.fillStyle = '#1a1a18';
-  ctx.fill();
-
-  ctx.save();
-  ctx.beginPath();
-  ctx.arc(cx, cy, screenR, 0, Math.PI * 2);
-  ctx.clip();
-  drawInto(ctx, img, cx - screenR, cy - screenR, diameter, diameter);
-  ctx.restore();
-  return { bodyH: bodyR * 2 };
-}
-
-/** Dispatch by frame id → the draw fn (null for unsupported → caller falls back to a plain still). */
-export function frameFor(id) {
-  return {
-    phone: drawPhoneFrame, iphone: drawPhoneFrame,
-    android: drawAndroidPhoneFrame,
-    ipad: drawIpadFrame, tablet: drawIpadFrame,
-    watch: drawWatchFrame,
-  }[id] || null; // 'mac' etc. → no added frame
-}
-
-/** Infer a frame id from a screenshot target id (order matters: play-phone → android before → phone). */
-export function inferFrame(target) {
-  if (/watch|wear/.test(target)) return 'watch';
-  if (/ipad|tablet/.test(target)) return 'ipad';
-  if (/play.*phone|android/.test(target)) return 'android';
-  if (/iphone|phone/.test(target)) return 'phone';
-  return null;
-}
+/**
+ * Device frames for the `framed` screenshot style — an iPhone bezel (Dynamic Island), an iPad bezel, or a
+ * round Apple-Watch ring, with the capture drawn inside. The screen rect follows the capture's OWN aspect,
+ * so nothing is cropped. Ported from a production store-asset pipeline; pure rendering.
+ *
+ * (Mac captures are already windowed — traffic-light title bar — so Mac uses the plain premium still; no
+ *  extra window frame is drawn here.)
+ */
+import { roundRectPath } from './canvas.mjs';
+
+/**
+ * Paint the screen area. `screen` is either an image (cover-fit, as before) or a callback
+ * `(ctx, x, y, w, h) => void` that paints it — the hook that lets the reel scroll content inside a device
+ * that itself never moves. With a callback the caller must say how tall the screen is via `opts.aspect`,
+ * since there's no image to measure.
+ */
+function paintScreen(ctx, screen, x, y, w, h) {
+  if (typeof screen === 'function') return screen(ctx, x, y, w, h);
+  return drawInto(ctx, screen, x, y, w, h);
+}
+
+/** Screen height for a frame: the image's own aspect, or an explicit one when painting via callback. */
+const screenHeight = (screen, screenW, opts) =>
+  screenW * (typeof screen === 'function' ? (opts.aspect ?? 2.165) : screen.height / screen.width);
+
+/** Cover-fit an image into a rect (preserve aspect, crop overflow). */
+function drawInto(ctx, img, x, y, w, h) {
+  const sAspect = img.height / img.width;
+  let dw = w;
+  let dh = w * sAspect;
+  if (dh < h) {
+    dh = h;
+    dw = h / sAspect;
+  }
+  ctx.drawImage(img, x + (w - dw) / 2, y + (h - dh) / 2, dw, dh);
+}
+
+/** iPhone: dark unibody, thin uniform bezel, centred Dynamic Island. */
+export function drawPhoneFrame(ctx, img, cx, cy, screenW, opts = {}) {
+  const screenH = screenHeight(img, screenW, opts);
+  const bezel = Math.round(screenW * 0.032);
+  const bodyW = screenW + bezel * 2;
+  const bodyH = screenH + bezel * 2;
+  const bodyX = Math.round(cx - bodyW / 2);
+  const bodyY = Math.round(cy - bodyH / 2);
+  const sx = bodyX + bezel;
+  const sy = bodyY + bezel;
+
+  ctx.save();
+  ctx.shadowColor = 'rgba(0,0,0,0.4)';
+  ctx.shadowBlur = Math.round(screenW * 0.09);
+  ctx.shadowOffsetY = Math.round(screenW * 0.035);
+  roundRectPath(ctx, bodyX, bodyY, bodyW, bodyH, Math.round(screenW * 0.155));
+  ctx.fillStyle = '#0b0b0a';
+  ctx.fill();
+  ctx.restore();
+
+  ctx.save();
+  roundRectPath(ctx, sx, sy, screenW, screenH, Math.round(screenW * 0.135));
+  ctx.clip();
+  paintScreen(ctx, img, sx, sy, screenW, screenH);
+  ctx.restore();
+
+  const iw = Math.round(screenW * 0.3);
+  const ih = Math.round(screenW * 0.085);
+  roundRectPath(ctx, Math.round(sx + (screenW - iw) / 2), Math.round(sy + bezel * 1.1), iw, ih, ih / 2);
+  ctx.fillStyle = '#050505';
+  ctx.fill();
+  return { bodyH, bodyY, screen: { x: sx, y: sy, w: screenW, h: screenH, r: Math.round(screenW * 0.135) } };
+}
+
+/** Android (Pixel-neutral): dark unibody, uniform bezel, centred punch-hole camera. */
+export function drawAndroidPhoneFrame(ctx, img, cx, cy, screenW, opts = {}) {
+  const screenH = screenHeight(img, screenW, opts);
+  const bezel = Math.round(screenW * 0.035);
+  const bodyW = screenW + bezel * 2;
+  const bodyH = screenH + bezel * 2;
+  const bodyX = Math.round(cx - bodyW / 2);
+  const bodyY = Math.round(cy - bodyH / 2);
+  const sx = bodyX + bezel;
+  const sy = bodyY + bezel;
+
+  ctx.save();
+  ctx.shadowColor = 'rgba(0,0,0,0.4)';
+  ctx.shadowBlur = Math.round(screenW * 0.09);
+  ctx.shadowOffsetY = Math.round(screenW * 0.035);
+  roundRectPath(ctx, bodyX, bodyY, bodyW, bodyH, Math.round(screenW * 0.13));
+  ctx.fillStyle = '#0b0b0a';
+  ctx.fill();
+  ctx.restore();
+
+  ctx.save();
+  roundRectPath(ctx, sx, sy, screenW, screenH, Math.round(screenW * 0.105));
+  ctx.clip();
+  paintScreen(ctx, img, sx, sy, screenW, screenH);
+  ctx.restore();
+
+  // Centred punch-hole camera near the top edge.
+  ctx.beginPath();
+  ctx.arc(sx + screenW / 2, sy + bezel * 1.6, Math.round(screenW * 0.018), 0, Math.PI * 2);
+  ctx.fillStyle = '#050505';
+  ctx.fill();
+  return { bodyH, bodyY, screen: { x: sx, y: sy, w: screenW, h: screenH, r: Math.round(screenW * 0.105) } };
+}
+
+/** iPad: dark unibody, tight even bezel, gentler corners, no island. */
+export function drawIpadFrame(ctx, img, cx, cy, screenW, opts = {}) {
+  const screenH = screenHeight(img, screenW, opts);
+  const bezel = Math.round(screenW * 0.024);
+  const bodyW = screenW + bezel * 2;
+  const bodyH = screenH + bezel * 2;
+  const bodyX = Math.round(cx - bodyW / 2);
+  const bodyY = Math.round(cy - bodyH / 2);
+  const sx = bodyX + bezel;
+  const sy = bodyY + bezel;
+
+  ctx.save();
+  ctx.shadowColor = 'rgba(0,0,0,0.36)';
+  ctx.shadowBlur = Math.round(screenW * 0.06);
+  ctx.shadowOffsetY = Math.round(screenW * 0.024);
+  roundRectPath(ctx, bodyX, bodyY, bodyW, bodyH, Math.round(screenW * 0.05));
+  ctx.fillStyle = '#0b0b0a';
+  ctx.fill();
+  ctx.restore();
+
+  ctx.save();
+  roundRectPath(ctx, sx, sy, screenW, screenH, Math.round(screenW * 0.035));
+  ctx.clip();
+  paintScreen(ctx, img, sx, sy, screenW, screenH);
+  ctx.restore();
+  return { bodyH, bodyY, screen: { x: sx, y: sy, w: screenW, h: screenH, r: Math.round(screenW * 0.035) } };
+}
+
+/** Apple Watch: round dark unibody, thin ring, a crown nub; the square capture is clipped to the circle. */
+export function drawWatchFrame(ctx, img, cx, cy, diameter) {
+  const screenR = diameter / 2;
+  const bezel = Math.round(diameter * 0.05);
+  const bodyR = screenR + bezel;
+
+  ctx.save();
+  ctx.shadowColor = 'rgba(0,0,0,0.4)';
+  ctx.shadowBlur = Math.round(diameter * 0.08);
+  ctx.shadowOffsetY = Math.round(diameter * 0.03);
+  ctx.beginPath();
+  ctx.arc(cx, cy, bodyR, 0, Math.PI * 2);
+  ctx.fillStyle = '#0b0b0a';
+  ctx.fill();
+  ctx.restore();
+
+  // Crown nub on the right edge.
+  const crownW = Math.round(diameter * 0.03);
+  const crownH = Math.round(diameter * 0.12);
+  roundRectPath(ctx, cx + bodyR - Math.round(crownW * 0.35), cy - crownH / 2, crownW, crownH, Math.round(crownW * 0.5));
+  ctx.fillStyle = '#1a1a18';
+  ctx.fill();
+
+  ctx.save();
+  ctx.beginPath();
+  ctx.arc(cx, cy, screenR, 0, Math.PI * 2);
+  ctx.clip();
+  drawInto(ctx, img, cx - screenR, cy - screenR, diameter, diameter);
+  ctx.restore();
+  return { bodyH: bodyR * 2 };
+}
+
+/** Dispatch by frame id → the draw fn (null for unsupported → caller falls back to a plain still). */
+export function frameFor(id) {
+  return {
+    phone: drawPhoneFrame, iphone: drawPhoneFrame,
+    android: drawAndroidPhoneFrame,
+    ipad: drawIpadFrame, tablet: drawIpadFrame,
+    watch: drawWatchFrame,
+  }[id] || null; // 'mac' etc. → no added frame
+}
+
+/** Infer a frame id from a screenshot target id (order matters: play-phone → android before → phone). */
+export function inferFrame(target) {
+  if (/watch|wear/.test(target)) return 'watch';
+  // Play targets are matched FIRST: `play-tablet` contains "tablet", so an ipad/tablet test placed above
+  // this would frame Android tablet captures in an iPad body — the same misrepresentation we refuse to
+  // make on phones.
+  if (/^play/.test(target) || /android/.test(target)) return 'android';
+  if (/ipad|tablet/.test(target)) return 'ipad';
+  if (/iphone|phone/.test(target)) return 'phone';
+  return null;
+}

package/src/graphic.mjs

@@ -1,77 +1,107 @@
-/**
- * Feature graphic — Google Play's 1024×500 listing banner (no alpha). A brand matte with the logo +
- * wordmark + tagline on the left and a tilted device (a hero capture in a frame) bleeding off the right.
- * Ported/generalized from a production store-asset pipeline; brand-driven.
- */
-import fs from 'node:fs';
-import path from 'node:path';
-import { createCanvas, loadImage } from '@napi-rs/canvas';
-import { font, hexA, roundRectPath, fillVerticalGradient, radialGlow } from './canvas.mjs';
-import { frameFor, drawAndroidPhoneFrame } from './frames.mjs';
-import { rgbPngBuffer } from './png.mjs';
-
-const DEFAULT = { matteTop: '#052E16', matteBottom: '#0b0b0a', glow: null, glowAlpha: 0.22 };
-
-/** Split a tagline into ≤2 lines (on the first sentence break, else the whole thing). */
-function splitTagline(t) {
-  if (!t) return ['', ''];
-  const m = t.match(/^(.*?[.!?])\s+(.*)$/);
-  return m ? [m[1], m[2]] : [t, ''];
-}
-
-/** Build the 1024×500 feature graphic → writes a no-alpha PNG. `frame`: which device frame for the hero. */
-export async function buildFeatureGraphic({ W = 1024, H = 500, brand, theme, heroPath, outFile, frame = 'android' }) {
-  const th = { ...DEFAULT, ...(theme || {}) };
-  const glow = th.glow || brand.sub;
-  const c = createCanvas(W, H);
-  const ctx = c.getContext('2d');
-  fillVerticalGradient(ctx, W, H, th.matteTop, th.matteBottom);
-  radialGlow(ctx, W * 0.3, H * 0.5, W * 0.5, glow, th.glowAlpha);
-
-  const leftX = 72;
-  const iconSize = 92;
-  const logo = brand.logo && fs.existsSync(brand.logo) ? await loadImage(brand.logo) : null;
-  if (logo) {
-    ctx.save();
-    roundRectPath(ctx, leftX, 70, iconSize, iconSize, iconSize * 0.22);
-    ctx.clip();
-    ctx.drawImage(logo, leftX, 70, iconSize, iconSize);
-    ctx.restore();
-  }
-  ctx.textAlign = 'left';
-  ctx.textBaseline = 'middle';
-  ctx.font = font(76, 'bold');
-  ctx.fillStyle = brand.title;
-  ctx.fillText(brand.name || 'App', leftX + (logo ? iconSize + 26 : 0), 70 + iconSize / 2 + 4);
-
-  ctx.textBaseline = 'top';
-  const [t1, t2] = splitTagline(brand.tagline);
-  ctx.font = font(48, 'bold');
-  ctx.fillStyle = brand.title;
-  if (t1) ctx.fillText(t1, leftX, 220);
-  if (t2) {
-    ctx.fillStyle = brand.sub;
-    ctx.fillText(t2, leftX, 278);
-  }
-  if (brand.endsub) {
-    ctx.font = font(28, 'regular');
-    ctx.fillStyle = hexA(brand.sub, 0.85);
-    ctx.fillText(brand.endsub, leftX, 352);
-  }
-
-  if (heroPath && fs.existsSync(heroPath)) {
-    const hero = await loadImage(heroPath);
-    const pc = createCanvas(640, 960);
-    const pctx = pc.getContext('2d');
-    (frameFor(frame) || drawAndroidPhoneFrame)(pctx, hero, pc.width / 2, pc.height / 2, 250);
-    ctx.save();
-    ctx.translate(W - 150, H / 2 + 40);
-    ctx.rotate(-0.12);
-    ctx.drawImage(pc, -pc.width / 2, -pc.height / 2);
-    ctx.restore();
-  }
-
-  fs.mkdirSync(path.dirname(outFile), { recursive: true });
-  fs.writeFileSync(outFile, rgbPngBuffer(c));
-  return { outFile, W, H };
-}
+/**
+ * Feature graphic — Google Play's 1024×500 listing banner (no alpha). A brand matte with the logo +
+ * wordmark + tagline on the left and a tilted device (a hero capture in a frame) bleeding off the right.
+ * Ported/generalized from a production store-asset pipeline; brand-driven.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createCanvas, loadImage } from '@napi-rs/canvas';
+import { font, hexA, roundRectPath, fillVerticalGradient, radialGlow } from './canvas.mjs';
+import { frameFor, drawAndroidPhoneFrame } from './frames.mjs';
+import { rgbPngBuffer } from './png.mjs';
+
+const DEFAULT = { matteTop: '#052E16', matteBottom: '#0b0b0a', glow: null, glowAlpha: 0.22 };
+
+/** Split a tagline into ≤2 lines (on the first sentence break, else the whole thing). */
+function splitTagline(t) {
+  if (!t) return ['', ''];
+  const m = t.match(/^(.*?[.!?])\s+(.*)$/);
+  return m ? [m[1], m[2]] : [t, ''];
+}
+
+/** Build the 1024×500 feature graphic → writes a no-alpha PNG. `frame`: which device frame for the hero. */
+export async function buildFeatureGraphic({ W = 1024, H = 500, brand, theme, heroPath, outFile, frame = 'android' }) {
+  const th = { ...DEFAULT, ...(theme || {}) };
+  const glow = th.glow || brand.sub;
+  const c = createCanvas(W, H);
+  const ctx = c.getContext('2d');
+  fillVerticalGradient(ctx, W, H, th.matteTop, th.matteBottom);
+  radialGlow(ctx, W * 0.3, H * 0.5, W * 0.5, glow, th.glowAlpha);
+
+  const leftX = 72;
+  const iconSize = 92;
+  const logo = brand.logo && fs.existsSync(brand.logo) ? await loadImage(brand.logo) : null;
+  if (logo) {
+    ctx.save();
+    roundRectPath(ctx, leftX, 70, iconSize, iconSize, iconSize * 0.22);
+    ctx.clip();
+    ctx.drawImage(logo, leftX, 70, iconSize, iconSize);
+    ctx.restore();
+  }
+  ctx.textAlign = 'left';
+  ctx.textBaseline = 'middle';
+  ctx.font = font(76, 'bold');
+  ctx.fillStyle = brand.title;
+  ctx.fillText(brand.name || 'App', leftX + (logo ? iconSize + 26 : 0), 70 + iconSize / 2 + 4);
+
+  ctx.textBaseline = 'top';
+  const [t1, t2] = splitTagline(brand.tagline);
+  ctx.font = font(48, 'bold');
+  ctx.fillStyle = brand.title;
+  if (t1) ctx.fillText(t1, leftX, 220);
+  if (t2) {
+    ctx.fillStyle = brand.sub;
+    ctx.fillText(t2, leftX, 278);
+  }
+  if (brand.endsub) {
+    ctx.font = font(28, 'regular');
+    ctx.fillStyle = hexA(brand.sub, 0.85);
+    ctx.fillText(brand.endsub, leftX, 352);
+  }
+
+  if (heroPath && fs.existsSync(heroPath)) {
+    const hero = await loadImage(heroPath);
+    const pc = createCanvas(640, 960);
+    const pctx = pc.getContext('2d');
+    (frameFor(frame) || drawAndroidPhoneFrame)(pctx, hero, pc.width / 2, pc.height / 2, 250);
+    ctx.save();
+    ctx.translate(W - 150, H / 2 + 40);
+    ctx.rotate(-0.12);
+    ctx.drawImage(pc, -pc.width / 2, -pc.height / 2);
+    ctx.restore();
+  }
+
+  fs.mkdirSync(path.dirname(outFile), { recursive: true });
+  fs.writeFileSync(outFile, rgbPngBuffer(c));
+  return { outFile, W, H };
+}
+
+
+/**
+ * The Play app icon — 512×512, 32-bit PNG, alpha allowed (the ONE store asset where it is).
+ *
+ * This is a branded graphic, not a per-scene screenshot: it renders `brand.logo` on the brand ground,
+ * which is why the target carries `graphic: true`. If no logo is configured we refuse rather than emit a
+ * blank square — a silently-empty icon is worse than a clear error at build time.
+ */
+export async function buildAppIcon({ W = 512, H = 512, brand, theme, outFile }) {
+  const th = { ...DEFAULT, ...(theme || {}) };
+  if (!brand.logo || !fs.existsSync(brand.logo)) {
+    throw new Error(
+      "play-icon needs `brand.logo` — a square PNG of your app icon. Set it, or drop the 'play-icon' target " +
+      '(Play also accepts the icon uploaded straight to the Console, so this target is a convenience).',
+    );
+  }
+  const c = createCanvas(W, H);
+  const ctx = c.getContext('2d');
+  const logo = await loadImage(brand.logo);
+  // Fill the square: Play shows the icon masked to its own shape, so bleed to the edges and let the
+  // store apply the mask. Any transparency in the source logo is preserved (alpha is legal here).
+  const a = logo.height / logo.width;
+  let dw = W;
+  let dh = W * a;
+  if (dh < H) { dh = H; dw = H / a; }
+  ctx.drawImage(logo, (W - dw) / 2, (H - dh) / 2, dw, dh);
+  fs.writeFileSync(outFile, c.toBuffer('image/png')); // RGBA — do NOT route through rgbPngBuffer
+  return { outFile, W, H };
+}

package/src/index.mjs

@@ -1,12 +1,27 @@
-/** Programmatic API — use the engine directly without the CLI. */
-export { buildVideo } from './video.mjs';
-export { buildReel } from './reel.mjs';
-export { buildPremium } from './premium.mjs';
-export { buildDeviceScreenshots } from './screenshots.mjs';
-export { buildFeatureGraphic } from './graphic.mjs';
-export { renderStill } from './still.mjs';
-export { rgbPngBuffer } from './png.mjs';
-export { loadConfig } from './config.mjs';
-export { registerFonts } from './fonts.mjs';
-export { VIDEO_TARGETS, IMAGE_TARGETS, videoTarget } from './specs.mjs';
-export { run } from './cli.mjs';
+/** Programmatic API — use the engine directly without the CLI. */
+
+/**
+ * Identity helper for `zdymak.config.mjs` — returns the config unchanged, but lets an editor type-check
+ * and autocomplete it from `types/index.d.ts` without the project needing TypeScript:
+ *
+ *   import { defineConfig } from 'zdymak';
+ *   export default defineConfig({ … });
+ *
+ * @param {import('../types/index.js').Config} config
+ * @returns {import('../types/index.js').Config}
+ */
+export const defineConfig = (config) => config;
+
+export { buildVideo } from './video.mjs';
+export { buildReel } from './reel.mjs';
+export { buildPremium } from './premium.mjs';
+export { buildDeviceScreenshots, localizeScenes, untranslatedScenes, localizeBrand } from './screenshots.mjs';
+export { buildFeatureGraphic } from './graphic.mjs';
+export { renderStill } from './still.mjs';
+export { rgbPngBuffer } from './png.mjs';
+export { loadConfig } from './config.mjs';
+export { registerFonts } from './fonts.mjs';
+export { VIDEO_TARGETS, IMAGE_TARGETS, videoTarget } from './specs.mjs';
+export { TRANSITIONS, TRANSITION_IDS, transitionFor } from './transitions.mjs';
+export { EFFECTS, EFFECT_IDS, effectFor } from './effects.mjs';
+export { run } from './cli.mjs';