@bettercms-ai/convert 0.22.0 → 0.23.0

package/dist/index.d.ts

@@ -1837,6 +1837,84 @@ declare function readBrief(value: unknown): Brief;
  */
 declare function readPlan(value: unknown): ComponentizePlan;
 
+/** The plan's own file shape, restated rather than imported to keep `index.ts` acyclic. */
+interface UpgradeFile {
+    path: string;
+    operation: "modify" | "add";
+    content: string;
+}
+/** Why a root was left without the marker. */
+type UpgradeSkipReason = 
+/** The root has its own `style` attribute; a second one would be resolved by the dialect. */
+"OWN_STYLE"
+/** The root has a spread (`{...rest}`) that may carry a style. */
+ | "SPREAD"
+/** Only a block ID reaches the root (`{Astro.props.bcmsBlock}`, `{id}`): its style is not in scope. */
+ | "BLOCK_ID_ONLY"
+/** `data-bcms-block="abc"`: a literal id, with no block object behind it. */
+ | "BLOCK_LITERAL"
+/** A call, a conditional, anything that does not name one block. */
+ | "BLOCK_UNRESOLVABLE"
+/** `data-bcms-block` on a component tag is a prop, not an element the editor can find. */
+ | "NOT_AN_ELEMENT"
+/** A dialect this pass does not rewrite (html, vue, svelte). */
+ | "DIALECT_UNSUPPORTED"
+/** The name this pass would introduce is already something else in the file. */
+ | "NAME_TAKEN"
+/** A generated section whose registry or `bcms-sections` no longer has the shape it can patch. */
+ | "REGISTRY_UNRECOGNISED"
+/** The file did not parse. */
+ | "PARSE_ERROR";
+interface UpgradeRootRef {
+    file: string;
+    /** 1-based line of the root's `<`. */
+    line: number;
+    tag: string;
+    /** What `data-bcms-block` was given, as written: `{blockId}`, `"abc"`. */
+    block: string;
+}
+interface UpgradedRoot extends UpgradeRootRef {
+    form: "section-prop" | "sectionRootAttrs" | "helper";
+}
+interface SkippedRoot extends UpgradeRootRef {
+    reason: UpgradeSkipReason;
+    message: string;
+}
+interface SectionUpgradeReceipt {
+    /** The helper at `src/bcms-content.ts` (and its siblings), when there is one or this pass wrote one. */
+    helpers: {
+        path: string;
+        from: number | null;
+        to: number;
+        operation: "add" | "modify" | "unchanged" | "foreign";
+    }[];
+    /** Generated registry / `bcms-sections` modules patched to hand `block.style` down. */
+    registry: {
+        path: string;
+        operation: "modify" | "unchanged";
+    }[];
+    roots: {
+        upgraded: UpgradedRoot[];
+        alreadyMarked: UpgradeRootRef[];
+        skipped: SkippedRoot[];
+    };
+}
+interface UpgradeOptions {
+    /** Replace a helper module this package did not write, when a root needs the helper. */
+    overwriteHelper?: boolean;
+    /** The repository's root `package.json`, to tell whether its SDK exports `sectionRootAttrs`. */
+    packageJson?: string;
+}
+/** Thrown, like `convertSources`, when the helper is needed and is not ours to replace. */
+declare class UpgradeError extends Error {
+    readonly code = "HELPER_CONFLICT";
+    constructor(message: string);
+}
+declare function upgradeSections(sources: readonly SourceFile[], options?: UpgradeOptions): Promise<{
+    files: UpgradeFile[];
+    receipt: SectionUpgradeReceipt;
+}>;
+
 /** One file operation, exactly as `src/lib/github/plan-digest.ts` spells it. */
 interface PlanFile {
     path: string;
@@ -1871,4 +1949,4 @@ declare function convertSources(briefIn: Brief, sources: SourceFile[], options?:
     receipt: ConversionReceipt;
 }>;
 
-export { ASTRO_LANE_PENDING, type AstNode, type AttrBinding, type Brief, type BriefForm, type BriefPage, type BriefPath, COMPONENT_DIR, CONTENT_DIR, type CanvasResult, type CanvasSource, type Carried, type ComponentizeOptions, type ComponentizePlan, type ComponentizePlanComponent, type ComponentizePlanField, type ComponentizePlanPage, type ComponentizePlanSection, type ComponentizeReceipt, type ConversionReceipt, ConvertError, type ConvertErrorCode, type ConvertOptions, DIALECT_RULES, type DataMember, type DataResult, type DeclaredPath, type Dialect, type DynamicBinding, FORM_SCRIPT, type FileDeclaration, type FindSitesResult, type FixAction, FormInvariantError, type FormPendingReason, type FormsReceipt, HELPER_PATH, HELPER_VERSION, type ImageResult, type ImageTarget, type ImportedFrom, type LlmFallback, type LocatedPath, type Node, PARSE_FILE, type ParsedFile, type ParserError, type PathLocator, type PendingFix, type PendingForm, type PendingPath, type PendingReason, type PendingSection, type PlanFile, REGISTRY_MARKER, type ReceiptFile, ReceiptInvariantError, type ReceiptNote, type Rewrite, SECTIONS_LIB, SECTION_MARKER, SKIP_DIRS, SKIP_FILES, SOURCE_EXTENSIONS, SSR_DRAFT_RECIPE, STUB_CONTENT, SectionInvariantError, type SectionPendingReason, type SectionsReceipt, type Site, type SiteWhere, type SourceFile, type Splice, type TargetIdentity, type UnlocatedPath, type ValidationCode, ValidationError, type Xray, type XrayBucket, aliasesFrom, assertForms, assertReceipt, assertSections, assetCandidates, assetImport, attrsFor, bindDataLiterals, bindImages, briefDigest, canvasBridge, carryFor, componentizeSources, convertSources, convertedHere, coverageOf, declaringElements, dialectOf, exportedFunction, extendedConfigs, findLiteral, findSites, findSitesTolerant, fixFor, flat, helperSource, importsIn, isDecorativeGlyph, isDynamicRoute, isKnownHelper, isSourceCandidate, locate, measureUnaddressable, overlapping, pageFilesFor, parseFile, propsAttribute, readBrief, readComponentizePlan, readDeclarations, readExpr, readPlan, relativeImport, resolveSpecifier, rewriteFile, routeCounts, routeOfFile, stripTags, unreadableConfigs, walkAst, wireForms };
+export { ASTRO_LANE_PENDING, type AstNode, type AttrBinding, type Brief, type BriefForm, type BriefPage, type BriefPath, COMPONENT_DIR, CONTENT_DIR, type CanvasResult, type CanvasSource, type Carried, type ComponentizeOptions, type ComponentizePlan, type ComponentizePlanComponent, type ComponentizePlanField, type ComponentizePlanPage, type ComponentizePlanSection, type ComponentizeReceipt, type ConversionReceipt, ConvertError, type ConvertErrorCode, type ConvertOptions, DIALECT_RULES, type DataMember, type DataResult, type DeclaredPath, type Dialect, type DynamicBinding, FORM_SCRIPT, type FileDeclaration, type FindSitesResult, type FixAction, FormInvariantError, type FormPendingReason, type FormsReceipt, HELPER_PATH, HELPER_VERSION, type ImageResult, type ImageTarget, type ImportedFrom, type LlmFallback, type LocatedPath, type Node, PARSE_FILE, type ParsedFile, type ParserError, type PathLocator, type PendingFix, type PendingForm, type PendingPath, type PendingReason, type PendingSection, type PlanFile, REGISTRY_MARKER, type ReceiptFile, ReceiptInvariantError, type ReceiptNote, type Rewrite, SECTIONS_LIB, SECTION_MARKER, SKIP_DIRS, SKIP_FILES, SOURCE_EXTENSIONS, SSR_DRAFT_RECIPE, STUB_CONTENT, SectionInvariantError, type SectionPendingReason, type SectionUpgradeReceipt, type SectionsReceipt, type Site, type SiteWhere, type SkippedRoot, type SourceFile, type Splice, type TargetIdentity, type UnlocatedPath, UpgradeError, type UpgradeOptions, type UpgradeRootRef, type UpgradeSkipReason, type UpgradedRoot, type ValidationCode, ValidationError, type Xray, type XrayBucket, aliasesFrom, assertForms, assertReceipt, assertSections, assetCandidates, assetImport, attrsFor, bindDataLiterals, bindImages, briefDigest, canvasBridge, carryFor, componentizeSources, convertSources, convertedHere, coverageOf, declaringElements, dialectOf, exportedFunction, extendedConfigs, findLiteral, findSites, findSitesTolerant, fixFor, flat, helperSource, importsIn, isDecorativeGlyph, isDynamicRoute, isKnownHelper, isSourceCandidate, locate, measureUnaddressable, overlapping, pageFilesFor, parseFile, propsAttribute, readBrief, readComponentizePlan, readDeclarations, readExpr, readPlan, relativeImport, resolveSpecifier, rewriteFile, routeCounts, routeOfFile, stripTags, unreadableConfigs, upgradeSections, walkAst, wireForms };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.ts
-import MagicString6 from "magic-string";
+import MagicString7 from "magic-string";
 
 // src/brief.ts
 import { createHash } from "crypto";
@@ -3764,8 +3764,8 @@ function bindLists(ctx, members, module, out, indexes) {
         const loops = iterations(ctx.parsed.roots, name);
         if (loops.length > 1) return { refuse: "REPEATER_AMBIGUOUS" };
         if (loops.length === 0) return null;
-        const mentions2 = ctx.content.match(new RegExp(`(?<![\\w$])${name}(?![\\w$])`, "g")) ?? [];
-        if (mentions2.length !== 2 || escapes.has(name)) return { refuse: "IN_EXPRESSION" };
+        const mentions3 = ctx.content.match(new RegExp(`(?<![\\w$])${name}(?![\\w$])`, "g")) ?? [];
+        if (mentions3.length !== 2 || escapes.has(name)) return { refuse: "IN_EXPRESSION" };
         return { loop: loops[0], params: callbackParams(loops[0], name) };
       }
     });
