@sempods/apps 0.7.0 → 0.8.0-dev.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sempods/apps",
-  "version": "0.7.0",
+  "version": "0.8.0-dev.1",
   "description": "Tooling for a sempods apps repository: create, check, update and publish several sempods apps with one shared SDK version.",
   "keywords": [
     "sempods",
@@ -55,8 +55,8 @@
     "unified-engine": "11.2.2"
   },
   "peerDependencies": {
-    "@sempods/app-sdk": "^0.5.0",
-    "@sempods/client-sdk": "^0.5.0"
+    "@sempods/app-sdk": "^0.6.0",
+    "@sempods/client-sdk": "^0.6.0"
   },
   "scripts": {}
 }

package/scripts/build-site.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // Builds every app with a published profile into its path of one static site
-// folder, site-dist/, and writes the overview and the host's routing files.
+// folder, site-dist/, with a page for each route, and writes the overview and
+// the host's routing files.
 // apps/<id>/dist keeps the app's local build.
 // Usage: pnpm run build-site [--profile production|preview]
 //        (or SEMPODS_SITE_PROFILE=<profile> in the host's environment)
@@ -15,7 +16,7 @@ import {
 import { join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
-import { readApps, SITE_PROFILES, siteIdentity } from './lib/apps.mjs';
+import { AUTO, readApps, SITE_PROFILES, siteIdentity } from './lib/apps.mjs';
 import { PROFILE_MODES, staleGenerated } from './lib/generate.mjs';
 import { ifPresent, writeJson } from './lib/json.mjs';
 import { renderNotFound, renderOverview } from './lib/overview.mjs';
@@ -79,7 +80,9 @@ function overviewEntry(app, outDir) {
   const entry = {
     id: app.id,
     title: app.title,
-    language: app.language,
+    ...(app.description ? { description: app.description } : {}),
+    // An app that follows the browser has no one language to announce.
+    ...(app.language === AUTO ? {} : { language: app.language }),
     href: app.path,
   };
   if (existsSync(join(outDir, 'icon-192.png')))
@@ -143,6 +146,15 @@ export function buildSite(root, { profile = 'production', build = appBuild } = {
     // so without a redirect.
     const callback = new URL(redirectUri).pathname;
     writeFileSync(join(out, `${callback.slice(1)}.html`), html);
+    // Each route answers the same way from a copy of the page, so the host
+    // needs no rewrite and unknown paths still show the not-found page.
+    for (const route of app.routes ?? []) {
+      if (['', '.html'].some((ext) => existsSync(join(appOut, route + ext))))
+        throw new Error(
+          `apps/${app.id}: the route ${route} collides with ${route} in the app's build output; rename one of them.`,
+        );
+      writeFileSync(join(appOut, `${route}.html`), html);
+    }
 
     entries.push(overviewEntry(app, appOut));
   }

package/scripts/check.mjs

@@ -21,6 +21,7 @@ import { parseArgs } from 'node:util';
 import semver from 'semver';
 import { readApps } from './lib/apps.mjs';
 import { staleGenerated } from './lib/generate.mjs';
+import { pageProblems } from './lib/page.mjs';
 import { migrationState } from './migrate.mjs';
 import { readJson, writeJson } from './lib/json.mjs';
 import { repositoryRoot, TOOLING } from './lib/paths.mjs';
@@ -120,6 +121,7 @@ export function staticProblems(root, { tooling = TOOLING } = {}) {
       problems.push(
         `apps/${app.id}/${file} does not match apps.json; regenerate it instead of editing`,
       );
+    problems.push(...pageProblems(dir, app.id));
     const pkg = readJson(join(dir, 'package.json'));
     for (const sdk of SDK)
       expect(`apps/${app.id}`, sdk, pkg.dependencies?.[sdk]);
@@ -156,7 +158,7 @@ export function staticProblems(root, { tooling = TOOLING } = {}) {
       !semver.satisfies(version, range, { includePrerelease: true })
     )
       problems.push(
-        `${sdk} ${version} is outside the range ${toolingManifest.name} ${toolingManifest.version} supports (${range}); update ${toolingManifest.name} or use a supported SDK version`,
+        `${sdk} ${version} is outside the range ${toolingManifest.name} ${toolingManifest.version} supports (${range}); move the SDK with pnpm run sdk-update <version> in that range, or update ${toolingManifest.name}`,
       );
   }
   // The app-author reference ships inside the installed SDK.

package/scripts/icon.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Draws an app's icon again: the monogram of its title in apps.json, in the
+// accent of the theme its src/main.tsx imports, for example after a rename or
+// a theme change. It replaces public/favicon.svg, icon-192.png and
+// icon-512.png. Usage: pnpm run icon <id>
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readApps } from './lib/apps.mjs';
+import { writeAppIcons } from './lib/icon.mjs';
+import { repositoryRoot } from './lib/paths.mjs';
+import { scriptArgs } from './lib/pnpm.mjs';
+import { appTheme, iconColours, themeCss } from './lib/themes.mjs';
+
+/** Writes the icons of app `id`; returns them as apps/<id>/<file>. */
+export function drawIcon(root, id) {
+  const app = readApps(root).apps.find((entry) => entry.id === id);
+  if (!app) throw new Error(`apps.json lists no app "${id}"`);
+  const dir = join(root, 'apps', id);
+  if (!existsSync(dir)) throw new Error(`apps/${id} is missing`);
+  const theme = appTheme(dir);
+  if (!theme || !existsSync(join(dir, 'src', 'themes', `${theme}.css`)))
+    throw new Error(
+      `apps/${id}/src/main.tsx imports no theme from src/themes/; import one as the skeleton does, then run this again`,
+    );
+  return writeAppIcons(dir, app.title, iconColours(themeCss(dir, theme))).map(
+    (file) => `apps/${id}/${file}`,
+  );
+}
+
+if (
+  process.argv[1] &&
+  resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  const [id, ...rest] = scriptArgs();
+  if (!id || rest.length > 0) {
+    console.error('Usage: pnpm run icon <id>');
+    process.exit(2);
+  }
+  try {
+    const files = drawIcon(repositoryRoot(), id);
+    console.log(`Drew:\n${files.map((file) => `  ${file}`).join('\n')}`);
+  } catch (error) {
+    console.error(`icon: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/lib/apps.mjs

@@ -5,7 +5,10 @@ import { readJson, writeJson } from './json.mjs';
 
 export const SCHEMA_VERSION = 1;
 export const FIRST_DEV_PORT = 5174;
+// The UI languages of the SDK; "auto" follows the browser among them.
 export const LANGUAGES = ['en', 'de'];
+export const AUTO = 'auto';
+export const APP_LANGUAGES = [AUTO, ...LANGUAGES];
 // Where the site is published (configure-site): one origin per profile and the
 // host whose routing build-site writes for.
 export const SITE_PROFILES = ['production', 'preview'];
@@ -46,6 +49,45 @@ export function invalidId(id) {
   return undefined;
 }
 
+// Routes answer as <id>/<route>.html next to the app's own build output.
+const ROUTE_RESERVED = new Set([
+  'assets',
+  'callback',
+  'did',
+  'index',
+  'licenses',
+]);
+
+/**
+ * Returns a reason when `description` cannot describe an app, otherwise
+ * undefined. It is optional: one short sentence for the sign-in screen, the
+ * installed app and the overview.
+ */
+export function invalidDescription(description) {
+  if (description === undefined) return undefined;
+  if (typeof description !== 'string' || description.trim() === '')
+    return 'description must be text';
+  if (description.trim().length > 120)
+    return 'description must be one short sentence, at most 120 characters';
+  return undefined;
+}
+
+/** Returns a reason when `route` cannot name a route, otherwise undefined. */
+export function invalidRoute(route) {
+  if (
+    typeof route !== 'string' ||
+    !ID_PATTERN.test(route) ||
+    route.endsWith('-')
+  )
+    return 'a route is one lowercase segment: a letter, then up to 39 letters, digits or hyphens';
+  if (ROUTE_RESERVED.has(route))
+    return `"${route}" is reserved by the site layout`;
+  // build-site writes <route>.html, which Windows refuses for device names.
+  if (WINDOWS_DEVICES.has(route))
+    return `"${route}" is a reserved device name on Windows`;
+  return undefined;
+}
+
 /**
  * Returns a reason when `value` is not an origin as apps.json records it,
  * otherwise undefined. configure-site also lets the SDK check the identity.
@@ -134,9 +176,11 @@ export function validateApps(manifest) {
     ids.add(app.id);
     if (typeof app.title !== 'string' || app.title.trim() === '')
       problems.push(`${app.id}: title must be text`);
-    if (!LANGUAGES.includes(app.language))
+    const description = invalidDescription(app.description);
+    if (description) problems.push(`${app.id}: ${description}`);
+    if (!APP_LANGUAGES.includes(app.language))
       problems.push(
-        `${app.id}: language must be one of ${LANGUAGES.join(', ')}`,
+        `${app.id}: language must be one of ${APP_LANGUAGES.join(', ')}`,
       );
     if (app.path !== `/${app.id}/`)
       problems.push(`${app.id}: path must be "/${app.id}/"`);
@@ -151,6 +195,16 @@ export function validateApps(manifest) {
     ports.add(app.devPort);
     if (typeof app.pwa !== 'boolean')
       problems.push(`${app.id}: pwa must be true or false`);
+    if (app.routes !== undefined && !Array.isArray(app.routes))
+      problems.push(`${app.id}: routes must be a list`);
+    else if (app.routes)
+      app.routes.forEach((route, i) => {
+        const reason = invalidRoute(route);
+        if (reason)
+          problems.push(`${app.id}: route ${JSON.stringify(route)}: ${reason}`);
+        else if (app.routes.indexOf(route) !== i)
+          problems.push(`${app.id}: route ${route} is listed twice`);
+      });
   }
   return problems;
 }

package/scripts/lib/generate.mjs

@@ -3,7 +3,8 @@
 // apps.json, so tooling updates reach existing apps.
 import { readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { SITE_PROFILES, siteIdentity } from './apps.mjs';
+import { AUTO, SITE_PROFILES, siteIdentity } from './apps.mjs';
+import { escapeHtml } from './html.mjs';
 
 const HEADER = `// Generated from apps.json by @sempods/apps. Do not edit: change apps.json
 // and run pnpm run regenerate.`;
@@ -33,11 +34,31 @@ const ${name}: BrowserRuntimeOptions = {
     clientId: ${json(clientId)},
     redirectUri: ${json(redirectUri)},
   },
-  returnTo: app.basePath,
+  ${RETURN_TO[Boolean(app.routes?.length)]},
 };
 `;
 }
 
+// With routes, sign-in returns to the route it started from: the runtime
+// calls returnPath when each sign-in starts.
+const RETURN_TO = {
+  false: 'returnTo: app.basePath',
+  true: 'returnTo: returnPath',
+};
+
+const RETURN_PATH = `
+// The page sign-in returns to: the current route, otherwise the start page.
+function returnPath(): string {
+  const routes: readonly string[] = app.routes;
+  const route = location.pathname
+    .slice(app.basePath.length)
+    .replace(/\\/$/, '');
+  return location.pathname.startsWith(app.basePath) && routes.includes(route)
+    ? app.basePath + route
+    : app.basePath;
+}
+`;
+
 /**
  * Runtime settings per profile: local development with a dynamic identity on
  * loopback HTTP, and the did:web identities of the configured site origins.
@@ -47,17 +68,22 @@ export function runtimeSource(app, site) {
   const modes = SITE_PROFILES.map(
     (name) => `  ${json(PROFILE_MODES[name])}: ${json(name)},`,
   ).join('\n');
+  // "auto" stays a literal: the app resolves it from the browser.
+  const language =
+    app.language === AUTO ? json(AUTO) : `${json(app.language)} as Language`;
   return `${HEADER}
-import type { BrowserRuntimeOptions, Language } from '@sempods/app-sdk';
+import type { BrowserRuntimeOptions${app.language === AUTO ? '' : ', Language'} } from '@sempods/app-sdk';
 
 export const app = {
   id: ${json(app.id)},
   title: ${json(app.title)},
-  language: ${json(app.language)} as Language,
+  description: ${json(app.description ?? null)},
+  language: ${language},
   basePath: ${json(app.path)},
   pwa: ${app.pwa},
+  routes: ${json(app.routes ?? [])},
 } as const;
-
+${app.routes?.length ? RETURN_PATH : ''}
 // Local development: a dynamic identity, local HTTP only.
 const local: BrowserRuntimeOptions = {
   identity: {
@@ -69,7 +95,7 @@ const local: BrowserRuntimeOptions = {
       return \`\${location.origin}${app.path}callback\`;
     },
   },
-  returnTo: app.basePath,
+  ${RETURN_TO[Boolean(app.routes?.length)]},
   development: 'loopback-http',
 };
 ${published.map((name) => publishedProfile(name, site[name], app)).join('')}
@@ -95,9 +121,14 @@ export const runtimeOptions: BrowserRuntimeOptions =
 `;
 }
 
-/** Vite base path, development server and PWA settings for this app's path. */
+/** Vite base path, development server, page title and PWA settings. */
 export function viteSource(app) {
   const p = app.path;
+  // The start page and every route, with or without a trailing slash, as the
+  // app's router accepts them; route names need no escaping.
+  const routes = app.routes?.length
+    ? `((${app.routes.join('|')})\\/?)?`
+    : '';
   const escaped = p.replaceAll('/', '\\/');
   const pwa = app.pwa
     ? `{
@@ -109,12 +140,12 @@ export function viteSource(app) {
       id: ${json(p)},
       name: ${json(app.title)},
       short_name: ${json(app.title)},
-      lang: ${json(app.language)},
-      start_url: ${json(p)},
+${app.description ? `      description: ${json(app.description)},\n` : ''}${app.language === AUTO ? '' : `      lang: ${json(app.language)},
+`}      start_url: ${json(p)},
       scope: ${json(p)},
       display: 'standalone',
-      background_color: '#f6faf9',
-      theme_color: '#176354',
+      background_color: '#ffffff',
+      theme_color: '#ffffff',
       icons: [
         { src: ${json(`${p}icon-192.png`)}, sizes: '192x192', type: 'image/png' },
         { src: ${json(`${p}icon-512.png`)}, sizes: '512x512', type: 'image/png' },
@@ -124,10 +155,10 @@ export function viteSource(app) {
       // Precache the built shell only; nothing is cached at runtime.
       globPatterns: ['**/*.{js,css,html,png,svg,webmanifest}'],
       runtimeCaching: [],
-      // Serve the cached shell only for this app's start route. The callback,
-      // Pod and login pages always go to the network.
+      // Serve the cached shell only for this app's start page and routes. The
+      // callback, Pod and login pages always go to the network.
       navigateFallback: ${json(`${p}index.html`)},
-      navigateFallbackAllowlist: [/^${escaped}$/],
+      navigateFallbackAllowlist: [/^${escaped}${routes}$/],
       skipWaiting: false,
       clientsClaim: false,
       cleanupOutdatedCaches: true,
@@ -135,10 +166,20 @@ export function viteSource(app) {
   }`
     : 'null';
   return `${HEADER}
+import type { Plugin } from 'vite';
 import type { VitePWAOptions } from 'vite-plugin-pwa';
 
 export const base = ${json(p)};
 
+// The page title from apps.json, added to the head of every page Vite serves
+// or builds; index.html has no <title> of its own.
+export const pageTitle: Plugin = {
+  name: 'sempods-page-title',
+  transformIndexHtml: () => [
+    { tag: 'title', children: ${json(escapeHtml(app.title))}, injectTo: 'head' },
+  ],
+};
+
 export const server = {
   host: '127.0.0.1',
   port: ${app.devPort},

package/scripts/lib/icon.mjs

@@ -0,0 +1,192 @@
+// The default app icon: a monogram, the first letter of the app's title on a
+// rounded square in the theme's accent. new-app and icon write it as
+// public/favicon.svg and as the PNG icons of the web app manifest, all from
+// the same strokes, so no font or image tool is needed.
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { crc32, deflateSync } from 'node:zlib';
+
+const VIEW = 64;
+const RADIUS = 14;
+const STROKE = 5;
+// Letters are drawn in a box 28 units high from y = 18, centred horizontally.
+const TOP = 18;
+// The calm theme's accent and the text on it, in light and dark mode; only
+// the SVG can follow the page's mode.
+export const CALM = {
+  light: { background: '#1f2933', letter: '#ffffff' },
+  dark: { background: '#e5e7eb', letter: '#111315' },
+};
+
+/** Points along an elliptical arc; angles in degrees, 0 = right, 90 = down. */
+function arc(cx, cy, rx, ry, from, to) {
+  const steps = Math.max(2, Math.ceil(Math.abs(to - from) / 6));
+  return Array.from({ length: steps + 1 }, (_, i) => {
+    const angle = ((from + ((to - from) * i) / steps) * Math.PI) / 180;
+    return [cx + rx * Math.cos(angle), cy + ry * Math.sin(angle)];
+  });
+}
+
+// One entry per letter: strokes as lists of points in the letter's box.
+const GLYPHS = {
+  A: [[[0, 28], [11, 0], [22, 28]], [[4.5, 18], [17.5, 18]]],
+  B: [
+    [[0, 28], [0, 0], [10, 0], ...arc(10, 6.5, 6.5, 6.5, -90, 90), [0, 13]],
+    [[0, 13], [11, 13], ...arc(11, 20.5, 7.5, 7.5, -90, 90), [0, 28]],
+  ],
+  C: [arc(12, 14, 12, 14, -40, -320)],
+  D: [[[0, 0], [0, 28], [7, 28], ...arc(7, 14, 12, 14, 90, -90), [0, 0]]],
+  E: [[[17, 0], [0, 0], [0, 28], [17, 28]], [[0, 14], [13, 14]]],
+  F: [[[17, 0], [0, 0], [0, 28]], [[0, 14], [13, 14]]],
+  G: [[...arc(12, 14, 12, 14, -40, -360), [14, 14]]],
+  H: [[[0, 0], [0, 28]], [[18, 0], [18, 28]], [[0, 14], [18, 14]]],
+  I: [[[0, 0], [0, 28]]],
+  J: [[[14, 0], [14, 20], ...arc(7, 20, 7, 8, 0, 180)]],
+  K: [[[0, 0], [0, 28]], [[20, 0], [3, 15], [20, 28]]],
+  L: [[[0, 0], [0, 28], [16, 28]]],
+  M: [[[0, 28], [0, 0], [11, 18], [22, 0], [22, 28]]],
+  N: [[[0, 28], [0, 0], [18, 28], [18, 0]]],
+  O: [arc(12, 14, 12, 14, 0, 360)],
+  P: [[[0, 28], [0, 0], [10, 0], ...arc(10, 7.5, 7.5, 7.5, -90, 90), [0, 15]]],
+  Q: [arc(12, 14, 12, 14, 0, 360), [[14, 20], [23, 28]]],
+  R: [
+    [[0, 28], [0, 0], [10, 0], ...arc(10, 7.5, 7.5, 7.5, -90, 90), [0, 15]],
+    [[9, 15], [18, 28]],
+  ],
+  S: [[...arc(9, 7, 8.5, 7, -20, -270), ...arc(9, 21, 9, 7, -90, 160)]],
+  T: [[[0, 0], [20, 0]], [[10, 0], [10, 28]]],
+  U: [[[0, 0], [0, 19], ...arc(9, 19, 9, 9, 180, 0), [18, 0]]],
+  V: [[[0, 0], [10, 28], [20, 0]]],
+  W: [[[0, 0], [6, 28], [13, 8], [20, 28], [26, 0]]],
+  X: [[[0, 0], [19, 28]], [[19, 0], [0, 28]]],
+  Y: [[[0, 0], [10, 13], [20, 0]], [[10, 13], [10, 28]]],
+  Z: [[[0, 0], [18, 0], [0, 28], [18, 28]]],
+};
+
+/** The monogram letter of a title: its first letter A–Z, accents removed. */
+export function monogramLetter(title) {
+  const first = String(title).trim().normalize('NFD').charAt(0).toUpperCase();
+  return Object.hasOwn(GLYPHS, first) ? first : undefined;
+}
+
+/** The letter's strokes in icon coordinates, centred; none for no letter. */
+function strokes(letter) {
+  const glyph = GLYPHS[letter] ?? [];
+  const xs = glyph.flat().map(([x]) => x);
+  const shift = VIEW / 2 - (Math.min(...xs) + Math.max(...xs)) / 2;
+  return glyph.map((stroke) =>
+    stroke.map(([x, y]) => [x + shift, y + TOP]),
+  );
+}
+
+const round = (n) => Math.round(n * 100) / 100;
+const rgb = (hex) => [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16));
+
+/**
+ * The SVG icon. In dark mode it takes the theme's dark accent, so it keeps its
+ * contrast on a dark page.
+ */
+export function monogramSvg(letter, colours = CALM) {
+  const d = strokes(letter)
+    .map((stroke) =>
+      stroke
+        .map(([x, y], i) => `${i ? 'L' : 'M'}${round(x)} ${round(y)}`)
+        .join(''),
+    )
+    .join('');
+  const path = d
+    ? `<path d="${d}" fill="none" stroke-width="${STROKE}" stroke-linecap="round" stroke-linejoin="round"/>`
+    : '';
+  const style = ({ background, letter }) =>
+    `rect{fill:${background}}path{stroke:${letter}}`;
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${VIEW} ${VIEW}"><style>${style(colours.light)}@media (prefers-color-scheme:dark){${style(colours.dark)}}</style><rect width="${VIEW}" height="${VIEW}" rx="${RADIUS}"/>${path}</svg>\n`;
+}
+
+function segmentDistance([px, py], [ax, ay], [bx, by]) {
+  const dx = bx - ax;
+  const dy = by - ay;
+  const length = dx * dx + dy * dy;
+  const t =
+    length === 0
+      ? 0
+      : Math.max(0, Math.min(1, ((px - ax) * dx + (py - ay) * dy) / length));
+  return Math.hypot(px - ax - t * dx, py - ay - t * dy);
+}
+
+/** Signed distance to the rounded square; negative inside. */
+function squareDistance([x, y]) {
+  const qx = Math.abs(x - VIEW / 2) - (VIEW / 2 - RADIUS);
+  const qy = Math.abs(y - VIEW / 2) - (VIEW / 2 - RADIUS);
+  return (
+    Math.hypot(Math.max(qx, 0), Math.max(qy, 0)) +
+    Math.min(Math.max(qx, qy), 0) -
+    RADIUS
+  );
+}
+
+function chunk(type, data) {
+  const head = Buffer.alloc(8);
+  head.writeUInt32BE(data.length, 0);
+  head.write(type, 4, 'latin1');
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(Buffer.concat([head.subarray(4), data])) >>> 0, 0);
+  return Buffer.concat([head, data, crc]);
+}
+
+/** The PNG icon of `size` pixels, antialiased, with transparent corners. */
+export function monogramPng(letter, size, colours = CALM) {
+  const segments = strokes(letter).flatMap((stroke) =>
+    stroke.slice(1).map((point, i) => [stroke[i], point]),
+  );
+  const square = rgb(colours.light.background);
+  const mark = rgb(colours.light.letter);
+  const scale = size / VIEW;
+  const coverage = (distance) =>
+    Math.max(0, Math.min(1, 0.5 - distance * scale));
+  const rows = Buffer.alloc(size * (size * 4 + 1));
+  for (let y = 0; y < size; y++) {
+    const row = y * (size * 4 + 1);
+    rows[row] = 0; // filter: none
+    for (let x = 0; x < size; x++) {
+      const point = [(x + 0.5) / scale, (y + 0.5) / scale];
+      const alpha = coverage(squareDistance(point));
+      let near = Infinity;
+      for (const [a, b] of segments)
+        near = Math.min(near, segmentDistance(point, a, b));
+      const ink = coverage(near - STROKE / 2);
+      const offset = row + 1 + x * 4;
+      for (let c = 0; c < 3; c++)
+        rows[offset + c] = Math.round(square[c] * (1 - ink) + mark[c] * ink);
+      rows[offset + 3] = Math.round(alpha * 255);
+    }
+  }
+  const header = Buffer.alloc(13);
+  header.writeUInt32BE(size, 0);
+  header.writeUInt32BE(size, 4);
+  header.set([8, 6, 0, 0, 0], 8); // 8 bits, RGBA, no interlace
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk('IHDR', header),
+    chunk('IDAT', deflateSync(rows)),
+    chunk('IEND', Buffer.alloc(0)),
+  ]);
+}
+
+/**
+ * Writes an app's icons: public/favicon.svg and the manifest's icon-192.png
+ * and icon-512.png. Returns them as paths inside the app.
+ */
+export function writeAppIcons(appDir, title, colours = CALM) {
+  const letter = monogramLetter(title);
+  const pub = join(appDir, 'public');
+  mkdirSync(pub, { recursive: true });
+  writeFileSync(join(pub, 'favicon.svg'), monogramSvg(letter, colours));
+  for (const size of [192, 512])
+    writeFileSync(
+      join(pub, `icon-${size}.png`),
+      monogramPng(letter, size, colours),
+    );
+  return ['favicon.svg', 'icon-192.png', 'icon-512.png'].map(
+    (file) => `public/${file}`,
+  );
+}

package/scripts/lib/overview.mjs

@@ -62,11 +62,12 @@ function card(entry) {
   const icon = entry.icon
     ? `<img src="${escape(entry.icon)}" alt="" width="64" height="64" />`
     : `<span class="letter" aria-hidden="true">${escape(letter)}</span>`;
+  const lang = entry.language ? ` lang="${escape(entry.language)}"` : '';
   const description = entry.description
     ? `\n          <span class="description">${escape(entry.description)}</span>`
     : '';
   return `        <li>
-          <a href="${escape(entry.href)}" lang="${escape(entry.language)}">
+          <a href="${escape(entry.href)}"${lang}>
           ${icon}
           <span class="name">${escape(entry.title)}</span>${description}
           </a>
@@ -81,8 +82,9 @@ export function siteLanguage(entries) {
 }
 
 /**
- * The overview: one card per `{ id, title, language, href, icon?,
- * description? }`, in the given order.
+ * The overview: one card per `{ id, title, language?, href, icon?,
+ * description? }`, in the given order; an app without a language follows the
+ * browser.
  */
 export function renderOverview(entries) {
   const language = siteLanguage(entries);

package/scripts/lib/page.mjs

@@ -0,0 +1,89 @@
+// The page title comes from apps.json: the generated Vite plugin pageTitle
+// adds it to the head, so an app's index.html has no <title> of its own and its
+// vite.config.ts uses the plugin. check reports what stands in the way; the
+// migration moves apps that still have the skeleton's files.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { escapeHtml } from './html.mjs';
+import { ifPresent } from './json.mjs';
+import { SKELETON } from './paths.mjs';
+
+export const PAGE = 'index.html';
+export const VITE_CONFIG = 'vite.config.ts';
+
+// The skeleton's vite.config.ts from 0.7.0 until the plugin, which the
+// migration replaces with the current one.
+const VITE_CONFIG_0_7 = `import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+import { VitePWA } from 'vite-plugin-pwa';
+import { base, pwa, server } from './vite.sempods.generated.ts';
+
+// Base path, development port and PWA settings come from apps.json through the
+// generated file; add your own plugins and options here.
+export default defineConfig({
+  base,
+  server,
+  preview: server,
+  plugins: [react(), ...(pwa ? [VitePWA(pwa)] : [])],
+});
+`;
+
+// A <title> element in the head; an SVG <title> in the body is not one.
+const OWN_TITLE = /<title[\s>]/i;
+const head = (html) => html.split(/<body[\s>]/i)[0];
+const usesPlugin = (config) => /\bpageTitle\b/.test(config);
+
+/** Why the page would not get its title from apps.json; empty when it does. */
+export function pageProblems(appDir, id) {
+  const problems = [];
+  const html = ifPresent(() => readFileSync(join(appDir, PAGE), 'utf8'));
+  if (html !== undefined && OWN_TITLE.test(head(html)))
+    problems.push(
+      `apps/${id}/${PAGE} has its own <title>; remove it, the page title comes from apps.json`,
+    );
+  const config = ifPresent(() =>
+    readFileSync(join(appDir, VITE_CONFIG), 'utf8'),
+  );
+  if (config !== undefined && !usesPlugin(config))
+    problems.push(
+      `apps/${id}/${VITE_CONFIG} does not add pageTitle from vite.sempods.generated.ts to its plugins, so the page has no title`,
+    );
+  return problems;
+}
+
+/**
+ * Moves one app to the generated page title where that is unambiguous: a
+ * vite.config.ts unchanged from the skeleton gets the plugin, and a page
+ * whose only title is the app's title from apps.json loses it. Returns the
+ * changed files as apps/<id>/<file>; anything else is left to check.
+ */
+export function adoptPageTitle(appDir, app) {
+  const changed = [];
+  const configFile = join(appDir, VITE_CONFIG);
+  const config = ifPresent(() => readFileSync(configFile, 'utf8'));
+  if (config === VITE_CONFIG_0_7) {
+    writeFileSync(
+      configFile,
+      readFileSync(join(SKELETON, VITE_CONFIG), 'utf8'),
+    );
+    changed.push(VITE_CONFIG);
+  }
+  const pageFile = join(appDir, PAGE);
+  const html = ifPresent(() => readFileSync(pageFile, 'utf8'));
+  const line = new RegExp(
+    `^[ \\t]*<title>${escapeRegExp(escapeHtml(app.title))}</title>[ \\t]*\\r?\\n`,
+    'm',
+  );
+  if (
+    html !== undefined &&
+    (changed.length > 0 || usesPlugin(config ?? '')) &&
+    head(html).match(/<title[\s>]/gi)?.length === 1 &&
+    line.test(head(html))
+  ) {
+    writeFileSync(pageFile, html.replace(line, ''));
+    changed.push(PAGE);
+  }
+  return changed.map((file) => `apps/${app.id}/${file}`);
+}
+
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');