@homie-rocks/studio 0.19.1 → 0.20.0

package/lab/take.js

@@ -0,0 +1,189 @@
+/*
+ * A take: one short, repeatable piece of play the Game Lab shows in both builds (games/<id>/lab.json). The same file
+ * is read by the lab page (served as it is) and by `homie-studio lab` in Node.
+ *
+ *   {
+ *     "v": 1,
+ *     "default": "knock",
+ *     "takes": {
+ *       "knock": {
+ *         "note": "Walk right into Rook and bump him",
+ *         "seconds": 3,              // how long the take is
+ *         "seed": 7,                 // the world's dice (Math.random) in both builds
+ *         "device": "desk",          // desk (1280x800) or phone (390x844)
+ *         "fps": 60,                 // 60, 30, 15 or 12 frames a second
+ *         "stage": "dummy",          // a scene the game sets up for this mechanic (lab.stage; optional)
+ *         "view": "close",           // one of the game's lab.camera presets (optional)
+ *         "overlays": ["onion"],     // overlays on at the start (optional)
+ *         "track": "speed",          // the graph shown first (optional)
+ *         "storage": { "key": "value" },   // localStorage at the start (a saved hero, a setting)
+ *         "inputs": [
+ *           { "at": 0.1, "key": "ArrowRight", "hold": 0.6 },   // pressed at 0.1 s, held 0.6 s
+ *           { "at": 0.9, "key": "Space" },                    // a tap
+ *           { "at": 1.0, "down": "KeyW" }, { "at": 1.4, "up": "KeyW" },
+ *           { "at": 1.5, "pointer": "down", "x": 120, "y": 600, "id": 2, "pt": "touch" }
+ *         ]
+ *       }
+ *     }
+ *   }
+ *
+ * Times are seconds from the take's start; x and y are CSS pixels of the game's page at the take's device size.
+ */
+
+export const DEVICES = Object.freeze({
+  desk: { w: 1280, h: 800, dpr: 1, label: 'Desk' },
+  phone: { w: 390, h: 844, dpr: 2, label: 'Phone' },
+});
+export const FPS = Object.freeze([60, 30, 15, 12]);
+export const SCALES = Object.freeze([1, 0.5, 0.25, 0.1]);
+export const LIMITS = Object.freeze({ seconds: 60, inputs: 5000, takes: 24, name: 32 });
+export const TAKE_NAME = /^[a-z0-9][a-z0-9-]{0,31}$/;
+
+const num = (v, d) => (Number.isFinite(Number(v)) ? Number(v) : d);
+const r4 = (v) => Math.round(v * 10000) / 10000;
+
+/** What is wrong with a take, in words (empty: nothing). */
+export function checkTake(take, name = 'take') {
+  const out = [];
+  if (!take || typeof take !== 'object' || Array.isArray(take)) return [`${name} is not an object`];
+  const s = Number(take.seconds);
+  if (!(s > 0 && s <= LIMITS.seconds)) out.push(`${name}.seconds must be between 0 and ${LIMITS.seconds}`);
+  if (take.fps !== undefined && !FPS.includes(Number(take.fps))) out.push(`${name}.fps must be one of ${FPS.join(', ')}`);
+  if (take.device !== undefined && !Object.hasOwn(DEVICES, take.device)) out.push(`${name}.device must be desk or phone`);
+  if (take.seed !== undefined && !(Number.isInteger(Number(take.seed)) && Number(take.seed) >= 0)) out.push(`${name}.seed must be a whole number`);
+  if (take.stage !== undefined && !(typeof take.stage === 'string' && /^[a-z0-9][a-z0-9-]{0,31}$/.test(take.stage))) out.push(`${name}.stage is a short lowercase name`);
+  if (take.storage !== undefined && (typeof take.storage !== 'object' || Array.isArray(take.storage) || take.storage === null)) out.push(`${name}.storage must be an object of keys`);
+  const inputs = take.inputs ?? [];
+  if (!Array.isArray(inputs)) out.push(`${name}.inputs must be a list`);
+  else {
+    if (inputs.length > LIMITS.inputs) out.push(`${name} has ${inputs.length} inputs (at most ${LIMITS.inputs})`);
+    inputs.forEach((row, i) => {
+      const at = Number(row?.at);
+      if (!(at >= 0)) { out.push(`${name}.inputs[${i}].at must be seconds from the start`); return; }
+      const kinds = ['key', 'down', 'up', 'pointer'].filter((k) => row[k] !== undefined);
+      if (kinds.length !== 1) out.push(`${name}.inputs[${i}] needs exactly one of key, down, up or pointer`);
+      else if (kinds[0] === 'pointer') {
+        if (!['down', 'move', 'up', 'cancel'].includes(row.pointer)) out.push(`${name}.inputs[${i}].pointer is down, move, up or cancel`);
+        if (!Number.isFinite(Number(row.x)) || !Number.isFinite(Number(row.y))) out.push(`${name}.inputs[${i}] needs x and y`);
+      } else if (typeof row[kinds[0]] !== 'string' || !/^[A-Za-z0-9]{1,24}$/.test(row[kinds[0]])) out.push(`${name}.inputs[${i}].${kinds[0]} is a KeyboardEvent code such as ArrowRight, KeyW or Space`);
+    });
+  }
+  return out;
+}
+
+/** Every take of a lab file, checked: { takes, default, problems }. */
+export function readLabFile(json) {
+  const problems = [];
+  const takes = {};
+  if (!json || typeof json !== 'object') return { takes, default: null, problems: ['lab.json is not an object'] };
+  const all = json.takes && typeof json.takes === 'object' ? json.takes : {};
+  for (const [name, take] of Object.entries(all).slice(0, LIMITS.takes)) {
+    if (!TAKE_NAME.test(name)) { problems.push(`take "${name}": a name is lowercase letters, digits and hyphens`); continue; }
+    const p = checkTake(take, name);
+    if (p.length) problems.push(...p); else takes[name] = take;
+  }
+  const names = Object.keys(takes);
+  return { takes, default: names.includes(json.default) ? json.default : names[0] ?? null, problems };
+}
+
+/** How many frames a take has at its frame rate. */
+export function framesOf(take, fps = take?.fps ?? 60) { return Math.max(1, Math.round(num(take?.seconds, 3) * fps)); }
+
+/** A take as the harness plays it: inputs as events in ms, in order. */
+export function expandTake(take, { fps } = {}) {
+  const f = FPS.includes(Number(fps)) ? Number(fps) : FPS.includes(Number(take.fps)) ? Number(take.fps) : 60;
+  const events = [];
+  for (const row of take.inputs ?? []) {
+    const at = num(row.at, 0) * 1000;
+    if (row.key !== undefined) {
+      events.push({ at, type: 'key', code: row.key, down: true });
+      events.push({ at: at + Math.max(1000 / f, num(row.hold, 0.05) * 1000), type: 'key', code: row.key, down: false });
+    } else if (row.down !== undefined) events.push({ at, type: 'key', code: row.down, down: true });
+    else if (row.up !== undefined) events.push({ at, type: 'key', code: row.up, down: false });
+    else if (row.pointer !== undefined) events.push({ at, type: 'pointer', ev: row.pointer, x: num(row.x, 0), y: num(row.y, 0), id: Math.max(1, Math.round(num(row.id, 1))), pt: row.pt === 'mouse' || row.pt === 'pen' ? row.pt : 'touch' });
+  }
+  // Stable: two events at one time keep the file's order.
+  const order = events.map((e, i) => [e, i]).sort((a, b) => a[0].at - b[0].at || a[1] - b[1]).map(([e]) => e);
+  return {
+    fps: f,
+    frames: framesOf(take, f),
+    seed: Number.isInteger(Number(take.seed)) ? Number(take.seed) : 1,
+    device: Object.hasOwn(DEVICES, take.device) ? take.device : 'desk',
+    stage: typeof take.stage === 'string' ? take.stage : null,
+    view: typeof take.view === 'string' ? take.view : null,
+    overlays: Array.isArray(take.overlays) ? take.overlays.map(String) : [],
+    track: typeof take.track === 'string' ? take.track : null,
+    storage: take.storage && typeof take.storage === 'object' ? take.storage : null,
+    inputs: order,
+  };
+}
+
+/**
+ * What the harness recorded (events in ms) as a take's inputs (seconds): a key pressed and let go becomes one row
+ * with its hold; anything else stays an edge.
+ */
+export function inputsFromRecording(events) {
+  const rows = [];
+  const open = new Map();
+  for (const e of events) {
+    const at = r4(num(e.at, 0) / 1000);
+    if (e.type === 'key' && e.down) { const row = { at, down: e.code }; open.set(e.code, row); rows.push(row); }
+    else if (e.type === 'key') {
+      const d = open.get(e.code);
+      if (d) { open.delete(e.code); delete d.down; d.key = e.code; d.hold = r4(at - d.at); } else rows.push({ at, up: e.code });
+    } else if (e.type === 'pointer') rows.push({ at, pointer: e.ev, x: e.x, y: e.y, id: e.id, pt: e.pt });
+  }
+  return rows.map((r) => (r.key !== undefined ? { at: r.at, key: r.key, hold: r.hold } : r));
+}
+
+/** lab.json as text: readable, one input to a line. */
+export function formatLabFile(json) {
+  const out = ['{', `  "v": 1,`, `  "default": ${JSON.stringify(json.default ?? null)},`, '  "takes": {'];
+  const names = Object.keys(json.takes ?? {});
+  names.forEach((name, i) => {
+    const t = json.takes[name];
+    const keys = Object.keys(t).filter((k) => k !== 'inputs');
+    out.push(`    ${JSON.stringify(name)}: {`);
+    const lines = keys.map((k) => `      ${JSON.stringify(k)}: ${JSON.stringify(t[k])}`);
+    const inputs = Array.isArray(t.inputs) ? t.inputs : [];
+    lines.push(`      "inputs": [${inputs.length ? `\n${inputs.map((r) => `        ${JSON.stringify(r)}`).join(',\n')}\n      ` : ''}]`);
+    out.push(lines.join(',\n'));
+    out.push(`    }${i < names.length - 1 ? ',' : ''}`);
+  });
+  out.push('  }', '}');
+  return `${out.join('\n')}\n`;
+}
+
+/** tunables.json as text: one tunable to a line, so a kept change is a one-line diff. */
+export function formatTunables(spec) {
+  const names = Object.keys(spec ?? {});
+  if (!names.length) return '{}\n';
+  const one = (s) => (s && typeof s === 'object' && !Array.isArray(s) ? `{ ${Object.entries(s).map(([k, v]) => `${JSON.stringify(k)}: ${JSON.stringify(v)}`).join(', ')} }` : JSON.stringify(s));
+  return `{\n${names.map((k, i) => `  ${JSON.stringify(k)}: ${one(spec[k])}${i < names.length - 1 ? ',' : ''}`).join('\n')}\n}\n`;
+}
+
+/** A tunable's value (a bare number, or { value }). */
+export function tunableValue(s) { return typeof s === 'number' ? s : num(s?.value, NaN); }
+
+/** tunables.json with new values (by name): what is unknown or not a number is refused, ranges are kept. */
+export function setTunables(spec, values) {
+  const next = JSON.parse(JSON.stringify(spec ?? {}));
+  const changed = [];
+  const refused = [];
+  for (const [k, raw] of Object.entries(values ?? {})) {
+    const v = Number(raw);
+    if (!Object.hasOwn(next, k)) { refused.push(`${k}: not in tunables.json`); continue; }
+    if (!Number.isFinite(v)) { refused.push(`${k}: ${JSON.stringify(raw)} is not a number`); continue; }
+    const s = next[k];
+    const before = tunableValue(s);
+    if (typeof s === 'number') next[k] = v;
+    else {
+      s.value = v;
+      // A value past the slider's end moves the end: the file says what was kept, and the slider still reaches it.
+      if (Number.isFinite(s.min) && v < s.min) s.min = v;
+      if (Number.isFinite(s.max) && v > s.max) s.max = v;
+    }
+    if (before !== v) changed.push({ name: k, from: before, to: v });
+  }
+  return { spec: next, changed, refused };
+}

