feat(tag): drain a pre-load stub queue so the tag can be embedded async

Pages that load the tag with `async` can no longer rely on
`window.SurfaceEmbed` existing when their inline init runs. The install
snippet now ships a tiny stub that queues SurfaceEmbed constructions
(capturing `data-question-id` at queue time, while `document.currentScript`
still points at the constructing tag), zero-arg method calls, and
SurfaceSetConsent answers onto `window.SurfaceTagQueue`; the tag drains and
replays the queue once its real APIs are on `window`, then re-points kept
stub references at the real embeds. Pages without the stub hit a single
`Array.isArray` check — no behavior change for existing installations.

`SurfaceEmbedOptions.questionId` is added so the drain can pass the
captured question id through to the constructor.

Manual test page: test/async-stub.html (async tag + immediate IIFE init +
pre-load consent call, the smallest.ai pattern).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013Kjq1CG5RwFMpeucoPJWML

Author: paragmore

src/embed/embed.ts

@@ -98,7 +98,9 @@ export class SurfaceEmbed {
     this.log = createLogger("Surface Embed");
     this.store = (window as unknown as Record<string, unknown>).SurfaceTagStore as SurfaceStore;
     this.currentQuestionId =
-      document.currentScript?.getAttribute("data-question-id") || null;
+      options.questionId ||
+      document.currentScript?.getAttribute("data-question-id") ||
+      null;
 
     SurfaceEmbed._instances.push(this);
 

src/index.ts

@@ -12,6 +12,7 @@ import { SurfaceEmbed } from "./embed/embed";
 import { resolveOpenTriggersOnLoad } from "./open-triggers/open-triggers";
 import { initReview } from "./review/review";
 import { initializeSurfaceRuntimeConfig } from "./runtime-config";
+import { drainStubQueue } from "./stub-queue";
 
 const scriptTag = document.currentScript as HTMLScriptElement;
 const runtimeConfig = initializeSurfaceRuntimeConfig(scriptTag);
@@ -47,3 +48,8 @@ void resolveOpenTriggersOnLoad(environmentId, runtimeConfig);
 // Surface CMS review bridge. Inert unless the page is loaded inside the CMS
 // review iframe (?surface_review= token) — adds no listeners otherwise.
 initReview();
+
+// Async-loaded pages may have queued SurfaceEmbed / SurfaceSetConsent calls on
+// the install snippet's stub before this script arrived — replay them now that
+// the real APIs are on window.
+drainStubQueue();

src/stub-queue.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { drainStubQueue } from "./stub-queue";
+import { SurfaceEmbed } from "./embed/embed";
+import { getSurfaceConsent } from "./consent/consent";
+
+vi.mock("./embed/embed", () => ({
+  SurfaceEmbed: vi.fn(function (this: Record<string, unknown>) {
+    this.showSurfaceForm = vi.fn();
+    this.hideSurfaceForm = vi.fn();
+    this.initializeEmbed = vi.fn();
+  }),
+}));
+
+const MockedSurfaceEmbed = vi.mocked(SurfaceEmbed);
+
+const queueWindow = window as unknown as { SurfaceTagQueue?: unknown };
+
+const embedEntry = (overrides: Record<string, unknown> = {}) => ({
+  type: "embed",
+  args: ["https://forms.withsurface.com/s/form-1", "slideover", "surface-form-button"],
+  calls: [],
+  ...overrides,
+});
+
+describe("drainStubQueue", () => {
+  beforeEach(() => {
+    MockedSurfaceEmbed.mockClear();
+    delete queueWindow.SurfaceTagQueue;
+  });
+
+  it("does nothing without a queued array", () => {
+    drainStubQueue();
+    queueWindow.SurfaceTagQueue = { push: () => {} };
+    drainStubQueue();
+    expect(MockedSurfaceEmbed).not.toHaveBeenCalled();
+  });
+
+  it("constructs a real embed per queued entry, merging the captured question id", () => {
+    queueWindow.SurfaceTagQueue = [
+      embedEntry({ questionId: "q-123", args: ["https://x.com/s/f", "popup", "btn", { popupSize: "large" }] }),
+    ];
+
+    drainStubQueue();
+
+    expect(MockedSurfaceEmbed).toHaveBeenCalledWith("https://x.com/s/f", "popup", "btn", {
+      popupSize: "large",
+      questionId: "q-123",
+    });
+  });
+
+  it("replays queued method calls and re-points the stub instance at the real embed", () => {
+    const stub: Record<string, () => void> = {};
+    queueWindow.SurfaceTagQueue = [embedEntry({ calls: ["showSurfaceForm"], stub })];
+
+    drainStubQueue();
+
+    const real = MockedSurfaceEmbed.mock.instances[0] as unknown as Record<string, ReturnType<typeof vi.fn>>;
+    expect(real.showSurfaceForm).toHaveBeenCalledTimes(1);
+
+    stub.hideSurfaceForm();
+    expect(real.hideSurfaceForm).toHaveBeenCalledTimes(1);
+  });
+
+  it("applies a queued consent answer", () => {
+    queueWindow.SurfaceTagQueue = [
+      { type: "consent", args: [{ adTracking: true, surfaceAnalytics: true }] },
+    ];
+
+    drainStubQueue();
+
+    expect(getSurfaceConsent()).toEqual({ adTracking: true, surfaceAnalytics: true });
+  });
+
+  it("processes pushes made after the drain immediately", () => {
+    queueWindow.SurfaceTagQueue = [];
+    drainStubQueue();
+
+    (queueWindow.SurfaceTagQueue as { push: (e: unknown) => void }).push(embedEntry());
+    expect(MockedSurfaceEmbed).toHaveBeenCalledTimes(1);
+  });
+
+  it("skips malformed entries without breaking the rest", () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    queueWindow.SurfaceTagQueue = [null, { type: "embed" }, embedEntry()];
+
+    expect(() => drainStubQueue()).not.toThrow();
+    expect(MockedSurfaceEmbed).toHaveBeenCalledTimes(2);
+  });
+});

