From 1cef55521e70c8e7565db6f28c01f6476b45b085 Mon Sep 17 00:00:00 2001
From: Marcus Ding <marcusding@me.com>
Date: Sat, 1 Nov 2025 20:43:40 +0100
Subject: [PATCH 1/2] Add animation design tab and rotate pattern fills

---
 javascript/index.html                | 269 +++++++++
 javascript/js/app.js                 | 792 ++++++++++++++++++++++++++-
 javascript/js/doyle_spiral_engine.js |  64 ++-
 javascript/js/three_viewer.js        |  76 ++-
 4 files changed, 1194 insertions(+), 7 deletions(-)

diff --git a/javascript/index.html b/javascript/index.html
index e965679..8e72655 100644
--- a/javascript/index.html
+++ b/javascript/index.html
@@ -268,6 +268,228 @@
       position: relative;
     }
 
+    .animation-card {
+      padding: 1.6rem;
+      gap: 1.5rem;
+    }
+
+    .animation-header {
+      display: flex;
+      justify-content: space-between;
+      align-items: flex-start;
+      gap: 1.5rem;
+      flex-wrap: wrap;
+    }
+
+    .animation-header p {
+      color: var(--text-muted);
+      max-width: 40ch;
+      line-height: 1.4;
+      font-size: 0.9rem;
+    }
+
+    .animation-grid {
+      display: grid;
+      gap: 1.5rem;
+      grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+      align-items: flex-start;
+    }
+
+    .animation-section {
+      display: grid;
+      gap: 1rem;
+    }
+
+    .animation-section h3 {
+      font-size: 0.95rem;
+      letter-spacing: 0.06em;
+      text-transform: uppercase;
+      color: var(--text-muted);
+    }
+
+    .hex-host {
+      display: flex;
+      justify-content: center;
+      padding: 0.75rem;
+    }
+
+    .hex-diagram {
+      width: 220px;
+      height: 220px;
+    }
+
+    .hex-diagram polygon {
+      fill: rgba(148, 163, 184, 0.22);
+      stroke: rgba(100, 116, 139, 0.5);
+      stroke-width: 1.4;
+      cursor: pointer;
+      transition: fill 0.2s ease, stroke 0.2s ease, transform 0.2s ease;
+    }
+
+    .hex-diagram polygon:hover {
+      transform: scale(1.02);
+    }
+
+    .hex-diagram polygon.is-active {
+      fill: rgba(37, 99, 235, 0.45);
+      stroke: rgba(37, 99, 235, 0.85);
+    }
+
+    .hex-diagram polygon.is-high {
+      fill: rgba(245, 158, 11, 0.55);
+      stroke: rgba(217, 119, 6, 0.9);
+    }
+
+    .frame-toolbar {
+      display: flex;
+      gap: 0.6rem;
+      flex-wrap: wrap;
+    }
+
+    .frame-list {
+      display: grid;
+      gap: 0.9rem;
+    }
+
+    .frame-card {
+      background: rgba(255, 255, 255, 0.7);
+      border-radius: 1rem;
+      border: 1px solid rgba(148, 163, 184, 0.26);
+      padding: 1rem 1.1rem;
+      display: grid;
+      gap: 0.9rem;
+      transition: box-shadow 0.2s ease, border 0.2s ease;
+    }
+
+    .frame-card.active {
+      border-color: rgba(37, 99, 235, 0.55);
+      box-shadow: 0 0 0 3px rgba(37, 99, 235, 0.12);
+    }
+
+    .frame-card header {
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      gap: 0.5rem;
+    }
+
+    .frame-card header h4 {
+      font-size: 0.95rem;
+      font-weight: 600;
+    }
+
+    .frame-meta {
+      display: grid;
+      gap: 0.65rem;
+    }
+
+    .frame-meta label {
+      display: flex;
+      align-items: center;
+      gap: 0.5rem;
+      font-size: 0.85rem;
+      color: var(--text-muted);
+    }
+
+    .frame-meta input[type="number"] {
+      width: 100%;
+      padding: 0.45rem 0.6rem;
+      border-radius: 0.6rem;
+      border: 1px solid rgba(148, 163, 184, 0.35);
+      font-size: 0.85rem;
+    }
+
+    .neighbor-toggle-grid {
+      display: grid;
+      grid-template-columns: repeat(3, minmax(0, 1fr));
+      gap: 0.45rem;
+    }
+
+    .neighbor-toggle {
+      appearance: none;
+      border: none;
+      border-radius: 0.75rem;
+      padding: 0.5rem 0.6rem;
+      font-size: 0.75rem;
+      font-weight: 600;
+      background: rgba(148, 163, 184, 0.18);
+      color: var(--text-muted);
+      cursor: pointer;
+      transition: background 0.2s ease, color 0.2s ease;
+    }
+
+    .neighbor-toggle.active {
+      background: rgba(37, 99, 235, 0.18);
+      color: var(--accent);
+    }
+
+    .neighbor-toggle.high {
+      background: rgba(245, 158, 11, 0.2);
+      color: #b45309;
+    }
+
+    .selection-buttons,
+    .selection-helpers {
+      display: grid;
+      gap: 0.6rem;
+    }
+
+    .selection-helpers {
+      grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
+      align-items: end;
+    }
+
+    .selection-helpers label {
+      display: grid;
+      gap: 0.35rem;
+      font-size: 0.8rem;
+      color: var(--text-muted);
+    }
+
+    .selection-helpers input {
+      width: 100%;
+      padding: 0.55rem 0.6rem;
+      border-radius: 0.65rem;
+      border: 1px solid rgba(148, 163, 184, 0.35);
+      font-size: 0.85rem;
+    }
+
+    .selection-summary {
+      font-size: 0.85rem;
+      color: var(--text-muted);
+      background: rgba(148, 163, 184, 0.12);
+      border-radius: 0.9rem;
+      padding: 0.75rem 1rem;
+    }
+
+    .arcgroup-hit {
+      fill: rgba(37, 99, 235, 0);
+      stroke: rgba(37, 99, 235, 0);
+      stroke-width: 1.2;
+      cursor: pointer;
+      pointer-events: auto;
+      transition: fill 0.2s ease, stroke 0.2s ease;
+    }
+
+    .arcgroup-hit:hover {
+      fill: rgba(37, 99, 235, 0.08);
+    }
+
+    .arcgroup-hit.state-selected {
+      fill: rgba(59, 130, 246, 0.3);
+      stroke: rgba(37, 99, 235, 0.75);
+    }
+
+    .arcgroup-hit.state-active {
+      fill: rgba(245, 158, 11, 0.34);
+      stroke: rgba(217, 119, 6, 0.8);
+    }
+
+    .arcgroup-hit.frame-active {
+      fill: rgba(236, 72, 153, 0.32);
+      stroke: rgba(219, 39, 119, 0.82);
+    }
+
     #svgPreview svg {
       width: 100%;
       height: 100%;
@@ -570,12 +792,59 @@ <h1>Doyle Spiral Studio</h1>
         <div class="view-toggle" role="group" aria-label="Preview mode">
           <button type="button" class="active" data-view="2d" aria-pressed="true">2D SVG</button>
           <button type="button" data-view="3d" aria-pressed="false">3D View</button>
+          <button type="button" data-view="animation" aria-pressed="false">Animation</button>
         </div>
 
         <div class="preview-card" id="view2d">
           <div id="svgPreview" class="empty-state">Rendering spiral…</div>
         </div>
 
+        <div class="preview-card animation-card" id="animationPanel" hidden>
+          <div class="animation-header">
+            <div>
+              <h2>Animation Designer</h2>
+              <p>
+                Compose frame transitions for a generic arcgroup and map them onto the spiral. Click cells in the SVG to cycle
+                between no selection, selection (blue), and selection with activation (gold).
+              </p>
+            </div>
+            <div class="status" id="animationStatus">Select arcgroups to begin.</div>
+          </div>
+          <div class="animation-grid">
+            <section class="animation-section">
+              <h3>Frame sequence</h3>
+              <div class="hex-host" id="animationHexHost"></div>
+              <div class="frame-toolbar">
+                <button type="button" id="addAnimationFrame">Add frame</button>
+              </div>
+              <div class="frame-list" id="animationFrames"></div>
+            </section>
+            <section class="animation-section">
+              <h3>Apply to SVG</h3>
+              <p class="selection-summary" id="selectionInstructions">
+                Use the SVG preview to choose arcgroups. Selected cells highlight blue; golden cells are marked as high.
+              </p>
+              <div class="selection-buttons">
+                <button type="button" id="selectAllArcgroups">Select all arcgroups</button>
+                <button type="button" class="secondary" id="clearArcgroupSelection">Clear selection</button>
+              </div>
+              <div class="selection-helpers">
+                <label for="radialRepeat">
+                  Repeat every
+                  <input type="number" id="radialRepeat" min="1" value="3" />
+                </label>
+                <label for="radialWidth">
+                  Width (cells)
+                  <input type="number" id="radialWidth" min="1" value="1" />
+                </label>
+                <button type="button" class="secondary" id="applyRadialSelection">Apply radial selection</button>
+              </div>
+              <div class="selection-summary" id="selectionStats">No arcgroups selected.</div>
+              <button type="button" id="runAnimation">Animate sequence</button>
+            </section>
+          </div>
+        </div>
+
         <div class="stats" id="stats" hidden>
           <div class="stat-card"><strong id="statArcGroups">0</strong>Arc groups</div>
           <div class="stat-card"><strong id="statPolygons">0</strong>Polygons extruded</div>
