@universalcms/connect 0.1.0 → 0.13.0

package/dist/preflight.mjs

@@ -0,0 +1,138 @@
+/** Read-only original-route planning. No credentials, project execution or requests. */
+import { analyze, CONFIG_FILE, planSetup, projectRoot, readProjectFile, SetupError, validateConfig, validatePlan } from './core.mjs';
+import { inspectSetupFramework } from './framework.mjs';
+import { assertConnectorRuntime } from './connector-runtime.mjs';
+import { assertRuntimeDependencies } from './runtime-dependencies.mjs';
+import { readConnection, validateConnection } from './staged-setup.mjs';
+import { setupSource, readSourceSettings, validateSourcePlan } from './source-setup.mjs';
+import { planPublicationSetup, planInstalledPublication, readPublicationConfiguration } from './publication-setup.mjs';
+import { planContentSetup } from './content-setup.mjs';
+import { assertPlannedSettingsCompatibility } from './website-setup.mjs';
+import { setupReviewDiagnostic, setupRecovery } from './preflight-recovery.mjs';
+
+const fields = ['apiOrigin', 'siteId', 'environmentId', 'locale', 'websiteOrigin', 'adminOrigin'];
+const labels = new Set(['Next.js', 'React', 'Vue', 'Nuxt', 'Angular', 'Astro', 'SvelteKit', 'Laravel', 'WordPress', 'Static', 'Custom']);
+const guidance = {
+  project: 'Open the actual website project folder. Its ordinary public files must be readable.',
+  framework: 'Automatic original-route setup requires a compatible reviewed Next.js, React/Vite, Astro, Vue, Nuxt, Angular SSR, SvelteKit or literal HTML project. WordPress uses its native plugin and WP-CLI. Review conflicting framework evidence, custom servers and unsupported versions before continuing. Other frameworks require their existing server or private-build adapter from Developer setup; changing the selected framework label cannot install an adapter.',
+  runtime: 'Install the matching @universalcms/connect release as a production dependency in this website folder using Developer setup. A cached or external CLI is insufficient. Restore missing local runtime files before continuing.',
+  'public-scope': 'Provide the six public Developer setup values, or use this folder’s saved public connection. They must match existing connection, source, publication and delivery configuration. Private environment values are never used by preflight.',
+  'installed-integration': 'Existing integration files are incomplete, customized or use a different scope. Preserve them and review the existing adapter before continuing. Do not rerun scaffold setup or replace a key to repair a missing adapter.',
+  source: 'The public source inventory or its route ownership needs review. Preserve custom adapters and explicitly map public content; private, dynamic and custom-router routes cannot be guessed.',
+  publication: 'Original website URLs need an exact reviewed publication mapping and compatible server routes. Preserve existing routes and adapters before continuing.',
+  content: 'The original website renderer needs reviewed content bindings. Preserve native interactions and route ownership; source import alone does not connect published edits.',
+  settings: 'The native header, footer or route ownership needs a reviewed settings adapter. Preserve native navigation and compose the shared settings components before continuing.',
+};
+const summary = 'Read-only plan only. No files, keys or CMS data changed. A successful plan does not verify key access, installation, live delivery or rendered settings. Run the reviewed setup, restart or deploy, then check publication and settings and verify the actual website.';
+const requireMatch = (saved, requested, names) => {
+  if (names.some(name => saved[name] !== requested[name])) throw Error('Public scope mismatch');
+};
+
+// assertConnectionMatches also inspects private environment settings. Preflight
+// deliberately compares only separately validated public configuration instead.
+async function publicConnection(root, options) {
+  if (!options || typeof options !== 'object' || Array.isArray(options) || Object.keys(options).some(name => !fields.includes(name))) throw Error('Public options only');
+  const saved = await readConnection(root);
+  const entered = Object.fromEntries(Object.entries(options).filter(([, value]) => value !== undefined));
+  const connection = validateConnection({ version: 1, locale: 'en', ...(saved ?? {}), ...entered });
+  if (saved) requireMatch(saved, connection, fields);
+  const configText = await readProjectFile(root, CONFIG_FILE);
+  const config = configText === null ? null : validateConfig(JSON.parse(configText));
+  if (config) requireMatch(config, connection, ['apiOrigin', 'siteId', 'environmentId', 'locale']);
+  const source = await readSourceSettings(root);
+  if (Object.keys(source).length) requireMatch(source, connection, fields.filter(name => name !== 'apiOrigin'));
+  const publication = await readPublicationConfiguration(root);
+  if (publication) {
+    requireMatch(publication, connection, ['apiOrigin', 'siteId', 'environmentId', 'websiteOrigin']);
+    if (publication.routes.some(route => route.locale !== connection.locale)) throw Error('Publication locale mismatch');
+  }
+  return { connection, config, publication };
+}
+
+async function unchangedInstallation(root, plan) {
+  if (!plan || plan.files.some(file => file.state !== 'unchanged')) throw Error('Incomplete installation');
+  await validatePlan(plan);
+  for (const file of plan.files) if (await readProjectFile(root, file.path) !== file.content) throw Error('Changed installation');
+}
+
+/** Typed public diagnostics only; raw planner/parser errors remain redacted. */
+export async function preflightSetup(directory, options = {}) {
+  let phase = 'project', framework = 'Custom', installed = false;
+  let frameworkMessage, publicScope;
+  const checks = {}, plans = [];
+  const settings = { status: 'review-required', installed: false, liveVerified: false };
+  try {
+    const root = await projectRoot(directory);
+    phase = 'framework';
+    const analysis = await analyze(root);
+    framework = labels.has(analysis.framework) ? analysis.framework : 'Custom';
+    let detected;
+    try { detected = await inspectSetupFramework(root, { analysis }); }
+    catch (error) {
+      // The framework inspector constructs fixed guidance from allowlisted
+      // labels and reasons, never customer source, versions or script text.
+      if (error instanceof SetupError) frameworkMessage = error.message;
+      throw error;
+    }
+    framework = detected.label;
+    checks.framework = 'planned';
+    phase = 'runtime';
+    await assertConnectorRuntime(root, detected.framework);
+    checks.runtime = 'planned';
+    phase = 'public-scope';
+    const { connection, config, publication: previousPublication } = await publicConnection(root, options);
+    publicScope = connection;
+    checks.publicScope = 'planned';
+    phase = 'installed-integration';
+    const settingsManifest = await readProjectFile(root, '.universalcms/website.integration.json');
+    const installedPublication = await planInstalledPublication(root);
+    if (previousPublication) await unchangedInstallation(root, installedPublication);
+    if (config) {
+      const demo = await planSetup(root, { ...config });
+      await unchangedInstallation(root, demo);
+      await assertRuntimeDependencies(root, detected.framework, connection.adminOrigin);
+      plans.push(demo);
+    }
+    if (settingsManifest !== null) {
+      if (!previousPublication) throw Error('Missing installed publication scope');
+      const source = await setupSource(root, { ...Object.fromEntries(fields.filter(name => name !== 'apiOrigin').map(name => [name, connection[name]])), publication: true });
+      if (source.retainedAdapter || source.files.some(file => file.state !== 'unchanged')) throw Error('Installed source needs review');
+      await validateSourcePlan(source);
+      plans.push(installedPublication, source);
+      installed = true;
+      checks.source = checks.publication = checks.content = 'preserved';
+      settings.status = 'preserved'; settings.installed = true;
+    } else {
+      if (!previousPublication && await readProjectFile(root, '.universalcms/content.bindings.json') !== null) throw Error('Missing installed publication scope');
+      phase = 'source';
+      const source = await setupSource(root, { ...Object.fromEntries(fields.filter(name => name !== 'apiOrigin').map(name => [name, connection[name]])), publication: true });
+      checks.source = 'planned';
+      phase = 'publication';
+      const publication = await planPublicationSetup(root, connection, source);
+      checks.publication = 'planned';
+      phase = 'content';
+      const content = await planContentSetup(root, publication, source);
+      checks.content = 'planned';
+      phase = 'settings';
+      await assertPlannedSettingsCompatibility(root, content, publication);
+      // Settings require the installed content registry. Do not pretend that a
+      // future layout/settings plan has been installed or visually verified.
+      phase = 'source'; await validateSourcePlan(source);
+      phase = 'publication'; await validatePlan(publication);
+      phase = 'content'; await validatePlan(content);
+      plans.push(source, publication, content);
+    }
+    const files = new Map();
+    for (const plan of plans) for (const file of plan.files) {
+      const prior = files.get(file.path);
+      if (!prior || prior === 'unchanged') files.set(file.path, file.state);
+    }
+    const counts = Object.fromEntries(['create', 'update', 'unchanged'].map(state => [state, [...files.values()].filter(value => value === state).length]));
+    return { status: 'planned', framework, checks, installed, settings, files: counts, liveVerified: false, renderedVerified: false, message: summary };
+  } catch (error) {
+    const known = setupReviewDiagnostic(error);
+    const message = known?.message ?? (phase === 'framework' && frameworkMessage ? frameworkMessage : guidance[phase]);
+    const blocker = known ?? { code: `${phase}-review-required`, stage: phase, message, paths: [], omittedPathCount: 0 };
+    return { status: 'review-required', framework, phase, checks, installed: false, settings, liveVerified: false, renderedVerified: false, message, blockers: [blocker], recovery: setupRecovery({ phase, framework, blocker, connection: publicScope }), limitation: summary };
+  }
+}

