From f81e12bf0eecb0bfdf5f12dbab057e689d52a765 Mon Sep 17 00:00:00 2001
From: SandroMaglione <lass.maglio@gmail.com>
Date: Fri, 14 Aug 2026 06:20:21 +0200
Subject: [PATCH 1/2] Improve API reference navigation and changelog

---
 .changeset/README.md                          |  32 +++
 .github/workflows/website.yml                 |   2 +
 AGENTS.md                                     |   2 +-
 CHANGELOG.md                                  |  28 ++-
 .../api-reference-site.test.mjs               | 107 ++++++++
 scripts/api-reference-site/assets/client.js   |  18 +-
 scripts/api-reference-site/assets/styles.css  | 123 +++++++++-
 scripts/api-reference-site/generate.mjs       | 229 +++++++++++++++++-
 8 files changed, 518 insertions(+), 23 deletions(-)

diff --git a/.changeset/README.md b/.changeset/README.md
index 0df73d6..f08f492 100644
--- a/.changeset/README.md
+++ b/.changeset/README.md
@@ -1,3 +1,35 @@
 # Changesets
 
 Run `pnpm changeset` for every user-facing change.
+
+## Writing changelog entries
+
+Changeset descriptions are published directly on the documentation website. Write them for library users rather than repository maintainers.
+
+- Lead with the user-visible outcome and name the affected API when useful.
+- Keep the entry short and specific. One to three brief paragraphs is usually enough.
+- Use separate paragraphs when they make the outcome, motivation, or migration clearer.
+- Use inline code for API names, types, and short expressions.
+- Include at most one small fenced TypeScript example when an API is added or its usage changes meaningfully.
+- For a breaking change, state what changed and show the replacement or migration directly.
+- Omit commit hashes, pull request numbers, implementation history, test details, and internal refactoring unless they affect users.
+
+A typical API entry looks like:
+
+````md
+Add `Machine.example` for describing the user-visible behavior.
+
+Use it when a short explanation would not make the new calling pattern clear:
+
+```ts
+const value = Machine.example(input)
+```
+````
+
+Prefer a shorter entry without an example for fixes and internal improvements:
+
+```md
+Fix resumed machines so nested history is restored before raised events are processed.
+
+This preserves the same observable transition order as a freshly started machine.
+```
diff --git a/.github/workflows/website.yml b/.github/workflows/website.yml
index 39d1129..3a931de 100644
--- a/.github/workflows/website.yml
+++ b/.github/workflows/website.yml
@@ -22,6 +22,8 @@ jobs:
       pages: read
     steps:
       - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
       - uses: pnpm/action-setup@v6
       - uses: actions/setup-node@v7
         with:
diff --git a/AGENTS.md b/AGENTS.md
index 830348d..50e60c0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -49,5 +49,5 @@ Every package directly below `examples/` must have a `check` script and a commit
 
 ## Pull request conventions
 
-- Add or update a changeset for changes under `src/` or changes to `package.json`.
+- Add or update a changeset for changes under `src/` or changes to `package.json`, following the changelog-writing guide in `.changeset/README.md`.
 - Fill in the pull request template, including the validation performed and the changeset decision.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 262f7e1..37d23c5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,9 +4,31 @@
 
 ### Minor Changes
 
-- b192484: Allow state query helpers to inspect extracted snapshot subtrees, and add
-  equality-aware `AtomMachine.selectSnapshot` and `selectSnapshotChild`
-  combinators.
+- b192484: Allow `Machine.defineStates` query helpers to inspect an extracted
+  snapshot subtree. Paths remain absolute and type-safe, but `get`,
+  `getSnapshot`, and `matches` can now continue from a snapshot selected
+  earlier instead of requiring the complete root snapshot.
+
+  ```ts
+  const readySnapshot = States.getSnapshot(snapshot, "Ready")
+
+  if (Option.isSome(readySnapshot)) {
+    States.get(readySnapshot.value, "Ready.editor")
+    States.matches(readySnapshot.value, "Ready.editor.Editing")
+  }
+
+  const editorSnapshotAtom = AtomMachine.selectSnapshot(
+    machineAtom,
+    "Ready.editor"
+  )
+  ```
+
+  Add equality-aware `AtomMachine.selectSnapshot` and
+  `AtomMachine.selectSnapshotChild` combinators for reactive consumers that
+  need the complete logical snapshot subtree instead of only its state value.
+  The selected atoms retain nested topology, suppress structurally equal
+  updates, and produce `Option.none()` while the path or invoked child is
+  inactive.
 
 ## 0.6.1
 