package/lib/build.mjs

@@ -46,7 +46,7 @@ import { vocabularyOf } from '../worker/brain.mjs';
 
 const SOURCE_SKIP = new Set(['node_modules', 'dist', '.git', '.wrangler', '.port']);
 /** Never copied into a static game's served folder. */
-const STATIC_SKIP = new Set(['node_modules', '.git', '.wrangler', '.port', '.DS_Store', 'game.json', 'PORT.md', 'CODEX.md']);
+const STATIC_SKIP = new Set(['node_modules', '.git', '.wrangler', '.port', '.DS_Store', 'game.json', 'PORT.md', 'CODEX.md', 'lab.json']);
 const LOADERS = { '.png': 'file', '.jpg': 'file', '.jpeg': 'file', '.gif': 'file', '.webp': 'file', '.mp3': 'file', '.ogg': 'file', '.wav': 'file', '.m4a': 'file', '.glb': 'file', '.gltf': 'file', '.bin': 'file', '.hdr': 'file', '.svg': 'file', '.json': 'json', '.woff2': 'file', '.ttf': 'file' };
 
 /** The port toolkit as one classic script (window.HomiePort), for static games. Built once per build. */
@@ -222,10 +222,66 @@ function keepMap(root, id, out, metafile) {
   writeFileSync(join(dir, 'main.js.sha256'), `${createHash('sha256').update(readFileSync(join(out, 'assets', 'main.js'))).digest('hex')}\n`);
 }
 
