jspsych-tangram 0.0.1

package/src/core/io/data-tracking.ts

@@ -0,0 +1,271 @@
+/**
+ * Data tracking types for experiment data collection
+ *
+ * This module defines the schema for capturing user interactions and trial outcomes.
+ * Two main callback points:
+ * 1. onInteraction - fires after each place-down (complete interaction)
+ * 2. onTrialEnd - fires once when trial completes
+ */
+
+// ===== Interaction Event =====
+// Fired when a piece is placed down (spawn, move, or delete)
+
+/**
+ * Interaction event
+ */
+export interface InteractionEvent {
+  // === Event Metadata ===
+  interactionId: string;          // UUID for this interaction
+  trialId: string;                // UUID for the trial
+  gameId: string;                 // UUID for the game session
+  interactionIndex: number;       // Sequential counter (0, 1, 2, ...) within the trial
+
+  // === Interaction Type ===
+  interactionType: "spawn" | "move" | "delete";
+
+  // === Piece Information ===
+  pieceId: string;
+  blueprintId: string;
+  blueprintType: "primitive" | "composite";
+
+  // === Pickup Event ===
+  pickupTimestamp: number;        // timestamp in ms (Date.now()) when piece was picked up
+  pickupSource: "blueprint" | "sector";  // Where piece came from
+  pickupSectorId: string | undefined; // Defined if pickupSource is "sector"
+  pickupPosition: { x: number; y: number };
+  pickupVertices: number[][][];   // World-space polygons at pickup
+
+  // === Placedown Event ===
+  placedownTimestamp: number;     // timestamp in ms (Date.now()) when piece was placed down
+  placedownOutcome: "placed" | "deleted";
+  // If placed: position/vertices/sector required; if deleted: all undefined
+  placedownSectorId?: string;     // Target sector (required if placed, undefined if deleted)
+  placedownPosition?: { x: number; y: number };  // Required if placed, undefined if deleted
+  placedownVertices?: number[][][];  // Required if placed, undefined if deleted
+  placedownAnchorId?: string;     // Which anchor was snapped to (only if placed)
+
+  // === Validation Context ===
+  // Only relevant if placed (always false if deleted)
+  wasValid: boolean;              // Was placement valid at drop time
+  wasOverlapping: boolean;        // Was overlapping with other pieces
+
+  // === Timing ===
+  holdDuration: number;           // ms between pickup and placedown
+
+  // === Click Events ===
+  // All click-related events that occurred before/during this interaction
+  // Includes blueprint switches, invalid placement attempts, etc.
+  clickEvents: Array<{
+    timestamp: number;            // timestamp in ms (Date.now())
+    location: { x: number; y: number }; // Anchor grid coordinates for the click
+    clickType: "blueprint_view_switch" | "invalid_placement" | "sector_complete_attempt";
+    // Type-specific data
+    blueprintViewSwitch?: {
+      from: "quickstash" | "primitives";
+      to: "quickstash" | "primitives";
+    };
+    invalidPlacement?: {
+      reason: "overlapping" | "outside_bounds" | "no_valid_anchor" | "sector_complete";
+      attemptedSectorId?: string;
+    };
+  }>;
+
+  // === Mouse Tracking (Discrete Anchor Coordinates) ===
+  // Only logged when mouse snaps to a different anchor point
+  // Covers entire interaction: before pickup + while holding piece
+  mouseTracking: Array<{
+    timestamp: number;            // timestamp in ms (Date.now())
+    anchorX: number;              // Anchor grid X coordinate
+    anchorY: number;              // Anchor grid Y coordinate
+    sectorId: string | undefined; // Which sector mouse is in (undefined if in inner ring)
+    phase: "before_pickup" | "while_holding";  // Before or during interaction
+  }>;
+
+  // === State Snapshots (for replay) ===
+  preSnapshotId?: string;         // UUID of previous interaction (null if first interaction)
+  postSnapshot: StateSnapshot;    // State after this interaction
+}
+
+// ===== State Snapshot =====
+
+/**
+ * Complete state snapshot at a point in time
+ * Used for pre/post interaction snapshots and final state
+ */
+export interface StateSnapshot {
+  snapshotId: string;             // UUID for this snapshot
+  timestamp: number;              // timestamp in ms (Date.now())
+  sectors: SectorSnapshot[];
+  completedSectorIds: string[];
+
+  // Maps sector IDs to tangram targets (static for trial, but included for completeness)
+  sectorTangramMap: Array<{
+    sectorId: string;
+    tangramId: string;            // Which tangram target this sector represents
+  }>;
+
+  // Blueprint ring order (primitives and quickstash)
+  // Captures the current state of available blueprints in the center ring
+  blueprintOrder: {
+    primitives: string[];         // Ordered list of primitive blueprint IDs
+    quickstash: string[];         // Ordered list of quickstash blueprint IDs
+  };
+}
+
+// ===== Trial-End Data =====
+
+/**
+ * Base trial data shared between construction and prep trials
+ */
+export interface BaseTrialData {
+  // Trial identifiers
+  trialId: string;                // UUID for this trial
+  gameId: string;                 // UUID for game session
+  trialNum: number;               // Trial number in experiment sequence
+
+  // Timing
+  trialStartTime: number;         // Absolute timestamp (Date.now())
+  trialEndTime: number;           // Absolute timestamp (Date.now())
+  totalDuration: number;          // duration in ms (trialEndTime - trialStartTime)
+
+  // Final state snapshot
+  finalSnapshot: StateSnapshot;
+}
+
+/**
+ * Construction trial end data
+ */
+export interface ConstructionTrialData extends BaseTrialData {
+  trialType: "construction";
+
+  // End reason (construction-specific)
+  endReason: "timeout" | "auto_complete";
+
+  // Construction-specific data
+  completionTimes: Array<{
+    sectorId: string;
+    completedAt: number;          // timestamp in ms (Date.now())
+  }>;
+
+  // Final blueprint state (usage counts + definitions)
+  finalBlueprintState: Array<{
+    blueprintId: string;
+    blueprintType: "primitive" | "composite";
+    totalPieces: number;          // Total across all sectors
+    bySector: Array<{
+      sectorId: string;
+      count: number;
+    }>;
+    // Blueprint definition (for composites)
+    parts?: Array<{
+      kind: string;
+      anchorOffset: { x: number; y: number };
+    }>;
+    shape?: Array<Array<{ x: number; y: number }>>; // Shape in anchor coordinates
+    label?: string;
+  }>;
+
+  // Quickstash macros ready for next trial (composites only, in plugin input format)
+  quickstashMacros: Array<{
+    id: string;
+    parts: Array<{
+      kind: string;
+      anchorOffset: { x: number; y: number };
+    }>;
+    label?: string;
+  }>;
+}
+
+/**
+ * Prep trial end data
+ */
+export interface PrepTrialData extends BaseTrialData {
+  trialType: "prep";
+
+  // End reason (prep-specific)
+  endReason: "submit";
+
+  // Prep-specific data: created macros
+  createdMacros: MacroSnapshot[];
+
+  // Quickstash macros ready for next trial (in plugin input format)
+  quickstashMacros: Array<{
+    id: string;
+    parts: Array<{
+      kind: string;
+      anchorOffset: { x: number; y: number };
+    }>;
+    label?: string;
+  }>;
+}
+
+/**
+ * Union type for any trial data
+ */
+export type TrialEndData = ConstructionTrialData | PrepTrialData;
+
+/**
+ * Snapshot of a sector's final state
+ */
+export interface SectorSnapshot {
+  sectorId: string;
+  completed: boolean;
+  completedAt?: number;           // timestamp in ms (Date.now()) (undefined if not completed)
+  pieceCount: number;
+  pieces: PieceSnapshot[];
+}
+
+/**
+ * Snapshot of a single piece's final state
+ */
+export interface PieceSnapshot {
+  pieceId: string;
+  blueprintId: string;
+  blueprintType: "primitive" | "composite";
+  position: { x: number; y: number };
+  vertices: number[][][];
+}
+
+/**
+ * Snapshot of a created macro (prep mode only)
+ */
+export interface MacroSnapshot {
+  macroId: string;                // sector ID (prep mode uses sectors as macro slots)
+  parts: Array<{
+    kind: string;                 // TanKind
+    anchorOffset: { x: number; y: number }; // Relative offset in anchor coordinates (centroid-based)
+  }>;
+  shape: number[][][];            // Union shape polygons
+  pieceCount: number;
+}
+
+// ===== Callback Interface =====
+
+/**
+ * Callbacks for data tracking
+ * Provide these to the InteractionTracker to receive data events
+ */
+export interface DataTrackingCallbacks {
+  /**
+   * Called immediately after each complete interaction (when piece is placed down)
+   * Use this for incremental data saving (e.g., socket.emit())
+   */
+  onInteraction?: (event: InteractionEvent) => void;
+
+  /**
+   * Called once when trial ends
+   * Contains complete interaction history + final state
+   * Type discriminated by trialType: "construction" | "prep"
+   */
+  onTrialEnd?: (data: TrialEndData) => void;
+}
+
+// ===== Helper Type Guards =====
+
+export function isConstructionTrial(data: TrialEndData): data is ConstructionTrialData {
+  return data.trialType === "construction";
+}
+
+export function isPrepTrial(data: TrialEndData): data is PrepTrialData {
+  return data.trialType === "prep";
+}

