jspsych-tangram 0.0.6 → 0.0.8

package/package.json

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

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

@@ -1,7 +1,7 @@
 import React from "react";
 import type { Poly, TanKind, Blueprint, PrimitiveBlueprint } from "@/core/domain/types";
-import { wedgePath, type CircleLayout } from "@/core/domain/layout";
-import { boundsOfBlueprint } from "@/core/engine/geometry";
+import { wedgePath, rectForBand, type CircleLayout } from "@/core/domain/layout";
+import { boundsOfBlueprint, placeSilhouetteGridAlignedAsPolys } from "@/core/engine/geometry";
 import { CONFIG } from "@/core/config/config";
 import { generateEdgeStrokePaths, shouldUseSelectiveBorders, shouldShowBorders, getHiddenEdgesForPolygon } from "@/core/engine/validation/border-rendering";
 
@@ -21,6 +21,7 @@ export type BoardViewProps = {
   placedSilBySector: Map<string, Poly[]>;
   anchorDots: AnchorDots[];
   pieces: PieceView[];
+  scaleS: number;  // scaling factor for silhouettes
 
   // UI state flags
   clickMode: boolean;
@@ -28,6 +29,7 @@ export type BoardViewProps = {
   selectedPieceId: string | null;
   dragInvalid: boolean;
   lockedPieceId: string | null;
+  showTangramDecomposition?: boolean;  // whether to show tangram decomposed into primitives
 
   // refs + handlers wired by the container
   svgRef: React.RefObject<SVGSVGElement>;
@@ -55,8 +57,8 @@ export default function BoardView(props: BoardViewProps) {
   const {
     controller, layout, viewBox, width, height,
     badgeR, badgeCenter,
-    placedSilBySector, anchorDots, pieces,
-    clickMode, draggingId, selectedPieceId, dragInvalid, lockedPieceId,
+    placedSilBySector, anchorDots, pieces, scaleS,
+    clickMode, draggingId, selectedPieceId, dragInvalid, lockedPieceId, showTangramDecomposition,
     svgRef, setPieceRef,
     onPiecePointerDown, onBlueprintPointerDown, onRootPointerDown, onPointerMove, onPointerUp, onCenterBadgePointerDown,
   } = props;
@@ -136,7 +138,7 @@ export default function BoardView(props: BoardViewProps) {
       onPointerDown={(e) => {
         onRootPointerDown(e);
       }}
-      style={{ background: "#fff", touchAction: "none", userSelect: "none" }}
+      style={{ background: "#f5f5f5", touchAction: "none", userSelect: "none" }}
     >
       {/* bands as wedges */}
       {layout.sectors.map((s, i) => {
@@ -272,15 +274,52 @@ export default function BoardView(props: BoardViewProps) {
 
       {/* silhouettes (use pre-placed polys) */}
       {layout.sectors.map((s) => {
-        const placedPolys = placedSilBySector.get(s.id) ?? [];
-        if (!placedPolys.length) return null;
-        return (
-          <g key={`sil-${s.id}`} pointerEvents="none">
-            {placedPolys.map((poly, i) => (
-              <path key={i} d={pathD(poly)} fill={CONFIG.color.silhouetteMask} opacity={CONFIG.opacity.silhouetteMask} />
-            ))}
-          </g>
-        );
+        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) => (
+                <React.Fragment key={`prim-${i}`}>
+                  {/* Fill path */}
+                  <path
+                    d={pathD(scaledPoly)}
+                    fill={CONFIG.color.silhouetteMask}
+                    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 {
+          // Default: render unified silhouette
+          const placedPolys = placedSilBySector.get(s.id) ?? [];
+          if (!placedPolys.length) return null;
+          return (
+            <g key={`sil-${s.id}`} pointerEvents="none">
+              {placedPolys.map((poly, i) => (
+                <path key={i} d={pathD(poly)} fill={CONFIG.color.silhouetteMask} opacity={CONFIG.opacity.silhouetteMask} />
+              ))}
+            </g>
+          );
+        }
       })}
 
       {/* anchor grid */}

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

@@ -149,6 +149,24 @@ export interface GameBoardConfig {
    */
   requireAllSlots?: boolean;
   
+  /**
+   * Whether to show tangram target shapes decomposed into individual primitives with borders
+   * Independent from showBorders/hideTouchingBorders (which control spawned pieces)
+   */
+  showTangramDecomposition?: boolean;
+  
+  /**
+   * HTML content to display above the gameboard as instructions
+   * Allows rich formatting via HTML
+   */
+  instructions?: string;
+  
+  /**
+   * Cleaned jsPsych plugin parameters (excluding callbacks)
+   * Saved to trial data for analysis
+   */
+  trialParams?: any;
+  
   /** Optional CSS width for the game board SVG */
   width?: number;
   
@@ -238,6 +256,9 @@ export default function GameBoard(props: GameBoardProps) {
     maxQuickstashSlots,
     maxCompositeSize,
     mode,
+    showTangramDecomposition,
+    instructions,
+    trialParams,
     width: _width,
     height: _height,
     onSectorComplete,
@@ -248,6 +269,9 @@ export default function GameBoard(props: GameBoardProps) {
     onControllerReady
   } = props;
   
+  // Timer state for countdown
+  const [timeRemaining, setTimeRemaining] = React.useState(timeLimitMs > 0 ? Math.floor(timeLimitMs / 1000) : 0);
+  
   // Initialize game controller with injected data
   const controller = React.useMemo(() => {
     const gameConfig = {
@@ -279,8 +303,8 @@ export default function GameBoard(props: GameBoardProps) {
     if (onInteraction) callbacks.onInteraction = onInteraction;
     if (onTrialEnd) callbacks.onTrialEnd = onTrialEnd;
 
-    return new InteractionTracker(controller, callbacks);
-  }, [controller, onInteraction, onTrialEnd]);
+    return new InteractionTracker(controller, callbacks, trialParams);
+  }, [controller, onInteraction, onTrialEnd, trialParams]);
 
   // Call onControllerReady when controller is ready
   React.useEffect(() => {
@@ -387,7 +411,7 @@ export default function GameBoard(props: GameBoardProps) {
   // Calculate sizing based on layout mode
   const getGameboardStyle = () => {
     const baseStyle = {
-      margin: '0 auto',
+      margin: '10px',
       display: 'flex',
       alignItems: 'center',
       justifyContent: 'center',
@@ -396,7 +420,7 @@ export default function GameBoard(props: GameBoardProps) {
 
     if (layoutMode === 'circle') {
       // Circle mode: square aspect ratio (height == width)
-      const size = Math.min(window.innerWidth * 0.96, window.innerHeight * 0.96);
+      const size = Math.min(window.innerWidth * CONFIG.layout.viewportScale, window.innerHeight * CONFIG.layout.viewportScale);
       return {
         ...baseStyle,
         width: `${size}px`,
@@ -404,8 +428,8 @@ export default function GameBoard(props: GameBoardProps) {
       };
     } else {
       // Semicircle mode: width is 2x height
-      const maxWidth = Math.min(window.innerWidth * 0.96, window.innerHeight * 0.96 * 2);
-      const maxHeight = Math.min(window.innerWidth * 0.96 / 2, window.innerHeight * 0.96);
+      const maxWidth = Math.min(window.innerWidth * CONFIG.layout.viewportScale, window.innerHeight * CONFIG.layout.viewportScale * 2);
+      const maxHeight = Math.min(window.innerWidth * CONFIG.layout.viewportScale / 2, window.innerHeight * CONFIG.layout.viewportScale);
       return {
         ...baseStyle,
         width: `${maxWidth}px`,
@@ -613,8 +637,96 @@ export default function GameBoard(props: GameBoardProps) {
     e.stopPropagation();
   };
 
+  // Timer effect
+  React.useEffect(() => {
+    if (timeLimitMs === 0) return;
+    
+    const interval = setInterval(() => {
+      setTimeRemaining(prev => {
+        if (prev <= 1) {
+          clearInterval(interval);
+          return 0;
+        }
+        return prev - 1;
+      });
+    }, 1000);
+    
+    return () => clearInterval(interval);
+  }, [timeLimitMs]);
+
+  // Format time helper
+  const formatTime = (seconds: number): string => {
+    const mins = Math.floor(seconds / 60);
+    const secs = Math.floor(seconds % 60);
+    return `${mins.toString().padStart(2, '0')}:${secs.toString().padStart(2, '0')}`;
+  };
+
+  // Container style
+  const containerStyle: React.CSSProperties = {
+    display: 'flex',
+    flexDirection: 'column',
+    width: '100%',
+    // minHeight: '100vh'
+  };
+
+  // Header style
+  const headerStyle: React.CSSProperties = {
+    display: 'flex',
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    padding: '20px',
+    background: '#f5f5f5',
+    flex: '0 0 auto'
+  };
+
+  // Instructions style
+  const instructionsStyle: React.CSSProperties = {
+    flexGrow: 1,
+    fontSize: '20px',
+    lineHeight: 1.5,
+    marginRight: '20px'
+  };
+
+  // Timer style
+  const timerStyle: React.CSSProperties = {
+    fontSize: '24px',
+    fontWeight: 'bold',
+    fontFamily: 'monospace',
+    color: '#333',
+    minWidth: '80px',
+    textAlign: 'right'
+  };
+
+  // Gameboard wrapper style (to center the gameboard in remaining space)
+  const gameboardWrapperStyle: React.CSSProperties = {
+    flex: '1 1 auto',
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    overflow: 'hidden'
+  };
+
   return (
-    <div className="tangram-gameboard" style={getGameboardStyle()}>
+    <div className="tangram-trial-container" style={containerStyle}>
+      {(instructions || timeLimitMs > 0) && (
+        <div className="tangram-header" style={headerStyle}>
+          {instructions && (
+            <div 
+              className="tangram-instructions" 
+              style={instructionsStyle}
+              dangerouslySetInnerHTML={{ __html: instructions }} 
+            />
+          )}
+          {timeLimitMs > 0 && (
+            <div className="tangram-timer" style={timerStyle}>
+              {formatTime(timeRemaining)}
+            </div>
+          )}
+        </div>
+      )}
+      <div className="tangram-gameboard-wrapper" style={gameboardWrapperStyle}>
+        <div className="tangram-gameboard" style={getGameboardStyle()}>
       <BoardView
         controller={controller}
         layout={layout}
@@ -639,8 +751,12 @@ export default function GameBoard(props: GameBoardProps) {
         onPointerMove={onPointerMove}
         onPointerUp={onPointerUp}
         onCenterBadgePointerDown={onCenterBadgePointerDown}
+        showTangramDecomposition={showTangramDecomposition ?? false}
+        scaleS={scaleS}
         {...eventCallbacks}
       />
+        </div>
+      </div>
     </div>
   );
 }

package/src/core/config/config.ts

@@ -11,6 +11,7 @@ export type Config = {
     piece: { draggingFill: string; validFill: string; invalidFill: string; invalidStroke: string; selectedStroke: string; allGreenStroke: string; borderStroke: string };
     ui: { light: string; dark: string };
     blueprint: { fill: string; selectedStroke: string; badgeFill: string; labelFill: string };
+    tangramDecomposition: { stroke: string };
   };
   opacity: {
     blueprint: number;
@@ -19,7 +20,7 @@ export type Config = {
     piece: { invalid: number; dragging: number; locked: number; normal: number };
   };
   size: {
-    stroke: { bandPx: number; pieceSelectedPx: number; allGreenStrokePx: number; pieceBorderPx: number };
+    stroke: { bandPx: number; pieceSelectedPx: number; allGreenStrokePx: number; pieceBorderPx: number; tangramDecompositionPx: number };
     anchorRadiusPx: { valid: number; invalid: number };
     badgeFontPx: number;
     centerBadge: { fractionOfOuterR: number; minPx: number; marginPx: number };
@@ -27,6 +28,7 @@ export type Config = {
   layout: {
     grid: { stepPx: number; unitPx: number };
     paddingPx: number;
+    viewportScale: number;
     /** renamed from capacity → constraints */
     constraints: {
       workspaceDiamAnchors: number;
@@ -45,31 +47,34 @@ export type Config = {
 export const CONFIG: Config = {
   color: {
     bands: {
-      silhouette: { fillEven: "#eef2ff", fillOdd: "#f6f7fb", stroke: "#c7d2fe" },
-      workspace:  { fillEven: "#f3f4f6", fillOdd: "#f9fafb", stroke: "#e5e7eb" }
+      silhouette: { fillEven: "#fff2ccff", fillOdd: "#fff2ccff", stroke: "#b1b1b1" },
+      workspace:  { fillEven: "#fff2ccff", fillOdd: "#fff2ccff", stroke: "#b1b1b1" }
     },
-    completion: { fill: "#dcfce7", stroke: "#86efac" },
-    silhouetteMask: "#94a3b8",
+    completion: { fill: "#ccfff2", stroke: "#13da57" },
+    silhouetteMask: "#374151",
     anchors: { invalid: "#7dd3fc", valid:   "#475569" },
-    piece: { draggingFill: "#1d4ed8", validFill: "#60a5fa", invalidFill: "#ef4444", invalidStroke: "#dc2626", selectedStroke: "#111827", allGreenStroke: "#86efac", borderStroke: "#374151" },
+    piece: { draggingFill: "#8e7cc3ff", validFill: "#8e7cc3ff", invalidFill: "#ef4444", invalidStroke: "#dc2626", selectedStroke: "#674ea7", allGreenStroke: "#86efac", borderStroke: "#674ea7" },
     ui: { light: "#60a5fa", dark: "#1d4ed8" },
-    blueprint: { fill: "#374151", selectedStroke: "#111827", badgeFill: "#eef2ff", labelFill: "#374151" }
+    blueprint: { fill: "#374151", selectedStroke: "#111827", badgeFill: "#000000", labelFill: "#ffffff" },
+    tangramDecomposition: { stroke: "#fef2cc" }
   },
   opacity: {
-    blueprint: 0.95,
-    silhouetteMask: 0.45,
-    anchors: { valid: 0.80, invalid: 0.50 },
-    piece: { invalid: 0.35, dragging: 0.60, locked: 0.70, normal: 0.95 },
+    blueprint: 0.4,
+    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 },
   },
   size: {
-    stroke: { bandPx: 1, pieceSelectedPx: 1.5, allGreenStrokePx: 6, pieceBorderPx: 1 },
+    stroke: { bandPx: 5, pieceSelectedPx: 3, allGreenStrokePx: 10, pieceBorderPx: 2, tangramDecompositionPx: 1 },
     anchorRadiusPx: { valid: 1.0, invalid: 1.0 },
-    badgeFontPx: 12,
+    badgeFontPx: 16,
     centerBadge: { fractionOfOuterR: 0.15, minPx: 20, marginPx: 4 }
   },
   layout: {
     grid: { stepPx: 20, unitPx: 40 },
     paddingPx: 1,
+    viewportScale: 0.8,
     constraints: {
       workspaceDiamAnchors: 10,  // num anchors req'd to be on diagonal
       quickstashDiamAnchors: 7,  // num anchors req'd to be in single quickstash slot
@@ -79,7 +84,7 @@ export const CONFIG: Config = {
   },
   game: {
     snapRadiusPx: 15,
-    showBorders: true,
+    showBorders: false,
     hideTouchingBorders: true
   }
 };

package/src/core/domain/types.ts

@@ -51,6 +51,7 @@ export type SilhouetteSpec = {
   id: string;
   anchors?: Anchor[];
   mask?: Poly[];            // polygon masks for silhouette matching
+  primitiveDecomposition?: Array<{ kind: TanKind; polygon: Poly }>;  // individual primitive pieces for decomposition view
 };
 
 export type Sector = {

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
@@ -372,12 +367,10 @@ 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,
+        trialParams: this.trialParams,
         endReason: endReason as 'timeout' | 'auto_complete',
         completionTimes: this.completionTimes,
         finalBlueprintState,
@@ -403,12 +396,10 @@ 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,
+        trialParams: this.trialParams,
         endReason: 'submit',
         createdMacros: finalMacros,
         quickstashMacros,

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,14 @@ 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)
 
+  // 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,
     };