Improve README with usage instructions and tech overview

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

.gitignore

@@ -1 +0,0 @@
-node_modules/

README.md

@@ -1,55 +1,40 @@
 # P2P Poll App
 
-A peer-to-peer polling app built with [Automerge](https://automerge.org/) and Vanilla JS. No backend required — polls sync in real time across browsers using CRDTs and a WebSocket relay.
+A peer-to-peer polling app where users can add options and vote on them. All data syncs directly between browsers using WebRTC — no central server stores any poll data.
 
-## Features
+## How It Works
 
-- **Add options** — type an option and press Enter or click "Add Option". Duplicate options (case-insensitive) are rejected with an inline error message.
+- **Yjs CRDTs** handle shared state — concurrent edits from different peers merge automatically without conflicts
-- **Vote on options** — click the vote button next to any option. You can vote on multiple options, but only once per option.
+- **y-webrtc** establishes direct WebRTC connections between browsers (a public signaling server is used only for peer discovery)
-- **Toggle votes** — click your vote again to remove it (the button turns green with a checkmark when you've voted).
+- Each user gets a stable random ID (stored in localStorage) ensuring one vote per user per option
-- **Live vote counts** — options are sorted by vote count in descending order and update in real time as votes come in from other users.
+- Polls are identified by room name, shareable via URL
-- **2-minute countdown timer** — click "Start 2-min Vote" to begin a shared countdown. Voting is open before and during the countdown. Once the timer expires, all vote buttons are disabled.
-- **Shared timer** — the deadline is stored in the Automerge document, so all peers see the same countdown and voting closes simultaneously for everyone.
-- **Copy URL** — click "Copy URL" to copy the poll link to your clipboard. Share it with others to join the same poll.
-- **P2P sync** — all state (options, votes, timer) syncs across browsers in real time with no central server handling your data.
 
-## How it works
+## Getting Started
-
-### Tech stack
-
-- **[Automerge](https://automerge.org/)** via `@automerge/vanillajs` — a CRDT library that lets multiple clients concurrently edit shared documents and merge changes without conflicts.
-- **BroadcastChannelNetworkAdapter** — syncs between tabs in the same browser instantly via the browser's BroadcastChannel API.
-- **WebSocketClientAdapter** — syncs across different browsers/devices via a WebSocket relay (`wss://sync.automerge.org`). The relay only forwards CRDT messages; it does not store or interpret your data.
-- **IndexedDBStorageAdapter** — persists the document locally so it survives page refreshes.
-- **Vite** — bundles the app with WebAssembly support (required by Automerge).
-
-### Data model
-
-The poll is a single Automerge document with three fields:
-
-```js
-{
-  options: string[],       // list of poll options in insertion order
-  votes: { [option]: number }, // vote count per option
-  deadline: number | null  // Unix timestamp (ms) when voting closes, or null
-}
-```
-
-### URL-based sharing
-
-Each document gets a unique Automerge URL (e.g. `automerge:abc123...`) stored in the page's URL hash. Opening the same URL in any browser loads and syncs the same document. Creating a new poll generates a new document and updates the hash automatically.
-
-### Voting rules
-
-- Voted options are tracked in `localStorage` (keyed by document URL), so they persist across page refreshes but are isolated per browser.
-- One vote per option per user. Votes can be toggled off and back on until the timer expires.
-- The timer (`doc.deadline`) is set once by whoever clicks "Start 2-min Vote" and is shared via the Automerge document, so all peers use the same deadline.
-
-## Running locally
 
 ```bash
-pnpm install
+npm install
-pnpm dev
+npm run dev
 ```
 
-Open the printed localhost URL. To test cross-browser sync, copy the URL (including the `#automerge:...` hash) and open it in a different browser.
+Open `http://localhost:5173` in your browser. To share a specific poll, use the `?room=` query parameter:
+
+```
+http://localhost:5173/?room=my-poll
+```
+
+Share this URL with others to join the same poll.
+
+## Cross-Device Testing
+
+```bash
+npm run dev -- --host
+```
+
+Then open `http://<your-local-ip>:5173/?room=test` on another device on the same network.
+
+## Tech Stack
+
+- [Yjs](https://yjs.dev/) — CRDT library for conflict-free shared state
+- [y-webrtc](https://github.com/yjs/y-webrtc) — WebRTC provider for P2P connectivity
+- [Vite](https://vite.dev/) — Dev server and bundler
+- Vanilla JS — No framework dependencies

app.js

@@ -1,214 +0,0 @@
-import {
-  Repo,
-  BroadcastChannelNetworkAdapter,
-  WebSocketClientAdapter,
-  IndexedDBStorageAdapter,
-  isValidAutomergeUrl,
-} from "@automerge/vanillajs";
-
-const REPO = new Repo({
-  network: [
-    new BroadcastChannelNetworkAdapter(),
-    new WebSocketClientAdapter("wss://sync.automerge.org"),
-  ],
-  storage: new IndexedDBStorageAdapter(),
-});
-
-let HANDLE;
-
-function getVotedKey(docUrl) {
-  return `p2p-poll-voted:${docUrl}`;
-}
-
-function getVotedOptions() {
-  const key = getVotedKey(document.location.hash);
-  return new Set(JSON.parse(localStorage.getItem(key) || "[]"));
-}
-
-function markVoted(opt) {
-  const key = getVotedKey(document.location.hash);
-  const voted = getVotedOptions();
-  voted.add(opt);
-  localStorage.setItem(key, JSON.stringify([...voted]));
-}
-
-function unmarkVoted(opt) {
-  const key = getVotedKey(document.location.hash);
-  const voted = getVotedOptions();
-  voted.delete(opt);
-  localStorage.setItem(key, JSON.stringify([...voted]));
-}
-
-const locationHash = document.location.hash.substring(1);
-const statusEl = document.getElementById("status");
-const optionsList = document.getElementById("options-list");
-const optionInput = document.getElementById("option-input");
-const addBtn = document.getElementById("add-btn");
-const duplicateMsg = document.getElementById("duplicate-msg");
-const copyBtn = document.getElementById("copy-btn");
-const timerEl = document.getElementById("timer");
-const startVotingBtn = document.getElementById("start-voting-btn");
-
-if (isValidAutomergeUrl(locationHash)) {
-  statusEl.textContent = "Loading document…";
-  try {
-    HANDLE = await REPO.find(locationHash);
-    statusEl.textContent = "";
-  } catch (err) {
-    statusEl.textContent = "Could not load document. Starting a new one.";
-    HANDLE = REPO.create({ options: [], votes: {}, deadline: null });
-    document.location.hash = HANDLE.url;
-  }
-} else {
-  HANDLE = REPO.create({ options: [], votes: {}, deadline: null });
-  document.location.hash = HANDLE.url;
-}
-
-HANDLE.on("change", ({ doc }) => render(doc));
-
-const initialDoc = HANDLE.doc();
-if (initialDoc) render(initialDoc);
-
-let timerInterval = null;
-
-function render(doc) {
-  renderOptions(doc);
-  renderTimer(doc);
-}
-
-function renderOptions(doc) {
-  const votes = doc.votes || {};
-  const deadline = doc.deadline ?? null;
-  const now = Date.now();
-  const votingClosed = deadline !== null && now >= deadline;
-  const votedOptions = getVotedOptions();
-
-  const sorted = [...(doc.options || [])].sort(
-    (a, b) => (votes[b] || 0) - (votes[a] || 0),
-  );
-
-  optionsList.innerHTML = "";
-  sorted.forEach((opt) => {
-    const count = votes[opt] || 0;
-    const alreadyVoted = votedOptions.has(opt);
-
-    const item = document.createElement("div");
-    item.className = "option-item";
-
-    const label = document.createElement("span");
-    label.className = "option-label";
-    label.textContent = opt;
-
-    const voteBtn = document.createElement("button");
-    voteBtn.className = alreadyVoted ? "vote-btn voted" : "vote-btn";
-    voteBtn.textContent = alreadyVoted ? `✓ ${count}` : `▲ ${count}`;
-    voteBtn.disabled = votingClosed;
-    if (votingClosed) voteBtn.title = "Voting is closed";
-    else if (alreadyVoted) voteBtn.title = "Click to remove your vote";
-
-    voteBtn.addEventListener("click", () => {
-      if (alreadyVoted) {
-        unmarkVoted(opt);
-        HANDLE.change((d) => {
-          if (!d.votes) d.votes = {};
-          d.votes[opt] = Math.max(0, (d.votes[opt] || 0) - 1);
-        });
-      } else {
-        markVoted(opt);
-        HANDLE.change((d) => {
-          if (!d.votes) d.votes = {};
-          d.votes[opt] = (d.votes[opt] || 0) + 1;
-        });
-      }
-    });
-
-    item.appendChild(label);
-    item.appendChild(voteBtn);
-    optionsList.appendChild(item);
-  });
-}
-
-function renderTimer(doc) {
-  const deadline = doc?.deadline ?? null;
-  const now = Date.now();
-
-  if (deadline === null) {
-    timerEl.textContent = "";
-    startVotingBtn.hidden = false;
-    return;
-  }
-
-  startVotingBtn.hidden = true;
-
-  if (now >= deadline) {
-    timerEl.textContent = "Voting closed.";
-    timerEl.className = "timer closed";
-    clearInterval(timerInterval);
-    timerInterval = null;
-    return;
-  }
-
-  const remaining = Math.ceil((deadline - now) / 1000);
-  const mins = Math.floor(remaining / 60);
-  const secs = remaining % 60;
-  timerEl.textContent = `Voting closes in ${mins}:${secs.toString().padStart(2, "0")}`;
-  timerEl.className = "timer active";
-
-  if (!timerInterval) {
-    timerInterval = setInterval(() => {
-      const d = HANDLE.doc();
-      if (!d) return;
-      renderTimer(d);
-      renderOptions(d);
-      if (Date.now() >= d.deadline) {
-        clearInterval(timerInterval);
-        timerInterval = null;
-      }
-    }, 1000);
-  }
-}
-
-startVotingBtn.addEventListener("click", () => {
-  HANDLE.change((d) => {
-    d.deadline = Date.now() + 2 * 60 * 1000;
-  });
-});
-
-addBtn.addEventListener("click", () => {
-  const value = optionInput.value.trim();
-  if (!value) return;
-
-  const doc = HANDLE.doc();
-  const valueLower = value.toLowerCase();
-  const isDuplicate = (doc?.options || []).some(
-    (opt) => opt.toLowerCase() === valueLower,
-  );
-
-  if (isDuplicate) {
-    duplicateMsg.textContent = `"${value}" is already in the list.`;
-    duplicateMsg.hidden = false;
-    return;
-  }
-
-  duplicateMsg.hidden = true;
-  HANDLE.change((d) => {
-    if (!d.options) d.options = [];
-    d.options.push(value);
-  });
-  optionInput.value = "";
-});
-
-optionInput.addEventListener("keydown", (e) => {
-  if (e.key === "Enter") addBtn.click();
-});
-
-optionInput.addEventListener("input", () => {
-  duplicateMsg.hidden = true;
-});
-
-copyBtn.addEventListener("click", () => {
-  navigator.clipboard.writeText(window.location.href).then(() => {
-    copyBtn.textContent = "Copied!";
-    setTimeout(() => (copyBtn.textContent = "Copy URL"), 1500);
-  });
-});

index.html

@@ -1,31 +1,33 @@
-<!doctype html>
+<!DOCTYPE html>
 <html lang="en">
-    <head>
+<head>
-        <meta charset="UTF-8" />
+  <meta charset="UTF-8">
-        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-        <title>P2P Polling App</title>
+  <title>P2P Poll</title>
-        <link rel="stylesheet" href="./styles.css" />
+  <link rel="stylesheet" href="/src/style.css">
-    </head>
+</head>
-    <body>
+<body>
-        <div id="app">
+  <div id="app">
-            <h1>P2P Polling App</h1>
+    <header>
-            <div id="status"></div>
+      <h1>P2P Poll</h1>
-            <div id="add-option">
+      <div id="status">
-                <input
+        <span id="connection-status" class="connecting">Connecting...</span>
-                    type="text"
+        <span id="peer-count">1 peer</span>
-                    id="option-input"
+      </div>
-                    placeholder="Enter an option..."
+    </header>
-                />
+
-                <button id="add-btn">Add Option</button>
+    <main>
-            </div>
+      <div id="add-option">
-            <div id="duplicate-msg" hidden></div>
+        <input type="text" id="option-input" placeholder="Add a poll option..." maxlength="100">
-            <div id="timer-section">
+        <button id="add-btn">Add</button>
-                <div id="timer"></div>
+      </div>
-                <button id="start-voting-btn">Start 2-min Vote</button>
+
-            </div>
+      <div id="poll-options"></div>
-            <div id="options-list"></div>
+
-            <button id="copy-btn">Copy URL</button>
+      <p id="empty-state">No options yet. Add one above!</p>
-        </div>
+    </main>
-        <script type="module" src="./app.js"></script>
+  </div>
-    </body>
+
+  <script type="module" src="/src/main.js"></script>
+</body>
 </html>

package.json

@@ -1,23 +1,18 @@
 {
-  "name": "p2p-poll-app",
+  "name": "p2p-poll",
+  "private": true,
+  "version": "1.0.0",
   "type": "module",
-  "engines": {
-    "node": ">=24"
-  },
   "scripts": {
     "dev": "vite",
     "build": "vite build",
     "preview": "vite preview"
   },
   "dependencies": {
-    "@automerge/automerge-repo": "^2.0.0",
+    "yjs": "^13.6.0",
-    "@automerge/automerge-repo-network-websocket": "^2.0.0",
+    "y-webrtc": "^10.3.0"
-    "@automerge/automerge-repo-storage-indexeddb": "^2.0.0",
-    "@automerge/vanillajs": "^2.5.3"
   },
   "devDependencies": {
-    "vite": "^6.0.0",
+    "vite": "^6.0.0"
-    "vite-plugin-top-level-await": "^1.4.0",
-    "vite-plugin-wasm": "^3.3.0"
   }
 }

src/main.js

@@ -0,0 +1,136 @@
+import * as Y from 'yjs';
+import { WebrtcProvider } from 'y-webrtc';
+
+// --- Peer ID (stable across reloads) ---
+
+function getOrCreatePeerId() {
+  let id = localStorage.getItem('peer-id');
+  if (!id) {
+    id = crypto.randomUUID();
+    localStorage.setItem('peer-id', id);
+  }
+  return id;
+}
+
+const peerId = getOrCreatePeerId();
+
+// --- Room name from URL ---
+
+function getRoomName() {
+  const params = new URLSearchParams(window.location.search);
+  return params.get('room') || 'default-poll';
+}
+
+const roomName = getRoomName();
+
+// --- Yjs setup ---
+
+const ydoc = new Y.Doc();
+const provider = new WebrtcProvider(roomName, ydoc);
+const yOptions = ydoc.getMap('poll-options');
+
+// --- Data operations ---
+
+function addOption(name) {
+  const id = crypto.randomUUID();
+  const optionMap = new Y.Map();
+  optionMap.set('name', name);
+  optionMap.set('votes', new Y.Map());
+  yOptions.set(id, optionMap);
+}
+
+function toggleVote(optionId) {
+  const optionMap = yOptions.get(optionId);
+  if (!optionMap) return;
+  const votes = optionMap.get('votes');
+  if (votes.has(peerId)) {
+    votes.delete(peerId);
+  } else {
+    votes.set(peerId, true);
+  }
+}
+
+// --- UI rendering ---
+
+const container = document.getElementById('poll-options');
+const emptyState = document.getElementById('empty-state');
+
+function render() {
+  container.innerHTML = '';
+
+  const entries = [];
+  yOptions.forEach((optionMap, id) => {
+    entries.push({
+      id,
+      name: optionMap.get('name'),
+      votes: optionMap.get('votes').size,
+      voted: optionMap.get('votes').has(peerId),
+    });
+  });
+
+  entries.sort((a, b) => b.votes - a.votes || a.name.localeCompare(b.name));
+
+  emptyState.className = entries.length > 0 ? 'hidden' : '';
+
+  for (const entry of entries) {
+    const div = document.createElement('div');
+    div.className = 'poll-option';
+
+    const nameSpan = document.createElement('span');
+    nameSpan.className = 'option-name';
+    nameSpan.textContent = entry.name;
+
+    const voteCount = document.createElement('span');
+    voteCount.className = 'vote-count';
+    voteCount.textContent = entry.votes;
+
+    const voteBtn = document.createElement('button');
+    voteBtn.className = entry.voted ? 'vote-btn voted' : 'vote-btn';
+    voteBtn.textContent = entry.voted ? 'Unvote' : 'Vote';
+    voteBtn.addEventListener('click', () => toggleVote(entry.id));
+
+    div.append(nameSpan, voteCount, voteBtn);
+    container.appendChild(div);
+  }
+}
+
+// Re-render on any change in the shared state
+yOptions.observeDeep(() => render());
+
+// --- Add option handlers ---
+
+const input = document.getElementById('option-input');
+const addBtn = document.getElementById('add-btn');
+
+addBtn.addEventListener('click', () => {
+  const name = input.value.trim();
+  if (name) {
+    addOption(name);
+    input.value = '';
+  }
+});
+
+input.addEventListener('keydown', (e) => {
+  if (e.key === 'Enter') addBtn.click();
+});
+
+// --- Connection status & peer count ---
+
+const statusEl = document.getElementById('connection-status');
+const peerCountEl = document.getElementById('peer-count');
+
+provider.on('synced', ({ synced }) => {
+  statusEl.textContent = synced ? 'Connected' : 'Connecting...';
+  statusEl.className = synced ? 'connected' : 'connecting';
+});
+
+function updatePeerCount() {
+  const count = provider.awareness.getStates().size;
+  peerCountEl.textContent = `${count} peer${count !== 1 ? 's' : ''}`;
+}
+
+provider.awareness.on('change', updatePeerCount);
+updatePeerCount();
+
+// --- Initial render ---
+render();

src/style.css

@@ -0,0 +1,144 @@
+* {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+
+body {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  background: #f5f5f5;
+  color: #333;
+  min-height: 100vh;
+}
+
+#app {
+  max-width: 600px;
+  margin: 0 auto;
+  padding: 2rem 1rem;
+}
+
+header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 2rem;
+}
+
+h1 {
+  font-size: 1.5rem;
+}
+
+#status {
+  display: flex;
+  gap: 1rem;
+  font-size: 0.85rem;
+  color: #666;
+}
+
+#connection-status::before {
+  content: "";
+  display: inline-block;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  margin-right: 4px;
+  vertical-align: middle;
+}
+
+#connection-status.connected::before {
+  background: #4caf50;
+}
+
+#connection-status.connecting::before {
+  background: #ff9800;
+}
+
+#add-option {
+  display: flex;
+  gap: 0.5rem;
+  margin-bottom: 1.5rem;
+}
+
+#option-input {
+  flex: 1;
+  padding: 0.6rem 0.8rem;
+  border: 1px solid #ddd;
+  border-radius: 6px;
+  font-size: 1rem;
+  outline: none;
+}
+
+#option-input:focus {
+  border-color: #2196f3;
+}
+
+#add-btn {
+  padding: 0.6rem 1.2rem;
+  background: #2196f3;
+  color: white;
+  border: none;
+  border-radius: 6px;
+  font-size: 1rem;
+  cursor: pointer;
+}
+
+#add-btn:hover {
+  background: #1976d2;
+}
+
+.poll-option {
+  display: flex;
+  align-items: center;
+  background: white;
+  padding: 0.8rem 1rem;
+  border-radius: 8px;
+  margin-bottom: 0.5rem;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);
+}
+
+.option-name {
+  flex: 1;
+  font-size: 1rem;
+}
+
+.vote-count {
+  font-size: 0.9rem;
+  font-weight: 600;
+  color: #666;
+  margin-right: 0.75rem;
+  min-width: 1.5rem;
+  text-align: center;
+}
+
+.vote-btn {
+  padding: 0.4rem 1rem;
+  border: 2px solid #2196f3;
+  border-radius: 6px;
+  font-size: 0.85rem;
+  cursor: pointer;
+  background: white;
+  color: #2196f3;
+}
+
+.vote-btn:hover {
+  background: #e3f2fd;
+}
+
+.vote-btn.voted {
+  background: #2196f3;
+  color: white;
+}
+
+.vote-btn.voted:hover {
+  background: #1976d2;
+}
+
+#empty-state {
+  text-align: center;
+  color: #999;
+  padding: 2rem;
+}
+
+#empty-state.hidden {
+  display: none;
+}

