@bettercms-ai/convert 0.1.0 → 0.2.0

package/dist/cli.js

@@ -5,7 +5,7 @@ import { readdir, readFile, writeFile, mkdir, stat } from "fs/promises";
 import { dirname, join as join2, relative, resolve, sep } from "path";
 
 // src/index.ts
-import MagicString3 from "magic-string";
+import MagicString4 from "magic-string";
 
 // src/brief.ts
 import { createHash } from "crypto";
@@ -134,7 +134,7 @@ function propsAttribute(props) {
 
 // src/helper.ts
 import { createHash as createHash2 } from "crypto";
-var HELPER_VERSION = 2;
+var HELPER_VERSION = 3;
 var HEADER = "// @bettercms-ai/convert helper v";
 var HELPER_PATH = Object.fromEntries(
   Object.keys(DIALECT_RULES).map((d) => [d, DIALECT_RULES[d].helper])
@@ -213,12 +213,37 @@ export function bcmsRows<T>(page: unknown, path: string, fallback: T[], slug?: s
   const value = readPath(root, path);
   return Array.isArray(value) ? (value as T[]) : fallback;
 }
+
+/**
+ * ONE SECTION's copy, for a component extracted by \`--componentize\`.
+ *
+ * \`overrides ?? pageGroup(bind) ?? defaults\` \u2014 the instance's own values when the editor gave it
+ * any, otherwise the page field group the placement is bound to, otherwise nothing at all, in
+ * which case every \`bcms(...)\` below renders the fallback the template shipped with. That last
+ * step is why a section renders correctly against the committed \`{}\` stub.
+ */
+export function bcmsSection(page: unknown, bind?: string, overrides?: unknown): Record<string, unknown> {
+  // \u{1F534} AN EMPTY OBJECT IS AN ANSWER. \`overrides: {}\` is an instance an editor cleared, and
+  // "\`??\` unless it happens to be empty" quietly put the page's copy back into it.
+  if (isRecord(overrides)) return overrides;
+  const group = bind ? readPath(page, bind) : undefined;
+  return isRecord(group) ? group : {};
+}
 `;
 }
 var HISTORICAL = {
-  "src/bcms-content.ts": { 1: "c272412532efed7db64b6cf313b2bed4291f9951430412289c8a588b7f565407" },
-  "src/lib/bcms-content.ts": { 1: "ae72ae14d706943d481c880d70da5789b4816ba1ba319a10fbc63ded4d0b42f2" },
-  "composables/bcms-content.ts": { 1: "c272412532efed7db64b6cf313b2bed4291f9951430412289c8a588b7f565407" }
+  "src/bcms-content.ts": {
+    1: "c272412532efed7db64b6cf313b2bed4291f9951430412289c8a588b7f565407",
+    2: "51e2ae65ddd86bf43d14e29b3865e3f16e45f72069692d1fea57e1f986a894f0"
+  },
+  "src/lib/bcms-content.ts": {
+    1: "ae72ae14d706943d481c880d70da5789b4816ba1ba319a10fbc63ded4d0b42f2",
+    2: "a18731eb42f7db55dac0591c45f873758cde8e103fefcd6e5caf67936ae6a002"
+  },
+  "composables/bcms-content.ts": {
+    1: "c272412532efed7db64b6cf313b2bed4291f9951430412289c8a588b7f565407",
+    2: "51e2ae65ddd86bf43d14e29b3865e3f16e45f72069692d1fea57e1f986a894f0"
+  }
 };
 var sha256 = (value) => createHash2("sha256").update(value, "utf8").digest("hex");
 function isKnownHelper(content, dialect) {
@@ -3069,7 +3094,9 @@ function attrsOf2(open, content) {
           value: content.slice(argument?.start ?? 0, argument?.end ?? 0),
           valueRange: null,
           expression: true,
-          range: { start: attr.start ?? 0, end: attr.end ?? 0 }
+          range: { start: attr.start ?? 0, end: attr.end ?? 0 },
+          // `{...props}` — the braces ARE the attribute, so the expression is its whole span.
+          expressionRange: { start: attr.start ?? 0, end: attr.end ?? 0 }
         }
       ];
     }
@@ -3084,7 +3111,8 @@ function attrsOf2(open, content) {
         // The quotes are one character each on a StringLiteral; babel's range covers them.
         valueRange: literal ? { start: (value.start ?? 0) + 1, end: (value.end ?? 0) - 1 } : null,
         expression: !literal,
-        range
+        range,
+        expressionRange: value?.type === "JSXExpressionContainer" ? { start: value.start ?? 0, end: value.end ?? 0 } : null
       }
     ];
   });
@@ -3149,6 +3177,7 @@ function convert(node, content) {
       type: "element",
       tag,
       start,
+      end: node.end ?? start,
       // Babel's own offsets: the last attribute's `end`, or the end of the element's NAME. Both
       // come out of the parse, so an escaped quote inside an attribute cannot move them.
       attrInsertAt: node.type === "JSXFragment" ? start + 1 : attrInsertAfter(attrs, open?.start ?? start, tag),
@@ -3584,8 +3613,9 @@ function importsIn(parsed, _dialect) {
       if (entry.importKind === "type") continue;
       const local = entry.local?.name;
       if (typeof local !== "string") continue;
-      const imported = entry.type === "ImportDefaultSpecifier" ? null : entry.imported?.name ?? local;
-      out.set(local, { specifier, imported });
+      const kind = entry.type === "ImportDefaultSpecifier" ? "default" : entry.type === "ImportNamespaceSpecifier" ? "namespace" : "named";
+      const imported = kind === "named" ? entry.imported?.name ?? local : null;
+      out.set(local, { specifier, imported, kind });
     }
   });
   return out;
@@ -3593,6 +3623,33 @@ function importsIn(parsed, _dialect) {
 
 // src/routes.ts
 var isDynamicRoute = (file) => file.split("/").some((segment) => /^\[.+\]/.test(segment) || /\[.+\]\.[a-z]+$/i.test(segment));
+var PAGE_EXTENSIONS = /* @__PURE__ */ new Set(["astro", "tsx", "jsx", "ts", "js", "svelte", "vue"]);
+var isOrganisational = (segment) => segment.startsWith("(") && segment.endsWith(")") || segment.startsWith("@");
+function routeOfFile(file) {
+  const extension = file.slice(file.lastIndexOf(".") + 1);
+  if (!PAGE_EXTENSIONS.has(extension)) return null;
+  let parts = file.split("/");
+  if (parts[0] === "src") parts = parts.slice(1);
+  if (parts[0] === "app" && parts[1] === "pages") parts = parts.slice(1);
+  const router = parts[0];
+  if (router !== "pages" && router !== "app" && router !== "routes") return null;
+  let segments = parts.slice(1);
+  const last = segments[segments.length - 1];
+  if (last === void 0) return null;
+  const base = last.slice(0, last.lastIndexOf("."));
+  if (router === "pages") {
+    segments = [...segments.slice(0, -1), ...base === "index" ? [] : [base]];
+  } else {
+    if (base !== "page" && base !== "+page") return null;
+    segments = segments.slice(0, -1);
+  }
+  const url = segments.filter((segment) => !isOrganisational(segment));
+  return `/${url.join("/")}`.replace(/\/{2,}/g, "/");
+}
+function pageFilesFor(route, files) {
+  const wanted = route === "" ? "/" : route.replace(/\/+$/, "") || "/";
+  return [...files].filter((file) => routeOfFile(file) === wanted).sort();
+}
 var FUNCTIONS2 = /* @__PURE__ */ new Set(["FunctionDeclaration", "FunctionExpression", "ArrowFunctionExpression"]);
 function defaultComponent(ast) {
   let found = null;
@@ -3854,7 +3911,7 @@ function namesFile(fromFile, specifier, target) {
 function snapshotLocal(parsed, dialect, slug, file) {
   const target = `${CONTENT_DIR}/${slug}.json`;
   for (const [local, from] of importsIn(parsed, dialect)) {
-    if (from.imported !== null) continue;
+    if (from.kind !== "default") continue;
     if (namesFile(file, from.specifier, target)) return local;
   }
   return null;
@@ -4064,6 +4121,8 @@ var attrsOf3 = (el, content) => {
       value: attr.value,
       valueRange,
       expression: false,
+      // parse5 reads HTML, which has no expressions at all.
+      expressionRange: null,
       range: range ?? { start: 0, end: 0 }
     };
   });
@@ -4094,6 +4153,7 @@ function convert2(node, content) {
       type: "element",
       tag: el.tagName,
       start,
+      end: at.endOffset,
       attrInsertAt: insertAt,
       inner,
       attrs,
@@ -4114,6 +4174,18 @@ function parse2(content) {
 // src/sites/astro.ts
 import { parse as parse3 } from "@astrojs/compiler";
 import { parse as parseScript } from "@babel/parser";
+function byteToChar(content) {
+  if (!/[^\u0000-\u007f]/.test(content)) return null;
+  const bytes = [];
+  for (let at = 0; at < content.length; ) {
+    const code = content.codePointAt(at);
+    const width = code < 128 ? 1 : code < 2048 ? 2 : code < 65536 ? 3 : 4;
+    for (let n = 0; n < width; n++) bytes.push(at);
+    at += code < 65536 ? 1 : 2;
+  }
+  bytes.push(content.length);
+  return (offset) => bytes[offset] ?? content.length;
+}
 var RAW_TAGS2 = /* @__PURE__ */ new Set(["script", "style"]);
 var backOverSpace = (content, at) => {
   let end = at;
@@ -4160,6 +4232,8 @@ function attrsOf4(node, content) {
     const raw = attr.raw ?? "";
     const end = attrEnd(content, attr, start, attributes[at + 1]?.position?.start?.offset);
     const range = { start, end };
+    const open = attr.kind === "spread" || attr.kind === "shorthand" ? content.lastIndexOf("{", start) : content.indexOf("{", start + attr.name.length);
+    const close = content.lastIndexOf("}", end);
     const quoted = attr.kind === "quoted";
     const rawStart = quoted ? content.indexOf(raw, start) : -1;
     const unquoted = raw.length === attr.value.length;
@@ -4169,7 +4243,8 @@ function attrsOf4(node, content) {
         value: attr.value,
         valueRange: quoted && rawStart >= 0 && attr.value !== "" ? { start: rawStart + (unquoted ? 0 : 1), end: rawStart + raw.length - (unquoted ? 0 : 1) } : null,
         expression: !quoted,
-        range
+        range,
+        expressionRange: !quoted && open >= 0 && close > open ? { start: open, end: close + 1 } : null
       }
     ];
   });
@@ -4208,11 +4283,13 @@ function convert3(node, content) {
   const reportedEnd = node.position?.end?.offset;
   const closes = reportedEnd !== void 0 && content.slice(reportedEnd - closeTag.length, reportedEnd) === closeTag;
   const inner = closes ? { start: content.indexOf(">", insertAt) + 1, end: reportedEnd - closeTag.length } : null;
+  const end = closes ? reportedEnd : content.indexOf(">", insertAt) + 1;
   return [
     {
       type: "element",
       tag,
       start,
+      end,
       attrInsertAt: insertAt,
       inner,
       attrs,
@@ -4221,11 +4298,26 @@ function convert3(node, content) {
     }
   ];
 }
+function remap(nodes, at) {
+  for (const node of nodes) {
+    const start = node.position?.start;
+    if (start?.offset !== void 0) start.offset = at(start.offset);
+    const end = node.position?.end;
+    if (end?.offset !== void 0) end.offset = at(end.offset);
+    for (const attr of node.attributes ?? []) {
+      const attrStart = attr.position?.start;
+      if (attrStart?.offset !== void 0) attrStart.offset = at(attrStart.offset);
+    }
+    remap(node.children ?? [], at);
+  }
+}
 async function parseFile(content) {
   let top;
   try {
     const result = await parse3(content, { position: true });
     top = result.ast.children ?? [];
+    const at = byteToChar(content);
+    if (at) remap(top, at);
   } catch (error) {
     return { roots: [], error: { code: "PARSE_ERROR", message: error.message } };
   }
@@ -4267,7 +4359,7 @@ function attrsOf5(node) {
     const name = typeof attr.name === "string" ? attr.name : attr.type;
     const range = { start: attr.start ?? 0, end: attr.end ?? 0 };
     if (attr.type !== "Attribute") {
-      return [{ name: `\0${name}`, value: "", valueRange: null, expression: true, range }];
+      return [{ name: `\0${name}`, value: "", valueRange: null, expression: true, expressionRange: null, range }];
     }
     const literal = literalValue(attr);
     return [
@@ -4276,6 +4368,8 @@ function attrsOf5(node) {
         value: literal?.value ?? "",
         valueRange: literal && literal.value !== "" ? literal.range : null,
         expression: literal === null,
+        // Not read: svelte sections are DIALECT_UNSUPPORTED. @see componentize.ts
+        expressionRange: null,
         range
       }
     ];
@@ -4321,6 +4415,7 @@ function convert4(node, content) {
       type: "element",
       tag,
       start,
+      end,
       attrInsertAt: insertAt,
       inner: closes ? { start: content.indexOf(">", insertAt) + 1, end: end - close.length } : null,
       attrs,
@@ -4385,6 +4480,7 @@ function attrsOf6(node) {
           value: "",
           valueRange: null,
           expression: true,
+          expressionRange: null,
           range: spanOf(prop.loc)
         }
       ];
@@ -4396,6 +4492,7 @@ function attrsOf6(node) {
           value: "",
           valueRange: null,
           expression: true,
+          expressionRange: null,
           range: spanOf(prop.loc)
         }
       ];
@@ -4409,6 +4506,7 @@ function attrsOf6(node) {
         value,
         valueRange: quoted && value !== "" ? { start: quoted.start + 1, end: quoted.end - 1 } : null,
         expression: false,
+        expressionRange: null,
         range
       }
     ];
@@ -4438,6 +4536,7 @@ function convert5(node, content) {
       type: "element",
       tag,
       start,
+      end,
       attrInsertAt: insertAt,
       inner: closes ? { start: content.indexOf(">", insertAt) + 1, end: end - close.length } : null,
       attrs,
@@ -4533,6 +4632,123 @@ function findSitesTolerant(content, literals) {
   return sites;
 }
 
+// src/validate.ts
+var SAFE_SEGMENT = /^[A-Za-z0-9_-]{1,64}$/;
+var ROUTE = /^\/(?:[A-Za-z0-9_\-.~%$@+[\]()!'*,:=&]+(?:\/[A-Za-z0-9_\-.~%$@+[\]()!'*,:=&]+)*\/?)?$/;
+var ValidationError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "ValidationError";
+  }
+  code;
+};
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var Check = class {
+  constructor(code) {
+    this.code = code;
+  }
+  code;
+  fail(where, why) {
+    throw new ValidationError(this.code, `${where} ${why}.`);
+  }
+  record(value, where) {
+    if (!isRecord(value)) this.fail(where, "is not an object");
+    return value;
+  }
+  array(value, where) {
+    if (!Array.isArray(value)) this.fail(where, "is not an array");
+    return value;
+  }
+  string(value, where) {
+    if (typeof value !== "string") this.fail(where, "is not a string");
+    return value;
+  }
+  optionalString(value, where) {
+    if (value === void 0 || value === null) return void 0;
+    return this.string(value, where);
+  }
+  /** A value that becomes a FILE NAME or an object key in generated source. @see SAFE_SEGMENT */
+  segment(value, where) {
+    const held = this.string(value, where);
+    if (!SAFE_SEGMENT.test(held)) {
+      this.fail(where, `is not a safe path segment (${JSON.stringify(held)}); expected ${SAFE_SEGMENT.source}`);
+    }
+    return held;
+  }
+  route(value, where) {
+    const held = this.string(value, where);
+    if (!ROUTE.test(held) || held.includes("..")) this.fail(where, `is not an absolute URL path (${JSON.stringify(held)})`);
+    return held;
+  }
+};
+function readBrief(value) {
+  const check = new Check("BRIEF_INVALID");
+  const brief = check.record(value, "the brief");
+  const pages = check.array(brief.pages, `the brief's "pages"`);
+  for (const [at, entry] of pages.entries()) {
+    const where = `brief.pages[${at}]`;
+    const page = check.record(entry, where);
+    check.segment(page.slug, `${where}.slug`);
+    check.route(page.route, `${where}.route`);
+    for (const [n, held] of check.array(page.paths, `${where}.paths`).entries()) {
+      const path = check.record(held, `${where}.paths[${n}]`);
+      check.string(path.path, `${where}.paths[${n}].path`);
+      check.string(path.kind, `${where}.paths[${n}].kind`);
+      const scope = check.optionalString(path.scope, `${where}.paths[${n}].scope`);
+      if (scope !== void 0 && scope !== "page" && scope !== "layout") {
+        check.fail(`${where}.paths[${n}].scope`, 'is neither "page" nor "layout"');
+      }
+      if (path.original !== null && path.original !== void 0 && typeof path.original !== "string") {
+        check.fail(`${where}.paths[${n}].original`, "is not a string or null");
+      }
+    }
+  }
+  return brief;
+}
+function readPlan(value) {
+  const check = new Check("PLAN_INVALID");
+  const plan2 = check.record(value, "the plan");
+  if (!Array.isArray(plan2.pages)) check.fail(`the plan's "pages"`, "is missing or not an array");
+  for (const [at, entry] of plan2.pages.entries()) {
+    const where = `plan.pages[${at}]`;
+    const page = check.record(entry, where);
+    check.route(page.route, `${where}.route`);
+    if (page.sections === void 0) continue;
+    for (const [n, held] of check.array(page.sections, `${where}.sections`).entries()) {
+      const at2 = `${where}.sections[${n}]`;
+      const section = check.record(held, at2);
+      check.segment(section.groupKey, `${at2}.groupKey`);
+      check.optionalString(section.sectionType, `${at2}.sectionType`);
+      if (section.fields !== void 0) {
+        for (const [f, field] of check.array(section.fields, `${at2}.fields`).entries()) {
+          const shape = check.record(field, `${at2}.fields[${f}]`);
+          check.optionalString(shape.key, `${at2}.fields[${f}].key`);
+          check.optionalString(shape.path, `${at2}.fields[${f}].path`);
+        }
+      }
+      if (section.reuse !== void 0) {
+        const reuse = check.record(section.reuse, `${at2}.reuse`);
+        check.optionalString(reuse.componentId, `${at2}.reuse.componentId`);
+        if (reuse.proposedSlug !== void 0) check.segment(reuse.proposedSlug, `${at2}.reuse.proposedSlug`);
+      }
+      if (section.pending !== void 0) check.record(section.pending, `${at2}.pending`);
+    }
+  }
+  if (plan2.components !== void 0) {
+    for (const [at, entry] of check.array(plan2.components, `the plan's "components"`).entries()) {
+      const where = `plan.components[${at}]`;
+      const component = check.record(entry, where);
+      check.segment(component.proposedSlug, `${where}.proposedSlug`);
+      check.optionalString(component.name, `${where}.name`);
+      check.optionalString(component.sectionType, `${where}.sectionType`);
+      check.optionalString(component.componentId, `${where}.componentId`);
+    }
+  }
+  check.optionalString(plan2.digest, `the plan's "digest"`);
+  return plan2;
+}
+
 // src/scan.ts
 var SKIP_DIRS = [
   "node_modules/",
@@ -4579,6 +4795,1104 @@ function isSourceCandidate(path) {
   return SOURCE_EXTENSIONS.some((ext) => lower.endsWith(ext));
 }
 
+// src/carry.ts
+var GLOBALS = /* @__PURE__ */ new Set([
+  "Astro",
+  "Fragment",
+  "React",
+  "JSX",
+  "globalThis",
+  "undefined",
+  "null",
+  "true",
+  "false",
+  "NaN",
+  "Infinity",
+  "Math",
+  "JSON",
+  "Object",
+  "Array",
+  "String",
+  "Number",
+  "Boolean",
+  "Date",
+  "RegExp",
+  "Map",
+  "Set",
+  "WeakMap",
+  "WeakSet",
+  "Promise",
+  "Symbol",
+  "BigInt",
+  "Error",
+  "Intl",
+  "URL",
+  "URLSearchParams",
+  "console",
+  "process",
+  "window",
+  "document",
+  "navigator",
+  "fetch",
+  "isNaN",
+  "isFinite",
+  "parseInt",
+  "parseFloat",
+  "encodeURIComponent",
+  "decodeURIComponent",
+  "structuredClone",
+  "import",
+  "arguments",
+  "this",
+  "void",
+  "typeof"
+]);
+function carryFor(options) {
+  const { dialect, fromFile, toFile, content, parsed, root } = options;
+  const wanted = referencedNames(root, content);
+  if (wanted === null) {
+    return { imports: [], declarations: [], free: ["<an expression this version cannot read>"] };
+  }
+  const provided = new Set(options.provided);
+  const imports = importsIn(parsed, dialect);
+  const declarations = moduleScope(parsed, content);
+  const carriedImports = /* @__PURE__ */ new Map();
+  const carriedDeclarations = /* @__PURE__ */ new Map();
+  const free = /* @__PURE__ */ new Set();
+  const seen = /* @__PURE__ */ new Set();
+  const queue = [...wanted];
+  while (queue.length > 0) {
+    const name = queue.shift();
+    if (seen.has(name) || provided.has(name) || GLOBALS.has(name)) continue;
+    seen.add(name);
+    const imported = imports.get(name);
+    if (imported) {
+      if (skipImport(imported.specifier, fromFile, options.skipSpecifier)) continue;
+      const specifier = imported.specifier.startsWith(".") ? relativeImport(toFile, joinFrom(fromFile, imported.specifier)) : imported.specifier;
+      carriedImports.set(
+        name,
+        imported.kind === "namespace" ? `import * as ${name} from "${specifier}";` : imported.kind === "default" ? `import ${name} from "${specifier}";` : `import { ${imported.imported === name ? name : `${imported.imported} as ${name}`} } from "${specifier}";`
+      );
+      continue;
+    }
+    const declared = declarations.get(name);
+    if (declared) {
+      carriedDeclarations.set(declared.at, declared.text);
+      queue.push(...declared.uses);
+      continue;
+    }
+    free.add(name);
+  }
+  return {
+    imports: [...new Set(carriedImports.values())].sort(),
+    declarations: [...carriedDeclarations].sort(([a], [b]) => a - b).map(([, text]) => text),
+    free: [...free].sort()
+  };
+}
+function skipImport(specifier, fromFile, skip) {
+  return skip(specifier.startsWith(".") ? joinFrom(fromFile, specifier) : "", specifier);
+}
+function joinFrom(fromFile, specifier) {
+  const parts = fromFile.split("/").slice(0, -1);
+  for (const segment of specifier.split("/")) {
+    if (segment === "." || segment === "") continue;
+    if (segment === "..") parts.pop();
+    else parts.push(segment);
+  }
+  return parts.join("/");
+}
+function referencedNames(root, content) {
+  const used = /* @__PURE__ */ new Set();
+  const add = (code, scope) => {
+    const scanned = scanExpression(code);
+    if (!scanned) return null;
+    for (const name of scanned.free) {
+      if (!scope.some((held) => held.has(name))) used.add(name);
+    }
+    return scanned.bound;
+  };
+  const visit = (node, bounds, scope) => {
+    if (node.type === "expr") {
+      const start = Math.max(node.range.start, bounds.start);
+      const end = Math.min(node.range.end, bounds.end);
+      const holes = node.children.flatMap(
+        (child) => child.type === "element" ? [{ start: child.start, end: child.end }] : []
+      );
+      let text = "";
+      let at = start;
+      for (const hole of [...holes].sort((a, b) => a.start - b.start)) {
+        if (hole.start < at || hole.end > end) continue;
+        text += `${content.slice(at, hole.start)}null`;
+        at = hole.end;
+      }
+      text += content.slice(at, end);
+      const open = text.indexOf("{");
+      const close = text.lastIndexOf("}");
+      const bound = add(open >= 0 && close > open ? text.slice(open + 1, close) : text, scope);
+      if (!bound) return false;
+      const inner2 = [...scope, bound];
+      for (const child of node.children) if (!visit(child, bounds, inner2)) return false;
+      return true;
+    }
+    if (node.type !== "element") return true;
+    if (!isIntrinsic(node.tag) && node.tag !== "") {
+      const tag = node.tag.split(".")[0];
+      if (!scope.some((held) => held.has(tag))) used.add(tag);
+    }
+    for (const attr of node.attrs) {
+      if (!attr.expression) continue;
+      const span = attr.expressionRange;
+      if (!span) continue;
+      const raw = content.slice(span.start, span.end);
+      if (add(stripBraces(raw), scope) === null) return false;
+    }
+    const inner = node.inner ?? bounds;
+    const kids = node.children;
+    for (const [at, child] of kids.entries()) {
+      const next = kids[at + 1];
+      const stop = next ? next.type === "element" ? next.start : next.range.start : inner.end;
+      if (!visit(child, { start: inner.start, end: Math.min(inner.end, stop) }, scope)) return false;
+    }
+    return true;
+  };
+  return visit(root, { start: root.start, end: root.end }, []) ? used : null;
+}
+function stripBraces(text) {
+  const trimmed = text.trim();
+  const inner = trimmed.startsWith("{") && trimmed.endsWith("}") ? trimmed.slice(1, -1) : trimmed;
+  return inner.trim().startsWith("...") ? inner.trim().slice(3) : inner;
+}
+function scanExpression(code) {
+  if (code.trim() === "") return { free: /* @__PURE__ */ new Set(), bound: /* @__PURE__ */ new Set() };
+  let ast;
+  try {
+    ast = parseProgram(`(${code}
+)`);
+  } catch {
+    try {
+      ast = parseProgram(code);
+    } catch {
+      return null;
+    }
+  }
+  const candidates = /* @__PURE__ */ new Set();
+  const skip = /* @__PURE__ */ new Set();
+  const bound = /* @__PURE__ */ new Set();
+  walkAst(ast, (node) => {
+    switch (node.type) {
+      case "Identifier":
+      case "JSXIdentifier":
+        if (typeof node.name === "string") candidates.add(node.name);
+        return;
+      case "MemberExpression":
+      case "OptionalMemberExpression":
+      case "JSXMemberExpression":
+        if (!node.computed) nameOf2(node.property, skip);
+        return;
+      case "ObjectProperty":
+      case "ObjectMethod":
+      case "ClassProperty":
+      case "ClassMethod":
+        if (!node.computed) nameOf2(node.key, skip);
+        return;
+      case "JSXAttribute":
+        nameOf2(node.name, skip);
+        return;
+      case "JSXOpeningElement":
+      case "JSXClosingElement": {
+        const name = node.name;
+        if (name?.type === "JSXIdentifier" && typeof name.name === "string") skip.add(name.name);
+        return;
+      }
+      case "TSTypeReference":
+      case "TSQualifiedName":
+      case "TSInterfaceDeclaration":
+      case "TSTypeAliasDeclaration":
+        for (const key of ["typeName", "left", "right", "id"]) nameOf2(node[key], skip);
+        return;
+      case "VariableDeclarator":
+        patternNames2(node.id, bound);
+        return;
+      case "CatchClause":
+        patternNames2(node.param, bound);
+        return;
+      default:
+        return;
+    }
+  });
+  walkAst(ast, (node) => {
+    if (node.type === "ArrowFunctionExpression" || node.type === "FunctionExpression" || node.type === "FunctionDeclaration" || node.type === "ObjectMethod" || node.type === "ClassMethod") {
+      for (const param of node.params ?? []) patternNames2(param, bound);
+      if (node.id) patternNames2(node.id, bound);
+    }
+  });
+  const free = /* @__PURE__ */ new Set();
+  for (const name of candidates) if (!skip.has(name) && !bound.has(name)) free.add(name);
+  return { free, bound };
+}
+function nameOf2(node, out) {
+  if (!node) return;
+  if (typeof node.name === "string") out.add(node.name);
+  if (node.type === "JSXNamespacedName") {
+    nameOf2(node.namespace, out);
+    nameOf2(node.name, out);
+  }
+}
+function patternNames2(node, out) {
+  if (!node || typeof node !== "object") return;
+  const typed = node;
+  switch (typed.type) {
+    case "Identifier":
+      out.add(String(typed.name));
+      return;
+    case "ObjectPattern":
+      for (const property of typed.properties ?? []) {
+        patternNames2(property.type === "RestElement" ? property.argument : property.value, out);
+      }
+      return;
+    case "ArrayPattern":
+      for (const element of typed.elements ?? []) patternNames2(element, out);
+      return;
+    case "AssignmentPattern":
+      patternNames2(typed.left, out);
+      return;
+    case "RestElement":
+      patternNames2(typed.argument, out);
+      return;
+    default:
+      return;
+  }
+}
+function moduleScope(parsed, content) {
+  const out = /* @__PURE__ */ new Map();
+  const program = parsed.ast?.program;
+  if (!program) return out;
+  const source = parsed.script?.code ?? content;
+  for (const statement of program.body ?? []) {
+    const kind = statement.type;
+    if (kind !== "VariableDeclaration" && kind !== "FunctionDeclaration" && kind !== "ClassDeclaration" && kind !== "TSTypeAliasDeclaration" && kind !== "TSInterfaceDeclaration" && kind !== "TSEnumDeclaration") {
+      continue;
+    }
+    const start = statement.start;
+    const end = statement.end;
+    if (start === void 0 || end === void 0) continue;
+    const text = source.slice(start, end);
+    const names = /* @__PURE__ */ new Set();
+    if (kind === "VariableDeclaration") {
+      for (const declarator of statement.declarations ?? []) patternNames2(declarator.id, names);
+    } else {
+      patternNames2(statement.id, names);
+    }
+    if (names.size === 0) continue;
+    const scanned = scanExpression(text.replace(/^(?:export\s+)?/, ""));
+    const uses = scanned ? [...scanned.free].filter((name) => !names.has(name)) : [];
+    for (const name of names) out.set(name, { at: start, text, uses });
+  }
+  return out;
+}
+
+// src/componentize.ts
+import MagicString3 from "magic-string";
+var SectionInvariantError = class extends Error {
+  code = "SECTION_INVARIANT";
+  constructor(message) {
+    super(message);
+    this.name = "SectionInvariantError";
+  }
+};
+function assertSections(total, sections) {
+  const sum = sections.extracted + sections.inlineOnly + sections.alreadyExtracted + sections.pending.length;
+  if (sum !== total) {
+    throw new SectionInvariantError(
+      `The receipt does not account for every section: ${total} planned but ${sections.extracted} extracted + ${sections.inlineOnly} inline-only + ${sections.alreadyExtracted} already extracted + ${sections.pending.length} pending = ${sum}.`
+    );
+  }
+  return sections;
+}
+var SECTION_MARKER = "// @bettercms-ai/convert section v1";
+var REGISTRY_MARKER = "// @bettercms-ai/convert sections v1";
+var COMPONENT_DIR = "src/components/bcms";
+var SECTIONS_LIB = "src/lib/bcms-sections.ts";
+var EXTRACTABLE = ["astro", "jsx"];
+async function componentizeSources(briefIn, planIn, sources, options) {
+  const pending = [];
+  let extracted = 0;
+  let inlineOnly = 0;
+  let alreadyExtracted = 0;
+  let planPending = 0;
+  let total = 0;
+  const brief = readBrief(briefIn);
+  const plan2 = readPlan(planIn);
+  const contents = new Map(sources.map((s) => [s.path, s.content]));
+  const pend = (route, groupKey, reason, message) => void pending.push({ route, groupKey, reason, ...message ? { message } : {} });
+  const trees = /* @__PURE__ */ new Map();
+  const treeOf = async (file) => {
+    if (trees.has(file)) return trees.get(file);
+    const content = contents.get(file) ?? "";
+    const dialect = dialectOf(file, content);
+    const parsed = dialect ? await parseFile4(dialect, content) : null;
+    const tree = parsed && !parsed.error ? { parsed, elements: elementIndex(parsed.roots) } : null;
+    trees.set(file, tree);
+    return tree;
+  };
+  const helperPath = HELPER_PATH.astro;
+  const helperExisting = contents.get(helperPath);
+  const helperVersion = helperExisting === void 0 ? null : isKnownHelper(helperExisting, "astro");
+  const helperBlocked = helperExisting !== void 0 && helperVersion === null && options?.overwriteHelper !== true;
+  const outFiles = /* @__PURE__ */ new Map();
+  const written = /* @__PURE__ */ new Map();
+  const shipped = /* @__PURE__ */ new Map();
+  const componentsOf = (dialect) => {
+    const held = written.get(dialect) ?? /* @__PURE__ */ new Map();
+    written.set(dialect, held);
+    return held;
+  };
+  const fresh = /* @__PURE__ */ new Set();
+  const registryConflicts = [];
+  for (const dialect of EXTRACTABLE) {
+    const path = `${COMPONENT_DIR}/Sections.${dialect === "astro" ? "astro" : "tsx"}`;
+    const existing = contents.get(path);
+    if (existing === void 0) continue;
+    if (!isGenerated(existing)) {
+      registryConflicts.push(path);
+      continue;
+    }
+    const held = readRegistry(existing, dialect);
+    componentsOf(dialect);
+    for (const [slug, component] of held.components) written.get(dialect).set(slug, component);
+    const order = shipped.get(dialect) ?? /* @__PURE__ */ new Map();
+    shipped.set(dialect, order);
+    for (const [page, list] of held.shipped) order.set(page, list);
+  }
+  const lib = contents.get(SECTIONS_LIB);
+  if (lib !== void 0 && !isGenerated(lib)) registryConflicts.push(SECTIONS_LIB);
+  const registryBlocked = registryConflicts.length > 0 && options?.overwriteHelper !== true;
+  for (const page of plan2.pages ?? []) {
+    const sections2 = (page.sections ?? []).filter((section) => {
+      if (section.pending) {
+        planPending++;
+        return false;
+      }
+      return true;
+    });
+    total += sections2.length;
+    if (sections2.length === 0) continue;
+    const briefPage = brief.pages.find((p) => p.route === page.route);
+    const pageSlug = briefPage?.slug ?? slugify(page.route === "/" ? "home" : page.route);
+    if (helperBlocked) {
+      for (const section of sections2) {
+        pend(page.route, section.groupKey, "HELPER_CONFLICT", `${helperPath} is not a module this package wrote.`);
+      }
+      continue;
+    }
+    if (registryBlocked) {
+      for (const section of sections2) {
+        pend(page.route, section.groupKey, "REGISTRY_CONFLICT", `${registryConflicts.join(", ")} is not a file this package wrote.`);
+      }
+      continue;
+    }
+    const snapshotPath = `${CONTENT_DIR}/${pageSlug}.json`;
+    if (!snapshotUsable(contents.get(snapshotPath))) {
+      for (const section of sections2) {
+        pend(page.route, section.groupKey, "SNAPSHOT_INVALID", `${snapshotPath} is not a JSON object.`);
+      }
+      continue;
+    }
+    const pageFiles = pageFilesFor(page.route, contents.keys());
+    if (pageFiles.length > 1) {
+      for (const section of sections2) {
+        pend(page.route, section.groupKey, "ROUTE_FILE_AMBIGUOUS", `${pageFiles.join(" and ")} both serve ${page.route}.`);
+      }
+      continue;
+    }
+    const file = pageFiles[0];
+    if (file === void 0) {
+      for (const section of sections2) {
+        pend(page.route, section.groupKey, "NOT_IN_SOURCE", `no page file found for ${page.route}.`);
+      }
+      continue;
+    }
+    const done = new Set(alreadyOn(contents.get(file) ?? "", pageSlug, sections2));
+    alreadyExtracted += done.size;
+    if (done.size === sections2.length) continue;
+    const found = await locateSections(
+      sections2.filter((section) => !done.has(section.groupKey)),
+      briefPage?.paths ?? [],
+      sources,
+      treeOf
+    );
+    for (const [groupKey, reason] of found.misses) {
+      pend(page.route, groupKey, reason.code, reason.message);
+    }
+    const live = found.placed;
+    if (live.length === 0) continue;
+    const placedHere = [];
+    for (const placed of live) {
+      const elements = placed.byFile.get(file);
+      if (elements && elements.length > 0) {
+        placedHere.push({ section: placed.section, elements });
+        continue;
+      }
+      pend(
+        page.route,
+        placed.section.groupKey,
+        "SECTION_ROOT_AMBIGUOUS",
+        `rendered by ${[...placed.byFile.keys()].join(", ")}, not ${file}.`
+      );
+    }
+    if (placedHere.length === 0) continue;
+    const content = contents.get(file);
+    const dialect = dialectOf(file, content);
+    if (!dialect || !EXTRACTABLE.includes(dialect)) {
+      for (const placed of placedHere) {
+        pend(page.route, placed.section.groupKey, "DIALECT_UNSUPPORTED", `${file} is ${dialect ?? "not a template"}.`);
+      }
+      continue;
+    }
+    const tree = await treeOf(file);
+    if (!tree) {
+      for (const placed of placedHere) {
+        pend(page.route, placed.section.groupKey, "NOT_IN_SOURCE", `${file} did not parse.`);
+      }
+      continue;
+    }
+    const parsed = tree.parsed;
+    const roots = [];
+    for (const placed of placedHere) {
+      const root = lowestCommonAncestor(placed.elements);
+      if (!root) {
+        pend(page.route, placed.section.groupKey, "SECTION_ROOT_AMBIGUOUS", "its fields sit under no single element.");
+        continue;
+      }
+      const component = resolveComponent(plan2, placed.section);
+      roots.push({ section: placed.section, route: page.route, root, ...component });
+    }
+    const nested = /* @__PURE__ */ new Set();
+    for (const a of roots) {
+      for (const b of roots) {
+        if (a !== b && a.root.start <= b.root.start && b.root.end <= a.root.end) {
+          nested.add(a);
+          nested.add(b);
+        }
+      }
+    }
+    for (const resolved of nested) {
+      pend(page.route, resolved.section.groupKey, "SECTION_ROOT_AMBIGUOUS", "its root contains another section's.");
+    }
+    const candidates = roots.filter((r) => !nested.has(r)).sort((a, b) => a.root.start - b.root.start);
+    if (candidates.length === 0) continue;
+    const extractable = componentsOf(dialect);
+    const placeable = [];
+    for (const resolved of candidates) {
+      const path = `${COMPONENT_DIR}/${resolved.name}.${dialect === "astro" ? "astro" : "tsx"}`;
+      const existing = contents.get(path);
+      if (existing !== void 0 && !isGenerated(existing) && !extractable.has(resolved.slug)) {
+        pend(page.route, resolved.section.groupKey, "COMPONENT_CONFLICT", `${path} is not a file this package wrote.`);
+        continue;
+      }
+      if (extractable.has(resolved.slug)) {
+        placeable.push(resolved);
+        continue;
+      }
+      const built = componentFile(dialect, path, file, content, parsed, resolved);
+      if (built.free.length > 0) {
+        pend(
+          page.route,
+          resolved.section.groupKey,
+          "SECTION_FREE_IDENTIFIERS",
+          `its markup uses ${built.free.join(", ")}, which the component file cannot be given.`
+        );
+        continue;
+      }
+      extractable.set(resolved.slug, { name: resolved.name, path });
+      fresh.add(resolved.slug);
+      addFile(outFiles, contents, {
+        path,
+        operation: existing === void 0 ? "add" : "modify",
+        content: built.content
+      });
+      placeable.push(resolved);
+    }
+    if (placeable.length === 0) continue;
+    const layout = runOf(placeable, parsed.roots);
+    if (layout === null) {
+      for (const resolved of placeable) {
+        pend(page.route, resolved.section.groupKey, "SECTION_NOT_CONTIGUOUS", "its roots share no container.");
+      }
+      continue;
+    }
+    const order = shipped.get(dialect) ?? /* @__PURE__ */ new Map();
+    shipped.set(dialect, order);
+    order.set(
+      pageSlug,
+      placeable.map((r) => ({ slug: r.slug, bind: r.section.groupKey }))
+    );
+    const rewritten = layout.contiguous ? splicePageRun(file, content, dialect, parsed, placeable, pageSlug) : splicePageInline(file, content, dialect, parsed, placeable, pageSlug, extractable);
+    addFile(outFiles, contents, { path: file, operation: "modify", content: rewritten });
+    if (layout.contiguous) extracted += placeable.length;
+    else inlineOnly += placeable.length;
+  }
+  const componentSlugs = [...written.values()].flatMap((held) => [...held.keys()]);
+  if (componentSlugs.length > 0) {
+    const pageSlugs = [...new Set([...shipped.values()].flatMap((order) => [...order.keys()]))].sort();
+    addFile(outFiles, contents, {
+      path: SECTIONS_LIB,
+      operation: contents.has(SECTIONS_LIB) ? "modify" : "add",
+      content: sectionsLib(pageSlugs)
+    });
+    for (const [dialect, held] of [...written].sort(([a], [b]) => a.localeCompare(b))) {
+      if (held.size === 0) continue;
+      const registryPath = `${COMPONENT_DIR}/Sections.${dialect === "astro" ? "astro" : "tsx"}`;
+      addFile(outFiles, contents, {
+        path: registryPath,
+        operation: contents.has(registryPath) ? "modify" : "add",
+        content: registryFile(dialect, registryPath, held, shipped.get(dialect) ?? /* @__PURE__ */ new Map())
+      });
+    }
+    emitHelper(outFiles, contents, helperVersion, options?.overwriteHelper);
+    emitStubs(outFiles, contents, pageSlugs);
+  }
+  const sections = assertSections(total, { extracted, inlineOnly, alreadyExtracted, pending });
+  return {
+    files: [...outFiles.values()].sort((a, b) => a.path.localeCompare(b.path)),
+    receipt: {
+      planDigest: plan2.digest ?? "",
+      sections,
+      // What THIS run wrote a file for. A component an earlier run left is reused, not re-reported.
+      components: [...fresh].sort(),
+      planPending
+    }
+  };
+}
+function alreadyOn(content, pageSlug, sections) {
+  const ours = COMPONENT_DIR.split("/").slice(-2).join("/");
+  const importsOurs = new RegExp(`from\\s*["'][^"']*${ours}/`).test(content);
+  if (!importsOurs) return [];
+  if (new RegExp(`page=\\s*["']${pageSlug.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}["']`).test(content)) {
+    return sections.map((section) => section.groupKey);
+  }
+  return sections.map((section) => section.groupKey).filter((groupKey) => new RegExp(`bind=\\s*["']${groupKey.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}["']`).test(content));
+}
+function readRegistry(content, dialect) {
+  const components = /* @__PURE__ */ new Map();
+  const shipped = /* @__PURE__ */ new Map();
+  const paths = /* @__PURE__ */ new Map();
+  for (const match of content.matchAll(/^import\s+(\w+)\s+from\s+"\.\/([^"]+)";$/gm)) {
+    const [, name, file] = match;
+    paths.set(name, `${COMPONENT_DIR}/${file}${dialect === "astro" ? "" : ".tsx"}`);
+  }
+  const registry = content.match(/const REGISTRY[^=]*=\s*\{([\s\S]*?)\n\};/);
+  for (const match of (registry?.[1] ?? "").matchAll(/^\s*"([^"]+)":\s*(\w+),$/gm)) {
+    const [, slug, name] = match;
+    const path = paths.get(name);
+    if (path) components.set(slug, { name, path });
+  }
+  const table = content.match(/const SHIPPED[^=]*=\s*\{([\s\S]*?)\n\};/);
+  for (const match of (table?.[1] ?? "").matchAll(/^\s*"([^"]+)":\s*(\[.*\]),$/gm)) {
+    try {
+      shipped.set(match[1], JSON.parse(match[2]));
+    } catch {
+    }
+  }
+  return { components, shipped };
+}
+function snapshotUsable(existing) {
+  if (existing === void 0) return true;
+  try {
+    const parsed = JSON.parse(existing);
+    return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed);
+  } catch {
+    return false;
+  }
+}
+function addFile(out, contents, file) {
+  if (contents.get(file.path) === file.content) return;
+  out.set(file.path, file);
+}
+async function locateSections(sections, briefPaths, sources, treeOf) {
+  const placed = [];
+  const misses = [];
+  for (const section of sections) {
+    const paths = fieldPaths(section);
+    const literals = new Set(
+      briefPaths.filter((p) => (p.scope ?? "page") === "page" && groupOf(p.path) === section.groupKey && p.original).map((p) => flat(stripTags(p.original))).filter(Boolean)
+    );
+    const hits = /* @__PURE__ */ new Map();
+    for (const source of sources) {
+      const tree = await treeOf(source.path);
+      if (!tree) continue;
+      const parsed = tree.parsed;
+      const elements = tree.elements;
+      const found = /* @__PURE__ */ new Map();
+      for (const declaration2 of declarationsIn(parsed.roots, source.content)) {
+        if (declaration2.scope !== "page") continue;
+        if (groupOf(declaration2.path) !== section.groupKey) continue;
+        const placed2 = elements.get(declaration2.at);
+        if (placed2) found.set(declaration2.at, placed2);
+      }
+      if (found.size === 0 && literals.size > 0) {
+        for (const site of collectSites(parsed.roots, [...literals])) {
+          if (site.partial || site.where === "script" || site.where === "comment") continue;
+          const placed2 = elements.get(site.attrInsertAt);
+          if (placed2) found.set(site.attrInsertAt, placed2);
+        }
+      }
+      if (found.size > 0) hits.set(source.path, [...found.values()]);
+    }
+    if (hits.size === 0) {
+      misses.push([
+        section.groupKey,
+        { code: "NOT_IN_SOURCE", message: `no file renders ${paths.join(", ") || section.groupKey}.` }
+      ]);
+      continue;
+    }
+    placed.push({ section, byFile: hits });
+  }
+  return { placed, misses };
+}
+var groupOf = (path) => path.split(/[.[]/)[0] ?? "";
+var fieldPaths = (section) => (section.fields ?? []).map((field) => field.path ?? `${section.groupKey}.${field.key ?? ""}`);
+function elementIndex(roots) {
+  const out = /* @__PURE__ */ new Map();
+  const visit = (node, chain) => {
+    if (node.type === "expr") {
+      for (const child of node.children) visit(child, chain);
+      return;
+    }
+    if (node.type !== "element") return;
+    const mine = [...chain, node];
+    out.set(node.attrInsertAt, { node, chain: mine });
+    for (const child of node.children) visit(child, mine);
+  };
+  for (const root of roots) visit(root, []);
+  return out;
+}
+function lowestCommonAncestor(elements) {
+  if (elements.length === 0) return null;
+  let common = elements[0].chain;
+  for (const placed of elements.slice(1)) {
+    const shared = [];
+    for (let i = 0; i < Math.min(common.length, placed.chain.length); i++) {
+      if (common[i] !== placed.chain[i]) break;
+      shared.push(common[i]);
+    }
+    common = shared;
+  }
+  return common[common.length - 1] ?? null;
+}
+function runOf(placeable, roots) {
+  const parents = placeable.map((r) => parentOf(r.root, roots));
+  if (parents.some((p) => p === void 0)) return null;
+  const [first, ...rest] = parents;
+  if (rest.some((p) => p !== first)) return null;
+  const siblings = (first === null ? roots : first.children).filter(
+    (node) => node.type === "element"
+  );
+  const indices = placeable.map((r) => siblings.indexOf(r.root)).sort((a, b) => a - b);
+  if (indices.some((at) => at < 0)) return null;
+  const contiguous = indices.every((at, i) => i === 0 || at === indices[i - 1] + 1);
+  return { contiguous };
+}
+function parentOf(target, roots) {
+  if (roots.some((node) => node === target)) return null;
+  const search = (nodes, parent) => {
+    for (const node of nodes) {
+      if (node.type === "expr") {
+        const inside = search(node.children, parent);
+        if (inside !== void 0) return inside;
+        continue;
+      }
+      if (node.type !== "element") continue;
+      if (node.children.some((child) => child === target)) return node;
+      const deeper = search(node.children, node);
+      if (deeper !== void 0) return deeper;
+    }
+    return void 0;
+  };
+  return search(roots, null);
+}
+function resolveComponent(plan2, section) {
+  const components = plan2.components ?? [];
+  const wanted = section.reuse?.proposedSlug;
+  const byId = section.reuse?.componentId;
+  const entry = (wanted ? components.find((c) => c.proposedSlug === wanted) : void 0) ?? (byId ? components.find((c) => c.componentId === byId) : void 0) ?? onlyOne(components.filter((c) => c.sectionType && c.sectionType === section.sectionType));
+  const family = entry?.name ?? section.sectionType ?? section.groupKey;
+  return { slug: entry?.proposedSlug ?? wanted ?? slugify(family), name: pascal(family) };
+}
+var onlyOne = (all) => all.length === 1 ? all[0] : void 0;
+function pascal(value) {
+  const parts = value.split(/[^A-Za-z0-9]+/).filter(Boolean);
+  const name = parts.map((part) => part[0].toUpperCase() + part.slice(1)).join("");
+  return /^[A-Za-z]/.test(name) ? name : `Section${name}`;
+}
+var slugify = (value) => value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "section";
+function componentFile(dialect, path, fromFile, content, parsed, resolved) {
+  const markup = sliceWithBlockId(content, resolved.root);
+  const groupKey = resolved.section.groupKey;
+  const locals = helperLocals(parsed, dialect, fromFile);
+  const helperNames = ["bcms", "bcmsRows", "bcmsLayout"].flatMap(
+    (name) => locals[name].filter((local) => mentions(markup, local)).map((local) => ({ name, local }))
+  );
+  const helpers = [.../* @__PURE__ */ new Set([...helperNames.map((h) => alias(h.name, h.local)), "bcmsSection"])].sort();
+  const helperSpecifier = relativeImport(path, HELPER_PATH[dialect]).replace(/\.tsx?$/, "");
+  const snapshot = snapshotOf(parsed, dialect, fromFile, markup);
+  const carry = carryFor({
+    dialect,
+    fromFile,
+    toFile: path,
+    content,
+    parsed,
+    root: resolved.root,
+    provided: [
+      "blockId",
+      "bind",
+      "overrides",
+      "page",
+      ...helperNames.map((h) => h.local),
+      ...snapshot ? [snapshot] : []
+    ],
+    // The helper and the snapshots are what the component declares for itself.
+    skipSpecifier: (repoPath, specifier) => specifier.includes(`${CONTENT_DIR}/`) || repoPath.startsWith(HELPER_PATH[dialect].replace(/\.tsx?$/, ""))
+  });
+  if (carry.free.length > 0) return { content: "", free: carry.free };
+  const carried = [...carry.imports];
+  const key = /^[A-Za-z_$][\w$]*$/.test(groupKey) ? groupKey : JSON.stringify(groupKey);
+  const carriedDeclarations = carry.declarations.length > 0 ? `${carry.declarations.join("\n")}
+` : "";
+  const copy = snapshot ? `const ${snapshot} = { ${key}: bcmsSection(page, bind ?? ${JSON.stringify(groupKey)}, overrides) };` : "";
+  if (dialect === "astro") {
+    return { free: [], content: `---
+${SECTION_MARKER}
+${[...carried, `import { ${helpers.join(", ")} } from "${helperSpecifier}";`].join("\n")}
+
+interface Props {
+  /** The placement's block id. The editor hit-tests \`[data-bcms-block]\` for section chrome. */
+  blockId?: string;
+  /** The page field group this placement renders \u2014 Phase A keeps the copy where P2 put it. */
+  bind?: string;
+  /** The instance's own copy, when an editor gave it any. Wins over the bound group. */
+  overrides?: Record<string, unknown>;
+  /** The page snapshot, so one component can serve every page whose group has this shape. */
+  page?: unknown;
+}
+const { blockId, bind, overrides, page } = Astro.props;
+${carriedDeclarations}${copy}
+---
+${markup}
+` };
+  }
+  return { free: [], content: `${SECTION_MARKER}
+${[...carried, `import { ${helpers.join(", ")} } from "${helperSpecifier}";`, `import type { BcmsSectionProps } from "${relativeImport(path, SECTIONS_LIB).replace(/\.tsx?$/, "")}";`].join("\n")}
+${carriedDeclarations === "" ? "" : `
+${carriedDeclarations}`}
+export default function ${resolved.name}({ blockId, bind, overrides, page }: BcmsSectionProps) {
+  ${copy}
+  return (
+    ${markup}
+  );
+}
+` };
+}
+function sliceWithBlockId(content, root) {
+  const slice = new MagicString3(content.slice(root.start, root.end));
+  slice.appendLeft(root.attrInsertAt - root.start, " data-bcms-block={blockId}");
+  return slice.toString();
+}
+var alias = (name, local) => name === local ? name : `${name} as ${local}`;
+var mentions = (markup, name) => new RegExp(`(?<![\\w$])${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?![\\w$])`).test(markup);
+function snapshotOf(parsed, dialect, fromFile, markup) {
+  for (const [local, from] of importsIn(parsed, dialect)) {
+    if (from.imported !== null) continue;
+    if (!from.specifier.includes(`${CONTENT_DIR}/`) || !from.specifier.endsWith(".json")) continue;
+    if (mentions(markup, local)) return local;
+  }
+  return null;
+}
+function sectionsLib(pageSlugs) {
+  const imports = pageSlugs.map(
+    (slug) => `import ${identifierFor(slug)} from "${relativeImport(SECTIONS_LIB, `${CONTENT_DIR}/${slug}.json`)}";`
+  );
+  const table = pageSlugs.map((slug) => `  ${JSON.stringify(slug)}: ${identifierFor(slug)},`).join("\n");
+  return `${REGISTRY_MARKER}
+// Structure comes from bcms-content/*.json, written into the tree before the build: each page's
+// \`blocks\` are its ordered section instances, and components.json names which component each one
+// is. The committed stubs are empty \u2014 a build with them renders the order the repository ships.
+import bcmsComponents from "${relativeImport(SECTIONS_LIB, `${CONTENT_DIR}/components.json`)}";
+${imports.join("\n")}
+
+const SNAPSHOTS: Record<string, unknown> = {
+${table}
+};
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** What every extracted section component is handed. */
+export interface BcmsSectionProps {
+  blockId?: string;
+  bind?: string;
+  overrides?: Record<string, unknown>;
+  page?: unknown;
+}
+
+/** One placement on one page: which component, bound to which page field group. */
+export interface BcmsPlacement {
+  blockId?: string;
+  slug: string;
+  bind?: string;
+  overrides?: Record<string, unknown>;
+}
+
+/** The page's own snapshot \u2014 the copy every placement on it reads through \`bind\`. */
+export function pageSnapshot(pageSlug: string): unknown {
+  return SNAPSHOTS[pageSlug];
+}
+
+/** The page's \`component\` blocks, before any of them is matched to a component this repo has. */
+function componentBlocks(pageSlug: string): Record<string, unknown>[] {
+  const snapshot = SNAPSHOTS[pageSlug];
+  const blocks = isRecord(snapshot) ? snapshot.blocks : undefined;
+  if (!Array.isArray(blocks)) return [];
+  return (blocks as unknown[]).filter(
+    (block): block is Record<string, unknown> => isRecord(block) && block.type === "component",
+  );
+}
+
+/**
+ * Has the CMS said anything about this page's structure?
+ *
+ * \u{1F534} THE RAW LIST, NOT THE RESOLVED ONE. "No sections came back" has two causes that must not be
+ * treated alike: the CMS holds nothing yet (fall back to the order this repository ships), or the
+ * CMS holds a list whose components this repository does not have (render nothing \u2014 the page HAS
+ * been arranged, and re-showing the old bands would silently ignore an editor's work).
+ */
+export function hasCmsSections(pageSlug: string): boolean {
+  return componentBlocks(pageSlug).length > 0;
+}
+
+/**
+ * The page's section instances, in the order the CMS holds them.
+ *
+ * An instance naming a component this repository does not have is SKIPPED, never rendered as a
+ * hole: the CMS is free to add a section type the repo has not shipped yet, and a half-built page
+ * is worse than a page missing one band.
+ */
+export function pageSections(pageSlug: string): BcmsPlacement[] {
+  const blocks = componentBlocks(pageSlug);
+  if (blocks.length === 0) return [];
+
+  const slugs = new Map<string, string>();
+  if (Array.isArray(bcmsComponents)) {
+    for (const component of bcmsComponents as unknown[]) {
+      if (!isRecord(component)) continue;
+      const id = component.id ?? component.componentId;
+      const slug = component.slug ?? component.proposedSlug;
+      if (typeof id === "string" && typeof slug === "string") slugs.set(id, slug);
+    }
+  }
+
+  const out: BcmsPlacement[] = [];
+  for (const block of blocks) {
+    const props = isRecord(block.props) ? block.props : {};
+    const slug = typeof props.componentId === "string" ? slugs.get(props.componentId) : undefined;
+    if (!slug) continue;
+    out.push({
+      blockId: typeof block.id === "string" ? block.id : undefined,
+      slug,
+      bind: typeof props.bind === "string" ? props.bind : undefined,
+      overrides: isRecord(props.overrides) ? props.overrides : undefined,
+    });
+  }
+  return out;
+}
+`;
+}
+var identifierFor = (slug) => `bcms${slug.replace(/[^A-Za-z0-9]+(.)?/g, (_, c) => c ? c.toUpperCase() : "").replace(/^./, (c) => c.toUpperCase())}`;
+function registryFile(dialect, path, written, shipped) {
+  const entries = [...written].sort(([a], [b]) => a.localeCompare(b));
+  const imports = entries.map(([, component]) => {
+    const specifier = relativeImport(path, component.path);
+    return `import ${component.name} from "${dialect === "astro" ? specifier : specifier.replace(/\.tsx?$/, "")}";`;
+  }).join("\n");
+  const registry = entries.map(([slug, component]) => `  ${JSON.stringify(slug)}: ${component.name},`).join("\n");
+  const shippedTable = [...shipped].sort(([a], [b]) => a.localeCompare(b)).map(([page, list]) => `  ${JSON.stringify(page)}: ${JSON.stringify(list)},`).join("\n");
+  const lib = relativeImport(path, SECTIONS_LIB).replace(/\.tsx?$/, "");
+  const registryType = dialect === "astro" ? "Record<string, unknown>" : "Record<string, (props: BcmsSectionProps) => JSX.Element | null>";
+  const shared = `${imports}
+import { hasCmsSections, pageSections, pageSnapshot, type BcmsPlacement${dialect === "astro" ? "" : ", type BcmsSectionProps"} } from "${lib}";
+
+/** slug \u2192 the component that renders it. An unknown slug is skipped, never a hole. */
+const REGISTRY: ${registryType} = {
+${registry}
+};
+
+/**
+ * The order the REPOSITORY ships, per page \u2014 the fallback when the CMS holds no blocks yet.
+ *
+ * \u{1F534} LOAD-BEARING. An empty \`blocks\` means "nothing has been said about this page", not "this
+ * page is empty": it is what a fresh clone, the committed stub and every not-yet-componentised
+ * page all look like. Rendering nothing there would blank the site on the first build after the
+ * codemod ran, with nothing in the diff to explain it.
+ */
+const SHIPPED: Record<string, BcmsPlacement[]> = {
+${shippedTable}
+};
+
+/**
+ * \u{1F534} THE FALLBACK IS DECIDED ON THE RAW LIST. A page whose CMS blocks all name components this
+ * repository does not have has still been ARRANGED \u2014 falling back there would put the shipped
+ * bands back on a page an editor deliberately emptied, and no amount of reading the diff would
+ * explain it. Only "the CMS holds nothing" takes the shipped order.
+ */
+const placementsFor = (page: string): BcmsPlacement[] =>
+  hasCmsSections(page) ? pageSections(page) : (SHIPPED[page] ?? []);`;
+  if (dialect === "astro") {
+    return `---
+${REGISTRY_MARKER}
+${shared}
+
+interface Props {
+  /** The page slug, as \`bcms-content/<slug>.json\` spells it. */
+  page: string;
+}
+const { page } = Astro.props;
+const placements = placementsFor(page);
+const snapshot = pageSnapshot(page);
+---
+{placements.map((placement) => {
+  const Component = REGISTRY[placement.slug] as never;
+  return Component ? (
+    <Component
+      blockId={placement.blockId}
+      bind={placement.bind}
+      overrides={placement.overrides}
+      page={snapshot}
+    />
+  ) : null;
+})}
+`;
+  }
+  return `${REGISTRY_MARKER}
+${shared}
+
+export default function Sections({ page }: { page: string }) {
+  const placements = placementsFor(page);
+  const snapshot = pageSnapshot(page);
+  return (
+    <>
+      {placements.map((placement, i) => {
+        const Component = REGISTRY[placement.slug];
+        return Component ? (
+          <Component
+            key={placement.blockId ?? \`\${placement.slug}-\${i}\`}
+            blockId={placement.blockId}
+            bind={placement.bind}
+            overrides={placement.overrides}
+            page={snapshot}
+          />
+        ) : null;
+      })}
+    </>
+  );
+}
+`;
+}
+function splicePageRun(file, content, dialect, parsed, placeable, pageSlug) {
+  const names = allocateNames(topLevelBindings(dialect, parsed, content), [{ key: "Sections", name: "Sections" }]);
+  const local = names.get("Sections");
+  const source = new MagicString3(content);
+  const first = placeable[0].root;
+  const last = placeable[placeable.length - 1].root;
+  source.overwrite(first.start, last.end, `<${local} page="${pageSlug}" />`);
+  const registry = `${COMPONENT_DIR}/Sections.${dialect === "astro" ? "astro" : "tsx"}`;
+  const specifier = relativeImport(file, registry);
+  addImports(source, parsed, [
+    `import ${local} from "${dialect === "astro" ? specifier : specifier.replace(/\.tsx?$/, "")}";`
+  ]);
+  return source.toString();
+}
+function splicePageInline(file, content, dialect, parsed, placeable, pageSlug, written) {
+  const wanted = [
+    ...new Set(placeable.map((r) => r.slug))
+  ].map((slug) => ({ key: slug, name: written.get(slug).name }));
+  const names = allocateNames(topLevelBindings(dialect, parsed, content), [
+    ...wanted,
+    { key: "pageSnapshot", name: "pageSnapshot" }
+  ]);
+  const snapshot = names.get("pageSnapshot");
+  const source = new MagicString3(content);
+  for (const resolved of placeable) {
+    source.overwrite(
+      resolved.root.start,
+      resolved.root.end,
+      `<${names.get(resolved.slug)} bind=${JSON.stringify(resolved.section.groupKey)} page={${snapshot}(${JSON.stringify(pageSlug)})} />`
+    );
+  }
+  const lib = relativeImport(file, SECTIONS_LIB).replace(/\.tsx?$/, "");
+  const imports = [
+    ...wanted.map(({ key }) => {
+      const specifier = relativeImport(file, written.get(key).path);
+      return `import ${names.get(key)} from "${dialect === "astro" ? specifier : specifier.replace(/\.tsx?$/, "")}";`;
+    }),
+    `import { pageSnapshot${snapshot === "pageSnapshot" ? "" : ` as ${snapshot}`} } from "${lib}";`
+  ];
+  addImports(source, parsed, imports);
+  return source.toString();
+}
+function addImports(source, parsed, lines) {
+  const at = parsed.importAt;
+  if (!at || lines.length === 0) return;
+  if (at.wrap) source.appendLeft(at.at, `${at.wrap.before}${lines.join("\n")}${at.wrap.after}`);
+  else if (at.at === 0) source.appendLeft(0, `${lines.join("\n")}
+`);
+  else source.appendLeft(at.at, `
+${lines.join("\n")}`);
+}
+var isGenerated = (content) => content.includes(SECTION_MARKER) || content.includes(REGISTRY_MARKER);
+function emitHelper(out, contents, version, overwrite) {
+  const path = HELPER_PATH.astro;
+  const source = helperSource("astro");
+  const existing = contents.get(path);
+  if (existing === void 0) {
+    addFile(out, contents, { path, operation: "add", content: source });
+    return;
+  }
+  if (version === null && overwrite !== true) return;
+  if (version === null || version < HELPER_VERSION) {
+    addFile(out, contents, { path, operation: "modify", content: source });
+  }
+}
+function emitStubs(out, contents, pageSlugs) {
+  const components = `${CONTENT_DIR}/components.json`;
+  if (!contents.has(components)) {
+    addFile(out, contents, { path: components, operation: "add", content: "[]" });
+  }
+  for (const slug of pageSlugs) {
+    const path = `${CONTENT_DIR}/${slug}.json`;
+    const existing = contents.get(path);
+    let held = {};
+    if (existing !== void 0) {
+      try {
+        const parsed = JSON.parse(existing);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) continue;
+        held = parsed;
+      } catch {
+        continue;
+      }
+    }
+    if (Array.isArray(held.blocks)) continue;
+    addFile(out, contents, {
+      path,
+      operation: existing === void 0 ? "add" : "modify",
+      content: `${JSON.stringify({ ...held, blocks: [] }, null, 2)}
+`
+    });
+  }
+}
+function readComponentizePlan(value) {
+  return readPlan(value);
+}
+
 // src/index.ts
 var ConvertError = class extends Error {
   constructor(code, message) {
@@ -4590,7 +5904,7 @@ var ConvertError = class extends Error {
 };
 var keyOf = (route, scope, path) => scope === "layout" ? `layout::${path}` : `${route}::page::${path}`;
 var escapeRegExp2 = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-var identifierFor = (slug) => `bcms${slug.replace(/[^A-Za-z0-9]+(.)?/g, (_, c) => c ? c.toUpperCase() : "").replace(/^./, (c) => c.toUpperCase())}`;
+var identifierFor2 = (slug) => `bcms${slug.replace(/[^A-Za-z0-9]+(.)?/g, (_, c) => c ? c.toUpperCase() : "").replace(/^./, (c) => c.toUpperCase())}`;
 async function drillProp(ctx, fromFile, component, prop, kind, hop) {
   const miss = { ok: false, reason: "PROP_TARGET_NOT_FOUND", edits: [] };
   if (hop > MAX_HOPS) return { ok: false, reason: "PROP_DRILLED_DEEP", edits: [] };
@@ -4638,7 +5952,8 @@ async function drillProp(ctx, fromFile, component, prop, kind, hop) {
   if (found.propsType) at(found.propsType.at, found.propsType.text);
   return { ok: true, edits: [{ file, splices }] };
 }
-async function convertSources(brief, sources, options) {
+async function convertSources(briefIn, sources, options) {
+  const brief = readBrief(briefIn);
   const digest = briefDigest(brief);
   const targets = /* @__PURE__ */ new Map();
   for (const page of brief.pages) {
@@ -4773,7 +6088,7 @@ async function convertSources(brief, sources, options) {
     else rewritten++;
   }
   for (const [file, splices] of [...componentEdits].sort(([a], [b]) => a.localeCompare(b))) {
-    const source = new MagicString3(contents.get(file));
+    const source = new MagicString4(contents.get(file));
     const seen = /* @__PURE__ */ new Set();
     for (const splice of splices) {
       const id = `${splice.start}:${splice.end}:${splice.text}`;
@@ -4793,7 +6108,7 @@ async function convertSources(brief, sources, options) {
     }
   }
   const { helpers, helperUpgraded } = emitHelpers(dialects, contents, outFiles, options?.overwriteHelper);
-  emitStubs(dialects, snapshotSlugs, contents, outFiles);
+  emitStubs2(dialects, snapshotSlugs, contents, outFiles);
   const receipt = assertReceipt({
     briefDigest: digest,
     paths: { declared: targets.size, rewritten, alreadyDeclared, pending },
@@ -4908,7 +6223,7 @@ async function plan(file, content, dialect, targets, sites, importAt, outcomes,
     { key: "helper:bcmsRows", name: "bcmsRows" },
     { key: "helper:bcmsLayout", name: "bcmsLayout" },
     // Keyed by the SLUG: two slugs that spell one identifier are still two pages. @see scope.ts
-    ...slugs.map((slug) => ({ key: `slug:${slug}`, name: identifierFor(slug) }))
+    ...slugs.map((slug) => ({ key: `slug:${slug}`, name: identifierFor2(slug) }))
   ].filter((entry) => !preset.has(entry.key));
   const names = new Map([...preset, ...allocateNames(taken, wanted)]);
   const snapshotName = (slug) => names.get(`slug:${slug}`);
@@ -5300,7 +6615,7 @@ function emitHelpers(dialects, contents, out, overwrite) {
   }
   return { helpers, helperUpgraded };
 }
-function emitStubs(dialects, slugs, contents, out) {
+function emitStubs2(dialects, slugs, contents, out) {
   if (![...dialects].some((d) => DIALECT_RULES[d].text)) return;
   const paths = [...[...slugs].map((slug) => `${CONTENT_DIR}/${slug}.json`), `${CONTENT_DIR}/layout.json`];
   for (const path of paths.sort()) {
@@ -5310,13 +6625,15 @@ function emitStubs(dialects, slugs, contents, out) {
 }
 
 // src/cli.ts
-var VERSION = "0.1.0";
+var VERSION = "0.2.0";
 var MAX_FILE_BYTES = 512 * 1024;
 var CliError = class extends Error {
 };
 function parseArgs(argv) {
   const args = {
     brief: void 0,
+    componentize: false,
+    plan: void 0,
     root: ".",
     dryRun: false,
     receipt: void 0,
@@ -5328,6 +6645,8 @@ function parseArgs(argv) {
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === "--brief") args.brief = argv[++i];
+    else if (arg === "--componentize") args.componentize = true;
+    else if (arg === "--plan") args.plan = argv[++i];
     else if (arg === "--root") args.root = argv[++i] ?? ".";
     else if (arg === "--receipt") args.receipt = argv[++i];
     else if (arg === "--dry-run") args.dryRun = true;
@@ -5346,16 +6665,20 @@ function parseArgs(argv) {
 var HELP = `bettercms-convert ${VERSION}
 
   bettercms-convert --brief <json> --root . [options]
+  bettercms-convert --componentize --brief <json> --plan <json> --root . [options]
 
   --brief <file>       The conversion brief, as get_conversion_brief returns it. Required.
+  --componentize       Lift each planned SECTION into a component the CMS can reorder.
+  --plan <file>        The componentize plan, as get_componentize_plan returns it.
+                       Required with --componentize.
   --root <dir>         The repository to convert. Default: the working directory.
   --dry-run            Print what would change; write nothing.
   --receipt <file>     Write the receipt as JSON.
-  --strict             Exit 2 when any path is left pending (for CI).
+  --strict             Exit 2 when anything is left pending (for CI).
   --overwrite-helper   Replace a bcms-content helper this tool did not write.
   --verbose            Print stack traces and every file considered.
 
-Exit: 0 done (pending paths are listed), 1 refused, 2 --strict with pending paths.
+Exit: 0 done (pending items are listed), 1 refused, 2 --strict with pending items.
 `;
 async function readTree(root, verbose) {
   const files = [];
@@ -5381,6 +6704,26 @@ async function readTree(root, verbose) {
   await walk(root);
   return files;
 }
+async function readSnapshots(root) {
+  const dir = join2(root, CONTENT_DIR);
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw new CliError(
+        `SNAPSHOT_UNREADABLE: ${CONTENT_DIR} could not be read (${error.message}). Componentize writes into those snapshots, so it will not proceed while it cannot see them.`
+      );
+    }
+    return [];
+  }
+  const out = [];
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+    out.push({ path: `${CONTENT_DIR}/${entry.name}`, content: await readFile(join2(dir, entry.name), "utf-8") });
+  }
+  return out;
+}
 function under(root, path) {
   const target = resolve(root, path);
   if (target !== root && !target.startsWith(root + sep)) {
@@ -5404,6 +6747,24 @@ ${rewritten} of ${declared} paths bound (${alreadyDeclared} already declared, ${
 `);
   }
 }
+function reportSections(files, receipt, dryRun) {
+  const { extracted, inlineOnly, alreadyExtracted, pending } = receipt.sections;
+  for (const file of files) {
+    process.stdout.write(`${dryRun ? "would " : ""}${file.operation} ${file.path}
+`);
+  }
+  process.stdout.write(
+    `
+${extracted} sections extracted (${inlineOnly} inline-only, ${alreadyExtracted} already extracted, ${pending.length} pending)
+`
+  );
+  for (const section of pending) {
+    process.stdout.write(
+      `  pending ${section.route} ${section.groupKey} \u2014 ${section.reason}${section.message ? ` (${section.message})` : ""}
+`
+    );
+  }
+}
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (args.help) {
@@ -5411,6 +6772,9 @@ async function main() {
     return 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.");
+  }
   const root = resolve(args.root);
   const brief = JSON.parse(await readFile(resolve(args.brief), "utf-8"));
   if (!Array.isArray(brief.pages)) {
@@ -5419,26 +6783,50 @@ async function main() {
   const sources = await readTree(root, args.verbose);
   if (args.verbose) process.stderr.write(`read ${sources.length} candidate files under ${root}
 `);
-  const { files, receipt } = await convertSources(brief, sources, {
-    overwriteHelper: args.overwriteHelper
-  });
-  if (!args.dryRun) {
-    for (const file of files) {
+  const written = async (files2) => {
+    if (args.dryRun) return;
+    for (const file of files2) {
       const target = under(root, 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(receipt, null, 2)}
+  };
+  const saveReceipt = async (receipt2) => {
+    if (!args.receipt) return;
+    await writeFile(resolve(args.receipt), `${JSON.stringify(receipt2, null, 2)}
 `, "utf-8");
+  };
+  if (args.componentize) {
+    if (!args.plan) throw new CliError("--plan <file> is required with --componentize. See --help.");
+    let plan2;
+    try {
+      plan2 = readComponentizePlan(JSON.parse(await readFile(resolve(args.plan), "utf-8")));
+    } catch (error) {
+      throw new CliError(`${args.plan}: ${error.message}`);
+    }
+    const { files: files2, receipt: receipt2 } = await componentizeSources(
+      brief,
+      plan2,
+      [...sources, ...await readSnapshots(root)],
+      { overwriteHelper: args.overwriteHelper }
+    );
+    await written(files2);
+    await saveReceipt(receipt2);
+    reportSections(files2, receipt2, args.dryRun);
+    return args.strict && receipt2.sections.pending.length > 0 ? 2 : 0;
   }
+  const { files, receipt } = await convertSources(brief, sources, {
+    overwriteHelper: args.overwriteHelper
+  });
+  await written(files);
+  await saveReceipt(receipt);
   report(files, receipt, args.dryRun);
   return args.strict && receipt.paths.pending.length > 0 ? 2 : 0;
 }
 main().then((code) => process.exit(code)).catch((error) => {
   const message = error instanceof Error ? error.message : String(error);
-  const code = error instanceof ConvertError ? `${error.code}: ` : "";
+  const named = error;
+  const code = typeof named.code === "string" && /^[A-Z_]+$/.test(named.code) ? `${named.code}: ` : "";
   process.stderr.write(`${code}${message}
 `);
   if (process.argv.includes("--verbose") && error instanceof Error) {