@sanseng/liveavatar-js-sdk-skywalking 1.0.0 → 1.0.1

package/README.md

@@ -4,8 +4,9 @@
 
 ## What it solves
 
-- Reports LiveAvatar A/V Sync alert lifecycles with compact, causally ordered diagnostic evidence for investigation in SkyWalking.
+- Reports SDK-generated LiveAvatar A/V Sync alert lifecycles with compact, causally ordered diagnostic evidence for investigation in SkyWalking.
 - Reports qualifying SDK Operational Log errors without uploading the original error message, stack, token, or business payload.
+- Reports every terminal `performance.first-frame` Operational Log, including success, connection failure, and first-frame timeout.
 - Adds observability through the public LiveAvatar Plugin API v1, without subscribing to legacy SDK events or using SDK internals.
 - Bundles and registers a browser SkyWalking client when one has not already been supplied by the application.
 
@@ -19,24 +20,40 @@ npm install @sanseng/liveavatar-js-sdk @sanseng/liveavatar-js-sdk-skywalking
 import { createClient } from "@sanseng/liveavatar-js-sdk";
 import { createSkyWalkingPlugin } from "@sanseng/liveavatar-js-sdk-skywalking";
 
+const client = createClient({
+  plugins: [createSkyWalkingPlugin()],
+  connectConfig: {
+    // Your normal LiveAvatar connection configuration.
+  },
+});
+```
+
+The plugin registers SkyWalking during client setup. SDK errors, terminal first-frame logs, and SDK-generated A/V Sync alerts are all reported by default. Its service is always `yy-tx::liveavatar-js-sdk`; it cannot be configured. If `window.ClientMonitor` already exists, the plugin treats it as externally registered and never overwrites or registers it. The bundled client registers only once per page; later differing configurations are ignored with a console warning.
+
+Enable SDK A/V Sync diagnostics only when automatic A/V Sync alerts and their evidence are needed. When it is disabled, the SDK produces no automatic A/V Sync alerts, so the plugin does not query A/V telemetry or send A/V logs:
+
+```ts
 const client = createClient({
   debug: { avSync: { enabled: true } },
-  plugins: [
-    createSkyWalkingPlugin({
-      isOverseas: false,
-      serviceVersion: "web_1.0.0",
-      jsErrors: true,
-      apiErrors: true,
-      resourceErrors: true,
-      autoTracePerf: true,
-    }),
-  ],
+  plugins: [createSkyWalkingPlugin()],
   connectConfig: {
     // Your normal LiveAvatar connection configuration.
   },
 });
 ```
 
-The plugin registers SkyWalking during client setup. Its service is always `yy-tx::liveavatar-js-sdk`; it cannot be configured. If `window.ClientMonitor` already exists, the plugin treats it as externally registered and never overwrites or registers it. The bundled client registers only once per page; later differing configurations are ignored with a console warning.
+## Reporting controls
+
+Use `reporting` to disable individual automatic report types; every type defaults to `true`:
+
+```ts
+createSkyWalkingPlugin({
+  reporting: { sdkError: true, firstFrame: false, avSync: true },
+});
+```
+
+When all three report types are `false`, the plugin does not initialize SkyWalking or subscribe to SDK extension points.
+
+Each SDK `performance.first-frame` Operational Log produces one SkyWalking structured log through `reportFrameErrors` with a one-millisecond dispatch timeout. “First frame” means the SDK-owned private video element reached `loadeddata`; it does not claim that pixels have already appeared in the application's visible UI. See the [API reference](docs/api.en.md#first-frame-log) for outcomes, payload fields, and omission rules.
 
-The package requires `@sanseng/liveavatar-js-sdk` `^2.2.0`.
+The package requires `@sanseng/liveavatar-js-sdk` `^2.4.0`.

package/dist/index.cjs.js

@@ -46,28 +46,34 @@ class SkyWalkingPlugin {
         this.apiVersion = 1;
         this._nextInstallationGeneration = 0;
         this._skyWalkingConfig = { ...config };
+        this._reporting = normalizeReportingConfig(config.reporting);
     }
     setup(registrar) {
         this._deactivateInstallation();
+        if (!hasEnabledReporting(this._reporting))
+            return;
         registerSkyWalking(this._skyWalkingConfig);
-        const diagnostics = registrar.consume(liveavatarJsSdk.SDK_AVSYNC_DIAGNOSTICS_V1);
         const installation = {
             generation: ++this._nextInstallationGeneration,
-            diagnostics,
             abortController: new AbortController(),
             alertReportStates: new Map(),
             active: true,
         };
         this._installation = installation;
         try {
-            registrar.observe(liveavatarJsSdk.SDK_AVSYNC_ALERTS_V1, {
-                id: AVSYNC_ALERTS_CONTRIBUTION_ID,
-                handler: (alert, context) => this._handleAlertNotification(installation, alert, context.signal),
-            });
-            registrar.observe(liveavatarJsSdk.SDK_OPERATIONAL_LOGS_V1, {
-                id: OPERATIONAL_LOGS_CONTRIBUTION_ID,
-                handler: (record, context) => this._handleOperationalLog(installation, record, context.signal),
-            });
+            if (this._reporting.avSync) {
+                installation.diagnostics = registrar.consume(liveavatarJsSdk.SDK_AVSYNC_DIAGNOSTICS_V1);
+                registrar.observe(liveavatarJsSdk.SDK_AVSYNC_ALERTS_V1, {
+                    id: AVSYNC_ALERTS_CONTRIBUTION_ID,
+                    handler: (alert, context) => this._handleAlertNotification(installation, alert, context.signal),
+                });
+            }
+            if (this._reporting.sdkError || this._reporting.firstFrame) {
+                registrar.observe(liveavatarJsSdk.SDK_OPERATIONAL_LOGS_V1, {
+                    id: OPERATIONAL_LOGS_CONTRIBUTION_ID,
+                    handler: (record, context) => this._handleOperationalLog(installation, record, context.signal),
+                });
+            }
         }
         catch (error) {
             this._deactivateInstallation();
@@ -116,12 +122,19 @@ class SkyWalkingPlugin {
         }
     }
     _handleOperationalLog(installation, record, signal) {
-        if (!this._isInvocationActive(installation, signal) ||
-            record.level !== "error" ||
-            record.event !== "sdk.error") {
+        if (!this._isInvocationActive(installation, signal))
             return Promise.resolve();
+        if (this._reporting.sdkError &&
+            record.level === "error" &&
+            record.event === "sdk.error") {
+            return this._runObserverTask(installation, signal, "SDK error log", () => this._reportSdkError(installation, record, signal));
         }
-        return this._runObserverTask(installation, signal, "SDK error log", () => this._reportSdkError(installation, record, signal));
+        if (this._reporting.firstFrame &&
+            record.category === "media" &&
+            record.event === "performance.first-frame") {
+            return this._runObserverTask(installation, signal, "first-frame log", () => this._reportFirstFrameLog(installation, record, signal));
+        }
+        return Promise.resolve();
     }
     _enqueue(state, task) {
         const queued = state.tail.then(task, task);
@@ -132,6 +145,9 @@ class SkyWalkingPlugin {
         const isActive = () => this._isInvocationActive(installation, signal);
         if (!isActive())
             return;
+        const diagnostics = installation.diagnostics;
+        if (diagnostics === undefined)
+            return;
         const clientMonitor = getClientMonitor();
         if (clientMonitor === undefined) {
             this._warnInvocation(installation, signal, "ClientMonitor.reportFrameErrors is unavailable", {
@@ -144,7 +160,7 @@ class SkyWalkingPlugin {
         const query = await createEvidenceQuery(alert.phase, state.lastSuccessfulToWallClockMs, [signal, installation.abortController.signal]);
         if (!isActive() || query === undefined)
             return;
-        const collection = await collectTelemetry(installation.diagnostics, alert, retrievedAtWallClockMs, query, isActive, (message, error) => this._warnInvocationFailure(installation, signal, message, error, {
+        const collection = await collectTelemetry(diagnostics, alert, retrievedAtWallClockMs, query, isActive, (message, error) => this._warnInvocationFailure(installation, signal, message, error, {
             alert: toJsonSafeAlert(alert),
         }));
         if (!isActive() || collection === undefined)
@@ -272,6 +288,43 @@ class SkyWalkingPlugin {
         if (!this._isInvocationActive(installation, signal))
             return;
     }
+    async _reportFirstFrameLog(installation, record, signal) {
+        if (!this._isInvocationActive(installation, signal))
+            return;
+        const payload = toSkyWalkingFirstFrameLogPayload(record);
+        if (payload === undefined) {
+            this._warnInvocation(installation, signal, "Skipped invalid first-frame Operational Log", { eventId: record.eventId });
+            return;
+        }
+        const clientMonitor = getClientMonitor();
+        if (clientMonitor === undefined) {
+            this._warnInvocation(installation, signal, "ClientMonitor.reportFrameErrors is unavailable", {
+                pluginId: this.id,
+                attemptId: payload.attemptId,
+                outcome: payload.outcome,
+            });
+            return;
+        }
+        if (!this._isInvocationActive(installation, signal))
+            return;
+        try {
+            await Promise.resolve(clientMonitor.reportFrameErrors({
+                category: "media",
+                grade: payload.outcome === "first-frame" ? "Info" : "Warning",
+                content: payload,
+                // The bundled client batches error records. Its public timeout
+                // option bypasses the default delay for these terminal events.
+                timeout: 1,
+            }, {
+                name: "",
+                message: `[LiveAvatar first-frame] ${payload.outcome}`,
+                stack: "",
+            }));
+        }
+        catch (error) {
+            this._warnInvocationFailure(installation, signal, "Failed to report first-frame Operational Log to SkyWalking", error, { attemptId: payload.attemptId, outcome: payload.outcome });
+        }
+    }
     _deactivateInstallation() {
         const installation = this._installation;
         if (installation === undefined)
@@ -1231,6 +1284,60 @@ function toJsonSafeAlert(alert) {
         features: { ...alert.features },
     };
 }
+/**
+ * Strictly projects the published first-frame Operational Log. The SDK record
+ * has additional identifiers and arbitrary attributes; none of those can
+ * reach SkyWalking through this path.
+ */
+function toSkyWalkingFirstFrameLogPayload(record) {
+    const correlation = toRecord(record.correlation);
+    const attributes = toRecord(record.attributes);
+    const attemptId = correlation.attemptId;
+    const outcome = attributes.outcome;
+    if (!isNonNegativeNumber(record.occurredAtMs) ||
+        !isPositiveInteger(attemptId) ||
+        !isFirstFrameOutcome(outcome)) {
+        return undefined;
+    }
+    const sourceNodes = toRecord(attributes.nodes);
+    const nodes = {};
+    copyNonNegativeNumber(sourceNodes, "configReadyMs", nodes);
+    copyNonNegativeNumber(sourceNodes, "rtcConnectedMs", nodes);
+    copyNonNegativeNumber(sourceNodes, "videoTrackAddedMs", nodes);
+    copyNonNegativeNumber(sourceNodes, "videoMetadataMs", nodes);
+    copyNonNegativeNumber(sourceNodes, "firstFrameMs", nodes);
+    return {
+        schemaVersion: 1,
+        kind: "liveavatar.performance.first-frame",
+        sdkVersion: liveavatarJsSdk.VERSION,
+        occurredAtMs: record.occurredAtMs,
+        attemptId,
+        outcome,
+        ...(typeof attributes.renderMode === "string"
+            ? { renderMode: attributes.renderMode }
+            : {}),
+        ...(isNonNegativeNumber(attributes.timeoutAfterRtcMs)
+            ? { timeoutAfterRtcMs: attributes.timeoutAfterRtcMs }
+            : {}),
+        nodes,
+    };
+}
+function copyNonNegativeNumber(source, key, target) {
+    const value = source[key];
+    if (isNonNegativeNumber(value))
+        target[key] = value;
+}
+function isFirstFrameOutcome(value) {
+    return (value === "first-frame" ||
+        value === "connect-failed" ||
+        value === "first-frame-timeout");
+}
+function isPositiveInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+function isNonNegativeNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
 function stringifyJson(value) {
     const serialized = JSON.stringify(value);
     if (serialized === undefined) {
@@ -1279,9 +1386,8 @@ function registerSkyWalking(config = {}) {
 }
 /** Triggers a SkyWalking performance report through an already registered client. */
 function setSkyWalkingPerformance(config = {}, customMetrics) {
-    const clientMonitor = getClientMonitor();
-    if (clientMonitor === undefined ||
-        typeof clientMonitor.setPerformance !== "function") {
+    const clientMonitor = getPerformanceClientMonitor();
+    if (clientMonitor === undefined) {
         warnOnce("set-performance-unavailable", "[LiveAvatar SkyWalking plugin] ClientMonitor.setPerformance is unavailable; register SkyWalking first");
         return;
     }
@@ -1306,6 +1412,16 @@ async function reportSkyWalkingFrameErrors(config, error) {
     }
     await Promise.resolve(clientMonitor.reportFrameErrors(config, error));
 }
+function normalizeReportingConfig(config) {
+    return {
+        sdkError: config?.sdkError ?? true,
+        firstFrame: config?.firstFrame ?? true,
+        avSync: config?.avSync ?? true,
+    };
+}
+function hasEnabledReporting(config) {
+    return config.sdkError || config.firstFrame || config.avSync;
+}
 function normalizeSkyWalkingConfig(config) {
     return {
         collector: config.collector ??
@@ -1353,6 +1469,13 @@ function getClientMonitor() {
         ? candidate
         : undefined;
 }
+/** Finds the performance API without requiring the unrelated error API. */
+function getPerformanceClientMonitor() {
+    const candidate = getGlobalClientMonitor();
+    return typeof candidate?.setPerformance === "function"
+        ? candidate
+        : undefined;
+}
 function getGlobalClientMonitor() {
     if (typeof window === "undefined")
         return undefined;

package/dist/index.d.ts

@@ -14,11 +14,23 @@ interface SkyWalkingSlowInteractionConfig {
     threshold?: number;
     reportInterval?: number;
 }
+/** Selects which SDK-generated records the plugin sends to SkyWalking. */
+interface SkyWalkingReportingConfig {
+    /** Report SDK Operational Log errors. Defaults to `true`. */
+    sdkError?: boolean;
+    /** Report terminal SDK first-frame Operational Logs. Defaults to `true`. */
+    firstFrame?: boolean;
+    /** Report SDK-generated A/V Sync alert lifecycles and evidence. Defaults to `true`. */
+    avSync?: boolean;
+}
 /**
  * Registration options accepted by SkyWalking js-sdk 1.1.27, plus the
- * plugin-level overseas switch. `service` is deliberately fixed by the plugin.
+ * plugin-level reporting controls and overseas switch. `service` is deliberately
+ * fixed by the plugin.
  */
 interface SkyWalkingPluginConfig {
+    /** Select automatic SDK log types. Every type is enabled by default. */
+    reporting?: SkyWalkingReportingConfig;
     /** Explicit collector URL. It takes precedence over `isOverseas`. */
     collector?: string;
     /** `false` selects the domestic collector; `true` selects the overseas one. */
@@ -241,6 +253,31 @@ interface SkyWalkingFrameErrorReportConfig {
     maxReqCostTime?: number;
     timeout?: number;
 }
+/**
+ * Custom performance fields sent for one terminal connect-to-first-frame
+ * attempt. Stage fields are present only when the SDK observed that stage.
+ */
+type SkyWalkingFirstFrameOutcome = "first-frame" | "connect-failed" | "first-frame-timeout";
+/** Allowed first-frame timing nodes copied from the SDK Operational Log. */
+interface SkyWalkingFirstFrameLogNodes {
+    configReadyMs?: number;
+    rtcConnectedMs?: number;
+    videoTrackAddedMs?: number;
+    videoMetadataMs?: number;
+    firstFrameMs?: number;
+}
+/** Structured content of one terminal SDK `performance.first-frame` log. */
+interface SkyWalkingFirstFrameLogPayload {
+    schemaVersion: 1;
+    kind: "liveavatar.performance.first-frame";
+    sdkVersion: string;
+    occurredAtMs: number;
+    attemptId: number;
+    outcome: SkyWalkingFirstFrameOutcome;
+    renderMode?: string;
+    timeoutAfterRtcMs?: number;
+    nodes: SkyWalkingFirstFrameLogNodes;
+}
 /**
  * Reports LiveAvatar A/V-sync incident lifecycle events through the bundled or
  * externally provided SkyWalking client.
@@ -250,6 +287,7 @@ declare class SkyWalkingPlugin implements SDKPlugin {
     /** SDK Plugin API v1 is the registrar-based public plugin contract. */
     readonly apiVersion = 1;
     private readonly _skyWalkingConfig;
+    private readonly _reporting;
     private _installation;
     private _nextInstallationGeneration;
     constructor(config?: SkyWalkingPluginConfig);
@@ -261,6 +299,7 @@ declare class SkyWalkingPlugin implements SDKPlugin {
     private _reportActiveAlert;
     private _reportRecovery;
     private _reportSdkError;
+    private _reportFirstFrameLog;
     private _deactivateInstallation;
     private _isInvocationActive;
     private _runObserverTask;
@@ -283,4 +322,4 @@ declare function setSkyWalkingHRT(config?: Partial<SkyWalkingPluginConfig>, cust
 declare function reportSkyWalkingFrameErrors(config: SkyWalkingFrameErrorReportConfig, error: SkyWalkingFrameError): Promise<void>;
 
 export { SKYWALKING_PLUGIN_ID, SkyWalkingPlugin, createSkyWalkingPlugin, registerSkyWalking, reportSkyWalkingFrameErrors, setSkyWalkingHRT, setSkyWalkingPerformance };
-export type { AvSyncAlertEvidencePayload, AvSyncEvidence, AvSyncEvidenceLogChunkPayload, AvSyncRecoveryPayload, JsonSafeAlert, SkyWalkingFrameError, SkyWalkingFrameErrorReportConfig, SkyWalkingHooks, SkyWalkingPluginConfig, SkyWalkingRegistrationOptions, SkyWalkingSdkErrorPayload, SkyWalkingSlowInteractionConfig };
+export type { AvSyncAlertEvidencePayload, AvSyncEvidence, AvSyncEvidenceLogChunkPayload, AvSyncRecoveryPayload, JsonSafeAlert, SkyWalkingFirstFrameLogNodes, SkyWalkingFirstFrameLogPayload, SkyWalkingFirstFrameOutcome, SkyWalkingFrameError, SkyWalkingFrameErrorReportConfig, SkyWalkingHooks, SkyWalkingPluginConfig, SkyWalkingRegistrationOptions, SkyWalkingReportingConfig, SkyWalkingSdkErrorPayload, SkyWalkingSlowInteractionConfig };

package/dist/index.esm.js

@@ -44,28 +44,34 @@ class SkyWalkingPlugin {
         this.apiVersion = 1;
         this._nextInstallationGeneration = 0;
         this._skyWalkingConfig = { ...config };
+        this._reporting = normalizeReportingConfig(config.reporting);
     }
     setup(registrar) {
         this._deactivateInstallation();
+        if (!hasEnabledReporting(this._reporting))
+            return;
         registerSkyWalking(this._skyWalkingConfig);
-        const diagnostics = registrar.consume(SDK_AVSYNC_DIAGNOSTICS_V1);
         const installation = {
             generation: ++this._nextInstallationGeneration,
-            diagnostics,
             abortController: new AbortController(),
             alertReportStates: new Map(),
             active: true,
         };
         this._installation = installation;
         try {
-            registrar.observe(SDK_AVSYNC_ALERTS_V1, {
-                id: AVSYNC_ALERTS_CONTRIBUTION_ID,
-                handler: (alert, context) => this._handleAlertNotification(installation, alert, context.signal),
-            });
-            registrar.observe(SDK_OPERATIONAL_LOGS_V1, {
-                id: OPERATIONAL_LOGS_CONTRIBUTION_ID,
-                handler: (record, context) => this._handleOperationalLog(installation, record, context.signal),
-            });
+            if (this._reporting.avSync) {
+                installation.diagnostics = registrar.consume(SDK_AVSYNC_DIAGNOSTICS_V1);
+                registrar.observe(SDK_AVSYNC_ALERTS_V1, {
+                    id: AVSYNC_ALERTS_CONTRIBUTION_ID,
+                    handler: (alert, context) => this._handleAlertNotification(installation, alert, context.signal),
+                });
+            }
+            if (this._reporting.sdkError || this._reporting.firstFrame) {
+                registrar.observe(SDK_OPERATIONAL_LOGS_V1, {
+                    id: OPERATIONAL_LOGS_CONTRIBUTION_ID,
+                    handler: (record, context) => this._handleOperationalLog(installation, record, context.signal),
+                });
+            }
         }
         catch (error) {
             this._deactivateInstallation();
@@ -114,12 +120,19 @@ class SkyWalkingPlugin {
         }
     }
     _handleOperationalLog(installation, record, signal) {
-        if (!this._isInvocationActive(installation, signal) ||
-            record.level !== "error" ||
-            record.event !== "sdk.error") {
+        if (!this._isInvocationActive(installation, signal))
             return Promise.resolve();
+        if (this._reporting.sdkError &&
+            record.level === "error" &&
+            record.event === "sdk.error") {
+            return this._runObserverTask(installation, signal, "SDK error log", () => this._reportSdkError(installation, record, signal));
         }
-        return this._runObserverTask(installation, signal, "SDK error log", () => this._reportSdkError(installation, record, signal));
+        if (this._reporting.firstFrame &&
+            record.category === "media" &&
+            record.event === "performance.first-frame") {
+            return this._runObserverTask(installation, signal, "first-frame log", () => this._reportFirstFrameLog(installation, record, signal));
+        }
+        return Promise.resolve();
     }
     _enqueue(state, task) {
         const queued = state.tail.then(task, task);
@@ -130,6 +143,9 @@ class SkyWalkingPlugin {
         const isActive = () => this._isInvocationActive(installation, signal);
         if (!isActive())
             return;
+        const diagnostics = installation.diagnostics;
+        if (diagnostics === undefined)
+            return;
         const clientMonitor = getClientMonitor();
         if (clientMonitor === undefined) {
             this._warnInvocation(installation, signal, "ClientMonitor.reportFrameErrors is unavailable", {
@@ -142,7 +158,7 @@ class SkyWalkingPlugin {
         const query = await createEvidenceQuery(alert.phase, state.lastSuccessfulToWallClockMs, [signal, installation.abortController.signal]);
         if (!isActive() || query === undefined)
             return;
-        const collection = await collectTelemetry(installation.diagnostics, alert, retrievedAtWallClockMs, query, isActive, (message, error) => this._warnInvocationFailure(installation, signal, message, error, {
+        const collection = await collectTelemetry(diagnostics, alert, retrievedAtWallClockMs, query, isActive, (message, error) => this._warnInvocationFailure(installation, signal, message, error, {
             alert: toJsonSafeAlert(alert),
         }));
         if (!isActive() || collection === undefined)
@@ -270,6 +286,43 @@ class SkyWalkingPlugin {
         if (!this._isInvocationActive(installation, signal))
             return;
     }
+    async _reportFirstFrameLog(installation, record, signal) {
+        if (!this._isInvocationActive(installation, signal))
+            return;
+        const payload = toSkyWalkingFirstFrameLogPayload(record);
+        if (payload === undefined) {
+            this._warnInvocation(installation, signal, "Skipped invalid first-frame Operational Log", { eventId: record.eventId });
+            return;
+        }
+        const clientMonitor = getClientMonitor();
+        if (clientMonitor === undefined) {
+            this._warnInvocation(installation, signal, "ClientMonitor.reportFrameErrors is unavailable", {
+                pluginId: this.id,
+                attemptId: payload.attemptId,
+                outcome: payload.outcome,
+            });
+            return;
+        }
+        if (!this._isInvocationActive(installation, signal))
+            return;
+        try {
+            await Promise.resolve(clientMonitor.reportFrameErrors({
+                category: "media",
+                grade: payload.outcome === "first-frame" ? "Info" : "Warning",
+                content: payload,
+                // The bundled client batches error records. Its public timeout
+                // option bypasses the default delay for these terminal events.
+                timeout: 1,
+            }, {
+                name: "",
+                message: `[LiveAvatar first-frame] ${payload.outcome}`,
+                stack: "",
+            }));
+        }
+        catch (error) {
+            this._warnInvocationFailure(installation, signal, "Failed to report first-frame Operational Log to SkyWalking", error, { attemptId: payload.attemptId, outcome: payload.outcome });
+        }
+    }
     _deactivateInstallation() {
         const installation = this._installation;
         if (installation === undefined)
@@ -1229,6 +1282,60 @@ function toJsonSafeAlert(alert) {
         features: { ...alert.features },
     };
 }
+/**
+ * Strictly projects the published first-frame Operational Log. The SDK record
+ * has additional identifiers and arbitrary attributes; none of those can
+ * reach SkyWalking through this path.
+ */
+function toSkyWalkingFirstFrameLogPayload(record) {
+    const correlation = toRecord(record.correlation);
+    const attributes = toRecord(record.attributes);
+    const attemptId = correlation.attemptId;
+    const outcome = attributes.outcome;
+    if (!isNonNegativeNumber(record.occurredAtMs) ||
+        !isPositiveInteger(attemptId) ||
+        !isFirstFrameOutcome(outcome)) {
+        return undefined;
+    }
+    const sourceNodes = toRecord(attributes.nodes);
+    const nodes = {};
+    copyNonNegativeNumber(sourceNodes, "configReadyMs", nodes);
+    copyNonNegativeNumber(sourceNodes, "rtcConnectedMs", nodes);
+    copyNonNegativeNumber(sourceNodes, "videoTrackAddedMs", nodes);
+    copyNonNegativeNumber(sourceNodes, "videoMetadataMs", nodes);
+    copyNonNegativeNumber(sourceNodes, "firstFrameMs", nodes);
+    return {
+        schemaVersion: 1,
+        kind: "liveavatar.performance.first-frame",
+        sdkVersion: VERSION,
+        occurredAtMs: record.occurredAtMs,
+        attemptId,
+        outcome,
+        ...(typeof attributes.renderMode === "string"
+            ? { renderMode: attributes.renderMode }
+            : {}),
+        ...(isNonNegativeNumber(attributes.timeoutAfterRtcMs)
+            ? { timeoutAfterRtcMs: attributes.timeoutAfterRtcMs }
+            : {}),
+        nodes,
+    };
+}
+function copyNonNegativeNumber(source, key, target) {
+    const value = source[key];
+    if (isNonNegativeNumber(value))
+        target[key] = value;
+}
+function isFirstFrameOutcome(value) {
+    return (value === "first-frame" ||
+        value === "connect-failed" ||
+        value === "first-frame-timeout");
+}
+function isPositiveInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+function isNonNegativeNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
 function stringifyJson(value) {
     const serialized = JSON.stringify(value);
     if (serialized === undefined) {
@@ -1277,9 +1384,8 @@ function registerSkyWalking(config = {}) {
 }
 /** Triggers a SkyWalking performance report through an already registered client. */
 function setSkyWalkingPerformance(config = {}, customMetrics) {
-    const clientMonitor = getClientMonitor();
-    if (clientMonitor === undefined ||
-        typeof clientMonitor.setPerformance !== "function") {
+    const clientMonitor = getPerformanceClientMonitor();
+    if (clientMonitor === undefined) {
         warnOnce("set-performance-unavailable", "[LiveAvatar SkyWalking plugin] ClientMonitor.setPerformance is unavailable; register SkyWalking first");
         return;
     }
@@ -1304,6 +1410,16 @@ async function reportSkyWalkingFrameErrors(config, error) {
     }
     await Promise.resolve(clientMonitor.reportFrameErrors(config, error));
 }
+function normalizeReportingConfig(config) {
+    return {
+        sdkError: config?.sdkError ?? true,
+        firstFrame: config?.firstFrame ?? true,
+        avSync: config?.avSync ?? true,
+    };
+}
+function hasEnabledReporting(config) {
+    return config.sdkError || config.firstFrame || config.avSync;
+}
 function normalizeSkyWalkingConfig(config) {
     return {
         collector: config.collector ??
@@ -1351,6 +1467,13 @@ function getClientMonitor() {
         ? candidate
         : undefined;
 }
+/** Finds the performance API without requiring the unrelated error API. */
+function getPerformanceClientMonitor() {
+    const candidate = getGlobalClientMonitor();
+    return typeof candidate?.setPerformance === "function"
+        ? candidate
+        : undefined;
+}
 function getGlobalClientMonitor() {
     if (typeof window === "undefined")
         return undefined;

package/dist/index.umd.js

@@ -48,28 +48,34 @@
             this.apiVersion = 1;
             this._nextInstallationGeneration = 0;
             this._skyWalkingConfig = { ...config };
+            this._reporting = normalizeReportingConfig(config.reporting);
         }
         setup(registrar) {
             this._deactivateInstallation();
+            if (!hasEnabledReporting(this._reporting))
+                return;
             registerSkyWalking(this._skyWalkingConfig);
-            const diagnostics = registrar.consume(liveavatarJsSdk.SDK_AVSYNC_DIAGNOSTICS_V1);
             const installation = {
                 generation: ++this._nextInstallationGeneration,
-                diagnostics,
                 abortController: new AbortController(),
                 alertReportStates: new Map(),
                 active: true,
             };
             this._installation = installation;
             try {
-                registrar.observe(liveavatarJsSdk.SDK_AVSYNC_ALERTS_V1, {
-                    id: AVSYNC_ALERTS_CONTRIBUTION_ID,
-                    handler: (alert, context) => this._handleAlertNotification(installation, alert, context.signal),
-                });
-                registrar.observe(liveavatarJsSdk.SDK_OPERATIONAL_LOGS_V1, {
-                    id: OPERATIONAL_LOGS_CONTRIBUTION_ID,
-                    handler: (record, context) => this._handleOperationalLog(installation, record, context.signal),
-                });
+                if (this._reporting.avSync) {
+                    installation.diagnostics = registrar.consume(liveavatarJsSdk.SDK_AVSYNC_DIAGNOSTICS_V1);
+                    registrar.observe(liveavatarJsSdk.SDK_AVSYNC_ALERTS_V1, {
+                        id: AVSYNC_ALERTS_CONTRIBUTION_ID,
+                        handler: (alert, context) => this._handleAlertNotification(installation, alert, context.signal),
+                    });
+                }
+                if (this._reporting.sdkError || this._reporting.firstFrame) {
+                    registrar.observe(liveavatarJsSdk.SDK_OPERATIONAL_LOGS_V1, {
+                        id: OPERATIONAL_LOGS_CONTRIBUTION_ID,
+                        handler: (record, context) => this._handleOperationalLog(installation, record, context.signal),
+                    });
+                }
             }
             catch (error) {
                 this._deactivateInstallation();
@@ -118,12 +124,19 @@
             }
         }
         _handleOperationalLog(installation, record, signal) {
-            if (!this._isInvocationActive(installation, signal) ||
-                record.level !== "error" ||
-                record.event !== "sdk.error") {
+            if (!this._isInvocationActive(installation, signal))
                 return Promise.resolve();
+            if (this._reporting.sdkError &&
+                record.level === "error" &&
+                record.event === "sdk.error") {
+                return this._runObserverTask(installation, signal, "SDK error log", () => this._reportSdkError(installation, record, signal));
             }
-            return this._runObserverTask(installation, signal, "SDK error log", () => this._reportSdkError(installation, record, signal));
+            if (this._reporting.firstFrame &&
+                record.category === "media" &&
+                record.event === "performance.first-frame") {
+                return this._runObserverTask(installation, signal, "first-frame log", () => this._reportFirstFrameLog(installation, record, signal));
+            }
+            return Promise.resolve();
         }
         _enqueue(state, task) {
             const queued = state.tail.then(task, task);
@@ -134,6 +147,9 @@
             const isActive = () => this._isInvocationActive(installation, signal);
             if (!isActive())
                 return;
+            const diagnostics = installation.diagnostics;
+            if (diagnostics === undefined)
+                return;
             const clientMonitor = getClientMonitor();
             if (clientMonitor === undefined) {
                 this._warnInvocation(installation, signal, "ClientMonitor.reportFrameErrors is unavailable", {
@@ -146,7 +162,7 @@
             const query = await createEvidenceQuery(alert.phase, state.lastSuccessfulToWallClockMs, [signal, installation.abortController.signal]);
             if (!isActive() || query === undefined)
                 return;
-            const collection = await collectTelemetry(installation.diagnostics, alert, retrievedAtWallClockMs, query, isActive, (message, error) => this._warnInvocationFailure(installation, signal, message, error, {
+            const collection = await collectTelemetry(diagnostics, alert, retrievedAtWallClockMs, query, isActive, (message, error) => this._warnInvocationFailure(installation, signal, message, error, {
                 alert: toJsonSafeAlert(alert),
             }));
             if (!isActive() || collection === undefined)
@@ -274,6 +290,43 @@
             if (!this._isInvocationActive(installation, signal))
                 return;
         }
+        async _reportFirstFrameLog(installation, record, signal) {
+            if (!this._isInvocationActive(installation, signal))
+                return;
+            const payload = toSkyWalkingFirstFrameLogPayload(record);
+            if (payload === undefined) {
+                this._warnInvocation(installation, signal, "Skipped invalid first-frame Operational Log", { eventId: record.eventId });
+                return;
+            }
+            const clientMonitor = getClientMonitor();
+            if (clientMonitor === undefined) {
+                this._warnInvocation(installation, signal, "ClientMonitor.reportFrameErrors is unavailable", {
+                    pluginId: this.id,
+                    attemptId: payload.attemptId,
+                    outcome: payload.outcome,
+                });
+                return;
+            }
+            if (!this._isInvocationActive(installation, signal))
+                return;
+            try {
+                await Promise.resolve(clientMonitor.reportFrameErrors({
+                    category: "media",
+                    grade: payload.outcome === "first-frame" ? "Info" : "Warning",
+                    content: payload,
+                    // The bundled client batches error records. Its public timeout
+                    // option bypasses the default delay for these terminal events.
+                    timeout: 1,
+                }, {
+                    name: "",
+                    message: `[LiveAvatar first-frame] ${payload.outcome}`,
+                    stack: "",
+                }));
+            }
+            catch (error) {
+                this._warnInvocationFailure(installation, signal, "Failed to report first-frame Operational Log to SkyWalking", error, { attemptId: payload.attemptId, outcome: payload.outcome });
+            }
+        }
         _deactivateInstallation() {
             const installation = this._installation;
             if (installation === undefined)
@@ -1233,6 +1286,60 @@
             features: { ...alert.features },
         };
     }
+    /**
+     * Strictly projects the published first-frame Operational Log. The SDK record
+     * has additional identifiers and arbitrary attributes; none of those can
+     * reach SkyWalking through this path.
+     */
+    function toSkyWalkingFirstFrameLogPayload(record) {
+        const correlation = toRecord(record.correlation);
+        const attributes = toRecord(record.attributes);
+        const attemptId = correlation.attemptId;
+        const outcome = attributes.outcome;
+        if (!isNonNegativeNumber(record.occurredAtMs) ||
+            !isPositiveInteger(attemptId) ||
+            !isFirstFrameOutcome(outcome)) {
+            return undefined;
+        }
+        const sourceNodes = toRecord(attributes.nodes);
+        const nodes = {};
+        copyNonNegativeNumber(sourceNodes, "configReadyMs", nodes);
+        copyNonNegativeNumber(sourceNodes, "rtcConnectedMs", nodes);
+        copyNonNegativeNumber(sourceNodes, "videoTrackAddedMs", nodes);
+        copyNonNegativeNumber(sourceNodes, "videoMetadataMs", nodes);
+        copyNonNegativeNumber(sourceNodes, "firstFrameMs", nodes);
+        return {
+            schemaVersion: 1,
+            kind: "liveavatar.performance.first-frame",
+            sdkVersion: liveavatarJsSdk.VERSION,
+            occurredAtMs: record.occurredAtMs,
+            attemptId,
+            outcome,
+            ...(typeof attributes.renderMode === "string"
+                ? { renderMode: attributes.renderMode }
+                : {}),
+            ...(isNonNegativeNumber(attributes.timeoutAfterRtcMs)
+                ? { timeoutAfterRtcMs: attributes.timeoutAfterRtcMs }
+                : {}),
+            nodes,
+        };
+    }
+    function copyNonNegativeNumber(source, key, target) {
+        const value = source[key];
+        if (isNonNegativeNumber(value))
+            target[key] = value;
+    }
+    function isFirstFrameOutcome(value) {
+        return (value === "first-frame" ||
+            value === "connect-failed" ||
+            value === "first-frame-timeout");
+    }
+    function isPositiveInteger(value) {
+        return typeof value === "number" && Number.isInteger(value) && value > 0;
+    }
+    function isNonNegativeNumber(value) {
+        return typeof value === "number" && Number.isFinite(value) && value >= 0;
+    }
     function stringifyJson(value) {
         const serialized = JSON.stringify(value);
         if (serialized === undefined) {
@@ -1281,9 +1388,8 @@
     }
     /** Triggers a SkyWalking performance report through an already registered client. */
     function setSkyWalkingPerformance(config = {}, customMetrics) {
-        const clientMonitor = getClientMonitor();
-        if (clientMonitor === undefined ||
-            typeof clientMonitor.setPerformance !== "function") {
+        const clientMonitor = getPerformanceClientMonitor();
+        if (clientMonitor === undefined) {
             warnOnce("set-performance-unavailable", "[LiveAvatar SkyWalking plugin] ClientMonitor.setPerformance is unavailable; register SkyWalking first");
             return;
         }
@@ -1308,6 +1414,16 @@
         }
         await Promise.resolve(clientMonitor.reportFrameErrors(config, error));
     }
+    function normalizeReportingConfig(config) {
+        return {
+            sdkError: config?.sdkError ?? true,
+            firstFrame: config?.firstFrame ?? true,
+            avSync: config?.avSync ?? true,
+        };
+    }
+    function hasEnabledReporting(config) {
+        return config.sdkError || config.firstFrame || config.avSync;
+    }
     function normalizeSkyWalkingConfig(config) {
         return {
             collector: config.collector ??
@@ -1355,6 +1471,13 @@
             ? candidate
             : undefined;
     }
+    /** Finds the performance API without requiring the unrelated error API. */
+    function getPerformanceClientMonitor() {
+        const candidate = getGlobalClientMonitor();
+        return typeof candidate?.setPerformance === "function"
+            ? candidate
+            : undefined;
+    }
     function getGlobalClientMonitor() {
         if (typeof window === "undefined")
             return undefined;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sanseng/liveavatar-js-sdk-skywalking",
-  "version": "1.0.0",
-  "description": "Bundled SkyWalking plugin for @sanseng/liveavatar-js-sdk A/V Sync diagnostics and Operational Log SDK errors",
+  "version": "1.0.1",
+  "description": "SkyWalking plugin for LiveAvatar A/V Sync alerts, first-frame performance, and SDK errors with type-selective reporting",
   "license": "MIT",
   "author": "sanseng",
   "main": "dist/index.cjs.js",
@@ -43,7 +43,7 @@
     "observability"
   ],
   "peerDependencies": {
-    "@sanseng/liveavatar-js-sdk": "^2.2.0"
+    "@sanseng/liveavatar-js-sdk": "^2.4.0"
   },
   "devDependencies": {
     "@rollup/plugin-typescript": "^12.3.0",
@@ -53,6 +53,7 @@
     "rimraf": "^6.1.2",
     "rollup": "^4.55.1",
     "rollup-plugin-dts": "^6.3.0",
+    "tslib": "^2.8.1",
     "typescript": "^5.9.3",
     "vite": "^7.3.0",
     "vitest": "^4.1.7"