@bettercms-ai/convert 0.21.0 → 0.23.0

package/dist/cli.js

@@ -6,7 +6,7 @@ import { readdir, readFile, writeFile, mkdir, stat } from "fs/promises";
 import { dirname, join as join2, relative, resolve, sep } from "path";
 
 // src/index.ts
-import MagicString6 from "magic-string";
+import MagicString7 from "magic-string";
 
 // src/brief.ts
 import { createHash } from "crypto";
@@ -3767,8 +3767,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) };
       }
     });
@@ -4190,7 +4190,7 @@ async function bindImages(ctx, targets) {
 
 // src/helper.ts
 import { createHash as createHash2 } from "crypto";
-var HELPER_VERSION = 10;
+var HELPER_VERSION = 11;
 var HEADER = "// @bettercms-ai/convert helper v";
 var HELPER_PATH = Object.fromEntries(
   Object.keys(DIALECT_RULES).map((d) => [d, DIALECT_RULES[d].helper])
@@ -4552,6 +4552,46 @@ const STYLE_SPACE_TOKEN_PX: Record<string, string> = {
   "space-xl": "64px",
 };
 
+const STYLE_THEME: Record<string, { colorScheme: string; background: string; color: string }> = {
+  light: { colorScheme: "light", background: "#ffffff", color: "#111111" },
+  dark: { colorScheme: "dark", background: "#0b0b0d", color: "#f7f8f8" },
+};
+const STYLE_BG: Record<string, string> = {
+  surface: "var(--bcms-bg-surface,#ffffff)",
+  muted: "var(--bcms-bg-muted,#f3f4f6)",
+  accent: "var(--bcms-bg-accent,#4f46e5)",
+  dark: "var(--bcms-bg-dark,#0b0b0d)",
+};
+const STYLE_CORNER_PX: Record<string, string> = { "0": "0", s: "4px", m: "8px", l: "16px", xl: "24px", "2xl": "32px" };
+const STYLE_SHADOW: Record<string, string> = {
+  "0": "none",
+  s: "0 1px 2px rgba(0,0,0,.06)",
+  m: "0 4px 12px rgba(0,0,0,.08)",
+  l: "0 10px 24px rgba(0,0,0,.10)",
+  xl: "0 24px 48px rgba(0,0,0,.14)",
+};
+const STYLE_HAIRLINE = "1px solid rgba(0,0,0,.10)";
+
+/** A map entry by OWN key only, so a token like \`constructor\` never reaches CSS. */
+function styleOwn<T>(map: Record<string, T>, key: unknown): T | undefined {
+  return typeof key === "string" && Object.prototype.hasOwnProperty.call(map, key) ? map[key] : undefined;
+}
+
+/** An http(s) or root-relative url with nothing that could end \`url(\u2026)\`; "" for anything else. */
+function styleSafeUrl(raw: unknown): string {
+  if (typeof raw !== "string") return "";
+  const url = raw.trim();
+  if (!url || url.length > 2000) return "";
+  if (/["'()\\;]|\\s/.test(url)) return "";
+  if (url.startsWith("//")) return "";
+  if (url.startsWith("/")) return url;
+  return /^https?:\\/\\//i.test(url) ? url : "";
+}
+
+function styleClamp(n: number, lo: number, hi: number): number {
+  return Math.min(hi, Math.max(lo, n));
+}
+
 function styleSpaceToken(token: unknown): string {
   const px = typeof token === "string" ? STYLE_SPACE_TOKEN_PX[token] : undefined;
   return px ? "var(--bcms-" + token + "," + px + ")" : "";
@@ -4581,6 +4621,25 @@ export function bcmsSectionStyle(style: unknown): Record<string, string | number
   if (s.fontSize && STYLE_FONT_SIZE_REM[s.fontSize]) css.fontSize = STYLE_FONT_SIZE_REM[s.fontSize]!;
   if (s.weight && STYLE_WEIGHT[s.weight] != null) css.fontWeight = STYLE_WEIGHT[s.weight]!;
   if (s.radius && STYLE_RADIUS_PX[s.radius] != null) css.borderRadius = STYLE_RADIUS_PX[s.radius]!;
+  const theme = styleOwn(STYLE_THEME, s.theme);
+  if (theme) { css.colorScheme = theme.colorScheme; css.background = theme.background; css.color = theme.color; }
+  if (s.bg === "custom") { if (/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(s.bgCustom ?? "")) css.background = s.bgCustom!; }
+  else if (styleOwn(STYLE_BG, s.bg)) css.background = styleOwn(STYLE_BG, s.bg)!;
+  const bgImage = styleSafeUrl(s.bgImage);
+  if (bgImage) { css.backgroundImage = "url(" + bgImage + ")"; css.backgroundSize = "cover"; css.backgroundPosition = "center"; }
+  const n = style as Record<string, unknown>;
+  if (!top && typeof n.paddingTop === "number") css.paddingTop = styleClamp(n.paddingTop, 0, 240) + "px";
+  if (!bottom && typeof n.paddingBottom === "number") css.paddingBottom = styleClamp(n.paddingBottom, 0, 240) + "px";
+  if (!sides && typeof n.paddingSides === "number") {
+    const px = styleClamp(n.paddingSides, 0, 240) + "px";
+    css.paddingLeft = px; css.paddingRight = px;
+  }
+  if (n.fullHeight === true) { css.minHeight = "100vh"; css.display = "flex"; css.flexDirection = "column"; css.justifyContent = "center"; }
+  if (typeof n.opacity === "number") css.opacity = styleClamp(n.opacity, 0, 100) / 100;
+  if (styleOwn(STYLE_CORNER_PX, s.corner) != null) { css.borderRadius = styleOwn(STYLE_CORNER_PX, s.corner)!; css.overflow = "hidden"; }
+  if (styleOwn(STYLE_SHADOW, s.shadow)) css.boxShadow = styleOwn(STYLE_SHADOW, s.shadow)!;
+  if (n.borderTop === true) css.borderTop = STYLE_HAIRLINE;
+  if (n.borderBottom === true) css.borderBottom = STYLE_HAIRLINE;
   if ((style as { border?: unknown }).border === true) css.border = "1px solid currentColor";
   return Object.keys(css).length ? css : undefined;
 }
@@ -4605,7 +4664,8 @@ var HISTORICAL = {
     6: "c907e7245578d947c6541b1ab2c5c6659ea7789a1519e895b4a4aed122c6f649",
     7: "f22514ef48c50230985e605bea6cf9bf41756384a7dc80603e347baba9b65d93",
     8: "484e72852d2b496e016a1f2a2b1a77bb993f8a163b290781522d6114b6519bb9",
-    9: "d6441db2ff4578c3c5d4b7d461f3374b89247ef6ba9e0d535791e840d803e4f3"
+    9: "d6441db2ff4578c3c5d4b7d461f3374b89247ef6ba9e0d535791e840d803e4f3",
+    10: "ffcb59862972b15a67c5951e9f3b94ce5b8b50345e6aac2bfa5789cfc3136910"
   },
   "src/lib/bcms-content.ts": {
     1: "ae72ae14d706943d481c880d70da5789b4816ba1ba319a10fbc63ded4d0b42f2",
@@ -4616,7 +4676,8 @@ var HISTORICAL = {
     6: "63f1fa29e47e70c5193b81ee24addb238ba100247124d55bc17713102d587df5",
     7: "ed92fb88de953d9951abbe6a1edae1d048f4050eaf6fb607ac08167f94d8bcc7",
     8: "1a6f669d76d42effe77f082436e9d21c0efa6fc499e919e3d116bc3a27a7f3d5",
-    9: "eee9fb1635ae7d6f8f33676a1f390600ca24a62ee992775252273c73a011c494"
+    9: "eee9fb1635ae7d6f8f33676a1f390600ca24a62ee992775252273c73a011c494",
+    10: "35bb7c0e30f5c41fe68e52259ec4764de6de2734064fa0e1521f3338eef0a09e"
   },
   "composables/bcms-content.ts": {
     1: "c272412532efed7db64b6cf313b2bed4291f9951430412289c8a588b7f565407",
@@ -4627,7 +4688,8 @@ var HISTORICAL = {
     6: "c907e7245578d947c6541b1ab2c5c6659ea7789a1519e895b4a4aed122c6f649",
     7: "f22514ef48c50230985e605bea6cf9bf41756384a7dc80603e347baba9b65d93",
     8: "484e72852d2b496e016a1f2a2b1a77bb993f8a163b290781522d6114b6519bb9",
-    9: "d6441db2ff4578c3c5d4b7d461f3374b89247ef6ba9e0d535791e840d803e4f3"
+    9: "d6441db2ff4578c3c5d4b7d461f3374b89247ef6ba9e0d535791e840d803e4f3",
+    10: "ffcb59862972b15a67c5951e9f3b94ce5b8b50345e6aac2bfa5789cfc3136910"
   }
 };
 var sha256 = (value) => createHash2("sha256").update(value, "utf8").digest("hex");
@@ -9116,6 +9178,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: [],
@@ -9453,7 +9880,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}`;
@@ -10278,7 +10705,7 @@ function styleEdits(before, after) {
 // package.json
 var package_default = {
   name: "@bettercms-ai/convert",
-  version: "0.21.0",
+  version: "0.23.0",
   type: "module",
   description: "Deterministic codemod that turns an imported site's text-matched bindings into declared ones \u2014 parser offsets in, one magic-string pass out, plus a receipt of everything it could not do.",
   bin: {
@@ -10311,7 +10738,7 @@ var package_default = {
   dependencies: {
     "@astrojs/compiler": "^2.13.1",
     "@babel/parser": "^7.29.2",
-    "@bettercms-ai/types": "^1.29.0",
+    "@bettercms-ai/types": "^1.30.0",
     "@vue/compiler-sfc": "^3.5.0",
     "magic-string": "^0.30.21",
     parse5: "^7.3.0",
@@ -10341,6 +10768,7 @@ function parseArgs(argv) {
     componentize: false,
     forms: false,
     pins: {},
+    upgradeSections: false,
     xray: void 0,
     verifyStyles: false,
     base: "HEAD",
@@ -10359,6 +10787,7 @@ function parseArgs(argv) {
     if (arg === "--brief") args.brief = argv[++i];
     else if (arg === "--componentize") args.componentize = true;
     else if (arg === "--forms") args.forms = true;
+    else if (arg === "--upgrade-sections") args.upgradeSections = true;
     else if (arg === "--pin") {
       const raw = argv[++i] ?? "";
       const at = raw.indexOf("=");
@@ -10398,6 +10827,7 @@ var HELP = `bettercms-convert ${VERSION}
   bettercms-convert --brief <json> --root . [options]
   bettercms-convert --componentize --brief <json> --plan <json> --root . [options]
   bettercms-convert --forms --brief <json> --root . [options]
+  bettercms-convert --upgrade-sections --root . [--dry-run]
   bettercms-convert --xray <dist-dir>
   bettercms-convert --verify-styles [--base <ref>] --root .
 
@@ -10410,6 +10840,14 @@ var HELP = `bettercms-convert ${VERSION}
   --pin <form>=<file>  With --forms: the file a form's <form> is in, when the run reports
                        FORM_AMBIGUOUS (two files post exactly its fields). Form by id or
                        name. Repeatable.
+  --upgrade-sections   For a site converted before helper v10: give every section root
+                       (data-bcms-block) the data-bcms-style marker and the block's style,
+                       so the editor's section spacing and style handles turn on. Upgrades
+                       the helper, patches a generated registry to pass block.style, and
+                       spreads {...sectionRootAttrs(block)} where the SDK has it. A root
+                       with its own style or a spread, or whose block is not in scope, is
+                       left alone and listed with its reason. Takes no --brief; a second
+                       run changes nothing. Exit 2 with --strict when any root was skipped.
   --xray <dist-dir>    Measure a LOCAL build instead of converting: how much of each page's
                        visible copy no binding owns, and the biggest buckets of it. Run it
                        after a build to see what the next conversion still has to reach,
@@ -10541,6 +10979,28 @@ ${extracted} sections extracted (${registered} registered, ${inlineOnly} inline-
     );
   }
 }
+function reportUpgrade(files, receipt, dryRun) {
+  for (const file of files) {
+    process.stdout.write(`${dryRun ? "would " : ""}${file.operation} ${file.path}
+`);
+  }
+  for (const h of receipt.helpers) {
+    process.stdout.write(`helper ${h.path} ${h.from === null ? "(none)" : `v${h.from}`} -> v${h.to} (${h.operation})
+`);
+  }
+  for (const r of receipt.registry) process.stdout.write(`registry ${r.path} (${r.operation})
+`);
+  const { upgraded, alreadyMarked, skipped } = receipt.roots;
+  process.stdout.write(
+    `
+${upgraded.length} section roots upgraded (${alreadyMarked.length} already marked, ${skipped.length} skipped)
+`
+  );
+  for (const r of upgraded) process.stdout.write(`  upgraded ${r.file}:${r.line} <${r.tag}> ${r.block} \u2014 ${r.form}
+`);
+  for (const r of skipped) process.stdout.write(`  skipped ${r.file}:${r.line} <${r.tag}> ${r.block} \u2014 ${r.reason}: ${r.message}
+`);
+}
 async function xray(dir, strict) {
   const pages = [];
   const walk = async (at) => {
@@ -10614,6 +11074,31 @@ async function main() {
     return await xray(resolve(args.xray), args.strict);
   }
   if (args.verifyStyles) return await verifyStyles(resolve(args.root), args.base, args.verbose);
+  if (args.upgradeSections) {
+    if (args.brief || args.componentize || args.forms || args.plan) {
+      throw new CliError("--upgrade-sections reads the repository only: no --brief, --plan, --componentize or --forms. See --help.");
+    }
+    const root2 = resolve(args.root);
+    let packageJson;
+    try {
+      packageJson = await readFile(join2(root2, "package.json"), "utf-8");
+    } catch {
+      packageJson = void 0;
+    }
+    const sources2 = [...await readTree(root2, args.verbose), ...await readSnapshots(root2)];
+    const { files: files2, receipt: receipt2 } = await upgradeSections(sources2, { overwriteHelper: args.overwriteHelper, packageJson });
+    if (!args.dryRun) {
+      for (const file of files2) {
+        const target = under(root2, file.path);
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, file.content, "utf-8");
+      }
+    }
+    if (args.receipt) await writeFile(resolve(args.receipt), `${JSON.stringify(receipt2, null, 2)}
+`, "utf-8");
+    reportUpgrade(files2, receipt2, args.dryRun);
+    return args.strict && receipt2.roots.skipped.length > 0 ? 2 : 0;
+  }
   if (!args.brief) throw new CliError("--brief <file> is required. See --help.");
   if (args.plan && !args.componentize) {
     throw new CliError("--plan is only read with --componentize. See --help.");