From e89b8e1e7d8a54dd8662360d43ebad8d8e3ed8cd Mon Sep 17 00:00:00 2001
From: Aram Grigoryan <132480+aram356@users.noreply.github.com>
Date: Mon, 2 Mar 2026 22:30:18 -0800
Subject: [PATCH 1/8] Split Prebid into deferred bundle to reduce
 render-blocking JS by 88%

Prebid.js (168 KB) was 80% of the TSJS unified bundle, blocking page
rendering. Split it into a separate `<script defer>` tag so the
critical-path bundle drops from 190 KB to 22 KB.

Changes across 8 files:

- crates/js/src/bundle.rs: add `single_module_hash()` and
  `all_module_ids_excluding()` for deferred module serving
- crates/js/src/lib.rs: export new bundle functions
- crates/common/src/tsjs.rs: add `DEFERRED_MODULE_IDS` constant (single
  source of truth), deferred script tag generation functions, update
  `_all()` variants to exclude deferred modules
- crates/common/src/integrations/registry.rs: add
  `js_module_ids_immediate()` and `js_module_ids_deferred()` with tests
- crates/common/src/html_processor.rs: inject split tags at `<head>`:
  synchronous main bundle + deferred prebid tag
- crates/common/src/publisher.rs: serve deferred modules at
  `/static/tsjs=tsjs-{id}.min.js` with allowlist validation and tests
- crates/common/src/integrations/prebid.rs: fix test assertion for new
  deferred tag presence
- docs/guide/integration-guide.md: update Prebid load timing docs

Closes #358
---
 crates/common/src/html_processor.rs        |  11 +-
 crates/common/src/integrations/prebid.rs   |   8 +-
 crates/common/src/integrations/registry.rs | 119 +++++++++++++++
 crates/common/src/publisher.rs             | 159 +++++++++++++++++++--
 crates/common/src/tsjs.rs                  |  49 ++++++-
 crates/js/src/bundle.rs                    |  22 +++
 crates/js/src/lib.rs                       |   5 +-
 docs/guide/integration-guide.md            |   2 +-
 8 files changed, 348 insertions(+), 27 deletions(-)
diff --git a/crates/common/src/html_processor.rs b/crates/common/src/html_processor.rs
index a3b3c9bf..540ab29d 100644
--- a/crates/common/src/html_processor.rs
+++ b/crates/common/src/html_processor.rs
@@ -208,10 +208,13 @@ pub fn create_html_processor(config: HtmlProcessorConfig) -> impl StreamProcesso
                     for insert in integrations.head_inserts(&ctx) {
                         snippet.push_str(&insert);
                     }
-                    // Then inject the TSJS bundle — its top-level init code can now
-                    // read the config that was set by the inline scripts above.
-                    let module_ids = integrations.js_module_ids();
-                    snippet.push_str(&tsjs::tsjs_script_tag(&module_ids));
+                    // Main bundle: core + non-deferred integrations (synchronous).
+                    let immediate_ids = integrations.js_module_ids_immediate();
+                    snippet.push_str(&tsjs::tsjs_script_tag(&immediate_ids));
+                    // Deferred bundles: large modules like prebid loaded after
+                    // HTML parsing completes. Empty when none are enabled.
+                    let deferred_ids = integrations.js_module_ids_deferred();
+                    snippet.push_str(&tsjs::tsjs_deferred_script_tags(&deferred_ids));
                     el.prepend(&snippet, ContentType::Html);
                     injected_tsjs.set(true);
                 }
diff --git a/crates/common/src/integrations/prebid.rs b/crates/common/src/integrations/prebid.rs
index 8177a823..8ae49641 100644
--- a/crates/common/src/integrations/prebid.rs
+++ b/crates/common/src/integrations/prebid.rs
@@ -1129,13 +1129,17 @@ template = "{{client_ip}}:{{user_agent}}"
             "Unified bundle should be injected"
         );
         assert!(
-            !processed.contains("prebid.min.js"),
-            "Prebid script should be removed when auto-config is enabled"
+            !processed.contains("cdn.prebid.org/prebid.min.js"),
+            "Publisher prebid script should be removed when auto-config is enabled"
         );
         assert!(
             !processed.contains("cdn.prebid.org/prebid.js"),
             "Prebid preload should be removed when auto-config is enabled"
         );
+        assert!(
+            processed.contains("tsjs-prebid.min.js"),
+            "Deferred prebid bundle should be injected"
+        );
     }
 
     #[test]
diff --git a/crates/common/src/integrations/registry.rs b/crates/common/src/integrations/registry.rs
index 07fec408..b3861820 100644
--- a/crates/common/src/integrations/registry.rs
+++ b/crates/common/src/integrations/registry.rs
@@ -789,6 +789,28 @@ impl IntegrationRegistry {
         ids
     }
 
+    /// Return JS module IDs for the main (synchronous) bundle, excluding
+    /// deferred modules like prebid.
+    #[must_use]
+    pub fn js_module_ids_immediate(&self) -> Vec<&'static str> {
+        self.js_module_ids()
+            .into_iter()
+            .filter(|id| !crate::tsjs::DEFERRED_MODULE_IDS.contains(id))
+            .collect()
+    }
+
+    /// Return JS module IDs that should be loaded with `defer`.
+    ///
+    /// Only includes deferred modules that are actually enabled in this
+    /// registry. Returns an empty vec when prebid is not configured.
+    #[must_use]
+    pub fn js_module_ids_deferred(&self) -> Vec<&'static str> {
+        self.js_module_ids()
+            .into_iter()
+            .filter(|id| crate::tsjs::DEFERRED_MODULE_IDS.contains(id))
+            .collect()
+    }
+
     #[cfg(test)]
     #[must_use]
     pub fn from_rewriters(
@@ -1338,4 +1360,101 @@ mod tests {
             "POST response should have x-synthetic-id header"
         );
     }
