@inglorious/capacitor 0.1.0 → 0.2.0

package/README.md

@@ -4,8 +4,9 @@
 
 Native project setup for [Capacitor](https://capacitorjs.com) apps, written once in `package.json` instead of clicked through Xcode and Android Studio. `@inglorious/create-app --mobile` sets it up for you.
 
-- `inglorious-capacitor configure` writes the app's native settings into `android/` and `ios/` after every `cap sync`: App Links and Universal Links, the signing team, push, Analytics off until consent, permissions and Info.plist entries, and the Firebase files.
+- `inglorious-capacitor configure` writes the app's native settings into `android/` and `ios/` after every `cap sync`: App Links and Universal Links, the signing team, push, Analytics off until consent and without the advertising ID, permissions and Info.plist entries, and the Firebase files.
 - `inglorious-capacitor assets` makes every icon and splash screen, light and dark, from one logo.
+- `inglorious-capacitor listing-assets` captures store screenshots of the running app in every size and language, and makes the promotional images (Google Play's feature graphic, a header and a search results card) and Google Play's 512px icon.
 
 ## Installation
 
@@ -21,7 +22,8 @@ Run `configure` as Capacitor's `sync` hook, so `cap add` and `cap sync` both app
     "capacitor:sync:after": "inglorious-capacitor configure",
     "mobile:init:ios": "cap add ios && inglorious-capacitor assets --ios",
     "mobile:init:android": "cap add android && inglorious-capacitor assets --android",
-    "mobile:assets": "inglorious-capacitor assets"
+    "mobile:assets": "inglorious-capacitor assets",
+    "mobile:listing-assets": "inglorious-capacitor listing-assets"
   }
 }
 ```
@@ -63,20 +65,20 @@ The `native` key of `package.json` holds them all. Every key is optional; the ap
 
 ### What `configure` does
 
-| Setting                                   | iOS                                                                                                        | Android                              |
-| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------ |
-| `appLinks`                                | Associated Domains entitlement                                                                             | Verified intent filter for `paths`   |
-| `appLinks` + `teamId`                     | `public/.well-known/apple-app-site-association`                                                            |                                      |
-| `appLinks` + `sha256`                     |                                                                                                            | `public/.well-known/assetlinks.json` |
-| `ios.teamId`                              | `DEVELOPMENT_TEAM`, so Xcode signs without asking                                                          |                                      |
-| `ios.swipeBack`                           | A swipe from the left edge goes back: WebKit's back gesture, turned on in a generated `MainViewController` |                                      |
-| `ios.infoPlist`                           | Info.plist entries                                                                                         |                                      |
-| `android.permissions`                     |                                                                                                            | `<uses-permission>` entries          |
-| `@capacitor-firebase/messaging` installed | Push entitlement, background mode, AppDelegate methods                                                     |                                      |
-| `@capacitor-firebase/analytics` installed | Collection off until consent                                                                               | Collection off until consent         |
-| `GoogleService-Info.plist` in the root    | Copied into the app target                                                                                 |                                      |
-| `google-services.json` in the root        |                                                                                                            | Copied to `android/app/`             |
-| always                                    |                                                                                                            | Keystores kept out of git            |
+| Setting                                   | iOS                                                                                                        | Android                                                        |
+| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `appLinks`                                | Associated Domains entitlement                                                                             | Verified intent filter for `paths`                             |
+| `appLinks` + `teamId`                     | `public/.well-known/apple-app-site-association`                                                            |                                                                |
+| `appLinks` + `sha256`                     |                                                                                                            | `public/.well-known/assetlinks.json`                           |
+| `ios.teamId`                              | `DEVELOPMENT_TEAM`, so Xcode signs without asking                                                          |                                                                |
+| `ios.swipeBack`                           | A swipe from the left edge goes back: WebKit's back gesture, turned on in a generated `MainViewController` |                                                                |
+| `ios.infoPlist`                           | Info.plist entries                                                                                         |                                                                |
+| `android.permissions`                     |                                                                                                            | `<uses-permission>` entries                                    |
+| `@capacitor-firebase/messaging` installed | Push entitlement, background mode, AppDelegate methods                                                     |                                                                |
+| `@capacitor-firebase/analytics` installed | Collection off until consent                                                                               | Collection off until consent, and no advertising ID permission |
+| `GoogleService-Info.plist` in the root    | Copied into the app target                                                                                 |                                                                |
+| `google-services.json` in the root        |                                                                                                            | Copied to `android/app/`                                       |
+| always                                    |                                                                                                            | Keystores kept out of git                                      |
 
 Path patterns end in `*` to match a prefix: `/jobs*` is every path that starts with `/jobs`. `exclude` takes paths and, starting with `#`, fragments; only iOS can exclude, so on Android list in `paths` only what opens the app. Serve both `.well-known` files as `application/json`.
 
