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

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 =
@@ -102,7 +128,9 @@ jsDelivr is the default npm CDN provider. Hosts can opt into `esm.sh` with
 Provider names are open-ended: custom/internal providers can pass their own name
 when they follow the jsDelivr-compatible package-file URL layout, or pass a
 provider object when package artifacts and shared dependencies need different
-route builders.
+route builders. Under `esm` the item player's own MathJax takes the provider's
+package-file root as its asset root when the page sets none; see
+[MathJax assets](../../docs/item-player/loading-strategies.md#mathjax-assets).
 
 `dependencies` and `peerDependencies` are not used as fallback runtime contracts.
 If multiple elements request different minor or patch versions of a shared

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
@@ -383,30 +393,6 @@ declare const enUS: {
         textToSpeech: {
             name: string;
             description: string;
-            toolA11y: string;
-            title: string;
-            initializing: string;
-            initFailed: string;
-            selectText: string;
-            speed: string;
-            play: string;
-            pause: string;
-            resume: string;
-            stop: string;
-            speaking: string;
-            paused: string;
-            charactersSelected: {
-                one: string;
-                other: string;
-            };
-            rate: {
-                slow: string;
-                slower: string;
-                normal: string;
-                faster: string;
-                fast: string;
-                veryFast: string;
-            };
             /** Inline reading controls and their live-region announcements. */
             inline: {
                 controlsA11y: string;
@@ -528,6 +514,7 @@ declare const enUS: {
             resolvedTools: string;
             provenanceSummary: string;
             perToolDecisions: string;
+            policyDiagnostics: string;
             profileReadOnly: string;
         };
         /** TTS settings panel. */

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",
@@ -397,30 +407,6 @@ const enUS = {
         textToSpeech: {
             name: "Text to Speech",
             description: "Read content aloud",
-            toolA11y: "Text-to-speech tool",
-            title: "Text-to-Speech",
-            initializing: "Initializing…",
-            initFailed: "Failed to initialize text-to-speech.",
-            selectText: "Select text on the page to read it aloud.",
-            speed: "Speed:",
-            play: "Play",
-            pause: "Pause",
-            resume: "Resume",
-            stop: "Stop",
-            speaking: "Speaking…",
-            paused: "Paused",
-            charactersSelected: {
-                one: "{count} character selected",
-                other: "{count} characters selected",
-            },
-            rate: {
-                slow: "Slow",
-                slower: "Slower",
-                normal: "Normal",
-                faster: "Faster",
-                fast: "Fast",
-                veryFast: "Very Fast",
-            },
             /** Inline reading controls and their live-region announcements. */
             inline: {
                 controlsA11y: "Reading controls",
@@ -542,6 +528,7 @@ const enUS = {
             resolvedTools: "Resolved Tools (toolkit)",
             provenanceSummary: "Tool Policy Provenance Summary",
             perToolDecisions: "Per-Tool Decisions",
+            policyDiagnostics: "Policy Diagnostics",
             profileReadOnly: "PNP Profile (read-only)",
         },
         /** TTS settings panel. */

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;
@@ -315,30 +321,6 @@ declare const nlNL: {
         textToSpeech: {
             name: string;
             description: string;
-            toolA11y: string;
-            title: string;
-            initializing: string;
-            initFailed: string;
-            selectText: string;
-            speed: string;
-            play: string;
-            pause: string;
-            resume: string;
-            stop: string;
-            speaking: string;
-            paused: string;
-            charactersSelected: {
-                one: string;
-                other: string;
-            };
-            rate: {
-                slow: string;
-                slower: string;
-                normal: string;
-                faster: string;
-                fast: string;
-                veryFast: string;
-            };
             inline: {
                 controlsA11y: string;
                 playbackSpeedA11y: string;
@@ -444,6 +426,7 @@ declare const nlNL: {
             resolvedTools: string;
             provenanceSummary: string;
             perToolDecisions: string;
+            policyDiagnostics: string;
             profileReadOnly: string;
         };
         tts: {

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",
@@ -315,30 +321,6 @@ const nlNL = {
         textToSpeech: {
             name: "Voorlezen",
             description: "Inhoud laten voorlezen",
-            toolA11y: "Voorleeshulp",
-            title: "Voorlezen",
-            initializing: "Wordt gestart…",
-            initFailed: "Voorlezen kon niet worden gestart.",
-            selectText: "Selecteer tekst op de pagina om die te laten voorlezen.",
-            speed: "Snelheid:",
-            play: "Voorlezen",
-            pause: "Pauzeren",
-            resume: "Hervatten",
-            stop: "Stoppen",
-            speaking: "Aan het voorlezen…",
-            paused: "Gepauzeerd",
-            charactersSelected: {
-                one: "{count} teken geselecteerd",
-                other: "{count} tekens geselecteerd",
-            },
-            rate: {
-                slow: "Langzaam",
-                slower: "Langzamer",
-                normal: "Normaal",
-                faster: "Sneller",
-                fast: "Snel",
-                veryFast: "Zeer snel",
-            },
             inline: {
                 controlsA11y: "Voorleesknoppen",
                 playbackSpeedA11y: "Voorleessnelheid",
@@ -444,6 +426,7 @@ const nlNL = {
             resolvedTools: "Toegekende hulpmiddelen (toolkit)",
             provenanceSummary: "Overzicht van herkomst van het hulpmiddelenbeleid",
             perToolDecisions: "Beslissingen per hulpmiddel",
+            policyDiagnostics: "Diagnose van het hulpmiddelenbeleid",
             profileReadOnly: "PNP-profiel (alleen lezen)",
         },
         tts: {

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/i18n/types.d.ts

@@ -52,11 +52,10 @@ type PluralCategoryKey = keyof PluralTranslation;
  * Dot-notation keys of a catalog shape.
  *
  * A plural group terminates the path at the group itself: `plural()` is called
- * with `tools.textToSpeech.charactersSelected`, never with
- * `…charactersSelected.other`. A group is recognized by every one of its keys
- * being a CLDR plural category — the containment has to run this way round,
- * because a group carrying only `one`/`other` does not contain the whole
- * category union.
+ * with `player.formative.triesLeft`, never with `…triesLeft.other`. A group is
+ * recognized by every one of its keys being a CLDR plural category — the
+ * containment has to run this way round, because a group carrying only
+ * `one`/`other` does not contain the whole category union.
  */
 type NestedKeys<T> = {
     [K in keyof T & string]: T[K] extends string ? K : keyof T[K] extends PluralCategoryKey ? K : T[K] extends object ? K | `${K}.${NestedKeys<T[K]>}` : K;

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, ReferencedItemEntity, ReferencedPassageEntity, 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
      */