Add cascadeChildPaths, route children endpoint, and CwaFixtureBuilder

- PATCH /_/routes/{id} accepts cascadeChildPaths: true to update all child
  route paths sharing the old prefix and create redirects; intermediate flush
  before creating redirects avoids Doctrine INSERT-before-UPDATE conflict
- GET /_/routes/{id}/children returns recursive child tree (route IRI, path,
  children) for admin UI navigation; admin-only, no Hydra wrapper
- CwaFixtureBuilder: layout/page/pageData builders with 4-phase flush,
  GroupBuilder for component groups and pageDataProperty positions,
  nested() on PageDataBuilder and PageBuilder to set parent relationships
  and auto-persist child entities after parent flush

Author: silverbackdan

CLAUDE.md

@@ -197,71 +197,52 @@ This means:
 1. **`$parentPage` and `$parentPageData` on `AbstractPage`** — `Assert\Expression` constraint, getters/setters, computed `getParentPageRoute()`, ORM attributes on both `Page` and `AbstractPageData`
 2. **`$nested` removed from `AbstractPage`** — property, getter, setter, ORM mapping, and schema entry all removed. Parent = nested, always.
 3. **`$route`, `$parentPage`, `$parentPageData` in `Route:manifest:read`** — parent sub-tree IRIs appear in `resource_iris` automatically via the normalizer walk
-4. **Behat tests** — `features/main/route.feature`: nested PageData and nested Page manifests both tested; `features/main/page.feature`: create with parentPage (201), create with parentPageData (201), both set (422), PATCH to set parentPage (200), flat PageData manifest (200), nested PageData manifest (200)
+4. **Behat tests** — `features/main/route.feature`: nested PageData and nested Page manifests both tested; `features/main/page.feature`: create with parentPage (201), create with parentPageData (201), both set (422), PATCH to set parentPage (200), flat PageData manifest (200), nested PageData manifest (200), nested Page manifest (200)
 5. **`/_/resource_manifest/{id}` unified endpoint** — `ResourceManifest` DTO (`src/ApiResource/ResourceManifest.php`) with `ResourceManifestStateProvider` resolving route paths (starts with `/`) or UUIDs (Page then AbstractPageData). `ResourceManifestVoter` delegates access control to `RouteVoter` or `AbstractRoutableVoter`. `ResourceManifestNormalizer` produces `{ "resource_iris": string[][] }` using the shared `ManifestDepthGroupTrait`.
 6. **`ManifestDepthGroupTrait`** (`src/Serializer/Normalizer/Trait/ManifestDepthGroupTrait.php`) — `buildDepthGroups`, `collectCurrentDepth`, `shouldSkipIri` extracted and shared between `RouteNormalizer` and `ResourceManifestNormalizer`
 7. **`pageDataProperty` component IRIs in manifests** — `PageDataNormalizer` injects `cwa_current_page_data` into the serialization context when `Route:manifest:read` is active. `ComponentPositionNormalizer.normalizeForPageData()` reads this context key and resolves `pageDataProperty` positions during manifest generation without requiring an HTTP `path` header. `ManifestDepthGroupTrait.collectCurrentDepth()` now also collects string IRI values from non-blank-node subresources (AP4 returns component IRIs as strings when `AbstractComponent` has no `Route:manifest:read` fields). Blank node resources (`/.well-known/genid/...`) are excluded from string IRI collection to avoid leaking internal metadata IRIs (e.g. `pageDataMetadata`). Behat test in `features/main/route.feature` covers `resource_iris[0][5]` matching a DummyComponent IRI.
 8. **`Layout.componentGroups` returns IRI strings** — see fixed bug above. Behat test in `features/main/layout.feature` covers `componentGroups[0]` equal to the component group IRI.
 
-### Outstanding — `parentPage` in standard Page read group
+### ~~Outstanding — `parentPage` in standard Page read group~~ — ALREADY WORKS
 