-export async function build(root, { only = null, log = () => {}, deploy = process.env.WORKERS_CI === '1', maps = false } = {}) {
+/** esbuild, as the studio has it installed (the version its package.json pins). */
+export async function studioEsbuild(root) {
   const require = createRequire(join(root, 'package.json'));
-  let esbuild;
-  try { esbuild = require('esbuild'); } catch { esbuild = await import('esbuild'); }
+  try { return require('esbuild'); } catch { return import('esbuild'); }
+}
+
+/**
+ * One game's own files into `out` (emptied first): its bundle, static copy or own build's output, its index.html and
+ * its public/ folder. What `build` serves at /games/<id>/, and what the Game Lab (lib/lab.mjs) builds New and Today
+ * with. `sourcemap` is esbuild's (the lab keeps a linked map beside its builds); `maps` keeps the site build's map in
+ * .studio/maps/<id>/. Returns { mode, warnings, metafile } (metafile: the bundle's inputs, null for other modes).
+ */
+export async function buildGameFiles(esbuild, root, g, out, { maps = false, sourcemap = null, cache = {}, log = () => {} } = {}) {
+  rmSync(out, { recursive: true, force: true });
+  mkdirSync(join(out, 'assets'), { recursive: true });
+  const mode = g.build?.mode ?? 'bundle';
+  let warnings = 0;
+  let metafile = null;
+  const bundle = async (entryRel) => {
+    const entry = join(g.dir, entryRel);
+    if (!existsSync(entry)) throw new Error(`games/${g.id}: entry ${entryRel} not found`);
+    const result = await esbuild.build({
+      entryPoints: [entry], bundle: true, format: 'esm', target: 'es2022', minify: true, sourcemap: sourcemap ?? (maps ? 'external' : false),
+      outfile: join(out, 'assets', 'main.js'), absWorkingDir: root, logLevel: 'silent', metafile: true,
+      loader: LOADERS, assetNames: '[name]-[hash]',
+    }).catch((error) => {
+      const first = error.errors?.[0];
+      throw new Error(`games/${g.id} did not build: ${first ? `${first.text}${first.location ? ` (${first.location.file}:${first.location.line})` : ''}` : error.message}`);
+    });
+    warnings += result.warnings.length;
+    metafile = result.metafile;
+    if (maps) keepMap(root, g.id, out, result.metafile);
+  };
+  if (mode === 'static') {
+    copyStatic(g.dir, out);
+    writeFileSync(join(out, 'homie-port.js'), await portScript(esbuild, root, cache));
+    if (g.entry) await bundle(g.entry);
+    const html = readFileSync(join(out, 'index.html'), 'utf8');
+    if (!/homie-port\.js/.test(html)) log(`warning: games/${g.id}/index.html does not load ./homie-port.js (the port toolkit); add <script src="./homie-port.js"></script> first in <head>`);
+  } else if (mode === 'command') {
+    const command = String(g.build.command ?? 'npm run build');
+    const res = spawnSync(command, { cwd: g.dir, shell: true, encoding: 'utf8', timeout: 10 * 60_000, maxBuffer: 64 * 1024 * 1024 });
+    if (res.status !== 0) throw new Error(`games/${g.id}: \`${command}\` failed: ${`${res.stdout ?? ''}${res.stderr ?? ''}`.trim().split('\n').slice(-6).join(' ')}`);
+    const built = join(g.dir, String(g.build.out ?? 'dist'));
+    if (!existsSync(join(built, 'index.html'))) throw new Error(`games/${g.id}: \`${command}\` left no index.html in ${relative(g.dir, built) || '.'}`);
+    cpSync(built, out, { recursive: true });
+    writeFileSync(join(out, 'homie-port.js'), await portScript(esbuild, root, cache));
+  } else {
+    await bundle(g.entry ?? 'src/main.ts');
+    const html = join(g.dir, 'index.html');
+    if (!existsSync(html)) throw new Error(`games/${g.id}/index.html is missing`);
+    writeFileSync(join(out, 'index.html'), readFileSync(html, 'utf8'));
+  }
+  if (mode !== 'static' && existsSync(join(g.dir, 'public'))) cpSync(join(g.dir, 'public'), out, { recursive: true });
+  if (!existsSync(join(out, 'index.html'))) throw new Error(`games/${g.id}/index.html is missing`);
+  return { mode, warnings, metafile };
+}
+
+export async function build(root, { only = null, log = () => {}, deploy = process.env.WORKERS_CI === '1', maps = false } = {}) {
+  const esbuild = await studioEsbuild(root);
   const studio = readStudio(root);
   const dist = join(root, 'site', 'dist');
   const games = listGames(root).filter((g) => !only || g.id === only);
@@ -236,47 +292,8 @@ export async function build(root, { only = null, log = () => {}, deploy = proces
   const cache = {};
   for (const g of games) {
     const out = join(dist, 'games', g.id);
-    rmSync(out, { recursive: true, force: true });
-    mkdirSync(join(out, 'assets'), { recursive: true });
-    const mode = g.build?.mode ?? 'bundle';
     const started = Date.now();
-    let warnings = 0;
-    const bundle = async (entryRel) => {
-      const entry = join(g.dir, entryRel);
-      if (!existsSync(entry)) throw new Error(`games/${g.id}: entry ${entryRel} not found`);
-      const result = await esbuild.build({
-        entryPoints: [entry], bundle: true, format: 'esm', target: 'es2022', minify: true, sourcemap: maps ? 'external' : false,
-        outfile: join(out, 'assets', 'main.js'), absWorkingDir: root, logLevel: 'silent', metafile: true,
-        loader: LOADERS, assetNames: '[name]-[hash]',
-      }).catch((error) => {
-        const first = error.errors?.[0];
-        throw new Error(`games/${g.id} did not build: ${first ? `${first.text}${first.location ? ` (${first.location.file}:${first.location.line})` : ''}` : error.message}`);
-      });
-      warnings += result.warnings.length;
-      if (maps) keepMap(root, g.id, out, result.metafile);
-    };
-    if (mode === 'static') {
-      copyStatic(g.dir, out);
-      writeFileSync(join(out, 'homie-port.js'), await portScript(esbuild, root, cache));
-      if (g.entry) await bundle(g.entry);
-      const html = readFileSync(join(out, 'index.html'), 'utf8');
-      if (!/homie-port\.js/.test(html)) log(`warning: games/${g.id}/index.html does not load ./homie-port.js (the port toolkit); add <script src="./homie-port.js"></script> first in <head>`);
-    } else if (mode === 'command') {
-      const command = String(g.build.command ?? 'npm run build');
-      const res = spawnSync(command, { cwd: g.dir, shell: true, encoding: 'utf8', timeout: 10 * 60_000, maxBuffer: 64 * 1024 * 1024 });
-      if (res.status !== 0) throw new Error(`games/${g.id}: \`${command}\` failed: ${`${res.stdout ?? ''}${res.stderr ?? ''}`.trim().split('\n').slice(-6).join(' ')}`);
-      const built = join(g.dir, String(g.build.out ?? 'dist'));
-      if (!existsSync(join(built, 'index.html'))) throw new Error(`games/${g.id}: \`${command}\` left no index.html in ${relative(g.dir, built) || '.'}`);
-      cpSync(built, out, { recursive: true });
-      writeFileSync(join(out, 'homie-port.js'), await portScript(esbuild, root, cache));
-    } else {
-      await bundle(g.entry ?? 'src/main.ts');
-      const html = join(g.dir, 'index.html');
-      if (!existsSync(html)) throw new Error(`games/${g.id}/index.html is missing`);
-      writeFileSync(join(out, 'index.html'), readFileSync(html, 'utf8'));
-    }
-    if (mode !== 'static' && existsSync(join(g.dir, 'public'))) cpSync(join(g.dir, 'public'), out, { recursive: true });
-    if (!existsSync(join(out, 'index.html'))) throw new Error(`games/${g.id}/index.html is missing`);
+    const { mode, warnings } = await buildGameFiles(esbuild, root, g, out, { maps, cache, log });
     // The guides' vocabulary (NETPLAY.md section 18): checked here, so a room never meets a line it cannot say.
     vocabFor(g, out);
     // The game's own source, for other studios to remix (game.json "share": { "source": false } keeps it private).

package/lib/changelog.mjs

@@ -0,0 +1,204 @@
+/**
+ * CHANGELOG.md: what changed in each @homie-rocks/studio version, and the Homie plugin's version beside it.
+ *
+ * The repository keeps it at its root; the package carries an identical copy (packages/studio/CHANGELOG.md, in
+ * `files`, kept the same by `node scripts/changelog.mjs --sync`), so an installed toolkit knows its own history with
+ * no network. Read by:
+ *   - `homie-studio upgrade`: "What's new since <the pinned version>", from the NEW version's own copy (the one
+ *     `npx -y @homie-rocks/studio@<new> upgrade` runs);
+ *   - the studio card (lib/mcp-tools.mjs), when a studio pins an older toolkit than the one answering;
+ *   - scripts/changelog.mjs: CI's check, and the GitHub release notes the publish workflow writes.
+ *
+ * The shape (Keep a Changelog, https://keepachangelog.com/en/1.1.0/), newest first:
+ *
+ *   ## [0.19.2] - 2026-10-02                              one section per studio version
+ *
+ *   **Plugin 0.20.2** · [#29](…) · [release-…](…)          the meta line: the plugin's version (", then 0.20.3" when
+ *                                                          the plugin had a release of its own after it), the pull
+ *                                                          requests and the tag
+ *   One sentence: what this version is.                    the summary "What's new" prints
+ *
+ *   ### Added | ### Changed | ### Fixed | ### Upgrade notes   bullets ("- " and lines indented under them)
+ *
+ *   [0.19.2]: https://…                                    link definitions, at the end of the file
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+export const CHANGELOG_FILE = fileURLToPath(new URL('../CHANGELOG.md', import.meta.url));
+export const GROUPS = Object.freeze(['Added', 'Changed', 'Fixed', 'Upgrade notes']);
+export const REPO_URL = 'https://github.com/homie-rocks/homie';
+
+const VERSION = /^\d+\.\d+\.\d+$/;
+const HEADING = /^## \[?(\d+\.\d+\.\d+)\]?(?:\s+-\s+(\d{4}-\d{2}-\d{2}))?\s*$/;
+const LINK_DEF = /^\[[^\]]+\]:\s+\S+/;
+
+/** -1, 0 or 1, as a sorts before, with or after b (x.y.z only; anything else sorts first). */
+export function compareVersions(a, b) {
+  const x = VERSION.test(String(a)) ? String(a).split('.').map(Number) : [-1, -1, -1];
+  const y = VERSION.test(String(b)) ? String(b).split('.').map(Number) : [-1, -1, -1];
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] < y[i] ? -1 : 1;
+  return 0;
+}
+
+/** Markdown as one line of plain words: links keep their text, code and bold lose their marks. */
+export function plain(markdown) {
+  return String(markdown ?? '')
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+    .replace(/\*\*([^*]+)\*\*/g, '$1')
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/** The paragraphs and bullets of a run of lines: paragraphs split on blank lines, a bullet takes the lines indented under it. */
+function blocks(lines) {
+  const out = [];
+  let cur = null;
+  for (const line of lines) {
+    if (!line.trim()) { cur = null; continue; }
+    if (/^- /.test(line)) { cur = { kind: 'bullet', text: line.slice(2).trim() }; out.push(cur); continue; }
+    if (cur && (cur.kind === 'paragraph' || /^\s+\S/.test(line))) { cur.text += ` ${line.trim()}`; continue; }
+    cur = { kind: 'paragraph', text: line.trim() }; out.push(cur);
+  }
+  return out;
+}
+
+/**
+ * The file as its sections. Each: { version, date, plugin, plugins, meta, summary, notes, groups, body, line }.
+ * `body` is the section's own Markdown (no heading, no link definitions), what a release's notes are made of.
+ * `problems` lists what does not follow the shape (CI fails on them); a heading that is not a version (an
+ * "Unreleased" one, say) ends the section before it and is otherwise left alone.
+ */
+export function parseChangelog(text) {
+  const lines = String(text ?? '').replace(/\r\n?/g, '\n').split('\n');
+  const versions = [];
+  const problems = [];
+  let cur = null;
+  const close = () => {
+    if (!cur) return;
+    while (cur.lines.length && !cur.lines[cur.lines.length - 1].trim()) cur.lines.pop();
+    const { lines: own, ...section } = cur;
+    section.body = own.join('\n').replace(/^\n+/, '');
+    // Before the first ### heading: the meta line, the summary and any notes; then the groups.
+    const groups = {};
+    let head = [];
+    let group = null;
+    for (const line of own) {
+      const g = /^### (.+?)\s*$/.exec(line);
+      if (g) { group = g[1]; groups[group] = []; continue; }
+      if (group === null) head.push(line); else groups[group].push(line);
+    }
+    const paras = blocks(head).map((b) => b.text);
+    const metaAt = paras.findIndex((p) => /^\*\*Plugin /.test(p));
+    section.meta = metaAt >= 0 ? paras[metaAt] : null;
+    const rest = paras.filter((_, i) => i !== metaAt);
+    section.summary = rest[0] ?? null;
+    section.notes = rest.slice(1);
+    section.plugins = section.meta ? [...(/^\*\*Plugin ([^*]+)\*\*/.exec(section.meta)?.[1] ?? '').matchAll(/\d+\.\d+\.\d+/g)].map((m) => m[0]) : [];
+    section.plugin = section.plugins.at(-1) ?? null;
+    section.groups = Object.fromEntries(Object.entries(groups).map(([k, v]) => [k, blocks(v).filter((b) => b.kind === 'bullet').map((b) => b.text)]));
+    const where = `CHANGELOG.md line ${section.line} (## [${section.version}])`;
+    if (!section.date) problems.push(`${where}: the heading has no date; write it as "## [${section.version}] - YYYY-MM-DD"`);
+    if (!section.meta) problems.push(`${where}: no "**Plugin x.y.z** · …" line under the heading`);
+    else if (!section.plugin) problems.push(`${where}: the Plugin line names no version`);
+    if (!section.summary) problems.push(`${where}: no one-sentence summary under the Plugin line`);
+    for (const k of Object.keys(section.groups)) if (!GROUPS.includes(k)) problems.push(`${where}: "### ${k}" is not one of ${GROUPS.map((g) => `"### ${g}"`).join(', ')}`);
+    if (!Object.values(section.groups).some((b) => b.length)) problems.push(`${where}: no "- " entries under ${GROUPS.map((g) => `"### ${g}"`).join(', ')}`);
+    versions.push(section);
+    cur = null;
+  };
+  lines.forEach((line, i) => {
+    if (/^## /.test(line)) {
+      close();
+      const m = HEADING.exec(line);
+      if (m) cur = { version: m[1], date: m[2] ?? null, heading: line, line: i + 1, lines: [] };
+      return;
+    }
+    if (cur && LINK_DEF.test(line)) { close(); return; }
+    if (cur) cur.lines.push(line);
+  });
+  close();
+  for (let i = 1; i < versions.length; i++) {
+    if (compareVersions(versions[i - 1].version, versions[i].version) <= 0) problems.push(`CHANGELOG.md line ${versions[i].line}: ${versions[i].version} comes after ${versions[i - 1].version}; newest first, each version once`);
+  }
+  return { versions, problems };
+}
+
+/** The package's own CHANGELOG.md, parsed; null when it is missing (a checkout from before 0.19.2) or unreadable. */
+export function readChangelog(file = CHANGELOG_FILE) {
+  try { return { file, ...parseChangelog(readFileSync(file, 'utf8')) }; } catch { return null; }
+}
+
+/** One version's section, or null. */
+export function sectionOf(changelog, version) {
+  return changelog?.versions?.find((s) => s.version === version) ?? null;
+}
+
+/**
+ * What changed after `from` up to and including `to`, newest first: each version's summary and its upgrade notes
+ * (what the person may have to do). null when there is nothing to say (no pin known, no changelog, or not older).
+ */
+export function whatsNew(from, to, { changelog = readChangelog() } = {}) {
+  if (!VERSION.test(String(from ?? '')) || !VERSION.test(String(to ?? '')) || compareVersions(from, to) >= 0 || !changelog) return null;
+  const versions = changelog.versions
+    .filter((s) => compareVersions(s.version, from) > 0 && compareVersions(s.version, to) <= 0)
+    .map((s) => ({ version: s.version, date: s.date, plugin: s.plugin, summary: plain(s.summary), upgrade: (s.groups['Upgrade notes'] ?? []).map(plain) }));
+  return versions.length ? { from, to, versions } : null;
+}
+
+/**
+ * whatsNew as a few lines for a terminal or a card's text: one line per version (the newest `maxVersions`), then the
+ * upgrade notes of every version in the range (the first `maxNotes`), each cut to `width`.
+ */
+export function whatsNewLines(news, { width = 110, maxVersions = 8, maxNotes = 8, source = null } = {}) {
+  if (!news?.versions?.length) return [];
+  const cut = (s, n) => (s.length > n ? `${s.slice(0, n - 1).replace(/\s+\S*$/, '')}…` : s);
+  const shown = news.versions.slice(0, maxVersions);
+  const pad = Math.max(...news.versions.map((v) => v.version.length));
+  const lines = [`What's new since ${news.from}${source ? ` (${source})` : ''}:`];
+  for (const v of shown) lines.push(`  ${v.version.padEnd(pad)}  ${cut(v.summary ?? '', width - pad - 4)}`);
+  const more = news.versions.length - shown.length;
+  if (more) lines.push(`  … and ${more} earlier version${more === 1 ? '' : 's'} (CHANGELOG.md has every one)`);
+  const notes = news.versions.flatMap((v) => v.upgrade.map((u) => [v.version, u]));
+  if (notes.length) {
+    lines.push('Upgrade notes (anything to do yourself):');
+    for (const [v, u] of notes.slice(0, maxNotes)) lines.push(`  ${v.padEnd(pad)}  ${cut(u, width - pad - 4)}`);
+    if (notes.length > maxNotes) lines.push(`  … and ${notes.length - maxNotes} more (--json has every one)`);
+  }
+  return lines;
+}
+
+/**
+ * Markdown with each paragraph and each "- " entry on one line. CHANGELOG.md wraps them at 120 columns, which a
+ * file ignores; GitHub's release notes render every line end as a break, so a wrapped entry would break mid-sentence.
+ */
+export function unwrap(markdown) {
+  const out = [];
+  for (const line of String(markdown ?? '').split('\n')) {
+    const prev = out.length ? out[out.length - 1] : '';
+    const starts = !line.trim() || /^(#{1,6} |- |\* |\d+\. |---\s*$|\|)/.test(line.trim()) && !/^\s+/.test(line);
+    const continues = prev.trim() && !/^(#{1,6} |---\s*$|\|)/.test(prev.trim());
+    if (!starts && continues) out[out.length - 1] = `${prev.replace(/\s+$/, '')} ${line.trim()}`;
+    else out.push(line);
+  }
+  return out.join('\n');
+}
+
+/**
+ * A GitHub release's notes: the version's section as it is in CHANGELOG.md (each paragraph and entry on one line),
+ * then the Desktop extension's line (its .mcpb is attached to the release) and where every version is.
+ */
+export function releaseNotes(changelog, version, { tag = null, repo = REPO_URL } = {}) {
+  const s = sectionOf(changelog, version);
+  if (!s) return null;
+  return [
+    unwrap(s.body),
+    '',
+    '---',
+    '',
+    `Homie for Claude Desktop ${version}: [desktop/README.md](${repo}/blob/${tag ?? 'main'}/desktop/README.md) says how to install it (\`homie-studio-${version}.mcpb\` below).`,
+    `Every version: [CHANGELOG.md](${repo}/blob/main/CHANGELOG.md).`,
+    '',
+  ].join('\n');
+}

package/lib/jobs.mjs

@@ -159,10 +159,11 @@ export function jobView(job, { lines = 12 } = {}) {
 }
 
 /** Run the studio's pinned CLI as a job: `homie-studio <args> --json`. */
-export function cliJob(root, label, args, opts = {}) {
+export function cliJob(root, label, args, { cli = null, ...opts } = {}) {
   const node = findNode();
   if (!node) throw new Error('no Node.js 22 or newer on this computer: install it from https://nodejs.org/en/download (the LTS), then ask again');
-  return startJob({ root, label, cmd: node.bin, args: [cliOf(root), ...args, '--json'], json: true, ...opts });
+  // `cli`: another homie-studio than the studio's pinned one (this package's, for an upgrade to it).
+  return startJob({ root, label, cmd: node.bin, args: [cli ?? cliOf(root), ...args, '--json'], json: true, ...opts });
 }
 
 /** `npm install` in a studio (its pinned toolkit and Wrangler). */