edgepress 2026.10.1 → 2026.10.13

package/tools/assets/sync-icons.mjs

@@ -0,0 +1,17 @@
+import { readFile, copyFile, mkdir, readdir, unlink } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+
+const root = fileURLToPath(new URL('../../',import.meta.url));
+const output = resolve(root,'content/assets/edgepress/icons');
+const library = resolve(root,'node_modules/lucide-static');
+const source = await readFile(resolve(root,'src/icons.js'),'utf8');
+const names = [...source.slice(source.indexOf('new Set(['),source.indexOf(']);')).matchAll(/'([a-z0-9-]+)'/g)].map(match=>match[1]);
+const mappings = {github:'code-xml'};
+await mkdir(output,{recursive:true});
+for(const name of names) await copyFile(resolve(library,'icons',(mappings[name]||name)+'.svg'),resolve(output,name+'.svg'));
+await copyFile(resolve(library,'LICENSE'),resolve(output,'LICENSE.txt'));
+const {version} = JSON.parse(await readFile(resolve(library,'package.json'),'utf8'));
+await import('node:fs/promises').then(({writeFile}) => writeFile(resolve(output,'provenance.json'),JSON.stringify({library:'lucide-static',version,source:'https://github.com/lucide-icons/lucide',mappings},null,2)+'\n'));
+for(const filename of await readdir(output)) if(filename.endsWith('.png')) await unlink(resolve(output,filename));
+console.log('Copied '+names.length+' Lucide icons at '+version);

package/tools/assets/video-preview.mjs

@@ -0,0 +1,15 @@
+import {execFile} from 'node:child_process';
+import {promisify} from 'node:util';
+import {writeFile} from 'node:fs/promises';
+import {basename, resolve} from 'node:path';
+const run = promisify(execFile);
+const file = process.argv[2];
+if (!file || !/\.(?:mp4|webm|ogv|ogg)$/i.test(file)) throw new Error('Usage: node tools/assets/video-preview.mjs path/to/video.mp4 [frame-seconds] (requires FFmpeg)');
+const video = resolve(file), poster = video + '.poster.jpg';
+const {stdout} = await run('ffprobe', ['-v','error','-select_streams','v:0','-show_entries','format=duration:stream=width,height','-of','json',video]);
+const info = JSON.parse(stdout), duration = Number(info.format.duration), {width, height} = info.streams[0];
+const time = Number(process.argv[3] ?? Math.min(1, duration / 2));
+if (!(Number.isFinite(time) && time >= 0 && time < duration)) throw new Error('Preview time must be inside the video');
+await run('ffmpeg', ['-v','error','-y','-ss',String(time),'-i',video,'-frames:v','1','-vf','scale=min(960\\,iw):-2','-q:v','3',poster]);
+await writeFile(video + '.json', JSON.stringify({duration, width, height, poster: basename(poster)}, null, 2) + '\n');
+console.log('Created ' + basename(poster) + ' and ' + basename(video) + '.json');

package/tools/recordings/capture-document-demo.mjs

