jspsych-tangram 0.0.12 → 0.0.13

package/src/core/components/pieces/BlueprintRing.tsx

@@ -1,23 +1,23 @@
 /**
  * BlueprintRing - Reusable blueprint selection interface component
- * 
+ *
  * This component provides the central blueprint selection interface that displays
  * available piece blueprints in a circular or semicircular arrangement around
  * a center badge. It handles both primitive pieces and quickstash macros.
- * 
+ *
  * ## Key Features
  * - **Dual Mode Display**: Switches between primitives and quickstash collections
- * - **Flexible Layout**: Adapts to circle and semicircle layout modes  
+ * - **Flexible Layout**: Adapts to circle and semicircle layout modes
  * - **Interactive Badge**: Center button to toggle between piece collections
  * - **Responsive Geometry**: Automatically calculates ring radius based on content
  * - **Event Integration**: Provides structured callbacks for piece selection
- * 
+ *
  * ## Architecture
  * - Pure presentation component (no internal state management)
  * - Receives all data and callbacks via props (dependency injection)
  * - Computes ring geometry based on layout constraints
  * - Renders SVG blueprint glyphs with proper scaling and positioning
- * 
+ *
  * ## Usage
  * Typically used within GameBoard or plugin components:
  * ```typescript
@@ -30,10 +30,10 @@
  *   onCenterBadgePointerDown={handleViewToggle}
  * />
  * ```
- * 
+ *
  * @see {@link GameBoard} Primary container that uses this component
  * @see {@link useBlueprintRing} Hook for managing blueprint ring state
- * @since Phase 3.3 - Extracted from monolithic Board component  
+ * @since Phase 3.3 - Extracted from monolithic Board component
  * @author Claude Code Assistant
  */
 
@@ -47,45 +47,94 @@ function pathD(poly: any[]) {
   return `M ${poly.map((pt: any) => `${pt.x} ${pt.y}`).join(" L ")} Z`;
 }
 