src/stub-queue.ts

@@ -0,0 +1,102 @@
+import { SurfaceEmbed } from "./embed/embed";
+import { setSurfaceConsent, type SurfaceConsent } from "./consent/consent";
+import type { EmbedTypeInput, SurfaceEmbedOptions } from "./types";
+
+/**
+ * Replays `SurfaceEmbed` / `SurfaceSetConsent` calls a page made before this
+ * script finished loading. Lets the tag be embedded with `async` (it no longer
+ * has to block the HTML parser just so `window.SurfaceEmbed` exists for later
+ * inline scripts).
+ *
+ * The counterpart is a small inline stub the install snippet places BEFORE the
+ * async script tag (source of truth for the generated snippet:
+ * `surface_forms` `lib/shared/surfaceTagSnippet.ts` — keep the entry shape in
+ * sync with `StubQueueEntry`):
+ *
+ * ```html
+ * <script>
+ *   window.SurfaceTagQueue = window.SurfaceTagQueue || [];
+ *   window.SurfaceEmbed = window.SurfaceEmbed || function () {
+ *     var entry = { type: "embed", args: arguments, calls: [], stub: this,
+ *       questionId: document.currentScript && document.currentScript.getAttribute("data-question-id") };
+ *     var stub = this;
+ *     ["showSurfaceForm", "hideSurfaceForm", "initializeEmbed"].forEach(function (method) {
+ *       stub[method] = function () { entry.calls.push(method); };
+ *     });
+ *     window.SurfaceTagQueue.push(entry);
+ *   };
+ *   window.SurfaceSetConsent = window.SurfaceSetConsent || function (consent) {
+ *     window.SurfaceTagQueue.push({ type: "consent", args: [consent] });
+ *   };
+ * </script>
+ * ```
+ *
+ * The stub captures `data-question-id` from the constructing script tag at
+ * queue time because `document.currentScript` is null by the time the drain
+ * runs (input-trigger embeds route on it).
+ */
+
+const RELAYED_METHODS = [
+  "showSurfaceForm",
+  "hideSurfaceForm",
+  "initializeEmbed",
+] as const;
+
+type RelayedMethod = (typeof RELAYED_METHODS)[number];
+
+interface StubQueueEntry {
+  type: "embed" | "consent";
+  args: ArrayLike<unknown>;
+  questionId?: string | null;
+  calls?: RelayedMethod[];
+  stub?: Record<string, unknown>;
+}
+
+export function drainStubQueue(): void {
+  const w = window as unknown as { SurfaceTagQueue?: unknown };
+  if (!Array.isArray(w.SurfaceTagQueue)) return;
+
+  const entries = w.SurfaceTagQueue as StubQueueEntry[];
+  // Swap the array out first: code that captured the stub function before the
+  // tag loaded still pushes here, and those pushes must process immediately
+  // instead of landing in a queue nobody reads again. A non-array queue also
+  // makes a double-loaded tag skip draining twice.
+  w.SurfaceTagQueue = { push: processEntry };
+  entries.forEach(processEntry);
+}
+
+function processEntry(entry: StubQueueEntry): void {
+  try {
+    if (entry?.type === "consent") {
+      setSurfaceConsent((entry.args?.[0] ?? {}) as Partial<SurfaceConsent>);
+      return;
+    }
+    if (entry?.type !== "embed") return;
+
+    const [src, embedType, targetClass, options] = Array.from(entry.args ?? []);
+    const embed = new SurfaceEmbed(
+      src as string,
+      embedType as EmbedTypeInput,
+      targetClass as string,
+      {
+        ...((options as SurfaceEmbedOptions) ?? {}),
+        ...(entry.questionId ? { questionId: entry.questionId } : {}),
+      }
+    );
+
+    for (const method of entry.calls ?? []) {
+      if (RELAYED_METHODS.includes(method)) embed[method]();
+    }
+
+    // The page may be holding the stub instance (`const c = new SurfaceEmbed(...)`)
+    // — re-point its methods at the real embed so later calls work.
+    if (entry.stub && typeof entry.stub === "object") {
+      for (const method of RELAYED_METHODS) {
+        entry.stub[method] = () => embed[method]();
+      }
+    }
+  } catch (error) {
+    // A malformed entry must never break the host page or later entries.
+    console.error("Surface Tag: failed to replay queued call", error);
+  }
+}