@@ -0,0 +1,147 @@
+import assert from 'node:assert/strict';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { resolve, extname } from 'node:path';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { chromium } from 'playwright';
+import { recordingContext, record, closeRecording, preparePage } from './desktop-recording.mjs';
+import { pointAt, pointAtPosition, drag } from './vm-desktop.mjs';
+
+const workspace = resolve(import.meta.dirname, '../../..');
+const site = resolve(workspace, 'web/js.gripe');
+const documents = resolve(process.env.DOCUMENT_DEMO_ROOT || resolve(site, 'content/assets/documents/doc-views'));
+const require = createRequire(resolve(site, 'package.json'));
+const engine = createRequire(require.resolve('edgepress/package.json'));
+const { loadConfig } = await import(pathToFileURL(engine.resolve('edgepress/src/config.js')));
+const { loadLanguagePacks } = await import(pathToFileURL(engine.resolve('edgepress/src/i18n.js')));
+const { collectAssets, rewriteAssetLinks } = await import(pathToFileURL(engine.resolve('edgepress/src/assets.js')));
+const { createExtensions } = await import(pathToFileURL(engine.resolve('edgepress/src/plugin-api.js')));
+const { renderBlocks } = await import(pathToFileURL(engine.resolve('edgepress/src/page-blocks.js')));
+const { renderLayout } = await import(pathToFileURL(engine.resolve('edgepress/src/theme.js')));
+const names = ['sample-document-medium.docx', 'sample-document-medium.doc', 'sample-document-5-pages.pdf', 'sample-document.ppt', 'sample-presentation-10-slides.pptx', 'sample-spreadsheet-100-rows.xlsx', 'sample-spreadsheet-100-rows.xls'];
+const files = new Map(await Promise.all(names.map(async name => [name, await readFile(resolve(documents, name))])));
+const config = await loadConfig(site);
+await loadLanguagePacks(config);
+const bundle = await collectAssets(config, { documentViewer: true });
+const extensions = await createExtensions(config);
+const assets = new Map(bundle.assets.map(asset => ['/' + asset.path, asset]));
+const artifact = resolve(workspace, 'edgepress/tools/.recordings');
+const output = resolve(site, 'content/assets/images/previews');
+await mkdir(output, { recursive: true });
+const browser = await chromium.connectOverCDP('http://127.0.0.1:9222');
+const pause = milliseconds => new Promise(done => setTimeout(done, milliseconds));
+const frameTargetBox = (element, selector) => element.evaluate((frame, selector) => {
+  const outer = frame.getBoundingClientRect();
+  const inner = frame.contentDocument.querySelector(selector).getBoundingClientRect();
+  return { x: outer.x + frame.clientLeft + inner.x, y: outer.y + frame.clientTop + inner.y, width: inner.width, height: inner.height };
+}, selector);
+const entries = [];
+try {
+  for (const locale of (process.env.RECORDING_LOCALES || 'en,zh-SG,zh-TW').split(',')) {
+    const rows = [...files.keys()].map(name => ({ columns: 1, cells: [[{ type: 'document', title: name, src: '/documents/doc-views/' + name }]] }));
+    const body = '<h1>doc-views</h1>' + await renderBlocks(rows, { config, locale });
+    const html = rewriteAssetLinks(await renderLayout(config, extensions, { title: 'doc-views', locale, urlPath: '/document-demo/' }, body), bundle.urlMap);
+    const context = await recordingContext(browser, { locale }, artifact);
+    const page = await context.newPage();
+    const errors = [];
+    page.on('pageerror', error => errors.push(error.message));
+    page.on('download', () => errors.push('Unexpected download'));
+    await context.route('**/*', async route => {
+      const url = new URL(route.request().url());
+      assert.equal(url.origin, new URL(config.site.url).origin);
+      if (url.pathname === '/document-demo/') return route.fulfill({ contentType: 'text/html', body: html });
+      if (url.pathname.startsWith('/documents/doc-views/')) return route.fulfill({ contentType: 'application/octet-stream', body: files.get(url.pathname.split('/').pop()) });
+      const asset = assets.get(url.pathname);
+      if (!asset) return route.fulfill({ status: 404, body: '' });
+      const types = { '.js': 'text/javascript', '.mjs': 'text/javascript', '.css': 'text/css', '.woff2': 'font/woff2', '.svg': 'image/svg+xml' };
+      return route.fulfill({ contentType: types[extname(url.pathname)] || 'application/octet-stream', body: asset.content || await readFile(asset.source) });
+    });
+    await preparePage(page);
+    await page.goto(config.site.url + '/document-demo/');
+    await page.locator('.privacy-reject').click();
+    const first = page.locator('.document-block').first();
+    await first.frameLocator('iframe').getByText('Sample Business Document', { exact: true }).waitFor();
+    const bullet = await first.frameLocator('iframe').getByText('Realistic structure: headings, lists, tables, and images', { exact: true }).first().evaluate(element => getComputedStyle(element.closest('p'), '::before').content);
+    assert.ok(bullet.includes('\u2022'), 'The recorded Word list must render its Unicode bullet without a proprietary font');
+    await first.scrollIntoViewIfNeeded();
+    await record(page, 'doc-views-' + locale.toLowerCase(), async () => {
+      await pause(2500);
+      const expand = first.locator('.document-viewer-expand');
+      await pointAt(page, expand); await expand.click(); await pause(1800);
+      await pointAt(page, expand); await expand.click(); await pause(600);
+      const zoom = first.getByRole('button', { name: locale === 'en' ? 'Zoom in' : '放大', exact: true });
+      await pointAt(page, zoom); await zoom.click(); await pause(1000);
+      await first.getByRole('button', { name: locale === 'en' ? 'Fit width' : locale === 'zh-SG' ? '适合宽度' : '符合寬度', exact: true }).click(); await pause(600);
+      await pointAt(page, first.locator('.document-viewer button').nth(1));
+      await first.locator('.document-viewer button').nth(1).click();
+      for (const index of [1, 2, 3, 4, 5, 6]) {
+        const block = page.locator('.document-block').nth(index);
+        await block.locator('iframe').waitFor();
+        const frame = block.frameLocator('iframe');
+        if (index === 1) await frame.locator('body').filter({ hasText: 'Sample Business Document' }).waitFor();
+        if (index === 2) {
+          await frame.getByText('Sample Business Document', { exact: true }).waitFor();
+          const painted = await frame.locator('.pdf-page img').first().evaluate(image => {
+            const canvas = document.createElement('canvas');
+            canvas.width = image.naturalWidth;
+            canvas.height = image.naturalHeight;
+            canvas.getContext('2d').drawImage(image, 0, 0);
+            const pixels = canvas.getContext('2d').getImageData(0, 0, canvas.width, canvas.height).data;
+            let ink = 0;
+            for (let offset = 0; offset < pixels.length; offset += 4) if (pixels[offset] < 128 && pixels[offset + 3]) ink++;
+            return { ink, width: canvas.width, height: canvas.height };
+          });
+          console.log('PDF canvas: ' + JSON.stringify(painted));
+          assert.ok(painted.ink > 100, 'The recorded PDF must paint visible content');
+        }
+        if ([3, 4].includes(index)) await frame.getByText('Sample Presentation', { exact: true }).waitFor();
+        if ([5, 6].includes(index)) await frame.getByText('Order ID', { exact: true }).waitFor();
+        await block.scrollIntoViewIfNeeded(); await pause(2200);
+        if (index === 2) {
+          for (let number = 2; number <= 8; number++) {
+            const section = frame.locator('[data-document-page="' + number + '"]');
+            await section.scrollIntoViewIfNeeded();
+            await section.locator('.pdf-page[aria-busy="false"] img').waitFor();
+            await pause(1600);
+          }
+        }
+        if (index === 3) {
+          const title = frame.locator('foreignObject').getByText('Sample Presentation', { exact: true });
+          assert.ok(await title.evaluate(element => element.getBoundingClientRect().height > 16), 'PPT title must be visibly readable');
+          await frame.locator('[data-document-page="2"]').scrollIntoViewIfNeeded();
+          await frame.getByText('Agenda', { exact: true }).waitFor();
+          assert.equal((await frame.locator('body').textContent()).includes('\uf0b7'), false, 'The recorded PPT bullets must not depend on a proprietary Symbol font');
+          await pause(2200);
+        }
+        if (index === 5) {
+          const address = block.locator('.document-viewer-formula input');
+          await pointAt(page, address); await address.fill('A90'); await address.press('Enter');
+          const cell = frame.locator('[data-row="89"][data-column="0"]');
+          await cell.waitFor();
+          const cellBox = await frameTargetBox(block.locator('iframe'), '[data-row="89"][data-column="0"]');
+          const cellPoint = { x: cellBox.x + cellBox.width / 2, y: cellBox.y + cellBox.height / 2 };
+          await pointAtPosition(page, cellPoint); await page.mouse.click(cellPoint.x, cellPoint.y); await pause(1800);
+          const summary = block.getByRole('tab', { name: 'Summary', exact: true });
+          await pointAt(page, summary); await summary.click(); await frame.getByText('595500', { exact: true }).waitFor(); await pause(2200);
+          const grip = frame.locator('[data-resize-column="0"]').first();
+          const width = Number(await grip.getAttribute('aria-valuenow'));
+          const position = await frameTargetBox(block.locator('iframe'), '[data-resize-column="0"]');
+          const from = { x: position.x + position.width / 2, y: position.y + position.height / 2 };
+          await pointAtPosition(page, from);
+          await drag(page, { from, to: { x: from.x + 100, y: from.y } });
+          assert.equal(Number(await grip.getAttribute('aria-valuenow')), width + 100);
+          await pause(1600);
+          const stretch = block.getByRole('button', { name: locale === 'en' ? 'Fill viewport' : locale === 'zh-SG' ? '铺满视口' : '填滿視口', exact: true });
+          await pointAt(page, stretch); await stretch.click(); await pause(1600);
+          const reset = block.getByRole('button', { name: locale === 'en' ? 'Restore column widths' : locale === 'zh-SG' ? '恢复原列宽' : '還原原欄寬', exact: true });
+          await pointAt(page, reset); await reset.click(); await pause(1000);
+        }
+        const close = block.locator('.document-viewer button').nth(1);
+        await pointAt(page, close); await close.click(); await pause(400);
+      }
+    });
+    assert.deepEqual(errors, []);
+    entries.push(...(await closeRecording(context, { artifact, output })).map(entry => ({ ...entry, kind: 'FFmpeg recording of actual Chromium in an isolated WSL2 desktop; automatically opened operator-supplied Office and eight-page PDF samples; no original-download links', source: 'edgepress/tools/recordings/capture-document-demo.mjs' })));
+  }
+} finally { await browser.close(); }
+await writeFile(resolve(artifact, 'document-demo.json'), JSON.stringify(entries, null, 2) + '\n');

