1. Open sheets.google.com and make a new blank sheet. Name it (e.g. "Sample Class 1 Points").
   ⚠️ Every teacher needs their own sheet. Do not paste another teacher's link here — your scans, scores, and backups would mix together and overwrite each other. Each teacher creates one sheet and gets their own link.
2. In that sheet's menu: Extensions → Apps Script.
3. At the top-left, click Untitled project and rename it (e.g. "Sample Class 1 Points") so the permission screen later looks familiar, not anonymous.
4. Delete any code in the editor and paste in Code 1 below.
5. Click the gear (Project Settings) on the left and tick "Show appsscript.json manifest file in editor."
6. Back in the editor (<> Editor), open the file named appsscript.json, delete what's there, and paste in Code 2. This limits the app to this one sheet only.
7. Click Deploy → New deployment. Type: Web app. Set Execute as: Me and Who has access: Anyone. Click Deploy.
8. Google will warn the app "isn't verified" — that's normal for your own script. Click Advanced → Go to … (unsafe) → Allow. (It runs as you, on your sheet only.)
9. Copy the Web app URL it gives you (ends in /exec), paste it in the box above, and click Save link.

Tip: to test by hand, pick testSetup in the function dropdown and click Run — that authorizes the script and drops one test row in your Log. Don't click Run on doPost; it only works from a real web request and will show a "postData" error otherwise.

Already set up? Two steps, not one:

1. Re-copy this updated Code 1 and paste it over your existing Code.gs (replacing it entirely), then save (Ctrl/Cmd+S).
2. Redeploy it — pasting new code alone does not update your live sync link. In Apps Script: Deploy → Manage deployments, click the ✏️ pencil icon next to your existing deployment, set Version to New version, then click Deploy. (Do not click "New deployment" — that would give you a different link and break your existing sync URL in this app.)

function doGet(e) {
  if (e && e.parameter && e.parameter.action === "roster") {
    var ss = SpreadsheetApp.getActiveSpreadsheet();
    var sh = ss.getSheetByName("Roster");
    if (!sh) {
      var all = ss.getSheets();
      for (var i = 0; i < all.length; i++) {
        var nm = all[i].getName().toLowerCase().replace(/\s+/g, "");
        if (nm === "roster" || nm === "roaster" || nm === "classlist" ||
            nm === "classes" || nm === "students" || nm === "kids") { sh = all[i]; break; }
      }
    }
    var out = [];
    if (sh && sh.getLastRow() > 1) {
      var rows = sh.getRange(2, 1, sh.getLastRow() - 1, 3).getValues();
      rows.forEach(function (r) {
        var name = (r[0] || "").toString().trim();
        var cls = (r[1] || "").toString().trim();
        var photo = (r[2] || "").toString().trim();
        if (name) out.push({ name: name, cls: cls, photo: photo });
      });
    }
    return ContentService.createTextOutput(JSON.stringify(out))
      .setMimeType(ContentService.MimeType.JSON);
  }

  // --- Snapshot pull (Phase 1) ---
  if (e && e.parameter && e.parameter.action === "snapshot") {
    var ss = SpreadsheetApp.getActiveSpreadsheet();
    var sh = ss.getSheetByName("Snapshot");
    if (!sh || sh.getLastRow() < 2) {
      return ContentService.createTextOutput(JSON.stringify({ ok: false, error: "No snapshots found." }))
        .setMimeType(ContentService.MimeType.JSON);
    }
    // Optional: pull snapshot for a specific device
    var deviceId = (e.parameter.deviceId || "").trim();
    var lastRow = sh.getLastRow();
    var lastCol = sh.getLastColumn();
    // Walk backward from the bottom to find the newest matching row
    for (var r = lastRow; r >= 2; r--) {
      var row = sh.getRange(r, 1, 1, lastCol).getValues()[0];
      var rowDevice = (row[1] || "").toString().trim();
      if (deviceId && rowDevice !== deviceId) continue;
      // Reassemble JSON from chunks (columns C onward)
      var chunks = [];
      for (var c = 2; c < row.length; c++) {
        var chunk = (row[c] || "").toString();
        if (chunk) chunks.push(chunk);
      }
      if (!chunks.length) continue;
      var json = chunks.join("");
      return ContentService.createTextOutput(JSON.stringify({ ok: true, deviceId: rowDevice, snapshot: json }))
        .setMimeType(ContentService.MimeType.JSON);
    }
    return ContentService.createTextOutput(JSON.stringify({ ok: false, error: "No snapshot found" + (deviceId ? " for device " + deviceId : "") + "." }))
      .setMimeType(ContentService.MimeType.JSON);
  }

  return ContentService.createTextOutput("Points sync is live.");
}

