@bettercms-ai/convert 0.3.0 → 0.4.0

package/dist/cli.js

@@ -134,7 +134,7 @@ function propsAttribute(props) {
 
 // src/helper.ts
 import { createHash as createHash2 } from "crypto";
-var HELPER_VERSION = 3;
+var HELPER_VERSION = 4;
 var HEADER = "// @bettercms-ai/convert helper v";
 var HELPER_PATH = Object.fromEntries(
   Object.keys(DIALECT_RULES).map((d) => [d, DIALECT_RULES[d].helper])
@@ -217,32 +217,97 @@ export function bcmsRows<T>(page: unknown, path: string, fallback: T[], slug?: s
 /**
  * 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.
+ * OVERRIDES FIRST, PER KEY: \`overrides[key] ?? group[key]\`. An instance that owns its copy
+ * (Phase B) carries an override for every prop it declares, so the group underneath it is never
+ * read; a placement still bound to a page field group (Phase A) carries none, so the group is all
+ * there is. The interesting case is the one in between \u2014 a section half moved \u2014 where a key the
+ * instance does not hold has to keep rendering the page's value rather than nothing.
+ *
+ * \u{1F534} \`??\`, NOT \`||\`. An empty string is a value an editor typed, and treating it as absent put
+ * the page's old copy back into a heading somebody had deliberately cleared.
+ *
+ * With neither an override nor a group, the answer is \`{}\` and every \`bcms(...)\` below renders
+ * the fallback the template shipped with \u2014 which 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 : {};
+  const base: Record<string, unknown> = isRecord(group) ? { ...group } : {};
+  if (!isRecord(overrides)) return base;
+  for (const key of Object.keys(overrides)) {
+    const value = overrides[key];
+    if (value === undefined || value === null) continue;
+    /**
+     * \u{1F534} A TABLE PROP IS STORED AS \`{ rows: [...] }\` AND READ AS A LIST. That is the shape the
+     * dashboard edits a repeater in; handing it to \`bcmsRows\` unchanged is not an array, so the
+     * helper fell back to the rows the template shipped with and the editor's work never showed.
+     */
+    base[key] = isRecord(value) && Array.isArray(value.rows) ? value.rows : value;
+  }
+  return base;
+}
+
+/**
+ * WHICH ADDRESS one bound element declares \u2014 decided at RENDER time, from the placement.
+ *
+ * An element carries exactly ONE \`data-bcms-field\`, and which lane it names depends on where its
+ * copy lives. A placement that owns its copy declares the BLOCK lane \u2014
+ * \`<blockId>__overrides.<propKey>\` \u2014 because that is the address the editor commits an instance's
+ * own value to. A placement bound to a page field group declares the PAGE path, which is what the
+ * page form and the coverage meter already know.
+ *
+ * \u{1F534} THE BOUND ADDRESS IS RE-BASED ONTO **THIS** PLACEMENT'S GROUP. The markup was cut from ONE
+ * page and carries that page's paths (\`hero.title\`); the whole point of \`shapeHash\` is that a
+ * second page renders the same component bound to a group of its own (\`bind="landingHero"\`).
+ * Handing the embedded path through unchanged declared \`hero.title\` on a page whose field is
+ * \`landingHero.title\` \u2014 an address that page does not have, so the editor wrote into nothing and
+ * the meter counted a binding that was never there. The prefix the markup was cut with comes out,
+ * the placement's own group goes in.
+ *
+ * \u{1F534} THE SAME EXTRACTED FILE SERVES BOTH LANES. The choice is a function of the props, never of
+ * how the codemod ran: one component renders a Phase A placement on one page and a Phase B
+ * instance on the next, and a repository does not have to be re-cut when its copy moves.
+ */
+export function bcmsFields(
+  placement: { blockId?: string; bind?: string; overrides?: unknown },
+  pathPrefix: string,
+): (path: string) => string {
+  const id = placement.blockId;
+  const own = typeof id === "string" && id !== "" && !placement.bind && isRecord(placement.overrides);
+  /**
+   * What replaces the prefix the markup was cut with, or null for "leave every path alone".
+   *
+   * Null covers a placement with neither a bind nor an instance \u2014 a shipped fallback, or a page
+   * nobody has componentized yet \u2014 and a bound placement in a component whose prefix is EMPTY,
+   * where the plan said the prop key IS the whole page path: there is no group segment to swap,
+   * so prepending one would invent an address rather than correct it.
+   */
+  const lane = own ? \`\${id}__overrides.\` : placement.bind && pathPrefix ? \`\${placement.bind}.\` : null;
+  return (path: string): string => {
+    // A path outside the group this section was cut from is not one this placement re-addresses:
+    // it names a key the instance does not hold and a group this placement is not bound to.
+    // (An EMPTY prefix is a plan saying the prop key IS the page path, and matches everything.)
+    if (lane === null || !path.startsWith(pathPrefix)) return path;
+    return lane + path.slice(pathPrefix.length);
+  };
 }
 `;
 }
 var HISTORICAL = {
   "src/bcms-content.ts": {
     1: "c272412532efed7db64b6cf313b2bed4291f9951430412289c8a588b7f565407",
-    2: "51e2ae65ddd86bf43d14e29b3865e3f16e45f72069692d1fea57e1f986a894f0"
+    2: "51e2ae65ddd86bf43d14e29b3865e3f16e45f72069692d1fea57e1f986a894f0",
+    3: "d4305b2983adcb456ef782d35ea9d083a04465c2b68baa0d44a084dfa01a9227"
   },
   "src/lib/bcms-content.ts": {
     1: "ae72ae14d706943d481c880d70da5789b4816ba1ba319a10fbc63ded4d0b42f2",
-    2: "a18731eb42f7db55dac0591c45f873758cde8e103fefcd6e5caf67936ae6a002"
+    2: "a18731eb42f7db55dac0591c45f873758cde8e103fefcd6e5caf67936ae6a002",
+    3: "0be9c73160361882a038552bc02673c14ed532287823dabaafe36179bc55ed7e"
   },
   "composables/bcms-content.ts": {
     1: "c272412532efed7db64b6cf313b2bed4291f9951430412289c8a588b7f565407",
-    2: "51e2ae65ddd86bf43d14e29b3865e3f16e45f72069692d1fea57e1f986a894f0"
+    2: "51e2ae65ddd86bf43d14e29b3865e3f16e45f72069692d1fea57e1f986a894f0",
+    3: "d4305b2983adcb456ef782d35ea9d083a04465c2b68baa0d44a084dfa01a9227"
   }
 };
 var sha256 = (value) => createHash2("sha256").update(value, "utf8").digest("hex");
@@ -4839,6 +4904,7 @@ function readPlan(value) {
       const section = check.record(held, at2);
       check.segment(section.groupKey, `${at2}.groupKey`);
       check.optionalString(section.sectionType, `${at2}.sectionType`);
+      check.optionalString(section.copy, `${at2}.copy`);
       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}]`);
@@ -5228,7 +5294,8 @@ function assertSections(total, sections) {
   }
   return sections;
 }
-var SECTION_MARKER = "// @bettercms-ai/convert section v1";
+var SECTION_MARKER = "// @bettercms-ai/convert section v2";
+var SECTION_MARKERS = [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";
@@ -5250,12 +5317,53 @@ async function componentizeSources(briefIn, planIn, sources, options) {
   let registered = 0;
   let planPending = 0;
   let total = 0;
+  const pend = (route, groupKey, reason, message) => void pending.push({ route, groupKey, reason, ...message ? { message } : {} });
   const brief = readBrief(briefIn);
   const plan2 = readPlan(planIn);
+  const copy = options?.copy ?? "bind";
+  const instanceOwned = (section) => section.copy === "instance";
+  const notes = unreadableConfigs(sources).map(
+    (path) => ({
+      code: "TSCONFIG_UNREADABLE",
+      file: path,
+      message: `${path} is not JSON this package can read, so its \`paths\` aliases resolved to nothing.`
+    })
+  );
+  const refuseRun = (reason, message) => {
+    for (const page of plan2.pages ?? []) {
+      for (const section of page.sections ?? []) {
+        if (section.pending) {
+          planPending++;
+          continue;
+        }
+        total++;
+        pend(page.route, section.groupKey, reason, message);
+      }
+    }
+    return {
+      files: [],
+      receipt: {
+        planDigest: plan2.digest ?? "",
+        copy,
+        sections: assertSections(total, { extracted: 0, inlineOnly: 0, alreadyExtracted: 0, registered: 0, pending }),
+        components: [],
+        planPending,
+        notes
+      }
+    };
+  };
+  const movesCopy = (plan2.pages ?? []).some(
+    (page) => (page.sections ?? []).some((section) => !section.pending && instanceOwned(section))
+  );
+  if (copy === "instance" && !movesCopy) {
+    return refuseRun(
+      "COPY_MODE_MISMATCH",
+      'this run was asked for --copy instance, but no placement in the plan carries copy: "instance" \u2014 run componentize_sections { copy: "instance" } on the server first, then fetch the plan again.'
+    );
+  }
   const contents = new Map(sources.map((s) => [s.path, s.content]));
   const fileSet = new Set(contents.keys());
   const aliases = aliasesFrom(sources);
