From dc121a4006a885d29966c024cbb25bf091d1f778 Mon Sep 17 00:00:00 2001
From: Sebby1770 <274013474+Sebby1770@users.noreply.github.com>
Date: Sat, 22 Aug 2026 15:38:48 +1000
Subject: [PATCH] feat: extract SortCore step generators, add 4 algorithms +
 complexity profiler (v6)

- sorting-core.js: all 14 sorting algorithms as pure step generators
  (browser global SortCore + Node CJS), one implementation shared by
  the page, the tests, and the profiler
- New algorithms: Comb, Gnome, Cycle (minimal writes), simplified TimSort
- Complexity Profiler: benchmarks every algorithm at n=16..512, log-log
  chart + fitted empirical growth exponent vs theoretical class
- SortRunner now animates the op stream instead of hardcoding algorithms
- 47 sorting unit tests incl. stability proofs and cycle write bound
- SW cache v6, README/CHANGELOG updates

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 CHANGELOG.md          |  24 ++
 README.md             |  30 +-
 index.html            |  20 +-
 script.js             | 754 ++++++++++++++++++------------------------
 sorting-core.js       | 614 ++++++++++++++++++++++++++++++++++
 style.css             |  25 +-
 sw.js                 |   5 +-
 tests/sorting.test.js | 152 +++++++++
 8 files changed, 1175 insertions(+), 449 deletions(-)
 create mode 100644 sorting-core.js
 create mode 100644 tests/sorting.test.js

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 965b5e5..681be1d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,30 @@
 
 All notable changes to Algo Lab (Algorithm Visualizer).
 
+## [2026-08-22] — v6 Sorting Core
+
+### Added
+- **Four new sorting algorithms**: Comb Sort, Gnome Sort, Cycle Sort (provably minimal
+  writes — great for the writes metric), and a simplified TimSort (insertion-sorted
+  minruns + merge passes with the already-ordered shortcut)
+- **`sorting-core.js`** — every sorting algorithm now lives in one dependency-free
+  module as a pure step generator (works in the browser as `SortCore` and in Node via
+  `require`). The page, the tests, and the profiler all consume the same op stream.
+- **Complexity Profiler** — one click benchmarks all 14 algorithms at
+  n = 16, 32, 64, 128, 256, 512 on the current dataset shape, draws a log-log chart,
+  and reports each algorithm's measured growth exponent next to its theoretical class
+- **47 sorting unit tests** (`node --test tests/sorting.test.js`): correctness on every
+  dataset shape and edge case, stability proofs via tagged keys, cycle sort's ≤ n write
+  bound and zero-writes-on-sorted property, exact bubble counts on reversed input, and
+  exponent-estimator checks that separate the quadratic sorts from the linearithmic ones
+
+### Changed
+- `SortRunner` no longer hardcodes algorithm logic — it animates the `SortCore`
+  operation stream (compare / swap / write / touch / counts / mark ops), which keeps
+  metrics, narration, heatmap, sound, and step mode identical across all algorithms
+- Tournament, race mode, and quiz automatically include the four new algorithms
+- Service worker cache bumped to v6 and now precaches `sorting-core.js`
+
 ## [2026-08-20] — v5 Path Lab
 
 ### Added
diff --git a/README.md b/README.md
index 11a4d8a..e378a7c 100644
--- a/README.md
+++ b/README.md
@@ -4,10 +4,10 @@ An interactive teaching lab built with pure HTML, CSS, and vanilla JavaScript 
 
 Two labs share the same chrome, theme, and sound toggle:
 
-- **Sort Lab** (`index.html`) — 10 sorting algorithms
+- **Sort Lab** (`index.html`) — 14 sorting algorithms + empirical complexity profiler
 - **Path Lab** (`pathfinding.html`) — 6 pathfinding algorithms + maze generators
 