-**Requirement (discovered 2026-06-15):** The Nuxt module's admin parent-page picker must filter out descendants of the current page to prevent circular parent chains (e.g. A → B → A). The picker is populated from `GET /_/pages` (via `useParentPageLoader`). To detect descendants client-side, each page in that collection response must include its own `parentPage` IRI.
+`parentPage` already appears in `GET /_/pages` responses for pages that have a parent set. Because `Page` has no explicit `normalizationContext`, AP4 does not inject a `groups` key into the Symfony serializer context. Without a `groups` key, the Symfony serializer ignores all `#[Groups]` annotations and serializes all accessible properties — including `parentPage` via `getParentPage()`. No code change was needed; Behat test added to `features/main/page.feature` for coverage.
 
-Currently `parentPage` is only in `Route:manifest:read`. It needs to be added to whatever serialization group drives the `/_/pages` collection read (e.g. `Page:read` or a shared `AbstractPage:read` group). This satisfies the principle of least exposure — there is a concrete consumer (the admin picker descendant-filter).
+### ~~Bug: PATCH `/_/pages/{uuid}` throws 500 when body contains `componentGroups`~~ — FIXED
 
-A Behat test should cover: `GET /_/pages` response includes `parentPage` for a page that has one set.
+**Symptom (discovered 2026-06-17):** Saving a Page from the Nuxt admin modal triggered a 500/422 when the PATCH body contained `componentGroups` as embedded JSON-LD objects (AP4 tried to denormalize the component positions collection, which caused `ArrayCollection::$sortValue` access errors).
 
-### Bug: PATCH `/_/pages/{uuid}` throws 500 when body contains `componentGroups`
+**Fix (committed 2026-06-17):** Overrode `getComponentGroups()` in `Page.php` with `#[ApiProperty(writable: false)]`. AP4 now ignores `componentGroups` during deserialization — whether sent as IRI strings or embedded objects. Component groups are managed via their own endpoints.
 
-**Symptom (discovered 2026-06-17):** Saving a Page from the Nuxt admin modal returns:
-```
-500: Warning: Undefined property: Doctrine\Common\Collections\ArrayCollection::$sortValue
-```
-
-**Trigger payload:** The Nuxt module admin modal PATCHes the full resource data including `componentGroups` as an array (either IRI strings or embedded JSON-LD objects, depending on what was returned in the GET). Example body:
-```json
-{
-  "@type": "Page",
-  "reference": "My Page",
-  "layout": "/_/layouts/uuid",
-  "componentGroups": ["/_/component_groups/uuid1", "/_/component_groups/uuid2"]
-}
-```
-
-**Likely root cause:** The Symfony deserializer processes the `componentGroups` array and, during denormalization of `ComponentGroup` entities, either a lifecycle callback or the `ComponentPositionNormalizer` accesses `$sortValue` on the `ComponentGroup.componentPositions` `ArrayCollection` as if it were a scalar property — rather than iterating over individual `ComponentPosition` entities. This results in PHP trying to read `$sortValue` on the `ArrayCollection` object itself.
-
-**Where to look:**
-- `ComponentGroup` entity — any `#[ORM\PrePersist]` / `#[ORM\PreUpdate]` listener that reads `componentPositions->sortValue`
-- `ComponentPositionNormalizer` — any code path triggered during `PATCH` denormalization that accesses the position collection
-- Symfony's denormalization of `ComponentGroup.componentPositions` when the PATCH body includes inline `componentGroups`
+**Behat tests:** Two scenarios in `features/main/page.feature` — PATCH with IRI-string componentGroups (200), PATCH with embedded componentGroups including positions (200).
 
-**Workaround (Nuxt module, committed 2026-06-17):** `PageAdminModal` passes `excludeFields: ['componentGroups']` to `useItemPage`, so `componentGroups` is stripped from the PATCH body before sending. This bypasses the bug without fixing it. A proper API-side fix is still needed so that PATCH requests including `componentGroups` do not 500.
+---
 
-**Test to write:** Behat scenario — `PATCH /_/pages/{uuid}` with `componentGroups` in the request body returns 200, not 500.
 
 ---
 
