Fix manifest missing component IRIs and Layout componentGroups embedding

Two bugs fixed:

1. Layout.componentGroups was returning embedded objects instead of IRI
   strings. AP4 reads readableLink from getter methods, not property
   declarations — override getComponentGroups() in Layout with
   #[ApiProperty(readableLink: false, writableLink: false)] and add
   explicit normalization/denormalization context with Layout:read/write
   serialization groups.

2. resource_manifest was missing component IRIs from ComponentPositions
   that use pageDataProperty. AP4 auto-computes readableLink=false for
   ComponentPosition.component (AbstractComponent has no Route:manifest:read
   fields), so AP4 returns the component as an IRI string rather than an
   embedded object. ManifestDepthGroupTrait was only collecting @id values
   from embedded arrays, not string IRIs.

   Fix: collect top-level string IRIs in collectCurrentDepth, but skip
   blank node resources (/.well-known/genid/) since AP4 assigns genid @ids
   to plain objects like ResourceMetadata — their string properties are
   internal metadata, not consumer-facing API resources.

   PageDataNormalizer injects cwa_current_page_data into context when
   serializing under Route:manifest:read so ComponentPositionNormalizer
   can resolve pageDataProperty slots without an HTTP request.

Author: silverbackdan

CLAUDE.md

@@ -112,6 +112,23 @@ Key current group assignments:
 - `AbstractPageData`: `page` (the Page template IRI) → `Route:manifest:read`
 - `AbstractPage`: `route`, `parentPage`, `parentPageData` → `Route:manifest:read`
 
+### Bug: `Layout.componentGroups` returns embedded objects instead of IRIs
+
+**Symptom (discovered 2026-06-16):** The navigation bar is empty for unauthenticated users. No failed requests appear in the network tab — the layout's component group contents are simply never fetched.
+
+**Root cause:** `GET /_api/_/layouts/{uuid}` returns `componentGroups` as **full embedded objects**:
+```json
+"componentGroups": [{ "@id": "/_api/_/component_groups/...", "location": "top", "componentPositions": [...] }]
+```
+
+The module's `fetchAssociatedResources` expects all associated property values to be **IRI strings** (this is both the module's contract and the caching architecture principle: "Never embed related resource data — always return IRIs"). Receiving objects instead of strings causes a silent TypeError (`object.split is not a function`) that is swallowed by `fetchBatch`, so the component groups are never stored and `CwaComponentGroup` finds nothing.
+
+**Why page content still works:** The manifest response includes page component group IRIs directly in `resource_iris`, so they are fetched as standalone resources in the manifest batch. Layouts have no manifest and rely entirely on `fetchAssociatedResources`.
+
+**Required fix:** Change the `Layout` serialization group so `componentGroups` is serialized as an array of IRI strings only (not embedded objects). Check `ComponentGroup.componentPositions` for the same issue — the module also expects these to be IRI strings.
+
+The module will be updated with a defensive `@id` extraction as a fallback, but the correct fix is here: the API must return IRIs, not embedded objects, for all associated resource properties.
+
 ### API endpoints
 
 | Endpoint | Purpose |
@@ -196,6 +213,139 @@ Currently `parentPage` is only in `Route:manifest:read`. It needs to be added to
 
 A Behat test should cover: `GET /_/pages` response includes `parentPage` for a page that has one set.
 