+
+    #[test]
+    fn js_module_ids_immediate_excludes_prebid() {
+        let settings = crate::test_support::tests::create_test_settings();
+        let mut settings_with_prebid = settings;
+        settings_with_prebid
+            .integrations
+            .insert_config(
+                "prebid",
+                &serde_json::json!({
+                    "enabled": true,
+                    "server_url": "https://test-prebid.com/openrtb2/auction",
+                    "timeout_ms": 1000,
+                    "bidders": ["mocktioneer"],
+                    "debug": false
+                }),
+            )
+            .expect("should insert prebid config");
+
+        let registry =
+            IntegrationRegistry::new(&settings_with_prebid).expect("should create registry");
+
+        let all = registry.js_module_ids();
+        let immediate = registry.js_module_ids_immediate();
+        let deferred = registry.js_module_ids_deferred();
+
+        assert!(
+            all.contains(&"prebid"),
+            "should include prebid in full list"
+        );
+        assert!(
+            !immediate.contains(&"prebid"),
+            "should not include prebid in immediate IDs"
+        );
+        assert!(
+            deferred.contains(&"prebid"),
+            "should include prebid in deferred IDs"
+        );
+    }
+
+    #[test]
+    fn js_module_ids_deferred_empty_when_prebid_disabled() {
+        let mut settings = crate::test_support::tests::create_test_settings();
+        settings
+            .integrations
+            .insert_config(
+                "prebid",
+                &serde_json::json!({
+                    "enabled": false,
+                    "server_url": "https://test-prebid.com/openrtb2/auction"
+                }),
+            )
+            .expect("should update prebid config");
+
+        let registry = IntegrationRegistry::new(&settings).expect("should create registry");
+
+        let deferred = registry.js_module_ids_deferred();
+        assert!(
+            deferred.is_empty(),
+            "should have no deferred IDs when prebid is disabled"
+        );
+    }
+
+    #[test]
+    fn js_module_ids_split_is_exhaustive() {
+        let settings = crate::test_support::tests::create_test_settings();
+        let mut settings_with_prebid = settings;
+        settings_with_prebid
+            .integrations
+            .insert_config(
+                "prebid",
+                &serde_json::json!({
+                    "enabled": true,
+                    "server_url": "https://test-prebid.com/openrtb2/auction",
+                    "timeout_ms": 1000,
+                    "bidders": ["mocktioneer"],
+                    "debug": false
+                }),
+            )
+            .expect("should insert prebid config");
+
+        let registry =
+            IntegrationRegistry::new(&settings_with_prebid).expect("should create registry");
+
+        let all = registry.js_module_ids();
+        let mut recombined = registry.js_module_ids_immediate();
+        recombined.extend(registry.js_module_ids_deferred());
+        recombined.sort();
+
+        let mut all_sorted = all;
+        all_sorted.sort();
+
+        assert_eq!(
+            recombined, all_sorted,
+            "should reconstruct full module list from immediate + deferred"
+        );
+    }
 }
diff --git a/crates/common/src/publisher.rs b/crates/common/src/publisher.rs
index 78489d2e..539d9d78 100644
--- a/crates/common/src/publisher.rs
+++ b/crates/common/src/publisher.rs
@@ -17,9 +17,11 @@ use crate::synthetic::get_or_generate_synthetic_id;
 
 /// Unified tsjs static serving: `/static/tsjs=<filename>`
 ///
-/// Concatenates core + enabled integration JS modules at runtime based on the
-/// `IntegrationRegistry`. The URL remains `/static/tsjs=tsjs-unified(.min).js`
-/// for backward compatibility.
+/// Serves two types of bundles:
+/// - **Unified bundle** (`tsjs-unified.min.js`): core + immediate (non-deferred)
+///   integration modules.
+/// - **Deferred module** (`tsjs-{id}.min.js`): a single self-contained IIFE for
+///   modules loaded with `defer` (e.g., prebid).
 ///
 /// # Errors
 ///
@@ -29,23 +31,53 @@ pub fn handle_tsjs_dynamic(
     integration_registry: &IntegrationRegistry,
 ) -> Result<Response, Report<TrustedServerError>> {
     const PREFIX: &str = "/static/tsjs=";
-    const ALLOWED_FILENAMES: &[&str] = &["tsjs-unified.js", "tsjs-unified.min.js"];
+    const UNIFIED_FILENAMES: &[&str] = &["tsjs-unified.js", "tsjs-unified.min.js"];
+
     let path = req.get_path();
     if !path.starts_with(PREFIX) {
         return Ok(Response::from_status(StatusCode::NOT_FOUND).with_body("Not Found"));
     }
     let filename = &path[PREFIX.len()..];
-    if !ALLOWED_FILENAMES.contains(&filename) {
-        return Ok(Response::from_status(StatusCode::NOT_FOUND).with_body("Not Found"));
+
+    if UNIFIED_FILENAMES.contains(&filename) {
+        // Serve core + immediate modules (excludes deferred like prebid)
+        let module_ids = integration_registry.js_module_ids_immediate();
+        let body = trusted_server_js::concatenate_modules(&module_ids);
+        let mut resp = serve_static_with_etag(&body, req, "application/javascript; charset=utf-8");
+        resp.set_header(HEADER_X_COMPRESS_HINT, "on");
+        return Ok(resp);
+    }
+
+    if let Some(module_id) = parse_deferred_module_filename(filename) {
+        // Only serve if the deferred module is actually enabled
+        let deferred_ids = integration_registry.js_module_ids_deferred();
+        if !deferred_ids.contains(&module_id) {
+            return Ok(Response::from_status(StatusCode::NOT_FOUND).with_body("Not Found"));
+        }
+        if let Some(content) = trusted_server_js::module_bundle(module_id) {
+            let mut resp =
+                serve_static_with_etag(content, req, "application/javascript; charset=utf-8");
+            resp.set_header(HEADER_X_COMPRESS_HINT, "on");
+            return Ok(resp);
+        }
     }
 
-    // Concatenate core + enabled integration modules
-    let module_ids = integration_registry.js_module_ids();
-    let body = trusted_server_js::concatenate_modules(&module_ids);
+    Ok(Response::from_status(StatusCode::NOT_FOUND).with_body("Not Found"))
+}
 
-    let mut resp = serve_static_with_etag(&body, req, "application/javascript; charset=utf-8");
-    resp.set_header(HEADER_X_COMPRESS_HINT, "on");
-    Ok(resp)
+/// Extract a module ID from a deferred-module filename like `tsjs-prebid.min.js`.
+///
+/// Returns `Some(&'static str)` if the filename matches a known deferred module
+/// ID, `None` otherwise. Only explicitly listed IDs are accepted for security.
+fn parse_deferred_module_filename(filename: &str) -> Option<&'static str> {
+    let stem = filename
+        .strip_prefix("tsjs-")
+        .and_then(|s| s.strip_suffix(".min.js").or_else(|| s.strip_suffix(".js")))?;
+
+    crate::tsjs::DEFERRED_MODULE_IDS
+        .iter()
+        .find(|&&id| id == stem)
+        .copied()
 }
 
 /// Parameters for processing response streaming
@@ -454,5 +486,106 @@ mod tests {
         assert_eq!(response.get_status(), StatusCode::OK);
     }
 
