jspsych-tangram 0.0.13 → 0.0.15

package/package.json

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

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

@@ -718,15 +718,25 @@ export default function GameBoard(props: GameBoardProps) {
     textAlign: 'center'
   };
 
-  // Timer style (positioned absolutely to not affect centering)
+  // Timer style - positioned absolutely to align right edge with semicircle's right edge
+  // Independent of instructions content
+  const scaleX = svgDimensions.width / viewBox.w;
+  const rightEdgeOfSemicircleLogical = viewBox.w / 2 + layout.outerR;
+  const distanceFromRightEdgeLogical = viewBox.w - rightEdgeOfSemicircleLogical;
+  const distanceFromRightEdgePx = distanceFromRightEdgeLogical * scaleX;
+
+  // Shift left by 5 monospaced characters (monospace is typically 0.6em wide per char)
+  const charWidth = 24 * 0.6; // fontSize * typical monospace char width ratio
+  const offsetLeft = charWidth * 5;
+
   const timerStyle: React.CSSProperties = {
     position: 'absolute',
-    right: 0,
+    right: `${distanceFromRightEdgePx + offsetLeft}px`,
     fontSize: '24px',
     fontWeight: 'bold',
     fontFamily: 'monospace',
     color: '#333',
-    minWidth: '80px',
+    whiteSpace: 'nowrap',
     textAlign: 'right'
   };
 
@@ -797,42 +807,3 @@ export default function GameBoard(props: GameBoardProps) {
     </div>
   );
 }
-
-/**
- * Hook for managing GameBoard state externally
- * Useful for plugins that need direct access to game state
- */
-export function useGameBoard(config: GameBoardConfig) {
-  const controller = React.useMemo(() => {
-    const gameConfig = {
-      n: config.sectors.length,
-      layout: config.layout,
-      target: config.target,
-      input: config.input,
-      timeLimitMs: config.timeLimitMs,
-      maxQuickstashSlots: config.maxQuickstashSlots,
-      ...(config.maxCompositeSize !== undefined && { maxCompositeSize: config.maxCompositeSize }),
-      mode: config.mode || "construction",
-      ...(config.minPiecesPerMacro !== undefined && { minPiecesPerMacro: config.minPiecesPerMacro }),
-      ...(config.requireAllSlots !== undefined && { requireAllSlots: config.requireAllSlots })
-    };
-
-    return new BaseGameController(
-      config.sectors,
-      config.quickstash,
-      config.primitives,
-      gameConfig
-    );
-  }, [config]);
-
-  const snapshot = React.useMemo(() =>
-    controller.snapshot(),
-    [controller.updateCount]
-  );
-
-  return {
-    controller,
-    snapshot,
-    isComplete: !!controller.state.endedAt
-  };
-}

package/src/core/components/board/useGameBoard.ts

@@ -0,0 +1,52 @@
+/**
+ * Hook for managing GameBoard state externally
+ *
+ * This hook provides external access to the GameBoard's internal state
+ * management, useful for plugins that need to track or control game state
+ * directly without rendering the full GameBoard component.
+ *
+ * REQUIRES: config contains valid GameBoardConfig properties
+ * EFFECTS: Creates and manages a BaseGameController instance
+ *
+ * @param config - GameBoard configuration object
+ * @returns Object containing controller, snapshot, and completion status
+ */
+
+import React from "react";
+import { BaseGameController } from "@/core/engine/state/BaseGameController";
+import type { GameBoardConfig } from "./GameBoard";
+
+export function useGameBoard(config: GameBoardConfig) {
+  const controller = React.useMemo(() => {
+    const gameConfig = {
+      n: config.sectors.length,
+      layout: config.layout,
+      target: config.target,
+      input: config.input,
+      timeLimitMs: config.timeLimitMs,
+      maxQuickstashSlots: config.maxQuickstashSlots,
+      ...(config.maxCompositeSize !== undefined && { maxCompositeSize: config.maxCompositeSize }),
+      mode: config.mode || "construction",
+      ...(config.minPiecesPerMacro !== undefined && { minPiecesPerMacro: config.minPiecesPerMacro }),
+      ...(config.requireAllSlots !== undefined && { requireAllSlots: config.requireAllSlots })
+    };
+
+    return new BaseGameController(
+      config.sectors,
+      config.quickstash,
+      config.primitives,
+      gameConfig
+    );
+  }, [config]);
+
+  const snapshot = React.useMemo(() =>
+    controller.snapshot(),
+    [controller.updateCount]
+  );
+
+  return {
+    controller,
+    snapshot,
+    isComplete: !!controller.state.endedAt
+  };
+}

package/src/core/components/index.ts

@@ -6,11 +6,13 @@
  */
 
 // Core game board component
