@bettercms-ai/convert 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,237 @@
 # @bettercms-ai/convert
 
+## 0.4.0
+
+The workspace lockfile records this version: a lock still naming 0.3.0 makes a frozen install
+reject the checkout, which is what broke the migrator image on #616.
+
+### Minor Changes
+
+- Componentize Phase B: an extracted section declares the lane its copy actually lives in.
+
+  An element carries exactly ONE `data-bcms-field`, and which address it names is now decided
+  when the component RENDERS rather than when the codemod ran. A placement bound to a page
+  field group declares the page path, as before. A placement that owns its copy — `overrides`
+  and no `bind` — declares the block lane, `<blockId>__overrides.<propKey>`, which is where
+  the editor commits an instance's own value.
+
+  🔴 The extracted files are BYTE-IDENTICAL in both copy models. That is the point: moving a
+  page's copy onto its instances is a data change on the server, not a second cut of the
+  repository, and one component renders a Phase A placement on one page and a Phase B
+  instance on the next. Each of P2's bindings is wrapped in the placement's own chooser,
+  `bcmsFields({ blockId, bind, overrides }, "<prefix>")`, so the page path is still verbatim
+  in the file. The prefix that turns a page path into a prop key comes from the plan's
+  `fields[].key`/`path` map, not from the group key.
+
+  The root's `data-bcms-block` is now REPLACED when the repository already wrote one, instead
+  of a second being appended beside it — two instances claiming one element.
+
+- `--copy bind|instance` (default `bind`), and the `COPY_MODE_MISMATCH` refusal.
+
+  An assertion rather than a switch, since the output does not depend on it. It catches the
+  one order-of-operations mistake that would otherwise be silent: `--copy instance` run in the
+  repository before the server has moved the copy leaves a tree that looks converted and
+  renders every section out of page fields the dashboard is about to hide. A plan whose
+  placements all still carry `bind` refuses every section by name, with nothing written. The
+  receipt carries `copy`, the same word the server's receipt uses.
+
+  The registry's shipped fallback now omits `bind` for an instance-owned placement, for the
+  same reason: binding it would make a fresh clone render a section out of hidden fields.
+
+- The extracted-component format is VERSIONED (`section v2`), and older ones are upgraded.
+
+  🔴 Without this Phase B never reaches a repository that already ran 0.3. Completion is
+  decided on the marker and a v1 component carries one, so every already-componentized page
+  was reported done, its components kept their page-path bindings, and `--copy instance`
+  there placed five sections while moving no address at all. Each v1 component is now brought
+  to the current format in place — every `data-bcms-field` wrapped in the chooser, the chooser
+  declared and imported, the marker restamped — once, before any page is called done. A
+  component the plan says nothing about is left alone; one that cannot be upgraded is
+  `SECTION_UNMIGRATABLE` rather than a silent skip.
+
+- An already-componentized page's shipped placements are restated from the current plan.
+
+  A bind run followed by an instance run kept `bind` on every placement in the registry's
+  fallback table, so a fresh clone rendered sections out of page fields the dashboard had
+  already hidden — and the reverse transition never put `bind` back. The `bind` is now
+  restated on every run, in the order the registry already holds; nothing is extracted, and
+  the registry is rewritten only when those bytes actually change. Repeated placements of one
+  component — two groups sharing a `shapeHash`, which is what `shapeHash` is FOR — are matched
+  POSITIONALLY, registry order against plan order per slug: keying them by slug collapsed them,
+  so a page with one group still bound and another moved wrote both from the second.
+
+- The v1 → v2 upgrade reuses names the file already has, or refuses.
+
+  These files have been sitting in somebody's repository. Blindly adding
+  `import { bcmsFields }` and `const bcmsField = …` to a module that already declares either
+  produced a duplicate binding — a file that does not compile — reported as a successful
+  upgrade. An import of the helper's own `bcmsFields` is reused under whatever local name it
+  has; a `bcmsField` the file demonstrably builds from our helper is left alone and only its
+  bindings are wrapped; anything else is `SECTION_UNMIGRATABLE`.
+
+  🔴 A NAME IS NOT A PROVENANCE. Reusing anything *called* `bcmsFields` trusted an import from
+  any module at all — `import { bcmsFields } from "./their-utils"` is a different function with
+  the same name — and any coexisting `bcmsField` vouched for itself. The specifier must RESOLVE
+  to the helper module this package writes (through the project's own aliases), and `bcmsField`
+  must be declared as `const bcmsField = <that exact local>(…)`, read structurally off the
+  module's own top-level AST.
+
+- Which group an upgraded component was cut from is read off the FILE, not off the plan.
+
+  One component serves every page whose group has its shape, and its markup carries the paths of
+  the one page it was cut FROM. Taking the plan's first placement for that slug gave a component
+  reading `hero.*` the prefix `landingHero.` as soon as that placement came first: every wrapped
+  address matched nothing, the block lane never fired, and the file was stamped current for good.
+  The candidate prefixes are matched against the addresses the file actually declares, and a slug
+  whose placements cannot be told apart that way is `SECTION_UNMIGRATABLE`. Server-pending
+  placements count as prefix EVIDENCE — which group the bytes were cut from is a fact about the
+  past, and a refused placement may be the only thing that explains them — while still being
+  excluded from placement and copy-mode decisions.
+
+- Fresh extraction allocates collision-free names for the chooser and its import.
+
+  The markup being cut is the PAGE's, and a page is free to have declared `bcmsField` itself.
+  Declaring ours unconditionally — and listing the name as `provided`, so `carryFor` neither
+  carried the page's declaration nor reported it free — silently rebound every use of theirs
+  inside the extracted section to our chooser. Both names now go through the same allocator as
+  every other identifier this codemod introduces, reserved against the module's bindings AND
+  against every identifier-shaped token in the bytes being lifted: in a TSX page that declaration
+  lives inside the component function, where a module-level check cannot see it, so the capture
+  happened anyway. ALL of the names, not the two base ones — reserving only `bcmsField` sent the
+  allocator to `bcmsField_1`, which a section referencing both also uses, and the capture simply
+  moved one suffix along.
+
+- The prop map is checked before this repository is consulted at all, AND against the
+  addresses it has to convert.
+
+  Checking it where the markup is cut let an ALREADY-componentized page bypass it: a later plan
+  spelling `{ key: "title", path: "hero.heading" }` was reported complete while the component it
+  names went on addressing `overrides.heading`, a key the instance does not hold. The map is a
+  property of the plan, so it is now answered from the plan, before completion is even asked.
+
+  🔴 AND A MAP CAN BE INTERNALLY CONSISTENT AND STILL WRONG ABOUT THE SECTION.
+  `{ groupKey: "hero", key: "title", path: "other.title" }` derives one clean prefix, `other.`,
+  which matches nothing the markup declares — so every element quietly stayed on the page lane
+  while the run reported the section done. The derived prefix is now verified against every
+  address the section actually declares — and a field address this cannot read statically
+  (`{computedPath}`, `{prefix + ".title"}`) counts as one it cannot convert, because contributing
+  nothing to the check is how such an element stayed on the page lane at render time. A
+  repeater's template literal is readable and is not affected.
+
+- Migration refusals are about ONE component, and a `.tsx` chooser is found where it lives.
+
+  Keyed by slug alone, an unmigratable `Hero.astro` marked the perfectly good `Hero.tsx`
+  unmigratable in a mixed repository — a page refused for a fact about a file its route does not
+  render. And a `.tsx` component declares its chooser INSIDE the function, which is where this
+  package puts it: a program-level binding check saw nothing there and inserted a second
+  `const bcmsField` into the same block. Both scopes are read; the refusal is keyed by dialect
+  and slug.
+
+  Reading a registry back also resolves its extensionless imports to a file its OWN dialect can
+  render. Two dialects share a component name whenever they share a slug, and a general resolver
+  — whose extension order is this package's, not the project's — bound the `.tsx` registry's
+  `hero` to the astro file, after which everything was about the wrong component.
+
+- `readRegistry` validates each `SHIPPED` row instead of trusting the array.
+
+  `[null]` is valid JSON, and the first thing to read it back dereferenced `placement.slug` and
+  threw a `TypeError` out of a pure function that names nothing. A row must be an object with a
+  string `slug` and, when present, string `bind`/`blockId`; anything else is `REGISTRY_UNREADABLE`,
+  which is what every other unreadable row in that file already was — as is a `REGISTRY` naming
+  no components (this module is only emitted when there is at least one, so a table with no rows
+  is one whose rows were lost) and a `SHIPPED` slug the `REGISTRY` does not name. An EMPTY
+  `SHIPPED` is still read: a run whose only page was `SECTION_NOT_CONTIGUOUS` writes the
+  components and no order at all, so refusing that would strand the repository. A single page
+  whose placement list is EMPTY is refused, though — `every` is vacuously true of it, and the
+  fallback exists precisely so a build with no CMS blocks renders the bands the repository ships.
+
+- Two more edges: a root carrying SEVERAL `data-bcms-block` attributes keeps exactly one (only
+  the first was being rewritten, so the extracted element still came out with two), and a v1
+  component with no `data-bcms-field` at all is upgraded on its marker alone rather than refused
+  for an ambiguity it cannot have — every candidate prefix matched it vacuously.
+
+### Patch Changes
+
+- No synthesized group fallback: an extracted component reads `bcmsSection(page, bind, overrides)`.
+
+  🔴 `bind ?? "<groupKey>"` belonged to Phase A, where every placement was bound and the default
+  could only restate what the placement already said. Under Phase B a placement that OWNS its
+  copy carries no bind on purpose — and the fallback put the page's field group straight back
+  underneath it, so a key the instance had not been given rendered the page's stale copy out of
+  fields the dashboard has already hidden. A placement that names no group has none, and every
+  `bcms(...)` then renders what the template shipped with. The v1 → v2 upgrade rewrites the old
+  form away rather than stamping it as current — through the module's own AST, by offset and
+  through the file's OWN local name for the export, because an exact-text rewrite missed a call a
+  formatter had reflowed and a name-matched one missed an aliased
+  `import { bcmsSection as sectionCopy }`; the marker then said the question had been settled. A
+  module with no readable program is refused, and so is one where nothing was rewritten while a
+  `??` fallback sits in a call this cannot identify as the helper's.
+
+- Only provably safe field expressions count as an address.
+
+  Starting with a quote is not a proof: `{"hero.title".replace("hero", "footer")}` names
+  `footer.title` at render time, and reading its first characters as the address accepted a
+  section whose element then quietly stayed on the page lane — the failure the check exists to
+  catch, reached through the check itself. Two shapes are provable: a string literal and NOTHING
+  else, and a template literal whose every interpolation is an INDEX (`[${i}]`, what a repeater
+  writes, which cannot change the prefix). Everything else — `{computedPath}`, `{"a" + x}`,
+  `` {`${prefix}.title`} `` — is opaque, and opaque is `PROP_MAP_INCONSISTENT`.
+
+- `COPY_MODE_MISMATCH` ignores sections the SERVER already refused.
+
+  A `copy: "instance"` section carrying `pending` is not a placement this run would make, but it
+  counted as evidence that the plan had moved its copy — so `--copy instance` passed the gate on
+  a plan whose only instance-owned section was server-pending, and the run wrote the BIND
+  conversion for the sections it could act on. Which is the exact tree the flag exists to stop.
+
+- A bound address is RE-BASED onto its own placement's group.
+
+  The markup is cut from ONE page and carries that page's paths, and the whole point of
+  `shapeHash` is that a second page renders the same component bound to a group of its own.
+  Handing the embedded path through unchanged declared `hero.title` on a page whose field is
+  `landingHero.title` — an address that page does not have, so the editor wrote into nothing
+  and the meter counted a binding that was never there.
+
+- `INLINE_NEEDS_INSTANCE`: a page that cannot be looped cannot own its copy.
+
+  The in-place call site — `<Hero bind="hero" page={pageSnapshot("home")} />` — is written by
+  the codemod from the plan and carries no `blockId` and no `overrides`; it never consults the
+  CMS's blocks at all, which is exactly what makes the inline form componentisation *without*
+  the page builder. Emitting it for a placement whose copy has MOVED rendered the page's field
+  group and declared the page lane for an address that no longer holds anything. The component
+  is still written; the page is left as its author wrote it.
+
+- `HELPER_CONFLICT` and `COPY_MODE_MISMATCH` now return an EMPTY file list.
+
+  On an already-componentized repository the registry read-back seeds the component table, so
+  the emit fired even though every section was pending: the helper was upgraded, the sections
+  library rebuilt and the registry rewritten for a run the operator was told did nothing. With
+  a hand-edited helper it was worse — the v1 → v2 upgrade rewrote components to
+  `import { bcmsFields }` from a module that does not export it. A refusal that modifies the
+  tree is not a refusal, so both return before reading or emitting any generated artefact.
+
+- Two new refusals where the codemod used to guess.
+
+  `PROP_MAP_INCONSISTENT`: a plan whose `fields[].path` is not one common prefix plus its
+  `key` — `{ path: "hero.heading", key: "title" }` — fell back to `<groupKey>.`, so the block
+  address became `overrides.heading` for a prop the instance holds as `title`, and every edit
+  went to a key nothing reads. `DUPLICATE_FIELD_BINDING`: an element already carrying two
+  `data-bcms-field` had both rewritten, leaving the extracted element still violating the
+  one-attribute invariant.
+
+- Helper v4: `bcmsSection` merges OVERRIDES-FIRST, per key.
+
+  `overrides[key] ?? group[key]` rather than "overrides, or else the group". The case that
+  matters is the one in between — a section whose copy is half moved — where a key the
+  instance does not hold has to keep rendering the page's value rather than nothing. `??`,
+  never `||`: an empty string is a value an editor typed. A table prop stored in the shape
+  the dashboard edits (`{ rows: [...] }`) is unwrapped to its list, so `bcmsRows` sees an
+  array instead of falling back to the rows the template shipped with.
+
+  New export `bcmsFields`, which is what an extracted section's bindings read through. An
+  existing v1–v3 helper is upgraded in place as usual; one this package did not write is
+  still `HELPER_CONFLICT`.
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -112,7 +112,14 @@ query cannot reach a chrome marker. A value that lives in an ATTRIBUTE (a promot
 `href`) has no field attribute of its own and rides `data-bcms-props="<address>|<kind>|<attr>;…"` —
 where `<address>` carries the same `layout:` prefix when it is chrome. A section root additionally
 carries `data-bcms-block="<blockId>"`, which is what the editor hit-tests for section chrome and
-reorder.
+reorder — and inside an extracted section that root's own placement decides which lane its elements
+address: the page path while the copy is the page's, `data-bcms-field="<blockId>__overrides.<key>"`
+once the copy is the instance's. The page-lane address is re-based onto **that placement's** group:
+the markup was cut from one page and carries its paths, and a second page renders the same
+component bound to a group of its own, where `hero.title` is a field that does not exist.
+**One `data-bcms-field` per element, always.** Two would leave the publisher and the editor reading
+different attributes off one node, and which of them won would depend on the dialect — JSX takes
+the last, Astro the first.
 
 ## As a library
 
@@ -173,8 +180,10 @@ left alone. A repeater on a dynamic route passes the same parameter to `bcmsRows
 ## Componentize
 
 The second mode. P2 above makes a page's copy editable in place; `--componentize` makes its
-SECTIONS movable — each band becomes a component the CMS can reorder, duplicate and swap, while its
-copy stays exactly where P2 put it.
+SECTIONS movable — each band becomes a component the CMS can reorder, duplicate and swap. Where the
+copy lives is a separate question, and the plan answers it: **Phase A** leaves it in the page's
+field groups (`props.bind`), **Phase B** moves it onto the instance (`props.overrides`). The same
+extracted files serve both.
 
 The division of labour is the one that already works by hand: **the CMS owns STRUCTURE, the repo
 owns RENDERING.** The server decides which field groups are sections (`get_componentize_plan` →
@@ -196,20 +205,45 @@ modify src/pages/index.astro
 modify bcms-content/home.json
 add    bcms-content/components.json
 
-5 sections extracted (0 registered, 0 inline-only, 0 already extracted, 0 pending)
+5 sections extracted (0 registered, 0 inline-only, 0 already extracted, 0 pending), copy: bind
 ```
 
 `--plan <file>` is required and is only read in this mode. `--dry-run`, `--receipt`, `--strict` and
 `--overwrite-helper` mean what they mean above; `--strict` exits 2 on any pending SECTION.
 
+`--copy bind|instance` (default `bind`) says which copy model the plan is expected to describe. It
+is an **assertion, not a switch** — the extracted files are byte-identical either way — and it
+exists to catch one order-of-operations mistake that would otherwise be silent: running
+`--copy instance` in the repository BEFORE the server has moved the copy leaves a tree that looks
+converted and renders every section out of page fields the dashboard is about to hide. A plan whose
+placements all still carry `bind` says so, and every section is refused `COPY_MODE_MISMATCH` with
+nothing written. The receipt carries the mode as `copy`, the same word the server's receipt uses.
+
 ### What is written
 
 - **`src/components/bcms/<Name>.<astro|tsx>`** — the section root's markup **verbatim**, P2's
-  `data-bcms-field` and `bcms(...)` reads included, plus `data-bcms-block={blockId}` on the root
-  (the editor hit-tests that for section chrome and reorder). Its copy comes from a new
-  `bcmsSection(page, bind, overrides)` in the committed helper: `overrides ?? pageGroup(bind) ??`
-  the fallbacks the template already carries. One component serves every page whose group has the
-  same shape, which is what the plan's `shapeHash` is for.
+  `bcms(...)` reads and its page paths included, plus `data-bcms-block={blockId}` on the root (the
+  editor hit-tests that for section chrome and reorder; a root that already carried one has it
+  REPLACED — and any further ones removed — never joined). Its copy comes from `bcmsSection(page, bind, overrides)` in the
+  committed helper — `overrides[key] ?? pageGroup(bind)[key] ??` the fallbacks the template already
+  carries. **The placement's own `bind`, with no synthesized default:** `bind ?? "<groupKey>"`
+  belonged to Phase A, where every placement was bound and the default could only restate what the
+  placement already said; under Phase B it put the page's field group back underneath an instance
+  that owns its copy, so a key the instance had not been given rendered stale page copy out of
+  fields the dashboard has already hidden. A placement that names no group has none, and every
+  `bcms(...)` renders what the template shipped with — and each of P2's bindings is wrapped in the placement's own chooser,
+  `bcmsFields({ blockId, bind, overrides }, "<prefix>")`, so the page path is still verbatim in the
+  file and the ADDRESS is decided when the component renders. Both names it introduces are
+  allocated (`bcmsField_1`, and so on) against the page's own top-level bindings **and against
+  every identifier-shaped token in the bytes being lifted** — all of them, since a section using
+  `bcmsField` *and* `bcmsField_1` would otherwise just move the capture one suffix along — because
+  a page that declared `bcmsField` would
+  otherwise have every use of theirs inside the extracted section silently rebound to our chooser
+  — and in a TSX page that declaration lives inside the component function, where a module-level
+  check cannot see it. Reserving the name puts the reference back on the honest path, which is
+  `SECTION_FREE_IDENTIFIERS` naming the identifier that could not travel. One component serves every page whose group has the same shape,
+  which is what the plan's `shapeHash` is for — and one component serves both copy models, which is
+  what makes moving a page's copy a data change rather than another cut.
 - **`src/lib/bcms-sections.ts`** — `pageSections(pageSlug)` over the committed snapshots'
   `blocks` plus `bcms-content/components.json`, returning `[{ blockId, slug, bind, overrides }]`.
   An instance naming a component this repo does not have is **skipped, never a hole**.
@@ -219,7 +253,10 @@ add    bcms-content/components.json
   look like, so rendering nothing there would blank the site on the first build after the codemod
   ran, with nothing in the diff to explain it. The fallback is decided on the **raw** block list:
   a page whose blocks all name components this repo does not have has still been *arranged*, and
-  putting the shipped bands back would undo an editor's work on the next build.
+  putting the shipped bands back would undo an editor's work on the next build. A shipped placement
+  carries `bind` only while the plan says its copy is the page's: an instance-owned one has none,
+  because binding it there would make a fresh clone render a section out of fields the dashboard
+  has already hidden.
 - **Nothing at all, for a section the repository has ALREADY componentised.** A page that renders
   `<Hero />` from a file it imports has made this cut itself: the existing file is REGISTERED under
   the section's slug — the registry imports it where it lives, **in the shape its module actually
@@ -284,11 +321,16 @@ import travels as `import * as X`, not as a named one.
 | `SECTION_FREE_IDENTIFIERS` | the markup uses a name the component file cannot be given. The identifier is named in the message. |
 | `COMPONENT_CONFLICT` | a file already sits at `src/components/bcms/<Name>` and this package did not write it. Decided on our marker, never on the path — that is a name a person may reasonably have chosen first. |
 | `REGISTRY_CONFLICT` | the same, for `Sections.astro`/`Sections.tsx` or `src/lib/bcms-sections.ts`. Both are rebuilt whole on every run, so an unmarked file there would be destroyed. `--overwrite-helper` proceeds. |
-| `REGISTRY_UNREADABLE` | the registry IS ours and its `REGISTRY`/`SHIPPED` tables cannot be read back — a component it names is GONE from the tree, a row is not a property this can read, or the tables are missing. Every property is parsed structurally and all of them must convert; a partial read is what silently drops a page's bands. It is rebuilt whole every run, so re-emitting it from what this run happened to see would blank those pages. No flag overrides this one: deleting the file is a decision only a person can take. |
+| `REGISTRY_UNREADABLE` | the registry IS ours and its `REGISTRY`/`SHIPPED` tables cannot be read back — a `REGISTRY` naming no components at all (this module is only emitted when there is at least one, so a table with no rows is one whose rows were lost), a `SHIPPED` row that is not an object with a string `slug` (and string `bind`/`blockId` when present), a page whose placement list is EMPTY (a row is only written for a page that has some, and the fallback rendering that page blank is the worst thing this could accept), or a `SHIPPED` slug the `REGISTRY` does not name. `[null]` is valid JSON and threw a `TypeError` out of a pure function the first time anything dereferenced it. An EMPTY `SHIPPED` is read, deliberately: a run whose only page was `SECTION_NOT_CONTIGUOUS` writes the components and no order at all, so refusing that would strand the repository — a component it names is GONE from the tree, a row is not a property this can read, or the tables are missing. Every property is parsed structurally and all of them must convert; a partial read is what silently drops a page's bands. It is rebuilt whole every run, so re-emitting it from what this run happened to see would blank those pages. No flag overrides this one: deleting the file is a decision only a person can take. |
 | `ROUTE_FILE_AMBIGUOUS` | two files serve one route. |
 | `DIALECT_UNSUPPORTED` | the page is svelte, vue or html. Nothing is written for it. |
-| `HELPER_CONFLICT` | `src/bcms-content.ts` is a module this package did not write. `--overwrite-helper` proceeds. |
+| `HELPER_CONFLICT` | `src/bcms-content.ts` is a module this package did not write. Refused **for the whole run, with an empty file list**: `bcmsSection` and `bcmsFields` are what every extracted *and* every upgraded component reads through, so pending it per page while the rest of the run proceeded rewrote v1 components to import an export the helper does not provide. `--overwrite-helper` proceeds. |
 | `SNAPSHOT_INVALID` | `bcms-content/<page>.json` is not JSON this can add `blocks` to. Refused before a byte is written for that route. |
+| `COPY_MODE_MISMATCH` | `--copy instance` was asked of a plan whose placements are all still bound to page field groups. Refused before this repository is even opened — **the run returns an empty file list**, because a refusal that upgrades the helper and rewrites the registry is not a refusal. The message says to run `componentize_sections { copy: "instance" }` on the server first. The reverse pairing is NOT a refusal: `--copy bind` over an instance plan still produces a tree that renders, so refusing it would only stop a run that works. |
+| `PROP_MAP_INCONSISTENT` | the plan's `fields[].path` is not `<one common prefix> + fields[].key` — `{ path: "hero.heading", key: "title" }`, or two fields that disagree about the prefix. A page path cannot be turned into a prop key losslessly, so the block-lane address would name a key the instance does not hold; falling back to `<groupKey>.` sent every edit to something nothing reads. Checked **before this repository is consulted at all**, so an already-componentized page is held to it too — doing it where the markup is cut reported such a page complete while its component went on addressing the wrong key. And checked again against the addresses it has to CONVERT: `{ groupKey: "hero", key: "title", path: "other.title" }` is internally consistent and wrong about the section, whose markup declares `hero.title` — a prefix that converts none of what the section actually declares would leave every element on the page lane whatever the placement said. A field address this cannot read statically counts as one it cannot convert, and is named in the message. Only two shapes are provable — a string literal and NOTHING else, and a template literal whose every interpolation is a LONE IDENTIFIER used as an index (`[${i}]`, what a repeater writes, which cannot change the prefix; `[${getKey()}]` names whatever that returns and is not). `{computedPath}`, `{"a" + x}` and `{"hero.title".replace("hero","footer")}` are all opaque: starting with a quote is not a proof, since that last one names `footer.title` at render time. A field carrying only one of the two says nothing about the mapping and is skipped, not refused: a Phase A plan spells no `key` at all. |
+| `DUPLICATE_FIELD_BINDING` | one element in the section carries more than one `data-bcms-field`. There is no single address to rewrite, and rewriting both leaves the extracted element still violating the one-attribute invariant. |
+| `INLINE_NEEDS_INSTANCE` | the page cannot be looped and the placement's copy has MOVED. The in-place call site the codemod writes — `<Hero bind="hero" page={pageSnapshot("home")} />` — comes from the plan and carries no `blockId` and no `overrides`: it never consults the CMS's blocks at all, which is what makes the inline form componentisation *without* the page builder. Emitting it would render the page's field group (the copy the dashboard is about to hide) and declare the page lane for an address that no longer holds anything. The component is still written; the page is left as its author wrote it. |
+| `SECTION_UNMIGRATABLE` | a component an OLDER version of this package wrote cannot be brought to the current format: it no longer parses, it no longer declares its placement, its element carries two field attributes, **the prefix its markup was cut with cannot be recovered** (see below), or it already binds `bcmsField`/`bcmsFields` to something this package did not write — adding a second declaration is a file that does not compile, reported as a successful upgrade. A name is not a provenance: an import is reused only when its specifier RESOLVES to the helper module this package writes, and a `bcmsField` only when it is declared as `const bcmsField = <that exact local>(…)` — read structurally, in the module scope **and** in the component function's own body, which is where a `.tsx` component declares it. It is left exactly as it is, and the section is reported rather than counted `alreadyExtracted` on a format it is not on. |
 | `NOT_IN_SOURCE` | no file we were given renders the group's fields, or the route names no page file. |
 
 A plan spanning TWO frameworks gets two of everything that is dialect-shaped: its own components,
@@ -302,6 +344,41 @@ Completion is decided per ROUTE, from that page's own bytes — it imports our r
 somewhere carries our marker", which is true of every group that has ever been extracted and left a
 brand-new page untouched.
 
+**The marker carries a FORMAT VERSION, and anything older is upgraded before it is called done.**
+A 0.3 component (`section v1`: page-path bindings, no render-time lane) carries a marker too, so
+reading the marker alone reported every already-componentized page finished and left its components
+on the page lane forever — `--copy instance` there placed five sections and moved no address at
+all. Each older component is instead brought to the current format in place: every
+`data-bcms-field` wrapped in the chooser, the chooser declared and imported, the marker restamped.
+The Phase A `bind ?? "<group>"` fallback is rewritten away in the same pass — through the module's own AST, by offset and through the file's OWN local name for the helper's export, so neither a call a formatter has reflowed nor one made through an aliased import is missed. A module with no readable program is refused, and so is one where nothing was rewritten while a `??` fallback sits in a call this cannot identify as the helper's. An upgrade never leaves that behaviour under a current marker. It happens once; the next run sees the current version and writes nothing. A component that binds nothing needs no prefix and cannot be ambiguous about one — the marker is its whole upgrade. A component the plan
+says nothing about is left alone — nothing asked about it, and a v1 file is still a correct Phase A
+component. One that cannot be upgraded is `SECTION_UNMIGRATABLE`, never silently skipped — and that refusal is about ONE component, keyed
+by dialect as well as slug, so an unmigratable `Hero.astro` says nothing about the `Hero.tsx`
+beside it. (Each registry also resolves its own extensionless imports to a file its dialect can
+render, which is what makes two same-named components in one directory readable at all.)
+
+**Which group an upgraded component was cut from is read off the FILE, not off the plan.** One
+component serves every page whose group has its shape, and its markup carries the paths of the one
+page it was cut from; taking the plan's first placement for that slug gave a component reading
+`hero.*` the prefix `landingHero.` as soon as that placement came first, so every wrapped address
+matched nothing, the block lane never fired, and the file was stamped current for good. The
+candidate prefixes — one per placement of the slug, **server-pending ones included**, because which
+group the bytes were cut from is a fact about the past that a refused placement may be the only
+thing to explain — are matched against the addresses the file actually declares (a repeater's contributes everything before its first interpolation), and a slug
+whose placements cannot be told apart that way is refused rather than guessed at.
+
+**An already-componentized page still has a shipped entry, and the plan may have moved its copy.**
+Its placements' `bind` is restated from the current plan on every run — in the order the registry
+already holds, since a page whose markup was cut has no roots left to read an order off — so a bind
+run followed by an instance run drops `bind` from the fallback table and the reverse puts it back.
+Repeated placements of one component (two groups sharing a `shapeHash`, which is what `shapeHash` is
+FOR) are matched **positionally**, registry order against plan order per slug: keying them by slug
+collapsed them, and a page with one group still bound and another moved wrote both from the second.
+Every plan occurrence holds its slot whether or not this run can act on it — one it cannot (refused,
+server-pending) consumes its position and keeps the earlier record, because a missed update is
+recoverable and a wrong one is a page rendering someone else's copy.
+Nothing is extracted there, and the registry is rewritten only if those bytes actually change.
+
 The registry and the sections library are rebuilt WHOLE each run, so they are first read back:
 components an earlier run wrote are reused rather than rewritten, and the shipped order of every
 page already served is carried forward. Without that, componentizing one new page emitted a
@@ -316,7 +393,8 @@ it happens to see.
 
 A run whose roots DO share a container but have a foreign sibling between them is not refused: each
 root becomes its own `<Hero …/>` where its markup was, counted `inlineOnly`. The markup is
-componentised and the ORDER stays the repository's — looping that page would move the sibling too.
+componentised and the ORDER stays the repository's — looping that page would move the sibling too. A placement whose copy the plan has moved cannot take that form and is
+`INLINE_NEEDS_INSTANCE`: the in-place call site carries no `blockId` and no `overrides`.
 
 The arithmetic is checked rather than hoped for:
 
@@ -342,6 +420,9 @@ and removing them would mean editing statements no section asked about.
 bind their own copy; only `findPropTargets` is jsx/astro-only, so a drilled prop there is
 `PROP_TARGET_NOT_FOUND` rather than a wrong edit).
 
-Componentize: svelte and vue extraction, and Phase B of the lane — copy owned by the INSTANCE
-(`overrides`) with the page-lane bindings rewritten to the block lane. `bcmsSection` already
-prefers `overrides`, so the repo half of Phase B is a data change rather than another codemod.
+Componentize: svelte and vue extraction. Phase B — copy owned by the INSTANCE — is here for both
+dialects this lane extracts: the block-lane address is chosen at render time, so moving a page's
+copy onto its instances is a data change rather than another cut of the repository. What Phase B
+does NOT reach is the `inlineOnly` shape: a page whose roots could not be looped keeps calling
+`<Hero bind="hero" …/>` in place, which never consults the CMS's blocks at all, so its copy stays
+the page's whatever the plan says.