jspsych-tangram 0.0.7 → 0.0.9

package/dist/prep/index.d.ts

@@ -46,6 +46,12 @@ declare const info: {
             default: string[];
             description: string;
         };
+        /** HTML content to display above the gameboard as instructions */
+        instructions: {
+            type: ParameterType;
+            default: undefined;
+            description: string;
+        };
         /** Callback fired after each interaction (optional analytics hook) */
         onInteraction: {
             type: ParameterType;
@@ -121,6 +127,12 @@ declare class TangramPrepPlugin implements JsPsychPlugin<Info> {
                 default: string[];
                 description: string;
             };
+            /** HTML content to display above the gameboard as instructions */
+            instructions: {
+                type: ParameterType;
+                default: undefined;
+                description: string;
+            };
             /** Callback fired after each interaction (optional analytics hook) */
             onInteraction: {
                 type: ParameterType;

package/dist/prep/index.js

@@ -14,7 +14,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,
@@ -24,7 +25,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 }
@@ -32,6 +33,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
@@ -43,7 +45,7 @@ const CONFIG = {
   },
   game: {
     snapRadiusPx: 15,
-    showBorders: true,
+    showBorders: false,
     hideTouchingBorders: true
   }
 };
@@ -814,152 +816,17 @@ 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;
 }
 
