@bettercms-ai/convert 0.18.2 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @bettercms-ai/convert
 
+## 0.20.0
+
+### Minor Changes
+
+- c4bd14b: `--forms` wires an Astro `<form>` by the CMS form's NAME: `data-bcms-form={bcmsFormId("Contact")}`, `action={bcmsFormAction("Contact")}` and `method={bcmsFormMethod("Contact")}`, resolved at build by a committed `src/bcms-forms.ts` from `bcms-content.json` and `BCMS_API_URL`. The source carries no host and no form id, so a repository built by more than one BetterCMS environment wires each build to the environment that built it. An Astro form wired by id is rewired by name once, one wired by name with a static `method="post"` gets `method={bcmsFormMethod(…)}` once, and one already wired by name counts as wired whatever quotes or spacing a formatter gave the calls; a shared name pends `FORM_NAME_AMBIGUOUS`. Form NAMES are the cross-rung contract; rename on both rungs: a wiring by name is never rewritten, so a form this project calls something else pends `FORM_WIRED_TO_OTHER_NAME` with nothing written, and a wiring by a name no form of the brief covers gets one note. At build the helper never fails: a name it cannot resolve among the project's own non-ignored forms, a shared name or a missing `BCMS_API_URL` renders that form unwired (no `action`, no `method`, no `data-bcms-form`) with one warning line naming `BCMS_FORM_NOT_FOUND`, `BCMS_FORM_NAME_AMBIGUOUS` or `BCMS_FORM_API_URL_MISSING` and the form, and a `bcms-content.json` it cannot parse, or one listing a form with no id or name, renders every form unwired with one `FORMS_SNAPSHOT_UNREADABLE` line, because forms are derived only by the release of a successful build. The helper passes a strict site tsconfig (`astro check`). Its first line, `// @bettercms-ai/convert forms-helper v2`, marks it as ours: a copy at that version or older (v1 included) is rewritten to the current bytes, and a `src/bcms-forms.ts` without that line pends `HELPER_CONFLICT`. A matched `<form>` that already carries every attribute no longer gains a stray space.
+
+  Not changed: html and JSX forms stay wired by id (html has no build, and JSX may render in a client bundle that cannot use `node:fs`). The backend's orchestration-validation workflow is left unsuffixed; only the convert, section-validation and component-validation workflows are per rung.
+
+## 0.19.0
+
+### Minor Changes
+
+- 3d022b0: A locale copy placed on its default-locale twin's section component now carries `props.bindPaths` (`{ <propKey>: "<this page's field path>" }`) beside `bind`, because its own field keys differ from the component's. `ComponentProps.bindPaths` is new in types; the convert helper (v9) and the extracted section components and registry read a prop's copy and declare its address through it, so `/fr` renders and edits its own words instead of a field it does not have. Older readers ignore it.
+
+### Patch Changes
+
+- Updated dependencies [12b2d62]
+- Updated dependencies [3d022b0]
+- Updated dependencies [a0a6ad9]
+- Updated dependencies [621a70e]
+- Updated dependencies [2729e58]
+  - @bettercms-ai/types@1.25.0
+
 ## 0.18.2
 
 ### Patch Changes

package/README.md

@@ -624,13 +624,43 @@ It writes six things onto a matched `<form>` and nothing else: `action="<submitU
 `method="post"`, `data-bcms-form="<id>"` (plus `data-bcms-form-success` when the CMS form has a
 success message), `data-bcms-form-field="<key>"` on each matched control, a
 `<p class="bcms-form-msg" hidden>` before `</form>` when there is none, and the submit script once
-per file — the same bytes the hosted renderer ships, pinned by a test. No helper, no snapshot, no
-import: a form posts to an absolute URL at runtime, so there is nothing to read at build time.
+per file — the same bytes the hosted renderer ships, pinned by a test.
+
+In an Astro file the form is named, not addressed: `data-bcms-form={bcmsFormId("Contact")}`,
+`action={bcmsFormAction("Contact")}` and `method={bcmsFormMethod("Contact")}`, imported from
+`src/bcms-forms.ts`, which this run adds. At build that helper reads the form's id from
+`bcms-content.json` and the API from `BCMS_API_URL`, so the source holds no host and no id and every
+BetterCMS environment that builds the repository wires it to itself. The built page is unchanged: an
+id, an absolute action and `post`. The helper reads the forms the brief names from: the building
+project's own, ignored ones left out. With no snapshot (a local build) the form renders unwired. The
+helper never fails a build: a name it cannot resolve, a name two forms share, or a build with no
+`BCMS_API_URL` renders that form unwired too (no `action`, no `method`, no `data-bcms-form`, so
+Astro drops all three) and prints one warning line naming the code (`BCMS_FORM_NOT_FOUND`,
+`BCMS_FORM_NAME_AMBIGUOUS`, `BCMS_FORM_API_URL_MISSING`) and the form; a `bcms-content.json` it
+cannot parse, or one listing a form with no id or name, renders every form unwired with one
+`FORMS_SNAPSHOT_UNREADABLE` line. Forms are derived by the release of a successful build and convert
+runs after it, so a helper that threw would leave a first import or a renamed form undeployable for
+good. The helper type-checks under a strict site tsconfig, because `astro check` lints it. Its first
+line, `// @bettercms-ai/convert forms-helper v2`, is what makes the file ours: a copy at that version
+or older is rewritten to the current bytes, a newer one is left alone, and a file without the line is
+`HELPER_CONFLICT`. An Astro form an earlier run wired by id is rewired by name once, a form wired by
+name with v1's static `method="post"` gets `method={bcmsFormMethod(…)}` once, and a form wired by
+name counts as wired whatever quotes or spacing a formatter gave the calls. html and JSX still get
+the literal id and endpoint of the environment that ran the codemod — html has no build, and a JSX
+form may render in a client bundle that cannot read a file.
+
+**Form NAMES are the cross-rung contract; rename on both rungs.** A wiring by name is never
+rewritten, whether or not the name resolves on the environment running the codemod: prod and dev
+share the name and nothing else, so rewriting it for one unwires the form on the other. A form this
+project calls something else is pending `FORM_WIRED_TO_OTHER_NAME` and nothing is written; a wiring by
+a name no form of the brief even covers gets one line in `notes`.
 
 The match is the FIELD KEYS: a `<form>` is a CMS form's only when the names its controls post are a
 superset of that form's field keys and exactly one `<form>` answers. Everything else is pending with
 a reason — `FORM_NOT_IN_SOURCE`, `FORM_AMBIGUOUS`, `FIELD_UNMATCHED`, `ACTION_IS_EXPRESSION`,