package/tools/recordings/demo-workbench.mjs

@@ -0,0 +1,57 @@
+// Recording-only workbench. Commands execute the real standalone EdgePress CLI;
+// Geany edits the actual generated file. Nothing is installed into production.
+import assert from 'node:assert/strict';
+import {readFile,writeFile,mkdir,rm,cp} from 'node:fs/promises';
+import {resolve,sep,extname} from 'node:path';
+import {spawn} from 'node:child_process';
+import {pathToFileURL} from 'node:url';
+import {guest,guestPath,typeCommand,editFile,openApp,activate} from './vm-desktop.mjs';
+import {parse,stringify} from 'yaml';
+
+export async function workbench({artifact,packageRoot,photoPath,locale,context,embedding=false}){
+ const upstream=resolve(packageRoot),root=resolve(artifact,(embedding?'embedding-example-':'edgepress-example-')+locale);
+ assert.ok(root.startsWith(resolve(artifact)+sep));await rm(root,{recursive:true,force:true});await mkdir(root,{recursive:true});
+ const cli=resolve(upstream,'src/cli.js');
+ async function run(args){return new Promise((done,reject)=>{const child=spawn(process.execPath,[cli,...args],{cwd:root,windowsHide:true,env:{...process.env,WRANGLER_SEND_METRICS:'false'}});let output='';child.stdout.on('data',value=>output+=value);child.stderr.on('data',value=>output+=value);child.once('error',reject);child.once('exit',code=>code===0?done(output):reject(Error(output)));});}
+ await run(['init']);
+ const chinese=locale!=='en',title=embedding?(chinese?'散步中的瞬间':'Photos from our walk'):(chinese?'海边的下午':'An afternoon by the water');
+ const settings=parse(await readFile(resolve(root,'config.yml'),'utf8'));settings.site.title=chinese?'我的写作空间':'My writing space';settings.site.description=chinese?'用文字和照片记录生活。':'Stories and photographs from everyday life.';settings.site.navigation=settings.site.navigation.filter(item=>['home','posts','search'].includes(item.key));settings.site.footerNavigation=[];settings.plugins.consent.services=[];await writeFile(resolve(root,'config.yml'),stringify(settings));
+ await writeFile(resolve(root,'edgepress.config.mjs'),'export default '+JSON.stringify({paths:{content:'content',static:'static',theme:'themes/default',output:'dist',cache:'.recording-cache'},permalink:'/:year/:month/:slug/',i18n:{defaultLocale:locale,languagePacks:[chinese?'en':'zh-CN']},plugins:['plugins/consent/index.js']})+';\n');
+ if(chinese){await cp(resolve(root,'languages/packs/zh-CN.json'),resolve(root,'languages/base/zh-CN.json'));await cp(resolve(root,'languages/base/en.json'),resolve(root,'languages/packs/en.json'));}
+ // Use a small, real writing site so the recording starts at its article list.
+ await rm(resolve(root,'content/posts'),{recursive:true,force:true});await mkdir(resolve(root,'content/posts'),{recursive:true});
+ await rm(resolve(root,'content/pages'),{recursive:true,force:true});await mkdir(resolve(root,'content/pages/home'),{recursive:true});
+ await writeFile(resolve(root,'content/pages/home',locale.toLowerCase()+'.json'),JSON.stringify({title:settings.site.title,lang:locale,slug:'home',homepage:true,blocks:[{columns:1,cells:[[{type:'hero',eyebrow:chinese?'生活里的小事':'Notes from everyday life',title:settings.site.title,text:settings.site.description}]]},{columns:1,cells:[[{type:'post-list',title:chinese?'最近的文章':'Recent stories',category:'uncategorized',count:3}]]}]},null,2)+'\n');
+ if(embedding){settings.plugins.consent.services=[{id:'ishare',provider:'oembed',backendUrl:'https://ishare.js.gripe',enabled:true,name:chinese?'爱分享':'ishare',purpose:chinese?'在你同意后显示作者分享的图片与视频。':'Show the author’s shared photos and videos after you agree.',dataCategories:chinese?'请求的媒体和 IP 地址。':'Requested media and IP address.',recipient:'ishare',retention:chinese?'直到发布者删除。':'Until the publisher deletes it.',privacyUrl:'https://ishare.js.gripe/privacy/'}];await writeFile(resolve(root,'config.yml'),stringify(settings));}
+ await mkdir(resolve(root,'content/assets/photos'),{recursive:true});await cp(photoPath,resolve(root,'content/assets/photos/seaside.jpg'));
+ let file=null,port;
+ const terminalTitle='EdgePress '+locale;
+ const {loadConfig}=await import(pathToFileURL(resolve(upstream,'src/config.js')));const {readDocuments}=await import(pathToFileURL(resolve(upstream,'src/content.js')));
+ const rc=resolve(root,'.recording-bashrc');
+ const shellRoot="'"+guestPath(root).replaceAll("'","'\\''")+"'";
+ await writeFile(rc,'export PATH=/opt/recording/node_modules/.bin:/usr/local/bin:/usr/bin:/bin\ncd -- '+shellRoot+'\nexport WRANGLER_SEND_METRICS=false\nexport PS1="❯ "\n');
+ await guest(['ln','-s','/opt/recording/node_modules',guestPath(resolve(root,'node_modules'))]);
+ await openApp(['xterm','-T',terminalTitle,'-fa','Monospace','-fs','16','-bg','#17212c','-fg','#e8edf2','-geometry','106x30+60+40','-e','bash','--rcfile',guestPath(rc)],terminalTitle);
+ await new Promise(done=>setTimeout(done,800));
+ async function findPost(){const documents=await readDocuments(await loadConfig(root));const article=documents.find(item=>item.kind==='posts'&&item.title===title);if(article)file=article.file;return article;}
+ async function createPost(){await run(['new','post',title]);const article=await findPost();assert.ok(article);return file;}
+ async function newPost(){await typeCommand(root,terminalTitle,"edgepress new post '"+title+"'");for(let attempt=0;attempt<30;attempt++){const article=await findPost();if(article)return;await new Promise(done=>setTimeout(done,300));}throw Error('CLI did not create the post');}
+ async function editPost(body){assert.ok(file);const front=(await readFile(file,'utf8')).split('---')[1];await editFile(root,file,'---'+front+'---\n\n'+body+'\n');}
+ async function startServer({omitWait=task=>task()}={}){
+  const {createServer}=await import('node:net');const socket=createServer();await new Promise(done=>socket.listen(0,'127.0.0.1',done));port=socket.address().port;await new Promise(done=>socket.close(done));
+  await typeCommand(root,terminalTitle,'edgepress server --port '+port);
+  await new Promise(done=>setTimeout(done,1600));
+  await omitWait(async()=>{for(let attempt=0;attempt<180;attempt++){try{const response=await fetch('http://127.0.0.1:'+port+'/',{signal:AbortSignal.timeout(1200)});if(response.ok)return;}catch{}await new Promise(done=>setTimeout(done,500));}throw Error('Guest preview did not become ready');});
+ }
+ async function dispose(){for(const title of [terminalTitle,'Geany']){try{const ids=await guest(['xdotool','search','--onlyvisible','--name',title]);for(const id of ids.split(/\s+/)){const pid=await guest(['xdotool','getwindowpid',id]);if(/^\d+$/.test(pid))await guest(['kill','-TERM',pid]);}}catch{}}}
+ const content=chinese?'## 海边的下午\n\n走到海边时，雨刚停。潮水很轻，远处的山还藏在云里。\n\n![雨后的海岸](/photos/seaside.jpg)\n\n下次还想沿着这条路走远一点。':'## An afternoon by the water\n\nThe rain had just stopped. Small waves reached the shore, and the mountains were still tucked into the clouds.\n\n![The coast after the rain](/photos/seaside.jpg)\n\nNext time, I want to follow this path a little farther.';
+ await context.route('https://edgepress-demo.test/**',async route=>{
+  try{
+  assert.ok(port,'Start the real guest preview before opening the website');
+  const request=route.request(),url=new URL(request.url()),response=await fetch('http://127.0.0.1:'+port+url.pathname+url.search);
+  const headers=Object.fromEntries(response.headers);delete headers['content-encoding'];delete headers['content-length'];
+  return await route.fulfill({status:response.status,headers,body:Buffer.from(await response.arrayBuffer())});
+  }catch(error){if(!route.request().isNavigationRequest())return route.abort();throw error;}
+ });
+ return {title,content,createPost,newPost,editPost,startServer,dispose,activateTerminal:()=>activate(terminalTitle),async publishedPath(){const article=await findPost();assert.ok(article);return article.path;}};
+}

