@bettercms-ai/convert 0.22.0 → 0.24.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 = 11;
+var HELPER_VERSION = 12;
 var HEADER = "// @bettercms-ai/convert helper v";
 var HELPER_PATH = Object.fromEntries(
   Object.keys(DIALECT_RULES).map((d) => [d, DIALECT_RULES[d].helper])
@@ -4247,8 +4247,69 @@ function render(value: unknown): string | undefined {
   return undefined;
 }
 
+/**
+ * The PUBLISHED copy, on a server BetterCMS hosts \u2014 read at request time, not at build time.
+ *
+ * BetterCMS keeps one file current for a running server app (\`BCMS_CONTENT_FILE\`, the same
+ * bcms-content.json the build was given) and rewrites it on every publish, so a server-rendered
+ * page shows a publish within seconds instead of after a rebuild. Each snapshot this module reads
+ * resolves to its live counterpart: the shared layout by identity, a page by its \`slug\`.
+ *
+ * Nowhere else does anything change: with no variable (a build, \`astro dev\`, a browser, an edge
+ * runtime) every snapshot is the one the bundle imported, exactly as before. A file that cannot be
+ * read keeps the last good copy; it is checked at most once a second.
+ */
+type BcmsLiveContent = { stamp: number; bySlug: Map<string, unknown>; layout: unknown };
+let bcmsLive: BcmsLiveContent | null = null;
+let bcmsLiveCheckedAt = 0;
+
+function liveContent(): BcmsLiveContent | null {
+  const proc = (globalThis as {
+    process?: { env?: Record<string, string | undefined>; getBuiltinModule?: (id: string) => unknown };
+  }).process;
+  const file = proc?.env?.BCMS_CONTENT_FILE;
+  if (!file || typeof proc?.getBuiltinModule !== "function") return null;
+  const now = Date.now();
+  if (now - bcmsLiveCheckedAt < 1000) return bcmsLive;
+  bcmsLiveCheckedAt = now;
+  try {
+    const fs = proc.getBuiltinModule("node:fs") as {
+      statSync(path: string): { mtimeMs: number };
+      readFileSync(path: string, encoding: "utf8"): string;
+    };
+    const stamp = fs.statSync(file).mtimeMs;
+    if (bcmsLive && bcmsLive.stamp === stamp) return bcmsLive;
+    const snapshot: unknown = JSON.parse(fs.readFileSync(file, "utf8"));
+    const bySlug = new Map<string, unknown>();
+    const collections = isRecord(snapshot) && isRecord(snapshot.collections) ? snapshot.collections : {};
+    for (const rows of Object.values(collections)) {
+      if (!Array.isArray(rows)) continue;
+      for (const row of rows) {
+        if (isRecord(row) && typeof row.slug === "string" && !bySlug.has(row.slug)) bySlug.set(row.slug, row);
+      }
+    }
+    const pages = isRecord(snapshot) && Array.isArray(snapshot.pages) ? snapshot.pages : [];
+    const withLayout = pages.find((page: unknown) => isRecord(page) && isRecord(page.layout));
+    const layout = isRecord(withLayout) ? withLayout.layout : isRecord(snapshot) ? snapshot.layout : undefined;
+    bcmsLive = { stamp, bySlug, layout };
+  } catch {
+    // Unreadable, or caught mid-write: keep serving the last good copy.
+  }
+  return bcmsLive;
+}
+
+/** The published counterpart of a snapshot this module was handed, or the snapshot itself. */
+function live(page: unknown): unknown {
+  const content = liveContent();
+  if (!content) return page;
+  if (page === layoutSnapshot) return isRecord(content.layout) ? content.layout : page;
+  if (isRecord(page) && typeof page.slug === "string") return content.bySlug.get(page.slug) ?? page;
+  return page;
+}
+
 /** One field of one page. \`slug\` selects the entry on a dynamic route. */
 export function bcms(page: unknown, path: string, fallback: string, slug?: string): string {
+  page = live(page);
   const entries = isRecord(page) ? page.entries : undefined;
   const root = slug !== undefined && isRecord(entries) ? entries[slug] : page;
   return render(readPath(root, path)) ?? fallback;
@@ -4256,7 +4317,7 @@ export function bcms(page: unknown, path: string, fallback: string, slug?: strin
 
 /** One field of the shared layout \u2014 the header and footer every route renders. */
 export function bcmsLayout(path: string, fallback: string): string {
-  return render(readPath(layoutSnapshot, path)) ?? fallback;
+  return render(readPath(live(layoutSnapshot), path)) ?? fallback;
 }
 
 /**
@@ -4264,6 +4325,7 @@ export function bcmsLayout(path: string, fallback: string): string {
  * an empty snapshot still renders the same number of cards it always did.
  */
 export function bcmsRows<T>(page: unknown, path: string, fallback: T[], slug?: string): T[] {
+  page = live(page);
   const entries = isRecord(page) ? page.entries : undefined;
   const root = slug !== undefined && isRecord(entries) ? entries[slug] : page;
   const value = readPath(root, path);
@@ -4309,6 +4371,7 @@ export function bcmsRowsAs<T>(
  * this out loud rather than leaving an editor to discover it.
  */
 export function bcmsList(page: unknown, paths: string[], fallback: string[], slug?: string): string[] {
+  page = live(page);
   const entries = isRecord(page) ? page.entries : undefined;
   const root = slug !== undefined && isRecord(entries) ? entries[slug] : page;
   return paths.map((path, index) => render(readPath(root, path)) ?? fallback[index] ?? "");
@@ -4333,6 +4396,7 @@ export function bcmsTuples(page: unknown, paths: string[][], fallback: string[][
  * no such rule and takes the CMS url directly.
  */
 export function bcmsImage<T>(page: unknown, path: string, fallback: T, slug?: string): T | string {
+  page = live(page);
   if (fallback !== null && typeof fallback === "object") return fallback;
   const entries = isRecord(page) ? page.entries : undefined;
   const root = slug !== undefined && isRecord(entries) ? entries[slug] : page;
@@ -4361,6 +4425,7 @@ export function bcmsSection(
   overrides?: unknown,
   bindPaths?: Record<string, string>,
 ): Record<string, unknown> {
+  page = live(page);
   const group = bind ? readPath(page, bind) : undefined;
   const base: Record<string, unknown> = isRecord(group) ? { ...group } : {};
   // A locale copy on its twin's component spells its fields its own way: each prop's copy is
@@ -4432,6 +4497,7 @@ export function bcmsSectionPaths(
   map: BcmsPathMap,
   bindPaths?: Record<string, string>,
 ): Record<string, unknown> {
+  page = live(page);
   const out: Record<string, unknown> = isRecord(page) ? { ...page } : {};
   const own = isRecord(overrides) ? overrides : {};
   const separator = prefix.slice(-1);
@@ -4665,7 +4731,8 @@ var HISTORICAL = {
     7: "f22514ef48c50230985e605bea6cf9bf41756384a7dc80603e347baba9b65d93",
     8: "484e72852d2b496e016a1f2a2b1a77bb993f8a163b290781522d6114b6519bb9",
     9: "d6441db2ff4578c3c5d4b7d461f3374b89247ef6ba9e0d535791e840d803e4f3",
-    10: "ffcb59862972b15a67c5951e9f3b94ce5b8b50345e6aac2bfa5789cfc3136910"
+    10: "ffcb59862972b15a67c5951e9f3b94ce5b8b50345e6aac2bfa5789cfc3136910",
+    11: "ceb2a932d4c2761a5045ff35032e0b45130a0b5034547ff37579c72c9ce3594e"
   },
   "src/lib/bcms-content.ts": {
     1: "ae72ae14d706943d481c880d70da5789b4816ba1ba319a10fbc63ded4d0b42f2",
@@ -4677,7 +4744,8 @@ var HISTORICAL = {
     7: "ed92fb88de953d9951abbe6a1edae1d048f4050eaf6fb607ac08167f94d8bcc7",
     8: "1a6f669d76d42effe77f082436e9d21c0efa6fc499e919e3d116bc3a27a7f3d5",
     9: "eee9fb1635ae7d6f8f33676a1f390600ca24a62ee992775252273c73a011c494",
-    10: "35bb7c0e30f5c41fe68e52259ec4764de6de2734064fa0e1521f3338eef0a09e"
+    10: "35bb7c0e30f5c41fe68e52259ec4764de6de2734064fa0e1521f3338eef0a09e",
+    11: "818784f2088150d64d91b42eac944dc9503f104d32a0e7a18c753d2982a5adc0"
   },
   "composables/bcms-content.ts": {
     1: "c272412532efed7db64b6cf313b2bed4291f9951430412289c8a588b7f565407",
@@ -4689,7 +4757,8 @@ var HISTORICAL = {
     7: "f22514ef48c50230985e605bea6cf9bf41756384a7dc80603e347baba9b65d93",
     8: "484e72852d2b496e016a1f2a2b1a77bb993f8a163b290781522d6114b6519bb9",
     9: "d6441db2ff4578c3c5d4b7d461f3374b89247ef6ba9e0d535791e840d803e4f3",
-    10: "ffcb59862972b15a67c5951e9f3b94ce5b8b50345e6aac2bfa5789cfc3136910"
+    10: "ffcb59862972b15a67c5951e9f3b94ce5b8b50345e6aac2bfa5789cfc3136910",
+    11: "ceb2a932d4c2761a5045ff35032e0b45130a0b5034547ff37579c72c9ce3594e"
   }
 };
 var sha256 = (value) => createHash2("sha256").update(value, "utf8").digest("hex");
@@ -9178,6 +9247,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 +9949,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 +10774,7 @@ function styleEdits(before, after) {
 // package.json
 var package_default = {
   name: "@bettercms-ai/convert",
-  version: "0.22.0",
+  version: "0.24.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 +10837,7 @@ function parseArgs(argv) {
     componentize: false,
     forms: false,
     pins: {},
+    upgradeSections: false,
     xray: void 0,
     verifyStyles: false,
     base: "HEAD",
@@ -10421,6 +10856,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 +10896,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 +10909,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 +11048,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 +11143,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.");