-`DIALECT_UNSUPPORTED`, `PARSE_ERROR` — because a form wired to the wrong id sends the customer's
+`DIALECT_UNSUPPORTED`, `PARSE_ERROR`, and for Astro `FORM_NAME_AMBIGUOUS` (two CMS forms share the
+name), `HELPER_CONFLICT` (`src/bcms-forms.ts` is somebody else's file) and
+`FORM_WIRED_TO_OTHER_NAME` (the `<form>` is wired by another name) — because a form wired to the wrong id sends the customer's
 leads into another form's inbox, silently, forever. A `<form>` that already carries
 `data-bcms-form` is `alreadyWired` and is left alone, so a second run is a no-op.
 

package/dist/cli.js

@@ -4190,7 +4190,7 @@ async function bindImages(ctx, targets) {
 
 // src/helper.ts
 import { createHash as createHash2 } from "crypto";
-var HELPER_VERSION = 8;
+var HELPER_VERSION = 9;
 var HEADER = "// @bettercms-ai/convert helper v";
 var HELPER_PATH = Object.fromEntries(
   Object.keys(DIALECT_RULES).map((d) => [d, DIALECT_RULES[d].helper])
@@ -4355,9 +4355,19 @@ export function bcmsImage<T>(page: unknown, path: string, fallback: T, slug?: st
  * 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> {
+export function bcmsSection(
+  page: unknown,
+  bind?: string,
+  overrides?: unknown,
+  bindPaths?: Record<string, string>,
+): Record<string, unknown> {
   const group = bind ? readPath(page, bind) : undefined;
   const base: Record<string, unknown> = isRecord(group) ? { ...group } : {};
+  // A locale copy on its twin's component spells its fields its own way: each prop's copy is
+  // read from the path the placement names for it.
+  if (bind && isRecord(bindPaths)) {
+    for (const [key, path] of Object.entries(bindPaths)) base[key] = readPath(page, path);
+  }
   if (!isRecord(overrides)) return base;
   for (const key of Object.keys(overrides)) {
     const value = overrides[key];
@@ -4420,21 +4430,25 @@ export function bcmsSectionPaths(
   overrides: unknown,
   prefix: string,
   map: BcmsPathMap,
+  bindPaths?: Record<string, string>,
 ): Record<string, unknown> {
   const out: Record<string, unknown> = isRecord(page) ? { ...page } : {};
   const own = isRecord(overrides) ? overrides : {};
   const separator = prefix.slice(-1);
-  const fromPage = (path: string): unknown =>
-    bind ? readPath(page, bind + separator + path.slice(prefix.length)) : undefined;
+  // A re-keyed locale copy names each prop's path on its own page; any other placement re-bases.
+  const fromPage = (path: string, key: string): unknown =>
+    !bind ? undefined
+    : isRecord(bindPaths) && typeof bindPaths[key] === "string" ? readPath(page, bindPaths[key])
+    : readPath(page, bind + separator + path.slice(prefix.length));
   for (const [path, key] of Object.entries(map.scalars ?? {})) {
     const value = own[key];
-    out[path] = value !== undefined && value !== null ? value : fromPage(path);
+    out[path] = value !== undefined && value !== null ? value : fromPage(path, key);
   }
   for (const [path, table] of Object.entries(map.tables ?? {})) {
     const held = own[table.key];
     const rows = isRecord(held) && Array.isArray(held.rows) ? held.rows : held;
     if (!Array.isArray(rows)) {
-      out[path] = fromPage(path);
+      out[path] = fromPage(path, table.key);
       continue;
     }
     const pageColumn = new Map(Object.entries(table.columns).map(([column, key]) => [key, column]));
@@ -4449,12 +4463,17 @@ export function bcmsSectionPaths(
 }
 
 export function bcmsFields(
-  placement: { blockId?: string; bind?: string; overrides?: unknown },
+  placement: { blockId?: string; bind?: string; overrides?: unknown; bindPaths?: Record<string, string> },
   pathPrefix: string,
   map?: BcmsPathMap,
 ): (path: string) => string {
   const id = placement.blockId;
   const own = typeof id === "string" && id !== "" && !placement.bind && isRecord(placement.overrides);
+  /** A re-keyed locale copy's own path for a prop, with whatever follows the prop kept. */
+  const moved = (key: string | undefined, rest: string): string | undefined => {
+    const paths = placement.bind && isRecord(placement.bindPaths) ? placement.bindPaths : undefined;
+    return key !== undefined && paths && typeof paths[key] === "string" ? paths[key] + rest : undefined;
+  };
   /**
    * What replaces the prefix the markup was cut with, or null for "leave every path alone".
    *
@@ -4473,11 +4492,14 @@ export function bcmsFields(
     const separator = pathPrefix.slice(-1);
     return (path: string): string => {
       if (!path.startsWith(pathPrefix) || !(own || placement.bind)) return path;
-      if (!own) return placement.bind + separator + path.slice(pathPrefix.length);
       const scalar = map.scalars?.[path];
-      if (scalar !== undefined) return id + "__overrides." + scalar;
       const row = /^([^[]+)\\[(\\d+)\\]\\.(.+)$/.exec(path);
       const table = row ? map.tables?.[row[1]] : undefined;
+      if (!own) {
+        return moved(scalar, "") ?? moved(table?.key, row ? "[" + row[2] + "]." + row[3] : "")
+          ?? placement.bind + separator + path.slice(pathPrefix.length);
+      }
+      if (scalar !== undefined) return id + "__overrides." + scalar;
       const column = row && table ? table.columns[row[3]] : undefined;
       return table && column !== undefined ? id + "__overrides." + table.key + "[" + row![2] + "]." + column : path;
     };
@@ -4487,7 +4509,9 @@ export function bcmsFields(
     // 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);
+    const rest = path.slice(pathPrefix.length);
+    const key = /^[^.[]+/.exec(rest)?.[0];
+    return (own ? undefined : moved(key, rest.slice(key?.length ?? 0))) ?? lane + rest;
   };
 }
 `;
@@ -4500,7 +4524,8 @@ var HISTORICAL = {
     4: "a5742f64dacb1b26ee6dd5e1469a54871487934c71bc8267df19e3a80e417595",
     5: "0472fe3ffdcfa49e719c7b9da9cb63b6eba637cc22783bb00c3c2cadd3d800da",
     6: "c907e7245578d947c6541b1ab2c5c6659ea7789a1519e895b4a4aed122c6f649",
-    7: "f22514ef48c50230985e605bea6cf9bf41756384a7dc80603e347baba9b65d93"
+    7: "f22514ef48c50230985e605bea6cf9bf41756384a7dc80603e347baba9b65d93",
+    8: "484e72852d2b496e016a1f2a2b1a77bb993f8a163b290781522d6114b6519bb9"
   },
   "src/lib/bcms-content.ts": {
     1: "ae72ae14d706943d481c880d70da5789b4816ba1ba319a10fbc63ded4d0b42f2",
@@ -4509,7 +4534,8 @@ var HISTORICAL = {
     4: "0146d027a727ecd3c9e3fc336fcf1299b59ddf75b04091c05703f3f983ec28af",
     5: "c8c93655320fa65664611ba84541f3fa7bfa292cc9a2fd655373440b99049fba",
     6: "63f1fa29e47e70c5193b81ee24addb238ba100247124d55bc17713102d587df5",
-    7: "ed92fb88de953d9951abbe6a1edae1d048f4050eaf6fb607ac08167f94d8bcc7"
+    7: "ed92fb88de953d9951abbe6a1edae1d048f4050eaf6fb607ac08167f94d8bcc7",
+    8: "1a6f669d76d42effe77f082436e9d21c0efa6fc499e919e3d116bc3a27a7f3d5"
   },
   "composables/bcms-content.ts": {
     1: "c272412532efed7db64b6cf313b2bed4291f9951430412289c8a588b7f565407",
@@ -4518,7 +4544,8 @@ var HISTORICAL = {
     4: "a5742f64dacb1b26ee6dd5e1469a54871487934c71bc8267df19e3a80e417595",
     5: "0472fe3ffdcfa49e719c7b9da9cb63b6eba637cc22783bb00c3c2cadd3d800da",
     6: "c907e7245578d947c6541b1ab2c5c6659ea7789a1519e895b4a4aed122c6f649",
-    7: "f22514ef48c50230985e605bea6cf9bf41756384a7dc80603e347baba9b65d93"
+    7: "f22514ef48c50230985e605bea6cf9bf41756384a7dc80603e347baba9b65d93",
+    8: "484e72852d2b496e016a1f2a2b1a77bb993f8a163b290781522d6114b6519bb9"
   }
 };
 var sha256 = (value) => createHash2("sha256").update(value, "utf8").digest("hex");
@@ -6407,6 +6434,114 @@ function readPlan(value) {
 // src/forms.ts
 import MagicString4 from "magic-string";
 var WIRABLE = ["html", "astro", "jsx"];
+var BY_NAME = ["astro"];
+var FORMS_HELPER_PATH = "src/bcms-forms.ts";
+var FORMS_HELPER_VERSION = 2;
+var FORMS_HELPER_HEADER = /^\/\/ @bettercms-ai\/convert forms-helper v(\d+)\r?\n/;
+var formsHelperVersion = (content) => {
+  const m = FORMS_HELPER_HEADER.exec(content);
+  return m ? Number(m[1]) : null;
+};
+var FORMS_HELPER_SOURCE = `// @bettercms-ai/convert forms-helper v${FORMS_HELPER_VERSION}
+// Written by @bettercms-ai/convert; a re-run rewrites it, so do not edit it.
+// Resolves a BetterCMS form by NAME at build, for the environment that is building this site: the id
+// from bcms-content.json (written into the tree before the build) and the endpoint from BCMS_API_URL.
+// The source names no host and no id, so every BetterCMS environment builds its own wiring.
+// A form it cannot resolve renders unwired (no action, no method, no id) with one warning line, and
+// the build goes on. Form NAMES are the contract between environments: rename a form on every one.
+import { existsSync, readFileSync } from "node:fs";
+
+type SnapshotForm = { id: string; name: string; projectId?: string | null; ignoredAt?: string | null };
+type Snapshot = { projectId: string | null; forms: SnapshotForm[] };
+type Wiring = { id: string; action: string };
+
+let snapshot: Snapshot | null | undefined;
+const resolved = new Map<string, Wiring | undefined>();
+
+const env = (key: string): string | undefined => process.env[key] || process.env[\`PUBLIC_\${key}\`] || undefined;
+
+const isForm = (value: unknown): value is SnapshotForm =>
+  typeof value === "object" &&
+  value !== null &&
+  typeof (value as { id?: unknown }).id === "string" &&
+  typeof (value as { name?: unknown }).name === "string";
+
+function readSnapshot(): Snapshot | null {
+  for (const file of ["bcms-content.json", "bcms-content/forms.json"]) {
+    if (!existsSync(file)) continue;
+    try {
+      const data: unknown = JSON.parse(readFileSync(file, "utf8"));
+      const record = (Array.isArray(data) ? { forms: data } : (data ?? {})) as { forms?: unknown; projectId?: unknown };
+      const forms: unknown[] = Array.isArray(record.forms) ? record.forms : [];
+      if (!forms.every(isForm)) throw new Error("a form entry has no id or name");
+      return { projectId: typeof record.projectId === "string" ? record.projectId : null, forms };
+    } catch (error) {
+      // Read once per build, so this is the one line however many forms the site has.
+      console.warn(\`[bcms-forms] FORMS_SNAPSHOT_UNREADABLE: \${file} could not be read (\${error instanceof Error ? error.message : String(error)}); every form renders unwired.\`);
+      return null;
+    }
+  }
+  return null;
+}
+
+function unwired(code: string, name: string, why: string): undefined {
+  console.warn(\`[bcms-forms] \${code}: form "\${name}" renders unwired; \${why}.\`);
+  return undefined;
+}
+
+function resolve(name: string): Wiring | undefined {
+  if (snapshot === undefined) snapshot = readSnapshot();
+  // No snapshot (a local dev build), or one it could not read: the form renders unwired, as before.
+  if (snapshot === null) return undefined;
+  const project = env("BCMS_PROJECT_ID") ?? snapshot.projectId;
+  // The forms the conversion brief names from: this project's own, ignored ones left out.
+  const own = snapshot.forms.filter((f) => !f.ignoredAt && (!project || f.projectId === project));
+  const hits = own.filter((f) => f.name === name);
+  const form = hits.length === 1 ? hits[0] : undefined;
+  if (!form && hits.length > 1) {
+    return unwired("BCMS_FORM_NAME_AMBIGUOUS", name, \`\${hits.length} forms in this project share that name; rename one in the Forms tab\`);
+  }
+  if (!form) {
+    return unwired(
+      "BCMS_FORM_NOT_FOUND",
+      name,
+      own.length === 0
+        ? "this project has no forms yet; the release of this build derives them"
+        : "no form in this project has that name; a name is shared by every environment, so rename the form on each one",
+    );
+  }
+  const api = env("BCMS_API_URL");
+  if (!api) return unwired("BCMS_FORM_API_URL_MISSING", name, "BCMS_API_URL is not set, so it has nowhere to post");
+  return { id: form.id, action: \`\${api.replace(/\\/$/, "")}/api/v1/forms/public/\${form.id}/submissions\` };
+}
+
+/** Resolved once per name, so a form's three attributes print one warning, not three. */
+function wiring(name: string): Wiring | undefined {
+  if (!resolved.has(name)) resolved.set(name, resolve(name));
+  return resolved.get(name);
+}
+
+export const bcmsFormId = (name: string): string | undefined => wiring(name)?.id;
+
+export const bcmsFormAction = (name: string): string | undefined => wiring(name)?.action;
+
+/** "post" only for a form that resolved: an unwired form keeps no method, like its action and id. */
+export const bcmsFormMethod = (name: string): "post" | undefined => (wiring(name) ? "post" : undefined);
+`;
+var idCall = (form) => `bcmsFormId(${JSON.stringify(form.name)})`;
+var actionCall = (form) => `bcmsFormAction(${JSON.stringify(form.name)})`;
+var methodCall = (form) => `bcmsFormMethod(${JSON.stringify(form.name)})`;
+function calledName(code, fn) {
+  const m = code === null ? null : new RegExp(`^${fn}\\s*\\(\\s*(["'\`])((?:\\\\.|(?!\\1)[^\\\\])*)\\1\\s*,?\\s*\\)$`).exec(code);
+  if (!m) return null;
+  const [, quote, raw] = m;
+  if (quote === "`" && raw.includes("${")) return null;
+  try {
+    return JSON.parse(`"${raw.replace(/\\(['`])/g, "$1").replace(/(?<!\\)"/g, '\\"')}"`);
+  } catch {
+    return null;
+  }
+}
 var CONTROLS = /* @__PURE__ */ new Set(["input", "select", "textarea"]);
 var FORM_SCRIPT = `<script>
 function bcmsPhone(cc,raw,trunk){var d=String(raw||'').trim();if(!d)return '';if(d.charAt(0)==='+'){var i=d.replace(/D/g,'');return i?'+'+i:'';}if(!cc)return d;var n=d.replace(/D/g,'');if(trunk&&n.charAt(0)==='0')n=n.slice(1);return n?'+'+cc+n:'';}
@@ -6468,6 +6603,10 @@ function* elementsIn(nodes) {
 var childElements = (node) => node.children.flatMap(
   (child) => child.type === "element" ? [child] : child.type === "expr" ? childElements(child) : []
 );
+function exprOf(c, name) {
+  const range = attrOf(c.el, name)?.expressionRange;
+  return range ? c.content.slice(range.start + 1, range.end - 1).trim() : null;
+}
 var LANDMARK_TAGS = /* @__PURE__ */ new Set(["footer", "header", "nav", "main", "aside", "dialog"]);
 function landmarkOf(chain) {
   for (let i = chain.length - 1; i >= 0; i--) {
@@ -6489,7 +6628,7 @@ function* formsIn(nodes, chain = []) {
   }
 }
 var isComponentTag = (dialect, tag) => dialect !== "html" && /^[A-Z]/.test(tag);
-function candidateOf(file, dialect, form, imported, landmark, content) {
+function candidateOf(file, dialect, form, imported, landmark, content, importAt) {
   const controls = /* @__PURE__ */ new Map();
   const wrapper = /* @__PURE__ */ new Map();
   const foreign = /* @__PURE__ */ new Set();
@@ -6530,7 +6669,7 @@ function candidateOf(file, dialect, form, imported, landmark, content) {
     content.slice(attr.expressionRange.start, attr.expressionRange.end).replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*|"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'|`(?:[^`\\$]|\\.|\$(?!\{))*`/g, "")
   );
   const dynamic = all.some((control) => !foreign.has(control) && computed(attrOf(control, "name")));
-  return { file, dialect, el: form, controls, wrapper, foreign, landmark, dynamic };
+  return { file, dialect, el: form, controls, wrapper, foreign, landmark, dynamic, content, importAt };
 }
 async function importedControls(source, parsed, dialect, project, cache) {
   const out = /* @__PURE__ */ new Map();
@@ -6563,11 +6702,20 @@ function wire(source, candidate, form) {
     else if (attr.valueRange) source.overwrite(attr.valueRange.start, attr.valueRange.end, escapeAttr(value));
     else source.overwrite(attr.range.start, attr.range.end, `${name}="${escapeAttr(value)}"`);
   };
-  set("action", form.submitUrl);
-  set("method", "post");
-  set("data-bcms-form", form.id);
+  const setExpr = (name, code) => {
+    const attr = attrOf(el, name);
+    if (!attr) inserts.push(`${name}={${code}}`);
+    else source.overwrite(attr.range.start, attr.range.end, `${name}={${code}}`);
+  };
+  const byName = BY_NAME.includes(dialect);
+  if (byName) setExpr("action", actionCall(form));
+  else set("action", form.submitUrl);
+  if (byName) setExpr("method", methodCall(form));
+  else set("method", "post");
+  if (byName) setExpr("data-bcms-form", idCall(form));
+  else set("data-bcms-form", form.id);
   if (form.successMessage) set("data-bcms-form-success", form.successMessage);
-  source.appendLeft(el.attrInsertAt, ` ${inserts.join(" ")}`);
+  if (inserts.length > 0) source.appendLeft(el.attrInsertAt, ` ${inserts.join(" ")}`);
   for (const inner of elementsIn(el.children)) {
     for (const attr of inner.attrs) {
       if (!DECLARED_BINDING_ATTR.test(attr.name)) continue;
@@ -6624,12 +6772,20 @@ async function wireForms(briefIn, sources, options_ = {}) {
     }
     const imported = dialect === "html" ? /* @__PURE__ */ new Map() : await importedControls(source, parsed, dialect, project, componentFiles);
     for (const { el, landmark } of formsIn(parsed.roots)) {
-      candidates.push(candidateOf(source.path, dialect, el, imported, landmark, source.content));
+      candidates.push(candidateOf(source.path, dialect, el, imported, landmark, source.content, parsed.importAt));
     }
   }
   const holds = (c, f) => f.fields.filter((field) => c.controls.has(field.key)).length;
-  const wiredTo = (c, f) => attrOf(c.el, "data-bcms-form")?.value === f.id;
-  const covers2 = (c, f) => c.dynamic && wiredTo(c, f) || f.fields.length > 0 && holds(c, f) === f.fields.length;
+  const byId = (c, f) => !attrOf(c.el, "data-bcms-form")?.expression && attrOf(c.el, "data-bcms-form")?.value === f.id;
+  const programAction = (c) => !!attrOf(c.el, "action")?.expression && calledName(exprOf(c, "action"), "bcmsFormAction") === null;
+  const wiredTo = (c, f) => BY_NAME.includes(c.dialect) ? calledName(exprOf(c, "data-bcms-form"), "bcmsFormId") === f.name || byId(c, f) && programAction(c) : byId(c, f);
+  const wiredName = (c) => BY_NAME.includes(c.dialect) ? calledName(exprOf(c, "data-bcms-form"), "bcmsFormId") : null;
+  const staticPost = (c) => {
+    const method = attrOf(c.el, "method");
+    return !!method && !method.expression && method.value.toLowerCase() === "post";
+  };
+  const claims = (c, f) => wiredTo(c, f) || byId(c, f);
+  const covers2 = (c, f) => c.dynamic && claims(c, f) || f.fields.length > 0 && holds(c, f) === f.fields.length;
   const samePath = (a, b) => a.replace(/\\/g, "/").replace(/^\.\//, "") === b.replace(/\\/g, "/").replace(/^\.\//, "");
   const options = new Map(forms.map((f) => [f.id, candidates.filter((c) => covers2(c, f))]));
   const pinned = /* @__PURE__ */ new Map();
@@ -6673,7 +6829,14 @@ async function wireForms(briefIn, sources, options_ = {}) {
   const wanted = /* @__PURE__ */ new Map();
   for (const list of options.values()) for (const c of list) wanted.set(c, (wanted.get(c) ?? 0) + 1);
   const matched = [];
+  const methodUpgrades = [];
+  const pendedByName = /* @__PURE__ */ new Set();
   const pending = [];
+  const existingHelper = sources.find((s) => samePath(s.path, FORMS_HELPER_PATH))?.content;
+  const helperVersion = existingHelper === void 0 ? null : formsHelperVersion(existingHelper);
+  const helperOk = existingHelper === void 0 || helperVersion !== null;
+  const helperStale = existingHelper !== void 0 && helperVersion !== null && helperVersion <= FORMS_HELPER_VERSION && existingHelper !== FORMS_HELPER_SOURCE;
+  let byNameOnSite = false;
   const onSite = [];
   let alreadyWired = 0;
   const pend2 = (f, reason, file, message) => void pending.push({ id: f.id, name: f.name, reason, ...file ? { file } : {}, ...message ? { message } : {} });
@@ -6712,12 +6875,25 @@ async function wireForms(briefIn, sources, options_ = {}) {
       continue;
     }
     const candidate = list[0];
+    const byName = BY_NAME.includes(candidate.dialect);
+    if (byName && forms.filter((f) => f.name === form.name).length > 1) {
+      pend2(form, "FORM_NAME_AMBIGUOUS", candidate.file, `more than one CMS form is named "${form.name}"; rename one in the Forms tab.`);
+      continue;
+    }
     if (wiredTo(candidate, form)) {
       alreadyWired++;
       onSite.push({ form, file: candidate.file });
+      if (byName) byNameOnSite = true;
+      if (wiredName(candidate) === form.name && staticPost(candidate) && helperOk) methodUpgrades.push({ form, candidate });
+      continue;
+    }
+    const other = wiredName(candidate);
+    if (other !== null) {
+      pendedByName.add(candidate);
+      pend2(form, "FORM_WIRED_TO_OTHER_NAME", candidate.file, `its <form> is wired by name to "${other}", and a wiring by name is never rewritten: form names are shared by every environment, so give this form the same name on each one.`);
       continue;
     }
-    if (attrOf(candidate.el, "action")?.expression) {
+    if (programAction(candidate)) {
       pend2(form, "ACTION_IS_EXPRESSION", candidate.file, "its action is an expression, so this run will not replace it.");
       continue;
     }
@@ -6729,18 +6905,46 @@ async function wireForms(briefIn, sources, options_ = {}) {
       pend2(form, "FIELD_UNMATCHED", candidate.file, `the control for ${misnamed.key} posts under an expression, so its name cannot be set to the CMS key.`);
       continue;
     }
+    if (byName && !helperOk) {
+      pend2(form, "HELPER_CONFLICT", FORMS_HELPER_PATH, `${FORMS_HELPER_PATH} exists and is not the file @bettercms-ai/convert writes, so nothing may import it. Move it and re-run.`);
+      continue;
+    }
     matched.push({ form, candidate });
     onSite.push({ form, file: candidate.file });
+    if (byName) byNameOnSite = true;
   }
   const contents = new Map(sources.map((s) => [s.path, s.content]));
   const byFile = /* @__PURE__ */ new Map();
-  for (const m of matched) byFile.set(m.candidate.file, [...byFile.get(m.candidate.file) ?? [], m]);
+  const editsOf = (path) => {
+    if (!byFile.has(path)) byFile.set(path, { wire: [], upgrade: [] });
+    return byFile.get(path);
+  };
+  for (const m of matched) editsOf(m.candidate.file).wire.push(m);
+  for (const m of methodUpgrades) editsOf(m.candidate.file).upgrade.push(m);
   const files = [];
-  for (const [path, list] of [...byFile].sort(([a], [b]) => a.localeCompare(b))) {
+  for (const [path, { wire: list, upgrade }] of [...byFile].sort(([a], [b]) => a.localeCompare(b))) {
     const content = contents.get(path);
     const source = new MagicString4(content);
     for (const { form, candidate } of list) wire(source, candidate, form);
-    if (!content.includes("form[data-bcms-form]")) {
+    for (const { form, candidate } of upgrade) {
+      const method = attrOf(candidate.el, "method");
+      source.overwrite(method.range.start, method.range.end, `method={${methodCall(form)}}`);
+    }
+    const first = (list[0] ?? upgrade[0]).candidate;
+    if (BY_NAME.includes(first.dialect) && first.importAt) {
+      const at = first.importAt;
+      const helper = relativeImport(path, FORMS_HELPER_PATH.replace(/\.ts$/, ""));
+      const names = !/\bbcmsFormId\b/.test(content) ? "bcmsFormAction, bcmsFormId, bcmsFormMethod" : !/\bbcmsFormMethod\b/.test(content) ? "bcmsFormMethod" : null;
+      if (names) {
+        const line = `import { ${names} } from "${helper}";`;
+        if (at.wrap) source.appendLeft(at.at, `${at.wrap.before}${line}${at.wrap.after}`);
+        else if (at.at === 0) source.appendLeft(0, `${line}
+`);
+        else source.appendLeft(at.at, `
+${line}`);
+      }
+    }
+    if (list.length > 0 && !content.includes("form[data-bcms-form]")) {
       const last = list.reduce((a, b) => b.candidate.el.end > a.candidate.el.end ? b : a);
       const indent = /[^\S\n]*$/.exec(content.slice(0, last.candidate.el.start))[0];
       source.appendRight(last.candidate.el.end, `
@@ -6748,6 +6952,10 @@ ${indent}${scriptFor(last.candidate.dialect)}`);
     }
     files.push({ path, operation: "modify", content: source.toString() });
   }
+  const helperAdded = existingHelper === void 0 && (matched.some((m) => BY_NAME.includes(m.candidate.dialect)) || methodUpgrades.length > 0);
+  if (helperAdded) files.push({ path: FORMS_HELPER_PATH, operation: "add", content: FORMS_HELPER_SOURCE });
+  const helperUpgraded = helperStale && byNameOnSite;
+  if (helperUpgraded) files.push({ path: FORMS_HELPER_PATH, operation: "modify", content: FORMS_HELPER_SOURCE });
   const notes = onSite.filter(({ form }) => form.status === "draft").map(({ form }) => `publish form ${form.name} in the Forms tab \u2014 a draft form rejects every submission with 403.`);
   for (const { form, candidate } of matched) {
     const tie = beat.get(candidate);
@@ -6763,6 +6971,13 @@ ${indent}${scriptFor(last.candidate.dialect)}`);
       );
     }
   }
+  for (const c of candidates) {
+    const name = wiredName(c);
+    if (name === null || pendedByName.has(c) || forms.some((f) => f.name === name)) continue;
+    notes.push(
+      `${c.file}: its <form> is wired by name to "${name}", which no form of this project has, so this environment's build renders it unwired; it was not rewritten \u2014 form names are shared by every environment, so give the form that name here too.`
+    );
+  }
   for (const { form, candidate } of matched) {
     const keys = form.fields.filter((field) => candidate.foreign.has(candidate.controls.get(field.key))).map((field) => field.key);
     if (keys.length > 0) {
@@ -6780,8 +6995,8 @@ ${indent}${scriptFor(last.candidate.dialect)}`);
       paths: { declared: 0, rewritten: 0, alreadyDeclared: 0, pending: [] },
       occurrences: { located: 0, rewritten: 0 },
       files: [],
-      helpers: [],
-      helperUpgraded: false,
+      helpers: helperAdded || helperUpgraded ? [FORMS_HELPER_PATH] : [],
+      helperUpgraded,
       dynamicBindings: [],
       forms: assertForms(forms.length, {
         wired: matched.length,
@@ -8114,6 +8329,7 @@ function componentFile(dialect, path, fromFile, content, parsed, resolved, pathP
     provided: [
       "blockId",
       "bind",
+      "bindPaths",
       "overrides",
       "page",
       fieldName,
@@ -8128,8 +8344,8 @@ function componentFile(dialect, path, fromFile, content, parsed, resolved, pathP
   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 ? "" : flat3 ? `const ${snapshot} = bcmsSectionPaths(page, bind, overrides, ${JSON.stringify(pathPrefix)}, ${JSON.stringify(pathMap)});` : `const ${snapshot} = { ${key}: bcmsSection(page, bind, overrides) };`;
-  const field = bound > 0 ? `const ${fieldName} = ${fieldsName}({ blockId, bind, overrides }, ${JSON.stringify(pathPrefix)}${flat3 ? `, ${JSON.stringify(pathMap)}` : ""});` : "";
+  const copy = !snapshot ? "" : flat3 ? `const ${snapshot} = bcmsSectionPaths(page, bind, overrides, ${JSON.stringify(pathPrefix)}, ${JSON.stringify(pathMap)}, bindPaths);` : `const ${snapshot} = { ${key}: bcmsSection(page, bind, overrides, bindPaths) };`;
+  const field = bound > 0 ? `const ${fieldName} = ${fieldsName}({ blockId, bind, bindPaths, overrides }, ${JSON.stringify(pathPrefix)}${flat3 ? `, ${JSON.stringify(pathMap)}` : ""});` : "";
   const declared = [copy, field].filter(Boolean).join("\n");
   const styles = dialect === "astro" ? carriedStyles(content) : "";
   if (dialect === "astro") {
@@ -8142,12 +8358,14 @@ interface Props {
   blockId?: string;
   /** The page field group this placement renders \u2014 Phase A keeps the copy where P2 put it. */
   bind?: string;
+  /** A locale copy's own field path for each prop, when its keys differ from this component's. */
+  bindPaths?: Record<string, 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;
+const { blockId, bind, bindPaths, overrides, page } = Astro.props;
 ${carriedDeclarations}${declared}
 ---
 ${markup}
@@ -8159,7 +8377,7 @@ ${styles}
 ${[...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) {
+export default function ${resolved.name}({ blockId, bind, bindPaths, overrides, page }: BcmsSectionProps) {
   ${declared.split("\n").join("\n  ")}
   return (
     ${markup}
@@ -8521,6 +8739,7 @@ const isRecord = (v: unknown): v is Record<string, unknown> =>
 export interface BcmsSectionProps {
   blockId?: string;
   bind?: string;
+  bindPaths?: Record<string, string>;
   overrides?: Record<string, unknown>;
   page?: unknown;
 }
@@ -8530,6 +8749,8 @@ export interface BcmsPlacement {
   blockId?: string;
   slug: string;
   bind?: string;
+  /** A locale copy's own field path for each prop, when its keys differ from the component's. */
+  bindPaths?: Record<string, string>;
   overrides?: Record<string, unknown>;
 }
 
@@ -8590,6 +8811,7 @@ export function pageSections(pageSlug: string): BcmsPlacement[] {
       blockId: typeof block.id === "string" ? block.id : undefined,
       slug,
       bind: typeof props.bind === "string" ? props.bind : undefined,
+      bindPaths: isRecord(props.bindPaths) ? (props.bindPaths as Record<string, string>) : undefined,
       overrides: isRecord(props.overrides) ? props.overrides : undefined,
     });
   }
@@ -8655,6 +8877,7 @@ const snapshot = pageSnapshot(page);
     <Component
       blockId={placement.blockId}
       bind={placement.bind}
+      bindPaths={placement.bindPaths}
       overrides={placement.overrides}
       page={snapshot}
     />
@@ -8677,6 +8900,7 @@ export default function Sections({ page }: { page: string }) {
             key={placement.blockId ?? \`\${placement.slug}-\${i}\`}
             blockId={placement.blockId}
             bind={placement.bind}
+            bindPaths={placement.bindPaths}
             overrides={placement.overrides}
             page={snapshot}
           />
@@ -9952,7 +10176,7 @@ function styleEdits(before, after) {
 // package.json
 var package_default = {
   name: "@bettercms-ai/convert",
-  version: "0.18.2",
+  version: "0.20.0",
   type: "module",
   description: "Deterministic codemod that turns an imported site's text-matched bindings into declared ones \u2014 parser offsets in, one magic-string pass out, plus a receipt of everything it could not do.",
   bin: {
@@ -9985,7 +10209,7 @@ var package_default = {
   dependencies: {
     "@astrojs/compiler": "^2.13.1",
     "@babel/parser": "^7.29.2",
-    "@bettercms-ai/types": "^1.12.0",
+    "@bettercms-ai/types": "^1.25.0",
     "@vue/compiler-sfc": "^3.5.0",
     "magic-string": "^0.30.21",
     parse5: "^7.3.0",