jspsych-tangram 0.0.1

package/src/core/domain/layout.ts

@@ -0,0 +1,159 @@
+import type { LayoutMode, PlacementTarget, Poly } from "./types";
+import { anchorsDiameterToPx } from "@/core/engine/geometry";
+import { solveRadii, optimizeBandSplit } from "@/core/domain/solve";
+import { CONFIG } from "@/core/config/config";
+
+export type SectorGeom = { id: string; index: number; start: number; end: number; mid: number };
+
+export type RingBands = {
+  silhouette: [number, number];
+  workspace: [number, number];
+};
+
+export type CircleLayout = {
+  mode: LayoutMode;
+  cx: number; cy: number;
+  innerR: number; outerR: number;
+  sectors: SectorGeom[];
+  bands: RingBands;
+  sweepStart: number;
+  sweepEnd: number;
+};
+
+export function computeCircleLayout(
+  viewport: { w: number; h: number },
+  n: number,
+  sectorIds: string[],
+  mode: LayoutMode = "circle",
+  target: PlacementTarget = "workspace",
+  extras: { qsMaxSlots: number; primitivesSlots: number; masks?: Poly[][] }
+): CircleLayout {
+  const pad = CONFIG.layout.paddingPx;
+
+  // place the semicircle so its diameter sits on the bottom edge of the SVG
+  const cx = viewport.w / 2;
+  const cy = mode === "semicircle" ? viewport.h : viewport.h / 2;
+
+  // The viewport bound must match the viewBox computed by solveLogicalBox so ring sizes stay consistent.
+  // vertical radius must not cross the top padding
+  const maxRVertical = mode === "semicircle" ? (viewport.h - pad) : cy;
+  const outerRViewportBound = Math.min(cx, maxRVertical) - pad;
+
+  // Solve *minimum* feasible radii and then optimize the band split within the viewport bound
+  const sol = solveRadii({
+    n,
+    layoutMode: mode,
+    target,
+    qsMaxSlots: extras.qsMaxSlots,
+    primitivesSlots: extras.primitivesSlots,
+    masks: extras.masks ?? [],
+  });
+
+  let innerR: number, outerR: number, bands: RingBands;
+
+  if (target === "workspace") {
+    const D_ws_px = anchorsDiameterToPx(CONFIG.layout.constraints.workspaceDiamAnchors);
+    const opt = optimizeBandSplit({
+      outerRViewportBound,
+      innerR_min: sol.innerR_min,
+      Tw_min: sol.Tw_min,
+      Tp_min: sol.Tp_min,
+      Rshape_px_max: sol.Rshape_px_max,
+      D_ws_px,
+    });
+    innerR = opt.innerR;
+    outerR = opt.outerR;
+    bands = {
+      workspace: [opt.innerR, opt.innerR + opt.Tw],
+      silhouette: [opt.innerR + opt.Tw, opt.outerR],
+    };
+  } else {
+    // silhouette-only: maximize thickness; entire ring is silhouette
+    outerR = Math.max(outerRViewportBound, sol.outerR_min);
+    // minimize innerR to maximize thickness, but not below minimal requirement
+    innerR = Math.min(sol.innerR_min, outerR);
+    if (outerR < sol.outerR_min) { outerR = sol.outerR_min; innerR = sol.innerR_min; }
+    bands = { silhouette: [innerR, outerR], workspace: [innerR, outerR] };
+  }
+
+  const sweep = mode === "circle" ? Math.PI * 2 : Math.PI;
+  // semicircle: sweep the upper arc by anchoring the diameter on the bottom (π→2π)
+  const sweepStart = mode === "circle" ? -Math.PI / 2 : Math.PI;
+  const sweepEnd = sweepStart + sweep;
+  const step = sweep / n;
+
+  const sectors: SectorGeom[] = [];
+  for (let i = 0; i < n; i++) {
+    const id = sectorIds[i] ?? String(i);
+    const start = sweepStart + i * step;
+    const end = start + step;
+    const mid = (start + end) / 2;
+    sectors.push({ id, index: i, start, end, mid });
+  }
+  return { mode, cx, cy, innerR, outerR, sectors, bands, sweepStart, sweepEnd };
+}
+
+/** Ring wedge path helper */
+export function wedgePath(
+  cx: number, cy: number,
+  innerR: number, outerR: number,
+  start: number, end: number
+): string {
+  const largeArc = end - start > Math.PI ? 1 : 0;
+  const x0 = cx + innerR * Math.cos(start);
+  const y0 = cy + innerR * Math.sin(start);
+  const x1 = cx + outerR * Math.cos(start);
+  const y1 = cy + outerR * Math.sin(start);
+  const x2 = cx + outerR * Math.cos(end);
+  const y2 = cy + outerR * Math.sin(end);
+  const x3 = cx + innerR * Math.cos(end);
+  const y3 = cy + innerR * Math.sin(end);
+  return [
+    `M ${x0} ${y0}`,
+    `L ${x1} ${y1}`,
+    `A ${outerR} ${outerR} 0 ${largeArc} 1 ${x2} ${y2}`,
+    `L ${x3} ${y3}`,
+    `A ${innerR} ${innerR} 0 ${largeArc} 0 ${x0} ${y0}`,
+    "Z",
+  ].join(" ");
+}
+
+/** Sector hit-test (band optional) */
+export function sectorAtPoint(
+  x: number, y: number, layout: CircleLayout, band?: keyof RingBands
+): string | undefined {
+  const dx = x - layout.cx;
+  const dy = y - layout.cy;
+  const r = Math.hypot(dx, dy);
+
+  const [rIn, rOut] = band ? layout.bands[band] : [layout.innerR, layout.outerR];
+  if (r < rIn || r > rOut) return undefined;
+
+  let theta = Math.atan2(dy, dx);            // [-π, +π]
+  if (layout.mode === "circle") {
+    if (theta < -Math.PI / 2) theta += 2 * Math.PI;
+  } else {
+    // semicircle covers [π, 2π]
+    if (theta < Math.PI) theta += 2 * Math.PI;
+  }
+
+  for (const s of layout.sectors) {
+    if (theta >= s.start && theta < s.end) return s.id;
+  }
+  return layout.sectors.at(-1)?.id;
+}
+
+/** Convenience: axis-aligned rect for fitting silhouettes in a band */
+export function rectForBand(
+  layout: CircleLayout, sector: SectorGeom, band: keyof RingBands, pad = 0.85
+) {
+  const [rIn, rOut] = layout.bands[band];
+  const rMid = (rIn + rOut) / 2;
+  const dr = rOut - rIn;
+  const arc = (sector.end - sector.start) * rMid * 0.9;
+  const w = arc * pad;
+  const h = dr * pad;
+  const cx = layout.cx + rMid * Math.cos(sector.mid);
+  const cy = layout.cy + rMid * Math.sin(sector.mid);
+  return { cx, cy, w, h };
+}