package/src/core/io/json-to-tangram-spec.ts

@@ -0,0 +1,110 @@
+// Convert raw stims JSON to clean TangramSpec[] for plugin interface
+import type { TangramSpec } from "@/core/types/plugin-interfaces";
+
+/** Raw JSON shapes from dev/assets/stims_dev.json */
+type RawTan = {
+  name: string;
+  verticesAtOrigin: Array<[number, number] | { x: number; y: number }>;
+};
+
+type RawStim = {
+  solutionTans: RawTan[];
+  stimImgPath?: string;
+  stimSilhouetteImgPath?: string;
+  set?: string;
+  id?: string | number;
+};
+
+/** Canonical tangram names we accept as actual piece polys. */
+const CANON = new Set([
+  "square",
+  "small_triangle", 
+  "parallelogram",
+  "med_triangle",
+  "large_triangle",
+]);
+
+// ----------------------- guards & converters -----------------------
+function isPoint(a: unknown): a is [number, number] {
+  return Array.isArray(a) && a.length >= 2
+    && typeof a[0] === "number" && typeof a[1] === "number";
+}
+
+function isPointObj(a: unknown): a is { x: number; y: number } {
+  return !!a && typeof a === "object"
+    && "x" in (a as any) && "y" in (a as any)
+    && typeof (a as any).x === "number" && typeof (a as any).y === "number";
+}
+
+function toNumberPair(p: [number, number] | { x: number; y: number }): [number, number] {
+  // Keep in math coords (+y up) - conversion to SVG coords happens in plugin wrapper
+  if (isPoint(p)) return [p[0], p[1]];
+  const obj = p as any;
+  return [obj.x, obj.y];
+}
+
+function polygonToNumbers(vertices: Array<[number, number] | { x: number; y: number }>): number[][] {
+  const out: number[][] = [];
+  for (const v of vertices) {
+    if (isPoint(v) || isPointObj(v)) {
+      out.push(toNumberPair(v));
+    }
+  }
+  return out;
+}
+
+// ----------------------- main converter -----------------------
+/**
+ * Convert raw stims JSON to TangramSpec[] for clean plugin interface.
+ * This replaces the old normalizeStims() function with proper separation of concerns.
+ */
+export function rawStimsToTangramSpecs(
+  src: unknown,
+  sectorIds: string[],
+  defaultRequired = 2
+): TangramSpec[] {
+  const rawList: RawStim[] = Array.isArray(src)
+    ? (src as RawStim[])
+    : (src && typeof src === "object" && Array.isArray((src as any).stims))
+    ? ((src as any).stims as RawStim[])
+    : [];
+
+  const tangrams: TangramSpec[] = [];
+
+  for (let i = 0; i < Math.min(sectorIds.length, rawList.length); i++) {
+    const raw = rawList[i];
+    if (!raw) continue;
+
+    // Extract only canonical piece shapes; ignore macros
+    const mask: number[][][] = [];
+    for (const tan of raw.solutionTans ?? []) {
+      if (!tan || !CANON.has(tan.name)) continue;
+      if (Array.isArray(tan.verticesAtOrigin) && tan.verticesAtOrigin.length >= 3) {
+        mask.push(polygonToNumbers(tan.verticesAtOrigin));
+      }
+    }
+
+    const id = sectorIds[i] ?? String(i);
+    tangrams.push({
+      id,
+      silhouette: {
+        mask,
+        requiredCount: defaultRequired,
+      },
+    });
+  }
+
+  return tangrams;
+}
+
+/** Fetch + convert helper for dev path (e.g., "/dev/assets/stims_dev.json"). */
+export async function loadTangramSpecsFromUrl(
+  url: string,
+  sectorIds: string[],
+  defaultRequired = 2
+): Promise<TangramSpec[]> {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`Failed to load stims: ${res.status} ${res.statusText}`);
+  const json = await res.json();
+  return rawStimsToTangramSpecs(json, sectorIds, defaultRequired);
+}

