@universalcms/connect 0.0.0-stage → 0.13.0

package/dist/connector-runtime.mjs

@@ -0,0 +1,130 @@
+/** Inspect the website's runtime package without importing customer package code. */
+import { constants } from 'node:fs';
+import { lstat, open, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { supportedAstroVersion } from './astro-setup.mjs';
+import { projectRoot, readProjectFile, SetupError } from './core.mjs';
+import { isNativeFramework, inspectNativeProject } from './native-adapters.mjs';
+
+const metadataLimit = 128 * 1024;
+const plain = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const inside = (root, target) => {
+  const relative = path.relative(root, target);
+  return relative !== '' && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+};
+const exportsFor = framework => ({
+  './publication': './dist/publication.mjs',
+  './react-publication': './dist/react-publication.mjs',
+  './publication.css': './dist/publication.css',
+  './website-runtime': './dist/website-runtime.mjs',
+  './react-website': './dist/react-website.mjs',
+  './website.css': './dist/website.css',
+  ...(isNativeFramework(framework)
+    ? { './native-website': './dist/native-website.mjs', './native-website-server': './dist/native-website-server.mjs', [`./${framework === 'nuxt' ? 'vue' : framework}-runtime`]: `./dist/${framework === 'nuxt' ? 'vue' : framework}-runtime.mjs`, ...(framework === 'vue' ? {'./vue-server':'./dist/vue-server.mjs'} : {}) }
+    : framework === 'astro'
+    ? { './astro-runtime': './dist/astro-runtime.mjs', './astro-website': './dist/astro-website.mjs' }
+    : framework === 'next'
+    ? { './public-bindings': './dist/public-bindings.mjs', './next-source': './dist/next-source.mjs', './next-publication': './dist/next-publication.mjs', './website-next': './dist/website-next.mjs' }
+    : { './public-bindings': './dist/public-bindings.mjs', './vite-source': './dist/vite-source.mjs', './vite-publication': './dist/vite-publication.mjs', './vite-publication-server': './dist/vite-publication-server.mjs', './website-node': './dist/website-node.mjs' }),
+});
+
+async function metadata(filename) {
+  let handle;
+  try {
+    const before = await lstat(filename);
+    if (!before.isFile() || before.isSymbolicLink() || before.size > metadataLimit || await realpath(filename) !== filename) return null;
+    handle = await open(filename, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const opened = await handle.stat();
+    if (!opened.isFile() || opened.ino !== before.ino || opened.dev !== before.dev || opened.size > metadataLimit) return null;
+    const buffer = Buffer.alloc(metadataLimit + 1); let size = 0;
+    while (size < buffer.length) {
+      const part = await handle.read(buffer, size, buffer.length - size, size);
+      if (!part.bytesRead) break;
+      size += part.bytesRead;
+    }
+    if (size > metadataLimit) return null;
+    const current = await lstat(filename), after = await handle.stat();
+    if (current.isSymbolicLink() || current.ino !== opened.ino || current.dev !== opened.dev || after.size !== opened.size || after.mtimeMs !== opened.mtimeMs || after.ctimeMs !== opened.ctimeMs) return null;
+    const value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, size)));
+    return plain(value) ? value : null;
+  } catch { return null; }
+  finally { await handle?.close(); }
+}
+
+async function regularAsset(directory, relative) {
+  const filename = path.join(directory, relative), info = await lstat(filename);
+  return info.isFile() && !info.isSymbolicLink() && info.size > 0 && info.size <= 8 * 1024 * 1024 && inside(directory, filename) && await realpath(filename) === filename;
+}
+
+/** A cached/global CLI is not proof that the website can resolve its generated imports. */
+export async function assertConnectorRuntime(directory, framework) {
+  const root = await projectRoot(directory);
+  const fail = reason => { throw new SetupError(`Website connector runtime is not ready: ${reason} Install @universalcms/connect as a production dependency in this website folder using the install command from Developer setup, then rerun setup. The local runtime must match the CLI version; running a cached or external CLI alone is insufficient. Existing website files and keys were preserved.`); };
+  let manifest;
+  try { manifest = JSON.parse(await readProjectFile(root, 'package.json')); } catch { fail('The website package manifest is invalid.'); }
+  if (!['next', 'vite', 'astro'].includes(framework) && !isNativeFramework(framework)) fail('The selected framework needs a reviewed connector runtime.');
+  const declaration = manifest?.dependencies?.['@universalcms/connect'];
+  if (typeof declaration !== 'string' || !declaration.trim() || declaration.length > 4096 || /[\r\n\0]/.test(declaration)) fail('@universalcms/connect is not declared in dependencies. A development-only or temporary installation cannot support the website runtime.');
+  const own = await metadata(fileURLToPath(new URL('../package.json', import.meta.url)));
+  if (own?.name !== '@universalcms/connect' || typeof own.version !== 'string') fail('The executing CLI package metadata is unavailable.');
+  try {
+    const modules = path.join(root, 'node_modules');
+    if (!(await lstat(modules)).isDirectory() || await realpath(modules) !== modules) fail('The website node_modules directory is unavailable or externally linked.');
+    const scope = await realpath(path.join(modules, '@universalcms'));
+    if (!inside(modules, scope) || !(await lstat(scope)).isDirectory()) fail('The local connector package scope is unavailable.');
+    // pnpm's package directory link is accepted only within this node_modules.
+    const installed = await realpath(path.join(scope, 'connect'));
+    if (!inside(modules, installed) || !(await lstat(installed)).isDirectory()) fail('The connector package must resolve inside this website node_modules.');
+    const pkg = await metadata(path.join(installed, 'package.json'));
+    if (pkg?.name !== '@universalcms/connect' || pkg.type !== 'module' || pkg.version !== own.version || !plain(pkg.exports)) fail('The installed connector metadata or version does not match this CLI.');
+    for (const [name, target] of Object.entries(exportsFor(framework))) {
+      if (pkg.exports[name] !== target || !await regularAsset(installed, target)) fail(`The required ${name} export or file is missing or incompatible.`);
+    }
+    if (isNativeFramework(framework)) {
+      const inspection = await inspectNativeProject(root, framework, manifest);
+      for (const spec of inspection.runtimeDependencies ?? []) {
+        const declared = manifest.dependencies?.[spec.name] ?? (spec.production ? undefined : manifest.devDependencies?.[spec.name]);
+        if (spec.production && declared === undefined) fail('The native server framework must be installed as a production dependency.');
+        if (typeof declared !== 'string' || !/^[~^]?\d+\.\d+\.\d+$/.test(declared)) fail('Native framework dependencies must declare reviewed versions.');
+        const directory = await realpath(path.join(modules, spec.name));
+        if (!inside(modules, directory)) fail('Native framework dependencies must resolve inside this website node_modules.');
+        const dependency = await metadata(path.join(directory, 'package.json'));
+        const installed = dependency?.version, required = declared.replace(/^[~^]/, '');
+        const actual = String(installed).split('.').map(Number), baseline = required.split('.').map(Number);
+        if (dependency?.name !== spec.name || !/^\d+\.\d+\.\d+$/.test(installed ?? '') || !spec.majors.includes(actual[0]) || actual[1] < (spec.minimumMinor ?? 0) || actual[0] !== baseline[0] || actual[1] < baseline[1] || actual[1] === baseline[1] && actual[2] < baseline[2] || !/^[~^]/.test(declared) && installed !== declared || declared.startsWith('~') && actual[1] !== baseline[1]) fail('An installed native framework dependency is missing or incompatible with its declaration.');
+        for (const asset of spec.assets) if (!await regularAsset(directory, asset)) fail('A native framework package is incomplete. Reinstall its reviewed dependencies.');
+      }
+    }
+    if (framework === 'astro') {
+      const supported = (value, major, minimum = 0) => new RegExp(`^${major}\\.(\\d+)\\.\\d+$`).test(value ?? '') && +value.split('.')[1] >= minimum;
+      const targets = [
+        ['astro', value => supportedAstroVersion(value), ['./dist/index.js', './dist/config/entrypoint.js']],
+        ['@astrojs/node', value => supported(value, 11), ['./dist/index.js', './dist/server.js']],
+        ['@astrojs/react', value => supported(value, 7), ['./dist/index.js', './dist/client.js', './dist/server.js']],
+        ['react', value => supported(value, 19, 2), ['./index.js', './jsx-runtime.js']],
+        ['react-dom', value => supported(value, 19, 2), ['./index.js', './client.js', './server.node.js']],
+      ];
+      const versions = {};
+      for (const [name, compatible, assets] of targets) {
+        const declared = manifest.dependencies?.[name];
+        if (typeof declared !== 'string' || !/^[~^]?\d+\.\d+\.\d+$/.test(declared)) fail('Astro, its official Node/React integrations, React and React DOM must be supported production dependencies.');
+        const directory = await realpath(path.join(modules, name));
+        if (!inside(modules, directory)) fail('Astro runtime dependencies must resolve inside this website node_modules.');
+        const dependency = await metadata(path.join(directory, 'package.json'));
+        const installed = dependency?.version, required = declared.replace(/^[~^]/, '');
+        const actual = String(installed).split('.').map(Number), baseline = required.split('.').map(Number);
+        if (dependency?.name !== name || !compatible(installed) || actual[0] !== baseline[0] || actual[1] < baseline[1] || actual[1] === baseline[1] && actual[2] < baseline[2] || !/^[~^]/.test(declared) && installed !== declared || declared.startsWith('~') && actual[1] !== baseline[1]) fail('An installed Astro runtime dependency is missing or incompatible with its declaration.');
+        for (const asset of assets) if (!await regularAsset(directory, asset)) fail('An Astro runtime package is incomplete. Reinstall the reviewed production dependencies.');
+        versions[name] = installed;
+      }
+      if (versions.react !== versions['react-dom']) fail('React and React DOM must use matching versions for Astro rendering.');
+    }
+    for (const target of ['dist/vendor/react-document.mjs', 'dist/vendor/react-form.mjs', 'dist/vendor/react-safety.mjs']) {
+      if (!await regularAsset(installed, target)) fail('The bundled published-content renderer is incomplete.');
+    }
+  } catch (error) {
+    if (error instanceof SetupError) throw error;
+    fail('The installed connector package or a required runtime file is missing or unreadable.');
+  }
+}