package/tools/recordings/desktop-recording.mjs

@@ -0,0 +1,92 @@
+// FFmpeg records the isolated VM display. Playwright drives only its browser.
+import {mkdir, readFile, writeFile, cp} from 'node:fs/promises';
+import {resolve} from 'node:path';
+import {spawn, spawnSync} from 'node:child_process';
+import {vm, guestPath} from './vm-desktop.mjs';
+import {createHash} from 'node:crypto';
+
+const sessions = new WeakMap();
+function ffmpeg(args) {
+  const result = spawnSync('ffmpeg', ['-hide_banner', '-loglevel', 'error', '-y', ...args], {encoding:'utf8', windowsHide:true});
+  if (result.status !== 0) throw new Error(result.stderr || result.error?.message || 'FFmpeg failed');
+}
+
+export async function recordingContext(browser, options, artifact) {
+  // Let the real guest window determine layout instead of emulating a viewport
+  // that can clip controls while FFmpeg records the physical desktop.
+  const context = await browser.newContext({...options, viewport:null});
+  sessions.set(context, {artifact, clips:[]});
+  return context;
+}
+
+export async function preparePage(page) {
+  await page.bringToFront();
+  const cdp = await page.context().newCDPSession(page);
+  try {
+    const {windowId} = await cdp.send('Browser.getWindowForTarget');
+    await cdp.send('Browser.setWindowBounds', {windowId, bounds:{left:40, top:20, width:1360, height:855}});
+  } finally {
+    await cdp.detach();
+  }
+}
+
+export async function record(page, name, story, {foreground} = {}) {
+  const session = sessions.get(page.context());
+  if (!session) throw new Error('Use a recording context');
+  console.log('Recording ' + name);
+  await preparePage(page);
+  await foreground?.();
+  const directory = resolve(session.artifact, name);
+  await mkdir(directory, {recursive:true});
+  const raw = resolve(directory, 'raw.mkv');
+  const args = ['env','DISPLAY=:99','ffmpeg','-hide_banner','-loglevel','error','-y','-f','x11grab','-framerate','25','-video_size','1440x900','-i',':99.0','-c:v','libx264','-preset','ultrafast','-crf','18','-pix_fmt','yuv420p','-progress','pipe:1',guestPath(raw)];
+  const child = spawn('wsl.exe', ['-d',vm,'--exec',...args], {windowsHide:true, stdio:['pipe','pipe','pipe']});
+  let errors='', progress=''; child.stderr.on('data', chunk => errors += chunk);
+  child.stdin.on('error', error => { errors += error.message; });
+  const finished = new Promise((done,reject)=>{child.once('error',reject);child.once('exit',code=>code===0?done():reject(new Error(errors||'VM capture exited '+code)));});
+  finished.catch(()=>{}); // Readiness reports early failures before awaiting shutdown.
+  // Read FFmpeg's progress rather than creating a screenshot/capture loop.
+  try{await new Promise((done,reject)=>{const timeout=setTimeout(()=>reject(new Error('VM capture did not start: '+errors)),15000);child.stdout.on('data',chunk=>{progress+=chunk;if(/frame=\s*[1-9]/.test(progress)){clearTimeout(timeout);done();}});child.once('exit',()=>{clearTimeout(timeout);reject(new Error(errors));});});}catch(error){if(child.exitCode===null)child.stdin.write('q');await finished.catch(()=>{});throw error;}
+  const started=Date.now(), seconds=()=> (Date.now()-started)/1000, segments=[];
+  let start=0;
+  const omitWait=async task=>{segments.push([start,seconds()]);try{return await task();}finally{start=seconds();}};
+  let succeeded=false;
+  try{await story({omitWait});segments.push([start,seconds()]);succeeded=true;}
+  finally{child.stdin.write('q');await finished;}
+  if(succeeded)session.clips.push({raw,name,segments});
+}
+
+// Export the VM desktop master after the browser fixture has been disposed.
+export async function closeRecording(context, {artifact, output}) {
+  await context.close();
+  const session = sessions.get(context);
+  const entries = [];
+  for (const {raw, name, segments} of session.clips) {
+    const directory = resolve(artifact, name);
+    await mkdir(directory, {recursive:true});
+    const movie = resolve(directory, 'demo.mp4');
+    const filters = segments.map(([start, end], index) => '[0:v]trim=start=' + start.toFixed(3) + ':end=' + end.toFixed(3) + ',setpts=PTS-STARTPTS[s' + index + ']').join(';') + ';' +
+      segments.map((_, index) => '[s' + index + ']').join('') + 'concat=n=' + segments.length + ':v=1:a=0,fps=25,scale=' + '1200' + ':-2:flags=lanczos[out]';
+    ffmpeg(['-i', raw, '-filter_complex', filters, '-map', '[out]', '-c:v', 'libx264', '-crf', '24', '-preset', 'medium', '-pix_fmt', 'yuv420p', '-movflags', '+faststart', '-an', movie]);
+    const gif = resolve(directory, 'demo.gif');
+    ffmpeg(['-i', movie, '-filter_complex', 'fps=8,scale=640:-2:flags=lanczos,split[a][b];[a]palettegen=max_colors=128:stats_mode=diff[p];[b][p]paletteuse=dither=bayer:bayer_scale=3:diff_mode=rectangle', '-loop', '-1', gif]);
+    const bytes = await readFile(gif), movieBytes = await readFile(movie);
+    const hash = data => createHash('sha256').update(data).digest('hex').slice(0, 16);
+    const file = name + '.' + hash(bytes) + '.gif', movieFile = name + '.' + hash(movieBytes) + '.mp4';
+    const probe=spawnSync('ffprobe',['-v','error','-show_entries','format=duration','-of','default=noprint_wrappers=1:nokey=1',movie],{encoding:'utf8',windowsHide:true});
+    if(probe.status!==0||!Number.isFinite(Number(probe.stdout)))throw new Error('Cannot verify exported duration');
+    const duration=Math.round(Number(probe.stdout)*1000);
+    const posterPath = resolve(directory, 'poster.webp');
+    ffmpeg(['-ss', String(name.startsWith('edgepress-') ? Math.max(0, duration / 1000 - 3) : 0), '-i', movie, '-frames:v', '1', '-quality', '90', posterPath]);
+    const poster = name + '.' + hash(await readFile(posterPath)) + '.webp';
+    for (const [source, target] of [[gif, file], [movie, movieFile], [posterPath, poster]]) await cp(source, resolve(output, target));
+    const entry = {name, file, poster, movie:movieFile, movieBytes:movieBytes.length, duration, bytes:bytes.length,
+      date:new Date().toISOString().slice(0, 10), kind:'FFmpeg recording of an isolated WSL2 desktop; '+(name.startsWith('edgepress-')||name.startsWith('ishare-sharing-')?'real terminal, editor and Chromium; preview startup wait shortened':'actual Chromium interface')+'; isolated service fixtures', source:'tools/recordings/capture-project-demos.mjs'};
+    entries.push(entry);
+    const manifest = resolve(artifact, 'manifest.json'), previous = await readFile(manifest, 'utf8').then(JSON.parse).catch(() => []);
+    await writeFile(manifest, JSON.stringify([...previous.filter(item => item.name !== name), entry], null, 2) + '\n');
+    console.log(JSON.stringify(entry));
+  }
+  sessions.delete(context);
+  return entries;
+}