-### Outstanding — UUID-based manifest must walk the `parentPage` chain
+## API contracts: Route UI/UX (from Nuxt module design discussion)
+
+### 1. Cascade child path update on route PATCH — COMPLETE ✓
 
-**Bug (discovered 2026-06-16):** When the Nuxt module admin accesses a nested `Page` entity directly via its admin URL (e.g. `/_cwa/%2F_api%2F_%2Fpages%2F{child-uuid}`), the fetcher calls `GET /_api/_/resource_manifest/{child-uuid}`. The module code is correct: it uses `irisByDepth[0]` as the parent depth and renders `pageIriAtDepth(depth)` for each level. However, the admin admin page displays only a placeholder (no parent content) because the manifest endpoint currently returns only the accessed page in a single depth group — it does not walk the `parentPage`/`parentPageData` chain upward.
+`PATCH /_/routes/{id}` accepts optional `cascadeChildPaths: true` boolean. When set and `path` changes, `RouteEventListener.onPostWrite` walks direct children via `AbstractPage.parentPage`/`parentPageData`, updates their route paths (prefixing with the new parent path), and creates redirects from old to new child paths. Children whose path does not start with the old prefix are ignored. Intermediate flush required before creating child redirects (Doctrine processes INSERTs before UPDATEs; flushing path changes first frees old paths in the DB). Behat tests in `features/main/route.feature`.
 
-**Required fix:** `ResourceManifestNormalizer` (or `ResourceManifestStateProvider`) when resolving by Page UUID must walk the `parentPage`/`parentPageData` chain to the root and produce `resource_iris: string[][]` with one inner array per depth level, root first — exactly as the route-path path does when the manifest normalizer walks the embedded parent sub-tree via the `Route:manifest:read` group.
+### 2. Route children endpoint — COMPLETE ✓
 
-For a chapter `Page` entity whose `parentPage` is a topic `Page`:
+`GET /_/routes/{id}/children` returns the recursive child tree for a specific route. Admin-only (`ROLE_ADMIN`). Response:
 ```json
 {
-  "resource_iris": [
-    ["/_/pages/topic-uuid", "/_/component_groups/...", ...],
-    ["/_/pages/chapter-uuid", "/_/component_groups/...", ...]
+  "children": [
+    {
+      "route": "/_/routes//conference/programme",
+      "path": "/conference/programme",
+      "children": []
+    }
   ]
 }
 ```
+Each node embeds its direct children recursively so the full sub-tree is visible in one request. Children are plain objects (not IRIs) since you need the tree structure to navigate it; `route` and `path` are the only data fields per node — all other route detail is fetched via the IRI.
 
-The fix should mirror what `RouteNormalizer` does when following `parentPage`/`parentPageData` during route-based manifest generation. The `ManifestDepthGroupTrait` `buildDepthGroups` should already handle this if the correct sub-tree is passed in — check whether `ResourceManifestNormalizer` is passing the full serialized entity (including embedded parent data) or only the top-level page object.
-
-A Behat test should cover: `GET /_/resource_manifest/{child-page-uuid}` for a page with `parentPage` set returns `resource_iris` with two depth groups (parent resources first, child resources last).
-
----
+Implementation: `RouteChildren` + `RouteChildrenNode` DTOs, `RouteChildrenStateProvider`, `RouteChildrenNormalizer`. Custom `Get` operation added to `Route` at `/routes/{id}/children`. The standard Route `Get` requirement updated to `(?!.+\/(?:redirects|children)$).+` to exclude both sub-resource suffixes. Behat tests in `features/main/route.feature`.
 
 ## Feature: CwaFixtureBuilder
 

features/bootstrap/DoctrineContext.php

@@ -367,6 +367,29 @@ public function thereIsAComponentGroupInAPage()
         $this->manager->flush();
     }
 