styles.css

@@ -1,93 +0,0 @@
-body {
-    font-family: sans-serif;
-    max-width: 480px;
-    margin: 40px auto;
-    padding: 0 16px;
-}
-
-#add-option {
-    display: flex;
-    gap: 8px;
-    margin-bottom: 8px;
-}
-
-#option-input {
-    flex: 1;
-    padding: 8px;
-    font-size: 1rem;
-    border: 1px solid #ccc;
-    border-radius: 4px;
-}
-
-#duplicate-msg {
-    color: #c00;
-    font-size: 0.9rem;
-    margin-bottom: 12px;
-}
-
-button {
-    padding: 8px 16px;
-    font-size: 1rem;
-    cursor: pointer;
-    border: 1px solid #ccc;
-    border-radius: 4px;
-    background: #fff;
-}
-
-button:hover:not(:disabled) {
-    background: #f0f0f0;
-}
-
-button:disabled {
-    opacity: 0.5;
-    cursor: default;
-}
-
-#timer-section {
-    display: flex;
-    align-items: center;
-    gap: 12px;
-    margin-bottom: 16px;
-}
-
-.timer.active {
-    font-weight: bold;
-    color: #1a6e1a;
-}
-
-.timer.closed {
-    font-weight: bold;
-    color: #c00;
-}
-
-.option-item {
-    display: flex;
-    align-items: center;
-    justify-content: space-between;
-    padding: 10px 12px;
-    border: 1px solid #ddd;
-    border-radius: 4px;
-    margin-bottom: 8px;
-}
-
-.option-label {
-    flex: 1;
-}
-
-.vote-btn {
-    padding: 4px 12px;
-    font-size: 0.9rem;
-    white-space: nowrap;
-}
-
-.vote-btn.voted {
-    background: #e6f4e6;
-    border-color: #4a9e4a;
-    color: #2a6e2a;
-}
-
-
-#copy-btn {
-    margin-top: 16px;
-    width: 100%;
-}

vite.config.js

@@ -1,7 +0,0 @@
-import { defineConfig } from 'vite'
-import wasm from 'vite-plugin-wasm'
-import topLevelAwait from 'vite-plugin-top-level-await'
-
-export default defineConfig({
-  plugins: [wasm(), topLevelAwait()]
-})