package/dist/project-files.mjs

@@ -0,0 +1,56 @@
+/**
+ * Bounded, symlink-safe project file access. Kept free of setup tooling so
+ * website runtimes (for example the Next source route) can import it without
+ * bundling framework compilers.
+ */
+import { constants } from 'node:fs';
+import { lstat, realpath, open } from 'node:fs/promises';
+import path from 'node:path';
+
+export class SetupError extends Error {}
+const fail = message => { throw new SetupError(message); };
+const maxFileBytes = 128 * 1024;
+
+export async function projectRoot(directory) {
+  const requested = path.resolve(directory);
+  const stat = await lstat(requested);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) fail('Choose an ordinary project directory, not a symbolic link.');
+  return realpath(requested);
+}
+
+/** Every segment is checked before reading or creating; external symlinks are never followed. */
+export async function inspect(root, relative, directory = false) {
+  if (typeof relative !== 'string' || !relative || relative.includes('\\') || path.isAbsolute(relative) || relative.split('/').some(part => !part || part === '.' || part === '..')) fail('Unsafe generated path.');
+  let target = root;
+  const segments = relative.split('/');
+  for (let index = 0; index < segments.length; index++) {
+    target = path.join(target, segments[index]);
+    let stat;
+    try { stat = await lstat(target); }
+    catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+    if (stat.isSymbolicLink() || await realpath(target) !== target) fail('A setup path is a symbolic link. Use ordinary project files.');
+    const shouldBeDirectory = index < segments.length - 1 || directory;
+    if (shouldBeDirectory ? !stat.isDirectory() : !stat.isFile()) fail('A setup path has an incompatible file type.');
+    if (index === segments.length - 1) return { target, stat };
+  }
+}
+
+export async function readProjectFile(root, relative) {
+  const found = await inspect(root, relative);
+  if (!found) return null;
+  if (found.stat.size > maxFileBytes) fail('A setup file exceeds the read limit.');
+  const handle = await open(found.target, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.ino !== found.stat.ino || stat.dev !== found.stat.dev || stat.size > maxFileBytes) fail('A project file changed during inspection. Retry setup.');
+    const buffer = Buffer.alloc(maxFileBytes + 1);
+    let bytes = 0;
+    while (bytes < buffer.length) {
+      const result = await handle.read(buffer, bytes, buffer.length - bytes, bytes);
+      if (!result.bytesRead) break;
+      bytes += result.bytesRead;
+    }
+    if (bytes > maxFileBytes) fail('A setup file exceeds the read limit.');
+    return new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, bytes));
+  } finally { await handle.close(); }
+}