diff --git a/scripts/api-reference-site/api-reference-site.test.mjs b/scripts/api-reference-site/api-reference-site.test.mjs
index 21576af..172b79d 100644
--- a/scripts/api-reference-site/api-reference-site.test.mjs
+++ b/scripts/api-reference-site/api-reference-site.test.mjs
@@ -7,9 +7,13 @@ import {
   normalizeBasePath,
   normalizeGitHubStars,
   normalizeOrigin,
+  parseChangelog,
+  parseChangeset,
+  renderChangelogPage,
   renderIndexPage,
   renderLayout,
   renderMarkdown,
+  renderModulePage,
   renderRobots,
   renderSitemap,
   siteManifest,
@@ -30,6 +34,22 @@ test("renders documentation prose while escaping source HTML", () => {
   assert.doesNotMatch(renderMarkdown("<script>alert(1)</script>"), /<script>/)
 })
 
+test("renders fenced code with highlighting and copy controls", () => {
+  const html = renderMarkdown(`Call the new API:
+
+\`\`\`ts
+const value = Machine.example("safe")
+\`\`\`
+
+Then reuse \`value\`.`)
+  assert.match(html, /<p>Call the new API:<\/p>/)
+  assert.match(html, /class="code-block code-block--markdown"/)
+  assert.match(html, /aria-label="Copy ts code"/)
+  assert.match(html, /syntax-keyword">const<\/span>/)
+  assert.match(html, /syntax-string">&quot;safe&quot;<\/span>/)
+  assert.match(html, /<p>Then reuse <code>value<\/code>\.<\/p>/)
+})
+
 test("assigns deterministic unique anchors to duplicate declarations", () => {
   const first = { name: "Machine" }
   const second = { name: "Machine" }
@@ -88,6 +108,92 @@ const site = {
   title: "Effect Machine"
 }
 
+test("parses Changesets release entries and pending descriptions", () => {
+  const releases = parseChangelog(`# Package
+
+## 1.2.0
+
+### Minor Changes
+
+- abc1234: Add a typed \`make\` helper.
+
+  Preserve inference across multiple lines.
+
+  \`\`\`ts
+  const machine = make()
+  \`\`\`
+
+### Patch Changes
+
+- def5678: Fix escaped output.
+`, new Map([["1.2.0", "2026-08-13"]]))
+  assert.deepEqual(releases, [{
+    version: "1.2.0",
+    date: "2026-08-13",
+    groups: [{
+      type: "minor",
+      entries: [{
+        description: "Add a typed `make` helper.\n\nPreserve inference across multiple lines.\n\n```ts\nconst machine = make()\n```"
+      }]
+    }, {
+      type: "patch",
+      entries: [{ description: "Fix escaped output." }]
+    }]
+  }])
+  assert.deepEqual(parseChangeset(`---
+"@typeonce/effect-machine": minor
+---
+
+Add snapshot selectors.
+`, "@typeonce/effect-machine"), { type: "minor", description: "Add snapshot selectors." })
+  assert.equal(parseChangeset(`---
+"another-package": patch
+---
+
+Ignore this package.
+`, "@typeonce/effect-machine"), undefined)
+})
+
+test("renders a navigable changelog with release dates", () => {
+  const html = renderChangelogPage({
+    ...site,
+    changelog: [{
+      version: "1.2.0",
+      date: "2026-08-13",
+      groups: [{ type: "minor", entries: [{ description: "Add a feature." }] }]
+    }]
+  })
+  assert.match(html, /class="navigation-changelog is-current"/)
+  assert.match(html, /id="release-1-2-0">v1\.2\.0/)
+  assert.match(html, /datetime="2026-08-13">August 13, 2026/)
+  assert.match(html, /<li><p>Add a feature\.<\/p><\/li>/)
+})
+
+test("renders collapsible category navigation with declaration anchors", () => {
+  const declaration = {
+    name: "make",
+    kind: "variable",
+    description: "Creates a machine.",
+    examples: [],
+    see: []
+  }
+  const module = {
+    api: {
+      declarationCount: 1,
+      description: "State machine APIs",
+      groups: [{ category: "constructors", declarations: [declaration] }]
+    },
+    export: "./Machine",
+    label: "Machine",
+    route: "Machine"
+  }
+  const html = renderModulePage({ ...site, modules: [module] }, module)
+  assert.match(html, /<details class="page-toc__group">/)
+  assert.match(html, /<summary>[\s\S]*Constructors[\s\S]*<\/summary>/)
+  assert.match(html, /<a href="#make">make<\/a>/)
+  assert.match(html, /<h3 id="make">make<\/h3>/)
+})
+
 test("renders canonical and social metadata without exposing the internal channel", () => {
   const html = renderLayout(site, {
     content: '<section class="reference-hero"><div class="eyebrow">API reference</div></section>',
@@ -162,6 +268,7 @@ test("generates manifest, robots, and sitemap URLs from the deployment base", ()
   assert.equal(manifest.icons[2].purpose, "maskable")
   assert.match(renderRobots(site), /Sitemap: https:\/\/docs\.example\.com\/docs\/sitemap\.xml/)
   assert.match(renderSitemap(site), /<loc>https:\/\/docs\.example\.com\/docs\/Machine\/<\/loc>/)
+  assert.match(renderSitemap(site), /<loc>https:\/\/docs\.example\.com\/docs\/changelog\/<\/loc>/)
 })
 
 test("accepts only pathless HTTPS production origins", () => {
diff --git a/scripts/api-reference-site/assets/client.js b/scripts/api-reference-site/assets/client.js
index 1ce30e2..eb4a572 100644
--- a/scripts/api-reference-site/assets/client.js
+++ b/scripts/api-reference-site/assets/client.js
@@ -85,14 +85,26 @@ searchInput?.addEventListener("input", async () => {
     const search = await pagefind.search(query)
     const data = await Promise.all(search.results.slice(0, 12).map((result) => result.data()))
     if (sequence !== searchSequence) return
-    searchStatus.textContent = `${search.results.length} result${search.results.length === 1 ? "" : "s"}`
-    for (const result of data) {
+    const seen = new Set()
+    const results = data.flatMap((result) => {
+      const sections = result.sub_results?.filter((section) => section.url.includes("#")) ?? []
+      const candidates = sections.length === 0
+        ? [{ title: result.meta.title, url: result.url, excerpt: result.excerpt }]
+        : sections.map((section) => ({ ...section, title: `${section.title} · ${result.meta.title}` }))
+      return candidates.filter((candidate) => {
+        if (seen.has(candidate.url)) return false
+        seen.add(candidate.url)
+        return true
+      })
+    }).slice(0, 12)
+    searchStatus.textContent = `${results.length} result${results.length === 1 ? "" : "s"}`
+    for (const result of results) {
       const item = document.createElement("li")
       const link = document.createElement("a")
       const title = document.createElement("strong")
       const excerpt = document.createElement("span")
       link.href = result.url
-      title.textContent = result.meta.title
+      title.textContent = result.title
       excerpt.innerHTML = result.excerpt
       link.append(title, excerpt)
       item.append(link)
diff --git a/scripts/api-reference-site/assets/styles.css b/scripts/api-reference-site/assets/styles.css
index c3f1adc..63f0103 100644
--- a/scripts/api-reference-site/assets/styles.css
+++ b/scripts/api-reference-site/assets/styles.css
@@ -312,6 +312,10 @@ kbd {
   padding: 0.55rem 0.65rem;
 }
 
+.module-navigation .navigation-changelog {
+  margin-top: 0.15rem;
+}
+
 .module-navigation a:hover,
 .module-navigation a.is-current {
   background: var(--accent-soft);
@@ -347,7 +351,8 @@ kbd {
 }
 
 .reference-hero,
-.module-reference {
+.module-reference,
+.changelog {
   margin: 0 auto;
   max-width: 64rem;
 }
@@ -381,14 +386,16 @@ h3 {
 }
 
 .reference-hero h1,
-.module-header h1 {
+.module-header h1,
+.changelog-header h1 {
   font-size: clamp(2.35rem, 4.5vw, 4.2rem);
   line-height: 0.95;
   margin-bottom: 1.25rem;
 }
 
 .reference-hero > p,
-.module-header > p {
+.module-header > p,
+.changelog-header > p {
   color: var(--text-soft);
   font-size: 1.06rem;
   line-height: 1.75;
@@ -503,6 +510,50 @@ h3 {
   padding: 0.34rem 0 0.34rem 0.75rem;
 }
 
+.page-toc__group + .page-toc__group {
+  margin-top: 0.25rem;
+}
+
+.page-toc__group summary {
+  align-items: center;
+  color: var(--muted);
+  cursor: pointer;
+  display: flex;
+  font-size: 0.73rem;
+  gap: 0.35rem;
+  justify-content: space-between;
+  list-style: none;
+  padding: 0.34rem 0;
+}
+
+.page-toc__group summary::-webkit-details-marker {
+  display: none;
+}
+
+.page-toc__group summary::before {
+  content: "›";
+  font-size: 0.9rem;
+  transition: transform 140ms ease;
+}
+
+.page-toc__group[open] summary::before {
+  transform: rotate(90deg);
+}
+
+.page-toc__group summary span {
+  flex: 1;
+}
+
+.page-toc__group nav {
+  margin: 0.1rem 0 0.45rem;
+}
+
+.page-toc__group nav a {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  overflow-wrap: anywhere;
+  padding-left: 1rem;
+}
+
 .page-toc a:hover {
   border-color: var(--accent);
   color: var(--accent);
@@ -521,6 +572,66 @@ h3 {
   margin-bottom: 3.5rem;
 }
 
+.changelog-header {
+  border-bottom: 1px solid var(--border);
+  padding-bottom: 3rem;
+}
+
+.release {
+  padding-top: 4rem;
+}
+
+.release__header {
+  align-items: baseline;
+  border-bottom: 1px solid var(--border);
+  display: flex;
+  justify-content: space-between;
+  padding-bottom: 0.8rem;
+}
+
+.release__header h2 {
+  font-size: 1.75rem;
+  margin: 0;
+}
+
+.release__header time {
+  color: var(--muted);
+  font-size: 0.75rem;
+}
+
+.release-group {
+  margin-top: 2rem;
+}
+
+.release-group h3 {
+  color: var(--muted);
+  font-size: 0.75rem;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.change-list {
+  display: grid;
+  gap: 1rem;
+  margin: 0;
+  padding-left: 1.25rem;
+}
+
+.change-list li {
+  color: var(--text-soft);
+  font-size: 0.9rem;
+  line-height: 1.7;
+  padding-left: 0.25rem;
+}
+
+.change-list li::marker {
+  color: var(--accent);
+}
+
+.change-list p:last-child {
+  margin-bottom: 0;
+}
+
 .breadcrumbs a:hover,
 .source-link:hover {
   color: var(--accent);
@@ -541,7 +652,8 @@ h3 {
 
 .module-meta code,
 .declaration__description code,
-.see-also code {
+.see-also code,
+.change-list p code {
   background: var(--code);
   border: 1px solid var(--border);
   border-radius: 0.28rem;
@@ -921,7 +1033,8 @@ h3 {
   }
 
   .reference-hero h1,
-  .module-header h1 {
+  .module-header h1,
+  .changelog-header h1 {
     font-size: clamp(2.15rem, 11vw, 3.35rem);
   }
 
diff --git a/scripts/api-reference-site/generate.mjs b/scripts/api-reference-site/generate.mjs
index 25ca7c0..58f11bb 100644
--- a/scripts/api-reference-site/generate.mjs
+++ b/scripts/api-reference-site/generate.mjs
@@ -1,3 +1,4 @@
+import { execFileSync } from "node:child_process"
 import {
   cpSync,
   copyFileSync,
@@ -67,6 +68,7 @@ const readSiteModel = (inputDirectory, config) => {
       navigationGroup: navigationGroup(segments)
     }
   })
+  const changelog = readChangelog(packageManifest.name)
 
   return {
     ...config,
@@ -74,7 +76,8 @@ const readSiteModel = (inputDirectory, config) => {
     revision: dataset.revision,
     package: packageManifest,
     modules,
-    navigation: groupNavigation(modules)
+    navigation: groupNavigation(modules),
+    changelog
   }
 }
 
@@ -94,6 +97,7 @@ const groupNavigation = (modules) => {
 
 const writeSite = (outputDirectory, site) => {
   writePage(join(outputDirectory, "index.html"), renderIndexPage(site))
+  writePage(join(outputDirectory, "changelog", "index.html"), renderChangelogPage(site))
   for (const module of site.modules) {
     writePage(join(outputDirectory, module.route, "index.html"), renderModulePage(site, module))
   }
@@ -144,17 +148,72 @@ export const renderIndexPage = (site) => {
   })
 }
 
-const renderModulePage = (site, module) => {
+export const renderChangelogPage = (site) => {
+  const releases = site.changelog ?? []
+  const toc = releases.map((release) => `
+    <a href="#release-${slugify(release.version)}">
+      <span>${escapeHtml(release.version === "unreleased" ? "Unreleased" : `v${release.version}`)}</span>
+      ${release.date === undefined ? "" : `<small>${escapeHtml(release.date)}</small>`}
+    </a>`).join("")
+  const content = `
+    <article class="changelog" data-pagefind-meta="type:changelog">
+      <header class="changelog-header">
+        <div class="breadcrumbs">
+          <a href="${siteUrl(site, "")}">API</a>
+          <span aria-hidden="true">/</span>
+          <span>Changelog</span>
+        </div>
+        <div class="eyebrow">Release history</div>
+        <h1>Changelog</h1>
+        <p>New features, improvements, and fixes from each release.</p>
+      </header>
+      ${releases.map(renderRelease).join("")}
+    </article>`
+  return renderLayout(site, {
+    title: `Changelog · ${site.title}`,
+    description: `Release history for ${site.package.name}`,
+    content,
+    currentRoute: "changelog",
+    pageKind: "changelog",
+    toc
+  })
+}
+
+const renderRelease = (release) => `
+  <section class="release" aria-labelledby="release-${slugify(release.version)}">
+    <header class="release__header">
+      <h2 id="release-${slugify(release.version)}">${
+  escapeHtml(release.version === "unreleased" ? "Unreleased" : `v${release.version}`)
+}</h2>
+      ${release.date === undefined ? "" : `
+        <time datetime="${escapeAttribute(release.date)}">${escapeHtml(formatReleaseDate(release.date))}</time>`}
+    </header>
+    ${release.groups.map((group) => `
+      <section class="release-group">
+        <h3>${escapeHtml(`${titleCase(group.type)} changes`)}</h3>
+        <ul class="change-list">
+          ${group.entries.map((entry) => `<li>${renderMarkdown(entry.description)}</li>`).join("")}
+        </ul>
+      </section>`).join("")}
+  </section>`
+
+export const renderModulePage = (site, module) => {
   const declarationIds = uniqueDeclarationIds(module.api.groups)
   const categoryLinks = module.api.groups.map((group) => `
-    <a href="#${slugify(group.category)}">
-      <span>${escapeHtml(titleCase(group.category))}</span>
-      <small>${group.declarations.length}</small>
-    </a>`).join("")
+    <details class="page-toc__group">
+      <summary>
+        <span>${escapeHtml(titleCase(group.category))}</span>
+        <small>${group.declarations.length}</small>
+      </summary>
+      <nav aria-label="${escapeAttribute(titleCase(group.category))} APIs">
+        ${group.declarations.map((declaration) => `
+          <a href="#${declarationIds.get(declaration)}">${escapeHtml(declaration.name)}</a>`).join("")}
+      </nav>
+    </details>`).join("")
   const groups = module.api.groups.map((group) => `
-    <section class="api-group" aria-labelledby="${slugify(group.category)}">
+    <section class="api-group" aria-labelledby="category-${slugify(group.category)}">
       <div class="api-group__heading">
-        <h2 id="${slugify(group.category)}">${escapeHtml(titleCase(group.category))}</h2>
+        <h2 id="category-${slugify(group.category)}">${escapeHtml(titleCase(group.category))}</h2>
         <span>${group.declarations.length}</span>
       </div>
       ${group.declarations.map((declaration) =>
@@ -210,11 +269,11 @@ const renderDeclaration = (declaration, id) => {
     .map((entry) => entry.replace(/^\s*-\s*/, "").trim())
     .filter(Boolean)
   return `
-    <article class="declaration" id="${id}" data-pagefind-meta="kind:${escapeAttribute(declaration.kind)}">
+    <article class="declaration" aria-labelledby="${id}" data-pagefind-meta="kind:${escapeAttribute(declaration.kind)}">
       <header class="declaration__header">
         <div class="declaration__title">
           <a class="anchor" href="#${id}" aria-label="Link to ${escapeAttribute(declaration.name)}">#</a>
-          <h3>${escapeHtml(declaration.name)}</h3>
+          <h3 id="${id}">${escapeHtml(declaration.name)}</h3>
           <span class="kind kind--${slugify(declaration.kind)}">${escapeHtml(declaration.kind)}</span>
         </div>
         ${declaration.sourceUrl === undefined ? "" : sourceLink(declaration.sourceUrl, "Source")}
@@ -350,6 +409,7 @@ const renderNavigation = (site, currentRoute) => `
       <button class="icon-button navigation-close" type="button" aria-label="Close navigation">Close</button>
     </div>
     <a class="navigation-overview${currentRoute === "" ? " is-current" : ""}" href="${siteUrl(site, "")}">Overview</a>
+    <a class="navigation-changelog${currentRoute === "changelog" ? " is-current" : ""}" href="${siteUrl(site, "changelog")}">Changelog</a>
     ${site.navigation.map((group) => `
       <section>
         <h2>${escapeHtml(group.label)}</h2>
@@ -381,6 +441,33 @@ const renderSearchDialog = () => `
 
 export const renderMarkdown = (value) => {
   if (value === undefined || value.trim().length === 0) return ""
+  const lines = value.trim().replaceAll("\r\n", "\n").split("\n")
+  const output = []
+  const prose = []
+  const flushProse = () => {
+    if (prose.length === 0) return
+    output.push(renderProseMarkdown(prose.join("\n")))
+    prose.length = 0
+  }
+  for (let index = 0; index < lines.length; index++) {
+    const fence = /^\s*```([^`]*)\s*$/u.exec(lines[index])
+    if (fence === null) {
+      prose.push(lines[index])
+      continue
+    }
+    flushProse()
+    const source = []
+    for (index += 1; index < lines.length && !/^\s*```\s*$/u.test(lines[index]); index++) {
+      source.push(lines[index])
+    }
+    output.push(renderMarkdownCodeBlock(source.join("\n"), fence[1].trim()))
+  }
+  flushProse()
+  return output.join("")
+}
+
+const renderProseMarkdown = (value) => {
+  if (value.trim().length === 0) return ""
   return value.trim().split(/\n\s*\n/).map((block) => {
     const lines = block.split("\n").map((line) => line.trim()).filter(Boolean)
     if (lines.length === 1 && /^\*\*[^*]+\*\*$/.test(lines[0])) {
@@ -393,6 +480,125 @@ export const renderMarkdown = (value) => {
   }).join("")
 }
 
+const renderMarkdownCodeBlock = (source, language) => {
+  const normalizedLanguage = ({ js: "javascript", jsx: "javascript", ts: "typescript", tsx: "typescript" })[
+    language.toLowerCase()
+  ] ?? language.toLowerCase()
+  const label = language.length === 0 ? "code" : `${language} code`
+  return `
+    <div class="code-block code-block--markdown">
+      <button class="copy-button" type="button" aria-label="Copy ${escapeAttribute(label)}">Copy</button>
+      <pre><code>${highlightCode(source, normalizedLanguage)}</code></pre>
+    </div>`
+}
+
+export const parseChangelog = (markdown, releaseDates = new Map()) => {
+  const headings = [...markdown.matchAll(/^##\s+([^\n]+)\s*$/gm)]
+  return headings.map((heading, index) => {
+    const version = heading[1].trim().replace(/^v/, "")
+    const start = heading.index + heading[0].length
+    const end = headings[index + 1]?.index ?? markdown.length
+    return {
+      version,
+      date: releaseDates.get(version),
+      groups: parseChangeGroups(markdown.slice(start, end))
+    }
+  }).filter((release) => release.groups.length > 0)
+}
+
+export const parseChangeset = (markdown, packageName) => {
+  const match = /^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]+)$/u.exec(markdown.trim())
+  if (match === null) return undefined
+  const escapedPackage = packageName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+  const bump = new RegExp(`^\\s*["']?${escapedPackage}["']?\\s*:\\s*(major|minor|patch)\\s*$`, "mu")
+    .exec(match[1])?.[1]
+  const description = match[2].trim()
+  return bump === undefined || description.length === 0 ? undefined : { type: bump, description }
+}
+
+const parseChangeGroups = (markdown) => {
+  const groups = []
+  let group
+  let entry
+  const finishEntry = () => {
+    if (entry === undefined || group === undefined) return
+    const description = entry.join("\n").trim()
+    if (description.length > 0) group.entries.push({ description })
+    entry = undefined
+  }
+  for (const line of markdown.split("\n")) {
+    const heading = /^###\s+(Major|Minor|Patch) Changes\s*$/iu.exec(line)
+    if (heading !== null) {
+      finishEntry()
+      group = { type: heading[1].toLowerCase(), entries: [] }
+      groups.push(group)
+      continue
+    }
+    const bullet = /^-\s+(?:[0-9a-f]+:\s+)?(.*)$/iu.exec(line)
+    if (bullet !== null && group !== undefined) {
+      finishEntry()
+      entry = [bullet[1]]
+      continue
+    }
+    if (entry !== undefined) entry.push(line.replace(/^ {2}/, ""))
+  }
+  finishEntry()
+  return groups.filter((candidate) => candidate.entries.length > 0)
+}
+
+const readChangelog = (packageName) => {
+  const releases = parseChangelog(
+    readFileSync(join(repositoryDirectory, "CHANGELOG.md"), "utf8"),
+    readReleaseDates(packageName)
+  )
+  const pending = readdirSync(join(repositoryDirectory, ".changeset"), { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".md") && entry.name !== "README.md")
+    .sort((left, right) => left.name.localeCompare(right.name))
+    .map((entry) => parseChangeset(
+      readFileSync(join(repositoryDirectory, ".changeset", entry.name), "utf8"),
+      packageName
+    ))
+    .filter((entry) => entry !== undefined)
+  if (pending.length === 0) return releases
+  const grouped = new Map()
+  for (const entry of pending) grouped.set(entry.type, [...grouped.get(entry.type) ?? [], entry])
+  return [{
+    version: "unreleased",
+    groups: ["major", "minor", "patch"]
+      .filter((type) => grouped.has(type))
+      .map((type) => ({ type, entries: grouped.get(type) }))
+  }, ...releases]
+}
+
+const readReleaseDates = (packageName) => {
+  let output
+  try {
+    output = execFileSync(
+      "git",
+      ["for-each-ref", "--format=%(refname:strip=2)\t%(creatordate:short)", "refs/tags"],
+      { cwd: repositoryDirectory, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }
+    )
+  } catch {
+    return new Map()
+  }
+  const prefix = `${packageName}@`
+  return new Map(output.trim().split("\n").flatMap((line) => {
+    const [tag, date] = line.split("\t")
+    return tag?.startsWith(prefix) && /^\d{4}-\d{2}-\d{2}$/.test(date ?? "")
+      ? [[tag.slice(prefix.length).replace(/^v/, ""), date]]
+      : []
+  }))
+}
+
+const formatReleaseDate = (value) => {
+  const [year, month, day] = value.split("-").map(Number)
+  const months = [
+    "January", "February", "March", "April", "May", "June",
+    "July", "August", "September", "October", "November", "December"
+  ]
+  return `${months[month - 1]} ${day}, ${year}`
+}
+
 const renderInlineMarkdown = (value) => escapeHtml(value)
   .replace(/`([^`]+)`/g, "<code>$1</code>")
   .replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>")
@@ -522,7 +728,7 @@ Sitemap: ${absoluteSiteUrl(site, "sitemap.xml")}
 
 export const renderSitemap = (site) => `<?xml version="1.0" encoding="UTF-8"?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
-${["", ...site.modules.map((module) => `${module.route}/`)]
+${["", "changelog/", ...site.modules.map((module) => `${module.route}/`)]
     .map((route) => `  <url><loc>${escapeXml(absoluteSiteUrl(site, route))}</loc></url>`)
     .join("\n")}
 </urlset>
@@ -623,6 +829,7 @@ const assertSafeOutputDirectory = (path) => {
 const validateSite = (outputDirectory, site) => {
   for (const path of [
     "index.html",
+    "changelog/index.html",
     "assets/styles.css",
     "assets/client.js",
     "apple-touch-icon.png",

From c9a98286b9a82cb78f60a5de48939ffda826b3eb Mon Sep 17 00:00:00 2001
From: SandroMaglione <lass.maglio@gmail.com>
Date: Fri, 14 Aug 2026 06:24:56 +0200
Subject: [PATCH 2/2] Fix skipped example CI matrix

---
 .github/workflows/ci.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d018710..b0bb2f8 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -62,6 +62,7 @@ jobs:
 
   example:
     needs: discover-examples
+    if: needs.discover-examples.outputs.required == 'true'
     strategy:
       fail-fast: false
       matrix: