From 0529a26618ec23db628e997370c075c495795799 Mon Sep 17 00:00:00 2001
From: Jeremy Smith <145979804+JeremySNR@users.noreply.github.com>
Date: Wed, 23 Sep 2026 07:33:59 +0100
Subject: [PATCH 1/3] Require release notes for every change and show them in
 the app
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- CI fails a pull request that changes the app without CHANGELOG
  [Unreleased] notes, unless labelled "no release notes".
- The release workflow refuses to build a version with no notes, before
  spending build time, instead of publishing empty notes.
- Settings → Updates shows an available update's notes before download and
  this version's notes on demand; "What's new" opens once after updating.
  Validation sections stay on GitHub only.
- Contributing guide and PR template explain how to write notes for users.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .github/PULL_REQUEST_TEMPLATE.md              |  8 ++
 .github/workflows/ci.yml                      | 15 +++
 .github/workflows/release.yml                 |  6 +-
 CHANGELOG.md                                  |  1 +
 CONTRIBUTING.md                               | 23 +++++
 scripts/changelog-section.mjs                 | 22 +++--
 scripts/check-release-notes.mjs               | 54 +++++++++++
 src/main/index.ts                             |  6 ++
 src/main/updates.ts                           |  2 +
 src/renderer/src/App.tsx                      |  2 +
 src/renderer/src/components/SettingsModal.tsx | 18 ++++
 src/renderer/src/components/WhatsNew.tsx      | 93 +++++++++++++++++++
 src/shared/releaseNotes.ts                    | 41 ++++++++
 src/shared/types.ts                           |  2 +
 tests/releaseNotes.test.ts                    | 50 ++++++++++
 tests/updates.test.ts                         |  7 ++
 16 files changed, 340 insertions(+), 10 deletions(-)
 create mode 100644 scripts/check-release-notes.mjs
 create mode 100644 src/renderer/src/components/WhatsNew.tsx
 create mode 100644 src/shared/releaseNotes.ts
 create mode 100644 tests/releaseNotes.test.ts

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 6bed8ef..f61f65f 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -6,6 +6,14 @@
 
 <!-- What problem this solves. -->
 
