Instantiator Adjustments

docs/SNAP_RECOMMENDATIONS_INTEGRATION.md

@@ -34,6 +34,9 @@ Recommendations script blocks can be placed anywhere on the page and will automa
 
 In this example the `recently-viewed` profile `tag` is set to render inside the `.ss__recs__recently-viewed` element.
 
+> [!IMPORTANT]
+> Each profile entry creates a single controller and API request, regardless of how many DOM elements match its `selector`. If multiple elements match, they all render using the same shared controller and recommendation data. To render different recommendation data in different locations, use separate profile entries.
+
 ## Recommendation Context Variables
 Context variables are set within the script blocks and can be used to set either global or per profile (profile specific) functionality. Variables are used to alter the results displayed by our recommendations and may be required depending on the profile placements in use.
 

packages/snap-preact/src/Instantiators/README.md

@@ -21,6 +21,7 @@ The `RecommendationInstantiator` class handles the targeting and creation of rec
 | `config.batched` | `boolean` | No | Enable batched recommendation requests. |
 | `config.limit` | `number` | No | Default limit for recommendation results. |
 | `config.variants` | `VariantConfig` | No | Configuration for variant handling. |
+| `config.beacon` | `BeaconSettings` | No | Beacon tracking settings. |
 | `config.middleware` | `object` | No | Event middleware configuration. |
 | `config.plugins` | `PluginGrouping[]` | No | Plugin configurations. |
 | `selector` | `string` | No | Custom selector for targeting script elements. Defaults to `'script[type="searchspring/recommend"], script[type="searchspring/personalized-recommendations"]'`. |
@@ -30,7 +31,78 @@ The `RecommendationInstantiator` class handles the targeting and creation of rec
 
 `*` Required if no corresponding service is provided in the constructor
 
-<!-- TODO: Add Examples -->
+## Integration Types
+
+The `RecommendationInstantiator` supports two script block integration styles: **grouped** and **legacy**.
+
+### Grouped Block
+
+The grouped block uses a `script[type="searchspring/recommendations"]` tag containing a `profiles` array. Each entry in `profiles` specifies a `tag` (or `profile`) and a `selector` targeting where the component should render.
+
+```html
+<div class="ss__recs__trending"></div>
+<div class="ss__recs__similar"></div>
+
+<script type="searchspring/recommendations">
+	globals = {
+		products: ["SKU-123"],
+		shopper: { id: "user_abc" },
+	};
+	profiles = [
+		{
+			tag: 'trending',
+			selector: '.ss__recs__trending',
+			options: {
+				limit: 5,
+			},
+		},
+		{
+			tag: 'similar',
+			selector: '.ss__recs__similar',
+		},
+	];
+</script>
+```
+
+> [!IMPORTANT]
+> Each profile entry in the `profiles` array creates exactly **one controller**, regardless of how many DOM elements match the `selector`. If a selector like `.ss__recs__trending` matches three elements, all three will render using the same shared controller. This means a single API request is made per profile, and all matched elements receive the same recommendation data.
+
+### Legacy Block
+
+The legacy block uses individual `script[type="searchspring/recommend"]` tags with a `profile` attribute. Each script tag results in its own controller.
+
+```html
+<script type="searchspring/recommend" profile="trending"></script>
+<script type="searchspring/recommend" profile="similar">
+	product = 'SKU-123';
+</script>
+```
+
+## Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `client` | `Client` | The Searchspring API client instance. |
+| `tracker` | `Tracker` | The tracker instance for analytics. |
+| `logger` | `Logger` | The logger instance. |
+| `controller` | `Record<string, RecommendationController>` | Map of created controllers keyed by controller ID (e.g. `recommend_trending_0`). |
+| `config` | `RecommendationInstantiatorConfig` | The configuration passed to the constructor. |
+| `context` | `ContextVariables` | Merged context from constructor and config. |
+| `targeter` | `DomTargeter` | The DOM targeter instance that finds script block elements. |
+
+## Methods
+
+### `plugin(func, ...args)`
+Registers a plugin to be applied to all controllers created by this instantiator. Plugins registered before controller creation are applied when the controller is created.
+
+### `on(event, ...func)`
+Registers middleware for a specific event (e.g. `beforeSearch`, `afterSearch`, `afterStore`) on all controllers.
+
+### `use(attachments)`
+Registers an `Attachments` object containing plugins and/or middleware to be applied to all controllers.
+
+### `cleanupStaleControllers()`
+Removes controllers whose targeted elements are no longer connected to the DOM. This is called automatically before each new controller is created, but can also be called manually for SPA navigation cleanup.
 
 ## Branching
 Branching allows for branch builds of templates. For production-ready templates, please ensure you are on the repository's default branch (typically `production`) before running `snapfu recs sync`.