@pie-players/pie-players-shared 0.3.73 → 0.3.74

package/README.md

@@ -21,10 +21,10 @@ Supported subpaths are declared in `package.json`:
 - `@pie-players/pie-players-shared/types`
 - `@pie-players/pie-players-shared/formative`
 - `@pie-players/pie-players-shared/timed-media`
+- `@pie-players/pie-players-shared/media`
 - `@pie-players/pie-players-shared/pie`
 - `@pie-players/pie-players-shared/pie/tag-names`
 - `@pie-players/pie-players-shared/loaders`
-- `@pie-players/pie-players-shared/server/npm-registry`
 - `@pie-players/pie-players-shared/i18n`
 
 ## Formative Delivery
@@ -84,6 +84,28 @@ The contract is [`docs/prds/timed-media-section-contract.md`](../../docs/prds/ti
 including why cue gate conditions name the formative vocabulary and why an
 unenforceable policy degrades to advisory rather than failing closed.
 
+## Media Validation
+
+`@pie-players/pie-players-shared/media` validates authored, wire-facing media
+references before they reach a media element: the source-scheme allow-list
+(`isSafeMediaSrc`), source normalization with dedupe by `src`
+(`normalizeMediaSources`), fragment-range normalization, and
+unknown-`MediaAssetRef.version` rejection. `applyMediaFragment` writes a
+fragment range as a Media Fragments URI, and `enforceMediaFragment` holds a
+media element to that range because browsers honour the URI inconsistently.
+Nothing runs at import time, so an element imports it without the assessment
+toolkit; the toolkit root re-exports the same names.
+
+```ts
+import {
+  isSafeMediaSrc,
+  isUnsupportedMediaAssetVersion,
+  normalizeMediaSources,
+} from "@pie-players/pie-players-shared/media";
+```
+
+The media vocabulary it validates is [`docs/prds/shared-contracts/media-asset-contract.md`](../../docs/prds/shared-contracts/media-asset-contract.md).
+
 ## Browser ESM Element Contract
 
 The canonical producer-side contract lives with the `pie-elements-ng` package
@@ -94,6 +116,10 @@ The ESM element loader consumes static `@pie-element/*` browser entries such as
 `dist/browser/delivery/index.js`; it does not transform element packages through
 CDN `+esm` entry points. Browser ESM elements must publish exact shared runtime
 metadata in `package.json` under `pie.browserSharedDependencies`.
+Under URL resolution it loads the variant an element declares in
+`pie.browserEditorRuntime` and maps that runtime's `pie.browserModules`, one
+runtime version per page; see
+[Shared editor runtime](../../docs/item-player/loading-strategies.md#shared-editor-runtime).
 
 jsDelivr is the default npm CDN provider. Hosts can opt into `esm.sh` with
 `loaderOptions.esmCdnProvider = "esm.sh"` and `loaderOptions.esmCdnUrl =

package/dist/components/vendor/nds/README.md

@@ -66,11 +66,13 @@ TypeScript program, and is covered by the `!**/src/components/vendor` ignore in
 
 Consuming bundlers treat this module per their own externals config:
 
-- `tool-tts-inline` (Vite lib build) does **not** externalize `players-shared`,
-  so this bundle is inlined into its published output.
-- `assessment-toolkit` builds its CE artifacts with `--external=@pie-players/*`,
-  so this module stays a bare external import in those artifacts — resolved by
-  the host/loader exactly like every other `@pie-players/*` specifier the
+- `tool-tts-inline` (Vite lib build) externalizes `players-shared` and its
+  subpaths, so its published output imports
+  `@pie-players/pie-players-shared/nds-icon-button` from the host.
+- `assessment-toolkit` builds its CE artifacts with every dependency and peer
+  dependency, plus each one's subpaths, as esbuild externals, so this module
+  stays a bare external import in those artifacts — resolved by the
+  host/loader exactly like every other `@pie-players/*` specifier the
   artifacts already emit.
 
 ## How to refresh

package/dist/config/profile.d.ts

@@ -6,9 +6,7 @@
  */
 declare global {
     interface Window {
-        PIE_BUILDER_ORIGIN_URL?: string;
         PIE_BUILDER_BUNDLE_URL?: string;
     }
 }
-export declare const BUILDER_ORIGIN_URL: string;
 export declare const BUILDER_BUNDLE_URL: string;

package/dist/config/profile.js

@@ -4,10 +4,7 @@
  * In PIEOneer, these come from `$env/dynamic/public`. In `pie-players` we avoid
  * SvelteKit env dependencies so this can be consumed by any bundler.
  */
-// Default public bundle host. Keep this aligned with the IIFE loader default.
-// (We prefer the proxy endpoint, which is stable/cached for browser usage.)
-const DEFAULT_BUILDER_ORIGIN_URL = "https://proxy.pie-api.com";
-const DEFAULT_BUILDER_BUNDLE_URL = `${DEFAULT_BUILDER_ORIGIN_URL}/bundles/`;
+import { DEFAULT_BUNDLE_HOST } from "../loaders/defaults.js";
 function readPublicEnv(key) {
     try {
         // Vite/SvelteKit-like
@@ -18,9 +15,6 @@ function readPublicEnv(key) {
     catch { }
     return undefined;
 }
-export const BUILDER_ORIGIN_URL = (typeof window !== "undefined" && window.PIE_BUILDER_ORIGIN_URL) ||
-    readPublicEnv("PUBLIC_BUILDER_ORIGIN_URL") ||
-    DEFAULT_BUILDER_ORIGIN_URL;
 export const BUILDER_BUNDLE_URL = (typeof window !== "undefined" && window.PIE_BUILDER_BUNDLE_URL) ||
     readPublicEnv("PUBLIC_BUILDER_BUNDLE_URL") ||
-    DEFAULT_BUILDER_BUNDLE_URL;
+    DEFAULT_BUNDLE_HOST;

package/dist/i18n/index.d.ts

@@ -12,9 +12,8 @@
  *   its own chunk.
  * - **Tools** import `./types.js` as `import type` (fully erased) plus
  *   `getDefaultI18n` from `./provider.js` for the no-publisher default. That
- *   path never reaches `./catalogs.js`, so no locale chunk is emitted into a
- *   tool bundle — which matters because every tool `vite.config.ts` sets
- *   `external: []`.
+ *   path never reaches `./catalogs.js`, so a host that bundles tools against
+ *   its own players-shared emits no locale chunk for them.
  *
  * @module @pie-players/pie-players-shared/i18n
  */

package/dist/i18n/index.js

@@ -12,9 +12,8 @@
  *   its own chunk.
  * - **Tools** import `./types.js` as `import type` (fully erased) plus
  *   `getDefaultI18n` from `./provider.js` for the no-publisher default. That
- *   path never reaches `./catalogs.js`, so no locale chunk is emitted into a
- *   tool bundle — which matters because every tool `vite.config.ts` sets
- *   `external: []`.
+ *   path never reaches `./catalogs.js`, so a host that bundles tools against
+ *   its own players-shared emits no locale chunk for them.
  *
  * @module @pie-players/pie-players-shared/i18n
  */

package/dist/i18n/messages/en-US.d.ts

@@ -73,6 +73,7 @@ declare const enUS: {
         items: string;
         section: string;
         loadingSection: string;
+        sectionLoadError: string;
         loadingPassage: string;
         configurationError: string;
         playerError: string;
@@ -163,6 +164,15 @@ declare const enUS: {
             centerA11y: string;
             closeA11y: string;
         };
+        /**
+         * The tap controls that move and turn the ruler and protractor without a
+         * drag. The move buttons reuse the `window` labels above.
+         */
+        placement: {
+            controlsA11y: string;
+            rotateClockwiseA11y: string;
+            rotateCounterclockwiseA11y: string;
+        };
         /**
          * Live-region announcements shared by the draggable tools — ruler,
          * protractor, line reader. Keyboard movement and rotation read the same in

package/dist/i18n/messages/en-US.js

@@ -73,6 +73,7 @@ const enUS = {
         items: "Items",
         section: "Section",
         loadingSection: "Loading section content…",
+        sectionLoadError: "Section content could not be loaded.",
         loadingPassage: "Loading passage content…",
         configurationError: "Configuration Error",
         playerError: "Player Error",
@@ -163,6 +164,15 @@ const enUS = {
             centerA11y: "Center tool window",
             closeA11y: "Close tool",
         },
+        /**
+         * The tap controls that move and turn the ruler and protractor without a
+         * drag. The move buttons reuse the `window` labels above.
+         */
+        placement: {
+            controlsA11y: "Move and rotate",
+            rotateClockwiseA11y: "Rotate {degrees}° clockwise",
+            rotateCounterclockwiseA11y: "Rotate {degrees}° counterclockwise",
+        },
         /**
          * Live-region announcements shared by the draggable tools — ruler,
          * protractor, line reader. Keyboard movement and rotation read the same in
@@ -207,8 +217,8 @@ const enUS = {
         },
         graph: {
             name: "Graph",
-            description: "Graphing calculator and coordinate plane",
-            buttonA11y: "Graph, graphing calculator",
+            description: "Coordinate plane",
+            buttonA11y: "Graph, coordinate plane",
             tooltip: "Graph",
             toolA11y: "Graph tool — draw points and lines on a coordinate grid",
             canvasA11y: "Graph canvas — use tools to add points and draw lines",

package/dist/i18n/messages/nl-NL.d.ts

@@ -58,6 +58,7 @@ declare const nlNL: {
         items: string;
         section: string;
         loadingSection: string;
+        sectionLoadError: string;
         loadingPassage: string;
         configurationError: string;
         playerError: string;
@@ -123,6 +124,11 @@ declare const nlNL: {
             centerA11y: string;
             closeA11y: string;
         };
+        placement: {
+            controlsA11y: string;
+            rotateClockwiseA11y: string;
+            rotateCounterclockwiseA11y: string;
+        };
         announce: {
             movedUp: string;
             movedDown: string;

package/dist/i18n/messages/nl-NL.js

@@ -58,6 +58,7 @@ const nlNL = {
         items: "Vragen",
         section: "Onderdeel",
         loadingSection: "Onderdeel wordt geladen…",
+        sectionLoadError: "Het onderdeel kon niet worden geladen.",
         loadingPassage: "Tekst wordt geladen…",
         configurationError: "Configuratiefout",
         playerError: "Fout in de speler",
@@ -123,6 +124,11 @@ const nlNL = {
             centerA11y: "Venster centreren",
             closeA11y: "Hulpmiddel sluiten",
         },
+        placement: {
+            controlsA11y: "Verplaatsen en draaien",
+            rotateClockwiseA11y: "{degrees}° rechtsom draaien",
+            rotateCounterclockwiseA11y: "{degrees}° linksom draaien",
+        },
         announce: {
             movedUp: "Omhoog verplaatst naar {position}",
             movedDown: "Omlaag verplaatst naar {position}",
@@ -150,8 +156,8 @@ const nlNL = {
         },
         graph: {
             name: "Grafiek",
-            description: "Grafische rekenmachine en assenstelsel",
-            buttonA11y: "Grafiek, grafische rekenmachine",
+            description: "Assenstelsel",
+            buttonA11y: "Grafiek, assenstelsel",
             tooltip: "Grafiek",
             toolA11y: "Grafiekhulpmiddel — punten en lijnen tekenen in een assenstelsel",
             canvasA11y: "Tekenvlak — gebruik de hulpmiddelen om punten toe te voegen en lijnen te tekenen",

package/dist/i18n/provider.d.ts

@@ -2,11 +2,10 @@
  * The bundled i18n provider.
  *
  * Deliberately imports only the English catalog. The dynamic loader map for every
- * other locale lives in `./catalogs.js`, which players import and tools do not:
- * every player and tool `vite.config.ts` sets `external: []`, so anything
- * reachable from a tool's entry inlines into that tool's bundle. Keeping the
- * loader map out of this module is what stops a locale chunk from being emitted
- * into eighteen tool bundles that will never call `setLocale`.
+ * other locale lives in `./catalogs.js`, which players import and tools do not.
+ * Tools resolve players-shared from the host's node_modules, so keeping the
+ * loader map out of this module keeps locale chunks out of a host bundle that
+ * reaches players-shared only through tools.
  *
  * @module @pie-players/pie-players-shared/i18n/provider
  */

package/dist/i18n/provider.js

@@ -2,11 +2,10 @@
  * The bundled i18n provider.
  *
  * Deliberately imports only the English catalog. The dynamic loader map for every
- * other locale lives in `./catalogs.js`, which players import and tools do not:
- * every player and tool `vite.config.ts` sets `external: []`, so anything
- * reachable from a tool's entry inlines into that tool's bundle. Keeping the
- * loader map out of this module is what stops a locale chunk from being emitted
- * into eighteen tool bundles that will never call `setLocale`.
+ * other locale lives in `./catalogs.js`, which players import and tools do not.
+ * Tools resolve players-shared from the host's node_modules, so keeping the
+ * loader map out of this module keeps locale chunks out of a host bundle that
+ * reaches players-shared only through tools.
  *
  * @module @pie-players/pie-players-shared/i18n/provider
  */

package/dist/index.d.ts

@@ -6,14 +6,16 @@ export * from "./security/index.js";
 export * from "./loaders/index.js";
 export * from "./object/index.js";
 export * from "./pie/index.js";
-export type { AssessmentEntity, AssessmentItemRef, AssessmentSection, AdvancedItemConfig, ConfigEntity, ConfigResource, Env, FormativeDeliveryPolicy, FormativeItemPolicy, TimedMediaSectionData, ItemConfig, ItemEntity, ItemSession, OutcomeResponse, PassageEntity, PieController, PieContent, PieDefaultModel, PieItemElement, PieModel, QuestionEntity, RubricBlock, TestPart, } from "./types/index.js";
+export type { AssessmentEntity, AssessmentItemRef, AssessmentSection, AdvancedItemConfig, ConfigEntity, ConfigResource, Env, FormativeDeliveryPolicy, FormativeItemPolicy, TimedMediaSectionData, ItemConfig, ItemEntity, ItemSession, OutcomeResponse, PassageEntity, PieController, PieContent, PieDefaultModel, PieItemElement, PieModel, PieUpdateSession, RubricBlock, TestPart, } from "./types/index.js";
 export { editorPostFix } from "./types/index.js";
 export * from "./ui/attribute-coercion.js";
 export * from "./ui/content-styles.js";
 export * from "./ui/pointer-drag.js";
+export * from "./ui/pointer-gesture.js";
+export * from "./ui/pointer-rotate.js";
 export * from "./ui/overlay-containment.js";
+export * from "./ui/overlay-placement.js";
 export * from "./ui/focus-trap.js";
 export * from "./ui/first-focusable.js";
-export * from "./ui/debug-panel-persistence.js";
 export * from "./ui/safe-storage.js";
 export * from "./ui/scope-css.js";

package/dist/index.js

@@ -11,9 +11,11 @@ export { editorPostFix } from "./types/index.js";
 export * from "./ui/attribute-coercion.js";
 export * from "./ui/content-styles.js";
 export * from "./ui/pointer-drag.js";
+export * from "./ui/pointer-gesture.js";
+export * from "./ui/pointer-rotate.js";
 export * from "./ui/overlay-containment.js";
+export * from "./ui/overlay-placement.js";
 export * from "./ui/focus-trap.js";
 export * from "./ui/first-focusable.js";
-export * from "./ui/debug-panel-persistence.js";
 export * from "./ui/safe-storage.js";
 export * from "./ui/scope-css.js";

package/dist/instrumentation/index.d.ts

@@ -3,6 +3,7 @@
  *
  * Provides pluggable instrumentation for PIE players.
  * Supports multiple providers (New Relic, console logging, custom, etc.)
+ * Players take the provider as `loaderConfig.instrumentationProvider`.
  *
  * @example Using New Relic (default)
  * ```typescript
@@ -11,10 +12,10 @@
  * const provider = new NewRelicInstrumentationProvider();
  * await provider.initialize();
  *
- * const monitor = new ResourceMonitor({
+ * const loaderConfig = {
  *   trackPageActions: true,
  *   instrumentationProvider: provider
- * });
+ * };
  * ```
  * @example Using console logger for development
  * ```typescript
@@ -23,10 +24,10 @@
  * const provider = new ConsoleInstrumentationProvider();
  * await provider.initialize({ debug: true });
  *
- * const monitor = new ResourceMonitor({
+ * const loaderConfig = {
  *   trackPageActions: true,
  *   instrumentationProvider: provider
- * });
+ * };
  * ```
  */
 export * from "./providers/index.js";

package/dist/instrumentation/index.js

@@ -3,6 +3,7 @@
  *
  * Provides pluggable instrumentation for PIE players.
  * Supports multiple providers (New Relic, console logging, custom, etc.)
+ * Players take the provider as `loaderConfig.instrumentationProvider`.
  *
  * @example Using New Relic (default)
  * ```typescript
@@ -11,10 +12,10 @@
  * const provider = new NewRelicInstrumentationProvider();
  * await provider.initialize();
  *
- * const monitor = new ResourceMonitor({
+ * const loaderConfig = {
  *   trackPageActions: true,
  *   instrumentationProvider: provider
- * });
+ * };
  * ```
  * @example Using console logger for development
  * ```typescript
@@ -23,10 +24,10 @@
  * const provider = new ConsoleInstrumentationProvider();
  * await provider.initialize({ debug: true });
  *
- * const monitor = new ResourceMonitor({
+ * const loaderConfig = {
  *   trackPageActions: true,
  *   instrumentationProvider: provider
- * });
+ * };
  * ```
  */
 // Providers

package/dist/instrumentation/new-relic-agent.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The New Relic browser agent's API, as far as PIE calls it. A local
+ * structural type, so no vendor package reaches the published declarations.
+ */
+export type NewRelicAgent = {
+    noticeError(error: Error, attributes?: Record<string, unknown>): void;
+    addPageAction(name: string, attributes?: Record<string, unknown>): void;
+    setUserId?(userId: string): void;
+    setCustomAttribute?(name: string, value: unknown): void;
+};
+/**
+ * Returns the New Relic browser agent's API if it is on the page now.
+ *
+ * `window.NREUM` is the agent's primary global and `window.newrelic` an alias
+ * the loader assigns onto the same object, but the install snippet creates
+ * `NREUM` as a configuration container before any agent code runs, so the probe
+ * tests the callable shape over both names. Nothing is cached: an agent that
+ * loads later is found on the next call.
+ */
+export declare function probeNewRelicAgent(): NewRelicAgent | undefined;

package/dist/instrumentation/new-relic-agent.js

@@ -0,0 +1,24 @@
+function hasAgentApi(handle) {
+    const candidate = handle;
+    return (typeof candidate?.noticeError === "function" &&
+        typeof candidate.addPageAction === "function");
+}
+/**
+ * Returns the New Relic browser agent's API if it is on the page now.
+ *
+ * `window.NREUM` is the agent's primary global and `window.newrelic` an alias
+ * the loader assigns onto the same object, but the install snippet creates
+ * `NREUM` as a configuration container before any agent code runs, so the probe
+ * tests the callable shape over both names. Nothing is cached: an agent that
+ * loads later is found on the next call.
+ */
+export function probeNewRelicAgent() {
+    if (typeof window === "undefined")
+        return undefined;
+    const { newrelic, NREUM } = window;
+    if (hasAgentApi(newrelic))
+        return newrelic;
+    if (hasAgentApi(NREUM))
+        return NREUM;
+    return undefined;
+}

package/dist/instrumentation/providers/BaseInstrumentationProvider.d.ts

@@ -27,8 +27,8 @@ export declare abstract class BaseInstrumentationProvider implements Instrumenta
     /**
      * Initialize the provider with configuration
      *
-     * Concrete providers should override this method to perform provider-specific
-     * initialization (e.g., loading SDK, checking global objects, etc.)
+     * Concrete providers store their configuration here and set `initialized`.
+     * Whether the backend is available belongs in `isReady()`.
      *
      * @param config Optional configuration
      */
@@ -36,8 +36,9 @@ export declare abstract class BaseInstrumentationProvider implements Instrumenta
     /**
      * Check if provider is ready to track events
      *
-     * Concrete providers should override this method to check provider-specific
-     * readiness (e.g., SDK loaded, global object available, etc.)
+     * Concrete providers conjoin `initialized` with a check of their backend
+     * made on every call (e.g., the agent's global is on the page now), so a
+     * backend that arrives after `initialize()` is picked up.
      *
      * @returns true if provider is ready
      */

package/dist/instrumentation/providers/NewRelicInstrumentationProvider.d.ts

@@ -3,8 +3,9 @@
  *
  * Default provider for existing New Relic Browser Agent instrumentation.
  *
- * This provider wraps the global `window.newrelic` object provided by
- * the New Relic Browser Agent.
+ * Sends through the New Relic Browser Agent's API on `window.newrelic` or
+ * `window.NREUM`, looked up on every call, so an agent that loads after
+ * `initialize()` receives everything tracked from then on.
  *
  * @example
  * ```typescript
@@ -27,8 +28,8 @@ export declare class NewRelicInstrumentationProvider extends BaseInstrumentation
     /**
      * Initialize the New Relic provider
      *
-     * Checks if the New Relic Browser Agent is available via `window.newrelic`.
-     * If not available, initialization succeeds but `isReady()` will return false.
+     * Configures the provider. The agent does not have to be on the page yet:
+     * `isReady()` turns true when it arrives.
      *
      * @param config Optional configuration
      */
@@ -36,14 +37,13 @@ export declare class NewRelicInstrumentationProvider extends BaseInstrumentation
     /**
      * Check if provider is ready
      *
-     * @returns true if New Relic is available and initialized
+     * @returns true once initialized, while the New Relic agent's API is on the page
      */
     isReady(): boolean;
     /**
      * Cleanup provider resources
      *
-     * Marks provider as uninitialized. The global `window.newrelic` object
-     * is not modified.
+     * Marks provider as uninitialized. The agent's globals are not modified.
      */
     destroy(): void;
     /**

package/dist/instrumentation/providers/NewRelicInstrumentationProvider.js

@@ -3,8 +3,9 @@
  *
  * Default provider for existing New Relic Browser Agent instrumentation.
  *
- * This provider wraps the global `window.newrelic` object provided by
- * the New Relic Browser Agent.
+ * Sends through the New Relic Browser Agent's API on `window.newrelic` or
+ * `window.NREUM`, looked up on every call, so an agent that loads after
+ * `initialize()` receives everything tracked from then on.
  *
  * @example
  * ```typescript
@@ -19,6 +20,7 @@
  * }
  * ```
  */
+import { probeNewRelicAgent } from "../new-relic-agent.js";
 import { BaseInstrumentationProvider } from "./BaseInstrumentationProvider.js";
 export class NewRelicInstrumentationProvider extends BaseInstrumentationProvider {
     providerId = "newrelic";
@@ -26,43 +28,32 @@ export class NewRelicInstrumentationProvider extends BaseInstrumentationProvider
     /**
      * Initialize the New Relic provider
      *
-     * Checks if the New Relic Browser Agent is available via `window.newrelic`.
-     * If not available, initialization succeeds but `isReady()` will return false.
+     * Configures the provider. The agent does not have to be on the page yet:
+     * `isReady()` turns true when it arrives.
      *
      * @param config Optional configuration
      */
     async initialize(config) {
         this.config = config;
-        // Check if New Relic is available
-        if (typeof window !== "undefined" && window.newrelic) {
-            this.initialized = true;
-            if (this.config?.debug) {
-                console.log("[NewRelicProvider] Initialized successfully");
-            }
-        }
-        else {
-            if (this.config?.debug) {
-                console.warn("[NewRelicProvider] New Relic not available (window.newrelic not found)");
-            }
-            // Don't throw - allow graceful degradation
-            this.initialized = false;
+        this.initialized = true;
+        if (this.config?.debug) {
+            console.log(probeNewRelicAgent()
+                ? "[NewRelicProvider] Initialized successfully"
+                : "[NewRelicProvider] Initialized; sends once the New Relic agent is on the page");
         }
     }
     /**
      * Check if provider is ready
      *
-     * @returns true if New Relic is available and initialized
+     * @returns true once initialized, while the New Relic agent's API is on the page
      */
     isReady() {
-        return (this.initialized &&
-            typeof window !== "undefined" &&
-            !!window.newrelic);
+        return this.initialized && probeNewRelicAgent() !== undefined;
     }
     /**
      * Cleanup provider resources
      *
-     * Marks provider as uninitialized. The global `window.newrelic` object
-     * is not modified.
+     * Marks provider as uninitialized. The agent's globals are not modified.
      */
     destroy() {
         this.initialized = false;
@@ -79,8 +70,7 @@ export class NewRelicInstrumentationProvider extends BaseInstrumentationProvider
      * @param attributes Transformed attributes (already filtered and transformed by base class)
      */
     doTrackError(error, attributes) {
-        const newrelic = window.newrelic;
-        newrelic.noticeError(error, attributes);
+        probeNewRelicAgent()?.noticeError(error, attributes);
     }
     /**
      * Track a custom event/page action with New Relic
@@ -91,8 +81,7 @@ export class NewRelicInstrumentationProvider extends BaseInstrumentationProvider
      * @param attributes Transformed attributes (already filtered and transformed by base class)
      */
     doTrackEvent(eventName, attributes) {
-        const newrelic = window.newrelic;
-        newrelic.addPageAction(eventName, attributes);
+        probeNewRelicAgent()?.addPageAction(eventName, attributes);
     }
     /**
      * Set user context for session tracking
@@ -103,13 +92,13 @@ export class NewRelicInstrumentationProvider extends BaseInstrumentationProvider
      * @param attributes Optional user attributes
      */
     doSetUserContext(userId, attributes) {
-        const newrelic = window.newrelic;
+        const newrelic = probeNewRelicAgent();
         // Set user ID if method exists
-        if (newrelic.setUserId) {
+        if (typeof newrelic?.setUserId === "function") {
             newrelic.setUserId(userId);
         }
         // Set custom attributes for user
-        if (attributes && newrelic.setCustomAttribute) {
+        if (attributes && typeof newrelic?.setCustomAttribute === "function") {
             for (const [key, value] of Object.entries(attributes)) {
                 newrelic.setCustomAttribute(key, value);
             }
@@ -123,8 +112,8 @@ export class NewRelicInstrumentationProvider extends BaseInstrumentationProvider
      * @param attributes Attributes to set globally
      */
     doSetGlobalAttributes(attributes) {
-        const newrelic = window.newrelic;
-        if (newrelic.setCustomAttribute) {
+        const newrelic = probeNewRelicAgent();
+        if (typeof newrelic?.setCustomAttribute === "function") {
             for (const [key, value] of Object.entries(attributes)) {
                 newrelic.setCustomAttribute(key, value);
             }

package/dist/instrumentation/types.d.ts

@@ -49,7 +49,8 @@ export interface InstrumentationProvider {
      */
     readonly providerName: string;
     /**
-     * Initialize the provider (load SDKs, configure clients, etc.)
+     * Configure the provider. Its backend does not have to be available yet:
+     * `isReady()` answers that.
      *
      * @param config Optional configuration for the provider
      */
@@ -105,7 +106,10 @@ export interface InstrumentationProvider {
     /**
      * Check if provider is ready to track events
      *
-     * @returns true if provider is initialized and ready, false otherwise
+     * Evaluated on every call, so a backend that becomes available after
+     * `initialize()` makes the provider ready without another call.
+     *
+     * @returns true if provider is initialized and its backend is available now
      */
     isReady(): boolean;
 }
@@ -195,7 +199,7 @@ export interface ErrorAttributes {
     /**
      * Component that generated the error
      *
-     * Examples: 'pie-item-player', 'pie-resource-monitor'
+     * Examples: 'pie-item-player', 'resource-monitor'
      */
     component: string;
     /**