This repository was archived by the owner on Oct 12, 2026. It is now read-only.
Repository navigation
feat(measurement): add Website Correction conversion signal #11
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,108 @@ | ||
| # Public conversion signal contract (The Website Correction application route) | ||
|
|
||
| Scope: read-only measurement of which public page pointed a visitor to The | ||
| Website Correction application route. This layer does not deploy, send, or | ||
| collect anything. It does not change pricing or legal copy, does not touch | ||
| auth, payments, or leads, and does not depend on PR #10's public copy. | ||
|
|
||
| ## Signal source | ||
|
|
||
| A Website Correction CTA is any public link that routes to the application | ||
| route (the contact page application section or the application email route) | ||
| or carries a `data-measure-source` marker. Every such CTA must carry an | ||
| explicit stable source tag naming its placement. | ||
|
|
||
| Canonical stable source names: | ||
|
|
||
| | Name | Placement | State in this checkout | | ||
| | --- | --- | --- | | ||
| | `homepage-hero` | Website Correction CTA in the homepage hero rail | Defined; no live CTA (PR #10 copy not merged) | | ||
| | `homepage-service` | Website Correction CTA in the homepage managed-service section | Defined; no live CTA (PR #10 copy not merged) | | ||
|
Comment on lines
+19
to
+20
There was a problem hiding this comment.
This checkout adds active Useful? React with 👍 / 👎. |
||
| | `homepage-footer` | Website Correction CTA in the homepage footer | Defined; no live CTA | | ||
|
|
||
| Names are used only when they correspond to a real Website Correction CTA; | ||
| a name with no live CTA is dormant, not attached to unrelated links. In this | ||
| checkout the homepage has no Website Correction CTA: the "Ask about 0509" and | ||
| footer "0509" links are product CTAs (0509 is a product, not The Website | ||
| Correction) and must never carry a Website Correction source name. Any new | ||
| placement needs a new registered name, added here, to the allowlist in | ||
| `public/contact/index.html`, and to `scripts/test-public-conversion-signal.mjs`. | ||
|
|
||
| ## Offer naming | ||
|
|
||
| The application route names the offer exactly as the public copy does: | ||
| The Website Correction. It is never presented as a generic "reviewed | ||
| service"; the human-reviewed nature of the offer is described in words | ||
| ("reviewed by a human"), not used as a substitute offer name. The application | ||
|
Comment on lines
+33
to
+36
There was a problem hiding this comment. 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win Remove the validator-forbidden phrase. Line 34 contains Reword the negative policy without that exact phrase. 🤖 Prompt for AI Agents |
||
| subject line is the operator-visible measurement signal: it names The | ||
| Website Correction and, when a marker is present, the source tag, so the | ||
| operator reads the signal directly in the received application email. The | ||
| default subject is exactly `The Website Correction application`; with a | ||
| marker present it becomes `The Website Correction application — from <name> | ||
| (internal measurement marker)`. | ||
|
|
||
| ## Marker mechanics | ||
|
|
||
| - CTA side: `data-measure-source="<name>"` on the anchor, routing to | ||
| `/contact/?source=<name>` or to the application mailto route with the | ||
| source name visible in the subject line. | ||
| - Endpoint side: `public/contact/index.html` reads the `?source=` parameter, | ||
| accepts only registered names, and prefills the application email subject | ||
| as `The Website Correction application — from <name> (internal measurement | ||
| marker)`. The prefilled subject is the human-readable, manual measurement | ||
| signal; it is visible in the email client before sending, and the visitor | ||
| can edit or remove it. | ||
| - Nothing auto-sends or auto-submits: the route is a plain `mailto:` link the | ||
| visitor opens and sends themselves. There is no form, no hidden field, no | ||
| script-triggered navigation. | ||
|
|
||
| ## Owner | ||
|
|
||
| The Tiny Studio operator (the repo operator) owns this signal contract and is | ||
| the only reader of the measurement signal. Interpretation happens only during | ||
| manual review of received application emails; no automation reads, tallies, or | ||
| acts on the signal. | ||
|
|
||
| ## Retention | ||
|
|
||
| The static site stores nothing: this layer adds no cookie, no server log, no | ||
| client-side storage, and no third-party request. The only retention is what an | ||
| applicant voluntarily includes in the subject line of the email they send to | ||
| `support@tinystudio.in`; that email is governed by the studio inbox policy and | ||
| is not processed automatically. | ||
|
|
||
| ## Privacy boundary | ||
|
|
||
| - No analytics provider, no cookies, no fingerprinting, no hidden fields, no | ||
| message-content collection. | ||
| - The marker is a first-party URL parameter and email subject prefill the | ||
| visitor can see, edit, or remove before sending. Removing it never blocks | ||
| the application. | ||
| - The disclosure about the marker sits on the contact page next to the | ||
| application route, where the visitor actually encounters the marker, and | ||
| states that it is for internal measurement only and that nothing is sent | ||
| until the visitor sends the email themselves. | ||
| - `public/privacy-choices/index.html` needs no change: this layer collects | ||
| nothing and offers no data choices, so there is nothing to opt out of there. | ||
| The privacy-choices page documents app-related data requests; this layer | ||
| does not create app data or choices, and the contact-page disclosure already | ||
| covers the only visitor-visible behavior this layer introduces. | ||
|
|
||
| ## Honesty | ||
|
|
||
| Static-site source tagging is not proof of completed applications; only received human messages count as completion evidence. | ||
| A tag being present or a link being opened proves nothing about completion. | ||
|
|
||
| ## Falsifiable decision rules | ||
|
|
||
| 1. The tag pipeline is falsified iff any Website Correction CTA exists on the | ||
| public homepage without a registered `data-measure-source` tag, or the | ||
| contact endpoint fails to propagate an accepted source into the visible | ||
| prefilled subject line. `scripts/test-public-conversion-signal.mjs` | ||
| enforces this rule deterministically and fails when it breaks. | ||
| 2. A completed application is counted only when a received human message | ||
| arrives in the studio inbox. If an application email arrives whose subject | ||
| carries no registered source name, the propagation rule is falsified and | ||
| the contact wiring must be re-verified before any conversion conclusion is | ||
| drawn. Under this rule, "no tagged clicks" and "no applications" are both | ||
| observable, and either direction can be disproven by a single counterexample. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,158 @@ | ||
| import { readFileSync, existsSync } from "node:fs" | ||
| import { fileURLToPath } from "node:url" | ||
| import { dirname, join } from "node:path" | ||
|
|
||
| const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..") | ||
| const read = (p) => readFileSync(join(ROOT, p), "utf8") | ||
|
|
||
| let failures = 0 | ||
| let checks = 0 | ||
| const ok = (cond, msg) => { | ||
| checks++ | ||
| if (cond) console.log(` ok ${msg}`) | ||
| else { | ||
| failures++ | ||
| console.error(` FAIL ${msg}`) | ||
| } | ||
| } | ||
|
|
||
| const OFFER_NAME = "The Website Correction" | ||
| const SIGNAL_REGISTRY = [ | ||
| { name: "homepage-hero", meaning: "Website Correction CTA in the homepage hero rail" }, | ||
| { name: "homepage-service", meaning: "Website Correction CTA in the homepage managed-service section" }, | ||
| { name: "homepage-footer", meaning: "Website Correction CTA in the homepage footer" } | ||
| ] | ||
| const REGISTRY_NAMES = SIGNAL_REGISTRY.map((s) => s.name) | ||
|
|
||
| const DOCS_PATH = "docs/measurement/public-conversion-signal.md" | ||
| const INDEX_HTML = "public/index.html" | ||
| const CONTACT_HTML = "public/contact/index.html" | ||
| const PRIVACY_CHOICES_HTML = "public/privacy-choices/index.html" | ||
|
|
||
| const forbidden = [ | ||
| "document.cookie", "localStorage", "sessionStorage", "navigator.sendBeacon", "sendBeacon(", | ||
| "fetch(", "XMLHttpRequest", | ||
| "googletagmanager", "google-analytics", "gtag(", "plausible.io", "fathom.js", | ||
| "posthog", "mixpanel", "amplitude", "window.analytics", "hotjar", "clarity.ms", "fbq(", | ||
| "connect.facebook.net", | ||
| "toDataURL", "hardwareConcurrency", "deviceMemory", "navigator.plugins", "FingerprintJS", | ||
| "window.fingerprint" | ||
| ] | ||
|
|
||
| const anchorsOf = (html) => [...html.matchAll(/<a\b[^>]*>/gi)].map((m) => m[0]) | ||
| const hrefOf = (a) => { | ||
| const m = a.match(/href\s*=\s*"([^"]*)"/i) | ||
| return m ? m[1] : "" | ||
| } | ||
| const decoded = (s) => s.replace(/%20/gi, " ").replace(/%3D/gi, "=").replace(/%26/gi, "&").toLowerCase() | ||
|
|
||
| const isWebsiteCorrectionCta = (a) => { | ||
| const href = decoded(hrefOf(a)) | ||
| return ( | ||
| /data-measure-source\s*=\s*"/i.test(a) || | ||
| (/^mailto:support@tinystudio\.in\?subject=/.test(href) && href.includes("website correction")) || | ||
| (href.includes("/contact/") && /[?&]source=/.test(href)) | ||
|
Comment on lines
+52
to
+54
There was a problem hiding this comment.
When the forthcoming homepage copy adds an untagged CTA such as Useful? React with 👍 / 👎. |
||
| ) | ||
| } | ||
|
|
||
| console.log("test-public-conversion-signal: public conversion signal (The Website Correction application route)") | ||
|
|
||
| console.log("A. signal definitions") | ||
| ok(REGISTRY_NAMES.length === new Set(REGISTRY_NAMES).size, "registry names are unique") | ||
| ok(REGISTRY_NAMES.every((n) => /^[a-z][a-z0-9-]*$/.test(n)), "registry names are stable lowercase slugs") | ||
|
|
||
| console.log("B. docs contract") | ||
| ok(existsSync(join(ROOT, DOCS_PATH)), `${DOCS_PATH} exists`) | ||
| if (existsSync(join(ROOT, DOCS_PATH))) { | ||
| const docs = read(DOCS_PATH) | ||
| for (const name of REGISTRY_NAMES) ok(docs.includes(name), `docs document signal source ${name}`) | ||
| ok(docs.includes(OFFER_NAME), "docs name the offer truthfully as The Website Correction") | ||
| ok(!docs.includes("reviewed service"), "docs never name the offer as a generic reviewed service") | ||
| ok(docs.includes("prefilled subject"), "docs state the prefilled application subject is the operator-visible signal") | ||
| ok(docs.includes("The Website Correction application — from"), "docs pin the operator-visible subject format with the exact product name") | ||
| ok(docs.includes("(internal measurement marker)"), "docs pin the full propagated subject format") | ||
| ok(/owner/i.test(docs), "docs name the signal owner") | ||
| ok(docs.includes("retention"), "docs state retention") | ||
| ok(/privacy boundary/i.test(docs), "docs state the privacy boundary") | ||
| ok(docs.includes("privacy-choices"), "docs explain where the privacy disclosure lives") | ||
| ok(/falsif/i.test(docs), "docs contain a falsifiable decision rule") | ||
| ok(docs.includes("not proof of completed applications"), "docs are honest that tags are not application proof") | ||
| ok(docs.includes("only received human messages count"), "docs count only received human messages as completion evidence") | ||
| } | ||
|
|
||
| console.log("C. homepage Website Correction CTA source tags") | ||
| const indexHtml = read(INDEX_HTML) | ||
| const ctaTags = anchorsOf(indexHtml).filter(isWebsiteCorrectionCta) | ||
| if (ctaTags.length === 0) { | ||
| console.log(" note: no Website Correction CTA present in this checkout (PR #10 public copy not merged); tag rule stays armed") | ||
| } | ||
| for (const a of ctaTags) { | ||
| const m = a.match(/data-measure-source\s*=\s*"([^"]*)"/i) | ||
| ok(m !== null, "every Website Correction CTA carries data-measure-source") | ||
| if (m) { | ||
| const name = m[1] | ||
| ok(REGISTRY_NAMES.includes(name), `source tag ${name} is a registered stable name`) | ||
| const href = decoded(hrefOf(a)) | ||
| const hasContext = | ||
| href.includes(`source=${name}`) || (href.startsWith("mailto:") && href.includes(name)) | ||
| ok(hasContext, `CTA ${name} routes to the application endpoint with source context`) | ||
| } | ||
| } | ||
|
|
||
| console.log("D. contact endpoint source propagation") | ||
| const contactHtml = read(CONTACT_HTML) | ||
| ok( | ||
| /href\s*=\s*"mailto:support@tinystudio\.in\?subject=[^"]*"/i.test(contactHtml), | ||
| "contact page has a Website Correction application mailto route" | ||
| ) | ||
| ok( | ||
| contactHtml.includes("?subject=The%20Website%20Correction%20application"), | ||
| "contact page default subject is exactly The Website Correction application" | ||
| ) | ||
| ok( | ||
| decoded(contactHtml).includes("website correction"), | ||
| "contact page application route names the offer as Website Correction" | ||
| ) | ||
| ok(contactHtml.includes(OFFER_NAME), "contact page names the offer truthfully as The Website Correction") | ||
| ok(!contactHtml.includes("reviewed service"), "contact page never names the offer as a generic reviewed service") | ||
| ok(contactHtml.includes("internal measurement"), "contact page states the signal is for internal measurement only") | ||
| ok(contactHtml.includes("nothing is sent"), "contact page states nothing is sent automatically") | ||
| ok(contactHtml.includes("remove the marker") || contactHtml.includes("remove it"), "contact page states the marker can be removed before sending") | ||
| ok(contactHtml.includes("URLSearchParams") && contactHtml.includes('get("source")'), "contact page reads the ?source= parameter") | ||
| ok( | ||
| REGISTRY_NAMES.every((n) => contactHtml.includes(n)), | ||
| "contact page allowlists every registered source name" | ||
| ) | ||
| ok( | ||
| contactHtml.includes('"The Website Correction application — from " + source + " (internal measurement marker)"'), | ||
| "contact page propagates the exact The Website Correction application — from <source> (internal measurement marker) subject" | ||
| ) | ||
| ok( | ||
| contactHtml.includes("indexOf(source)") || contactHtml.includes("includes(source)"), | ||
| "contact page rejects unregistered source values" | ||
| ) | ||
| for (const token of ["<form", "<input", "<textarea", "location.href", "location.assign", "location.replace", "window.open", ".submit(", "sendBeacon(", "fetch("]) { | ||
| ok(!contactHtml.includes(token), `contact page has no auto-send/auto-submit mechanism (${token})`) | ||
| } | ||
|
|
||
| console.log("E. no analytics provider, cookies, fingerprinting, or message-content collection") | ||
| for (const file of [INDEX_HTML, CONTACT_HTML, PRIVACY_CHOICES_HTML]) { | ||
| const html = read(file) | ||
| for (const token of forbidden) { | ||
| ok(!html.includes(token), `${file} has no ${token}`) | ||
| } | ||
| } | ||
|
|
||
| console.log("F. npm test/ci wiring") | ||
| const pkg = JSON.parse(read("package.json")) | ||
| ok( | ||
| pkg.scripts.test.includes("test-public-conversion-signal.mjs"), | ||
| "npm test runs the public conversion signal test" | ||
| ) | ||
| ok( | ||
| pkg.scripts.ci.includes("test-public-conversion-signal.mjs"), | ||
| "npm run ci runs the public conversion signal test" | ||
| ) | ||
|
|
||
| console.log(`\n${checks} checks, ${failures} failures`) | ||
| process.exit(failures === 0 ? 0 : 1) | ||
|
Comment on lines
+157
to
+158
There was a problem hiding this comment. 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win Make the stated 120-check result verifiable. With no homepage CTA, this script performs 116 checks. Each future homepage CTA adds three checks. The script does not assert an expected count, so it cannot validate the PR claim of a deterministic 120-check regression test. Either enforce the intended fixed count with a fixed fixture, or update the stated verification result to match the dynamic check model. 🤖 Prompt for AI Agents |
||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
Define the direct application link as an exception.
Lines 10-13 require every application-endpoint link to carry
data-measure-source. However,public/contact/index.htmlline 98 is the direct application link and intentionally has no marker. This makes the contract false for the current flow.Define source CTAs as inbound placement links, or explicitly exempt the contact-page application link.
🤖 Prompt for AI Agents