+### Outstanding — UUID-based manifest must walk the `parentPage` chain
+
+**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.
+
+**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.
+
+For a chapter `Page` entity whose `parentPage` is a topic `Page`:
+```json
+{
+  "resource_iris": [
+    ["/_/pages/topic-uuid", "/_/component_groups/...", ...],
+    ["/_/pages/chapter-uuid", "/_/component_groups/...", ...]
+  ]
+}
+```
+
+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).
+
+---
+
+## Feature: CwaFixtureBuilder
+
+> **Status: Design agreed, not yet implemented.**
+
+A fluent builder API that lets developers scaffold CWA website structure (layouts, pages, component groups, components, routes) in Doctrine fixture code with minimal boilerplate. The Doctrine Fixtures Bundle handles execution; this feature adds the ergonomic PHP API on top.
+
+### Dream developer API
+
+```php
+class AppScaffold extends AbstractCwaScaffold
+{
+    public function build(CwaFixtureBuilder $cwa): void
+    {
+        $cwa->layout('default', 'CwaLayout', function(LayoutBuilder $layout) {
+            $layout->group('navigation', fn(GroupBuilder $g) => $g
+                ->add(new NavigationLink('Home', '/'))
+                ->add(new NavigationLink('Blog', '/blog'))
+            );
+        });
+
+        $cwa->page('home', 'HomePage', layout: 'default', route: '/', function(PageBuilder $page) {
+            $page->group('hero', fn(GroupBuilder $g) => $g->add(new HtmlContent('<h1>Welcome</h1>')));
+            $page->group('body', fn(GroupBuilder $g) => $g->add(new HtmlContent('Intro text')));
+        });
+
+        // Complex pages extract cleanly to private methods via PHP 8.1 first-class callables
+        $cwa->page('blog', 'BlogPage', layout: 'default', route: '/blog', $this->buildBlog(...));
+
+        $cwa->page('conference', 'ConferencePage', layout: 'default', route: '/conference', $this->buildConference(...));
+    }
+
+    private function buildBlog(PageBuilder $page): void
+    {
+        $page->group('listing', fn(GroupBuilder $g) => $g->add(new Collection()));
+        $page->nested($this->buildBlogArticles(...));
+    }
+
+    private function buildBlogArticles(CwaFixtureBuilder $cwa): void
+    {
+        foreach ($this->articles() as $data) {
+            // route auto-generated: /blog/first-post (parent path + slug from title via RouteGenerator)
+            $cwa->pageData(new BlogArticleData(title: $data['title']), template: 'blog-article');
+        }
+    }
+
+    private function buildConference(PageBuilder $page): void
+    {
+        $page->group('details', fn(GroupBuilder $g) => $g->add(new HtmlContent('Details')));
+        $page->nested(function(CwaFixtureBuilder $cwa) {
+            // /conference/programme, /conference/speakers — auto-prefixed via RouteGenerator
+            $cwa->pageData(new ConferenceData(title: 'Programme'), template: 'conference-section');
+            $cwa->pageData(new ConferenceData(title: 'Speakers'), template: 'conference-section');
+        });
+    }
+}
+```
+
+### Integration — `AbstractCwaScaffold` IS the fixture
+
+```php
+abstract class AbstractCwaScaffold implements FixtureInterface
+{
+    public function __construct(private CwaFixtureBuilder $cwa) {}
+
+    public function load(ObjectManager $manager): void
+    {
+        $this->build($this->cwa->withManager($manager));
+    }
+
+    abstract public function build(CwaFixtureBuilder $cwa): void;
+}
+```
+
+Register `AppScaffold` as a service; it's ready to use as a Doctrine fixture with no extra boilerplate.
+
+### Builder shape
+
+```
+CwaFixtureBuilder
+  ->layout(ref, uiComponent, ?Closure)  → LayoutBuilder
+      ->group(name, ?allow[], Closure)  → LayoutBuilder  (closure receives GroupBuilder)
+  ->page(ref, uiComponent, layout, ?route, ?Closure)  → PageBuilder
+      ->group(name, Closure)  → PageBuilder
+      ->nested(Closure)  → PageBuilder  (CwaFixtureBuilder in closure has parent context)
+  ->pageData(AbstractPageData, ?template, ?Closure)  → PageDataBuilder
+      ->route(path)  → PageDataBuilder
+
+GroupBuilder
+  ->add(AbstractComponent, ?sort)  → GroupBuilder  (sort defaults to insertion order)
+```
+
+### Route auto-generation rules
+
+| Situation | Result |
+|---|---|
+| `route: '/'` explicit | uses that path |
+| no `route:` on `->page()` | no Route created (it's a template) |
+| `->pageData(...)` inside `->nested()`, no route | calls `RouteGenerator` with parent context → `/parent-path/slug-from-title` |
+| `->pageData(...)` at top level, no route | no Route created (draft) |
+
+### What the builder handles invisibly
+
+- `TimestampedDataPersister` called on each entity
+- `$manager->persist()` for all entities
+- Deduplication by reference (call `->layout('default', ...)` twice → same entity returned)
+- `ComponentPosition` wrapping and sort order
+- `setRoute()` / `setPageData()` bidirectional linking
+- Parent context propagation through `->nested()` so `parentPage`/`parentPageData` is set automatically
+
+---
+
 ### Design decisions
 
 - **No `$nested` boolean** — parent = nested, full stop. The presence of `$parentPage`/`$parentPageData` is the complete signal.

features/main/layout.feature

@@ -109,3 +109,10 @@ Feature: Layout resources
     Then the response status code should be 200
     And the JSON node "member" should have "1" elements
     And the JSON node "member[0].reference" should be equal to "primary"
+
+  @loginUser
+  Scenario: Layout componentGroups are returned as IRI strings, not embedded objects
+    Given there is a ComponentGroup in a Page and a Layout
+    When I send a "GET" request to the resource "layout"
+    Then the response status code should be 200
+    And the JSON node "componentGroups[0]" should be equal to the IRI of the resource "component_group"

features/main/route.feature

@@ -126,6 +126,12 @@ Feature: Route resources
     Then the response status code should be 200
     And the JSON node "route" should be equal to the string "/_/routes//my-route"
 
+  Scenario: The manifest includes component IRIs resolved from pageDataProperty positions
+    Given there is a PageData resource with the route path "/my-route"
+    When I send a "GET" request to "/_/resource_manifest//my-route"
+    Then the response status code should be 200
+    And the JSON node "resource_iris[0][5]" should match the regex "/\/component\/dummy_components\/[a-z0-9\-]+/"
+
   Scenario: The manifest for a nested PageData route includes parent resource IRIs grouped by depth
     Given there is a PageData resource with the route path "/conference/programme" nested within the route "/conference"
     When I send a "GET" request to "/_/resource_manifest//conference/programme"

src/Entity/Core/Layout.php

@@ -24,6 +24,7 @@
 use Silverback\ApiComponentsBundle\Entity\Utility\UiTrait;
 use Silverback\ApiComponentsBundle\Filter\OrSearchFilter;
 use Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity;
+use Symfony\Component\Serializer\Attribute\Groups;
 use Symfony\Component\Validator\Constraints as Assert;
 use Symfony\Component\Validator\Mapping\ClassMetadata;
 
@@ -33,7 +34,12 @@
 #[ORM\Entity]
 #[ORM\Table(name: 'layout')]
 #[Silverback\Timestamped]
-#[ApiResource(mercure: true, order: ['createdAt' => 'DESC'])]
+#[ApiResource(
+    normalizationContext: ['groups' => ['Layout:read']],
+    denormalizationContext: ['groups' => ['Layout:write']],
+    mercure: true,
+    order: ['createdAt' => 'DESC'],
+)]
 #[ApiFilter(OrderFilter::class, properties: ['createdAt', 'reference'], arguments: ['orderParameterName' => 'order'])]
 #[ApiFilter(OrSearchFilter::class, properties: ['reference' => 'ipartial', 'uiComponent' => 'ipartial'])]
 #[UniqueEntity(fields: ['reference'], message: 'There is already a Layout with that reference.')]