@@ -86,6 +88,70 @@ It runs for the platform Capacitor is syncing, and changes nothing when the sett
 
 It centres the logo (`public/logo.svg` or `public/logo.png` by default) on `background` for the icons and the splash screen, and on `backgroundDark` for the dark splash screen, then hands the result to [`@capacitor/assets`](https://github.com/ionic-team/capacitor-assets) for every size and density. `iconScale` and `splashScale` are the logo's width as a share of the icon and of the splash screen. Pass `--ios` or `--android` for one platform.
 
+## Store listing images
+
+`listing-assets` opens the running app in your installed Chrome (through `playwright-core`, so no browser download) and captures the screens listed in `listing.config.js`, once per device and language:
+
+```js
+/** @type {import("@inglorious/capacitor").ListingConfig} */
+export default {
+  url: "http://localhost:5173",
+  locales: ["en", "it"],
+  localeParam: "lang",
+  storage: { "app-analytics": { consent: "denied" } },
+
+  async signIn(page, { url }) {
+    await page.goto(`${url}/login`)
+    await page.fill('input[type="email"]', "demo@example.com")
+    await page.keyboard.press("Enter")
+    await page.fill('input[type="password"]', "demo-password")
+    await page.keyboard.press("Enter")
+    await page.waitForURL((address) => address.pathname !== "/login")
+  },
+
+  screens: [
+    { name: "01-feed", path: "/jobs" },
+    {
+      name: "02-new-job",
+      path: "/jobs/new",
+      prepare: (page) => page.getByLabel("Title").fill("Wedding in Puglia"),
+    },
+  ],
+
+  promo: {
+    tagline: { en: "Can't make it?\nPass it on.", it: "Non puoi?\nPassalo." },
+    subtitle: { en: "Jobs between colleagues.", it: "Lavori tra colleghi." },
+    accent: "#b4532a",
+  },
+}
+```
+
+It writes to `listing-assets/`:
+
+- `<device>/<locale>/<screen>.png` for each device in `devices`:
+
+  | Device       | Size      | For                                         |
+  | ------------ | --------- | ------------------------------------------- |
+  | `iphone-6.9` | 1320×2868 | App Store, required (default)               |
+  | `iphone-6.3` | 1206×2622 | App Store, optional                         |
+  | `ipad-13`    | 2064×2752 | App Store, required if the app runs on iPad |
+  | `android`    | 1080×1920 | Google Play phones (default)                |
+  | `tablet-7`   | 1080×1920 | Google Play 7" tablets                      |
+  | `tablet-10`  | 1440×2560 | Google Play 10" tablets                     |
+
+- the promotional images for each locale, on `native.assets.background` unless `promo.background` says otherwise, with `promo.color`, `promo.font` and an optional `promo.accent` bar:
+  - `feature-graphic-<locale>.png`, 1024×500 (Google Play): the logo beside the app's name and `promo.tagline`.
+  - `header-<locale>.png`, 3840×1646: the logo, name and tagline in the middle 3:2 an iPhone shows, between two framed screenshots.
+  - `search-results-<locale>.png`, 1920×1280: the logo, name, tagline and `promo.subtitle` beside one framed screenshot.
+
+  The framed screenshots are `promo.screens` (the first two `screens` by default) from `promo.device` (the first iPhone by default).
+
+- `icon-512.png`: Google Play's icon, made like the app icon.
+
+`storage` sets `localStorage` before the app starts, so prompts such as analytics consent or push stay out of the shots; it can be a function of the locale. `localeParam` adds the language to each screen's address. If the app takes the language from the signed-in account instead, choose it in `signIn`. `prepare` brings a screen to the state worth showing, after it loads and settles for `settle` milliseconds (1000 by default).
+
+Screenshots show real data, so use a demo account on a local backend with realistic seed data, never production.
+
 ## License
 
 **MIT License - Free and open source**

package/bin/inglorious-capacitor.js

@@ -6,7 +6,9 @@ const USAGE = `Usage: inglorious-capacitor <command>
   configure            Apply the "native" settings in package.json to the
                        native projects (runs after every cap sync)
   assets [--ios] [--android]
-                       Make the app icons and splash screens from the logo`
+                       Make the app icons and splash screens from the logo
+  listing-assets       Capture store screenshots of the running app, and make
+                       Google Play's feature graphic and icon (listing.config.js)`
 
 const FIRST_ARGUMENT = 2
 const SUCCESS = 0
@@ -22,6 +24,9 @@ try {
   } else if (command === "assets") {
     const { assets } = await import("../src/assets/index.js")
     await assets({ platforms: flags.map((flag) => flag.replace(/^--/, "")) })
+  } else if (command === "listing-assets") {
+    const { listingAssets } = await import("../src/listing-assets/index.js")
+    console.log(`Listing assets in ${await listingAssets()}`)
   } else {
     console.log(USAGE)
     process.exitCode = command ? FAILURE : SUCCESS

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@inglorious/capacitor",
-  "version": "0.1.0",
-  "description": "Configures Capacitor's native projects from package.json, and makes their icons and splash screens from one logo.",
+  "version": "0.2.0",
+  "description": "Configures Capacitor's native projects from package.json, makes their icons and splash screens from one logo, and the screenshots and graphics the stores ask for.",
   "author": "Matteo Antony Mistretta <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",
   "repository": {
@@ -19,7 +19,8 @@
     "app-links",
     "icons",
     "splash-screen",
-    "inglorious-web"
+    "inglorious-web",
+    "store-listing"
   ],
   "type": "module",
   "bin": {
@@ -42,6 +43,7 @@
   "dependencies": {
     "@capacitor/assets": "^4.0.0",
     "@trapezedev/project": "^7.1.11",
+    "playwright-core": "^1.65.0",
     "plist": "^3.1.1",
     "sharp": "^0.35.5"
   },

package/src/assets/index.js

@@ -16,7 +16,7 @@ const SOURCES = path.join(
   "assets",
 )
 const PLATFORMS = ["ios", "android"]
-const DEFAULTS = {
+export const ASSET_DEFAULTS = {
   background: "#ffffff",
   backgroundDark: "#121212",
   iconScale: 0.6,
@@ -37,14 +37,8 @@ const TRANSPARENT = "#00000000"
  */
 export async function assets({ root = process.cwd(), platforms = [] } = {}) {
   const settings = await readSettings(root, {})
-  const options = { ...DEFAULTS, ...settings.assets }
-  const logo =
-    options.logo ?? LOGOS.find((file) => existsSync(path.join(root, file)))
-  if (!logo || !existsSync(path.join(root, logo))) {
-    throw new Error(
-      `No logo found: add ${LOGOS.join(" or ")}, or set native.assets.logo`,
-    )
-  }
+  const options = { ...ASSET_DEFAULTS, ...settings.assets }
+  const logo = findLogo(root, options)
 
   const targets = (platforms.length ? platforms : PLATFORMS).filter(
     (platform) =>
@@ -59,7 +53,7 @@ export async function assets({ root = process.cwd(), platforms = [] } = {}) {
   const sources = path.join(root, SOURCES)
   rmSync(sources, { recursive: true, force: true })
   mkdirSync(sources, { recursive: true })
-  await composeSources(readFileSync(path.join(root, logo)), sources, options)
+  await composeSources(readFileSync(logo), sources, options)
 
   execFileSync(
     process.execPath,
@@ -74,6 +68,22 @@ export async function assets({ root = process.cwd(), platforms = [] } = {}) {
   )
 }
 
+/**
+ * @param {string} root
+ * @param {{ logo?: string }} options
+ * @returns {string} The logo's full path.
+ */
+export function findLogo(root, { logo } = {}) {
+  const file =
+    logo ?? LOGOS.find((candidate) => existsSync(path.join(root, candidate)))
+  if (!file || !existsSync(path.join(root, file))) {
+    throw new Error(
+      `No logo found: add ${LOGOS.join(" or ")}, or set native.assets.logo`,
+    )
+  }
+  return path.join(root, file)
+}
+
 /**
  * The sources `@capacitor/assets` expects, so it never scales the logo itself:
  * it would size the splash from the image's width, not the mark's.

package/src/configure/android.js

@@ -11,12 +11,17 @@ const ANALYTICS_OFF = [
   "firebase_analytics_collection_enabled",
   "google_analytics_adid_collection_enabled",
 ]
+const AD_ID_PERMISSIONS = [
+  "com.google.android.gms.permission.AD_ID",
+  "android.permission.ACCESS_ADSERVICES_AD_ID",
+]
+const TOOLS_NAMESPACE = "http://schemas.android.com/tools"
 const GOOGLE_SERVICES = "google-services.json"
 const KEYSTORES = ["*.jks", "*.keystore"]
 
 /**
  * Applies the settings to the Android project: App Links, Analytics off until
- * consent, extra permissions, the Firebase file, and keystores kept out of git.
+ * consent and without the advertising ID, extra permissions, the Firebase file, and keystores kept out of git.
  *
  * @param {import("@trapezedev/project").MobileProject} project
  * @param {import("../../types/index.d.ts").ProjectSettings} settings
@@ -45,6 +50,7 @@ export function configureAndroid(project, settings) {
         `<meta-data android:name="${name}" android:value="false" />`,
       )
     }
+    removeAdIdPermissions(manifest)
   }
 
   for (const permission of settings.android.permissions) {
@@ -69,6 +75,23 @@ export function configureAndroid(project, settings) {
   ignoreKeystores(path.join(androidRoot, ".gitignore"))
 }
 
+function removeAdIdPermissions(manifest) {
+  manifest.setAttrs(MANIFEST, { "xmlns:tools": TOOLS_NAMESPACE })
+  for (const permission of AD_ID_PERMISSIONS) {
+    if (
+      manifest.find(
+        `${MANIFEST}/uses-permission[@android:name='${permission}']`,
+      )?.length
+    ) {
+      continue
+    }
+    manifest.injectFragment(
+      MANIFEST,
+      `<uses-permission android:name="${permission}" tools:node="remove" />`,
+    )
+  }
+}
+
 function appLinksFilter(appLinks) {
   const data = intentFilterData(appLinks)
     .map(

package/src/configure/configure.test.js

@@ -85,6 +85,15 @@ describe("configure", () => {
     expect(first.manifest).toContain(
       '<meta-data android:name="firebase_analytics_collection_enabled" android:value="false" />',
     )
+    expect(first.manifest).toContain(
+      'xmlns:tools="http://schemas.android.com/tools"',
+    )
+    expect(first.manifest).toMatch(
+      /android:name="com\.google\.android\.gms\.permission\.AD_ID"[^>]*tools:node="remove"/,
+    )
+    expect(first.manifest).toMatch(
+      /android:name="android\.permission\.ACCESS_ADSERVICES_AD_ID"[^>]*tools:node="remove"/,
+    )
     expect(first.manifest).toContain(
       '<uses-permission android:name="android.permission.RECORD_AUDIO" />',
     )
@@ -128,6 +137,23 @@ describe("configure", () => {
     expect(entitlements).toContain("applinks:new.example.com")
   })
 
+  it("keeps the formatting of App Links files with the same content", async () => {
+    writePackage(root, {
+      native: {
+        appLinks: { domain: "app.example.com" },
+        android: { sha256: ["AA:BB"] },
+      },
+    })
+    await configure({ root, env: { CAPACITOR_CONFIG } })
+    const file = path.join(root, "public", ".well-known", "assetlinks.json")
+    const compact = JSON.stringify(JSON.parse(readFileSync(file, "utf8")))
+    writeFileSync(file, compact)
+
+    await configure({ root, env: { CAPACITOR_CONFIG } })
+
+    expect(readFileSync(file, "utf8")).toBe(compact)
+  })
+
   it("turns on iOS swipe back with a view controller of its own", async () => {
     writePackage(root, { native: { ios: { swipeBack: true } } })
 

package/src/configure/index.js

@@ -81,8 +81,15 @@ function writeWellKnown(settings) {
 }
 
 function writeJson(file, value) {
-  const source = JSON.stringify(value, null, INDENTATION) + EOL
-  if (existsSync(file) && readFileSync(file, "utf8") === source) return
+  if (existsSync(file) && isSameJson(readFileSync(file, "utf8"), value)) return
   mkdirSync(path.dirname(file), { recursive: true })
-  writeFileSync(file, source)
+  writeFileSync(file, JSON.stringify(value, null, INDENTATION) + EOL)
+}
+
+function isSameJson(source, value) {
+  try {
+    return JSON.stringify(JSON.parse(source)) === JSON.stringify(value)
+  } catch {
+    return false
+  }
 }

package/src/index.js

@@ -1,3 +1,4 @@
 export { assets } from "./assets/index.js"
 export { readSettings } from "./config.js"
 export { configure } from "./configure/index.js"
+export { listingAssets } from "./listing-assets/index.js"

package/src/listing-assets/devices.js

@@ -0,0 +1,42 @@
+/**
+ * Store screenshot sizes, as a viewport in CSS pixels and a pixel ratio whose
+ * product is the size the store asks for.
+ */
+export const DEVICES = {
+  "iphone-6.9": { viewport: { width: 440, height: 956 }, scale: 3 },
+  "iphone-6.3": { viewport: { width: 402, height: 874 }, scale: 3 },
+  "ipad-13": { viewport: { width: 1032, height: 1376 }, scale: 2 },
+  android: { viewport: { width: 360, height: 640 }, scale: 3 },
+  "tablet-7": { viewport: { width: 540, height: 960 }, scale: 2 },
+  "tablet-10": { viewport: { width: 720, height: 1280 }, scale: 2 },
+}
+
+export const DEFAULT_DEVICES = ["iphone-6.9", "android"]
+
+/**
+ * @param {string[]} names
+ * @returns {[string, typeof DEVICES[keyof typeof DEVICES]][]}
+ */
+export function resolveDevices(names = DEFAULT_DEVICES) {
+  const unknown = names.filter((name) => !(name in DEVICES))
+  if (unknown.length) {
+    throw new Error(
+      `Unknown devices: ${unknown.join(", ")}. Choose from ${Object.keys(DEVICES).join(", ")}`,
+    )
+  }
+  return names.map((name) => [name, DEVICES[name]])
+}
+
+/**
+ * The address of a screen in a locale: `localeParam` added to the path's own
+ * query, if the app reads the locale from links.
+ *
+ * @param {string} base
+ * @param {string} screenPath
+ * @param {{ locale?: string, localeParam?: string }} [options]
+ */
+export function screenUrl(base, screenPath, { locale, localeParam } = {}) {
+  const url = new URL(screenPath, base)
+  if (locale && localeParam) url.searchParams.set(localeParam, locale)
+  return url.href
+}

package/src/listing-assets/index.js

@@ -0,0 +1,220 @@
+import { existsSync, mkdirSync, readFileSync } from "node:fs"
+import path from "node:path"
+import process from "node:process"
+import { pathToFileURL } from "node:url"
+
+import sharp from "sharp"
+
+import { ASSET_DEFAULTS, findLogo } from "../assets/index.js"
+import { readSettings } from "../config.js"
+import { resolveDevices, screenUrl } from "./devices.js"
+import { PROMO_FORMATS, promoHtml } from "./promo.js"
+
+const CONFIG_FILES = ["listing.config.js", "listing.config.mjs"]
+const DEFAULTS = {
+  url: "http://localhost:5173",
+  out: "listing-assets",
+  browser: "chrome",
+  settle: 1000,
+}
+const PROMO_SHOTS = 2
+const LANGUAGE_TIMEOUT = 5000
+const FIRST = 0
+const PLAY_ICON_SIZE = 512
+
+/**
+ * Makes what the stores ask for besides the app: screenshots of the running
+ * app at each store size and in each locale, the promotional images (Google
+ * Play's feature graphic, a header and a search results card) in each locale,
+ * and Google Play's 512px icon. The screens, the locales and how to sign in
+ * come from `listing.config.js`; the logo and colours from `native.assets`.
+ *
+ * @param {{ root?: string }} [options]
+ * @returns {Promise<string>} The folder written to.
+ */
+export async function listingAssets({ root = process.cwd() } = {}) {
+  const settings = await readSettings(root, {})
+  const config = { ...DEFAULTS, ...(await readListingConfig(root)) }
+  const assets = { ...ASSET_DEFAULTS, ...settings.assets }
+  const logo = findLogo(root, assets)
+  const out = path.join(root, config.out)
+  const locales = config.locales?.length ? config.locales : [null]
+  const devices = resolveDevices(config.devices)
+
+  await assertReachable(config.url)
+  mkdirSync(out, { recursive: true })
+
+  const { chromium } = await import("playwright-core")
+  const browser = await chromium.launch({ channel: config.browser })
+  try {
+    for (const locale of locales) {
+      let session
+      for (const [device, { viewport, scale }] of devices) {
+        const dir = path.join(out, device, locale ?? "")
+        mkdirSync(dir, { recursive: true })
+        const context = await browser.newContext({
+          viewport,
+          deviceScaleFactor: scale,
+          isMobile: true,
+          hasTouch: true,
+          ...(locale && { locale }),
+          ...(session && { storageState: session }),
+        })
+        await context.addInitScript(
+          storageScript,
+          storageEntries(config.storage, locale),
+        )
+        const page = await context.newPage()
+        if (config.signIn && !session) {
+          await config.signIn(page, { url: config.url, locale })
+          session = await context.storageState()
+        }
+        for (const screen of config.screens ?? []) {
+          await page.goto(
+            screenUrl(config.url, screen.path, {
+              locale,
+              localeParam: config.localeParam,
+            }),
+          )
+          await page.waitForLoadState("networkidle")
+          await page.waitForTimeout(config.settle)
+          if (locale) await assertLanguage(page, locale, screen.name)
+          if (screen.prepare) await screen.prepare(page, { locale })
+          await page.screenshot({ path: path.join(dir, `${screen.name}.png`) })
+        }
+        await context.close()
+      }
+    }
+
+    const promo = config.promo ?? {}
+    const promoDevice = promo.device ?? defaultPromoDevice(devices)
+    const promoScreens =
+      promo.screens ??
+      (config.screens ?? []).slice(FIRST, PROMO_SHOTS).map(({ name }) => name)
+    for (const locale of locales) {
+      const options = {
+        logo: dataUrl(logo),
+        name: settings.appName,
+        tagline: localized(promo.tagline, locale),
+        subtitle: localized(promo.subtitle, locale),
+        shots: promoScreens.map((name) =>
+          dataUrl(path.join(out, promoDevice, locale ?? "", `${name}.png`)),
+        ),
+        background: promo.background ?? assets.background,
+        color: promo.color,
+        accent: promo.accent,
+        font: promo.font,
+      }
+      for (const [format, { width, height, scale }] of Object.entries(
+        PROMO_FORMATS,
+      )) {
+        const page = await browser.newPage({
+          viewport: { width, height },
+          deviceScaleFactor: scale,
+        })
+        await page.setContent(promoHtml(format, options))
+        await page.waitForLoadState("load")
+        await page.screenshot({
+          path: path.join(
+            out,
+            locale ? `${format}-${locale}.png` : `${format}.png`,
+          ),
+        })
+        await page.close()
+      }
+    }
+  } finally {
+    await browser.close()
+  }
+
+  await playIcon(logo, assets, path.join(out, "icon-512.png"))
+  return out
+}
+
+async function assertLanguage(page, locale, screen) {
+  try {
+    await page.waitForFunction(
+      (expected) => {
+        const { lang } = globalThis.document.documentElement
+        return !lang || lang === expected || lang.startsWith(`${expected}-`)
+      },
+      locale,
+      { timeout: LANGUAGE_TIMEOUT },
+    )
+  } catch {
+    const lang = await page.evaluate(
+      () => globalThis.document.documentElement.lang,
+    )
+    throw new Error(
+      `${screen} shows "${lang}" instead of "${locale}": check localeParam, or choose the language in signIn`,
+    )
+  }
+}
+
+function defaultPromoDevice(devices) {
+  const [[first]] = devices
+  const [iphone] = devices.find(([name]) => name.startsWith("iphone")) ?? []
+  return iphone ?? first
+}
+
+async function readListingConfig(root) {
+  const file = CONFIG_FILES.map((name) => path.join(root, name)).find(
+    (candidate) => existsSync(candidate),
+  )
+  if (!file) {
+    throw new Error(
+      `No listing config found: add listing.config.js with the screens to capture`,
+    )
+  }
+  const { default: config } = await import(pathToFileURL(file).href)
+  return config
+}
+
+async function assertReachable(url) {
+  try {
+    await fetch(url)
+  } catch {
+    throw new Error(`Nothing answers at ${url}: start the app first`)
+  }
+}
+
+function storageEntries(storage, locale) {
+  const values = typeof storage === "function" ? storage(locale) : storage
+  return Object.entries(values ?? {}).map(([key, value]) => [
+    key,
+    typeof value === "string" ? value : JSON.stringify(value),
+  ])
+}
+
+function storageScript(entries) {
+  for (const [key, value] of entries) localStorage.setItem(key, value)
+}
+
+function localized(value, locale) {
+  if (value == null || typeof value === "string") return value ?? ""
+  const [first = ""] = Object.values(value)
+  return value[locale] ?? first
+}
+
+function dataUrl(file) {
+  const type = file.endsWith(".svg") ? "image/svg+xml" : "image/png"
+  return `data:${type};base64,${readFileSync(file).toString("base64")}`
+}
+
+async function playIcon(logo, { background, iconScale }, file) {
+  const mark = await sharp(readFileSync(logo))
+    .resize(Math.round(PLAY_ICON_SIZE * iconScale))
+    .png()
+    .toBuffer()
+  await sharp({
+    create: {
+      width: PLAY_ICON_SIZE,
+      height: PLAY_ICON_SIZE,
+      channels: 4,
+      background,
+    },
+  })
+    .composite([{ input: mark, gravity: "centre" }])
+    .png()
+    .toFile(file)
+}

package/src/listing-assets/listing-assets.test.js

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest"
+
+import { DEFAULT_DEVICES, resolveDevices, screenUrl } from "./devices.js"
+import { promoHtml } from "./promo.js"
+
+describe("resolveDevices", () => {
+  it("defaults to the sizes both stores require", () => {
+    expect(resolveDevices().map(([name]) => name)).toEqual(DEFAULT_DEVICES)
+  })
+
+  it("gives each device the store's pixel size", () => {
+    const [[, iphone]] = resolveDevices(["iphone-6.9"])
+    expect(iphone.viewport.width * iphone.scale).toBe(1320)
+    expect(iphone.viewport.height * iphone.scale).toBe(2868)
+  })
+
+  it("names the devices it doesn't know", () => {
+    expect(() => resolveDevices(["iphone-6.9", "watch"])).toThrow("watch")
+  })
+})
+
+describe("screenUrl", () => {
+  it("adds the locale to the path's own query", () => {
+    expect(
+      screenUrl("http://localhost:5173", "/jobs?status=open", {
+        locale: "it",
+        localeParam: "lang",
+      }),
+    ).toBe("http://localhost:5173/jobs?status=open&lang=it")
+  })
+
+  it("leaves the path alone when the app doesn't read the locale from links", () => {
+    expect(screenUrl("http://localhost:5173", "/jobs", { locale: "it" })).toBe(
+      "http://localhost:5173/jobs",
+    )
+  })
+})
+
+describe("promoHtml", () => {
+  const options = {
+    logo: "data:image/png;base64,",
+    name: "Tom & Jerry",
+    tagline: "First <line>\nSecond",
+    background: "#fff",
+  }
+
+  it("escapes the name and breaks the tagline into lines", () => {
+    const html = promoHtml("feature-graphic", options)
+    expect(html).toContain("Tom &amp; Jerry")
+    expect(html).toContain("First &lt;line&gt;<br>Second")
+  })
+
+  it("frames a screenshot at each edge of the header", () => {
+    const html = promoHtml("header", { ...options, shots: ["a.png", "b.png"] })
+    expect(html).toMatch(/src="a\.png"[^>]*left:/)
+    expect(html).toMatch(/src="b\.png"[^>]*right:/)
+  })
+
+  it("leaves out what isn't given", () => {
+    const html = promoHtml("search-results", options)
+    expect(html).not.toContain('<img src="a.png')
+    expect(html).not.toContain("opacity")
+  })
+})

package/src/listing-assets/promo.js

@@ -0,0 +1,186 @@
+/**
+ * The promotional images, in CSS pixels rendered at `scale`:
+ * - `feature-graphic`: Google Play's banner above the listing.
+ * - `header`: a wide banner whose middle 3:2 is what an iPhone shows, so the
+ *   text stays there and the screenshots sit at the edges.
+ * - `search-results`: a 3:2 card, the text beside one screenshot.
+ */
+export const PROMO_FORMATS = {
+  "feature-graphic": { width: 1024, height: 500, scale: 1 },
+  header: { width: 1920, height: 823, scale: 2 },
+  "search-results": { width: 960, height: 640, scale: 2 },
+}
+
+const DEFAULT_COLOR = "#1f1f1f"
+const DEFAULT_FONT = "system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif"
+const PERCENT = 100
+const HALF = 2
+
+// Sizes in hundredths of the image's height.
+const FEATURE_GRAPHIC = {
+  gap: 11,
+  padding: 16,
+  logo: 40,
+  name: 19,
+  tagline: 7.5,
+}
+const HEADER = {
+  safeRatio: 1.5,
+  phoneTop: 11,
+  phoneSide: 2,
+  phoneHeight: 79,
+  textTop: 18,
+  textBottom: 8,
+  logo: 16,
+  name: 17,
+  taglineGap: 5,
+  tagline: 8.5,
+}
+const SEARCH_RESULTS = {
+  textShare: 0.55,
+  padding: 8,
+  phoneHeight: 82,
+  logo: 14,
+  name: 13,
+  taglineGap: 5,
+  tagline: 6.5,
+  subtitleGap: 3,
+  subtitle: 3.6,
+  subtitleOpacity: 0.75,
+}
+const BRAND_GAP = 3
+const ACCENT = { gap: 4, width: 14, height: 1 }
+const PHONE = { radius: 5, border: 0.9, shadowY: 2, shadowBlur: 6 }
+
+const LAYOUTS = {
+  "feature-graphic": featureGraphic,
+  header,
+  "search-results": searchResults,
+}
+
+/**
+ * @param {keyof typeof PROMO_FORMATS} format
+ * @param {{ logo: string, name: string, tagline?: string, subtitle?: string, shots?: string[], background: string, color?: string, accent?: string, font?: string }} options
+ *   `logo` and `shots` are image addresses.
+ * @returns {string} A whole HTML page.
+ */
+export function promoHtml(format, options) {
+  const { width, height } = PROMO_FORMATS[format]
+  const style = {
+    color: DEFAULT_COLOR,
+    font: DEFAULT_FONT,
+    tagline: "",
+    subtitle: "",
+    shots: [],
+    ...options,
+  }
+  const unit = height / PERCENT
+  return `<!doctype html><html><body style="margin:0">
+<div style="position:relative;width:${width}px;height:${height}px;box-sizing:border-box;overflow:hidden;
+  background:${style.background};color:${style.color};font-family:${style.font}">
+${LAYOUTS[format]({ width, height, unit, ...style })}
+</div></body></html>`
+}
+
+function featureGraphic({ unit, logo, name, tagline }) {
+  const size = scaled(FEATURE_GRAPHIC, unit)
+  return `<div style="height:100%;display:flex;align-items:center;gap:${size.gap}px;padding:0 ${size.padding}px">
+  <img src="${logo}" style="height:${size.logo}px;flex:none">
+  <div>
+    <div style="font-size:${size.name}px;line-height:1">${escapeHtml(name)}</div>
+    ${text(tagline, `margin-top:${size.tagline}px;font-size:${size.tagline}px;line-height:1.25`)}
+  </div>
+</div>`
+}
+
+function header({
+  width,
+  height,
+  unit,
+  logo,
+  name,
+  tagline,
+  shots,
+  color,
+  accent,
+}) {
+  const size = scaled(HEADER, unit)
+  const safeWidth = Math.round(height * HEADER.safeRatio)
+  const safeLeft = (width - safeWidth) / HALF
+  const [left, right] = shots
+  const placement = (side) =>
+    `top:${size.phoneTop}px;${side}:${size.phoneSide}px;height:${size.phoneHeight}px`
+  return `${left ? phone(left, unit, color, placement("left")) : ""}
+${right ? phone(right, unit, color, placement("right")) : ""}
+<div style="position:absolute;left:${safeLeft}px;width:${safeWidth}px;top:${size.textTop}px;bottom:${size.textBottom}px;
+  display:flex;flex-direction:column;align-items:center;justify-content:center;text-align:center">
+  ${brand(unit, logo, name, size)}
+  ${text(tagline, `margin-top:${size.taglineGap}px;font-size:${size.tagline}px;line-height:1.2`)}
+  ${accentBar(unit, accent)}
+</div>`
+}
+
+function searchResults({
+  width,
+  unit,
+  logo,
+  name,
+  tagline,
+  subtitle,
+  shots,
+  color,
+  accent,
+}) {
+  const size = scaled(SEARCH_RESULTS, unit)
+  const [shot] = shots
+  return `<div style="height:100%;display:flex;align-items:center;justify-content:space-between;padding:0 ${size.padding}px">
+  <div style="max-width:${width * SEARCH_RESULTS.textShare}px">
+    ${brand(unit, logo, name, size)}
+    ${text(tagline, `margin-top:${size.taglineGap}px;font-size:${size.tagline}px;line-height:1.2`)}
+    ${text(subtitle, `margin-top:${size.subtitleGap}px;font-size:${size.subtitle}px;line-height:1.4;opacity:${SEARCH_RESULTS.subtitleOpacity}`)}
+    ${accentBar(unit, accent)}
+  </div>
+  ${shot ? phone(shot, unit, color, `position:static;height:${size.phoneHeight}px`) : ""}
+</div>`
+}
+
+function scaled(sizes, unit) {
+  return Object.fromEntries(
+    Object.entries(sizes).map(([key, value]) => [key, value * unit]),
+  )
+}
+
+function brand(unit, logo, name, size) {
+  return `<div style="display:flex;align-items:center;gap:${BRAND_GAP * unit}px">
+    <img src="${logo}" style="height:${size.logo}px">
+    <span style="font-size:${size.name}px;line-height:1">${escapeHtml(name)}</span>
+  </div>`
+}
+
+function text(value, style) {
+  return value ? `<div style="${style}">${lines(value)}</div>` : ""
+}
+
+function accentBar(unit, accent) {
+  if (!accent) return ""
+  const size = scaled(ACCENT, unit)
+  return `<div style="margin-top:${size.gap}px;width:${size.width}px;height:${size.height}px;border-radius:${size.height}px;background:${accent}"></div>`
+}
+
+function phone(src, unit, color, placement) {
+  const size = scaled(PHONE, unit)
+  return `<img src="${src}" style="position:absolute;${placement};border-radius:${size.radius}px;
+  border:${size.border}px solid ${color};box-shadow:0 ${size.shadowY}px ${size.shadowBlur}px rgba(0,0,0,.2)">`
+}
+
+function lines(value) {
+  return escapeHtml(value).split("\n").join("<br>")
+}
+
+function escapeHtml(value) {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+}

package/types/index.d.ts

@@ -81,6 +81,82 @@ export declare function configure(options?: {
   env?: NodeJS.ProcessEnv
 }): Promise<string[]>
 
+/** A device whose store screenshots `listingAssets` captures. */
+export type ListingDevice =
+  "iphone-6.9" | "iphone-6.3" | "ipad-13" | "android" | "tablet-7" | "tablet-10"
+
+/** The default export of `listing.config.js`. */
+export interface ListingConfig {
+  /** The running app. Defaults to `http://localhost:5173`. */
+  url?: string
+  /** One set of screenshots each. Defaults to one set, in the browser's locale. */
+  locales?: string[]
+  /** The query parameter the app reads the locale from, such as `lang`. */
+  localeParam?: string
+  /** Defaults to `["iphone-6.9", "android"]`. */
+  devices?: ListingDevice[]
+  /** Defaults to `listing-assets`. */
+  out?: string
+  /** The Playwright browser channel. Defaults to `chrome`. */
+  browser?: string
+  /** Milliseconds to wait after a screen loads. Defaults to `1000`. */
+  settle?: number
+  /**
+   * `localStorage` entries set before the app starts, such as answers to the
+   * consent and push prompts, so they stay out of the screenshots.
+   */
+  storage?:
+    | Record<string, unknown>
+    | ((locale: string | null) => Record<string, unknown>)
+  /** Signs the demo account in, once per locale: the other devices reuse the session. */
+  signIn?: (
+    page: import("playwright-core").Page,
+    context: { url: string; locale: string | null },
+  ) => Promise<void>
+  /** In the order the stores show them. */
+  screens: {
+    /** The file name, such as `01-feed`. */
+    name: string
+    path: string
+    /** Brings the screen to the state worth showing, such as a filled form. */
+    prepare?: (
+      page: import("playwright-core").Page,
+      context: { locale: string | null },
+    ) => Promise<void>
+  }[]
+  /** The feature graphic, header and search results images. */
+  promo?: {
+    /** One line, or one per locale. A newline breaks the line. */
+    tagline?: string | Record<string, string>
+    /** The search results card's smaller line under the tagline. */
+    subtitle?: string | Record<string, string>
+    /**
+     * The screenshots framed in the header (both) and search results card
+     * (the first). Defaults to the first two `screens`.
+     */
+    screens?: string[]
+    /** Whose screenshots to frame. Defaults to the first iPhone in `devices`. */
+    device?: ListingDevice
+    /** Defaults to `native.assets.background`. */
+    background?: string
+    /** Text and phone frames. Defaults to `#1f1f1f`. */
+    color?: string
+    /** A short bar under the text, in this colour. None by default. */
+    accent?: string
+    /** A CSS font-family. Defaults to the system font. */
+    font?: string
+  }
+}
+
+/**
+ * Captures store screenshots of the running app and makes the promotional
+ * images and Google Play's 512px icon, from `listing.config.js`.
+ * @returns The folder written to.
+ */
+export declare function listingAssets(options?: {
+  root?: string
+}): Promise<string>
+
 /** Makes the native icons and splash screens from one logo. */
 export declare function assets(options?: {
   root?: string