+/**
+ * Get the fill color for a blueprint based on its type
+ *
+ * REQUIRES: blueprint is valid, primitiveColorIndices is an array of 5 valid indices
+ * EFFECTS: Returns color based on primitive type if usePrimitiveColors is true,
+ *          otherwise returns the default color. Composites always use default color.
+ */
+function getBlueprintColor(
+  blueprint: Blueprint,
+  usePrimitiveColors: boolean,
+  defaultColor: string,
+  primitiveColorIndices: number[]
+): string {
+  if (!usePrimitiveColors) {
+    return defaultColor;
+  }
+
+  // For primitive blueprints, use the mapped color from CONFIG
+  if ('kind' in blueprint) {
+    const kind = blueprint.kind as TanKind;
+    // Map primitive kind to index: square=0, smalltriangle=1, parallelogram=2, medtriangle=3, largetriangle=4
+    const kindToIndex: Record<TanKind, number> = {
+      'square': 0,
+      'smalltriangle': 1,
+      'parallelogram': 2,
+      'medtriangle': 3,
+      'largetriangle': 4
+    };
+    const primitiveIndex = kindToIndex[kind];
+    if (primitiveIndex !== undefined && primitiveColorIndices[primitiveIndex] !== undefined) {
+      const colorIndex = primitiveColorIndices[primitiveIndex];
+      const color = CONFIG.color.primitiveColors[colorIndex];
+      if (color) {
+        return color;
+      }
+    }
+    return defaultColor;
+  }
+
+  // For composite blueprints, always use the default color
+  return defaultColor;
+}
+
 /**
  * Props interface for BlueprintRing component
- * 
+ *
  * This interface defines all the data and callbacks needed to render
  * the blueprint selection interface. All props use dependency injection.
  */
 export interface BlueprintRingProps {
   /** Array of primitive tangram piece blueprints */
   primitives: PrimitiveBlueprint[];
-  
+
   /** Array of quickstash/macro piece blueprints */
   quickstash: Blueprint[];
-  
-  /** 
+
+  /**
    * Current view mode for blueprint ring
    * - "primitives": Show primitive tangram pieces
    * - "quickstash": Show macro/composite pieces
    */
   currentView: "primitives" | "quickstash";
-  
+
   /** Computed circle layout containing geometry information */
   layout: CircleLayout;
-  
+
   /** Radius of the center toggle badge in pixels */
   badgeR: number;
-  
+
   /** Center position of the toggle badge */
   badgeCenter: { x: number; y: number };
-  
+
   /** Maximum number of quickstash slots to display */
   maxQuickstashSlots: number;
-  
+
   /** ID of currently dragging piece (null if none) - used for interaction state */
   draggingId: string | null;
-  
-  /** 
+
+  /** Whether to use distinct colors for each primitive shape type in blueprints */
+  usePrimitiveColorsBlueprints?: boolean;
+
+  /** Array of 5 integers mapping primitives to colors from CONFIG.color.primitiveColors */
+  primitiveColorIndices?: number[];
+
+  /**
    * Callback fired when user starts interacting with a blueprint
    * @param e - Pointer event from the interaction
-   * @param bp - Blueprint that was selected  
+   * @param bp - Blueprint that was selected
    * @param bpGeom - Geometry information for the selected blueprint
    */
   onBlueprintPointerDown: (
@@ -93,14 +142,14 @@ export interface BlueprintRingProps {
     bp: Blueprint,
     bpGeom: { bx: number; by: number; cx: number; cy: number }
   ) => void;
-  
-  /** 
+
+  /**
    * Callback fired when user clicks the center badge to toggle views
    * @param e - Pointer event from the badge click
    */
   onCenterBadgePointerDown: (e: React.PointerEvent) => void;
-  
-  /** 
+
+  /**
    * Helper function to lookup primitive blueprints by kind
    * Used for rendering composite pieces that reference primitives
    */
@@ -119,22 +168,24 @@ export default function BlueprintRing(props: BlueprintRingProps) {
     draggingId,
     onBlueprintPointerDown,
     onCenterBadgePointerDown,
-    getPrimitive
+    getPrimitive,
+    usePrimitiveColorsBlueprints,
+    primitiveColorIndices
   } = props;
-  
+
   // Determine which blueprints to show
   const blueprints: Blueprint[] = currentView === "primitives" ? primitives : quickstash;
-  
+
   // Calculate ring geometry
   const QS_SLOTS = maxQuickstashSlots;
   const PRIM_SLOTS = primitives.length;
   const slotsForView = currentView === "primitives" ? Math.max(1, PRIM_SLOTS) : Math.max(1, QS_SLOTS);
   const sweep = layout.mode === "circle" ? Math.PI * 2 : Math.PI;
   const delta = sweep / slotsForView;
-  
+
   const start = layout.mode === "circle" ? -Math.PI / 2 : Math.PI;
   const blueprintTheta = (i: number) => start + (i + 0.5) * delta;
-  
+
   // Chord requirement calculation
   const anchorsDiameterToPx = (anchorsDiag: number, gridPx: number = CONFIG.layout.grid.stepPx) =>
     anchorsDiag * Math.SQRT2 * gridPx;
@@ -143,22 +194,29 @@ export default function BlueprintRing(props: BlueprintRingProps) {
     : 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);
-  
+
   // Blueprint glyph renderer
   const renderBlueprintGlyph = (bp: Blueprint, bx: number, by: number) => {
     const bb = boundsOfBlueprint(bp, (k: string) => getPrimitive(k as TanKind)!);
     const cx = bb.min.x + bb.width / 2;
     const cy = bb.min.y + bb.height / 2;
     const selected = false; // Future enhancement: add selection highlighting
-    
+
+    const fillColor = getBlueprintColor(
+      bp,
+      usePrimitiveColorsBlueprints || false,
+      CONFIG.color.blueprint.fill,
+      primitiveColorIndices || [0, 1, 2, 3, 4]
+    );
+
     return (
       <g
         key={bp.id}
@@ -168,7 +226,7 @@ export default function BlueprintRing(props: BlueprintRingProps) {
           <path
             key={idx}
             d={pathD(poly)}
-            fill={CONFIG.color.blueprint.fill}
+            fill={fillColor}
             opacity={CONFIG.opacity.blueprint}
             stroke={selected ? CONFIG.color.blueprint.selectedStroke : "none"}
             strokeWidth={selected ? 2 : 0}
@@ -180,21 +238,21 @@ export default function BlueprintRing(props: BlueprintRingProps) {
       </g>
     );
   };
-  
+
   return (
     <g className="blueprint-ring">
       {/* Center badge */}
-      <g 
-        transform={`translate(${badgeCenter.x}, ${badgeCenter.y})`} 
-        style={{ cursor: draggingId ? "default" : "pointer" }} 
+      <g
+        transform={`translate(${badgeCenter.x}, ${badgeCenter.y})`}
+        style={{ cursor: draggingId ? "default" : "pointer" }}
         onPointerDown={onCenterBadgePointerDown}
       >
         <circle r={badgeR} fill={CONFIG.color.blueprint.badgeFill} />
-        <text 
-          textAnchor="middle" 
-          dominantBaseline="middle" 
-          fontSize={CONFIG.size.badgeFontPx} 
-          fill={CONFIG.color.blueprint.labelFill} 
+        <text
+          textAnchor="middle"
+          dominantBaseline="middle"
+          fontSize={CONFIG.size.badgeFontPx}
+          fill={CONFIG.color.blueprint.labelFill}
           pointerEvents="none"
         >
           {currentView}
@@ -217,18 +275,18 @@ export default function BlueprintRing(props: BlueprintRingProps) {
  * Useful for components that need more control over blueprint ring behavior
  */
 export function useBlueprintRing(
-  primitives: PrimitiveBlueprint[], 
-  quickstash: Blueprint[], 
+  primitives: PrimitiveBlueprint[],
+  quickstash: Blueprint[],
   initialView: "primitives" | "quickstash" = "quickstash"
 ) {
   const [currentView, setCurrentView] = React.useState<"primitives" | "quickstash">(initialView);
-  
+
   const switchView = React.useCallback(() => {
     setCurrentView(prev => prev === "primitives" ? "quickstash" : "primitives");
   }, []);
-  
+
   const blueprints = currentView === "primitives" ? primitives : quickstash;
-  
+
   return {
     currentView,
     blueprints,

package/src/core/config/config.ts

@@ -1,6 +1,7 @@
 // src/core/config/config.ts
 export type Config = {
   color: {
+    background: string;
     bands: {
       silhouette: { fillEven: string; fillOdd: string; stroke: string };
       workspace:  { fillEven: string; fillOdd: string; stroke: string };
@@ -12,6 +13,7 @@ export type Config = {
     ui: { light: string; dark: string };
     blueprint: { fill: string; selectedStroke: string; badgeFill: string; labelFill: string };
     tangramDecomposition: { stroke: string };
+    primitiveColors: string[];
   };
   opacity: {
     blueprint: number;
@@ -24,6 +26,7 @@ export type Config = {
     anchorRadiusPx: { valid: number; invalid: number };
     badgeFontPx: number;
     centerBadge: { fractionOfOuterR: number; minPx: number; marginPx: number };
+    invalidMarker: { sizePx: number; strokePx: number };
   };
   layout: {
     grid: { stepPx: number; unitPx: number };
@@ -41,35 +44,46 @@ export type Config = {
     snapRadiusPx: number;
     showBorders: boolean;
     hideTouchingBorders: boolean;
+    silhouettesBelowPieces: boolean;
   };
 };
 
 export const CONFIG: Config = {
   color: {
+    background: "#fff7e0ff",
     bands: {
-      silhouette: { fillEven: "#fff2ccff", fillOdd: "#fff2ccff", stroke: "#b1b1b1" },
-      workspace:  { fillEven: "#fff2ccff", fillOdd: "#fff2ccff", stroke: "#b1b1b1" }
+      silhouette: { fillEven: "#ffffff", fillOdd: "#ffffff", stroke: "#b1b1b1" },
+      workspace:  { fillEven: "#ffffff", fillOdd: "#ffffff", stroke: "#b1b1b1" }
     },
-    completion: { fill: "#ccfff2", stroke: "#13da57" },
+    completion: { fill: "#ccffcc", stroke: "#13da57" },
     silhouetteMask: "#374151",
     anchors: { invalid: "#7dd3fc", valid:   "#475569" },
-    piece: { draggingFill: "#8e7cc3ff", validFill: "#8e7cc3ff", invalidFill: "#ef4444", invalidStroke: "#dc2626", selectedStroke: "#674ea7", allGreenStroke: "#86efac", borderStroke: "#674ea7" },
+    // validFill used here for placed composites
+    piece: { draggingFill: "#8e7cc3", validFill: "#8e7cc3", invalidFill: "#d55c00", invalidStroke: "#dc2626", selectedStroke: "#674ea7", allGreenStroke: "#86efac", borderStroke: "#674ea7" },
     ui: { light: "#60a5fa", dark: "#1d4ed8" },
     blueprint: { fill: "#374151", selectedStroke: "#111827", badgeFill: "#000000", labelFill: "#ffffff" },
-    tangramDecomposition: { stroke: "#fef2cc" }
+    tangramDecomposition: { stroke: "#fef2cc" },
+    primitiveColors: [  // from seaborn "colorblind" palette, 6 colors, with red omitted
+      '#0173b2',
+      '#de8f05',
+      '#029e73',
+      '#cc78bc',
+      '#ca9161'
+  ]
   },
   opacity: {
-    blueprint: 0.4,
+    blueprint: 0.6,
     silhouetteMask: 0.25,
     //anchors: { valid: 0.80, invalid: 0.50 },
     anchors: { invalid: 0.0, valid: 0.0 },
-    piece: { invalid: 0.35, dragging: 0.75, locked: 1, normal: 1 },
+    piece: { invalid: 1, dragging: 1, locked: 1, normal: 1 },
   },
   size: {
-    stroke: { bandPx: 5, pieceSelectedPx: 3, allGreenStrokePx: 10, pieceBorderPx: 2, tangramDecompositionPx: 1 },
+    stroke: { bandPx: 5, pieceSelectedPx: 5, allGreenStrokePx: 10, pieceBorderPx: 2, tangramDecompositionPx: 1 },
     anchorRadiusPx: { valid: 1.0, invalid: 1.0 },
     badgeFontPx: 16,
-    centerBadge: { fractionOfOuterR: 0.15, minPx: 20, marginPx: 4 }
+    centerBadge: { fractionOfOuterR: 0.15, minPx: 20, marginPx: 4 },
+    invalidMarker: { sizePx: 10, strokePx: 4 }
   },
   layout: {
     grid: { stepPx: 20, unitPx: 40 },
@@ -85,6 +99,7 @@ export const CONFIG: Config = {
   game: {
     snapRadiusPx: 15,
     showBorders: false,
-    hideTouchingBorders: true
+    hideTouchingBorders: true,
+    silhouettesBelowPieces: true
   }
 };

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

@@ -34,6 +34,9 @@ export interface StartConstructionTrialParams {
   instructions?: string;
   onInteraction?: (event: any) => void;
   onTrialEnd?: (data: any) => void;
+  usePrimitiveColorsBlueprints?: boolean;
+  usePrimitiveColorsTargets?: boolean;
+  primitiveColorIndices?: number[];
 }
 
 // Type for anchor-based composite definitions
@@ -143,7 +146,10 @@ export function startConstructionTrial(
     trialParams,
     ...(params.instructions && { instructions: params.instructions }),
     ...(params.onInteraction && { onInteraction: params.onInteraction }),
-    ...(params.onTrialEnd && { onTrialEnd: params.onTrialEnd })
+    ...(params.onTrialEnd && { onTrialEnd: params.onTrialEnd }),
+    ...(params.usePrimitiveColorsBlueprints !== undefined && { usePrimitiveColorsBlueprints: params.usePrimitiveColorsBlueprints }),
+    ...(params.usePrimitiveColorsTargets !== undefined && { usePrimitiveColorsTargets: params.usePrimitiveColorsTargets }),
+    ...(params.primitiveColorIndices !== undefined && { primitiveColorIndices: params.primitiveColorIndices })
   };
 
   const root = createRoot(display_element);

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

@@ -79,6 +79,24 @@ const info = {
       type: ParameterType.FUNCTION,
       default: undefined,
       description: "Callback when trial completes with full data"
+    },
+    /** Whether to use distinct colors for each primitive shape type in blueprints */
+    use_primitive_colors_blueprints: {
+      type: ParameterType.BOOL,
+      default: false,
+      description: "Whether each primitive shape type should have its own distinct color in the blueprint dock area"
+    },
+    /** Whether to use distinct colors for each primitive shape type in target tangrams */
+    use_primitive_colors_targets: {
+      type: ParameterType.BOOL,
+      default: false,
+      description: "Whether each primitive shape type should have its own distinct color in target tangram silhouettes"
+    },
+    /** Indices mapping primitives to colors from the color palette */
+    primitive_color_indices: {
+      type: ParameterType.OBJECT,
+      default: [0, 1, 2, 3, 4],
+      description: "Array of 5 integers indexing into primitiveColors array, mapping [square, smalltriangle, parallelogram, medtriangle, largetriangle] to colors"
     }
   },
   data: {
@@ -163,7 +181,10 @@ class TangramConstructPlugin implements JsPsychPlugin<Info> {
       show_tangram_decomposition: trial.show_tangram_decomposition,
       instructions: trial.instructions,
       onInteraction: trial.onInteraction,
-      onTrialEnd: wrappedOnTrialEnd
+      onTrialEnd: wrappedOnTrialEnd,
+      usePrimitiveColorsBlueprints: trial.use_primitive_colors_blueprints,
+      usePrimitiveColorsTargets: trial.use_primitive_colors_targets,
+      primitiveColorIndices: trial.primitive_color_indices
     };
 
     // Use React wrapper to start the trial

package/src/plugins/tangram-nback/NBackApp.tsx

@@ -19,6 +19,8 @@ export interface StartNBackTrialParams {
   instructions?: string;
   button_text?: string;
   duration: number;
+  usePrimitiveColors?: boolean;
+  primitiveColorIndices?: number[];
   onTrialEnd?: (data: any) => void;
 }
 
@@ -49,6 +51,8 @@ function NBackView({ params }: NBackViewProps) {
     instructions,
     button_text,
     duration,
+    usePrimitiveColors,
+    primitiveColorIndices,
     onTrialEnd
   } = params;
 
@@ -135,7 +139,12 @@ function NBackView({ params }: NBackViewProps) {
       ...data,
       accuracy,
       tangram_id: tangram.tangramID,
-      is_match: isMatch
+      is_match: isMatch,
+      show_tangram_decomposition: show_tangram_decomposition,
+      use_primitive_colors: usePrimitiveColors,
+      primitive_color_indices: primitiveColorIndices,
+      duration: duration,
+      button_text: button_text
     };
 
     if (onTrialEnd) {
@@ -208,25 +217,50 @@ function NBackView({ params }: NBackViewProps) {
 
       return (
         <g key="sil-decomposed" pointerEvents="none">
-          {placedPolys.map((scaledPoly, i) => (
-            <React.Fragment key={`prim-${i}`}>
-              {/* Fill path */}
-              <path
-                d={pathD(scaledPoly)}
-                fill={CONFIG.color.silhouetteMask}
-                opacity={CONFIG.opacity.silhouetteMask}
-                stroke="none"
-              />
+          {placedPolys.map((scaledPoly, i) => {
+            // Get color for this primitive based on its kind
+            const primInfo = primitiveDecomposition[i];
+            let fillColor = CONFIG.color.silhouetteMask;
 
-              {/* Full perimeter border */}
-              <path
-                d={pathD(scaledPoly)}
-                fill="none"
-                stroke={CONFIG.color.tangramDecomposition.stroke}
-                strokeWidth={CONFIG.size.stroke.tangramDecompositionPx}
-              />
-            </React.Fragment>
-          ))}
+            if (usePrimitiveColors && primInfo?.kind && primitiveColorIndices) {
+              // Map primitive kind to index
+              const kindToIndex: Record<TanKind, number> = {
+                'square': 0,
+                'smalltriangle': 1,
+                'parallelogram': 2,
+                'medtriangle': 3,
+                'largetriangle': 4
+              };
+              const primitiveIndex = kindToIndex[primInfo.kind as TanKind];
+              if (primitiveIndex !== undefined && primitiveColorIndices[primitiveIndex] !== undefined) {
+                const colorIndex = primitiveColorIndices[primitiveIndex];
+                const color = CONFIG.color.primitiveColors[colorIndex];
+                if (color) {
+                  fillColor = color;
+                }
+              }
+            }
+
+            return (
+              <React.Fragment key={`prim-${i}`}>
+                {/* Fill path */}
+                <path
+                  d={pathD(scaledPoly)}
+                  fill={fillColor}
+                  opacity={CONFIG.opacity.silhouetteMask}
+                  stroke="none"
+                />
+
+                {/* Full perimeter border */}
+                <path
+                  d={pathD(scaledPoly)}
+                  fill="none"
+                  stroke={CONFIG.color.tangramDecomposition.stroke}
+                  strokeWidth={CONFIG.size.stroke.tangramDecompositionPx}
+                />
+              </React.Fragment>
+            );
+          })}
         </g>
       );
     } else {
@@ -235,15 +269,40 @@ function NBackView({ params }: NBackViewProps) {
 
       return (
         <g key="sil-unified" pointerEvents="none">
-          {placedPolys.map((scaledPoly, i) => (
-            <path
-              key={`sil-${i}`}
-              d={pathD(scaledPoly)}
-              fill={CONFIG.color.silhouetteMask}
-              opacity={CONFIG.opacity.silhouetteMask}
-              stroke="none"
-            />
-          ))}
+          {placedPolys.map((scaledPoly, i) => {
+            // Get color for this primitive based on its kind
+            const primInfo = primitiveDecomposition[i];
+            let fillColor = CONFIG.color.silhouetteMask;
+
+            if (usePrimitiveColors && primInfo?.kind && primitiveColorIndices) {
+              // Map primitive kind to index
+              const kindToIndex: Record<TanKind, number> = {
+                'square': 0,
+                'smalltriangle': 1,
+                'parallelogram': 2,
+                'medtriangle': 3,
+                'largetriangle': 4
+              };
+              const primitiveIndex = kindToIndex[primInfo.kind as TanKind];
+              if (primitiveIndex !== undefined && primitiveColorIndices[primitiveIndex] !== undefined) {
+                const colorIndex = primitiveColorIndices[primitiveIndex];
+                const color = CONFIG.color.primitiveColors[colorIndex];
+                if (color) {
+                  fillColor = color;
+                }
+              }
+            }
+
+            return (
+              <path
+                key={`sil-${i}`}
+                d={pathD(scaledPoly)}
+                fill={fillColor}
+                opacity={CONFIG.opacity.silhouetteMask}
+                stroke="none"
+              />
+            );
+          })}
         </g>
       );
     }

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

@@ -41,6 +41,18 @@ const info = {
       default: 3000,
       description: "Duration in milliseconds to display tangram and accept responses"
     },
+    /** Whether to use distinct colors for each primitive shape type */
+    use_primitive_colors: {
+      type: ParameterType.BOOL,
+      default: false,
+      description: "Whether each primitive shape type should have its own distinct color in the displayed tangram"
+    },
+    /** Indices mapping primitives to colors from the color palette */
+    primitive_color_indices: {
+      type: ParameterType.OBJECT,
+      default: [0, 1, 2, 3, 4],
+      description: "Array of 5 integers indexing into primitiveColors array, mapping [square, smalltriangle, parallelogram, medtriangle, largetriangle] to colors"
+    },
     /** Callback fired when trial ends */
     onTrialEnd: {
       type: ParameterType.FUNCTION,
@@ -127,6 +139,8 @@ class TangramNBackPlugin implements JsPsychPlugin<Info> {
       instructions: trial.instructions,
       button_text: trial.button_text,
       duration: trial.duration,
+      usePrimitiveColors: trial.use_primitive_colors,
+      primitiveColorIndices: trial.primitive_color_indices,
       onTrialEnd: wrappedOnTrialEnd
     };
 

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

@@ -36,6 +36,8 @@ export interface StartPrepTrialParams {
   instructions?: string;
   onInteraction?: (event: any) => void;
   onTrialEnd?: (data: any) => void;
+  usePrimitiveColorsBlueprints?: boolean;
+  primitiveColorIndices?: number[];
 }
 
 /**
@@ -58,6 +60,8 @@ export function startPrepTrial(
     primitiveOrder,
     onInteraction,
     onTrialEnd,
+    usePrimitiveColorsBlueprints,
+    primitiveColorIndices,
   } = params;
 
   // Extract non-callback params for trial data
@@ -188,7 +192,9 @@ export function startPrepTrial(
     ...(params.instructions && { instructions: params.instructions }),
     onControllerReady: handleControllerReady,
     ...(onInteraction && { onInteraction }),
-    ...(onTrialEnd && { onTrialEnd })
+    ...(onTrialEnd && { onTrialEnd }),
+    ...(usePrimitiveColorsBlueprints !== undefined && { usePrimitiveColorsBlueprints }),
+    ...(primitiveColorIndices !== undefined && { primitiveColorIndices })
   }));
 
   return { root, display_element, jsPsych };

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

@@ -62,6 +62,18 @@ const info = {
     onTrialEnd: {
       type: ParameterType.FUNCTION,
       default: undefined
+    },
+    /** Whether to use distinct colors for each primitive shape type in blueprints */
+    use_primitive_colors_blueprints: {
+      type: ParameterType.BOOL,
+      default: false,
+      description: "Whether each primitive shape type should have its own distinct color in the blueprint dock area"
+    },
+    /** Indices mapping primitives to colors from the color palette */
+    primitive_color_indices: {
+      type: ParameterType.OBJECT,
+      default: [0, 1, 2, 3, 4],
+      description: "Array of 5 integers indexing into primitiveColors array, mapping [square, smalltriangle, parallelogram, medtriangle, largetriangle] to colors"
     }
   },
   data: {
@@ -124,6 +136,8 @@ class TangramPrepPlugin implements JsPsychPlugin<Info> {
       instructions: trial.instructions,
       onInteraction: trial.onInteraction,
       onTrialEnd: wrappedOnTrialEnd,
+      usePrimitiveColorsBlueprints: trial.use_primitive_colors_blueprints,
+      primitiveColorIndices: trial.primitive_color_indices,
     };
     
     const { root, display_element: element, jsPsych } = startPrepTrial(display_element, params, this.jsPsych);