package/src/core/domain/primitives.ts

@@ -0,0 +1,159 @@
+import type { PrimitiveBlueprint, Poly, Vec, TanKind } from "@/core/domain/types";
+
+// ===== numeric units (match Python SideLength scaling) ======================
+const U = 40;                 // 1 UNIT in pixels
+const HALFUNIT = U / 2;
+const DIAGONAL = U * Math.SQRT2;
+const HALFDIAGONAL = DIAGONAL / 2;
+
+// ===== small vec helpers ====================================================
+const P = (x: number, y: number): Vec => ({ x, y });
+
+/** rotate array left by k (Python deque.rotate(-k)) */
+function rotLeft<T>(arr: T[], k: number): T[] {
+  const n = arr.length; if (n === 0) return [];
+  const s = ((k % n) + n) % n;
+  return arr.slice(s).concat(arr.slice(0, s));
+}
+
+/**
+ * Mirrors your Python `next_point`:
+ * interior angle is CLOCKWISE at the vertex; we walk the boundary clockwise.
+ */
+function nextPoint(
+  x0: number, y0: number,  // previous vertex
+  x1: number, y1: number,  // current vertex
+  interiorDeg: number,
+  dist: number
+): Vec {
+  const phi = Math.atan2(y0 - y1, x0 - x1);            // incoming edge (x0->x1)
+  const theta = phi - (interiorDeg * Math.PI) / 180;   // rotate clockwise by interior angle
+  return P(x1 + dist * Math.cos(theta), y1 + dist * Math.sin(theta));
+}
+
+/**
+ * Build polygon from side lengths & clockwise interior angles.
+ * If `firstEdgeUnits` is provided ([(x0,y0),(x1,y1)] in **unit** coords with +y up),
+ * we use that exact first edge. Otherwise we default to +X of length sideLens[0].
+ * Returns vertices without repeating the start (close is implied).
+ */
+function constructFromSpec(
+  sideLens: number[],
+  angles: number[],
+  firstEdgeUnits?: [Vec, Vec]
+): Poly {
+  let pts: Vec[];
+  if (firstEdgeUnits) {
+    // map unit coords (up +y) -> canvas coords (down +y): invert y and scale by U
+    const a = firstEdgeUnits[0]; // typically (0,0)
+    const b = firstEdgeUnits[1];
+    const A = P(-a.x * U, a.y * U);
+    const B = P(-b.x * U, b.y * U);
+    pts = [A, B];
+  } else {
+    // default: first edge along +X
+    const firstSideLen = sideLens[0];
+    if (firstSideLen === undefined) throw new Error("No side lengths provided");
+    pts = [P(0, 0), P(firstSideLen, 0)];
+  }
+
+  // Python logic: rotate side lengths by -1 (since first edge already placed), angles unchanged
+  const sidesRot = rotLeft(sideLens, 1);
+  const angRot   = angles;
+
+  // add all but the final closing edge
+  for (let i = 1; i < sideLens.length - 1; i++) {
+    const last = pts[i - 1];
+    const curr = pts[i];
+    if (!last || !curr) continue;
+    const sLen = sidesRot[i - 1];
+    const aDeg = angRot[i - 1];
+    if (sLen === undefined || aDeg === undefined) continue;
+    pts.push(nextPoint(last.x, last.y, curr.x, curr.y, aDeg, sLen));
+  }
+  return pts;
+}
+
+// ===== default first edges in UNIT coords ( +y is UP here ) =================
+// Copied from your `default_pilot_rotations`. We invert y above for canvas.
+const FIRST_EDGES_UNITS: Record<TanKind, [Vec, Vec]> = {
+  small_triangle:   [P(0, 0), P(0.5, 0.5)],
+  parallelogram:    [P(0, 0), P(0.5, 0)],
+  large_triangle:   [P(0, 0), P(0.5, -0.5)],
+  med_triangle:     [P(0, 0), P(0.5, 0)],
+  square:           [P(0, 0), P(0.5, 0)],
+};
+
+// ===== canonical half-edge primitives ===================
+// TODO: Sean we need to talk about aligning this with your Python implementation
+// Unchanging primitive tangram pieces - these are constants, not configurable
+const PRIMITIVE_BLUEPRINTS_CACHE = (() => {
+  // Sequences copied verbatim from your Python tanprimitives_halfedges()
+  const specs: Array<{
+    id: string;
+    kind: TanKind;
+    sideLens: number[];
+    angles: number[];
+    color: string;
+  }> = [
+    {
+      id: "prim:square",
+      kind: "square",
+      sideLens: [HALFUNIT, HALFUNIT, HALFUNIT, HALFUNIT, HALFUNIT, HALFUNIT, HALFUNIT, HALFUNIT],
+      angles:   [180,      90,       180,      90,       180,      90,       180,      90],
+      color: "#f43f5e",
+    },
+    {
+      id: "prim:small",
+      kind: "small_triangle",
+      sideLens: [HALFDIAGONAL, HALFDIAGONAL, HALFUNIT, HALFUNIT, HALFUNIT, HALFUNIT],
+      angles:   [180,          45,           180,      90,       180,      45],
+      color: "#f59e0b",
+    },
+    {
+      id: "prim:parallelogram",
+      kind: "parallelogram",
+      sideLens: [HALFUNIT, HALFUNIT, HALFDIAGONAL, HALFDIAGONAL, HALFUNIT, HALFUNIT, HALFDIAGONAL, HALFDIAGONAL],
+      angles:   [180,          135,          180,      45,       180,          135,          180,     45],
+      color: "#10b981",
+    },
+    {
+      id: "prim:med",
+      kind: "med_triangle",
+      sideLens: [HALFUNIT, HALFUNIT, HALFUNIT, HALFUNIT, HALFDIAGONAL, HALFDIAGONAL, HALFDIAGONAL, HALFDIAGONAL],
+      angles:   [180,      180,      180,      45,       180,          90,            180,          45],
+      color: "#3b82f6",
+    },
+    {
+      id: "prim:large",
+      kind: "large_triangle",
+      sideLens: [
+        HALFDIAGONAL, HALFDIAGONAL, HALFDIAGONAL, HALFDIAGONAL,
+        HALFUNIT, HALFUNIT, HALFUNIT, HALFUNIT, HALFUNIT, HALFUNIT, HALFUNIT, HALFUNIT
+      ],
+      angles: [
+        180, 180, 180, 45,
+        180, 180, 180, 90, 180, 180, 180, 45
+      ],
+      color: "#8b5cf6",
+    },
+  ];
+
+  return specs.map(({ id, kind, sideLens, angles, color }) => {
+    const firstEdge = FIRST_EDGES_UNITS[kind]; // always present for these 5
+    const verts = constructFromSpec(sideLens, angles, firstEdge);
+    return {
+      id,
+      kind,
+      shape: [verts],
+      colorHint: color,
+    } as PrimitiveBlueprint;
+  });
+})();
+
+export function primitiveBlueprintsHalfEdge(): PrimitiveBlueprint[] {
+  return PRIMITIVE_BLUEPRINTS_CACHE;
+}
+
+// Direct access to primitives constant (for dependency injection)
+export const PRIMITIVE_BLUEPRINTS: PrimitiveBlueprint[] = PRIMITIVE_BLUEPRINTS_CACHE;