-![Algorithms](https://img.shields.io/badge/sort-10-blue) ![Pathfinding](https://img.shields.io/badge/path-6-indigo) ![PWA](https://img.shields.io/badge/PWA-offline-purple)
+![Algorithms](https://img.shields.io/badge/sort-14-blue) ![Pathfinding](https://img.shields.io/badge/path-6-indigo) ![PWA](https://img.shields.io/badge/PWA-offline-purple)
 
 ## Running
 
@@ -28,12 +28,16 @@ macOS: `open index.html` · Linux: `xdg-open index.html`
 Pathfinding algorithms and maze generators are covered by Node’s built-in test runner (no packages to install):
 
 ```bash
-node --test tests/pathfinding.test.js
+node --test tests/sorting.test.js tests/pathfinding.test.js
 ```
 
+Sorting coverage includes correctness on every dataset shape, stability proofs for the
+stable algorithms (via tagged keys), cycle sort's ≤ n write bound, and sanity checks on
+the complexity profiler's exponent estimator.
+
 ## Sort Lab
 
-### Algorithms (10)
+### Algorithms (14)
 
 | Algorithm | Best | Average | Worst | Stable | In-place | Memory |
 |-----------|------|---------|-------|--------|----------|--------|
@@ -47,6 +51,13 @@ node --test tests/pathfinding.test.js
 | Radix | O(nk) | O(nk) | O(nk) | Yes | No | O(n + k) |
 | Counting | O(n + k) | O(n + k) | O(n + k) | Yes | No | O(k) |
 | Cocktail Shaker | O(n) | O(n²) | O(n²) | Yes | Yes | O(1) |
+| Comb | O(n log n) | O(n²/2ᵖ) | O(n²) | No | Yes | O(1) |
+| Gnome | O(n) | O(n²) | O(n²) | Yes | Yes | O(1) |
+| Cycle | O(n²) | O(n²) | O(n²) | No | Yes | O(1) |
+| TimSort (simplified) | O(n) | O(n log n) | O(n log n) | Yes | No | O(n) |
+
+All fourteen are implemented once, as pure step generators in `sorting-core.js` —
+the page animates the operation stream, tests and the profiler consume it headlessly.
 
 ### Dataset generators
 
@@ -62,7 +73,10 @@ Random · Sorted · Nearly Sorted · Reversed · Few Unique · Sawtooth · Custo
 - Presentation Mode
 - Access heatmap + operations sparkline
 - Algorithm recommender
-- Benchmark tournament (all 10) with comparison matrix
+- Benchmark tournament (all 14) with comparison matrix
+- **Complexity Profiler** — measures total operations at n = 16…512, plots every
+  algorithm on a log-log chart, and fits the empirical growth exponent (the slope)
+  so you can watch bubble sort measure ≈ n² while counting sort measures ≈ n¹
 - Learning cards (trivia + use cases)
 - Run history (last 8, `localStorage` key `sortLabHistory`)
 - Share URL, CSV export, copy summary
@@ -124,9 +138,11 @@ algorithm-visualiser/
 ├── index.html              # Sort Lab
 ├── pathfinding.html        # Path Lab
 ├── style.css               # Shared theme + path grid
-├── script.js               # Sort Lab app
+├── script.js               # Sort Lab app (rendering, metrics, chrome)
+├── sorting-core.js         # Sorting step generators + profiler (browser + Node)
 ├── pathfinding.js          # Path Lab UI
 ├── pathfinding-core.js     # Search + mazes (browser + Node)
+├── tests/sorting.test.js
 ├── tests/pathfinding.test.js
 ├── sw.js                   # Service worker
 ├── manifest.json           # PWA manifest
@@ -135,7 +151,7 @@ algorithm-visualiser/
 └── README.md
 ```
 
-`pathfinding-core.js` exports `PathCore` in the browser and `module.exports` in Node.
+`sorting-core.js` and `pathfinding-core.js` export `SortCore` / `PathCore` in the browser and `module.exports` in Node.
 
 ## License
 
diff --git a/index.html b/index.html
index e7969df..04b3f19 100644
--- a/index.html
+++ b/index.html
@@ -54,6 +54,10 @@ <h2 class="panel-title">Controls</h2>
               <option value="radix">Radix Sort</option>
               <option value="counting">Counting Sort</option>
               <option value="cocktail">Cocktail Shaker Sort</option>
+              <option value="comb">Comb Sort</option>
+              <option value="gnome">Gnome Sort</option>
+              <option value="cycle">Cycle Sort</option>
+              <option value="tim">TimSort (simplified)</option>
             </select>
           </div>
 
@@ -73,6 +77,10 @@ <h2 class="panel-title">Controls</h2>
               <option value="radix">Radix Sort</option>
               <option value="counting">Counting Sort</option>
               <option value="cocktail">Cocktail Shaker Sort</option>
+              <option value="comb">Comb Sort</option>
+              <option value="gnome">Gnome Sort</option>
+              <option value="cycle">Cycle Sort</option>
+              <option value="tim">TimSort (simplified)</option>
             </select>
           </div>
 
@@ -137,7 +145,8 @@ <h2 class="panel-title">Controls</h2>
             <button id="resetBtn" class="btn btn-secondary" title="Shortcut: R">Reset</button>
           </div>
 
-          <button id="tournamentBtn" type="button" class="btn btn-accent btn-full" title="Run all 10 algorithms on current data">🏆 Benchmark Tournament</button>
+          <button id="tournamentBtn" type="button" class="btn btn-accent btn-full" title="Run all 14 algorithms on current data">🏆 Benchmark Tournament</button>
+          <button id="profilerBtn" type="button" class="btn btn-accent btn-full" title="Measure operation growth across input sizes">📈 Complexity Profiler</button>
 
           <p class="shortcut-hint">Space pause · S start · G generate · R reset · Esc exit present</p>
         </section>
@@ -178,6 +187,14 @@ <h2 class="panel-title">Tournament Leaderboard</h2>
           <div id="leaderboard" class="leaderboard-wrap"></div>
         </section>
 
+        <section class="panel" id="profilerPanel" hidden>
+          <h2 class="panel-title">Complexity Profiler</h2>
+          <p class="panel-sub">Empirical operation growth — log-log, slope &asymp; exponent</p>
+          <canvas id="profilerChart" class="profiler-chart" width="640" height="320" aria-label="Log-log chart of operations versus input size for every algorithm"></canvas>
+          <p id="profilerStatus" class="profiler-status" aria-live="polite"></p>
+          <div id="profilerTable" class="matrix-wrap"></div>
+        </section>
+
         <section class="panel" id="comparisonPanel" hidden>
           <h2 class="panel-title">Comparison Matrix</h2>
           <p class="panel-sub">Theoretical vs actual performance (last tournament)</p>
@@ -264,6 +281,7 @@ <h3>Race</h3>
   <div id="toast" class="toast" role="status" aria-live="polite"></div>
   <div id="a11yAnnouncer" class="sr-only" aria-live="assertive" aria-atomic="true"></div>
 
+  <script src="sorting-core.js"></script>
   <script src="script.js"></script>
 </body>
 </html>
\ No newline at end of file
diff --git a/script.js b/script.js
index 9894edc..a8bbfa0 100644
--- a/script.js
+++ b/script.js
@@ -1,11 +1,13 @@
 /* ============================================================
-   Sorting Algorithm Lab v4
+   Sorting Algorithm Lab v6
    Vanilla JS — no frameworks
+   Algorithm step logic lives in sorting-core.js (SortCore);
+   this file drives the visuals, metrics, and app chrome.
    ============================================================ */
 
 const ALGORITHM_IDS = [
   "bubble", "selection", "insertion", "merge", "quick", "heap", "shell", "radix",
-  "counting", "cocktail",
+  "counting", "cocktail", "comb", "gnome", "cycle", "tim",
 ];
 
 // ---------- Algorithm metadata ----------
@@ -110,6 +112,46 @@ const ALGORITHM_PROFILES = {
     memory: "O(1)",
     description: "Bidirectional bubble sort — sweeps forward then backward each pass.",
   },
+  comb: {
+    name: "Comb Sort",
+    best: "O(n log n)",
+    avg: "O(n²/2ᵖ)",
+    worst: "O(n²)",
+    stable: false,
+    inPlace: true,
+    memory: "O(1)",
+    description: "Bubble sort with a shrinking gap (÷1.3) — kills turtles early.",
+  },
+  gnome: {
+    name: "Gnome Sort",
+    best: "O(n)",
+    avg: "O(n²)",
+    worst: "O(n²)",
+    stable: true,
+    inPlace: true,
+    memory: "O(1)",
+    description: "Walks forward until a pair is out of order, swaps, and steps back.",
+  },
+  cycle: {
+    name: "Cycle Sort",
+    best: "O(n²)",
+    avg: "O(n²)",
+    worst: "O(n²)",
+    stable: false,
+    inPlace: true,
+    memory: "O(1)",
+    description: "Rotates each cycle into place — provably minimal array writes (≤ n).",
+  },
+  tim: {
+    name: "TimSort (simplified)",
+    best: "O(n)",
+    avg: "O(n log n)",
+    worst: "O(n log n)",
+    stable: true,
+    inPlace: false,
+    memory: "O(n)",
+    description: "Insertion-sorts small runs, then merges them — skipping already-ordered pairs.",
+  },
 };
 
 const LEARNING_CARDS = {
@@ -153,6 +195,22 @@ const LEARNING_CARDS = {
     trivia: "Cocktail shaker sort is also called bidirectional bubble sort or shaker sort.",
     useCase: "Teaching bidirectional scanning — slightly better than bubble on reversed arrays.",
   },
+  comb: {
+    trivia: "Comb sort's 1.3 shrink factor was found empirically — it eliminates small values stuck at the end ('turtles') that cripple bubble sort.",
+    useCase: "A drop-in bubble sort upgrade when you want simple code with far better average behavior.",
+  },
+  gnome: {
+    trivia: "Named after the garden gnome who sorts flower pots: step forward when they're in order, swap and step back when they're not.",
+    useCase: "Teaching the simplest possible stable sort — one loop, no nested indices.",
+  },
+  cycle: {
+    trivia: "Cycle sort is provably optimal in memory writes — every element is written at most once.",
+    useCase: "EEPROM and flash memory where each write costs wear — minimizing writes extends hardware life.",
+  },
+  tim: {
+    trivia: "TimSort, invented by Tim Peters in 2002 for Python, is the standard sort in Python and Java — it exploits runs that already exist in real data.",
+    useCase: "Real-world data that is partially sorted — appending new records to an already-sorted list.",
+  },
 };
 
 const DATASET_LABELS = {
@@ -196,6 +254,11 @@ const dom = {
   nextStepBtn: $("nextStepBtn"),
   resetBtn: $("resetBtn"),
   tournamentBtn: $("tournamentBtn"),
+  profilerBtn: $("profilerBtn"),
+  profilerPanel: $("profilerPanel"),
+  profilerChart: $("profilerChart"),
+  profilerTable: $("profilerTable"),
+  profilerStatus: $("profilerStatus"),
   exportCsvBtn: $("exportCsvBtn"),
   copySummaryBtn: $("copySummaryBtn"),
   visualizer: $("visualizer"),
@@ -741,80 +804,10 @@ class SortRunner {
     }
   }
 
-  async compare(i, j) {
-    this.metrics.comparisons++;
-    this.trackAccess(i, j);
-    if (!this.silent) {
-      this.bars[i]?.classList.add("compare");
-      this.bars[j]?.classList.add("compare");
-    }
-    this.audio?.compare();
-    this.updateMetricsDisplay();
-    this.narrate(`Now comparing indices ${i} and ${j} (values ${this.array[i]} and ${this.array[j]}).`);
-    this.recordOperation();
-    this.notifyVisualUpdate();
-    await this.waitStep();
-  }
-
-  clearCompare(i, j) {
-    this.bars[i]?.classList.remove("compare");
-    this.bars[j]?.classList.remove("compare");
-  }
-
-  async swap(i, j) {
-    this.metrics.swaps++;
-    this.metrics.writes += 2;
-    this.trackAccess(i, j);
-    [this.array[i], this.array[j]] = [this.array[j], this.array[i]];
-    if (!this.silent) {
-      this.bars[i].style.height = `${this.array[i]}%`;
-      this.bars[j].style.height = `${this.array[j]}%`;
-      this.bars[i].classList.add("swap");
-      this.bars[j].classList.add("swap");
-    }
-    this.audio?.swap();
-    this.updateMetricsDisplay();
-    this.narrate(`Swapping indices ${i} and ${j}.`);
-    this.recordOperation();
-    this.notifyVisualUpdate();
-    await this.waitStep();
-    this.bars[i]?.classList.remove("swap");
-    this.bars[j]?.classList.remove("swap");
-  }
-
-  async write(i, value) {
-    this.metrics.writes++;
-    this.trackAccess(i);
-    this.array[i] = value;
-    if (!this.silent) {
-      this.bars[i].style.height = `${value}%`;
-      this.bars[i].classList.add("write");
-    }
-    this.audio?.write();
-    this.updateMetricsDisplay();
-    this.narrate(`Writing value ${value} to index ${i}.`);
-    this.recordOperation();
-    this.notifyVisualUpdate();
-    await this.waitStep();
-    this.bars[i]?.classList.remove("write");
-  }
-
   markSorted(i) {
     this.bars[i]?.classList.add("sorted");
   }
 
-  async markPivot(i) {
-    this.trackAccess(i);
-    this.bars[i]?.classList.add("pivot");
-    this.narrate(`Pivot selected at index ${i} (value ${this.array[i]}).`);
-    this.notifyVisualUpdate();
-    await this.waitStep();
-  }
-
-  clearPivot(i) {
-    this.bars[i]?.classList.remove("pivot");
-  }
-
   async run(algorithm) {
     this.isRunning = true;
     this.stopped = false;
@@ -822,21 +815,11 @@ class SortRunner {
     this.metrics.start();
     this.clearStateClasses();
 
-    const runners = {
-      bubble: () => this.bubbleSort(),
-      selection: () => this.selectionSort(),
-      insertion: () => this.insertionSort(),
-      merge: () => this.mergeSort(),
-      quick: () => this.quickSort(),
-      heap: () => this.heapSort(),
-      shell: () => this.shellSort(),
-      radix: () => this.radixSort(),
-      counting: () => this.countingSort(),
-      cocktail: () => this.cocktailShakerSort(),
-    };
+    const generator = SortCore.algorithms[algorithm];
+    if (!generator) throw new Error(`Unknown algorithm: ${algorithm}`);
 
     try {
-      await runners[algorithm]();
+      await this.consume(generator(this.array));
       if (!this.silent) {
         this.bars.forEach((bar) => bar.classList.add("sorted"));
       }
@@ -850,376 +833,124 @@ class SortRunner {
     }
   }
 
-  async bubbleSort() {
-    const n = this.array.length;
-    for (let i = 0; i < n - 1; i++) {
-      for (let j = 0; j < n - i - 1; j++) {
-        await this.compare(j, j + 1);
-        if (this.array[j] > this.array[j + 1]) {
-          await this.swap(j, j + 1);
-        }
-        this.clearCompare(j, j + 1);
-      }
-      this.markSorted(n - i - 1);
-    }
-    this.markSorted(0);
-  }
-
-  async selectionSort() {
-    const n = this.array.length;
-    for (let i = 0; i < n - 1; i++) {
-      let minIdx = i;
-      if (!this.silent) this.bars[minIdx].classList.add("compare");
-
-      for (let j = i + 1; j < n; j++) {
-        await this.compare(j, minIdx);
-        if (this.array[j] < this.array[minIdx]) {
-          this.bars[minIdx]?.classList.remove("compare");
-          minIdx = j;
-          if (!this.silent) this.bars[minIdx].classList.add("compare");
-        } else {
-          this.bars[j]?.classList.remove("compare");
+  /**
+   * Animate a SortCore operation stream. The generator mutates
+   * this.array itself; this driver only renders, counts, and paces.
+   */
+  async consume(ops) {
+    for (const op of ops) {
+      switch (op.t) {
+        case "compare": {
+          this.metrics.comparisons++;
+          this.trackAccess(op.i, op.j);
+          if (!this.silent) {
+            this.bars[op.i]?.classList.add("compare");
+            this.bars[op.j]?.classList.add("compare");
+          }
+          this.audio?.compare();
+          this.updateMetricsDisplay();
+          this.narrate(
+            `Now comparing indices ${op.i} and ${op.j} (values ${this.array[op.i]} and ${this.array[op.j]}).`
+          );
+          this.recordOperation();
+          this.notifyVisualUpdate();
+          await this.waitStep();
+          this.bars[op.i]?.classList.remove("compare");
+          this.bars[op.j]?.classList.remove("compare");
+          break;
         }
-      }
 
-      if (minIdx !== i) await this.swap(i, minIdx);
-      this.bars[minIdx]?.classList.remove("compare");
-      this.markSorted(i);
-    }
-    this.markSorted(n - 1);
-  }
-
-  async insertionSort() {
-    const n = this.array.length;
-    this.markSorted(0);
-
-    for (let i = 1; i < n; i++) {
-      let j = i;
-      if (!this.silent) this.bars[i].classList.add("compare");
-
-      while (j > 0) {
-        await this.compare(j - 1, j);
-        if (this.array[j - 1] > this.array[j]) {
-          await this.swap(j - 1, j);
-          j--;
-        } else {
-          this.clearCompare(j - 1, j);
+        case "swap": {
+          this.metrics.swaps++;
+          this.metrics.writes += 2;
+          this.trackAccess(op.i, op.j);
+          if (!this.silent) {
+            this.bars[op.i].style.height = `${this.array[op.i]}%`;
+            this.bars[op.j].style.height = `${this.array[op.j]}%`;
+            this.bars[op.i].classList.add("swap");
+            this.bars[op.j].classList.add("swap");
+          }
+          this.audio?.swap();
+          this.updateMetricsDisplay();
+          this.narrate(`Swapping indices ${op.i} and ${op.j}.`);
+          this.recordOperation();
+          this.notifyVisualUpdate();
+          await this.waitStep();
+          this.bars[op.i]?.classList.remove("swap");
+          this.bars[op.j]?.classList.remove("swap");
           break;
         }
-        this.clearCompare(j - 1, j);
-      }
-
-      this.bars[i]?.classList.remove("compare");
-      for (let k = 0; k <= i; k++) this.markSorted(k);
-    }
-  }
-
-  async mergeSort() {
-    const aux = [...this.array];
-    await this.mergeSortRange(0, this.array.length - 1, aux);
-  }
-
-  async mergeSortRange(low, high, aux) {
-    if (low >= high) return;
-    const mid = Math.floor((low + high) / 2);
-    this.narrate(`Merge sort: dividing range [${low}…${high}] at midpoint ${mid}.`);
-    await this.mergeSortRange(low, mid, aux);
-    await this.mergeSortRange(mid + 1, high, aux);
-    await this.merge(low, mid, high, aux);
-  }
-
-  async merge(low, mid, high, aux) {
-    this.narrate(`Merging sorted halves [${low}…${mid}] and [${mid + 1}…${high}].`);
-    for (let k = low; k <= high; k++) {
-      aux[k] = this.array[k];
-    }
-
-    let i = low;
-    let j = mid + 1;
-    let k = low;
-
-    while (i <= mid && j <= high) {
-      await this.compare(i, j);
-      if (aux[i] <= aux[j]) {
-        await this.write(k, aux[i]);
-        i++;
-      } else {
-        await this.write(k, aux[j]);
-        j++;
-      }
-      this.clearCompare(i, j);
-      k++;
-    }
-
-    while (i <= mid) {
-      await this.write(k, aux[i]);
-      i++;
-      k++;
-    }
 
-    while (j <= high) {
-      await this.write(k, aux[j]);
-      j++;
-      k++;
-    }
-  }
-
-  async quickSort(low = 0, high = this.array.length - 1) {
-    if (low < high) {
-      const pivotIdx = await this.partition(low, high);
-      await this.quickSort(low, pivotIdx - 1);
-      await this.quickSort(pivotIdx + 1, high);
-    }
-  }
-
-  async partition(low, high) {
-    await this.markPivot(high);
-    const pivotValue = this.array[high];
-    let i = low - 1;
-
-    for (let j = low; j < high; j++) {
-      await this.compare(j, high);
-      if (this.array[j] < pivotValue) {
-        i++;
-        if (i !== j) await this.swap(i, j);
-      }
-      this.clearCompare(j, high);
-    }
-
-    await this.swap(i + 1, high);
-    this.clearPivot(high);
-    this.markSorted(i + 1);
-    return i + 1;
-  }
-
-  async heapSort() {
-    const n = this.array.length;
-    for (let i = Math.floor(n / 2) - 1; i >= 0; i--) {
-      await this.heapify(n, i);
-    }
-
-    for (let i = n - 1; i > 0; i--) {
-      await this.swap(0, i);
-      this.markSorted(i);
-      await this.heapify(i, 0);
-    }
-    this.markSorted(0);
-  }
-
-  async heapify(size, root) {
-    let largest = root;
-    const left = 2 * root + 1;
-    const right = 2 * root + 2;
-
-    if (left < size) {
-      await this.compare(left, largest);
-      if (this.array[left] > this.array[largest]) largest = left;
-      this.clearCompare(left, root);
-    }
-
-    if (right < size) {
-      const compareWith = largest;
-      await this.compare(right, compareWith);
-      if (this.array[right] > this.array[compareWith]) largest = right;
-      this.clearCompare(right, compareWith);
-    }
-
-    if (largest !== root) {
-      await this.swap(root, largest);
-      await this.heapify(size, largest);
-    }
-  }
-
-  async shellSort() {
-    const n = this.array.length;
-    let gap = Math.floor(n / 2);
-
-    while (gap > 0) {
-      this.currentGap = gap;
-      this.narrate(`Shell sort: starting pass with gap = ${gap}.`);
-
-      for (let i = gap; i < n; i++) {
-        const temp = this.array[i];
-        let j = i;
-        if (!this.silent) this.bars[i]?.classList.add("gap");
-
-        while (j >= gap) {
-          await this.compare(j - gap, j);
-          if (!this.silent) this.bars[j - gap]?.classList.add("gap");
-          this.narrate(
-            `Comparing indices ${j - gap} and ${j} (${gap} apart): ${this.array[j - gap]} vs ${temp}.`
-          );
-
-          if (this.array[j - gap] > temp) {
-            await this.write(j, this.array[j - gap]);
-            j -= gap;
-          } else {
-            this.clearCompare(j - gap, j);
-            this.bars[j - gap]?.classList.remove("gap");
-            break;
+        case "write": {
+          this.metrics.writes++;
+          this.trackAccess(op.i);
+          if (!this.silent) {
+            this.bars[op.i].style.height = `${op.value}%`;
+            this.bars[op.i].classList.add("write");
           }
-          this.clearCompare(j - gap, j);
-          this.bars[j - gap]?.classList.remove("gap");
+          this.audio?.write();
+          this.updateMetricsDisplay();
+          this.narrate(`Writing value ${op.value} to index ${op.i}.`);
+          this.recordOperation();
+          this.notifyVisualUpdate();
+          await this.waitStep();
+          this.bars[op.i]?.classList.remove("write");
+          break;
         }
 
-        if (j !== i) {
-          await this.write(j, temp);
+        case "touch": {
+          this.trackAccess(op.i);
+          if (!this.silent) this.bars[op.i]?.classList.add(op.cls);
+          this.notifyVisualUpdate();
+          await this.waitStep();
+          this.bars[op.i]?.classList.remove(op.cls);
+          break;
         }
-        this.bars[i]?.classList.remove("gap");
-      }
 
-      gap = Math.floor(gap / 2);
-    }
-  }
-
-  async radixSort() {
-    const max = Math.max(...this.array);
-    const placeNames = ["ones", "tens", "hundreds"];
-    let exp = 1;
-    let pass = 0;
-
-    while (Math.floor(max / exp) > 0) {
-      this.currentDigitExp = exp;
-      const place = placeNames[pass] || `10^${pass}`;
-      this.narrate(`Radix sort pass ${pass + 1}: sorting by ${place} digit.`);
-      await this.radixCountingSort(exp);
-      exp *= 10;
-      pass++;
-    }
-  }
-
-  async radixCountingSort(exp) {
-    const n = this.array.length;
-    const output = new Array(n);
-    const count = new Array(10).fill(0);
-
-    for (let i = 0; i < n; i++) {
-      const digit = Math.floor(this.array[i] / exp) % 10;
-      if (!this.silent) this.bars[i]?.classList.add("digit");
-      this.narrate(`Counting digit ${digit} at index ${i} (value ${this.array[i]}).`);
-      count[digit]++;
-      await this.waitStep();
-      this.bars[i]?.classList.remove("digit");
-    }
-
-    for (let i = 1; i < 10; i++) {
-      count[i] += count[i - 1];
-    }
-
-    for (let i = n - 1; i >= 0; i--) {
-      const digit = Math.floor(this.array[i] / exp) % 10;
-      const pos = count[digit] - 1;
-      output[pos] = this.array[i];
-      this.narrate(`Placing ${this.array[i]} into bucket position ${pos} (digit ${digit}).`);
-      count[digit]--;
-      if (!this.silent) {
-        this.bars[i]?.classList.add("digit");
-        await this.waitStep();
-        this.bars[i]?.classList.remove("digit");
-      }
-    }
-
-    for (let i = 0; i < n; i++) {
-      await this.write(i, output[i]);
-      if (!this.silent) {
-        this.bars[i]?.classList.add("digit");
-        await this.waitStep();
-        this.bars[i]?.classList.remove("digit");
-      }
-    }
-  }
-
-  async countingSort() {
-    const n = this.array.length;
-    const min = Math.min(...this.array);
-    const max = Math.max(...this.array);
-    const range = max - min + 1;
-    const count = new Array(range).fill(0);
-
-    this.narrate(`Counting sort: value range ${min}…${max} (${range} buckets).`);
-
-    for (let i = 0; i < n; i++) {
-      const bucket = this.array[i] - min;
-      this.trackAccess(i);
-      if (!this.silent) this.bars[i]?.classList.add("bucket");
-      count[bucket]++;
-      this.metrics.writes++;
-      this.onCountingArrayUpdate?.(count, min, max, bucket);
-      this.narrate(`Incrementing count for value ${this.array[i]} (bucket ${bucket}).`);
-      this.recordOperation();
-      this.notifyVisualUpdate();
-      await this.waitStep();
-      this.bars[i]?.classList.remove("bucket");
-    }
-
-    for (let i = 1; i < range; i++) {
-      count[i] += count[i - 1];
-      this.onCountingArrayUpdate?.(count, min, max, i);
-      this.narrate(`Prefix sum at bucket ${i}: cumulative count = ${count[i]}.`);
-      this.recordOperation();
-      await this.waitStep();
-    }
-
-    const output = new Array(n);
-    for (let i = n - 1; i >= 0; i--) {
-      const bucket = this.array[i] - min;
-      this.trackAccess(i);
-      const pos = count[bucket] - 1;
-      output[pos] = this.array[i];
-      count[bucket]--;
-      if (!this.silent) this.bars[i]?.classList.add("bucket");
-      this.onCountingArrayUpdate?.(count, min, max, bucket);
-      this.narrate(`Placing ${this.array[i]} at output position ${pos}.`);
-      this.recordOperation();
-      this.notifyVisualUpdate();
-      await this.waitStep();
-      this.bars[i]?.classList.remove("bucket");
-    }
+        case "counts": {
+          this.metrics.writes += op.costWrites || 0;
+          if (op.access && op.access.length) this.trackAccess(...op.access);
+          if (!this.silent && op.idx >= 0 && op.cls) {
+            this.bars[op.idx]?.classList.add(op.cls);
+          }
+          this.onCountingArrayUpdate?.(op.counts, op.min, op.max, op.highlight);
+          this.updateMetricsDisplay();
+          this.recordOperation();
+          this.notifyVisualUpdate();
+          await this.waitStep();
+          if (op.idx >= 0 && op.cls) this.bars[op.idx]?.classList.remove(op.cls);
+          break;
+        }
 
-    for (let i = 0; i < n; i++) {
-      await this.write(i, output[i]);
-      if (!this.silent) {
-        this.bars[i]?.classList.add("bucket");
-        await this.waitStep();
-        this.bars[i]?.classList.remove("bucket");
-      }
-    }
-  }
+        case "sorted":
+          this.markSorted(op.i);
+          break;
 
-  async cocktailShakerSort() {
-    const n = this.array.length;
-    let start = 0;
-    let end = n - 1;
+        case "mark":
+          this.trackAccess(op.i);
+          if (!this.silent) this.bars[op.i]?.classList.add(op.cls);
+          break;
 
-    while (start < end) {
-      this.narrate(`Cocktail pass: scanning forward from ${start} to ${end}.`);
+        case "unmark":
+          this.bars[op.i]?.classList.remove(op.cls);
+          break;
 
-      for (let i = start; i < end; i++) {
-        await this.compare(i, i + 1);
-        if (this.array[i] > this.array[i + 1]) {
-          await this.swap(i, i + 1);
-        }
-        this.clearCompare(i, i + 1);
-      }
-      this.markSorted(end);
-      end--;
+        case "narrate":
+          this.narrate(op.text);
+          break;
 
-      if (start >= end) break;
+        case "gap":
+          this.currentGap = op.gap;
+          break;
 
-      this.narrate(`Cocktail pass: scanning backward from ${end} to ${start}.`);
+        case "digitExp":
+          this.currentDigitExp = op.exp;
+          break;
 
-      for (let i = end; i > start; i--) {
-        await this.compare(i - 1, i);
-        if (this.array[i - 1] > this.array[i]) {
-          await this.swap(i - 1, i);
-        }
-        this.clearCompare(i - 1, i);
+        default:
+          break;
       }
-      this.markSorted(start);
-      start++;
     }
-
-    if (n > 0) this.markSorted(start);
   }
 }
 
@@ -1357,6 +1088,7 @@ class SortLabApp {
     dom.stopBtn.addEventListener("click", () => this.stopSort());
     dom.nextStepBtn.addEventListener("click", () => this.nextStep());
     dom.tournamentBtn.addEventListener("click", () => this.runTournament());
+    dom.profilerBtn.addEventListener("click", () => this.runProfiler());
     dom.exportCsvBtn.addEventListener("click", () => this.exportCsv());
     dom.copySummaryBtn.addEventListener("click", () => this.copySummary());
     dom.themeToggle.addEventListener("click", () => this.toggleTheme());
@@ -1757,7 +1489,7 @@ class SortLabApp {
     const ids = [
       "algorithm", "algorithmRace", "dataset", "size", "speed",
       "raceMode", "stepMode", "teachingMode", "quizMode", "generateBtn", "startBtn",
-      "resetBtn", "tournamentBtn", "applyCustomBtn", "shareUrlBtn", "presentationBtn",
+      "resetBtn", "tournamentBtn", "profilerBtn", "applyCustomBtn", "shareUrlBtn", "presentationBtn",
     ];
     ids.forEach((id) => {
       const el = dom[id];
@@ -1899,7 +1631,7 @@ class SortLabApp {
     const size = data.length;
     const results = [];
 
-    this.setStatus("Running benchmark tournament on all 10 algorithms…");
+    this.setStatus(`Running benchmark tournament on all ${ALGORITHM_IDS.length} algorithms…`);
     this.announce("Benchmark tournament started.");
 
     for (const algo of ALGORITHM_IDS) {
@@ -1947,6 +1679,152 @@ class SortLabApp {
     this.updateCustomFieldVisibility();
   }
 
+  // ---------- Complexity profiler ----------
+
+  static PROFILER_SIZES = [16, 32, 64, 128, 256, 512];
+
+  profilerColor(index) {
+    return `hsl(${Math.round((index * 360) / ALGORITHM_IDS.length)}, 70%, 52%)`;
+  }
+
+  async runProfiler() {
+    if (this.isRunning) return;
+    const sizes = SortLabApp.PROFILER_SIZES;
+    const datasetType = dom.dataset.value === "custom" ? "random" : dom.dataset.value;
+
+    dom.profilerPanel.hidden = false;
+    this.setStatus("Profiling all algorithms across input sizes…");
+    this.announce("Complexity profiling started.");
+
+    const results = [];
+    for (const id of ALGORITHM_IDS) {
+      dom.profilerStatus.textContent = `Measuring ${ALGORITHM_PROFILES[id].name}…`;
+      await new Promise((r) => setTimeout(r, 0));
+      const points = SortCore.benchmark(id, sizes, (n) => generateDataset(datasetType, n));
+      results.push({
+        id,
+        name: ALGORITHM_PROFILES[id].name,
+        theoretical: ALGORITHM_PROFILES[id].avg,
+        points,
+        exponent: SortCore.estimateExponent(points),
+      });
+    }
+
+    this.profilerResults = results;
+    this.renderProfilerChart(results, sizes);
+    this.renderProfilerTable(results, sizes);
+    dom.profilerStatus.textContent =
+      `Dataset: ${DATASET_LABELS[datasetType] || datasetType} — total operations (comparisons + swaps + writes) ` +
+      `measured at n = ${sizes.join(", ")}. On the log-log chart, the slope of each line ≈ the exponent k in O(nᵏ).`;
+    this.setStatus("Complexity profile complete");
+    this.showToast("Complexity profile complete");
+    this.announce("Complexity profiling complete.");
+  }
+
+  renderProfilerChart(results, sizes) {
+    const canvas = dom.profilerChart;
+    if (!canvas) return;
+    const ctx = canvas.getContext("2d");
+    const W = canvas.width;
+    const H = canvas.height;
+    const PAD = { left: 46, right: 12, top: 12, bottom: 26 };
+
+    ctx.clearRect(0, 0, W, H);
+
+    const xMin = Math.log(sizes[0]);
+    const xMax = Math.log(sizes[sizes.length - 1]);
+    let yMax = 1;
+    let yMin = Infinity;
+    results.forEach((r) =>
+      r.points.forEach((p) => {
+        if (p.ops > 0) {
+          yMax = Math.max(yMax, p.ops);
+          yMin = Math.min(yMin, p.ops);
+        }
+      })
+    );
+    const lyMin = Math.log(Math.max(1, yMin));
+    const lyMax = Math.log(yMax);
+    const toX = (n) => PAD.left + ((Math.log(n) - xMin) / (xMax - xMin)) * (W - PAD.left - PAD.right);
+    const toY = (ops) =>
+      H - PAD.bottom - ((Math.log(Math.max(1, ops)) - lyMin) / (lyMax - lyMin || 1)) * (H - PAD.top - PAD.bottom);
+
+    // axes + gridlines
+    ctx.strokeStyle = "rgba(148, 163, 184, 0.35)";
+    ctx.fillStyle = "#94a3b8";
+    ctx.font = "10px system-ui, sans-serif";
+    ctx.lineWidth = 1;
+
+    sizes.forEach((n) => {
+      const x = toX(n);
+      ctx.beginPath();
+      ctx.moveTo(x, PAD.top);
+      ctx.lineTo(x, H - PAD.bottom);
+      ctx.stroke();
+      ctx.textAlign = "center";
+      ctx.fillText(String(n), x, H - PAD.bottom + 14);
+    });
+
+    for (let e = Math.ceil(lyMin / Math.LN10); e <= Math.floor(lyMax / Math.LN10); e++) {
+      const ops = Math.pow(10, e);
+      const y = toY(ops);
+      ctx.beginPath();
+      ctx.moveTo(PAD.left, y);
+      ctx.lineTo(W - PAD.right, y);
+      ctx.stroke();
+      ctx.textAlign = "right";
+      ctx.fillText(`10^${e}`, PAD.left - 4, y + 3);
+    }
+
+    // one line per algorithm
+    results.forEach((r, idx) => {
+      ctx.strokeStyle = this.profilerColor(idx);
+      ctx.lineWidth = 2;
+      ctx.beginPath();
+      r.points.forEach((p, i) => {
+        const x = toX(p.n);
+        const y = toY(p.ops);
+        if (i === 0) ctx.moveTo(x, y);
+        else ctx.lineTo(x, y);
+      });
+      ctx.stroke();
+    });
+  }
+
+  renderProfilerTable(results, sizes) {
+    const maxN = sizes[sizes.length - 1];
+    const rows = [...results]
+      .sort((a, b) => (a.exponent ?? 99) - (b.exponent ?? 99))
+      .map((r, i) => {
+        const idx = ALGORITHM_IDS.indexOf(r.id);
+        const measured = r.exponent == null ? "—" : `n^${r.exponent.toFixed(2)}`;
+        const opsAtMax = r.points[r.points.length - 1].ops.toLocaleString();
+        return `
+          <tr>
+            <td>${i + 1}</td>
+            <td><span class="profiler-dot" style="background:${this.profilerColor(idx)}"></span>${r.name}</td>
+            <td><strong>${measured}</strong></td>
+            <td>${r.theoretical}</td>
+            <td>${opsAtMax}</td>
+          </tr>`;
+      })
+      .join("");
+
+    dom.profilerTable.innerHTML = `
+      <table class="data-table">
+        <thead>
+          <tr>
+            <th>#</th>
+            <th>Algorithm</th>
+            <th>Measured growth</th>
+            <th>Theoretical avg</th>
+            <th>Ops @ n=${maxN}</th>
+          </tr>
+        </thead>
+        <tbody>${rows}</tbody>
+      </table>`;
+  }
+
   renderLeaderboard(results) {
     dom.leaderboard.innerHTML = `
       <table class="data-table">
diff --git a/sorting-core.js b/sorting-core.js
new file mode 100644
index 0000000..6038084
--- /dev/null
+++ b/sorting-core.js
@@ -0,0 +1,614 @@
+/* ============================================================
+   Sort Lab — algorithm core
+   Works in the browser (global SortCore) and Node (CJS).
+
+   Every algorithm is a synchronous generator that mutates the
+   array it is given and yields operation objects. The UI driver
+   animates those operations; tests and the complexity profiler
+   consume them headlessly. One implementation, three consumers.
+
+   Operation vocabulary (t = type):
+     compare {i, j}            counts 1 comparison, animated step
+     swap    {i, j}            counts 1 swap + 2 writes (array already mutated)
+     write   {i, value}        counts 1 write (array already mutated)
+     touch   {i, cls}          no metric, animated flash (e.g. radix digit scan)
+     counts  {counts, min, max, highlight, costWrites, access}
+                               counting-array update; costWrites ∈ {0, 1}
+     sorted  {i}               mark index as finally placed
+     mark    {i, cls} / unmark {i, cls}   persistent highlight on an index
+     narrate {text}            teaching-mode narration, free
+     gap     {gap}             shell/comb gap changed, free
+     digitExp {exp}            radix digit place changed, free
+   ============================================================ */
+
+(function (root) {
+  "use strict";
+
+  const identity = (v) => v;
+
+  function ctxOf(opts) {
+    return { key: (opts && opts.key) || identity };
+  }
+
+  // ---------- op helpers ----------
+  const compare = (i, j) => ({ t: "compare", i, j });
+  const sortedOp = (i) => ({ t: "sorted", i });
+  const mark = (i, cls) => ({ t: "mark", i, cls });
+  const unmark = (i, cls) => ({ t: "unmark", i, cls });
+  const narrate = (text) => ({ t: "narrate", text });
+  const touch = (i, cls) => ({ t: "touch", i, cls });
+
+  function* doSwap(a, i, j) {
+    [a[i], a[j]] = [a[j], a[i]];
+    yield { t: "swap", i, j };
+  }
+
+  function* doWrite(a, i, value) {
+    a[i] = value;
+    yield { t: "write", i, value };
+  }
+
+  // ---------- classic ten ----------
+  function* bubble(a, opts) {
+    const { key } = ctxOf(opts);
+    const n = a.length;
+    for (let i = 0; i < n - 1; i++) {
+      for (let j = 0; j < n - i - 1; j++) {
+        yield compare(j, j + 1);
+        if (key(a[j]) > key(a[j + 1])) yield* doSwap(a, j, j + 1);
+      }
+      yield sortedOp(n - i - 1);
+    }
+    if (n > 0) yield sortedOp(0);
+  }
+
+  function* selection(a, opts) {
+    const { key } = ctxOf(opts);
+    const n = a.length;
+    for (let i = 0; i < n - 1; i++) {
+      let minIdx = i;
+      yield mark(minIdx, "compare");
+      for (let j = i + 1; j < n; j++) {
+        yield compare(j, minIdx);
+        if (key(a[j]) < key(a[minIdx])) {
+          yield unmark(minIdx, "compare");
+          minIdx = j;
+          yield mark(minIdx, "compare");
+        }
+      }
+      if (minIdx !== i) yield* doSwap(a, i, minIdx);
+      yield unmark(minIdx, "compare");
+      yield sortedOp(i);
+    }
+    if (n > 0) yield sortedOp(n - 1);
+  }
+
+  function* insertion(a, opts) {
+    const { key } = ctxOf(opts);
+    const n = a.length;
+    if (n > 0) yield sortedOp(0);
+    for (let i = 1; i < n; i++) {
+      let j = i;
+      while (j > 0) {
+        yield compare(j - 1, j);
+        if (key(a[j - 1]) > key(a[j])) {
+          yield* doSwap(a, j - 1, j);
+          j--;
+        } else {
+          break;
+        }
+      }
+      for (let k = 0; k <= i; k++) yield sortedOp(k);
+    }
+  }
+
+  function* mergeRange(a, low, high, aux, key) {
+    if (low >= high) return;
+    const mid = Math.floor((low + high) / 2);
+    yield narrate(`Merge sort: dividing range [${low}…${high}] at midpoint ${mid}.`);
+    yield* mergeRange(a, low, mid, aux, key);
+    yield* mergeRange(a, mid + 1, high, aux, key);
+
+    yield narrate(`Merging sorted halves [${low}…${mid}] and [${mid + 1}…${high}].`);
+    for (let k = low; k <= high; k++) aux[k] = a[k];
+    let i = low;
+    let j = mid + 1;
+    let k = low;
+    while (i <= mid && j <= high) {
+      yield compare(i, j);
+      if (key(aux[i]) <= key(aux[j])) {
+        yield* doWrite(a, k, aux[i]);
+        i++;
+      } else {
+        yield* doWrite(a, k, aux[j]);
+        j++;
+      }
+      k++;
+    }
+    while (i <= mid) {
+      yield* doWrite(a, k, aux[i]);
+      i++;
+      k++;
+    }
+    while (j <= high) {
+      yield* doWrite(a, k, aux[j]);
+      j++;
+      k++;
+    }
+  }
+
+  function* merge(a, opts) {
+    const { key } = ctxOf(opts);
+    yield* mergeRange(a, 0, a.length - 1, [...a], key);
+  }
+
+  function* quickRange(a, low, high, key) {
+    if (low >= high) {
+      if (low === high) yield sortedOp(low);
+      return;
+    }
+    yield mark(high, "pivot");
+    yield narrate(`Pivot selected at index ${high} (value ${a[high]}).`);
+    const pivotValue = key(a[high]);
+    let i = low - 1;
+    for (let j = low; j < high; j++) {
+      yield compare(j, high);
+      if (key(a[j]) < pivotValue) {
+        i++;
+        if (i !== j) yield* doSwap(a, i, j);
+      }
+    }
+    yield* doSwap(a, i + 1, high);
+    yield unmark(high, "pivot");
+    yield sortedOp(i + 1);
+    yield* quickRange(a, low, i, key);
+    yield* quickRange(a, i + 2, high, key);
+  }
+
+  function* quick(a, opts) {
+    const { key } = ctxOf(opts);
+    yield* quickRange(a, 0, a.length - 1, key);
+  }
+
+  function* heapify(a, size, root, key) {
+    let largest = root;
+    const left = 2 * root + 1;
+    const right = 2 * root + 2;
+    if (left < size) {
+      yield compare(left, largest);
+      if (key(a[left]) > key(a[largest])) largest = left;
+    }
+    if (right < size) {
+      yield compare(right, largest);
+      if (key(a[right]) > key(a[largest])) largest = right;
+    }
+    if (largest !== root) {
+      yield* doSwap(a, root, largest);
+      yield* heapify(a, size, largest, key);
+    }
+  }
+
+  function* heap(a, opts) {
+    const { key } = ctxOf(opts);
+    const n = a.length;
+    for (let i = Math.floor(n / 2) - 1; i >= 0; i--) {
+      yield* heapify(a, n, i, key);
+    }
+    for (let i = n - 1; i > 0; i--) {
+      yield* doSwap(a, 0, i);
+      yield sortedOp(i);
+      yield* heapify(a, i, 0, key);
+    }
+    if (n > 0) yield sortedOp(0);
+  }
+
+  function* shell(a, opts) {
+    const { key } = ctxOf(opts);
+    const n = a.length;
+    let gap = Math.floor(n / 2);
+    while (gap > 0) {
+      yield { t: "gap", gap };
+      yield narrate(`Shell sort: starting pass with gap = ${gap}.`);
+      for (let i = gap; i < n; i++) {
+        const temp = a[i];
+        let j = i;
+        yield mark(i, "gap");
+        while (j >= gap) {
+          yield compare(j - gap, j);
+          if (key(a[j - gap]) > key(temp)) {
+            yield* doWrite(a, j, a[j - gap]);
+            j -= gap;
+          } else {
+            break;
+          }
+        }
+        if (j !== i) yield* doWrite(a, j, temp);
+        yield unmark(i, "gap");
+      }
+      gap = Math.floor(gap / 2);
+    }
+  }
+
+  function* radix(a, opts) {
+    const { key } = ctxOf(opts);
+    const n = a.length;
+    if (n === 0) return;
+    const max = Math.max(...a.map(key));
+    const placeNames = ["ones", "tens", "hundreds"];
+    let exp = 1;
+    let pass = 0;
+    while (Math.floor(max / exp) > 0) {
+      yield { t: "digitExp", exp };
+      const place = placeNames[pass] || `10^${pass}`;
+      yield narrate(`Radix sort pass ${pass + 1}: sorting by ${place} digit.`);
+
+      const output = new Array(n);
+      const count = new Array(10).fill(0);
+      for (let i = 0; i < n; i++) {
+        const digit = Math.floor(key(a[i]) / exp) % 10;
+        yield narrate(`Counting digit ${digit} at index ${i} (value ${a[i]}).`);
+        count[digit]++;
+        yield touch(i, "digit");
+      }
+      for (let i = 1; i < 10; i++) count[i] += count[i - 1];
+      for (let i = n - 1; i >= 0; i--) {
+        const digit = Math.floor(key(a[i]) / exp) % 10;
+        const pos = count[digit] - 1;
+        output[pos] = a[i];
+        yield narrate(`Placing ${a[i]} into bucket position ${pos} (digit ${digit}).`);
+        count[digit]--;
+        yield touch(i, "digit");
+      }
+      for (let i = 0; i < n; i++) {
+        yield* doWrite(a, i, output[i]);
+        yield touch(i, "digit");
+      }
+      exp *= 10;
+      pass++;
+    }
+  }
+
+  function* counting(a, opts) {
+    const { key } = ctxOf(opts);
+    const n = a.length;
+    if (n === 0) return;
+    const keys = a.map(key);
+    const min = Math.min(...keys);
+    const max = Math.max(...keys);
+    const range = max - min + 1;
+    const count = new Array(range).fill(0);
+    yield narrate(`Counting sort: value range ${min}…${max} (${range} buckets).`);
+
+    for (let i = 0; i < n; i++) {
+      const bucket = key(a[i]) - min;
+      count[bucket]++;
+      yield narrate(`Incrementing count for value ${a[i]} (bucket ${bucket}).`);
+      yield { t: "counts", counts: count.slice(), min, max, highlight: bucket, costWrites: 1, access: [i], cls: "bucket", idx: i };
+    }
+    for (let i = 1; i < range; i++) {
+      count[i] += count[i - 1];
+      yield narrate(`Prefix sum at bucket ${i}: cumulative count = ${count[i]}.`);
+      yield { t: "counts", counts: count.slice(), min, max, highlight: i, costWrites: 0, access: [], cls: null, idx: -1 };
+    }
+    const output = new Array(n);
+    for (let i = n - 1; i >= 0; i--) {
+      const bucket = key(a[i]) - min;
+      const pos = count[bucket] - 1;
+      output[pos] = a[i];
+      count[bucket]--;
+      yield narrate(`Placing ${a[i]} at output position ${pos}.`);
+      yield { t: "counts", counts: count.slice(), min, max, highlight: bucket, costWrites: 0, access: [i], cls: "bucket", idx: i };
+    }
+    for (let i = 0; i < n; i++) {
+      yield* doWrite(a, i, output[i]);
+      yield touch(i, "bucket");
+    }
+  }
+
+  function* cocktail(a, opts) {
+    const { key } = ctxOf(opts);
+    const n = a.length;
+    let start = 0;
+    let end = n - 1;
+    while (start < end) {
+      yield narrate(`Cocktail pass: scanning forward from ${start} to ${end}.`);
+      for (let i = start; i < end; i++) {
+        yield compare(i, i + 1);
+        if (key(a[i]) > key(a[i + 1])) yield* doSwap(a, i, i + 1);
+      }
+      yield sortedOp(end);
+      end--;
+      if (start >= end) break;
+      yield narrate(`Cocktail pass: scanning backward from ${end} to ${start}.`);
+      for (let i = end; i > start; i--) {
+        yield compare(i - 1, i);
+        if (key(a[i - 1]) > key(a[i])) yield* doSwap(a, i - 1, i);
+      }
+      yield sortedOp(start);
+      start++;
+    }
+    if (n > 0) yield sortedOp(start);
+  }
+
+  // ---------- the new four ----------
+  function* comb(a, opts) {
+    const { key } = ctxOf(opts);
+    const n = a.length;
+    const SHRINK = 1.3;
+    let gap = n;
+    let swapped = true;
+    while (gap > 1 || swapped) {
+      gap = Math.max(1, Math.floor(gap / SHRINK));
+      yield { t: "gap", gap };
+      yield narrate(`Comb sort: comparing elements ${gap} apart.`);
+      swapped = false;
+      for (let i = 0; i + gap < n; i++) {
+        yield compare(i, i + gap);
+        if (key(a[i]) > key(a[i + gap])) {
+          yield* doSwap(a, i, i + gap);
+          swapped = true;
+        }
+      }
+    }
+    for (let i = 0; i < n; i++) yield sortedOp(i);
+  }
+
+  function* gnome(a, opts) {
+    const { key } = ctxOf(opts);
+    const n = a.length;
+    let pos = 0;
+    while (pos < n) {
+      if (pos === 0) {
+        pos++;
+        continue;
+      }
+      yield compare(pos - 1, pos);
+      if (key(a[pos - 1]) <= key(a[pos])) {
+        pos++;
+      } else {
+        yield* doSwap(a, pos - 1, pos);
+        pos--;
+        yield narrate(`Gnome steps back to index ${pos} after swapping.`);
+      }
+    }
+    for (let i = 0; i < n; i++) yield sortedOp(i);
+  }
+
+  function* cycle(a, opts) {
+    const { key } = ctxOf(opts);
+    const n = a.length;
+    for (let cycleStart = 0; cycleStart < n - 1; cycleStart++) {
+      let item = a[cycleStart];
+      yield mark(cycleStart, "pivot");
+      yield narrate(`Cycle sort: finding the final home of index ${cycleStart}.`);
+
+      let pos = cycleStart;
+      for (let i = cycleStart + 1; i < n; i++) {
+        yield compare(i, cycleStart);
+        if (key(a[i]) < key(item)) pos++;
+      }
+      if (pos === cycleStart) {
+        yield unmark(cycleStart, "pivot");
+        yield sortedOp(cycleStart);
+        continue;
+      }
+      while (key(item) === key(a[pos])) pos++;
+      let displaced = a[pos];
+      yield* doWrite(a, pos, item);
+      yield sortedOp(pos);
+      item = displaced;
+
+      while (pos !== cycleStart) {
+        pos = cycleStart;
+        for (let i = cycleStart + 1; i < n; i++) {
+          yield compare(i, cycleStart);
+          if (key(a[i]) < key(item)) pos++;
+        }
+        while (pos !== cycleStart && key(item) === key(a[pos])) pos++;
+        displaced = a[pos];
+        yield* doWrite(a, pos, item);
+        if (pos !== cycleStart) yield sortedOp(pos);
+        item = displaced;
+      }
+      yield unmark(cycleStart, "pivot");
+      yield sortedOp(cycleStart);
+    }
+    if (n > 0) yield sortedOp(n - 1);
+  }
+
+  const TIM_MIN_RUN = 16;
+
+  function* tim(a, opts) {
+    const { key } = ctxOf(opts);
+    const n = a.length;
+    if (n === 0) return;
+
+    yield narrate(`TimSort: insertion-sorting runs of up to ${TIM_MIN_RUN} elements.`);
+    for (let start = 0; start < n; start += TIM_MIN_RUN) {
+      const end = Math.min(start + TIM_MIN_RUN - 1, n - 1);
+      for (let i = start + 1; i <= end; i++) {
+        let j = i;
+        while (j > start) {
+          yield compare(j - 1, j);
+          if (key(a[j - 1]) > key(a[j])) {
+            yield* doSwap(a, j - 1, j);
+            j--;
+          } else {
+            break;
+          }
+        }
+      }
+    }
+
+    const aux = [...a];
+    for (let width = TIM_MIN_RUN; width < n; width *= 2) {
+      yield narrate(`TimSort: merging runs of width ${width}.`);
+      for (let low = 0; low + width < n; low += width * 2) {
+        const mid = low + width - 1;
+        const high = Math.min(low + width * 2 - 1, n - 1);
+        yield compare(mid, mid + 1);
+        if (key(a[mid]) <= key(a[mid + 1])) continue; // already ordered — TimSort's galloping shortcut
+        for (let k = low; k <= high; k++) aux[k] = a[k];
+        let i = low;
+        let j = mid + 1;
+        let k = low;
+        while (i <= mid && j <= high) {
+          yield compare(i, j);
+          if (key(aux[i]) <= key(aux[j])) {
+            yield* doWrite(a, k, aux[i]);
+            i++;
+          } else {
+            yield* doWrite(a, k, aux[j]);
+            j++;
+          }
+          k++;
+        }
+        while (i <= mid) {
+          yield* doWrite(a, k, aux[i]);
+          i++;
+          k++;
+        }
+        while (j <= high) {
+          yield* doWrite(a, k, aux[j]);
+          j++;
+          k++;
+        }
+      }
+    }
+    for (let i = 0; i < n; i++) yield sortedOp(i);
+  }
+
+  const algorithms = {
+    bubble,
+    selection,
+    insertion,
+    merge,
+    quick,
+    heap,
+    shell,
+    radix,
+    counting,
+    cocktail,
+    comb,
+    gnome,
+    cycle,
+    tim,
+  };
+
+  // ---------- headless execution ----------
+  const METRIC_STEP_TYPES = new Set(["compare", "swap", "write", "touch", "counts"]);
+
+  function newMetrics() {
+    return { comparisons: 0, swaps: 0, writes: 0, steps: 0 };
+  }
+
+  function applyMetric(metrics, op) {
+    switch (op.t) {
+      case "compare":
+        metrics.comparisons++;
+        break;
+      case "swap":
+        metrics.swaps++;
+        metrics.writes += 2;
+        break;
+      case "write":
+        metrics.writes++;
+        break;
+      case "counts":
+        metrics.writes += op.costWrites || 0;
+        break;
+      default:
+        break;
+    }
+    if (METRIC_STEP_TYPES.has(op.t)) metrics.steps++;
+  }
+
+  function totalOps(metrics) {
+    return metrics.comparisons + metrics.swaps + metrics.writes;
+  }
+
+  function run(algorithmId, input, opts) {
+    const algorithm = algorithms[algorithmId];
+    if (!algorithm) throw new Error(`Unknown algorithm: ${algorithmId}`);
+    const array = [...input];
+    const metrics = newMetrics();
+    for (const op of algorithm(array, opts)) applyMetric(metrics, op);
+    return { array, metrics };
+  }
+
+  // ---------- complexity profiling ----------
+  function benchmark(algorithmId, sizes, makeDataset, opts) {
+    return sizes.map((n) => {
+      const { metrics } = run(algorithmId, makeDataset(n), opts);
+      return { n, ops: totalOps(metrics), metrics };
+    });
+  }
+
+  /**
+   * Least-squares slope of ln(ops) against ln(n): for ops ≈ c·n^k the
+   * slope recovers k. Returns null when there are not enough points.
+   */
+  function estimateExponent(points) {
+    const usable = points.filter((p) => p.n > 1 && p.ops > 0);
+    if (usable.length < 2) return null;
+    const xs = usable.map((p) => Math.log(p.n));
+    const ys = usable.map((p) => Math.log(p.ops));
+    const mx = xs.reduce((s, v) => s + v, 0) / xs.length;
+    const my = ys.reduce((s, v) => s + v, 0) / ys.length;
+    let num = 0;
+    let den = 0;
+    for (let i = 0; i < xs.length; i++) {
+      num += (xs[i] - mx) * (ys[i] - my);
+      den += (xs[i] - mx) * (xs[i] - mx);
+    }
+    if (den === 0) return null;
+    return num / den;
+  }
+
+  // ---------- deterministic datasets (tests + node profiling) ----------
+  function mulberry32(seed) {
+    let s = seed >>> 0;
+    return function () {
+      s |= 0;
+      s = (s + 0x6d2b79f5) | 0;
+      let t = Math.imul(s ^ (s >>> 15), 1 | s);
+      t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+      return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+  }
+
+  const datasets = {
+    random(n, rng) {
+      const rand = rng || Math.random;
+      return Array.from({ length: n }, () => Math.floor(rand() * 91) + 5);
+    },
+    sorted(n) {
+      return Array.from({ length: n }, (_, i) => Math.floor(((i + 1) / n) * 90) + 5);
+    },
+    reversed(n) {
+      return datasets.sorted(n).reverse();
+    },
+    fewUnique(n, rng) {
+      const rand = rng || Math.random;
+      const uniques = [12, 28, 44, 60, 76, 92];
+      return Array.from({ length: n }, () => uniques[Math.floor(rand() * uniques.length)]);
+    },
+  };
+
+  const api = {
+    ALGORITHM_IDS: Object.keys(algorithms),
+    TIM_MIN_RUN,
+    algorithms,
+    newMetrics,
+    applyMetric,
+    totalOps,
+    run,
+    benchmark,
+    estimateExponent,
+    datasets,
+    mulberry32,
+  };
+
+  if (typeof module !== "undefined" && module.exports) module.exports = api;
+  else root.SortCore = api;
+})(typeof globalThis !== "undefined" ? globalThis : this);
diff --git a/style.css b/style.css
index 0060c63..1d8c91b 100644
--- a/style.css
+++ b/style.css
@@ -1298,4 +1298,27 @@ body.presentation-active {
 
 body.race-active .path-cell {
   font-size: clamp(0.38rem, 1vw, 0.65rem);
-}
\ No newline at end of file
+}
+/* ---------- Complexity profiler ---------- */
+.profiler-chart {
+  width: 100%;
+  height: auto;
+  border-radius: 8px;
+  background: var(--panel-inset, rgba(148, 163, 184, 0.08));
+}
+
+.profiler-status {
+  font-size: 0.78rem;
+  color: var(--text-muted, #94a3b8);
+  margin: 0.5rem 0;
+  line-height: 1.4;
+}
+
+.profiler-dot {
+  display: inline-block;
+  width: 10px;
+  height: 10px;
+  border-radius: 50%;
+  margin-right: 6px;
+  vertical-align: middle;
+}
diff --git a/sw.js b/sw.js
index 6c004a2..8a73097 100644
--- a/sw.js
+++ b/sw.js
@@ -1,11 +1,12 @@
-/* Algo Lab — Service Worker v5 */
-const CACHE_NAME = "algo-lab-v5";
+/* Algo Lab — Service Worker v6 */
+const CACHE_NAME = "algo-lab-v6";
 const ASSETS = [
   "./",
   "./index.html",
   "./pathfinding.html",
   "./style.css",
   "./script.js",
+  "./sorting-core.js",
   "./pathfinding.js",
   "./pathfinding-core.js",
   "./manifest.json",
diff --git a/tests/sorting.test.js b/tests/sorting.test.js
new file mode 100644
index 0000000..ebc2f1c
--- /dev/null
+++ b/tests/sorting.test.js
@@ -0,0 +1,152 @@
+"use strict";
+
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const SortCore = require("../sorting-core.js");
+
+const { ALGORITHM_IDS, run, benchmark, estimateExponent, datasets, mulberry32 } = SortCore;
+
+const STABLE_IDS = ["bubble", "insertion", "merge", "radix", "counting", "cocktail", "gnome", "tim"];
+
+function sortedCopy(arr) {
+  return [...arr].sort((a, b) => a - b);
+}
+
+test("registry exposes all fourteen algorithms", () => {
+  assert.equal(ALGORITHM_IDS.length, 14);
+  for (const id of ["comb", "gnome", "cycle", "tim"]) {
+    assert.ok(ALGORITHM_IDS.includes(id), `missing ${id}`);
+  }
+});
+
+test("run throws on unknown algorithm", () => {
+  assert.throws(() => run("bogo", [3, 1, 2]), /Unknown algorithm/);
+});
+
+for (const id of SortCore.ALGORITHM_IDS) {
+  test(`${id}: sorts every dataset shape`, () => {
+    const rng = mulberry32(42);
+    const inputs = [
+      [],
+      [7],
+      [2, 1],
+      [5, 5, 5, 5],
+      datasets.random(97, rng),
+      datasets.sorted(64),
+      datasets.reversed(64),
+      datasets.fewUnique(80, rng),
+    ];
+    for (const input of inputs) {
+      const { array } = run(id, input);
+      assert.deepEqual(array, sortedCopy(input), `${id} failed on n=${input.length}`);
+    }
+  });
+
+  test(`${id}: does not mutate its input`, () => {
+    const input = [9, 4, 7, 1, 8, 2];
+    const frozen = [...input];
+    run(id, input);
+    assert.deepEqual(input, frozen);
+  });
+}
+
+for (const id of STABLE_IDS) {
+  test(`${id}: is stable`, () => {
+    const rng = mulberry32(7);
+    // value = key * 1000 + tag; sort by key only, tags record input order
+    const n = 60;
+    const input = Array.from({ length: n }, (_, tag) => Math.floor(rng() * 8) * 1000 + tag);
+    const key = (v) => Math.floor(v / 1000);
+    const { array } = run(id, input, { key });
+
+    for (let i = 1; i < array.length; i++) {
+      const prevKey = key(array[i - 1]);
+      const curKey = key(array[i]);
+      assert.ok(prevKey <= curKey, `${id}: keys out of order at ${i}`);
+      if (prevKey === curKey) {
+        assert.ok(
+          array[i - 1] % 1000 < array[i] % 1000,
+          `${id}: equal keys reordered at ${i} (${array[i - 1]} before ${array[i]})`
+        );
+      }
+    }
+  });
+}
+
+test("cycle: performs at most n writes on distinct values", () => {
+  const rng = mulberry32(3);
+  const input = Array.from({ length: 50 }, (_, i) => i + 1);
+  for (let i = input.length - 1; i > 0; i--) {
+    const j = Math.floor(rng() * (i + 1));
+    [input[i], input[j]] = [input[j], input[i]];
+  }
+  const { array, metrics } = run("cycle", input);
+  assert.deepEqual(array, sortedCopy(input));
+  assert.ok(metrics.writes <= input.length, `writes ${metrics.writes} > n ${input.length}`);
+});
+
+test("cycle: zero writes on an already sorted distinct array", () => {
+  const input = Array.from({ length: 40 }, (_, i) => i);
+  const { metrics } = run("cycle", input);
+  assert.equal(metrics.writes, 0);
+});
+
+test("bubble: exact comparison and swap counts on reversed input", () => {
+  const n = 30;
+  const { metrics } = run("bubble", datasets.reversed(n));
+  // reversed distinct values: every adjacent pair is inverted
+  assert.equal(metrics.comparisons, (n * (n - 1)) / 2);
+  assert.equal(metrics.swaps, (n * (n - 1)) / 2);
+});
+
+test("selection: at most n-1 swaps", () => {
+  const rng = mulberry32(11);
+  const input = datasets.random(80, rng);
+  const { metrics } = run("selection", input);
+  assert.ok(metrics.swaps <= input.length - 1);
+});
+
+test("tim: near-linear comparisons on already sorted input", () => {
+  const n = 128;
+  const { metrics } = run("tim", datasets.sorted(n));
+  assert.ok(
+    metrics.comparisons < 2 * n,
+    `expected < ${2 * n} comparisons on sorted input, got ${metrics.comparisons}`
+  );
+});
+
+test("benchmark: op counts grow with n", () => {
+  const points = benchmark("bubble", [16, 32, 64], (n) => datasets.reversed(n));
+  assert.equal(points.length, 3);
+  assert.ok(points[0].ops < points[1].ops && points[1].ops < points[2].ops);
+});
+
+test("estimateExponent recovers known growth rates", () => {
+  const quadratic = [16, 32, 64, 128, 256].map((n) => ({ n, ops: 3 * n * n }));
+  const linear = [16, 32, 64, 128, 256].map((n) => ({ n, ops: 5 * n }));
+  const linearithmic = [16, 32, 64, 128, 256].map((n) => ({ n, ops: n * Math.log2(n) }));
+
+  assert.ok(Math.abs(estimateExponent(quadratic) - 2) < 0.01);
+  assert.ok(Math.abs(estimateExponent(linear) - 1) < 0.01);
+  const k = estimateExponent(linearithmic);
+  assert.ok(k > 1 && k < 1.5, `n log n slope should land between 1 and 1.5, got ${k}`);
+});
+
+test("estimateExponent handles degenerate input", () => {
+  assert.equal(estimateExponent([]), null);
+  assert.equal(estimateExponent([{ n: 16, ops: 100 }]), null);
+});
+
+test("measured exponents separate quadratic sorts from linearithmic ones", () => {
+  const rng = mulberry32(99);
+  const sizes = [32, 64, 128, 256];
+  const make = (n) => datasets.random(n, rng);
+
+  const bubbleK = estimateExponent(benchmark("bubble", sizes, make));
+  const mergeK = estimateExponent(benchmark("merge", sizes, make));
+  const countingK = estimateExponent(benchmark("counting", sizes, make));
+
+  assert.ok(bubbleK > 1.7, `bubble should look quadratic, got ${bubbleK}`);
+  assert.ok(mergeK < 1.5, `merge should look linearithmic, got ${mergeK}`);
+  assert.ok(countingK < 1.3, `counting should look linear, got ${countingK}`);
+});