-    // Tests related to serving Prebid.js directly or intercepting its paths were removed.
+    #[test]
+    fn parse_deferred_module_filename_extracts_known_id() {
+        assert_eq!(
+            parse_deferred_module_filename("tsjs-prebid.min.js"),
+            Some("prebid"),
+            "should extract prebid from minified filename"
+        );
+        assert_eq!(
+            parse_deferred_module_filename("tsjs-prebid.js"),
+            Some("prebid"),
+            "should extract prebid from unminified filename"
+        );
+    }
+
+    #[test]
+    fn parse_deferred_module_filename_rejects_unknown_ids() {
+        assert_eq!(
+            parse_deferred_module_filename("tsjs-evil.min.js"),
+            None,
+            "should reject unknown module names"
+        );
+        assert_eq!(
+            parse_deferred_module_filename("tsjs-core.min.js"),
+            None,
+            "should reject non-deferred modules"
+        );
+        assert_eq!(
+            parse_deferred_module_filename("prebid.min.js"),
+            None,
+            "should reject without tsjs- prefix"
+        );
+        assert_eq!(
+            parse_deferred_module_filename("tsjs-prebid.txt"),
+            None,
+            "should reject non-js extension"
+        );
+    }
+
+    #[test]
+    fn tsjs_dynamic_serves_deferred_prebid_when_enabled() {
+        // Default test settings include prebid enabled
+        let settings = create_test_settings();
+        let registry =
+            IntegrationRegistry::new(&settings).expect("should create integration registry");
+        let req = Request::new(
+            Method::GET,
+            "https://publisher.example/static/tsjs=tsjs-prebid.min.js",
+        );
+
+        let response = handle_tsjs_dynamic(&req, &registry).expect("should handle tsjs request");
+        assert_eq!(
+            response.get_status(),
+            StatusCode::OK,
+            "should serve deferred prebid module when enabled"
+        );
+    }
+
+    #[test]
+    fn tsjs_dynamic_returns_not_found_for_disabled_deferred_module() {
+        let mut settings = create_test_settings();
+        settings
+            .integrations
+            .insert_config(
+                "prebid",
+                &serde_json::json!({
+                    "enabled": false,
+                    "server_url": "https://test-prebid.com/openrtb2/auction"
+                }),
+            )
+            .expect("should update prebid config");
+        let registry =
+            IntegrationRegistry::new(&settings).expect("should create integration registry");
+        let req = Request::new(
+            Method::GET,
+            "https://publisher.example/static/tsjs=tsjs-prebid.min.js",
+        );
+
+        let response = handle_tsjs_dynamic(&req, &registry).expect("should handle tsjs request");
+        assert_eq!(
+            response.get_status(),
+            StatusCode::NOT_FOUND,
+            "should return 404 for disabled deferred module"
+        );
+    }
+
+    #[test]
+    fn tsjs_dynamic_returns_not_found_for_arbitrary_module_name() {
+        let settings = create_test_settings();
+        let registry =
+            IntegrationRegistry::new(&settings).expect("should create integration registry");
+        let req = Request::new(
+            Method::GET,
+            "https://publisher.example/static/tsjs=tsjs-evil.min.js",
+        );
+
+        let response = handle_tsjs_dynamic(&req, &registry).expect("should handle tsjs request");
+        assert_eq!(
+            response.get_status(),
+            StatusCode::NOT_FOUND,
+            "should reject unknown module names"
+        );
+    }
 }
diff --git a/crates/common/src/tsjs.rs b/crates/common/src/tsjs.rs
index 2bec8a3b..88997c99 100644
--- a/crates/common/src/tsjs.rs
+++ b/crates/common/src/tsjs.rs
@@ -1,4 +1,11 @@
-use trusted_server_js::{all_module_ids, concatenated_hash};
+use trusted_server_js::{all_module_ids_excluding, concatenated_hash, single_module_hash};
+
+/// Module IDs loaded with `defer` in a separate `<script>` tag.
+///
+/// Single source of truth — imported by
+/// [`IntegrationRegistry`](crate::integrations::IntegrationRegistry) and
+/// [`handle_tsjs_dynamic`](crate::publisher::handle_tsjs_dynamic).
+pub const DEFERRED_MODULE_IDS: &[&str] = &["prebid"];
 
 /// `/static` URL for the tsjs bundle with cache-busting hash based on
 /// the concatenated content of the given module set.
@@ -17,17 +24,47 @@ pub fn tsjs_script_tag(module_ids: &[&str]) -> String {
     )
 }
 
-/// `/static` URL using **all** available modules. Used in contexts that lack
-/// an `IntegrationRegistry` (e.g., creative rewriting, config defaults).
+/// `/static` URL using all available modules **except** deferred ones.
+///
+/// Used in contexts that lack an
+/// [`IntegrationRegistry`](crate::integrations::IntegrationRegistry) (e.g., creative
+/// rewriting, config defaults).
 #[must_use]
 pub fn tsjs_script_src_all() -> String {
-    let ids = all_module_ids();
+    let ids = all_module_ids_excluding(DEFERRED_MODULE_IDS);
     tsjs_script_src(&ids)
 }
 
-/// `<script>` tag using **all** available modules.
+/// `<script>` tag using all available modules **except** deferred ones.
 #[must_use]
 pub fn tsjs_script_tag_all() -> String {
-    let ids = all_module_ids();
+    let ids = all_module_ids_excluding(DEFERRED_MODULE_IDS);
     tsjs_script_tag(&ids)
 }
+
+/// `/static` URL for a single deferred module with its own cache-busting hash.
+#[must_use]
+pub fn tsjs_deferred_script_src(module_id: &str) -> String {
+    let hash = single_module_hash(module_id).unwrap_or_default();
+    format!("/static/tsjs=tsjs-{module_id}.min.js?v={hash}")
+}
+
+/// `<script defer>` tag for a single deferred module.
+#[must_use]
+pub fn tsjs_deferred_script_tag(module_id: &str) -> String {
+    format!(
+        "<script src=\"{}\" defer></script>",
+        tsjs_deferred_script_src(module_id)
+    )
+}
+
+/// Generate all deferred `<script defer>` tags for the given module IDs.
+///
+/// Returns an empty string when no deferred modules are present.
+#[must_use]
+pub fn tsjs_deferred_script_tags(module_ids: &[&str]) -> String {
+    module_ids
+        .iter()
+        .map(|id| tsjs_deferred_script_tag(id))
+        .collect::<String>()
+}
diff --git a/crates/js/src/bundle.rs b/crates/js/src/bundle.rs
index 3152af6c..d49a3b65 100644
--- a/crates/js/src/bundle.rs
+++ b/crates/js/src/bundle.rs
@@ -54,6 +54,28 @@ pub fn concatenated_hash(ids: &[&str]) -> String {
     encode(hasher.finalize())
 }
 
+/// SHA-256 hash of a single module's content (without prepending core).
+///
+/// Used for cache-busting URLs of deferred modules served individually.
+#[must_use]
+pub fn single_module_hash(id: &str) -> Option<String> {
+    module_bundle(id).map(|content| {
+        let mut hasher = Sha256::new();
+        hasher.update(content.as_bytes());
+        encode(hasher.finalize())
+    })
+}
+
+/// Return all available module IDs except those in `exclude`.
+#[must_use]
+pub fn all_module_ids_excluding(exclude: &[&str]) -> Vec<&'static str> {
+    TSJS_MODULES
+        .iter()
+        .map(|m| m.id)
+        .filter(|id| !exclude.contains(id))
+        .collect()
+}
+
 fn module_map() -> &'static HashMap<&'static str, &'static str> {
     static MAP: OnceLock<HashMap<&'static str, &'static str>> = OnceLock::new();
     MAP.get_or_init(|| TSJS_MODULES.iter().map(|m| (m.id, m.bundle)).collect())
diff --git a/crates/js/src/lib.rs b/crates/js/src/lib.rs
index a5977431..1fee08f3 100644
--- a/crates/js/src/lib.rs
+++ b/crates/js/src/lib.rs
@@ -1,3 +1,6 @@
 pub mod bundle;
 
