@bettercms-ai/convert 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @bettercms-ai/convert
 
+## 0.23.0
+
+### Minor Changes
+
+- 6c75c11: `bettercms-convert --upgrade-sections --root .` gives a site converted before helper v10 the section style marker, so the visual editor shows section spacing and style handles on its pages. Every element that carries `data-bcms-block` and no `data-bcms-style` gets the marker together with the style it promises. A component that `--componentize` wrote gets `data-bcms-style="" style={bcmsSectionStyle[Text](blockStyle)}` and the `blockStyle` prop, and its registry and `src/lib/bcms-sections.ts` are patched to pass each placement's `block.style`. The result is byte-identical to what a fresh extraction writes today. `data-bcms-block={block.id}` becomes `{...sectionRootAttrs(block)}` when the SDK range guarantees that export (`@bettercms-ai/astro` 0.19, `@bettercms-ai/next` 0.18), and otherwise gets the marker and `block.style` through the helper. The helper is upgraded to the current version, or added with its layout stub. Roots with their own `style` or a spread, roots that receive only a block id, and literal, conditional or unresolvable blocks are left alone. Each one is listed in the receipt with its reason (`OWN_STYLE`, `SPREAD`, `BLOCK_ID_ONLY`, `BLOCK_LITERAL`, `BLOCK_UNRESOLVABLE`, …). A second run writes nothing, and no class, className or existing style token changes. `--dry-run`, `--receipt`, `--strict` and `--overwrite-helper` work as in the other modes.
+
 ## 0.22.0
 
 ### Minor Changes

package/README.md

@@ -601,6 +601,45 @@ the now-unused `bcms`/snapshot imports P2 added, and a page whose registered cal
 `<Sections>` keeps the imports of the components it used to call. They are harmless at build time
 and removing them would mean editing statements no section asked about.
 
+### Section spacing handles on a site converted before helper v10 (`--upgrade-sections`)
+
+The visual editor shows a page's section spacing and style handles only when EVERY root the build
+stamps with `data-bcms-block` also carries `data-bcms-style` — the site's promise that the root's
+inline style is `blockStyleToCss(block.style)`. Conversions before 0.21 (helper v6–v9, componentize
+v2 sections, hand-written roots) stamp the block and not the marker, so those pages never get
+handles. `get_next_steps` says so (`upgrade-section-roots`) when the release finds such roots.
+
+```bash
+npx @bettercms-ai/convert@latest --upgrade-sections --root . --dry-run   # read the plan
+npx @bettercms-ai/convert@latest --upgrade-sections --root .             # then push and release
+```
+
+Each root with `data-bcms-block` and no `data-bcms-style` gets the marker together with the style:
+
+- a component `--componentize` wrote (`data-bcms-block={blockId}`): `data-bcms-style=""
+  style={bcmsSectionStyle[Text](blockStyle)}`, the `blockStyle` prop, and the registry and
+  `src/lib/bcms-sections.ts` patched to pass `block.style` down — byte-identical to what a fresh
+  extraction writes today;
+- `data-bcms-block={block.id}` where the SDK has `sectionRootAttrs` (`@bettercms-ai/astro` >= 0.19,
+  `@bettercms-ai/next` >= 0.18, read off the LOWEST version the range admits):
+  `{...sectionRootAttrs(block)}`;
+- the same root on an older SDK: `data-bcms-style="" style={bcmsSectionStyle[Text](block.style)}`
+  through the helper, which is upgraded (or added, with its `bcms-content/layout.json` stub).
+
+Left alone, and listed as `skipped` with a reason: `OWN_STYLE` (the root sets its own `style`),
+`SPREAD` (a `{...rest}` that may carry one), `BLOCK_ID_ONLY` (only an id reaches the root —
+`data-bcms-block={Astro.props.bcmsBlock}`; pass the block or its style down), `BLOCK_LITERAL`,
+`BLOCK_UNRESOLVABLE` (a conditional or a call), `NOT_AN_ELEMENT`, `NAME_TAKEN`,
+`REGISTRY_UNRECOGNISED`, `DIALECT_UNSUPPORTED` (html, vue, svelte), `PARSE_ERROR`. A helper this
+package did not write is `HELPER_CONFLICT` (exit 1) only when a root needs it; `--overwrite-helper`
+replaces it.
+
+The receipt (`--receipt <file>`) is `{ helpers, registry, roots: { upgraded, alreadyMarked,
+skipped } }`, each root as `{ file, line, tag, block, form | reason + message }`. No class,
+className or existing style token changes (`--verify-styles` stays clean), and a second run writes
+nothing and counts every root it marked as `alreadyMarked`. `--strict` exits 2 while any root is
+skipped.
+
 ## Forms
 
 The third mode, and the shortest. The release-time derive lane reads every `<form>` in the built

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) };
       }
     });
@@ -9178,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: [],
@@ -9515,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}`;
@@ -10340,7 +10705,7 @@ function styleEdits(before, after) {
 // package.json
 var package_default = {
   name: "@bettercms-ai/convert",
-  version: "0.22.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: {
@@ -10403,6 +10768,7 @@ function parseArgs(argv) {
     componentize: false,
     forms: false,
     pins: {},
+    upgradeSections: false,
     xray: void 0,
     verifyStyles: false,
     base: "HEAD",
@@ -10421,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("=");
@@ -10460,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 .
 
@@ -10472,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,
@@ -10603,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) => {
@@ -10676,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.");