+    /**
+     * @Given there is a valid Page with a ComponentGroup
+     */
+    public function thereIsAValidPageWithAComponentGroup(): void
+    {
+        $layout = $this->thereIsALayout();
+
+        $page = new Page();
+        $page->reference = 'page-with-group';
+        $page->uiComponent = 'TestComponent';
+        $page->isTemplate = false;
+        $page->layout = $layout;
+        $this->timestampedHelper->persistTimestampedFields($page, true);
+        $this->manager->persist($page);
+
+        $group = $this->thereIsAComponentGroupWithComponents(1);
+        $page->addComponentGroup($group);
+        $this->manager->persist($page);
+        $this->manager->flush();
+
+        $this->restContext->resources['page'] = $this->iriConverter->getIriFromResource($page);
+    }
+
     /**
      * @Given /^there is a ComponentGroup in a Page and a Layout$/
      */
@@ -786,10 +809,49 @@ public function thereIsANestedPageResource(string $childPath, string $parentPath
         $this->manager->persist($childRoute);
         $this->restContext->resources['page'] = $this->iriConverter->getIriFromResource($childPage);
         $this->restContext->resources['page_route'] = $this->iriConverter->getIriFromResource($childRoute);
+        $this->restContext->resources['page_manifest'] = '/_/resource_manifest/' . $childPage->getId();
 
         $this->manager->flush();
     }
 
+    /**
+     * @When I patch the page with the component group in the request body
+     */
+    public function iPatchPageWithComponentGroupInBody(): void
+    {
+        $cgIri = $this->restContext->resources['component_group'];
+        $this->restContext->iSendARequestToTheResourceWithBody(
+            'PATCH',
+            'page',
+            null,
+            new PyStringNode([sprintf('{"componentGroups": ["%s"]}', $cgIri)], 0)
+        );
+    }
+
+    /**
+     * @When I patch the page with an embedded component group in the request body
+     */
+    public function iPatchPageWithEmbeddedComponentGroupInBody(): void
+    {
+        $cgIri = $this->restContext->resources['component_group'];
+        $posIri = $this->restContext->resources['position_0'];
+        $body = json_encode([
+            'componentGroups' => [
+                [
+                    '@id' => $cgIri,
+                    '@type' => 'ComponentGroup',
+                    'componentPositions' => [['@id' => $posIri, 'sortValue' => 0]],
+                ],
+            ],
+        ]);
+        $this->restContext->iSendARequestToTheResourceWithBody(
+            'PATCH',
+            'page',
+            null,
+            new PyStringNode([$body], 0)
+        );
+    }
+
     /**
      * @When I patch the PageData with the property :property and resource :resource
      */
@@ -1228,6 +1290,18 @@ public function theRouteShouldRedirectTo(string $oldPath, string $newPath): void
         Assert::assertEquals($newPath, $route->getRedirect()->getPath());
     }
 
+    /**
+     * @Then the Route :path should not redirect
+     */
+    public function theRouteShouldNotRedirect(string $path): void
+    {
+        $this->manager->clear();
+        $repository = $this->manager->getRepository(Route::class);
+        $route = $repository->findOneBy(['path' => $path]);
+        Assert::assertNotNull($route, sprintf('Expected route "%s" to exist.', $path));
+        Assert::assertNull($route->getRedirect(), sprintf('Expected route "%s" to have no redirect, but it does.', $path));
+    }
+
     /**
      * @Then /^(\d+) refresh token(?:s)? should exist$/
      */

features/main/page.feature

@@ -126,3 +126,31 @@ Feature: Page resources
     Then the response status code should be 200
     And the JSON node "resource_iris" should have 2 elements
     And the JSON node "resource_iris[1][0]" should be equal to the IRI of the resource "page_data"