@@ -9195,6 +9195,371 @@ function readComponentizePlan(value) {
   return readPlan(value);
 }
 
+// src/upgrade.ts
+import MagicString6 from "magic-string";
+var UpgradeError = class extends Error {
+  code = "HELPER_CONFLICT";
+  constructor(message) {
+    super(message);
+    this.name = "UpgradeError";
+  }
+};
+var SDK_SINCE = {
+  astro: { pkg: "@bettercms-ai/astro", version: [0, 19, 0] },
+  jsx: { pkg: "@bettercms-ai/next", version: [0, 18, 0] }
+};
+function sdkHasSectionRootAttrs(packageJson, dialect) {
+  if (!packageJson) return false;
+  let pkg;
+  try {
+    pkg = JSON.parse(packageJson);
+  } catch {
+    return false;
+  }
+  const { pkg: name, version: since } = SDK_SINCE[dialect];
+  const range = [pkg.dependencies, pkg.devDependencies, pkg.peerDependencies].map((deps) => deps && typeof deps === "object" ? deps[name] : void 0).find((v2) => typeof v2 === "string");
+  if (range === void 0) return false;
+  if (range.trim() === "latest" || range.trim() === "*") return true;
+  const match = /^\s*(?:\^|~|>=|=)?\s*v?(\d+)\.(\d+)\.(\d+)/.exec(range);
+  if (!match) return false;
+  const v = [Number(match[1]), Number(match[2]), Number(match[3])];
+  for (let i = 0; i < 3; i++) {
+    if (v[i] !== since[i]) return v[i] > since[i];
+  }
+  return true;
+}
+function elementsIn2(nodes, out = []) {
+  for (const node of nodes) {
+    if (node.type === "element") {
+      out.push(node);
+      elementsIn2(node.children, out);
+    } else if (node.type === "expr") elementsIn2(node.children, out);
+  }
+  return out;
+}
+var lineAt = (content, offset) => content.slice(0, offset).split("\n").length;
+var exprOf2 = (content, range) => content.slice(range.start + 1, range.end - 1).trim();
+var isSpread = (content, attr) => !!attr.expressionRange && content.slice(attr.expressionRange.start, attr.expressionRange.end).trimStart().startsWith("{...");
+var mentions2 = (content, name) => new RegExp(`(?<![\\w$.])${name.replace(/[$]/g, "\\$")}(?![\\w$])`).test(content);
+function importOf(content, matches) {
+  const re = /import\s*\{([^}]*)\}\s*from\s*(["'])([^"']+)\2\s*;?/g;
+  for (const m of content.matchAll(re)) {
+    if (!matches(m[3])) continue;
+    const names = m[1].split(",").map((n) => n.trim()).filter(Boolean);
+    return { start: m.index, end: m.index + m[0].length, names };
+  }
+  return null;
+}
+function addNamedImport(source, content, parsed, specifier, sameModule, names) {
+  const existing = importOf(content, sameModule);
+  if (existing) {
+    const missing = names.filter((n) => !existing.names.some((e) => e === n || e.endsWith(` as ${n}`)));
+    if (missing.length === 0) return;
+    const quote = content.slice(existing.start, existing.end).includes("'") ? "'" : '"';
+    const spec = /from\s*["']([^"']+)["']/.exec(content.slice(existing.start, existing.end))[1];
+    const all = [...existing.names, ...missing].sort((a, b) => a.localeCompare(b));
+    const semi = content.slice(existing.start, existing.end).trimEnd().endsWith(";") ? ";" : "";
+    source.overwrite(existing.start, existing.end, `import { ${all.join(", ")} } from ${quote}${spec}${quote}${semi}`);
+    return;
+  }
+  const line = `import { ${[...names].sort().join(", ")} } from "${specifier}";`;
+  const at = parsed.importAt;
+  if (!at) return;
+  if (at.wrap) source.appendLeft(at.at, `${at.wrap.before}${line}${at.wrap.after}`);
+  else if (at.at === 0) source.appendLeft(0, `${line}
+`);
+  else source.appendLeft(at.at, `
+${line}`);
+}
+var importedFrom = (content, name, sameModule) => !!importOf(content, sameModule)?.names.some((e) => e === name || e.endsWith(` as ${name}`));
+var LIB_PROPS_DOC = "  /** The placement's `block.style`, which the section root paints (`data-bcms-style`). */\n  blockStyle?: Record<string, unknown>;";
+var LIB_PLACEMENT_DOC = "  /** The placement's `block.style` \u2014 what the editor's section spacing and style controls write. */\n  style?: Record<string, unknown>;";
+function insertAfterLine(content, from, to, anchor, addition) {
+  const slice = content.slice(from, to);
+  const m = anchor.exec(slice);
+  if (!m) return null;
+  const eol = content.indexOf("\n", from + m.index);
+  if (eol < 0 || eol > to) return null;
+  const nl = eolOf(content);
+  return content.slice(0, eol + 1) + addition.split("\n").join(nl) + nl + content.slice(eol + 1);
+}
+var eolOf = (content) => content.includes("\r\n") ? "\r\n" : "\n";
+function interfaceBody(content, name) {
+  const at = content.indexOf(`export interface ${name} {`);
+  if (at < 0) return null;
+  const end = content.indexOf("\n}", at);
+  return end < 0 ? null : { start: at, end };
+}
+function patchLib(content) {
+  let out = content;
+  if (!/blockStyle\?:/.test(out)) {
+    const body = interfaceBody(out, "BcmsSectionProps");
+    if (!body) return null;
+    const next = insertAfterLine(out, body.start, body.end, /^\s*page\?: unknown;/m, LIB_PROPS_DOC);
+    if (next === null) return null;
+    out = next;
+  }
+  const placement = interfaceBody(out, "BcmsPlacement");
+  if (!placement) return null;
+  if (!/^\s*style\?:/m.test(out.slice(placement.start, placement.end))) {
+    const next = insertAfterLine(out, placement.start, placement.end, /^\s*overrides\?: Record<string, unknown>;/m, LIB_PLACEMENT_DOC);
+    if (next === null) return null;
+    out = next;
+  }
+  if (!/style: isRecord\(block\.style\)/.test(out)) {
+    const push = /^([ \t]*)overrides: isRecord\(props\.overrides\) \? props\.overrides : undefined,\r?$/m.exec(out);
+    if (!push) return null;
+    const eol = out.indexOf("\n", push.index);
+    out = out.slice(0, eol + 1) + `${push[1]}style: isRecord(block.style) ? block.style : undefined,${eolOf(out)}` + out.slice(eol + 1);
+  }
+  return out;
+}
+function patchRegistry(content) {
+  if (content.includes("blockStyle={placement.style}")) return content;
+  const lines = content.split("\n");
+  const out = [];
+  let patched = 0;
+  for (const line of lines) {
+    out.push(line);
+    const m = /^([ \t]*)overrides=\{placement\.overrides\}(\r?)$/.exec(line);
+    if (m) {
+      out.push(`${m[1]}blockStyle={placement.style}${m[2]}`);
+      patched++;
+    }
+  }
+  return patched > 0 ? out.join("\n") : null;
+}
+var STYLE_READER = { astro: "bcmsSectionStyleText", jsx: "bcmsSectionStyle" };
+var BLOCK_MEMBER = /^([A-Za-z_$][\w$]*)(\??\.)(id|blockId)$/;
+var ID_ONLY = /^(?:(?:Astro\.)?props\??\.)?[A-Za-z_$][\w$]*$/;
+async function upgradeSections(sources, options = {}) {
+  const contents = new Map(sources.map((f) => [f.path, f.content]));
+  const out = /* @__PURE__ */ new Map();
+  const write = (path, content) => {
+    if (contents.get(path) === content) return;
+    out.set(path, { path, operation: contents.has(path) ? "modify" : "add", content });
+  };
+  const receipt = {
+    helpers: [],
+    registry: [],
+    roots: { upgraded: [], alreadyMarked: [], skipped: [] }
+  };
+  let registryOk = true;
+  for (const file of sources) {
+    if (!file.content.includes(REGISTRY_MARKER)) continue;
+    const isLib = file.content.includes("export function pageSections(");
+    const next = isLib ? patchLib(file.content) : patchRegistry(file.content);
+    if (next === null) {
+      registryOk = false;
+      continue;
+    }
+    receipt.registry.push({ path: file.path, operation: next === file.content ? "unchanged" : "modify" });
+    write(file.path, next);
+  }
+  const helperState = /* @__PURE__ */ new Map();
+  const helperDialect = /* @__PURE__ */ new Map();
+  for (const dialect of Object.keys(HELPER_PATH)) {
+    const path = HELPER_PATH[dialect];
+    if (!path || helperDialect.has(path)) continue;
+    helperDialect.set(path, dialect);
+    const existing = contents.get(path);
+    helperState.set(path, existing === void 0 ? void 0 : isKnownHelper(existing, dialect));
+  }
+  const helperNeeded = /* @__PURE__ */ new Set();
+  for (const file of sources) {
+    const dialect = dialectOf(file.path);
+    if (!dialect || !/data-bcms-block|sectionRootAttrs/.test(file.content)) continue;
+    const ref = (el, attr) => ({
+      file: file.path,
+      line: lineAt(file.content, el.start),
+      tag: el.tag,
+      block: attr.expression ? file.content.slice(attr.expressionRange?.start ?? attr.range.start, attr.expressionRange?.end ?? attr.range.end) : JSON.stringify(attr.value)
+    });
+    const skip = (el, attr, reason, message) => {
+      receipt.roots.skipped.push({ ...ref(el, attr), reason, message });
+    };
+    const parsed = await parseFile4(dialect, file.content);
+    if (parsed.error) {
+      receipt.roots.skipped.push({
+        file: file.path,
+        line: 1,
+        tag: "",
+        block: "",
+        reason: "PARSE_ERROR",
+        message: parsed.error.message
+      });
+      continue;
+    }
+    const roots = elementsIn2(parsed.roots).flatMap((el) => {
+      const attr = el.attrs.find((a) => a.name === "data-bcms-block");
+      return attr ? [{ el, attr }] : [];
+    });
+    for (const el of elementsIn2(parsed.roots)) {
+      const spread = el.attrs.find((a) => isSpread(file.content, a) && /sectionRootAttrs\s*\(/.test(file.content.slice(a.expressionRange.start, a.expressionRange.end)));
+      if (spread && !el.attrs.some((a) => a.name === "data-bcms-block")) {
+        receipt.roots.alreadyMarked.push({
+          file: file.path,
+          line: lineAt(file.content, el.start),
+          tag: el.tag,
+          block: file.content.slice(spread.expressionRange.start, spread.expressionRange.end)
+        });
+      }
+    }
+    if (roots.length === 0) continue;
+    if (dialect !== "astro" && dialect !== "jsx") {
+      for (const { el, attr } of roots) {
+        if (el.attrs.some((a) => a.name === "data-bcms-style")) receipt.roots.alreadyMarked.push(ref(el, attr));
+        else skip(el, attr, "DIALECT_UNSUPPORTED", `${dialect} section roots are not rewritten by this pass; add data-bcms-style and the block's style by hand.`);
+      }
+      continue;
+    }
+    const source = new MagicString6(file.content);
+    const reader = STYLE_READER[dialect];
+    const helperPath = HELPER_PATH[dialect];
+    const helperSpecifier = relativeImport(file.path, helperPath).replace(/\.tsx?$/, "");
+    const isHelperModule = (spec) => /(^|\/)bcms-content(\.[jt]sx?)?$/.test(spec);
+    const sdk = SDK_SINCE[dialect].pkg;
+    const isSdk = (spec) => spec === sdk;
+    const useSdk = sdkHasSectionRootAttrs(options.packageJson, dialect);
+    const generated = SECTION_MARKERS.some((m) => file.content.includes(m));
+    const typed = dialect === "astro" || file.path.endsWith(".tsx");
+    const free = (name, from) => importedFrom(file.content, name, from) || !mentions2(file.content, name);
+    let wantReader = false;
+    let wantSdk = false;
+    let sectionProp = false;
+    for (const { el, attr } of roots) {
+      if (el.attrs.some((a) => a.name === "data-bcms-style")) {
+        receipt.roots.alreadyMarked.push(ref(el, attr));
+        continue;
+      }
+      if (!isIntrinsic(el.tag)) {
+        skip(el, attr, "NOT_AN_ELEMENT", `<${el.tag}> is a component: data-bcms-block on it is a prop. Mark the element that component renders.`);
+        continue;
+      }
+      if (el.attrs.some((a) => a.name === "style")) {
+        skip(el, attr, "OWN_STYLE", "The root already sets its own style; a second style attribute would be resolved by the dialect and one of them would vanish. Merge the block's style into it by hand.");
+        continue;
+      }
+      if (el.attrs.some((a) => isSpread(file.content, a))) {
+        skip(el, attr, "SPREAD", "The root spreads props that may carry a style; marking it could promise a style the spread overrides.");
+        continue;
+      }
+      if (!attr.expression || !attr.expressionRange) {
+        skip(el, attr, "BLOCK_LITERAL", "data-bcms-block is a literal id: there is no block object here to read a style from.");
+        continue;
+      }
+      const expr = exprOf2(file.content, attr.expressionRange);
+      if (generated && expr === "blockId") {
+        if (!registryOk) {
+          skip(el, attr, "REGISTRY_UNRECOGNISED", "The generated registry or bcms-sections does not pass block.style and could not be patched; re-run --componentize, then this.");
+          continue;
+        }
+        if (!free(reader, isHelperModule) || /\bblockStyle\b/.test(file.content)) {
+          skip(el, attr, "NAME_TAKEN", `${reader} or blockStyle already means something else in this file.`);
+          continue;
+        }
+        source.appendLeft(attr.range.end, ` data-bcms-style="" style={${reader}(blockStyle)}`);
+        receipt.roots.upgraded.push({ ...ref(el, attr), form: "section-prop" });
+        wantReader = true;
+        sectionProp = true;
+        continue;
+      }
+      const member = BLOCK_MEMBER.exec(expr);
+      if (member) {
+        const [, object, dot, key] = member;
+        if (useSdk && key === "id") {
+          if (!free("sectionRootAttrs", isSdk)) {
+            skip(el, attr, "NAME_TAKEN", "sectionRootAttrs already means something else in this file.");
+            continue;
+          }
+          source.overwrite(attr.range.start, attr.range.end, `{...sectionRootAttrs(${object})}`);
+          receipt.roots.upgraded.push({ ...ref(el, attr), form: "sectionRootAttrs" });
+          wantSdk = true;
+          continue;
+        }
+        if (!free(reader, isHelperModule)) {
+          skip(el, attr, "NAME_TAKEN", `${reader} already means something else in this file.`);
+          continue;
+        }
+        const style = typed && dialect === "jsx" ? `(${object} as { style?: unknown } | null | undefined)?.style` : `${object}${dot}style`;
+        source.appendLeft(attr.range.end, ` data-bcms-style="" style={${reader}(${style})}`);
+        receipt.roots.upgraded.push({ ...ref(el, attr), form: "helper" });
+        wantReader = true;
+        continue;
+      }
+      if (ID_ONLY.test(expr)) {
+        skip(
+          el,
+          attr,
+          "BLOCK_ID_ONLY",
+          `Only a block id reaches this root (${expr}); the block's style is not in scope. Pass the block (or its style) down with the id, then re-run.`
+        );
+        continue;
+      }
+      skip(el, attr, "BLOCK_UNRESOLVABLE", `data-bcms-block={${expr}} does not name one block whose style this root could paint.`);
+    }
+    if (sectionProp) {
+      const destructure = dialect === "astro" ? /const\s*\{([^}]*\bblockId\b[^}]*)\}\s*=\s*Astro\.props\s*;?/.exec(file.content) : /\(\s*\{([^}]*\bblockId\b[^}]*)\}\s*:\s*BcmsSectionProps\s*\)/.exec(file.content);
+      if (destructure) {
+        const close = destructure.index + destructure[0].indexOf("}");
+        let at = close;
+        while (at > 0 && /\s/.test(file.content[at - 1])) at--;
+        source.appendLeft(at, ", blockStyle");
+      }
+      if (dialect === "astro") {
+        const props = /interface Props \{[\s\S]*?\n\}/.exec(file.content);
+        if (props) {
+          const end = props.index + props[0].length - 1;
+          const nl = eolOf(file.content);
+          source.appendLeft(
+            end,
+            `  /** The placement's \`block.style\` \u2014 painted on the root, which says so with \`data-bcms-style\`. */${nl}  blockStyle?: Record<string, unknown>;${nl}`
+          );
+        }
+      }
+    }
+    if (wantReader) {
+      addNamedImport(source, file.content, parsed, helperSpecifier, isHelperModule, [reader]);
+      helperNeeded.add(helperPath);
+    }
+    if (wantSdk) addNamedImport(source, file.content, parsed, sdk, isSdk, ["sectionRootAttrs"]);
+    if (source.hasChanged()) write(file.path, source.toString());
+  }
+  for (const [path, version] of helperState) {
+    const dialect = helperDialect.get(path);
+    const needed = helperNeeded.has(path);
+    if (version === void 0) {
+      if (!needed) continue;
+      write(path, helperSource(dialect));
+      receipt.helpers.push({ path, from: null, to: HELPER_VERSION, operation: "add" });
+      const stub = `${CONTENT_DIR}/layout.json`;
+      if (!contents.has(stub)) write(stub, STUB_CONTENT);
+      continue;
+    }
+    if (version === null) {
+      if (needed && !options.overwriteHelper) {
+        throw new UpgradeError(
+          `${path} already exists and its bytes are not ones @bettercms-ai/convert wrote \u2014 someone else's module, or ours with edits in it. The upgraded roots read bcmsSectionStyle from it. Move it, or re-run with --overwrite-helper.`
+        );
+      }
+      if (needed) {
+        write(path, helperSource(dialect));
+        receipt.helpers.push({ path, from: null, to: HELPER_VERSION, operation: "modify" });
+      } else receipt.helpers.push({ path, from: null, to: HELPER_VERSION, operation: "foreign" });
+      continue;
+    }
+    if (version < HELPER_VERSION) {
+      write(path, helperSource(dialect));
+      receipt.helpers.push({ path, from: version, to: HELPER_VERSION, operation: "modify" });
+    } else receipt.helpers.push({ path, from: version, to: HELPER_VERSION, operation: "unchanged" });
+  }
+  const byPlace = (a, b) => a.file.localeCompare(b.file) || a.line - b.line;
+  receipt.roots.upgraded.sort(byPlace);
+  receipt.roots.alreadyMarked.sort(byPlace);
+  receipt.roots.skipped.sort(byPlace);
+  return { files: [...out.values()].sort((a, b) => a.path.localeCompare(b.path)), receipt };
+}
+
 // src/index.ts
 var UNPARSEABLE_DIALECT = {
   roots: [],
@@ -9532,7 +9897,7 @@ async function convertSources(briefIn, sources, options) {
     rewritten++;
   }
   for (const [file, splices] of [...componentEdits].sort(([a], [b]) => a.localeCompare(b))) {
-    const source = new MagicString6(contents.get(file));
+    const source = new MagicString7(contents.get(file));
     const seen = /* @__PURE__ */ new Set();
     for (const splice of splices) {
       const id = `${splice.start}:${splice.end}:${splice.text}`;
@@ -10326,6 +10691,7 @@ export {
   SSR_DRAFT_RECIPE,
   STUB_CONTENT,
   SectionInvariantError,
+  UpgradeError,
   ValidationError,
   aliasesFrom,
   assertForms,
@@ -10376,6 +10742,7 @@ export {
   routeOfFile,
   stripTags,
   unreadableConfigs,
+  upgradeSections,
   walkAst,
   wireForms
 };