skillprint-js-sdk 1.1.0-beta.7 → 1.1.0-beta.9

package/README.md

@@ -14,7 +14,7 @@ A professional JavaScript & TypeScript SDK for integrating Skillprint's real-tim
 - 📸 **Automated Screenshot Capture**: Asynchronous, throttled gameplay screenshot captures for Canvas and WebGL contexts without dropping game frame rates.
 - 🔄 **Real-Time Dynamic Parameters**: Receive, convert, clamp, and apply AI-driven parameter modifications seamlessly during active sessions.
 - 🎮 **Built-In Engine Adapters**: Ready-to-use adapter wrappers for Phaser.js, Three.js, PixiJS, and Generic Canvas.
-- 📊 **Discrete Telemetry Events**: Optional `logEvent()` for precise, low-latency gameplay signals (a fixed vocabulary, or your own custom event names) alongside screenshot capture. See [Discrete Telemetry Events](#discrete-telemetry-events).
+- 📊 **Discrete Telemetry Events**: `logEvent()` for universal and game-specific gameplay events, sent with the screenshots and timestamped from session start. See [Discrete Telemetry Events](#discrete-telemetry-events).
 - 🌐 **WebGL & URL Extraction**: Automatic query parameter extraction for web deployments (`mood`, `playerId`).
 - 🧪 **100% Test Coverage Ready**: Fully tested with Vitest and jsdom.
 
@@ -191,35 +191,68 @@ manager.startGameSessionWithOverrides(
 
 ## Discrete Telemetry Events
 
-Screenshot capture is the SDK's primary telemetry mechanism and covers every game automatically. `logEvent()` is an **optional, additive** layer on top of it for games that want precise, low-latency event signals alongside the vision-based scoring — it doesn't replace or interact with the screenshot loop.
+Screenshots are the SDK's main telemetry and cover every game automatically. `logEvent()` adds discrete events: what the player did and when. Events and screenshots are both stamped with the **milliseconds since the session started**, so Skillprint can line each event up with the frames around it.
 
 ```typescript
 import { GameEvent } from 'skillprint-js-sdk';
 
-manager.logEvent(GameEvent.LEVEL_START);
+manager.logEvent(GameEvent.LEVEL_START, { level: 3 });
+manager.logEvent('ROTATE_CLOCKWISE');
 manager.logEvent(GameEvent.LEVEL_COMPLETE, { level: 3, score: 1200 });
 ```
 
-`logEvent` is fire-and-forget: a failed request is logged as a warning and does not throw, so it can never interrupt gameplay. Calling it with no active session is a no-op (also just a warning).
+Events are queued, and each screenshot upload carries the ones logged up to its last screenshot. Later events wait for the upload with the screenshots after them, and `stopGameSession()` sends the rest with the closing upload. The SDK decides which events go with which upload; the server keeps each upload's events with its screenshots and does no time arithmetic. If no screenshots come for a long while, events only go on their own once more than one upload's worth (1000) has piled up. `logEvent` never throws, and with no active session it only logs a warning.
 
-### Two ways to use it
+### Universal and game-specific events
 
-**1. The fixed `GameEvent` vocabulary** — recommended for most integrations. Events logged with one of these names are automatically read as a clear positive or negative signal, with nothing else to configure:
+**Universal events** (`GameEvent`) mean the same thing in every game. Send the ones that apply to yours:
 
-| Event | Signal |
-|---|---|
-| `LEVEL_START`, `LEVEL_COMPLETE` | Positive |
-| `LEVEL_QUIT`, `LEVEL_FAILED`, `LEVEL_RESTART`, `HINT` | Negative |
-| `GENERIC_POSITIVE`, `GENERIC_NEGATIVE` | Use for anything else that's clearly good or bad for the player and doesn't fit the events above |
+| Event | When | Scoring signal |
+|---|---|---|
+| `GAME_START`, `GAME_END` | The game begins or ends | |
+| `GAME_PAUSE`, `GAME_RESUME` | Play is paused or resumed | |
+| `LEVEL_START`, `LEVEL_COMPLETE` | A level begins or is completed | Positive |
+| `LEVEL_QUIT`, `LEVEL_FAILED`, `LEVEL_RESTART` | A level is abandoned, lost or restarted | Negative |
+| `MATCH`, `UNMATCH` | A match is made or undone, in games built on matching | |
+| `HINT` | The player asks for a hint | Negative |
+| `GENERIC_POSITIVE`, `GENERIC_NEGATIVE` | Anything else clearly good or bad for the player | Positive / Negative |
 
-**2. A custom event name** (any string) — for a richer, game-specific vocabulary:
+**Game-specific events** are any other name, for actions only your game has. For Hextris, for example:
 
 ```typescript
-manager.logEvent('CLOCKWISE_TAP', { comboCount: 4 });
-manager.logEvent('TWO_COLORS_MATCHED', { color: 'red' });
+manager.logEvent('ROTATE_CLOCKWISE');
+manager.logEvent('ROTATE_ANTICLOCKWISE');
 ```
 
-Custom event names don't need to be registered in advance — send whatever your game already tracks. They're picked up by Skillprint's scoring as additional context alongside screenshots. If you want a custom event to map to a specific improvement in scoring accuracy for your game, talk to your Skillprint contact about setting up a custom scoring configuration.
+They don't need registering; send what your game already tracks, in `UPPER_SNAKE_CASE`. `isUniversalEvent(name)` tells the two kinds apart.
+
+Each event can carry data (`{ level: 3, score: 1200 }`). `event` and `timestamp` are set by the SDK and can't be overridden.
+
+### What is sent
+
+Each screenshot upload can carry, beside the images:
+- `offset_ms<n>`: when the n-th screenshot was captured, in ms from session start
+- `events`: a JSON array of the events logged up to the upload's last screenshot (at most 1000), e.g. `[{"event": "ROTATE_CLOCKWISE", "timestamp": 1250}]`, where `timestamp` is ms from session start
+
+### Pages that upload their own frames
+
+A page that captures its own screenshots and calls `SkillprintAPIClient` directly (see [Host mode](#skillprintapiclient)) keeps a `SessionTimeline` itself:
+
+```typescript
+import { SessionTimeline, SkillprintAPIClient } from 'skillprint-js-sdk';
+
+const timeline = new SessionTimeline();
+await client.startSession(sessionId, 'focus', null, 'hextris');
+timeline.start();
+
+const offset = timeline.offsetMs();        // when a frame is captured
+timeline.record('ROTATE_CLOCKWISE');       // when the player acts
+
+await client.postScreenshots(sessionId, [frame], false, {
+  offsetsMs: [offset],
+  events: timeline.eventsForUpload(offset)   // null for the closing upload
+});
+```
 
 ## API Reference
 
@@ -249,7 +282,7 @@ Custom event names don't need to be registered in advance — send whatever your
 The HTTP client `SkillprintManager` uses. Use it directly when your page already captures its own frames, or when you need session scores.
 - `constructor(baseUrl: string, partnerApiKey?: string, logger?: SDKLogger)`
 - `startSession(sessionId, targetMood, customPlayerId?, gameName?, gameParameters?: ParameterInfo[], options?: { deviceContext? })`
-- `postScreenshots(sessionId, screenshots: Blob[], isLastChunk?, options?: { gameStates? })`: `gameStates[n]` (for example `{ score: 1200 }`) is sent with the n-th screenshot, and the latest `score` becomes the session's score. `inputCount` is how many player inputs the batch covers; a batch with 0 is left out of skill scores. `isLastChunk: true` scores the batch and closes the session.
+- `postScreenshots(sessionId, screenshots: Blob[], isLastChunk?, options?: { gameStates?, inputCount?, offsetsMs?, events? })`: `offsetsMs[n]` is when the n-th screenshot was captured and `events` are the events since the last upload, both in ms from session start (see [Discrete Telemetry Events](#discrete-telemetry-events)). `gameStates[n]` (for example `{ score: 1200 }`) is sent with the n-th screenshot, and the latest `score` becomes the session's score. `inputCount` is how many player inputs the batch covers; a batch with 0 is left out of skill scores. `isLastChunk: true` scores the batch and closes the session.
 - `getSession(sessionId): Promise<SessionResult>`: the session's `state` (`OPEN`, then `CLOSED` once scored), `skillScores`, `moodScores`, `score`, `telemetry` (adjustments and logged events) and `parameterUpdates`
 - `pollParameterResults(sessionId)`: only the parameter updates
 - `getUserProfile()`: the player's skill profile; needs a player token

package/dist/index.cjs

@@ -24,6 +24,7 @@ __export(index_exports, {
   GameEvent: () => GameEvent,
   GenericCanvasSkillprintAdapter: () => GenericCanvasSkillprintAdapter,
   LogLevel: () => LogLevel,
+  MAX_EVENTS_PER_UPLOAD: () => MAX_EVENTS_PER_UPLOAD,
   Mood: () => Mood,
   ParameterDefinition: () => ParameterDefinition,
   ParameterInfo: () => ParameterInfo,
@@ -33,6 +34,7 @@ __export(index_exports, {
   PixiSkillprintAdapter: () => PixiSkillprintAdapter,
   PollResultsResponse: () => PollResultsResponse,
   ScreenshotUtility: () => ScreenshotUtility,
+  SessionTimeline: () => SessionTimeline,
   SkillprintAPIClient: () => SkillprintAPIClient,
   SkillprintApiError: () => SkillprintApiError,
   SkillprintConfig: () => SkillprintConfig,
@@ -41,7 +43,8 @@ __export(index_exports, {
   StartSessionRequest: () => StartSessionRequest,
   TelemetryEventRequest: () => TelemetryEventRequest,
   ThreeSkillprintAdapter: () => ThreeSkillprintAdapter,
-  WebGLUrlParameterExtractor: () => WebGLUrlParameterExtractor
+  WebGLUrlParameterExtractor: () => WebGLUrlParameterExtractor,
+  isUniversalEvent: () => isUniversalEvent
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -76,16 +79,25 @@ var LogLevel = /* @__PURE__ */ ((LogLevel2) => {
   return LogLevel2;
 })(LogLevel || {});
 var GameEvent = /* @__PURE__ */ ((GameEvent4) => {
+  GameEvent4["GAME_START"] = "GAME_START";
+  GameEvent4["GAME_END"] = "GAME_END";
+  GameEvent4["GAME_PAUSE"] = "GAME_PAUSE";
+  GameEvent4["GAME_RESUME"] = "GAME_RESUME";
   GameEvent4["LEVEL_START"] = "LEVEL_START";
   GameEvent4["LEVEL_COMPLETE"] = "LEVEL_COMPLETE";
   GameEvent4["LEVEL_QUIT"] = "LEVEL_QUIT";
   GameEvent4["LEVEL_FAILED"] = "LEVEL_FAILED";
   GameEvent4["LEVEL_RESTART"] = "LEVEL_RESTART";
+  GameEvent4["MATCH"] = "MATCH";
+  GameEvent4["UNMATCH"] = "UNMATCH";
   GameEvent4["HINT"] = "HINT";
   GameEvent4["GENERIC_POSITIVE"] = "GENERIC_POSITIVE";
   GameEvent4["GENERIC_NEGATIVE"] = "GENERIC_NEGATIVE";
   return GameEvent4;
 })(GameEvent || {});
+function isUniversalEvent(name) {
+  return Object.values(GameEvent).includes(name);
+}
 
 // src/config.ts
 var SkillprintConfig = class {
@@ -473,8 +485,9 @@ var SkillprintAPIClient = class {
     const endpoint = this.UPLOAD_SCREENSHOTS_ENDPOINT.replace("{sessionId}", sessionId);
     const url = `${this.baseUrl}${endpoint}`;
     this.logger?.(`Posting ${screenshots.length} screenshots (isLastChunk: ${isLastChunk}): POST ${url}`, "info" /* INFO */);
-    if (screenshots.length === 0 && !isLastChunk) {
-      const errorMsg = "No screenshots provided, and 'is_last_chunk' is false. API likely requires files in this case.";
+    const events = options.events || [];
+    if (screenshots.length === 0 && !isLastChunk && events.length === 0) {
+      const errorMsg = "No screenshots or events provided, and 'is_last_chunk' is false. Nothing to upload.";
       this.logger?.(errorMsg, "warning" /* WARNING */);
       throw new Error(errorMsg);
     }
@@ -498,6 +511,14 @@ var SkillprintAPIClient = class {
     if (typeof options.inputCount === "number") {
       formData.append("input_count", String(options.inputCount));
     }
+    (options.offsetsMs || []).forEach((offset, i) => {
+      if (typeof offset === "number" && offset >= 0) {
+        formData.append(`offset_ms${i}`, String(Math.round(offset)));
+      }
+    });
+    if (options.events !== void 0) {
+      formData.append("events", JSON.stringify(events));
+    }
     try {
       const response = await fetch(url, {
         method: "POST",
@@ -819,6 +840,106 @@ var ScreenshotUtility = class {
   }
 };
 
+// src/session-timeline.ts
+var MAX_EVENTS_PER_UPLOAD = 1e3;
+var defaultNow = () => typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+var SessionTimeline = class {
+  /**
+   * @param now Clock in milliseconds; defaults to `performance.now()`
+   * @param maxQueued Events kept while waiting for an upload; later ones are dropped
+   */
+  constructor(now = defaultNow, maxQueued = 5e3) {
+    this.startedAt = null;
+    this.queue = [];
+    this.recordedAny = false;
+    this.now = now;
+    this.maxQueued = maxQueued;
+  }
+  /** Starts the clock at 0 and empties the queue. */
+  start() {
+    this.startedAt = this.now();
+    this.queue = [];
+    this.recordedAny = false;
+  }
+  /** Stops the clock and empties the queue. */
+  reset() {
+    this.startedAt = null;
+    this.queue = [];
+    this.recordedAny = false;
+  }
+  get isStarted() {
+    return this.startedAt !== null;
+  }
+  /**
+   * Whole milliseconds from `start()` to `at` (default: now); 0 before
+   * the start, or for a time earlier than it.
+   */
+  offsetMs(at) {
+    if (this.startedAt === null) return 0;
+    const when = typeof at === "number" && Number.isFinite(at) ? at : this.now();
+    return Math.max(0, Math.round(when - this.startedAt));
+  }
+  /**
+   * Stamps an event with the current offset and queues it.
+   * Returns the queued event, or null when the queue is full.
+   *
+   * `event` is a `GameEvent` for the universal vocabulary, or the game's
+   * own name for a game-specific event (e.g. 'ROTATE_CLOCKWISE'). `data`
+   * is merged in; it can't override `event` or `timestamp`. `at` is when
+   * it happened, on this timeline's clock (default: now).
+   */
+  record(event, data = {}, at) {
+    if (this.queue.length >= this.maxQueued) return null;
+    const entry = { ...data, event, timestamp: this.offsetMs(at) };
+    this.queue.push(entry);
+    this.recordedAny = true;
+    return entry;
+  }
+  get pendingEvents() {
+    return this.queue.length;
+  }
+  /** True once this session has recorded any event. */
+  get hasRecorded() {
+    return this.recordedAny;
+  }
+  /** Removes and returns the earliest queued events, at most `max`, in session-time order. */
+  takeEvents(max = MAX_EVENTS_PER_UPLOAD) {
+    this.sortQueue();
+    return this.queue.splice(0, max);
+  }
+  /**
+   * Removes and returns the queued events logged up to `offsetMs`
+   * (inclusive), at most `max`, in session-time order. Later ones stay
+   * queued for the upload that carries the screenshots after them.
+   */
+  takeEventsThrough(offsetMs, max = MAX_EVENTS_PER_UPLOAD) {
+    this.sortQueue();
+    let n = 0;
+    while (n < this.queue.length && n < max && this.queue[n].timestamp <= offsetMs) n++;
+    return this.queue.splice(0, n);
+  }
+  /**
+   * The `events` for an upload whose last screenshot was taken at
+   * `lastFrameOffsetMs`: the events logged up to then, or every queued
+   * event for the closing upload (pass null). An empty list once the
+   * session has recorded any event, so the server can tell a quiet stretch
+   * from a game that doesn't log events; undefined before that.
+   */
+  eventsForUpload(lastFrameOffsetMs) {
+    if (!this.recordedAny) return void 0;
+    return lastFrameOffsetMs === null ? this.takeEvents() : this.takeEventsThrough(lastFrameOffsetMs);
+  }
+  // Events stamped with `at` can arrive out of order; uploads send them in order.
+  sortQueue() {
+    this.queue.sort((a, b) => a.timestamp - b.timestamp);
+  }
+  /** Puts events back at the front of the queue, e.g. after a failed upload. */
+  requeue(events) {
+    const room = Math.max(0, this.maxQueued - this.queue.length);
+    this.queue.unshift(...events.slice(0, room));
+  }
+};
+
 // src/url-parameter-extractor.ts
 var WebGLUrlParameterExtractor = class {
   /**
@@ -941,6 +1062,8 @@ var _SkillprintManager = class _SkillprintManager {
     this.apiClient = null;
     this.screenshotUtility = null;
     this.screenshotQueue = [];
+    /** The session's clock and its queue of events waiting for an upload. */
+    this.timeline = new SessionTimeline();
     this.registeredParameters = /* @__PURE__ */ new Map();
     // Timers
     this.screenshotCaptureTimer = null;
@@ -960,6 +1083,7 @@ var _SkillprintManager = class _SkillprintManager {
     this.apiClient = null;
     this.screenshotUtility = null;
     this.screenshotQueue = [];
+    this.timeline = new SessionTimeline();
     this.registeredParameters = /* @__PURE__ */ new Map();
     this.initializeSDK();
     _SkillprintManager.instance = this;
@@ -1061,6 +1185,7 @@ var _SkillprintManager = class _SkillprintManager {
     }
     this.currentSessionId = this.generateSessionId();
     this.isSessionActive = true;
+    this.timeline.start();
     this.log(`Starting game session for ${this.config.targetEnvironment} environment.`, "info" /* INFO */);
     const parameterInfos = Array.from(this.registeredParameters.values()).map(
       (p) => new ParameterInfo(
@@ -1089,6 +1214,7 @@ var _SkillprintManager = class _SkillprintManager {
       this.log(`Failed to start Skillprint session: ${message}`, "error" /* ERROR */);
       this.isSessionActive = false;
       this.currentSessionId = null;
+      this.timeline.reset();
     }
   }
   /**
@@ -1109,6 +1235,8 @@ var _SkillprintManager = class _SkillprintManager {
     }
     const sessionId = this.currentSessionId;
     const remaining = this.screenshotQueue;
+    const recorded = this.timeline.hasRecorded;
+    const events = this.timeline.takeEvents(Number.MAX_SAFE_INTEGER);
     const inFlightPost = this.inFlightPost;
     const apiClient = this.apiClient;
     this.log(`Stopping Skillprint session: ${sessionId}`);
@@ -1122,6 +1250,7 @@ var _SkillprintManager = class _SkillprintManager {
     this.screenshotQueue = [];
     this.currentSessionId = null;
     this.inFlightPost = null;
+    this.timeline.reset();
     if (!sessionId || !apiClient) {
       this.log("Skillprint session stopped.");
       return;
@@ -1129,41 +1258,56 @@ var _SkillprintManager = class _SkillprintManager {
     if (inFlightPost) await inFlightPost;
     const batchSize = this.postBatchSize();
     try {
+      const eventsUpTo = (lastFrameOffsetMs) => {
+        if (!recorded) return void 0;
+        const n = lastFrameOffsetMs === null ? events.length : events.findIndex((e) => e.timestamp > lastFrameOffsetMs);
+        return events.splice(0, Math.min(n === -1 ? events.length : n, MAX_EVENTS_PER_UPLOAD));
+      };
       if (remaining.length === 0) {
-        await apiClient.postScreenshots(sessionId, [], true);
+        while (events.length > MAX_EVENTS_PER_UPLOAD) {
+          await apiClient.postScreenshots(sessionId, [], false, { events: events.splice(0, MAX_EVENTS_PER_UPLOAD) });
+        }
+        await apiClient.postScreenshots(sessionId, [], true, { events: eventsUpTo(null) });
       } else {
         for (let i = 0; i < remaining.length; i += batchSize) {
           const batch = remaining.slice(i, i + batchSize);
           const isLastChunk = i + batchSize >= remaining.length;
-          await apiClient.postScreenshots(sessionId, batch, isLastChunk);
+          if (isLastChunk) {
+            while (events.length > MAX_EVENTS_PER_UPLOAD) {
+              await apiClient.postScreenshots(sessionId, [], false, { events: events.splice(0, MAX_EVENTS_PER_UPLOAD) });
+            }
+          }
+          const lastOffset = Math.max(...batch.map((s) => s.offsetMs));
+          await apiClient.postScreenshots(sessionId, batch.map((s) => s.blob), isLastChunk, {
+            offsetsMs: batch.map((s) => s.offsetMs),
+            events: eventsUpTo(isLastChunk ? null : lastOffset)
+          });
         }
       }
-      this.log(`Skillprint session stopped. Flushed ${remaining.length} queued screenshots.`);
+      const flushed = remaining.length;
+      this.log(`Skillprint session stopped. Flushed ${flushed} queued screenshots.`);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       this.log(`Failed to flush screenshots on session stop: ${message}`, "error" /* ERROR */);
     }
   }
   /**
-   * Logs a discrete gameplay event for the active session, independent
-   * of screenshot capture. Fire-and-forget: a failed telemetry post is
-   * logged as a warning rather than thrown, so it can't interrupt
-   * gameplay the way an unhandled rejection might.
+   * Logs a discrete gameplay event for the active session: a universal
+   * `GameEvent`, or the game's own name for a game-specific event (e.g.
+   * 'ROTATE_CLOCKWISE'). It is stamped with the milliseconds since the
+   * session started and sent with the next screenshot upload (or on its own
+   * when there is no screenshot to send), and the rest go with the closing
+   * upload on stopGameSession().
+   *
+   * Never throws; with no active session it is ignored with a warning.
    */
   async logEvent(event, data = {}) {
     if (!this.isSessionActive || !this.currentSessionId || !this.apiClient) {
       this.log("logEvent called with no active session. Ignoring.", "warning" /* WARNING */);
       return;
     }
-    try {
-      await this.apiClient.logTelemetryEvent(
-        this.currentSessionId,
-        this.config.gameName,
-        new TelemetryEventRequest(event, data)
-      );
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      this.log(`Failed to log event '${event}': ${message}`, "warning" /* WARNING */);
+    if (!this.timeline.record(event, data)) {
+      this.log(`Event queue full. Dropping '${event}'.`, "warning" /* WARNING */);
     }
   }
   startScreenshotCaptureLoop() {
@@ -1175,11 +1319,12 @@ var _SkillprintManager = class _SkillprintManager {
         return;
       }
       const sessionId = this.currentSessionId;
+      const offsetMs = this.timeline.offsetMs();
       const screenshot = await this.screenshotUtility.captureScreenshot(canvas);
       if (!this.isSessionActive || this.currentSessionId !== sessionId) return;
       if (screenshot) {
         if (this.screenshotQueue.length < 50) {
-          this.screenshotQueue.push(screenshot);
+          this.screenshotQueue.push({ blob: screenshot, offsetMs });
           this.log(`Screenshot captured. Queue size: ${this.screenshotQueue.length}`);
         } else {
           this.log("Screenshot queue full. Discarding new screenshot.", "warning" /* WARNING */);
@@ -1189,27 +1334,41 @@ var _SkillprintManager = class _SkillprintManager {
   }
   startScreenshotPostLoop() {
     this.screenshotPostTimer = setInterval(async () => {
-      if (!this.isSessionActive || this.screenshotQueue.length === 0 || !this.apiClient || !this.currentSessionId) return;
-      const batchToPost = this.screenshotQueue.splice(0, Math.min(this.screenshotQueue.length, this.postBatchSize()));
-      if (batchToPost.length > 0) {
-        this.log(`Posting ${batchToPost.length} screenshots...`);
-        const apiClient = this.apiClient;
-        const sessionId = this.currentSessionId;
-        const post = (async () => {
-          try {
-            const result = await apiClient.postScreenshots(sessionId, batchToPost, false);
-            this.log(`Successfully posted ${batchToPost.length} screenshots. Response: ${result.data}`);
-          } catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            this.log(`Failed to post screenshots: ${message}`, "error" /* ERROR */);
-          }
-        })();
-        this.inFlightPost = post;
-        await post;
-        if (this.inFlightPost === post) this.inFlightPost = null;
-      }
+      if (!this.isSessionActive || !this.apiClient || !this.currentSessionId) return;
+      if (this.screenshotQueue.length === 0 && this.timeline.pendingEvents <= MAX_EVENTS_PER_UPLOAD) return;
+      const batch = this.screenshotQueue.splice(0, Math.min(this.screenshotQueue.length, this.postBatchSize()));
+      const events = batch.length > 0 ? this.timeline.eventsForUpload(Math.max(...batch.map((s) => s.offsetMs))) : this.timeline.takeEvents();
+      const apiClient = this.apiClient;
+      const sessionId = this.currentSessionId;
+      this.log(`Posting ${batch.length} screenshots and ${events?.length ?? 0} events...`);
+      const post = (async () => {
+        try {
+          const result = await apiClient.postScreenshots(sessionId, batch.map((s) => s.blob), false, {
+            offsetsMs: batch.map((s) => s.offsetMs),
+            events
+          });
+          this.log(`Successfully posted ${batch.length} screenshots and ${events?.length ?? 0} events. Response: ${result.data}`);
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          this.log(`Failed to post screenshots: ${message}`, "error" /* ERROR */);
+          this.requeueEvents(events ?? [], error, sessionId);
+        }
+      })();
+      this.inFlightPost = post;
+      await post;
+      if (this.inFlightPost === post) this.inFlightPost = null;
     }, this.config.screenshotPostIntervalSeconds * 1e3);
   }
+  /**
+   * Keeps events from an upload that may succeed if tried again (a network
+   * error or a 5xx), so the next upload carries them. A 4xx would fail the
+   * same way again, so those are dropped.
+   */
+  requeueEvents(events, error, sessionId) {
+    if (events.length === 0 || !this.isSessionActive || this.currentSessionId !== sessionId) return;
+    if (error instanceof SkillprintApiError && error.status < 500) return;
+    this.timeline.requeue(events);
+  }
   postBatchSize() {
     return Math.max(
       1,
@@ -1456,6 +1615,7 @@ var GenericCanvasSkillprintAdapter = class _GenericCanvasSkillprintAdapter {
   GameEvent,
   GenericCanvasSkillprintAdapter,
   LogLevel,
+  MAX_EVENTS_PER_UPLOAD,
   Mood,
   ParameterDefinition,
   ParameterInfo,
@@ -1465,6 +1625,7 @@ var GenericCanvasSkillprintAdapter = class _GenericCanvasSkillprintAdapter {
   PixiSkillprintAdapter,
   PollResultsResponse,
   ScreenshotUtility,
+  SessionTimeline,
   SkillprintAPIClient,
   SkillprintApiError,
   SkillprintConfig,
@@ -1473,6 +1634,7 @@ var GenericCanvasSkillprintAdapter = class _GenericCanvasSkillprintAdapter {
   StartSessionRequest,
   TelemetryEventRequest,
   ThreeSkillprintAdapter,
-  WebGLUrlParameterExtractor
+  WebGLUrlParameterExtractor,
+  isUniversalEvent
 });
 //# sourceMappingURL=index.cjs.map