package/tools/recordings/provision-vm.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# Run inside a disposable Debian/Ubuntu VM, never on the host desktop.
+export DEBIAN_FRONTEND=noninteractive
+apt-get update -qq
+apt-get install -y --no-install-recommends ca-certificates curl xz-utils xvfb openbox xterm geany chromium ffmpeg xdotool fonts-noto-cjk dbus-x11 xclip tint2 x11-xserver-utils
+mkdir -p /etc/chromium/policies/managed
+printf '{"TranslateEnabled":false}\n' > /etc/chromium/policies/managed/recording.json
+mkdir -p /opt/recording
+curl -fsSL https://nodejs.org/dist/v22.22.0/node-v22.22.0-linux-x64.tar.xz -o /opt/recording/node.tar.xz
+tar -xJf /opt/recording/node.tar.xz -C /opt/recording
+ln -sf /opt/recording/node-v22.22.0-linux-x64/bin/node /usr/local/bin/node
+ln -sf /opt/recording/node-v22.22.0-linux-x64/bin/npm /usr/local/bin/npm
+ln -sf /opt/recording/node-v22.22.0-linux-x64/bin/npx /usr/local/bin/npx
+mkdir -p /root/.config/geany
+if [ ! -f /root/.config/geany/geany.conf ]; then
+  printf "[geany]\neditor_font=Monospace 16\nline_wrapping=true\n" > /root/.config/geany/geany.conf
+fi

