fix: Docs initial cleanup

Author: Tania Mathern

docs/working-stores.md

@@ -492,9 +492,65 @@ with open("source.jpg", "rb") as src, open("signed.jpg", "w+b") as dst:
     builder.sign("image/jpeg", src, dst)
 ```
 
-When linking multiple ingredient archives, give each a distinct label and reference them separately in `ingredientIds`:
+When linking multiple ingredient archives, give each a distinct label and reference it in the appropriate action's `ingredientIds` array.
+
+If each ingredient has its own action (e.g., one `c2pa.opened` for the parent and one `c2pa.placed` for a composited element), set up two actions with separate `ingredientIds`:
 
 ```py
+manifest_json = {
+    "claim_generator_info": [{"name": "my-app", "version": "1.0"}],
+    "assertions": [{
+        "label": "c2pa.actions.v2",
+        "data": {
+            "actions": [
+                {
+                    "action": "c2pa.opened",
+                    "digitalSourceType": "http://cv.iptc.org/newscodes/digitalsourcetype/digitalCreation",
+                    "parameters": {"ingredientIds": ["parent-photo"]},
+                },
+                {
+                    "action": "c2pa.placed",
+                    "parameters": {"ingredientIds": ["overlay-graphic"]},
+                },
+            ]
+        },
+    }],
+}
+
+builder = Builder(manifest_json, context=ctx)
+
+builder.add_ingredient(
+    {"title": "photo.jpg", "relationship": "parentOf", "label": "parent-photo"},
+    "application/c2pa",
+    photo_archive,
+)
+builder.add_ingredient(
+    {"title": "overlay.png", "relationship": "componentOf", "label": "overlay-graphic"},
+    "application/c2pa",
+    overlay_archive,
+)
+```
+
+A single `c2pa.placed` action can also reference several `componentOf` ingredients composited together. List all labels in the `ingredientIds` array:
+
+```py
+manifest_json = {
+    "claim_generator_info": [{"name": "my-app", "version": "1.0"}],
+    "assertions": [{
+        "label": "c2pa.actions.v2",
+        "data": {
+            "actions": [{
+                "action": "c2pa.placed",
+                "parameters": {
+                    "ingredientIds": ["base-layer", "overlay-layer"]
+                },
+            }]
+        },
+    }],
+}
+
+builder = Builder(manifest_json, context=ctx)
+
 builder.add_ingredient(
     {"title": "base.jpg", "relationship": "componentOf", "label": "base-layer"},
     "application/c2pa",
@@ -507,6 +563,8 @@ builder.add_ingredient(
 )
 ```
 
+After signing, the action's `parameters.ingredients` array contains one resolved URL per ingredient.
+
 ### Ingredient relationships
 
 Specify the relationship between the ingredient and the current asset:

tests/test_unit_tests.py

@@ -1021,6 +1021,35 @@ def callback_signer_es256(data: bytes) -> bytes:
             return signature
         self.callback_signer_es256 = callback_signer_es256
 
+    def _create_ingredient_archive(self, ingredient_json=None):
+        """Helper: create an ingredient archive from a single ingredient."""
+        if ingredient_json is None:
+            ingredient_json = {"title": "photo.jpg", "relationship": "componentOf"}
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "1.0"}],
+            "assertions": [
+                {
+                    "label": "c2pa.actions",
+                    "data": {
+                        "actions": [
+                            {
+                                "action": "c2pa.created",
+                                "digitalSourceType": "http://cv.iptc.org/newscodes/digitalsourcetype/digitalCreation",
+                            }
+                        ]
+                    },
+                }
+            ],
+        }
+        builder = Builder.from_json(manifest)
+        with open(self.testPath, "rb") as f:
+            builder.add_ingredient(ingredient_json, "image/jpeg", f)
+        archive = io.BytesIO()
+        builder.to_archive(archive)
+        builder.close()
+        archive.seek(0)
+        return archive
+
     def test_can_retrieve_builder_supported_mimetypes(self):
         result1 = Builder.get_supported_mime_types()
         self.assertTrue(len(result1) > 0)
@@ -4151,44 +4180,6 @@ def test_builder_opened_action_multiple_ingredient_no_auto_add(self):
         # Make sure settings are put back to the common test defaults
         load_settings('{"builder":{"actions":{"auto_placed_action":{"enabled":false},"auto_opened_action":{"enabled":false},"auto_created_action":{"enabled":false}}}}')
 
-
-    # -----------------------------------------------------------------------
-    # Tests: Linking ingredient archives to actions.
-    #
-    # Only labels set on the signing builder's add_ingredient call work for
-    # linking ingredient archives to actions via ingredientIds.
-    # Labels baked into the archive and instance_id (anywhere) do NOT work.
-    # -----------------------------------------------------------------------
-
-    def _create_ingredient_archive(self, ingredient_json=None):
-        """Helper: create an ingredient archive from a single ingredient."""
-        if ingredient_json is None:
-            ingredient_json = {"title": "photo.jpg", "relationship": "componentOf"}
-        manifest = {
-            "claim_generator_info": [{"name": "c2pa-test", "version": "1.0"}],
-            "assertions": [
-                {
-                    "label": "c2pa.actions",
-                    "data": {
-                        "actions": [
-                            {
-                                "action": "c2pa.created",
-                                "digitalSourceType": "http://cv.iptc.org/newscodes/digitalsourcetype/digitalCreation",
-                            }
-                        ]
-                    },
-                }
-            ],
-        }
-        builder = Builder.from_json(manifest)
-        with open(self.testPath, "rb") as f:
-            builder.add_ingredient(ingredient_json, "image/jpeg", f)
-        archive = io.BytesIO()
-        builder.to_archive(archive)
-        builder.close()
-        archive.seek(0)
-        return archive
-
     def test_link_archive_label_on_signing_builder_placed(self):
         """Label set on the signing builder's add_ingredient links an
         ingredient archive to a c2pa.placed action."""
@@ -4419,6 +4410,87 @@ def test_link_archive_two_ingredients_labels(self):
 
         load_settings('{"builder":{"actions":{"auto_placed_action":{"enabled":false},"auto_opened_action":{"enabled":false},"auto_created_action":{"enabled":false}}}}')
 
+    def test_link_archive_multiple_ingredients_in_one_placed_action(self):
+        """A single c2pa.placed action references two componentOf ingredients
+        via ingredientIds with two labels."""
+        load_settings('{"builder":{"actions":{"auto_placed_action":{"enabled":false},"auto_opened_action":{"enabled":false},"auto_created_action":{"enabled":false}}}}')
+
+        archive1 = self._create_ingredient_archive(
+            {"title": "base-layer.jpg", "relationship": "componentOf"}
+        )
+        archive2 = self._create_ingredient_archive(
+            {"title": "overlay-layer.jpg", "relationship": "componentOf"}
+        )
+
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "1.0"}],
+            "assertions": [
+                {
+                    "label": "c2pa.actions.v2",
+                    "data": {
+                        "actions": [
+                            {
+                                "action": "c2pa.placed",
+                                "parameters": {
+                                    "ingredientIds": ["base-layer", "overlay-layer"]
+                                },
+                            }
+                        ]
+                    },
+                }
+            ],
+        }
+
+        builder = Builder.from_json(manifest)
+        builder.add_ingredient(
+            {"title": "base-layer.jpg", "relationship": "componentOf", "label": "base-layer"},
+            "application/c2pa",
+            archive1,
+        )
+        builder.add_ingredient(
+            {"title": "overlay-layer.jpg", "relationship": "componentOf", "label": "overlay-layer"},
+            "application/c2pa",
+            archive2,
+        )
+
+        with open(self.testPath, "rb") as src:
+            output = io.BytesIO()
+            builder.sign(self.signer, "image/jpeg", src, output)
+            output.seek(0)
+
+            reader = Reader("image/jpeg", output)
+            manifest_data = json.loads(reader.json())
+            active = manifest_data["active_manifest"]
+            assertions = manifest_data["manifests"][active]["assertions"]
+
+            placed_action = None
+            for assertion in assertions:
+                if assertion.get("label") == "c2pa.actions.v2":
+                    for action in assertion["data"]["actions"]:
+                        if action["action"] == "c2pa.placed":
+                            placed_action = action
+                            break
+
+            self.assertIsNotNone(placed_action, "c2pa.placed action not found")
+            self.assertIn("parameters", placed_action)
+            self.assertIn("ingredients", placed_action["parameters"])
+            ingredients = placed_action["parameters"]["ingredients"]
+            self.assertEqual(len(ingredients), 2,
+                "c2pa.placed should reference both ingredients")
+
+            url0 = ingredients[0]["url"]
+            url1 = ingredients[1]["url"]
+            self.assertNotEqual(url0, url1,
+                "Each ingredient should have a distinct URL")
+
+            reader.close()
+            output.close()
+        archive1.close()
+        archive2.close()
+        builder.close()
+
+        load_settings('{"builder":{"actions":{"auto_placed_action":{"enabled":false},"auto_opened_action":{"enabled":false},"auto_created_action":{"enabled":false}}}}')
+
 
 class TestStream(unittest.TestCase):
     def setUp(self):