jspsych-tangram 0.0.8 → 0.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jspsych-tangram",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "Tangram tasks for jsPsych: prep and construct.",
   "type": "module",
   "main": "dist/index.cjs",

package/src/assets/README.md

@@ -0,0 +1,6 @@
+# Assets Directory
+
+- `locked.png` - Icon displayed when quickstash view is active (locked to quickstash only)
+- `unlocked.png` - Icon displayed when primitives view is active (unlocked/full inventory)
+
+These icons appear in the center badge button that switches between blueprint views.

package/src/assets/images.d.ts

@@ -0,0 +1,19 @@
+declare module "*.png" {
+  const value: string;
+  export default value;
+}
+
+declare module "*.jpg" {
+  const value: string;
+  export default value;
+}
+
+declare module "*.jpeg" {
+  const value: string;
+  export default value;
+}
+
+declare module "*.svg" {
+  const value: string;
+  export default value;
+}

package/src/core/components/board/BoardView.tsx

@@ -5,6 +5,10 @@ import { boundsOfBlueprint, placeSilhouetteGridAlignedAsPolys } from "@/core/eng
 import { CONFIG } from "@/core/config/config";
 import { generateEdgeStrokePaths, shouldUseSelectiveBorders, shouldShowBorders, getHiddenEdgesForPolygon } from "@/core/engine/validation/border-rendering";
 
+// Import lock/unlock icons
+import lockedIcon from "@/assets/locked.png";
+import unlockedIcon from "@/assets/unlocked.png";
+
 export type PieceView = { id: string; blueprintId: string; x: number; y: number; sectorId?: string };
 export type AnchorDots = { sectorId: string; valid: {x:number;y:number}[]; invalid: {x:number;y:number}[] };
 
