jspsych-tangram 0.0.1

package/src/core/io/InteractionTracker.ts

@@ -0,0 +1,742 @@
+/**
+ * InteractionTracker - Event accumulation and data tracking for experiments
+ *
+ * This class listens to game controller events and builds structured data
+ * according to the data-tracking.ts schema. It generates InteractionEvent
+ * objects and accumulates TrialEndData for export.
+ *
+ * ## Key Responsibilities
+ * - Track interaction lifecycle (pickup → placedown)
+ * - Accumulate click events and mouse tracking between interactions
+ * - Generate InteractionEvent objects with state snapshots
+ * - Build TrialEndData on trial completion
+ * - Call onInteraction/onTrialEnd callbacks for data export
+ *
+ * ## Architecture
+ * ```
+ * User Interaction
+ *   ↓
+ * UI Controllers (drag/click)
+ *   ↓
+ * BaseGameController Events
+ *   ↓
+ * InteractionTracker
+ *   ↓
+ * onInteraction(event) → socket.emit()
+ * onTrialEnd(data) → socket.emit()
+ * ```
+ */
+
+import { v4 as uuidv4 } from 'uuid';
+import type { BaseGameController } from '../engine/state/BaseGameController';
+import { boundsOfBlueprint, piecePolysAt } from '../engine/geometry';
+import { CONFIG } from '../config/config';
+import type {
+  InteractionEvent,
+  StateSnapshot,
+  ConstructionTrialData,
+  PrepTrialData,
+  DataTrackingCallbacks,
+  SectorSnapshot,
+  PieceSnapshot,
+  MacroSnapshot
+} from './data-tracking';
+
+/**
+ * Pickup event data (temporary storage until placedown)
+ */
+interface PickupData {
+  pieceId: string;
+  blueprintId: string;
+  blueprintType: 'primitive' | 'composite';
+  timestamp: number;
+  source: 'blueprint' | 'sector';
+  sectorId: string | undefined;
+  position: { x: number; y: number };
+  vertices: number[][][];
+}
+
+/**
+ * Click event data (accumulated until interaction completes)
+ */
+interface ClickEventData {
+  timestamp: number;
+  location: { x: number; y: number };
+  clickType: 'blueprint_view_switch' | 'invalid_placement' | 'sector_complete_attempt';
+  blueprintViewSwitch?: {
+    from: 'quickstash' | 'primitives';
+    to: 'quickstash' | 'primitives';
+  };
+  invalidPlacement?: {
+    reason: 'overlapping' | 'outside_bounds' | 'no_valid_anchor' | 'sector_complete';
+    attemptedSectorId?: string;
+  };
+}
+
+/**
+ * Mouse tracking event data (accumulated until interaction completes)
+ */
+interface MouseTrackingData {
+  timestamp: number;
+  anchorX: number;
+  anchorY: number;
+  sectorId: string | undefined;
+  phase: 'before_pickup' | 'while_holding';
+}
+
+/**
+ * InteractionTracker - Main tracking class
+ */
+export class InteractionTracker {
+  // IDs
+  private gameId: string;
+  private trialId: string;
+
+  // Callbacks
+  private callbacks: DataTrackingCallbacks;
+
+  // Controller reference
+  private controller: BaseGameController;
+
+  // Trial timing
+  private trialStartTime: number;
+  private readonly gridStep: number = CONFIG.layout.grid.stepPx;
+
+  // Interaction state
+  private interactionIndex: number = 0;
+  private currentPickup: PickupData | null = null;
+  private previousSnapshotId: string | undefined = undefined;
+
+  // Event accumulation (reset after each interaction)
+  private clickEvents: ClickEventData[] = [];
+  private mouseTracking: MouseTrackingData[] = [];
+
+  // Interaction history (for TrialEndData)
+  private interactions: InteractionEvent[] = [];
+
+  // Construction-specific tracking
+  private completionTimes: Array<{ sectorId: string; completedAt: number }> = [];
+
+  // Prep-specific tracking
+  private createdMacros: MacroSnapshot[] = [];
+
+  constructor(
+    controller: BaseGameController,
+    callbacks: DataTrackingCallbacks,
+    trialId?: string,
+    gameId?: string
+  ) {
+    this.controller = controller;
+    this.callbacks = callbacks;
+    this.trialId = trialId || uuidv4();
+    this.gameId = gameId || uuidv4();
+    this.trialStartTime = Date.now();
+
+    // Register tracking callbacks with controller
+    this.controller.setTrackingCallbacks({
+      onSectorCompleted: (sectorId) => this.recordSectorCompletion(sectorId)
+    });
+  }
+
+  /**
+   * Cleanup method to unregister from controller
+   */
+  dispose(): void {
+    this.controller.setTrackingCallbacks(null);
+  }
+
+  // ===== Event Recording Methods =====
+  // Called by UI controllers to record events
+
+  /**
+   * Record piece pickup event
+   */
+  recordPickup(
+    pieceId: string,
+    blueprintId: string,
+    blueprintType: 'primitive' | 'composite',
+    source: 'blueprint' | 'sector',
+    position: { x: number; y: number },
+    vertices: number[][][],
+    sectorId?: string
+  ): void {
+    const anchorPosition = this.toAnchorPoint(position);
+    const anchorVertices = this.toAnchorVertices(vertices);
+
+    this.currentPickup = {
+      pieceId,
+      blueprintId,
+      blueprintType,
+      timestamp: Date.now(),
+      source,
+      sectorId,
+      position: anchorPosition,
+      vertices: anchorVertices
+    };
+
+    // Mark all subsequent mouse tracking as "while_holding"
+    // (UI controllers should call recordMouseMove after this)
+  }
+
+  /**
+   * Record piece placedown event
+   */
+  recordPlacedown(
+    outcome: 'placed' | 'deleted',
+    sectorId?: string,
+    position?: { x: number; y: number },
+    vertices?: number[][][],
+    anchorId?: string,
+    wasValid?: boolean,
+    wasOverlapping?: boolean,
+    completedSector?: boolean
+  ): void {
+    if (!this.currentPickup) {
+      console.warn('[InteractionTracker] recordPlacedown called without pickup');
+      return;
+    }
+
+    const interactionType = this.determineInteractionType(this.currentPickup.source, outcome);
+    const placedownTimestamp = Date.now();
+    const holdDuration = placedownTimestamp - this.currentPickup.timestamp;
+
+    // Build post-interaction snapshot
+    // If this placement completes a sector, mark it in the snapshot
+    const postSnapshot = this.buildStateSnapshot(completedSector ? sectorId : undefined);
+
+    const anchorPosition = position ? this.toAnchorPoint(position) : undefined;
+    const anchorVertices = vertices ? this.toAnchorVertices(vertices) : undefined;
+
+    // Create interaction event - build incrementally to satisfy exactOptionalPropertyTypes
+    const event: InteractionEvent = {
+      // Metadata
+      interactionId: uuidv4(),
+      trialId: this.trialId,
+      gameId: this.gameId,
+      interactionIndex: this.interactionIndex++,
+
+      // Interaction type
+      interactionType,
+
+      // Piece information
+      pieceId: this.currentPickup.pieceId,
+      blueprintId: this.currentPickup.blueprintId,
+      blueprintType: this.currentPickup.blueprintType,
+
+      // Pickup event
+      pickupTimestamp: this.currentPickup.timestamp,
+      pickupSource: this.currentPickup.source,
+      pickupSectorId: this.currentPickup.sectorId,
+      pickupPosition: this.currentPickup.position,
+      pickupVertices: this.currentPickup.vertices,
+
+      // Placedown event
+      placedownTimestamp,
+      placedownOutcome: outcome,
+
+      // Validation context
+      wasValid: outcome === 'placed' && wasValid === true,
+      wasOverlapping: outcome === 'placed' && wasOverlapping === true,
+
+      // Timing
+      holdDuration,
+
+      // Events
+      clickEvents: [...this.clickEvents],
+      mouseTracking: [...this.mouseTracking],
+
+      // Snapshots
+      postSnapshot
+    };
+
+    // Add optional placedown properties based on outcome
+    if (outcome === 'placed' && sectorId) {
+      event.placedownSectorId = sectorId;
+    }
+    if (outcome === 'placed' && anchorPosition) {
+      event.placedownPosition = anchorPosition;
+    }
+    if (outcome === 'placed' && anchorVertices) {
+      event.placedownVertices = anchorVertices;
+    }
+    if (anchorId) {
+      event.placedownAnchorId = anchorId;
+    }
+    if (this.previousSnapshotId !== undefined) {
+      event.preSnapshotId = this.previousSnapshotId;
+    }
+
+    // Store for trial end data
+    this.interactions.push(event);
+    this.previousSnapshotId = postSnapshot.snapshotId;
+
+    // Call interaction callback
+    if (this.callbacks.onInteraction) {
+      this.callbacks.onInteraction(event);
+    }
+
+    // Reset interaction state
+    this.currentPickup = null;
+    this.clickEvents = [];
+    this.mouseTracking = [];
+  }
+
+  /**
+   * Record click event
+   */
+  recordClickEvent(
+    location: { x: number; y: number },
+    clickType: 'blueprint_view_switch' | 'invalid_placement' | 'sector_complete_attempt',
+    metadata?: {
+      blueprintViewSwitch?: { from: 'quickstash' | 'primitives'; to: 'quickstash' | 'primitives' };
+      invalidPlacement?: { reason: 'overlapping' | 'outside_bounds' | 'no_valid_anchor' | 'sector_complete'; attemptedSectorId?: string };
+    }
+  ): void {
+    const anchorLocation = this.toAnchorPoint(location);
+
+    this.clickEvents.push({
+      timestamp: Date.now(),
+      location: anchorLocation,
+      clickType,
+      ...metadata
+    });
+  }
+
+  /**
+   * Record mouse movement to different anchor
+   */
+  recordMouseMove(
+    anchorX: number,
+    anchorY: number,
+    sectorId?: string
+  ): void {
+    const phase: 'before_pickup' | 'while_holding' = this.currentPickup ? 'while_holding' : 'before_pickup';
+    const anchorCoordX = this.toAnchorValue(anchorX);
+    const anchorCoordY = this.toAnchorValue(anchorY);
+
+    // Only record if anchor position changed
+    const lastTracking = this.mouseTracking[this.mouseTracking.length - 1];
+    if (lastTracking && lastTracking.anchorX === anchorCoordX && lastTracking.anchorY === anchorCoordY) {
+      return; // Same position, skip
+    }
+
+    this.mouseTracking.push({
+      timestamp: Date.now(),
+      anchorX: anchorCoordX,
+      anchorY: anchorCoordY,
+      sectorId,
+      phase
+    });
+  }
+
+  /**
+   * Record sector completion
+   */
+  recordSectorCompletion(sectorId: string): void {
+    this.completionTimes.push({
+      sectorId,
+      completedAt: Date.now()
+    });
+  }
+
+  /**
+   * Record macro creation (prep mode only)
+   */
+  recordMacroCreation(macro: MacroSnapshot): void {
+    this.createdMacros.push(macro);
+  }
+
+  // ===== Trial Completion =====
+
+  /**
+   * Finalize trial and call onTrialEnd callback
+   */
+  finalizeTrial(endReason: 'timeout' | 'auto_complete' | 'submit'): void {
+    const trialEndTime = Date.now();
+    const totalDuration = trialEndTime - this.trialStartTime;
+    const finalSnapshot = this.buildStateSnapshot();
+
+    const mode = this.controller.state.cfg.mode;
+
+    if (mode === 'construction') {
+      const finalBlueprintState = this.buildFinalBlueprintState(finalSnapshot);
+      
+      // Extract composites as quickstash macros (ready for next trial input)
+      const quickstashMacros = finalBlueprintState
+        .filter(bp => bp.blueprintType === 'composite')
+        .map(bp => ({
+          id: bp.blueprintId,
+          parts: bp.parts!,  // Composites always have parts
+          ...(bp.label && { label: bp.label })
+        }));
+
+      const data: ConstructionTrialData = {
+        trialType: 'construction',
+        trialId: this.trialId,
+        gameId: this.gameId,
+        trialNum: 0, // TODO: Plugin should provide this
+        trialStartTime: this.trialStartTime,
+        trialEndTime,
+        totalDuration,
+        endReason: endReason as 'timeout' | 'auto_complete',
+        completionTimes: this.completionTimes,
+        finalBlueprintState,
+        quickstashMacros,
+        finalSnapshot
+      };
+
+      if (this.callbacks.onTrialEnd) {
+        this.callbacks.onTrialEnd(data);
+      }
+    } else {
+      const finalMacros = this.createdMacros.length
+        ? this.createdMacros
+        : this.buildMacrosFromSnapshot(finalSnapshot);
+
+      // Convert MacroSnapshot to quickstash input format
+      // Ensure IDs start with "comp:" for proper border rendering
+      const quickstashMacros = finalMacros.map(macro => ({
+        id: macro.macroId.startsWith('comp:') ? macro.macroId : `comp:${macro.macroId}`,
+        parts: macro.parts
+        // Note: label not included in prep macros
+      }));
+
+      const data: PrepTrialData = {
+        trialType: 'prep',
+        trialId: this.trialId,
+        gameId: this.gameId,
+        trialNum: 0, // TODO: Plugin should provide this
+        trialStartTime: this.trialStartTime,
+        trialEndTime,
+        totalDuration,
+        endReason: 'submit',
+        createdMacros: finalMacros,
+        quickstashMacros,
+        finalSnapshot
+      };
+
+      if (this.callbacks.onTrialEnd) {
+        this.callbacks.onTrialEnd(data);
+      }
+    }
+  }
+
+  // ===== Helper Methods =====
+
+  /**
+   * Determine interaction type from source and outcome
+   */
+  private determineInteractionType(
+    source: 'blueprint' | 'sector',
+    outcome: 'placed' | 'deleted'
+  ): 'spawn' | 'move' | 'delete' {
+    if (outcome === 'deleted') return 'delete';
+    if (source === 'blueprint') return 'spawn';
+    return 'move';
+  }
+
+  private toAnchorValue(value: number): number {
+    return Math.round(value / this.gridStep);
+  }
+
+  private toAnchorPoint(point: { x: number; y: number }): { x: number; y: number } {
+    return { x: this.toAnchorValue(point.x), y: this.toAnchorValue(point.y) };
+  }
+
+  private toAnchorVertices(vertices: number[][][]): number[][][] {
+    return vertices.map(ring =>
+      ring.map(vertex => [
+        this.toAnchorValue(vertex[0]!),
+        this.toAnchorValue(vertex[1]!)
+      ])
+    );
+  }
+
+  private buildMacrosFromSnapshot(snapshot: StateSnapshot): MacroSnapshot[] {
+    return snapshot.sectors.map(sec => {
+      // STEP 1: Convert bbox positions to shape origin positions in anchor coordinates
+      const shapeOriginPositions = sec.pieces.map(piece => {
+        const bp = this.controller.getBlueprint(piece.blueprintId);
+        const kind = bp && 'kind' in bp ? bp.kind : piece.blueprintId;
+        
+        // Get the piece's actual position in pixels from controller state
+        const actualPiece = this.controller.findPiece(piece.pieceId);
+        if (!actualPiece || !bp) {
+          return {
+            kind,
+            position: piece.position  // Fallback to bbox position
+          };
+        }
+        
+        // Get bounding box of the blueprint using the geometry helper
+        const bb = boundsOfBlueprint(bp, this.controller.getPrimitive);
+        
+        // Convert bbox position to shape origin position
+        // In pixels: shapeOriginPos = piece.pos - bb.min
+        // Then convert to anchor coordinates
+        const shapeOriginPixels = {
+          x: actualPiece.pos.x - bb.min.x,
+          y: actualPiece.pos.y - bb.min.y
+        };
+        const shapeOriginAnchor = this.toAnchorPoint(shapeOriginPixels);
+        
+        return {
+          kind,
+          position: shapeOriginAnchor  // Shape origin in anchor coordinates
+        };
+      });
+
+      // STEP 2: Calculate centroid and convert to relative offsets
+      if (shapeOriginPositions.length === 0) {
+        return {
+          macroId: sec.sectorId,
+          parts: [],
+          shape: [],
+          pieceCount: 0
+        };
+      }
+
+      // Calculate centroid of all pieces (in anchor coordinates)
+      let sumX = 0, sumY = 0;
+      for (const item of shapeOriginPositions) {
+        sumX += item.position.x;
+        sumY += item.position.y;
+      }
+      const centroidX = Math.round(sumX / shapeOriginPositions.length);
+      const centroidY = Math.round(sumY / shapeOriginPositions.length);
+
+      // Convert absolute positions to relative offsets (like ANCHOR_COMPOSITES format)
+      const parts = shapeOriginPositions.map(item => ({
+        kind: item.kind,
+        anchorOffset: {
+          x: Math.round(item.position.x - centroidX),
+          y: Math.round(item.position.y - centroidY)
+        }
+      }));
+
+      const shape = sec.pieces.flatMap(piece => piece.vertices || []);
+
+      return {
+        macroId: sec.sectorId,
+        parts,
+        shape,
+        pieceCount: sec.pieceCount
+      };
+    });
+  }
+
+  /**
+   * Build state snapshot from current controller state
+   * @param justCompletedSectorId - Sector ID that was just completed (but controller state hasn't updated yet)
+   */
+  private buildStateSnapshot(justCompletedSectorId?: string): StateSnapshot {
+    const snapshotId = uuidv4();
+    const timestamp = Date.now();
+
+    // Build sector snapshots
+    const sectors: SectorSnapshot[] = [];
+    const completedSectorIds: string[] = [];
+
+    for (const sector of this.controller.state.cfg.sectors) {
+      const sectorState = this.controller.state.sectors[sector.id];
+      // Check if this sector was just completed OR is already completed
+      const completed = sector.id === justCompletedSectorId || !!sectorState?.completedAt;
+
+      if (completed) {
+        completedSectorIds.push(sector.id);
+      }
+
+      const pieces: PieceSnapshot[] = (sectorState?.pieces || []).map(p => ({
+        pieceId: p.id,
+        blueprintId: p.blueprintId,
+        blueprintType: this.getBlueprintType(p.blueprintId),
+        position: this.toAnchorPoint(p.pos),
+        vertices: this.getPieceVertices(p.id)
+      }));
+
+      const snapshot: SectorSnapshot = {
+        sectorId: sector.id,
+        completed,
+        pieceCount: pieces.length,
+        pieces
+      };
+
+      if (sectorState?.completedAt !== undefined) {
+        snapshot.completedAt = sectorState.completedAt;
+      }
+
+      sectors.push(snapshot);
+    }
+
+    // Build sector-tangram map
+    const sectorTangramMap = this.controller.state.cfg.sectors.map(s => ({
+      sectorId: s.id,
+      tangramId: s.id // In our system, sector ID == tangram ID
+    }));
+
+    // Build blueprint order
+    const blueprintOrder = {
+      primitives: this.controller.state.primitives.map(bp => bp.id),
+      quickstash: this.controller.state.quickstash.map(bp => bp.id)
+    };
+
+    return {
+      snapshotId,
+      timestamp,
+      sectors,
+      completedSectorIds,
+      sectorTangramMap,
+      blueprintOrder
+    };
+  }
+
+  /**
+   * Get blueprint type from blueprint ID
+   */
+  private getBlueprintType(blueprintId: string): 'primitive' | 'composite' {
+    const bp = this.controller.getBlueprint(blueprintId);
+    if (!bp) return 'primitive'; // Fallback
+    return 'kind' in bp ? 'primitive' : 'composite';
+  }
+
+  /**
+   * Get piece vertices in world space
+   */
+  private getPieceVertices(pieceId: string): number[][][] {
+    const piece = this.controller.findPiece(pieceId);
+    if (!piece) return [];
+
+    const bp = this.controller.getBlueprint(piece.blueprintId);
+    if (!bp) return [];
+
+    const bb = boundsOfBlueprint(bp, (k) => this.controller.getPrimitive(k));
+    const polys = piecePolysAt(bp, bb, piece.pos) ?? [];
+    const asNumbers = polys.map(ring => ring.map(pt => [pt.x, pt.y] as [number, number]));
+    return this.toAnchorVertices(asNumbers);
+  }
+
+  /**
+   * Build final blueprint state (usage counts + definitions)
+   */
+  private buildFinalBlueprintState(snapshot: StateSnapshot): Array<{
+    blueprintId: string;
+    blueprintType: 'primitive' | 'composite';
+    totalPieces: number;
+    bySector: Array<{ sectorId: string; count: number }>;
+    parts?: Array<{ kind: string; anchorOffset: { x: number; y: number } }>;
+    shape?: Array<Array<{ x: number; y: number }>>;
+    label?: string;
+  }> {
+    const counts = new Map<string, {
+      blueprintType: 'primitive' | 'composite';
+      totalPieces: number;
+      bySector: Map<string, number>;
+    }>();
+
+    // Accumulate counts
+    for (const sector of snapshot.sectors) {
+      for (const piece of sector.pieces) {
+        if (!counts.has(piece.blueprintId)) {
+          counts.set(piece.blueprintId, {
+            blueprintType: piece.blueprintType,
+            totalPieces: 0,
+            bySector: new Map()
+          });
+        }
+
+        const entry = counts.get(piece.blueprintId)!;
+        entry.totalPieces++;
+        entry.bySector.set(sector.sectorId, (entry.bySector.get(sector.sectorId) || 0) + 1);
+      }
+    }
+
+    // Ensure all primitives are represented, even if count is zero
+    for (const primitive of this.controller.state.primitives) {
+      if (!counts.has(primitive.id)) {
+        counts.set(primitive.id, {
+          blueprintType: 'primitive',
+          totalPieces: 0,
+          bySector: new Map()
+        });
+      }
+    }
+
+    // Ensure all composites are represented, even if count is zero
+    for (const composite of this.controller.state.quickstash) {
+      if (!counts.has(composite.id)) {
+        counts.set(composite.id, {
+          blueprintType: 'composite',
+          totalPieces: 0,
+          bySector: new Map()
+        });
+      }
+    }
+
+    // Convert to array format with blueprint definitions
+    return Array.from(counts.entries()).map(([blueprintId, data]) => {
+      const blueprint = this.controller.getBlueprint(blueprintId);
+      
+      const result: {
+        blueprintId: string;
+        blueprintType: 'primitive' | 'composite';
+        totalPieces: number;
+        bySector: Array<{ sectorId: string; count: number }>;
+        parts?: Array<{ kind: string; anchorOffset: { x: number; y: number } }>;
+        shape?: Array<Array<{ x: number; y: number }>>;
+        label?: string;
+      } = {
+        blueprintId,
+        blueprintType: data.blueprintType,
+        totalPieces: data.totalPieces,
+        bySector: Array.from(data.bySector.entries()).map(([sectorId, count]) => ({
+          sectorId,
+          count
+        }))
+      };
+
+      // Add blueprint definition for both primitives and composites
+      if (blueprint) {
+        if (data.blueprintType === 'composite' && 'parts' in blueprint) {
+          // Composite blueprint: convert pixel-based parts to anchor-based parts
+          result.parts = blueprint.parts.map(part => ({
+            kind: part.kind,
+            anchorOffset: {
+              x: Math.round(part.offset.x / this.gridStep),
+              y: Math.round(part.offset.y / this.gridStep)
+            }
+          }));
+
+          // Convert pixel-based shape to anchor-based shape
+          if (blueprint.shape) {
+            result.shape = blueprint.shape.map(poly => 
+              poly.map(vertex => ({
+                x: Math.round(vertex.x / this.gridStep),
+                y: Math.round(vertex.y / this.gridStep)
+              }))
+            );
+          }
+
+          // Add label if available
+          if (blueprint.label) {
+            result.label = blueprint.label;
+          }
+        } else if (data.blueprintType === 'primitive' && 'kind' in blueprint) {
+          // Primitive blueprint: convert pixel-based shape to anchor-based shape
+          if (blueprint.shape) {
+            result.shape = blueprint.shape.map(poly => 
+              poly.map(vertex => ({
+                x: Math.round(vertex.x / this.gridStep),
+                y: Math.round(vertex.y / this.gridStep)
+              }))
+            );
+          }
+
+          // Primitives don't have labels, but we could add a default one based on kind
+          result.label = blueprint.kind;
+        }
+      }
+
+      return result;
+    });
+  }
+}