+var lockedIcon = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAFoAAABaCAYAAAA4qEECAAAACXBIWXMAAAsSAAALEgHS3X78AAAFY0lEQVR4nO2d7XXrNgyGH/r0f7zB9QbXnaDqBt6gvhM0I2SE3A2UDXwnqLKBPEHdDewJ0B+kYieWZEoiQfrjPQcnjqOI0GuYAAFQMiJCLjDGLIEFsHQyB/7w/Pd397MCamAnInVgFUfDpCTaGLMACmDlfj4FHuKAJX4DVCKyC3x+b6gTbYyZA2sn31UHhy1QAqWI7FVHFhEVwVpsCUgmUgKF2vUrEVxlQGyXVBqE3zPBqoTHIHhOXlPEUCmBedZEY6OHfQZkTZU9sMqO6Buw4ujWHYLkJXaBkJqUWFIDy6REYx3eLUwVl2TPREc5heR1BgRoy1qV6DsleRLZD5KVyH6QrET2UMeX+uJyE28H6UvykvuILobKHs/Qz4fkObcdJ0+VGo9FzcV8tDGmBP7qPSg+DtgLqrFWBLYSs8C/AhMTbyKy7j3igjWvSPu1LPH4ajo9y4S6ChdyI5emjFTz8isjcgxYC98kNIxOnfuUTmEhk5e6Tvd1IiMpBxFNmlDOy6kMIDtVpNRqKK3O0BhToetk/sPOxZ0FU1cxX2CNAGxFZCc9lW3XvlARvrreh3cRKc7ezcSaOx0e1tH1hZc1PY6INA79zKrbFKuUlXrpccZDdKnomHqwzlXzmqpeotG35l0PyWMWSa3zPGkiqKKP6FJZmXUH0VVIa0pk1WUr0e5T11REaLe+dYwPEOtIk13fqSLPykp0Wd4uwLm7piTtnM1zM/aMI9boovr6hgvHvgU49zdjTNHyvnZ36bp5MYOPGFW74bDtoouA52871y7g+X3w3XH7YdGFsgJwzMKdYh55zCry+dtQwJHoVQIF7gUrSGvR94ICYOYckGYu4N7wZIxZzLDx5QNxsZxh04kPxMUS9JNINfBChB7kS4KNal4JsygaIhtNooNUTwKS/oxeoqky7kVsbB3JujuhLkCzMKBF9O+S0ebKU7il+j+xx5ldPmQyfuZKMoCIVMCv2ONoEP2qMMZUlLEHiD11HEQkdv4iCIwxUafQ2Bad7ZShjd9SK+CLkz3kTQJsQ4o93RMQNX4MFPN2NcN4t816jBE1ltZwhpPgLLmiPdZ9Aip3TNbInmjsdNG3oHhCvww3GDOOd27JFT5FidwLF+8z2ktKD4TFfkb+Idgm0DEpUV8L0Yeevx94ED0dYttyC9rJPmCzgjtFlcagnjkl+ywmOVxSasHn5M8vYJFzwsrhICK7JryrUmriA7cCPCW1vpJVYQXHODr3Oe6asYEj0VU6PW4eFTii3Ty9TajMrWLbOOrTJXiZRJXbRtm8eBAdF2Xz4oNo58HfUmhzo3g7jYq+Zu9KXV0Go+54nSPKT7+1JMArwiW86wiNL2sm3ERKKfF/VvA42zkbus9BREyoc8WC68r/N+Ap/3RtDB84S/y7A4LlqI0xueeKIWx/+PtXkoHzqeOkRpdV3TCmELbpsbWG2Td4yA2QwefUgCS/BLzO185xehSYB/6ksyObsLeX2zHmxihOkdB3Biixqc3UBC8If6eaom9Mn5tXvQJ/9x40HFtsGKmd5pxjHV/oPZU/ReS57wCvp1YYY2r0N3xeC7YicnF7im9fx4rMqzCJcMCz1cGLaDnW7R74jEI865XenUpia3M/xmp0g/ghQ+qViUOia5XBoWoO8ee1yaj1QC7B/rXIKJK94ug+JLqvXAo0jTqjc+CT2nbdwEtuu7C7xSaKphUaAi1pm62/qb/aoWXUzWiDztEdhD8e4aRB9I1YdzArjkr0CeGNo0xNnK9UBNp4pEr0CeFF5oRXXPODIzsILzMgtpFSg+BGHg/3VcLjcdVKSEr0Vzjil4x/AHvTrF5jm3d2wZUcif8BqSLxz8FiAOgAAAAASUVORK5CYII=";
+
+var unlockedIcon = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAFoAAABaCAYAAAA4qEECAAAACXBIWXMAAAsSAAALEgHS3X78AAAFYklEQVR4nO1d0ZGjOBB9ct3/+iJYMlg2giODcwjeDCYEbwbeDNgMvBloIjgmAyYDHEHfh4SHsQUIaLVk7FfVNTblkZpHq1u0GqGICKlAKZUDyADkVrYA/vH891f7VwOoANREVDGrOBsqJtFKqQxAAWBn/35h7uIMQ/wJgCaimrl9b4gTrZTaAthb+SbaOfAGoARQElEj2jMRiQiMxZYAKBEpARRi5y9EsE6A2D7REoQ/MsGihIcgeIu0XMRUKQFskyYaZvbQJEDWUmkA7JIjegVWHNy6OUjOYW4QYpMSSioAeVSiYQLeGlzFmDRYGCiXkLxPgABp2YsS/aAkLyL7SbIQ2U+ShcieGvhin1xq4h0gvbJ3Nk+swZ/G9MEZZooFmKlkDB36cIYhezzv7WHJW8jOkxsAR5i7TOfNAszoOgKoBfXqk6pPz0muA3J3fDXmBBkTN2ITXi4i2lqVhKJHH6sYGXXHyGQP5kbGlJe465tsxSPWHYvoZshYYrsMNpITIbvXhfQpWwgo9eJB2AmfR1Vjjw1eoMhkF1OI1oGV0SNxofZoo8aAX7QXJAbRznOLZc1ZDzlzAtqxp60sEtEEh1XHsGanHwNwWNCm0w0h3mLEjVUnYc1M/d4k55GQVUtbQBUwJpx62q4jEV06iYaZN4fu/MafgtfqXKMlFtGEzrx6gw/sER6u5MuOsf1D94tS6gXAV8b2p2J/+dS58hKJo9tovCwIukTbNrXA+YxJ9cl1QC5ouIiONd+VkqzrOgrEQzI1zIFQALgQzeknh5AJ9ZMSdgDELTpzHDsJ9R0LRfshR4TgkNAUTMRPbyA7nL/ZxymuoQV1iIF8A2PRknDFg7W7j3wD+RnHTX9EdIJZUV4r8r8idPqvUmpLtw/rHBH+oscqV9gCskGhgblrY6+o9xWYmHSAfBWsWEenmAQ7CN9C9q5UpJMyNrEDhGsJDlTLdkC8wyTlZR+g9IR9wLRGYN+9Gf/JYhxSJRkArG7H0P1IWPTfKRMNXIo4/wvaB8IS/U5EWcD22aCUCmpwoV1HHbj9u4GEj2aBUmqnlKqUUmSlUkpJpXdZEHJao5mmYEOFNc4Cmhl9BJ9H65SJhl/NR5E40XoDcyuaMnzcwz60EgvRbJD+mp1PGjcLrcRCVPdAtM+IS31U3gXRPosCqS8cVG0gCJUy5Jp1DBX3ONchEwqGDdFHXYdmuGohUQD44zj+B3FrUnyggY8blqSHHhE1RLQD8LNz+CcR7VLPo8Byey8Wfc/QgCWazA6HbxGVWSveLLefch1lFFXWjbL98CQ6LMr2w4VoG1R+x9BmpfjdDdTXadJSVpdVo+x++UQ0EWl87MP8xHy8Wi4vcCX+DyKqzENbOnZG2nP/w/UB5w40SikN/53Ih8C+ZmgXUkHMu50zrhm+ElFx034P0Zyrwo+2Cv7dZQTONUP7w19MHd/Duh6Xjr96R9pANqut4FmavaqRUM1dz3lyZC8Hz7N3FdwO95cJV7MPXyFQCbQAJ/CUg+0HXaTHFefaq6hEQpYN3mrS0ZV4X6W4nqqtYRZS11Qf7bXw4LvBYGbJ5qy4fId8JRN3xf8ZplK2Hvuh93tYJAoB7xDOqZwL3iVhtsEfs1VaH374kgzAz0df+bg9eHzbPct+Mm8zA8ojkz2Z5NlEPzDZs0j2nnX0IfJ2x5Lw3764B4vqo23HOda9sPsGM4Vbli1kuglIYbfbELJoF2AWH91D+PMVThJEr8S62aw4KNEdwttAGZs4X9FgeFWTONEdwovECde45xdH9hBeJkBsK6UEwa08X+4rhOfrqoUQlehrWOJzzH8BewOTN69gEvI1u5Iz8T+TOcUtjzRRXwAAAABJRU5ErkJggg==";
+
 function pathD(poly) {
   return `M ${poly.map((pt) => `${pt.x} ${pt.y}`).join(" L ")} Z`;
 }