// Log columns are: Time, Student, Class/Group, Activity, Points, New total, ID,
// Undo Of, Note. Note is appended at the very end deliberately — sheets that
// were created before this column existed keep their original 8-column
// header untouched; new rows simply carry a 9th value. Add a "Note" label to
// I1 by hand on an older sheet if you'd like the column header to show it.
// The ID column is how duplicate scans get caught — if the app sends the same
// scan twice (a flaky connection, a manual resync), the second one is skipped.
function logHasId(log, id) {
  if (!id) return false;
  var last = log.getLastRow();
  if (last < 2) return false;
  var ids = log.getRange(2, 7, last - 1, 1).getValues();
  for (var i = 0; i < ids.length; i++) { if (ids[i][0] === id) return true; }
  return false;
}

// Sort helper for rebuildLeaderBoard — "First Last" becomes "Last, First"
// so ties on points sort alphabetically by last name, same as the app.
function lastFirstKey(name) {
  var parts = (name || "").toString().trim().split(/\s+/);
  if (parts.length < 2) return name || "";
  return parts[parts.length - 1] + ", " + parts.slice(0, -1).join(" ");
}

// Recomputes a "Leader Board" tab straight from the Log, so standings are
// always current without anyone having to click "Send standings now."
function rebuildLeaderBoard() {
  var ss = SpreadsheetApp.getActiveSpreadsheet();
  var log = ss.getSheetByName("Log");
  if (!log || log.getLastRow() < 2) return;
  var rows = log.getRange(2, 1, log.getLastRow() - 1, 6).getValues();
  var totals = {};
  rows.forEach(function (r) {
    var name = r[1];
    if (!name) return;
    totals[name] = { group: r[2], total: r[5] }; // last row per student wins — rows are in time order
  });
  var list = Object.keys(totals).map(function (name) {
    return { name: name, group: totals[name].group, total: totals[name].total };
  });
  list.sort(function (a, b) { return b.total - a.total || lastFirstKey(a.name).localeCompare(lastFirstKey(b.name)); });
  var lb = ss.getSheetByName("Leader Board") || ss.insertSheet("Leader Board");
  lb.clear();
  lb.appendRow(["Rank", "Student", "Class/Group", "Points"]);
  list.forEach(function (it, i) { lb.appendRow([i + 1, it.name, it.group, it.total]); });
  lb.setFrozenRows(1);
}

// ---- Snapshot helpers (Phase 1) ----

// Google Sheets cells have a ~50,000 character limit. We chunk the JSON
// across columns C, D, E… so even large data objects (with big logs or
// photo data-URLs) are stored safely.
var SNAPSHOT_CHUNK_SIZE = 45000;
var SNAPSHOT_MAX_PER_DEVICE = 5;