package/tools/recordings/start-vm-desktop.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# DISPLAY :99 is private to the guest. Do not use WSLg/host desktop displays.
+unset WAYLAND_DISPLAY DBUS_SESSION_BUS_ADDRESS XDG_RUNTIME_DIR
+export DISPLAY=:99 LANG=C.UTF-8 GDK_BACKEND=x11 QT_QPA_PLATFORM=xcb
+mkdir -p /opt/recording/logs
+if ! pgrep -f 'Xvfb :99' >/dev/null; then
+  # A stopped disposable VM can leave X11 locks although its server is gone.
+  rm -f /tmp/.X99-lock /tmp/.X11-unix/X99
+  Xvfb :99 -screen 0 1440x900x24 -nolisten tcp >/opt/recording/logs/display.log 2>&1 &
+fi
+for attempt in {1..50}; do
+  if xdpyinfo -display :99 >/dev/null 2>&1; then break; fi
+  sleep 0.2
+done
+xdpyinfo -display :99 >/dev/null
+if ! pgrep -x openbox >/dev/null; then nohup openbox >/opt/recording/logs/desktop.log 2>&1 </dev/null & fi
+sleep 0.5
+xsetroot -solid '#243343'
+if ! curl -fsS http://127.0.0.1:9222/json/version >/dev/null 2>&1; then
+  nohup chromium --ozone-platform=x11 --no-sandbox --disable-dev-shm-usage --disable-gpu --disable-gpu-rasterization --disable-gpu-compositing --disable-extensions --no-first-run --no-default-browser-check --disable-features=Translate,TranslateUI --lang=en-US --password-store=basic --remote-debugging-port=9222 --remote-debugging-address=127.0.0.1 --user-data-dir=/opt/recording/browser --window-position=40,20 --window-size=1360,855 about:blank >/opt/recording/logs/browser.log 2>&1 </dev/null &
+fi
+for attempt in {1..50}; do
+  if curl -fsS http://127.0.0.1:9222/json/version >/dev/null 2>&1; then break; fi
+  sleep 0.2
+done
+curl -fsS http://127.0.0.1:9222/json/version >/dev/null
+if [ "${1:-}" = '--keep-alive' ]; then exec sleep infinity; fi

