jspsych-tangram 0.0.7 → 0.0.9

package/src/core/io/InteractionTracker.ts

@@ -88,16 +88,15 @@ interface MouseTrackingData {
  * InteractionTracker - Main tracking class
  */
 export class InteractionTracker {
-  // IDs
-  private gameId: string;
-  private trialId: string;
-
   // Callbacks
   private callbacks: DataTrackingCallbacks;
 
   // Controller reference
   private controller: BaseGameController;
 
+  // Trial parameters
+  private trialParams: any;
+
   // Trial timing
   private trialStartTime: number;
   private readonly gridStep: number = CONFIG.layout.grid.stepPx;
@@ -123,13 +122,11 @@ export class InteractionTracker {
   constructor(
     controller: BaseGameController,
     callbacks: DataTrackingCallbacks,
-    trialId?: string,
-    gameId?: string
+    trialParams?: any
   ) {
     this.controller = controller;
     this.callbacks = callbacks;
-    this.trialId = trialId || uuidv4();
-    this.gameId = gameId || uuidv4();
+    this.trialParams = trialParams;
     this.trialStartTime = Date.now();
 
     // Register tracking callbacks with controller
@@ -211,8 +208,6 @@ export class InteractionTracker {
     const event: InteractionEvent = {
       // Metadata
       interactionId: uuidv4(),
-      trialId: this.trialId,
-      gameId: this.gameId,
       interactionIndex: this.interactionIndex++,
 
       // Interaction type
@@ -356,11 +351,17 @@ export class InteractionTracker {
     const totalDuration = trialEndTime - this.trialStartTime;
     const finalSnapshot = this.buildStateSnapshot();
 
+    // Calculate anchor to stimuli ratio (grid step in stimuli units)
+    // CONFIG.layout.grid.stepPx is the pixel size of one anchor unit
+    // CONFIG.layout.grid.unitPx is the pixel size of one stimuli unit (UNIT in tangram.py)
+    // So the ratio is stepPx / unitPx (typically 20 / 40 = 0.5)
+    const anchorToStimuliRatio = CONFIG.layout.grid.stepPx / CONFIG.layout.grid.unitPx;
+
     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')
@@ -372,12 +373,11 @@ export class InteractionTracker {
 
       const data: ConstructionTrialData = {
         trialType: 'construction',
-        trialId: this.trialId,
-        gameId: this.gameId,
-        trialNum: 0, // TODO: Plugin should provide this
         trialStartTime: this.trialStartTime,
         trialEndTime,
         totalDuration,
+        anchorToStimuliRatio,
+        trialParams: this.trialParams,
         endReason: endReason as 'timeout' | 'auto_complete',
         completionTimes: this.completionTimes,
         finalBlueprintState,
@@ -403,12 +403,11 @@ export class InteractionTracker {
 
       const data: PrepTrialData = {
         trialType: 'prep',
-        trialId: this.trialId,
-        gameId: this.gameId,
-        trialNum: 0, // TODO: Plugin should provide this
         trialStartTime: this.trialStartTime,
         trialEndTime,
         totalDuration,
+        anchorToStimuliRatio,
+        trialParams: this.trialParams,
         endReason: 'submit',
         createdMacros: finalMacros,
         quickstashMacros,
@@ -458,7 +457,7 @@ export class InteractionTracker {
       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) {
@@ -467,10 +466,10 @@ export class InteractionTracker {
             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
@@ -479,7 +478,7 @@ export class InteractionTracker {
           y: actualPiece.pos.y - bb.min.y
         };
         const shapeOriginAnchor = this.toAnchorPoint(shapeOriginPixels);
-        
+
         return {
           kind,
           position: shapeOriginAnchor  // Shape origin in anchor coordinates
@@ -675,7 +674,7 @@ export class InteractionTracker {
     // 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';
@@ -708,7 +707,7 @@ export class InteractionTracker {
 
           // Convert pixel-based shape to anchor-based shape
           if (blueprint.shape) {
-            result.shape = blueprint.shape.map(poly => 
+            result.shape = blueprint.shape.map(poly =>
               poly.map(vertex => ({
                 x: Math.round(vertex.x / this.gridStep),
                 y: Math.round(vertex.y / this.gridStep)
@@ -723,7 +722,7 @@ export class InteractionTracker {
         } 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 => 
+            result.shape = blueprint.shape.map(poly =>
               poly.map(vertex => ({
                 x: Math.round(vertex.x / this.gridStep),
                 y: Math.round(vertex.y / this.gridStep)

package/src/core/io/data-tracking.ts

@@ -16,8 +16,6 @@
 export interface InteractionEvent {
   // === Event Metadata ===
   interactionId: string;          // UUID for this interaction
-  trialId: string;                // UUID for the trial
-  gameId: string;                 // UUID for the game session
   interactionIndex: number;       // Sequential counter (0, 1, 2, ...) within the trial
 
   // === Interaction Type ===
@@ -118,16 +116,17 @@ export interface StateSnapshot {
  * Base trial data shared between construction and prep trials
  */
 export interface BaseTrialData {
-  // Trial identifiers
-  trialId: string;                // UUID for this trial
-  gameId: string;                 // UUID for game session
-  trialNum: number;               // Trial number in experiment sequence
-
   // Timing
   trialStartTime: number;         // Absolute timestamp (Date.now())
   trialEndTime: number;           // Absolute timestamp (Date.now())
   totalDuration: number;          // duration in ms (trialEndTime - trialStartTime)
 
+  // Coordinate system metadata
+  anchorToStimuliRatio: number;   // Ratio of anchor units to stimuli units (gridStepPx / unitPx)
+
+  // Parameters passed to the trial
+  trialParams: any;               // Cleaned jsPsych plugin parameters (excluding callbacks)
+
   // Final state snapshot
   finalSnapshot: StateSnapshot;
 }

package/src/plugins/tangram-construct/ConstructionApp.tsx

@@ -30,6 +30,8 @@ export interface StartConstructionTrialParams {
   input?: InputMode;
   layout?: LayoutMode;
   time_limit_ms: number;
+  show_tangram_decomposition?: boolean;
+  instructions?: string;
   onInteraction?: (event: any) => void;
   onTrialEnd?: (data: any) => void;
 }
@@ -72,11 +74,17 @@ export function startConstructionTrial(
       return isCanonical;
     });
 
-    const mask = filteredTans.map((tan: any, tanIndex: number) => {
+    const mask = filteredTans.map((tan: any) => {
       const polygon = tan.vertices.map(([x, y]: number[]) => ({ x: x ?? 0, y: -(y ?? 0) }));
       return polygon;
     });
 
+    // Store primitive decomposition for optional decomposition view
+    const primitiveDecomposition = filteredTans.map((tan: any) => ({
+      kind: (tan.name ?? tan.kind) as TanKind,
+      polygon: tan.vertices.map(([x, y]: number[]) => ({ x: x ?? 0, y: -(y ?? 0) }))
+    }));
+
     // Assign sector ID from alphabetical sequence
     const sectorId = `sector${index}`;
     
@@ -86,6 +94,7 @@ export function startConstructionTrial(
       silhouette: {
         id: sectorId,
         mask,
+        primitiveDecomposition,
       },
     };
 
@@ -116,6 +125,9 @@ export function startConstructionTrial(
   } else {
   }
 
+  // Extract non-callback params for trial data
+  const { onInteraction, onTrialEnd, ...trialParams } = params;
+
   // Create React root and render GameBoard
   const gameBoardProps = {
     sectors,
@@ -127,6 +139,9 @@ export function startConstructionTrial(
     timeLimitMs: params.time_limit_ms,
     maxQuickstashSlots: CONFIG.layout.defaults.maxQuickstashSlots,
     mode: 'construction' as const,
+    showTangramDecomposition: params.show_tangram_decomposition ?? false,
+    trialParams,
+    ...(params.instructions && { instructions: params.instructions }),
     ...(params.onInteraction && { onInteraction: params.onInteraction }),
     ...(params.onTrialEnd && { onTrialEnd: params.onTrialEnd })
   };

package/src/plugins/tangram-construct/index.ts

@@ -56,6 +56,18 @@ const info = {
       default: 18,
       description: "Snap radius for anchor-based piece placement"
     },
+    /** Whether to show tangram target shapes decomposed into individual primitives with borders */
+    show_tangram_decomposition: {
+      type: ParameterType.BOOL,
+      default: false,
+      description: "Whether to show tangram target shapes decomposed into individual primitives with borders"
+    },
+    /** HTML content to display above the gameboard as instructions */
+    instructions: {
+      type: ParameterType.STRING,
+      default: "",
+      description: "HTML content to display above the gameboard as instructions"
+    },
     /** Callback fired after each interaction (piece pickup + placedown) */
     onInteraction: {
       type: ParameterType.FUNCTION,
@@ -148,6 +160,8 @@ class TangramConstructPlugin implements JsPsychPlugin<Info> {
       input: trial.input,
       layout: trial.layout,
       time_limit_ms: trial.time_limit_ms,
+      show_tangram_decomposition: trial.show_tangram_decomposition,
+      instructions: trial.instructions,
       onInteraction: trial.onInteraction,
       onTrialEnd: wrappedOnTrialEnd
     };

package/src/plugins/tangram-prep/PrepApp.tsx

@@ -33,6 +33,7 @@ export interface StartPrepTrialParams {
   requireAllSlots: boolean;
   quickstashMacros?: AnchorComposite[];
   primitiveOrder: string[];
+  instructions?: string;
   onInteraction?: (event: any) => void;
   onTrialEnd?: (data: any) => void;
 }
@@ -59,6 +60,9 @@ export function startPrepTrial(
     onTrialEnd,
   } = params;
 
+  // Extract non-callback params for trial data
+  const { onInteraction: _, onTrialEnd: __, ...trialParams } = params;
+
   // make copy of PRIMITIVE_BLUEPRINTS sorted by primitiveOrder
   const PRIMITIVE_BLUEPRINTS_ORDERED = [...PRIMITIVE_BLUEPRINTS].sort((a, b) => primitiveOrder.indexOf(a.kind) - primitiveOrder.indexOf(b.kind));
 
@@ -180,6 +184,8 @@ export function startPrepTrial(
     mode: 'prep', // Enable prep-specific behavior
     minPiecesPerMacro: minPiecesPerMacro,
     requireAllSlots: requireAllSlots,
+    trialParams,
+    ...(params.instructions && { instructions: params.instructions }),
     onControllerReady: handleControllerReady,
     ...(onInteraction && { onInteraction }),
     ...(onTrialEnd && { onTrialEnd })

package/src/plugins/tangram-prep/index.ts

@@ -47,6 +47,12 @@ const info = {
       default: ["square", "smalltriangle", "parallelogram", "medtriangle", "largetriangle"],
       description: "Array of primitive names in the order they should be displayed"
     },
+    /** HTML content to display above the gameboard as instructions */
+    instructions: {
+      type: ParameterType.STRING,
+      default: undefined,
+      description: "HTML content to display above the gameboard as instructions"
+    },
     /** Callback fired after each interaction (optional analytics hook) */
     onInteraction: {
       type: ParameterType.FUNCTION,
@@ -115,6 +121,7 @@ class TangramPrepPlugin implements JsPsychPlugin<Info> {
       requireAllSlots: trial.require_all_slots,
       quickstashMacros: trial.quickstash_macros,
       primitiveOrder: trial.primitive_order,
+      instructions: trial.instructions,
       onInteraction: trial.onInteraction,
       onTrialEnd: wrappedOnTrialEnd,
     };