jspsych-tangram 0.0.7 → 0.0.8

package/dist/prep/index.cjs

@@ -16,7 +16,8 @@ const CONFIG = {
     anchors: { invalid: "#7dd3fc", valid: "#475569" },
     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: "#000000", labelFill: "#ffffff" }
+    blueprint: { fill: "#374151", selectedStroke: "#111827", badgeFill: "#000000", labelFill: "#ffffff" },
+    tangramDecomposition: { stroke: "#fef2cc" }
   },
   opacity: {
     blueprint: 0.4,
@@ -26,7 +27,7 @@ const CONFIG = {
     piece: { invalid: 0.35, dragging: 0.75, locked: 1, normal: 1 }
   },
   size: {
-    stroke: { bandPx: 5, pieceSelectedPx: 3, allGreenStrokePx: 10, pieceBorderPx: 2 },
+    stroke: { bandPx: 5, pieceSelectedPx: 3, allGreenStrokePx: 10, pieceBorderPx: 2, tangramDecompositionPx: 1 },
     anchorRadiusPx: { valid: 1, invalid: 1 },
     badgeFontPx: 16,
     centerBadge: { fractionOfOuterR: 0.15, minPx: 20, marginPx: 4 }
@@ -34,6 +35,7 @@ const CONFIG = {
   layout: {
     grid: { stepPx: 20, unitPx: 40 },
     paddingPx: 1,
+    viewportScale: 0.8,
     constraints: {
       workspaceDiamAnchors: 10,
       // num anchors req'd to be on diagonal
@@ -45,7 +47,7 @@ const CONFIG = {
   },
   game: {
     snapRadiusPx: 15,
-    showBorders: true,
+    showBorders: false,
     hideTouchingBorders: true
   }
 };
@@ -816,150 +818,11 @@ function rectForBand(layout, sector, band, pad = 0.85) {
   return { cx, cy, w, h };
 }
 
-function generateEdgeStrokePaths(poly) {
-  const strokePaths = [];
-  for (let i = 0; i < poly.length; i++) {
-    const current = poly[i];
-    const next = poly[(i + 1) % poly.length];
-    if (current && next) {
-      strokePaths.push(`M ${current.x} ${current.y} L ${next.x} ${next.y}`);
-    }
-  }
-  return strokePaths;
-}
-function edgeToUnitSegments$1(start, end, gridSize) {
-  const segments = [];
-  const startGrid = {
-    x: Math.round(start.x / gridSize),
-    y: Math.round(start.y / gridSize)
-  };
-  const endGrid = {
-    x: Math.round(end.x / gridSize),
-    y: Math.round(end.y / gridSize)
-  };
-  const dx = endGrid.x - startGrid.x;
-  const dy = endGrid.y - startGrid.y;
-  if (dx === 0 && dy === 0) return [];
-  const steps = Math.max(Math.abs(dx), Math.abs(dy));
-  const stepX = dx / steps;
-  const stepY = dy / steps;
-  for (let i = 0; i < steps; i++) {
-    const aX = Math.round(startGrid.x + i * stepX);
-    const aY = Math.round(startGrid.y + i * stepY);
-    const bX = Math.round(startGrid.x + (i + 1) * stepX);
-    const bY = Math.round(startGrid.y + (i + 1) * stepY);
-    segments.push({
-      a: { x: aX, y: aY },
-      b: { x: bX, y: bY }
-    });
-  }
-  return segments;
-}
-function getHiddenEdgesForPolygon(piece, polyIndex, allPiecesInSector, getBlueprint, getPrimitive) {
-  let blueprint;
-  try {
-    blueprint = getBlueprint(piece.blueprintId);
-  } catch (error) {
-    console.warn("getBlueprint failed in getHiddenEdgesForPolygon:", error);
-    return [];
-  }
-  if (!blueprint?.shape) {
-    return [];
-  }
-  const poly = blueprint.shape[polyIndex];
-  if (!poly) return [];
-  const gridSize = CONFIG.layout.grid.stepPx;
-  const bb = boundsOfBlueprint(blueprint, getPrimitive);
-  const ox = piece.pos.x - bb.min.x;
-  const oy = piece.pos.y - bb.min.y;
-  const translatedPoly = poly.map((vertex) => ({
-    x: vertex.x + ox,
-    y: vertex.y + oy
-  }));
-  const hiddenEdges = [];
-  for (let i = 0; i < translatedPoly.length; i++) {
-    const current = translatedPoly[i];
-    const next = translatedPoly[(i + 1) % translatedPoly.length];
-    if (!current || !next) {
-      hiddenEdges.push(false);
-      continue;
-    }
-    const edgeSegments = edgeToUnitSegments$1(current, next, gridSize);
-    let isTouching = false;
-    if (piece.blueprintId.startsWith("comp:")) {
-      for (let otherPolyIndex = 0; otherPolyIndex < blueprint.shape.length; otherPolyIndex++) {
-        if (otherPolyIndex === polyIndex) continue;
-        const otherPoly = blueprint.shape[otherPolyIndex];
-        if (!otherPoly) continue;
-        const otherTranslatedPoly = otherPoly.map((vertex) => ({
-          x: vertex.x + ox,
-          y: vertex.y + oy
-        }));
-        for (let j = 0; j < otherTranslatedPoly.length; j++) {
-          const otherCurrent = otherTranslatedPoly[j];
-          const otherNext = otherTranslatedPoly[(j + 1) % otherTranslatedPoly.length];
-          if (!otherCurrent || !otherNext) continue;
-          const otherEdgeSegments = edgeToUnitSegments$1(otherCurrent, otherNext, gridSize);
-          for (const edgeSeg of edgeSegments) {
-            const isShared = otherEdgeSegments.some(
-              (otherSeg) => (
-                // Check if segments share the same endpoints (identical or reversed)
-                edgeSeg.a.x === otherSeg.a.x && edgeSeg.a.y === otherSeg.a.y && edgeSeg.b.x === otherSeg.b.x && edgeSeg.b.y === otherSeg.b.y || edgeSeg.a.x === otherSeg.b.x && edgeSeg.a.y === otherSeg.b.y && edgeSeg.b.x === otherSeg.a.x && edgeSeg.b.y === otherSeg.a.y
-              )
-            );
-            if (isShared) {
-              isTouching = true;
-              break;
-            }
-          }
-          if (isTouching) break;
-        }
-        if (isTouching) break;
-      }
-    }
-    if (!isTouching && CONFIG.game.hideTouchingBorders) {
-      for (const otherPiece of allPiecesInSector) {
-        if (otherPiece.id === piece.id) continue;
-        const otherBlueprint = getBlueprint(otherPiece.blueprintId);
-        if (!otherBlueprint?.shape) continue;
-        const otherBb = boundsOfBlueprint(otherBlueprint, getPrimitive);
-        const otherOx = otherPiece.pos.x - otherBb.min.x;
-        const otherOy = otherPiece.pos.y - otherBb.min.y;
-        for (const otherPoly of otherBlueprint.shape) {
-          const otherTranslatedPoly = otherPoly.map((vertex) => ({
-            x: vertex.x + otherOx,
-            y: vertex.y + otherOy
-          }));
-          for (let j = 0; j < otherTranslatedPoly.length; j++) {
-            const otherCurrent = otherTranslatedPoly[j];
-            const otherNext = otherTranslatedPoly[(j + 1) % otherTranslatedPoly.length];
-            if (!otherCurrent || !otherNext) continue;
-            const otherEdgeSegments = edgeToUnitSegments$1(otherCurrent, otherNext, gridSize);
-            for (const edgeSeg of edgeSegments) {
-              const isShared = otherEdgeSegments.some(
-                (otherSeg) => (
-                  // Check if segments share the same endpoints (identical or reversed)
-                  edgeSeg.a.x === otherSeg.a.x && edgeSeg.a.y === otherSeg.a.y && edgeSeg.b.x === otherSeg.b.x && edgeSeg.b.y === otherSeg.b.y || edgeSeg.a.x === otherSeg.b.x && edgeSeg.a.y === otherSeg.b.y && edgeSeg.b.x === otherSeg.a.x && edgeSeg.b.y === otherSeg.a.y
-                )
-              );
-              if (isShared) {
-                isTouching = true;
-                break;
-              }
-            }
-            if (isTouching) break;
-          }
-          if (isTouching) break;
-        }
-        if (isTouching) break;
-      }
-    }
-    hiddenEdges.push(isTouching);
-  }
-  return hiddenEdges;
+function shouldShowBorders() {
+  return CONFIG.game.showBorders;
 }
 function shouldUseSelectiveBorders(blueprintId) {
-  return (CONFIG.game.hideTouchingBorders);
+  return CONFIG.game.showBorders;
 }
 
 function pathD(poly) {
@@ -977,11 +840,13 @@ function BoardView(props) {
     placedSilBySector,
     anchorDots,
     pieces,
+    scaleS,
     clickMode,
     draggingId,
     selectedPieceId,
     dragInvalid,
     lockedPieceId,
+    showTangramDecomposition,
     svgRef,
     setPieceRef,
     onPiecePointerDown,
@@ -1047,7 +912,7 @@ function BoardView(props) {
       onPointerDown: (e) => {
         onRootPointerDown(e);
       },
-      style: { background: "#fff", touchAction: "none", userSelect: "none" }
+      style: { background: "#f5f5f5", touchAction: "none", userSelect: "none" }
     },
     layout.sectors.map((s, i) => {
       const done = !!controller.state.sectors[s.id].completedAt;
@@ -1067,11 +932,12 @@ function BoardView(props) {
       const isDragging = draggingId === p.id;
       const locked = p.sectorId && controller.isSectorCompleted(p.sectorId);
       const isConnectivityLocked = lockedPieceId === p.id;
-      const isSelected = selectedPieceId === p.id;
+      selectedPieceId === p.id;
       const isCarriedInvalid = isDragging && dragInvalid;
       const translateX = p.x - bb.min.x;
       const translateY = p.y - bb.min.y;
       return /* @__PURE__ */ React.createElement("g", { key: p.id, ref: setPieceRef(p.id), transform: `translate(${translateX}, ${translateY})`, style: { cursor: locked ? "default" : clickMode ? "pointer" : "grab" }, pointerEvents: clickMode && isDragging ? "none" : "auto" }, ("shape" in bp ? bp.shape : []).map((poly, idx) => {
+        const showBorders = shouldShowBorders();
         shouldUseSelectiveBorders(p.blueprintId);
         return /* @__PURE__ */ React.createElement(React.Fragment, { key: idx }, /* @__PURE__ */ React.createElement(
           "path",
@@ -1082,51 +948,38 @@ function BoardView(props) {
             stroke: "none",
             onPointerDown: (e) => onPiecePointerDown(e, p)
           }
-        ), ((
-          // For pieces with selective borders: render individual edge strokes with edge detection
-          (() => {
-            const allPiecesInSector = pieces.filter((piece) => piece.sectorId === p.sectorId);
-            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));
-            const draggedPiece = draggingId ? allPiecesInSector.find((piece) => piece.id === draggingId) : null;
-            let wasTouchingDraggedPiece;
-            if (p.blueprintId.startsWith("comp:")) {
-              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)) : new Array(hiddenEdges.length).fill(false);
-              wasTouchingDraggedPiece = externalHiddenEdges.map((external, i) => external && !internalHiddenEdges[i]);
-            } else {
-              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) => {
-              const wasHiddenDueToDraggedPiece = wasTouchingDraggedPiece[strokeIdx] || false;
-              let isHidden;
-              if (isDragging && p.blueprintId.startsWith("comp:")) {
-                const internalHiddenEdges = getHiddenEdgesForPolygon(pieceAsPiece, idx, [], (id) => controller.getBlueprint(id), (kind) => controller.getPrimitive(kind));
-                isHidden = internalHiddenEdges[strokeIdx] || false;
-              } else {
-                isHidden = isDragging ? false : (hiddenEdges[strokeIdx] || false) && !wasHiddenDueToDraggedPiece;
-              }
-              return /* @__PURE__ */ React.createElement(
-                "path",
-                {
-                  key: `stroke-${idx}-${strokeIdx}`,
-                  d: strokePath,
-                  fill: "none",
-                  stroke: isHidden ? "none" : isConnectivityLocked ? CONFIG.color.piece.invalidStroke : isCarriedInvalid ? CONFIG.color.piece.invalidStroke : isSelected || isDragging ? CONFIG.color.piece.selectedStroke : CONFIG.color.piece.borderStroke,
-                  strokeWidth: isHidden ? 0 : isSelected || isDragging ? CONFIG.size.stroke.pieceSelectedPx : CONFIG.size.stroke.pieceBorderPx,
-                  onPointerDown: (e) => onPiecePointerDown(e, p)
-                }
-              );
-            });
-          })()
-        ) ));
+        ), showBorders);
       }));
     }),
     layout.sectors.map((s) => {
-      const placedPolys = placedSilBySector.get(s.id) ?? [];
-      if (!placedPolys.length) return null;
-      return /* @__PURE__ */ React.createElement("g", { key: `sil-${s.id}`, pointerEvents: "none" }, placedPolys.map((poly, i) => /* @__PURE__ */ React.createElement("path", { key: i, d: pathD(poly), fill: CONFIG.color.silhouetteMask, opacity: CONFIG.opacity.silhouetteMask })));
+      const sectorCfg = controller.state.cfg.sectors.find((ss) => ss.id === s.id);
+      if (showTangramDecomposition && sectorCfg?.silhouette.primitiveDecomposition) {
+        const primitiveDecomposition = sectorCfg.silhouette.primitiveDecomposition;
+        const rect = rectForBand(layout, s, "silhouette", 1);
+        const rawPolys = primitiveDecomposition.map((primInfo) => primInfo.polygon);
+        const placedPolys = placeSilhouetteGridAlignedAsPolys(rawPolys, scaleS, { cx: rect.cx, cy: rect.cy });
+        return /* @__PURE__ */ React.createElement("g", { key: `sil-decomposed-${s.id}`, pointerEvents: "none" }, placedPolys.map((scaledPoly, i) => /* @__PURE__ */ React.createElement(React.Fragment, { key: `prim-${i}` }, /* @__PURE__ */ React.createElement(
+          "path",
+          {
+            d: pathD(scaledPoly),
+            fill: CONFIG.color.silhouetteMask,
+            opacity: CONFIG.opacity.silhouetteMask,
+            stroke: "none"
+          }
+        ), /* @__PURE__ */ React.createElement(
+          "path",
+          {
+            d: pathD(scaledPoly),
+            fill: "none",
+            stroke: CONFIG.color.tangramDecomposition.stroke,
+            strokeWidth: CONFIG.size.stroke.tangramDecompositionPx
+          }
+        ))));
+      } else {
+        const placedPolys = placedSilBySector.get(s.id) ?? [];
+        if (!placedPolys.length) return null;
+        return /* @__PURE__ */ React.createElement("g", { key: `sil-${s.id}`, pointerEvents: "none" }, placedPolys.map((poly, i) => /* @__PURE__ */ React.createElement("path", { key: i, d: pathD(poly), fill: CONFIG.color.silhouetteMask, opacity: CONFIG.opacity.silhouetteMask })));
+      }
     }),
     anchorDots.map(({ sectorId, valid, invalid }) => {
       const isInnerRing = sectorId === "inner-ring";
@@ -2588,7 +2441,7 @@ function useClickController(controller, layout, pieces, clickMode, draggingId, s
 }
 
 class InteractionTracker {
-  constructor(controller, callbacks, trialId, gameId) {
+  constructor(controller, callbacks, trialParams) {
     this.gridStep = CONFIG.layout.grid.stepPx;
     // Interaction state
     this.interactionIndex = 0;
@@ -2605,8 +2458,7 @@ class InteractionTracker {
     this.createdMacros = [];
     this.controller = controller;
     this.callbacks = callbacks;
-    this.trialId = trialId || uuid.v4();
-    this.gameId = gameId || uuid.v4();
+    this.trialParams = trialParams;
     this.trialStartTime = Date.now();
     this.controller.setTrackingCallbacks({
       onSectorCompleted: (sectorId) => this.recordSectorCompletion(sectorId)
@@ -2654,8 +2506,6 @@ class InteractionTracker {
     const event = {
       // Metadata
       interactionId: uuid.v4(),
-      trialId: this.trialId,
-      gameId: this.gameId,
       interactionIndex: this.interactionIndex++,
       // Interaction type
       interactionType,
@@ -2772,13 +2622,10 @@ class InteractionTracker {
       }));
       const data = {
         trialType: "construction",
-        trialId: this.trialId,
-        gameId: this.gameId,
-        trialNum: 0,
-        // TODO: Plugin should provide this
         trialStartTime: this.trialStartTime,
         trialEndTime,
         totalDuration,
+        trialParams: this.trialParams,
         endReason,
         completionTimes: this.completionTimes,
         finalBlueprintState,
@@ -2797,13 +2644,10 @@ class InteractionTracker {
       }));
       const data = {
         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,
@@ -3061,6 +2905,9 @@ function GameBoard(props) {
     maxQuickstashSlots,
     maxCompositeSize,
     mode,
+    showTangramDecomposition,
+    instructions,
+    trialParams,
     width: _width,
     height: _height,
     onSectorComplete,
@@ -3070,6 +2917,7 @@ function GameBoard(props) {
     onTrialEnd,
     onControllerReady
   } = props;
+  const [timeRemaining, setTimeRemaining] = React.useState(timeLimitMs > 0 ? Math.floor(timeLimitMs / 1e3) : 0);
   const controller = React.useMemo(() => {
     const gameConfig = {
       n: sectors.length,
@@ -3096,8 +2944,8 @@ function GameBoard(props) {
     const callbacks = {};
     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]);
   React.useEffect(() => {
     if (onControllerReady) {
       onControllerReady(controller);
@@ -3177,22 +3025,22 @@ function GameBoard(props) {
   }), [handleSectorComplete, onPiecePlace, onPieceRemove]);
   const getGameboardStyle = () => {
     const baseStyle = {
-      margin: "0 auto",
+      margin: "10px",
       display: "flex",
       alignItems: "center",
       justifyContent: "center",
       position: "relative"
     };
     if (layoutMode === "circle") {
-      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`,
         height: `${size}px`
       };
     } else {
-      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`,
@@ -3361,7 +3209,68 @@ function GameBoard(props) {
     force();
     e.stopPropagation();
   };
-  return /* @__PURE__ */ React.createElement("div", { className: "tangram-gameboard", style: getGameboardStyle() }, /* @__PURE__ */ React.createElement(
+  React.useEffect(() => {
+    if (timeLimitMs === 0) return;
+    const interval = setInterval(() => {
+      setTimeRemaining((prev) => {
+        if (prev <= 1) {
+          clearInterval(interval);
+          return 0;
+        }
+        return prev - 1;
+      });
+    }, 1e3);
+    return () => clearInterval(interval);
+  }, [timeLimitMs]);
+  const formatTime = (seconds) => {
+    const mins = Math.floor(seconds / 60);
+    const secs = Math.floor(seconds % 60);
+    return `${mins.toString().padStart(2, "0")}:${secs.toString().padStart(2, "0")}`;
+  };
+  const containerStyle = {
+    display: "flex",
+    flexDirection: "column",
+    width: "100%"
+    // minHeight: '100vh'
+  };
+  const headerStyle = {
+    display: "flex",
+    flexDirection: "row",
+    justifyContent: "space-between",
+    alignItems: "center",
+    padding: "20px",
+    background: "#f5f5f5",
+    flex: "0 0 auto"
+  };
+  const instructionsStyle = {
+    flexGrow: 1,
+    fontSize: "20px",
+    lineHeight: 1.5,
+    marginRight: "20px"
+  };
+  const timerStyle = {
+    fontSize: "24px",
+    fontWeight: "bold",
+    fontFamily: "monospace",
+    color: "#333",
+    minWidth: "80px",
+    textAlign: "right"
+  };
+  const gameboardWrapperStyle = {
+    flex: "1 1 auto",
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    overflow: "hidden"
+  };
+  return /* @__PURE__ */ React.createElement("div", { className: "tangram-trial-container", style: containerStyle }, (instructions || timeLimitMs > 0) && /* @__PURE__ */ React.createElement("div", { className: "tangram-header", style: headerStyle }, instructions && /* @__PURE__ */ React.createElement(
+    "div",
+    {
+      className: "tangram-instructions",
+      style: instructionsStyle,
+      dangerouslySetInnerHTML: { __html: instructions }
+    }
+  ), timeLimitMs > 0 && /* @__PURE__ */ React.createElement("div", { className: "tangram-timer", style: timerStyle }, formatTime(timeRemaining))), /* @__PURE__ */ React.createElement("div", { className: "tangram-gameboard-wrapper", style: gameboardWrapperStyle }, /* @__PURE__ */ React.createElement("div", { className: "tangram-gameboard", style: getGameboardStyle() }, /* @__PURE__ */ React.createElement(
     BoardView,
     {
       controller,
@@ -3387,9 +3296,11 @@ function GameBoard(props) {
       onPointerMove,
       onPointerUp,
       onCenterBadgePointerDown,
+      showTangramDecomposition: showTangramDecomposition ?? false,
+      scaleS,
       ...eventCallbacks
     }
-  ));
+  ))));
 }
 
 const U = 40;
@@ -3555,8 +3466,9 @@ function startPrepTrial(display_element, params, jsPsych) {
     onInteraction,
     onTrialEnd
   } = params;
+  const { onInteraction: _, onTrialEnd: __, ...trialParams } = params;
   const PRIMITIVE_BLUEPRINTS_ORDERED = [...PRIMITIVE_BLUEPRINTS].sort((a, b) => primitiveOrder.indexOf(a.kind) - primitiveOrder.indexOf(b.kind));
-  const prepSectors = Array.from({ length: numQuickstashSlots }, (_, i) => ({
+  const prepSectors = Array.from({ length: numQuickstashSlots }, (_2, i) => ({
     id: `prep-sector-${i}`,
     tangramId: `prep-sector-${i}`,
     // dummy value since prep mode doesn't have tangrams
@@ -3640,6 +3552,8 @@ function startPrepTrial(display_element, params, jsPsych) {
     // Enable prep-specific behavior
     minPiecesPerMacro,
     requireAllSlots,
+    trialParams,
+    ...params.instructions && { instructions: params.instructions },
     onControllerReady: handleControllerReady,
     ...onInteraction && { onInteraction },
     ...onTrialEnd && { onTrialEnd }
@@ -3693,6 +3607,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: jspsych.ParameterType.STRING,
+      default: void 0,
+      description: "HTML content to display above the gameboard as instructions"
+    },
     /** Callback fired after each interaction (optional analytics hook) */
     onInteraction: {
       type: jspsych.ParameterType.FUNCTION,
@@ -3744,6 +3664,7 @@ class TangramPrepPlugin {
       requireAllSlots: trial.require_all_slots,
       quickstashMacros: trial.quickstash_macros,
       primitiveOrder: trial.primitive_order,
+      instructions: trial.instructions,
       onInteraction: trial.onInteraction,
       onTrialEnd: wrappedOnTrialEnd
     };