-export { default as GameBoard, useGameBoard } from './board/GameBoard';
+export { default as GameBoard } from './board/GameBoard';
+export { useGameBoard } from './board/useGameBoard';
 export type { GameBoardConfig, GameBoardProps } from './board/GameBoard';
 
 // Blueprint ring component for plugin UI
-export { default as BlueprintRing, useBlueprintRing } from './pieces/BlueprintRing';
+export { default as BlueprintRing } from './pieces/BlueprintRing';
+export { useBlueprintRing } from './pieces/useBlueprintRing';
 export type { BlueprintRingProps } from './pieces/BlueprintRing';
 
 // Legacy Board components (deprecated - use GameBoard instead)

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

@@ -268,29 +268,4 @@ export default function BlueprintRing(props: BlueprintRingProps) {
       })}
     </g>
   );
-}
-
-/**
- * Hook for managing blueprint ring state
- * Useful for components that need more control over blueprint ring behavior
- */
-export function useBlueprintRing(
-  primitives: PrimitiveBlueprint[],
-  quickstash: Blueprint[],
-  initialView: "primitives" | "quickstash" = "quickstash"
-) {
-  const [currentView, setCurrentView] = React.useState<"primitives" | "quickstash">(initialView);
-
-  const switchView = React.useCallback(() => {
-    setCurrentView(prev => prev === "primitives" ? "quickstash" : "primitives");
-  }, []);
-
-  const blueprints = currentView === "primitives" ? primitives : quickstash;
-
-  return {
-    currentView,
-    blueprints,
-    switchView,
-    setCurrentView
-  };
 }

package/src/core/components/pieces/useBlueprintRing.ts

@@ -0,0 +1,39 @@
+/**
+ * Hook for managing BlueprintRing state externally
+ *
+ * This hook manages the state for switching between primitives and quickstash
+ * views in the blueprint ring. Useful for components that need more control
+ * over blueprint ring behavior.
+ *
+ * REQUIRES: primitives and quickstash are valid arrays of blueprints
+ * EFFECTS: Manages view state and provides toggle functionality
+ *
+ * @param primitives - Array of primitive piece blueprints
+ * @param quickstash - Array of quickstash macro blueprints
+ * @param initialView - Initial view to display (defaults to "quickstash")
+ * @returns Object with current view, blueprints, and control functions
+ */
+
+import React from "react";
+import type { Blueprint, PrimitiveBlueprint } from "@/core/domain/types";
+
+export function useBlueprintRing(
+  primitives: PrimitiveBlueprint[],
+  quickstash: Blueprint[],
+  initialView: "primitives" | "quickstash" = "quickstash"
+) {
+  const [currentView, setCurrentView] = React.useState<"primitives" | "quickstash">(initialView);
+
+  const switchView = React.useCallback(() => {
+    setCurrentView(prev => prev === "primitives" ? "quickstash" : "primitives");
+  }, []);
+
+  const blueprints = currentView === "primitives" ? primitives : quickstash;
+
+  return {
+    currentView,
+    blueprints,
+    switchView,
+    setCurrentView
+  };
+}

package/src/index.ts

@@ -1,3 +1,4 @@
 export { default as TangramConstructPlugin } from "./plugins/tangram-construct";
 export { default as TangramPrepPlugin } from "./plugins/tangram-prep";
-export { default as TangramNBackPlugin } from "./plugins/tangram-nback";
+export { default as TangramNBackPlugin } from "./plugins/tangram-nback";
+export { default as TangramAFCPlugin } from "./plugins/tangram-afc";

package/src/plugins/tangram-afc/AFCApp.tsx