src/types.ts

@@ -59,6 +59,12 @@ export interface SurfaceEmbedOptions {
   enforceIDSelector?: boolean;
   widgetStyles?: Partial<WidgetStyles>;
   prefillData?: Record<string, string>;
+  /**
+   * Overrides the `data-question-id` normally read from the constructing
+   * script tag — needed when construction is replayed from the async stub
+   * queue, where `document.currentScript` is already null.
+   */
+  questionId?: string;
 }
 
 export interface ExternalFormProps {

surface_embed_v1.js

@@ -1947,7 +1947,7 @@
       this.src = new URL(src);
       this.log = createLogger("Surface Embed");
       this.store = window.SurfaceTagStore;
-      this.currentQuestionId = document.currentScript?.getAttribute("data-question-id") || null;
+      this.currentQuestionId = options.questionId || document.currentScript?.getAttribute("data-question-id") || null;
       _SurfaceEmbed._instances.push(this);
       if (this._isFormPreviewMode()) {
         this.log.info({ message: "Form is in preview mode" });
@@ -2494,6 +2494,49 @@
     window.addEventListener("message", onMessage);
   }
 
+  // src/stub-queue.ts
+  var RELAYED_METHODS = [
+    "showSurfaceForm",
+    "hideSurfaceForm",
+    "initializeEmbed"
+  ];
+  function drainStubQueue() {
+    const w3 = window;
+    if (!Array.isArray(w3.SurfaceTagQueue)) return;
+    const entries = w3.SurfaceTagQueue;
+    w3.SurfaceTagQueue = { push: processEntry };
+    entries.forEach(processEntry);
+  }
+  function processEntry(entry) {
+    try {
+      if (entry?.type === "consent") {
+        setSurfaceConsent(entry.args?.[0] ?? {});
+        return;
+      }
+      if (entry?.type !== "embed") return;
+      const [src, embedType, targetClass, options] = Array.from(entry.args ?? []);
+      const embed = new SurfaceEmbed(
+        src,
+        embedType,
+        targetClass,
+        {
+          ...options ?? {},
+          ...entry.questionId ? { questionId: entry.questionId } : {}
+        }
+      );
+      for (const method of entry.calls ?? []) {
+        if (RELAYED_METHODS.includes(method)) embed[method]();
+      }
+      if (entry.stub && typeof entry.stub === "object") {
+        for (const method of RELAYED_METHODS) {
+          entry.stub[method] = () => embed[method]();
+        }
+      }
+    } catch (error) {
+      console.error("Surface Tag: failed to replay queued call", error);
+    }
+  }
+
   // src/index.ts
   var scriptTag = document.currentScript;
   var runtimeConfig2 = initializeSurfaceRuntimeConfig(scriptTag);
@@ -2515,4 +2558,5 @@
   });
   void resolveOpenTriggersOnLoad(environmentId2, runtimeConfig2);
   initReview();
