@universalcms/connect 0.1.0 → 0.13.1

package/dist/astro-source.mjs

@@ -0,0 +1,451 @@
+/** Inert, bounded Astro source extraction and original-layout content bindings. */
+import path from 'node:path';
+import { lstat, readdir, realpath } from 'node:fs/promises';
+import { parse } from './vendor/astro-compiler/node/index.js';
+import ts from './vendor/typescript.cjs';
+import { projectRoot, readProjectFile, SetupError } from './core.mjs';
+import { CONTENT_BINDINGS_FILE, contentDigest, readContentRegistry, readFrozenContent, validateContentRegistry } from './content-registry.mjs';
+import { isExcludedPublicationPath, validatePublicationConfig } from './publication.mjs';
+import { publicHref } from './website-model.mjs';
+import { inspectNativeChromeTemplate } from './native-chrome-source.mjs';
+
+export const ASTRO_SOURCE_LIMITS = Object.freeze({ bytes: 128 * 1024, totalBytes: 8 * 1024 * 1024, nodes: 30000, depth: 80, files: 1000, directories: 256, blocks: 200, text: 30000 });
+const fail = reason => { throw new SetupError(`Astro source needs reviewed integration: ${reason} Existing files were preserved.`); };
+const json = value => JSON.stringify(value, null, 2) + '\n';
+const normalize = value => value.replace(/\s+/g, ' ').trim();
+const token = value => contentDigest(value).slice(0, 20);
+const uuid = value => { const h = contentDigest(value); return `${h.slice(0,8)}-${h.slice(8,12)}-5${h.slice(13,16)}-a${h.slice(17,20)}-${h.slice(20,32)}`; };
+const privateSegment = /^(?:api|admin|account|dashboard|profile|auth|login|logout|register|checkout|orders|settings|billing|portal|patient|patients|vault|records|private)(?:-|$)/;
+const forbiddenTags = new Set(['header','footer','nav','form','input','textarea','select','option','iframe','object','embed','canvas','template','base']);
+const inlineTags = new Set(['a','span','strong','em','small','b','i','u','s','del','sup','sub','code','mark','br']);
+const safeUrl = value => !!publicHref(value) && !value.startsWith('#') && (value.startsWith('/') || /^https:\/\//i.test(value));
+const significant = children => (children ?? []).filter(node => node.type !== 'comment' && !(node.type === 'text' && !node.value.trim()));
+const own = (object, key) => Object.prototype.hasOwnProperty.call(object, key);
+const inspections = new WeakMap();
+
+function imageOrigin(value) {
+  try {
+    const url = new URL(value);
+    if (typeof value !== 'string' || !publicHref(value, {relative:false}) || url.pathname !== '/' || url.search || url.hash || !(url.protocol === 'https:' || url.protocol === 'http:' && ['localhost','127.0.0.1','[::1]'].includes(url.hostname))) fail('relative images require an exact public website origin');
+    return url.origin;
+  } catch { fail('relative images require an exact public website origin'); }
+}
+
+// Only locate the end of a compiler-identified opening tag. Quotes make a
+// literal `>` part of an attribute, never an editing boundary.
+function openingTag(source,start) {
+  let quote=null;
+  for(let index=start+1;index<source.length;index++) {
+    const value=source[index];
+    if(quote){if(value===quote)quote=null;continue;}
+    if(value==='"'||value==="'"){quote=value;continue;}
+    if(value==='>')return {end:index+1,selfClosing:source.slice(start,index).trimEnd().endsWith('/')};
+  }
+  fail('native opening tag is incomplete');
+}
+
+function decodeText(value) {
+  return value.replace(/&(?:[a-zA-Z][a-zA-Z0-9]*|#\d+|#x[\da-fA-F]+);/g, entity => {
+    const named = { '&amp;':'&', '&lt;':'<', '&gt;':'>', '&quot;':'"', '&apos;':"'", '&nbsp;':' ' };
+    if (own(named, entity)) return named[entity];
+    const number = entity.startsWith('&#x') ? Number.parseInt(entity.slice(3,-1),16) : entity.startsWith('&#') ? Number(entity.slice(2,-1)) : NaN;
+    if (!Number.isInteger(number) || number <= 0 || number > 0x10ffff || number >= 0xd800 && number <= 0xdfff) fail('unsupported character reference');
+    return String.fromCodePoint(number);
+  });
+}
+
+/** The pinned compiler reports byte offsets. Validate them against source tokens,
+ * rather than applying unverified parser positions to JavaScript string slices. */
+function sourceRanges(source) {
+  const bytes = Buffer.from(source), offsets = new Map([[0,0]]);
+  let byte = 0, character = 0;
+  for (const value of source) { byte += Buffer.byteLength(value); character += value.length; offsets.set(byte,character); }
+  return node => {
+    // The compiler omits the HTML element position when a doctype is present.
+    // This one outer shell is never inferred from a partial/duplicate match.
+    if(node.type==='element'&&node.name==='html'&&!node.position) {
+      const opens=[...source.matchAll(/<html(?=[\s/>])/g)],closes=[...source.matchAll(/<\/html>/g)];
+      if(opens.length!==1||closes.length!==1||opens[0].index>=closes[0].index)fail('HTML shell positions are ambiguous');
+      openingTag(source,opens[0].index);
+      return {start:opens[0].index,end:closes[0].index+7};
+    }
+    const start = node.position?.start?.offset, end = node.position?.end?.offset;
+    if (!Number.isSafeInteger(start) || start < 0 || !offsets.has(start)) fail('compiler source positions are incomplete');
+    const result = { start:offsets.get(start), end:offsets.get(end) };
+    if(node.type==='attribute') {
+      if(node.kind!=='quoted'||!['src','alt'].includes(node.name)||typeof node.raw!=='string'||!['"',"'"].includes(node.raw[0])||node.raw.at(-1)!==node.raw[0])fail('image attributes require quoted literal values');
+      // Attribute starts, like element starts, are byte offsets. Verify the
+      // exact token locally; searching a tag could match data-src or text in
+      // another attribute's quoted value instead of the owned image source.
+      const prefix = new RegExp(`^${node.name}\\s*=\\s*`).exec(source.slice(result.start));
+      if(!prefix || source.slice(result.start+prefix[0].length,result.start+prefix[0].length+node.raw.length)!==node.raw)fail('compiler attribute positions do not match the native source');
+      return {start:result.start,end:result.start+prefix[0].length+node.raw.length};
+    }
+    const tag=node.type==='element'||node.type==='component';
+    // Certain adjacent self-closing HTML tags start one byte after '<'. Accept
+    // only that exact local correction, verified against the compiler tag name.
+    if(tag&&source[result.start]!=='<'&&result.start>0&&source[result.start-1]==='<'&&source.slice(result.start,result.start+node.name.length)===node.name)result.start--;
+    const opening=tag ? openingTag(source,result.start):null;
+    const voidTag=['img','br','hr','meta','link','input','source','area','base','col','embed','param','track','wbr'].includes(node.name);
+    // Compiler 2.13.0 truncates void/self-closing end offsets. Its validated
+    // opening-tag start plus the bounded quote-aware delimiter is authoritative.
+    if(tag && (voidTag||opening.selfClosing))result.end=opening.end;
+    else if(!Number.isSafeInteger(end)||end<=start||end>bytes.length||!offsets.has(end))fail('compiler source positions are incomplete');
+    const text = source.slice(result.start,result.end);
+    if (node.type === 'element' || node.type === 'component') {
+      if (!text.startsWith('<' + node.name) || !/[\s/>]/.test(text[1+node.name.length]??'')) fail('compiler source positions do not match the native element');
+      if (!voidTag && !opening.selfClosing && !text.endsWith(`</${node.name}>`)) fail('implicitly closed elements require review');
+    } else if (node.type === 'text' && text !== node.value) fail('compiler text positions do not match the native source');
+    return result;
+  };
+}
+
+async function parsed(source) {
+  if (typeof source !== 'string' || Buffer.byteLength(source) > ASTRO_SOURCE_LIMITS.bytes || source.includes('\0')) fail('source exceeds its text budget');
+  let result;
+  try { result = await parse(source, { position:true }); } catch { fail('invalid Astro syntax'); }
+  if (!result?.ast || result.diagnostics?.some(item => item.severity === 1)) fail('invalid Astro syntax');
+  let count = 0;
+  const walk = (node, depth = 0) => {
+    if (++count > ASTRO_SOURCE_LIMITS.nodes || depth > ASTRO_SOURCE_LIMITS.depth) fail('template exceeds its AST budget');
+    for (const child of node.children ?? []) walk(child,depth+1);
+  };
+  walk(result.ast);
+  return { ast:result.ast, range:sourceRanges(source) };
+}
+
+function inspectFrontmatter(ast, source, { layout = false } = {}) {
+  const front = (ast.children ?? []).filter(node => node.type === 'frontmatter');
+  if (front.length > 1) fail('multiple frontmatter regions');
+  const imports = new Map(), constants = new Map();
+  let end = 0;
+  if (front.length) {
+    // Compiler frontmatter positions are not used for delimiter edits. The first
+    // bounded delimiter pair must agree exactly with the parsed script body.
+    const match = /^(?:\uFEFF)?---[ \t]*\r?\n([\s\S]*?)^---(?=\s|<|$)/m.exec(source);
+    if (!match || match.index !== 0 || match[1].trim() !== front[0].value.trim()) fail('frontmatter delimiters require review');
+    end = match[0].length;
+    const file = ts.createSourceFile('page.ts',front[0].value,ts.ScriptTarget.Latest,true,ts.ScriptKind.TS);
+    if (file.parseDiagnostics.length) fail('frontmatter syntax is invalid');
+    for (const statement of file.statements) {
+      if (ts.isImportDeclaration(statement)) {
+        const name = statement.importClause?.name;
+        if (layout || !name || statement.importClause.isTypeOnly || statement.importClause.namedBindings || statement.attributes || !ts.isStringLiteral(statement.moduleSpecifier) || !/^\.\.?\/[A-Za-z0-9_./-]+\.astro$/.test(statement.moduleSpecifier.text)) fail('only one inspected relative Astro layout import is supported');
+        if (imports.size) fail('multiple layout imports require review');
+        imports.set(name.text, statement.moduleSpecifier.text); continue;
+      }
+      if (ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement) || ts.isEmptyStatement(statement)) continue;
+      if (!ts.isVariableStatement(statement) || !(statement.declarationList.flags & ts.NodeFlags.Const) || statement.modifiers?.length) fail('executable frontmatter or route exports require review');
+      for (const declaration of statement.declarationList.declarations) {
+        const value = declaration.initializer;
+        if (layout && ts.isObjectBindingPattern(declaration.name) && value && ts.isPropertyAccessExpression(value) && ts.isIdentifier(value.expression) && value.expression.text === 'Astro' && value.name.text === 'props') {
+          for (const binding of declaration.name.elements) {
+            if (binding.dotDotDotToken || binding.propertyName || !ts.isIdentifier(binding.name) || binding.initializer && !ts.isStringLiteral(binding.initializer)) fail('layout props require literal defaults and names');
+            constants.set(binding.name.text,{ prop:true });
+          }
+          continue;
+        }
+        if (!ts.isIdentifier(declaration.name) || !value || !(ts.isStringLiteral(value) || ts.isNumericLiteral(value) || [ts.SyntaxKind.TrueKeyword,ts.SyntaxKind.FalseKeyword,ts.SyntaxKind.NullKeyword].includes(value.kind))) fail('frontmatter must contain only immutable primitive literals');
+        if (/^__(?:cms|universalcms)/i.test(declaration.name.text)) fail('reserved generated identifiers already exist');
+        constants.set(declaration.name.text,{ value:ts.isStringLiteral(value) ? value.text : value.getText(file) });
+      }
+    }
+  }
+  return { end, imports, constants };
+}
+
+function attributes(node, { layout = false, props = new Map(), pageLayout = false } = {}) {
+  const names = new Set();
+  for (const attribute of node.attributes ?? []) {
+    if (names.has(attribute.name)) fail('duplicate native attributes'); names.add(attribute.name);
+    if(node.name==='meta'&&attribute.name.toLowerCase()==='http-equiv')fail('HTTP-equivalent metadata requires explicit routing and security review');
+    if (/^(?:set:|client:|server:|on|data-cms-|data-universalcms)/i.test(attribute.name) || attribute.name === 'is:raw' || attribute.name === 'hidden') fail('dynamic, private or already-bound native attributes require review');
+    if (attribute.kind !== 'quoted' && attribute.kind !== 'empty') {
+      if (!(layout && attribute.kind === 'expression' && props.has(attribute.value.trim()))) fail('dynamic native attributes require review');
+    }
+    if (pageLayout && attribute.kind !== 'quoted') fail('layout arguments must be literal strings');
+    if (node.name === 'a' && attribute.name === 'href' && (attribute.kind !== 'quoted' || !publicHref(decodeText(attribute.value), {mail:true}))) fail('native links need a safe literal href');
+  }
+}
+
+async function inspectLayout(root, filename, source) {
+  const tree = await parsed(source), front = inspectFrontmatter(tree.ast,source,{layout:true});
+  const top = significant(tree.ast.children).filter(node => !['frontmatter','doctype'].includes(node.type) && !(node.type==='element'&&node.name==='style'));
+  if (top.length !== 1 || top[0].type !== 'element' || top[0].name !== 'html') fail('a layout must be one literal HTML document');
+  let slots = 0, bodies = 0;
+  const visit = (node, inBody = false, inHead = false) => {
+    if (node.type === 'frontmatter' || node.type === 'doctype' || node.type === 'comment' || node.type === 'text') return;
+    if (node.type === 'expression') {
+      const expression = (node.children ?? []).map(child => child.type === 'text' ? child.value : '').join('').trim();
+      if (!inHead || !front.constants.has(expression) || node.children.some(child => child.type !== 'text')) fail('layout expressions outside literal head props require review');
+      return;
+    }
+    if (node.type !== 'element' || forbiddenTags.has(node.name) || node.name === 'script' || node.name === 'svg') fail('custom layout components, scripts or native chrome require review');
+    attributes(node,{layout:true,props:front.constants});
+    tree.range(node);
+    if (node.name === 'body') { if (++bodies !== 1) fail('ambiguous layout body'); inBody = true; }
+    if (node.name === 'head') inHead = true;
+    if (node.name === 'slot') {
+      if (!inBody || node.attributes.length || significant(node.children).length || ++slots !== 1) fail('layout requires exactly one unconditional default slot');
+      return;
+    }
+    if (node.name === 'style') return;
+    for (const child of node.children ?? []) visit(child,inBody,inHead);
+  };
+  visit(top[0]);
+  for(const node of tree.ast.children)if(node.type==='element'&&node.name==='style'){attributes(node);tree.range(node);}
+  if (slots !== 1 || bodies !== 1) fail('layout requires one body and one unconditional default slot');
+  return { path:filename, content:source, sha256:contentDigest(source), state:'unchanged' };
+}
+
+async function layoutFor(root, filename, front, node) {
+  const imported = front.imports.get(node.name);
+  if (!root || !imported) fail('unresolved native layout or component');
+  const target = path.posix.normalize(path.posix.join(path.posix.dirname(filename),imported));
+  if (!/^src\/(?:layouts|components)\/[A-Za-z0-9_/-]+\.astro$/.test(target) || target.split('/').some(part => part.startsWith('.'))) fail('layout import must stay within ordinary public src layouts or components');
+  const content = await ordinary(root,target);
+  if (content === null) fail('layout import is missing');
+  return inspectLayout(root,target,content);
+}
+
+async function ordinary(root, filename) {
+  const content = await readProjectFile(root,filename);
+  if (content !== null && (await lstat(path.join(root,filename))).nlink !== 1) fail('linked source files require review');
+  return content;
+}
+
+/** Pure parsing apart from an optional, bounded relative layout read. */
+export async function extractAstroPage({ source, slug, locale = 'en', filename = 'src/pages/index.astro', root, websiteOrigin, allowNativeChrome = false } = {}) {
+  if (typeof slug !== 'string' || !/^[a-z0-9]+(?:[-/][a-z0-9]+)*$/.test(slug) || slug.length > 160) fail('invalid public page identity');
+  try { if (Intl.getCanonicalLocales(locale)[0] !== locale) fail('noncanonical content locale'); } catch { fail('invalid content locale'); }
+  if (/\b(?:astroBound|AstroWebsite|__cms)\b|@universalcms\/connect\//.test(source ?? '')) fail('existing generated bindings cannot be wrapped twice');
+  const nativeChrome = allowNativeChrome ? (await inspectNativeChromeTemplate(source)).descriptor : undefined;
+  const tree = await parsed(source), front = inspectFrontmatter(tree.ast,source);
+  const top = significant(tree.ast.children).filter(node => !['frontmatter','doctype'].includes(node.type));
+  const styles = top.filter(node => node.type === 'element' && node.name === 'style');
+  const roots = top.filter(node => !styles.includes(node));
+  if (roots.length !== 1) fail('page needs one literal HTML document, main element or inspected layout');
+  const outer = roots[0], imports = [];
+  let body, scaffold = false;
+  if (outer.type === 'component') {
+    attributes(outer,{pageLayout:true});
+    imports.push(await layoutFor(root,filename,front,outer)); body = outer;
+  } else if (outer.type === 'element' && outer.name === 'html') {
+    const children = significant(outer.children), bodies = children.filter(node => node.type === 'element' && node.name === 'body');
+    if (bodies.length !== 1 || children.some(node => node.type !== 'element' || !['head','body'].includes(node.name)) || children.filter(node => node.name === 'head').length > 1) fail('page document needs one literal body');
+    body = bodies[0];
+  } else if (outer.type === 'element' && outer.name === 'main') { body = outer; scaffold = true; }
+  else fail('unsupported page root');
+  if (front.imports.size !== imports.length) fail('unused or unresolved component imports require review');
+  const blocks = [], edits = [], declarations = [], bindings = {};
+  let textBudget = 0, title;
+  const textNodes = (node, { nativeLink = false } = {}) => {
+    const result = [];
+    const visit = child => {
+      if (child.type === 'comment') return;
+      if (child.type === 'text') { result.push(child); return; }
+      if (child.type !== 'element' || !inlineTags.has(child.name)) fail('editorial blocks require literal text and inline native elements');
+      if (child.name === 'a' && !nativeLink) fail('links within editable text require explicit bindings');
+      attributes(child);
+      if (child.name === 'br') { result.push({break:true}); return; }
+      for (const nested of child.children ?? []) visit(nested);
+    };
+    for (const child of node.children ?? []) visit(child);
+    return result;
+  };
+  const emit = (node,type,text,data,innerEdits) => {
+    if (!text && type !== 'image') fail('empty editorial blocks require review');
+    textBudget += text.length;
+    if (blocks.length >= ASTRO_SOURCE_LIMITS.blocks || textBudget > ASTRO_SOURCE_LIMITS.text) fail('editorial content exceeds its budget');
+    const range = tree.range(node), id = uuid(`universalcms-astro-v1:${locale}:${slug}:${range.start}:${range.end}:${type}`), variable = `__cmsBlock${blocks.length}`;
+    const block = {id,version:1,type,text,...(data ? {data} : {})}; blocks.push(block);
+    const slot = `slot-${token(id)}`; bindings[slot] = {variants:[{values:[],id}]};
+    declarations.push(`const ${variable} = astroBound(__cms, ${JSON.stringify(id)}, ${JSON.stringify(type)});`);
+    let native = source.slice(range.start,range.end);
+    const replacements = innerEdits(variable,range);
+    for (const edit of replacements.sort((a,b) => b.start-a.start)) native = native.slice(0,edit.start-range.start)+edit.text+native.slice(edit.end-range.start);
+    edits.push({...range,text:`{${variable} && (${native})}`});
+    if (type === 'heading' && (!title || node.name === 'h1' && title.tag !== 'h1')) title = {text,id,tag:node.name};
+  };
+  const visit = (node, inBody = false) => {
+    if (node.type === 'frontmatter' || node.type === 'doctype' || node.type === 'comment') return;
+    if (node.type === 'text') { if (inBody && node.value.trim()) fail('uncontained native text needs an explicit editorial block'); return; }
+    if (node === outer && node.type === 'component') { for (const child of node.children) visit(child,true); return; }
+    if (node.type !== 'element') fail('template expressions or unresolved components require review');
+    if (nativeChrome && ['header','footer'].includes(node.name)) return;
+    attributes(node); tree.range(node);
+    if (forbiddenTags.has(node.name) || node.name === 'script' || node.name === 'svg' || node.name === 'slot') fail('native chrome, forms, scripts or opaque elements need explicit settings composition');
+    if (node.name === 'head') {
+      const checkHead = child => {
+        if (child.type === 'text' || child.type === 'comment') return;
+        if (child.type !== 'element' || !['title','meta','link','style'].includes(child.name)) fail('dynamic page metadata requires review');
+        attributes(child); tree.range(child);
+        if (child.name !== 'style' && child.children?.some(item => item.type !== 'text' && item.type !== 'comment')) fail('dynamic page metadata requires review');
+      };
+      for (const child of node.children ?? []) checkHead(child); return;
+    }
+    if (node.name === 'style') return;
+    if (node === body) inBody = true;
+    if (inBody && (/^h[1-6]$/.test(node.name) || node.name === 'p')) {
+      const nodes = textNodes(node), text = normalize(nodes.map(child => child.break ? ' ' : decodeText(child.value)).join(''));
+      let first = true;
+      emit(node,node.name === 'p' ? 'paragraph':'heading',text,node.name !== 'p' && Number(node.name[1]) > 1 ? {level:Math.min(4,Number(node.name[1]))}:undefined,(variable) => nodes.filter(child => !child.break && child.value.trim()).map(child => {
+        // Preserve the original inline text placement for the imported revision.
+        // Later editorial replacements occupy the first native text slot, while
+        // every original wrapper and its attributes remain owned by the website.
+        const range = tree.range(child), replacement = `{${variable}.text === ${JSON.stringify(text)} ? ${JSON.stringify(decodeText(child.value))} : ${first ? `${variable}.text` : "''"}}`; first = false;
+        return {...range,text:replacement};
+      }));
+      return;
+    }
+    if (inBody && ['ul','ol'].includes(node.name)) {
+      const items = significant(node.children);
+      if (!items.length || items.some(child => child.type !== 'element' || child.name !== 'li')) fail('lists need literal list items');
+      const values = items.map(child => { attributes(child); return normalize(textNodes(child).map(part => part.break ? ' ' : decodeText(part.value)).join('')); });
+      if (items.some(item => significant(item.children).some(child => child.type !== 'text'))) fail('formatted list items require explicit native bindings');
+      if (values.some(value => !value)) fail('empty list items require review');
+      const range = tree.range(node), opening = openingTag(source,range.start).end;
+      const closing = range.end - (`</${node.name}>`).length;
+      const itemRange = tree.range(items[0]), itemOpen = source.slice(itemRange.start,openingTag(source,itemRange.start).end);
+      // Every list item must have the same native attributes to avoid silently
+      // changing per-row layout while supporting CMS additions and deletions.
+      if (items.some(item => { const r=tree.range(item); return source.slice(r.start,openingTag(source,r.start).end)!==itemOpen; })) fail('distinct list item layouts require explicit bindings');
+      emit(node,'list',values.join('\n'),undefined,variable => [{start:opening,end:closing,text:`{${variable}.text.split('\\n').map((__cmsItem) => (${itemOpen}{__cmsItem}</li>))}`}]);
+      return;
+    }
+    if (inBody && node.name === 'img') {
+      const attrs = new Map(node.attributes.map(attribute => [attribute.name,attribute]));
+      const src = decodeText(attrs.get('src')?.value ?? ''), alt = decodeText(attrs.get('alt')?.value ?? '');
+      if (!safeUrl(src) || attrs.has('srcset') || !attrs.has('alt') || alt.length > 300) fail('images need a literal safe src and bounded alt without responsive source expressions');
+      const url = src.startsWith('/') ? new URL(src,imageOrigin(websiteOrigin)).href : src;
+      emit(node,'image','',{url,alt},(variable,range) => {
+        const updates = [];
+        for (const [name,value] of [['src',`${variable}.url`],['alt',`${variable}.alt`]]) {
+          updates.push({...tree.range(attrs.get(name)),text:`${name}={${value}}`});
+        }
+        return updates;
+      }); return;
+    }
+    if (inBody && node.name === 'a') {
+      // Navigation text is native behavior, not an editable editorial block.
+      if (!(node.attributes ?? []).some(attribute => attribute.name === 'href')) fail('native links need a safe literal href');
+      textNodes(node,{nativeLink:true}); return;
+    }
+    for (const child of node.children ?? []) visit(child,inBody);
+  };
+  visit(outer);
+  for (const style of styles) { attributes(style); tree.range(style); }
+  if (!title || !blocks.length || title.text.length > 200) fail('each public page needs a literal editorial heading');
+  const document = {schemaVersion:1,title:title.text,excerpt:(blocks.find(block => block.type === 'paragraph')?.text ?? '').slice(0,1000),fields:{},taxonomy:{categories:[],tags:[]},blocks};
+  const inventory = {identity:{kind:'page',slug,locale},baseline:document,titleBlockId:title.id,bindings,...(nativeChrome ? {nativeChrome} : {}),imports:imports.map(({path,sha256})=>({path,sha256}))};
+  const bodyRange = tree.range(body);
+  const openEnd = openingTag(source,bodyRange.start).end, closeStart = bodyRange.end - (`</${body.name}>`).length;
+  const island = '<AstroWebsite pathname={__cms.pathname} scope={__cms.scope} initialResult={__cms.result} initialSettings={__cms.settings} inventory={__cms.publicInventory} client:load>';
+  if (scaffold) {
+    edits.push({start:bodyRange.start,end:bodyRange.start,text:'<html><head><meta charset="utf-8" /><meta name="viewport" content="width=device-width" /></head><body>'+island});
+    edits.push({start:bodyRange.end,end:bodyRange.end,text:'</AstroWebsite></body></html>'});
+  } else {
+    edits.push({start:openEnd,end:openEnd,text:island});
+    edits.push({start:closeStart,end:closeStart,text:'</AstroWebsite>'});
+  }
+  const generated = `\nimport { astroBound } from '@universalcms/connect/astro-runtime';\nimport { AstroWebsite } from '@universalcms/connect/astro-website';\nimport '@universalcms/connect/website.css';\nimport '@universalcms/connect/publication.css';\nconst __cms = Astro.locals.universalcms;\n${declarations.join('\n')}\n`;
+  if (front.end) { const close = source.lastIndexOf('---',front.end-1); edits.push({start:close,end:close,text:generated}); }
+  else edits.push({start:0,end:0,text:`---${generated}---\n`});
+  let transformed = source;
+  for (const edit of edits.sort((a,b)=>b.start-a.start || b.end-a.end)) transformed = transformed.slice(0,edit.start)+edit.text+transformed.slice(edit.end);
+  await parsed(transformed);
+  return {entry:{kind:'page',slug,locale,document},inventory,source:transformed,imports,complete:true,warnings:[]};
+}
+
+async function routeFiles(root) {
+  const result = [], paths = new Set(); let dirs=0, files=0;
+  const walk = async (directory,segments=[],depth=0) => {
+    if (++dirs > ASTRO_SOURCE_LIMITS.directories || depth > 12) fail('route inventory exceeds its directory budget');
+    const target=path.join(root,directory), info=await lstat(target);
+    if (!info.isDirectory() || info.isSymbolicLink() || await realpath(target)!==target) fail('route directories must be ordinary local directories');
+    for (const item of (await readdir(target,{withFileTypes:true})).sort((a,b)=>a.name.localeCompare(b.name))) {
+      if (++files > ASTRO_SOURCE_LIMITS.files) fail('route inventory exceeds its file budget');
+      if (item.isSymbolicLink()) fail('linked routes require review');
+      if (item.name.startsWith('_') || item.name.startsWith('.')) continue;
+      const filename=`${directory}/${item.name}`;
+      if (item.isDirectory()) {
+        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(item.name) || privateSegment.test(item.name)) fail('dynamic or private route ownership requires review');
+        await walk(filename,[...segments,item.name],depth+1); continue;
+      }
+      if (!item.isFile() || !/^[a-z0-9]+(?:-[a-z0-9]+)*\.astro$/.test(item.name)) fail('nonliteral Astro pages or endpoint routes require review');
+      const basename=item.name.slice(0,-6);
+      if (privateSegment.test(basename) || basename==='404' || basename==='500') fail('private or error routes require review');
+      const pathname='/'+[...segments,...(basename==='index'?[]:[basename])].join('/');
+      if (isExcludedPublicationPath(pathname)) fail('private or reserved route ownership requires review');
+      if (paths.has(pathname)) fail('duplicate Astro page paths'); paths.add(pathname);
+      result.push({path:pathname,sourceFile:filename,kind:'page',slug:pathname==='/'?'home':pathname.slice(1)});
+    }
+  };
+  for (const name of ['src/middleware.ts','src/middleware.js','src/middleware/index.ts','src/middleware/index.js']) if (await ordinary(root,name)!==null) fail('existing middleware requires an access review');
+  await walk('src/pages');
+  if (!result.length || result.some(row=>row.path==='/home') && result.some(row=>row.path==='/')) fail('missing pages or ambiguous home identity');
+  return result;
+}
+
+/** Read public pages and immutable originals; never execute Astro/project code. */
+export async function inspectAstroSource(directory,{locale='en',websiteOrigin}={}) {
+  if(websiteOrigin !== undefined) websiteOrigin = imageOrigin(websiteOrigin);
+  const root=await projectRoot(directory), routes=await routeFiles(root), registry=await readContentRegistry(root);
+  if (registry?.profile || registry?.routes.some(row=>!row.sourceFile.endsWith('.astro'))) fail('existing content ownership belongs to another adapter');
+  const entries=[], inventories={}, prepared=[], observed=new Map(); let totalBytes=0;
+  for (const route of routes) {
+    const current=await ordinary(root,route.sourceFile); if(current===null)fail('page disappeared during inspection');
+    const installed=registry?.routes.find(row=>row.path===route.path);
+    let original=current;
+    if (installed) {
+      if (installed.sourceFile!==route.sourceFile || installed.slug!==route.slug || installed.locale!==locale || installed.kind!=='page') fail('saved Astro route identity changed');
+      original=(await readFrozenContent(root,installed)).texts.original;
+    }
+    const extracted = await extractAstroPage({source:original,slug:route.slug,locale,filename:route.sourceFile,root,websiteOrigin});
+    if (installed && extracted.source!==current) fail('generated Astro page changed');
+    totalBytes+=Buffer.byteLength(original);
+    observed.set(route.sourceFile,{path:route.sourceFile,content:current,state:'unchanged',sha256:contentDigest(current)});
+    for (const item of extracted.imports) { observed.set(item.path,item); totalBytes+=Buffer.byteLength(item.content); }
+    if(totalBytes>ASTRO_SOURCE_LIMITS.totalBytes)fail('source inventory exceeds its byte budget');
+    entries.push(extracted.entry); inventories[route.path]=extracted.inventory;
+    prepared.push({...route,locale,original,current,installed,extracted});
+  }
+  if(registry && registry.routes.length!==routes.length)fail('previously bound routes were removed');
+  const diagnostics={discoveredPages:routes.length,automaticPages:entries.length,skippedPages:0,unsupportedRoutes:0,warnings:[]};
+  const result={entries,snapshot:{version:1,entries,inventories},routes:prepared.map(({path,kind,slug,locale})=>({path,kind,slug,locale})),sourceFiles:[...observed.values()].map(({path,sha256})=>({path,sha256})),diagnostics};
+  inspections.set(result,{root,prepared,observed,registry,digest:contentDigest(json(result)),routeFiles:routes,websiteOrigin});
+  return result;
+}
+
+/** Core-compatible plan; originals and inventories precede all page replacement. */
+export async function planAstroContent(directory,configuration,inspection) {
+  const root=await projectRoot(directory),config=validatePublicationConfig(configuration);
+  inspection ??= await inspectAstroSource(root,{locale:config.routes[0]?.locale,websiteOrigin:config.websiteOrigin});
+  const state=inspections.get(inspection);
+  if(!state || state.root!==root)fail('use the current inspection for this website');
+  if(state.websiteOrigin !== undefined && state.websiteOrigin !== config.websiteOrigin)fail('source and publication website origins must match');
+  if(contentDigest(json(inspection))!==state.digest)fail('the public source inspection changed before planning');
+  if(json(await routeFiles(root))!==json(state.routeFiles))fail('route inventory changed after inspection');
+  if(config.routes.length!==inspection.routes.length || config.routes.some(row=>!inspection.routes.some(other=>['path','kind','slug','locale'].every(key=>row[key]===other[key]))))fail('publication identities must match exact Astro source routes');
+  const files=[],rows=[];
+  for(const observed of state.observed.values()) if(await ordinary(root,observed.path)!==observed.content)fail('source changed after inspection');
+  for(const item of state.prepared) {
+    if(item.installed) {
+      const frozen=await readFrozenContent(root,item.installed);
+      if(json(frozen.inventory)!==json(item.extracted.inventory))fail('frozen Astro inventory or layout imports changed');
+      for(const name of ['original','native','inventory','source'])files.push({path:item.installed[`${name}File`],content:frozen.texts[name],state:'unchanged'});
+      rows.push(item.installed);continue;
+    }
+    const suffix=token(`${item.path}:${item.kind}:${item.slug}:${item.locale}`),nativeFile=`.universalcms/content/${suffix}.native.txt`,originalFile=`.universalcms/content/${suffix}.original.txt`,inventoryFile=`.universalcms/content/${suffix}.json`;
+    for(const filename of [nativeFile,originalFile,inventoryFile])if(await ordinary(root,filename)!==null)fail('a prospective frozen content file already exists');
+    const inventoryText=json(item.extracted.inventory),source=item.extracted.source;
+    const row={path:item.path,kind:item.kind,slug:item.slug,locale:item.locale,sourceFile:item.sourceFile,nativeFile,originalFile,inventoryFile,sourceHash:contentDigest(source),nativeHash:contentDigest(source),originalHash:contentDigest(item.original),inventoryHash:contentDigest(inventoryText)};
+    files.push({path:originalFile,content:item.original,state:'create'},{path:nativeFile,content:source,state:'create'},{path:inventoryFile,content:inventoryText,state:'create'},{path:item.sourceFile,content:source,state:'update',previous:item.current});rows.push(row);
+  }
+  for(const observed of state.observed.values())if(!files.some(file=>file.path===observed.path))files.push({path:observed.path,content:observed.content,state:'unchanged'});
+  const registry=validateContentRegistry({version:1,routes:rows}),text=json(registry),before=await ordinary(root,CONTENT_BINDINGS_FILE);
+  if(before!==null && before!==text)fail('saved Astro content registry changed');
+  files.push({path:CONTENT_BINDINGS_FILE,content:text,state:before===null?'create':'unchanged'});
+  if(files.some(file=>Buffer.byteLength(file.content)>ASTRO_SOURCE_LIMITS.bytes))fail('generated binding exceeds its per-file budget');
+  return {root,framework:'astro',files,routes:rows,entries:inspection.entries,snapshot:inspection.snapshot};
+}

