@signap/signals-angular 2.2.0-dev.20260930000246.gd4b7f02 → 2.2.0

package/README.md

@@ -71,7 +71,8 @@ round-trip — no separate ack/lookup transition.
 | field       | type                                     | when populated                         |
 |-------------|------------------------------------------|----------------------------------------|
 | `data`      | `Signal<IdentifyResult \| undefined>`    | once `agent.identify()` resolves       |
-| `isLoading` | `Signal<boolean>`                        | true between call time and `data`       |
+| `isLoading` | `Signal<boolean>`                        | true between call time and `data`; false while held |
+| `isHeld`    | `Signal<boolean>`                        | true while `enabled()` is `false`      |
 | `error`     | `Signal<Error \| null>`                  | last failure (load / identify)         |
 | `refetch`   | `() => Promise<void>`                    | re-run `agent.identify()`              |
 
@@ -82,6 +83,19 @@ SSR-safe: `provideSignals()` gates `SignalsAgent.load()` behind
 `isPlatformBrowser(PLATFORM_ID)`, so it never runs during Angular Universal /
 prerender server rendering.
 
+## Holding collection
+
+```ts
+const enabled = signal(false);
+provideSignals({ apiKey: "pk_live_...", endpoint: "https://ingest.example" }, { enabled });
+```
+
+While `enabled()` is `false` the client does not load the agent: the SDK registers no event listener, runs no collector and sends no request, and `injectVisitorData()` returns `isHeld() === true`. Setting it to `true` loads the agent and runs the first identify, exactly as if `enabled` had never been set. Setting it back to `false` stops the SDK's interaction listeners for the whole page and discards any identify result still in flight; a request that has already been sent is not recalled. Without the second argument, nothing is held. `SignalsClient` also exposes the same two transitions as `release()` and `hold()`.
+
+Holding or releasing does not delete anything Signap has already received.
+
+The hold applies to the agent this client loads. A copy of the SDK loaded another way, for example the CDN script, is not held.
+
 ## Endpoint (required)
 
 `provideSignals()` takes the underlying `AgentLoadOptions`. `endpoint` is

package/dist/index.cjs

