From 9e12ce2272c6b5a646b290b796cfa3317b85b142 Mon Sep 17 00:00:00 2001
From: "prompt.ac/@jeffrey" <mail@aesthetic.computer>
Date: Wed, 7 Oct 2026 12:37:07 -0700
Subject: [PATCH] Track Whistlegraph app referrals and access-link visits

---
 lith/Caddyfile                                |  2 +-
 .../aesthetic.computer/lib/visit-model.mjs    | 19 +++++
 .../aesthetic.computer/lib/visit-tracker.mjs  | 15 +++-
 system/public/whistlegraph.app/index.html     |  1 +
 system/public/whistlegraph.org/index.html     |  2 +-
 system/tests/visit-tracking-browser.test.mjs  | 78 +++++++++++++++++++
 system/tests/visit-tracking.test.mjs          | 18 ++++-
 toolchain/analytics/VISITS.md                 | 27 +++++++
 toolchain/analytics/whistlegraph-report.mjs   | 36 +++++++++
 9 files changed, 191 insertions(+), 7 deletions(-)
 create mode 100644 toolchain/analytics/whistlegraph-report.mjs

diff --git a/lith/Caddyfile b/lith/Caddyfile
index 0f98017f80..e2bb824823 100644
--- a/lith/Caddyfile
+++ b/lith/Caddyfile
@@ -1522,7 +1522,7 @@ whistlegraph.app {
     root * /opt/ac/system/public/whistlegraph.app
     header X-Content-Type-Options nosniff
     header Referrer-Policy strict-origin-when-cross-origin
-    header Content-Security-Policy "default-src 'none'; img-src 'self'; style-src 'self'; font-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
+    header Content-Security-Policy "default-src 'none'; script-src https://aesthetic.computer/aesthetic.computer/lib/; connect-src https://aesthetic.computer/api/visit-track; img-src 'self'; style-src 'self'; font-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
     header Cache-Control "no-cache"
     file_server
 }