-  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);
@@ -5269,7 +5377,9 @@ async function componentizeSources(briefIn, planIn, sources, options) {
   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;
+  if (helperExisting !== void 0 && helperVersion === null && options?.overwriteHelper !== true) {
+    return refuseRun("HELPER_CONFLICT", `${helperPath} is not a module this package wrote.`);
+  }
   const outFiles = /* @__PURE__ */ new Map();
   const written = /* @__PURE__ */ new Map();
   const shipped = /* @__PURE__ */ new Map();
@@ -5279,6 +5389,29 @@ async function componentizeSources(briefIn, planIn, sources, options) {
     return held;
   };
   const fresh = /* @__PURE__ */ new Set();
+  const bindOf = (section) => instanceOwned(section) ? void 0 : section.groupKey;
+  const placementOf = (slug, section) => {
+    const bind = bindOf(section);
+    return bind === void 0 ? { slug } : { slug, bind };
+  };
+  const rebind = (dialect, pageSlug, all, usable) => {
+    if (dialect === null || !EXTRACTABLE.includes(dialect)) return;
+    const order = shipped.get(dialect);
+    const held = order?.get(pageSlug);
+    if (!order || !held) return;
+    const queues = /* @__PURE__ */ new Map();
+    for (const section of all) {
+      const slug = resolveComponent(plan2, section).slug;
+      queues.set(slug, [...queues.get(slug) ?? [], section]);
+    }
+    order.set(
+      pageSlug,
+      held.map((placement) => {
+        const section = queues.get(placement.slug)?.shift();
+        return section && usable.has(section) ? placementOf(placement.slug, section) : placement;
+      })
+    );
+  };
   const registryConflicts = [];
   const registryUnreadable = [];
   for (const dialect of EXTRACTABLE) {
@@ -5304,6 +5437,11 @@ async function componentizeSources(briefIn, planIn, sources, options) {
   if (lib !== void 0 && !isGenerated(lib)) registryConflicts.push(SECTIONS_LIB);
   const registryBlocked = registryConflicts.length > 0 && options?.overwriteHelper !== true;
   const registryUnread = registryUnreadable.length > 0;
+  const migrated = registryBlocked || registryUnread ? { files: [], refused: /* @__PURE__ */ new Map() } : await migrateSections(plan2, contents, written, fileSet, aliases);
+  for (const file of migrated.files) {
+    addFile(outFiles, contents, file);
+    contents.set(file.path, file.content);
+  }
   for (const page of plan2.pages ?? []) {
     const sections2 = (page.sections ?? []).filter((section) => {
       if (section.pending) {
@@ -5314,23 +5452,33 @@ async function componentizeSources(briefIn, planIn, sources, options) {
     });
     total += sections2.length;
     if (sections2.length === 0) continue;
+    const prefixes = /* @__PURE__ */ new Map();
+    for (const section of sections2) {
+      const prefix = propPrefix(section);
+      if (prefix === null) {
+        pend(
+          page.route,
+          section.groupKey,
+          "PROP_MAP_INCONSISTENT",
+          "the plan's fields do not spell every path as one common prefix plus its key, so a page path cannot be turned into a prop key."
+        );
+        continue;
+      }
+      prefixes.set(section, prefix);
+    }
+    const usable = sections2.filter((section) => prefixes.has(section));
+    if (usable.length === 0) continue;
     const pendingBefore = pending.length;
     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) {
+      for (const section of usable) {
         pend(page.route, section.groupKey, "REGISTRY_CONFLICT", `${registryConflicts.join(", ")} is not a file this package wrote.`);
       }
       continue;
     }
     if (registryUnread) {
-      for (const section of sections2) {
+      for (const section of usable) {
         pend(
           page.route,
           section.groupKey,
@@ -5342,30 +5490,43 @@ async function componentizeSources(briefIn, planIn, sources, options) {
     }
     const snapshotPath = `${CONTENT_DIR}/${pageSlug}.json`;
     if (!snapshotUsable(contents.get(snapshotPath))) {
-      for (const section of sections2) {
+      for (const section of usable) {
         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) {
+      for (const section of usable) {
         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) {
+      for (const section of usable) {
         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));
+    const pageDialect = dialectOf(file, contents.get(file) ?? "");
+    const done = new Set(alreadyOn(contents.get(file) ?? "", pageSlug, usable));
+    let stuck = 0;
+    for (const section of usable) {
+      if (!done.has(section.groupKey)) continue;
+      const why = pageDialect ? migrated.refused.get(refusalKey(pageDialect, resolveComponent(plan2, section).slug)) : void 0;
+      if (why === void 0) continue;
+      done.delete(section.groupKey);
+      stuck++;
+      pend(page.route, section.groupKey, "SECTION_UNMIGRATABLE", why);
+    }
     alreadyExtracted += done.size;
-    if (done.size === sections2.length) continue;
+    if (done.size + stuck === usable.length) {
+      rebind(pageDialect, pageSlug, page.sections ?? [], new Set(usable));
+      continue;
+    }
     const found = await locateSections(
-      sections2.filter((section) => !done.has(section.groupKey)),
+      usable.filter((section) => !done.has(section.groupKey)),
       briefPage?.paths ?? [],
       sources,
       treeOf
@@ -5480,7 +5641,7 @@ async function componentizeSources(briefIn, planIn, sources, options) {
       registered++;
       registeredHere.push({
         slug: component.slug,
-        bind: held.section.groupKey,
+        section: held.section,
         call: callSiteOf(tree, member ? `${binding.local}.${member}` : held.call)
       });
     }
@@ -5492,7 +5653,13 @@ async function componentizeSources(briefIn, planIn, sources, options) {
         continue;
       }
       const component = resolveComponent(plan2, placed.section);
-      roots.push({ section: placed.section, route: page.route, root, ...component });
+      roots.push({
+        section: placed.section,
+        route: page.route,
+        root,
+        pathPrefix: prefixes.get(placed.section),
+        ...component
+      });
     }
     const nested = /* @__PURE__ */ new Set();
     for (const a of roots) {
@@ -5519,7 +5686,25 @@ async function componentizeSources(briefIn, planIn, sources, options) {
         placeable.push(resolved);
         continue;
       }
-      const built = componentFile(dialect, path, file, content, parsed, resolved);
+      const built = componentFile(dialect, path, file, content, parsed, resolved, resolved.pathPrefix);
+      if (built.unconvertible.length > 0) {
+        pend(
+          page.route,
+          resolved.section.groupKey,
+          "PROP_MAP_INCONSISTENT",
+          `its fields map to the prefix "${resolved.pathPrefix}", which ${[...new Set(built.unconvertible)].slice(0, 3).join(", ")} cannot be converted through \u2014 so those elements would stay on the page lane whatever the placement says.`
+        );
+        continue;
+      }
+      if (built.duplicates.length > 0) {
+        pend(
+          page.route,
+          resolved.section.groupKey,
+          "DUPLICATE_FIELD_BINDING",
+          `${built.duplicates.join(", ")} carries more than one data-bcms-field, so there is no single address to rewrite.`
+        );
+        continue;
+      }
       if (built.free.length > 0) {
         pend(
           page.route,
@@ -5540,8 +5725,8 @@ async function componentizeSources(briefIn, planIn, sources, options) {
     }
     if (placeable.length === 0 && registeredHere.length === 0) continue;
     const spans = [
-      ...placeable.map((r) => ({ slug: r.slug, bind: r.section.groupKey, root: r.root })),
-      ...registeredHere.map((r) => ({ slug: r.slug, bind: r.bind, root: r.call }))
+      ...placeable.map((r) => ({ slug: r.slug, bind: bindOf(r.section), root: r.root })),
+      ...registeredHere.map((r) => ({ slug: r.slug, bind: bindOf(r.section), root: r.call }))
     ].sort((a, b) => (a.root?.start ?? Number.MAX_SAFE_INTEGER) - (b.root?.start ?? Number.MAX_SAFE_INTEGER));
     const known = spans.filter((s) => s.root !== null);
     const layout = runOf(known, parsed.roots, content);
@@ -5557,7 +5742,7 @@ async function componentizeSources(briefIn, planIn, sources, options) {
     shipped.set(dialect, order);
     order.set(
       pageSlug,
-      spans.map((s) => ({ slug: s.slug, bind: s.bind }))
+      spans.map((s) => s.bind === void 0 ? { slug: s.slug } : { slug: s.slug, bind: s.bind })
     );
     if (useRun) {
       addFile(outFiles, contents, {
@@ -5566,13 +5751,25 @@ async function componentizeSources(briefIn, planIn, sources, options) {
         content: splicePageRun(file, content, dialect, parsed, known, pageSlug)
       });
       extracted += placeable.length;
-    } else if (placeable.length > 0) {
-      addFile(outFiles, contents, {
-        path: file,
-        operation: "modify",
-        content: splicePageInline(file, content, dialect, parsed, placeable, pageSlug, extractable)
-      });
-      inlineOnly += placeable.length;
+    } else {
+      const inline = placeable.filter((resolved) => !instanceOwned(resolved.section));
+      for (const resolved of placeable) {
+        if (inline.includes(resolved)) continue;
+        pend(
+          page.route,
+          resolved.section.groupKey,
+          "INLINE_NEEDS_INSTANCE",
+          `${file} cannot be replaced by one <Sections page="${pageSlug}" />, and an in-place call site carries no blockId or overrides \u2014 so this placement's own copy could not be rendered or addressed.`
+        );
+      }
+      if (inline.length > 0) {
+        addFile(outFiles, contents, {
+          path: file,
+          operation: "modify",
+          content: splicePageInline(file, content, dialect, parsed, inline, pageSlug, extractable)
+        });
+      }
+      inlineOnly += inline.length;
     }
   }
   const componentSlugs = [...written.values()].flatMap((held) => [...held.keys()]);
@@ -5600,17 +5797,12 @@ async function componentizeSources(briefIn, planIn, sources, options) {
     files: [...outFiles.values()].sort((a, b) => a.path.localeCompare(b.path)),
     receipt: {
       planDigest: plan2.digest ?? "",
+      copy,
       sections,
       // What THIS run wrote a file for. A component an earlier run left is reused, not re-reported.
       components: [...fresh].sort(),
       planPending,
-      notes: unreadableConfigs(sources).map(
-        (path) => ({
-          code: "TSCONFIG_UNREADABLE",
-          file: path,
-          message: `${path} is not JSON this package can read, so its \`paths\` aliases resolved to nothing.`
-        })
-      )
+      notes
     }
   };
 }
@@ -5633,7 +5825,7 @@ async function readRegistry(content, dialect, path, files, aliases) {
     if (!from.specifier.startsWith(".")) continue;
     const resolved = resolveSpecifier(path, from.specifier, files, aliases);
     if (resolved !== null) {
-      imports.set(local, { name: local, path: resolved, kind: from.kind, imported: from.imported });
+      imports.set(local, { name: local, path: preferDialect(resolved, dialect, files), kind: from.kind, imported: from.imported });
     }
   }
   const registry = blockOf(content, "REGISTRY");
@@ -5642,6 +5834,7 @@ async function readRegistry(content, dialect, path, files, aliases) {
   const registryRows = propertiesOf(registry);
   const shippedRows = propertiesOf(table);
   if (registryRows === null || shippedRows === null) return null;
+  if (registryRows.length === 0) return null;
   for (const row of registryRows) {
     const named = row.value.match(/^([A-Za-z_$][\w$]*)(?:\.([A-Za-z_$][\w$]*))?$/);
     const entry = named ? imports.get(named[1]) : void 0;
@@ -5651,7 +5844,8 @@ async function readRegistry(content, dialect, path, files, aliases) {
   for (const row of shippedRows) {
     try {
       const placements = JSON.parse(row.value);
-      if (!Array.isArray(placements)) return null;
+      if (!Array.isArray(placements) || placements.length === 0 || !placements.every(isPlacement)) return null;
+      if (placements.some((placement) => !components.has(placement.slug))) return null;
       shipped.set(row.key, placements);
     } catch {
       return null;
@@ -5659,6 +5853,18 @@ async function readRegistry(content, dialect, path, files, aliases) {
   }
   return { components, shipped };
 }
+function preferDialect(resolved, dialect, files) {
+  const wanted = dialect === "astro" ? [".astro"] : [".tsx", ".jsx"];
+  if (wanted.some((extension) => resolved.endsWith(extension))) return resolved;
+  const base = resolved.replace(/\.[^./]+$/, "");
+  return wanted.map((extension) => `${base}${extension}`).find((candidate) => files.has(candidate)) ?? resolved;
+}
+function isPlacement(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const held = value;
+  if (typeof held.slug !== "string") return false;
+  return ["bind", "blockId"].every((key) => held[key] === void 0 || typeof held[key] === "string");
+}
 function blockOf(content, name) {
   const declaration2 = content.indexOf(`const ${name}`);
   if (declaration2 < 0) return null;
@@ -5905,14 +6111,35 @@ function pascal(value) {
   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);
+function componentFile(dialect, path, fromFile, content, parsed, resolved, pathPrefix) {
+  const addresses = fieldAddresses(content, elementsUnder(resolved.root));
+  const unconvertible = [
+    ...addresses.heads.filter((address) => !address.startsWith(pathPrefix)),
+    ...addresses.opaque
+  ];
+  if (unconvertible.length > 0) return { content: "", free: [], duplicates: [], unconvertible };
+  const cut = content.slice(resolved.root.start, resolved.root.end);
+  const reserved = /* @__PURE__ */ new Set([...topLevelBindings(dialect, parsed, content), ...referencedNames2(cut)]);
+  const introduced = allocateNames(reserved, [
+    { key: "bcmsFields", name: "bcmsFields" },
+    { key: "bcmsField", name: "bcmsField" }
+  ]);
+  const fieldsName = introduced.get("bcmsFields");
+  const fieldName = introduced.get("bcmsField");
+  const { markup, bound, duplicates } = sectionMarkup(content, resolved.root, fieldName);
+  if (duplicates.length > 0) return { content: "", free: [], duplicates, unconvertible: [] };
   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 helpers = [
+    .../* @__PURE__ */ new Set([
+      ...helperNames.map((h) => alias(h.name, h.local)),
+      "bcmsSection",
+      ...bound > 0 ? [alias("bcmsFields", fieldsName)] : []
+    ])
+  ].sort();
   const helperSpecifier = relativeImport(path, HELPER_PATH[dialect]).replace(/\.tsx?$/, "");
   const snapshot = snapshotOf(parsed, dialect, fromFile, markup);
   const carry = carryFor({
@@ -5927,20 +6154,23 @@ function componentFile(dialect, path, fromFile, content, parsed, resolved) {
       "bind",
       "overrides",
       "page",
+      fieldName,
       ...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 };
+  if (carry.free.length > 0) return { content: "", free: carry.free, duplicates: [], unconvertible: [] };
   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) };` : "";
+  const copy = snapshot ? `const ${snapshot} = { ${key}: bcmsSection(page, bind, overrides) };` : "";
+  const field = bound > 0 ? `const ${fieldName} = ${fieldsName}({ blockId, bind, overrides }, ${JSON.stringify(pathPrefix)});` : "";
+  const declared = [copy, field].filter(Boolean).join("\n");
   if (dialect === "astro") {
-    return { free: [], content: `---
+    return { free: [], duplicates: [], unconvertible: [], content: `---
 ${SECTION_MARKER}
 ${[...carried, `import { ${helpers.join(", ")} } from "${helperSpecifier}";`].join("\n")}
 
@@ -5955,27 +6185,297 @@ interface Props {
   page?: unknown;
 }
 const { blockId, bind, overrides, page } = Astro.props;
-${carriedDeclarations}${copy}
+${carriedDeclarations}${declared}
 ---
 ${markup}
 ` };
   }
-  return { free: [], content: `${SECTION_MARKER}
+  return { free: [], duplicates: [], unconvertible: [], 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}
+  ${declared.split("\n").join("\n  ")}
   return (
     ${markup}
   );
 }
 ` };
 }
-function sliceWithBlockId(content, root) {
+function sectionMarkup(content, root, fieldName) {
   const slice = new MagicString3(content.slice(root.start, root.end));
-  slice.appendLeft(root.attrInsertAt - root.start, " data-bcms-block={blockId}");
-  return slice.toString();
+  const at = (offset) => offset - root.start;
+  const stamps = root.attrs.filter((attr) => attr.name === "data-bcms-block");
+  if (stamps.length === 0) slice.appendLeft(at(root.attrInsertAt), " data-bcms-block={blockId}");
+  else {
+    slice.overwrite(at(stamps[0].range.start), at(stamps[0].range.end), "data-bcms-block={blockId}");
+    for (const extra of stamps.slice(1)) {
+      let from = extra.range.start;
+      while (from > root.start && /\s/.test(content[from - 1])) from--;
+      slice.remove(at(from), at(extra.range.end));
+    }
+  }
+  const wrapped = wrapFieldAttrs(slice, content, elementsUnder(root), at, fieldName);
+  return { markup: slice.toString(), ...wrapped };
+}
+function wrapFieldAttrs(slice, content, elements, at, fieldName) {
+  let bound = 0;
+  const duplicates = [];
+  for (const element of elements) {
+    const fields = element.attrs.filter((attr) => attr.name === "data-bcms-field");
+    if (fields.length > 1) {
+      duplicates.push(`<${element.tag}>`);
+      continue;
+    }
+    for (const attr of fields) {
+      bound++;
+      if (attr.expressionRange) {
+        slice.appendRight(at(attr.expressionRange.start) + 1, `${fieldName}(`);
+        slice.appendLeft(at(attr.expressionRange.end) - 1, ")");
+        continue;
+      }
+      const value = attr.valueRange ? content.slice(attr.valueRange.start, attr.valueRange.end) : "";
+      slice.overwrite(
+        at(attr.range.start),
+        at(attr.range.end),
+        `data-bcms-field={${fieldName}(${JSON.stringify(value)})}`
+      );
+    }
+  }
+  return { bound, duplicates };
+}
+function provableAddress(expression) {
+  const first = expression[0];
+  if (first === '"' || first === "'") {
+    for (let at = 1; at < expression.length; at++) {
+      if (expression[at] === "\\") {
+        at++;
+        continue;
+      }
+      if (expression[at] === first) return at === expression.length - 1 ? expression.slice(1, at) : null;
+    }
+    return null;
+  }
+  if (first !== "`" || expression.length < 2 || !expression.endsWith("`")) return null;
+  const body = expression.slice(1, -1);
+  if (body.includes("`") || body.includes("\\")) return null;
+  let head = null;
+  for (let at = 0; at < body.length; at++) {
+    if (body[at] !== "$" || body[at + 1] !== "{") continue;
+    const close = body.indexOf("}", at + 2);
+    if (close < 0) return null;
+    if (!/^[A-Za-z_$][\w$]*$/.test(body.slice(at + 2, close).trim())) return null;
+    if (body[at - 1] !== "[" || body[close + 1] !== "]") return null;
+    head ??= body.slice(0, at);
+    at = close;
+  }
+  return head ?? body;
+}
+function fieldAddresses(content, elements) {
+  const heads = [];
+  const opaque = [];
+  for (const element of elements) {
+    for (const attr of element.attrs) {
+      if (attr.name !== "data-bcms-field") continue;
+      if (!attr.expression && attr.valueRange) {
+        heads.push(content.slice(attr.valueRange.start, attr.valueRange.end));
+        continue;
+      }
+      const inner = attr.expressionRange ? content.slice(attr.expressionRange.start + 1, attr.expressionRange.end - 1).trim() : "";
+      const head = provableAddress(inner);
+      if (head === null) opaque.push(`data-bcms-field={${inner}}`);
+      else heads.push(head);
+    }
+  }
+  return { heads, opaque };
+}
+function elementsUnder(...roots) {
+  const out = [];
+  const walk = (node) => {
+    if (node.type === "element") {
+      out.push(node);
+      for (const child of node.children) walk(child);
+      return;
+    }
+    if (node.type === "expr") for (const child of node.children) walk(child);
+  };
+  for (const root of roots) walk(root);
+  return out;
+}
+var V1_ANCHOR = {
+  astro: "const { blockId, bind, overrides, page } = Astro.props;",
+  jsx: "}: BcmsSectionProps) {"
+};
+var refusalKey = (dialect, slug) => `${dialect}\0${slug}`;
+function generatedBindings(parsed) {
+  const program = parsed.ast?.program;
+  const body = program?.body ?? [];
+  const scopes = [body];
+  for (const statement of body) {
+    const declaration2 = statement.type === "ExportDefaultDeclaration" ? statement.declaration : void 0;
+    const inner = declaration2?.type === "FunctionDeclaration" ? declaration2.body?.body : void 0;
+    if (inner) scopes.push(inner);
+  }
+  const out = /* @__PURE__ */ new Map();
+  for (const scope of scopes) {
+    for (const statement of scope) {
+      if (statement.type !== "VariableDeclaration") continue;
+      for (const declarator of statement.declarations ?? []) {
+        const id = declarator.id;
+        const name = id?.type === "Identifier" ? id.name : void 0;
+        if (name !== void 0 && !out.has(name)) out.set(name, declarator.init);
+      }
+    }
+  }
+  return out;
+}
+function stripBindFallback(parsed, source, content, locals) {
+  if (!parsed.ast?.program) return "unreadable";
+  const offset = parsed.script?.offset ?? 0;
+  let rewritten = 0;
+  let unproven = 0;
+  walkAst(parsed.ast, (node) => {
+    if (node.type !== "CallExpression") return;
+    const argument = (node.arguments ?? [])[1];
+    if (argument?.type !== "LogicalExpression" || argument.operator !== "??") return;
+    const callee = node.callee;
+    if (callee?.type !== "Identifier" || !locals.has(callee.name)) {
+      unproven++;
+      return;
+    }
+    const left = argument.left;
+    source.overwrite(
+      offset + argument.start,
+      offset + argument.end,
+      content.slice(offset + left.start, offset + left.end)
+    );
+    rewritten++;
+  });
+  return rewritten === 0 && unproven > 0 ? "unproven" : "ok";
+}
+var isCallOf = (init, callee) => {
+  const fn = init?.type === "CallExpression" ? init.callee : void 0;
+  return fn?.type === "Identifier" && fn.name === callee;
+};
+async function migrateSections(plan2, contents, written, fileSet, aliases) {
+  const files = [];
+  const refused = /* @__PURE__ */ new Map();
+  const prefixesFor = (slug) => {
+    const out = /* @__PURE__ */ new Set();
+    for (const page of plan2.pages ?? []) {
+      for (const section of page.sections ?? []) {
+        if (resolveComponent(plan2, section).slug !== slug) continue;
+        const prefix = propPrefix(section);
+        if (prefix !== null) out.add(prefix);
+      }
+    }
+    return [...out];
+  };
+  for (const [dialect, components] of written) {
+    for (const [slug, entry] of components) {
+      const content = contents.get(entry.path);
+      if (content === void 0 || content.includes(SECTION_MARKER)) continue;
+      const older = SECTION_MARKERS.find((marker) => content.includes(marker));
+      if (older === void 0) continue;
+      const candidates = prefixesFor(slug);
+      if (candidates.length === 0) continue;
+      const parsed = await parseFile4(dialect, content);
+      if (parsed.error) {
+        refused.set(refusalKey(dialect, slug), `${entry.path} carries our marker but does not parse (${parsed.error.message}).`);
+        continue;
+      }
+      const elements = elementsUnder(...parsed.roots);
+      const imports = [...importsIn(parsed, dialect)];
+      const helperModule = HELPER_PATH[dialect];
+      const helperLocalsFor = (exported) => new Set(
+        imports.filter(
+          ([, from]) => from.imported === exported && resolveSpecifier(entry.path, from.specifier, fileSet, aliases) === helperModule
+        ).map(([local]) => local)
+      );
+      const { heads: evidence, opaque } = fieldAddresses(content, elements);
+      const pathPrefix = evidence.length + opaque.length === 0 ? "" : opaque.length > 0 ? null : onlyOne(candidates.filter((prefix) => evidence.every((head) => head.startsWith(prefix)))) ?? null;
+      if (pathPrefix === null) {
+        const matching = candidates.filter((prefix) => evidence.every((head) => head.startsWith(prefix)));
+        refused.set(
+          refusalKey(dialect, slug),
+          opaque.length > 0 ? `${entry.path} carries ${[...new Set(opaque)].slice(0, 3).join(", ")}, whose address this cannot read \u2014 so there is no prefix it can be shown to convert through.` : matching.length === 0 ? `${entry.path} declares ${evidence.length > 0 ? `addresses (${[...new Set(evidence)].slice(0, 3).join(", ")})` : "addresses"} that match none of this slug's placements (${candidates.join(", ") || "none with a usable prop map"}), so the prefix its markup was cut with cannot be recovered.` : `${entry.path} matches more than one of this slug's placements (${matching.join(", ")}), so the prefix its markup was cut with is ambiguous.`
+        );
+        continue;
+      }
+      const source = new MagicString3(content);
+      const { bound, duplicates } = wrapFieldAttrs(source, content, elements, (at) => at, "bcmsField");
+      if (duplicates.length > 0) {
+        refused.set(refusalKey(dialect, slug), `${entry.path} has ${duplicates.join(", ")} carrying more than one data-bcms-field, so there is no single address to rewrite.`);
+        continue;
+      }
+      const markerEnd = content.indexOf(older) + older.length;
+      source.overwrite(markerEnd - older.length, markerEnd, SECTION_MARKER);
+      const stripped = stripBindFallback(parsed, source, content, helperLocalsFor("bcmsSection"));
+      if (stripped !== "ok") {
+        refused.set(
+          refusalKey(dialect, slug),
+          stripped === "unreadable" ? `${entry.path} carries our marker but its module could not be read as a program, so the Phase A \`bind ?? "\u2026"\` fallback cannot be shown to be gone.` : `${entry.path} carries a \`?? \` fallback in a call this cannot identify as ${helperModule}'s bcmsSection, so the Phase A page-group default cannot be shown to be gone.`
+        );
+        continue;
+      }
+      if (bound > 0) {
+        const locals = generatedBindings(parsed);
+        const names = /* @__PURE__ */ new Set([...topLevelBindings(dialect, parsed, content), ...locals.keys()]);
+        const fieldsLocal = [...helperLocalsFor("bcmsFields")][0];
+        if (fieldsLocal === void 0 && names.has("bcmsFields")) {
+          refused.set(
+            refusalKey(dialect, slug),
+            `${entry.path} already binds "bcmsFields" to something other than ${helperModule}'s export.`
+          );
+          continue;
+        }
+        const declared = names.has("bcmsField");
+        if (declared && (fieldsLocal === void 0 || !isCallOf(locals.get("bcmsField"), fieldsLocal))) {
+          refused.set(
+            refusalKey(dialect, slug),
+            `${entry.path} already binds "bcmsField" to something other than a call of ${helperModule}'s bcmsFields.`
+          );
+          continue;
+        }
+        if (!declared) {
+          const anchor = V1_ANCHOR[dialect];
+          const at = anchor ? content.indexOf(anchor) : -1;
+          if (anchor === void 0 || at < 0) {
+            refused.set(refusalKey(dialect, slug), `${entry.path} carries our marker but no longer declares its placement, so there is nowhere the chooser can be put.`);
+            continue;
+          }
+          source.appendLeft(
+            at + anchor.length,
+            `
+${dialect === "astro" ? "" : "  "}const bcmsField = ${fieldsLocal ?? "bcmsFields"}({ blockId, bind, overrides }, ${JSON.stringify(pathPrefix)});`
+          );
+        }
+        if (fieldsLocal === void 0) {
+          const helper = imports.find(([, from]) => from.imported === "bcmsSection")?.[1].specifier ?? relativeImport(entry.path, HELPER_PATH[dialect]).replace(/\.tsx?$/, "");
+          source.appendLeft(markerEnd, `
+import { bcmsFields } from "${helper}";`);
+        }
+      }
+      files.push({ path: entry.path, operation: "modify", content: source.toString() });
+    }
+  }
+  return { files, refused };
+}
+function propPrefix(section) {
+  const prefixes = /* @__PURE__ */ new Set();
+  for (const field of section.fields ?? []) {
+    const { path, key } = field;
+    if (typeof path !== "string" || typeof key !== "string") continue;
+    if (!path.endsWith(key)) return null;
+    prefixes.add(path.slice(0, path.length - key.length));
+  }
+  if (prefixes.size > 1) return null;
+  return prefixes.size === 1 ? [...prefixes][0] : `${section.groupKey}.`;
+}
+function referencedNames2(markup) {
+  const out = /* @__PURE__ */ new Set();
+  for (const [name] of markup.matchAll(/[A-Za-z_$][\w$]*/g)) out.add(name);
+  return out;
 }
 var alias = (name, local) => name === local ? name : `${name} as ${local}`;
 var mentions = (markup, name) => new RegExp(`(?<![\\w$])${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?![\\w$])`).test(markup);
@@ -6234,7 +6734,7 @@ function addImports(source, parsed, lines) {
   else source.appendLeft(at.at, `
 ${lines.join("\n")}`);
 }
-var isGenerated = (content) => content.includes(SECTION_MARKER) || content.includes(REGISTRY_MARKER);
+var isGenerated = (content) => SECTION_MARKERS.some((marker) => content.includes(marker)) || content.includes(REGISTRY_MARKER);
 function emitHelper(out, contents, version, overwrite) {
   const path = HELPER_PATH.astro;
   const source = helperSource("astro");
@@ -7087,7 +7587,7 @@ function emitStubs2(dialects, slugs, contents, out) {
 }
 
 // src/cli.ts
-var VERSION = "0.2.0";
+var VERSION = "0.4.0";
 var MAX_FILE_BYTES = 512 * 1024;
 var CliError = class extends Error {
 };
@@ -7096,6 +7596,7 @@ function parseArgs(argv) {
     brief: void 0,
     componentize: false,
     plan: void 0,
+    copy: "bind",
     root: ".",
     dryRun: false,
     receipt: void 0,
@@ -7109,7 +7610,13 @@ function parseArgs(argv) {
     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 === "--copy") {
+      const mode = argv[++i];
+      if (mode !== "bind" && mode !== "instance") {
+        throw new CliError(`--copy takes "bind" or "instance", not ${JSON.stringify(mode ?? "")}. See --help.`);
+      }
+      args.copy = mode;
+    } else if (arg === "--root") args.root = argv[++i] ?? ".";
     else if (arg === "--receipt") args.receipt = argv[++i];
     else if (arg === "--dry-run") args.dryRun = true;
     else if (arg === "--strict") args.strict = true;
@@ -7133,6 +7640,10 @@ var HELP = `bettercms-convert ${VERSION}
   --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.
+  --copy bind|instance Which copy model the plan is expected to describe. Default: bind
+                       (the copy stays in the page's field groups). "instance" is refused
+                       \u2014 COPY_MODE_MISMATCH \u2014 unless the plan's placements say the server
+                       has already moved it onto them.
   --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.
@@ -7217,7 +7728,7 @@ function reportSections(files, receipt, dryRun) {
   }
   process.stdout.write(
     `
-${extracted} sections extracted (${registered} registered, ${inlineOnly} inline-only, ${alreadyExtracted} already extracted, ${pending.length} pending)
+${extracted} sections extracted (${registered} registered, ${inlineOnly} inline-only, ${alreadyExtracted} already extracted, ${pending.length} pending), copy: ${receipt.copy}
 `
   );
   for (const section of pending) {
@@ -7237,6 +7748,9 @@ async function main() {
   if (args.plan && !args.componentize) {
     throw new CliError("--plan is only read with --componentize. See --help.");
   }
+  if (args.copy === "instance" && !args.componentize) {
+    throw new CliError("--copy 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)) {
@@ -7270,7 +7784,7 @@ async function main() {
       brief,
       plan2,
       [...sources, ...await readSnapshots(root)],
-      { overwriteHelper: args.overwriteHelper }
+      { overwriteHelper: args.overwriteHelper, copy: args.copy }
     );
     await written(files2);
     await saveReceipt(receipt2);