package/dist/public-bindings.d.mts

@@ -0,0 +1,3 @@
+import type { Inventory } from './react-publication.mjs';
+export function bindingTextFingerprint(text: string): string;
+export function publicBindingInventory(inventory: unknown): Inventory & { publicSource: 1; fingerprints: { title: string; excerpt: string; blocks: Record<string,string> } };

package/dist/public-bindings.mjs

@@ -0,0 +1,28 @@
+/** Public comparison metadata for proved literal React source bindings.
+ * These fingerprints select rendering behavior; they confer no authorization. */
+const constants = [0x428a2f98,0x71374491,0xb5c0fbcf,0xe9b5dba5,0x3956c25b,0x59f111f1,0x923f82a4,0xab1c5ed5,0xd807aa98,0x12835b01,0x243185be,0x550c7dc3,0x72be5d74,0x80deb1fe,0x9bdc06a7,0xc19bf174,0xe49b69c1,0xefbe4786,0x0fc19dc6,0x240ca1cc,0x2de92c6f,0x4a7484aa,0x5cb0a9dc,0x76f988da,0x983e5152,0xa831c66d,0xb00327c8,0xbf597fc7,0xc6e00bf3,0xd5a79147,0x06ca6351,0x14292967,0x27b70a85,0x2e1b2138,0x4d2c6dfc,0x53380d13,0x650a7354,0x766a0abb,0x81c2c92e,0x92722c85,0xa2bfe8a1,0xa81a664b,0xc24b8b70,0xc76c51a3,0xd192e819,0xd6990624,0xf40e3585,0x106aa070,0x19a4c116,0x1e376c08,0x2748774c,0x34b0bcb5,0x391c0cb3,0x4ed8aa4a,0x5b9cca4f,0x682e6ff3,0x748f82ee,0x78a5636f,0x84c87814,0x8cc70208,0x90befffa,0xa4506ceb,0xbef9a3f7,0xc67178f2];
+const rotate=(x,n)=>(x>>>n)|(x<<(32-n));
+export function bindingTextFingerprint(text) {
+  if(typeof text!=='string')throw Error('Invalid public binding text');
+  const bytes=new TextEncoder().encode(text);
+  if(bytes.length>2*1024*1024)throw Error('Public binding text exceeds its budget');
+  const buffer=new Uint8Array(Math.ceil((bytes.length+9)/64)*64);buffer.set(bytes);buffer[bytes.length]=0x80;
+  const view=new DataView(buffer.buffer);view.setUint32(buffer.length-4,bytes.length*8);
+  const hash=[0x6a09e667,0xbb67ae85,0x3c6ef372,0xa54ff53a,0x510e527f,0x9b05688c,0x1f83d9ab,0x5be0cd19],words=new Uint32Array(64);
+  for(let offset=0;offset<buffer.length;offset+=64){
+    for(let i=0;i<16;i++)words[i]=view.getUint32(offset+i*4);
+    for(let i=16;i<64;i++){const x=words[i-15],y=words[i-2];words[i]=((rotate(x,7)^rotate(x,18)^(x>>>3))+words[i-16]+(rotate(y,17)^rotate(y,19)^(y>>>10))+words[i-7])>>>0;}
+    let [a,b,c,d,e,f,g,h]=hash;
+    for(let i=0;i<64;i++){const t1=(h+(rotate(e,6)^rotate(e,11)^rotate(e,25))+((e&f)^(~e&g))+constants[i]+words[i])>>>0,t2=((rotate(a,2)^rotate(a,13)^rotate(a,22))+((a&b)^(a&c)^(b&c)))>>>0;h=g;g=f;f=e;e=(d+t1)>>>0;d=c;c=b;b=a;a=(t1+t2)>>>0;}
+    for(const [i,value]of [a,b,c,d,e,f,g,h].entries())hash[i]=(hash[i]+value)>>>0;
+  }
+  return hash.map(word=>word.toString(16).padStart(8,'0')).join('');
+}
+export function publicBindingInventory(inventory) {
+  if(!inventory?.identity||!inventory.baseline||!Array.isArray(inventory.baseline.blocks)||!inventory.bindings)throw Error('Literal public bindings need reviewed inventory');
+  const baseline=inventory.baseline,blocks=baseline.blocks;
+  if(blocks.length>1000||blocks.some(block=>!['heading','paragraph','list','quote','code'].includes(block.type)||typeof block.text!=='string'||block.data&&Object.keys(block.data).some(name=>name!=='level'))||Object.values(inventory.bindings).some(slot=>!Array.isArray(slot.variants)||slot.variants.length!==1||slot.variants[0].values.length))throw Error('Data-driven or structured public bindings need explicit source review');
+  const known=new Set(blocks.map(block=>block.id));
+  const bindings=Object.fromEntries(Object.entries(inventory.bindings).map(([slot,value])=>{if(!known.has(value.variants[0].id))throw Error('Unknown public binding block');return [slot,{variants:[{values:[],id:value.variants[0].id}]}];}));
+  return {publicSource:1,identity:{kind:inventory.identity.kind,slug:inventory.identity.slug,locale:inventory.identity.locale},baseline:{schemaVersion:1,title:'',excerpt:'',blocks:blocks.map(block=>({id:block.id,version:block.version,type:block.type,text:'',...(block.type==='heading'&&block.data?.level?{data:{level:block.data.level}}:{})}))},titleBlockId:inventory.titleBlockId,excerptBlockId:inventory.excerptBlockId??blocks.find(block=>block.type==='paragraph')?.id,bindings,fingerprints:{title:bindingTextFingerprint(baseline.title),excerpt:bindingTextFingerprint(baseline.excerpt),blocks:Object.fromEntries(blocks.map(block=>[block.id,bindingTextFingerprint(block.text)]))}};
+}

