Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Show unreleased changes on a changelog page and in /changelog.json (#482)

Nguyen Xuan An41fab61f0883
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 4c344079..9b73e800 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -32,3 +32,15 @@ jobs:
- run: npm run smoke:mcp-package -- --protocol-only
- name: Publish a new version through OIDC
run: npm run publish:ci
+
+ release:
+ needs: publish
+ runs-on: ubuntu-latest
+ permissions:
+ contents: write
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ - name: Create the tag and release page if they are missing
+ run: node scripts/release-publish-notes.mjs
+ env:
+ GH_TOKEN: ${{ github.token }}
diff --git a/.gitignore b/.gitignore
index 37eef5cf..5eff4bd9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,6 +5,7 @@ build/
public/releases/
public/release.json
public/changelog.md
+public/changelog.json
public/guide.md
public/gltf.md
public/gltf-morph.md
diff --git a/changelog.html b/changelog.html
new file mode 100644
index 00000000..e1de6fcc
--- /dev/null
+++ b/changelog.html
@@ -0,0 +1,27 @@
+<!doctype html>
+<html lang="en" data-theme="afterimage">
+<head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><meta name="description" content="Every change in 67js, including the ones not yet released."/><title>Changelog · 67js</title><link rel="icon" href="/favicon.svg"/></head>
+<body class="site documentation">
+<a class="skip-link" href="#content">Skip to content</a>
+<header class="navigation">
+ <a class="brand" href="/">67js</a>
+ <span class="version" data-release-version>Loading release</span>
+ <nav aria-label="Library"><a href="/docs.html">Docs</a><a href="/changelog.html" aria-current="page">Changelog</a></nav>
+ <a class="site-nav-cta" href="https://github.com/codepawl/67.js"><span class="package-logo package-logo-github" aria-hidden="true"></span>GitHub</a>
+</header>
+<main id="content" class="docs docs-page">
+ <aside class="docs-sidebar" aria-label="Changelog navigation">
+ <a class="docs-title" href="#unreleased">Changelog</a>
+ <details id="doc-topic-menu"><summary>Versions <span id="doc-topic-name"></span><span aria-hidden="true">⌄</span></summary><nav id="doc-toc" aria-label="Versions"></nav></details>
+ </aside>
+ <div class="docs-reading">
+ <article id="doc-article" class="changelog" tabindex="-1" aria-label="Changelog"></article>
+ <noscript><p>Read the <a href="/changelog.md">plain-text changelog</a> with JavaScript disabled.</p></noscript>
+ </div>
+</main>
+<footer class="site-footer" aria-label="Site footer">
+ <p><a class="brand" href="/" aria-label="67js home">67js</a> by <a href="https://codepawl.com">CodePawl</a></p>
+ <nav class="footer-links" aria-label="Project links"><a href="https://github.com/codepawl/67.js">GitHub</a><a href="https://www.npmjs.com/package/@codepawlhq/67js">npm</a><a href="/changelog.md">Plain text</a><a href="/changelog.json">JSON</a><a href="/license.txt">MIT license</a></nav>
+</footer>
+<script type="module" src="/src/changelog.js"></script>
+</body></html>
diff --git a/changes/482.md b/changes/482.md
new file mode 100644
index 00000000..7073745b
--- /dev/null
+++ b/changes/482.md
@@ -0,0 +1 @@
+- Show unreleased changes on the site (issue #482). The site build now writes `/changelog.json` (`{ version, released, unreleased }`, each entry with its issue number and a `breaking` flag) and puts an "Unreleased" section above the released ones in `/changelog.md`, both read from `changes/*.md` and `CHANGELOG.md`. A new `changelog.html` page shows them with a link to each issue and an icon on breaking entries, and `docs/mcp.md`, `docs/agent-scene.md` and the `build-67js-scene` skill point agents at the JSON. `.github/workflows/publish.yml` also creates the `v<version>` tag and a GitHub Release from that version's `CHANGELOG.md` section after `publish:ci`, and skips a release that already exists.
diff --git a/docs.html b/docs.html
index 05036f04..87e7c4a8 100644
--- a/docs.html
+++ b/docs.html
@@ -6,7 +6,7 @@
<header class="navigation">
<a class="brand" href="/">67js</a>
<span class="version" data-release-version>Loading release</span>
- <nav aria-label="Library"><a href="/docs.html" aria-current="page">Docs</a></nav>
+ <nav aria-label="Library"><a href="/docs.html" aria-current="page">Docs</a><a href="/changelog.html">Changelog</a></nav>
<a class="site-nav-cta" href="https://github.com/codepawl/67.js"><span class="package-logo package-logo-github" aria-hidden="true"></span>GitHub</a>
</header>
<main id="content" class="docs docs-page">
diff --git a/docs/agent-scene.md b/docs/agent-scene.md
index 9dfd4607..678a28ec 100644
--- a/docs/agent-scene.md
+++ b/docs/agent-scene.md
@@ -8,6 +8,8 @@ It does not execute JavaScript, access the DOM, or provide an MCP transport.
Recipes also retain [lighting, fog, effects and directional shadow coverage](agent-look.md).
Their patches and checkpoints share the same atomic revision contract as model edits.
+To see what changed, including changes not yet released, read `https://67js.codepawl.com/changelog.json`.
+
Release `0.7.0` adds optional [procedural motion](agent-motion.md) and transient `sampleMotion(time)` seeks.
Recipe edits retain authored keyframes. Sampling preserves revisions and geometry while updating rendered transforms, materials and camera.
diff --git a/docs/mcp.md b/docs/mcp.md
index 2250ff24..de4ea000 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -10,6 +10,8 @@ Release `0.7.0` adds [procedural motion](agent-motion.md), transient preview see
Release `0.8.0` adds [imported character motion](agent-character-motion.md) with source joints and independent clip timing.
Release `0.9.0` adds [visual review](agent-review.md) for several labeled views or poses from one isolated snapshot.
+To see what changed, including changes not yet released, read `https://67js.codepawl.com/changelog.json`: `released` sections, `unreleased` entries and each entry's issue number and `breaking` flag.
+
It renders one active scene and returns PNG images through MCP image content.
Tool results also contain JSON text and structured metadata.
The image bytes appear only in the image content block.
diff --git a/index.html b/index.html
index af632ec3..12dc21cb 100644
--- a/index.html
+++ b/index.html
@@ -23,7 +23,7 @@
<a class="brand" href="/" aria-label="67js home">67js</a>
<span class="version" data-release-version>Loading release</span>
<nav aria-label="Library">
- <a href="/docs.html">Docs</a>
+ <a href="/docs.html">Docs</a><a href="/changelog.html">Changelog</a>
</nav>
<a class="site-nav-cta" href="https://github.com/codepawl/67.js"><span class="package-logo package-logo-github" aria-hidden="true"></span>GitHub</a>
</header>
@@ -121,7 +121,7 @@ renderer.render({ eye: [58, 31, 84], target: [-8, 3, -18] });</code></pre>
</main>
<footer class="site-footer" aria-label="Site footer">
<p><a class="brand" href="/" aria-label="67js home">67js</a> by <a href="https://codepawl.com">CodePawl</a></p>
- <nav class="footer-links" aria-label="Project links"><a href="https://github.com/codepawl/67.js">GitHub</a><a href="https://www.npmjs.com/package/@codepawlhq/67js">npm</a><a data-release-commit href="https://github.com/codepawl/67.js">Release commit</a><a href="/changelog.md">Changelog</a><a href="/license.txt">MIT license</a><a href="/logo.svg" download>Logo SVG</a></nav>
+ <nav class="footer-links" aria-label="Project links"><a href="https://github.com/codepawl/67.js">GitHub</a><a href="https://www.npmjs.com/package/@codepawlhq/67js">npm</a><a data-release-commit href="https://github.com/codepawl/67.js">Release commit</a><a href="/changelog.html">Changelog</a><a href="/license.txt">MIT license</a><a href="/logo.svg" download>Logo SVG</a></nav>
</footer>
<script type="module" src="/src/home.js"></script>
<script type="module" src="/src/home-effects.js"></script>
diff --git a/modeling.html b/modeling.html
index 977ee983..507b3a90 100644
--- a/modeling.html
+++ b/modeling.html
@@ -11,7 +11,7 @@
<a class="skip-link" href="#content">Skip to content</a>
<header class="navigation">
<a class="brand" href="/" aria-label="67js home">67js</a>
- <nav aria-label="Library"><a href="/downloads.html">Downloads</a><a href="/docs.html">Docs</a></nav>
+ <nav aria-label="Library"><a href="/downloads.html">Downloads</a><a href="/docs.html">Docs</a><a href="/changelog.html">Changelog</a></nav>
</header>
<main id="content" class="modeling-study">
<div class="study-heading"><div><h1>Aster lantern</h1><p>A turned porcelain base, a spiral brass cage, and a little clockwork.</p></div><a href="/docs.html#parts">Modeling tools</a></div>
diff --git a/scripts/changelog-fragments.mjs b/scripts/changelog-fragments.mjs
index 83455574..2fc962d6 100644
--- a/scripts/changelog-fragments.mjs
+++ b/scripts/changelog-fragments.mjs
@@ -26,6 +26,64 @@ export async function readFragments(folder = fragmentsFolder) {
return fragments;
}
+// A changelog entry is a "- " bullet; a line that follows without a bullet continues it.
+// An entry is breaking when its text says "Breaking" with a capital B, as in "Breaking:" or "Breaking look change:".
+const breakingPattern = /\bBreaking\b/;
+
+function issueNumberOf(text, fallbackName) {
+ const inText = text.match(/#(\d+)/);
+ if (inText) return Number(inText[1]);
+ const inName = fallbackName?.match(/^(\d+)/);
+ return inName ? Number(inName[1]) : null;
+}
+
+export function parseEntries(markdown, fallbackName) {
+ const entries = [];
+ for (const line of markdown.replace(/\r\n/g, '\n').split('\n')) {
+ if (line.startsWith('- ')) entries.push(line.slice(2).trim());
+ else if (line.trim() && entries.length > 0) entries[entries.length - 1] += ` ${line.trim()}`;
+ }
+ return entries.map((text) => ({ issue: issueNumberOf(text, fallbackName), text, breaking: breakingPattern.test(text) }));
+}
+
+// Splits CHANGELOG.md into its "## <version>" sections, newest first as written.
+export function parseChangelogSections(changelogText) {
+ const sections = [];
+ const text = changelogText.replace(/\r\n/g, '\n');
+ const headings = [...text.matchAll(/^## (\S+)[ \t]*$/gm)];
+ headings.forEach((heading, index) => {
+ const end = index + 1 < headings.length ? headings[index + 1].index : text.length;
+ const body = text.slice(heading.index + heading[0].length, end);
+ sections.push({ version: heading[1], body: trimBlankLines(body) });
+ });
+ return sections;
+}
+
+// The markdown of one version's section, without its heading. Throws when the version is not in the changelog.
+export function extractVersionSection(changelogText, version) {
+ const section = parseChangelogSections(changelogText).find((candidate) => candidate.version === version);
+ if (!section) throw new Error(`CHANGELOG.md has no section for ${version}.`);
+ return section.body;
+}
+
+// Everything a reader or an agent needs: released sections from the changelog, pending entries from the fragments.
+export async function readChangelogData({ changelogText, version, folder = fragmentsFolder }) {
+ const fragments = await readFragments(folder);
+ const unreleased = fragments.flatMap((fragment) => parseEntries(fragment.text, fragment.name));
+ const released = parseChangelogSections(changelogText).map((section) => ({ version: section.version, entries: parseEntries(section.body) }));
+ return { version, released, unreleased };
+}
+
+// The changelog text with a "## Unreleased" section above the released ones, for the site's /changelog.md.
+export async function changelogWithUnreleased(changelogText, folder = fragmentsFolder) {
+ const fragments = await readFragments(folder);
+ if (fragments.length === 0) return changelogText;
+ const text = changelogText.replace(/\r\n/g, '\n');
+ const section = `## Unreleased\n\n${fragments.map((fragment) => fragment.text).join('\n')}\n\n`;
+ const firstSection = text.search(/^## /m);
+ return firstSection === -1 ? `${text.replace(/\s+$/, '')}\n\n${section.trimEnd()}\n` : `${text.slice(0, firstSection)}${section}${text.slice(firstSection)}`;
+}
+
// Puts a version section above the newest one. Fragment text is copied as it is.
export function foldIntoChangelog(changelogText, version, fragments) {
const changelog = changelogText.replace(/\r\n/g, '\n');
diff --git a/scripts/check-links.mjs b/scripts/check-links.mjs
index 159e9cae..5e085d61 100644
--- a/scripts/check-links.mjs
+++ b/scripts/check-links.mjs
@@ -11,7 +11,7 @@ import { dirname, join, relative, resolve } from 'node:path';
const skippedFolders = new Set(['node_modules', '.git', '.claude', 'build', 'dist', 'artifacts', 'coverage']);
const linkPattern = /(?:\]\(|href="|src=")([^)"#\s]+)/g;
// `release.json` is generated by `npm run prepare:release`. `./main.js` is an example path inside the guide.
-const knownGeneratedLinks = new Set(['/release.json', './main.js']);
+const knownGeneratedLinks = new Set(['/release.json', '/changelog.json', './main.js']);
const externalPattern = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i;
function collectFiles(folder, found) {
diff --git a/scripts/prepare-release.mjs b/scripts/prepare-release.mjs
index e2b06589..b7713c99 100644
--- a/scripts/prepare-release.mjs
+++ b/scripts/prepare-release.mjs
@@ -4,6 +4,7 @@ import { spawnSync } from 'node:child_process';
import { createHash } from 'node:crypto';
import { dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
+import { changelogWithUnreleased, readChangelogData } from './changelog-fragments.mjs';
const root = fileURLToPath(new URL('..', import.meta.url));
const metadata = JSON.parse(await readFile(resolve(root, 'package.json'), 'utf8'));
@@ -32,7 +33,11 @@ let integrity = `sha512-${createHash('sha512').update(archive).digest('base64')}
await cp(resolve(root, 'build'), resolve(releases, metadata.version), { recursive: true });
run(process.execPath, ['node_modules/vite/bin/vite.js', 'build', '--config', 'vite.browser.config.js']);
await copyFile(resolve(root, 'build-browser/67.module.js'), resolve(releases, metadata.version, '67.module.js'));
-await copyFile(resolve(root, 'CHANGELOG.md'), resolve(root, 'public/changelog.md'));
+// The site shows pending change notes above the released sections. Nothing here is kept by hand.
+const changelogText = await readFile(resolve(root, 'CHANGELOG.md'), 'utf8');
+await writeFile(resolve(root, 'public/changelog.md'), await changelogWithUnreleased(changelogText));
+await writeFile(resolve(root, 'public/changelog.json'), `${JSON.stringify(await readChangelogData({ changelogText, version: metadata.version }), null, 2)}
+`);
await copyFile(resolve(root, 'docs/guide.md'), resolve(root, 'public/guide.md'));
await copyFile(resolve(root, 'docs/gltf.md'), resolve(root, 'public/gltf.md'));
const sourceDocuments = [
@@ -90,6 +95,7 @@ const release = {
packageBytes: archive.length,
api: './docs.html#renderer-reference',
changelog: '/changelog.md',
+ changelogData: '/changelog.json',
};
await writeFile(resolve(root, 'public/release.json'), `${JSON.stringify(release, null, 2)}\n`);
console.log(`Prepared ${metadata.name}@${metadata.version}: ${packed.size} bytes, commit ${commit.slice(0, 8)}, registry published ${registryPublished}.`);
diff --git a/scripts/release-notes.mjs b/scripts/release-notes.mjs
new file mode 100644
index 00000000..5b3f365f
--- /dev/null
+++ b/scripts/release-notes.mjs
@@ -0,0 +1,29 @@
+// Prints the release notes for a version: its CHANGELOG.md section and the npm install line.
+// Usage: node scripts/release-notes.mjs [version] (defaults to the version in package.json)
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { extractVersionSection } from './changelog-fragments.mjs';
+
+const root = fileURLToPath(new URL('..', import.meta.url));
+
+export function releaseNotes(changelogText, version, packageName) {
+ const section = extractVersionSection(changelogText, version);
+ return `${section}\n\nInstall: \`npm install ${packageName}@${version}\`\n`;
+}
+
+async function main() {
+ const metadata = JSON.parse(await readFile(resolve(root, 'package.json'), 'utf8'));
+ const version = process.argv[2] ?? metadata.version;
+ const changelogText = await readFile(resolve(root, 'CHANGELOG.md'), 'utf8');
+ process.stdout.write(releaseNotes(changelogText, version, metadata.name));
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+ try {
+ await main();
+ } catch (error) {
+ console.error(error.message);
+ process.exit(1);
+ }
+}
diff --git a/scripts/release-publish-notes.mjs b/scripts/release-publish-notes.mjs
new file mode 100644
index 00000000..d3395c6f
--- /dev/null
+++ b/scripts/release-publish-notes.mjs
@@ -0,0 +1,26 @@
+// Creates the v<version> tag and release page after npm publish. Skips quietly when the release already exists.
+// Needs the `gh` CLI and GH_TOKEN with contents: write, and runs only in Actions (GITHUB_SHA is the pushed commit).
+import { readFile, writeFile, mkdtemp } from 'node:fs/promises';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { releaseNotes } from './release-notes.mjs';
+
+const metadata = JSON.parse(await readFile('package.json', 'utf8'));
+const tag = `v${metadata.version}`;
+const commit = process.env.GITHUB_SHA;
+if (!commit) throw new Error('Run this step from GitHub Actions: GITHUB_SHA is not set.');
+
+function releaseExists() {
+ return spawnSync('gh', ['release', 'view', tag], { encoding: 'utf8' }).status === 0;
+}
+
+if (releaseExists()) {
+ console.log(`Release ${tag} already exists.`);
+} else {
+ const notesFile = join(await mkdtemp(join(tmpdir(), 'release-notes-')), 'notes.md');
+ await writeFile(notesFile, releaseNotes(await readFile('CHANGELOG.md', 'utf8'), metadata.version, metadata.name));
+ const created = spawnSync('gh', ['release', 'create', tag, '--target', commit, '--title', `67js ${metadata.version}`, '--notes-file', notesFile], { stdio: 'inherit' });
+ // A run that lost a race to create the same release is not a failed publish.
+ if (created.status !== 0 && !releaseExists()) throw new Error(`gh release create failed with exit code ${created.status}.`);
+}
diff --git a/showcase.html b/showcase.html
index 0960c568..8a7ee464 100644
--- a/showcase.html
+++ b/showcase.html
@@ -13,7 +13,7 @@
<header class="navigation">
<a class="brand" href="/" aria-label="67js home">67js</a>
<nav aria-label="Library">
- <a href="/docs.html">Docs</a>
+ <a href="/docs.html">Docs</a><a href="/changelog.html">Changelog</a>
</nav>
<a class="site-nav-cta" href="https://github.com/codepawl/67.js"><span class="package-logo package-logo-github" aria-hidden="true"></span>GitHub</a>
</header>
diff --git a/skills/build-67js-scene/SKILL.md b/skills/build-67js-scene/SKILL.md
index d1a41a81..eabfdca8 100644
--- a/skills/build-67js-scene/SKILL.md
+++ b/skills/build-67js-scene/SKILL.md
@@ -81,4 +81,5 @@ Do not claim Blender parity or general Three.js speed superiority from one scene
## Finish
Deliver the scene link, a rendered image, relevant checks and known limits.
+To see what changed, including unreleased changes and breaking ones, read `https://67js.codepawl.com/changelog.json`.
Keep this skill aligned with the checked-out renderer API when changing that API.
diff --git a/src/changelog.js b/src/changelog.js
new file mode 100644
index 00000000..7951b441
--- /dev/null
+++ b/src/changelog.js
@@ -0,0 +1,102 @@
+import './home.js';
+import './documentation.css';
+
+const article = document.querySelector('#doc-article');
+const versionList = document.querySelector('#doc-toc');
+const topicMenu = document.querySelector('#doc-topic-menu');
+const desktopTopics = matchMedia('(min-width: 1051px)');
+const issueBase = 'https://github.com/codepawl/67.js/issues/';
+topicMenu.open = desktopTopics.matches;
+desktopTopics.addEventListener('change', () => { topicMenu.open = desktopTopics.matches; });
+
+const svgNamespace = 'http://www.w3.org/2000/svg';
+
+function breakingIcon() {
+ const icon = document.createElementNS(svgNamespace, 'svg');
+ icon.setAttribute('class', 'icon change-breaking-icon');
+ icon.setAttribute('viewBox', '0 0 24 24');
+ icon.setAttribute('fill', 'none');
+ icon.setAttribute('stroke', 'currentColor');
+ icon.setAttribute('stroke-width', '2');
+ icon.setAttribute('stroke-linecap', 'round');
+ icon.setAttribute('stroke-linejoin', 'round');
+ icon.setAttribute('aria-hidden', 'true');
+ icon.innerHTML = '<path d="M10.3 3.9 2.4 18a2 2 0 0 0 1.7 3h15.8a2 2 0 0 0 1.7-3L13.7 3.9a2 2 0 0 0-3.4 0Z"/><path d="M12 9v4M12 17h.01"/>';
+ return icon;
+}
+
+// Entry text uses `code` spans. Build nodes instead of HTML so the text can never inject markup.
+function appendText(parent, text) {
+ text.split('`').forEach((piece, index) => {
+ if (index % 2 === 1) {
+ const code = document.createElement('code');
+ code.textContent = piece;
+ parent.append(code);
+ } else {
+ parent.append(piece);
+ }
+ });
+}
+
+function entryRow(entry) {
+ const row = document.createElement('li');
+ row.className = 'change-entry';
+ const issue = document.createElement('span');
+ issue.className = 'change-issue';
+ if (entry.issue !== null) {
+ const link = document.createElement('a');
+ link.href = `${issueBase}${entry.issue}`;
+ link.textContent = `#${entry.issue}`;
+ issue.append(link);
+ }
+ const text = document.createElement('p');
+ if (entry.breaking) {
+ const label = document.createElement('span');
+ label.className = 'change-breaking';
+ label.append(breakingIcon(), 'Breaking');
+ text.append(label);
+ }
+ appendText(text, entry.text);
+ row.append(issue, text);
+ return row;
+}
+
+function versionSection(id, title, entries) {
+ const section = document.createElement('section');
+ section.id = id;
+ const heading = document.createElement('h2');
+ heading.textContent = title;
+ const list = document.createElement('ul');
+ list.className = 'change-list';
+ list.append(...entries.map(entryRow));
+ section.append(heading, list);
+ return section;
+}
+
+function render(data) {
+ const sections = [];
+ if (data.unreleased.length > 0) sections.push({ id: 'unreleased', title: 'Unreleased', entries: data.unreleased });
+ for (const release of data.released) sections.push({ id: `v${release.version}`, title: release.version, entries: release.entries });
+ const title = document.createElement('h1');
+ title.textContent = 'Changelog';
+ article.replaceChildren(title, ...sections.map((section) => versionSection(section.id, section.title, section.entries)));
+ versionList.replaceChildren(...sections.map((section) => {
+ const link = document.createElement('a');
+ link.href = `#${section.id}`;
+ link.textContent = section.title;
+ return link;
+ }));
+ document.querySelector('#doc-topic-name').textContent = sections[0]?.title ?? '';
+ if (location.hash) document.getElementById(location.hash.slice(1))?.scrollIntoView();
+}
+
+try {
+ const response = await fetch('/changelog.json');
+ if (!response.ok) throw new Error(`HTTP ${response.status}`);
+ render(await response.json());
+} catch {
+ const fallback = document.createElement('a');
+ fallback.href = '/changelog.md';
+ fallback.textContent = 'plain-text changelog';
+ article.replaceChildren('The changelog could not be loaded. Read the ', fallback, ' instead.');
+}
diff --git a/src/documentation.css b/src/documentation.css
index 7cdf5ed0..5f7097e8 100644
--- a/src/documentation.css
+++ b/src/documentation.css
@@ -71,3 +71,16 @@
.documentation .doc-pagination { gap:12px; }
.documentation .doc-pagination a { padding:13px; }
}
+
+/* Changelog page: one row per change, the issue number beside the text, spacing instead of dividers. */
+.documentation #doc-article.changelog h2 { font-size:22px; font-weight:600; letter-spacing:-.4px; margin:44px 0 14px; scroll-margin-top:calc(var(--navigation-height,80px) + 24px); }
+.change-list { list-style:none; margin:0; padding:0; }
+.documentation #doc-article .change-entry { display:grid; grid-template-columns:4.5em minmax(0,1fr); column-gap:12px; margin:0; padding:9px 0; }
+.change-issue { font:13px/1.8 ui-monospace,Consolas,monospace; }
+.documentation #doc-article .change-entry p { margin:0; font-size:14px; overflow-wrap:anywhere; }
+.change-breaking { display:inline-flex; align-items:center; vertical-align:-3px; gap:5px; margin-right:9px; font-weight:600; }
+.change-breaking-icon { flex:none; }
+.change-breaking-icon { width:16px; height:16px; }
+@media (max-width:760px) {
+ .documentation #doc-article .change-entry { grid-template-columns:minmax(0,1fr); row-gap:2px; padding:11px 0; }
+}
diff --git a/tests/changelog-data.test.js b/tests/changelog-data.test.js
new file mode 100644
index 00000000..323fff23
--- /dev/null
+++ b/tests/changelog-data.test.js
@@ -0,0 +1,80 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { changelogWithUnreleased, extractVersionSection, readChangelogData } from '../scripts/changelog-fragments.mjs';
+import { releaseNotes } from '../scripts/release-notes.mjs';
+
+const changelog = [
+ '# Changelog',
+ '',
+ '## 0.15.0',
+ '',
+ '- Add a thing (issue #10).',
+ '',
+ '- Breaking: a renderer no longer draws X (issue #11),',
+ ' and the next line continues the entry.',
+ '',
+ '## 0.14.0',
+ '',
+ '- Fix a seek that works without breaking playback (part of #9).',
+ '',
+].join('\n');
+
+async function withFragments(files, check) {
+ const folder = await mkdtemp(join(tmpdir(), 'changelog-data-'));
+ try {
+ for (const [name, text] of Object.entries(files)) await writeFile(join(folder, name), text);
+ await check(folder);
+ } finally {
+ await rm(folder, { recursive: true, force: true });
+ }
+}
+
+const fragmentFiles = {
+ '20.md': '- Add a page for changes (issue #20).\n',
+ '21-look.md': '- Breaking look change: the floor is darker.\n',
+ '21-look.size.md': '- entry:core: size note that must be skipped',
+ '300.md': '- Fix a thing with `code` in it.\n',
+};
+
+test('the changelog data holds released sections and pending fragments with issue and breaking flags', async () => {
+ await withFragments(fragmentFiles, async (folder) => {
+ const data = await readChangelogData({ changelogText: changelog, version: '0.15.0', folder });
+ assert.equal(data.version, '0.15.0');
+ assert.deepEqual(data.unreleased, [
+ { issue: 20, text: 'Add a page for changes (issue #20).', breaking: false },
+ { issue: 21, text: 'Breaking look change: the floor is darker.', breaking: true },
+ { issue: 300, text: 'Fix a thing with `code` in it.', breaking: false },
+ ]);
+ assert.deepEqual(data.released.map((release) => release.version), ['0.15.0', '0.14.0']);
+ assert.deepEqual(data.released[0].entries.map((entry) => [entry.issue, entry.breaking]), [[10, false], [11, true]]);
+ assert.match(data.released[0].entries[1].text, /next line continues the entry\.$/);
+ assert.equal(data.released[1].entries[0].breaking, false, 'the lowercase word "breaking" is not a marker');
+ });
+});
+
+test('the site changelog gets an Unreleased section above the released ones', async () => {
+ await withFragments(fragmentFiles, async (folder) => {
+ const text = await changelogWithUnreleased(changelog, folder);
+ assert.ok(text.indexOf('## Unreleased') < text.indexOf('## 0.15.0'));
+ assert.ok(text.startsWith('# Changelog\n\n## Unreleased\n\n- Add a page for changes'));
+ });
+ await withFragments({}, async (folder) => {
+ assert.equal(await changelogWithUnreleased(changelog, folder), changelog);
+ });
+});
+
+test('release notes are one version section with its breaking marker and the install line', () => {
+ const notes = releaseNotes(changelog, '0.15.0', '@codepawlhq/67js');
+ assert.match(notes, /^- Add a thing \(issue #10\)\./);
+ assert.match(notes, /Breaking: a renderer no longer draws X/);
+ assert.doesNotMatch(notes, /0\.14\.0|playback/);
+ assert.match(notes, /npm install @codepawlhq\/67js@0\.15\.0`\n$/);
+ assert.equal(extractVersionSection(changelog, '0.14.0'), '- Fix a seek that works without breaking playback (part of #9).');
+});
+
+test('release notes fail clearly when the version is not in the changelog', () => {
+ assert.throws(() => releaseNotes(changelog, '9.9.9', '@codepawlhq/67js'), /CHANGELOG\.md has no section for 9\.9\.9\./);
+});
diff --git a/vite.config.js b/vite.config.js
index 1b856338..5114f715 100644
--- a/vite.config.js
+++ b/vite.config.js
@@ -29,6 +29,7 @@ export default defineConfig({
assets: 'assets.html',
guide: 'getting-started.html',
docs: 'docs.html',
+ changelog: 'changelog.html',
showcase: 'showcase.html',
},
},