@@ -975,11 +842,13 @@ function BoardView(props) {
     placedSilBySector,
     anchorDots,
     pieces,
+    scaleS,
     clickMode,
     draggingId,
     selectedPieceId,
     dragInvalid,
     lockedPieceId,
+    showTangramDecomposition,
     svgRef,
     setPieceRef,
     onPiecePointerDown,
@@ -1045,7 +914,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;
@@ -1065,11 +934,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",
@@ -1080,51 +950,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";
@@ -1140,10 +997,20 @@ function BoardView(props) {
         }
       )));
     }),
+    /* @__PURE__ */ React.createElement("defs", null, /* @__PURE__ */ React.createElement("filter", { id: "invert-to-white" }, /* @__PURE__ */ React.createElement(
+      "feColorMatrix",
+      {
+        type: "matrix",
+        values: "-1 0 0 0 1\n                     0 -1 0 0 1\n                     0 0 -1 0 1\n                     0 0 0 1 0"
+      }
+    ))),
     (() => {
       const isPrep = controller.state.cfg.mode === "prep";
       const isSubmitEnabled = isPrep ? controller.isSubmitEnabled() : true;
       const isClickable = !draggingId && (!isPrep || isSubmitEnabled);
+      const [imageError, setImageError] = React.useState(false);
+      const iconSize = badgeR * 1.6;
+      const iconOffset = iconSize / 2;
       return /* @__PURE__ */ React.createElement(
         "g",
         {
@@ -1159,7 +1026,7 @@ function BoardView(props) {
             opacity: isSubmitEnabled ? 1 : 0.5
           }
         ),
-        /* @__PURE__ */ React.createElement(
+        isPrep ? /* @__PURE__ */ React.createElement(
           "text",
           {
             textAnchor: "middle",
@@ -1168,7 +1035,29 @@ function BoardView(props) {
             fill: isSubmitEnabled ? CONFIG.color.blueprint.labelFill : "#888",
             pointerEvents: "none"
           },
-          isPrep ? "Submit" : controller.state.blueprintView
+          "Submit"
+        ) : imageError ? /* @__PURE__ */ React.createElement(
+          "text",
+          {
+            textAnchor: "middle",
+            dominantBaseline: "middle",
+            fontSize: CONFIG.size.badgeFontPx,
+            fill: CONFIG.color.blueprint.labelFill,
+            pointerEvents: "none"
+          },
+          "inventory"
+        ) : /* @__PURE__ */ React.createElement(
+          "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)"
+          }
         )
       );
     })(),
@@ -2586,7 +2475,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;
@@ -2603,8 +2492,7 @@ class InteractionTracker {
     this.createdMacros = [];
     this.controller = controller;
     this.callbacks = callbacks;
-    this.trialId = trialId || v4();
-    this.gameId = gameId || v4();
+    this.trialParams = trialParams;
     this.trialStartTime = Date.now();
     this.controller.setTrackingCallbacks({
       onSectorCompleted: (sectorId) => this.recordSectorCompletion(sectorId)
@@ -2652,8 +2540,6 @@ class InteractionTracker {
     const event = {
       // Metadata
       interactionId: v4(),
-      trialId: this.trialId,
-      gameId: this.gameId,
       interactionIndex: this.interactionIndex++,
       // Interaction type
       interactionType,
@@ -2759,6 +2645,7 @@ class InteractionTracker {
     const trialEndTime = Date.now();
     const totalDuration = trialEndTime - this.trialStartTime;
     const finalSnapshot = this.buildStateSnapshot();
+    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);
@@ -2770,13 +2657,11 @@ class InteractionTracker {
       }));
       const data = {
         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,
         completionTimes: this.completionTimes,
         finalBlueprintState,
@@ -2795,13 +2680,11 @@ class InteractionTracker {
       }));
       const data = {
         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,
@@ -3059,6 +2942,9 @@ function GameBoard(props) {
     maxQuickstashSlots,
     maxCompositeSize,
     mode,
+    showTangramDecomposition,
+    instructions,
+    trialParams,
     width: _width,
     height: _height,
     onSectorComplete,
@@ -3068,6 +2954,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,
@@ -3094,8 +2981,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);
@@ -3175,22 +3062,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`,
@@ -3359,7 +3246,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,
@@ -3385,9 +3333,11 @@ function GameBoard(props) {
       onPointerMove,
       onPointerUp,
       onCenterBadgePointerDown,
+      showTangramDecomposition: showTangramDecomposition ?? false,
+      scaleS,
       ...eventCallbacks
     }
-  ));
+  ))));
 }
 
 const U = 40;
@@ -3553,8 +3503,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
@@ -3638,6 +3589,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 }
@@ -3691,6 +3644,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: void 0,
+      description: "HTML content to display above the gameboard as instructions"
+    },
     /** Callback fired after each interaction (optional analytics hook) */
     onInteraction: {
       type: ParameterType.FUNCTION,
@@ -3742,6 +3701,7 @@ class TangramPrepPlugin {
       requireAllSlots: trial.require_all_slots,
       quickstashMacros: trial.quickstash_macros,
       primitiveOrder: trial.primitive_order,
+      instructions: trial.instructions,
       onInteraction: trial.onInteraction,
       onTrialEnd: wrappedOnTrialEnd
     };