-pub use bundle::{all_module_ids, concatenate_modules, concatenated_hash, module_bundle};
+pub use bundle::{
+    all_module_ids, all_module_ids_excluding, concatenate_modules, concatenated_hash,
+    module_bundle, single_module_hash,
+};
diff --git a/docs/guide/integration-guide.md b/docs/guide/integration-guide.md
index c18c5a90..f810503d 100644
--- a/docs/guide/integration-guide.md
+++ b/docs/guide/integration-guide.md
@@ -313,7 +313,7 @@ Tests or scaffolding can inject configs by calling `settings.integrations.insert
 
 **3. HTML Rewrites Through the Registry**
 
-When the integration is enabled, the `IntegrationAttributeRewriter` removes any `<script src="prebid*.js">` or `<link href=…>` references that match `script_patterns`. The unified TSJS bundle is injected at the start of `<head>`, so dropping the publisher assets prevents duplicate downloads and still runs before any inline `pbjs` config.
+When the integration is enabled, the `IntegrationAttributeRewriter` removes any `<script src="prebid*.js">` or `<link href=…>` references that match `script_patterns`. The Prebid module is loaded as a separate `<script defer>` tag after the main TSJS bundle, so dropping the publisher assets prevents duplicate downloads. The server-injected config (`window.__tsjs_prebid`) is an inline script that runs before both bundles, ensuring configuration is available when the deferred Prebid module auto-initializes.
 
 **4. TSJS Assets & Testing**
 

From 753b05a9f5e0aab31c6feb9890832ca8475a2c25 Mon Sep 17 00:00:00 2001
From: Aram Grigoryan <132480+aram356@users.noreply.github.com>
Date: Mon, 2 Mar 2026 22:42:43 -0800
Subject: [PATCH 2/8] Document deferred vs immediate loading for each
 integration

Update CLAUDE.md and integration-guide.md to indicate which
integrations use deferred loading and explain the two loading modes.
---
 CLAUDE.md                       |  5 +++--
 docs/guide/integration-guide.md | 12 ++++++++++--
 2 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index abf6e896..05767f15 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -237,9 +237,10 @@ IntegrationRegistration::builder(ID)
     .build()
 ```
 
-- Integration IDs match JS directory names: `prebid`, `lockr`, `permutive`, `datadome`, `didomi`, `testlight`.
+- Integration IDs match JS directory names: `prebid` (deferred), `lockr`, `permutive`, `datadome`, `didomi`, `testlight`.
 - `creative` is JS-only (no Rust registration); `nextjs`, `aps`, `adserver_mock` are Rust-only.
-- `IntegrationRegistry::js_module_ids()` maps registered integrations to JS module names.
+- Deferred integrations (listed in `DEFERRED_MODULE_IDS` in `tsjs.rs`) are served as separate `<script defer>` tags instead of being concatenated into the main bundle.
+- `IntegrationRegistry::js_module_ids_immediate()` returns modules for the main bundle; `js_module_ids_deferred()` returns modules loaded with `defer`.
 
 ## JS Build Pipeline
 
diff --git a/docs/guide/integration-guide.md b/docs/guide/integration-guide.md
index f810503d..70912fd9 100644
--- a/docs/guide/integration-guide.md
+++ b/docs/guide/integration-guide.md
@@ -268,10 +268,16 @@ By following these steps you can ship independent integration modules that plug
 
 ## Existing Integrations
 
-Two built-in integrations demonstrate how the framework pieces fit together:
+Two built-in integrations demonstrate how the framework pieces fit together.
+
+Integrations are loaded in one of two ways:
+- **Immediate** (default) — concatenated into the main `tsjs-unified.min.js` bundle, loaded synchronously at `<head>` start.
+- **Deferred** — served as a separate `<script defer>` tag (`tsjs-{id}.min.js`), loaded after HTML parsing completes. Used for large modules that would otherwise block rendering. Deferred module IDs are listed in `DEFERRED_MODULE_IDS` in `crates/common/src/tsjs.rs`.
 
 ### Testlight
 
+**Loading**: Immediate
+
 **Purpose**: Sample partner stub showing request proxying, attribute rewrites, and asset injection.
 
 **Key files**:
@@ -281,7 +287,9 @@ Two built-in integrations demonstrate how the framework pieces fit together:
 
 ### Prebid
 
-**Purpose**: Production Prebid Server bridge that owns `/first-party/ad` & `/third-party/ad`, injects synthetic IDs, rewrites creatives/notification URLs, and removes publisher-supplied Prebid scripts because the NPM-bundled Prebid.js already ships in the unified TSJS build.
+**Loading**: Deferred (`<script defer>`)
+
+**Purpose**: Production Prebid Server bridge that owns `/first-party/ad` & `/third-party/ad`, injects synthetic IDs, rewrites creatives/notification URLs, and removes publisher-supplied Prebid scripts. The NPM-bundled Prebid.js is served as a separate deferred bundle (`tsjs-prebid.min.js`) to avoid blocking page rendering (168 KB).
 
 **Key files**:
 

From 0b548c755d3e70367043105edeb0bee54360d5ac Mon Sep 17 00:00:00 2001
From: Aram Grigoryan <132480+aram356@users.noreply.github.com>
Date: Mon, 2 Mar 2026 23:28:33 -0800
Subject: [PATCH 3/8] Replace hardcoded DEFERRED_MODULE_IDS with
 per-integration builder flag

Each integration now declares deferred JS loading via .with_deferred_js()
on IntegrationRegistrationBuilder, replacing the static constant that
required manual maintenance. Removes unused _all() convenience functions
from tsjs.rs and all_module_ids_excluding() from bundle.rs.
---
 CLAUDE.md                                   |  2 +-
 crates/common/src/creative.rs               |  2 +-
 crates/common/src/integrations/prebid.rs    |  1 +
 crates/common/src/integrations/registry.rs  | 32 +++++++++++++++++----
 crates/common/src/integrations/testlight.rs |  6 ++--
 crates/common/src/publisher.rs              | 16 +++++------
 crates/common/src/tsjs.rs                   | 27 +----------------
 crates/js/src/bundle.rs                     | 10 -------
 crates/js/src/lib.rs                        |  3 +-
 docs/guide/integration-guide.md             |  2 +-
 10 files changed, 43 insertions(+), 58 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 05767f15..9ad1845c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -239,7 +239,7 @@ IntegrationRegistration::builder(ID)
 
 - Integration IDs match JS directory names: `prebid` (deferred), `lockr`, `permutive`, `datadome`, `didomi`, `testlight`.
 - `creative` is JS-only (no Rust registration); `nextjs`, `aps`, `adserver_mock` are Rust-only.
-- Deferred integrations (listed in `DEFERRED_MODULE_IDS` in `tsjs.rs`) are served as separate `<script defer>` tags instead of being concatenated into the main bundle.
+- Integrations opt into deferred loading via `.with_deferred_js()` on the registration builder. Deferred modules are served as separate `<script defer>` tags instead of being concatenated into the main bundle.
 - `IntegrationRegistry::js_module_ids_immediate()` returns modules for the main bundle; `js_module_ids_deferred()` returns modules loaded with `defer`.
 
 ## JS Build Pipeline
