Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Let change notes carry a picture or clip for the changelog and release notes (#1043)

Nguyen Xuan Ana243d46d0443
diff --git a/changes/1043.md b/changes/1043.md
new file mode 100644
index 00000000..e6ba0f2a
--- /dev/null
+++ b/changes/1043.md
@@ -0,0 +1 @@
+- Change notes can carry a picture or clip with a `media: <url> <alt text>` line, shown on the site changelog and in the GitHub release notes (#1043)
diff --git a/changes/README.md b/changes/README.md
index e411f277..cf386c71 100644
--- a/changes/README.md
+++ b/changes/README.md
@@ -15,6 +15,8 @@ Other docs link here for the rule. Each note holds the changelog bullet exactly
Keep the bullet to one line a user can read in a few seconds: what they can do now, or what got better, and the issue number. Put the measurements, the method and the edge cases in the pull request and the docs, not here. Start a breaking change with `Breaking:`.
+A bullet may carry one picture or clip on the line below it: ` media: <url> <alt text>`. The URL is `https://` or a site path starting with `/`, and a `.mp4` or `.webm` plays as a muted loop. The site changelog shows it under the bullet, and `changes:fold` writes it into `CHANGELOG.md` as markdown (an image line, or a link line for a clip) so the GitHub release notes carry it too.
+
Do not edit `CHANGELOG.md` in a pull request. Two pull requests then never touch the same file, so GitHub has nothing to conflict on.
`npm run changes` prints the pending notes. At release time `npm run changes:fold` writes them into `CHANGELOG.md` as the section for the version in `package.json` and deletes the files. Then edit that section by hand before the release: merge bullets about the same feature, drop internal ones (benchmark scripts, CI, refactors with no visible effect), and sort the rest under `### Highlights`, `### Agents and MCP`, `### Rendering`, `### glTF`, `### Animation and physics`, `### Tools, docs and site` and `### Breaking changes`. The site shows each `###` heading, and every entry under `Breaking changes` gets the breaking mark.
diff --git a/scripts/changelog-fragments.mjs b/scripts/changelog-fragments.mjs
index f0fdd405..39075a1f 100644
--- a/scripts/changelog-fragments.mjs
+++ b/scripts/changelog-fragments.mjs
@@ -1,6 +1,7 @@
import { readdir, readFile, writeFile, rm } from 'node:fs/promises';
import { resolve } from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
+import { isAllowedMediaUrl, isVideoUrl } from '../src/changelog-media.js';
const root = fileURLToPath(new URL('..', import.meta.url));
const fragmentsFolder = resolve(root, 'changes');
@@ -41,6 +42,40 @@ function issueNumberOf(text, fallbackName) {
// "Breaking changes" is breaking.
const groupHeading = /^###\s+(.+?)\s*$/;
+// A note adds a picture or clip with a line "media: <url> <alt text>" under its bullet. CHANGELOG.md holds the same
+// thing as markdown ("![alt](url)", or "[alt](url)" for a video), so both forms are read back.
+const mediaLine = /^\s*media:\s+(\S+)(?:\s+(.*\S))?\s*$/;
+const markdownImageLine = /^\s*!\[([^\]]*)\]\((\S+)\)\s*$/;
+const markdownVideoLine = /^\s*\[([^\]]*)\]\((\S+)\)\s*$/;
+
+function mediaOfLine(line) {
+ const note = line.match(mediaLine);
+ if (note) return { url: note[1], alt: note[2] ?? '' };
+ const image = line.match(markdownImageLine);
+ if (image) return { url: image[2], alt: image[1] };
+ const video = line.match(markdownVideoLine);
+ if (video && isVideoUrl(video[2])) return { url: video[2], alt: video[1] };
+ return null;
+}
+
+function checkedMedia(media, line) {
+ if (!isAllowedMediaUrl(media.url)) {
+ throw new Error(`Media line "${line.trim()}" needs an https URL or a path that starts with "/". Write "media: https://example.com/clip.mp4 What the clip shows".`);
+ }
+ if (!media.alt) throw new Error(`Media line "${line.trim()}" needs alt text after the URL. Write "media: <url> What the picture shows".`);
+ return media;
+}
+
+// Turns "media:" lines into the markdown GitHub renders: an image, or a link for a video.
+export function mediaLinesToMarkdown(text) {
+ return text.split('\n').map((line) => {
+ const note = line.match(mediaLine);
+ if (!note) return line;
+ const media = checkedMedia({ url: note[1], alt: note[2] ?? '' }, line);
+ return isVideoUrl(media.url) ? ` [${media.alt}](${media.url})` : ` ![${media.alt}](${media.url})`;
+ }).join('\n');
+}
+
export function parseEntries(markdown, fallbackName) {
const entries = [];
let group = null;
@@ -50,14 +85,17 @@ export function parseEntries(markdown, fallbackName) {
group = heading[1];
} else if (line.startsWith('- ')) {
entries.push({ text: line.slice(2).trim(), group });
+ } else if (line.trim() && entries.length > 0 && mediaOfLine(line)) {
+ entries[entries.length - 1].media = checkedMedia(mediaOfLine(line), line);
} else if (line.trim() && entries.length > 0) {
entries[entries.length - 1].text += ` ${line.trim()}`;
}
}
- return entries.map(({ text, group: entryGroup }) => {
+ return entries.map(({ text, group: entryGroup, media }) => {
const breaking = breakingPattern.test(text) || breakingPattern.test(entryGroup ?? '');
const entry = { issue: issueNumberOf(text, fallbackName), text, breaking };
if (entryGroup) entry.group = entryGroup;
+ if (media) entry.media = media;
return entry;
});
}
@@ -95,12 +133,12 @@ export async function changelogWithUnreleased(changelogText, folder = fragmentsF
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 section = `## Unreleased\n\n${fragments.map((fragment) => mediaLinesToMarkdown(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.
+// Puts a version section above the newest one. Fragment text is copied as it is, except that media lines become markdown.
export function foldIntoChangelog(changelogText, version, fragments) {
const changelog = changelogText.replace(/\r\n/g, '\n');
if (!semver.test(version)) throw new Error(`Not a valid version: ${version}`);
@@ -108,7 +146,7 @@ export function foldIntoChangelog(changelogText, version, fragments) {
if (new RegExp(`^## ${version.replaceAll('.', '\\.')}$`, 'm').test(changelog)) {
throw new Error(`CHANGELOG.md already has a section for ${version}.`);
}
- const section = `## ${version}\n\n${fragments.map((fragment) => fragment.text).join('\n')}\n\n`;
+ const section = `## ${version}\n\n${fragments.map((fragment) => mediaLinesToMarkdown(fragment.text)).join('\n')}\n\n`;
const firstSection = changelog.search(/^## /m);
if (firstSection === -1) return `${changelog.replace(/\s+$/, '')}\n\n${section.trimEnd()}\n`;
return `${changelog.slice(0, firstSection)}${section}${changelog.slice(firstSection)}`;
diff --git a/src/changelog-media.js b/src/changelog-media.js
new file mode 100644
index 00000000..b7dea3a5
--- /dev/null
+++ b/src/changelog-media.js
@@ -0,0 +1,11 @@
+// Change notes may carry a picture or a clip. The site and the release notes decide how to show it from the file name.
+const videoPattern = /\.(?:mp4|webm)$/i;
+
+export function isVideoUrl(url) {
+ return videoPattern.test(url.split(/[?#]/)[0]);
+}
+
+// Only https URLs and site-relative paths ("/media/x.png") are allowed, so a note cannot pull in a script or a tracker over http.
+export function isAllowedMediaUrl(url) {
+ return /^https:\/\/\S+$/.test(url) || /^\/(?!\/)\S*$/.test(url);
+}
diff --git a/src/changelog.js b/src/changelog.js
index b8c42222..11ff8b45 100644
--- a/src/changelog.js
+++ b/src/changelog.js
@@ -1,5 +1,6 @@
import './home.js';
import './documentation.css';
+import { isVideoUrl } from './changelog-media.js';
const article = document.querySelector('#doc-article');
const versionList = document.querySelector('#doc-toc');
@@ -38,6 +39,28 @@ function appendText(parent, text) {
});
}
+// A clip plays like a GIF: muted, looping and inline. A picture loads when it scrolls near.
+function mediaElement(media) {
+ if (isVideoUrl(media.url)) {
+ const video = document.createElement('video');
+ video.className = 'change-media';
+ video.src = media.url;
+ video.muted = true;
+ video.loop = true;
+ video.autoplay = true;
+ video.playsInline = true;
+ video.setAttribute('aria-label', media.alt);
+ return video;
+ }
+ const image = document.createElement('img');
+ image.className = 'change-media';
+ image.src = media.url;
+ image.alt = media.alt;
+ image.loading = 'lazy';
+ image.decoding = 'async';
+ return image;
+}
+
function entryRow(entry) {
const row = document.createElement('li');
row.className = 'change-entry';
@@ -59,6 +82,7 @@ function entryRow(entry) {
// The issue column already links the number, so a trailing "(#N)" for the same issue is dropped.
const trailingIssue = entry.issue === null ? null : new RegExp(`\\s*\\(#${entry.issue}\\)$`);
appendText(text, trailingIssue ? entry.text.replace(trailingIssue, '') : entry.text);
+ if (entry.media) text.append(mediaElement(entry.media));
row.append(issue, text);
return row;
}
diff --git a/src/documentation.css b/src/documentation.css
index 2cccd2d1..5b50502f 100644
--- a/src/documentation.css
+++ b/src/documentation.css
@@ -80,6 +80,7 @@
.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-media { display:block; max-width:100%; height:auto; margin-top:10px; border-radius:10px; }
.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; }
diff --git a/tests/changelog-media-fold.test.js b/tests/changelog-media-fold.test.js
new file mode 100644
index 00000000..b52a9c5f
--- /dev/null
+++ b/tests/changelog-media-fold.test.js
@@ -0,0 +1,40 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { foldIntoChangelog, parseEntries } from '../scripts/changelog-fragments.mjs';
+import { releaseNotes } from '../scripts/release-notes.mjs';
+
+const changelog = '# Changelog\n\n## 0.14.0\n\n- Old note.\n';
+
+test('a media line is folded into CHANGELOG.md as a markdown image, or a link for a clip', () => {
+ const fragments = [
+ { name: 'a.md', text: '- A with a picture (#1)\n media: https://example.com/a.png The new cube' },
+ { name: 'b.md', text: '- B with a clip (#2)\nmedia: /media/b.mp4 The camera orbit' },
+ ];
+ const folded = foldIntoChangelog(changelog, '0.15.0', fragments);
+ assert.match(folded, /- A with a picture \(#1\)\n {2}!\[The new cube\]\(https:\/\/example\.com\/a\.png\)\n/);
+ assert.match(folded, /- B with a clip \(#2\)\n {2}\[The camera orbit\]\(\/media\/b\.mp4\)\n/);
+});
+
+test('folding rejects a media line with an http URL, a protocol-relative URL or no alt text', () => {
+ const fold = (line) => foldIntoChangelog(changelog, '0.15.0', [{ name: 'a.md', text: `- A.\n${line}` }]);
+ assert.throws(() => fold('media: http://example.com/a.png Alt'), /https URL or a path/);
+ assert.throws(() => fold('media: //example.com/a.png Alt'), /https URL or a path/);
+ assert.throws(() => fold('media: https://example.com/a.png'), /alt text/);
+});
+
+test('a media line becomes entry.media, in a fragment and in the folded changelog', () => {
+ const pending = parseEntries('- A (#1)\nmedia: /media/a.webm The orbit\n- B.', 'x.md');
+ assert.deepEqual(pending[0].media, { url: '/media/a.webm', alt: 'The orbit' });
+ assert.equal(pending[0].text, 'A (#1)');
+ assert.equal(pending[1].media, undefined);
+ const released = parseEntries('- A (#1)\n ![The cube](https://example.com/a.png)\n- B (#2)\n [The orbit](/media/b.mp4)\n- C.\n [not media](https://example.com/page)');
+ assert.deepEqual(released[0].media, { url: 'https://example.com/a.png', alt: 'The cube' });
+ assert.deepEqual(released[1].media, { url: '/media/b.mp4', alt: 'The orbit' });
+ assert.equal(released[2].media, undefined);
+ assert.match(released[2].text, /not media/);
+});
+
+test('release notes keep the media of a version section', () => {
+ const folded = foldIntoChangelog(changelog, '0.15.0', [{ name: 'a.md', text: '- A (#1)\nmedia: https://example.com/a.png The cube' }]);
+ assert.match(releaseNotes(folded, '0.15.0', 'pkg'), /!\[The cube\]\(https:\/\/example\.com\/a\.png\)/);
+});
diff --git a/tests/changelog-media.test.js b/tests/changelog-media.test.js
new file mode 100644
index 00000000..1d26ee82
--- /dev/null
+++ b/tests/changelog-media.test.js
@@ -0,0 +1,17 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { isAllowedMediaUrl, isVideoUrl } from '../src/changelog-media.js';
+
+test('clips are told from pictures by file name, ignoring a query string', () => {
+ assert.equal(isVideoUrl('/media/a.mp4'), true);
+ assert.equal(isVideoUrl('https://example.com/a.WEBM?x=1'), true);
+ assert.equal(isVideoUrl('/media/a.png'), false);
+});
+
+test('only https URLs and site paths are allowed as media', () => {
+ assert.equal(isAllowedMediaUrl('https://example.com/a.png'), true);
+ assert.equal(isAllowedMediaUrl('/media/a.png'), true);
+ for (const url of ['http://example.com/a.png', '//example.com/a.png', 'javascript:alert(1)', 'data:image/png;base64,AA']) {
+ assert.equal(isAllowedMediaUrl(url), false, url);
+ }
+});