edgepress 2026.10.13 → 2026.10.15

package/src/page-editor.js

@@ -0,0 +1,178 @@
+import { createServer } from 'node:http';
+import { createHash, randomBytes } from 'node:crypto';
+import { readFile, readdir, lstat, realpath, open, rename, unlink } from 'node:fs/promises';
+import { resolve, relative, dirname, basename, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createPage } from './page-scaffold.js';
+
+const editorRoot = dirname(fileURLToPath(import.meta.url));
+const maxDocumentBytes = 2 * 1024 * 1024;
+const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const revision = source => createHash('sha256').update(source).digest('hex');
+const inside = (root, file) => file !== root && !relative(root, file).startsWith('..' + sep) && relative(root, file) !== '..' && !relative(root, file).startsWith(sep);
+
+async function listPages(contentRoot) {
+  const found = [];
+  async function scan(folder, prefix = '') {
+    let entries;
+    try { entries = await readdir(folder, { withFileTypes: true }); }
+    catch (error) { if (error.code === 'ENOENT') return; throw error; }
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) await scan(resolve(folder, entry.name), prefix + entry.name + '/');
+      else if (entry.isFile() && entry.name.endsWith('.json') && prefix) found.push(prefix + entry.name);
+    }
+  }
+  await scan(contentRoot);
+  return found.sort((a, b) => a.localeCompare(b));
+}
+
+async function safePageFile(contentRoot, path) {
+  if (typeof path !== 'string' || path.includes('\\') || path.includes('..') || path.startsWith('/') || !path.endsWith('.json')) {
+    throw new Error('Invalid page path');
+  }
+  if (!(await listPages(contentRoot)).includes(path)) throw new Error('Page does not exist');
+  const folder = await realpath(contentRoot);
+  const file = resolve(contentRoot, path);
+  const actual = await realpath(file);
+  const info = await lstat(file);
+  if (!info.isFile() || info.isSymbolicLink() || !inside(folder, actual)) throw new Error('Unsafe page file');
+  // The directory scanner rejects linked directories, even when the final file is regular.
+  return file;
+}
+
+function validatePage(page, original, typeNames) {
+  if (!isObject(page)) throw new Error('Page must be an object');
+  if (page.lang !== original.lang || page.$schema !== original.$schema) throw new Error('The page language and schema cannot be changed here');
+  if (typeof page.title !== 'string' || !page.title.trim() || page.title.length > 500) throw new Error('Page title is required');
+  if (page.homepage !== undefined && typeof page.homepage !== 'boolean') throw new Error('homepage must be a boolean');
+  if (!Array.isArray(page.blocks) || !page.blocks.length || page.blocks.length > 100) throw new Error('Page must contain 1–100 rows');
+  function validateElements(elements, location, depth) {
+    if (!Array.isArray(elements) || !elements.length || elements.length > 100) throw new Error(location + ' needs 1–100 elements');
+    if (depth > 12) throw new Error('Nested elements are too deep');
+    for (const [index, element] of elements.entries()) {
+      if (!isObject(element) || !typeNames.has(element.type)) throw new Error(location + '[' + index + '] has an invalid element type');
+      if (element.blocks !== undefined) validateElements(element.blocks, location + '[' + index + '].blocks', depth + 1);
+    }
+  }
+  for (const [index, row] of page.blocks.entries()) {
+    if (!isObject(row) || Object.keys(row).some(key => !['columns', 'cells'].includes(key))) throw new Error('Invalid row at ' + index);
+    if (!Number.isInteger(row.columns) || row.columns < 1 || row.columns > 4 || !Array.isArray(row.cells) || row.cells.length !== row.columns) throw new Error('Row ' + (index + 1) + ' must have 1–4 matching columns and cells');
+    for (const [cell, elements] of row.cells.entries()) validateElements(elements, 'Row ' + (index + 1) + ', column ' + (cell + 1), 0);
+  }
+}
+
+function respond(res, status, data) {
+  res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' });
+  res.end(JSON.stringify(data));
+}
+
+async function requestBody(req) {
+  if (!/^application\/json(?:;|$)/i.test(req.headers['content-type'] || '')) throw new Error('Expected application/json');
+  let bytes = 0;
+  const chunks = [];
+  for await (const chunk of req) {
+    bytes += chunk.length;
+    if (bytes > maxDocumentBytes) throw new Error('Page exceeds 2 MB');
+    chunks.push(chunk);
+  }
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+
+/** Starts a loopback-only editor. Never deploy this server. */
+export async function startPageEditor({ root = process.cwd(), port = 4178, locales = ['en', 'zh-CN'], defaultLocale = 'en' } = {}) {
+  const contentRoot = resolve(root, 'content/pages');
+  const typeSchema = JSON.parse(await readFile(resolve(editorRoot, '../schemas/pages.schema.json'), 'utf8'));
+  const typeNames = new Set(typeSchema.definitions.element.properties.type.enum);
+  const catalog = JSON.parse(await readFile(resolve(editorRoot, 'page-block-catalog.json'), 'utf8'));
+  if (typeNames.size !== Object.keys(catalog.blocks).length || [...typeNames].some(type => !catalog.blocks[type]?.template || catalog.blocks[type].template.type !== type)) {
+    throw new Error('The visual editor block catalog is out of sync with the Pages schema');
+  }
+  const staticFiles = new Map([
+    ['/', { file: 'page-editor.html', type: 'text/html; charset=utf-8' }],
+    ['/editor.js', { file: 'page-editor-client.js', type: 'text/javascript; charset=utf-8' }],
+    ['/editor.css', { file: 'page-editor.css', type: 'text/css; charset=utf-8' }]
+  ]);
+  // Serialize writes so two browser tabs cannot commit the same revision.
+  let pendingWrite = Promise.resolve();
+  let serverPort = null;
+  const server = createServer(async (req, res) => {
+    try {
+      if (req.headers.host !== '127.0.0.1:' + serverPort) return respond(res, 403, { error: 'Localhost only' });
+      res.setHeader('Content-Security-Policy', "default-src 'none'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'");
+      res.setHeader('X-Frame-Options', 'DENY');
+      const url = new URL(req.url, 'http://127.0.0.1:' + serverPort);
+      if (req.method === 'GET' && staticFiles.has(url.pathname)) {
+        const item = staticFiles.get(url.pathname);
+        res.writeHead(200, { 'Content-Type': item.type, 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' });
+        const bytes = await readFile(resolve(editorRoot, item.file));
+        // The optional editor extension shares the same module scope as the original
+        // editor to reuse its loaded page and revision state without a second copy.
+        if (url.pathname === '/editor.js') {
+          const extension = await readFile(resolve(editorRoot, 'page-editor-extension.js'));
+          return res.end(Buffer.concat([bytes, Buffer.from('\n'), extension]));
+        }
+        return res.end(bytes);
+      }
+      if (req.method === 'GET' && url.pathname === '/api/block-catalog') {
+        return respond(res, 200, catalog);
+      }
+      if (req.method === 'GET' && url.pathname === '/api/locales') {
+        return respond(res, 200, { locales, defaultLocale });
+      }
+      if (req.method === 'POST' && url.pathname === '/api/pages') {
+        if (req.headers.origin !== 'http://127.0.0.1:' + serverPort) return respond(res, 403, { error: 'Invalid editor origin' });
+        const body = await requestBody(req);
+        const result = await (pendingWrite = pendingWrite.catch(() => {}).then(async () => {
+          if (!isObject(body) || Object.keys(body).some(key => !['title', 'slug', 'lang'].includes(key))) throw new Error('Invalid new page parameters');
+          return createPage(root, { title: body.title, slug: body.slug, lang: body.lang, locales, defaultLocale });
+        }));
+        return respond(res, 201, { path: result.path, revision: revision(result.source), page: result.page });
+      }
+      if (req.method === 'GET' && url.pathname === '/api/pages') {
+        const paths = await listPages(contentRoot);
+        return respond(res, 200, { pages: paths });
+      }
+      if (req.method === 'GET' && url.pathname === '/api/page') {
+        const file = await safePageFile(contentRoot, url.searchParams.get('path'));
+        const source = await readFile(file, 'utf8');
+        if (Buffer.byteLength(source) > maxDocumentBytes) throw new Error('Page exceeds 2 MB');
+        return respond(res, 200, { page: JSON.parse(source), revision: revision(source) });
+      }
+      if (req.method === 'PUT' && url.pathname === '/api/page') {
+        if (req.headers.origin !== 'http://127.0.0.1:' + serverPort) return respond(res, 403, { error: 'Invalid editor origin' });
+        const body = await requestBody(req);
+        const result = await (pendingWrite = pendingWrite.catch(() => {}).then(async () => {
+          const file = await safePageFile(contentRoot, url.searchParams.get('path'));
+          const originalSource = await readFile(file, 'utf8');
+          if (!isObject(body) || typeof body.revision !== 'string' || body.revision !== revision(originalSource)) {
+            return { status: 409, data: { error: 'This page has changed on disk. Reload before saving.' } };
+          }
+          const original = JSON.parse(originalSource);
+          validatePage(body.page, original, typeNames);
+          const nextSource = JSON.stringify(body.page, null, 2) + '\n';
+          if (Buffer.byteLength(nextSource) > maxDocumentBytes) throw new Error('Page exceeds 2 MB');
+          const temp = resolve(dirname(file), '.' + basename(file) + '.' + randomBytes(8).toString('hex') + '.tmp');
+          let created = false;
+          try {
+            const fd = await open(temp, 'wx', 0o600);
+            created = true;
+            try { await fd.writeFile(nextSource, 'utf8'); await fd.sync(); }
+            finally { await fd.close(); }
+            await rename(temp, file);
+          } finally { if (created) await unlink(temp).catch(error => { if (error.code !== 'ENOENT') throw error; }); }
+          return { status: 200, data: { revision: revision(nextSource) } };
+        }));
+        return respond(res, result.status, result.data);
+      }
+      return respond(res, 404, { error: 'Not found' });
+    } catch (error) {
+      const badInput = error instanceof SyntaxError || /Invalid|must|exceeds|needs|required|Unsafe|does not exist|cannot be changed|too deep|Expected|Unsupported|slug|title|locale/.test(error.message);
+      const conflict = /already exists/.test(error.message);
+      return respond(res, conflict ? 409 : badInput ? 400 : 500, { error: conflict || badInput ? error.message : 'Editor request failed' });
+    }
+  });
+  await new Promise((ok, fail) => { server.once('error', fail); server.listen(port, '127.0.0.1', ok); });
+  serverPort = server.address().port;
+  return { server, url: 'http://127.0.0.1:' + serverPort + '/', close: () => new Promise((ok, fail) => server.close(error => error ? fail(error) : ok())) };
+}

package/src/page-scaffold.js

@@ -0,0 +1,70 @@
+import { mkdir, lstat, realpath, open, access, rm } from 'node:fs/promises';
+import { dirname, relative, resolve, sep } from 'node:path';
+import { slugify } from './content.js';
+
+const validSlug = /^[\p{L}\p{N}]+(?:-[\p{L}\p{N}]+)*$/u;
+function within(root, path) {
+  const rel = relative(root, path);
+  return rel && rel !== '..' && !rel.startsWith('..' + sep) && !rel.startsWith(sep);
+}
+async function directory(path) {
+  try {
+    const stats = await lstat(path);
+    if (stats.isSymbolicLink() || !stats.isDirectory()) throw new Error('Unsafe page directory: ' + path);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    await mkdir(path);
+  }
+}
+
+/** Reused by the CLI and the local editor. The browser never supplies a filesystem path. */
+export async function createPage(root, {
+  title, slug, lang, locales = ['en', 'zh-CN'], defaultLocale = 'en'
+} = {}) {
+  if (typeof title !== 'string' || !title.trim() || title.length > 160 || /[\x00-\x1f\x7f]/.test(title)) {
+    throw new Error('Page title must be one line of 1–160 characters');
+  }
+  const locale = locales.find(value => value.toLowerCase() === String(lang || defaultLocale).toLowerCase());
+  if (!locale) throw new Error('Unsupported page locale; configure the language first');
+  const name = slug === undefined || slug === '' ? slugify(title) : String(slug);
+  if (!validSlug.test(name) || name.length > 100 || name !== name.toLowerCase()) {
+    throw new Error('Page slug must be a single lowercase URL segment (letters, digits, hyphens)');
+  }
+  const projectRoot = resolve(root);
+  const content = resolve(projectRoot, 'content');
+  const pages = resolve(content, 'pages');
+  await directory(content);
+  await directory(pages);
+  const pageDir = resolve(pages, name);
+  await directory(pageDir);
+  const actualPages = await realpath(pages);
+  const actualPageDir = await realpath(pageDir);
+  if (!within(actualPages, actualPageDir)) throw new Error('Unsafe page path');
+  const file = resolve(pageDir, locale.toLowerCase() + '.json');
+  const alternate = resolve(pageDir, locale.toLowerCase() + '.md');
+  try { await access(alternate); throw new Error('Page already exists: ' + alternate); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const bundledSchema = resolve(projectRoot, 'schemas/pages.schema.json');
+  let schemaPath = resolve(projectRoot, 'node_modules/edgepress/schemas/pages.schema.json');
+  try { await access(bundledSchema); schemaPath = bundledSchema; }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const schema = relative(dirname(file), schemaPath).split(sep).join('/');
+  const page = {
+    $schema: schema.startsWith('.') ? schema : './' + schema,
+    title: title.trim(), lang: locale, slug: name,
+    description: '', blocks: [
+      { columns: 1, cells: [[{ type: 'hero', title: title.trim(), text: 'Describe this page.' }]] }
+    ]
+  };
+  const source = JSON.stringify(page, null, 2) + '\n';
+  let handle;
+  try { handle = await open(file, 'wx', 0o644); }
+  catch (error) {
+    if (error.code === 'EEXIST') throw new Error('Page already exists: ' + file);
+    throw error;
+  }
+  try { await handle.writeFile(source); }
+  catch (error) { await handle.close(); await rm(file, { force: true }); throw error; }
+  await handle.close();
+  return { file, path: name + '/' + locale.toLowerCase() + '.json', page, source };
+}

package/tests/document-package.test.mjs

@@ -4,22 +4,17 @@ import { readFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { dirname, resolve } from 'node:path';
 
-test('cloud dependency is pinned to a published source commit and excludes the removed PPT engine', async () => {
+test('cloud dependency follows published release ranges and excludes the removed PPT engine', async () => {
   const manifest = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
-  const lock = JSON.parse(await readFile(new URL('../package-lock.json', import.meta.url), 'utf8'));
   const source = manifest.dependencies['@jsw-teams/document-viewer'];
-  assert.match(source, /^https:\/\/codeload\.github\.com\/jsw-teams\/document-viewer\/tar\.gz\/[a-f0-9]{40}$/);
-  assert.equal(lock.packages['node_modules/@jsw-teams/document-viewer'].resolved, source);
+  assert.match(source, /^git\+https:\/\/github\.com\/jsw-teams\/document-viewer\.git#semver:\^2026\.10\.1$/);
   assert.ok(!manifest.files.includes('vendor'));
-  assert.ok(!lock.packages['node_modules/@file-viewer/ppt']);
-  assert.equal(manifest.overrides['@file-viewer/doc'].dompurify, '3.4.17');
-  const sanitizerVersions = Object.entries(lock.packages).filter(([path]) => path.endsWith('node_modules/dompurify')).map(([, dependency]) => dependency.version);
-  assert.deepEqual(sanitizerVersions, ['3.4.17']);
+  assert.match(manifest.overrides['@file-viewer/doc'].dompurify,/^\^3\./);
   const require = createRequire(import.meta.url);
   const root = resolve(dirname(require.resolve('@jsw-teams/document-viewer')), '..');
   const component = JSON.parse(await readFile(resolve(root, 'package.json'), 'utf8'));
   assert.ok(!component.dependencies['@file-viewer/ppt']);
-  assert.equal(component.dependencies.cfb, '1.2.2');
+  assert.match(component.dependencies.cfb, /^\^1\./);
   for (const path of ['src/ppt/parser.js', 'src/ppt/worker.js', 'src/renderers/ppt.js', 'src/icons.js', 'src/sheets/columns.js', 'src/sheets/column-controls.js', 'src/lucide-license.txt', 'tools/assets.mjs', 'NOTICE.md']) {
     const content = await readFile(resolve(root, path), 'utf8');
     assert.ok(content.length);

package/tests/oembed-layout.test.mjs

@@ -60,7 +60,9 @@ test('embed entry stays compact until requested, retries failures and keeps keyb
       assert.equal(await entry.locator('[data-oembed-status]').evaluate(element => element.getBoundingClientRect().height), 0);
       assert((await entry.boundingBox()).height < 300);
       assert.equal(requests, 0);
-      await button.focus(); await page.keyboard.press('Enter');
+      // Locator.press does not wait for CSS visibility; hidden controls cannot receive focus.
+      await button.waitFor({state:'visible'});
+      await button.press('Enter');
       // This is an event counter, so deferred text-view styles must not make
       // the assertion depend on the browser scheduling animation frames.
       await page.waitForFunction(() => window.testOpened > 0, null, { polling: 50 });
@@ -68,7 +70,8 @@ test('embed entry stays compact until requested, retries failures and keeps keyb
       assert.equal(requests, 0);
       assert.equal(await button.isEnabled(), true);
       await page.evaluate(() => { window.testAllowed = true; });
-      await button.focus(); await page.keyboard.press('Enter');
+      await button.waitFor({state:'visible'});
+      await button.press('Enter');
       await page.waitForFunction(() => document.querySelector('[data-edgepress-oembed]').getAttribute('aria-busy') === 'true');
       assert.equal(await button.isEnabled(), false);
       const pendingBounds = await entry.locator('[data-oembed-placeholder]').boundingBox();
@@ -81,7 +84,8 @@ test('embed entry stays compact until requested, retries failures and keeps keyb
       await page.waitForTimeout(300);
       assert.equal(calls,1);
       assert.equal(await entry.getAttribute('data-oembed-unavailable'),'true');
-      await button.focus(); await page.keyboard.press('Enter');
+      await button.waitFor({state:'visible'});
+      await button.press('Enter');
       await page.waitForFunction(() => document.querySelector('[data-edgepress-oembed]').dataset.loaded === 'true');
       await page.frameLocator('iframe').getByText('Shared story content').waitFor();
       assert.equal(calls, 2);

package/tests/page-editor.test.mjs

@@ -0,0 +1,106 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, readFile, writeFile, rm, symlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { chromium } from 'playwright';
+import { startPageEditor } from '../src/page-editor.js';
+
+const sample = {
+  $schema: '../../../schemas/pages.schema.json',
+  title: 'Hello', lang: 'en', homepage: true,
+  description: 'Example', customSetting: { untouched: ['a', 'b'] },
+  blocks: [{ columns: 2, cells: [
+    [{ type: 'heading', level: 2, text: 'First' }],
+    [{ type: 'section', title: 'Other', blocks: [{ type: 'text', text: 'Nested' }], custom: 7 }]
+  ] }]
+};
+
+async function withEditor(run) {
+  const root = await mkdtemp(join(tmpdir(), 'edgepress-visual-editor-'));
+  const dir = resolve(root, 'content/pages/home');
+  await mkdir(dir, { recursive: true });
+  const file = resolve(dir, 'en.json');
+  await writeFile(file, JSON.stringify(sample, null, 2) + '\n');
+  const editor = await startPageEditor({ root, port: 0 });
+  try { await run({ root, file, ...editor }); }
+  finally { await editor.close(); await rm(root, { recursive: true, force: true }); }
+}
+
+test('local visual editor serves a content-safe interface and lists JSON Pages', async () => {
+  await withEditor(async ({ url }) => {
+    const response = await fetch(url);
+    assert.equal(response.status, 200);
+    assert.match(response.headers.get('content-security-policy'), /frame-ancestors 'none'/);
+    assert.match(await response.text(), /可视化 Pages 编辑器/);
+    const pages = await (await fetch(url + 'api/pages')).json();
+    assert.deepEqual(pages.pages, ['home/en.json']);
+    const script = await fetch(url + 'editor.js');
+    assert.equal(script.status, 200);
+    assert.match(script.headers.get('content-type'), /javascript/);
+  });
+});
+
+test('editor preserves unknown metadata and nested elements, detects external changes, and rejects unsafe writes', async () => {
+  await withEditor(async ({ url, file, root }) => {
+    const path = 'api/page?path=home%2Fen.json';
+    const original = await (await fetch(url + path)).json();
+    assert.deepEqual(original.page, sample);
+    const payload = { page: structuredClone(original.page), revision: original.revision };
+    payload.page.title = 'Edited';
+    payload.page.blocks[0].cells[0][0].text = 'Updated';
+    const update = () => fetch(url + path, { method: 'PUT', headers: { 'Content-Type': 'application/json', Origin: url.slice(0, -1) }, body: JSON.stringify(payload) });
+    let response = await update();
+    assert.equal(response.status, 200, await response.text());
+    const saved = JSON.parse(await readFile(file, 'utf8'));
+    assert.equal(saved.title, 'Edited');
+    assert.equal(saved.blocks[0].cells[0][0].text, 'Updated');
+    assert.deepEqual(saved.customSetting, sample.customSetting);
+    assert.deepEqual(saved.blocks[0].cells[1][0], sample.blocks[0].cells[1][0]);
+    response = await update();
+    assert.equal(response.status, 409);
+    const current = await (await fetch(url + path)).json();
+    current.page.blocks[0].columns = 1;
+    response = await fetch(url + path, { method: 'PUT', headers: { 'Content-Type': 'application/json', Origin: url.slice(0, -1) }, body: JSON.stringify(current) });
+    assert.equal(response.status, 400);
+    assert.equal(JSON.parse(await readFile(file, 'utf8')).blocks[0].columns, 2);
+    response = await fetch(url + path, { method: 'PUT', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(current) });
+    assert.equal(response.status, 403);
+    assert.equal((await fetch(url + 'api/page?path=..%2F..%2Fsecret.json')).status, 400);
+    assert.equal((await fetch(url + 'api/page?path=home%2Fmissing.json')).status, 400);
+    const outside = await mkdtemp(join(tmpdir(), 'edgepress-visual-outside-'));
+    try {
+      await writeFile(resolve(outside, 'en.json'), JSON.stringify(sample));
+      await symlink(outside, resolve(root, 'content/pages/linked'), 'dir');
+      const list = await (await fetch(url + 'api/pages')).json();
+      assert.deepEqual(list.pages, ['home/en.json']);
+      assert.equal((await fetch(url + 'api/page?path=linked%2Fen.json')).status, 400);
+    } finally { await rm(outside, { recursive: true, force: true }); }
+  });
+});
+
+test('visual browser controls edit, preview and save a page without hand-writing JSON', { timeout: 45000 }, async () => {
+  await withEditor(async ({ url, file }) => {
+    const browser = await chromium.launch({ args: ['--disable-extensions'] });
+    try {
+      const page = await browser.newPage();
+      await page.goto(url);
+      await page.waitForFunction(() => document.querySelector('#page-name')?.textContent === 'Hello');
+      await page.locator('#title').fill('Visual title');
+      await page.locator('.canvas-row').first().locator('select').first().selectOption('1');
+      await page.locator('#add-row').click();
+      assert.equal(await page.locator('.canvas-row').count(), 2);
+      await page.locator('.canvas-row').last().locator('.pick').click();
+      await page.locator('#fields textarea[aria-label="text"]').fill('Typed in the visual editor');
+      await page.locator('#save').click();
+      await page.locator('#status.saved').waitFor();
+      const result = JSON.parse(await readFile(file, 'utf8'));
+      assert.equal(result.title, 'Visual title');
+      assert.equal(result.blocks[0].columns, 1);
+      assert.equal(result.blocks[0].cells[0].length, 2);
+      assert.equal(result.blocks[0].cells[0][1].custom, 7);
+      assert.equal(result.blocks[1].cells[0][0].text, 'Typed in the visual editor');
+      assert.deepEqual(result.customSetting, sample.customSetting);
+    } finally { await browser.close(); }
+  });
+});

package/tests/page-scaffold.test.mjs

@@ -0,0 +1,125 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, mkdir, writeFile, rm, symlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { chromium } from 'playwright';
+import { createPage } from '../src/page-scaffold.js';
+import { startPageEditor } from '../src/page-editor.js';
+
+async function sandbox(run) {
+  const root = await mkdtemp(join(tmpdir(), 'edgepress-pages-create-'));
+  try { return await run(root); }
+  finally { await rm(root, { recursive: true, force: true }); }
+}
+
+test('createPage scaffolds valid localized JSON Pages without overwriting existing files', async () => {
+  await sandbox(async root => {
+    await mkdir(resolve(root, 'schemas'), { recursive: true });
+    await writeFile(resolve(root, 'schemas/pages.schema.json'), '{}');
+    const created = await createPage(root, { title: 'About This Site', locales: ['en', 'zh-CN'] });
+    assert.equal(created.path, 'about-this-site/en.json');
+    assert.equal(created.page.title, 'About This Site');
+    assert.equal(created.page.lang, 'en');
+    assert.equal(created.page.$schema, '../../../schemas/pages.schema.json');
+    assert.equal(created.page.blocks[0].cells[0][0].type, 'hero');
+    assert.deepEqual(JSON.parse(await readFile(created.file, 'utf8')), created.page);
+    await assert.rejects(createPage(root, { title: 'About This Site' }), /already exists/);
+    const translated = await createPage(root, {
+      title: '关于我们', slug: 'about-this-site', lang: 'zh-cn', locales: ['en', 'zh-CN']
+    });
+    assert.equal(translated.path, 'about-this-site/zh-cn.json');
+    assert.equal(translated.page.lang, 'zh-CN');
+    assert.notEqual(created.file, translated.file);
+    await assert.rejects(createPage(root, { title: 'No', slug: '../oops' }), /slug/);
+    await assert.rejects(createPage(root, { title: 'No', slug: 'OOPS' }), /slug/);
+    await assert.rejects(createPage(root, { title: 'No', lang: 'fr', locales: ['en'] }), /locale/);
+    const existing = resolve(root, 'content/pages/legacy/en.md');
+    await mkdir(resolve(root, 'content/pages/legacy'));
+    await writeFile(existing, '# legacy');
+    await assert.rejects(createPage(root, { title: 'Legacy' }), /already exists/);
+    assert.equal(await readFile(existing, 'utf8'), '# legacy');
+  });
+});
+
+test('createPage refuses to use a symlink as a page folder', async () => {
+  await sandbox(async root => {
+    const target = resolve(root, 'unrelated');
+    await mkdir(resolve(root, 'content/pages'), { recursive: true });
+    await mkdir(target);
+    await symlink(target, resolve(root, 'content/pages/linked'), 'dir');
+    await assert.rejects(createPage(root, { title: 'linked' }), /Unsafe/);
+  });
+});
+
+test('public editor catalog covers every supported Pages type and reusable website components', async () => {
+  const source = JSON.parse(await readFile('src/page-block-catalog.json', 'utf8'));
+  const schema = JSON.parse(await readFile('schemas/pages.schema.json', 'utf8'));
+  const types = schema.definitions.element.properties.type.enum;
+  assert.equal(types.length, 30);
+  assert.deepEqual(Object.keys(source.blocks).sort(), [...types].sort());
+  for (const [key, definition] of Object.entries(source.blocks)) {
+    assert.equal(definition.template.type, key);
+    assert.ok(definition.label && definition.category);
+  }
+  for (const type of ['link-directory', 'privacy-controller', 'media-text', 'feature-grid', 'media-viewer', 'local-tool']) {
+    assert.ok(source.blocks[type], type + ' must be supported for web and other site consumers');
+  }
+  for (const type of ['captcha', 'oembed', 'service', 'ad-slot', 'local-tool']) {
+    assert.equal(source.blocks[type].requiresSetup, true);
+  }
+});
+
+test('page API creates a page and enforces local-origin, duplicate and path restrictions', async () => {
+  await sandbox(async root => {
+    const editor = await startPageEditor({ root, port: 0, locales: ['en', 'zh-CN'] });
+    try {
+      const request = (body, origin) => fetch(editor.url + 'api/pages', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...(origin ? { Origin: origin } : {}) },
+        body: JSON.stringify(body)
+      });
+      assert.equal((await request({ title: 'Test' })).status, 403);
+      const origin = editor.url.slice(0, -1);
+      assert.equal((await request({ title: 'Test', lang: 'fr' }, origin)).status, 400);
+      assert.equal((await request({ title: 'Test', slug: '../../no' }, origin)).status, 400);
+      const created = await request({ title: 'New Page', slug: 'my-new-page', lang: 'en' }, origin);
+      assert.equal(created.status, 201);
+      const data = await created.json();
+      assert.equal(data.path, 'my-new-page/en.json');
+      assert.equal((await request({ title: 'New Page', slug: 'my-new-page' }, origin)).status, 409);
+      const onDisk = JSON.parse(await readFile(resolve(root, 'content/pages/my-new-page/en.json'), 'utf8'));
+      assert.equal(onDisk.title, 'New Page');
+      const registry = await (await fetch(editor.url + 'api/block-catalog')).json();
+      assert.equal(Object.keys(registry.blocks).length, 30);
+    } finally { await editor.close(); }
+  });
+});
+
+test('browser creates a Page and adds a specialized shared block without editing JSON', { timeout: 45000 }, async () => {
+  await sandbox(async root => {
+    const editor = await startPageEditor({ root, port: 0, locales: ['en', 'zh-CN'] });
+    const browser = await chromium.launch({ args: ['--disable-extensions'] });
+    try {
+      const page = await browser.newPage();
+      await page.goto(editor.url);
+      await page.locator('#new-page').click();
+      await page.locator('#create-title').fill('Site Information');
+      await page.locator('#create-slug').fill('site-info');
+      await page.locator('#create-lang').selectOption('en');
+      await page.getByRole('button', { name: '创建并编辑' }).click();
+      await page.waitForFunction(() => document.querySelector('#page-path')?.textContent?.includes('site-info/en.json'));
+      await page.waitForFunction(() => [...document.querySelectorAll('#canvas .canvas-cell select option')].some(option => option.value === 'privacy-controller'));
+      const selector = page.locator('#canvas .canvas-cell select').first();
+      await selector.selectOption('privacy-controller');
+      await page.locator('#canvas .canvas-cell button').filter({ hasText: '添加' }).first().click();
+      await page.locator('#save').click();
+      await page.locator('#status.saved').waitFor();
+      const saved = JSON.parse(await readFile(resolve(root, 'content/pages/site-info/en.json'), 'utf8'));
+      assert.equal(saved.title, 'Site Information');
+      assert.equal(saved.blocks[0].cells[0][1].type, 'privacy-controller');
+      assert.equal(saved.blocks[0].cells[0][1].contactLabel, '联系方式');
+      assert.equal(saved.blocks[0].cells[0][0].type, 'hero');
+    } finally { await browser.close(); await editor.close(); }
+  });
+});

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

@@ -0,0 +1,32 @@
+// Capture real guest terminal/editor/browser interactions, never host input or drawn terminal frames.
+import assert from 'node:assert/strict';
+import {mkdir,writeFile} from 'node:fs/promises';
+import {resolve} from 'node:path';
+import {chromium} from 'playwright';
+import {workbench} from './demo-workbench.mjs';
+import {recordingContext,record,closeRecording} from './desktop-recording.mjs';
+import {activate,pointAt} from './vm-desktop.mjs';
+
+const root=resolve(import.meta.dirname,'../..'),artifact=resolve(root,'tools/.recordings/cli-native');
+const output=resolve(root,'content/assets/images/previews');
+await mkdir(artifact,{recursive:true});await mkdir(output,{recursive:true});
+const browser=await chromium.connectOverCDP('http://127.0.0.1:9222');
+const context=await recordingContext(browser,{locale:'en'},artifact);
+let bench;
+try{
+ bench=await workbench({artifact,packageRoot:root,locale:'en',context});
+ const page=await context.newPage(),errors=[];page.on('pageerror',error=>errors.push(error.message));
+ await record(page,'edgepress-cli-local',async({omitWait})=>{
+  await bench.activateTerminal();await bench.newPost();
+  await bench.editPost('## A working local site\n\nThis article was created in the real CLI and saved in Geany.\n\nThe local preview runs with **npm run deploy:local**.');
+  await bench.activateTerminal();await bench.startServer({omitWait,command:'npm run deploy:local --'});
+  await activate('Chromium');await page.goto('https://edgepress-demo.test/');
+  const link=page.getByRole('link',{name:bench.title,exact:true}).first();
+  await link.waitFor();await pointAt(page,link);await link.click();
+  await page.getByRole('heading',{name:'A working local site',exact:true}).waitFor();
+  await new Promise(done=>setTimeout(done,2400));
+ },{foreground:()=>bench.activateTerminal()});
+ assert.deepEqual(errors,[]);
+ const entries=await closeRecording(context,{artifact,output,source:'tools/recordings/capture-cli-demo.mjs'});
+ await writeFile(resolve(artifact,'result.json'),JSON.stringify(entries,null,2)+'\n');
+}finally{await bench?.dispose();await browser.close();}

package/tools/recordings/demo-workbench.mjs

@@ -2,7 +2,7 @@
 // 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 {resolve,sep} 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';
@@ -23,7 +23,7 @@ export async function workbench({artifact,packageRoot,photoPath,locale,context,e
  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'));
+ if(photoPath){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')));
@@ -37,9 +37,9 @@ export async function workbench({artifact,packageRoot,photoPath,locale,context,e
  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()}={}){
+ async function startServer({omitWait=task=>task(),command='edgepress server'}={}){
   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 typeCommand(root,terminalTitle,command+' --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');});
  }

package/tools/recordings/desktop-recording.mjs

@@ -57,7 +57,7 @@ export async function record(page, name, story, {foreground} = {}) {
 }
 
 // Export the VM desktop master after the browser fixture has been disposed.
-export async function closeRecording(context, {artifact, output}) {
+export async function closeRecording(context, {artifact, output, source='tools/recordings/desktop-recording.mjs', kind}) {
   await context.close();
   const session = sessions.get(context);
   const entries = [];
@@ -81,7 +81,7 @@ export async function closeRecording(context, {artifact, output}) {
     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'};
+      date:new Date().toISOString().slice(0, 10), kind: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};
     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');