+  drainStubQueue();
 })();

surface_tag.js

@@ -1947,7 +1947,7 @@
       this.src = new URL(src);
       this.log = createLogger("Surface Embed");
       this.store = window.SurfaceTagStore;
-      this.currentQuestionId = document.currentScript?.getAttribute("data-question-id") || null;
+      this.currentQuestionId = options.questionId || document.currentScript?.getAttribute("data-question-id") || null;
       _SurfaceEmbed._instances.push(this);
       if (this._isFormPreviewMode()) {
         this.log.info({ message: "Form is in preview mode" });
@@ -2494,6 +2494,49 @@
     window.addEventListener("message", onMessage);
   }
 
+  // src/stub-queue.ts
+  var RELAYED_METHODS = [
+    "showSurfaceForm",
+    "hideSurfaceForm",
+    "initializeEmbed"
+  ];
+  function drainStubQueue() {
+    const w3 = window;
+    if (!Array.isArray(w3.SurfaceTagQueue)) return;
+    const entries = w3.SurfaceTagQueue;
+    w3.SurfaceTagQueue = { push: processEntry };
+    entries.forEach(processEntry);
+  }
+  function processEntry(entry) {
+    try {
+      if (entry?.type === "consent") {
+        setSurfaceConsent(entry.args?.[0] ?? {});
+        return;
+      }
+      if (entry?.type !== "embed") return;
+      const [src, embedType, targetClass, options] = Array.from(entry.args ?? []);
+      const embed = new SurfaceEmbed(
+        src,
+        embedType,
+        targetClass,
+        {
+          ...options ?? {},
+          ...entry.questionId ? { questionId: entry.questionId } : {}
+        }
+      );
+      for (const method of entry.calls ?? []) {
+        if (RELAYED_METHODS.includes(method)) embed[method]();
+      }
+      if (entry.stub && typeof entry.stub === "object") {
+        for (const method of RELAYED_METHODS) {
+          entry.stub[method] = () => embed[method]();
+        }
+      }
+    } catch (error) {
+      console.error("Surface Tag: failed to replay queued call", error);
+    }
+  }
+
   // src/index.ts
   var scriptTag = document.currentScript;
   var runtimeConfig2 = initializeSurfaceRuntimeConfig(scriptTag);
@@ -2515,4 +2558,5 @@
   });
   void resolveOpenTriggersOnLoad(environmentId2, runtimeConfig2);
   initReview();
+  drainStubQueue();
 })();