package/src/core/domain/solve.ts

@@ -0,0 +1,184 @@
+// src/core/domain/solve.ts
+import type { LayoutMode, PlacementTarget, Poly } from "@/core/domain/types";
+import { anchorsDiameterToPx } from "@/core/engine/geometry";
+import { CONFIG } from "@/core/config/config";
+
+// --- helpers to infer lattice unit and silhouette radius -------------------
+function igcd(a: number, b: number) {
+  a = Math.round(Math.abs(a)); b = Math.round(Math.abs(b));
+  while (b) [a, b] = [b, a % b];
+  return a || 1;
+}
+function inferUnitFromPolys(polys: Poly[]): number {
+  let g = 0;
+  for (const poly of polys) {
+    for (let i = 0; i < poly.length; i++) {
+      const a = poly[i], b = poly[(i + 1) % poly.length];
+      if (!a || !b) continue;
+      const dx = Math.round(Math.abs(b.x - a.x));
+      const dy = Math.round(Math.abs(b.y - a.y));
+      if (dx) g = g ? igcd(g, dx) : dx;
+      if (dy) g = g ? igcd(g, dy) : dy;
+    }
+  }
+  return g || 1;
+}
+function polysAABB(polys: Poly[]) {
+  let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+  for (const poly of polys) for (const p of poly) {
+    if (p.x < minX) minX = p.x;
+    if (p.y < minY) minY = p.y;
+    if (p.x > maxX) maxX = p.x;
+    if (p.y > maxY) maxY = p.y;
+  }
+  const cx = (minX + maxX) / 2, cy = (minY + maxY) / 2;
+  return { minX, minY, maxX, maxY, cx, cy };
+}
+
+type RadiiParams = {
+  n: number;                          // number of outer sectors
+  layoutMode: LayoutMode;             // "circle" | "semicircle"
+  target: PlacementTarget;            // "workspace" | "silhouette"
+  qsMaxSlots: number;                 // number of quickstash slots on inner ring
+  primitivesSlots: number;            // number of primitive slots on inner ring
+  gridPx?: number;                    // override GRID_PX (rare)
+  reqWorkspaceDiamAnchors?: number;   // override default capacity (rare)
+  reqQuickstashDiamAnchors?: number;  // override default capacity (rare)
+  reqPrimitiveDiamAnchors?: number;   // override defaults (rare)
+  layoutPadPx?: number;               // override outer pad (rare)
+  masks?: Poly[][];                   // raw silhouette polys per sector (for workspace fit calc)
+};
+
+export type RadiiSolution = {
+  innerR_min: number;
+  dr_min: number;
+  outerR_min: number;
+  Tw_min: number;          // minimal workspace-band thickness (px)  (= required diagonal diameter)
+  Tp_min: number;          // minimal silhouette-plate thickness (px) (= 2*max silhouette radius or 0)
+  Rshape_px_max: number;   // max raw-shape radius after canonical unit scaling
+};
+
+export function solveRadii(params: RadiiParams): RadiiSolution {
+  const {
+    n,
+    layoutMode,
+    target,
+    qsMaxSlots,
+    primitivesSlots,
+    gridPx = CONFIG.layout.grid.stepPx,
+    reqWorkspaceDiamAnchors = CONFIG.layout.constraints.workspaceDiamAnchors,
+    reqQuickstashDiamAnchors = CONFIG.layout.constraints.quickstashDiamAnchors,
+    reqPrimitiveDiamAnchors = CONFIG.layout.constraints.primitiveDiamAnchors,
+  } = params;
+
+  // Canonical lattice scale from raw masks (if provided)
+  const allPolys: Poly[] = (params.masks ?? []).flat();
+  const rawUnit = allPolys.length ? inferUnitFromPolys(allPolys) : 0;
+  const unitScaleS = rawUnit ? (2 * gridPx) / rawUnit : 1;
+
+  // Max silhouette radius (px) across all sectors, measured from each sector mask AABB center
+  let Rshape_px_max = 0;
+  if (params.masks && params.masks.length) {
+    for (const sectorPolys of params.masks) {
+      if (!sectorPolys?.length) continue;
+      const a = polysAABB(sectorPolys);
+      const { cx, cy } = a;
+      for (const poly of sectorPolys) {
+        for (const p of poly) {
+          const rx = (p.x - cx) * unitScaleS;
+          const ry = (p.y - cy) * unitScaleS;
+          const r = Math.hypot(rx, ry);
+          if (r > Rshape_px_max) Rshape_px_max = r;
+        }
+      }
+    }
+  }
+
+  const sweep = layoutMode === "circle" ? Math.PI * 2 : Math.PI;
+  const dOut = sweep / Math.max(1, n);
+  const dIn = sweep / Math.max(1, qsMaxSlots);
+  const dPrim = sweep / Math.max(1, primitivesSlots);
+  const sinOut = Math.sin(dOut / 2);
+  const sinIn = Math.sin(dIn / 2);
+  const sinPrim = Math.sin(dPrim / 2);
+
+  // Diagonal-based anchor diameters (so "X anchors" refers to the 45° lattice)
+  const D_ws   = anchorsDiameterToPx(reqWorkspaceDiamAnchors, gridPx);
+  const D_bp   = anchorsDiameterToPx(reqQuickstashDiamAnchors, gridPx);
+  const D_prim = anchorsDiameterToPx(reqPrimitiveDiamAnchors, gridPx);
+
+  // Inner-ring minimum from chord ≥ required diameter (blueprints + primitives)
+  const innerR_min_bp   = D_bp   * (0.5 + 1 / (2 * Math.max(1e-9, sinIn)));
+  const innerR_min_prim = D_prim * (0.5 + 1 / (2 * Math.max(1e-9, sinPrim)));
+  const innerR_min_ws   = D_ws / (2 * Math.max(1e-9, sinOut)) - D_ws / 2;
+
+  const innerR_min = Math.max(innerR_min_bp, innerR_min_prim, innerR_min_ws);
+
+  // Component minima: workspace band must be at least D_ws thick; silhouette plate
+  // must be thick enough to contain the largest mask radius (both sides).
+  const Tw_min = D_ws;
+  const Tp_min = target === "workspace" ? (2 * Rshape_px_max) : 0;
+  const dr_min = Tw_min + Tp_min;
+
+  const outerR_min = innerR_min + dr_min;
+
+  return { innerR_min, dr_min, outerR_min, Tw_min, Tp_min, Rshape_px_max };
+}
+
+export function optimizeBandSplit(args: {
+  outerRViewportBound: number;
+  innerR_min: number;
+  Tw_min: number;
+  Tp_min: number;
+  Rshape_px_max: number;
+  D_ws_px: number; // anchorsDiameterToPx(REQ_WORKSPACE_DIAM_ANCHORS)
+}): { innerR: number; Tw: number; Tp: number; outerR: number } {
+  const { outerRViewportBound, innerR_min, Tw_min, Tp_min, Rshape_px_max, D_ws_px } = args;
+
+  const dr_min = Tw_min + Tp_min;
+
+  // If the viewport can’t even accommodate the minima, clamp to the minimal feasible ring.
+  if (outerRViewportBound < innerR_min + dr_min) {
+    const outerR = innerR_min + dr_min;
+    return { innerR: innerR_min, Tw: Tw_min, Tp: Tp_min, outerR };
+  }
+
+  // Maximize ring thickness by minimizing innerR (this maximizes anchor size everywhere).
+  const outerR = outerRViewportBound;
+  const innerR = innerR_min;
+  const dr = outerR - innerR;
+
+  // Distribute slack between bands with a gentle bias towards the silhouette plate
+  // when masks have large radial extent (so they don’t look cramped).
+  const slack = Math.max(0, dr - dr_min);
+  const wWork = 1;
+  const wSil  = 1 + (Rshape_px_max / Math.max(1e-9, D_ws_px));
+  const addWork = slack * (wWork / (wWork + wSil));
+  const Tw = Tw_min + addWork;
+  const Tp = dr - Tw;
+
+  return { innerR, Tw, Tp, outerR };
+}
+
+/**
+ * Compute the *logical* SVG viewBox (LOGICAL_W/H) from the minimal feasible
+ * outer radius implied by the anchor-capacity constraints. The result ensures
+ * lattice density is invariant across devices/zoom levels.
+ *
+ * NOTE: This should be called prior to computeCircleLayout and the returned
+ * width/height must be passed as the viewport to computeCircleLayout so both
+ * functions agree on the same bound.
+ */
+export function solveLogicalBox(params: RadiiParams & { layoutPadPx: number }): { LOGICAL_W: number; LOGICAL_H: number } {
+  const { layoutMode, layoutPadPx } = params;
+  const { outerR_min } = solveRadii(params);
+
+  if (layoutMode === "circle") {
+    const LOGICAL_W = 2 * (outerR_min + layoutPadPx);
+    return { LOGICAL_W, LOGICAL_H: LOGICAL_W };
+  } else {
+    // semicircle: height is half the width; outerR computed against both axes ends up ~W/2
+    const LOGICAL_W = 2 * (outerR_min + layoutPadPx);
+    return { LOGICAL_W, LOGICAL_H: LOGICAL_W / 2 };
+  }
+}