package/dist/astro-website.d.mts

@@ -0,0 +1,5 @@
+import type { ReactNode } from 'react';
+import type { WebsiteResult } from './website-runtime.mjs';
+import type { Inventory } from './react-publication.mjs';
+export type AstroWebsiteProps = { pathname: string; scope: string; initialResult: WebsiteResult; initialSettings: unknown; inventory?: Inventory; children?: ReactNode; formEndpoint?: string; chrome?: boolean };
+export function AstroWebsite(props: AstroWebsiteProps): ReactNode;

package/dist/astro-website.mjs

@@ -0,0 +1,42 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React, { useEffect } from 'react';
+import { CmsWebsite, CmsWebsitePage } from './react-website.mjs';
+import { PublishedDocumentProvider, CmsAdditionalContent } from './react-publication.mjs';
+const flatten = (blocks) => blocks.flatMap(block => [block, ...(block.type === 'section' && Array.isArray(block.data?.blocks) ? flatten(block.data.blocks) : block.type === 'columns' && Array.isArray(block.data?.columns) ? flatten(block.data.columns.flat()) : [])]);
+/** Astro renders native slots once on the server. Let the existing publication
+ * guard reload them when a revision changes instead of marking old static HTML
+ * as freshly rendered through React's document-only update handler. */
+function NativeRevisionGuard({ pathname }) {
+    useEffect(() => {
+        const documentRoot = document.documentElement;
+        const changed = (event) => {
+            const detail = event.detail;
+            const currentPath = window.location.pathname.replace(/\/$/, '') || '/';
+            if (detail?.path !== pathname || document.documentElement !== documentRoot || currentPath !== pathname && !(pathname === '/' && currentPath === '/index.html'))
+                return;
+            // Keep the event uncanceled so the blocking publication bootstrap clears
+            // the old document and reloads. Stop React's document-only refresh handler
+            // from marking static Astro children as the newly rendered revision.
+            event.stopImmediatePropagation();
+        };
+        window.addEventListener('universalcms:publication-change', changed, { capture: true });
+        return () => window.removeEventListener('universalcms:publication-change', changed, { capture: true });
+    }, [pathname]);
+    return null;
+}
+/** One hydrated owner provides the existing all-section consent/settings logic.
+ * Astro's native children stay intact; only explicitly unbound blocks are React. */
+export function AstroWebsite({ pathname, scope, initialResult, initialSettings, inventory, children, formEndpoint, chrome = true }) {
+    if (!inventory)
+        return _jsx(CmsWebsitePage, { scope: scope, pathname: pathname, initialResult: initialResult, initialSettings: initialSettings, chrome: chrome });
+    if (initialResult.state !== 'published')
+        return _jsx("main", { role: "alert", children: _jsx("h1", { children: "Page temporarily unavailable" }) });
+    const entry = initialResult.entry;
+    const original = new Map(flatten(inventory.baseline.blocks).map(block => [block.id, block.type]));
+    const current = new Map(flatten(entry.document.blocks).map(block => [block.id, block.type]));
+    // A changed kind is no longer present in an Astro-native slot. Removing that
+    // binding lets CmsAdditionalContent render it with the normal form policy.
+    const route = { ...inventory, bindings: Object.fromEntries(Object.entries(inventory.bindings).map(([name, slot]) => [name, { ...slot, variants: slot.variants.filter(value => current.get(value.id) === original.get(value.id)) }])) };
+    return _jsxs(CmsWebsite, { scope: scope, initialSettings: initialSettings, entry: entry, applyTemplate: true, chrome: chrome, children: [_jsx(NativeRevisionGuard, { pathname: pathname }), _jsxs(PublishedDocumentProvider, { initialEntry: entry, pathname: pathname, route: route, formEndpoint: formEndpoint, children: [children, _jsx(CmsAdditionalContent, { includeUnbound: true })] })] });
+}