edgepress 2026.10.13 → 2026.10.14

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(); }
+  });
+});