ci: release with semantic-release from conventional commits

.github/workflows/pr-title.yml

@@ -0,0 +1,19 @@
+name: PR title
+
+# This repository merges by squash, and the squash commit takes the pull
+# request title. The title is therefore the release trigger, and the only
+# text semantic-release will read as a commit subject.
+on:
+  pull_request:
+    types: [opened, edited, reopened, synchronize]
+
+permissions:
+  pull-requests: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v6
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yml

@@ -0,0 +1,41 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      # semantic-release pushes the tag and creates the GitHub release,
+      # comments on the issues and pull requests a release closes, and
+      # publishes to npm through OIDC instead of a token.
+      contents: write
+      issues: write
+      pull-requests: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci
+      # The suite renders in real browsers, as in ci.yml.
+      - name: Install browsers
+        run: npx playwright install --with-deps chromium firefox
+      - run: npm test
+      # npm trusted publishing needs npm >= 11.5.1; Node 24 ships it.
+      - run: npm --version
+      - run: npx semantic-release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.releaserc.json

@@ -0,0 +1,9 @@
+{
+  "branches": ["master"],
+  "plugins": [
+    ["@semantic-release/commit-analyzer", { "preset": "conventionalcommits" }],
+    ["@semantic-release/release-notes-generator", { "preset": "conventionalcommits" }],
+    "@semantic-release/npm",
+    "@semantic-release/github"
+  ]
+}

README.md

@@ -190,3 +190,28 @@ npm run fixtures:update   # rewrite reference images from a Chromium render
 Lint and formatting are Biome's, configured in `biome.jsonc`. `src/spriting.js`
 is the one file with a rule exception, explained in that config: it is a port of
 the 0.5.0 sprite sheet and is kept diffable against it.
+
+## Releases
+
+Releases are made by [semantic-release](https://semantic-release.gitbook.io/)
+from `master`: it decides the version, writes the release notes, tags, and
+publishes to npm. Nothing is released by hand, and `package.json` carries
+`0.0.0-development` — the published version is set during the release.
+
+This repository merges pull requests by squash, and the squash commit takes the
+**pull request title**. The title is therefore what decides the next version:
+
+| Pull request title | Release |
+| --- | --- |
+| `fix: ...`, `perf: ...` | patch |
+| `feat: ...` | minor |
+| `feat!: ...`, or any type with a `BREAKING CHANGE:` footer | major |
+| `docs:`, `test:`, `chore:`, `refactor:`, `revert:`, `ci:`, `build:`, `style:` | none |
+
+Note `revert:` in the last row: reverting a released change does not itself
+release, so an actual rollback wants `fix:`.
+
+A workflow checks the title against this convention on every pull request, so a
+title that would not release — or would release the wrong thing — fails before
+review. The scope (`fix(matchers): ...`) is free text and does not affect the
+version.