package/dist/publication-browser.d.mts

@@ -0,0 +1,5 @@
+export const PUBLICATION_STATUS_PATH: '/api/universalcms/publication';
+export const PUBLICATION_DOCUMENT_PATH: '/api/universalcms/document';
+export const PUBLICATION_SCRIPT_PATH: '/.well-known/universalcms-publication-client.js';
+/** Server-side generator. Output includes only reviewed public paths. */
+export function createPublicationBrowserScript(configuration: unknown): string;

package/dist/publication-browser.mjs

@@ -0,0 +1,258 @@
+import { validatePublicationConfig } from './publication.mjs';
+
+export const PUBLICATION_STATUS_PATH = '/api/universalcms/publication';
+export const PUBLICATION_DOCUMENT_PATH = '/api/universalcms/document';
+export const PUBLICATION_SCRIPT_PATH = '/.well-known/universalcms-publication-client.js';
+
+/** This function is serialized, not imported into the customer's application. */
+function publicationBrowser(paths, endpoint) {
+  'use strict';
+  const managed = new Set(paths);
+  const nativeFetch = window.fetch.bind(window);
+  const assign = window.location.assign.bind(window.location);
+  const reload = window.location.reload.bind(window.location);
+  let lastUrl = window.location.href, leaving = false, pending = null, baseline = null;
+  const validRevision = value => typeof value === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}:\d{1,16}(?::[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})?$/i.test(value);
+  function canonical(pathname) {
+    try {
+      const value = decodeURIComponent(pathname);
+      if (/[\\\u0000-\u0020\u007f?#%]/.test(value) || value.includes('//') || value.split('/').some(part => part === '.' || part === '..')) return null;
+      const path = value.length > 1 ? value.replace(/\/$/, '') : value;
+      return path === '/index.html' && managed.has('/') ? '/' : path;
+    } catch { return null; }
+  }
+  const owns = pathname => managed.has(canonical(pathname));
+  async function smallJson(response, signal) {
+    if (response.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase() !== 'application/json' ||
+        Number(response.headers.get('content-length') ?? 0) > 512 || !response.body) throw Error('Unavailable');
+    const reader = response.body.getReader(), decoder = new TextDecoder('utf-8', { fatal: true });
+    let text = '', bytes = 0;
+    try {
+      for (;;) {
+        const next = await new Promise((resolve, reject) => {
+          const abort = () => reject(Error('Unavailable'));
+          signal.addEventListener('abort', abort, { once: true });
+          if (signal.aborted) abort();
+          reader.read().then(value => { signal.removeEventListener('abort', abort); resolve(value); }, error => { signal.removeEventListener('abort', abort); reject(error); });
+        });
+        if (next.done) break;
+        if ((bytes += next.value.byteLength) > 512) throw Error('Unavailable');
+        text += decoder.decode(next.value, { stream: true });
+      }
+      return JSON.parse(text + decoder.decode());
+    } finally { void reader.cancel().catch(() => {}); reader.releaseLock(); }
+  }
+  const publishedStatus = value => value && value.state === 'published' && Object.keys(value).every(key => key === 'state' || key === 'revision') && (!Object.hasOwn(value, 'revision') || validRevision(value.revision));
+
+  // Managed navigation uses the same publication authority as original URLs.
+  // Keep native anchor nodes, handlers and accessibility attributes intact.
+  let refreshLinks = () => {};
+  function installManagedLinks() {
+    if (typeof document.querySelectorAll !== 'function') return;
+    // A blocking bootstrap can run before React hydrates server-rendered links.
+    // CSSOM rules change visibility without changing that server DOM (including
+    // head children), so hydration keeps the original anchors and their handlers.
+    let sheet;
+    try {
+      sheet = new CSSStyleSheet();
+      document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];
+    } catch { leaving = true; replaceDocument(503); return; }
+    const cache = new Map(), inFlight = new Map();
+    let active = 0, scheduled = false, latest = new Map(), overflow = new Set(), epoch = 0;
+    function destination(link) {
+      try { const url = new URL(link.getAttribute('href'), window.location.href); return url.origin === window.location.origin && owns(url.pathname) ? canonical(url.pathname) : null; }
+      catch { return null; }
+    }
+    function updateVisibility() {
+      if (leaving) return;
+      const hidden = new Set(overflow);
+      for (const [path, hrefs] of latest) {
+        const known = cache.get(path);
+        if (known?.published && known.until > Date.now()) continue;
+        for (const href of hrefs) hidden.add(href);
+      }
+      // Escape every code point as a CSS string token. A literal href may contain
+      // quotes, backslashes or CSS-looking query text; none can create a rule.
+      const quoted = value => '"' + Array.from(value, character => '\\' + character.codePointAt(0).toString(16) + ' ').join('') + '"';
+      try { sheet.replaceSync(Array.from(hidden, href => 'a[href=' + quoted(href) + ']{display:none!important}').join('\n')); }
+      catch { leaving = true; replaceDocument(503); }
+    }
+    function scan(force = false) {
+      scheduled = false;
+      if (leaving || document.visibilityState === 'hidden') return;
+      if (force) { cache.clear(); epoch++; for (const controller of inFlight.values()) controller.abort(); }
+      latest = new Map(); overflow = new Set();
+      let count = 0;
+      for (const link of document.querySelectorAll('a[href]')) {
+        const path = destination(link);
+        if (!path) continue;
+        const href = link.getAttribute('href');
+        // Identical hrefs share a selector. Conservatively keep their whole group
+        // hidden when any member exceeds the scan budget, without marking nodes.
+        if (++count > 200) { overflow.add(href); continue; }
+        if (!latest.has(path)) latest.set(path, new Set());
+        latest.get(path).add(href);
+      }
+      updateVisibility();
+      pump();
+    }
+    function pump() {
+      if (leaving) { for (const controller of inFlight.values()) controller.abort(); return; }
+      if (document.visibilityState === 'hidden') return;
+      for (const [path] of latest) {
+        if (active >= 4) break;
+        if (inFlight.has(path) || (cache.get(path)?.until ?? 0) > Date.now()) continue;
+        active++;
+        const controller = new AbortController(), started = epoch; inFlight.set(path, controller);
+        const timeout = setTimeout(() => controller.abort(), 10000);
+        void (async () => {
+          let published = false;
+          try {
+            const response = await nativeFetch(endpoint + '?path=' + encodeURIComponent(path), { credentials: 'omit', cache: 'no-store', redirect: 'error', signal: controller.signal, headers: { Accept: 'application/json' } });
+            if (response.status === 200) published = publishedStatus(await smallJson(response, controller.signal));
+            else void response.body?.cancel().catch(() => {});
+          } catch { /* Missing, failed and malformed responses keep links hidden. */ }
+          finally {
+            clearTimeout(timeout); active--; inFlight.delete(path);
+            if (started === epoch) {
+              cache.set(path, { until: Date.now() + 15000, published });
+              updateVisibility();
+            }
+            pump();
+          }
+        })();
+      }
+    }
+    refreshLinks = force => scan(force);
+    if (typeof MutationObserver === 'function') new MutationObserver(() => {
+      if (!scheduled && !leaving) { scheduled = true; setTimeout(() => scan(), 0); }
+    }).observe(document.documentElement, { childList: true, subtree: true, attributes: true, attributeFilter: ['href'] });
+    scan();
+  }
+  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', installManagedLinks, { once: true });
+  else installManagedLinks();
+  function renderedRevision(pathname) {
+    // The binding provider writes this only after rendering that publication.
+    // It is read lazily because this blocking script runs before the page body.
+    const meta = document.querySelector('meta[name="universalcms-publication-revision"]');
+    return meta && canonical(meta.getAttribute('data-path')) === pathname && validRevision(meta.content) ? meta.content : null;
+  }
+  function replaceDocument(status) {
+    const missing = status === 404;
+    // Replacing the document removes native content, portals and framework event
+    // listeners. A CSS overlay alone would leave the old document accessible.
+    window.stop();
+    document.open();
+    document.write('<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="robots" content="noindex"><title>' + (missing ? '404 — Page not found' : status === 0 ? 'Loading page' : 'Content unavailable') + '</title></head><body><main style="max-width:42rem;margin:12vh auto;padding:2rem;font-family:system-ui,sans-serif"><h1>' + (missing ? '404 — Page not found' : status === 0 ? 'Loading page…' : 'Content unavailable') + '</h1><p>' + (missing ? 'This page is not published or does not exist.' : status === 0 ? 'Checking the current publication.' : 'Please try again shortly.') + '</p><a href="/">Home</a></main></body></html>');
+    document.close();
+  }
+  function navigate(destination, replace) {
+    if (leaving) return;
+    leaving = true;
+    if (pending) pending.abort();
+    replaceDocument(0);
+    if (replace) window.location.replace(destination); else assign(destination);
+  }
+  async function recheck() {
+    if (leaving || pending || document.visibilityState === 'hidden' || !owns(window.location.pathname)) return;
+    const url = window.location.href, controller = new AbortController();
+    pending = controller;
+    const deadline = setTimeout(() => controller.abort(), 10000);
+    try {
+      const response = await nativeFetch(endpoint + '?path=' + encodeURIComponent(canonical(window.location.pathname)), { credentials: 'omit', cache: 'no-store', redirect: 'error', signal: controller.signal, headers: { Accept: 'application/json', 'X-UniversalCMS-Include-Revision': '1' } });
+      // The endpoint has a tiny fixed envelope. Read text only within the same
+      // deadline; malformed/non-JSON/redirected responses cannot authorize HTML.
+      const result = await smallJson(response, controller.signal);
+      if (url !== window.location.href || leaving) return;
+      if (response.status === 200 && publishedStatus(result)) {
+        if (result.revision) {
+          const path = canonical(window.location.pathname), before = renderedRevision(path) ?? baseline;
+          if (before !== null && before !== result.revision) {
+            // A native React provider may update props in place to preserve
+            // cart/form/filter state. It must own errors and update the meta only
+            // after the new document is rendered. Unhandled changes reload once.
+            const event = new CustomEvent('universalcms:publication-change', { detail: { path, revision: result.revision }, cancelable: true });
+            if (window.dispatchEvent(event)) { leaving = true; replaceDocument(0); reload(); }
+            return;
+          }
+          baseline = result.revision;
+        }
+        return;
+      }
+      leaving = true;
+      replaceDocument(response.status === 404 && result?.state === 'missing' ? 404 : 503);
+    } catch {
+      if (url === window.location.href && !leaving) { leaving = true; replaceDocument(503); }
+    } finally {
+      clearTimeout(deadline);
+      if (pending === controller) pending = null;
+    }
+  }
+  // Intercept before React/Next registers its router. A managed transition must
+  // pass the server boundary, including a previously prefetched/cached route.
+  document.addEventListener('click', event => {
+    if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.altKey || event.shiftKey) return;
+    const link = event.target instanceof Element ? event.target.closest('a[href]') : null;
+    if (!link || link.hasAttribute('download') || link.target && link.target !== '_self') return;
+    let destination;
+    try { destination = new URL(link.href, window.location.href); } catch { return; }
+    if (destination.origin !== window.location.origin || (!owns(destination.pathname) && !owns(window.location.pathname))) return;
+    if (destination.pathname === window.location.pathname && destination.search === window.location.search && destination.hash) return;
+    event.preventDefault(); event.stopImmediatePropagation();
+    navigate(destination.href, false);
+  }, true);
+  for (const method of ['pushState', 'replaceState']) {
+    const original = window.history[method].bind(window.history);
+    window.history[method] = function (state, unused, value) {
+      if (value === undefined || value === null) return original(state, unused, value);
+      const destination = new URL(value, window.location.href);
+      if (destination.origin === window.location.origin && (destination.pathname !== window.location.pathname || destination.search !== window.location.search) && (owns(destination.pathname) || owns(window.location.pathname))) {
+        navigate(destination.href, method === 'replaceState');
+        return;
+      }
+      const result = original(state, unused, value);
+      lastUrl = window.location.href;
+      return result;
+    };
+  }
+  window.addEventListener('popstate', event => {
+    if (window.location.href !== lastUrl && (owns(window.location.pathname) || owns(new URL(lastUrl).pathname))) {
+      event.stopImmediatePropagation();
+      if (!leaving) { leaving = true; replaceDocument(0); reload(); }
+    }
+  }, true);
+  // A BFCache snapshot must not retain the old page for a later restoration.
+  window.addEventListener('pagehide', event => {
+    if (event.persisted && owns(window.location.pathname)) {
+      if (pending) pending.abort();
+      document.body?.replaceChildren();
+    }
+  }, true);
+  window.addEventListener('pageshow', event => {
+    if (event.persisted && owns(window.location.pathname)) { leaving = true; replaceDocument(0); reload(); }
+  }, true);
+  window.addEventListener('focus', () => { void recheck(); refreshLinks(true); });
+  // A binding reader may fail after the availability check succeeded. Remove
+  // the entire application, including portals outside that reader's subtree.
+  window.addEventListener('universalcms:document-unavailable', event => {
+    if (leaving || !owns(window.location.pathname) || canonical(event.detail?.path) !== canonical(window.location.pathname)) return;
+    leaving = true;
+    if (pending) pending.abort();
+    replaceDocument(event.detail?.status === 404 ? 404 : 503);
+  });
+  document.addEventListener('visibilitychange', () => { if (document.visibilityState === 'visible') { void recheck(); refreshLinks(true); } });
+  setInterval(() => { void recheck(); refreshLinks(false); }, 15000);
+}
+
+/** Only public paths are serialized; scope and server configuration stay private. */
+export function createPublicationBrowserScript(configuration) {
+  const config = validatePublicationConfig(configuration);
+  const paths = JSON.stringify(config.routes.map(route => route.path)).replace(/</g, '\\u003c').replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+  return `;(${publicationBrowser.toString()})(${paths},${JSON.stringify(PUBLICATION_STATUS_PATH)});\n`;
+}
+
+/** Native PHP hosts supply only their reviewed public paths on a blocking script
+ * element. The guard itself remains the same tested publication client. */
+export function createNativePublicationBrowserScript() {
+  return `;(function(){'use strict';let paths;try{paths=JSON.parse(document.currentScript.dataset.universalcmsPaths);if(!Array.isArray(paths)||paths.length<1||paths.length>1001||paths.some(path=>typeof path!=='string'||path.length>500||!path.startsWith('/')||/[\\\\\\u0000-\\u0020\\u007f?#%]/.test(path)||path.includes('//')||path.split('/').some(part=>part==='.'||part==='..')))throw Error();}catch{document.documentElement.style.visibility='hidden';document.addEventListener('DOMContentLoaded',()=>{document.body.replaceChildren();const message=document.createElement('p');message.textContent='Website content is temporarily unavailable.';document.body.append(message);document.documentElement.style.visibility='';},{once:true});return;}(${publicationBrowser.toString()})(paths,${JSON.stringify(PUBLICATION_STATUS_PATH)});})();\n`;
+}