jspsych-tangram 0.0.7 → 0.0.9

package/package.json

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

package/src/assets/README.md

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

package/src/assets/images.d.ts

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

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

@@ -1,10 +1,14 @@
 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";
 
+// Import lock/unlock icons
+import lockedIcon from "@/assets/locked.png";
+import unlockedIcon from "@/assets/unlocked.png";
+
 export type PieceView = { id: string; blueprintId: string; x: number; y: number; sectorId?: string };
 export type AnchorDots = { sectorId: string; valid: {x:number;y:number}[]; invalid: {x:number;y:number}[] };
 
@@ -21,6 +25,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 +33,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 +61,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;
@@ -87,12 +93,12 @@ export default function BoardView(props: BoardViewProps) {
     : CONFIG.layout.constraints.quickstashDiamAnchors;
   const D_slot = anchorsDiameterToPx(reqAnchors);
   const R_needed = D_slot / (2 * Math.max(1e-9, Math.sin(delta / 2)));
-  
+
   // Minimum radius to avoid overlapping with badge
   // Badge takes up: badgeR + margin, plus we need half the slot diameter for clearance
   const R_min = badgeR + CONFIG.size.centerBadge.marginPx + D_slot / 2;
   const ringMax = layout.innerR - (badgeR + CONFIG.size.centerBadge.marginPx);
-  
+
   // Clamp to [R_min, ringMax]
   const blueprintRingR = Math.min(Math.max(R_needed, R_min), ringMax);
 
@@ -136,7 +142,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) => {
@@ -193,7 +199,7 @@ export default function BoardView(props: BoardViewProps) {
                     stroke="none"
                     onPointerDown={(e) => onPiecePointerDown(e, p)}
                   />
-                  
+
                   {/* Border paths - only rendered if borders are enabled */}
                   {showBorders && (
                     useSelectiveBorders ? (
@@ -203,32 +209,32 @@ export default function BoardView(props: BoardViewProps) {
                         const pieceAsPiece = { ...p, pos: { x: p.x, y: p.y } };
                         const allPiecesAsPieces = allPiecesInSector.map(piece => ({ ...piece, pos: { x: piece.x, y: piece.y } }));
                         const hiddenEdges = getHiddenEdgesForPolygon(pieceAsPiece, idx, allPiecesAsPieces, (id) => controller.getBlueprint(id), (kind) => controller.getPrimitive(kind));
-                        
+
                         // Check if this piece's edges were hidden due to touching the dragged piece
                         const draggedPiece = draggingId ? allPiecesInSector.find(piece => piece.id === draggingId) : null;
-                        
+
                         // For composites, we need to distinguish between internal edges (always hidden) and external edges (shown when dragging)
                         let wasTouchingDraggedPiece: boolean[];
                         if (p.blueprintId.startsWith('comp:')) {
                           // For composites, check internal edges separately from external edges
                           const internalHiddenEdges = getHiddenEdgesForPolygon(pieceAsPiece, idx, [], (id) => controller.getBlueprint(id), (kind) => controller.getPrimitive(kind));
-                          const externalHiddenEdges = draggedPiece ? 
-                            getHiddenEdgesForPolygon(pieceAsPiece, idx, [{ ...draggedPiece, pos: { x: draggedPiece.x, y: draggedPiece.y } }], (id) => controller.getBlueprint(id), (kind) => controller.getPrimitive(kind)) : 
+                          const externalHiddenEdges = draggedPiece ?
+                            getHiddenEdgesForPolygon(pieceAsPiece, idx, [{ ...draggedPiece, pos: { x: draggedPiece.x, y: draggedPiece.y } }], (id) => controller.getBlueprint(id), (kind) => controller.getPrimitive(kind)) :
                             new Array(hiddenEdges.length).fill(false);
-                          
+
                           // Only consider external edges as "touching dragged piece"
                           wasTouchingDraggedPiece = externalHiddenEdges.map((external, i) => external && !internalHiddenEdges[i]);
                         } else {
                           // For primitives, all hidden edges are external
-                          wasTouchingDraggedPiece = draggedPiece ? 
-                            getHiddenEdgesForPolygon(pieceAsPiece, idx, [{ ...draggedPiece, pos: { x: draggedPiece.x, y: draggedPiece.y } }], (id) => controller.getBlueprint(id), (kind) => controller.getPrimitive(kind)) : 
+                          wasTouchingDraggedPiece = draggedPiece ?
+                            getHiddenEdgesForPolygon(pieceAsPiece, idx, [{ ...draggedPiece, pos: { x: draggedPiece.x, y: draggedPiece.y } }], (id) => controller.getBlueprint(id), (kind) => controller.getPrimitive(kind)) :
                             new Array(hiddenEdges.length).fill(false);
                         }
-                        
+
                         return generateEdgeStrokePaths(poly).map((strokePath, strokeIdx) => {
                           // Show border if: 1) it wasn't hidden originally, OR 2) it was hidden due to touching the dragged piece
                           const wasHiddenDueToDraggedPiece = wasTouchingDraggedPiece[strokeIdx] || false;
-                          
+
                           // Special case: if this piece is being dragged and it's a composite, keep internal edges hidden
                           let isHidden: boolean;
                           if (isDragging && p.blueprintId.startsWith('comp:')) {
@@ -239,7 +245,7 @@ export default function BoardView(props: BoardViewProps) {
                             // Normal logic for non-dragged pieces or primitives
                             isHidden = isDragging ? false : ((hiddenEdges[strokeIdx] || false) && !wasHiddenDueToDraggedPiece);
                           }
-                          
+
                           return (
                             <path
                               key={`stroke-${idx}-${strokeIdx}`}
@@ -272,15 +278,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 */}
@@ -305,26 +348,65 @@ export default function BoardView(props: BoardViewProps) {
         );
       })}
 
+      {/* SVG filter for inverting icon colors to white */}
+      <defs>
+        <filter id="invert-to-white">
+          <feColorMatrix
+            type="matrix"
+            values="-1 0 0 0 1
+                     0 -1 0 0 1
+                     0 0 -1 0 1
+                     0 0 0 1 0"
+          />
+        </filter>
+      </defs>
+
       {/* center badge */}
       {(() => {
         const isPrep = controller.state.cfg.mode === "prep";
         const isSubmitEnabled = isPrep ? controller.isSubmitEnabled() : true;
         const isClickable = !draggingId && (!isPrep || isSubmitEnabled);
-        
+        const [imageError, setImageError] = React.useState(false);
+
+        // Size the image to fill most of the badge (80% of diameter)
+        const iconSize = badgeR * 1.6;
+        const iconOffset = iconSize / 2;
+
         return (
-          <g transform={`translate(${badgeCenter.x}, ${badgeCenter.y})`} 
-             style={{ cursor: isClickable ? "pointer" : "default" }} 
+          <g transform={`translate(${badgeCenter.x}, ${badgeCenter.y})`}
+             style={{ cursor: isClickable ? "pointer" : "default" }}
              onPointerDown={isClickable ? onCenterBadgePointerDown : undefined}>
-            <circle r={badgeR} 
-                    fill={isSubmitEnabled ? CONFIG.color.blueprint.badgeFill : "#ccc"} 
+            <circle r={badgeR}
+                    fill={isSubmitEnabled ? CONFIG.color.blueprint.badgeFill : "#ccc"}
                     opacity={isSubmitEnabled ? 1.0 : 0.5} />
-            <text textAnchor="middle" 
-                  dominantBaseline="middle" 
-                  fontSize={CONFIG.size.badgeFontPx} 
-                  fill={isSubmitEnabled ? CONFIG.color.blueprint.labelFill : "#888"} 
-                  pointerEvents="none">
-              {isPrep ? "Submit" : controller.state.blueprintView}
-            </text>
+            {isPrep ? (
+              <text textAnchor="middle"
+                    dominantBaseline="middle"
+                    fontSize={CONFIG.size.badgeFontPx}
+                    fill={isSubmitEnabled ? CONFIG.color.blueprint.labelFill : "#888"}
+                    pointerEvents="none">
+                Submit
+              </text>
+            ) : imageError ? (
+              <text textAnchor="middle"
+                    dominantBaseline="middle"
+                    fontSize={CONFIG.size.badgeFontPx}
+                    fill={CONFIG.color.blueprint.labelFill}
+                    pointerEvents="none">
+                inventory
+              </text>
+            ) : (
+              <image
+                href={controller.state.blueprintView === "quickstash" ? lockedIcon : unlockedIcon}
+                x={-iconOffset}
+                y={-iconOffset}
+                width={iconSize}
+                height={iconSize}
+                pointerEvents="none"
+                onError={() => setImageError(true)}
+                filter="url(#invert-to-white)"
+              />
+            )}
           </g>
         );
       })()}

package/src/core/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;
@@ -53,7 +55,8 @@ export const CONFIG: 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,
@@ -63,7 +66,7 @@ export const CONFIG: 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.0, invalid: 1.0 },
     badgeFontPx: 16,
     centerBadge: { fractionOfOuterR: 0.15, minPx: 20, marginPx: 4 }
@@ -71,6 +74,7 @@ export const CONFIG: Config = {
   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
@@ -80,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 = {