function saveSnapshot(ss, deviceId, jsonString) {
  var sh = ss.getSheetByName("Snapshot") || ss.insertSheet("Snapshot");
  if (sh.getLastRow() === 0) {
    sh.appendRow(["Time", "Device ID", "Data →"]);
    sh.setFrozenRows(1);
  }
  // Build row: [timestamp, deviceId, chunk1, chunk2, …]
  var row = [new Date(), deviceId];
  for (var i = 0; i < jsonString.length; i += SNAPSHOT_CHUNK_SIZE) {
    row.push(jsonString.substring(i, i + SNAPSHOT_CHUNK_SIZE));
  }
  sh.appendRow(row);

  // Trim old snapshots for this device — keep only the newest N
  trimSnapshots(sh, deviceId);
}

function trimSnapshots(sh, deviceId) {
  var lastRow = sh.getLastRow();
  if (lastRow < 2) return;
  var deviceCol = sh.getRange(2, 2, lastRow - 1, 1).getValues();
  var matchingRows = [];
  for (var i = 0; i < deviceCol.length; i++) {
    if ((deviceCol[i][0] || "").toString().trim() === deviceId) {
      matchingRows.push(i + 2); // 1-indexed sheet row
    }
  }
  // If this device has more than SNAPSHOT_MAX_PER_DEVICE snapshots, delete oldest
  if (matchingRows.length > SNAPSHOT_MAX_PER_DEVICE) {
    var toDelete = matchingRows.slice(0, matchingRows.length - SNAPSHOT_MAX_PER_DEVICE);
    // Delete from bottom up so row numbers don't shift
    for (var j = toDelete.length - 1; j >= 0; j--) {
      sh.deleteRow(toDelete[j]);
    }
  }
}

// Returns a log sheet, creating it and writing its header EXACTLY ONCE.
//
// The header used to be written with a bare check-then-act:
//   if (sh.getLastRow() === 0) sh.appendRow(header);
// One "Send Attendance" fires one request per student — twenty-odd at once —
// and Apps Script runs those concurrently. Two executions that both arrive
// before either has appended BOTH see an empty sheet, so both write a header.
// That is the doubled header. It is the ONLY thing this race produced: the
// data rows are one per request either way, which is why the header was the
// one symptom that survived a clean-sheet test.
//
// The lock closes the window. flush() is not optional — it forces the header
// to be visible to the next execution before the lock is released; without it
// the append can still be pending and the next execution reads 0 again.
function logSheet_(ss, name, header) {
  var lock = LockService.getScriptLock();
  var held = false;
  try { held = lock.tryLock(30000); } catch (err) {}
  try {
    var sh = ss.getSheetByName(name) || ss.insertSheet(name);
    if (sh.getLastRow() === 0) {
      sh.appendRow(header);
      SpreadsheetApp.flush();
    }
    return sh;
  } finally {
    if (held) { try { lock.releaseLock(); } catch (err) {} }
  }
}