@@ -45,15 +51,18 @@ class Layout
 
     #[ORM\Column]
     #[Assert\NotBlank(message: 'Please enter a reference.')]
+    #[Groups(['Layout:read', 'Layout:write'])]
     public string $reference;
 
     #[ORM\OneToMany(targetEntity: Page::class, mappedBy: 'layout')]
     #[ApiProperty(writable: false)]
+    #[Groups(['Layout:read'])]
     public Collection $pages;
 
     #[ORM\ManyToMany(targetEntity: ComponentGroup::class, inversedBy: 'layouts')]
     #[ORM\JoinColumn(onDelete: 'CASCADE')]
     #[ORM\InverseJoinColumn(onDelete: 'CASCADE')]
+    #[Groups(['Layout:read', 'Layout:write'])]
     private Collection $componentGroups;
 
     public function __construct()
@@ -63,6 +72,12 @@ public function __construct()
         $this->pages = new ArrayCollection();
     }
 
+    #[ApiProperty(readableLink: false, writableLink: false)]
+    public function getComponentGroups(): Collection|array
+    {
+        return $this->componentGroups;
+    }
+
     public static function loadValidatorMetadata(ClassMetadata $metadata): void
     {
         $metadata->addPropertyConstraint('uiComponent', new Assert\NotBlank(

src/Entity/Utility/UiTrait.php

@@ -15,6 +15,7 @@
 use Doctrine\Common\Collections\Collection;
 use Doctrine\ORM\Mapping as ORM;
 use Silverback\ApiComponentsBundle\Entity\Core\ComponentGroup;
+use Symfony\Component\Serializer\Attribute\Groups;
 
 /**
  * @author Daniel West <daniel@silverback.is>
@@ -24,9 +25,11 @@
 trait UiTrait
 {
     #[ORM\Column(nullable: true)]
+    #[Groups(['Layout:read', 'Layout:write'])]
     public ?string $uiComponent = null;
 
     #[ORM\Column(type: 'json', nullable: true)]
+    #[Groups(['Layout:read', 'Layout:write'])]
     public ?array $uiClassNames = null;
 
     /**

src/Serializer/Normalizer/ComponentPositionNormalizer.php

@@ -93,7 +93,7 @@ public function normalize($object, $format = null, array $context = []): float|a
         $staticComponent = $object->component;
         $resourceMetadata = $this->resourceMetadataProvider->findResourceMetadata($object);
 
-        $object = $this->normalizeForPageData($object);
+        $object = $this->normalizeForPageData($object, $context);
         if ($object->pageDataProperty) {
             $resourceMetadata->setIsDynamicPosition(true);
             try {
@@ -142,19 +142,25 @@ private function normalizePublishableComponent(AbstractComponent $component)
         return $draft ?? $component;
     }
 
-    private function normalizeForPageData(ComponentPosition $object): ComponentPosition
+    private function normalizeForPageData(ComponentPosition $object, array $context): ComponentPosition
     {
-        if (!$object->pageDataProperty || !$this->requestStack->getCurrentRequest()) {
-            return $object;
-        }
-        try {
-            $pageData = $this->pageDataProvider->getPageData();
-        } catch (UnprocessableEntityHttpException $e) {
-            // when serializing for mercure, we do not need the path header
+        if (!$object->pageDataProperty) {
             return $object;
         }
 
-        if (!$pageData) {
+        if (isset($context['cwa_current_page_data'])) {
+            $pageData = $context['cwa_current_page_data'];
+        } elseif ($this->requestStack->getCurrentRequest()) {
+            try {
+                $pageData = $this->pageDataProvider->getPageData();
+            } catch (UnprocessableEntityHttpException $e) {
+                // when serializing for mercure, we do not need the path header
+                return $object;
+            }
+            if (!$pageData) {
+                return $object;
+            }
+        } else {
             return $object;
         }
 

src/Serializer/Normalizer/PageDataNormalizer.php

@@ -47,6 +47,10 @@ public function normalize($object, $format = null, array $context = []): float|a
         $resourceMetadata = $this->resourceMetadataProvider->findResourceMetadata($object);
         $resourceMetadata->setPageDataMetadata($metadata);
 
+        if (\in_array('Route:manifest:read', $context['groups'] ?? [], true)) {
+            $context['cwa_current_page_data'] = $object;
+        }
+
         return $this->normalizer->normalize($object, $format, $context);
     }
 

src/Serializer/Normalizer/Trait/ManifestDepthGroupTrait.php

@@ -46,8 +46,13 @@ private function collectCurrentDepth(array $resource, array $iris, array $parent
             $iris[] = $id;
         }
 
+        $isBlankNode = isset($resource['@id']) && str_contains($resource['@id'], '/.well-known/genid/');
+
         foreach ($resource as $key => $value) {
             if (!\is_array($value)) {
+                if (!$isBlankNode && \is_string($value) && !str_starts_with($key, '@') && str_starts_with($value, '/') && !$this->shouldSkipIri($value) && !\in_array($value, $iris, true)) {
+                    $iris[] = $value;
+                }
                 continue;
             }