+
+  @loginAdmin
+  Scenario: I can PATCH a page when componentGroups are included in the request body
+    Given there is a valid Page with a ComponentGroup
+    When I patch the page with the component group in the request body
+    Then the response status code should be 200
+
+  @loginAdmin
+  Scenario: I can PATCH a page when embedded componentGroups with positions are included in the request body
+    Given there is a valid Page with a ComponentGroup
+    When I patch the page with an embedded component group in the request body
+    Then the response status code should be 200
+
+  @loginAdmin
+  Scenario: The page collection includes parentPage when set
+    Given there is a Page
+    And there is a page with parent page "page"
+    When I send a "GET" request to "/_/pages?order[reference]=asc"
+    Then the response status code should be 200
+    And the JSON node "member[0].parentPage" should be equal to the IRI of the resource "page"
+
+  @loginAdmin
+  Scenario: I can get a resource manifest for a nested Page by UUID
+    Given there is a Page resource with the route path "/conference/programme" nested within the route "/conference"
+    When I send a "GET" request to the resource "page_manifest"
+    Then the response status code should be 200
+    And the JSON node "resource_iris" should have 2 elements
+    And the JSON node "resource_iris[1][0]" should be equal to the IRI of the resource "page"

features/main/route.feature

@@ -90,6 +90,66 @@ Feature: Route resources
     And the JSON should be valid according to the schema file "route.schema.json"
     And the Route "/original" should redirect to "/new"
 
+  @loginAdmin
+  Scenario: PATCH a route path with cascadeChildPaths updates child routes and creates redirects
+    Given there is a PageData resource with the route path "/conference/programme" nested within the route "/conference"
+    When I send a "PATCH" request to the resource "parent_route" with data:
+      | path            | cascadeChildPaths |
+      | /new-conference | true              |
+    Then the response status code should be 200
+    And the JSON node "path" should be equal to the string "/new-conference"
+    And the Route "/conference" should redirect to "/new-conference"
+    And the Route "/conference/programme" should redirect to "/new-conference/programme"
+
+  @loginAdmin
+  Scenario: PATCH a route path without cascadeChildPaths does not cascade to children
+    Given there is a PageData resource with the route path "/conference/programme" nested within the route "/conference"
+    When I send a "PATCH" request to the resource "parent_route" with data:
+      | path            |
+      | /new-conference |
+    Then the response status code should be 200
+    And the Route "/conference/programme" should not redirect
+
+  @loginAdmin
+  Scenario: PATCH with cascadeChildPaths but path unchanged causes no cascade
+    Given there is a PageData resource with the route path "/conference/programme" nested within the route "/conference"
+    When I send a "PATCH" request to the resource "parent_route" with data:
+      | path        | cascadeChildPaths |
+      | /conference | true              |
+    Then the response status code should be 200
+    And the Route "/conference/programme" should not redirect
+
+  @loginAdmin
+  Scenario: PATCH with cascadeChildPaths ignores children with diverged route paths
+    Given there is a PageData resource with the route path "/talks" nested within the route "/conference"
+    When I send a "PATCH" request to the resource "parent_route" with data:
+      | path            | cascadeChildPaths |
+      | /new-conference | true              |
+    Then the response status code should be 200
+    And the Route "/talks" should not redirect
+
+  @loginAdmin
+  Scenario: GET a route's children returns recursive tree with path and IRI per node
+    Given there is a PageData resource with the route path "/conference/programme" nested within the route "/conference"
+    When I send a "GET" request to the resource "parent_route" and the postfix "/children"
+    Then the response status code should be 200
+    And the JSON node "children" should have 1 element
+    And the JSON node "children[0].route" should be equal to "/_/routes//conference/programme"
+    And the JSON node "children[0].path" should be equal to the string "/conference/programme"
+    And the JSON node "children[0].children" should have 0 elements
+
+  @loginAdmin
+  Scenario: GET children for a leaf route returns an empty children array
+    Given there is a PageData resource with the route path "/conference/programme" nested within the route "/conference"
+    When I send a "GET" request to the resource "page_data_route" and the postfix "/children"
+    Then the response status code should be 200
+    And the JSON node "children" should have 0 elements
+
+  Scenario: Anonymous users cannot access route children
+    Given there is a PageData resource with the route path "/conference/programme" nested within the route "/conference"
+    When I send a "GET" request to the resource "parent_route" and the postfix "/children"
+    Then the response status code should be 401
+
   @loginUser
   Scenario: I generate a route for a path that already exists and the new route is generated with a postfix
     Given there is a PageData resource with the route path "/unnamed-page"