function doPost(e) {
  if (!e || !e.postData) {
    return ContentService.createTextOutput(
      "No data received. This runs from the Points app. To test by hand, run testSetup() instead."
    );
  }

  var ss = SpreadsheetApp.getActiveSpreadsheet();
  var body = JSON.parse(e.postData.contents);

  // --- Snapshot save (Phase 1) ---
  if (body.type === "snapshot") {
    var deviceId = (body.deviceId || "unknown").toString().trim();
    var snapshot = body.snapshot || "{}";
    // snapshot is the full JSON string of the app's data object
    saveSnapshot(ss, deviceId, snapshot);
    return ContentService.createTextOutput("ok");
  }

  if (body.type === "scan" || body.type === "correction") {
    var log = logSheet_(ss, "Log", ["Time", "Student", "Class/Group", "Activity", "Points", "New total", "ID", "Undo Of", "Note"]);
    if (!logHasId(log, body.id)) {
      log.appendRow([new Date(body.ts), body.name, body.group, body.label, body.delta, body.total, body.id || "", body.undoOf || "", body.note || ""]);
      rebuildLeaderBoard();
    }
  }

  // A rebbi tagged an existing entry with a note (e.g. "talked to Dovid")
  // after the fact, from the app's History tab. Finds that scan's row by its
  // ID (column G) and fills in column I (Note) — added at the END of the row
  // so older, already-populated sheets are never shifted or reflowed.
  if (body.type === "note") {
    var nlog = ss.getSheetByName("Log");
    if (nlog && body.id) {
      var nlast = nlog.getLastRow();
      if (nlast >= 2) {
        var nids = nlog.getRange(2, 7, nlast - 1, 1).getValues(); // column G = ID
        for (var ni = 0; ni < nids.length; ni++) {
          if (nids[ni][0] === body.id) {
            nlog.getRange(ni + 2, 9).setValue(body.note || ""); // column I = Note
            break;
          }
        }
      }
    }
  }

  if (body.type === "standings") {
    var st = ss.getSheetByName("Standings") || ss.insertSheet("Standings");
    st.clear();
    st.appendRow(["Rank", "Student", "Class/Group", "Points"]);
    (body.rows || []).forEach(function (r) { st.appendRow(r); });
  }

  if (body.type === "pasuk") {
    var pl = logSheet_(ss, "Pesukim Log", ["Time", "Student", "Class/Group", "Pasuk"]);
    pl.appendRow([new Date(body.ts), body.name, body.group, body.ref + ":" + body.pasuk]);
  }

  if (body.type === "pasukgrid") {
    var pc = ss.getSheetByName("Pesukim Chart") || ss.insertSheet("Pesukim Chart");
    pc.clear();
    var header = ["Student", "Class/Group"];
    for (var v = body.from; v <= body.to; v++) { header.push(body.ref + ":" + v); }
    header.push("Done");
    pc.appendRow(header);
    (body.rows || []).forEach(function (r) { pc.appendRow(r); });
  }

  if (body.type === "totals") {
    var st = ss.getSheetByName("Student Totals") || ss.insertSheet("Student Totals");
    st.clear();
    st.appendRow(["Updated", new Date()]);
    st.appendRow(body.header || []);
    (body.rows || []).forEach(function (r) { st.appendRow(r); });
    st.setFrozenRows(2);
  }

  // Attendance. Takes a BATCH — {rows:[{ts,date,name,group,status}, ...]} — and
  // writes the whole class in ONE locked operation.
  //
  // Why: the app used to send one request per student. Apps Script runs those
  // concurrently, each execution called getLastRow() to decide where to append,
  // and several read the same row number before any had written — so they
  // appended over each other. A class of 20 landed 7 rows with wrong names.
  // logSheet_'s lock only ever guarded the HEADER write; the appends were
  // unprotected. Taking the lock around the whole append is the fix, and
  // batching is what makes one lock enough.
  //
  // BOTH SHAPES ARE ACCEPTED, and this is not only for the transition. Any
  // rebbi who has not redeployed is still sending one-at-a-time, and a script
  // that understood only the new shape would silently drop his attendance
  // entirely. The single-student auto-push that fires when a status changes on
  // the Attendance tab also still uses the old shape by design — it is one row
  // by nature. Do not remove this branch.
  if (body.type === "attendance") {
    var attRows = Array.isArray(body.rows)
      ? body.rows
      : [{ ts: body.ts, date: body.date, name: body.name, group: body.group, status: body.status }];
    var attLock = LockService.getScriptLock();
    var attHeld = false;
    try { attHeld = attLock.tryLock(30000); } catch (err) {}
    try {
      var att = logSheet_(ss, "Attendance Log", ["Time", "Date", "Student", "Class/Group", "Status"]);
      // setValues() in one call rather than appendRow() per row: one write, one
      // getLastRow() read, and nothing else can interleave between them.
      var attOut = [];
      for (var ai = 0; ai < attRows.length; ai++) {
        var ar = attRows[ai] || {};
        // SKIP EMPTY ROWS. A send with nothing to send used to POST anyway with
        // no body.rows at all, so the single-row fallback above built
        // [new Date(undefined), undefined, undefined, undefined, undefined] and
        // wrote a garbage row dated 1969 (new Date(undefined) is Invalid Date,
        // which lands at the epoch once the Sheet coerces it).
        // The app no longer POSTs an empty diff, but the guard belongs here too:
        // this script has to keep serving older app versions that still do, and
        // an empty row is never something anyone meant to record.
        if (!ar.name && !ar.status) continue;
        attOut.push([new Date(ar.ts), ar.date, ar.name, ar.group, ar.status]);
      }
      if (attOut.length) {
        att.getRange(att.getLastRow() + 1, 1, attOut.length, 5).setValues(attOut);
        SpreadsheetApp.flush();
      }
    } finally {
      if (attHeld) { try { attLock.releaseLock(); } catch (err) {} }
    }
  }

  if (body.type === "tracker") {
    var trk = logSheet_(ss, "Tracker Log", ["Time", "Student", "Class/Group", "Activity"]);
    trk.appendRow([new Date(body.ts), body.name, body.group, body.activity]);
  }

  if (body.type === "hw") {
    var hwl = logSheet_(ss, "Homework Log", ["Time", "Date", "Student", "Class/Group", "Checked"]);
    hwl.appendRow([new Date(body.ts), body.date, body.name, body.group, body.checked ? "Yes" : "No"]);
  }

  return ContentService.createTextOutput("ok");
}