package/tools/recordings/vm-desktop.mjs

@@ -0,0 +1,124 @@
+import {spawn} from 'node:child_process';
+import {writeFile,readFile} from 'node:fs/promises';
+import {resolve,dirname} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+export const vm = process.env.RECORDING_VM || 'CodexRecordingVM';
+const workspace=resolve(dirname(fileURLToPath(import.meta.url)),'../../..').replaceAll('\\','/');
+export const guestPath = path => resolve(path).replaceAll('\\', '/').replace(workspace,process.env.RECORDING_GUEST_ROOT||'/opt/recording/workspace').replace(/^([a-z]):/i, (_, drive) => '/mnt/' + drive.toLowerCase());
+function guestProcess(args) {
+  const quote = value => "'" + String(value).replaceAll("'", "'\\''") + "'";
+  const child = spawn('wsl.exe', ['-d', vm, '--exec', 'bash', '-s'], {windowsHide:true});
+  child.stdin.end('exec env -u WAYLAND_DISPLAY -u DBUS_SESSION_BUS_ADDRESS -u XDG_RUNTIME_DIR LANG=C.UTF-8 DISPLAY=:99 GDK_BACKEND=x11 QT_QPA_PLATFORM=xcb NO_AT_BRIDGE=1 ' + args.map(quote).join(' ') + '\n');
+  return child;
+}
+export async function openApp(args, title) {
+  const child = guestProcess(args);
+  let errors=''; child.stderr.on('data', chunk => errors += chunk); child.stdout.resume();
+  child.on('error', error => { errors += error.message; });
+  for (let attempt=0;attempt<40;attempt++) {
+    try { await activate(title); return child; } catch {}
+    if(child.exitCode!==null)throw new Error(args[0] + ' failed: ' + errors);
+    await new Promise(done=>setTimeout(done,200));
+  }
+  child.kill();throw new Error(args[0] + ' did not open: ' + errors);
+}
+export async function guest(args) {
+  return new Promise((done, reject) => {
+    // UTF-8 stdin avoids Windows/WSL command-line reparsing of paths and quotes.
+    const child = guestProcess(['timeout', '15s', ...args]);
+    let output = ''; child.stdout.on('data', chunk => output += chunk); child.stderr.on('data', chunk => output += chunk);
+    child.once('error', reject); child.once('exit', code => code === 0 ? done(output.trim()) : reject(new Error(args[0] + ' exited ' + code + ': ' + output)));
+  });
+}
+export async function activate(title) {
+  const id = (await guest(['xdotool', 'search', '--onlyvisible', '--name', title])).split(/\s+/).at(-1);
+  await guest(['xdotool', 'windowactivate', '--sync', id]);
+}
+
+// Move only the guest's real X11 pointer so FFmpeg records the same cursor the
+// browser receives. CDP coordinates alone leave the desktop cursor behind.
+export async function pointAt(page, locator) {
+  await locator.scrollIntoViewIfNeeded();
+  await new Promise(done => setTimeout(done, 250));
+  const box = await locator.boundingBox();
+  if (!box) throw new Error('Demo target is not visible');
+  const position = {x:box.x + box.width / 2, y:box.y + box.height / 2};
+  await pointAtPosition(page, position);
+  return position;
+}
+
+async function windowOrigin(page) {
+  return page.evaluate(() => ({
+    x:screenX + (outerWidth - innerWidth) / 2,
+    y:screenY + outerHeight - innerHeight
+  }));
+}
+
+export async function pointAtPosition(page, {x, y}) {
+  const window = await windowOrigin(page);
+  // --sync waits for a movement event forever when the pointer is already here.
+  await guest(['xdotool', 'mousemove', String(Math.round(window.x + x)), String(Math.round(window.y + y))]);
+  await page.mouse.move(x, y);
+}
+
+export async function drag(page, {from, to, steps=16, duration=900}) {
+  const window = await windowOrigin(page);
+  const coordinates = point => [String(Math.round(window.x + point.x)), String(Math.round(window.y + point.y))];
+  // Keep press, movement and release in one native event stream. Mixing CDP
+  // button state with X11 movement can cancel the actual browser drag.
+  const args = ['xdotool', 'mousemove', ...coordinates(from), 'mousedown', '1'];
+  for (let step=1; step<=steps; step++) {
+    args.push('sleep', String(duration / steps / 1000), 'mousemove', ...coordinates({
+      x:from.x + (to.x - from.x) * step / steps,
+      y:from.y + (to.y - from.y) * step / steps
+    }));
+  }
+  args.push('mouseup', '1');
+  await guest(args);
+  await page.mouse.move(to.x, to.y);
+}
+
+export async function chooseFiles(page, input) {
+  // The private guest Desktop contains only the two demo attachments. Native
+  // GTK coordinates are scoped to this controlled VM, never the host desktop.
+  await pointAt(page, input);
+  await guest(['xdotool', 'click', '1']);
+  await new Promise(done => setTimeout(done, 1000));
+  await activate('Open File');
+  const id = (await guest(['xdotool', 'search', '--onlyvisible', '--name', 'Open File'])).split(/\s+/).at(-1);
+  const geometry = Object.fromEntries((await guest(['xdotool', 'getwindowgeometry', '--shell', id])).split('\n').map(line => line.split('=')).map(([key, value]) => [key, Number(value)]));
+  const move = async (x, y) => guest(['xdotool', 'mousemove', String(Math.round(x)), String(Math.round(y)), 'click', '1']);
+  await move(geometry.X + 65, geometry.Y + 75); // Desktop bookmark.
+  await new Promise(done => setTimeout(done, 1200));
+  await move(geometry.X + 340, geometry.Y + 63); // First file row.
+  await guest(['xdotool', 'key', 'ctrl+a']);
+  await new Promise(done => setTimeout(done, 900));
+  // Click Open explicitly; Enter can activate GTK's Cancel default.
+  await move(geometry.X + geometry.WIDTH - 53, geometry.Y + geometry.HEIGHT - 43);
+}
+export async function typeCommand(root, title, command) {
+  const path = resolve(root, '.recording-command.txt');
+  await writeFile(path, command);
+  await activate(title);
+  await guest(['xdotool', 'type', '--clearmodifiers', '--delay', '70', '--file', guestPath(path)]);
+  await guest(['xdotool', 'key', 'Return']);
+}
+export async function editFile(root, file, source) {
+  const path = resolve(root, '.recording-editor.txt');
+  await writeFile(path, source);
+  await openApp(['geany', '-i', guestPath(file)], 'Geany');
+  const id=(await guest(['xdotool','search','--onlyvisible','--name','Geany'])).split(/\s+/).at(-1);
+  await guest(['xdotool','windowsize','--sync',id,'1200','780','windowmove',id,'100','70']);
+  // Keep the guest X11 selection owner alive until GTK has read the clipboard.
+  const clipboard=guestProcess(['xclip','-quiet','-selection','clipboard','-in',guestPath(path)]);
+  clipboard.stdout.resume();clipboard.stderr.resume();
+  try{
+    await new Promise(done=>setTimeout(done,300));
+    await guest(['xdotool', 'key', 'ctrl+a', 'ctrl+v']);
+    await new Promise(done => setTimeout(done, 1800));
+    await guest(['xdotool', 'key', 'ctrl+s']);
+    await new Promise(done=>setTimeout(done,300));
+    if((await readFile(file,'utf8')).replaceAll('\r\n','\n')!==source.replaceAll('\r\n','\n'))throw new Error('Guest editor did not save the expected document');
+  }finally{clipboard.kill();}
+}