package/src/core/io/quickstash.ts

@@ -0,0 +1,141 @@
+// src/core/io/quickstash.ts
+import { CONFIG } from "@/core/config/config";
+import type { Blueprint, CompositeBlueprint, PrimitiveBlueprint, TanKind, Vec } from "@/core/domain/types";
+import { primitiveBlueprintsHalfEdge } from "@/core/domain/primitives";
+
+/**
+ * Convert anchor coordinates to pixel coordinates
+ * @param anchorX - X coordinate in anchor units (integer)
+ * @param anchorY - Y coordinate in anchor units (integer)
+ * @returns Pixel coordinates
+ */
+export function anchorToPixels(anchorX: number, anchorY: number): Vec {
+  return { 
+    x: anchorX * CONFIG.layout.grid.stepPx, 
+    y: anchorY * CONFIG.layout.grid.stepPx 
+  };
+}
+
+/**
+ * Convert pixel coordinates to anchor coordinates
+ * @param pixelX - X coordinate in pixels
+ * @param pixelY - Y coordinate in pixels
+ * @returns Anchor coordinates (rounded to nearest grid point)
+ */
+export function pixelsToAnchor(pixelX: number, pixelY: number): Vec {
+  return {
+    x: Math.round(pixelX / CONFIG.layout.grid.stepPx),
+    y: Math.round(pixelY / CONFIG.layout.grid.stepPx)
+  };
+}
+
+/**
+ * Convert anchor-based composite definition to pixel-based composite with custom grid step
+ * @param anchorComposite - Composite defined with anchor coordinates
+ * @param primsByKind - Map of primitive blueprints by kind
+ * @param gridStepPx - Grid step in pixels (defaults to current CONFIG)
+ * @returns CompositeBlueprint with pixel coordinates
+ */
+export function convertAnchorCompositeToPixels(
+  anchorComposite: { id: string; parts: Array<{ kind: TanKind; anchorOffset: { x: number; y: number } }>; label?: string },
+  primsByKind: Map<TanKind, PrimitiveBlueprint>,
+  gridStepPx: number = CONFIG.layout.grid.stepPx
+): CompositeBlueprint {
+  const { id, parts, label } = anchorComposite;
+  
+  // Convert anchor offsets to pixel offsets using custom grid step
+  const pixelParts: Array<{ kind: TanKind; offset: Vec }> = parts.map(p => ({
+    kind: p.kind,
+    offset: { 
+      x: p.anchorOffset.x * gridStepPx, 
+      y: p.anchorOffset.y * gridStepPx 
+    }
+  }));
+  
+  // Compute shape using custom grid step
+  const shape: Vec[][] = [];
+  for (const p of parts) {
+    const prim = primsByKind.get(p.kind);
+    if (!prim) continue;
+    
+    const pixelOffset = { 
+      x: p.anchorOffset.x * gridStepPx, 
+      y: p.anchorOffset.y * gridStepPx 
+    };
+    for (const poly of prim.shape) {
+      shape.push(poly.map(v => ({ x: v.x + pixelOffset.x, y: v.y + pixelOffset.y })));
+    }
+  }
+  
+  return { id, parts: pixelParts, shape, label: label ?? `Composite-${id}` };
+}
+
+/**
+ * Anchor-based composite definitions (configuration-independent)
+ * These are converted to pixel coordinates at render time
+ */
+const ANCHOR_COMPOSITES = [
+  {
+    id: "comp:parallelogram+parallelogram",
+    parts: [
+      { kind: "parallelogram" as TanKind, anchorOffset: { x: 0, y: 0 } },
+      { kind: "parallelogram" as TanKind, anchorOffset: { x: 2, y: 2 } }, // Diagonal contact
+    ],
+    label: "Parallelogram+Parallelogram"
+  },
+  {
+    id: "comp:small_triangle+med_triangle", 
+    parts: [
+      { kind: "small_triangle" as TanKind, anchorOffset: { x: -2, y: -2 } },
+      { kind: "med_triangle" as TanKind, anchorOffset: { x: 0, y: 0 } },
+    ],
+    label: "SmallTriangle+MedTriangle"
+  },
+  {
+    id: "comp:square",
+    parts: [
+      { kind: "square" as TanKind, anchorOffset: { x: 0, y: 0 } },
+    ],
+    label: "Square"
+  }
+];
+
+/**
+ * Create quickstash with custom grid step (useful for testing different configurations)
+ * @param gridStepPx - Grid step in pixels
+ * @returns Array of blueprints with pixel coordinates based on custom grid step
+ */
+export function createQuickstashWithGridStep(gridStepPx: number): Blueprint[] {
+  const prims = primitiveBlueprintsHalfEdge();
+  const byKind = new Map<TanKind, PrimitiveBlueprint>();
+  prims.forEach(p => byKind.set(p.kind, p));
+
+  // Convert anchor-based definitions to pixel-based composites with custom grid step
+  const list: Blueprint[] = ANCHOR_COMPOSITES.map(anchorComposite => 
+    convertAnchorCompositeToPixels(anchorComposite, byKind, gridStepPx)
+  );
+
+  const maxSlots = CONFIG.layout.defaults.maxQuickstashSlots;
+  if (list.length > maxSlots) {
+    throw new Error(
+      `Quickstash has ${list.length} items but max is ${maxSlots}. Trim defaultQuickstash() or raise CONFIG.layout.defaults.maxQuickstashSlots.`
+    );
+  }
+  return list;
+}
+
+/**
+ * Get anchor-based composite definitions (for debugging/testing)
+ * @returns Array of anchor-based composite definitions
+ */
+export function getAnchorComposites() {
+  return ANCHOR_COMPOSITES;
+}
+
+/**
+ * Default Quickstash using anchor coordinates
+ * Conversion to pixels happens at render time using current CONFIG
+ */
+export function defaultQuickstash(): Blueprint[] {
+  return createQuickstashWithGridStep(CONFIG.layout.grid.stepPx);
+}