diff --git a/javascript/js/app.js b/javascript/js/app.js
index 5eb1b96..2dc025f 100644
--- a/javascript/js/app.js
+++ b/javascript/js/app.js
@@ -26,6 +26,18 @@ const threeStats = document.getElementById('threeStats');
 const fileInput = document.getElementById('threeFileInput');
 const exportButton = document.getElementById('exportSvgButton');
 const exportFilenameInput = document.getElementById('exportFilename');
+const animationPanel = document.getElementById('animationPanel');
+const animationStatus = document.getElementById('animationStatus');
+const animationHexHost = document.getElementById('animationHexHost');
+const animationFramesContainer = document.getElementById('animationFrames');
+const addAnimationFrameButton = document.getElementById('addAnimationFrame');
+const selectAllArcgroupsButton = document.getElementById('selectAllArcgroups');
+const clearArcgroupSelectionButton = document.getElementById('clearArcgroupSelection');
+const applyRadialSelectionButton = document.getElementById('applyRadialSelection');
+const radialRepeatInput = document.getElementById('radialRepeat');
+const radialWidthInput = document.getElementById('radialWidth');
+const runAnimationButton = document.getElementById('runAnimation');
+const selectionStatsElement = document.getElementById('selectionStats');
 
 const DEFAULTS = {
   p: 16,
@@ -53,6 +65,19 @@ const renderWorkerURL = workerSupported ? new URL('./render_worker.js', import.m
 let renderWorkerHandle = null;
 let currentRenderToken = 0;
 const svgParser = typeof DOMParser !== 'undefined' ? new DOMParser() : null;
+const SVG_NS = 'http://www.w3.org/2000/svg';
+
+let selectionState = new Map();
+let overlayElements = new Map();
+let arcgroupMetadata = { byId: new Map(), rings: new Map() };
+let frameIdCounter = 0;
+let animationFrames = [];
+let selectedFrameId = null;
+let hexDiagram = null;
+let animationTimer = null;
+let animationRunning = false;
+let currentFrameActive = new Set();
+let currentAnimationFrameIndex = 0;
 
 function sanitiseFileName(name) {
   return name.replace(/[\\/:*?"<>|]+/g, '-');
@@ -189,6 +214,711 @@ function pulseSettingsButton() {
   setTimeout(() => threeSettingsToggle.classList.remove('pulse'), 1200);
 }
 
+function setAnimationStatus(message, state = 'idle') {
+  if (!animationStatus) {
+    return;
+  }
+  animationStatus.textContent = message;
+  animationStatus.classList.remove('loading', 'error');
+  if (state !== 'idle') {
+    animationStatus.classList.add(state);
+  }
+}
+
+function computeCentroid(outline) {
+  if (!Array.isArray(outline) || !outline.length) {
+    return { x: 0, y: 0 };
+  }
+  let sumX = 0;
+  let sumY = 0;
+  let count = 0;
+  for (const point of outline) {
+    if (!Array.isArray(point) || point.length < 2) {
+      continue;
+    }
+    const x = Number(point[0]) || 0;
+    const y = Number(point[1]) || 0;
+    sumX += x;
+    sumY += y;
+    count += 1;
+  }
+  if (!count) {
+    return { x: 0, y: 0 };
+  }
+  return { x: sumX / count, y: sumY / count };
+}
+
+function pathDataFromOutline(outline) {
+  if (!Array.isArray(outline) || !outline.length) {
+    return '';
+  }
+  const commands = [];
+  outline.forEach((point, index) => {
+    if (!Array.isArray(point) || point.length < 2) {
+      return;
+    }
+    const x = Number(point[0]) || 0;
+    const y = Number(point[1]) || 0;
+    commands.push(`${index === 0 ? 'M' : 'L'}${x.toFixed(4)},${y.toFixed(4)}`);
+  });
+  commands.push('Z');
+  return commands.join(' ');
+}
+
+function createHexPoints(cx, cy, radius) {
+  const points = [];
+  for (let i = 0; i < 6; i += 1) {
+    const angle = (Math.PI / 180) * (60 * i - 30);
+    const x = cx + radius * Math.cos(angle);
+    const y = cy + radius * Math.sin(angle);
+    points.push(`${x.toFixed(2)},${y.toFixed(2)}`);
+  }
+  return points.join(' ');
+}
+
+function buildHexDiagram() {
+  if (!animationHexHost) {
+    return;
+  }
+  animationHexHost.innerHTML = '';
+  const svg = document.createElementNS(SVG_NS, 'svg');
+  svg.setAttribute('viewBox', '-80 -80 160 160');
+  svg.setAttribute('class', 'hex-diagram');
+  const radius = 20;
+  const offsetX = Math.sqrt(3) * radius;
+  const offsetY = 1.5 * radius;
+  const cells = [
+    { node: 'center', cx: 0, cy: 0 },
+    { node: '0', cx: offsetX, cy: 0 },
+    { node: '1', cx: offsetX / 2, cy: offsetY },
+    { node: '2', cx: -offsetX / 2, cy: offsetY },
+    { node: '3', cx: -offsetX, cy: 0 },
+    { node: '4', cx: -offsetX / 2, cy: -offsetY },
+    { node: '5', cx: offsetX / 2, cy: -offsetY },
+  ];
+  cells.forEach(cell => {
+    const polygon = document.createElementNS(SVG_NS, 'polygon');
+    polygon.setAttribute('points', createHexPoints(cell.cx, cell.cy, radius));
+    polygon.dataset.node = cell.node;
+    polygon.addEventListener('click', handleHexCellClick);
+    svg.appendChild(polygon);
+  });
+  animationHexHost.appendChild(svg);
+  hexDiagram = svg;
+  updateHexDiagram();
+}
+
+function updateHexDiagram() {
+  if (!hexDiagram) {
+    return;
+  }
+  const frame = getSelectedFrame();
+  hexDiagram.querySelectorAll('polygon').forEach(polygon => {
+    polygon.classList.remove('is-active', 'is-high');
+    if (!frame) {
+      return;
+    }
+    const node = polygon.dataset.node || '';
+    if (node === 'center') {
+      if (frame.centerActive) {
+        polygon.classList.add('is-high');
+      }
+      return;
+    }
+    const idx = Number(node);
+    if (Number.isInteger(idx) && frame.neighbours[idx]) {
+      polygon.classList.add('is-active');
+    }
+  });
+}
+
+function createFrame({ centerActive = false, neighbours = null, duration = 600 } = {}) {
+  const baseNeighbours = Array.isArray(neighbours) ? neighbours.slice(0, 6) : [];
+  while (baseNeighbours.length < 6) {
+    baseNeighbours.push(false);
+  }
+  frameIdCounter += 1;
+  return {
+    id: frameIdCounter,
+    centerActive: Boolean(centerActive),
+    neighbours: baseNeighbours.map(value => Boolean(value)),
+    duration: Math.max(50, Number(duration) || 600),
+  };
+}
+
+function getSelectedFrame() {
+  if (!selectedFrameId) {
+    return null;
+  }
+  return animationFrames.find(frame => frame.id === selectedFrameId) || null;
+}
+
+function renderFrameList() {
+  if (!animationFramesContainer) {
+    return;
+  }
+  animationFramesContainer.innerHTML = '';
+  animationFrames.forEach((frame, index) => {
+    const card = document.createElement('div');
+    card.className = 'frame-card';
+    card.dataset.frameId = String(frame.id);
+    if (frame.id === selectedFrameId) {
+      card.classList.add('active');
+    }
+
+    const header = document.createElement('header');
+    const title = document.createElement('h4');
+    title.textContent = `Frame ${index + 1}`;
+    header.appendChild(title);
+    const removeButton = document.createElement('button');
+    removeButton.type = 'button';
+    removeButton.className = 'secondary';
+    removeButton.dataset.action = 'remove-frame';
+    removeButton.dataset.frameId = String(frame.id);
+    removeButton.textContent = 'Remove';
+    removeButton.disabled = animationFrames.length <= 1;
+    header.appendChild(removeButton);
+    card.appendChild(header);
+
+    const meta = document.createElement('div');
+    meta.className = 'frame-meta';
+
+    const centerLabel = document.createElement('label');
+    const centerToggle = document.createElement('input');
+    centerToggle.type = 'checkbox';
+    centerToggle.className = 'frame-center-toggle';
+    centerToggle.dataset.frameId = String(frame.id);
+    centerToggle.checked = frame.centerActive;
+    centerLabel.appendChild(centerToggle);
+    centerLabel.appendChild(document.createTextNode('Center active'));
+    meta.appendChild(centerLabel);
+
+    const neighbourGrid = document.createElement('div');
+    neighbourGrid.className = 'neighbor-toggle-grid';
+    frame.neighbours.forEach((value, idx) => {
+      const btn = document.createElement('button');
+      btn.type = 'button';
+      btn.className = 'neighbor-toggle';
+      if (value) {
+        btn.classList.add('active');
+      }
+      btn.dataset.frameId = String(frame.id);
+      btn.dataset.neighbourIndex = String(idx);
+      btn.textContent = `N${idx + 1}`;
+      neighbourGrid.appendChild(btn);
+    });
+    meta.appendChild(neighbourGrid);
+
+    const durationLabel = document.createElement('label');
+    durationLabel.textContent = 'Duration (ms)';
+    const durationInput = document.createElement('input');
+    durationInput.type = 'number';
+    durationInput.min = '50';
+    durationInput.step = '10';
+    durationInput.value = String(frame.duration);
+    durationInput.dataset.frameId = String(frame.id);
+    durationInput.className = 'frame-duration';
+    durationLabel.appendChild(durationInput);
+    meta.appendChild(durationLabel);
+
+    card.appendChild(meta);
+    animationFramesContainer.appendChild(card);
+  });
+}
+
+function selectFrame(frameId) {
+  if (!Number.isInteger(frameId)) {
+    return;
+  }
+  if (!animationFrames.some(frame => frame.id === frameId)) {
+    return;
+  }
+  selectedFrameId = frameId;
+  renderFrameList();
+  updateHexDiagram();
+}
+
+function addNewFrame() {
+  const template = getSelectedFrame() || animationFrames[animationFrames.length - 1] || null;
+  const frame = createFrame({
+    centerActive: template ? template.centerActive : false,
+    neighbours: template ? template.neighbours : Array(6).fill(false),
+    duration: template ? template.duration : 600,
+  });
+  animationFrames.push(frame);
+  selectedFrameId = frame.id;
+  renderFrameList();
+  updateHexDiagram();
+  stopAnimationLoop();
+}
+
+function removeFrame(frameId) {
+  if (animationFrames.length <= 1) {
+    return;
+  }
+  const index = animationFrames.findIndex(frame => frame.id === frameId);
+  if (index === -1) {
+    return;
+  }
+  animationFrames.splice(index, 1);
+  if (selectedFrameId === frameId) {
+    const fallback = animationFrames[Math.max(0, index - 1)] || animationFrames[0] || null;
+    selectedFrameId = fallback ? fallback.id : null;
+  }
+  renderFrameList();
+  updateHexDiagram();
+  stopAnimationLoop();
+}
+
+function handleFrameListClick(event) {
+  const target = event.target;
+  if (!target) {
+    return;
+  }
+  if (target.dataset.action === 'remove-frame') {
+    const frameId = Number(target.dataset.frameId);
+    if (Number.isInteger(frameId)) {
+      removeFrame(frameId);
+    }
+    return;
+  }
+  if (target.classList.contains('neighbor-toggle')) {
+    const frameId = Number(target.dataset.frameId);
+    const neighbourIndex = Number(target.dataset.neighbourIndex);
+    const frame = animationFrames.find(item => item.id === frameId);
+    if (frame && Number.isInteger(neighbourIndex) && neighbourIndex >= 0 && neighbourIndex < frame.neighbours.length) {
+      frame.neighbours[neighbourIndex] = !frame.neighbours[neighbourIndex];
+      selectedFrameId = frameId;
+      stopAnimationLoop();
+      renderFrameList();
+      updateHexDiagram();
+    }
+    return;
+  }
+  const card = target.closest('.frame-card');
+  if (card) {
+    const frameId = Number(card.dataset.frameId);
+    if (Number.isInteger(frameId) && frameId !== selectedFrameId) {
+      selectFrame(frameId);
+    }
+  }
+}
+
+function handleFrameListInput(event) {
+  const target = event.target;
+  if (!target) {
+    return;
+  }
+  const frameId = Number(target.dataset.frameId);
+  const frame = animationFrames.find(item => item.id === frameId);
+  if (!frame) {
+    return;
+  }
+  if (target.classList.contains('frame-duration')) {
+    const value = Math.max(50, Number(target.value) || 600);
+    frame.duration = value;
+  } else if (target.classList.contains('frame-center-toggle')) {
+    frame.centerActive = target.checked;
+  }
+  selectedFrameId = frameId;
+  stopAnimationLoop();
+  renderFrameList();
+  updateHexDiagram();
+}
+
+function handleHexCellClick(event) {
+  event.preventDefault();
+  const target = event.currentTarget;
+  if (!target) {
+    return;
+  }
+  const frame = getSelectedFrame();
+  if (!frame) {
+    return;
+  }
+  const node = target.dataset.node || '';
+  stopAnimationLoop();
+  if (node === 'center') {
+    frame.centerActive = !frame.centerActive;
+  } else {
+    const index = Number(node);
+    if (Number.isInteger(index) && index >= 0 && index < frame.neighbours.length) {
+      frame.neighbours[index] = !frame.neighbours[index];
+    }
+  }
+  renderFrameList();
+  updateHexDiagram();
+}
+
+function computeArcgroupMetadata(geometry) {
+  const metadata = { byId: new Map(), rings: new Map() };
+  if (!geometry || !Array.isArray(geometry.arcgroups)) {
+    return metadata;
+  }
+  const ringBuckets = new Map();
+  geometry.arcgroups.forEach(group => {
+    const outline = Array.isArray(group.outline) ? group.outline : [];
+    const centroid = computeCentroid(outline);
+    const angle = Math.atan2(centroid.y, centroid.x);
+    const ringIndex = Number.isFinite(group.ring_index) ? group.ring_index : 0;
+    const entry = {
+      id: group.id,
+      ringIndex,
+      centroid,
+      angle,
+      neighbours: Array.isArray(group.neighbours) ? group.neighbours.map(Number) : [],
+      angularIndex: 0,
+    };
+    metadata.byId.set(group.id, entry);
+    if (!ringBuckets.has(ringIndex)) {
+      ringBuckets.set(ringIndex, []);
+    }
+    ringBuckets.get(ringIndex).push(entry);
+  });
+  ringBuckets.forEach((entries, ringIndex) => {
+    entries.sort((a, b) => a.angle - b.angle);
+    entries.forEach((entry, index) => {
+      entry.angularIndex = index;
+    });
+    metadata.rings.set(ringIndex, entries.map(entry => entry.id));
+  });
+  return metadata;
+}
+
+function clearOverlayLayer(svgElement) {
+  if (!svgElement) {
+    return;
+  }
+  const existing = svgElement.querySelector('[data-interaction-layer]');
+  if (existing) {
+    existing.remove();
+  }
+}
+
+function handleArcgroupClick(event) {
+  event.preventDefault();
+  const target = event.currentTarget;
+  if (!target) {
+    return;
+  }
+  const id = Number(target.dataset.arcgroupId);
+  if (!Number.isFinite(id)) {
+    return;
+  }
+  cycleSelectionState(id);
+}
+
+function prepareSvgInteractions(svgElement, geometry) {
+  overlayElements.forEach(element => {
+    element.removeEventListener('click', handleArcgroupClick);
+  });
+  overlayElements = new Map();
+  clearOverlayLayer(svgElement);
+  currentFrameActive = new Set();
+
+  if (!svgElement || !geometry || !Array.isArray(geometry.arcgroups) || !geometry.arcgroups.length) {
+    arcgroupMetadata = { byId: new Map(), rings: new Map() };
+    selectionState = new Map();
+    updateSelectionHighlights();
+    updateSelectionStats();
+    pushSelectionStateToViewer();
+    pushFrameActiveToViewer(currentFrameActive);
+    setAnimationStatus('Animation controls require Arram-Boyle arcgroups.', 'error');
+    setOverlayInteractivity(false);
+    return;
+  }
+
+  stopAnimationLoop();
+  arcgroupMetadata = computeArcgroupMetadata(geometry);
+  const nextSelection = new Map();
+  arcgroupMetadata.byId.forEach((_, id) => {
+    if (selectionState.has(id)) {
+      nextSelection.set(id, selectionState.get(id));
+    }
+  });
+  selectionState = nextSelection;
+
+  const layer = document.createElementNS(SVG_NS, 'g');
+  layer.setAttribute('data-interaction-layer', 'true');
+
+  geometry.arcgroups.forEach(group => {
+    const id = Number(group.id);
+    if (!Number.isFinite(id)) {
+      return;
+    }
+    const pathData = pathDataFromOutline(group.outline || []);
+    if (!pathData) {
+      return;
+    }
+    const path = document.createElementNS(SVG_NS, 'path');
+    path.setAttribute('d', pathData);
+    path.setAttribute('fill', 'transparent');
+    path.setAttribute('stroke', 'transparent');
+    path.setAttribute('class', 'arcgroup-hit');
+    path.dataset.arcgroupId = String(id);
+    path.addEventListener('click', handleArcgroupClick);
+    layer.appendChild(path);
+    overlayElements.set(id, path);
+  });
+
+  svgElement.appendChild(layer);
+  setOverlayInteractivity(activeView === 'animation');
+  updateSelectionHighlights();
+  updateSelectionStats();
+  pushSelectionStateToViewer();
+  pushFrameActiveToViewer(currentFrameActive);
+  setAnimationStatus(selectionState.size ? 'Ready to animate.' : 'Select arcgroups to begin.');
+}
+
+function updateSelectionHighlights(activeSet = currentFrameActive) {
+  overlayElements.forEach((element, id) => {
+    element.classList.remove('state-selected', 'state-active', 'frame-active');
+    const state = selectionState.get(id);
+    if (state === 'selected' || state === 'active') {
+      element.classList.add('state-selected');
+    }
+    if (state === 'active') {
+      element.classList.add('state-active');
+    }
+    if (activeSet && activeSet.has(id)) {
+      element.classList.add('frame-active');
+    }
+  });
+}
+
+function setOverlayInteractivity(enabled) {
+  overlayElements.forEach(element => {
+    element.style.pointerEvents = enabled ? 'auto' : 'none';
+  });
+}
+
+function updateSelectionStats() {
+  if (!selectionStatsElement) {
+    return;
+  }
+  const totalSelected = Array.from(selectionState.values()).filter(value => value === 'selected' || value === 'active').length;
+  const totalActive = Array.from(selectionState.values()).filter(value => value === 'active').length;
+  if (!lastRender || !hasGeometry(lastRender.geometry)) {
+    selectionStatsElement.textContent = 'No arcgroups available.';
+    return;
+  }
+  if (!totalSelected) {
+    selectionStatsElement.textContent = 'No arcgroups selected.';
+    return;
+  }
+  let message = `${totalSelected} arcgroup${totalSelected === 1 ? '' : 's'} selected`;
+  if (totalActive) {
+    message += `, ${totalActive} high`;
+  }
+  selectionStatsElement.textContent = `${message}.`;
+}
+
+function cycleSelectionState(groupId) {
+  if (!Number.isInteger(groupId)) {
+    return;
+  }
+  const current = selectionState.get(groupId) || 'none';
+  let next;
+  if (current === 'none') {
+    next = 'selected';
+  } else if (current === 'selected') {
+    next = 'active';
+  } else {
+    next = 'none';
+  }
+  if (next === 'none') {
+    selectionState.delete(groupId);
+  } else {
+    selectionState.set(groupId, next);
+  }
+  stopAnimationLoop();
+  updateSelectionHighlights();
+  updateSelectionStats();
+  pushSelectionStateToViewer();
+  setAnimationStatus(selectionState.size ? 'Ready to animate.' : 'Select arcgroups to begin.');
+}
+
+function selectAllArcgroups() {
+  if (!arcgroupMetadata || !arcgroupMetadata.byId.size) {
+    return;
+  }
+  arcgroupMetadata.byId.forEach((_, id) => {
+    const current = selectionState.get(id);
+    if (current !== 'active') {
+      selectionState.set(id, 'selected');
+    }
+  });
+  stopAnimationLoop();
+  updateSelectionHighlights();
+  updateSelectionStats();
+  pushSelectionStateToViewer();
+  setAnimationStatus('All arcgroups selected.', 'idle');
+}
+
+function clearArcgroupSelection() {
+  if (!selectionState.size) {
+    return;
+  }
+  selectionState.clear();
+  stopAnimationLoop();
+  updateSelectionHighlights();
+  updateSelectionStats();
+  pushSelectionStateToViewer();
+  setAnimationStatus('Selection cleared.', 'idle');
+}
+
+function applyRadialSelection() {
+  if (!arcgroupMetadata || !arcgroupMetadata.byId.size) {
+    return;
+  }
+  const repeatEvery = Math.max(1, Math.floor(Number(radialRepeatInput?.value) || 1));
+  const width = Math.max(1, Math.floor(Number(radialWidthInput?.value) || 1));
+  arcgroupMetadata.byId.forEach((meta, id) => {
+    const angularIndex = Number.isFinite(meta.angularIndex) ? meta.angularIndex : 0;
+    if (angularIndex % repeatEvery < width) {
+      const current = selectionState.get(id);
+      if (current !== 'active') {
+        selectionState.set(id, 'selected');
+      }
+    }
+  });
+  stopAnimationLoop();
+  updateSelectionHighlights();
+  updateSelectionStats();
+  pushSelectionStateToViewer();
+  setAnimationStatus('Radial selection applied.', 'idle');
+}
+
+function pushSelectionStateToViewer() {
+  if (!threeApp || typeof threeApp.setSelectionState !== 'function') {
+    return;
+  }
+  const payload = {};
+  selectionState.forEach((value, key) => {
+    payload[key] = value;
+  });
+  threeApp.setSelectionState(payload);
+}
+
+function pushFrameActiveToViewer(activeSet) {
+  if (!threeApp || typeof threeApp.applyFrameHighlight !== 'function') {
+    return;
+  }
+  const payload = Array.from(activeSet || [], id => Number(id));
+  threeApp.applyFrameHighlight(payload);
+}
+
+function computeActiveIdsForFrame(frame) {
+  const active = new Set();
+  selectionState.forEach((state, id) => {
+    if (state === 'active') {
+      active.add(id);
+    }
+  });
+  if (!frame) {
+    return active;
+  }
+  if (frame.centerActive) {
+    selectionState.forEach((state, id) => {
+      if (state === 'selected' || state === 'active') {
+        active.add(id);
+      }
+    });
+  }
+  if (Array.isArray(frame.neighbours) && arcgroupMetadata && arcgroupMetadata.byId) {
+    selectionState.forEach((state, id) => {
+      if (state !== 'selected' && state !== 'active') {
+        return;
+      }
+      const meta = arcgroupMetadata.byId.get(id);
+      if (!meta || !Array.isArray(meta.neighbours)) {
+        return;
+      }
+      frame.neighbours.forEach((flag, index) => {
+        if (!flag) {
+          return;
+        }
+        const neighbourId = meta.neighbours[index];
+        if (Number.isFinite(neighbourId)) {
+          active.add(neighbourId);
+        }
+      });
+    });
+  }
+  return active;
+}
+
+function ensureViewerGeometrySync() {
+  if (!lastRender || !hasGeometry(lastRender.geometry)) {
+    return;
+  }
+  const viewer = ensureThreeApp();
+  if (!viewer) {
+    return;
+  }
+  if (typeof viewer.useGeometryFromPayload === 'function') {
+    viewer.useGeometryFromPayload(lastRender.params || collectParams(), lastRender.geometry);
+  }
+  pushSelectionStateToViewer();
+}
+
+function stopAnimationLoop() {
+  if (animationTimer) {
+    clearTimeout(animationTimer);
+    animationTimer = null;
+  }
+  const wasRunning = animationRunning;
+  animationRunning = false;
+  currentFrameActive = new Set();
+  if (runAnimationButton) {
+    runAnimationButton.textContent = 'Animate sequence';
+  }
+  updateSelectionHighlights();
+  pushFrameActiveToViewer(currentFrameActive);
+  const message = selectionState.size ? 'Ready to animate.' : 'Select arcgroups to begin.';
+  if (wasRunning) {
+    setAnimationStatus(selectionState.size ? 'Animation stopped.' : 'Select arcgroups to begin.');
+  } else if (activeView === 'animation') {
+    setAnimationStatus(message);
+  }
+}
+
+function scheduleNextAnimationFrame() {
+  if (!animationRunning) {
+    return;
+  }
+  const frame = animationFrames[currentAnimationFrameIndex] || animationFrames[0] || null;
+  if (!frame) {
+    stopAnimationLoop();
+    return;
+  }
+  currentFrameActive = computeActiveIdsForFrame(frame);
+  updateSelectionHighlights(currentFrameActive);
+  pushFrameActiveToViewer(currentFrameActive);
+  const duration = Math.max(50, Number(frame.duration) || 600);
+  animationTimer = setTimeout(() => {
+    currentAnimationFrameIndex = (currentAnimationFrameIndex + 1) % animationFrames.length;
+    scheduleNextAnimationFrame();
+  }, duration);
+}
+
+function startAnimationLoop() {
+  if (!animationFrames.length) {
+    setAnimationStatus('Add at least one frame to animate.', 'error');
+    return;
+  }
+  if (!selectionState.size) {
+    setAnimationStatus('Select arcgroups before animating.', 'error');
+    return;
+  }
+  ensureViewerGeometrySync();
+  animationRunning = true;
+  currentAnimationFrameIndex = 0;
+  runAnimationButton && (runAnimationButton.textContent = 'Stop animation');
+  setAnimationStatus('Animation running…', 'loading');
+  scheduleNextAnimationFrame();
+}
+
 function ensureThreeApp() {
   if (threeApp) {
     return threeApp;
@@ -288,6 +1018,8 @@ function handleRenderSuccess(result) {
 
   lastRender = { params, geometry, mode, svgString };
 
+  prepareSvgInteractions(svgElement, geometry);
+
   updateStats(geometry);
   statMode.textContent = mode === 'arram_boyle' ? 'Arram-Boyle' : 'Classic Doyle';
   setStatus('Spiral updated. Switch views to explore it in 3D.');
@@ -300,6 +1032,9 @@ function handleRenderSuccess(result) {
       threeApp.queueGeometryUpdate(params, true);
     }
   }
+
+  pushSelectionStateToViewer();
+  pushFrameActiveToViewer(currentFrameActive);
 }
 
 function handleRenderFailure(message) {
@@ -308,6 +1043,7 @@ function handleRenderFailure(message) {
   setStatus(message || 'Unexpected error', 'error');
   lastRender = null;
   updateExportAvailability(false);
+  prepareSvgInteractions(null, null);
 }
 
 function startRenderJob(params, showLoading) {
@@ -413,7 +1149,12 @@ viewButtons.forEach(button => {
     });
 
     const show3d = view === '3d';
-    view2d.hidden = show3d;
+    const showAnimation = view === 'animation';
+    const show2d = view === '2d' || showAnimation;
+    view2d.hidden = !show2d;
+    if (animationPanel) {
+      animationPanel.hidden = !showAnimation;
+    }
     view3d.hidden = !show3d;
     updateStats(lastRender ? lastRender.geometry : null);
 
@@ -428,7 +1169,11 @@ viewButtons.forEach(button => {
           app.queueGeometryUpdate(params, true);
         }
       }
+    } else if (showAnimation) {
+      setAnimationStatus(selectionState.size ? 'Ready to animate.' : 'Select arcgroups to begin.');
+      updateSelectionHighlights();
     }
+    setOverlayInteractivity(showAnimation);
   });
 });
 
@@ -448,6 +1193,51 @@ if (fillPatternTypeSelect) {
   fillPatternTypeSelect.addEventListener('change', updatePatternTypeVisibility);
 }
 
+if (animationFramesContainer) {
+  animationFramesContainer.addEventListener('click', handleFrameListClick);
+  animationFramesContainer.addEventListener('input', handleFrameListInput);
+}
+
+if (addAnimationFrameButton) {
+  addAnimationFrameButton.addEventListener('click', addNewFrame);
+}
+
+if (selectAllArcgroupsButton) {
+  selectAllArcgroupsButton.addEventListener('click', selectAllArcgroups);
+}
+
+if (clearArcgroupSelectionButton) {
+  clearArcgroupSelectionButton.addEventListener('click', clearArcgroupSelection);
+}
+
+if (applyRadialSelectionButton) {
+  applyRadialSelectionButton.addEventListener('click', applyRadialSelection);
+}
+
+if (runAnimationButton) {
+  runAnimationButton.addEventListener('click', () => {
+    if (animationRunning) {
+      stopAnimationLoop();
+    } else {
+      startAnimationLoop();
+    }
+  });
+}
+
+if (!animationFrames.length) {
+  animationFrames = [
+    createFrame({ centerActive: true }),
+    createFrame({ centerActive: false }),
+  ];
+  selectedFrameId = animationFrames[0].id;
+}
+
+buildHexDiagram();
+renderFrameList();
+updateHexDiagram();
+updateSelectionStats();
+setAnimationStatus('Render the spiral to begin.');
+
 updateExportAvailability(false);
 toggleFillSettings();
 updateTValue();
diff --git a/javascript/js/doyle_spiral_engine.js b/javascript/js/doyle_spiral_engine.js
index 12a5109..98249a8 100644
--- a/javascript/js/doyle_spiral_engine.js
+++ b/javascript/js/doyle_spiral_engine.js
@@ -863,6 +863,8 @@ class ArcGroup {
     this._patternSegmentsCache = new Map();
     this.template = null;
     this.templateTransform = null;
+    this.neighbourKeys = new Set();
+    this.neighbourIds = [];
   }
 
   addArc(arc) {
@@ -1153,6 +1155,7 @@ class ArcGroup {
         patternSegments: segments,
         patternType,
         rectWidth,
+        dataId: this.id,
       });
       return;
     }
@@ -1161,6 +1164,7 @@ class ArcGroup {
         fill: null,
         stroke: '#000000',
         strokeWidth: 0.6,
+        dataId: this.id,
       });
     }
   }