@@ -36,34 +36,109 @@ var import_signals_web = require("@signap/signals-web");
 var SignalsClient = class {
   agentState = (0, import_core.signal)(null);
   loadErrorState = (0, import_core.signal)(null);
+  heldState;
   /** Resolved agent, or `null` until `SignalsAgent.load()` settles. */
   agent = this.agentState.asReadonly();
   /** Non-null if `SignalsAgent.load()` rejected. */
   loadError = this.loadErrorState.asReadonly();
+  /** True while held (`provideSignals(opts, { enabled })` with `enabled()` false): nothing is loaded. */
+  held;
   /**
-   * Resolves once `load()` has settled (agent set OR loadError set). Lets
-   * `injectVisitorData()` await readiness without an Angular `effect`, so the
-   * auto-identify fires exactly once regardless of change-detection timing.
+   * Resolves once the FIRST `load()` has settled (agent set OR loadError set), or
+   * at once outside a browser. While the client is held before its first release,
+   * it stays pending.
    */
   ready;
+  opts;
+  browser;
+  resolveReady = () => {
+  };
+  started = false;
+  loaded = null;
+  // Bumped on every withdrawal; a load() that settles under an older generation is discarded.
+  generation = 0;
+  listeners = /* @__PURE__ */ new Set();
   /**
-   * @param opts    forwarded verbatim to `SignalsAgent.load()`.
-   * @param browser whether we're running in a browser; `load()` only fires
-   *                client-side so SSR / prerender never touches
-   *                window/document/WebCrypto (the Angular analog of the Vue
-   *                plugin's `typeof window` guard).
+   * @param opts          forwarded verbatim to `SignalsAgent.load()`.
+   * @param browser       whether we're running in a browser; `load()` only fires
+   *                      client-side so SSR / prerender never touches
+   *                      window/document/WebCrypto (the Angular analog of the Vue
+   *                      plugin's `typeof window` guard).
+   * @param initiallyHeld start held (issue 2894): do not load until `release()`.
    */
-  constructor(opts, browser) {
+  constructor(opts, browser, initiallyHeld = false) {
+    this.opts = opts;
+    this.browser = browser;
+    this.heldState = (0, import_core.signal)(initiallyHeld);
+    this.held = this.heldState.asReadonly();
+    this.ready = new Promise((resolve) => {
+      this.resolveReady = resolve;
+    });
     if (!browser) {
-      this.ready = Promise.resolve();
+      this.resolveReady();
       return;
     }
-    this.ready = import_signals_web.SignalsAgent.load(opts).then((loaded) => {
+    if (!initiallyHeld) this.release();
+  }
+  /**
+   * Leave the held state: load the agent once (a no-op if already released). What
+   * `provideSignals()` calls when its `enabled` signal becomes true.
+   */
+  release() {
+    this.heldState.set(false);
+    if (!this.browser || this.started) return;
+    this.started = true;
+    const mine = this.generation;
+    import_signals_web.SignalsAgent.load(this.opts).then((loaded) => {
+      if (mine !== this.generation) {
+        if (!this.started) loaded.stopObservers();
+        return;
+      }
+      this.loaded = loaded;
       this.agentState.set(loaded);
+      this.settled();
     }).catch((err) => {
+      if (mine !== this.generation) return;
       this.loadErrorState.set(err instanceof Error ? err : new Error(String(err)));
+      this.settled();
     });
   }
+  /**
+   * Enter the held state. After a release this stops the SDK's interaction
+   * listeners (page-wide, for this copy of the SDK), drops the agent and discards
+   * a load still in flight; a request already sent is not recalled, and nothing
+   * already received is deleted. Before any release it only marks the client held.
+   */
+  hold() {
+    this.heldState.set(true);
+    if (!this.started) {
+      this.notify();
+      return;
+    }
+    this.started = false;
+    this.generation++;
+    this.loaded?.stopObservers();
+    this.loaded = null;
+    this.agentState.set(null);
+    this.loadErrorState.set(null);
+    this.notify();
+  }
+  /**
+   * @internal Called after every state change (a load settling, a hold). Lets
+   * `injectVisitorData()` re-run without an Angular `effect`, so the auto-identify
+   * fires exactly once per release regardless of change-detection timing.
+   */
+  onChange(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  settled() {
+    this.resolveReady();
+    this.notify();
+  }
+  notify() {
+    for (const l of [...this.listeners]) l();
+  }
 };
 
 // src/provide-signals.ts
@@ -75,11 +150,21 @@ var import_core2 = require("@angular/core");
 var SIGNALS_CLIENT = new import_core2.InjectionToken("signap.signals.client");
 
 // src/provide-signals.ts
-function provideSignals(opts) {
+function provideSignals(opts, config = {}) {
   return (0, import_core3.makeEnvironmentProviders)([
     {
       provide: SIGNALS_CLIENT,
-      useFactory: () => new SignalsClient(opts, (0, import_common.isPlatformBrowser)((0, import_core3.inject)(import_core3.PLATFORM_ID)))
+      useFactory: () => {
+        const browser = (0, import_common.isPlatformBrowser)((0, import_core3.inject)(import_core3.PLATFORM_ID));
+        const { enabled } = config;
+        if (!enabled) return new SignalsClient(opts, browser);
+        const client = new SignalsClient(opts, browser, !(0, import_core3.untracked)(enabled));
+        (0, import_core3.effect)(() => {
+          const on = enabled();
+          (0, import_core3.untracked)(() => on ? client.release() : client.hold());
+        });
+        return client;
+      }
     }
   ]);
 }
@@ -96,10 +181,30 @@ function injectVisitorData(opts) {
   }
   const data = (0, import_core4.signal)(void 0);
   const error = (0, import_core4.signal)(null);
-  const isLoading = (0, import_core4.signal)(client.agent() === null && client.loadError() === null);
+  const isLoading = (0, import_core4.signal)(
+    !client.held() && client.agent() === null && client.loadError() === null
+  );
+  const isHeld = (0, import_core4.computed)(() => client.held());
   let token = { cancelled: false };
+  let started = false;
+  const onChange = () => {
+    if (client.held()) {
+      token.cancelled = true;
+      started = false;
+      data.set(void 0);
+      error.set(null);
+      isLoading.set(false);
+      return;
+    }
+    if (started) return;
+    if (client.agent() === null && client.loadError() === null) return;
+    started = true;
+    void run();
+  };
+  const unsubscribe = client.onChange(onChange);
   (0, import_core4.inject)(import_core4.DestroyRef).onDestroy(() => {
     token.cancelled = true;
+    unsubscribe();
   });
   const run = async () => {
     const agent = client.agent();
@@ -128,8 +233,8 @@ function injectVisitorData(opts) {
       if (!my.cancelled) isLoading.set(false);
     }
   };
-  void client.ready.then(() => run());
-  return { data, isLoading, error, refetch: run };
+  void Promise.resolve().then(onChange);
+  return { data, isLoading, isHeld, error, refetch: run };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/client.ts","../src/provide-signals.ts","../src/tokens.ts","../src/inject-visitor-data.ts"],"sourcesContent":["export {\n  type AgentLoadOptions,\n  type IdentifyOptions,\n  type IdentifyResult,\n  SdkError,\n  type SdkErrorCode,\n  VERSION as WEB_SDK_VERSION,\n} from \"@signap/signals-web\";\n\nexport { SignalsClient } from \"./client\";\nexport { provideSignals } from \"./provide-signals\";\nexport { SIGNALS_CLIENT } from \"./tokens\";\nexport {\n  injectVisitorData,\n  type InjectVisitorDataOptions,\n  type InjectVisitorDataResult,\n} from \"./inject-visitor-data\";\n","import { type Signal, signal } from \"@angular/core\";\nimport { type AgentLoadOptions, SignalsAgent } from \"@signap/signals-web\";\n\n/**\n * Holds a single lazily-loaded SignalsAgent and exposes its readiness as Angular\n * signals — the framework-native analog of the Vue wrapper's provide/inject refs\n * and the React wrapper's context. `agent()` is `null` until `SignalsAgent.load()`\n * settles; `loadError()` is non-null if it rejected (e.g. an invalid apiKey).\n *\n * Deliberately NOT `@Injectable`: a decorator-free class keeps this package\n * AOT-safe under a plain tsup build (no ngtsc / ng-packagr partial-Ivy metadata\n * step). It is wired into DI by the factory in `provideSignals()`.\n */\nexport class SignalsClient {\n  private readonly agentState = signal<SignalsAgent | null>(null);\n  private readonly loadErrorState = signal<Error | null>(null);\n\n  /** Resolved agent, or `null` until `SignalsAgent.load()` settles. */\n  readonly agent: Signal<SignalsAgent | null> = this.agentState.asReadonly();\n  /** Non-null if `SignalsAgent.load()` rejected. */\n  readonly loadError: Signal<Error | null> = this.loadErrorState.asReadonly();\n  /**\n   * Resolves once `load()` has settled (agent set OR loadError set). Lets\n   * `injectVisitorData()` await readiness without an Angular `effect`, so the\n   * auto-identify fires exactly once regardless of change-detection timing.\n   */\n  readonly ready: Promise<void>;\n\n  /**\n   * @param opts    forwarded verbatim to `SignalsAgent.load()`.\n   * @param browser whether we're running in a browser; `load()` only fires\n   *                client-side so SSR / prerender never touches\n   *                window/document/WebCrypto (the Angular analog of the Vue\n   *                plugin's `typeof window` guard).\n   */\n  constructor(opts: AgentLoadOptions, browser: boolean) {\n    if (!browser) {\n      this.ready = Promise.resolve();\n      return;\n    }\n    this.ready = SignalsAgent.load(opts)\n      .then((loaded) => {\n        this.agentState.set(loaded);\n      })\n      .catch((err: unknown) => {\n        this.loadErrorState.set(err instanceof Error ? err : new Error(String(err)));\n      });\n  }\n}\n","import { isPlatformBrowser } from \"@angular/common\";\nimport {\n  type EnvironmentProviders,\n  PLATFORM_ID,\n  inject,\n  makeEnvironmentProviders,\n} from \"@angular/core\";\nimport type { AgentLoadOptions } from \"@signap/signals-web\";\nimport { SignalsClient } from \"./client\";\nimport { SIGNALS_CLIENT } from \"./tokens\";\n\n/**\n * Registers a single app-wide SignalsAgent — the idiomatic standalone-Angular\n * entry point, analogous to React's `<SignalsProvider>` and Vue's\n * `app.use(SignalsPlugin)`:\n *\n * ```ts\n * bootstrapApplication(AppComponent, {\n *   providers: [\n *     provideSignals({ apiKey: \"pk_live_...\", endpoint: \"https://ingest.example\" }),\n *   ],\n * });\n * ```\n *\n * SSR-safe: the factory injects `PLATFORM_ID` and only lets the client call\n * `SignalsAgent.load()` in a browser, so a server render / prerender never loads\n * the agent.\n *\n * `opts` is snapshotted here at bootstrap; to swap apiKey/endpoint, re-bootstrap\n * (same snapshot-at-init contract as the React/Vue wrappers).\n */\nexport function provideSignals(opts: AgentLoadOptions): EnvironmentProviders {\n  return makeEnvironmentProviders([\n    {\n      provide: SIGNALS_CLIENT,\n      useFactory: () => new SignalsClient(opts, isPlatformBrowser(inject(PLATFORM_ID))),\n    },\n  ]);\n}\n","import { InjectionToken } from \"@angular/core\";\nimport type { SignalsClient } from \"./client\";\n\n/**\n * DI token the app-wide {@link SignalsClient} is registered under (by\n * `provideSignals()`) and that `injectVisitorData()` resolves. Most consumers\n * don't inject this directly — call `injectVisitorData()`. It is exported for\n * advanced use (e.g. `inject(SIGNALS_CLIENT).agent()` to read the raw agent).\n */\nexport const SIGNALS_CLIENT = new InjectionToken<SignalsClient>(\"signap.signals.client\");\n","import { DestroyRef, type Signal, assertInInjectionContext, inject, signal } from \"@angular/core\";\nimport type { IdentifyOptions, IdentifyResult } from \"@signap/signals-web\";\nimport { SIGNALS_CLIENT } from \"./tokens\";\n\nexport type InjectVisitorDataOptions = IdentifyOptions;\n\nexport interface InjectVisitorDataResult {\n  /**\n   * Resolved visitor from `agent.identify()`. Under ADR §A2 the call is a single\n   * synchronous round-trip — `visitorId`/`confidence`/`identifiedAt` arrive\n   * together, no polling. A `Signal`, so read it as `data()` (in a template or a\n   * `computed`/`effect`).\n   */\n  data: Signal<IdentifyResult | undefined>;\n  /** True between call time and the identify() resolution (or `error`). */\n  isLoading: Signal<boolean>;\n  error: Signal<Error | null>;\n  /** Re-run `agent.identify()` (e.g. from a button click). */\n  refetch: () => Promise<void>;\n}\n\n/**\n * Auto-identifies once the provider's agent is ready, then exposes the resolved\n * visitor as Angular signals — the framework-native analog of React's\n * `useVisitorData()` hook and Vue's `useVisitorData()` composable.\n *\n * Must be called in an injection context (a component/directive constructor or a\n * field initializer, or inside `runInInjectionContext`) below `provideSignals()`.\n */\nexport function injectVisitorData(opts?: InjectVisitorDataOptions): InjectVisitorDataResult {\n  assertInInjectionContext(injectVisitorData);\n\n  const client = inject(SIGNALS_CLIENT, { optional: true });\n  if (!client) {\n    throw new Error(\n      \"[@signap/signals-angular] injectVisitorData() requires provideSignals() in the application (or component) providers\",\n    );\n  }\n\n  const data = signal<IdentifyResult | undefined>(undefined);\n  const error = signal<Error | null>(null);\n  // Loading until the agent (or a load error) settles.\n  const isLoading = signal(client.agent() === null && client.loadError() === null);\n\n  // Supersede token so a slow response from a call that refetch() replaced (or a\n  // response arriving after teardown) is discarded.\n  let token = { cancelled: false };\n  inject(DestroyRef).onDestroy(() => {\n    token.cancelled = true;\n  });\n\n  const run = async (): Promise<void> => {\n    const agent = client.agent();\n    if (!agent) {\n      const loadError = client.loadError();\n      if (loadError) {\n        error.set(loadError);\n        isLoading.set(false);\n      }\n      return;\n    }\n    token.cancelled = true;\n    const my = { cancelled: false };\n    token = my;\n    isLoading.set(true);\n    error.set(null);\n    data.set(undefined);\n    try {\n      const res = await agent.identify(opts);\n      if (my.cancelled) return;\n      data.set(res);\n    } catch (err) {\n      if (my.cancelled) return;\n      error.set(err instanceof Error ? err : new Error(String(err)));\n    } finally {\n      if (!my.cancelled) isLoading.set(false);\n    }\n  };\n\n  // Auto-run exactly once, after load() settles. `ready` resolves whether load()\n  // succeeded or failed; even if it already resolved, `.then` defers to a\n  // microtask so the returned signals are wired up before the first run().\n  void client.ready.then(() => run());\n\n  return { data, isLoading, error, refetch: run };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAAAA,sBAOO;;;ACPP,kBAAoC;AACpC,yBAAoD;AAY7C,IAAM,gBAAN,MAAoB;AAAA,EACR,iBAAa,oBAA4B,IAAI;AAAA,EAC7C,qBAAiB,oBAAqB,IAAI;AAAA;AAAA,EAGlD,QAAqC,KAAK,WAAW,WAAW;AAAA;AAAA,EAEhE,YAAkC,KAAK,eAAe,WAAW;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMjE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAST,YAAY,MAAwB,SAAkB;AACpD,QAAI,CAAC,SAAS;AACZ,WAAK,QAAQ,QAAQ,QAAQ;AAC7B;AAAA,IACF;AACA,SAAK,QAAQ,gCAAa,KAAK,IAAI,EAChC,KAAK,CAAC,WAAW;AAChB,WAAK,WAAW,IAAI,MAAM;AAAA,IAC5B,CAAC,EACA,MAAM,CAAC,QAAiB;AACvB,WAAK,eAAe,IAAI,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC,CAAC;AAAA,IAC7E,CAAC;AAAA,EACL;AACF;;;AChDA,oBAAkC;AAClC,IAAAC,eAKO;;;ACNP,IAAAC,eAA+B;AASxB,IAAM,iBAAiB,IAAI,4BAA8B,uBAAuB;;;ADsBhF,SAAS,eAAe,MAA8C;AAC3E,aAAO,uCAAyB;AAAA,IAC9B;AAAA,MACE,SAAS;AAAA,MACT,YAAY,MAAM,IAAI,cAAc,UAAM,qCAAkB,qBAAO,wBAAW,CAAC,CAAC;AAAA,IAClF;AAAA,EACF,CAAC;AACH;;;AEtCA,IAAAC,eAAkF;AA6B3E,SAAS,kBAAkB,MAA0D;AAC1F,6CAAyB,iBAAiB;AAE1C,QAAM,aAAS,qBAAO,gBAAgB,EAAE,UAAU,KAAK,CAAC;AACxD,MAAI,CAAC,QAAQ;AACX,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AAEA,QAAM,WAAO,qBAAmC,MAAS;AACzD,QAAM,YAAQ,qBAAqB,IAAI;AAEvC,QAAM,gBAAY,qBAAO,OAAO,MAAM,MAAM,QAAQ,OAAO,UAAU,MAAM,IAAI;AAI/E,MAAI,QAAQ,EAAE,WAAW,MAAM;AAC/B,2BAAO,uBAAU,EAAE,UAAU,MAAM;AACjC,UAAM,YAAY;AAAA,EACpB,CAAC;AAED,QAAM,MAAM,YAA2B;AACrC,UAAM,QAAQ,OAAO,MAAM;AAC3B,QAAI,CAAC,OAAO;AACV,YAAM,YAAY,OAAO,UAAU;AACnC,UAAI,WAAW;AACb,cAAM,IAAI,SAAS;AACnB,kBAAU,IAAI,KAAK;AAAA,MACrB;AACA;AAAA,IACF;AACA,UAAM,YAAY;AAClB,UAAM,KAAK,EAAE,WAAW,MAAM;AAC9B,YAAQ;AACR,cAAU,IAAI,IAAI;AAClB,UAAM,IAAI,IAAI;AACd,SAAK,IAAI,MAAS;AAClB,QAAI;AACF,YAAM,MAAM,MAAM,MAAM,SAAS,IAAI;AACrC,UAAI,GAAG,UAAW;AAClB,WAAK,IAAI,GAAG;AAAA,IACd,SAAS,KAAK;AACZ,UAAI,GAAG,UAAW;AAClB,YAAM,IAAI,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC,CAAC;AAAA,IAC/D,UAAE;AACA,UAAI,CAAC,GAAG,UAAW,WAAU,IAAI,KAAK;AAAA,IACxC;AAAA,EACF;AAKA,OAAK,OAAO,MAAM,KAAK,MAAM,IAAI,CAAC;AAElC,SAAO,EAAE,MAAM,WAAW,OAAO,SAAS,IAAI;AAChD;","names":["import_signals_web","import_core","import_core","import_core"]}
+{"version":3,"sources":["../src/index.ts","../src/client.ts","../src/provide-signals.ts","../src/tokens.ts","../src/inject-visitor-data.ts"],"sourcesContent":["export {\n  type AgentLoadOptions,\n  type IdentifyOptions,\n  type IdentifyResult,\n  SdkError,\n  type SdkErrorCode,\n  VERSION as WEB_SDK_VERSION,\n} from \"@signap/signals-web\";\n\nexport { SignalsClient } from \"./client\";\nexport { provideSignals, type SignalsConfig } from \"./provide-signals\";\nexport { SIGNALS_CLIENT } from \"./tokens\";\nexport {\n  injectVisitorData,\n  type InjectVisitorDataOptions,\n  type InjectVisitorDataResult,\n} from \"./inject-visitor-data\";\n","import { type Signal, type WritableSignal, signal } from \"@angular/core\";\nimport { type AgentLoadOptions, SignalsAgent } from \"@signap/signals-web\";\n\n/**\n * Holds a single lazily-loaded SignalsAgent and exposes its readiness as Angular\n * signals — the framework-native analog of the Vue wrapper's provide/inject refs\n * and the React wrapper's context. `agent()` is `null` until `SignalsAgent.load()`\n * settles; `loadError()` is non-null if it rejected (e.g. an invalid apiKey).\n *\n * Deliberately NOT `@Injectable`: a decorator-free class keeps this package\n * AOT-safe under a plain tsup build (no ngtsc / ng-packagr partial-Ivy metadata\n * step). It is wired into DI by the factory in `provideSignals()`.\n */\nexport class SignalsClient {\n  private readonly agentState = signal<SignalsAgent | null>(null);\n  private readonly loadErrorState = signal<Error | null>(null);\n  private readonly heldState: WritableSignal<boolean>;\n\n  /** Resolved agent, or `null` until `SignalsAgent.load()` settles. */\n  readonly agent: Signal<SignalsAgent | null> = this.agentState.asReadonly();\n  /** Non-null if `SignalsAgent.load()` rejected. */\n  readonly loadError: Signal<Error | null> = this.loadErrorState.asReadonly();\n  /** True while held (`provideSignals(opts, { enabled })` with `enabled()` false): nothing is loaded. */\n  readonly held: Signal<boolean>;\n  /**\n   * Resolves once the FIRST `load()` has settled (agent set OR loadError set), or\n   * at once outside a browser. While the client is held before its first release,\n   * it stays pending.\n   */\n  readonly ready: Promise<void>;\n\n  private readonly opts: AgentLoadOptions;\n  private readonly browser: boolean;\n  private resolveReady: () => void = () => {};\n  private started = false;\n  private loaded: SignalsAgent | null = null;\n  // Bumped on every withdrawal; a load() that settles under an older generation is discarded.\n  private generation = 0;\n  private readonly listeners = new Set<() => void>();\n\n  /**\n   * @param opts          forwarded verbatim to `SignalsAgent.load()`.\n   * @param browser       whether we're running in a browser; `load()` only fires\n   *                      client-side so SSR / prerender never touches\n   *                      window/document/WebCrypto (the Angular analog of the Vue\n   *                      plugin's `typeof window` guard).\n   * @param initiallyHeld start held (issue 2894): do not load until `release()`.\n   */\n  constructor(opts: AgentLoadOptions, browser: boolean, initiallyHeld = false) {\n    this.opts = opts;\n    this.browser = browser;\n    this.heldState = signal(initiallyHeld);\n    this.held = this.heldState.asReadonly();\n    this.ready = new Promise<void>((resolve) => {\n      this.resolveReady = resolve;\n    });\n    if (!browser) {\n      this.resolveReady();\n      return;\n    }\n    if (!initiallyHeld) this.release();\n  }\n\n  /**\n   * Leave the held state: load the agent once (a no-op if already released). What\n   * `provideSignals()` calls when its `enabled` signal becomes true.\n   */\n  release(): void {\n    this.heldState.set(false);\n    if (!this.browser || this.started) return;\n    this.started = true;\n    const mine = this.generation;\n    SignalsAgent.load(this.opts)\n      .then((loaded) => {\n        if (mine !== this.generation) {\n          // Withdrawn while in flight. load() started the observers synchronously;\n          // stop them, unless a newer release is running them now (page-wide singletons).\n          if (!this.started) loaded.stopObservers();\n          return;\n        }\n        this.loaded = loaded;\n        this.agentState.set(loaded);\n        this.settled();\n      })\n      .catch((err: unknown) => {\n        if (mine !== this.generation) return;\n        this.loadErrorState.set(err instanceof Error ? err : new Error(String(err)));\n        this.settled();\n      });\n  }\n\n  /**\n   * Enter the held state. After a release this stops the SDK's interaction\n   * listeners (page-wide, for this copy of the SDK), drops the agent and discards\n   * a load still in flight; a request already sent is not recalled, and nothing\n   * already received is deleted. Before any release it only marks the client held.\n   */\n  hold(): void {\n    this.heldState.set(true);\n    if (!this.started) {\n      this.notify();\n      return;\n    }\n    this.started = false;\n    this.generation++;\n    this.loaded?.stopObservers();\n    this.loaded = null;\n    this.agentState.set(null);\n    this.loadErrorState.set(null);\n    this.notify();\n  }\n\n  /**\n   * @internal Called after every state change (a load settling, a hold). Lets\n   * `injectVisitorData()` re-run without an Angular `effect`, so the auto-identify\n   * fires exactly once per release regardless of change-detection timing.\n   */\n  onChange(listener: () => void): () => void {\n    this.listeners.add(listener);\n    return () => this.listeners.delete(listener);\n  }\n\n  private settled(): void {\n    this.resolveReady();\n    this.notify();\n  }\n\n  private notify(): void {\n    for (const l of [...this.listeners]) l();\n  }\n}\n","import { isPlatformBrowser } from \"@angular/common\";\nimport {\n  type EnvironmentProviders,\n  PLATFORM_ID,\n  type Signal,\n  effect,\n  inject,\n  makeEnvironmentProviders,\n  untracked,\n} from \"@angular/core\";\nimport type { AgentLoadOptions } from \"@signap/signals-web\";\nimport { SignalsClient } from \"./client\";\nimport { SIGNALS_CLIENT } from \"./tokens\";\n\n/**\n * Registers a single app-wide SignalsAgent — the idiomatic standalone-Angular\n * entry point, analogous to React's `<SignalsProvider>` and Vue's\n * `app.use(SignalsPlugin)`:\n *\n * ```ts\n * bootstrapApplication(AppComponent, {\n *   providers: [\n *     provideSignals({ apiKey: \"pk_live_...\", endpoint: \"https://ingest.example\" }),\n *   ],\n * });\n * ```\n *\n * SSR-safe: the factory injects `PLATFORM_ID` and only lets the client call\n * `SignalsAgent.load()` in a browser, so a server render / prerender never loads\n * the agent.\n *\n * `opts` is snapshotted here at bootstrap; to swap apiKey/endpoint, re-bootstrap\n * (same snapshot-at-init contract as the React/Vue wrappers).\n */\nexport function provideSignals(\n  opts: AgentLoadOptions,\n  config: SignalsConfig = {},\n): EnvironmentProviders {\n  return makeEnvironmentProviders([\n    {\n      provide: SIGNALS_CLIENT,\n      useFactory: () => {\n        const browser = isPlatformBrowser(inject(PLATFORM_ID));\n        const { enabled } = config;\n        if (!enabled) return new SignalsClient(opts, browser);\n        const client = new SignalsClient(opts, browser, !untracked(enabled));\n        // The factory runs in an injection context, so the effect lives as long as\n        // the environment injector. The client's writes are untracked so they are\n        // not writes \"inside\" the effect (Angular 17/18 reject those by default).\n        effect(() => {\n          const on = enabled();\n          untracked(() => (on ? client.release() : client.hold()));\n        });\n        return client;\n      },\n    },\n  ]);\n}\n\n/** Second argument of `provideSignals()`. */\nexport interface SignalsConfig {\n  /**\n   * While this signal is `false` the client is held: it does not load the agent, so\n   * the SDK registers no event listener, runs no collector and sends no request, and\n   * `injectVisitorData()` returns `isHeld() === true`. When it becomes `true` the\n   * agent loads and the first identify runs, as if `enabled` had never been set.\n   * When it goes back to `false` the SDK's interaction listeners stop (page-wide, for\n   * this copy of the SDK) and any identify result still in flight is discarded; a\n   * request already sent is not recalled, and nothing already received is deleted.\n   * Omitted = never held.\n   */\n  enabled?: Signal<boolean>;\n}\n","import { InjectionToken } from \"@angular/core\";\nimport type { SignalsClient } from \"./client\";\n\n/**\n * DI token the app-wide {@link SignalsClient} is registered under (by\n * `provideSignals()`) and that `injectVisitorData()` resolves. Most consumers\n * don't inject this directly — call `injectVisitorData()`. It is exported for\n * advanced use (e.g. `inject(SIGNALS_CLIENT).agent()` to read the raw agent).\n */\nexport const SIGNALS_CLIENT = new InjectionToken<SignalsClient>(\"signap.signals.client\");\n","import {\n  DestroyRef,\n  type Signal,\n  assertInInjectionContext,\n  computed,\n  inject,\n  signal,\n} from \"@angular/core\";\nimport type { IdentifyOptions, IdentifyResult } from \"@signap/signals-web\";\nimport { SIGNALS_CLIENT } from \"./tokens\";\n\nexport type InjectVisitorDataOptions = IdentifyOptions;\n\nexport interface InjectVisitorDataResult {\n  /**\n   * Resolved visitor from `agent.identify()`. Under ADR §A2 the call is a single\n   * synchronous round-trip — `visitorId`/`confidence`/`identifiedAt` arrive\n   * together, no polling. A `Signal`, so read it as `data()` (in a template or a\n   * `computed`/`effect`).\n   */\n  data: Signal<IdentifyResult | undefined>;\n  /** True between call time and the identify() resolution (or `error`). False while held. */\n  isLoading: Signal<boolean>;\n  /**\n   * True while `provideSignals(opts, { enabled })` is held. Nothing is loaded or sent,\n   * `data()` is `undefined` and `refetch()` does nothing. Always false without `enabled`.\n   */\n  isHeld: Signal<boolean>;\n  error: Signal<Error | null>;\n  /** Re-run `agent.identify()` (e.g. from a button click). */\n  refetch: () => Promise<void>;\n}\n\n/**\n * Auto-identifies once the provider's agent is ready, then exposes the resolved\n * visitor as Angular signals — the framework-native analog of React's\n * `useVisitorData()` hook and Vue's `useVisitorData()` composable.\n *\n * Must be called in an injection context (a component/directive constructor or a\n * field initializer, or inside `runInInjectionContext`) below `provideSignals()`.\n */\nexport function injectVisitorData(opts?: InjectVisitorDataOptions): InjectVisitorDataResult {\n  assertInInjectionContext(injectVisitorData);\n\n  const client = inject(SIGNALS_CLIENT, { optional: true });\n  if (!client) {\n    throw new Error(\n      \"[@signap/signals-angular] injectVisitorData() requires provideSignals() in the application (or component) providers\",\n    );\n  }\n\n  const data = signal<IdentifyResult | undefined>(undefined);\n  const error = signal<Error | null>(null);\n  // Loading until the agent (or a load error) settles — unless held.\n  const isLoading = signal(\n    !client.held() && client.agent() === null && client.loadError() === null,\n  );\n  const isHeld = computed(() => client.held());\n\n  // Supersede token so a slow response from a call that refetch() replaced (or a\n  // response arriving after teardown) is discarded.\n  let token = { cancelled: false };\n  let started = false;\n  const onChange = (): void => {\n    if (client.held()) {\n      // Held (issue 2894): discard any identify in flight and any previous result, and\n      // re-arm so a later release identifies once, like a fresh call.\n      token.cancelled = true;\n      started = false;\n      data.set(undefined);\n      error.set(null);\n      isLoading.set(false);\n      return;\n    }\n    if (started) return;\n    if (client.agent() === null && client.loadError() === null) return; // not settled yet\n    started = true;\n    void run();\n  };\n  const unsubscribe = client.onChange(onChange);\n  inject(DestroyRef).onDestroy(() => {\n    token.cancelled = true;\n    unsubscribe();\n  });\n\n  const run = async (): Promise<void> => {\n    const agent = client.agent();\n    if (!agent) {\n      const loadError = client.loadError();\n      if (loadError) {\n        error.set(loadError);\n        isLoading.set(false);\n      }\n      return;\n    }\n    token.cancelled = true;\n    const my = { cancelled: false };\n    token = my;\n    isLoading.set(true);\n    error.set(null);\n    data.set(undefined);\n    try {\n      const res = await agent.identify(opts);\n      if (my.cancelled) return;\n      data.set(res);\n    } catch (err) {\n      if (my.cancelled) return;\n      error.set(err instanceof Error ? err : new Error(String(err)));\n    } finally {\n      if (!my.cancelled) isLoading.set(false);\n    }\n  };\n\n  // Auto-run once per release, after load() settles. The client calls onChange on\n  // every settle and hold; the first look is deferred to a microtask (as the old\n  // `ready.then` was) so the returned signals are wired up before the first run().\n  void Promise.resolve().then(onChange);\n\n  return { data, isLoading, isHeld, error, refetch: run };\n}\n"],"mappings":"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","names":["import_signals_web","import_core","import_core","import_core"]}

package/dist/index.d.cts

@@ -15,24 +15,55 @@ import { Signal, EnvironmentProviders, InjectionToken } from '@angular/core';
 declare class SignalsClient {
     private readonly agentState;
     private readonly loadErrorState;
+    private readonly heldState;
     /** Resolved agent, or `null` until `SignalsAgent.load()` settles. */
     readonly agent: Signal<SignalsAgent | null>;
     /** Non-null if `SignalsAgent.load()` rejected. */
     readonly loadError: Signal<Error | null>;
+    /** True while held (`provideSignals(opts, { enabled })` with `enabled()` false): nothing is loaded. */
+    readonly held: Signal<boolean>;
     /**
-     * Resolves once `load()` has settled (agent set OR loadError set). Lets
-     * `injectVisitorData()` await readiness without an Angular `effect`, so the
-     * auto-identify fires exactly once regardless of change-detection timing.
+     * Resolves once the FIRST `load()` has settled (agent set OR loadError set), or
+     * at once outside a browser. While the client is held before its first release,
+     * it stays pending.
      */
     readonly ready: Promise<void>;
+    private readonly opts;
+    private readonly browser;
+    private resolveReady;
+    private started;
+    private loaded;
+    private generation;
+    private readonly listeners;
     /**
-     * @param opts    forwarded verbatim to `SignalsAgent.load()`.
-     * @param browser whether we're running in a browser; `load()` only fires
-     *                client-side so SSR / prerender never touches
-     *                window/document/WebCrypto (the Angular analog of the Vue
-     *                plugin's `typeof window` guard).
+     * @param opts          forwarded verbatim to `SignalsAgent.load()`.
+     * @param browser       whether we're running in a browser; `load()` only fires
+     *                      client-side so SSR / prerender never touches
+     *                      window/document/WebCrypto (the Angular analog of the Vue
+     *                      plugin's `typeof window` guard).
+     * @param initiallyHeld start held (issue 2894): do not load until `release()`.
      */
-    constructor(opts: AgentLoadOptions, browser: boolean);
+    constructor(opts: AgentLoadOptions, browser: boolean, initiallyHeld?: boolean);
+    /**
+     * Leave the held state: load the agent once (a no-op if already released). What
+     * `provideSignals()` calls when its `enabled` signal becomes true.
+     */
+    release(): void;
+    /**
+     * Enter the held state. After a release this stops the SDK's interaction
+     * listeners (page-wide, for this copy of the SDK), drops the agent and discards
+     * a load still in flight; a request already sent is not recalled, and nothing
+     * already received is deleted. Before any release it only marks the client held.
+     */
+    hold(): void;
+    /**
+     * @internal Called after every state change (a load settling, a hold). Lets
+     * `injectVisitorData()` re-run without an Angular `effect`, so the auto-identify
+     * fires exactly once per release regardless of change-detection timing.
+     */
+    onChange(listener: () => void): () => void;
+    private settled;
+    private notify;
 }
 
 /**
@@ -55,7 +86,21 @@ declare class SignalsClient {
  * `opts` is snapshotted here at bootstrap; to swap apiKey/endpoint, re-bootstrap
  * (same snapshot-at-init contract as the React/Vue wrappers).
  */
-declare function provideSignals(opts: AgentLoadOptions): EnvironmentProviders;
+declare function provideSignals(opts: AgentLoadOptions, config?: SignalsConfig): EnvironmentProviders;
+/** Second argument of `provideSignals()`. */
+interface SignalsConfig {
+    /**
+     * While this signal is `false` the client is held: it does not load the agent, so
+     * the SDK registers no event listener, runs no collector and sends no request, and
+     * `injectVisitorData()` returns `isHeld() === true`. When it becomes `true` the
+     * agent loads and the first identify runs, as if `enabled` had never been set.
+     * When it goes back to `false` the SDK's interaction listeners stop (page-wide, for
+     * this copy of the SDK) and any identify result still in flight is discarded; a
+     * request already sent is not recalled, and nothing already received is deleted.
+     * Omitted = never held.
+     */
+    enabled?: Signal<boolean>;
+}
 
 /**
  * DI token the app-wide {@link SignalsClient} is registered under (by
@@ -74,8 +119,13 @@ interface InjectVisitorDataResult {
      * `computed`/`effect`).
      */
     data: Signal<IdentifyResult | undefined>;
-    /** True between call time and the identify() resolution (or `error`). */
+    /** True between call time and the identify() resolution (or `error`). False while held. */
     isLoading: Signal<boolean>;
+    /**
+     * True while `provideSignals(opts, { enabled })` is held. Nothing is loaded or sent,
+     * `data()` is `undefined` and `refetch()` does nothing. Always false without `enabled`.
+     */
+    isHeld: Signal<boolean>;
     error: Signal<Error | null>;
     /** Re-run `agent.identify()` (e.g. from a button click). */
     refetch: () => Promise<void>;
@@ -90,4 +140,4 @@ interface InjectVisitorDataResult {
  */
 declare function injectVisitorData(opts?: InjectVisitorDataOptions): InjectVisitorDataResult;
 
-export { type InjectVisitorDataOptions, type InjectVisitorDataResult, SIGNALS_CLIENT, SignalsClient, injectVisitorData, provideSignals };
+export { type InjectVisitorDataOptions, type InjectVisitorDataResult, SIGNALS_CLIENT, SignalsClient, type SignalsConfig, injectVisitorData, provideSignals };

package/dist/index.d.ts

@@ -15,24 +15,55 @@ import { Signal, EnvironmentProviders, InjectionToken } from '@angular/core';
 declare class SignalsClient {
     private readonly agentState;
     private readonly loadErrorState;
+    private readonly heldState;
     /** Resolved agent, or `null` until `SignalsAgent.load()` settles. */
     readonly agent: Signal<SignalsAgent | null>;
     /** Non-null if `SignalsAgent.load()` rejected. */
     readonly loadError: Signal<Error | null>;
+    /** True while held (`provideSignals(opts, { enabled })` with `enabled()` false): nothing is loaded. */
+    readonly held: Signal<boolean>;
     /**
-     * Resolves once `load()` has settled (agent set OR loadError set). Lets
-     * `injectVisitorData()` await readiness without an Angular `effect`, so the
-     * auto-identify fires exactly once regardless of change-detection timing.
+     * Resolves once the FIRST `load()` has settled (agent set OR loadError set), or
+     * at once outside a browser. While the client is held before its first release,
+     * it stays pending.
      */
     readonly ready: Promise<void>;
+    private readonly opts;
+    private readonly browser;
+    private resolveReady;
+    private started;
+    private loaded;
+    private generation;
+    private readonly listeners;
     /**
-     * @param opts    forwarded verbatim to `SignalsAgent.load()`.
-     * @param browser whether we're running in a browser; `load()` only fires
-     *                client-side so SSR / prerender never touches
-     *                window/document/WebCrypto (the Angular analog of the Vue
-     *                plugin's `typeof window` guard).
+     * @param opts          forwarded verbatim to `SignalsAgent.load()`.
+     * @param browser       whether we're running in a browser; `load()` only fires
+     *                      client-side so SSR / prerender never touches
+     *                      window/document/WebCrypto (the Angular analog of the Vue
+     *                      plugin's `typeof window` guard).
+     * @param initiallyHeld start held (issue 2894): do not load until `release()`.
      */
-    constructor(opts: AgentLoadOptions, browser: boolean);
+    constructor(opts: AgentLoadOptions, browser: boolean, initiallyHeld?: boolean);
+    /**
+     * Leave the held state: load the agent once (a no-op if already released). What
+     * `provideSignals()` calls when its `enabled` signal becomes true.
+     */
+    release(): void;
+    /**
+     * Enter the held state. After a release this stops the SDK's interaction
+     * listeners (page-wide, for this copy of the SDK), drops the agent and discards
+     * a load still in flight; a request already sent is not recalled, and nothing
+     * already received is deleted. Before any release it only marks the client held.
+     */
+    hold(): void;
+    /**
+     * @internal Called after every state change (a load settling, a hold). Lets
+     * `injectVisitorData()` re-run without an Angular `effect`, so the auto-identify
+     * fires exactly once per release regardless of change-detection timing.
+     */
+    onChange(listener: () => void): () => void;
+    private settled;
+    private notify;
 }
 
 /**
@@ -55,7 +86,21 @@ declare class SignalsClient {
  * `opts` is snapshotted here at bootstrap; to swap apiKey/endpoint, re-bootstrap
  * (same snapshot-at-init contract as the React/Vue wrappers).
  */
-declare function provideSignals(opts: AgentLoadOptions): EnvironmentProviders;
+declare function provideSignals(opts: AgentLoadOptions, config?: SignalsConfig): EnvironmentProviders;
+/** Second argument of `provideSignals()`. */
+interface SignalsConfig {
+    /**
+     * While this signal is `false` the client is held: it does not load the agent, so
+     * the SDK registers no event listener, runs no collector and sends no request, and
+     * `injectVisitorData()` returns `isHeld() === true`. When it becomes `true` the
+     * agent loads and the first identify runs, as if `enabled` had never been set.
+     * When it goes back to `false` the SDK's interaction listeners stop (page-wide, for
+     * this copy of the SDK) and any identify result still in flight is discarded; a
+     * request already sent is not recalled, and nothing already received is deleted.
+     * Omitted = never held.
+     */
+    enabled?: Signal<boolean>;
+}
 
 /**
  * DI token the app-wide {@link SignalsClient} is registered under (by
@@ -74,8 +119,13 @@ interface InjectVisitorDataResult {
      * `computed`/`effect`).
      */
     data: Signal<IdentifyResult | undefined>;
-    /** True between call time and the identify() resolution (or `error`). */
+    /** True between call time and the identify() resolution (or `error`). False while held. */
     isLoading: Signal<boolean>;
+    /**
+     * True while `provideSignals(opts, { enabled })` is held. Nothing is loaded or sent,
+     * `data()` is `undefined` and `refetch()` does nothing. Always false without `enabled`.
+     */
+    isHeld: Signal<boolean>;
     error: Signal<Error | null>;
     /** Re-run `agent.identify()` (e.g. from a button click). */
     refetch: () => Promise<void>;
@@ -90,4 +140,4 @@ interface InjectVisitorDataResult {
  */
 declare function injectVisitorData(opts?: InjectVisitorDataOptions): InjectVisitorDataResult;
 
-export { type InjectVisitorDataOptions, type InjectVisitorDataResult, SIGNALS_CLIENT, SignalsClient, injectVisitorData, provideSignals };
+export { type InjectVisitorDataOptions, type InjectVisitorDataResult, SIGNALS_CLIENT, SignalsClient, type SignalsConfig, injectVisitorData, provideSignals };

package/dist/index.js

@@ -10,42 +10,119 @@ import { SignalsAgent } from "@signap/signals-web";
 var SignalsClient = class {
   agentState = signal(null);
   loadErrorState = signal(null);
+  heldState;
   /** Resolved agent, or `null` until `SignalsAgent.load()` settles. */
   agent = this.agentState.asReadonly();
   /** Non-null if `SignalsAgent.load()` rejected. */
   loadError = this.loadErrorState.asReadonly();
+  /** True while held (`provideSignals(opts, { enabled })` with `enabled()` false): nothing is loaded. */
+  held;
   /**
-   * Resolves once `load()` has settled (agent set OR loadError set). Lets
-   * `injectVisitorData()` await readiness without an Angular `effect`, so the
-   * auto-identify fires exactly once regardless of change-detection timing.
+   * Resolves once the FIRST `load()` has settled (agent set OR loadError set), or
+   * at once outside a browser. While the client is held before its first release,
+   * it stays pending.
    */
   ready;
+  opts;
+  browser;
+  resolveReady = () => {
+  };
+  started = false;
+  loaded = null;
+  // Bumped on every withdrawal; a load() that settles under an older generation is discarded.
+  generation = 0;
+  listeners = /* @__PURE__ */ new Set();
   /**
-   * @param opts    forwarded verbatim to `SignalsAgent.load()`.
-   * @param browser whether we're running in a browser; `load()` only fires
-   *                client-side so SSR / prerender never touches
-   *                window/document/WebCrypto (the Angular analog of the Vue
-   *                plugin's `typeof window` guard).
+   * @param opts          forwarded verbatim to `SignalsAgent.load()`.
+   * @param browser       whether we're running in a browser; `load()` only fires
+   *                      client-side so SSR / prerender never touches
+   *                      window/document/WebCrypto (the Angular analog of the Vue
+   *                      plugin's `typeof window` guard).
+   * @param initiallyHeld start held (issue 2894): do not load until `release()`.
    */
-  constructor(opts, browser) {
+  constructor(opts, browser, initiallyHeld = false) {
+    this.opts = opts;
+    this.browser = browser;
+    this.heldState = signal(initiallyHeld);
+    this.held = this.heldState.asReadonly();
+    this.ready = new Promise((resolve) => {
+      this.resolveReady = resolve;
+    });
     if (!browser) {
-      this.ready = Promise.resolve();
+      this.resolveReady();
       return;
     }
-    this.ready = SignalsAgent.load(opts).then((loaded) => {
+    if (!initiallyHeld) this.release();
+  }
+  /**
+   * Leave the held state: load the agent once (a no-op if already released). What
+   * `provideSignals()` calls when its `enabled` signal becomes true.
+   */
+  release() {
+    this.heldState.set(false);
+    if (!this.browser || this.started) return;
+    this.started = true;
+    const mine = this.generation;
+    SignalsAgent.load(this.opts).then((loaded) => {
+      if (mine !== this.generation) {
+        if (!this.started) loaded.stopObservers();
+        return;
+      }
+      this.loaded = loaded;
       this.agentState.set(loaded);
+      this.settled();
     }).catch((err) => {
+      if (mine !== this.generation) return;
       this.loadErrorState.set(err instanceof Error ? err : new Error(String(err)));
+      this.settled();
     });
   }
+  /**
+   * Enter the held state. After a release this stops the SDK's interaction
+   * listeners (page-wide, for this copy of the SDK), drops the agent and discards
+   * a load still in flight; a request already sent is not recalled, and nothing
+   * already received is deleted. Before any release it only marks the client held.
+   */
+  hold() {
+    this.heldState.set(true);
+    if (!this.started) {
+      this.notify();
+      return;
+    }
+    this.started = false;
+    this.generation++;
+    this.loaded?.stopObservers();
+    this.loaded = null;
+    this.agentState.set(null);
+    this.loadErrorState.set(null);
+    this.notify();
+  }
+  /**
+   * @internal Called after every state change (a load settling, a hold). Lets
+   * `injectVisitorData()` re-run without an Angular `effect`, so the auto-identify
+   * fires exactly once per release regardless of change-detection timing.
+   */
+  onChange(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  settled() {
+    this.resolveReady();
+    this.notify();
+  }
+  notify() {
+    for (const l of [...this.listeners]) l();
+  }
 };
 
 // src/provide-signals.ts
 import { isPlatformBrowser } from "@angular/common";
 import {
   PLATFORM_ID,
+  effect,
   inject,
-  makeEnvironmentProviders
+  makeEnvironmentProviders,
+  untracked
 } from "@angular/core";
 
 // src/tokens.ts
@@ -53,17 +130,33 @@ import { InjectionToken } from "@angular/core";
 var SIGNALS_CLIENT = new InjectionToken("signap.signals.client");
 
 // src/provide-signals.ts
-function provideSignals(opts) {
+function provideSignals(opts, config = {}) {
   return makeEnvironmentProviders([
     {
       provide: SIGNALS_CLIENT,
-      useFactory: () => new SignalsClient(opts, isPlatformBrowser(inject(PLATFORM_ID)))
+      useFactory: () => {
+        const browser = isPlatformBrowser(inject(PLATFORM_ID));
+        const { enabled } = config;
+        if (!enabled) return new SignalsClient(opts, browser);
+        const client = new SignalsClient(opts, browser, !untracked(enabled));
+        effect(() => {
+          const on = enabled();
+          untracked(() => on ? client.release() : client.hold());
+        });
+        return client;
+      }
     }
   ]);
 }
 
 // src/inject-visitor-data.ts
-import { DestroyRef, assertInInjectionContext, inject as inject2, signal as signal2 } from "@angular/core";
+import {
+  DestroyRef,
+  assertInInjectionContext,
+  computed,
+  inject as inject2,
+  signal as signal2
+} from "@angular/core";
 function injectVisitorData(opts) {
   assertInInjectionContext(injectVisitorData);
   const client = inject2(SIGNALS_CLIENT, { optional: true });
@@ -74,10 +167,30 @@ function injectVisitorData(opts) {
   }
   const data = signal2(void 0);
   const error = signal2(null);
-  const isLoading = signal2(client.agent() === null && client.loadError() === null);
+  const isLoading = signal2(
+    !client.held() && client.agent() === null && client.loadError() === null
+  );
+  const isHeld = computed(() => client.held());
   let token = { cancelled: false };
+  let started = false;
+  const onChange = () => {
+    if (client.held()) {
+      token.cancelled = true;
+      started = false;
+      data.set(void 0);
+      error.set(null);
+      isLoading.set(false);
+      return;
+    }
+    if (started) return;
+    if (client.agent() === null && client.loadError() === null) return;
+    started = true;
+    void run();
+  };
+  const unsubscribe = client.onChange(onChange);
   inject2(DestroyRef).onDestroy(() => {
     token.cancelled = true;
+    unsubscribe();
   });
   const run = async () => {
     const agent = client.agent();
@@ -106,8 +219,8 @@ function injectVisitorData(opts) {
       if (!my.cancelled) isLoading.set(false);
     }
   };
-  void client.ready.then(() => run());
-  return { data, isLoading, error, refetch: run };
+  void Promise.resolve().then(onChange);
+  return { data, isLoading, isHeld, error, refetch: run };
 }
 export {
   SIGNALS_CLIENT,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/client.ts","../src/provide-signals.ts","../src/tokens.ts","../src/inject-visitor-data.ts"],"sourcesContent":["export {\n  type AgentLoadOptions,\n  type IdentifyOptions,\n  type IdentifyResult,\n  SdkError,\n  type SdkErrorCode,\n  VERSION as WEB_SDK_VERSION,\n} from \"@signap/signals-web\";\n\nexport { SignalsClient } from \"./client\";\nexport { provideSignals } from \"./provide-signals\";\nexport { SIGNALS_CLIENT } from \"./tokens\";\nexport {\n  injectVisitorData,\n  type InjectVisitorDataOptions,\n  type InjectVisitorDataResult,\n} from \"./inject-visitor-data\";\n","import { type Signal, signal } from \"@angular/core\";\nimport { type AgentLoadOptions, SignalsAgent } from \"@signap/signals-web\";\n\n/**\n * Holds a single lazily-loaded SignalsAgent and exposes its readiness as Angular\n * signals — the framework-native analog of the Vue wrapper's provide/inject refs\n * and the React wrapper's context. `agent()` is `null` until `SignalsAgent.load()`\n * settles; `loadError()` is non-null if it rejected (e.g. an invalid apiKey).\n *\n * Deliberately NOT `@Injectable`: a decorator-free class keeps this package\n * AOT-safe under a plain tsup build (no ngtsc / ng-packagr partial-Ivy metadata\n * step). It is wired into DI by the factory in `provideSignals()`.\n */\nexport class SignalsClient {\n  private readonly agentState = signal<SignalsAgent | null>(null);\n  private readonly loadErrorState = signal<Error | null>(null);\n\n  /** Resolved agent, or `null` until `SignalsAgent.load()` settles. */\n  readonly agent: Signal<SignalsAgent | null> = this.agentState.asReadonly();\n  /** Non-null if `SignalsAgent.load()` rejected. */\n  readonly loadError: Signal<Error | null> = this.loadErrorState.asReadonly();\n  /**\n   * Resolves once `load()` has settled (agent set OR loadError set). Lets\n   * `injectVisitorData()` await readiness without an Angular `effect`, so the\n   * auto-identify fires exactly once regardless of change-detection timing.\n   */\n  readonly ready: Promise<void>;\n\n  /**\n   * @param opts    forwarded verbatim to `SignalsAgent.load()`.\n   * @param browser whether we're running in a browser; `load()` only fires\n   *                client-side so SSR / prerender never touches\n   *                window/document/WebCrypto (the Angular analog of the Vue\n   *                plugin's `typeof window` guard).\n   */\n  constructor(opts: AgentLoadOptions, browser: boolean) {\n    if (!browser) {\n      this.ready = Promise.resolve();\n      return;\n    }\n    this.ready = SignalsAgent.load(opts)\n      .then((loaded) => {\n        this.agentState.set(loaded);\n      })\n      .catch((err: unknown) => {\n        this.loadErrorState.set(err instanceof Error ? err : new Error(String(err)));\n      });\n  }\n}\n","import { isPlatformBrowser } from \"@angular/common\";\nimport {\n  type EnvironmentProviders,\n  PLATFORM_ID,\n  inject,\n  makeEnvironmentProviders,\n} from \"@angular/core\";\nimport type { AgentLoadOptions } from \"@signap/signals-web\";\nimport { SignalsClient } from \"./client\";\nimport { SIGNALS_CLIENT } from \"./tokens\";\n\n/**\n * Registers a single app-wide SignalsAgent — the idiomatic standalone-Angular\n * entry point, analogous to React's `<SignalsProvider>` and Vue's\n * `app.use(SignalsPlugin)`:\n *\n * ```ts\n * bootstrapApplication(AppComponent, {\n *   providers: [\n *     provideSignals({ apiKey: \"pk_live_...\", endpoint: \"https://ingest.example\" }),\n *   ],\n * });\n * ```\n *\n * SSR-safe: the factory injects `PLATFORM_ID` and only lets the client call\n * `SignalsAgent.load()` in a browser, so a server render / prerender never loads\n * the agent.\n *\n * `opts` is snapshotted here at bootstrap; to swap apiKey/endpoint, re-bootstrap\n * (same snapshot-at-init contract as the React/Vue wrappers).\n */\nexport function provideSignals(opts: AgentLoadOptions): EnvironmentProviders {\n  return makeEnvironmentProviders([\n    {\n      provide: SIGNALS_CLIENT,\n      useFactory: () => new SignalsClient(opts, isPlatformBrowser(inject(PLATFORM_ID))),\n    },\n  ]);\n}\n","import { InjectionToken } from \"@angular/core\";\nimport type { SignalsClient } from \"./client\";\n\n/**\n * DI token the app-wide {@link SignalsClient} is registered under (by\n * `provideSignals()`) and that `injectVisitorData()` resolves. Most consumers\n * don't inject this directly — call `injectVisitorData()`. It is exported for\n * advanced use (e.g. `inject(SIGNALS_CLIENT).agent()` to read the raw agent).\n */\nexport const SIGNALS_CLIENT = new InjectionToken<SignalsClient>(\"signap.signals.client\");\n","import { DestroyRef, type Signal, assertInInjectionContext, inject, signal } from \"@angular/core\";\nimport type { IdentifyOptions, IdentifyResult } from \"@signap/signals-web\";\nimport { SIGNALS_CLIENT } from \"./tokens\";\n\nexport type InjectVisitorDataOptions = IdentifyOptions;\n\nexport interface InjectVisitorDataResult {\n  /**\n   * Resolved visitor from `agent.identify()`. Under ADR §A2 the call is a single\n   * synchronous round-trip — `visitorId`/`confidence`/`identifiedAt` arrive\n   * together, no polling. A `Signal`, so read it as `data()` (in a template or a\n   * `computed`/`effect`).\n   */\n  data: Signal<IdentifyResult | undefined>;\n  /** True between call time and the identify() resolution (or `error`). */\n  isLoading: Signal<boolean>;\n  error: Signal<Error | null>;\n  /** Re-run `agent.identify()` (e.g. from a button click). */\n  refetch: () => Promise<void>;\n}\n\n/**\n * Auto-identifies once the provider's agent is ready, then exposes the resolved\n * visitor as Angular signals — the framework-native analog of React's\n * `useVisitorData()` hook and Vue's `useVisitorData()` composable.\n *\n * Must be called in an injection context (a component/directive constructor or a\n * field initializer, or inside `runInInjectionContext`) below `provideSignals()`.\n */\nexport function injectVisitorData(opts?: InjectVisitorDataOptions): InjectVisitorDataResult {\n  assertInInjectionContext(injectVisitorData);\n\n  const client = inject(SIGNALS_CLIENT, { optional: true });\n  if (!client) {\n    throw new Error(\n      \"[@signap/signals-angular] injectVisitorData() requires provideSignals() in the application (or component) providers\",\n    );\n  }\n\n  const data = signal<IdentifyResult | undefined>(undefined);\n  const error = signal<Error | null>(null);\n  // Loading until the agent (or a load error) settles.\n  const isLoading = signal(client.agent() === null && client.loadError() === null);\n\n  // Supersede token so a slow response from a call that refetch() replaced (or a\n  // response arriving after teardown) is discarded.\n  let token = { cancelled: false };\n  inject(DestroyRef).onDestroy(() => {\n    token.cancelled = true;\n  });\n\n  const run = async (): Promise<void> => {\n    const agent = client.agent();\n    if (!agent) {\n      const loadError = client.loadError();\n      if (loadError) {\n        error.set(loadError);\n        isLoading.set(false);\n      }\n      return;\n    }\n    token.cancelled = true;\n    const my = { cancelled: false };\n    token = my;\n    isLoading.set(true);\n    error.set(null);\n    data.set(undefined);\n    try {\n      const res = await agent.identify(opts);\n      if (my.cancelled) return;\n      data.set(res);\n    } catch (err) {\n      if (my.cancelled) return;\n      error.set(err instanceof Error ? err : new Error(String(err)));\n    } finally {\n      if (!my.cancelled) isLoading.set(false);\n    }\n  };\n\n  // Auto-run exactly once, after load() settles. `ready` resolves whether load()\n  // succeeded or failed; even if it already resolved, `.then` defers to a\n  // microtask so the returned signals are wired up before the first run().\n  void client.ready.then(() => run());\n\n  return { data, isLoading, error, refetch: run };\n}\n"],"mappings":";AAAA;AAAA,EAIE;AAAA,EAEW;AAAA,OACN;;;ACPP,SAAsB,cAAc;AACpC,SAAgC,oBAAoB;AAY7C,IAAM,gBAAN,MAAoB;AAAA,EACR,aAAa,OAA4B,IAAI;AAAA,EAC7C,iBAAiB,OAAqB,IAAI;AAAA;AAAA,EAGlD,QAAqC,KAAK,WAAW,WAAW;AAAA;AAAA,EAEhE,YAAkC,KAAK,eAAe,WAAW;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMjE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAST,YAAY,MAAwB,SAAkB;AACpD,QAAI,CAAC,SAAS;AACZ,WAAK,QAAQ,QAAQ,QAAQ;AAC7B;AAAA,IACF;AACA,SAAK,QAAQ,aAAa,KAAK,IAAI,EAChC,KAAK,CAAC,WAAW;AAChB,WAAK,WAAW,IAAI,MAAM;AAAA,IAC5B,CAAC,EACA,MAAM,CAAC,QAAiB;AACvB,WAAK,eAAe,IAAI,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC,CAAC;AAAA,IAC7E,CAAC;AAAA,EACL;AACF;;;AChDA,SAAS,yBAAyB;AAClC;AAAA,EAEE;AAAA,EACA;AAAA,EACA;AAAA,OACK;;;ACNP,SAAS,sBAAsB;AASxB,IAAM,iBAAiB,IAAI,eAA8B,uBAAuB;;;ADsBhF,SAAS,eAAe,MAA8C;AAC3E,SAAO,yBAAyB;AAAA,IAC9B;AAAA,MACE,SAAS;AAAA,MACT,YAAY,MAAM,IAAI,cAAc,MAAM,kBAAkB,OAAO,WAAW,CAAC,CAAC;AAAA,IAClF;AAAA,EACF,CAAC;AACH;;;AEtCA,SAAS,YAAyB,0BAA0B,UAAAA,SAAQ,UAAAC,eAAc;AA6B3E,SAAS,kBAAkB,MAA0D;AAC1F,2BAAyB,iBAAiB;AAE1C,QAAM,SAASC,QAAO,gBAAgB,EAAE,UAAU,KAAK,CAAC;AACxD,MAAI,CAAC,QAAQ;AACX,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AAEA,QAAM,OAAOC,QAAmC,MAAS;AACzD,QAAM,QAAQA,QAAqB,IAAI;AAEvC,QAAM,YAAYA,QAAO,OAAO,MAAM,MAAM,QAAQ,OAAO,UAAU,MAAM,IAAI;AAI/E,MAAI,QAAQ,EAAE,WAAW,MAAM;AAC/B,EAAAD,QAAO,UAAU,EAAE,UAAU,MAAM;AACjC,UAAM,YAAY;AAAA,EACpB,CAAC;AAED,QAAM,MAAM,YAA2B;AACrC,UAAM,QAAQ,OAAO,MAAM;AAC3B,QAAI,CAAC,OAAO;AACV,YAAM,YAAY,OAAO,UAAU;AACnC,UAAI,WAAW;AACb,cAAM,IAAI,SAAS;AACnB,kBAAU,IAAI,KAAK;AAAA,MACrB;AACA;AAAA,IACF;AACA,UAAM,YAAY;AAClB,UAAM,KAAK,EAAE,WAAW,MAAM;AAC9B,YAAQ;AACR,cAAU,IAAI,IAAI;AAClB,UAAM,IAAI,IAAI;AACd,SAAK,IAAI,MAAS;AAClB,QAAI;AACF,YAAM,MAAM,MAAM,MAAM,SAAS,IAAI;AACrC,UAAI,GAAG,UAAW;AAClB,WAAK,IAAI,GAAG;AAAA,IACd,SAAS,KAAK;AACZ,UAAI,GAAG,UAAW;AAClB,YAAM,IAAI,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC,CAAC;AAAA,IAC/D,UAAE;AACA,UAAI,CAAC,GAAG,UAAW,WAAU,IAAI,KAAK;AAAA,IACxC;AAAA,EACF;AAKA,OAAK,OAAO,MAAM,KAAK,MAAM,IAAI,CAAC;AAElC,SAAO,EAAE,MAAM,WAAW,OAAO,SAAS,IAAI;AAChD;","names":["inject","signal","inject","signal"]}
+{"version":3,"sources":["../src/index.ts","../src/client.ts","../src/provide-signals.ts","../src/tokens.ts","../src/inject-visitor-data.ts"],"sourcesContent":["export {\n  type AgentLoadOptions,\n  type IdentifyOptions,\n  type IdentifyResult,\n  SdkError,\n  type SdkErrorCode,\n  VERSION as WEB_SDK_VERSION,\n} from \"@signap/signals-web\";\n\nexport { SignalsClient } from \"./client\";\nexport { provideSignals, type SignalsConfig } from \"./provide-signals\";\nexport { SIGNALS_CLIENT } from \"./tokens\";\nexport {\n  injectVisitorData,\n  type InjectVisitorDataOptions,\n  type InjectVisitorDataResult,\n} from \"./inject-visitor-data\";\n","import { type Signal, type WritableSignal, signal } from \"@angular/core\";\nimport { type AgentLoadOptions, SignalsAgent } from \"@signap/signals-web\";\n\n/**\n * Holds a single lazily-loaded SignalsAgent and exposes its readiness as Angular\n * signals — the framework-native analog of the Vue wrapper's provide/inject refs\n * and the React wrapper's context. `agent()` is `null` until `SignalsAgent.load()`\n * settles; `loadError()` is non-null if it rejected (e.g. an invalid apiKey).\n *\n * Deliberately NOT `@Injectable`: a decorator-free class keeps this package\n * AOT-safe under a plain tsup build (no ngtsc / ng-packagr partial-Ivy metadata\n * step). It is wired into DI by the factory in `provideSignals()`.\n */\nexport class SignalsClient {\n  private readonly agentState = signal<SignalsAgent | null>(null);\n  private readonly loadErrorState = signal<Error | null>(null);\n  private readonly heldState: WritableSignal<boolean>;\n\n  /** Resolved agent, or `null` until `SignalsAgent.load()` settles. */\n  readonly agent: Signal<SignalsAgent | null> = this.agentState.asReadonly();\n  /** Non-null if `SignalsAgent.load()` rejected. */\n  readonly loadError: Signal<Error | null> = this.loadErrorState.asReadonly();\n  /** True while held (`provideSignals(opts, { enabled })` with `enabled()` false): nothing is loaded. */\n  readonly held: Signal<boolean>;\n  /**\n   * Resolves once the FIRST `load()` has settled (agent set OR loadError set), or\n   * at once outside a browser. While the client is held before its first release,\n   * it stays pending.\n   */\n  readonly ready: Promise<void>;\n\n  private readonly opts: AgentLoadOptions;\n  private readonly browser: boolean;\n  private resolveReady: () => void = () => {};\n  private started = false;\n  private loaded: SignalsAgent | null = null;\n  // Bumped on every withdrawal; a load() that settles under an older generation is discarded.\n  private generation = 0;\n  private readonly listeners = new Set<() => void>();\n\n  /**\n   * @param opts          forwarded verbatim to `SignalsAgent.load()`.\n   * @param browser       whether we're running in a browser; `load()` only fires\n   *                      client-side so SSR / prerender never touches\n   *                      window/document/WebCrypto (the Angular analog of the Vue\n   *                      plugin's `typeof window` guard).\n   * @param initiallyHeld start held (issue 2894): do not load until `release()`.\n   */\n  constructor(opts: AgentLoadOptions, browser: boolean, initiallyHeld = false) {\n    this.opts = opts;\n    this.browser = browser;\n    this.heldState = signal(initiallyHeld);\n    this.held = this.heldState.asReadonly();\n    this.ready = new Promise<void>((resolve) => {\n      this.resolveReady = resolve;\n    });\n    if (!browser) {\n      this.resolveReady();\n      return;\n    }\n    if (!initiallyHeld) this.release();\n  }\n\n  /**\n   * Leave the held state: load the agent once (a no-op if already released). What\n   * `provideSignals()` calls when its `enabled` signal becomes true.\n   */\n  release(): void {\n    this.heldState.set(false);\n    if (!this.browser || this.started) return;\n    this.started = true;\n    const mine = this.generation;\n    SignalsAgent.load(this.opts)\n      .then((loaded) => {\n        if (mine !== this.generation) {\n          // Withdrawn while in flight. load() started the observers synchronously;\n          // stop them, unless a newer release is running them now (page-wide singletons).\n          if (!this.started) loaded.stopObservers();\n          return;\n        }\n        this.loaded = loaded;\n        this.agentState.set(loaded);\n        this.settled();\n      })\n      .catch((err: unknown) => {\n        if (mine !== this.generation) return;\n        this.loadErrorState.set(err instanceof Error ? err : new Error(String(err)));\n        this.settled();\n      });\n  }\n\n  /**\n   * Enter the held state. After a release this stops the SDK's interaction\n   * listeners (page-wide, for this copy of the SDK), drops the agent and discards\n   * a load still in flight; a request already sent is not recalled, and nothing\n   * already received is deleted. Before any release it only marks the client held.\n   */\n  hold(): void {\n    this.heldState.set(true);\n    if (!this.started) {\n      this.notify();\n      return;\n    }\n    this.started = false;\n    this.generation++;\n    this.loaded?.stopObservers();\n    this.loaded = null;\n    this.agentState.set(null);\n    this.loadErrorState.set(null);\n    this.notify();\n  }\n\n  /**\n   * @internal Called after every state change (a load settling, a hold). Lets\n   * `injectVisitorData()` re-run without an Angular `effect`, so the auto-identify\n   * fires exactly once per release regardless of change-detection timing.\n   */\n  onChange(listener: () => void): () => void {\n    this.listeners.add(listener);\n    return () => this.listeners.delete(listener);\n  }\n\n  private settled(): void {\n    this.resolveReady();\n    this.notify();\n  }\n\n  private notify(): void {\n    for (const l of [...this.listeners]) l();\n  }\n}\n","import { isPlatformBrowser } from \"@angular/common\";\nimport {\n  type EnvironmentProviders,\n  PLATFORM_ID,\n  type Signal,\n  effect,\n  inject,\n  makeEnvironmentProviders,\n  untracked,\n} from \"@angular/core\";\nimport type { AgentLoadOptions } from \"@signap/signals-web\";\nimport { SignalsClient } from \"./client\";\nimport { SIGNALS_CLIENT } from \"./tokens\";\n\n/**\n * Registers a single app-wide SignalsAgent — the idiomatic standalone-Angular\n * entry point, analogous to React's `<SignalsProvider>` and Vue's\n * `app.use(SignalsPlugin)`:\n *\n * ```ts\n * bootstrapApplication(AppComponent, {\n *   providers: [\n *     provideSignals({ apiKey: \"pk_live_...\", endpoint: \"https://ingest.example\" }),\n *   ],\n * });\n * ```\n *\n * SSR-safe: the factory injects `PLATFORM_ID` and only lets the client call\n * `SignalsAgent.load()` in a browser, so a server render / prerender never loads\n * the agent.\n *\n * `opts` is snapshotted here at bootstrap; to swap apiKey/endpoint, re-bootstrap\n * (same snapshot-at-init contract as the React/Vue wrappers).\n */\nexport function provideSignals(\n  opts: AgentLoadOptions,\n  config: SignalsConfig = {},\n): EnvironmentProviders {\n  return makeEnvironmentProviders([\n    {\n      provide: SIGNALS_CLIENT,\n      useFactory: () => {\n        const browser = isPlatformBrowser(inject(PLATFORM_ID));\n        const { enabled } = config;\n        if (!enabled) return new SignalsClient(opts, browser);\n        const client = new SignalsClient(opts, browser, !untracked(enabled));\n        // The factory runs in an injection context, so the effect lives as long as\n        // the environment injector. The client's writes are untracked so they are\n        // not writes \"inside\" the effect (Angular 17/18 reject those by default).\n        effect(() => {\n          const on = enabled();\n          untracked(() => (on ? client.release() : client.hold()));\n        });\n        return client;\n      },\n    },\n  ]);\n}\n\n/** Second argument of `provideSignals()`. */\nexport interface SignalsConfig {\n  /**\n   * While this signal is `false` the client is held: it does not load the agent, so\n   * the SDK registers no event listener, runs no collector and sends no request, and\n   * `injectVisitorData()` returns `isHeld() === true`. When it becomes `true` the\n   * agent loads and the first identify runs, as if `enabled` had never been set.\n   * When it goes back to `false` the SDK's interaction listeners stop (page-wide, for\n   * this copy of the SDK) and any identify result still in flight is discarded; a\n   * request already sent is not recalled, and nothing already received is deleted.\n   * Omitted = never held.\n   */\n  enabled?: Signal<boolean>;\n}\n","import { InjectionToken } from \"@angular/core\";\nimport type { SignalsClient } from \"./client\";\n\n/**\n * DI token the app-wide {@link SignalsClient} is registered under (by\n * `provideSignals()`) and that `injectVisitorData()` resolves. Most consumers\n * don't inject this directly — call `injectVisitorData()`. It is exported for\n * advanced use (e.g. `inject(SIGNALS_CLIENT).agent()` to read the raw agent).\n */\nexport const SIGNALS_CLIENT = new InjectionToken<SignalsClient>(\"signap.signals.client\");\n","import {\n  DestroyRef,\n  type Signal,\n  assertInInjectionContext,\n  computed,\n  inject,\n  signal,\n} from \"@angular/core\";\nimport type { IdentifyOptions, IdentifyResult } from \"@signap/signals-web\";\nimport { SIGNALS_CLIENT } from \"./tokens\";\n\nexport type InjectVisitorDataOptions = IdentifyOptions;\n\nexport interface InjectVisitorDataResult {\n  /**\n   * Resolved visitor from `agent.identify()`. Under ADR §A2 the call is a single\n   * synchronous round-trip — `visitorId`/`confidence`/`identifiedAt` arrive\n   * together, no polling. A `Signal`, so read it as `data()` (in a template or a\n   * `computed`/`effect`).\n   */\n  data: Signal<IdentifyResult | undefined>;\n  /** True between call time and the identify() resolution (or `error`). False while held. */\n  isLoading: Signal<boolean>;\n  /**\n   * True while `provideSignals(opts, { enabled })` is held. Nothing is loaded or sent,\n   * `data()` is `undefined` and `refetch()` does nothing. Always false without `enabled`.\n   */\n  isHeld: Signal<boolean>;\n  error: Signal<Error | null>;\n  /** Re-run `agent.identify()` (e.g. from a button click). */\n  refetch: () => Promise<void>;\n}\n\n/**\n * Auto-identifies once the provider's agent is ready, then exposes the resolved\n * visitor as Angular signals — the framework-native analog of React's\n * `useVisitorData()` hook and Vue's `useVisitorData()` composable.\n *\n * Must be called in an injection context (a component/directive constructor or a\n * field initializer, or inside `runInInjectionContext`) below `provideSignals()`.\n */\nexport function injectVisitorData(opts?: InjectVisitorDataOptions): InjectVisitorDataResult {\n  assertInInjectionContext(injectVisitorData);\n\n  const client = inject(SIGNALS_CLIENT, { optional: true });\n  if (!client) {\n    throw new Error(\n      \"[@signap/signals-angular] injectVisitorData() requires provideSignals() in the application (or component) providers\",\n    );\n  }\n\n  const data = signal<IdentifyResult | undefined>(undefined);\n  const error = signal<Error | null>(null);\n  // Loading until the agent (or a load error) settles — unless held.\n  const isLoading = signal(\n    !client.held() && client.agent() === null && client.loadError() === null,\n  );\n  const isHeld = computed(() => client.held());\n\n  // Supersede token so a slow response from a call that refetch() replaced (or a\n  // response arriving after teardown) is discarded.\n  let token = { cancelled: false };\n  let started = false;\n  const onChange = (): void => {\n    if (client.held()) {\n      // Held (issue 2894): discard any identify in flight and any previous result, and\n      // re-arm so a later release identifies once, like a fresh call.\n      token.cancelled = true;\n      started = false;\n      data.set(undefined);\n      error.set(null);\n      isLoading.set(false);\n      return;\n    }\n    if (started) return;\n    if (client.agent() === null && client.loadError() === null) return; // not settled yet\n    started = true;\n    void run();\n  };\n  const unsubscribe = client.onChange(onChange);\n  inject(DestroyRef).onDestroy(() => {\n    token.cancelled = true;\n    unsubscribe();\n  });\n\n  const run = async (): Promise<void> => {\n    const agent = client.agent();\n    if (!agent) {\n      const loadError = client.loadError();\n      if (loadError) {\n        error.set(loadError);\n        isLoading.set(false);\n      }\n      return;\n    }\n    token.cancelled = true;\n    const my = { cancelled: false };\n    token = my;\n    isLoading.set(true);\n    error.set(null);\n    data.set(undefined);\n    try {\n      const res = await agent.identify(opts);\n      if (my.cancelled) return;\n      data.set(res);\n    } catch (err) {\n      if (my.cancelled) return;\n      error.set(err instanceof Error ? err : new Error(String(err)));\n    } finally {\n      if (!my.cancelled) isLoading.set(false);\n    }\n  };\n\n  // Auto-run once per release, after load() settles. The client calls onChange on\n  // every settle and hold; the first look is deferred to a microtask (as the old\n  // `ready.then` was) so the returned signals are wired up before the first run().\n  void Promise.resolve().then(onChange);\n\n  return { data, isLoading, isHeld, error, refetch: run };\n}\n"],"mappings":";AAAA;AAAA,EAIE;AAAA,EAEW;AAAA,OACN;;;ACPP,SAA2C,cAAc;AACzD,SAAgC,oBAAoB;AAY7C,IAAM,gBAAN,MAAoB;AAAA,EACR,aAAa,OAA4B,IAAI;AAAA,EAC7C,iBAAiB,OAAqB,IAAI;AAAA,EAC1C;AAAA;AAAA,EAGR,QAAqC,KAAK,WAAW,WAAW;AAAA;AAAA,EAEhE,YAAkC,KAAK,eAAe,WAAW;AAAA;AAAA,EAEjE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA;AAAA,EAEQ;AAAA,EACA;AAAA,EACT,eAA2B,MAAM;AAAA,EAAC;AAAA,EAClC,UAAU;AAAA,EACV,SAA8B;AAAA;AAAA,EAE9B,aAAa;AAAA,EACJ,YAAY,oBAAI,IAAgB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUjD,YAAY,MAAwB,SAAkB,gBAAgB,OAAO;AAC3E,SAAK,OAAO;AACZ,SAAK,UAAU;AACf,SAAK,YAAY,OAAO,aAAa;AACrC,SAAK,OAAO,KAAK,UAAU,WAAW;AACtC,SAAK,QAAQ,IAAI,QAAc,CAAC,YAAY;AAC1C,WAAK,eAAe;AAAA,IACtB,CAAC;AACD,QAAI,CAAC,SAAS;AACZ,WAAK,aAAa;AAClB;AAAA,IACF;AACA,QAAI,CAAC,cAAe,MAAK,QAAQ;AAAA,EACnC;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,UAAgB;AACd,SAAK,UAAU,IAAI,KAAK;AACxB,QAAI,CAAC,KAAK,WAAW,KAAK,QAAS;AACnC,SAAK,UAAU;AACf,UAAM,OAAO,KAAK;AAClB,iBAAa,KAAK,KAAK,IAAI,EACxB,KAAK,CAAC,WAAW;AAChB,UAAI,SAAS,KAAK,YAAY;AAG5B,YAAI,CAAC,KAAK,QAAS,QAAO,cAAc;AACxC;AAAA,MACF;AACA,WAAK,SAAS;AACd,WAAK,WAAW,IAAI,MAAM;AAC1B,WAAK,QAAQ;AAAA,IACf,CAAC,EACA,MAAM,CAAC,QAAiB;AACvB,UAAI,SAAS,KAAK,WAAY;AAC9B,WAAK,eAAe,IAAI,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC,CAAC;AAC3E,WAAK,QAAQ;AAAA,IACf,CAAC;AAAA,EACL;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,OAAa;AACX,SAAK,UAAU,IAAI,IAAI;AACvB,QAAI,CAAC,KAAK,SAAS;AACjB,WAAK,OAAO;AACZ;AAAA,IACF;AACA,SAAK,UAAU;AACf,SAAK;AACL,SAAK,QAAQ,cAAc;AAC3B,SAAK,SAAS;AACd,SAAK,WAAW,IAAI,IAAI;AACxB,SAAK,eAAe,IAAI,IAAI;AAC5B,SAAK,OAAO;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,SAAS,UAAkC;AACzC,SAAK,UAAU,IAAI,QAAQ;AAC3B,WAAO,MAAM,KAAK,UAAU,OAAO,QAAQ;AAAA,EAC7C;AAAA,EAEQ,UAAgB;AACtB,SAAK,aAAa;AAClB,SAAK,OAAO;AAAA,EACd;AAAA,EAEQ,SAAe;AACrB,eAAW,KAAK,CAAC,GAAG,KAAK,SAAS,EAAG,GAAE;AAAA,EACzC;AACF;;;AClIA,SAAS,yBAAyB;AAClC;AAAA,EAEE;AAAA,EAEA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;;;ACTP,SAAS,sBAAsB;AASxB,IAAM,iBAAiB,IAAI,eAA8B,uBAAuB;;;ADyBhF,SAAS,eACd,MACA,SAAwB,CAAC,GACH;AACtB,SAAO,yBAAyB;AAAA,IAC9B;AAAA,MACE,SAAS;AAAA,MACT,YAAY,MAAM;AAChB,cAAM,UAAU,kBAAkB,OAAO,WAAW,CAAC;AACrD,cAAM,EAAE,QAAQ,IAAI;AACpB,YAAI,CAAC,QAAS,QAAO,IAAI,cAAc,MAAM,OAAO;AACpD,cAAM,SAAS,IAAI,cAAc,MAAM,SAAS,CAAC,UAAU,OAAO,CAAC;AAInE,eAAO,MAAM;AACX,gBAAM,KAAK,QAAQ;AACnB,oBAAU,MAAO,KAAK,OAAO,QAAQ,IAAI,OAAO,KAAK,CAAE;AAAA,QACzD,CAAC;AACD,eAAO;AAAA,MACT;AAAA,IACF;AAAA,EACF,CAAC;AACH;;;AEzDA;AAAA,EACE;AAAA,EAEA;AAAA,EACA;AAAA,EACA,UAAAA;AAAA,EACA,UAAAC;AAAA,OACK;AAkCA,SAAS,kBAAkB,MAA0D;AAC1F,2BAAyB,iBAAiB;AAE1C,QAAM,SAASC,QAAO,gBAAgB,EAAE,UAAU,KAAK,CAAC;AACxD,MAAI,CAAC,QAAQ;AACX,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AAEA,QAAM,OAAOC,QAAmC,MAAS;AACzD,QAAM,QAAQA,QAAqB,IAAI;AAEvC,QAAM,YAAYA;AAAA,IAChB,CAAC,OAAO,KAAK,KAAK,OAAO,MAAM,MAAM,QAAQ,OAAO,UAAU,MAAM;AAAA,EACtE;AACA,QAAM,SAAS,SAAS,MAAM,OAAO,KAAK,CAAC;AAI3C,MAAI,QAAQ,EAAE,WAAW,MAAM;AAC/B,MAAI,UAAU;AACd,QAAM,WAAW,MAAY;AAC3B,QAAI,OAAO,KAAK,GAAG;AAGjB,YAAM,YAAY;AAClB,gBAAU;AACV,WAAK,IAAI,MAAS;AAClB,YAAM,IAAI,IAAI;AACd,gBAAU,IAAI,KAAK;AACnB;AAAA,IACF;AACA,QAAI,QAAS;AACb,QAAI,OAAO,MAAM,MAAM,QAAQ,OAAO,UAAU,MAAM,KAAM;AAC5D,cAAU;AACV,SAAK,IAAI;AAAA,EACX;AACA,QAAM,cAAc,OAAO,SAAS,QAAQ;AAC5C,EAAAD,QAAO,UAAU,EAAE,UAAU,MAAM;AACjC,UAAM,YAAY;AAClB,gBAAY;AAAA,EACd,CAAC;AAED,QAAM,MAAM,YAA2B;AACrC,UAAM,QAAQ,OAAO,MAAM;AAC3B,QAAI,CAAC,OAAO;AACV,YAAM,YAAY,OAAO,UAAU;AACnC,UAAI,WAAW;AACb,cAAM,IAAI,SAAS;AACnB,kBAAU,IAAI,KAAK;AAAA,MACrB;AACA;AAAA,IACF;AACA,UAAM,YAAY;AAClB,UAAM,KAAK,EAAE,WAAW,MAAM;AAC9B,YAAQ;AACR,cAAU,IAAI,IAAI;AAClB,UAAM,IAAI,IAAI;AACd,SAAK,IAAI,MAAS;AAClB,QAAI;AACF,YAAM,MAAM,MAAM,MAAM,SAAS,IAAI;AACrC,UAAI,GAAG,UAAW;AAClB,WAAK,IAAI,GAAG;AAAA,IACd,SAAS,KAAK;AACZ,UAAI,GAAG,UAAW;AAClB,YAAM,IAAI,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC,CAAC;AAAA,IAC/D,UAAE;AACA,UAAI,CAAC,GAAG,UAAW,WAAU,IAAI,KAAK;AAAA,IACxC;AAAA,EACF;AAKA,OAAK,QAAQ,QAAQ,EAAE,KAAK,QAAQ;AAEpC,SAAO,EAAE,MAAM,WAAW,QAAQ,OAAO,SAAS,IAAI;AACxD;","names":["inject","signal","inject","signal"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signap/signals-angular",
-  "version": "2.2.0-dev.20260930000246.gd4b7f02",
+  "version": "2.2.0",
   "description": "Angular provider + inject() helper wrapper for @signap/signals-web",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -22,7 +22,7 @@
     "@angular/core": ">=17 <21"
   },
   "dependencies": {
-    "@signap/signals-web": "2.3.0-dev.20260930000246.gd4b7f02"
+    "@signap/signals-web": "^2.3.0"
   },
   "devDependencies": {
     "@angular/common": "^19.0.0",