package/src/core/io/stims.ts

@@ -0,0 +1,110 @@
+// core/io/stims.ts
+import type { Poly, Sector, Vec } from "@/core/domain/types";
+
+/** Raw JSON shapes from dev/assets/stims_dev.json */
+type RawTan = {
+  name: string;
+  verticesAtOrigin: Array<[number, number] | { x: number; y: number }>;
+};
+
+type RawStim = {
+  solutionTans: RawTan[];
+  stimImgPath?: string;
+  stimSilhouetteImgPath?: string;
+  set?: string;
+  id?: string | number;
+};
+
+/** Canonical tangram names we accept as actual piece polys. */
+const CANON = new Set([
+  "square",
+  "small_triangle",
+  "parallelogram",
+  "med_triangle",
+  "large_triangle",
+]);
+
+// ----------------------- guards & converters -----------------------
+function isPoint(a: unknown): a is [number, number] {
+  return Array.isArray(a) && a.length >= 2
+    && typeof a[0] === "number" && typeof a[1] === "number";
+}
+function isPointObj(a: unknown): a is { x: number; y: number } {
+  return !!a && typeof a === "object"
+    && "x" in (a as any) && "y" in (a as any)
+    && typeof (a as any).x === "number" && typeof (a as any).y === "number";
+}
+
+function toVec(p: [number, number] | { x: number; y: number }): Vec {
+  // JSON vertices are authored in math coords (+y up). Convert to SVG (+y down).
+  if (isPoint(p)) return { x: p[0], y: -p[1] };
+  const obj = p as any;
+  return { x: obj.x, y: -obj.y };
+}
+
+// NOTE: We flip Y above so silhouettes render right-side-up in SVG.
+function polyFromVertices(vertices: Array<[number, number] | { x: number; y: number }>): Poly {
+  // defensively map every element that looks like a point
+  const out: Vec[] = [];
+  for (const v of vertices) {
+    if (isPoint(v) || isPointObj(v)) out.push(toVec(v));
+  }
+  return out;
+}
+
+// ----------------------- normalization -----------------------
+/**
+ * Accepts either an array of raw stims or an object with { stims: [...] }.
+ * Returns Sectors with silhouette.mask = array of polys (one per tan).
+ */
+export function normalizeStims(
+  src: unknown,
+  fallbackSectorIds: string[],
+  defaultRequired = 2
+): Sector[] {
+  const rawList: RawStim[] = Array.isArray(src)
+    ? (src as RawStim[])
+    : (src && typeof src === "object" && Array.isArray((src as any).stims))
+    ? ((src as any).stims as RawStim[])
+    : [];
+
+  const sectors: Sector[] = [];
+
+  for (let i = 0; i < Math.min(fallbackSectorIds.length, rawList.length); i++) {
+    const raw = rawList[i];
+    if (!raw) continue;
+
+    // take only canonical piece shapes; ignore macros
+    const polys: Poly[] = [];
+    for (const tan of raw.solutionTans ?? []) {
+      if (!tan || !CANON.has(tan.name)) continue;
+      if (Array.isArray(tan.verticesAtOrigin) && tan.verticesAtOrigin.length >= 3) {
+        polys.push(polyFromVertices(tan.verticesAtOrigin));
+      }
+    }
+
+    const id = fallbackSectorIds[i] ?? String(i);
+    sectors.push({
+      id,
+      silhouette: {
+        id,
+        mask: polys,
+        requiredCount: defaultRequired,
+      },
+    });
+  }
+
+  return sectors;
+}
+
+/** Fetch + normalize helper for dev path (e.g., "/dev/assets/stims_dev.json"). */
+export async function loadStimSectorsFromUrl(
+  url: string,
+  sectorIds: string[],
+  defaultRequired = 2
+): Promise<Sector[]> {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`Failed to load stims: ${res.status} ${res.statusText}`);
+  const json = await res.json();
+  return normalizeStims(json, sectorIds, defaultRequired);
+}

package/src/core/types/index.ts

@@ -0,0 +1,5 @@
+// Central type exports for the refactored architecture
+export * from './plugin-interfaces';
+
+// Re-export commonly used type combinations
+export type { ConstructionTrialParams, PrepTrialParams } from './plugin-interfaces';