package/dist/content-next-setup.mjs

@@ -0,0 +1,200 @@
+/** Render publications on the original Next routes with frozen source slots. */
+import path from 'node:path';
+import { lstat, readdir } from 'node:fs/promises';
+import ts from './vendor/typescript.cjs';
+import { isExcludedPublicationPath, validatePublicationConfig } from './publication.mjs';
+import { CONFIG_FILE, readProjectFile, projectRoot, SetupError, validateConfig } from './core.mjs';
+import { createTemplates } from './templates.mjs';
+import { inspectSourceRoutes } from './source-routes.mjs';
+import { transformSourcePublication } from './source-bindings.mjs';
+import { publicBindingInventory } from './public-bindings.mjs';
+import { CONTENT_BINDINGS_FILE, contentDigest, readContentRegistry, readFrozenContent } from './content-registry.mjs';
+import { inspectReviewedNativeOwnership } from './reviewed-native-ownership.mjs';
+import { matchesNativeRoutes } from './native-routes.mjs';
+import { inspectReviewedCommerceOwnership } from './reviewed-commerce-ownership.mjs';
+import { setupReviewError } from './preflight-recovery.mjs';
+const json = value => `${JSON.stringify(value, null, 2)}\n`;
+const fail = message => { throw new SetupError(message); };
+const relative = (from, to) => { const value = path.posix.relative(path.posix.dirname(from), to); return value.startsWith('.') ? value : `./${value}`; };
+// Old init/setup installations may retain the additive delivery demo. Its exact
+// generated catch-all is deliberately unavailable after full setup; it is not an
+// unknown native route. Never grant that ownership from a route name alone.
+export async function inspectOwnedDemo(root) {
+  const text = await readProjectFile(root, CONFIG_FILE);
+  if (text === null) return null;
+  let saved;
+  try { saved = validateConfig(JSON.parse(text)); }
+  catch { fail('The saved connector configuration is invalid. Restore it before running setup.'); }
+  if (saved.framework !== 'next') return null;
+  const mount = `${saved.appDirectory}${saved.mount}`, dynamic = `${mount}/[...slug]`;
+  const expected = (await createTemplates(saved)).filter(file => file.path.startsWith(`${mount}/`));
+  const observed = [{ path: CONFIG_FILE, content: text, state: 'unchanged' }];
+  for (const file of expected) {
+    const current = await readProjectFile(root, file.path);
+    if (current !== file.content) fail('A generated demo route contains different content. Review its ownership before full setup. Existing files were preserved.');
+    observed.push({ ...file, state: 'unchanged' });
+  }
+  for (const file of observed) if ((await lstat(path.join(root, file.path))).nlink !== 1) fail('A generated file is linked or changed. Existing files were preserved.');
+  for (const [directory, names] of [[mount, ['cms.server.js', '[...slug]']], [dynamic, ['page.jsx', 'error.jsx']]]) {
+    const entries = await readdir(path.join(root, directory), { withFileTypes: true });
+    if (entries.length !== names.length || entries.some(entry => !names.includes(entry.name) || entry.isSymbolicLink() || (entry.name === '[...slug]' ? !entry.isDirectory() : !entry.isFile()))) fail('The generated demo mount contains additional routes. Review its ownership before full setup.');
+  }
+  // The demo planner separately owns these files and may be updating their
+  // connection values in the same transaction. Do not duplicate its write set.
+  return { path: dynamic, files: observed };
+}
+export function nextContentPageTemplate(row, configurationFile = '.universalcms/publication.config.json') {
+  const native = relative(row.sourceFile, row.nativeFile).replace(/\.(?:[jt]sx?)$/, '');
+  const typed = row.sourceFile.endsWith('.tsx');
+  return `// Generated by @universalcms/connect. Published CMS document owns these bound slots.\nimport { cache } from 'react';\nimport { connection } from 'next/server';\nimport { notFound } from 'next/navigation';\nimport { createPublishedDocumentReader, publicPublishedEntry } from '@universalcms/connect/publication';\nimport { PublishedDocumentProvider } from '@universalcms/connect/react-publication';\nimport { publicBindingInventory } from '@universalcms/connect/public-bindings';\nimport configuration from ${JSON.stringify(relative(row.sourceFile, configurationFile))};\nimport inventory from ${JSON.stringify(relative(row.sourceFile, row.inventoryFile))};\nimport NativePage from ${JSON.stringify(native)};\n\nconst read = createPublishedDocumentReader({ configuration: configuration${typed ? " as Parameters<typeof createPublishedDocumentReader>[0]['configuration']" : ''} });\nconst load = cache(async () => {\n  await connection();\n  const result = await read(${JSON.stringify(row.path)});\n  if (result.state === 'missing') notFound();\n  if (result.state !== 'published') throw new Error('Published content is temporarily unavailable');\n  return publicPublishedEntry(result.entry);\n});\nexport async function generateMetadata() {\n  const entry = await load();\n  return { title: entry.document.title, description: entry.document.excerpt };\n}\nexport default async function Page() {\n  const entry = await load();\n  const publicInventory = publicBindingInventory(inventory${typed ? " as import('@universalcms/connect/react-publication').Inventory" : ''});\n  return <PublishedDocumentProvider initialEntry={entry} pathname=${JSON.stringify(row.path)} route={publicInventory}><NativePage /></PublishedDocumentProvider>;\n}\n`;
+}
+/** Configure request-time content/metadata only when the Next export is one
+ * literal object. Dynamic configuration is preserved and requires review. */
+function rewriteNextContentConfiguration(source, filename) {
+  const file = ts.createSourceFile(filename, source, ts.ScriptTarget.Latest, true, filename.endsWith('.ts') ? ts.ScriptKind.TS : ts.ScriptKind.JS);
+  const unbox = value => { while (value && (ts.isAsExpression(value) || ts.isSatisfiesExpression(value) || ts.isParenthesizedExpression(value))) value = value.expression; return value; };
+  const exported = file.statements.find(statement => ts.isExportAssignment(statement));
+  let object = unbox(exported?.expression);
+  if (object && ts.isIdentifier(object)) {
+    const name = object.text;
+    const declarations = file.statements.filter(ts.isVariableStatement).flatMap(statement => [...statement.declarationList.declarations]);
+    object = unbox(declarations.find(declaration => ts.isIdentifier(declaration.name) && declaration.name.text === name)?.initializer);
+  }
+  if (file.parseDiagnostics.length || !object || !ts.isObjectLiteralExpression(object) || object.properties.some(property => ts.isSpreadAssignment(property))) fail('Dynamic Next configuration needs a reviewed request-time content integration: disable Cache Components and serve published metadata in the initial HTML. Existing settings were preserved.');
+  const named = (properties, name) => properties.filter(property => property.name && (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)) && property.name.text === name);
+  const edits = [];
+  let disablesCacheComponents = false;
+  for (const name of ['cacheComponents', 'htmlLimitedBots']) {
+    const properties = named(object.properties, name);
+    if (properties.length > 1 || properties.some(property => !ts.isPropertyAssignment(property))) fail('Ambiguous Next content settings require manual review.');
+    const property = properties[0];
+    if (name === 'cacheComponents' && property) {
+      if (![ts.SyntaxKind.TrueKeyword, ts.SyntaxKind.FalseKeyword].includes(property.initializer.kind)) fail('Dynamic Cache Components settings need manual review before binding public content.');
+      if (property.initializer.kind === ts.SyntaxKind.TrueKeyword) {
+        disablesCacheComponents = true;
+        edits.push({ start: property.initializer.getStart(file), end: property.initializer.end, text: 'false' });
+      }
+    }
+    if (name === 'htmlLimitedBots') {
+      if (property && property.initializer.getText(file) !== '/.*/') edits.push({ start: property.initializer.getStart(file), end: property.initializer.end, text: '/.*/' });
+      else if (!property) edits.push({ start: object.getStart(file) + 1, end: object.getStart(file) + 1, text: '\n  htmlLimitedBots: /.*/,\n' });
+    }
+  }
+  const topPartials = named(object.properties, 'partialPrefetching');
+  if (topPartials.length > 1 || topPartials.some(property => !ts.isPropertyAssignment(property) || ![ts.SyntaxKind.TrueKeyword, ts.SyntaxKind.FalseKeyword].includes(property.initializer.kind))) fail('Dynamic partial prefetch settings need manual review.');
+  if (topPartials[0]) {
+    const property = topPartials[0];
+    let start = property.getStart(file), end = property.end;
+    const after = source.slice(end, object.end - 1).match(/^\s*,/);
+    if (after) end += after[0].length;
+    else { const before = source.slice(object.getStart(file) + 1, start).match(/,\s*$/); if (before) start -= before[0].length; }
+    edits.push({start,end,text:''});
+  }
+  const experiments = named(object.properties, 'experimental');
+  if (experiments.length > 1) fail('Ambiguous Next experimental settings need review.');
+  const experimental = experiments[0];
+  if (experimental && ts.isPropertyAssignment(experimental) && ts.isObjectLiteralExpression(experimental.initializer)) {
+    const partials = named(experimental.initializer.properties, 'partialPrefetching');
+    if (partials.length > 1) fail('Ambiguous Next partial prefetch settings need review.');
+    if (partials[0]) {
+      const property = partials[0];
+      let start = property.getStart(file), end = property.end;
+      const after = source.slice(end, experimental.initializer.end - 1).match(/^\s*,/);
+      if (after) end += after[0].length;
+      else { const before = source.slice(experimental.initializer.getStart(file) + 1, start).match(/,\s*$/); if (before) start -= before[0].length; }
+      edits.push({ start, end, text: '' });
+    }
+  } else if (experimental && /partialPrefetching/.test(experimental.getText(file))) fail('Dynamic partial prefetch settings need manual review.');
+  let output = source;
+  for (const edit of edits.sort((a, b) => b.start - a.start)) output = output.slice(0, edit.start) + edit.text + output.slice(edit.end);
+  return { source: output, disablesCacheComponents };
+}
+export function configureNextContent(source, filename) { return rewriteNextContentConfiguration(source, filename).source; }
+async function assertNoActiveCacheComponents(root) {
+  let visited = 0, bytes = 0;
+  const excluded = new Set(['node_modules', '.git', '.next', '.universalcms', 'dist', 'build', 'coverage', 'public']);
+  async function visit(relative, depth) {
+    if (depth > 12) fail('Website cache-feature review exceeds its directory budget. Review Cache Components manually.');
+    const entries = await readdir(path.join(root, relative), { withFileTypes: true });
+    for (const item of entries) {
+      if (excluded.has(item.name) || item.name.startsWith('.')) continue;
+      if (++visited > 4000) fail('Website cache-feature review exceeds its file budget. Review Cache Components manually.');
+      const name = relative ? `${relative}/${item.name}` : item.name;
+      if (item.isSymbolicLink()) fail('Linked website sources require manual review before disabling Cache Components.');
+      if (item.isDirectory()) { await visit(name, depth + 1); continue; }
+      if (!item.isFile() || !/\.[cm]?[jt]sx?$/.test(item.name) || /\.d\.ts$/.test(item.name) || /^next\.config\./.test(item.name)) continue;
+      const source = await readProjectFile(root, name);
+      bytes += Buffer.byteLength(source ?? '');
+      if (bytes > 8 * 1024 * 1024) fail('Website cache-feature review exceeds its byte budget. Review Cache Components manually.');
+      if (/['"]use cache(?:: [a-z-]+)?['"]|\b(?:cacheLife|cacheTag|unstable_cacheLife|unstable_cacheTag)\b/.test(source ?? '')) fail('This website actively uses Cache Components APIs. Preserve its cache configuration and implement a reviewed request-time CMS boundary before enabling content binding.');
+    }
+  }
+  await visit('', 0);
+}
+// Publication mapping must report unresolved native ownership before trying to
+// map reserved application paths such as /cart as CMS content. Both planners
+// use the same validated native review and exact connector-owned demo exclusion.
+export function assertNextUnresolvedRouteOwnership(inventory, nativeOwnership, demo) {
+  const unresolvedPaths = inventory.unresolvedPaths.filter(name => name !== demo?.path && !(nativeOwnership?.dynamicDirectories?.includes(name) || nativeOwnership?.profile === 'reviewed-icecream-commerce-2026-10-15' && name === 'src/app/menu/[id]'));
+  if (unresolvedPaths.length) throw setupReviewError('next-route-ownership', unresolvedPaths);
+}
+export async function planNextContent(directory, configuration) {
+  configuration = validatePublicationConfig(configuration);
+  const root = await projectRoot(directory), prior = await readContentRegistry(root), files = [];
+  const nativeOwnership = await inspectReviewedNativeOwnership(root) ?? await inspectReviewedCommerceOwnership(root);
+  if (nativeOwnership && configuration.routes.some(route => matchesNativeRoutes(nativeOwnership, route.path))) fail('Reviewed native commerce routes cannot also be CMS editorial pages. Refresh the public source inventory before enabling publication control.');
+  let foundConfiguration = false;
+  for (const extension of ['js','mjs','cjs','ts']) {
+    const filename = `next.config.${extension}`, source = await readProjectFile(root, filename);
+    if (source === null) continue;
+    if (foundConfiguration) fail('Multiple Next configuration files require manual review.');
+    foundConfiguration = true;
+    const result = rewriteNextContentConfiguration(source, filename), updated = result.source;
+    if (result.disablesCacheComponents) await assertNoActiveCacheComponents(root);
+    files.push({ path: filename, content: updated, state: updated === source ? 'unchanged' : 'update', ...(updated !== source ? { previous: source } : {}) });
+  }
+  if (!foundConfiguration) files.push({ path: 'next.config.mjs', content: 'export default { htmlLimitedBots: /.*/ };\n', state: 'create' });
+  const inventory = await inspectSourceRoutes(root), routes = [], demo = await inspectOwnedDemo(root);
+  assertNextUnresolvedRouteOwnership(inventory, nativeOwnership, demo);
+  const managedPaths = new Set(configuration.routes.map(route => route.path));
+  const unownedPaths = inventory.routes.map(route => `/${route}`).filter(pathname => !managedPaths.has(pathname) && !nativeOwnership?.nativePaths.includes(pathname) && !isExcludedPublicationPath(pathname));
+  if (unownedPaths.length) fail(`Every public website page needs explicit content ownership before full setup. Unmapped routes: ${unownedPaths.slice(0, 10).join(', ')}${unownedPaths.length > 10 ? ', …' : ''}. Add reviewed CMS mappings or a reviewed native adapter; existing routes were preserved.`);
+  if (prior?.routes.some(row => !configuration.routes.some(route => ['path','kind','slug','locale'].every(key => route[key] === row[key])))) fail('An existing content route cannot be removed or reassigned automatically.');
+  for (const route of configuration.routes) {
+    const existing = prior?.routes.find(row => row.path === route.path);
+    if (existing) {
+      const { texts } = await readFrozenContent(root, existing);
+      if (texts.source !== nextContentPageTemplate(existing)) fail('A customized Next content wrapper requires manual review.');
+      routes.push(existing);
+      for (const prefix of ['source','native','inventory','original']) files.push({ path: existing[`${prefix}File`], content: texts[prefix], state: 'unchanged' });
+      continue;
+    }
+    if (route.kind !== 'page') fail('Automatic Next source binding requires static pages. Map custom post routes through the shared renderer manually.');
+    const sourceFile = inventory.files[route.path === '/' ? 'home' : route.path.slice(1)];
+    if (!sourceFile || !/\.[jt]sx$/.test(sourceFile)) fail('Automatic content bindings require a JSX/TSX source page for each route.');
+    const source = await readProjectFile(root, sourceFile);
+    const transformed = transformSourcePublication({ source, slug: route.slug, locale: route.locale, filename: sourceFile, publicSource: true });
+    // Projection is part of planning, so unsupported source structure cannot
+    // wait until a running page serializes its client provider properties.
+    try { publicBindingInventory(transformed.inventory); }
+    catch { fail('The source needs reviewed literal public bindings before private setup. Existing files were preserved.'); }
+    const suffix = contentDigest(`${route.path}:${route.kind}:${route.slug}:${route.locale}`).slice(0, 20);
+    const nativeFile = sourceFile.replace(/\/page\.([jt]sx)$/, '/page.universalcms-native.$1');
+    const inventoryFile = `.universalcms/content/${suffix}.json`, originalFile = `.universalcms/content/${suffix}.original.txt`;
+    for (const name of [nativeFile,inventoryFile,originalFile]) if (await readProjectFile(root, name) !== null) fail('A generated content adapter path already contains a file. It was preserved.');
+    const inventoryText = json(transformed.inventory);
+    const row = { ...route, sourceFile, nativeFile, inventoryFile, originalFile, sourceHash: '', nativeHash: contentDigest(transformed.source), inventoryHash: contentDigest(inventoryText), originalHash: contentDigest(source) };
+    const wrapper = nextContentPageTemplate(row); row.sourceHash = contentDigest(wrapper);
+    // Save the immutable original and all imported dependencies before replacing
+    // its route entrypoint. Partial I/O failure must not erase the source first.
+    files.push({ path: originalFile, content: source, state: 'create' }, { path: nativeFile, content: transformed.source, state: 'create' }, { path: inventoryFile, content: inventoryText, state: 'create' }, { path: sourceFile, content: wrapper, state: 'update', previous: source });
+    routes.push(row);
+  }
+  const ownershipFiles = nativeOwnership ? [...nativeOwnership.files, ...(nativeOwnership.manifest ? [nativeOwnership.manifest] : [])] : [];
+  if (ownershipFiles.some(observed => files.some(file => file.path === observed.path && file.state !== 'unchanged'))) fail('A native reviewed dependency also needs CMS content edits. Separate shared ownership before setup; existing files were preserved.');
+  files.push(...ownershipFiles);
+  const registry = json({ version: 1, routes, ...(nativeOwnership ? { profile:nativeOwnership.profile,nativePaths:nativeOwnership.nativePaths,...(nativeOwnership.nativePatterns ? {nativePatterns:nativeOwnership.nativePatterns} : {}),files:ownershipFiles.map(file => ({path:file.path,sha256:contentDigest(file.content)})) } : {}) }), previous = await readProjectFile(root, CONTENT_BINDINGS_FILE);
+  files.push({ path: CONTENT_BINDINGS_FILE, content: registry, state: previous === null ? 'create' : previous === registry ? 'unchanged' : 'update', ...(previous !== null && previous !== registry ? { previous } : {}) });
+  if (files.some(file => Buffer.byteLength(file.content) > 128 * 1024)) fail('This content binding exceeds the safe per-file setup budget. Split its public source or use a reviewed adapter.');
+  return { root, framework: 'next', files, routes };
+}

package/dist/content-registry-validation.mjs

@@ -0,0 +1,40 @@
+import { REVIEWED_NEXT_NATIVE_PROFILE, validateNativeRoutes, isNativeReviewFilePath } from './native-routes.mjs';
+/** Pure validation for generated native content ownership. */
+const fail = message => { throw new Error(message); };
+const ordinary = value => typeof value === 'string' && value.length < 512 && !value.startsWith('/') && !value.includes('\\') && value.split('/').every(part => !!part && part !== '.' && part !== '..');
+const hash = value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+export const REVIEWED_STOREFRONT_PROFILE = 'reviewed-storefront-native-2026-10-15';
+export const REVIEWED_ICECREAM_PROFILE = 'reviewed-icecream-commerce-2026-10-15';
+const icecreamIds = ['sicilian-pistachio','madagascar-bourbon-vanilla','belgian-midnight-fudge','strawberry-wild-basil','salted-caramel-pretzel-crackle','alphonso-mango-passion-vegan','espresso-affogato-truffle','wild-blueberry-lavender','caramelized-honey-pecan','mint-matcha-stracciatella','cookie-dough-avalanche','vegan-raspberry-hibiscus','hot-fudge-brownie-sundae-bowl','artisan-4-pint-tasting-box','diy-sundae-party-kit','ruby-berry-carnival-sundae'];
+export function reviewedNativePaths(profile) {
+  if (profile === REVIEWED_STOREFRONT_PROFILE) return ['/stylist-consult','/track-order'];
+  if (profile === REVIEWED_ICECREAM_PROFILE) return ['/cart','/checkout','/order-success',...icecreamIds.map(id => '/menu/' + id)].sort();
+  return [];
+}
+export function validateContentRegistry(value) {
+  const shared = value?.profile === REVIEWED_STOREFRONT_PROFILE;
+  const native = value?.profile === REVIEWED_NEXT_NATIVE_PROFILE;
+  const reviewed = shared || value?.profile === REVIEWED_ICECREAM_PROFILE || native;
+  const keys = native ? 'files,nativePaths,nativePatterns,profile,routes,version' : reviewed ? 'files,nativePaths,profile,routes,version' : 'routes,version';
+  if (!value || value.version !== 1 || Object.keys(value).sort().join() !== keys || !Array.isArray(value.routes) || !value.routes.length || value.routes.length > 1000) fail('The content binding registry needs review.');
+  if (reviewed && (!Array.isArray(value.files) || !value.files.length || value.files.length > (native ? 201 : 100) || value.files.some(file => !file || Object.keys(file).sort().join() !== 'path,sha256' || !ordinary(file.path) || !hash(file.sha256)) || new Set(value.files.map(file => file.path)).size !== value.files.length)) fail('The reviewed shared content modules are invalid.');
+  if (native) {
+    validateNativeRoutes(value, value.routes);
+    if (!value.files.some(file => file.path === '.universalcms/native.routes.json') || value.files.some(file => file.path !== '.universalcms/native.routes.json' && !isNativeReviewFilePath(file.path))) fail('Native registry fingerprints must contain the explicit manifest and reviewed public source modules only.');
+  }
+  if (reviewed && !native && (!Array.isArray(value.nativePaths) || JSON.stringify([...value.nativePaths].sort()) !== JSON.stringify(reviewedNativePaths(value.profile)) || value.routes.some(row => value.nativePaths.includes(row?.path)))) fail('Native route ownership must match the exact reviewed profile without overlapping CMS routes.');
+  const paths = new Set(), identities = new Set(), files = new Map(), inventories = new Set();
+  for (const row of value.routes) {
+    if (!row || Object.keys(row).some(key => !['path', 'kind', 'slug', 'locale', 'sourceFile', 'nativeFile', 'inventoryFile', 'originalFile', 'sourceHash', 'nativeHash', 'inventoryHash', 'originalHash'].includes(key)) || typeof row.path !== 'string' || !/^\/(?:[a-z0-9]+(?:[-/][a-z0-9]+)*)?$/.test(row.path) || !['page', 'post'].includes(row.kind) || typeof row.slug !== 'string' || !/^[a-z0-9]+(?:[-/][a-z0-9]+)*$/.test(row.slug) || typeof row.locale !== 'string' || !['sourceFile','nativeFile','inventoryFile','originalFile'].every(key => ordinary(row[key])) || !['sourceHash','nativeHash','inventoryHash','originalHash'].every(key => hash(row[key]))) fail('A content binding route is invalid.');
+    let locale; try { locale = Intl.getCanonicalLocales(row.locale)[0]; } catch { fail('A content binding locale is invalid.'); }
+    const identity = `${row.kind}:${locale}:${row.slug}`;
+    if (paths.has(row.path) || identities.has(identity) || inventories.has(row.inventoryFile) || row.sourceFile === row.nativeFile) fail('Content binding routes must have unique paths, identities and inventories.');
+    for (const prefix of ['source', 'native', 'original']) {
+      const name = row[`${prefix}File`], digest = row[`${prefix}Hash`], previous = files.get(name);
+      if (previous && (!shared || previous !== `${prefix}:${digest}`)) fail('Shared content modules require an exact reviewed profile and consistent ownership.');
+      files.set(name, `${prefix}:${digest}`);
+    }
+    paths.add(row.path); identities.add(identity); inventories.add(row.inventoryFile);
+  }
+  return value;
+}

package/dist/content-registry.mjs

@@ -0,0 +1,44 @@
+import { createHash } from 'node:crypto';
+import { lstat } from 'node:fs/promises';
+import path from 'node:path';
+import { readProjectFile, SetupError } from './project-files.mjs';
+export const CONTENT_BINDINGS_FILE = '.universalcms/content.bindings.json';
+export const contentDigest = text => createHash('sha256').update(text).digest('hex');
+const fail = message => { throw new SetupError(message); };
+import { REVIEWED_NEXT_NATIVE_PROFILE } from './native-routes.mjs';
+import { inspectReviewedNativeOwnership } from './reviewed-native-ownership.mjs';
+import { validateContentRegistry } from './content-registry-validation.mjs';
+export { validateContentRegistry, REVIEWED_STOREFRONT_PROFILE, REVIEWED_ICECREAM_PROFILE, reviewedNativePaths } from './content-registry-validation.mjs';
+export async function readContentRegistry(root) {
+  const text = await readProjectFile(root, CONTENT_BINDINGS_FILE);
+  if (text === null) return null;
+  if ((await lstat(path.join(root, CONTENT_BINDINGS_FILE))).nlink !== 1) fail('Content bindings cannot be linked files.');
+  let value;
+  try { value = JSON.parse(text); } catch { fail('The content binding registry is invalid. Preserve it and review the integration.'); }
+  validateContentRegistry(value);
+  for (const file of value.files ?? []) {
+    const current = await readProjectFile(root, file.path);
+    if (current === null || contentDigest(current) !== file.sha256 || (await lstat(path.join(root, file.path))).nlink !== 1) fail('A reviewed shared content module changed. Preserve its edits and review the native CMS bindings before setup or deployment.');
+  }
+  if (value.profile === REVIEWED_NEXT_NATIVE_PROFILE) {
+    const review = await inspectReviewedNativeOwnership(root);
+    const files = review && [...review.files, review.manifest].map(file => ({path:file.path,sha256:contentDigest(file.content)}));
+    if (!review || JSON.stringify(review.nativePaths) !== JSON.stringify(value.nativePaths) || JSON.stringify(review.nativePatterns) !== JSON.stringify(value.nativePatterns) || JSON.stringify(files) !== JSON.stringify(value.files)) fail('Native route ownership changed. Review the explicit manifest and content bindings before continuing.');
+  }
+  return value;
+}
+export async function readFrozenContent(root, row) {
+  // Shared imported components are as authoritative as their route entrypoint.
+  // Never validate only a frozen JSON baseline while ignoring edited modules.
+  await readContentRegistry(root);
+  const texts = {};
+  for (const prefix of ['source','native','inventory','original']) {
+    const file = row[`${prefix}File`], text = await readProjectFile(root, file);
+    if (text === null || contentDigest(text) !== row[`${prefix}Hash`] || (await lstat(path.join(root, file))).nlink !== 1) fail('A bound content source or baseline changed. Preserve your edits and review its stable CMS bindings before setup or deployment.');
+    texts[prefix] = text;
+  }
+  let inventory; try { inventory = JSON.parse(texts.inventory); } catch { fail('The frozen content inventory is invalid.'); }
+  if (!inventory || !inventory.identity || ['kind','slug','locale'].some(key => inventory.identity[key] !== row[key]) || inventory.baseline?.schemaVersion !== 1 || !Array.isArray(inventory.baseline?.blocks) || !inventory.bindings || typeof inventory.bindings !== 'object') fail('The frozen content inventory does not match its registered route.');
+  const entry = { kind: row.kind, slug: row.slug, locale: row.locale, document: inventory.baseline };
+  return { inventory, entry, texts };
+}

package/dist/content-setup.mjs

@@ -0,0 +1,13 @@
+/** Published-content setup is separate from source import and availability. */
+import { planAstroContent } from './astro-source.mjs';
+import { planNextContent } from './content-next-setup.mjs';
+import { planViteContent } from './content-vite-setup.mjs';
+import { isNativeFramework, planNativeContent } from './native-adapters.mjs';
+
+export function planContentSetup(root, publication, sourcePlan) {
+  if (isNativeFramework(publication.framework)) return planNativeContent(root, publication.framework, publication.config);
+  if (publication.framework === 'astro') return planAstroContent(root, publication.config);
+  return publication.framework === 'vite'
+    ? planViteContent(root, publication.config, sourcePlan)
+    : planNextContent(root, publication.config);
+}