diff --git a/crates/common/src/creative.rs b/crates/common/src/creative.rs
index d8e2793a..6c159533 100644
--- a/crates/common/src/creative.rs
+++ b/crates/common/src/creative.rs
@@ -322,7 +322,7 @@ pub fn rewrite_creative_html(settings: &Settings, markup: &str) -> String {
                     let injected = injected_ts_creative.clone();
                     move |el| {
                         if !injected.get() {
-                            let script_tag = tsjs::tsjs_script_tag_all();
+                            let script_tag = tsjs::tsjs_script_tag(&["creative"]);
                             el.prepend(&script_tag, ContentType::Html);
                             injected.set(true);
                         }
diff --git a/crates/common/src/integrations/prebid.rs b/crates/common/src/integrations/prebid.rs
index 8ae49641..5d99ffd8 100644
--- a/crates/common/src/integrations/prebid.rs
+++ b/crates/common/src/integrations/prebid.rs
@@ -223,6 +223,7 @@ pub fn register(settings: &Settings) -> Option<IntegrationRegistration> {
             .with_proxy(integration.clone())
             .with_attribute_rewriter(integration.clone())
             .with_head_injector(integration)
+            .with_deferred_js()
             .build(),
     )
 }
diff --git a/crates/common/src/integrations/registry.rs b/crates/common/src/integrations/registry.rs
index b3861820..158a1e29 100644
--- a/crates/common/src/integrations/registry.rs
+++ b/crates/common/src/integrations/registry.rs
@@ -390,6 +390,7 @@ pub trait IntegrationHeadInjector: Send + Sync {
 /// Registration payload returned by integration builders.
 pub struct IntegrationRegistration {
     pub integration_id: &'static str,
+    pub js_deferred: bool,
     pub proxies: Vec<Arc<dyn IntegrationProxy>>,
     pub attribute_rewriters: Vec<Arc<dyn IntegrationAttributeRewriter>>,
     pub script_rewriters: Vec<Arc<dyn IntegrationScriptRewriter>>,
@@ -413,6 +414,7 @@ impl IntegrationRegistrationBuilder {
         Self {
             registration: IntegrationRegistration {
                 integration_id,
+                js_deferred: false,
                 proxies: Vec::new(),
                 attribute_rewriters: Vec::new(),
                 script_rewriters: Vec::new(),
@@ -458,6 +460,14 @@ impl IntegrationRegistrationBuilder {
         self
     }
 
+    /// Mark this integration's JS module for deferred loading via
+    /// `<script defer>` instead of the main synchronous bundle.
+    #[must_use]
+    pub fn with_deferred_js(mut self) -> Self {
+        self.registration.js_deferred = true;
+        self
+    }
+
     #[must_use]
     pub fn build(self) -> IntegrationRegistration {
         self.registration
@@ -476,6 +486,7 @@ struct IntegrationRegistryInner {
 
     // Metadata for introspection
     routes: Vec<(IntegrationEndpoint, &'static str)>,
+    deferred_js_ids: Vec<&'static str>,
     html_rewriters: Vec<Arc<dyn IntegrationAttributeRewriter>>,
     script_rewriters: Vec<Arc<dyn IntegrationScriptRewriter>>,
     html_post_processors: Vec<Arc<dyn IntegrationHtmlPostProcessor>>,
@@ -495,6 +506,7 @@ impl Default for IntegrationRegistryInner {
             script_rewriters: Vec::new(),
             html_post_processors: Vec::new(),
             head_injectors: Vec::new(),
+            deferred_js_ids: Vec::new(),
         }
     }
 }
@@ -600,6 +612,9 @@ impl IntegrationRegistry {
                 inner
                     .head_injectors
                     .extend(registration.head_injectors.into_iter());
+                if registration.js_deferred {
+                    inner.deferred_js_ids.push(registration.integration_id);
+                }
             }
         }
 
@@ -790,24 +805,26 @@ impl IntegrationRegistry {
     }
 
     /// Return JS module IDs for the main (synchronous) bundle, excluding
-    /// deferred modules like prebid.
+    /// modules registered with [`with_deferred_js`](IntegrationRegistrationBuilder::with_deferred_js).
     #[must_use]
     pub fn js_module_ids_immediate(&self) -> Vec<&'static str> {
         self.js_module_ids()
             .into_iter()
-            .filter(|id| !crate::tsjs::DEFERRED_MODULE_IDS.contains(id))
+            .filter(|id| !self.inner.deferred_js_ids.contains(id))
             .collect()
     }
 
-    /// Return JS module IDs that should be loaded with `defer`.
+    /// Return JS module IDs that should be loaded with `<script defer>`.
     ///
-    /// Only includes deferred modules that are actually enabled in this
-    /// registry. Returns an empty vec when prebid is not configured.
+    /// Only includes modules registered with
+    /// [`with_deferred_js`](IntegrationRegistrationBuilder::with_deferred_js)
+    /// that are actually enabled. Returns an empty vec when no deferred
+    /// integrations are configured.
     #[must_use]
     pub fn js_module_ids_deferred(&self) -> Vec<&'static str> {
         self.js_module_ids()
             .into_iter()
-            .filter(|id| crate::tsjs::DEFERRED_MODULE_IDS.contains(id))
+            .filter(|id| self.inner.deferred_js_ids.contains(id))
             .collect()
     }
 
@@ -829,6 +846,7 @@ impl IntegrationRegistry {
                 script_rewriters,
                 html_post_processors: Vec::new(),
                 head_injectors: Vec::new(),
+                deferred_js_ids: Vec::new(),
             }),
         }
     }
@@ -852,6 +870,7 @@ impl IntegrationRegistry {
                 script_rewriters,
                 html_post_processors: Vec::new(),
                 head_injectors,
+                deferred_js_ids: Vec::new(),
             }),
         }
     }
@@ -907,6 +926,7 @@ impl IntegrationRegistry {
                 script_rewriters: Vec::new(),
                 html_post_processors: Vec::new(),
                 head_injectors: Vec::new(),
+                deferred_js_ids: Vec::new(),
             }),
         }
     }