package/src/core/domain/types.ts

@@ -0,0 +1,111 @@
+// Domain primitives (no rotation/flip; XY only)
+export type Vec = { x: number; y: number };
+export type Poly = Vec[];
+
+// Canonical tans
+export type TanKind =
+  | "square"
+  | "small_triangle"
+  | "parallelogram"
+  | "med_triangle"
+  | "large_triangle";
+
+// 2×2 interaction axes
+export type PlacementTarget = "workspace" | "silhouette";
+export type InputMode = "drag" | "click";
+
+// Blueprints (generators)
+export type PrimitiveBlueprint = {
+  id: string;
+  kind: TanKind;
+  shape: Poly[];     // canonical polygon(s) at origin (no rotation)
+  colorHint?: string;
+};
+
+export type CompositePart = { kind: TanKind; offset: Vec };
+
+export type CompositeBlueprint = {
+  id: string;
+  parts: CompositePart[];   // rigid offsets from origin
+  shape: Poly[];            // precomputed union polygons at origin (optional now)
+  label?: string;
+};
+
+export type Blueprint = PrimitiveBlueprint | CompositeBlueprint;
+
+// Live instance
+export type Piece = {
+  id: string;
+  blueprintId: string;
+  pos: Vec;                 // world position of blueprint origin (top-left of AABB offset separately)
+  sectorId?: string;        // set when placed
+};
+
+export type Anchor = {
+  id: string;
+  position: Vec;
+  accepts: { kind?: TanKind; compositeSignature?: string }[];
+};
+
+export type SilhouetteSpec = {
+  id: string;
+  anchors?: Anchor[];
+  mask?: Poly[];            // polygon masks for silhouette matching
+  requiredCount?: number;   // minimal pieces to consider the sector complete (M4)
+};
+
+export type Sector = {
+  id: string;
+  silhouette: SilhouetteSpec;
+};
+
+export type LayoutMode = "circle" | "semicircle";
+
+export type RoundConfig = {
+  n: number;
+  layout: LayoutMode;
+  target: PlacementTarget;     // one-ring (silhouette) or two-ring (workspace)
+  input: InputMode;            // drag | click  (click comes later)
+  maxQuickstashSlots: number;  // number of blueprint/quickstash slots on inner ring
+  timeLimitMs: number;
+  snapRadiusPx?: number;
+  maxCompositeSize: number;
+  sectors: Sector[];           // length = n
+  mode: "construction" | "prep"; // Game mode for behavior differences
+};
+
+export type SectorState = {
+  sectorId: string;
+  pieces: Piece[];
+  completedAt?: number;        // stamped once and never cleared (locked)
+};
+
+export type BlueprintView = "quickstash" | "primitives";
+
+export type RoundState = {
+  cfg: RoundConfig;
+  blueprintView: BlueprintView;
+  primitives: PrimitiveBlueprint[];
+  quickstash: Blueprint[];
+  sectors: Record<string, SectorState>;
+  startedAt: number;
+  endedAt?: number;            // set when all sectors are complete
+};
+
+export type PointerSample = { t: number; x: number; y: number };
+
+export type ActionEvent =
+  | { t:number; type:"spawn";  blueprintId:string; from:"quickstash"|"primitives"; pieceId:string }
+  | { t:number; type:"drag";   pieceId:string; to?:{ x:number; y:number }; pointer?:PointerSample[] }
+  | { t:number; type:"drop";   pieceId:string; sectorId?:string; anchorId?:string; accepted:boolean }
+  | { t:number; type:"remove"; pieceId:string }
+  | { t:number; type:"sectorComplete"; sectorId:string }
+  | { t:number; type:"blueprintView";  to:BlueprintView }
+  | { t:number; type:"timeout" | "autoAdvance" };
+
+export type RoundSnapshot = {
+  perSector: Array<{ sectorId: string; completedAt?: number; pieceCount: number }>;
+  events: ActionEvent[];
+  timeMs: number;
+  completed: boolean;
+};