@@ -89,12 +93,12 @@ export default function BoardView(props: BoardViewProps) {
     : CONFIG.layout.constraints.quickstashDiamAnchors;
   const D_slot = anchorsDiameterToPx(reqAnchors);
   const R_needed = D_slot / (2 * Math.max(1e-9, Math.sin(delta / 2)));
-  
+
   // Minimum radius to avoid overlapping with badge
   // Badge takes up: badgeR + margin, plus we need half the slot diameter for clearance
   const R_min = badgeR + CONFIG.size.centerBadge.marginPx + D_slot / 2;
   const ringMax = layout.innerR - (badgeR + CONFIG.size.centerBadge.marginPx);
-  
+
   // Clamp to [R_min, ringMax]
   const blueprintRingR = Math.min(Math.max(R_needed, R_min), ringMax);
 
@@ -195,7 +199,7 @@ export default function BoardView(props: BoardViewProps) {
                     stroke="none"
                     onPointerDown={(e) => onPiecePointerDown(e, p)}
                   />
-                  
+
                   {/* Border paths - only rendered if borders are enabled */}
                   {showBorders && (
                     useSelectiveBorders ? (
@@ -205,32 +209,32 @@ export default function BoardView(props: BoardViewProps) {
                         const pieceAsPiece = { ...p, pos: { x: p.x, y: p.y } };
                         const allPiecesAsPieces = allPiecesInSector.map(piece => ({ ...piece, pos: { x: piece.x, y: piece.y } }));
                         const hiddenEdges = getHiddenEdgesForPolygon(pieceAsPiece, idx, allPiecesAsPieces, (id) => controller.getBlueprint(id), (kind) => controller.getPrimitive(kind));
-                        
+
                         // Check if this piece's edges were hidden due to touching the dragged piece
                         const draggedPiece = draggingId ? allPiecesInSector.find(piece => piece.id === draggingId) : null;
-                        
+
                         // For composites, we need to distinguish between internal edges (always hidden) and external edges (shown when dragging)
                         let wasTouchingDraggedPiece: boolean[];
                         if (p.blueprintId.startsWith('comp:')) {
                           // For composites, check internal edges separately from external edges
                           const internalHiddenEdges = getHiddenEdgesForPolygon(pieceAsPiece, idx, [], (id) => controller.getBlueprint(id), (kind) => controller.getPrimitive(kind));
-                          const externalHiddenEdges = draggedPiece ? 
-                            getHiddenEdgesForPolygon(pieceAsPiece, idx, [{ ...draggedPiece, pos: { x: draggedPiece.x, y: draggedPiece.y } }], (id) => controller.getBlueprint(id), (kind) => controller.getPrimitive(kind)) : 
+                          const externalHiddenEdges = draggedPiece ?
+                            getHiddenEdgesForPolygon(pieceAsPiece, idx, [{ ...draggedPiece, pos: { x: draggedPiece.x, y: draggedPiece.y } }], (id) => controller.getBlueprint(id), (kind) => controller.getPrimitive(kind)) :
                             new Array(hiddenEdges.length).fill(false);
-                          
+
                           // Only consider external edges as "touching dragged piece"
                           wasTouchingDraggedPiece = externalHiddenEdges.map((external, i) => external && !internalHiddenEdges[i]);
                         } else {
                           // For primitives, all hidden edges are external
-                          wasTouchingDraggedPiece = draggedPiece ? 
-                            getHiddenEdgesForPolygon(pieceAsPiece, idx, [{ ...draggedPiece, pos: { x: draggedPiece.x, y: draggedPiece.y } }], (id) => controller.getBlueprint(id), (kind) => controller.getPrimitive(kind)) : 
+                          wasTouchingDraggedPiece = draggedPiece ?
+                            getHiddenEdgesForPolygon(pieceAsPiece, idx, [{ ...draggedPiece, pos: { x: draggedPiece.x, y: draggedPiece.y } }], (id) => controller.getBlueprint(id), (kind) => controller.getPrimitive(kind)) :
                             new Array(hiddenEdges.length).fill(false);
                         }
-                        
+
                         return generateEdgeStrokePaths(poly).map((strokePath, strokeIdx) => {
                           // Show border if: 1) it wasn't hidden originally, OR 2) it was hidden due to touching the dragged piece
                           const wasHiddenDueToDraggedPiece = wasTouchingDraggedPiece[strokeIdx] || false;
-                          
+
                           // Special case: if this piece is being dragged and it's a composite, keep internal edges hidden
                           let isHidden: boolean;
                           if (isDragging && p.blueprintId.startsWith('comp:')) {
@@ -241,7 +245,7 @@ export default function BoardView(props: BoardViewProps) {
                             // Normal logic for non-dragged pieces or primitives
                             isHidden = isDragging ? false : ((hiddenEdges[strokeIdx] || false) && !wasHiddenDueToDraggedPiece);
                           }
-                          
+
                           return (
                             <path
                               key={`stroke-${idx}-${strokeIdx}`}
@@ -275,16 +279,16 @@ export default function BoardView(props: BoardViewProps) {
       {/* silhouettes (use pre-placed polys) */}
       {layout.sectors.map((s) => {
         const sectorCfg = controller.state.cfg.sectors.find((ss: any) => ss.id === s.id);
-        
+
         // Check if we should render decomposed primitives
         if (showTangramDecomposition && sectorCfg?.silhouette.primitiveDecomposition) {
           const primitiveDecomposition = sectorCfg.silhouette.primitiveDecomposition;
-          
+
           // Use same positioning logic as unified silhouette
           const rect = rectForBand(layout, s, "silhouette", 1.0);
           const rawPolys = primitiveDecomposition.map((primInfo: any) => primInfo.polygon);
           const placedPolys = placeSilhouetteGridAlignedAsPolys(rawPolys, scaleS, { cx: rect.cx, cy: rect.cy });
-          
+
           return (
             <g key={`sil-decomposed-${s.id}`} pointerEvents="none">
               {placedPolys.map((scaledPoly, i) => (
@@ -296,7 +300,7 @@ export default function BoardView(props: BoardViewProps) {
                     opacity={CONFIG.opacity.silhouetteMask}
                     stroke="none"
                   />
-                  
+
                   {/* Full perimeter border */}
                   <path
                     d={pathD(scaledPoly)}
@@ -344,26 +348,65 @@ export default function BoardView(props: BoardViewProps) {
         );
       })}
 
+      {/* SVG filter for inverting icon colors to white */}
+      <defs>
+        <filter id="invert-to-white">
+          <feColorMatrix
+            type="matrix"
+            values="-1 0 0 0 1
+                     0 -1 0 0 1
+                     0 0 -1 0 1
+                     0 0 0 1 0"
+          />
+        </filter>
+      </defs>
+
       {/* center badge */}
       {(() => {
         const isPrep = controller.state.cfg.mode === "prep";
         const isSubmitEnabled = isPrep ? controller.isSubmitEnabled() : true;
         const isClickable = !draggingId && (!isPrep || isSubmitEnabled);
-        
+        const [imageError, setImageError] = React.useState(false);
+
+        // Size the image to fill most of the badge (80% of diameter)
+        const iconSize = badgeR * 1.6;
+        const iconOffset = iconSize / 2;
+
         return (
-          <g transform={`translate(${badgeCenter.x}, ${badgeCenter.y})`} 
-             style={{ cursor: isClickable ? "pointer" : "default" }} 
+          <g transform={`translate(${badgeCenter.x}, ${badgeCenter.y})`}
+             style={{ cursor: isClickable ? "pointer" : "default" }}
              onPointerDown={isClickable ? onCenterBadgePointerDown : undefined}>
-            <circle r={badgeR} 
-                    fill={isSubmitEnabled ? CONFIG.color.blueprint.badgeFill : "#ccc"} 
+            <circle r={badgeR}
+                    fill={isSubmitEnabled ? CONFIG.color.blueprint.badgeFill : "#ccc"}
                     opacity={isSubmitEnabled ? 1.0 : 0.5} />
-            <text textAnchor="middle" 
-                  dominantBaseline="middle" 
-                  fontSize={CONFIG.size.badgeFontPx} 
-                  fill={isSubmitEnabled ? CONFIG.color.blueprint.labelFill : "#888"} 
-                  pointerEvents="none">
-              {isPrep ? "Submit" : controller.state.blueprintView}
-            </text>
+            {isPrep ? (
+              <text textAnchor="middle"
+                    dominantBaseline="middle"
+                    fontSize={CONFIG.size.badgeFontPx}
+                    fill={isSubmitEnabled ? CONFIG.color.blueprint.labelFill : "#888"}
+                    pointerEvents="none">
+                Submit
+              </text>
+            ) : imageError ? (
+              <text textAnchor="middle"
+                    dominantBaseline="middle"
+                    fontSize={CONFIG.size.badgeFontPx}
+                    fill={CONFIG.color.blueprint.labelFill}
+                    pointerEvents="none">
+                inventory
+              </text>
+            ) : (
+              <image
+                href={controller.state.blueprintView === "quickstash" ? lockedIcon : unlockedIcon}
+                x={-iconOffset}
+                y={-iconOffset}
+                width={iconSize}
+                height={iconSize}
+                pointerEvents="none"
+                onError={() => setImageError(true)}
+                filter="url(#invert-to-white)"
+              />
+            )}
           </g>
         );
       })()}

package/src/core/io/InteractionTracker.ts

@@ -351,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')
@@ -370,6 +376,7 @@ export class InteractionTracker {
         trialStartTime: this.trialStartTime,
         trialEndTime,
         totalDuration,
+        anchorToStimuliRatio,
         trialParams: this.trialParams,
         endReason: endReason as 'timeout' | 'auto_complete',
         completionTimes: this.completionTimes,
@@ -399,6 +406,7 @@ export class InteractionTracker {
         trialStartTime: this.trialStartTime,
         trialEndTime,
         totalDuration,
+        anchorToStimuliRatio,
         trialParams: this.trialParams,
         endReason: 'submit',
         createdMacros: finalMacros,
@@ -449,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) {
@@ -458,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
@@ -470,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
@@ -666,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';
@@ -699,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)
@@ -714,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

@@ -121,6 +121,9 @@ export interface BaseTrialData {
   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)