@@ -0,0 +1,341 @@
+/**
+ * AFCApp.tsx - React wrapper for tangram alternative forced choice (AFC) trials
+ *
+ * This component handles the React rendering logic for AFC trials,
+ * displaying two tangram silhouettes side-by-side with response buttons.
+ */
+
+import React, { useRef, useState } from "react";
+import { createRoot } from "react-dom/client";
+import { JsPsych } from "jspsych";
+import type { Poly, TanKind } from "../../core/domain/types";
+import { placeSilhouetteGridAlignedAsPolys, inferUnitFromPolys } from "../../core/engine/geometry";
+import { CONFIG } from "../../core/config/config";
+
+export interface StartAFCTrialParams {
+  tangramLeft: any;
+  tangramRight: any;
+  instructions?: string;
+  buttonTextLeft?: string;
+  buttonTextRight?: string;
+  showTangramDecomposition?: boolean;
+  usePrimitiveColors?: boolean;
+  primitiveColorIndices?: number[];
+  onTrialEnd?: (data: any) => void;
+}
+
+/**
+ * Start an AFC trial by rendering the AFCView component
+ */
+export function startAFCTrial(
+  display_element: HTMLElement,
+  params: StartAFCTrialParams,
+  _jsPsych: JsPsych
+) {
+  // Create React root and render AFCView
+  const root = createRoot(display_element);
+  root.render(React.createElement(AFCView, { params }));
+
+  return { root, display_element, jsPsych: _jsPsych };
+}
+
+interface AFCViewProps {
+  params: StartAFCTrialParams;
+}
+
+function AFCView({ params }: AFCViewProps) {
+  const {
+    tangramLeft,
+    tangramRight,
+    instructions,
+    buttonTextLeft,
+    buttonTextRight,
+    showTangramDecomposition,
+    usePrimitiveColors,
+    primitiveColorIndices,
+    onTrialEnd
+  } = params;
+
+  // Timing and response tracking
+  const trialStartTime = useRef<number>(Date.now());
+  const [hasResponded, setHasResponded] = useState(false);
+
+  const handleResponse = (choice: "left" | "right") => {
+    if (hasResponded) return;
+
+    setHasResponded(true);
+    const rt = Date.now() - trialStartTime.current;
+
+    if (onTrialEnd) {
+      onTrialEnd({
+        rt,
+        response: choice,
+        show_tangram_decomposition: showTangramDecomposition,
+        use_primitive_colors: usePrimitiveColors,
+        primitive_color_indices: primitiveColorIndices,
+        button_text_left: buttonTextLeft,
+        button_text_right: buttonTextRight
+      });
+    }
+  };
+
+  return (
+    <div style={{
+      display: "flex",
+      flexDirection: "column",
+      alignItems: "center",
+      justifyContent: "center",
+      padding: "20px",
+      background: "#fff7e0ff",
+      minHeight: "100vh"
+    }}>
+      {/* Instructions */}
+      {instructions && (
+        <div
+          style={{
+            maxWidth: "800px",
+            width: "100%",
+            marginBottom: "30px",
+            textAlign: "center",
+            fontSize: "18px",
+            lineHeight: "1.5"
+          }}
+          dangerouslySetInnerHTML={{ __html: instructions }}
+        />
+      )}
+
+      {/* Container for Tangrams */}
+      <div style={{
+        display: "flex",
+        flexDirection: "row",
+        gap: "50px",
+        justifyContent: "center",
+        alignItems: "flex-start",
+        flexWrap: "wrap"
+      }}>
+        {/* Left Option */}
+        <TangramOption
+          tangram={tangramLeft}
+          buttonText={buttonTextLeft}
+          onClick={() => handleResponse("left")}
+          disabled={hasResponded}
+          showDecomposition={showTangramDecomposition}
+          usePrimitiveColors={usePrimitiveColors}
+          primitiveColorIndices={primitiveColorIndices}
+        />
+
+        {/* Right Option */}
+        <TangramOption
+          tangram={tangramRight}
+          buttonText={buttonTextRight}
+          onClick={() => handleResponse("right")}
+          disabled={hasResponded}
+          showDecomposition={showTangramDecomposition}
+          usePrimitiveColors={usePrimitiveColors}
+          primitiveColorIndices={primitiveColorIndices}
+        />
+      </div>
+    </div>
+  );
+}
+
+interface TangramOptionProps {
+  tangram: any;
+  buttonText: string;
+  onClick: () => void;
+  disabled: boolean;
+  showDecomposition?: boolean;
+  usePrimitiveColors?: boolean;
+  primitiveColorIndices?: number[];
+}
+
+function TangramOption({
+  tangram,
+  buttonText,
+  onClick,
+  disabled,
+  showDecomposition,
+  usePrimitiveColors,
+  primitiveColorIndices
+}: TangramOptionProps) {
+
+  if (!tangram) {
+    return <div style={{ width: 300, height: 300, background: "#eee" }}>No Tangram Data</div>;
+  }
+
+  // Canonical piece names
+  const CANON = new Set([
+    "square",
+    "smalltriangle",
+    "parallelogram",
+    "medtriangle",
+    "largetriangle",
+  ]);
+
+  // Convert TangramSpec to internal format
+  const filteredTans = tangram.solutionTans.filter((tan: any) => {
+    const tanName = tan.name ?? tan.kind;
+    return CANON.has(tanName);
+  });
+
+  const mask = filteredTans.map((tan: any) => {
+    const polygon = tan.vertices.map(([x, y]: number[]) => ({ x: x ?? 0, y: -(y ?? 0) }));
+    return polygon;
+  });
+
+  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) }))
+  }));
+
+  // Use FIXED viewport size
+  const DISPLAY_SIZE = 300;
+  const viewport = {
+    w: DISPLAY_SIZE,
+    h: DISPLAY_SIZE
+  };
+
+  // Compute scale factor
+  const scaleS = React.useMemo(() => {
+    const u = inferUnitFromPolys(mask);
+    return u ? (CONFIG.layout.grid.unitPx / u) : 1;
+  }, [mask]);
+
+  const centerPos = {
+    cx: viewport.w / 2,
+    cy: viewport.h / 2
+  };
+
+  const pathD = (poly: Poly): string => {
+    if (!poly || poly.length === 0) return "";
+    const moves = poly.map((p, i) => `${i === 0 ? "M" : "L"} ${p.x} ${p.y}`);
+    return moves.join(" ") + " Z";
+  };
+
+  const renderSilhouette = () => {
+    if (showDecomposition) {
+      const rawPolys = primitiveDecomposition.map((primInfo: any) => primInfo.polygon);
+      const placedPolys = placeSilhouetteGridAlignedAsPolys(rawPolys, scaleS, centerPos);
+
+      return (
+        <g key="sil-decomposed" pointerEvents="none">
+          {placedPolys.map((scaledPoly, i) => {
+            const primInfo = primitiveDecomposition[i];
+            let fillColor = CONFIG.color.silhouetteMask;
+
+            if (usePrimitiveColors && primInfo?.kind && primitiveColorIndices) {
+              const kindToIndex: Record<TanKind, number> = {
+                'square': 0,
+                'smalltriangle': 1,
+                'parallelogram': 2,
+                'medtriangle': 3,
+                'largetriangle': 4
+              };
+              const primitiveIndex = kindToIndex[primInfo.kind as TanKind];
+              if (primitiveIndex !== undefined && primitiveColorIndices[primitiveIndex] !== undefined) {
+                const colorIndex = primitiveColorIndices[primitiveIndex];
+                const color = CONFIG.color.primitiveColors[colorIndex];
+                if (color) {
+                  fillColor = color;
+                }
+              }
+            }
+
+            return (
+              <React.Fragment key={`prim-${i}`}>
+                <path
+                  d={pathD(scaledPoly)}
+                  fill={fillColor}
+                  opacity={usePrimitiveColors ? CONFIG.opacity.piece.normal : CONFIG.opacity.silhouetteMask}
+                  stroke="none"
+                />
+                <path
+                  d={pathD(scaledPoly)}
+                  fill="none"
+                  stroke={CONFIG.color.tangramDecomposition.stroke}
+                  strokeWidth={CONFIG.size.stroke.tangramDecompositionPx}
+                />
+              </React.Fragment>
+            );
+          })}
+        </g>
+      );
+    } else {
+      const placedPolys = placeSilhouetteGridAlignedAsPolys(mask, scaleS, centerPos);
+
+      return (
+        <g key="sil-unified" pointerEvents="none">
+          {placedPolys.map((scaledPoly, i) => {
+            const primInfo = primitiveDecomposition[i];
+            let fillColor = CONFIG.color.silhouetteMask;
+
+            if (usePrimitiveColors && primInfo?.kind && primitiveColorIndices) {
+              const kindToIndex: Record<TanKind, number> = {
+                'square': 0,
+                'smalltriangle': 1,
+                'parallelogram': 2,
+                'medtriangle': 3,
+                'largetriangle': 4
+              };
+              const primitiveIndex = kindToIndex[primInfo.kind as TanKind];
+              if (primitiveIndex !== undefined && primitiveColorIndices[primitiveIndex] !== undefined) {
+                const colorIndex = primitiveColorIndices[primitiveIndex];
+                const color = CONFIG.color.primitiveColors[colorIndex];
+                if (color) {
+                  fillColor = color;
+                }
+              }
+            }
+
+            return (
+              <path
+                key={`sil-${i}`}
+                d={pathD(scaledPoly)}
+                fill={fillColor}
+                opacity={usePrimitiveColors ? CONFIG.opacity.piece.normal : CONFIG.opacity.silhouetteMask}
+                stroke="none"
+              />
+            );
+          })}
+        </g>
+      );
+    }
+  };
+
+  return (
+    <div style={{
+      display: "flex",
+      flexDirection: "column",
+      alignItems: "center",
+      gap: "20px"
+    }}>
+      <svg
+        width={viewport.w}
+        height={viewport.h}
+        viewBox={`0 0 ${viewport.w} ${viewport.h}`}
+        style={{
+          display: "block",
+          background: CONFIG.color.bands.silhouette.fillEven,
+          border: `${CONFIG.size.stroke.bandPx}px solid ${CONFIG.color.bands.silhouette.stroke}`,
+          borderRadius: "8px"
+        }}
+      >
+        {renderSilhouette()}
+      </svg>
+
+      <button
+        className="jspsych-btn"
+        onClick={onClick}
+        disabled={disabled}
+        style={{
+          padding: "12px 30px",
+          fontSize: "16px",
+          cursor: disabled ? "not-allowed" : "pointer",
+          opacity: disabled ? 0.5 : 1
+        }}
+      >
+        {buttonText}
+      </button>
+    </div>
+  );
+}