diff --git a/crates/common/src/integrations/testlight.rs b/crates/common/src/integrations/testlight.rs
index fda22ea9..a69838d4 100644
--- a/crates/common/src/integrations/testlight.rs
+++ b/crates/common/src/integrations/testlight.rs
@@ -219,7 +219,7 @@ fn default_timeout_ms() -> u32 {
 
 fn default_shim_src() -> String {
     // Testlight is included in the unified bundle, so we return the unified script source
-    tsjs::tsjs_script_src_all()
+    tsjs::tsjs_script_src(&["testlight"])
 }
 
 fn default_enabled() -> bool {
@@ -260,7 +260,7 @@ mod tests {
 
     #[test]
     fn html_rewriter_replaces_integration_script() {
-        let shim_src = tsjs::tsjs_script_src_all();
+        let shim_src = tsjs::tsjs_script_src(&["testlight"]);
         let config = TestlightConfig {
             enabled: true,
             endpoint: "https://example.com/openrtb".to_string(),
@@ -290,7 +290,7 @@ mod tests {
 
     #[test]
     fn html_rewriter_is_noop_when_disabled() {
-        let shim_src = tsjs::tsjs_script_src_all();
+        let shim_src = tsjs::tsjs_script_src(&["testlight"]);
         let config = TestlightConfig {
             enabled: true,
             endpoint: "https://example.com/openrtb".to_string(),
diff --git a/crates/common/src/publisher.rs b/crates/common/src/publisher.rs
index 539d9d78..87e4eeb1 100644
--- a/crates/common/src/publisher.rs
+++ b/crates/common/src/publisher.rs
@@ -67,17 +67,17 @@ pub fn handle_tsjs_dynamic(
 
 /// Extract a module ID from a deferred-module filename like `tsjs-prebid.min.js`.
 ///
-/// Returns `Some(&'static str)` if the filename matches a known deferred module
-/// ID, `None` otherwise. Only explicitly listed IDs are accepted for security.
+/// Returns `Some(&'static str)` if the filename matches a known JS module ID,
+/// `None` otherwise. The caller must additionally verify that the module is
+/// both deferred and enabled via the [`IntegrationRegistry`].
 fn parse_deferred_module_filename(filename: &str) -> Option<&'static str> {
     let stem = filename
         .strip_prefix("tsjs-")
         .and_then(|s| s.strip_suffix(".min.js").or_else(|| s.strip_suffix(".js")))?;
 
-    crate::tsjs::DEFERRED_MODULE_IDS
-        .iter()
-        .find(|&&id| id == stem)
-        .copied()
+    trusted_server_js::all_module_ids()
+        .into_iter()
+        .find(|&id| id == stem)
 }
 
 /// Parameters for processing response streaming
@@ -509,8 +509,8 @@ mod tests {
         );
         assert_eq!(
             parse_deferred_module_filename("tsjs-core.min.js"),
-            None,
-            "should reject non-deferred modules"
+            Some("core"),
+            "should accept any known module ID (deferred check happens in caller)"
         );
         assert_eq!(
             parse_deferred_module_filename("prebid.min.js"),
diff --git a/crates/common/src/tsjs.rs b/crates/common/src/tsjs.rs
index 88997c99..19632fc7 100644
--- a/crates/common/src/tsjs.rs
+++ b/crates/common/src/tsjs.rs
@@ -1,11 +1,4 @@
-use trusted_server_js::{all_module_ids_excluding, concatenated_hash, single_module_hash};
-
-/// Module IDs loaded with `defer` in a separate `<script>` tag.
-///
-/// Single source of truth — imported by
-/// [`IntegrationRegistry`](crate::integrations::IntegrationRegistry) and
-/// [`handle_tsjs_dynamic`](crate::publisher::handle_tsjs_dynamic).
-pub const DEFERRED_MODULE_IDS: &[&str] = &["prebid"];
+use trusted_server_js::{concatenated_hash, single_module_hash};
 
 /// `/static` URL for the tsjs bundle with cache-busting hash based on
 /// the concatenated content of the given module set.
@@ -24,24 +17,6 @@ pub fn tsjs_script_tag(module_ids: &[&str]) -> String {
     )
 }
 
-/// `/static` URL using all available modules **except** deferred ones.
-///
-/// Used in contexts that lack an
-/// [`IntegrationRegistry`](crate::integrations::IntegrationRegistry) (e.g., creative
-/// rewriting, config defaults).
-#[must_use]
-pub fn tsjs_script_src_all() -> String {
-    let ids = all_module_ids_excluding(DEFERRED_MODULE_IDS);
-    tsjs_script_src(&ids)
-}
-
-/// `<script>` tag using all available modules **except** deferred ones.
-#[must_use]
-pub fn tsjs_script_tag_all() -> String {
-    let ids = all_module_ids_excluding(DEFERRED_MODULE_IDS);
-    tsjs_script_tag(&ids)
-}
-
 /// `/static` URL for a single deferred module with its own cache-busting hash.
 #[must_use]
 pub fn tsjs_deferred_script_src(module_id: &str) -> String {
diff --git a/crates/js/src/bundle.rs b/crates/js/src/bundle.rs
index d49a3b65..7ae44aaa 100644
--- a/crates/js/src/bundle.rs
+++ b/crates/js/src/bundle.rs
@@ -66,16 +66,6 @@ pub fn single_module_hash(id: &str) -> Option<String> {
     })
 }
 
-/// Return all available module IDs except those in `exclude`.
-#[must_use]
-pub fn all_module_ids_excluding(exclude: &[&str]) -> Vec<&'static str> {
-    TSJS_MODULES
-        .iter()
-        .map(|m| m.id)
-        .filter(|id| !exclude.contains(id))
-        .collect()
-}
-
 fn module_map() -> &'static HashMap<&'static str, &'static str> {
     static MAP: OnceLock<HashMap<&'static str, &'static str>> = OnceLock::new();
     MAP.get_or_init(|| TSJS_MODULES.iter().map(|m| (m.id, m.bundle)).collect())
diff --git a/crates/js/src/lib.rs b/crates/js/src/lib.rs
index 1fee08f3..7c92212b 100644
--- a/crates/js/src/lib.rs
+++ b/crates/js/src/lib.rs
@@ -1,6 +1,5 @@
 pub mod bundle;
 
 pub use bundle::{
-    all_module_ids, all_module_ids_excluding, concatenate_modules, concatenated_hash,
-    module_bundle, single_module_hash,
+    all_module_ids, concatenate_modules, concatenated_hash, module_bundle, single_module_hash,
 };
diff --git a/docs/guide/integration-guide.md b/docs/guide/integration-guide.md
index 70912fd9..4f2b303a 100644
--- a/docs/guide/integration-guide.md
+++ b/docs/guide/integration-guide.md
@@ -272,7 +272,7 @@ Two built-in integrations demonstrate how the framework pieces fit together.
 
 Integrations are loaded in one of two ways:
 - **Immediate** (default) — concatenated into the main `tsjs-unified.min.js` bundle, loaded synchronously at `<head>` start.
-- **Deferred** — served as a separate `<script defer>` tag (`tsjs-{id}.min.js`), loaded after HTML parsing completes. Used for large modules that would otherwise block rendering. Deferred module IDs are listed in `DEFERRED_MODULE_IDS` in `crates/common/src/tsjs.rs`.
+- **Deferred** — served as a separate `<script defer>` tag (`tsjs-{id}.min.js`), loaded after HTML parsing completes. Used for large modules that would otherwise block rendering. Integrations opt in by calling `.with_deferred_js()` on their registration builder.
 
 ### Testlight
 

From 8b627e4420c45db5ecc61b7a68be73c387ef8894 Mon Sep 17 00:00:00 2001
From: Aram Grigoryan <132480+aram356@users.noreply.github.com>
Date: Mon, 2 Mar 2026 23:30:25 -0800
Subject: [PATCH 4/8] Fixed formatting of settings.json

---
 .claude/settings.json | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/.claude/settings.json b/.claude/settings.json
index c4261ade..95f403b4 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -10,22 +10,22 @@
       "Bash(tree:*)",
       "Bash(wc:*)",
       "Bash(which:*)",
-
       "Bash(npm ci:*)",
       "Bash(npm run:*)",
       "Bash(npm test:*)",
-
       "Bash(cargo build:*)",
       "Bash(cargo check:*)",
       "Bash(cargo clippy:*)",
       "Bash(cargo fmt:*)",
       "Bash(cargo metadata:*)",
       "Bash(cargo test:*)",
-
       "Bash(git branch:*)",
       "Bash(git diff:*)",
       "Bash(git log:*)",
-      "Bash(git status:*)"
+      "Bash(git status:*)",
+      "mcp__plugin_chrome-devtools-mcp_chrome-devtools__new_page",
+      "mcp__plugin_chrome-devtools-mcp_chrome-devtools__performance_stop_trace",
+      "mcp__plugin_chrome-devtools-mcp_chrome-devtools__evaluate_script"
     ]
   }
 }

From fdb8c9ac8d28c0507db48eb7f65dd579936ef6dc Mon Sep 17 00:00:00 2001
From: Aram Grigoryan <132480+aram356@users.noreply.github.com>
Date: Mon, 2 Mar 2026 23:32:37 -0800
Subject: [PATCH 5/8] Fixed formatting

---
 docs/guide/integration-guide.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/guide/integration-guide.md b/docs/guide/integration-guide.md
index 4f2b303a..4c251758 100644
--- a/docs/guide/integration-guide.md
+++ b/docs/guide/integration-guide.md
@@ -271,6 +271,7 @@ By following these steps you can ship independent integration modules that plug
 Two built-in integrations demonstrate how the framework pieces fit together.
 
 Integrations are loaded in one of two ways:
+
 - **Immediate** (default) — concatenated into the main `tsjs-unified.min.js` bundle, loaded synchronously at `<head>` start.
 - **Deferred** — served as a separate `<script defer>` tag (`tsjs-{id}.min.js`), loaded after HTML parsing completes. Used for large modules that would otherwise block rendering. Integrations opt in by calling `.with_deferred_js()` on their registration builder.
 

From 7b7118e92514a28cab2649bff8e0fc8a4b136ac1 Mon Sep 17 00:00:00 2001
From: Aram Grigoryan <132480+aram356@users.noreply.github.com>
Date: Tue, 3 Mar 2026 12:02:42 -0800
Subject: [PATCH 6/8] Fix cache-busting hash to reflect full unified bundle
 content

tsjs_script_src(&["testlight"]) hashed only core+testlight, but the
unified bundle contains all immediate modules. Added tsjs_unified_script_src()
and tsjs_unified_script_tag() that hash all module IDs so the cache key
matches the actual served content.
---
 crates/common/src/creative.rs               |  2 +-
 crates/common/src/integrations/testlight.rs |  9 ++++----
 crates/common/src/tsjs.rs                   | 23 ++++++++++++++++++++-
 3 files changed, 28 insertions(+), 6 deletions(-)

diff --git a/crates/common/src/creative.rs b/crates/common/src/creative.rs
index 6c159533..63db7e6f 100644
--- a/crates/common/src/creative.rs
+++ b/crates/common/src/creative.rs
@@ -322,7 +322,7 @@ pub fn rewrite_creative_html(settings: &Settings, markup: &str) -> String {
                     let injected = injected_ts_creative.clone();
                     move |el| {
                         if !injected.get() {
-                            let script_tag = tsjs::tsjs_script_tag(&["creative"]);
+                            let script_tag = tsjs::tsjs_unified_script_tag();
                             el.prepend(&script_tag, ContentType::Html);
                             injected.set(true);
                         }
diff --git a/crates/common/src/integrations/testlight.rs b/crates/common/src/integrations/testlight.rs
index a69838d4..1c8e31b5 100644
--- a/crates/common/src/integrations/testlight.rs
+++ b/crates/common/src/integrations/testlight.rs
@@ -218,8 +218,9 @@ fn default_timeout_ms() -> u32 {
 }
 
 fn default_shim_src() -> String {
-    // Testlight is included in the unified bundle, so we return the unified script source
-    tsjs::tsjs_script_src(&["testlight"])
+    // Testlight is included in the unified bundle, so we return the unified script source.
+    // Uses conservative all-module hash since the registry is unavailable at config time.
+    tsjs::tsjs_unified_script_src()
 }
 
 fn default_enabled() -> bool {
@@ -260,7 +261,7 @@ mod tests {
 
     #[test]
     fn html_rewriter_replaces_integration_script() {
-        let shim_src = tsjs::tsjs_script_src(&["testlight"]);
+        let shim_src = tsjs::tsjs_unified_script_src();
         let config = TestlightConfig {
             enabled: true,
             endpoint: "https://example.com/openrtb".to_string(),
@@ -290,7 +291,7 @@ mod tests {
 
     #[test]
     fn html_rewriter_is_noop_when_disabled() {
-        let shim_src = tsjs::tsjs_script_src(&["testlight"]);
+        let shim_src = tsjs::tsjs_unified_script_src();
         let config = TestlightConfig {
             enabled: true,
             endpoint: "https://example.com/openrtb".to_string(),
diff --git a/crates/common/src/tsjs.rs b/crates/common/src/tsjs.rs
index 19632fc7..4921a9bb 100644
--- a/crates/common/src/tsjs.rs
+++ b/crates/common/src/tsjs.rs
@@ -1,4 +1,4 @@
-use trusted_server_js::{concatenated_hash, single_module_hash};
+use trusted_server_js::{all_module_ids, concatenated_hash, single_module_hash};
 
 /// `/static` URL for the tsjs bundle with cache-busting hash based on
 /// the concatenated content of the given module set.
@@ -17,6 +17,27 @@ pub fn tsjs_script_tag(module_ids: &[&str]) -> String {
     )
 }
 
+/// `/static` URL for the unified bundle with a conservative cache-busting hash.
+///
+/// Hashes all compiled module IDs so the cache invalidates whenever any module
+/// changes. Over-invalidates slightly (includes deferred modules in the hash)
+/// but never serves stale content. Use [`tsjs_script_src`] with exact module
+/// IDs when the [`IntegrationRegistry`] is available.
+#[must_use]
+pub fn tsjs_unified_script_src() -> String {
+    let ids = all_module_ids();
+    tsjs_script_src(&ids)
+}
+
+/// `<script>` tag for the unified bundle with a conservative cache-busting hash.
+///
+/// See [`tsjs_unified_script_src`] for details.
+#[must_use]
+pub fn tsjs_unified_script_tag() -> String {
+    let ids = all_module_ids();
+    tsjs_script_tag(&ids)
+}
+
 /// `/static` URL for a single deferred module with its own cache-busting hash.
 #[must_use]
 pub fn tsjs_deferred_script_src(module_id: &str) -> String {

From c39cc6a581b6e4d58ca427cc1d6de853472e891b Mon Sep 17 00:00:00 2001
From: Aram Grigoryan <132480+aram356@users.noreply.github.com>
Date: Wed, 4 Mar 2026 12:13:08 -0800
Subject: [PATCH 7/8] Bootstrap pbjs globals before deferred Prebid bundle
 loads

Inject window.pbjs, pbjs.que, and pbjs.cmd in the head injector inline
script so publisher pages with bare pbjs.que.push() calls don't throw
before the deferred bundle executes. Also fix stale doc references that
still described Prebid as part of the unified sync bundle.
---
 crates/common/src/integrations/prebid.rs |  2 +-
 docs/guide/integration-guide.md          | 10 +++++-----
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/crates/common/src/integrations/prebid.rs b/crates/common/src/integrations/prebid.rs
index d940d9a4..89a8826c 100644
--- a/crates/common/src/integrations/prebid.rs
+++ b/crates/common/src/integrations/prebid.rs
@@ -321,7 +321,7 @@ impl IntegrationHeadInjector for PrebidIntegration {
             .replace("</", "<\\/");
 
         vec![format!(
-            r#"<script>window.__tsjs_prebid={config_json};</script>"#
+            r#"<script>window.pbjs=window.pbjs||{{}};window.pbjs.que=window.pbjs.que||[];window.pbjs.cmd=window.pbjs.cmd||[];window.__tsjs_prebid={config_json};</script>"#
         )]
     }
 }
diff --git a/docs/guide/integration-guide.md b/docs/guide/integration-guide.md
index 4c251758..f199db94 100644
--- a/docs/guide/integration-guide.md
+++ b/docs/guide/integration-guide.md
@@ -212,12 +212,12 @@ impl IntegrationScriptRewriter for MyIntegration {
 `html_processor.rs` calls these hooks after applying the standard origin→first-party rewrite, so you can simply swap URLs, append query parameters, or mutate inline JSON. Use this to point `<script>` tags at your own tsjs-managed bundle (for example, `/static/tsjs=tsjs-testlight.min.js`) or to rewrite embedded Next.js payloads.
 
 ::: warning Removing Elements
-Returning `AttributeRewriteAction::remove_element()` (or `ScriptRewriteAction::RemoveNode` for inline content) removes the element entirely, so integrations can drop publisher-provided markup when the Trusted Server already injects a safe alternative. Prebid, for example, simply removes `prebid.js` because the unified TSJS bundle is injected automatically at the start of `<head>`.
+Returning `AttributeRewriteAction::remove_element()` (or `ScriptRewriteAction::RemoveNode` for inline content) removes the element entirely, so integrations can drop publisher-provided markup when the Trusted Server already injects a safe alternative. Prebid, for example, removes publisher `prebid.js` tags because it ships its own deferred bundle (`tsjs-prebid.min.js`).
 :::
 
 ### 5b. Implement Head Injection (Optional)
 
-If the integration needs to inject HTML snippets at the start of `<head>` (for example, configuration scripts that run after the unified TSJS bundle), implement `IntegrationHeadInjector`. Snippets returned by this trait are prepended into `<head>` immediately after the TSJS bundle tag, so the `tsjs` API is available.
+If the integration needs to inject HTML snippets at the start of `<head>` (for example, configuration scripts or global bootstraps), implement `IntegrationHeadInjector`. Snippets are prepended into `<head>` before the TSJS bundle tags, so they run first.
 
 ```rust
 impl IntegrationHeadInjector for MyIntegration {
@@ -232,7 +232,7 @@ impl IntegrationHeadInjector for MyIntegration {
 }
 ```
 
-`html_processor.rs` calls `head_inserts` once per HTML response when the `<head>` element is first encountered. The returned snippets are concatenated after the unified script tag and prepended together, so ordering between integrations is not guaranteed — keep snippets self-contained.
+`html_processor.rs` calls `head_inserts` once per HTML response when the `<head>` element is first encountered. The returned snippets are concatenated before the unified script tag, so ordering between integrations is not guaranteed — keep snippets self-contained.
 
 ::: tip When to Use Head Injection
 Use `IntegrationHeadInjector` when you need to emit configuration, inline scripts, or `<meta>` tags that must appear early in `<head>`. For attribute or script content changes on existing elements, prefer `IntegrationAttributeRewriter` or `IntegrationScriptRewriter` instead.
@@ -251,7 +251,7 @@ Add the module to `crates/common/src/integrations/mod.rs`'s builder list. The re
 
 Place any integration-specific JavaScript entrypoint under `crates/js/lib/src/integrations/` (for example, `crates/js/lib/src/integrations/testlight.ts`). The shared `npm run build` script automatically discovers every file in that directory and produces a bundle named `tsjs-<entry>.js`, which the Rust crate embeds as `/static/tsjs=tsjs-<entry>.min.js`.
 
-Integrations that ship additional JS (such as Testlight) typically expose a `shim_src` config and rewrite publisher tags to point at that URL. Others (like Prebid) can simply drop the legacy tag because the unified bundle is injected automatically at the start of `<head>`.
+Integrations that ship additional JS (such as Testlight) typically expose a `shim_src` config and rewrite publisher tags to point at that URL. Others (like Prebid) drop the publisher tag because the server injects its own deferred bundle automatically.
 
 ### 8. Test Locally
 
@@ -326,7 +326,7 @@ When the integration is enabled, the `IntegrationAttributeRewriter` removes any
 
 **4. TSJS Assets & Testing**
 
-The NPM integration lives in `crates/js/lib/src/integrations/prebid/index.ts`. Tests typically assert that publisher references disappear, relying on the html processor's unified bundle injection to deliver the Prebid.js bundle.
+The NPM integration lives in `crates/js/lib/src/integrations/prebid/index.ts`. Tests typically assert that publisher references disappear and the deferred `tsjs-prebid.min.js` tag is present.
 
 Reusing these patterns makes it straightforward to convert additional legacy flows (for example, Next.js rewrites) into first-class integrations.
 

From a8acfa6f5e77dd2808eef01f3f6cc6bbfe72d653 Mon Sep 17 00:00:00 2001
From: Aram Grigoryan <132480+aram356@users.noreply.github.com>
Date: Thu, 5 Mar 2026 09:55:12 -0800
Subject: [PATCH 8/8] Added #[must_use]

---
 crates/common/src/publisher.rs | 1 +
 1 file changed, 1 insertion(+)

diff --git a/crates/common/src/publisher.rs b/crates/common/src/publisher.rs
index 87e4eeb1..7c86d06d 100644
--- a/crates/common/src/publisher.rs
+++ b/crates/common/src/publisher.rs
@@ -70,6 +70,7 @@ pub fn handle_tsjs_dynamic(
 /// Returns `Some(&'static str)` if the filename matches a known JS module ID,
 /// `None` otherwise. The caller must additionally verify that the module is
 /// both deferred and enabled via the [`IntegrationRegistry`].
+#[must_use]
 fn parse_deferred_module_filename(filename: &str) -> Option<&'static str> {
     let stem = filename
         .strip_prefix("tsjs-")