// Run THIS one by hand (pick it in the function dropdown, click Run) to
// authorize the script and confirm it works. It writes one test row you
// can delete afterward. Do not click Run on doPost — it needs a web request.
function testSetup() {
  var ss = SpreadsheetApp.getActiveSpreadsheet();
  var log = ss.getSheetByName("Log") || ss.insertSheet("Log");
  if (log.getLastRow() === 0) {
    log.appendRow(["Time", "Student", "Class/Group", "Activity", "Points", "New total", "ID", "Undo Of", "Note"]);
  }
  log.appendRow([new Date(), "Test student", "Gimel 1", "Setup test", 0, 0, "test-" + Date.now(), "", ""]);
  rebuildLeaderBoard();
}

// Run THIS once to create the "Roster" tab with Name / Class headers and a
// few example rows. Then fill it in with your students and their classes, and
// tap "Import roster from sheet" on the Students tab in the app.
function setupRoster() {
  var ss = SpreadsheetApp.getActiveSpreadsheet();
  var sh = ss.getSheetByName("Roster") || ss.insertSheet("Roster");
  if (sh.getLastRow() === 0) {
    sh.appendRow(["Name", "Class"]);
    sh.appendRow(["Yaakov Cohen", "Math 5A"]);
    sh.appendRow(["Dovid Levi", "Math 5A"]);
    sh.appendRow(["Moshe Stern", "Math 6B"]);
  }
}

{
  "timeZone": "America/New_York",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/spreadsheets.currentonly"
  ]
}

With Code 2 in place, the permission screen will say it only wants the spreadsheet "this application is installed in" — meaning your points sheet, nothing else in your Drive.

If you ever change the code, you must re-deploy for it to take effect: Deploy → Manage deployments → ✏️ Edit → Version: New version → Deploy. The URL stays the same.

Already set up from before? The Pesukim chart needs the newest Code 1 above. Re-paste it, then re-deploy: Deploy → Manage deployments → ✏️ Edit → Version: New version → Deploy. Your link stays the same.

Updating from an older setup: the newest Code 1 adds an ID and Undo Of column at the end of the Log tab (used to stop the same scan being recorded twice) and a new Leader Board tab that recalculates itself from the Log automatically. Existing rows in Log are untouched; new columns just start filling in going forward. Re-paste and re-deploy as above.

Heads up: the page sends data without waiting for a reply, so a wrong link won't show an error here. After saving, do one scan and check that a row appears in your sheet's Log tab — if it does, you're set.