From f641856f963241e2c4231ca7e949f02b445165c4 Mon Sep 17 00:00:00 2001
From: Jurriaan Roelofs <jur@dxpr.com>
Date: Wed, 15 Apr 2026 14:18:01 +0200
Subject: [PATCH 1/6] feat: Drupal.rl thin JS API with request batching (#42)

Introduces a shared Drupal.rl transport layer so multiple RL consumers on
the same page produce ~2 requests instead of one per experiment:

- js/rl.js exposes Drupal.rl.decide / turn / reward / flush. Decides
  flush on the next tick (catching every module that registers in
  Drupal.behaviors.attach); turns and rewards flush in a 500 ms window
  and via sendBeacon on visibilitychange / pagehide.
- rl.php collapses the legacy turn/turns/reward/decide form handlers
  into a single action=batch JSON endpoint. ping is preserved for the
  hook_requirements() health check.
- rl_page_attachments() publishes drupalSettings.rl.endpointUrl so
  consumer modules no longer have to compute and attach the URL
  themselves.
- All four consumer modules (rl_example, rl_example_frontend,
  rl_menu_link, rl_page_title) migrated to the Drupal.rl API. The
  broken action=scores call in rl_example_frontend is replaced with
  Drupal.rl.decide().
- README and docs updated to describe the new JS API.
---
 README.md                                     |  39 +--
 docs/rl_project_desc.html                     |  30 +-
 js/rl.js                                      | 261 ++++++++++++++++++
 modules/rl_example/js/rl-example-tracking.js  |  68 ++---
 modules/rl_example/rl_example.libraries.yml   |   2 +
 .../src/Plugin/Block/NewsletterBlock.php      |  54 +---
 .../js/frontend-ab-testing.js                 | 165 +++--------
 .../rl_example_frontend.libraries.yml         |   2 +
 .../src/Plugin/Block/NewsletterBlock.php      |  50 +---
 modules/rl_menu_link/README.md                |   4 +-
 modules/rl_menu_link/js/menu-tracking.js      |  31 +--
 .../rl_menu_link/rl_menu_link.libraries.yml   |   1 +
 modules/rl_menu_link/rl_menu_link.module      |   8 +-
 modules/rl_page_title/README.md               |   5 +-
 modules/rl_page_title/js/title-tracking.js    |  32 +--
 .../rl_page_title/rl_page_title.libraries.yml |   1 +
 modules/rl_page_title/rl_page_title.module    |   6 +-
 rl.libraries.yml                              |   8 +
 rl.module                                     |   7 +
 rl.php                                        | 200 ++++++++++----
 20 files changed, 575 insertions(+), 399 deletions(-)
 create mode 100644 js/rl.js

diff --git a/README.md b/README.md
index 8fbce54..ebda71e 100644
--- a/README.md
+++ b/README.md
@@ -213,27 +213,34 @@ $cache_manager = \Drupal::service('rl.cache_manager');
 $cache_manager->overridePageCacheIfShorter(60); // 60 seconds
 ```
 
-## HTTP Endpoints
+## JavaScript API
 
-### rl.php - Direct Endpoint (Recommended)
-**Use the direct rl.php endpoint for optimal performance:**
+Attach the `rl/api` library to make `Drupal.rl` available. It is a thin transport proxy that coalesces every RL call on the page into a single batched POST to `rl.php`, so N experiments on the same page produce ~2 requests regardless of how many modules are tracking.
 
 ```javascript
-// Record turns (trials) - when content is viewed
-const formData = new FormData();
-formData.append('action', 'turns');
-formData.append('experiment_id', 'abc123');
-formData.append('arm_ids', '1,2,3');
-navigator.sendBeacon('/modules/contrib/rl/rl.php', formData);
-
-// Record reward (success) - when user clicks/converts  
-const rewardData = new FormData();
-rewardData.append('action', 'rewards');
-rewardData.append('experiment_id', 'abc123');
-rewardData.append('arm_id', '1');
-navigator.sendBeacon('/modules/contrib/rl/rl.php', rewardData);
+// Ask for a Thompson Sampling decision - resolves to the winning arm id.
+Drupal.rl.decide('hero_cta', ['v0', 'v1', 'v2']).then(function (armId) {
+  renderVariant(armId);
+});
+
+// Record an impression.
+Drupal.rl.turn('hero_cta', 'v0');
+
+// Record a conversion.
+Drupal.rl.reward('hero_cta', 'v0');
 ```
 
+Decides flush on the next tick so every module that registers during `Drupal.behaviors.attach` shares one request. Turns and rewards flush in a 500 ms window, and buffered events are flushed via `navigator.sendBeacon` on `visibilitychange` / `pagehide` so they survive navigation.
+
+### rl.php endpoint
+
+`rl.php` is the low-level HTTP endpoint `Drupal.rl` talks to. It accepts two actions:
+
+- `action=ping` - liveness check used by `hook_requirements()`.
+- `action=batch` - JSON body used by `Drupal.rl`. See `js/rl.js` for the payload shape.
+
+Direct consumption of `action=batch` without going through `Drupal.rl` is not recommended.
+
 ## Cache Management
 
 RL provides optional cache management for web components:
diff --git a/docs/rl_project_desc.html b/docs/rl_project_desc.html
index 39b6804..05de4ff 100644
--- a/docs/rl_project_desc.html
+++ b/docs/rl_project_desc.html
@@ -62,7 +62,7 @@ <h3>Installation</h3>
 <h4>Verify rl.php Access</h4>
 <p>The RL module includes a <code>.htaccess</code> file that allows direct access to <code>rl.php</code> (following the same pattern as Drupal 11's contrib statistics module). Test that it's working:</p>
 
-<pre><code>curl -X POST -d "action=turns&experiment_id=test&arm_ids=1" http://example.com/modules/contrib/rl/rl.php</code></pre>
+<pre><code>curl -X POST -d "action=ping" http://example.com/modules/contrib/rl/rl.php</code></pre>
 
 <p><strong>If the test fails:</strong></p>
 <ul>
@@ -147,24 +147,22 @@ <h3>API</h3>
 $cache_manager->overridePageCacheIfShorter(60); // 60 seconds
 </code></pre>
 
-<h3>HTTP Endpoints</h3>
+<h3>JavaScript API</h3>
 
-<h4>rl.php - Direct Endpoint (Recommended)</h4>
-<p><strong>Use the direct rl.php endpoint for optimal performance:</strong></p>
+<p>Attach the <code>rl/api</code> library to make <code>Drupal.rl</code> available on the page. It exposes a thin transport layer that coalesces every RL call on the page into a single batched POST to <code>rl.php</code>:</p>
 
-<pre><code>// Record turns (trials) - when content is viewed
-const formData = new FormData();
-formData.append('action', 'turns');
-formData.append('experiment_uuid', 'abc123');
-formData.append('arm_ids', '1,2,3');
-navigator.sendBeacon('/modules/contrib/rl/rl.php', formData);
+<pre><code>// Ask for a Thompson Sampling decision - resolves to the winning arm id.
+Drupal.rl.decide('hero_cta', ['v0', 'v1', 'v2']).then(function (armId) {
+  renderVariant(armId);
+});
 
-// Record reward (success) - when user clicks/converts  
-const rewardData = new FormData();
-rewardData.append('action', 'rewards');
-rewardData.append('experiment_uuid', 'abc123');
-rewardData.append('arm_id', '1');
-navigator.sendBeacon('/modules/contrib/rl/rl.php', rewardData);</code></pre>
+// Record an impression.
+Drupal.rl.turn('hero_cta', 'v0');
+
+// Record a conversion.
+Drupal.rl.reward('hero_cta', 'v0');</code></pre>
+
+<p>Decides flush on the next tick so all modules that register during <code>Drupal.behaviors.attach</code> share one request. Turns and rewards flush in a 500 ms window and on <code>pagehide</code> via <code>navigator.sendBeacon</code>.</p>
 
 <h3>Cache Management</h3>
 
diff --git a/js/rl.js b/js/rl.js
new file mode 100644
index 0000000..a0b81e3
--- /dev/null
+++ b/js/rl.js
@@ -0,0 +1,261 @@
+/**
+ * @file
+ * Thin RL transport proxy with request batching.
+ *
+ * Exposes Drupal.rl.decide(), Drupal.rl.turn(), Drupal.rl.reward(), and
+ * Drupal.rl.flush(). Batches calls into a single POST to rl.php so that
+ * multiple RL-powered features on the same page share one request instead
+ * of each making its own.
+ *
+ * Batching strategy:
+ *   - decide() flushes on the next tick (setTimeout 0), catching every
+ *     module that registers synchronously during Drupal.behaviors.attach.
+ *   - turn() / reward() flush in a 500 ms window to coalesce events that
+ *     arrive as the user interacts with the page.
+ *   - visibilitychange / pagehide flush immediately via navigator.sendBeacon
+ *     so buffered events survive navigation.
+ *
+ * Modelled on Drupal.history in Drupal core, which batches node-view
+ * tracking the same way.
+ *
+ * @namespace
+ */
+
+(function (Drupal, drupalSettings) {
+
+  'use strict';
+
+  var queue = emptyQueue();
+  var timer = null;
+  var timerDelay = null;
+
+  function emptyQueue() {
+    return {
+      decides: Object.create(null),
+      turns: [],
+      rewards: [],
+    };
+  }
+
+  function endpoint() {
+    if (drupalSettings.rl && drupalSettings.rl.endpointUrl) {
+      return drupalSettings.rl.endpointUrl;
+    }
+    return null;
+  }
+
+  function hasPending() {
+    for (var id in queue.decides) {
+      if (Object.prototype.hasOwnProperty.call(queue.decides, id)) {
+        return true;
+      }
+    }
+    return queue.turns.length > 0 || queue.rewards.length > 0;
+  }
+
+  function schedule(delay) {
+    if (timer !== null && timerDelay <= delay) {
+      return;
+    }
+    if (timer !== null) {
+      clearTimeout(timer);
+    }
+    timerDelay = delay;
+    timer = setTimeout(function () {
+      timer = null;
+      timerDelay = null;
+      flush();
+    }, delay);
+  }
+
+  function takeQueue() {
+    var snapshot = queue;
+    queue = emptyQueue();
+    return snapshot;
+  }
+
+  function buildPayload(snapshot) {
+    var decides = [];
+    for (var id in snapshot.decides) {
+      if (Object.prototype.hasOwnProperty.call(snapshot.decides, id)) {
+        decides.push({ id: id, arms: snapshot.decides[id].arms });
+      }
+    }
+    return {
+      decides: decides,
+      turns: snapshot.turns,
+      rewards: snapshot.rewards,
+    };
+  }
+
+  function resolveDecides(snapshot, decisions) {
+    for (var id in snapshot.decides) {
+      if (!Object.prototype.hasOwnProperty.call(snapshot.decides, id)) {
+        continue;
+      }
+      var entry = snapshot.decides[id];
+      var armId = null;
+      if (decisions && decisions[id] && decisions[id].armId) {
+        armId = decisions[id].armId;
+      }
+      // Fallback to the first arm when the server returns no decision
+      // (unregistered experiment, missing data, etc.) so callers always
+      // get a usable variant.
+      if (!armId) {
+        armId = entry.arms[0];
+      }
+      entry.resolvers.forEach(function (resolver) {
+        resolver.resolve(armId);
+      });
+    }
+  }
+
+  function rejectDecides(snapshot, reason) {
+    for (var id in snapshot.decides) {
+      if (!Object.prototype.hasOwnProperty.call(snapshot.decides, id)) {
+        continue;
+      }
+      snapshot.decides[id].resolvers.forEach(function (resolver) {
+        resolver.reject(reason);
+      });
+    }
+  }
+
+  function batchUrl(url) {
+    return url + (url.indexOf('?') === -1 ? '?' : '&') + 'action=batch';
+  }
+
+  function flush() {
+    if (!hasPending()) {
+      return;
+    }
+    var url = endpoint();
+    if (!url) {
+      var dropped = takeQueue();
+      rejectDecides(dropped, new Error('Drupal.rl: endpointUrl not set'));
+      return;
+    }
+    var snapshot = takeQueue();
+    var body = JSON.stringify(buildPayload(snapshot));
+
+    fetch(batchUrl(url), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: body,
+      credentials: 'same-origin',
+      keepalive: true,
+    })
+      .then(function (response) {
+        if (!response.ok) {
+          rejectDecides(snapshot, new Error('Drupal.rl: HTTP ' + response.status));
+          return null;
+        }
+        return response.json();
+      })
+      .then(function (json) {
+        if (json) {
+          resolveDecides(snapshot, json.decisions || {});
+        }
+      })
+      .catch(function (err) {
+        rejectDecides(snapshot, err);
+      });
+  }
+
+  function flushBeacon() {
+    if (!hasPending()) {
+      return;
+    }
+    var url = endpoint();
+    if (!url) {
+      return;
+    }
+    var snapshot = takeQueue();
+    var body = JSON.stringify(buildPayload(snapshot));
+
+    if ('sendBeacon' in navigator) {
+      var blob = new Blob([body], { type: 'application/json' });
+      navigator.sendBeacon(batchUrl(url), blob);
+    }
+    // Decide promises cannot be fulfilled once the page is unloading, so
+    // reject any that happen to still be buffered. Callers on a page that
+    // is going away do not need the answer.
+    rejectDecides(snapshot, new Error('Drupal.rl: page unloading'));
+  }
+
+  Drupal.rl = {
+
+    /**
+     * Request a Thompson Sampling decision for an experiment.
+     *
+     * @param {string} experimentId
+     *   The pre-registered experiment id.
+     * @param {Array<string>} armIds
+     *   The arm ids the caller is offering. The winning arm id is returned
+     *   unchanged so the caller can map it back to its own variant table.
+     *
+     * @return {Promise<string>}
+     *   Resolves to the winning arm id. Falls back to armIds[0] when the
+     *   server cannot provide a decision.
+     */
+    decide: function (experimentId, armIds) {
+      return new Promise(function (resolve, reject) {
+        var entry = queue.decides[experimentId];
+        if (!entry) {
+          entry = queue.decides[experimentId] = {
+            arms: armIds.slice(),
+            resolvers: [],
+          };
+        }
+        entry.resolvers.push({ resolve: resolve, reject: reject });
+        schedule(0);
+      });
+    },
+
+    /**
+     * Record an impression for a variant.
+     *
+     * @param {string} experimentId
+     * @param {string} armId
+     */
+    turn: function (experimentId, armId) {
+      queue.turns.push({ id: experimentId, arm: armId });
+      schedule(500);
+    },
+
+    /**
+     * Record a conversion for a variant.
+     *
+     * @param {string} experimentId
+     * @param {string} armId
+     */
+    reward: function (experimentId, armId) {
+      queue.rewards.push({ id: experimentId, arm: armId });
+      schedule(500);
+    },
+
+    /**
+     * Force an immediate flush of the buffered queue.
+     */
+    flush: function () {
+      if (timer !== null) {
+        clearTimeout(timer);
+        timer = null;
+        timerDelay = null;
+      }
+      flush();
+    },
+
+  };
+
+  // Flush buffered events on navigation so turns and rewards are not lost.
+  // visibilitychange covers tab switches and mobile navigation; pagehide
+  // covers desktop back/forward cache restoration.
+  document.addEventListener('visibilitychange', function () {
+    if (document.visibilityState === 'hidden') {
+      flushBeacon();
+    }
+  });
+  window.addEventListener('pagehide', flushBeacon);
+
+})(Drupal, drupalSettings);
diff --git a/modules/rl_example/js/rl-example-tracking.js b/modules/rl_example/js/rl-example-tracking.js
index d0a1ff9..5809d7a 100644
--- a/modules/rl_example/js/rl-example-tracking.js
+++ b/modules/rl_example/js/rl-example-tracking.js
@@ -1,63 +1,35 @@
+/**
+ * @file
+ * Records a turn for the newsletter form when it enters the viewport.
+ *
+ * Critical for forms in footers that are not immediately visible. The
+ * reward is recorded server-side in the AJAX submit callback; this file
+ * only needs to register the impression.
+ */
+
 (function (Drupal, drupalSettings, once) {
+
   'use strict';
 
-  /**
-   * Tracks when the newsletter form becomes visible in the viewport.
-   * This is critical for forms in footers that aren't immediately visible.
-   */
   Drupal.behaviors.rlExampleViewportTracking = {
-    attach: function (context, settings) {
-      // Only proceed if we have the necessary settings
-      if (!settings.rlExample || !settings.rlExample.tracking) {
+    attach: function (context) {
+      var tracking = drupalSettings.rlExample && drupalSettings.rlExample.tracking;
+      if (!tracking) {
         return;
       }
 
-      const trackingData = settings.rlExample.tracking;
-
-      // Use once() to ensure we only process each form once
-      once('rl-example-viewport', '.rl-example-newsletter-form', context).forEach(function(form) {
-        // Create an IntersectionObserver to detect when form enters viewport
-        const observer = new IntersectionObserver(function(entries) {
-          entries.forEach(function(entry) {
+      once('rl-example-viewport', '.rl-example-newsletter-form', context).forEach(function (form) {
+        var observer = new IntersectionObserver(function (entries) {
+          entries.forEach(function (entry) {
             if (entry.isIntersecting) {
-              // Form is now visible - record the turn
-              const formData = new FormData();
-              formData.append('action', 'turns');
-              formData.append('experiment_id', trackingData.experimentId);
-              formData.append('arm_ids', trackingData.armId);
-              
-              // Send the turn signal
-              navigator.sendBeacon(trackingData.rlEndpointUrl, formData);
-              
-              // Disconnect observer after recording turn
+              Drupal.rl.turn(tracking.experimentId, tracking.armId);
               observer.disconnect();
             }
           });
-        }, {
-          // Trigger when 100% of the form is visible
-          threshold: 1.0
-        });
-
-        // Start observing the form
+        }, { threshold: 1.0 });
         observer.observe(form);
       });
-
-      // Example: Reward tracking via JavaScript (commented out)
-      // In this module, we handle rewards in the PHP submitCallback instead.
-      // Uncomment and modify this if you need client-side reward tracking:
-      //
-      // once('rl-example-reward', '.rl-example-newsletter-form button[type="submit"]', context).forEach(function(button) {
-      //   button.addEventListener('click', function(e) {
-      //     // Send reward signal to RL
-      //     const rewardData = new FormData();
-      //     rewardData.append('action', 'reward');
-      //     rewardData.append('experiment_id', trackingData.experimentId);
-      //     rewardData.append('arm_id', trackingData.armId);
-      //     
-      //     navigator.sendBeacon(trackingData.rlEndpointUrl, rewardData);
-      //   });
-      // });
-    }
+    },
   };
 
-})(Drupal, drupalSettings, once);
\ No newline at end of file
+})(Drupal, drupalSettings, once);
diff --git a/modules/rl_example/rl_example.libraries.yml b/modules/rl_example/rl_example.libraries.yml
index 576685c..c59d6af 100644
--- a/modules/rl_example/rl_example.libraries.yml
+++ b/modules/rl_example/rl_example.libraries.yml
@@ -3,4 +3,6 @@ tracking:
     js/rl-example-tracking.js: {}
   dependencies:
     - core/drupal
+    - core/drupalSettings
     - core/once
+    - rl/api
diff --git a/modules/rl_example/src/Plugin/Block/NewsletterBlock.php b/modules/rl_example/src/Plugin/Block/NewsletterBlock.php
index ffa0b94..7b910ae 100644
--- a/modules/rl_example/src/Plugin/Block/NewsletterBlock.php
+++ b/modules/rl_example/src/Plugin/Block/NewsletterBlock.php
@@ -2,17 +2,15 @@
 
 namespace Drupal\rl_example\Plugin\Block;
 
+use Drupal\Core\Ajax\AjaxResponse;
+use Drupal\Core\Ajax\MessageCommand;
 use Drupal\Core\Block\BlockBase;
-use Drupal\Core\Extension\ModuleExtensionList;
 use Drupal\Core\Messenger\MessengerInterface;
 use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
 use Drupal\rl\Registry\ExperimentRegistryInterface;
 use Drupal\rl\Service\CacheManager;
 use Drupal\rl\Service\ExperimentManagerInterface;
 use Symfony\Component\DependencyInjection\ContainerInterface;
-use Symfony\Component\HttpFoundation\RequestStack;
-use Drupal\Core\Ajax\AjaxResponse;
-use Drupal\Core\Ajax\MessageCommand;
 
 /**
  * Provides a newsletter signup block with A/B tested button text.
@@ -52,20 +50,6 @@ class NewsletterBlock extends BlockBase implements ContainerFactoryPluginInterfa
    */
   protected $cacheManager;
 
-  /**
-   * The module extension list service.
-   *
-   * @var \Drupal\Core\Extension\ModuleExtensionList
-   */
-  protected $moduleExtensionList;
-
-  /**
-   * The request stack service.
-   *
-   * @var \Symfony\Component\HttpFoundation\RequestStack
-   */
-  protected $requestStack;
-
   /**
    * The experiment ID.
    *
@@ -85,25 +69,6 @@ class NewsletterBlock extends BlockBase implements ContainerFactoryPluginInterfa
 
   /**
    * Constructs a NewsletterBlock object.
-   *
-   * @param array $configuration
-   *   A configuration array containing information about the plugin instance.
-   * @param string $plugin_id
-   *   The plugin ID for the plugin instance.
-   * @param mixed $plugin_definition
-   *   The plugin implementation definition.
-   * @param \Drupal\rl\Service\ExperimentManagerInterface $experiment_manager
-   *   The RL experiment manager.
-   * @param \Drupal\rl\Registry\ExperimentRegistryInterface $experiment_registry
-   *   The RL experiment registry.
-   * @param \Drupal\Core\Messenger\MessengerInterface $messenger
-   *   The messenger service.
-   * @param \Drupal\rl\Service\CacheManager $cache_manager
-   *   The RL cache manager.
-   * @param \Drupal\Core\Extension\ModuleExtensionList $module_extension_list
-   *   The module extension list service.
-   * @param \Symfony\Component\HttpFoundation\RequestStack $request_stack
-   *   The request stack service.
    */
   public function __construct(
     array $configuration,
@@ -113,16 +78,12 @@ public function __construct(
     ExperimentRegistryInterface $experiment_registry,
     MessengerInterface $messenger,
     CacheManager $cache_manager,
-    ModuleExtensionList $module_extension_list,
-    RequestStack $request_stack,
   ) {
     parent::__construct($configuration, $plugin_id, $plugin_definition);
     $this->experimentManager = $experiment_manager;
     $this->experimentRegistry = $experiment_registry;
     $this->messenger = $messenger;
     $this->cacheManager = $cache_manager;
-    $this->moduleExtensionList = $module_extension_list;
-    $this->requestStack = $request_stack;
 
     // Use deterministic ID for this specific experiment.
     $this->experimentId = 'rl_example-newsletter_button';
@@ -148,8 +109,6 @@ public static function create(ContainerInterface $container, array $configuratio
       $container->get('rl.experiment_registry'),
       $container->get('messenger'),
       $container->get('rl.cache_manager'),
-      $container->get('extension.list.module'),
-      $container->get('request_stack')
     );
   }
 
@@ -194,16 +153,13 @@ public function build() {
       ],
     ];
 
-    // Build correct endpoint URL for rl.php.
-    $rl_path = $this->moduleExtensionList->getPath('rl');
-    $base_path = $this->requestStack->getCurrentRequest()->getBasePath();
-
-    // Attach JavaScript library for viewport tracking.
+    // Attach JavaScript library for viewport tracking. The rl.php endpoint
+    // URL comes from drupalSettings.rl.endpointUrl, published by
+    // rl_page_attachments() whenever the rl/api library is loaded.
     $form['#attached']['library'][] = 'rl_example/tracking';
     $form['#attached']['drupalSettings']['rlExample']['tracking'] = [
       'experimentId' => $this->experimentId,
       'armId' => $best_id,
-      'rlEndpointUrl' => "{$base_path}/{$rl_path}/rl.php",
     ];
 
     // Override page cache if block cache is shorter than site cache.
diff --git a/modules/rl_example_frontend/js/frontend-ab-testing.js b/modules/rl_example_frontend/js/frontend-ab-testing.js
index c57f7cb..915ff62 100644
--- a/modules/rl_example_frontend/js/frontend-ab-testing.js
+++ b/modules/rl_example_frontend/js/frontend-ab-testing.js
@@ -1,146 +1,65 @@
+/**
+ * @file
+ * Frontend A/B testing for newsletter signup button.
+ *
+ * Uses Drupal.rl as the transport layer: one decide call resolves the
+ * winning variant, one turn call fires when the form enters the viewport,
+ * one reward call fires when the submit button is clicked. Drupal.rl
+ * coalesces all of these with any other RL calls on the page into a
+ * single POST.
+ */
+
 (function (Drupal, drupalSettings, once) {
+
   'use strict';
 
-  /**
-   * Frontend A/B testing for newsletter signup button.
-   * 
-   * This approach eliminates cache complexity by:
-   * 1. Fetching Thompson sampling scores via AJAX on page load
-   * 2. Overriding button text based on best performing arm
-   * 3. Tracking turns via IntersectionObserver 
-   * 4. Tracking rewards via click handlers
-   */
   Drupal.behaviors.rlExampleFrontendABTesting = {
-    attach: function (context, settings) {
-      // Only proceed if we have the necessary settings
-      if (!settings.rlExampleFrontend) {
+    attach: function (context) {
+      var config = drupalSettings.rlExampleFrontend;
+      if (!config) {
         return;
       }
 
-      const config = settings.rlExampleFrontend;
-      let selectedArmId = null;
-
-      // Use once() to ensure we only process each form once
-      once('rl-frontend-ab', '.rl-example-frontend-newsletter-form', context).forEach(function(form) {
-        
-        // Step 1: Get Thompson sampling scores and select best arm
-        fetchThompsonScores(config.experimentId, Object.keys(config.buttonTexts))
-          .then(function(scores) {
-            // Find the arm with highest score
-            let bestScore = -1;
-            let bestArmId = null;
-            
-            for (const armId in scores) {
-              if (scores[armId] > bestScore) {
-                bestScore = scores[armId];
-                bestArmId = armId;
-              }
+      once('rl-frontend-ab', '.rl-example-frontend-newsletter-form', context).forEach(function (form) {
+        Drupal.rl.decide(config.experimentId, Object.keys(config.buttonTexts))
+          .then(function (armId) {
+            if (!config.buttonTexts[armId]) {
+              return;
             }
-            
-            if (bestArmId && config.buttonTexts[bestArmId]) {
-              selectedArmId = bestArmId;
-              
-              // Step 2: Override button text with selected variation
-              const submitButton = form.querySelector('input[type="submit"]');
-              if (submitButton) {
-                submitButton.value = config.buttonTexts[bestArmId];
-              }
-              
-              // Step 3: Set up intersection observer for turn tracking
-              setupTurnTracking(form, config, selectedArmId);
-              
-              // Step 4: Set up click handler for reward tracking
-              setupRewardTracking(form, config, selectedArmId);
+            var submitButton = form.querySelector('input[type="submit"]');
+            if (submitButton) {
+              submitButton.value = config.buttonTexts[armId];
             }
+            observeTurn(form, config.experimentId, armId);
+            bindReward(form, config.experimentId, armId);
+          })
+          .catch(function () {
+            // Leave the default button text in place on decide failure.
           });
       });
 
-      /**
-       * Fetch Thompson sampling scores from RL system
-       */
-      function fetchThompsonScores(experimentId, armIds) {
-        return new Promise(function(resolve, reject) {
-          // Make AJAX request to get Thompson sampling scores
-          const xhr = new XMLHttpRequest();
-          xhr.open('POST', config.rlEndpointUrl);
-          xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
-          
-          xhr.onload = function() {
-            if (xhr.status === 200) {
-              try {
-                const response = JSON.parse(xhr.responseText);
-                if (response.scores) {
-                  resolve(response.scores);
-                } else {
-                  reject('No scores in response');
-                }
-              } catch (e) {
-                reject('Invalid JSON response');
-              }
-            } else {
-              reject('HTTP ' + xhr.status);
-            }
-          };
-          
-          xhr.onerror = function() {
-            reject('Network error');
-          };
-          
-          // Send request for Thompson scores
-          const params = 'action=scores&experiment_id=' + encodeURIComponent(experimentId) + 
-                        '&arm_ids=' + encodeURIComponent(armIds.join(','));
-          xhr.send(params);
-        });
-      }
-
-      /**
-       * Set up intersection observer for turn tracking
-       */
-      function setupTurnTracking(form, config, armId) {
-        const observer = new IntersectionObserver(function(entries) {
-          entries.forEach(function(entry) {
+      function observeTurn(form, experimentId, armId) {
+        var observer = new IntersectionObserver(function (entries) {
+          entries.forEach(function (entry) {
             if (entry.isIntersecting) {
-              // Form is now visible - record the turn
-              const formData = new FormData();
-              formData.append('action', 'turns');
-              formData.append('experiment_id', config.experimentId);
-              formData.append('arm_ids', armId);
-              
-              // Send the turn signal
-              navigator.sendBeacon(config.rlEndpointUrl, formData);
-              
-              // Disconnect observer after recording turn
+              Drupal.rl.turn(experimentId, armId);
               observer.disconnect();
             }
           });
-        }, {
-          // Trigger when 50% of the form is visible
-          threshold: 0.5
-        });
-
-        // Start observing the form
+        }, { threshold: 0.5 });
         observer.observe(form);
       }
 
-      /**
-       * Set up click handler for reward tracking
-       */
-      function setupRewardTracking(form, config, armId) {
-        const submitButton = form.querySelector('input[type="submit"]');
-        if (submitButton) {
-          submitButton.addEventListener('click', function(e) {
-            // Send reward signal to RL - user clicked the button
-            const formData = new FormData();
-            formData.append('action', 'rewards');
-            formData.append('experiment_id', config.experimentId);
-            formData.append('arm_id', armId);
-            
-            // Use sendBeacon for non-blocking send
-            navigator.sendBeacon(config.rlEndpointUrl, formData);
-          });
+      function bindReward(form, experimentId, armId) {
+        var submitButton = form.querySelector('input[type="submit"]');
+        if (!submitButton) {
+          return;
         }
+        submitButton.addEventListener('click', function () {
+          Drupal.rl.reward(experimentId, armId);
+        });
       }
-    }
+    },
   };
 
-})(Drupal, drupalSettings, once);
\ No newline at end of file
+})(Drupal, drupalSettings, once);
diff --git a/modules/rl_example_frontend/rl_example_frontend.libraries.yml b/modules/rl_example_frontend/rl_example_frontend.libraries.yml
index d328355..4bbb76c 100644
--- a/modules/rl_example_frontend/rl_example_frontend.libraries.yml
+++ b/modules/rl_example_frontend/rl_example_frontend.libraries.yml
@@ -3,4 +3,6 @@ frontend_ab_testing:
     js/frontend-ab-testing.js: {}
   dependencies:
     - core/drupal
+    - core/drupalSettings
     - core/once
+    - rl/api
diff --git a/modules/rl_example_frontend/src/Plugin/Block/NewsletterBlock.php b/modules/rl_example_frontend/src/Plugin/Block/NewsletterBlock.php
index cefcd33..d8676ee 100644
--- a/modules/rl_example_frontend/src/Plugin/Block/NewsletterBlock.php
+++ b/modules/rl_example_frontend/src/Plugin/Block/NewsletterBlock.php
@@ -2,15 +2,13 @@
 
 namespace Drupal\rl_example_frontend\Plugin\Block;
 
+use Drupal\Core\Ajax\AjaxResponse;
+use Drupal\Core\Ajax\MessageCommand;
 use Drupal\Core\Block\BlockBase;
-use Drupal\Core\Extension\ModuleExtensionList;
 use Drupal\Core\Messenger\MessengerInterface;
 use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
 use Drupal\rl\Registry\ExperimentRegistryInterface;
 use Symfony\Component\DependencyInjection\ContainerInterface;
-use Symfony\Component\HttpFoundation\RequestStack;
-use Drupal\Core\Ajax\AjaxResponse;
-use Drupal\Core\Ajax\MessageCommand;
 
 /**
  * Provides a newsletter signup block with frontend A/B tested button text.
@@ -36,20 +34,6 @@ class NewsletterBlock extends BlockBase implements ContainerFactoryPluginInterfa
    */
   protected $messenger;
 
-  /**
-   * The module extension list service.
-   *
-   * @var \Drupal\Core\Extension\ModuleExtensionList
-   */
-  protected $moduleExtensionList;
-
-  /**
-   * The request stack service.
-   *
-   * @var \Symfony\Component\HttpFoundation\RequestStack
-   */
-  protected $requestStack;
-
   /**
    * The experiment ID.
    *
@@ -70,21 +54,6 @@ class NewsletterBlock extends BlockBase implements ContainerFactoryPluginInterfa
 
   /**
    * Constructs a NewsletterBlock object.
-   *
-   * @param array $configuration
-   *   A configuration array containing information about the plugin instance.
-   * @param string $plugin_id
-   *   The plugin ID for the plugin instance.
-   * @param mixed $plugin_definition
-   *   The plugin implementation definition.
-   * @param \Drupal\rl\Registry\ExperimentRegistryInterface $experiment_registry
-   *   The RL experiment registry.
-   * @param \Drupal\Core\Messenger\MessengerInterface $messenger
-   *   The messenger service.
-   * @param \Drupal\Core\Extension\ModuleExtensionList $module_extension_list
-   *   The module extension list service.
-   * @param \Symfony\Component\HttpFoundation\RequestStack $request_stack
-   *   The request stack service.
    */
   public function __construct(
     array $configuration,
@@ -92,14 +61,10 @@ public function __construct(
     $plugin_definition,
     ExperimentRegistryInterface $experiment_registry,
     MessengerInterface $messenger,
-    ModuleExtensionList $module_extension_list,
-    RequestStack $request_stack,
   ) {
     parent::__construct($configuration, $plugin_id, $plugin_definition);
     $this->experimentRegistry = $experiment_registry;
     $this->messenger = $messenger;
-    $this->moduleExtensionList = $module_extension_list;
-    $this->requestStack = $request_stack;
 
     // Use deterministic ID for this specific experiment.
     $this->experimentId = 'rl_example_frontend-newsletter_button';
@@ -123,8 +88,6 @@ public static function create(ContainerInterface $container, array $configuratio
       $plugin_definition,
       $container->get('rl.experiment_registry'),
       $container->get('messenger'),
-      $container->get('extension.list.module'),
-      $container->get('request_stack')
     );
   }
 
@@ -154,16 +117,13 @@ public function build() {
       ],
     ];
 
-    // Build correct endpoint URL for rl.php.
-    $rl_path = $this->moduleExtensionList->getPath('rl');
-    $base_path = $this->requestStack->getCurrentRequest()->getBasePath();
-
-    // Attach JavaScript library and settings for frontend A/B testing.
+    // Attach JavaScript library and settings for frontend A/B testing. The
+    // rl.php endpoint URL comes from drupalSettings.rl.endpointUrl, which
+    // rl_page_attachments() publishes when the rl/api library is loaded.
     $form['#attached']['library'][] = 'rl_example_frontend/frontend_ab_testing';
     $form['#attached']['drupalSettings']['rlExampleFrontend'] = [
       'experimentId' => $this->experimentId,
       'buttonTexts' => $this->buttonTexts,
-      'rlEndpointUrl' => "{$base_path}/{$rl_path}/rl.php",
     ];
 
     return $form;
diff --git a/modules/rl_menu_link/README.md b/modules/rl_menu_link/README.md
index 4513702..ba6cfc4 100644
--- a/modules/rl_menu_link/README.md
+++ b/modules/rl_menu_link/README.md
@@ -58,7 +58,9 @@ Same model as the Redirect module.
    listener to record a reward when the user clicks. Each visit and each
    click is its own event - there is no per-session cap, so repeat
    visitors do not depress the conversion signal.
-4. Both events are POSTed via `navigator.sendBeacon()` to `rl.php`.
+4. Both events are dispatched through `Drupal.rl` (the shared transport
+   proxy in `rl/api`), which batches them with any other RL calls on the
+   page before POSTing to `rl.php`.
 
 ### UX flows
 
diff --git a/modules/rl_menu_link/js/menu-tracking.js b/modules/rl_menu_link/js/menu-tracking.js
index c7d12a3..62873ce 100644
--- a/modules/rl_menu_link/js/menu-tracking.js
+++ b/modules/rl_menu_link/js/menu-tracking.js
@@ -2,13 +2,13 @@
  * @file
  * Client-side tracking for RL Menu Link experiments.
  *
- * Records a turn (impression) when a tracked menu link enters the viewport,
- * and a reward when the user clicks the link. Tracked anchors are identified
- * by data-rl-ml-experiment-id and data-rl-ml-arm-id attributes injected by
- * the preprocess_menu hook.
+ * Records a turn when a tracked menu link enters the viewport and a reward
+ * when the user clicks the link. Tracked anchors are identified by
+ * data-rl-ml-experiment-id and data-rl-ml-arm-id attributes injected by the
+ * preprocess_menu hook.
  *
  * Each click on a tracked link records a reward. There is no per-session
- * cap, so repeated clicks during the same session each count - this keeps
+ * cap so repeated clicks during the same session each count - this keeps
  * the conversion signal Thompson Sampling sees unbiased across visits.
  *
  * Per-page-load dedupe is provided by once() and a per-anchor data attribute
@@ -22,11 +22,6 @@
 
   Drupal.behaviors.rlMenuLinkTracking = {
     attach: function (context) {
-      if (!drupalSettings.rlMenuLink || !drupalSettings.rlMenuLink.rlEndpointUrl) {
-        return;
-      }
-
-      var endpointUrl = drupalSettings.rlMenuLink.rlEndpointUrl;
       var anchors = once('rl-menu-link-tracking', 'a[data-rl-ml-experiment-id]', context);
 
       anchors.forEach(function (anchor) {
@@ -43,14 +38,14 @@
             entries.forEach(function (entry) {
               if (entry.isIntersecting && !entry.target.dataset.rlMlTracked) {
                 entry.target.dataset.rlMlTracked = '1';
-                _send('turn', experimentId, armId);
+                Drupal.rl.turn(experimentId, armId);
               }
             });
           }, { threshold: 0.1 });
           observer.observe(anchor);
         }
         else {
-          _send('turn', experimentId, armId);
+          Drupal.rl.turn(experimentId, armId);
         }
 
         // Reward tracking on click. No sessionStorage cap; each click is a
@@ -61,7 +56,7 @@
             return;
           }
           anchor.dataset.rlMlClicked = '1';
-          _send('reward', experimentId, armId);
+          Drupal.rl.reward(experimentId, armId);
           // Clear the flag after the click event finishes propagating, so a
           // second click later in the same page load can also be recorded.
           window.setTimeout(function () {
@@ -69,15 +64,7 @@
           }, 0);
         });
       });
-
-      function _send(action, experimentId, armId) {
-        var data = new FormData();
-        data.append('action', action);
-        data.append('experiment_id', experimentId);
-        data.append('arm_id', armId);
-        navigator.sendBeacon(endpointUrl, data);
-      }
-    }
+    },
   };
 
 })(Drupal, drupalSettings, once);
diff --git a/modules/rl_menu_link/rl_menu_link.libraries.yml b/modules/rl_menu_link/rl_menu_link.libraries.yml
index 91c14e2..37f07a1 100644
--- a/modules/rl_menu_link/rl_menu_link.libraries.yml
+++ b/modules/rl_menu_link/rl_menu_link.libraries.yml
@@ -5,3 +5,4 @@ tracking:
     - core/drupal
     - core/drupalSettings
     - core/once
+    - rl/api
diff --git a/modules/rl_menu_link/rl_menu_link.module b/modules/rl_menu_link/rl_menu_link.module
index d3949e3..c185fb3 100644
--- a/modules/rl_menu_link/rl_menu_link.module
+++ b/modules/rl_menu_link/rl_menu_link.module
@@ -50,12 +50,10 @@ function rl_menu_link_preprocess_menu(array &$variables) {
   $variables['#cache']['tags'][] = 'rl_menu_link:all';
 
   if (!empty($touched_plugin_ids)) {
-    $rl_path = \Drupal::service('extension.list.module')->getPath('rl');
-    $base_path = \Drupal::request()->getBasePath();
+    // The rl.php endpoint URL comes from drupalSettings.rl.endpointUrl,
+    // published by rl_page_attachments() whenever the rl/api library is
+    // loaded.
     $variables['#attached']['library'][] = 'rl_menu_link/tracking';
-    $variables['#attached']['drupalSettings']['rlMenuLink'] = [
-      'rlEndpointUrl' => $base_path . '/' . $rl_path . '/rl.php',
-    ];
     // Add per-plugin-id tags so each experiment can invalidate the menus
     // that contain its specific link.
     foreach ($touched_plugin_ids as $plugin_id) {
diff --git a/modules/rl_page_title/README.md b/modules/rl_page_title/README.md
index 0a95a31..7302a13 100644
--- a/modules/rl_page_title/README.md
+++ b/modules/rl_page_title/README.md
@@ -64,8 +64,9 @@ analytics. This matches how Redirect handles multilingual.
 4. `js/title-tracking.js` records a turn (impression) on page load and a
    reward 10 seconds later (a bounce-rate proxy: if the user is still on the
    page after 10 seconds, the variant kept them).
-5. Both events are POSTed via `navigator.sendBeacon()` to `rl.php`, the
-   parent RL module's tracking endpoint.
+5. Both events are dispatched through `Drupal.rl` (the shared transport
+   proxy in `rl/api`), which batches them with any other RL calls on the
+   page before POSTing to `rl.php`.
 
 ### UX flows
 
diff --git a/modules/rl_page_title/js/title-tracking.js b/modules/rl_page_title/js/title-tracking.js
index 8af4d30..fa3e84a 100644
--- a/modules/rl_page_title/js/title-tracking.js
+++ b/modules/rl_page_title/js/title-tracking.js
@@ -2,13 +2,13 @@
  * @file
  * Client-side tracking for RL Page Title experiments.
  *
- * Records a turn (impression) on page load and a reward after the user has
- * stayed on the page for 10 seconds (a bounce-rate proxy).
+ * Records a turn on page load and a reward after the user has stayed on the
+ * page for 10 seconds (a bounce-rate proxy).
  *
- * Each page load records exactly one turn and (if the user stays long enough)
- * one reward. There is no per-session dedupe - every visit is its own event.
- * That keeps the conversion rate observed by Thompson Sampling unbiased
- * across repeated visits.
+ * Each page load records exactly one turn and (if the user stays long
+ * enough) one reward. There is no per-session dedupe: every visit is its
+ * own event. That keeps the conversion rate observed by Thompson Sampling
+ * unbiased across repeated visits.
  *
  * Per-page-load dedupe is provided by once() and a window-scoped flag so we
  * cannot record more than one event for the same arm on the same page load
@@ -29,34 +29,24 @@
         var settings = drupalSettings.rlPageTitle;
         var experimentId = settings.experimentId;
         var armId = settings.armId;
-        var endpointUrl = settings.rlEndpointUrl;
 
-        // Record turn (impression).
-        var turnData = new FormData();
-        turnData.append('action', 'turn');
-        turnData.append('experiment_id', experimentId);
-        turnData.append('arm_id', armId);
-        navigator.sendBeacon(endpointUrl, turnData);
+        Drupal.rl.turn(experimentId, armId);
 
         // Record reward after 10 seconds (bounce-rate proxy). No
         // sessionStorage gate: every page load that crosses the threshold
         // emits a reward, which is the correct signal for Thompson Sampling.
-        // The window-scoped flag below only prevents duplicate rewards from
-        // the same page load (e.g., if attachBehaviors fires twice).
+        // The window-scoped flag only prevents duplicate rewards from the
+        // same page load (e.g., if attachBehaviors fires twice).
         var pageLoadFlag = '__rl_pt_rewarded_' + experimentId + '_' + armId;
         setTimeout(function () {
           if (window[pageLoadFlag]) {
             return;
           }
           window[pageLoadFlag] = true;
-          var rewardData = new FormData();
-          rewardData.append('action', 'reward');
-          rewardData.append('experiment_id', experimentId);
-          rewardData.append('arm_id', armId);
-          navigator.sendBeacon(endpointUrl, rewardData);
+          Drupal.rl.reward(experimentId, armId);
         }, 10000);
       });
-    }
+    },
   };
 
 })(Drupal, drupalSettings, once);
diff --git a/modules/rl_page_title/rl_page_title.libraries.yml b/modules/rl_page_title/rl_page_title.libraries.yml
index e78c6bd..16d0ce3 100644
--- a/modules/rl_page_title/rl_page_title.libraries.yml
+++ b/modules/rl_page_title/rl_page_title.libraries.yml
@@ -5,3 +5,4 @@ tracking:
     - core/drupal
     - core/drupalSettings
     - core/once
+    - rl/api
diff --git a/modules/rl_page_title/rl_page_title.module b/modules/rl_page_title/rl_page_title.module
index 9cfdba1..06ef91e 100644
--- a/modules/rl_page_title/rl_page_title.module
+++ b/modules/rl_page_title/rl_page_title.module
@@ -200,14 +200,12 @@ function rl_page_title_page_attachments(array &$attachments) {
     return;
   }
 
-  $rl_path = \Drupal::service('extension.list.module')->getPath('rl');
-  $base_path = \Drupal::request()->getBasePath();
-
+  // The rl.php endpoint URL comes from drupalSettings.rl.endpointUrl,
+  // published by rl_page_attachments() whenever the rl/api library is loaded.
   $attachments['#attached']['library'][] = 'rl_page_title/tracking';
   $attachments['#attached']['drupalSettings']['rlPageTitle'] = [
     'experimentId' => $result['experiment_id'],
     'armId' => $result['arm_id'],
-    'rlEndpointUrl' => $base_path . '/' . $rl_path . '/rl.php',
   ];
 }
 
diff --git a/rl.libraries.yml b/rl.libraries.yml
index c545d49..d254009 100644
--- a/rl.libraries.yml
+++ b/rl.libraries.yml
@@ -1,3 +1,11 @@
+api:
+  version: 1.0
+  js:
+    js/rl.js: {}
+  dependencies:
+    - core/drupal
+    - core/drupalSettings
+
 experiment-highlight:
   version: 1.0
   css:
diff --git a/rl.module b/rl.module
index 97a350d..937ce1f 100644
--- a/rl.module
+++ b/rl.module
@@ -48,6 +48,13 @@ function rl_page_attachments(array &$attachments) {
   if (\Drupal::currentUser()->hasPermission('view rl reports')) {
     $attachments['#attached']['library'][] = 'rl/experiment-highlight';
   }
+
+  // Publish the rl.php endpoint URL to drupalSettings so any page that
+  // attaches the rl/api library can use Drupal.rl without each consumer
+  // module recomputing the URL.
+  $rl_path = \Drupal::service('extension.list.module')->getPath('rl');
+  $base_path = \Drupal::request()->getBasePath();
+  $attachments['#attached']['drupalSettings']['rl']['endpointUrl'] = $base_path . '/' . $rl_path . '/rl.php';
 }
 
 /**
diff --git a/rl.php b/rl.php
index 2b49102..ca5dcaa 100644
--- a/rl.php
+++ b/rl.php
@@ -2,34 +2,54 @@
 
 /**
  * @file
- * Handles RL experiment tracking via AJAX with minimal bootstrap.
+ * Handles RL experiment tracking via a minimal Drupal bootstrap.
  *
  * Following the statistics.php architecture for optimal performance.
- * Updated for Drupal 10/11 compatibility.
+ *
+ * Two actions are supported:
+ *   - ping: liveness check, no experiment touched.
+ *   - batch: JSON POST body used by Drupal.rl on the client side. Carries
+ *     multiple decide / turn / reward events for potentially several
+ *     experiments in a single request. See the docblock on
+ *     handle_batch_request() below for the payload shape.
+ *
+ * The legacy action=turn / action=turns / action=reward / action=decide
+ * form endpoints were removed in favor of action=batch when the shared
+ * Drupal.rl client library was introduced.
  */
 
 use Drupal\Core\DrupalKernel;
 use Symfony\Component\HttpFoundation\Request;
 
-$action = filter_input(INPUT_POST, 'action', FILTER_SANITIZE_FULL_SPECIAL_CHARS);
-$experiment_id = filter_input(INPUT_POST, 'experiment_id', FILTER_SANITIZE_FULL_SPECIAL_CHARS);
-$arm_id = filter_input(INPUT_POST, 'arm_id', FILTER_SANITIZE_FULL_SPECIAL_CHARS);
+// Action can arrive in the query string (JSON batch requests) or as a form
+// field (ping uses form POST from the Drupal health check).
+$action = $_GET['action'] ?? filter_input(INPUT_POST, 'action', FILTER_SANITIZE_FULL_SPECIAL_CHARS);
 
-// Ping action is read-only and doesn't require experiment_id.
+// Ping is a cheap liveness check used by hook_requirements() to verify the
+// web server serves rl.php directly. No Drupal bootstrap needed.
 if ($action === 'ping') {
   http_response_code(200);
   exit('pong');
 }
 
-if (!$action || !$experiment_id || !in_array($action, ['turn', 'turns', 'reward'])) {
+if ($action !== 'batch') {
   http_response_code(400);
-  exit('Invalid request parameters');
+  exit('Invalid action');
 }
 
-// Validate experiment ID format (alphanumeric, hyphens, underscores).
-if (!preg_match('/^[a-zA-Z0-9_-]+$/', $experiment_id)) {
+// Read and decode the JSON body before bootstrapping Drupal so malformed
+// requests cost nothing.
+$raw_body = file_get_contents('php://input');
+if ($raw_body === FALSE || $raw_body === '') {
+  http_response_code(400);
+  header('Content-Type: application/json');
+  exit('{"decisions":{}}');
+}
+$payload = json_decode($raw_body, TRUE);
+if (!is_array($payload)) {
   http_response_code(400);
-  exit('Invalid experiment_id format');
+  header('Content-Type: application/json');
+  exit('{"decisions":{}}');
 }
 
 try {
@@ -63,51 +83,137 @@
   $container = $kernel->getContainer();
 
   $registry = $container->get('rl.experiment_registry');
-  if (!$registry->isRegistered($experiment_id)) {
-    exit();
-  }
-
   $storage = $container->get('rl.experiment_data_storage');
+  $manager = $container->has('rl.experiment_manager') ? $container->get('rl.experiment_manager') : NULL;
 
+  $decisions = handle_batch_request($payload, $registry, $storage, $manager);
 
-  switch ($action) {
-    case 'turn':
-      if ($arm_id && preg_match('/^[a-zA-Z0-9_-]+$/', $arm_id)) {
-        $storage->recordTurn($experiment_id, $arm_id);
-      }
-      break;
-
-    case 'turns':
-      $arm_ids = filter_input(INPUT_POST, 'arm_ids', FILTER_SANITIZE_FULL_SPECIAL_CHARS);
-      if ($arm_ids) {
-        $arm_ids_array = explode(',', $arm_ids);
-        $arm_ids_array = array_map('trim', $arm_ids_array);
+  http_response_code(200);
+  header('Content-Type: application/json');
+  header('Cache-Control: no-store, private, max-age=0');
+  echo json_encode(['decisions' => $decisions]);
+}
+catch (\Exception $e) {
+  // Log error and return 500.
+  error_log('RL endpoint error: ' . $e->getMessage());
+  http_response_code(500);
+  exit('Server error');
+}
 
-        $valid_arm_ids = [];
-        foreach ($arm_ids_array as $aid) {
-          if (preg_match('/^[a-zA-Z0-9_-]+$/', $aid)) {
-            $valid_arm_ids[] = $aid;
-          }
+/**
+ * Process a Drupal.rl batch payload.
+ *
+ * Expected JSON shape (each section is optional):
+ * @code
+ * {
+ *   "decides": [
+ *     {"id": "<experiment_id>", "arms": ["v0", "v1", ...]},
+ *     ...
+ *   ],
+ *   "turns":   [{"id": "<experiment_id>", "arm": "v0"}, ...],
+ *   "rewards": [{"id": "<experiment_id>", "arm": "v1"}, ...]
+ * }
+ * @endcode
+ *
+ * Returns the decisions map keyed by experiment id:
+ * @code
+ * {"<experiment_id>": {"armId": "v1"}, ...}
+ * @endcode
+ *
+ * Unknown or malformed entries are silently skipped so one bad event does
+ * not poison the rest of the batch. Callers that receive no decision for a
+ * given experiment should fall back to their own default variant.
+ *
+ * @param array $payload
+ *   The decoded JSON body.
+ * @param \Drupal\rl\Registry\ExperimentRegistryInterface $registry
+ * @param \Drupal\rl\Storage\ExperimentDataStorageInterface $storage
+ * @param \Drupal\rl\Service\ExperimentManagerInterface|null $manager
+ *
+ * @return object
+ *   Decisions object (stdClass to preserve JSON object shape when empty).
+ */
+function handle_batch_request(array $payload, $registry, $storage, $manager): \stdClass {
+  $decisions = new \stdClass();
+  $id_pattern = '/^[a-zA-Z0-9_-]+$/';
+
+  if ($manager !== NULL && isset($payload['decides']) && is_array($payload['decides'])) {
+    foreach ($payload['decides'] as $decide) {
+      if (!is_array($decide)) {
+        continue;
+      }
+      $eid = isset($decide['id']) ? (string) $decide['id'] : '';
+      if ($eid === '' || !preg_match($id_pattern, $eid)) {
+        continue;
+      }
+      if (!$registry->isRegistered($eid)) {
+        continue;
+      }
+      $arms = $decide['arms'] ?? [];
+      if (!is_array($arms) || count($arms) < 2) {
+        continue;
+      }
+      $arm_ids = [];
+      foreach ($arms as $arm) {
+        $arm_id = (string) $arm;
+        if ($arm_id === '' || !preg_match($id_pattern, $arm_id)) {
+          continue 2;
         }
+        $arm_ids[] = $arm_id;
+      }
+      try {
+        $scores = $manager->getThompsonScores($eid, NULL, $arm_ids);
+      }
+      catch (\Throwable $e) {
+        continue;
+      }
+      if (!is_array($scores) || !$scores) {
+        continue;
+      }
+      arsort($scores);
+      $decisions->{$eid} = ['armId' => (string) key($scores)];
+    }
+  }
 
-        if (!empty($valid_arm_ids)) {
-          $storage->recordTurns($experiment_id, $valid_arm_ids);
-        }
+  if (isset($payload['turns']) && is_array($payload['turns'])) {
+    foreach ($payload['turns'] as $turn) {
+      if (!is_array($turn)) {
+        continue;
+      }
+      $eid = isset($turn['id']) ? (string) $turn['id'] : '';
+      $aid = isset($turn['arm']) ? (string) $turn['arm'] : '';
+      if ($eid === '' || $aid === '') {
+        continue;
       }
-      break;
+      if (!preg_match($id_pattern, $eid) || !preg_match($id_pattern, $aid)) {
+        continue;
+      }
+      if (!$registry->isRegistered($eid)) {
+        continue;
+      }
+      $storage->recordTurn($eid, $aid);
+    }
+  }
 
-    case 'reward':
-      if ($arm_id && preg_match('/^[a-zA-Z0-9_-]+$/', $arm_id)) {
-        $storage->recordReward($experiment_id, $arm_id);
+  if (isset($payload['rewards']) && is_array($payload['rewards'])) {
+    foreach ($payload['rewards'] as $reward) {
+      if (!is_array($reward)) {
+        continue;
+      }
+      $eid = isset($reward['id']) ? (string) $reward['id'] : '';
+      $aid = isset($reward['arm']) ? (string) $reward['arm'] : '';
+      if ($eid === '' || $aid === '') {
+        continue;
+      }
+      if (!preg_match($id_pattern, $eid) || !preg_match($id_pattern, $aid)) {
+        continue;
       }
-      break;
+      if (!$registry->isRegistered($eid)) {
+        continue;
+      }
+      $storage->recordReward($eid, $aid);
+    }
   }
 
-  http_response_code(200);
-}
-catch (\Exception $e) {
-  // Log error and return 500.
-  error_log('RL endpoint error: ' . $e->getMessage());
-  http_response_code(500);
-  exit('Server error');
+  return $decisions;
 }

From 88b686aa7c73cc8da20f6690443b8922f8d611c2 Mon Sep 17 00:00:00 2001
From: Jurriaan Roelofs <jur@dxpr.com>
Date: Wed, 15 Apr 2026 14:21:41 +0200
Subject: [PATCH 2/6] docs: document rl.php HTTP endpoint for non-browser
 callers

Drupal.rl is only one consumer of the batch endpoint. Native mobile
apps, server-side workers, other CMSes, and edge functions can POST to
rl.php directly using the same JSON protocol. Document the wire format,
validation rules, error responses, and curl examples in both README.md
and the project description HTML so those callers do not have to read
rl.php to integrate.
---
 README.md                 | 115 ++++++++++++++++++++++++++++++++++++--
 docs/rl_project_desc.html |  67 ++++++++++++++++++++++
 2 files changed, 177 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index ebda71e..3c5c54b 100644
--- a/README.md
+++ b/README.md
@@ -232,14 +232,119 @@ Drupal.rl.reward('hero_cta', 'v0');
 
 Decides flush on the next tick so every module that registers during `Drupal.behaviors.attach` shares one request. Turns and rewards flush in a 500 ms window, and buffered events are flushed via `navigator.sendBeacon` on `visibilitychange` / `pagehide` so they survive navigation.
 
-### rl.php endpoint
+## HTTP API (`rl.php`)
 
-`rl.php` is the low-level HTTP endpoint `Drupal.rl` talks to. It accepts two actions:
+`rl.php` is the low-level HTTP endpoint. It is reachable directly from any client that can make an HTTP POST, not only in-browser Drupal pages. Native mobile apps, server-side workers, other CMSes, and edge functions can record turns and rewards or request Thompson Sampling decisions against the same experiments used by in-browser code.
 
-- `action=ping` - liveness check used by `hook_requirements()`.
-- `action=batch` - JSON body used by `Drupal.rl`. See `js/rl.js` for the payload shape.
+The JavaScript `Drupal.rl` described above is a thin batching proxy that speaks this exact protocol, so the two paths converge on the same data.
 
-Direct consumption of `action=batch` without going through `Drupal.rl` is not recommended.
+### Endpoint
+
+```
+POST {base_url}/modules/contrib/rl/{rl_module_path}/rl.php?action={action}
+```
+
+Two actions are supported:
+
+- `action=ping` - liveness check. Returns `pong` with HTTP 200. No body, no database touch, no Drupal bootstrap. Used by the built-in `hook_requirements()` probe.
+- `action=batch` - the real work: zero or more decide / turn / reward events in a single JSON body.
+
+The endpoint requires no authentication. All experiment IDs and arm IDs must already be registered in the `rl_experiment_registry` table (normally via a module's `__construct()` calling `ExperimentRegistryInterface::register()`) - unknown IDs are silently ignored so garbage writes cannot create arbitrary registry entries.
+
+### `action=batch` request
+
+```
+POST /modules/contrib/rl/rl.php?action=batch
+Content-Type: application/json
+
+{
+  "decides": [
+    {"id": "hero_cta", "arms": ["v0", "v1", "v2"]},
+    {"id": "page_title_123", "arms": ["v0", "v1"]}
+  ],
+  "turns": [
+    {"id": "menu_main_5", "arm": "v1"},
+    {"id": "hero_cta", "arm": "v0"}
+  ],
+  "rewards": [
+    {"id": "hero_cta", "arm": "v0"}
+  ]
+}
+```
+
+All three sections are optional. A request with just `turns` is the fastest way to log an impression from outside the browser.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `decides[].id` | string | Registered experiment id. `^[a-zA-Z0-9_-]+$`. |
+| `decides[].arms` | string[] | Arm ids in play. Minimum 2. Each must match `^[a-zA-Z0-9_-]+$`. |
+| `turns[].id` | string | Registered experiment id. |
+| `turns[].arm` | string | Arm id of the variant that was shown. |
+| `rewards[].id` | string | Registered experiment id. |
+| `rewards[].arm` | string | Arm id of the variant that converted. |
+
+Invalid or unregistered entries are dropped silently so one bad event does not poison the rest of the batch. Callers should always supply a local fallback for missing decisions.
+
+### `action=batch` response
+
+```
+HTTP/1.1 200 OK
+Content-Type: application/json
+Cache-Control: no-store, private, max-age=0
+
+{
+  "decisions": {
+    "hero_cta": {"armId": "v1"},
+    "page_title_123": {"armId": "v0"}
+  }
+}
+```
+
+The `decisions` map only contains entries that had a successful Thompson Sampling lookup. If the client requested a decide for an experiment that is not registered, or has fewer than two arms, or has no data yet, the key is simply absent - treat that as "use the default variant". The map is keyed by experiment id and the value is `{"armId": "<winning arm>"}`.
+
+Turns and rewards produce no response payload beyond the HTTP 200 - they are fire-and-forget writes.
+
+### Error responses
+
+| Status | When |
+| --- | --- |
+| `400` | Missing/invalid `action`, malformed JSON, or empty body. Response body is either `Invalid action` or `{"decisions":{}}`. |
+| `500` | Drupal kernel failed to boot. Error logged to the PHP error log. |
+
+### Curl examples
+
+Impression from a server-side job:
+
+```bash
+curl -X POST 'https://example.com/modules/contrib/rl/rl.php?action=batch' \
+  -H 'Content-Type: application/json' \
+  -d '{"turns":[{"id":"hero_cta","arm":"v1"}]}'
+```
+
+Decision lookup from a native mobile client:
+
+```bash
+curl -X POST 'https://example.com/modules/contrib/rl/rl.php?action=batch' \
+  -H 'Content-Type: application/json' \
+  -d '{"decides":[{"id":"hero_cta","arms":["v0","v1","v2"]}]}'
+```
+
+Response:
+
+```json
+{"decisions":{"hero_cta":{"armId":"v1"}}}
+```
+
+Liveness probe:
+
+```bash
+curl -X POST 'https://example.com/modules/contrib/rl/rl.php?action=ping'
+# => pong
+```
+
+### Performance notes
+
+`rl.php` bootstraps a minimal Drupal kernel per request (same pattern as core's `statistics.php`), not the full stack that would run behind a normal route. One kernel boot processes the whole batch, so the cheapest way to use this endpoint is to send as many events as possible in one request. `Drupal.rl` already does this on the browser side; non-browser callers should coalesce events similarly when they can.
 
 ## Cache Management
 
diff --git a/docs/rl_project_desc.html b/docs/rl_project_desc.html
index 05de4ff..bf0691c 100644
--- a/docs/rl_project_desc.html
+++ b/docs/rl_project_desc.html
@@ -164,6 +164,73 @@ <h3>JavaScript API</h3>
 
 <p>Decides flush on the next tick so all modules that register during <code>Drupal.behaviors.attach</code> share one request. Turns and rewards flush in a 500 ms window and on <code>pagehide</code> via <code>navigator.sendBeacon</code>.</p>
 
+<h3>HTTP API (<code>rl.php</code>)</h3>
+
+<p><code>rl.php</code> is the low-level HTTP endpoint reachable directly from any client that can make an HTTP POST, not only in-browser Drupal pages. Native mobile apps, server-side workers, other CMSes, and edge functions can record turns and rewards or request Thompson Sampling decisions against the same experiments used by in-browser code. The JavaScript <code>Drupal.rl</code> is simply a thin batching proxy that speaks this protocol.</p>
+
+<p>Two actions are supported:</p>
+<ul>
+<li><code>action=ping</code> - liveness probe used by <code>hook_requirements()</code>. Returns <code>pong</code> with HTTP 200. No database touch, no Drupal bootstrap.</li>
+<li><code>action=batch</code> - zero or more decide, turn, and reward events in a single JSON body. All three sections are optional.</li>
+</ul>
+
+<p>The endpoint requires no authentication. Experiment IDs must already be registered in the <code>rl_experiment_registry</code> table (normally via a module's <code>__construct()</code>) - unknown IDs are silently dropped so garbage writes cannot create arbitrary registry entries.</p>
+
+<h4>Request</h4>
+
+<pre><code>POST /modules/contrib/rl/rl.php?action=batch
+Content-Type: application/json
+
+{
+  "decides": [
+    {"id": "hero_cta", "arms": ["v0", "v1", "v2"]},
+    {"id": "page_title_123", "arms": ["v0", "v1"]}
+  ],
+  "turns": [
+    {"id": "menu_main_5", "arm": "v1"},
+    {"id": "hero_cta", "arm": "v0"}
+  ],
+  "rewards": [
+    {"id": "hero_cta", "arm": "v0"}
+  ]
+}</code></pre>
+
+<p>Experiment IDs and arm IDs must match <code>^[a-zA-Z0-9_-]+$</code>. Decides require at least 2 arms. Invalid or unregistered entries are dropped silently so one bad event does not poison the rest of the batch.</p>
+
+<h4>Response</h4>
+
+<pre><code>HTTP/1.1 200 OK
+Content-Type: application/json
+Cache-Control: no-store, private, max-age=0
+
+{
+  "decisions": {
+    "hero_cta": {"armId": "v1"},
+    "page_title_123": {"armId": "v0"}
+  }
+}</code></pre>
+
+<p>Only successful decide lookups appear in the map. Callers should always hold a local fallback for missing keys. Turns and rewards produce no response payload beyond HTTP 200 - they are fire-and-forget writes.</p>
+
+<h4>Curl examples</h4>
+
+<p>Impression from a server-side job:</p>
+<pre><code>curl -X POST 'https://example.com/modules/contrib/rl/rl.php?action=batch' \
+  -H 'Content-Type: application/json' \
+  -d '{"turns":[{"id":"hero_cta","arm":"v1"}]}'</code></pre>
+
+<p>Decision lookup from a native mobile client:</p>
+<pre><code>curl -X POST 'https://example.com/modules/contrib/rl/rl.php?action=batch' \
+  -H 'Content-Type: application/json' \
+  -d '{"decides":[{"id":"hero_cta","arms":["v0","v1","v2"]}]}'
+# => {"decisions":{"hero_cta":{"armId":"v1"}}}</code></pre>
+
+<p>Liveness probe:</p>
+<pre><code>curl -X POST 'https://example.com/modules/contrib/rl/rl.php?action=ping'
+# => pong</code></pre>
+
+<p><strong>Performance note:</strong> <code>rl.php</code> bootstraps a minimal Drupal kernel per request (same pattern as core's <code>statistics.php</code>). One boot processes the whole batch, so non-browser callers should coalesce events into a single request whenever they can.</p>
+
 <h3>Cache Management</h3>
 
 <p>RL provides optional cache management for web components:</p>

From 0cbb2e4b73bdb04ed5510c98335b6c1e337c0e3a Mon Sep 17 00:00:00 2001
From: Jurriaan Roelofs <jur@dxpr.com>
Date: Wed, 15 Apr 2026 14:39:22 +0200
Subject: [PATCH 3/6] refactor: make rl.php additive and drop JS decide API

Responds to the arm-ownership / ai_sorting feedback on #45. Deciding
which variant to show belongs in PHP at render time where the consumer
already owns the arm list (see ai_sorting's Views sort plugin and
VariantSelectorBase in this module). Client-side decides would force
runtime JS to know the current arm set, which drifts out of sync when
experiment managers add or remove variants.

- rl.php is now strictly additive: action=ping, action=turn,
  action=turns, and action=reward legacy form handlers are restored
  unchanged so ai_sorting and any other production consumer keeps
  working. The new action=batch sits alongside them as a JSON endpoint
  that Drupal.rl speaks.
- action=batch carries only turns and rewards. The decides section is
  gone, and the response is now {"ok":true} instead of a decisions map.
- js/rl.js drops Drupal.rl.decide() entirely and all of its promise /
  queue machinery. The API is now just turn(), reward(), and flush()
  plus pagehide sendBeacon.
- rl_example_frontend is converted to the canonical pattern: the block
  decides the winning variant in PHP inside build() using
  ExperimentManager::getThompsonScores(), server-renders the winning
  button text, and exposes the arm id to Drupal.rl.turn() / .reward()
  via drupalSettings. Block picks up a 60-second cache max-age so the
  server-chosen variant can rotate as scores evolve.
- README and HTML docs are rewritten around this split: "deciding"
  section for the PHP pattern, "JS API" section for tracking, "HTTP
  API" section documenting all five actions (ping / turn / turns /
  reward / batch) as peers.
---
 README.md                                     | 183 +++++++++---------
 docs/rl_project_desc.html                     | 110 +++++------
 js/rl.js                                      | 157 +++------------
 .../js/frontend-ab-testing.js                 |  50 ++---
 .../src/Plugin/Block/NewsletterBlock.php      |  74 +++++--
 rl.php                                        | 179 ++++++++---------
 6 files changed, 342 insertions(+), 411 deletions(-)

diff --git a/README.md b/README.md
index 3c5c54b..eff06b7 100644
--- a/README.md
+++ b/README.md
@@ -213,58 +213,108 @@ $cache_manager = \Drupal::service('rl.cache_manager');
 $cache_manager->overridePageCacheIfShorter(60); // 60 seconds
 ```
 
-## JavaScript API
+## Deciding which variant to show
 
-Attach the `rl/api` library to make `Drupal.rl` available. It is a thin transport proxy that coalesces every RL call on the page into a single batched POST to `rl.php`, so N experiments on the same page produce ~2 requests regardless of how many modules are tracking.
+Pick the winning variant in PHP at render time. Your consumer already
+has the full arm set in hand (entity fields, view filters, plugin
+config, etc.), so it can call the RL service directly:
 
-```javascript
-// Ask for a Thompson Sampling decision - resolves to the winning arm id.
-Drupal.rl.decide('hero_cta', ['v0', 'v1', 'v2']).then(function (armId) {
-  renderVariant(armId);
-});
+```php
+$scores = $experiment_manager->getThompsonScores(
+  'my_experiment',
+  NULL,
+  ['v0', 'v1', 'v2']  // arm ids owned by your domain
+);
+arsort($scores);
+$best_arm = key($scores);
+```
+
+Deciding server-side keeps the arm list where it belongs (with the
+experiment owner) and avoids shipping it to the browser. See
+`ai_sorting`'s Views sort plugin for the canonical pattern and
+`VariantSelectorBase` in this module for a reusable base class.
+
+There is deliberately no client-side decide API. Client-side decides
+would force runtime JS to know the current arm set, which drifts out of
+sync as experiment managers add or remove variants.
+
+## JavaScript API (`Drupal.rl`)
+
+Attach the `rl/api` library to make `Drupal.rl` available. It is a thin
+transport proxy that coalesces every impression and conversion fired on
+the page into one batched POST to `rl.php`, so N experiments on the same
+page produce just one or two tracking requests instead of one pair per
+experiment.
 
-// Record an impression.
+```javascript
+// Record an impression when the variant becomes visible.
 Drupal.rl.turn('hero_cta', 'v0');
 
-// Record a conversion.
+// Record a conversion when the user clicks / submits / converts.
 Drupal.rl.reward('hero_cta', 'v0');
+
+// Optional: force an immediate flush.
+Drupal.rl.flush();
 ```
 
-Decides flush on the next tick so every module that registers during `Drupal.behaviors.attach` shares one request. Turns and rewards flush in a 500 ms window, and buffered events are flushed via `navigator.sendBeacon` on `visibilitychange` / `pagehide` so they survive navigation.
+Events accumulate for 500 ms and then flush in a single POST. Buffered
+events are also flushed via `navigator.sendBeacon` on `visibilitychange`
+and `pagehide` so they survive navigation.
+
+`Drupal.rl` is one transport among several. Modules that already ship
+their own tracking JS (like `ai_sorting`, which batches turns on its own
+100 ms window and posts them as form data) keep working untouched.
 
 ## HTTP API (`rl.php`)
 
-`rl.php` is the low-level HTTP endpoint. It is reachable directly from any client that can make an HTTP POST, not only in-browser Drupal pages. Native mobile apps, server-side workers, other CMSes, and edge functions can record turns and rewards or request Thompson Sampling decisions against the same experiments used by in-browser code.
+`rl.php` is the low-level endpoint. It is reachable directly from any
+client that can make an HTTP POST - browser pages, native mobile apps,
+server-side workers, other CMSes, edge functions. Deciding is *not*
+exposed here: it happens in PHP at render time as shown above.
 
-The JavaScript `Drupal.rl` described above is a thin batching proxy that speaks this exact protocol, so the two paths converge on the same data.
+Four actions are supported. All are additive - adding `batch` did not
+deprecate the legacy form actions, and `ai_sorting` and other production
+consumers keep using them unchanged.
 
-### Endpoint
+| Action | Encoding | Purpose |
+| --- | --- | --- |
+| `ping` | form POST | Liveness check. Returns `pong`. |
+| `turn` | form POST | Record one impression. |
+| `turns` | form POST | Record impressions for many arms in one experiment. |
+| `reward` | form POST | Record one conversion. |
+| `batch` | JSON POST | Record turns and rewards across many experiments in one request. Used by `Drupal.rl`. |
 
-```
-POST {base_url}/modules/contrib/rl/{rl_module_path}/rl.php?action={action}
-```
+Experiment IDs and arm IDs must match `^[a-zA-Z0-9_-]+$`. Experiments
+must already be registered via `ExperimentRegistryInterface::register()`;
+unknown IDs are silently dropped so garbage writes cannot create
+registry entries.
+
+### Legacy form actions
 
-Two actions are supported:
+```bash
+# Turn
+curl -X POST https://example.com/modules/contrib/rl/rl.php \
+  -d 'action=turn&experiment_id=hero_cta&arm_id=v0'
 
-- `action=ping` - liveness check. Returns `pong` with HTTP 200. No body, no database touch, no Drupal bootstrap. Used by the built-in `hook_requirements()` probe.
-- `action=batch` - the real work: zero or more decide / turn / reward events in a single JSON body.
+# Multiple arms in one experiment
+curl -X POST https://example.com/modules/contrib/rl/rl.php \
+  -d 'action=turns&experiment_id=hero_cta&arm_ids=v0,v1'
 
-The endpoint requires no authentication. All experiment IDs and arm IDs must already be registered in the `rl_experiment_registry` table (normally via a module's `__construct()` calling `ExperimentRegistryInterface::register()`) - unknown IDs are silently ignored so garbage writes cannot create arbitrary registry entries.
+# Reward
+curl -X POST https://example.com/modules/contrib/rl/rl.php \
+  -d 'action=reward&experiment_id=hero_cta&arm_id=v0'
+```
 
-### `action=batch` request
+### `action=batch`
 
 ```
 POST /modules/contrib/rl/rl.php?action=batch
 Content-Type: application/json
 
 {
-  "decides": [
-    {"id": "hero_cta", "arms": ["v0", "v1", "v2"]},
-    {"id": "page_title_123", "arms": ["v0", "v1"]}
-  ],
   "turns": [
-    {"id": "menu_main_5", "arm": "v1"},
-    {"id": "hero_cta", "arm": "v0"}
+    {"id": "hero_cta", "arm": "v0"},
+    {"id": "menu_main_5", "arm": "v1"}
   ],
   "rewards": [
     {"id": "hero_cta", "arm": "v0"}
@@ -272,79 +322,38 @@ Content-Type: application/json
 }
 ```
 
-All three sections are optional. A request with just `turns` is the fastest way to log an impression from outside the browser.
-
-| Field | Type | Notes |
-| --- | --- | --- |
-| `decides[].id` | string | Registered experiment id. `^[a-zA-Z0-9_-]+$`. |
-| `decides[].arms` | string[] | Arm ids in play. Minimum 2. Each must match `^[a-zA-Z0-9_-]+$`. |
-| `turns[].id` | string | Registered experiment id. |
-| `turns[].arm` | string | Arm id of the variant that was shown. |
-| `rewards[].id` | string | Registered experiment id. |
-| `rewards[].arm` | string | Arm id of the variant that converted. |
-
-Invalid or unregistered entries are dropped silently so one bad event does not poison the rest of the batch. Callers should always supply a local fallback for missing decisions.
-
-### `action=batch` response
-
-```
-HTTP/1.1 200 OK
-Content-Type: application/json
-Cache-Control: no-store, private, max-age=0
-
-{
-  "decisions": {
-    "hero_cta": {"armId": "v1"},
-    "page_title_123": {"armId": "v0"}
-  }
-}
-```
-
-The `decisions` map only contains entries that had a successful Thompson Sampling lookup. If the client requested a decide for an experiment that is not registered, or has fewer than two arms, or has no data yet, the key is simply absent - treat that as "use the default variant". The map is keyed by experiment id and the value is `{"armId": "<winning arm>"}`.
-
-Turns and rewards produce no response payload beyond the HTTP 200 - they are fire-and-forget writes.
-
-### Error responses
-
-| Status | When |
-| --- | --- |
-| `400` | Missing/invalid `action`, malformed JSON, or empty body. Response body is either `Invalid action` or `{"decisions":{}}`. |
-| `500` | Drupal kernel failed to boot. Error logged to the PHP error log. |
+Both sections are optional. Invalid or unregistered entries are dropped
+silently so one bad event does not poison the rest of the batch. The
+response is `{"ok":true}` with HTTP 200; writes are fire-and-forget.
 
 ### Curl examples
 
-Impression from a server-side job:
-
 ```bash
+# Batch tracking from a server-side job.
 curl -X POST 'https://example.com/modules/contrib/rl/rl.php?action=batch' \
   -H 'Content-Type: application/json' \
-  -d '{"turns":[{"id":"hero_cta","arm":"v1"}]}'
-```
-
-Decision lookup from a native mobile client:
+  -d '{"turns":[{"id":"hero_cta","arm":"v1"}],"rewards":[{"id":"hero_cta","arm":"v1"}]}'
 
-```bash
-curl -X POST 'https://example.com/modules/contrib/rl/rl.php?action=batch' \
-  -H 'Content-Type: application/json' \
-  -d '{"decides":[{"id":"hero_cta","arms":["v0","v1","v2"]}]}'
-```
-
-Response:
-
-```json
-{"decisions":{"hero_cta":{"armId":"v1"}}}
+# Liveness probe.
+curl -X POST 'https://example.com/modules/contrib/rl/rl.php' -d 'action=ping'
+# => pong
 ```
 
-Liveness probe:
+### Error responses
 
-```bash
-curl -X POST 'https://example.com/modules/contrib/rl/rl.php?action=ping'
-# => pong
-```
+| Status | When |
+| --- | --- |
+| `400` | Missing/invalid `action`, malformed JSON, or missing `experiment_id` on a legacy action. |
+| `500` | Drupal kernel failed to boot. Error logged to the PHP error log. |
 
 ### Performance notes
 
-`rl.php` bootstraps a minimal Drupal kernel per request (same pattern as core's `statistics.php`), not the full stack that would run behind a normal route. One kernel boot processes the whole batch, so the cheapest way to use this endpoint is to send as many events as possible in one request. `Drupal.rl` already does this on the browser side; non-browser callers should coalesce events similarly when they can.
+`rl.php` bootstraps a minimal Drupal kernel per request (same pattern as
+core's `statistics.php`), not the full stack that would run behind a
+normal route. One kernel boot processes the whole batch, so the cheapest
+way to use this endpoint is to send as many events as possible in one
+request. `Drupal.rl` already does this on the browser side; non-browser
+callers should coalesce events similarly when they can.
 
 ## Cache Management
 
diff --git a/docs/rl_project_desc.html b/docs/rl_project_desc.html
index bf0691c..e95bee4 100644
--- a/docs/rl_project_desc.html
+++ b/docs/rl_project_desc.html
@@ -147,87 +147,83 @@ <h3>API</h3>
 $cache_manager->overridePageCacheIfShorter(60); // 60 seconds
 </code></pre>
 
-<h3>JavaScript API</h3>
+<h3>Deciding which variant to show</h3>
 
-<p>Attach the <code>rl/api</code> library to make <code>Drupal.rl</code> available on the page. It exposes a thin transport layer that coalesces every RL call on the page into a single batched POST to <code>rl.php</code>:</p>
+<p>Pick the winning variant in PHP at render time. Your consumer already has the full arm set in hand (entity fields, view filters, plugin config), so it can call the RL service directly:</p>
 
-<pre><code>// Ask for a Thompson Sampling decision - resolves to the winning arm id.
-Drupal.rl.decide('hero_cta', ['v0', 'v1', 'v2']).then(function (armId) {
-  renderVariant(armId);
-});
+<pre><code>$scores = $experiment_manager->getThompsonScores(
+  'my_experiment',
+  NULL,
+  ['v0', 'v1', 'v2']  // arm ids owned by your domain
+);
+arsort($scores);
+$best_arm = key($scores);</code></pre>
 
-// Record an impression.
+<p>Deciding server-side keeps the arm list where it belongs (with the experiment owner) and avoids shipping it to the browser. See <code>ai_sorting</code>'s Views sort plugin for the canonical pattern and <code>VariantSelectorBase</code> in this module for a reusable base class. There is deliberately no client-side decide API.</p>
+
+<h3>JavaScript API (<code>Drupal.rl</code>)</h3>
+
+<p>Attach the <code>rl/api</code> library to make <code>Drupal.rl</code> available. It is a thin transport proxy that coalesces every impression and conversion fired on the page into one batched POST to <code>rl.php</code>:</p>
+
+<pre><code>// Record an impression when the variant becomes visible.
 Drupal.rl.turn('hero_cta', 'v0');
 
-// Record a conversion.
-Drupal.rl.reward('hero_cta', 'v0');</code></pre>
+// Record a conversion when the user clicks / submits / converts.
+Drupal.rl.reward('hero_cta', 'v0');
+
+// Optional: force an immediate flush.
+Drupal.rl.flush();</code></pre>
 
-<p>Decides flush on the next tick so all modules that register during <code>Drupal.behaviors.attach</code> share one request. Turns and rewards flush in a 500 ms window and on <code>pagehide</code> via <code>navigator.sendBeacon</code>.</p>
+<p>Events accumulate for 500 ms and then flush in a single POST. Buffered events are also flushed via <code>navigator.sendBeacon</code> on <code>visibilitychange</code> and <code>pagehide</code> so they survive navigation.</p>
+
+<p><code>Drupal.rl</code> is one transport among several. Modules that already ship their own tracking JS (like <code>ai_sorting</code>, which batches turns on its own 100 ms window and posts form data) keep working untouched.</p>
 
 <h3>HTTP API (<code>rl.php</code>)</h3>
 
-<p><code>rl.php</code> is the low-level HTTP endpoint reachable directly from any client that can make an HTTP POST, not only in-browser Drupal pages. Native mobile apps, server-side workers, other CMSes, and edge functions can record turns and rewards or request Thompson Sampling decisions against the same experiments used by in-browser code. The JavaScript <code>Drupal.rl</code> is simply a thin batching proxy that speaks this protocol.</p>
+<p><code>rl.php</code> is the low-level endpoint. It is reachable directly from any client that can make an HTTP POST - browser pages, native mobile apps, server-side workers, other CMSes, edge functions. Deciding is <em>not</em> exposed here: it happens in PHP at render time as shown above.</p>
 
-<p>Two actions are supported:</p>
-<ul>
-<li><code>action=ping</code> - liveness probe used by <code>hook_requirements()</code>. Returns <code>pong</code> with HTTP 200. No database touch, no Drupal bootstrap.</li>
-<li><code>action=batch</code> - zero or more decide, turn, and reward events in a single JSON body. All three sections are optional.</li>
-</ul>
+<p>Four actions are supported. All are additive - adding <code>batch</code> did not deprecate the legacy form actions, and production consumers like <code>ai_sorting</code> keep using them unchanged.</p>
+
+<table>
+  <thead><tr><th>Action</th><th>Encoding</th><th>Purpose</th></tr></thead>
+  <tbody>
+    <tr><td><code>ping</code></td><td>form POST</td><td>Liveness check. Returns <code>pong</code>.</td></tr>
+    <tr><td><code>turn</code></td><td>form POST</td><td>Record one impression.</td></tr>
+    <tr><td><code>turns</code></td><td>form POST</td><td>Record impressions for many arms in one experiment.</td></tr>
+    <tr><td><code>reward</code></td><td>form POST</td><td>Record one conversion.</td></tr>
+    <tr><td><code>batch</code></td><td>JSON POST</td><td>Record turns and rewards across many experiments in one request. Used by <code>Drupal.rl</code>.</td></tr>
+  </tbody>
+</table>
+
+<p>Experiment IDs and arm IDs must match <code>^[a-zA-Z0-9_-]+$</code>. Experiments must already be registered via <code>ExperimentRegistryInterface::register()</code>; unknown IDs are silently dropped so garbage writes cannot create registry entries.</p>
+
+<h4>Legacy form actions</h4>
+
+<pre><code>curl -X POST https://example.com/modules/contrib/rl/rl.php \
+  -d 'action=turn&amp;experiment_id=hero_cta&amp;arm_id=v0'
 
-<p>The endpoint requires no authentication. Experiment IDs must already be registered in the <code>rl_experiment_registry</code> table (normally via a module's <code>__construct()</code>) - unknown IDs are silently dropped so garbage writes cannot create arbitrary registry entries.</p>
+curl -X POST https://example.com/modules/contrib/rl/rl.php \
+  -d 'action=turns&amp;experiment_id=hero_cta&amp;arm_ids=v0,v1'
 
-<h4>Request</h4>
+curl -X POST https://example.com/modules/contrib/rl/rl.php \
+  -d 'action=reward&amp;experiment_id=hero_cta&amp;arm_id=v0'</code></pre>
+
+<h4><code>action=batch</code></h4>
 
 <pre><code>POST /modules/contrib/rl/rl.php?action=batch
 Content-Type: application/json
 
 {
-  "decides": [
-    {"id": "hero_cta", "arms": ["v0", "v1", "v2"]},
-    {"id": "page_title_123", "arms": ["v0", "v1"]}
-  ],
   "turns": [
-    {"id": "menu_main_5", "arm": "v1"},
-    {"id": "hero_cta", "arm": "v0"}
+    {"id": "hero_cta", "arm": "v0"},
+    {"id": "menu_main_5", "arm": "v1"}
   ],
   "rewards": [
     {"id": "hero_cta", "arm": "v0"}
   ]
 }</code></pre>
 
-<p>Experiment IDs and arm IDs must match <code>^[a-zA-Z0-9_-]+$</code>. Decides require at least 2 arms. Invalid or unregistered entries are dropped silently so one bad event does not poison the rest of the batch.</p>
-
-<h4>Response</h4>
-
-<pre><code>HTTP/1.1 200 OK
-Content-Type: application/json
-Cache-Control: no-store, private, max-age=0
-
-{
-  "decisions": {
-    "hero_cta": {"armId": "v1"},
-    "page_title_123": {"armId": "v0"}
-  }
-}</code></pre>
-
-<p>Only successful decide lookups appear in the map. Callers should always hold a local fallback for missing keys. Turns and rewards produce no response payload beyond HTTP 200 - they are fire-and-forget writes.</p>
-
-<h4>Curl examples</h4>
-
-<p>Impression from a server-side job:</p>
-<pre><code>curl -X POST 'https://example.com/modules/contrib/rl/rl.php?action=batch' \
-  -H 'Content-Type: application/json' \
-  -d '{"turns":[{"id":"hero_cta","arm":"v1"}]}'</code></pre>
-
-<p>Decision lookup from a native mobile client:</p>
-<pre><code>curl -X POST 'https://example.com/modules/contrib/rl/rl.php?action=batch' \
-  -H 'Content-Type: application/json' \
-  -d '{"decides":[{"id":"hero_cta","arms":["v0","v1","v2"]}]}'
-# => {"decisions":{"hero_cta":{"armId":"v1"}}}</code></pre>
-
-<p>Liveness probe:</p>
-<pre><code>curl -X POST 'https://example.com/modules/contrib/rl/rl.php?action=ping'
-# => pong</code></pre>
+<p>Both sections are optional. Invalid or unregistered entries are dropped silently. The response is <code>{"ok":true}</code> with HTTP 200; writes are fire-and-forget.</p>
 
 <p><strong>Performance note:</strong> <code>rl.php</code> bootstraps a minimal Drupal kernel per request (same pattern as core's <code>statistics.php</code>). One boot processes the whole batch, so non-browser callers should coalesce events into a single request whenever they can.</p>
 
diff --git a/js/rl.js b/js/rl.js
index a0b81e3..c583063 100644
--- a/js/rl.js
+++ b/js/rl.js
@@ -2,18 +2,20 @@
  * @file
  * Thin RL transport proxy with request batching.
  *
- * Exposes Drupal.rl.decide(), Drupal.rl.turn(), Drupal.rl.reward(), and
- * Drupal.rl.flush(). Batches calls into a single POST to rl.php so that
- * multiple RL-powered features on the same page share one request instead
- * of each making its own.
+ * Exposes Drupal.rl.turn(), Drupal.rl.reward(), and Drupal.rl.flush().
+ * Batches calls into a single POST to rl.php so that multiple RL-powered
+ * features on the same page share one request instead of each making its
+ * own.
  *
- * Batching strategy:
- *   - decide() flushes on the next tick (setTimeout 0), catching every
- *     module that registers synchronously during Drupal.behaviors.attach.
- *   - turn() / reward() flush in a 500 ms window to coalesce events that
- *     arrive as the user interacts with the page.
- *   - visibilitychange / pagehide flush immediately via navigator.sendBeacon
- *     so buffered events survive navigation.
+ * Batching strategy: events accumulate for 500 ms and then flush in one
+ * POST. visibilitychange / pagehide flush immediately via
+ * navigator.sendBeacon so buffered events survive navigation.
+ *
+ * Deciding which variant to show is a server-side concern - see
+ * ai_sorting's Views sort plugin or VariantSelectorBase in this module.
+ * Drupal.rl deliberately does not provide a decide API: client-side
+ * decides would require the caller to know the current arm set, which
+ * belongs in the experiment owner's domain model, not in runtime JS.
  *
  * Modelled on Drupal.history in Drupal core, which batches node-view
  * tracking the same way.
@@ -27,14 +29,9 @@
 
   var queue = emptyQueue();
   var timer = null;
-  var timerDelay = null;
 
   function emptyQueue() {
-    return {
-      decides: Object.create(null),
-      turns: [],
-      rewards: [],
-    };
+    return { turns: [], rewards: [] };
   }
 
   function endpoint() {
@@ -45,27 +42,17 @@
   }
 
   function hasPending() {
-    for (var id in queue.decides) {
-      if (Object.prototype.hasOwnProperty.call(queue.decides, id)) {
-        return true;
-      }
-    }
     return queue.turns.length > 0 || queue.rewards.length > 0;
   }
 
-  function schedule(delay) {
-    if (timer !== null && timerDelay <= delay) {
-      return;
-    }
+  function schedule() {
     if (timer !== null) {
-      clearTimeout(timer);
+      return;
     }
-    timerDelay = delay;
     timer = setTimeout(function () {
       timer = null;
-      timerDelay = null;
       flush();
-    }, delay);
+    }, 500);
   }
 
   function takeQueue() {
@@ -74,53 +61,6 @@
     return snapshot;
   }
 
-  function buildPayload(snapshot) {
-    var decides = [];
-    for (var id in snapshot.decides) {
-      if (Object.prototype.hasOwnProperty.call(snapshot.decides, id)) {
-        decides.push({ id: id, arms: snapshot.decides[id].arms });
-      }
-    }
-    return {
-      decides: decides,
-      turns: snapshot.turns,
-      rewards: snapshot.rewards,
-    };
-  }
-
-  function resolveDecides(snapshot, decisions) {
-    for (var id in snapshot.decides) {
-      if (!Object.prototype.hasOwnProperty.call(snapshot.decides, id)) {
-        continue;
-      }
-      var entry = snapshot.decides[id];
-      var armId = null;
-      if (decisions && decisions[id] && decisions[id].armId) {
-        armId = decisions[id].armId;
-      }
-      // Fallback to the first arm when the server returns no decision
-      // (unregistered experiment, missing data, etc.) so callers always
-      // get a usable variant.
-      if (!armId) {
-        armId = entry.arms[0];
-      }
-      entry.resolvers.forEach(function (resolver) {
-        resolver.resolve(armId);
-      });
-    }
-  }
-
-  function rejectDecides(snapshot, reason) {
-    for (var id in snapshot.decides) {
-      if (!Object.prototype.hasOwnProperty.call(snapshot.decides, id)) {
-        continue;
-      }
-      snapshot.decides[id].resolvers.forEach(function (resolver) {
-        resolver.reject(reason);
-      });
-    }
-  }
-
   function batchUrl(url) {
     return url + (url.indexOf('?') === -1 ? '?' : '&') + 'action=batch';
   }
@@ -131,12 +71,12 @@
     }
     var url = endpoint();
     if (!url) {
-      var dropped = takeQueue();
-      rejectDecides(dropped, new Error('Drupal.rl: endpointUrl not set'));
+      // No endpoint configured - drop the queue rather than dangling.
+      takeQueue();
       return;
     }
     var snapshot = takeQueue();
-    var body = JSON.stringify(buildPayload(snapshot));
+    var body = JSON.stringify(snapshot);
 
     fetch(batchUrl(url), {
       method: 'POST',
@@ -144,22 +84,9 @@
       body: body,
       credentials: 'same-origin',
       keepalive: true,
-    })
-      .then(function (response) {
-        if (!response.ok) {
-          rejectDecides(snapshot, new Error('Drupal.rl: HTTP ' + response.status));
-          return null;
-        }
-        return response.json();
-      })
-      .then(function (json) {
-        if (json) {
-          resolveDecides(snapshot, json.decisions || {});
-        }
-      })
-      .catch(function (err) {
-        rejectDecides(snapshot, err);
-      });
+    }).catch(function () {
+      // Swallow network errors. Tracking is best-effort.
+    });
   }
 
   function flushBeacon() {
@@ -171,47 +98,16 @@
       return;
     }
     var snapshot = takeQueue();
-    var body = JSON.stringify(buildPayload(snapshot));
+    var body = JSON.stringify(snapshot);
 
     if ('sendBeacon' in navigator) {
       var blob = new Blob([body], { type: 'application/json' });
       navigator.sendBeacon(batchUrl(url), blob);
     }
-    // Decide promises cannot be fulfilled once the page is unloading, so
-    // reject any that happen to still be buffered. Callers on a page that
-    // is going away do not need the answer.
-    rejectDecides(snapshot, new Error('Drupal.rl: page unloading'));
   }
 
   Drupal.rl = {
 
-    /**
-     * Request a Thompson Sampling decision for an experiment.
-     *
-     * @param {string} experimentId
-     *   The pre-registered experiment id.
-     * @param {Array<string>} armIds
-     *   The arm ids the caller is offering. The winning arm id is returned
-     *   unchanged so the caller can map it back to its own variant table.
-     *
-     * @return {Promise<string>}
-     *   Resolves to the winning arm id. Falls back to armIds[0] when the
-     *   server cannot provide a decision.
-     */
-    decide: function (experimentId, armIds) {
-      return new Promise(function (resolve, reject) {
-        var entry = queue.decides[experimentId];
-        if (!entry) {
-          entry = queue.decides[experimentId] = {
-            arms: armIds.slice(),
-            resolvers: [],
-          };
-        }
-        entry.resolvers.push({ resolve: resolve, reject: reject });
-        schedule(0);
-      });
-    },
-
     /**
      * Record an impression for a variant.
      *
@@ -220,7 +116,7 @@
      */
     turn: function (experimentId, armId) {
       queue.turns.push({ id: experimentId, arm: armId });
-      schedule(500);
+      schedule();
     },
 
     /**
@@ -231,7 +127,7 @@
      */
     reward: function (experimentId, armId) {
       queue.rewards.push({ id: experimentId, arm: armId });
-      schedule(500);
+      schedule();
     },
 
     /**
@@ -241,7 +137,6 @@
       if (timer !== null) {
         clearTimeout(timer);
         timer = null;
-        timerDelay = null;
       }
       flush();
     },
diff --git a/modules/rl_example_frontend/js/frontend-ab-testing.js b/modules/rl_example_frontend/js/frontend-ab-testing.js
index 915ff62..1ee1c7e 100644
--- a/modules/rl_example_frontend/js/frontend-ab-testing.js
+++ b/modules/rl_example_frontend/js/frontend-ab-testing.js
@@ -1,64 +1,44 @@
 /**
  * @file
- * Frontend A/B testing for newsletter signup button.
+ * Tracking for the rl_example_frontend newsletter block.
  *
- * Uses Drupal.rl as the transport layer: one decide call resolves the
- * winning variant, one turn call fires when the form enters the viewport,
- * one reward call fires when the submit button is clicked. Drupal.rl
- * coalesces all of these with any other RL calls on the page into a
- * single POST.
+ * The winning variant is picked server-side in NewsletterBlock::build()
+ * and the button is rendered with the winning text already in place. This
+ * file only needs to report the impression when the form enters the
+ * viewport and the conversion when the user clicks the submit button.
+ * Both events go through Drupal.rl, which batches them with any other RL
+ * calls on the page.
  */
 
 (function (Drupal, drupalSettings, once) {
 
   'use strict';
 
-  Drupal.behaviors.rlExampleFrontendABTesting = {
+  Drupal.behaviors.rlExampleFrontendTracking = {
     attach: function (context) {
       var config = drupalSettings.rlExampleFrontend;
-      if (!config) {
+      if (!config || !config.experimentId || !config.armId) {
         return;
       }
 
       once('rl-frontend-ab', '.rl-example-frontend-newsletter-form', context).forEach(function (form) {
-        Drupal.rl.decide(config.experimentId, Object.keys(config.buttonTexts))
-          .then(function (armId) {
-            if (!config.buttonTexts[armId]) {
-              return;
-            }
-            var submitButton = form.querySelector('input[type="submit"]');
-            if (submitButton) {
-              submitButton.value = config.buttonTexts[armId];
-            }
-            observeTurn(form, config.experimentId, armId);
-            bindReward(form, config.experimentId, armId);
-          })
-          .catch(function () {
-            // Leave the default button text in place on decide failure.
-          });
-      });
-
-      function observeTurn(form, experimentId, armId) {
         var observer = new IntersectionObserver(function (entries) {
           entries.forEach(function (entry) {
             if (entry.isIntersecting) {
-              Drupal.rl.turn(experimentId, armId);
+              Drupal.rl.turn(config.experimentId, config.armId);
               observer.disconnect();
             }
           });
         }, { threshold: 0.5 });
         observer.observe(form);
-      }
 
-      function bindReward(form, experimentId, armId) {
         var submitButton = form.querySelector('input[type="submit"]');
-        if (!submitButton) {
-          return;
+        if (submitButton) {
+          submitButton.addEventListener('click', function () {
+            Drupal.rl.reward(config.experimentId, config.armId);
+          });
         }
-        submitButton.addEventListener('click', function () {
-          Drupal.rl.reward(experimentId, armId);
-        });
-      }
+      });
     },
   };
 
diff --git a/modules/rl_example_frontend/src/Plugin/Block/NewsletterBlock.php b/modules/rl_example_frontend/src/Plugin/Block/NewsletterBlock.php
index d8676ee..57c9886 100644
--- a/modules/rl_example_frontend/src/Plugin/Block/NewsletterBlock.php
+++ b/modules/rl_example_frontend/src/Plugin/Block/NewsletterBlock.php
@@ -8,10 +8,21 @@
 use Drupal\Core\Messenger\MessengerInterface;
 use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
 use Drupal\rl\Registry\ExperimentRegistryInterface;
+use Drupal\rl\Service\CacheManager;
+use Drupal\rl\Service\ExperimentManagerInterface;
 use Symfony\Component\DependencyInjection\ContainerInterface;
 
 /**
- * Provides a newsletter signup block with frontend A/B tested button text.
+ * Provides a newsletter signup block with A/B tested button text.
+ *
+ * Companion to the rl_example block. Both decide the winning variant
+ * server-side and track turns / rewards through the Drupal.rl JS API.
+ * The distinction is how conversions are recorded:
+ *   - rl_example records the reward in a Drupal AJAX submit callback,
+ *     which round-trips through a full Drupal request.
+ *   - rl_example_frontend records the reward with Drupal.rl.reward() from
+ *     a click handler, which goes through the thin rl.php endpoint and
+ *     does not block the submit flow.
  *
  * @Block(
  *   id = "rl_example_frontend_newsletter",
@@ -20,6 +31,13 @@
  */
 class NewsletterBlock extends BlockBase implements ContainerFactoryPluginInterface {
 
+  /**
+   * The RL experiment manager.
+   *
+   * @var \Drupal\rl\Service\ExperimentManagerInterface
+   */
+  protected $experimentManager;
+
   /**
    * The RL experiment registry.
    *
@@ -34,6 +52,13 @@ class NewsletterBlock extends BlockBase implements ContainerFactoryPluginInterfa
    */
   protected $messenger;
 
+  /**
+   * The RL cache manager.
+   *
+   * @var \Drupal\rl\Service\CacheManager
+   */
+  protected $cacheManager;
+
   /**
    * The experiment ID.
    *
@@ -59,12 +84,16 @@ public function __construct(
     array $configuration,
     $plugin_id,
     $plugin_definition,
+    ExperimentManagerInterface $experiment_manager,
     ExperimentRegistryInterface $experiment_registry,
     MessengerInterface $messenger,
+    CacheManager $cache_manager,
   ) {
     parent::__construct($configuration, $plugin_id, $plugin_definition);
+    $this->experimentManager = $experiment_manager;
     $this->experimentRegistry = $experiment_registry;
     $this->messenger = $messenger;
+    $this->cacheManager = $cache_manager;
 
     // Use deterministic ID for this specific experiment.
     $this->experimentId = 'rl_example_frontend-newsletter_button';
@@ -86,8 +115,10 @@ public static function create(ContainerInterface $container, array $configuratio
       $configuration,
       $plugin_id,
       $plugin_definition,
+      $container->get('rl.experiment_manager'),
       $container->get('rl.experiment_registry'),
       $container->get('messenger'),
+      $container->get('rl.cache_manager'),
     );
   }
 
@@ -95,7 +126,17 @@ public static function create(ContainerInterface $container, array $configuratio
    * {@inheritdoc}
    */
   public function build() {
-    // Build minimal form with fixed button text - JavaScript will override it.
+    // Decide which variant to render in PHP. The arm list is owned right
+    // here in the block config so the rl core never needs to know it.
+    $scores = $this->experimentManager->getThompsonScores(
+      $this->experimentId,
+      NULL,
+      array_keys($this->buttonTexts)
+    );
+    arsort($scores);
+    $best_id = key($scores);
+    $button_text = $this->buttonTexts[$best_id];
+
     $form = [
       '#type' => 'form',
       '#attributes' => ['class' => ['rl-example-frontend-newsletter-form']],
@@ -107,25 +148,25 @@ public function build() {
       '#required' => TRUE,
     ];
 
-    // Fixed button text that JavaScript will replace.
     $form['submit'] = [
       '#type' => 'submit',
-    // Default fallback text.
-      '#value' => 'Subscribe',
+      '#value' => $button_text,
       '#ajax' => [
         'callback' => [$this, 'submitCallback'],
       ],
     ];
 
-    // Attach JavaScript library and settings for frontend A/B testing. The
-    // rl.php endpoint URL comes from drupalSettings.rl.endpointUrl, which
-    // rl_page_attachments() publishes when the rl/api library is loaded.
+    // Tell the tracking JS which arm was picked. The rl.php endpoint URL
+    // comes from drupalSettings.rl.endpointUrl, published by
+    // rl_page_attachments() whenever the rl/api library is loaded.
     $form['#attached']['library'][] = 'rl_example_frontend/frontend_ab_testing';
     $form['#attached']['drupalSettings']['rlExampleFrontend'] = [
       'experimentId' => $this->experimentId,
-      'buttonTexts' => $this->buttonTexts,
+      'armId' => $best_id,
     ];
 
+    $this->cacheManager->overridePageCacheIfShorter($this->getCacheMaxAge());
+
     return $form;
   }
 
@@ -133,13 +174,22 @@ public function build() {
    * AJAX callback for form submission.
    */
   public function submitCallback(array &$form, $form_state) {
-    // Note: Reward tracking is handled by JavaScript in this frontend example.
-    // The JavaScript sends the reward signal directly to rl.php.
-    // Create AJAX response with success message.
+    // Reward tracking is handled by Drupal.rl.reward() from the JS click
+    // handler, not here.
     $response = new AjaxResponse();
     $response->addCommand(new MessageCommand($this->t('Thanks for subscribing!')));
 
     return $response;
   }
 
+  /**
+   * {@inheritdoc}
+   */
+  public function getCacheMaxAge() {
+    // Short cache lifetime so the server-rendered button text can change
+    // as Thompson Sampling scores evolve. 60 seconds trades off learning
+    // speed against server load.
+    return 60;
+  }
+
 }
diff --git a/rl.php b/rl.php
index ca5dcaa..ec3c0b4 100644
--- a/rl.php
+++ b/rl.php
@@ -6,50 +6,67 @@
  *
  * Following the statistics.php architecture for optimal performance.
  *
- * Two actions are supported:
+ * Four actions are supported:
  *   - ping: liveness check, no experiment touched.
+ *   - turn / turns / reward: legacy form-POST tracking used by
+ *     production consumers (ai_sorting, and any third-party JS that was
+ *     written before Drupal.rl shipped). These remain fully supported.
  *   - batch: JSON POST body used by Drupal.rl on the client side. Carries
- *     multiple decide / turn / reward events for potentially several
- *     experiments in a single request. See the docblock on
- *     handle_batch_request() below for the payload shape.
+ *     multiple turn and reward events for potentially several experiments
+ *     in a single request. See the docblock on handle_batch_request()
+ *     below for the payload shape.
  *
- * The legacy action=turn / action=turns / action=reward / action=decide
- * form endpoints were removed in favor of action=batch when the shared
- * Drupal.rl client library was introduced.
+ * Deciding which variant to show is an application concern that belongs in
+ * PHP at render time (see ai_sorting's Views sort plugin, or
+ * VariantSelectorBase in this module). rl.php intentionally does not
+ * expose a client-side decide endpoint.
  */
 
 use Drupal\Core\DrupalKernel;
 use Symfony\Component\HttpFoundation\Request;
 
-// Action can arrive in the query string (JSON batch requests) or as a form
-// field (ping uses form POST from the Drupal health check).
+// The action can arrive in the query string (Drupal.rl batch requests) or
+// as a form field (legacy consumers + ping).
 $action = $_GET['action'] ?? filter_input(INPUT_POST, 'action', FILTER_SANITIZE_FULL_SPECIAL_CHARS);
 
-// Ping is a cheap liveness check used by hook_requirements() to verify the
-// web server serves rl.php directly. No Drupal bootstrap needed.
+// Ping is a cheap liveness check used by hook_requirements() to verify
+// the web server serves rl.php directly. No Drupal bootstrap needed.
 if ($action === 'ping') {
   http_response_code(200);
   exit('pong');
 }
 
-if ($action !== 'batch') {
-  http_response_code(400);
-  exit('Invalid action');
+$experiment_id = NULL;
+$arm_id = NULL;
+$payload = NULL;
+
+if ($action === 'batch') {
+  // Read and decode the JSON body before bootstrapping Drupal so malformed
+  // requests cost nothing.
+  $raw_body = file_get_contents('php://input');
+  if ($raw_body === FALSE || $raw_body === '') {
+    http_response_code(400);
+    header('Content-Type: application/json');
+    exit('{"error":"empty body"}');
+  }
+  $payload = json_decode($raw_body, TRUE);
+  if (!is_array($payload)) {
+    http_response_code(400);
+    header('Content-Type: application/json');
+    exit('{"error":"invalid json"}');
+  }
 }
-
-// Read and decode the JSON body before bootstrapping Drupal so malformed
-// requests cost nothing.
-$raw_body = file_get_contents('php://input');
-if ($raw_body === FALSE || $raw_body === '') {
-  http_response_code(400);
-  header('Content-Type: application/json');
-  exit('{"decisions":{}}');
+elseif (in_array($action, ['turn', 'turns', 'reward'], TRUE)) {
+  $experiment_id = filter_input(INPUT_POST, 'experiment_id', FILTER_SANITIZE_FULL_SPECIAL_CHARS);
+  $arm_id = filter_input(INPUT_POST, 'arm_id', FILTER_SANITIZE_FULL_SPECIAL_CHARS);
+  if (!$experiment_id || !preg_match('/^[a-zA-Z0-9_-]+$/', $experiment_id)) {
+    http_response_code(400);
+    exit('Invalid experiment_id');
+  }
 }
-$payload = json_decode($raw_body, TRUE);
-if (!is_array($payload)) {
+else {
   http_response_code(400);
-  header('Content-Type: application/json');
-  exit('{"decisions":{}}');
+  exit('Invalid action');
 }
 
 try {
@@ -84,14 +101,53 @@
 
   $registry = $container->get('rl.experiment_registry');
   $storage = $container->get('rl.experiment_data_storage');
-  $manager = $container->has('rl.experiment_manager') ? $container->get('rl.experiment_manager') : NULL;
 
-  $decisions = handle_batch_request($payload, $registry, $storage, $manager);
+  if ($action === 'batch') {
+    handle_batch_request($payload, $registry, $storage);
+    http_response_code(200);
+    header('Content-Type: application/json');
+    header('Cache-Control: no-store, private, max-age=0');
+    echo '{"ok":true}';
+    exit;
+  }
+
+  if (!$registry->isRegistered($experiment_id)) {
+    exit();
+  }
+
+  switch ($action) {
+    case 'turn':
+      if ($arm_id && preg_match('/^[a-zA-Z0-9_-]+$/', $arm_id)) {
+        $storage->recordTurn($experiment_id, $arm_id);
+      }
+      break;
+
+    case 'turns':
+      $arm_ids = filter_input(INPUT_POST, 'arm_ids', FILTER_SANITIZE_FULL_SPECIAL_CHARS);
+      if ($arm_ids) {
+        $arm_ids_array = array_map('trim', explode(',', $arm_ids));
+
+        $valid_arm_ids = [];
+        foreach ($arm_ids_array as $aid) {
+          if (preg_match('/^[a-zA-Z0-9_-]+$/', $aid)) {
+            $valid_arm_ids[] = $aid;
+          }
+        }
+
+        if (!empty($valid_arm_ids)) {
+          $storage->recordTurns($experiment_id, $valid_arm_ids);
+        }
+      }
+      break;
+
+    case 'reward':
+      if ($arm_id && preg_match('/^[a-zA-Z0-9_-]+$/', $arm_id)) {
+        $storage->recordReward($experiment_id, $arm_id);
+      }
+      break;
+  }
 
   http_response_code(200);
-  header('Content-Type: application/json');
-  header('Cache-Control: no-store, private, max-age=0');
-  echo json_encode(['decisions' => $decisions]);
 }
 catch (\Exception $e) {
   // Log error and return 500.
@@ -103,78 +159,25 @@
 /**
  * Process a Drupal.rl batch payload.
  *
- * Expected JSON shape (each section is optional):
+ * Expected JSON shape (both sections are optional):
  * @code
  * {
- *   "decides": [
- *     {"id": "<experiment_id>", "arms": ["v0", "v1", ...]},
- *     ...
- *   ],
  *   "turns":   [{"id": "<experiment_id>", "arm": "v0"}, ...],
  *   "rewards": [{"id": "<experiment_id>", "arm": "v1"}, ...]
  * }
  * @endcode
  *
- * Returns the decisions map keyed by experiment id:
- * @code
- * {"<experiment_id>": {"armId": "v1"}, ...}
- * @endcode
- *
  * Unknown or malformed entries are silently skipped so one bad event does
- * not poison the rest of the batch. Callers that receive no decision for a
- * given experiment should fall back to their own default variant.
+ * not poison the rest of the batch.
  *
  * @param array $payload
  *   The decoded JSON body.
  * @param \Drupal\rl\Registry\ExperimentRegistryInterface $registry
  * @param \Drupal\rl\Storage\ExperimentDataStorageInterface $storage
- * @param \Drupal\rl\Service\ExperimentManagerInterface|null $manager
- *
- * @return object
- *   Decisions object (stdClass to preserve JSON object shape when empty).
  */
-function handle_batch_request(array $payload, $registry, $storage, $manager): \stdClass {
-  $decisions = new \stdClass();
+function handle_batch_request(array $payload, $registry, $storage): void {
   $id_pattern = '/^[a-zA-Z0-9_-]+$/';
 
-  if ($manager !== NULL && isset($payload['decides']) && is_array($payload['decides'])) {
-    foreach ($payload['decides'] as $decide) {
-      if (!is_array($decide)) {
-        continue;
-      }
-      $eid = isset($decide['id']) ? (string) $decide['id'] : '';
-      if ($eid === '' || !preg_match($id_pattern, $eid)) {
-        continue;
-      }
-      if (!$registry->isRegistered($eid)) {
-        continue;
-      }
-      $arms = $decide['arms'] ?? [];
-      if (!is_array($arms) || count($arms) < 2) {
-        continue;
-      }
-      $arm_ids = [];
-      foreach ($arms as $arm) {
-        $arm_id = (string) $arm;
-        if ($arm_id === '' || !preg_match($id_pattern, $arm_id)) {
-          continue 2;
-        }
-        $arm_ids[] = $arm_id;
-      }
-      try {
-        $scores = $manager->getThompsonScores($eid, NULL, $arm_ids);
-      }
-      catch (\Throwable $e) {
-        continue;
-      }
-      if (!is_array($scores) || !$scores) {
-        continue;
-      }
-      arsort($scores);
-      $decisions->{$eid} = ['armId' => (string) key($scores)];
-    }
-  }
-
   if (isset($payload['turns']) && is_array($payload['turns'])) {
     foreach ($payload['turns'] as $turn) {
       if (!is_array($turn)) {
@@ -214,6 +217,4 @@ function handle_batch_request(array $payload, $registry, $storage, $manager): \s
       $storage->recordReward($eid, $aid);
     }
   }
-
-  return $decisions;
 }

From 171d254ccdccdd104a7dd4ba7af8ee82704c9f01 Mon Sep 17 00:00:00 2001
From: Jurriaan Roelofs <jur@dxpr.com>
Date: Wed, 15 Apr 2026 14:47:15 +0200
Subject: [PATCH 4/6] fix(lint): satisfy drupal-lint on rl.php

- Add missing @param descriptions for $registry and $storage in
  handle_batch_request().
- Replace direct $_GET access with filter_input(INPUT_GET, ...) so the
  Drupal coding standards sniff for super globals stays happy.
  request_stack is not usable here because action dispatch has to
  happen before the Drupal kernel boots.
---
 rl.php | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/rl.php b/rl.php
index ec3c0b4..5b98ff2 100644
--- a/rl.php
+++ b/rl.php
@@ -27,7 +27,8 @@
 
 // The action can arrive in the query string (Drupal.rl batch requests) or
 // as a form field (legacy consumers + ping).
-$action = $_GET['action'] ?? filter_input(INPUT_POST, 'action', FILTER_SANITIZE_FULL_SPECIAL_CHARS);
+$action = filter_input(INPUT_GET, 'action', FILTER_SANITIZE_FULL_SPECIAL_CHARS)
+  ?: filter_input(INPUT_POST, 'action', FILTER_SANITIZE_FULL_SPECIAL_CHARS);
 
 // Ping is a cheap liveness check used by hook_requirements() to verify
 // the web server serves rl.php directly. No Drupal bootstrap needed.
@@ -173,7 +174,9 @@
  * @param array $payload
  *   The decoded JSON body.
  * @param \Drupal\rl\Registry\ExperimentRegistryInterface $registry
+ *   The experiment registry used to validate experiment ids.
  * @param \Drupal\rl\Storage\ExperimentDataStorageInterface $storage
+ *   The experiment data storage used to persist turns and rewards.
  */
 function handle_batch_request(array $payload, $registry, $storage): void {
   $id_pattern = '/^[a-zA-Z0-9_-]+$/';

From bde2cd4b4e8d9dbf4348576544f65b51633554fc Mon Sep 17 00:00:00 2001
From: Jurriaan Roelofs <jur@dxpr.com>
Date: Wed, 15 Apr 2026 15:23:14 +0200
Subject: [PATCH 5/6] feat(rl): add Drupal.rl.decide with DOM-read arm list

Absorbs PR #44 into the Drupal.rl batch transport so client-decide
consumers (DXPR Builder and similar full-page-cache builders) share
a single round trip with the turn/reward tracking already batched by
Drupal.rl.

- js/rl.js gains Drupal.rl.decide(experimentId, armIds) returning a
  Promise<armId>. Decides share the same 500 ms queue and the same
  POST as turns and rewards, so a page with a variant block plus
  other RL tracking ends up making one request instead of two.
  Fallback on server failure or missing decision resolves to
  armIds[0] so callers never need a .catch() for the common path.
- rl.php handle_batch_request processes an optional decides section,
  calls ExperimentManager::getThompsonScores to seed cold-start
  priors, and returns a decisions map keyed by experiment id. The
  batch response becomes {"ok":true,"decisions":{...}}.
- Documentation adds a "decide discipline" section: callers must
  read arm ids from a DOM attribute that the server-side renderer
  emitted, never hardcode. This mirrors ai_sorting's PHP pattern of
  recomputing arm ids from the current view query on every render
  and keeps JS drift-free without forcing the rl core to store arm
  lists. The convention (v0..vN, UUIDs, node ids) is whatever the
  builder emits; rl core is arm-agnostic.
---
 README.md                 |  90 +++++++++++++++-----
 docs/rl_project_desc.html |  41 +++++++--
 js/rl.js                  | 175 +++++++++++++++++++++++++++++++++-----
 rl.php                    |  84 ++++++++++++++++--
 4 files changed, 337 insertions(+), 53 deletions(-)

diff --git a/README.md b/README.md
index eff06b7..2843545 100644
--- a/README.md
+++ b/README.md
@@ -215,9 +215,11 @@ $cache_manager->overridePageCacheIfShorter(60); // 60 seconds
 
 ## Deciding which variant to show
 
-Pick the winning variant in PHP at render time. Your consumer already
-has the full arm set in hand (entity fields, view filters, plugin
-config, etc.), so it can call the RL service directly:
+### Server-side (preferred)
+
+Pick the winning variant in PHP at render time whenever you can. Your
+consumer already has the full arm set in hand (entity fields, view
+filters, plugin config), so it can call the RL service directly:
 
 ```php
 $scores = $experiment_manager->getThompsonScores(
@@ -230,21 +232,24 @@ $best_arm = key($scores);
 ```
 
 Deciding server-side keeps the arm list where it belongs (with the
-experiment owner) and avoids shipping it to the browser. See
-`ai_sorting`'s Views sort plugin for the canonical pattern and
+experiment owner) and avoids a network round trip on every page load.
+See `ai_sorting`'s Views sort plugin for the canonical pattern and
 `VariantSelectorBase` in this module for a reusable base class.
 
-There is deliberately no client-side decide API. Client-side decides
-would force runtime JS to know the current arm set, which drifts out of
-sync as experiment managers add or remove variants.
+### Client-side (cache-friendly path)
+
+Some consumers have to decide in JS: full-page-cached builders that
+render all variants into the HTML and swap them on the client so they
+can keep Varnish/Fastly caching. For that case there is
+`Drupal.rl.decide()`, documented below.
 
 ## JavaScript API (`Drupal.rl`)
 
 Attach the `rl/api` library to make `Drupal.rl` available. It is a thin
-transport proxy that coalesces every impression and conversion fired on
-the page into one batched POST to `rl.php`, so N experiments on the same
-page produce just one or two tracking requests instead of one pair per
-experiment.
+transport proxy that coalesces every decide, impression, and conversion
+fired on the page into a single batched POST to `rl.php`, so N
+experiments on the same page produce one or two requests instead of one
+set per experiment.
 
 ```javascript
 // Record an impression when the variant becomes visible.
@@ -253,17 +258,51 @@ Drupal.rl.turn('hero_cta', 'v0');
 // Record a conversion when the user clicks / submits / converts.
 Drupal.rl.reward('hero_cta', 'v0');
 
+// Ask for a decision when the variant needs to be chosen client-side.
+// The arm list MUST be read from the DOM - see discipline below.
+var container = document.querySelector('[data-rl-experiment="hero_cta"]');
+var armIds = container.dataset.rlArms.split(',');
+Drupal.rl.decide('hero_cta', armIds).then(function (armId) {
+  showVariant(armId);
+});
+
 // Optional: force an immediate flush.
 Drupal.rl.flush();
 ```
 
-Events accumulate for 500 ms and then flush in a single POST. Buffered
-events are also flushed via `navigator.sendBeacon` on `visibilitychange`
-and `pagehide` so they survive navigation.
+Events accumulate for 500 ms and then flush in one POST. Decide,
+turn, and reward events share the same queue and the same request, so
+a page with a DXPR Builder variant block plus tracking on other
+elements ends up making a single round trip. Buffered tracking events
+are also flushed via `navigator.sendBeacon` on `visibilitychange` and
+`pagehide` so they survive navigation.
+
+### Discipline for `decide()`
+
+> **Never hardcode arm ids in JS. Always read them from a DOM
+> attribute that the server-side renderer emitted.**
+
+Rationale: the DOM is downstream of the same server-render pipeline
+that produced the decide's context. When the experiment manager adds
+or removes a variant, the consumer's page cache is invalidated, the
+next render emits the new attribute, and JS picks it up. JS never
+asserts what the arm set is - it just echoes whatever the current
+cached HTML says, mirroring ai_sorting's PHP pattern of recomputing
+`$arm_ids` from a fresh view query on every render. This keeps
+`Drupal.rl.decide()` drift-free without requiring the rl core to
+store arm lists.
+
+The convention your builder uses internally (numeric `v0..vN`, UUIDs,
+node ids, anything matching `^[a-zA-Z0-9_-]+$`) is whatever you emit
+into the attribute. The rl core is arm-agnostic.
+
+If the server returns no decision for an experiment (not registered,
+no data, network error), the returned promise resolves to `armIds[0]`
+so callers never need a `.catch()` for the common path.
 
 `Drupal.rl` is one transport among several. Modules that already ship
-their own tracking JS (like `ai_sorting`, which batches turns on its own
-100 ms window and posts them as form data) keep working untouched.
+their own tracking JS (like `ai_sorting`, which batches turns on its
+own 100 ms window and posts them as form data) keep working untouched.
 
 ## HTTP API (`rl.php`)
 
@@ -312,6 +351,9 @@ POST /modules/contrib/rl/rl.php?action=batch
 Content-Type: application/json
 
 {
+  "decides": [
+    {"id": "hero_cta", "arms": ["v0", "v1", "v2"]}
+  ],
   "turns": [
     {"id": "hero_cta", "arm": "v0"},
     {"id": "menu_main_5", "arm": "v1"}
@@ -322,9 +364,17 @@ Content-Type: application/json
 }
 ```
 
-Both sections are optional. Invalid or unregistered entries are dropped
-silently so one bad event does not poison the rest of the batch. The
-response is `{"ok":true}` with HTTP 200; writes are fire-and-forget.
+All three sections are optional. Invalid or unregistered entries are
+dropped silently so one bad event does not poison the rest of the
+batch. The response is
+
+```json
+{"ok":true,"decisions":{"hero_cta":{"armId":"v1"}}}
+```
+
+`decisions` contains only entries that had a successful Thompson
+Sampling lookup. Missing keys mean "use the default variant". Turns
+and rewards are fire-and-forget writes with no per-event response.
 
 ### Curl examples
 
diff --git a/docs/rl_project_desc.html b/docs/rl_project_desc.html
index e95bee4..d9838f9 100644
--- a/docs/rl_project_desc.html
+++ b/docs/rl_project_desc.html
@@ -149,7 +149,9 @@ <h3>API</h3>
 
 <h3>Deciding which variant to show</h3>
 
-<p>Pick the winning variant in PHP at render time. Your consumer already has the full arm set in hand (entity fields, view filters, plugin config), so it can call the RL service directly:</p>
+<h4>Server-side (preferred)</h4>
+
+<p>Pick the winning variant in PHP at render time whenever you can. Your consumer already has the full arm set in hand (entity fields, view filters, plugin config), so it can call the RL service directly:</p>
 
 <pre><code>$scores = $experiment_manager->getThompsonScores(
   'my_experiment',
@@ -159,11 +161,15 @@ <h3>Deciding which variant to show</h3>
 arsort($scores);
 $best_arm = key($scores);</code></pre>
 
-<p>Deciding server-side keeps the arm list where it belongs (with the experiment owner) and avoids shipping it to the browser. See <code>ai_sorting</code>'s Views sort plugin for the canonical pattern and <code>VariantSelectorBase</code> in this module for a reusable base class. There is deliberately no client-side decide API.</p>
+<p>Deciding server-side keeps the arm list where it belongs (with the experiment owner) and avoids a network round trip on every page load. See <code>ai_sorting</code>'s Views sort plugin for the canonical pattern and <code>VariantSelectorBase</code> in this module for a reusable base class.</p>
+
+<h4>Client-side (cache-friendly path)</h4>
+
+<p>Some consumers have to decide in JS: full-page-cached builders that render all variants into the HTML and swap them on the client so they can keep Varnish / Fastly caching. For that case there is <code>Drupal.rl.decide()</code>, documented below.</p>
 
 <h3>JavaScript API (<code>Drupal.rl</code>)</h3>
 
-<p>Attach the <code>rl/api</code> library to make <code>Drupal.rl</code> available. It is a thin transport proxy that coalesces every impression and conversion fired on the page into one batched POST to <code>rl.php</code>:</p>
+<p>Attach the <code>rl/api</code> library to make <code>Drupal.rl</code> available. It is a thin transport proxy that coalesces every decide, impression, and conversion fired on the page into a single batched POST to <code>rl.php</code>:</p>
 
 <pre><code>// Record an impression when the variant becomes visible.
 Drupal.rl.turn('hero_cta', 'v0');
@@ -171,10 +177,28 @@ <h3>JavaScript API (<code>Drupal.rl</code>)</h3>
 // Record a conversion when the user clicks / submits / converts.
 Drupal.rl.reward('hero_cta', 'v0');
 
+// Ask for a decision when the variant needs to be chosen client-side.
+// The arm list MUST be read from the DOM - see discipline below.
+var container = document.querySelector('[data-rl-experiment="hero_cta"]');
+var armIds = container.dataset.rlArms.split(',');
+Drupal.rl.decide('hero_cta', armIds).then(function (armId) {
+  showVariant(armId);
+});
+
 // Optional: force an immediate flush.
 Drupal.rl.flush();</code></pre>
 
-<p>Events accumulate for 500 ms and then flush in a single POST. Buffered events are also flushed via <code>navigator.sendBeacon</code> on <code>visibilitychange</code> and <code>pagehide</code> so they survive navigation.</p>
+<p>Events accumulate for 500 ms and then flush in one POST. Decide, turn, and reward events share the same queue and the same request, so a page with a DXPR Builder variant block plus tracking on other elements ends up making a single round trip. Buffered tracking events are also flushed via <code>navigator.sendBeacon</code> on <code>visibilitychange</code> and <code>pagehide</code> so they survive navigation.</p>
+
+<h4>Discipline for <code>decide()</code></h4>
+
+<blockquote><strong>Never hardcode arm ids in JS. Always read them from a DOM attribute that the server-side renderer emitted.</strong></blockquote>
+
+<p>Rationale: the DOM is downstream of the same server-render pipeline that produced the decide's context. When the experiment manager adds or removes a variant, the consumer's page cache is invalidated, the next render emits the new attribute, and JS picks it up. JS never asserts what the arm set is - it just echoes whatever the current cached HTML says, mirroring ai_sorting's PHP pattern of recomputing <code>$arm_ids</code> from a fresh view query on every render. This keeps <code>Drupal.rl.decide()</code> drift-free without requiring the rl core to store arm lists.</p>
+
+<p>The convention your builder uses internally (numeric <code>v0..vN</code>, UUIDs, node ids, anything matching <code>^[a-zA-Z0-9_-]+$</code>) is whatever you emit into the attribute. The rl core is arm-agnostic.</p>
+
+<p>If the server returns no decision for an experiment (not registered, no data, network error), the returned promise resolves to <code>armIds[0]</code> so callers never need a <code>.catch()</code> for the common path.</p>
 
 <p><code>Drupal.rl</code> is one transport among several. Modules that already ship their own tracking JS (like <code>ai_sorting</code>, which batches turns on its own 100 ms window and posts form data) keep working untouched.</p>
 
@@ -214,6 +238,9 @@ <h4><code>action=batch</code></h4>
 Content-Type: application/json
 
 {
+  "decides": [
+    {"id": "hero_cta", "arms": ["v0", "v1", "v2"]}
+  ],
   "turns": [
     {"id": "hero_cta", "arm": "v0"},
     {"id": "menu_main_5", "arm": "v1"}
@@ -223,7 +250,11 @@ <h4><code>action=batch</code></h4>
   ]
 }</code></pre>
 
-<p>Both sections are optional. Invalid or unregistered entries are dropped silently. The response is <code>{"ok":true}</code> with HTTP 200; writes are fire-and-forget.</p>
+<p>All three sections are optional. Invalid or unregistered entries are dropped silently. The response is</p>
+
+<pre><code>{"ok":true,"decisions":{"hero_cta":{"armId":"v1"}}}</code></pre>
+
+<p><code>decisions</code> contains only entries that had a successful Thompson Sampling lookup. Missing keys mean "use the default variant". Turns and rewards are fire-and-forget writes with no per-event response.</p>
 
 <p><strong>Performance note:</strong> <code>rl.php</code> bootstraps a minimal Drupal kernel per request (same pattern as core's <code>statistics.php</code>). One boot processes the whole batch, so non-browser callers should coalesce events into a single request whenever they can.</p>
 
diff --git a/js/rl.js b/js/rl.js
index c583063..393043e 100644
--- a/js/rl.js
+++ b/js/rl.js
@@ -2,20 +2,31 @@
  * @file
  * Thin RL transport proxy with request batching.
  *
- * Exposes Drupal.rl.turn(), Drupal.rl.reward(), and Drupal.rl.flush().
- * Batches calls into a single POST to rl.php so that multiple RL-powered
- * features on the same page share one request instead of each making its
- * own.
+ * Exposes Drupal.rl.decide(), Drupal.rl.turn(), Drupal.rl.reward(), and
+ * Drupal.rl.flush(). Batches calls into a single POST to rl.php so that
+ * multiple RL-powered features on the same page share one request
+ * instead of each making its own.
  *
  * Batching strategy: events accumulate for 500 ms and then flush in one
- * POST. visibilitychange / pagehide flush immediately via
+ * POST that can carry decides, turns, and rewards simultaneously.
+ * visibilitychange / pagehide flush tracking writes immediately via
  * navigator.sendBeacon so buffered events survive navigation.
  *
- * Deciding which variant to show is a server-side concern - see
- * ai_sorting's Views sort plugin or VariantSelectorBase in this module.
- * Drupal.rl deliberately does not provide a decide API: client-side
- * decides would require the caller to know the current arm set, which
- * belongs in the experiment owner's domain model, not in runtime JS.
+ * About decide(): client-side decide exists to serve consumers that
+ * render variants in JS (DXPR Builder's runtime, etc.) where shifting
+ * the decision to PHP would burn full-page cache. Consumers that can
+ * decide server-side (ai_sorting, rl_page_title, rl_menu_link,
+ * rl_example, rl_example_frontend) should keep doing so; decide() is
+ * for the client-rendered path only.
+ *
+ * Important discipline for callers:
+ *   Read the arm id list from the DOM at call time. Do not hardcode
+ *   arm ids in JS. The server-side renderer that produced the page's
+ *   cached HTML should emit the arm list as a data attribute on the
+ *   variant container; decide() just echoes that list back to the
+ *   server so Thompson Sampling can seed cold-start arms. This mirrors
+ *   ai_sorting's PHP pattern of recomputing the arm list from the
+ *   current view query on every render.
  *
  * Modelled on Drupal.history in Drupal core, which batches node-view
  * tracking the same way.
@@ -31,7 +42,12 @@
   var timer = null;
 
   function emptyQueue() {
-    return { turns: [], rewards: [] };
+    return {
+      // experimentId -> { arms: [...], resolvers: [fn] }
+      decides: Object.create(null),
+      turns: [],
+      rewards: [],
+    };
   }
 
   function endpoint() {
@@ -42,6 +58,11 @@
   }
 
   function hasPending() {
+    for (var id in queue.decides) {
+      if (Object.prototype.hasOwnProperty.call(queue.decides, id)) {
+        return true;
+      }
+    }
     return queue.turns.length > 0 || queue.rewards.length > 0;
   }
 
@@ -65,18 +86,67 @@
     return url + (url.indexOf('?') === -1 ? '?' : '&') + 'action=batch';
   }
 
+  function buildPayload(snapshot) {
+    var decides = [];
+    for (var id in snapshot.decides) {
+      if (Object.prototype.hasOwnProperty.call(snapshot.decides, id)) {
+        decides.push({ id: id, arms: snapshot.decides[id].arms });
+      }
+    }
+    return {
+      decides: decides,
+      turns: snapshot.turns,
+      rewards: snapshot.rewards,
+    };
+  }
+
+  function resolveDecides(snapshot, decisions) {
+    for (var id in snapshot.decides) {
+      if (!Object.prototype.hasOwnProperty.call(snapshot.decides, id)) {
+        continue;
+      }
+      var entry = snapshot.decides[id];
+      var armId = null;
+      if (decisions && decisions[id] && decisions[id].armId) {
+        armId = decisions[id].armId;
+      }
+      // Fallback: first arm in the caller-provided list. This keeps the
+      // promise contract "always resolves to a usable arm" so consumers
+      // do not need a .catch() for the common failure modes (unknown
+      // experiment, empty data, network error).
+      if (!armId) {
+        armId = entry.arms[0];
+      }
+      entry.resolvers.forEach(function (resolve) {
+        resolve(armId);
+      });
+    }
+  }
+
+  function fallbackDecides(snapshot) {
+    for (var id in snapshot.decides) {
+      if (!Object.prototype.hasOwnProperty.call(snapshot.decides, id)) {
+        continue;
+      }
+      var entry = snapshot.decides[id];
+      var fallback = entry.arms[0];
+      entry.resolvers.forEach(function (resolve) {
+        resolve(fallback);
+      });
+    }
+  }
+
   function flush() {
     if (!hasPending()) {
       return;
     }
     var url = endpoint();
+    var snapshot = takeQueue();
     if (!url) {
-      // No endpoint configured - drop the queue rather than dangling.
-      takeQueue();
+      fallbackDecides(snapshot);
       return;
     }
-    var snapshot = takeQueue();
-    var body = JSON.stringify(snapshot);
+    var body = JSON.stringify(buildPayload(snapshot));
 
     fetch(batchUrl(url), {
       method: 'POST',
@@ -84,8 +154,18 @@
       body: body,
       credentials: 'same-origin',
       keepalive: true,
+    }).then(function (response) {
+      if (!response.ok) {
+        fallbackDecides(snapshot);
+        return null;
+      }
+      return response.json();
+    }).then(function (json) {
+      if (json) {
+        resolveDecides(snapshot, json.decisions || {});
+      }
     }).catch(function () {
-      // Swallow network errors. Tracking is best-effort.
+      fallbackDecides(snapshot);
     });
   }
 
@@ -98,7 +178,20 @@
       return;
     }
     var snapshot = takeQueue();
-    var body = JSON.stringify(snapshot);
+
+    // sendBeacon is fire-and-forget: we cannot read the response, so
+    // pending decides cannot be fulfilled from this path. Resolve them
+    // with the default fallback. The page is navigating away anyway.
+    fallbackDecides(snapshot);
+
+    if (snapshot.turns.length === 0 && snapshot.rewards.length === 0) {
+      return;
+    }
+    var body = JSON.stringify({
+      decides: [],
+      turns: snapshot.turns,
+      rewards: snapshot.rewards,
+    });
 
     if ('sendBeacon' in navigator) {
       var blob = new Blob([body], { type: 'application/json' });
@@ -108,6 +201,46 @@
 
   Drupal.rl = {
 
+    /**
+     * Request a Thompson Sampling decision for an experiment.
+     *
+     * The armIds list must be read from the DOM (data attribute emitted
+     * by the server-side renderer that produced the cached HTML) at
+     * call time, never hardcoded. This mirrors ai_sorting's PHP pattern
+     * of recomputing the arm list from the current view query on every
+     * render, keeping JS and the cached HTML downstream of the same
+     * source of truth.
+     *
+     * @param {string} experimentId
+     *   The pre-registered experiment id.
+     * @param {Array<string>} armIds
+     *   The arm ids in play. Minimum 2. Must match ^[a-zA-Z0-9_-]+$
+     *   server-side (UUIDs without braces satisfy this). The winning
+     *   arm id is returned unchanged so the caller can map it back to
+     *   its own variant table.
+     *
+     * @return {Promise<string>}
+     *   Resolves to the winning arm id. Falls back to armIds[0] on any
+     *   server failure (unknown experiment, no data, network error) so
+     *   callers do not need a .catch() for the common path.
+     */
+    decide: function (experimentId, armIds) {
+      if (!Array.isArray(armIds) || armIds.length < 2) {
+        return Promise.reject(new Error('Drupal.rl.decide requires an array of at least 2 arm ids'));
+      }
+      return new Promise(function (resolve) {
+        var entry = queue.decides[experimentId];
+        if (!entry) {
+          entry = queue.decides[experimentId] = {
+            arms: armIds.slice(),
+            resolvers: [],
+          };
+        }
+        entry.resolvers.push(resolve);
+        schedule();
+      });
+    },
+
     /**
      * Record an impression for a variant.
      *
@@ -143,9 +276,11 @@
 
   };
 
-  // Flush buffered events on navigation so turns and rewards are not lost.
-  // visibilitychange covers tab switches and mobile navigation; pagehide
-  // covers desktop back/forward cache restoration.
+  // Flush buffered tracking events on navigation so turns and rewards
+  // are not lost. visibilitychange covers tab switches and mobile
+  // navigation; pagehide covers desktop back/forward cache restoration.
+  // Pending decides are resolved with the fallback arm - the page is
+  // going away so the answer no longer matters.
   document.addEventListener('visibilitychange', function () {
     if (document.visibilityState === 'hidden') {
       flushBeacon();
diff --git a/rl.php b/rl.php
index 5b98ff2..199bb53 100644
--- a/rl.php
+++ b/rl.php
@@ -102,13 +102,14 @@
 
   $registry = $container->get('rl.experiment_registry');
   $storage = $container->get('rl.experiment_data_storage');
+  $manager = $container->has('rl.experiment_manager') ? $container->get('rl.experiment_manager') : NULL;
 
   if ($action === 'batch') {
-    handle_batch_request($payload, $registry, $storage);
+    $decisions = handle_batch_request($payload, $registry, $storage, $manager);
     http_response_code(200);
     header('Content-Type: application/json');
     header('Cache-Control: no-store, private, max-age=0');
-    echo '{"ok":true}';
+    echo json_encode(['ok' => TRUE, 'decisions' => $decisions]);
     exit;
   }
 
@@ -160,16 +161,28 @@
 /**
  * Process a Drupal.rl batch payload.
  *
- * Expected JSON shape (both sections are optional):
+ * Expected JSON shape (all three sections are optional):
  * @code
  * {
- *   "turns":   [{"id": "<experiment_id>", "arm": "v0"}, ...],
- *   "rewards": [{"id": "<experiment_id>", "arm": "v1"}, ...]
+ *   "decides": [
+ *     {"id": "<experiment_id>", "arms": ["<arm>", "<arm>", ...]},
+ *     ...
+ *   ],
+ *   "turns":   [{"id": "<experiment_id>", "arm": "<arm>"}, ...],
+ *   "rewards": [{"id": "<experiment_id>", "arm": "<arm>"}, ...]
  * }
  * @endcode
  *
- * Unknown or malformed entries are silently skipped so one bad event does
- * not poison the rest of the batch.
+ * Decides resolve to Thompson Sampling winners and are returned keyed
+ * by experiment id:
+ * @code
+ * {"decisions": {"<experiment_id>": {"armId": "<arm>"}, ...}}
+ * @endcode
+ *
+ * Unknown or malformed entries are silently skipped so one bad event
+ * does not poison the rest of the batch. Callers that receive no
+ * decision for a given experiment should fall back to the first arm
+ * they passed in.
  *
  * @param array $payload
  *   The decoded JSON body.
@@ -177,9 +190,62 @@
  *   The experiment registry used to validate experiment ids.
  * @param \Drupal\rl\Storage\ExperimentDataStorageInterface $storage
  *   The experiment data storage used to persist turns and rewards.
+ * @param \Drupal\rl\Service\ExperimentManagerInterface|null $manager
+ *   The experiment manager used to compute Thompson Sampling scores.
+ *   May be NULL if the service is unavailable, in which case no
+ *   decisions are produced.
+ *
+ * @return object
+ *   A stdClass keyed by experiment id. Empty object if no decides were
+ *   requested or resolved. Uses stdClass so json_encode emits `{}`
+ *   instead of `[]` when the map is empty.
  */
-function handle_batch_request(array $payload, $registry, $storage): void {
+function handle_batch_request(array $payload, $registry, $storage, $manager = NULL): \stdClass {
   $id_pattern = '/^[a-zA-Z0-9_-]+$/';
+  $decisions = new \stdClass();
+
+  if ($manager !== NULL && isset($payload['decides']) && is_array($payload['decides'])) {
+    foreach ($payload['decides'] as $decide) {
+      if (!is_array($decide)) {
+        continue;
+      }
+      $eid = isset($decide['id']) ? (string) $decide['id'] : '';
+      if ($eid === '' || !preg_match($id_pattern, $eid)) {
+        continue;
+      }
+      if (!$registry->isRegistered($eid)) {
+        continue;
+      }
+      $arms = $decide['arms'] ?? [];
+      if (!is_array($arms) || count($arms) < 2) {
+        continue;
+      }
+      $arm_ids = [];
+      $valid = TRUE;
+      foreach ($arms as $arm) {
+        $arm_id = (string) $arm;
+        if ($arm_id === '' || !preg_match($id_pattern, $arm_id)) {
+          $valid = FALSE;
+          break;
+        }
+        $arm_ids[] = $arm_id;
+      }
+      if (!$valid) {
+        continue;
+      }
+      try {
+        $scores = $manager->getThompsonScores($eid, NULL, $arm_ids);
+      }
+      catch (\Throwable $e) {
+        continue;
+      }
+      if (!is_array($scores) || !$scores) {
+        continue;
+      }
+      arsort($scores);
+      $decisions->{$eid} = ['armId' => (string) key($scores)];
+    }
+  }
 
   if (isset($payload['turns']) && is_array($payload['turns'])) {
     foreach ($payload['turns'] as $turn) {
@@ -220,4 +286,6 @@ function handle_batch_request(array $payload, $registry, $storage): void {
       $storage->recordReward($eid, $aid);
     }
   }
+
+  return $decisions;
 }

From ed60bc3e8ca977b0f24fe2d47cdd2eabf34412d1 Mon Sep 17 00:00:00 2001
From: Jurriaan Roelofs <jur@dxpr.com>
Date: Wed, 15 Apr 2026 15:26:01 +0200
Subject: [PATCH 6/6] docs: trim project description decide section to
 onboarding tone

---
 docs/rl_project_desc.html | 110 +++-----------------------------------
 1 file changed, 6 insertions(+), 104 deletions(-)

diff --git a/docs/rl_project_desc.html b/docs/rl_project_desc.html
index d9838f9..e3f8714 100644
--- a/docs/rl_project_desc.html
+++ b/docs/rl_project_desc.html
@@ -147,116 +147,18 @@ <h3>API</h3>
 $cache_manager->overridePageCacheIfShorter(60); // 60 seconds
 </code></pre>
 
-<h3>Deciding which variant to show</h3>
+<h3>JavaScript API</h3>
 
-<h4>Server-side (preferred)</h4>
+<p>Attach the <code>rl/api</code> library to get <code>Drupal.rl</code> on the page:</p>
 
-<p>Pick the winning variant in PHP at render time whenever you can. Your consumer already has the full arm set in hand (entity fields, view filters, plugin config), so it can call the RL service directly:</p>
-
-<pre><code>$scores = $experiment_manager->getThompsonScores(
-  'my_experiment',
-  NULL,
-  ['v0', 'v1', 'v2']  // arm ids owned by your domain
-);
-arsort($scores);
-$best_arm = key($scores);</code></pre>
-
-<p>Deciding server-side keeps the arm list where it belongs (with the experiment owner) and avoids a network round trip on every page load. See <code>ai_sorting</code>'s Views sort plugin for the canonical pattern and <code>VariantSelectorBase</code> in this module for a reusable base class.</p>
-
-<h4>Client-side (cache-friendly path)</h4>
-
-<p>Some consumers have to decide in JS: full-page-cached builders that render all variants into the HTML and swap them on the client so they can keep Varnish / Fastly caching. For that case there is <code>Drupal.rl.decide()</code>, documented below.</p>
-
-<h3>JavaScript API (<code>Drupal.rl</code>)</h3>
-
-<p>Attach the <code>rl/api</code> library to make <code>Drupal.rl</code> available. It is a thin transport proxy that coalesces every decide, impression, and conversion fired on the page into a single batched POST to <code>rl.php</code>:</p>
-
-<pre><code>// Record an impression when the variant becomes visible.
-Drupal.rl.turn('hero_cta', 'v0');
-
-// Record a conversion when the user clicks / submits / converts.
+<pre><code>Drupal.rl.turn('hero_cta', 'v0');
 Drupal.rl.reward('hero_cta', 'v0');
 
-// Ask for a decision when the variant needs to be chosen client-side.
-// The arm list MUST be read from the DOM - see discipline below.
-var container = document.querySelector('[data-rl-experiment="hero_cta"]');
-var armIds = container.dataset.rlArms.split(',');
-Drupal.rl.decide('hero_cta', armIds).then(function (armId) {
+Drupal.rl.decide('hero_cta', ['v0', 'v1', 'v2']).then(function (armId) {
   showVariant(armId);
-});
-
-// Optional: force an immediate flush.
-Drupal.rl.flush();</code></pre>
-
-<p>Events accumulate for 500 ms and then flush in one POST. Decide, turn, and reward events share the same queue and the same request, so a page with a DXPR Builder variant block plus tracking on other elements ends up making a single round trip. Buffered tracking events are also flushed via <code>navigator.sendBeacon</code> on <code>visibilitychange</code> and <code>pagehide</code> so they survive navigation.</p>
-
-<h4>Discipline for <code>decide()</code></h4>
-
-<blockquote><strong>Never hardcode arm ids in JS. Always read them from a DOM attribute that the server-side renderer emitted.</strong></blockquote>
-
-<p>Rationale: the DOM is downstream of the same server-render pipeline that produced the decide's context. When the experiment manager adds or removes a variant, the consumer's page cache is invalidated, the next render emits the new attribute, and JS picks it up. JS never asserts what the arm set is - it just echoes whatever the current cached HTML says, mirroring ai_sorting's PHP pattern of recomputing <code>$arm_ids</code> from a fresh view query on every render. This keeps <code>Drupal.rl.decide()</code> drift-free without requiring the rl core to store arm lists.</p>
-
-<p>The convention your builder uses internally (numeric <code>v0..vN</code>, UUIDs, node ids, anything matching <code>^[a-zA-Z0-9_-]+$</code>) is whatever you emit into the attribute. The rl core is arm-agnostic.</p>
-
-<p>If the server returns no decision for an experiment (not registered, no data, network error), the returned promise resolves to <code>armIds[0]</code> so callers never need a <code>.catch()</code> for the common path.</p>
-
-<p><code>Drupal.rl</code> is one transport among several. Modules that already ship their own tracking JS (like <code>ai_sorting</code>, which batches turns on its own 100 ms window and posts form data) keep working untouched.</p>
-
-<h3>HTTP API (<code>rl.php</code>)</h3>
-
-<p><code>rl.php</code> is the low-level endpoint. It is reachable directly from any client that can make an HTTP POST - browser pages, native mobile apps, server-side workers, other CMSes, edge functions. Deciding is <em>not</em> exposed here: it happens in PHP at render time as shown above.</p>
-
-<p>Four actions are supported. All are additive - adding <code>batch</code> did not deprecate the legacy form actions, and production consumers like <code>ai_sorting</code> keep using them unchanged.</p>
-
-<table>
-  <thead><tr><th>Action</th><th>Encoding</th><th>Purpose</th></tr></thead>
-  <tbody>
-    <tr><td><code>ping</code></td><td>form POST</td><td>Liveness check. Returns <code>pong</code>.</td></tr>
-    <tr><td><code>turn</code></td><td>form POST</td><td>Record one impression.</td></tr>
-    <tr><td><code>turns</code></td><td>form POST</td><td>Record impressions for many arms in one experiment.</td></tr>
-    <tr><td><code>reward</code></td><td>form POST</td><td>Record one conversion.</td></tr>
-    <tr><td><code>batch</code></td><td>JSON POST</td><td>Record turns and rewards across many experiments in one request. Used by <code>Drupal.rl</code>.</td></tr>
-  </tbody>
-</table>
-
-<p>Experiment IDs and arm IDs must match <code>^[a-zA-Z0-9_-]+$</code>. Experiments must already be registered via <code>ExperimentRegistryInterface::register()</code>; unknown IDs are silently dropped so garbage writes cannot create registry entries.</p>
-
-<h4>Legacy form actions</h4>
-
-<pre><code>curl -X POST https://example.com/modules/contrib/rl/rl.php \
-  -d 'action=turn&amp;experiment_id=hero_cta&amp;arm_id=v0'
-
-curl -X POST https://example.com/modules/contrib/rl/rl.php \
-  -d 'action=turns&amp;experiment_id=hero_cta&amp;arm_ids=v0,v1'
-
-curl -X POST https://example.com/modules/contrib/rl/rl.php \
-  -d 'action=reward&amp;experiment_id=hero_cta&amp;arm_id=v0'</code></pre>
-
-<h4><code>action=batch</code></h4>
-
-<pre><code>POST /modules/contrib/rl/rl.php?action=batch
-Content-Type: application/json
-
-{
-  "decides": [
-    {"id": "hero_cta", "arms": ["v0", "v1", "v2"]}
-  ],
-  "turns": [
-    {"id": "hero_cta", "arm": "v0"},
-    {"id": "menu_main_5", "arm": "v1"}
-  ],
-  "rewards": [
-    {"id": "hero_cta", "arm": "v0"}
-  ]
-}</code></pre>
-
-<p>All three sections are optional. Invalid or unregistered entries are dropped silently. The response is</p>
-
-<pre><code>{"ok":true,"decisions":{"hero_cta":{"armId":"v1"}}}</code></pre>
-
-<p><code>decisions</code> contains only entries that had a successful Thompson Sampling lookup. Missing keys mean "use the default variant". Turns and rewards are fire-and-forget writes with no per-event response.</p>
+});</code></pre>
 
-<p><strong>Performance note:</strong> <code>rl.php</code> bootstraps a minimal Drupal kernel per request (same pattern as core's <code>statistics.php</code>). One boot processes the whole batch, so non-browser callers should coalesce events into a single request whenever they can.</p>
+<p>All three methods feed a shared 500 ms batch window, so every experiment on the page rides one POST to <code>rl.php</code>. See the README for the HTTP wire format and server-side integration patterns.</p>
 
 <h3>Cache Management</h3>