+## Release notes
+
+<!--
+What people using Cutawan will notice, in their words. Add the same lines under
+"## [Unreleased]" in CHANGELOG.md (### Added / Improved / Fixed); CI checks it.
+Nothing visible? Write "None" and add the "no release notes" label.
+-->
+
 ## How did you test it?
 
 <!--
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 0e2b3ee..7aac2bf 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -4,8 +4,23 @@ on:
   push:
     branches: [main]
   pull_request:
+    # labeled/unlabeled so adding "no release notes" re-runs the check.
+    types: [opened, synchronize, reopened, labeled, unlabeled]
 
 jobs:
+  release-notes:
+    name: release notes
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Require CHANGELOG notes for app changes
+        env:
+          BASE_REF: origin/${{ github.base_ref }}
+          PR_LABELS: ${{ toJSON(github.event.pull_request.labels.*.name) }}
+        run: node scripts/check-release-notes.mjs
   mac-package:
     name: packaged Apple Silicon inference and export
     runs-on: macos-latest
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 6857a6f..debe9a9 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -49,6 +49,10 @@ jobs:
         with:
           node-version: 22
           cache: npm
+      # Every release says what changed; fail before spending build time.
+      - name: Check release notes
+        shell: bash
+        run: node scripts/changelog-section.mjs "$(node -p "require('./package.json').version")" --require > /dev/null
       - run: npm ci
       - name: Validate packaged Mac before publishing
         if: runner.os == 'macOS'
@@ -100,7 +104,7 @@ jobs:
           set -euo pipefail
           node scripts/verify-release.mjs release
           version=$(node -p "require('./package.json').version")
-          node scripts/changelog-section.mjs "$version" > notes.md
+          node scripts/changelog-section.mjs "$version" --require > notes.md
           if gh release view "v$version" --json isDraft > release-state.json; then
             node -e 'if (!require("./release-state.json").isDraft) throw new Error("This version is already published; bump the version before releasing.")'
           else
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4448ace..f53b30e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,7 @@ still pre-1.0, minor bumps carry new features and patch bumps carry fixes.
 - Cut words straight from the transcript: drag across them and press Delete or "Cut selection". Cut words are struck through.
 - Undo and redo for clip edits (⌘Z / ⇧⌘Z), and Premiere-style keys: Space or K play/pause, J/L step a second, arrow keys step a frame, I/O set in and out.
 - The trim bar shows how long the clip plays after pauses and cuts.
+- "What's new" after each update, and any time from Settings → Updates. When an update is available, its notes show there before you download it.
 
 ### Improved
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5bbd047..3eeae75 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -38,6 +38,29 @@ npm run typecheck # both tsconfigs, node and web
 npm run lint      # eslint
 ```
 
+### Release notes
+
+Every change people will notice needs a line in `CHANGELOG.md` under
+`## [Unreleased]`, grouped as `### Added`, `### Improved` or `### Fixed`. CI
+fails a pull request that changes `src/`, `resources/` or `package.json`
+without one. For internal-only changes (tests, CI, docs, refactors with no
+visible effect), add the `no release notes` label instead.
+
+These lines are what people read: the release workflow publishes a version's
+section as its GitHub release notes, the app shows the same text in Settings →
+Updates before someone updates, and again as "What's new" after they do. So
+write them for someone using Cutawan, not for a code reviewer:
+
+- Say what changed for them: "Clips appear as soon as they're scored" rather
+  than "Move eager reframe out of analyzeProject".
+- One change per bullet, plain words, no file or function names.
+- Measurements, failed trials and limits go in a `### Validation` section (or
+  a doc linked from it). It appears on GitHub but not in the app.
+
+To release, rename `## [Unreleased]` to `## [x.y.z] - YYYY-MM-DD` in the same
+commit as the version bump. The release workflow refuses to build a version
+with no notes.
+
 ## How the code is laid out
 
 `README.md` has the full tree. The short version:
diff --git a/scripts/changelog-section.mjs b/scripts/changelog-section.mjs
index 4ecb0e0..ff4c90c 100644
--- a/scripts/changelog-section.mjs
+++ b/scripts/changelog-section.mjs
@@ -3,17 +3,19 @@
  * release notes.
  *
  * Plain Node ESM rather than a tsx script like the rest of `scripts/`, so the
- * release workflow can run it without an `npm ci` just to get tsx.
+ * release workflow can run it without an `npm ci` just to get tsx. Mirrors
+ * `changelogSection` in src/shared/releaseNotes.ts.
  *
- * Usage: node scripts/changelog-section.mjs 0.7.0
- * Exits 0 with empty output if there is no section for that version, so a
- * release with no changelog entry still publishes rather than failing.
+ * Usage: node scripts/changelog-section.mjs 0.7.0 [--require]
+ * With --require (the release workflow), a missing or empty section fails:
+ * every release must say what changed. Without it, prints nothing.
  */
 import { readFile } from 'node:fs/promises'
 
 const version = process.argv[2]
-if (!version) {
-  console.error('usage: node scripts/changelog-section.mjs <version>')
+const required = process.argv.includes('--require')
+if (!version || version.startsWith('--')) {
+  console.error('usage: node scripts/changelog-section.mjs <version> [--require]')
   process.exit(2)
 }
 
@@ -26,10 +28,12 @@ const isHeading = (line) => /^##\s+/.test(line)
 const headingVersion = (line) => line.match(/^##\s+\[?([0-9]+\.[0-9]+\.[0-9]+)\]?/)?.[1]
 
 const start = lines.findIndex((l) => headingVersion(l) === version)
-if (start === -1) process.exit(0)
-
-const rest = lines.slice(start + 1)
+const rest = start === -1 ? [] : lines.slice(start + 1)
 const end = rest.findIndex(isHeading)
 const body = (end === -1 ? rest : rest.slice(0, end)).join('\n').trim()
 
+if (!body && required) {
+  console.error(`CHANGELOG.md has no notes for ${version}. Rename "## [Unreleased]" to "## [${version}] - <date>" before releasing.`)
+  process.exit(1)
+}
 process.stdout.write(body)
diff --git a/scripts/check-release-notes.mjs b/scripts/check-release-notes.mjs
new file mode 100644
index 0000000..9ca08b2
--- /dev/null
+++ b/scripts/check-release-notes.mjs
@@ -0,0 +1,54 @@
+/**
+ * Pull-request gate: a change people will notice needs release notes.
+ *
+ * If the diff against the base branch touches the app (src/, resources/ or
+ * package.json) it must also add notes under `## [Unreleased]` in
+ * CHANGELOG.md; the release workflow later publishes that section, and the
+ * app shows it as "What's new". Internal-only changes (tests, CI, docs,
+ * refactors with no visible effect) can carry the `no release notes` label.
+ *
+ * Usage: BASE_REF=origin/main PR_LABELS='["..."]' node scripts/check-release-notes.mjs
+ */
+import { execFileSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+
+const base = process.env.BASE_REF || 'origin/main'
+const labels = JSON.parse(process.env.PR_LABELS || '[]').map((l) => String(l).toLowerCase())
+if (labels.includes('no release notes')) {
+  console.log('Skipped: labelled "no release notes".')
+  process.exit(0)
+}
+
+const git = (...args) => execFileSync('git', args, { encoding: 'utf8' })
+const changed = git('diff', '--name-only', `${base}...HEAD`).split('\n').filter(Boolean)
+const userFacing = changed.filter((f) => /^(src|resources)\//.test(f) || f === 'package.json')
+if (!userFacing.length) {
+  console.log('No app changes; release notes not required.')
+  process.exit(0)
+}
+
+const unreleased = (text) => {
+  const lines = text.split(/\r?\n/)
+  const start = lines.findIndex((l) => /^##\s+\[?unreleased\]?/i.test(l))
+  if (start === -1) return ''
+  const rest = lines.slice(start + 1)
+  const end = rest.findIndex((l) => /^##\s+/.test(l))
+  return (end === -1 ? rest : rest.slice(0, end)).filter((l) => /^\s*[-*]\s+\S/.test(l)).join('\n')
+}
+let before = ''
+try { before = unreleased(git('show', `${base}:CHANGELOG.md`)) } catch { /* new file */ }
+const after = unreleased(readFileSync('CHANGELOG.md', 'utf8'))
+
+if (!after || after === before) {
+  console.error([
+    'This pull request changes the app but adds no release notes.',
+    '',
+    'Add a line under "## [Unreleased]" in CHANGELOG.md (### Added, ### Improved or',
+    '### Fixed) saying what changed for people using Cutawan. If nothing visible',
+    'changed, add the "no release notes" label.',
+    '',
+    `App files changed: ${userFacing.slice(0, 8).join(', ')}${userFacing.length > 8 ? ', …' : ''}`
+  ].join('\n'))
+  process.exit(1)
+}
+console.log('Release notes present under [Unreleased].')
diff --git a/src/main/index.ts b/src/main/index.ts
index 935e69b..8485dc1 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -92,6 +92,12 @@ async function runSmokeCapture(win: BrowserWindow, dir: string): Promise<void> {
     app.quit()
     return
   }
+  // Seeded profiles have projects and no record of seen notes, so the
+  // after-update "What's new" dialog opens; capture and dismiss it.
+  if (await win.webContents.executeJavaScript(`Boolean(document.querySelector('[data-testid="whats-new"]'))`)) {
+    await shot('whats-new')
+    await click('[data-testid="whats-new-close"]')
+  }
   await shot('home')
   await click('[data-testid="project-card"]')
   await shot('clips')
diff --git a/src/main/updates.ts b/src/main/updates.ts
index b886074..63b5e75 100644
--- a/src/main/updates.ts
+++ b/src/main/updates.ts
@@ -23,6 +23,7 @@ const CHECK_TIMEOUT_MS = 10_000
 interface GithubRelease {
   tag_name?: string
   html_url?: string
+  body?: string | null
   draft?: boolean
   prerelease?: boolean
   assets?: ReleaseAsset[]
@@ -132,6 +133,7 @@ export function evaluateUpdate(
     latestVersion,
     updateAvailable: latestVersion !== null && compareVersions(latestVersion, currentVersion) > 0,
     releaseUrl: (usable ? release?.html_url : null) ?? (latestVersion ? RELEASES_PAGE : null),
+    releaseNotes: usable ? release?.body?.trim() || null : null,
     autoUpdateSupported,
     sourceUpdateSupported,
     error: null,
diff --git a/src/renderer/src/App.tsx b/src/renderer/src/App.tsx
index 487b460..ce2cbf0 100644
--- a/src/renderer/src/App.tsx
+++ b/src/renderer/src/App.tsx
@@ -7,6 +7,7 @@ import EditorScreen from './components/EditorScreen'
 import SettingsModal from './components/SettingsModal'
 import TopBar from './components/TopBar'
 import SetupWizard from './components/SetupWizard'
+import WhatsNewAfterUpdate from './components/WhatsNew'
 import { startUpdateChecks } from '@shared/updateSchedule'
 
 function ScreenView({ screen }: { screen: Screen }): React.JSX.Element {
@@ -71,6 +72,7 @@ export default function App(): React.JSX.Element {
       </main>
       {settingsOpen && <SettingsModal />}
       {settings && !settings.setupComplete && <SetupWizard />}
+      <WhatsNewAfterUpdate />
     </div>
   )
 }
diff --git a/src/renderer/src/components/SettingsModal.tsx b/src/renderer/src/components/SettingsModal.tsx
index 51aa86c..8c14d2c 100644
--- a/src/renderer/src/components/SettingsModal.tsx
+++ b/src/renderer/src/components/SettingsModal.tsx
@@ -22,6 +22,8 @@ import {
   Server,
 } from 'lucide-react'
 import { useStore } from '../store'
+import { NotesList, userNotes, WhatsNewDialog } from './WhatsNew'
+import { parseNotes } from '@shared/releaseNotes'
 import SizeTargetControls from './SizeTargetControls'
 import { DEFAULT_BRAND_COLORS, resolveCaptionStyle } from '@shared/captionStyles'
 import type {
@@ -836,6 +838,9 @@ function UpdatesSection(): React.JSX.Element {
     Object.values(s.exports).some((e) => e.status === 'exporting') ||
     Object.values(s.reframeBusy).some(Boolean) || Object.values(s.captionBusy).some(Boolean))
 
+  const [notesOpen, setNotesOpen] = useState(false)
+  const upcoming = updateCheck?.updateAvailable && updateCheck.releaseNotes ? userNotes(parseNotes(updateCheck.releaseNotes)) : []
+
   return (
     <div className="max-w-xl">
       <label className="flex items-center gap-2 text-sm font-medium">
@@ -844,7 +849,20 @@ function UpdatesSection(): React.JSX.Element {
       </label>
       <p className="mt-1 text-xs text-zinc-500">
         Cutawan v{settings?.appVersion ?? '…'} — updates are checked on launch and every six hours.
+        {settings?.appVersion && (
+          <button type="button" onClick={() => setNotesOpen(true)} data-testid="whats-new-button"
+            className="ml-1.5 text-zinc-400 underline underline-offset-2 hover:text-zinc-200">
+            What&apos;s new in this version
+          </button>
+        )}
       </p>
+      {notesOpen && settings?.appVersion && <WhatsNewDialog version={settings.appVersion} onClose={() => setNotesOpen(false)} />}
+      {upcoming.length > 0 && (
+        <div className="mt-2.5 rounded-lg border border-surface-600 bg-surface-850 px-3 py-2.5" data-testid="update-notes">
+          <p className="mb-2 text-xs font-medium text-zinc-200">What&apos;s new in v{updateCheck?.latestVersion}</p>
+          <NotesList blocks={upcoming} compact />
+        </div>
+      )}
 
       {updateDownload.status !== 'idle' || (updateCheck?.updateAvailable &&
         (updateCheck.autoUpdateSupported || updateCheck.manualDownloadSupported)) ? (
diff --git a/src/renderer/src/components/WhatsNew.tsx b/src/renderer/src/components/WhatsNew.tsx
new file mode 100644
index 0000000..6eb1ce5
--- /dev/null
+++ b/src/renderer/src/components/WhatsNew.tsx
@@ -0,0 +1,93 @@
+import { useEffect, useMemo, useState } from 'react'
+import { Sparkles, X } from 'lucide-react'
+import changelog from '../../../../CHANGELOG.md?raw'
+import { changelogSection, parseNotes, type NotesBlock } from '@shared/releaseNotes'
+import { useStore } from '../store'
+
+/** This build's notes, from the CHANGELOG bundled at build time. */
+export function bundledNotes(version: string): NotesBlock[] {
+  return userNotes(parseNotes(changelogSection(changelog, version)))
+}
+
+/** Validation write-ups are for contributors, not the in-app notes. */
+export function userNotes(blocks: NotesBlock[]): NotesBlock[] {
+  return blocks.filter((block) => !/^validation\b/i.test(block.heading ?? ''))
+}
+
+/** Grouped release notes; also used for an available update's notes. */
+export function NotesList({ blocks, compact = false }: { blocks: NotesBlock[]; compact?: boolean }): React.JSX.Element {
+  return (
+    <div className={compact ? 'space-y-2' : 'space-y-4'}>
+      {blocks.map((block, i) => (
+        <section key={i}>
+          {block.heading && (
+            <h3 className={`font-semibold uppercase tracking-wide text-zinc-400 ${compact ? 'text-[10px]' : 'text-[11px]'}`}>
+              {block.heading}
+            </h3>
+          )}
+          <ul className={`mt-1.5 list-disc space-y-1 pl-4 ${compact ? 'text-[11px]' : 'text-xs'} leading-relaxed text-zinc-300`}>
+            {block.items.map((item, j) => (
+              <li key={j}>{item.replace(/`([^`]+)`/g, '$1').replace(/\*\*([^*]+)\*\*/g, '$1')}</li>
+            ))}
+          </ul>
+        </section>
+      ))}
+    </div>
+  )
+}
+
+export function WhatsNewDialog({ version, onClose }: { version: string; onClose: () => void }): React.JSX.Element {
+  const blocks = bundledNotes(version)
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent): void => { if (e.key === 'Escape') onClose() }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [onClose])
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/80 p-6 backdrop-blur-sm" onClick={onClose}>
+      <div role="dialog" aria-label={`What's new in Cutawan ${version}`} data-testid="whats-new"
+        className="max-h-[80vh] w-full max-w-lg overflow-y-auto rounded-2xl border border-zinc-700 bg-zinc-900 p-6 shadow-2xl shadow-black/70"
+        onClick={(e) => e.stopPropagation()}>
+        <div className="flex items-start justify-between gap-4">
+          <h2 className="flex items-center gap-2 text-lg font-semibold tracking-tight">
+            <Sparkles size={18} className="text-accent-400" />
+            What&apos;s new in v{version}
+          </h2>
+          <button type="button" onClick={onClose} aria-label="Close" data-testid="whats-new-close" className="rounded-lg p-1 text-zinc-500 hover:bg-surface-700 hover:text-zinc-200">
+            <X size={16} />
+          </button>
+        </div>
+        <div className="mt-4">
+          {blocks.length ? <NotesList blocks={blocks} /> : <p className="text-xs text-zinc-500">No release notes for this version.</p>}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+const SEEN_KEY = 'cutawan:notes-seen-version'
+
+/**
+ * Shows this version's notes once after an update. A fresh install records
+ * the version silently; someone with existing projects (updating from a
+ * version before this dialog existed) sees the notes.
+ */
+export default function WhatsNewAfterUpdate(): React.JSX.Element | null {
+  const version = useStore((s) => s.settings?.setupComplete ? s.settings.appVersion : null)
+  const hasProjects = useStore((s) => s.projects.length > 0)
+  const [dismissed, setDismissed] = useState<string | null>(null)
+  const seen = useMemo(() => {
+    try { return localStorage.getItem(SEEN_KEY) } catch { return version }
+  }, [version])
+  const pending = Boolean(version && seen !== version && (seen || hasProjects) && bundledNotes(version).length)
+  // A fresh install (or a version without notes) is recorded silently.
+  useEffect(() => {
+    if (!version || pending || seen === version) return
+    try { localStorage.setItem(SEEN_KEY, version) } catch { /* storage unavailable */ }
+  }, [version, pending, seen])
+  if (!version || !pending || dismissed === version) return null
+  return <WhatsNewDialog version={version} onClose={() => {
+    try { localStorage.setItem(SEEN_KEY, version) } catch { /* storage unavailable */ }
+    setDismissed(version)
+  }} />
+}
diff --git a/src/shared/releaseNotes.ts b/src/shared/releaseNotes.ts
new file mode 100644
index 0000000..fd3fa07
--- /dev/null
+++ b/src/shared/releaseNotes.ts
@@ -0,0 +1,41 @@
+/**
+ * Release notes come from CHANGELOG.md: the release workflow publishes a
+ * version's section as its GitHub release notes, and the app shows the same
+ * section as "What's new" after an update.
+ */
+
+const headingVersion = (line: string): string | undefined =>
+  line.match(/^##\s+\[?([0-9]+\.[0-9]+\.[0-9]+)\]?/)?.[1]
+
+/** The body of `## [version]` in a changelog, trimmed; empty when absent. */
+export function changelogSection(changelog: string, version: string): string {
+  const lines = changelog.split(/\r?\n/)
+  const start = lines.findIndex((line) => headingVersion(line) === version)
+  if (start === -1) return ''
+  const rest = lines.slice(start + 1)
+  const end = rest.findIndex((line) => /^##\s+/.test(line))
+  return (end === -1 ? rest : rest.slice(0, end)).join('\n').trim()
+}
+
+export interface NotesBlock { heading: string | null; items: string[] }
+
+/**
+ * Split a section into `### Heading` groups of bullet items, joining wrapped
+ * bullet lines. Only the plain structure the changelog uses; no general
+ * Markdown.
+ */
+export function parseNotes(section: string): NotesBlock[] {
+  const blocks: NotesBlock[] = []
+  let current: NotesBlock | null = null
+  for (const raw of section.split(/\r?\n/)) {
+    const line = raw.trim()
+    if (!line) continue
+    const heading = line.match(/^###\s+(.*)$/)
+    if (heading) { current = { heading: heading[1], items: [] }; blocks.push(current); continue }
+    if (!current) { current = { heading: null, items: [] }; blocks.push(current) }
+    if (/^[-*]\s+/.test(line)) current.items.push(line.replace(/^[-*]\s+/, ''))
+    else if (current.items.length) current.items[current.items.length - 1] += ` ${line}`
+    else current.items.push(line)
+  }
+  return blocks.filter((b) => b.items.length)
+}
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 0ab280d..aee02d8 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -438,6 +438,8 @@ export interface UpdateCheckResult {
   updateAvailable: boolean
   /** GitHub release page to download the update from. */
   releaseUrl: string | null
+  /** The latest release's notes (its CHANGELOG section), when published. */
+  releaseNotes?: string | null
   /**
    * True when the app can download and install the update itself. Unsigned
    * packaged Macs use a manual download; source checkouts pull and rebuild.
diff --git a/tests/releaseNotes.test.ts b/tests/releaseNotes.test.ts
new file mode 100644
index 0000000..842fbbd
--- /dev/null
+++ b/tests/releaseNotes.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { changelogSection, parseNotes } from '@shared/releaseNotes'
+
+const sample = `# Changelog
+
+## [Unreleased]
+
+### Added
+
+- New thing
+
+## [1.2.0] - 2026-09-01
+
+### Improved
+
+- Faster exports that
+  wrap onto a second line.
+- Steadier camera.
+
+### Fixed
+
+- A bug.
+
+## [1.1.0] - 2026-08-01
+
+- Old.
+`
+
+describe('release notes', () => {
+  it('extracts one version and groups its bullets under headings', () => {
+    const section = changelogSection(sample, '1.2.0')
+    expect(section).not.toContain('New thing')
+    expect(section).not.toContain('Old.')
+    expect(parseNotes(section)).toEqual([
+      { heading: 'Improved', items: ['Faster exports that wrap onto a second line.', 'Steadier camera.'] },
+      { heading: 'Fixed', items: ['A bug.'] }
+    ])
+  })
+
+  it('returns nothing for a version without notes', () => {
+    expect(changelogSection(sample, '9.9.9')).toBe('')
+    expect(parseNotes('')).toEqual([])
+  })
+
+  it('has notes for the current package version, as releases require', () => {
+    const version = JSON.parse(readFileSync('package.json', 'utf8')).version
+    expect(parseNotes(changelogSection(readFileSync('CHANGELOG.md', 'utf8'), version)).length).toBeGreaterThan(0)
+  })
+})
diff --git a/tests/updates.test.ts b/tests/updates.test.ts
index ac89ca2..e154e77 100644
--- a/tests/updates.test.ts
+++ b/tests/updates.test.ts
@@ -125,6 +125,13 @@ describe('evaluateUpdate', () => {
     expect(res.error).toBeNull()
   })
 
+  it('carries the published release notes, never a draft\'s', () => {
+    expect(evaluateUpdate('0.1.0', { tag_name: 'v0.2.0', body: '### Added\n\n- Timeline cuts\n' }).releaseNotes)
+      .toBe('### Added\n\n- Timeline cuts')
+    expect(evaluateUpdate('0.1.0', { tag_name: 'v0.2.0', body: 'secret', draft: true }).releaseNotes).toBeNull()
+    expect(evaluateUpdate('0.1.0', { tag_name: 'v0.2.0', body: '   ' }).releaseNotes).toBeNull()
+  })
+
   it('reports up to date when the release matches or is older', () => {
     expect(evaluateUpdate('0.2.0', { tag_name: 'v0.2.0' }).updateAvailable).toBe(false)
     expect(evaluateUpdate('0.3.0', { tag_name: 'v0.2.0' }).updateAvailable).toBe(false)

From bb63e8da36d98793c2d8f35ebdf8079c702cf0f8 Mon Sep 17 00:00:00 2001
From: Jeremy Smith <145979804+JeremySNR@users.noreply.github.com>
Date: Wed, 23 Sep 2026 08:00:20 +0100
Subject: [PATCH 2/3] Fix review findings in release notes

- Read the seen-notes version every render, so a fresh install's silent
  record stops the dialog appearing once the first project exists.
- Portal the What's new dialog to the body so Settings cannot clip it.
- Accept a release PR that renames [Unreleased] to the new version.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 scripts/check-release-notes.mjs          | 36 +++++++++++++++---------
 src/renderer/src/components/WhatsNew.tsx | 19 ++++++++-----
 2 files changed, 34 insertions(+), 21 deletions(-)

diff --git a/scripts/check-release-notes.mjs b/scripts/check-release-notes.mjs
index 9ca08b2..5e8c984 100644
--- a/scripts/check-release-notes.mjs
+++ b/scripts/check-release-notes.mjs
@@ -12,7 +12,7 @@
 import { execFileSync } from 'node:child_process'
 import { readFileSync } from 'node:fs'
 
-const base = process.env.BASE_REF || 'origin/main'
+const baseRef = process.env.BASE_REF || 'origin/main'
 const labels = JSON.parse(process.env.PR_LABELS || '[]').map((l) => String(l).toLowerCase())
 if (labels.includes('no release notes')) {
   console.log('Skipped: labelled "no release notes".')
@@ -20,26 +20,34 @@ if (labels.includes('no release notes')) {
 }
 
 const git = (...args) => execFileSync('git', args, { encoding: 'utf8' })
-const changed = git('diff', '--name-only', `${base}...HEAD`).split('\n').filter(Boolean)
+const changed = git('diff', '--name-only', `${baseRef}...HEAD`).split('\n').filter(Boolean)
 const userFacing = changed.filter((f) => /^(src|resources)\//.test(f) || f === 'package.json')
 if (!userFacing.length) {
   console.log('No app changes; release notes not required.')
   process.exit(0)
 }
 
-const unreleased = (text) => {
-  const lines = text.split(/\r?\n/)
-  const start = lines.findIndex((l) => /^##\s+\[?unreleased\]?/i.test(l))
-  if (start === -1) return ''
-  const rest = lines.slice(start + 1)
-  const end = rest.findIndex((l) => /^##\s+/.test(l))
-  return (end === -1 ? rest : rest.slice(0, end)).filter((l) => /^\s*[-*]\s+\S/.test(l)).join('\n')
+// Bullets under [Unreleased] and under every version section. A release PR
+// renames [Unreleased] to the new version, so a new or changed section of
+// either kind counts as release notes.
+const sections = (text) => {
+  const out = new Map()
+  let name = null
+  for (const line of text.split(/\r?\n/)) {
+    const heading = line.match(/^##\s+\[?([^\]\s]+)\]?/)
+    if (heading) { name = heading[1].toLowerCase(); out.set(name, []); continue }
+    if (name && /^\s*[-*]\s+\S/.test(line)) out.get(name).push(line.trim())
+  }
+  return out
 }
-let before = ''
-try { before = unreleased(git('show', `${base}:CHANGELOG.md`)) } catch { /* new file */ }
-const after = unreleased(readFileSync('CHANGELOG.md', 'utf8'))
+let baseSections = new Map()
+try { baseSections = sections(git('show', `${baseRef}:CHANGELOG.md`)) } catch { /* new file */ }
+const head = sections(readFileSync('CHANGELOG.md', 'utf8'))
+const added = [...head].filter(([name, bullets]) =>
+  (name === 'unreleased' || /^[0-9]+\.[0-9]+\.[0-9]+$/.test(name)) && bullets.length &&
+  bullets.join('\n') !== (baseSections.get(name) ?? []).join('\n'))
 
-if (!after || after === before) {
+if (!added.length) {
   console.error([
     'This pull request changes the app but adds no release notes.',
     '',
@@ -51,4 +59,4 @@ if (!after || after === before) {
   ].join('\n'))
   process.exit(1)
 }
-console.log('Release notes present under [Unreleased].')
+console.log(`Release notes present: ${added.map(([name]) => `[${name}]`).join(', ')}.`)
diff --git a/src/renderer/src/components/WhatsNew.tsx b/src/renderer/src/components/WhatsNew.tsx
index 6eb1ce5..de25b48 100644
--- a/src/renderer/src/components/WhatsNew.tsx
+++ b/src/renderer/src/components/WhatsNew.tsx
@@ -1,4 +1,5 @@
-import { useEffect, useMemo, useState } from 'react'
+import { useEffect, useState } from 'react'
+import { createPortal } from 'react-dom'
 import { Sparkles, X } from 'lucide-react'
 import changelog from '../../../../CHANGELOG.md?raw'
 import { changelogSection, parseNotes, type NotesBlock } from '@shared/releaseNotes'
@@ -43,8 +44,10 @@ export function WhatsNewDialog({ version, onClose }: { version: string; onClose:
     window.addEventListener('keydown', onKey)
     return () => window.removeEventListener('keydown', onKey)
   }, [onClose])
-  return (
-    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/80 p-6 backdrop-blur-sm" onClick={onClose}>
+  // Portalled: opened from Settings, a transformed/clipping ancestor would
+  // otherwise confine the full-window overlay to the settings panel.
+  return createPortal(
+    <div className="fixed inset-0 z-[70] flex items-center justify-center bg-black/80 p-6 backdrop-blur-sm" onClick={onClose}>
       <div role="dialog" aria-label={`What's new in Cutawan ${version}`} data-testid="whats-new"
         className="max-h-[80vh] w-full max-w-lg overflow-y-auto rounded-2xl border border-zinc-700 bg-zinc-900 p-6 shadow-2xl shadow-black/70"
         onClick={(e) => e.stopPropagation()}>
@@ -61,7 +64,8 @@ export function WhatsNewDialog({ version, onClose }: { version: string; onClose:
           {blocks.length ? <NotesList blocks={blocks} /> : <p className="text-xs text-zinc-500">No release notes for this version.</p>}
         </div>
       </div>
-    </div>
+    </div>,
+    document.body
   )
 }
 
@@ -76,9 +80,10 @@ export default function WhatsNewAfterUpdate(): React.JSX.Element | null {
   const version = useStore((s) => s.settings?.setupComplete ? s.settings.appVersion : null)
   const hasProjects = useStore((s) => s.projects.length > 0)
   const [dismissed, setDismissed] = useState<string | null>(null)
-  const seen = useMemo(() => {
-    try { return localStorage.getItem(SEEN_KEY) } catch { return version }
-  }, [version])
+  // Read every render (cheap): a fresh install's silent write below must be
+  // seen before a first project would otherwise make this look like an update.
+  let seen: string | null
+  try { seen = localStorage.getItem(SEEN_KEY) } catch { seen = version }
   const pending = Boolean(version && seen !== version && (seen || hasProjects) && bundledNotes(version).length)
   // A fresh install (or a version without notes) is recorded silently.
   useEffect(() => {

From f1fc567338fe1b537750c680db4a244543dbbe72 Mon Sep 17 00:00:00 2001
From: Jeremy Smith <145979804+JeremySNR@users.noreply.github.com>
Date: Wed, 23 Sep 2026 09:28:41 +0100
Subject: [PATCH 3/3] Accept any label encoding in the release-notes check

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 scripts/check-release-notes.mjs | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/scripts/check-release-notes.mjs b/scripts/check-release-notes.mjs
index 5e8c984..01267c5 100644
--- a/scripts/check-release-notes.mjs
+++ b/scripts/check-release-notes.mjs
@@ -13,7 +13,18 @@ import { execFileSync } from 'node:child_process'
 import { readFileSync } from 'node:fs'
 
 const baseRef = process.env.BASE_REF || 'origin/main'
-const labels = JSON.parse(process.env.PR_LABELS || '[]').map((l) => String(l).toLowerCase())
+// Accept a JSON list, a single JSON string or a bare name, whatever the
+// workflow expression renders to.
+const parseLabels = (raw) => {
+  if (!raw) return []
+  try {
+    const value = JSON.parse(raw)
+    return (Array.isArray(value) ? value : [value]).map((l) => String(l).toLowerCase())
+  } catch {
+    return [raw.toLowerCase()]
+  }
+}
+const labels = parseLabels(process.env.PR_LABELS)
 if (labels.includes('no release notes')) {
   console.log('Skipped: labelled "no release notes".')
   process.exit(0)