Fix index cards appearing out of order when timestamps are non-monotonic

Sort index timeline items by conversation index instead of timestamp,
so cards always appear in their original prompt order (simonw#1 before simonw#2)
even when sub-second timestamps happen to be non-monotonic.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jack-kerouac

src/claude_code_transcripts/__init__.py

@@ -1437,16 +1437,16 @@ def generate_html(json_path, output_dir, github_repo=None):
         item_html = _macros.index_item(
             prompt_num, link, conv["timestamp"], rendered_content, stats_html
         )
-        timeline_items.append((conv["timestamp"], "prompt", item_html))
+        timeline_items.append((i, conv["timestamp"], item_html))
 
     # Add commits as separate timeline items
     for commit_ts, commit_hash, commit_msg, page_num, conv_idx in all_commits:
         item_html = _macros.index_commit(
             commit_hash, commit_msg, commit_ts, _github_repo
         )
-        timeline_items.append((commit_ts, "commit", item_html))
+        timeline_items.append((conv_idx, commit_ts, item_html))
 
-    # Sort by timestamp
+    # Sort by original conversation order (preserves prompt sequence)
     timeline_items.sort(key=lambda x: x[0])
     index_items = [item[2] for item in timeline_items]
 
@@ -1911,16 +1911,16 @@ def generate_html_from_session_data(session_data, output_dir, github_repo=None):
         item_html = _macros.index_item(
             prompt_num, link, conv["timestamp"], rendered_content, stats_html
         )
-        timeline_items.append((conv["timestamp"], "prompt", item_html))
+        timeline_items.append((i, conv["timestamp"], item_html))
 
     # Add commits as separate timeline items
     for commit_ts, commit_hash, commit_msg, page_num, conv_idx in all_commits:
         item_html = _macros.index_commit(
             commit_hash, commit_msg, commit_ts, _github_repo
         )
-        timeline_items.append((commit_ts, "commit", item_html))
+        timeline_items.append((conv_idx, commit_ts, item_html))
 
-    # Sort by timestamp
+    # Sort by original conversation order (preserves prompt sequence)
     timeline_items.sort(key=lambda x: x[0])
     index_items = [item[2] for item in timeline_items]
 

tests/test_generate_html.py

@@ -1638,3 +1638,64 @@ def test_search_total_pages_available(self, output_dir):
 
         # Total pages should be embedded for JS to know how many pages to fetch
         assert "totalPages" in index_html or "total_pages" in index_html
+
+
+class TestIndexCardOrder:
+    """Tests that index cards preserve original prompt order."""
+
+    def test_index_cards_follow_prompt_order_not_timestamp(self, output_dir):
+        """Cards in index.html must appear in prompt order, even when
+        an earlier prompt has a later timestamp than the next prompt.
+
+        Regression test: when two prompts share near-identical timestamps
+        (sub-second apart) the earlier prompt can have a *later* timestamp
+        due to message ordering in the JSON, causing the index to show
+        #2 before #1.
+        """
+        # Prompt 1 has a LATER timestamp than prompt 2
+        session_data = {
+            "loglines": [
+                {
+                    "type": "user",
+                    "timestamp": "2025-06-01T12:00:00.500Z",
+                    "message": {"role": "user", "content": "First prompt"},
+                },
+                {
+                    "type": "assistant",
+                    "timestamp": "2025-06-01T12:00:01.000Z",
+                    "message": {
+                        "role": "assistant",
+                        "content": [{"type": "text", "text": "Reply to first"}],
+                    },
+                },
+                {
+                    "type": "user",
+                    "timestamp": "2025-06-01T12:00:00.100Z",
+                    "message": {"role": "user", "content": "Second prompt"},
+                },
+                {
+                    "type": "assistant",
+                    "timestamp": "2025-06-01T12:00:00.600Z",
+                    "message": {
+                        "role": "assistant",
+                        "content": [{"type": "text", "text": "Reply to second"}],
+                    },
+                },
+            ]
+        }
+        session_file = output_dir / "session.jsonl"
+        with open(session_file, "w") as f:
+            for line in session_data["loglines"]:
+                f.write(json.dumps(line) + "\n")
+
+        generate_html(session_file, output_dir)
+
+        index_html = (output_dir / "index.html").read_text(encoding="utf-8")
+
+        # Find the positions of #1 and #2 in the HTML
+        pos_1 = index_html.index("#1</span>")
+        pos_2 = index_html.index("#2</span>")
+        assert pos_1 < pos_2, (
+            f"Card #1 (pos {pos_1}) should appear before card #2 (pos {pos_2}) "
+            "in the index, regardless of timestamps"
+        )