@@ -1313,6 +1317,7 @@ class DrawingContext {
     patternSegments = null,
     patternType = 'lines',
     rectWidth = 2,
+    dataId = null,
   } = {}) {
     if (!points || !points.length) {
       return;
@@ -1342,6 +1347,7 @@ class DrawingContext {
             stroke: stroke || 'none',
             'stroke-width': strokeWidth.toString(),
             'stroke-linejoin': 'round',
+            'data-arcgroup-id': dataId !== null && dataId !== undefined ? String(dataId) : undefined,
           });
         } else {
           const polygon = document.createElementNS(SVG_NS, 'polygon');
@@ -1350,6 +1356,9 @@ class DrawingContext {
           polygon.setAttribute('stroke', stroke || 'none');
           polygon.setAttribute('stroke-width', strokeWidth.toString());
           polygon.setAttribute('stroke-linejoin', 'round');
+          if (dataId !== null && dataId !== undefined) {
+            polygon.dataset.arcgroupId = String(dataId);
+          }
           this.mainGroup.appendChild(polygon);
         }
       }
@@ -1431,6 +1440,7 @@ class DrawingContext {
       const attrs = {
         points: polygonPoints,
         fill: fill ? fill : 'none',
+        'data-arcgroup-id': dataId !== null && dataId !== undefined ? String(dataId) : undefined,
       };
       if (fill) {
         attrs['fill-opacity'] = fillOpacity.toString();
@@ -1460,6 +1470,9 @@ class DrawingContext {
     } else {
       polygon.setAttribute('stroke', 'none');
     }
+    if (dataId !== null && dataId !== undefined) {
+      polygon.dataset.arcgroupId = String(dataId);
+    }
     this.mainGroup.appendChild(polygon);
   }
 
@@ -1721,6 +1734,7 @@ class DoyleSpiralEngine {
     this.arcGroups = new Map();
     this.fillPatternAngle = 0;
     this._ringTemplates = new Map();
+    this._patternBaseRotation = 0;
   }
 
   generateCircles() {
@@ -2019,6 +2033,12 @@ class DoyleSpiralEngine {
       const ring = radiusToRing.get(Number(circle.radius.toFixed(6)));
       group.ringIndex = ring !== undefined ? ring : null;
       group.baseCircle = circle;
+      const neighbourCircles = circle.getNeighbourCircles(6, spiralCenter, true, true) || [];
+      for (const neighbour of neighbourCircles) {
+        if (neighbour && neighbour !== circle) {
+          group.neighbourKeys.add(`circle_${neighbour.id}`);
+        }
+      }
       if (debugGroups) {
         group.debugFill = colorFromSeed(circle.id);
         group.debugStroke = '#000000';
@@ -2204,6 +2224,34 @@ class DoyleSpiralEngine {
         }
       }
     }
+
+    const idLookup = new Map();
+    for (const [key, group] of this.arcGroups.entries()) {
+      if (!key.startsWith('circle_')) {
+        continue;
+      }
+      idLookup.set(key, group.id);
+    }
+    for (const [key, group] of this.arcGroups.entries()) {
+      if (!key.startsWith('circle_')) {
+        continue;
+      }
+      if (!group.neighbourKeys || !group.neighbourKeys.size) {
+        group.neighbourIds = [];
+        continue;
+      }
+      const ids = new Set();
+      for (const neighbourKey of group.neighbourKeys) {
+        if (!idLookup.has(neighbourKey)) {
+          continue;
+        }
+        const neighbourId = idLookup.get(neighbourKey);
+        if (neighbourId !== undefined && neighbourId !== null) {
+          ids.add(neighbourId);
+        }
+      }
+      group.neighbourIds = Array.from(ids);
+    }
   }
 
   _renderArramBoyle(context, {
@@ -2220,7 +2268,12 @@ class DoyleSpiralEngine {
     this.generateOuterCircles();
     this.computeAllIntersections();
     context.setNormalizationScale(this.circles.concat(this.outerCircles));
-    this.fillPatternAngle = fillPatternAngle;
+    const perRingRotation = Number.isFinite(fillPatternAngle) ? fillPatternAngle : 0;
+    const baseRotationStep = Number.isFinite(this.p) && Math.abs(this.p) > 1e-9
+      ? 360 / this.p
+      : 0;
+    this.fillPatternAngle = perRingRotation;
+    this._patternBaseRotation = baseRotationStep;
     this.arcGroups.clear();
     this._ringTemplates = new Map();
 
@@ -2252,7 +2305,8 @@ class DoyleSpiralEngine {
           continue;
         }
         const ringIdx = group.ringIndex ?? 0;
-        const angle = ringIdx * fillPatternAngle;
+        const rawAngle = ringIdx * perRingRotation + ringIdx * baseRotationStep;
+        const angle = ((rawAngle % 180) + 180) % 180;
         group.toSVGFill(context, {
           debug: false,
           patternFill: true,
@@ -2351,7 +2405,10 @@ class DoyleSpiralEngine {
       const outline = group.getClosedOutline();
       const outlinePoints = outline.map(pt => [pt.re, pt.im]);
       const ringIdx = group.ringIndex ?? 0;
-      const lineAngle = ringIdx * this.fillPatternAngle;
+      const perRingRotation = Number.isFinite(this.fillPatternAngle) ? this.fillPatternAngle : 0;
+      const baseStep = Number.isFinite(this._patternBaseRotation) ? this._patternBaseRotation : 0;
+      const rawAngle = ringIdx * perRingRotation + ringIdx * baseStep;
+      const lineAngle = ((rawAngle % 180) + 180) % 180;
       exportData.arcgroups.push({
         id: group.id,
         name: group.name,
@@ -2359,6 +2416,7 @@ class DoyleSpiralEngine {
         line_angle: lineAngle,
         outline: outlinePoints,
         arc_count: group.arcs.length,
+        neighbours: Array.isArray(group.neighbourIds) ? group.neighbourIds.slice() : [],
       });
     }
     return exportData;
diff --git a/javascript/js/three_viewer.js b/javascript/js/three_viewer.js
index 1e6973c..84d92f4 100644
--- a/javascript/js/three_viewer.js
+++ b/javascript/js/three_viewer.js
@@ -88,6 +88,10 @@ function createThreeViewer({
   const spiralContainer = new THREE.Group();
   scene.add(spiralContainer);
 
+  const arcGroupMeshes = new Map();
+  let selectionStateMap = new Map();
+  let frameActiveIds = new Set();
+
   const palette = [
     0xc0c0d0, 0xb0b0c0, 0xa8a8b8, 0x9898a8,
     0xd0d0e0, 0xb8b8c8, 0xa0a0b0, 0xc8c8d8,
@@ -115,9 +119,12 @@ function createThreeViewer({
     spiralContainer.position.set(0, 0, 0);
     spiralContainer.rotation.set(0, 0, 0);
     spiralContainer.scale.set(1, 1, 1);
+    arcGroupMeshes.clear();
+    selectionStateMap = new Map();
+    frameActiveIds = new Set();
   }
 
-  function createPolygonMesh(outline, ringIndex = 0, lineAngle = 0) {
+  function createPolygonMesh(outline, ringIndex = 0, lineAngle = 0, groupId = null) {
     if (!outline || outline.length < 3) {
       return null;
     }
@@ -133,8 +140,9 @@ function createThreeViewer({
       bevelSize: 0.01,
       bevelSegments: 2,
     });
+    const baseColor = getColorForRing(ringIndex);
     const material = new THREE.MeshStandardMaterial({
-      color: getColorForRing(ringIndex),
+      color: baseColor,
       metalness: parseFloat(metalnessSlider ? metalnessSlider.value : '0.4') || 0.4,
       roughness: parseFloat(roughnessSlider ? roughnessSlider.value : '0.5') || 0.5,
       emissive: 0x000000,
@@ -145,24 +153,83 @@ function createThreeViewer({
     mesh.userData = {
       ringIndex,
       lineAngle: lineAngle || 0,
+      arcGroupId: Number.isFinite(groupId) ? groupId : null,
+      baseColor,
+      selectionState: 'none',
+      frameActive: false,
       isPulsing: false,
       wasInRange: false,
       pulseStart: 0,
     };
+    applyMeshHighlight(mesh);
     return mesh;
   }
 
+  function applyMeshHighlight(mesh) {
+    if (!mesh || !mesh.material) {
+      return;
+    }
+    const id = Number.isFinite(mesh.userData?.arcGroupId) ? mesh.userData.arcGroupId : null;
+    const base = mesh.userData?.baseColor || getColorForRing(mesh.userData?.ringIndex || 0);
+    const color = new THREE.Color(base);
+    const selection = frameActiveIds.has(id) ? 'active' : selectionStateMap.get(id) || 'none';
+    if (selection === 'active') {
+      color.lerp(new THREE.Color(0xf59e0b), 0.6);
+    } else if (selection === 'selected') {
+      color.lerp(new THREE.Color(0x3b82f6), 0.5);
+    }
+    mesh.material.color.copy(color);
+  }
+
+  function refreshMeshHighlights() {
+    arcGroupMeshes.forEach(mesh => applyMeshHighlight(mesh));
+  }
+
+  function setSelectionState(state = {}) {
+    selectionStateMap = new Map();
+    if (state && typeof state === 'object') {
+      Object.entries(state).forEach(([key, value]) => {
+        const id = Number(key);
+        if (!Number.isFinite(id)) {
+          return;
+        }
+        if (value === 'selected' || value === 'active') {
+          selectionStateMap.set(id, value);
+        }
+      });
+    }
+    refreshMeshHighlights();
+  }
+
+  function applyFrameHighlight(ids) {
+    frameActiveIds = new Set();
+    if (Array.isArray(ids) || ids instanceof Set) {
+      ids.forEach(value => {
+        const id = Number(value);
+        if (Number.isFinite(id)) {
+          frameActiveIds.add(id);
+        }
+      });
+    }
+    refreshMeshHighlights();
+  }
+
   function loadSpiralFromJSON(data) {
     if (!data || !Array.isArray(data.arcgroups)) {
       throw new Error('Invalid geometry payload');
     }
     clearSpiral();
     data.arcgroups.forEach(group => {
-      const mesh = createPolygonMesh(group.outline || [], group.ring_index, group.line_angle);
+      const groupId = Number(group.id);
+      const mesh = createPolygonMesh(group.outline || [], group.ring_index, group.line_angle, groupId);
       if (mesh) {
         spiralContainer.add(mesh);
+        if (Number.isFinite(groupId)) {
+          arcGroupMeshes.set(groupId, mesh);
+        }
       }
     });
+    refreshMeshHighlights();
     if (spiralContainer.children.length) {
       const box = new THREE.Box3().setFromObject(spiralContainer);
       const center = box.getCenter(new THREE.Vector3());
@@ -220,6 +287,7 @@ function createThreeViewer({
         }
       }
       mesh.userData.wasInRange = isInRange;
+      applyMeshHighlight(mesh);
     });
   }
 
@@ -454,6 +522,8 @@ function createThreeViewer({
     queueGeometryUpdate,
     loadSpiralFromJSON,
     resetView,
+    setSelectionState,
+    applyFrameHighlight,
   };
 }
 

From 871aa30c4bff5c48326390b236e11227b18ad847 Mon Sep 17 00:00:00 2001
From: Marcus Ding <marcusding@me.com>
Date: Sat, 1 Nov 2025 22:42:58 +0100
Subject: [PATCH 2/2] Add animation angle overrides and fix pattern rotation

---
 javascript/js/app.js                 | 205 ++++++++++++++++++++++++---
 javascript/js/doyle_spiral_engine.js |  62 ++++++--
 javascript/js/three_viewer.js        |  78 +++++++++-
 3 files changed, 313 insertions(+), 32 deletions(-)

diff --git a/javascript/js/app.js b/javascript/js/app.js
index 2dc025f..efdce6c 100644
--- a/javascript/js/app.js
+++ b/javascript/js/app.js
@@ -76,6 +76,9 @@ let selectedFrameId = null;
 let hexDiagram = null;
 let animationTimer = null;
 let animationRunning = false;
+let baseRenderSnapshot = null;
+let baseLineAngles = new Map();
+let animationOverridesActive = false;
 let currentFrameActive = new Set();
 let currentAnimationFrameIndex = 0;
 
@@ -568,6 +571,10 @@ function computeArcgroupMetadata(geometry) {
       angle,
       neighbours: Array.isArray(group.neighbours) ? group.neighbours.map(Number) : [],
       angularIndex: 0,
+      lineAngle: Number.isFinite(group.line_angle) ? Number(group.line_angle) : 0,
+      baseLineAngle: Number.isFinite(group.base_line_angle)
+        ? Number(group.base_line_angle)
+        : (Number.isFinite(group.line_angle) ? Number(group.line_angle) : 0),
     };
     metadata.byId.set(group.id, entry);
     if (!ringBuckets.has(ringIndex)) {
@@ -608,27 +615,40 @@ function handleArcgroupClick(event) {
   cycleSelectionState(id);
 }
 
-function prepareSvgInteractions(svgElement, geometry) {
+function prepareSvgInteractions(svgElement, geometry, options = {}) {
+  const {
+    preserveAnimation = false,
+    suppressStatus = false,
+    activeFrameSet = null,
+  } = options;
   overlayElements.forEach(element => {
     element.removeEventListener('click', handleArcgroupClick);
   });
   overlayElements = new Map();
   clearOverlayLayer(svgElement);
-  currentFrameActive = new Set();
+  if (activeFrameSet instanceof Set) {
+    currentFrameActive = new Set(activeFrameSet);
+  } else if (!preserveAnimation) {
+    currentFrameActive = new Set();
+  }
 
   if (!svgElement || !geometry || !Array.isArray(geometry.arcgroups) || !geometry.arcgroups.length) {
     arcgroupMetadata = { byId: new Map(), rings: new Map() };
     selectionState = new Map();
-    updateSelectionHighlights();
+    updateSelectionHighlights(currentFrameActive);
     updateSelectionStats();
     pushSelectionStateToViewer();
     pushFrameActiveToViewer(currentFrameActive);
-    setAnimationStatus('Animation controls require Arram-Boyle arcgroups.', 'error');
+    if (!suppressStatus) {
+      setAnimationStatus('Animation controls require Arram-Boyle arcgroups.', 'error');
+    }
     setOverlayInteractivity(false);
     return;
   }
 
-  stopAnimationLoop();
+  if (!preserveAnimation) {
+    stopAnimationLoop({ restoreBase: false });
+  }
   arcgroupMetadata = computeArcgroupMetadata(geometry);
   const nextSelection = new Map();
   arcgroupMetadata.byId.forEach((_, id) => {
@@ -638,6 +658,16 @@ function prepareSvgInteractions(svgElement, geometry) {
   });
   selectionState = nextSelection;
 
+  if (currentFrameActive.size) {
+    const filtered = new Set();
+    currentFrameActive.forEach(id => {
+      if (arcgroupMetadata.byId.has(id)) {
+        filtered.add(id);
+      }
+    });
+    currentFrameActive = filtered;
+  }
+
   const layer = document.createElementNS(SVG_NS, 'g');
   layer.setAttribute('data-interaction-layer', 'true');
 
@@ -663,11 +693,13 @@ function prepareSvgInteractions(svgElement, geometry) {
 
   svgElement.appendChild(layer);
   setOverlayInteractivity(activeView === 'animation');
-  updateSelectionHighlights();
+  updateSelectionHighlights(currentFrameActive);
   updateSelectionStats();
   pushSelectionStateToViewer();
   pushFrameActiveToViewer(currentFrameActive);
-  setAnimationStatus(selectionState.size ? 'Ready to animate.' : 'Select arcgroups to begin.');
+  if (!suppressStatus) {
+    setAnimationStatus(selectionState.size ? 'Ready to animate.' : 'Select arcgroups to begin.');
+  }
 }
 
 function updateSelectionHighlights(activeSet = currentFrameActive) {
@@ -862,19 +894,32 @@ function ensureViewerGeometrySync() {
   pushSelectionStateToViewer();
 }
 
-function stopAnimationLoop() {
+function stopAnimationLoop({ restoreBase = true } = {}) {
   if (animationTimer) {
     clearTimeout(animationTimer);
     animationTimer = null;
   }
   const wasRunning = animationRunning;
   animationRunning = false;
-  currentFrameActive = new Set();
   if (runAnimationButton) {
     runAnimationButton.textContent = 'Animate sequence';
   }
-  updateSelectionHighlights();
-  pushFrameActiveToViewer(currentFrameActive);
+  let restored = false;
+  if (restoreBase && animationOverridesActive) {
+    restoreBaseRenderWithActive(new Set());
+    restored = true;
+  }
+  animationOverridesActive = false;
+  if (threeApp && typeof threeApp.updateLineAngles === 'function') {
+    threeApp.updateLineAngles(null, baseLineAngles);
+  }
+  currentFrameActive = new Set();
+  if (!restored) {
+    updateSelectionHighlights(currentFrameActive);
+    pushFrameActiveToViewer(currentFrameActive);
+  } else {
+    pushFrameActiveToViewer(currentFrameActive);
+  }
   const message = selectionState.size ? 'Ready to animate.' : 'Select arcgroups to begin.';
   if (wasRunning) {
     setAnimationStatus(selectionState.size ? 'Animation stopped.' : 'Select arcgroups to begin.');
@@ -883,6 +928,80 @@ function stopAnimationLoop() {
   }
 }
 
+function restoreBaseRenderWithActive(activeSet = new Set()) {
+  if (!baseRenderSnapshot) {
+    currentFrameActive = new Set(activeSet instanceof Set ? activeSet : []);
+    updateSelectionHighlights(currentFrameActive);
+    pushFrameActiveToViewer(currentFrameActive);
+    return;
+  }
+  const frameSet = activeSet instanceof Set ? activeSet : new Set(activeSet || []);
+  currentFrameActive = new Set(frameSet);
+  handleRenderSuccess(baseRenderSnapshot, {
+    isAnimation: true,
+    activeFrameSet: currentFrameActive,
+    lineAngleOverrides: null,
+  });
+}
+
+function applyAnimationFrame(activeSet) {
+  const nextSet = activeSet instanceof Set ? activeSet : new Set(activeSet || []);
+  currentFrameActive = new Set(nextSet);
+
+  const baseParams = baseRenderSnapshot?.params || lastRender?.params || collectParams();
+  if (!baseParams) {
+    updateSelectionHighlights(currentFrameActive);
+    pushFrameActiveToViewer(currentFrameActive);
+    return;
+  }
+
+  const shift = Number(baseParams.fill_pattern_angle ?? 0);
+  const overrides = new Map();
+  if (Math.abs(shift) > 1e-6) {
+    currentFrameActive.forEach(id => {
+      const baseAngle = baseLineAngles.get(id);
+      if (Number.isFinite(baseAngle)) {
+        overrides.set(id, baseAngle + shift);
+      }
+    });
+  }
+
+  if (threeApp && typeof threeApp.updateLineAngles === 'function') {
+    threeApp.updateLineAngles(overrides.size ? overrides : null, baseLineAngles);
+  }
+
+  if (!baseParams.add_fill_pattern || overrides.size === 0) {
+    if (animationOverridesActive) {
+      restoreBaseRenderWithActive(currentFrameActive);
+    } else {
+      updateSelectionHighlights(currentFrameActive);
+      pushFrameActiveToViewer(currentFrameActive);
+    }
+    animationOverridesActive = false;
+    return;
+  }
+
+  const overridePayload = {};
+  overrides.forEach((value, key) => {
+    overridePayload[key] = value;
+  });
+
+  const params = { ...baseParams, line_angle_overrides: overridePayload };
+  try {
+    const result = renderSpiral(params);
+    handleRenderSuccess({ ...result, params }, {
+      isAnimation: true,
+      activeFrameSet: currentFrameActive,
+      lineAngleOverrides: overrides,
+    });
+    animationOverridesActive = true;
+  } catch (error) {
+    console.error('Animation render failed:', error);
+    updateSelectionHighlights(currentFrameActive);
+    pushFrameActiveToViewer(currentFrameActive);
+  }
+}
+
 function scheduleNextAnimationFrame() {
   if (!animationRunning) {
     return;
@@ -892,9 +1011,8 @@ function scheduleNextAnimationFrame() {
     stopAnimationLoop();
     return;
   }
-  currentFrameActive = computeActiveIdsForFrame(frame);
-  updateSelectionHighlights(currentFrameActive);
-  pushFrameActiveToViewer(currentFrameActive);
+  const activeSet = computeActiveIdsForFrame(frame);
+  applyAnimationFrame(activeSet);
   const duration = Math.max(50, Number(frame.duration) || 600);
   animationTimer = setTimeout(() => {
     currentAnimationFrameIndex = (currentAnimationFrameIndex + 1) % animationFrames.length;
@@ -911,11 +1029,25 @@ function startAnimationLoop() {
     setAnimationStatus('Select arcgroups before animating.', 'error');
     return;
   }
+  if (!baseRenderSnapshot && lastRender) {
+    baseRenderSnapshot = lastRender;
+    baseLineAngles = new Map();
+    if (lastRender.geometry && Array.isArray(lastRender.geometry.arcgroups)) {
+      lastRender.geometry.arcgroups.forEach(group => {
+        const id = Number(group.id);
+        const baseAngle = Number(group.base_line_angle ?? group.line_angle ?? 0);
+        if (Number.isFinite(id) && Number.isFinite(baseAngle)) {
+          baseLineAngles.set(id, baseAngle);
+        }
+      });
+    }
+  }
   ensureViewerGeometrySync();
   animationRunning = true;
   currentAnimationFrameIndex = 0;
   runAnimationButton && (runAnimationButton.textContent = 'Stop animation');
   setAnimationStatus('Animation running…', 'loading');
+  animationOverridesActive = false;
   scheduleNextAnimationFrame();
 }
 
@@ -1001,7 +1133,12 @@ function showSVG(svgElement) {
   svgPreview.classList.remove('empty-state');
 }
 
-function handleRenderSuccess(result) {
+function handleRenderSuccess(result, options = {}) {
+  const {
+    isAnimation = false,
+    activeFrameSet = null,
+    lineAngleOverrides = null,
+  } = options;
   const svgElement = materializeSvg(result);
   if (!svgElement) {
     throw new Error('Renderer produced no SVG content');
@@ -1017,20 +1154,46 @@ function handleRenderSuccess(result) {
     : new XMLSerializer().serializeToString(svgElement);
 
   lastRender = { params, geometry, mode, svgString };
+  if (!isAnimation) {
+    baseRenderSnapshot = lastRender;
+    baseLineAngles = new Map();
+    if (geometry && Array.isArray(geometry.arcgroups)) {
+      geometry.arcgroups.forEach(group => {
+        const id = Number(group.id);
+        const baseAngle = Number(group.base_line_angle ?? group.line_angle ?? 0);
+        if (Number.isFinite(id) && Number.isFinite(baseAngle)) {
+          baseLineAngles.set(id, baseAngle);
+        }
+      });
+    }
+  }
 
-  prepareSvgInteractions(svgElement, geometry);
+  const interactionOptions = {
+    preserveAnimation: isAnimation,
+    suppressStatus: isAnimation,
+  };
+  if (activeFrameSet instanceof Set) {
+    interactionOptions.activeFrameSet = activeFrameSet;
+  }
+  prepareSvgInteractions(svgElement, geometry, interactionOptions);
 
   updateStats(geometry);
   statMode.textContent = mode === 'arram_boyle' ? 'Arram-Boyle' : 'Classic Doyle';
-  setStatus('Spiral updated. Switch views to explore it in 3D.');
+  if (!isAnimation) {
+    setStatus('Spiral updated. Switch views to explore it in 3D.');
+  }
   updateExportAvailability(true);
 
   if (threeApp) {
-    if (geometry) {
+    if (geometry && !isAnimation) {
       threeApp.useGeometryFromPayload(params, geometry);
-    } else {
+    } else if (!geometry && !isAnimation) {
       threeApp.queueGeometryUpdate(params, true);
     }
+    if (typeof threeApp.updateLineAngles === 'function') {
+      const overridesPayload = lineAngleOverrides || null;
+      threeApp.updateLineAngles(overridesPayload, baseLineAngles);
+    }
   }
 
   pushSelectionStateToViewer();
@@ -1042,6 +1205,9 @@ function handleRenderFailure(message) {
   svgPreview.classList.add('empty-state');
   setStatus(message || 'Unexpected error', 'error');
   lastRender = null;
+  baseRenderSnapshot = null;
+  baseLineAngles = new Map();
+  animationOverridesActive = false;
   updateExportAvailability(false);
   prepareSvgInteractions(null, null);
 }
@@ -1121,6 +1287,7 @@ form.addEventListener('input', event => {
   if (event.target === fillPatternTypeSelect) {
     updatePatternTypeVisibility();
   }
+  stopAnimationLoop();
   debouncedRender();
   if (threeApp) {
     threeApp.queueGeometryUpdate(collectParams());
diff --git a/javascript/js/doyle_spiral_engine.js b/javascript/js/doyle_spiral_engine.js
index 98249a8..627c33e 100644
--- a/javascript/js/doyle_spiral_engine.js
+++ b/javascript/js/doyle_spiral_engine.js
@@ -2264,16 +2264,38 @@ class DoyleSpiralEngine {
     fillPatternOffset = 0.0,
     fillPatternType = 'lines',
     fillPatternRectWidth = 2.0,
+    lineAngleOverrides = null,
   } = {}) {
     this.generateOuterCircles();
     this.computeAllIntersections();
     context.setNormalizationScale(this.circles.concat(this.outerCircles));
     const perRingRotation = Number.isFinite(fillPatternAngle) ? fillPatternAngle : 0;
-    const baseRotationStep = Number.isFinite(this.p) && Math.abs(this.p) > 1e-9
-      ? 360 / this.p
-      : 0;
+    const normaliseAngle = value => ((value % 180) + 180) % 180;
+    let overrideMap = null;
+    if (lineAngleOverrides instanceof Map) {
+      overrideMap = new Map();
+      lineAngleOverrides.forEach((value, key) => {
+        const id = Number(key);
+        const angle = Number(value);
+        if (Number.isFinite(id) && Number.isFinite(angle)) {
+          overrideMap.set(id, angle);
+        }
+      });
+    } else if (lineAngleOverrides && typeof lineAngleOverrides === 'object') {
+      overrideMap = new Map();
+      Object.entries(lineAngleOverrides).forEach(([key, value]) => {
+        const id = Number(key);
+        const angle = Number(value);
+        if (Number.isFinite(id) && Number.isFinite(angle)) {
+          overrideMap.set(id, angle);
+        }
+      });
+      if (!overrideMap.size) {
+        overrideMap = null;
+      }
+    }
     this.fillPatternAngle = perRingRotation;
-    this._patternBaseRotation = baseRotationStep;
+    this._patternBaseRotation = 0;
     this.arcGroups.clear();
     this._ringTemplates = new Map();
 
@@ -2299,14 +2321,26 @@ class DoyleSpiralEngine {
       }
     }
 
+    for (const [key, group] of this.arcGroups.entries()) {
+      if (key.startsWith('outer_')) {
+        continue;
+      }
+      const ringIdx = group.ringIndex ?? 0;
+      const baseAngle = normaliseAngle(ringIdx * perRingRotation);
+      let angle = baseAngle;
+      if (overrideMap && overrideMap.has(group.id)) {
+        angle = normaliseAngle(overrideMap.get(group.id));
+      }
+      group.baseLineAngle = baseAngle;
+      group.lineAngle = angle;
+    }
+
     if (addFillPattern) {
       for (const [key, group] of this.arcGroups.entries()) {
         if (key.startsWith('outer_')) {
           continue;
         }
-        const ringIdx = group.ringIndex ?? 0;
-        const rawAngle = ringIdx * perRingRotation + ringIdx * baseRotationStep;
-        const angle = ((rawAngle % 180) + 180) % 180;
+        const angle = Number.isFinite(group.lineAngle) ? group.lineAngle : 0;
         group.toSVGFill(context, {
           debug: false,
           patternFill: true,
@@ -2351,6 +2385,7 @@ class DoyleSpiralEngine {
     fillPatternOffset = 0.0,
     fillPatternType = 'lines',
     fillPatternRectWidth = 2.0,
+    lineAngleOverrides = null,
   } = {}) {
     if (!this._generated) {
       this.generateCircles();
@@ -2373,6 +2408,7 @@ class DoyleSpiralEngine {
         fillPatternOffset,
         fillPatternType,
         fillPatternRectWidth,
+        lineAngleOverrides,
       });
       return {
         svg: context.toElement(),
@@ -2406,14 +2442,16 @@ class DoyleSpiralEngine {
       const outlinePoints = outline.map(pt => [pt.re, pt.im]);
       const ringIdx = group.ringIndex ?? 0;
       const perRingRotation = Number.isFinite(this.fillPatternAngle) ? this.fillPatternAngle : 0;
-      const baseStep = Number.isFinite(this._patternBaseRotation) ? this._patternBaseRotation : 0;
-      const rawAngle = ringIdx * perRingRotation + ringIdx * baseStep;
-      const lineAngle = ((rawAngle % 180) + 180) % 180;
+      const baseAngle = Number.isFinite(group.baseLineAngle)
+        ? group.baseLineAngle
+        : ((ringIdx * perRingRotation) % 180 + 180) % 180;
+      const lineAngle = Number.isFinite(group.lineAngle) ? group.lineAngle : baseAngle;
       exportData.arcgroups.push({
         id: group.id,
         name: group.name,
         ring_index: group.ringIndex,
         line_angle: lineAngle,
+        base_line_angle: baseAngle,
         outline: outlinePoints,
         arc_count: group.arcs.length,
         neighbours: Array.isArray(group.neighbourIds) ? group.neighbourIds.slice() : [],
@@ -2451,6 +2489,9 @@ function normaliseParams(params = {}) {
     red_outline: Boolean(params.red_outline ?? false),
     draw_group_outline: params.draw_group_outline !== undefined ? Boolean(params.draw_group_outline) : true,
     max_d: Number(params.max_d ?? 2000),
+    line_angle_overrides: typeof params.line_angle_overrides === 'object' && params.line_angle_overrides !== null
+      ? params.line_angle_overrides
+      : null,
   };
 }
 
@@ -2473,6 +2514,7 @@ function renderSpiral(params = {}, overrideMode = null) {
     fillPatternOffset: opts.fill_pattern_offset,
     fillPatternType: opts.fill_pattern_type,
     fillPatternRectWidth: opts.fill_pattern_rect_width,
+    lineAngleOverrides: opts.line_angle_overrides,
   });
   return {
     engine,
diff --git a/javascript/js/three_viewer.js b/javascript/js/three_viewer.js
index 84d92f4..d12bed5 100644
--- a/javascript/js/three_viewer.js
+++ b/javascript/js/three_viewer.js
@@ -124,7 +124,7 @@ function createThreeViewer({
     frameActiveIds = new Set();
   }
 
-  function createPolygonMesh(outline, ringIndex = 0, lineAngle = 0, groupId = null) {
+  function createPolygonMesh(outline, ringIndex = 0, lineAngle = 0, groupId = null, baseLineAngle = null) {
     if (!outline || outline.length < 3) {
       return null;
     }
@@ -152,7 +152,12 @@ function createThreeViewer({
     mesh.receiveShadow = true;
     mesh.userData = {
       ringIndex,
-      lineAngle: lineAngle || 0,
+      baseLineAngle: Number.isFinite(baseLineAngle) ? baseLineAngle : (Number.isFinite(lineAngle) ? lineAngle : 0),
+      lineAngle: Number.isFinite(lineAngle)
+        ? lineAngle
+        : Number.isFinite(baseLineAngle)
+          ? baseLineAngle
+          : 0,
       arcGroupId: Number.isFinite(groupId) ? groupId : null,
       baseColor,
       selectionState: 'none',
@@ -214,6 +219,66 @@ function createThreeViewer({
     refreshMeshHighlights();
   }
 
+  function updateLineAngles(overrides = null, baseAngles = null) {
+    const baseMap = new Map();
+    if (baseAngles instanceof Map) {
+      baseAngles.forEach((value, key) => {
+        const id = Number(key);
+        const angle = Number(value);
+        if (Number.isFinite(id) && Number.isFinite(angle)) {
+          baseMap.set(id, angle);
+        }
+      });
+    } else if (baseAngles && typeof baseAngles === 'object') {
+      Object.entries(baseAngles).forEach(([key, value]) => {
+        const id = Number(key);
+        const angle = Number(value);
+        if (Number.isFinite(id) && Number.isFinite(angle)) {
+          baseMap.set(id, angle);
+        }
+      });
+    }
+
+    const overrideMap = new Map();
+    if (overrides instanceof Map) {
+      overrides.forEach((value, key) => {
+        const id = Number(key);
+        const angle = Number(value);
+        if (Number.isFinite(id) && Number.isFinite(angle)) {
+          overrideMap.set(id, angle);
+        }
+      });
+    } else if (overrides && typeof overrides === 'object') {
+      Object.entries(overrides).forEach(([key, value]) => {
+        const id = Number(key);
+        const angle = Number(value);
+        if (Number.isFinite(id) && Number.isFinite(angle)) {
+          overrideMap.set(id, angle);
+        }
+      });
+    }
+
+    arcGroupMeshes.forEach(mesh => {
+      if (!mesh || !mesh.userData) {
+        return;
+      }
+      const id = Number(mesh.userData.arcGroupId);
+      if (!Number.isFinite(id)) {
+        return;
+      }
+      if (baseMap.has(id)) {
+        mesh.userData.baseLineAngle = baseMap.get(id);
+      }
+      const targetAngle = overrideMap.has(id)
+        ? overrideMap.get(id)
+        : mesh.userData.baseLineAngle;
+      if (Number.isFinite(targetAngle)) {
+        mesh.userData.lineAngle = targetAngle;
+      }
+    });
+    refreshMeshHighlights();
+  }
+
   function loadSpiralFromJSON(data) {
     if (!data || !Array.isArray(data.arcgroups)) {
       throw new Error('Invalid geometry payload');
@@ -221,7 +286,13 @@ function createThreeViewer({
     clearSpiral();
     data.arcgroups.forEach(group => {
       const groupId = Number(group.id);
-      const mesh = createPolygonMesh(group.outline || [], group.ring_index, group.line_angle, groupId);
+      const mesh = createPolygonMesh(
+        group.outline || [],
+        group.ring_index,
+        group.line_angle,
+        groupId,
+        group.base_line_angle,
+      );
       if (mesh) {
         spiralContainer.add(mesh);
         if (Number.isFinite(groupId)) {
@@ -524,6 +595,7 @@ function createThreeViewer({
     resetView,
     setSelectionState,
     applyFrameHighlight,
+    updateLineAngles,
   };
 }