diff --git a/system/public/aesthetic.computer/lib/visit-model.mjs b/system/public/aesthetic.computer/lib/visit-model.mjs
index 17e423b6e8..50ea720d14 100644
--- a/system/public/aesthetic.computer/lib/visit-model.mjs
+++ b/system/public/aesthetic.computer/lib/visit-model.mjs
@@ -9,6 +9,7 @@ export const VISIT_PROPERTIES = Object.freeze({
   "oskiewar.com": ["www.oskiewar.com", "midi.oskiewar.com"],
   "nopaint.art": ["www.nopaint.art"],
   "whistlegraph.org": ["www.whistlegraph.org", "tv.whistlegraph.org"],
+  "whistlegraph.app": ["www.whistlegraph.app"],
   "jas.life": ["www.jas.life", "rdp.jas.life"],
   "kidlisp.com": ["www.kidlisp.com", "learn.kidlisp.com", "keep.kidlisp.com", "buy.kidlisp.com", "pj.kidlisp.com", "top.kidlisp.com", "calm.kidlisp.com"],
   "notepat.com": ["www.notepat.com"],
@@ -39,7 +40,22 @@ export const VISIT_ACTIONS = Object.freeze([
   "mime_interact", "mime_scroll_feed", "mime_original_open",
   "note_played", "painting_edited", "recording_started",
   "painting_saved", "tape_saved",
+  "whistlegraph_app_clicked", "whistlegraph_access_clicked",
 ]);
+
+// Reviewed link milestones only; never retain destinations or mailto contents.
+export function visitLinkAction(hostname, href) {
+  let url;
+  try { url = new URL(href); } catch { return null; }
+  const property = visitProperty(hostname);
+  if (property === "whistlegraph.org" && url.protocol === "https:" &&
+      !url.port && !url.username && !url.password && visitProperty(url.hostname) === "whistlegraph.app")
+    return "whistlegraph_app_clicked";
+  if (property === "whistlegraph.app" && url.protocol === "mailto:" &&
+      url.pathname.toLowerCase() === "mail@aesthetic.computer")
+    return "whistlegraph_access_clicked";
+  return null;
+}
 export const VISIT_DEPTHS = Object.freeze([30, 60, 180, 600]);
 // Public upload milestones require a returned record code, never a click.
 export function visitMediaAction(extension, result) {
@@ -113,6 +129,7 @@ export function validateVisit(body, origin, userAgent = "") {
       !/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i.test(body.id || "") ||
       !SURFACES.includes(body.surface) || !ACTIVE_BUCKETS.includes(body.activeSeconds) ||
       typeof body.interacted !== "boolean" || typeof body.automated !== "boolean" ||
+      (body.linkVersion !== undefined && body.linkVersion !== 1) ||
       !Array.isArray(body.inputs) || body.inputs.length > INPUTS.length ||
       body.inputs.some(value => !INPUTS.includes(value)) ||
       !Array.isArray(body.actions) || body.actions.length > VISIT_ACTIONS.length ||
@@ -124,12 +141,14 @@ export function validateVisit(body, origin, userAgent = "") {
     automated: body.automated || automatedVisit({ userAgent }),
     inputs: [...new Set(body.inputs)], actions: [...new Set(body.actions)],
     referrerHost: typeof body.referrerHost === "string" ? visitReferrer(body.referrerHost) : null,
+    ...(body.linkVersion === 1 ? { linkVersion: 1 } : {}),
   };
 }
 
 export function visitUpdate(visit, now = new Date()) {
   const max = { activeSeconds: visit.activeSeconds, interacted: visit.interacted,
     automated: visit.automated, engaged: visit.interacted && visit.activeSeconds >= 10 };
+  if (visit.linkVersion === 1) max.linkVersion = 1;
   for (const input of visit.inputs) max[`inputs.${input}`] = true;
   for (const action of visit.actions) max[`actions.${action}`] = true;
   return {
diff --git a/system/public/aesthetic.computer/lib/visit-tracker.mjs b/system/public/aesthetic.computer/lib/visit-tracker.mjs
index 314a0dba90..8c4845a7ad 100644
--- a/system/public/aesthetic.computer/lib/visit-tracker.mjs
+++ b/system/public/aesthetic.computer/lib/visit-tracker.mjs
@@ -1,4 +1,4 @@
-import { ACTIVE_BUCKETS, VISIT_ACTIONS, automatedVisit, visitProperty, visitSurface, visitReferrer } from "./visit-model.mjs";
+import { ACTIVE_BUCKETS, VISIT_ACTIONS, automatedVisit, visitProperty, visitSurface, visitReferrer, visitLinkAction } from "./visit-model.mjs?v=20261007-whistlegraph";
 
 const ENDPOINT = "https://aesthetic.computer/api/visit-track";
 
@@ -22,8 +22,10 @@ export function startVisitTracker(win = window, doc = document) {
   const reset = () => {
     path = win.location.pathname;
     const surface = visitSurface(path);
+    const linkMeasured = ["whistlegraph.org", "whistlegraph.app"].includes(visitProperty(win.location.hostname)) &&
+      [...doc.querySelectorAll("a[href]")].some(link => visitLinkAction(win.location.hostname, link.href));
     state = surface === null ? null : {
-      version: 1, id: win.crypto.randomUUID(), surface,
+      version: 1, ...(linkMeasured ? { linkVersion: 1 } : {}), id: win.crypto.randomUUID(), surface,
       automated: automatedVisit(nav, win.location.search, win.acAutomation === true),
       interacted: false, activeSeconds: 0, inputs: [], actions: [],
       referrerHost: visitReferrer(doc.referrer),
@@ -108,17 +110,22 @@ export function startVisitTracker(win = window, doc = document) {
       }
     }, true);
   }
-  on(win, "click", e => {
+  const followLink = e => {
     if (!e.isTrusted || e.target?.closest?.("[data-ac-no-track]")) return;
+    if (e.type === "auxclick" && e.button !== 1) return;
     const link = e.target?.closest?.("a[href]");
     if (!link) return;
     interact(e.detail === 0 ? "keyboard" : "pointer");
     let url;
     try { url = new URL(link.href, win.location.href); } catch { return; }
+    const milestone = visitLinkAction(win.location.hostname, url.href);
+    if (milestone) action(milestone);
     if (!/^https?:$/.test(url.protocol)) return;
     action(link.hasAttribute("download") || /\.(?:dmg|zip|pdf|amxd|exe|apk)$/i.test(url.pathname)
       ? "download_clicked" : "link_followed");
-  }, true);
+  };
+  on(win, "click", followLink, true);
+  on(win, "auxclick", followLink, true);
   on(doc, "playing", e => {
     if (["AUDIO", "VIDEO"].includes(e.target?.tagName)) action("media_started");
   }, true);
diff --git a/system/public/whistlegraph.app/index.html b/system/public/whistlegraph.app/index.html
index 4108a1c413..f9cea40341 100644
--- a/system/public/whistlegraph.app/index.html
+++ b/system/public/whistlegraph.app/index.html
@@ -18,6 +18,7 @@
   <meta name="twitter:card" content="summary_large_image">
   <link rel="preload" href="/ComicRelief-Bold.ttf" as="font" type="font/ttf" crossorigin>
   <link rel="stylesheet" href="/style.css">
+  <script type="module" src="https://aesthetic.computer/aesthetic.computer/lib/visit-tracker.mjs?v=20261007-whistlegraph" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
 </head>
 <body>
   <main>
diff --git a/system/public/whistlegraph.org/index.html b/system/public/whistlegraph.org/index.html
index 297b9706ac..d1a8e5087a 100644
--- a/system/public/whistlegraph.org/index.html
+++ b/system/public/whistlegraph.org/index.html
@@ -317,7 +317,7 @@
     .sectionbar button, .sectionbar a.tab{padding:9px 13px 8px}
   }
 </style>
-<script type="module" src="https://aesthetic.computer/aesthetic.computer/lib/visit-tracker.mjs" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+<script type="module" src="https://aesthetic.computer/aesthetic.computer/lib/visit-tracker.mjs?v=20261007-whistlegraph" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
 </head>
 <body>
 <a class="bumper" href="https://whistlegraph.app/" data-i18n-html="bumper.app">Whistlegraph for iPhone — early access at <b>whistlegraph.app</b> →</a>
diff --git a/system/tests/visit-tracking-browser.test.mjs b/system/tests/visit-tracking-browser.test.mjs
index debc8611f1..fe3227e6e3 100644
--- a/system/tests/visit-tracking-browser.test.mjs
+++ b/system/tests/visit-tracking-browser.test.mjs
@@ -3,6 +3,84 @@ import assert from "node:assert/strict";
 import { readFile } from "node:fs/promises";
 import { chromium } from "playwright";
 
+test("Whistlegraph org-to-app link, referral and mail draft work under the deployed CSP", async () => {
+  const browser = await chromium.launch({ headless: true, channel: process.env.PLAYWRIGHT_CHANNEL });
+  try {
+    const context = await browser.newContext();
+    const received = [];
+    const orgHtml = await readFile(new URL("../public/whistlegraph.org/index.html", import.meta.url), "utf8");
+    const appHtml = await readFile(new URL("../public/whistlegraph.app/index.html", import.meta.url), "utf8");
+    const caddy = await readFile(new URL("../../lith/Caddyfile", import.meta.url), "utf8");
+    const csp = caddy.split("\nwhistlegraph.app {")[1].match(/header Content-Security-Policy "([^"]+)"/)[1];
+    const bumper = orgHtml.match(/<a class="bumper"[^>]*>[\s\S]*?<\/a>/)[0];
+    const tracker = orgHtml.match(/<script type="module" src="[^"]*visit-tracker[^>]*><\/script>/)[0];
+    await context.route("**/*", async route => {
+      const request = route.request(), url = new URL(request.url());
+      if (url.pathname === "/api/visit-track") {
+        received.push({ origin: request.headers().origin, ...JSON.parse(request.postData()) });
+        return route.fulfill({ status: 204, headers: { "Access-Control-Allow-Origin": "*" } });
+      }
+      if (/\/visit-(tracker|model)\.mjs$/.test(url.pathname)) {
+        return route.fulfill({ contentType: "text/javascript", body: await readFile(new URL(`../public/aesthetic.computer/lib/${url.pathname.split("/").at(-1)}`, import.meta.url), "utf8"), headers: { "Access-Control-Allow-Origin": "*" } });
+      }
+      if (url.hostname === "whistlegraph.app" && url.pathname === "/")
+        return route.fulfill({ contentType: "text/html", body: appHtml, headers: { "Content-Security-Policy": csp, "Referrer-Policy": "strict-origin-when-cross-origin" } });
+      if (url.hostname === "whistlegraph.org")
+        return route.fulfill({ contentType: "text/html", body: bumper + tracker + '<a id="unrelated" href="https://aesthetic.computer">AC</a>' });
+      return route.fulfill({ status: 200, body: "" });
+    });
+    const page = await context.newPage();
+    const violations = [];
+    await page.exposeFunction("recordCspViolation", value => violations.push(value));
+    await page.addInitScript(() => document.addEventListener("securitypolicyviolation", e => window.recordCspViolation(e.blockedURI)));
+    await page.goto("https://whistlegraph.org/");
+    await page.waitForFunction(() => !!window.acVisits);
+    await page.locator(".bumper").evaluate(link => link.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true })));
+    // A synthetic click may navigate, but must not be counted. Reload the source.
+    await page.goto("https://whistlegraph.org/");
+    await page.waitForFunction(() => !!window.acVisits);
+    assert.ok(!received.some(row => row.actions.includes("whistlegraph_app_clicked")));
+    await page.locator(".bumper").click();
+    await page.waitForURL("https://whistlegraph.app/");
+    await page.waitForFunction(() => !!window.acVisits);
+    await page.waitForTimeout(100);
+    assert.ok(received.some(row => row.origin === "https://whistlegraph.org" && row.linkVersion === 1 && row.actions.includes("whistlegraph_app_clicked")));
+    assert.ok(received.some(row => row.origin === "https://whistlegraph.app" && row.referrerHost === "whistlegraph.org" && row.linkVersion === 1));
+    // Keep the browser test from launching a mail application; activation stays trusted.
+    await page.evaluate(() => document.addEventListener("click", e => e.preventDefault()));
+    await page.locator("#get-app").click();
+    await page.waitForTimeout(100);
+    const requests = received.length;
+    await page.locator("#get-app").click();
+    await page.waitForTimeout(100);
+    assert.equal(received.length, requests, "repeat activation is once per visit");
+    assert.ok(received.some(row => row.origin === "https://whistlegraph.app" && row.actions.includes("whistlegraph_access_clicked")));
+    assert.ok(!JSON.stringify(received).includes("mailto:"));
+    assert.deepEqual(violations, [], "the app CSP permits the tracker and collector");
+    for (const input of ["keyboard", "middle"]) {
+      await page.goto("https://whistlegraph.org/");
+      await page.waitForFunction(() => !!window.acVisits);
+      await page.evaluate(() => {
+        document.addEventListener("click", e => e.preventDefault());
+        document.addEventListener("auxclick", e => e.preventDefault());
+      });
+      const before = received.filter(row => row.actions.includes("whistlegraph_app_clicked")).length;
+      await page.locator("#unrelated").click();
+      await page.locator(".bumper").click({ button: "right" });
+      await page.waitForTimeout(50);
+      assert.equal(received.filter(row => row.actions.includes("whistlegraph_app_clicked")).length, before);
+      if (input === "keyboard") {
+        await page.locator(".bumper").focus();
+        await page.keyboard.press("Enter");
+      } else await page.locator(".bumper").click({ button: "middle" });
+      await page.waitForTimeout(100);
+      assert.ok(received.filter(row => row.actions.includes("whistlegraph_app_clicked")).length > before, input);
+    }
+    assert.ok(received.every(row => row.automated), "browser QA stays classified as automation");
+    await context.close();
+  } finally { await browser.close(); }
+});
+
 test("browser funnel, automation, privacy opt-out, private SPA routes and duplicate installation", async () => {
   const browser = await chromium.launch({ headless: true, channel: process.env.PLAYWRIGHT_CHANNEL });
   try {
diff --git a/system/tests/visit-tracking.test.mjs b/system/tests/visit-tracking.test.mjs
index b4a1a1d903..9c107dc8ca 100644
--- a/system/tests/visit-tracking.test.mjs
+++ b/system/tests/visit-tracking.test.mjs
@@ -1,13 +1,29 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import { randomUUID } from "node:crypto";
-import { validateVisit, visitUpdate, visitProperty, visitSurface, automatedVisit, visitMediaAction, VISIT_ACTIONS } from "../public/aesthetic.computer/lib/visit-model.mjs";
+import { validateVisit, visitUpdate, visitProperty, visitSurface, automatedVisit, visitMediaAction, visitLinkAction, VISIT_ACTIONS } from "../public/aesthetic.computer/lib/visit-model.mjs";
 import { handler } from "../netlify/functions/visit-track.mjs";
 
 const snapshot = () => ({ version: 1, id: randomUUID(), surface: "home",
   activeSeconds: 10, interacted: true, automated: false,
   inputs: ["pointer"], actions: ["link_followed"] });
 
+test("Whistlegraph link milestones retain only reviewed actions and measurement coverage", () => {
+  assert.equal(visitProperty("www.whistlegraph.app"), "whistlegraph.app");
+  assert.equal(visitLinkAction("www.whistlegraph.org", "https://whistlegraph.app/"), "whistlegraph_app_clicked");
+  assert.equal(visitLinkAction("whistlegraph.app", "mailto:mail@aesthetic.computer?body=private"), "whistlegraph_access_clicked");
+  for (const href of ["https://whistlegraph.app.evil.test", "http://whistlegraph.app", "https://whistlegraph.app:1234", "https://secret@whistlegraph.app", "https://aesthetic.computer/", "invalid"])
+    assert.equal(visitLinkAction("whistlegraph.org", href), null);
+  assert.equal(visitLinkAction("jas.life", "https://whistlegraph.app"), null);
+  assert.equal(visitLinkAction("whistlegraph.app", "mailto:other@example.com"), null);
+  const visit = validateVisit({ ...snapshot(), linkVersion: 1, actions: ["whistlegraph_access_clicked"] }, "https://whistlegraph.app");
+  assert.equal(visitUpdate(visit).$max.linkVersion, 1);
+  assert.equal(visitUpdate(visit).$max["actions.whistlegraph_access_clicked"], true);
+  assert.equal(visitUpdate(validateVisit(snapshot(), "https://whistlegraph.org")).$max.linkVersion, undefined,
+    "old visits without link measurement must not enter a click-rate denominator");
+  assert.equal(validateVisit({ ...snapshot(), linkVersion: 2 }, "https://whistlegraph.app"), null);
+});
+
 test("creation milestones require a confirmed media record and carry no content", () => {
   for (const result of [null, {}, { slug: "upload-only" }, { code: "" }, { code: 123 }, { code: "abc", error: "failed" }])
     assert.equal(visitMediaAction("png", result), null);
diff --git a/toolchain/analytics/VISITS.md b/toolchain/analytics/VISITS.md
index e467104530..03535d4225 100644
--- a/toolchain/analytics/VISITS.md
+++ b/toolchain/analytics/VISITS.md
@@ -156,6 +156,33 @@ The tool reads existing data; it adds no browser identifiers or new retention.
 
 ## Coverage
 
+### Whistlegraph app referral route
+
+Whistlegraph.org → whistlegraph.app records `whistlegraph_app_clicked` on a
+trusted activation of an HTTPS app link (including keyboard and middle-click).
+Whistlegraph.app records `whistlegraph_access_clicked` when its reviewed mailto
+access link is activated. This means opening a mail draft, not sending email,
+joining a waitlist, installing the app, or paying. Both are boolean per visit.
+No destination, subject, message, or email identity is collected.
+
+The app uses the same visit collector, automation classification and privacy
+opt-outs as the studio sites. Referral hostnames show app arrivals from the org;
+the two sites' ephemeral visit IDs are never joined. `linkVersion: 1` marks
+visits whose page contains a reviewed link and loads the new measurement.
+Old visits and pages without those links are excluded from the click-rate
+denominator. Coverage starts with the October 7 deployment; no backfill.
+
+On Lith, from `/opt/ac/system`:
+
+```sh
+node --env-file=.env ../toolchain/analytics/whistlegraph-report.mjs --hours 24
+```
+
+The report separates automation, org click-through, app arrivals with an org
+referrer, and access-link clicks (including those within referred app visits).
+Privacy settings or browser link handling can omit referrers; these counts are
+not a cross-domain conversion funnel. All counts are grouped by visit start.
+
 ### Account activity and referrers
 
 `POST /api/account-activity` verifies a bearer token through the existing
diff --git a/toolchain/analytics/whistlegraph-report.mjs b/toolchain/analytics/whistlegraph-report.mjs
new file mode 100644
index 0000000000..2688806416
--- /dev/null
+++ b/toolchain/analytics/whistlegraph-report.mjs
@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// Read-only: run from /opt/ac/system with node --env-file=.env.
+import { connect, closePool } from "../../system/backend/database.mjs";
+
+const args = process.argv.slice(2);
+const value = name => args[args.indexOf(name) + 1];
+const hours = args.includes("--hours") ? Number(value("--hours")) : 24;
+const end = args.includes("--end") ? new Date(value("--end")) : new Date();
+if (!Number.isFinite(hours) || hours <= 0 || hours > 840 || !Number.isFinite(+end))
+  throw new Error("Use --hours 1..840 and optional --end ISO-date");
+const start = new Date(+end - hours * 3600000);
+const { db } = await connect();
+try {
+  const rows = await db.collection("network-visits").aggregate([
+    { $match: { property: { $in: ["whistlegraph.org", "whistlegraph.app"] },
+      startedAt: { $gte: start, $lt: end }, linkVersion: 1 } },
+    { $group: { _id: { property: "$property", automated: "$automated" },
+      visitsWithLink: { $sum: 1 }, firstMeasuredVisit: { $min: "$startedAt" },
+      appClickVisits: { $sum: { $cond: ["$actions.whistlegraph_app_clicked", 1, 0] } },
+      accessClickVisits: { $sum: { $cond: ["$actions.whistlegraph_access_clicked", 1, 0] } },
+      referredFromOrg: { $sum: { $cond: [{ $in: ["$referrerHost", ["whistlegraph.org", "tv.whistlegraph.org"]] }, 1, 0] } },
+      referredAccessClickVisits: { $sum: { $cond: [{ $and: [
+        { $in: ["$referrerHost", ["whistlegraph.org", "tv.whistlegraph.org"]] },
+        { $eq: ["$actions.whistlegraph_access_clicked", true] },
+      ] }, 1, 0] } },
+    } },
+  ], { maxTimeMS: 10000 }).toArray();
+  const org = rows.find(row => row._id.property === "whistlegraph.org" && !row._id.automated);
+  console.log(JSON.stringify({ start, end,
+    unit: "page visits with a reviewed link present and link tracking v1; not unique people",
+    note: "Older/unmeasured visits are excluded, not zero clicks. Clicks are once per visit. Referrer arrivals are a separate aggregate, not joined journeys. Access clicks open a mail draft; they do not prove sending or signup.",
+    orgClickThroughPercent: org?.visitsWithLink ? +(100 * org.appClickVisits / org.visitsWithLink).toFixed(2) : null,
+    audience: rows.filter(row => !row._id.automated),
+    automation: rows.filter(row => row._id.automated),
+  }, null, 2));
+} finally { await closePool(); }
-- 
2.51.2