package/tools/verification/README.md

@@ -0,0 +1,44 @@
+# Theme verification
+
+Run these optional development tools from a built EdgePress site's root. They use isolated Playwright Chromium with extensions disabled and local static fixtures. Install Playwright in the site's development dependencies and run `npx playwright install chromium` first. No live service accounts or deployments are verified.
+
+For a theme that declares `dataSaver` in `theme.json`, create `tests/data-saver-site.test.mjs`:
+
+```js
+import {fileURLToPath} from 'node:url';
+import {registerDataSaverTests} from 'edgepress/tools/verification/data-saver-site.mjs';
+
+registerDataSaverTests(fileURLToPath(new URL('../', import.meta.url)), {
+  locales: ['en', 'zh-CN'],
+  paths: ['/', '/about/'],
+  noJsPaths: ['/'],
+  coldPaths: ['/'],
+});
+```
+
+The suite checks full/text layouts, readable no-JavaScript output, real throttled transfers, early keyboard switching, stable waiting-screen choices, localized controls, disabled production debug entry, and absence of premature third-party requests. Use actual paths and enabled locales from your site. It expects the operator's explicit full-view defaults:
+
+```yaml
+site:
+  dataSaver:
+    enabled: true
+    debug: false
+    mode: auto
+    detectSlowConnection: true
+    respectBrowserPreference: false
+```
+
+Full and text views retain prose by default. A dynamic application can explicitly set `compareProse: false` if its anonymous fixture differs, while keeping headings, navigation, captions, cards and geometry checks. API fixtures contain anonymous synthetic responses; application-specific interactions and consent checks belong in the site's own tests.
+
+Run `node --test tests/data-saver-site.test.mjs`. `DATA_SAVER_SCREENSHOTS=tools/reports/data-saver` optionally retains screenshots and JSON measurements. The test does not enable data-saving support in themes that do not declare it.
+
+For a cold-cache benchmark, add `tools/verification/page-performance.mjs`:
+
+```js
+process.env.PERFORMANCE_PATHS ||= JSON.stringify(['/', '/about/']);
+await import('edgepress/tools/verification/page-performance.mjs');
+```
+
+Run it from the site root. Transfers use gzip, 100 KB/s and 150 ms latency. `PERFORMANCE_DIST` can select built output; `PERFORMANCE_OUTPUT=tools/reports/performance` retains evidence. Content-ready time, FCP and the observed LCP candidate are reported separately.
+
+For Pages readability, import `formatPages` from `edgepress/tools/assets/format-pages.mjs`. `await formatPages(process.cwd())` lists proposed changes; `{write: true}` applies them. It converts legacy Markdown/YAML Pages to real, formatted `.json` files and sets a local `$schema` reference. Conversion verifies parsed field values and element order, checks all files before writing, refuses duplicate locale formats, and rejects nonempty Markdown bodies. VS Code's JSON outline and folding work on the actual page → row → cell → element hierarchy. From the framework checkout, `node tools/assets/format-pages.mjs --write` formats the example site.