From a8ceeba429fd3c0b5034245a16f7b923130deb6e Mon Sep 17 00:00:00 2001
From: George Hartley <georgehartley@gmail.com>
Date: Wed, 22 Jul 2026 16:08:23 +1000
Subject: [PATCH 1/2] feat(docs): community Q&A widget injected into every
 built page
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Post-build injector (the only repo-controlled every-page injection point —
Sourcey templates live in node_modules): inject-qa.js appends a marker-
idempotent, self-contained vanilla-JS widget before </body> on every dist
HTML file and fails loudly on a missing or empty dist. The widget reads
the normalized pathname as page_key (matrix mirrors the API: decode once,
lowercase, collapse slashes, strip trailing slash and .html, / ->
/introduction), fetches GET /v1/public/questions, renders in the docs
theme (.dark-aware), URL-encodes the Ask deep link into the app, and
removes only its own container on any fetch/render failure. Every
user/LLM-originated string is inserted via createTextNode only — no
innerHTML or attribute sinks (the DOM test's innerHTML setter throws).

verify-qa-injection.mjs gates the Vercel build: every generated HTML file
must carry exactly one marker (zero and 2+ both fail), with an explicit
allowlist for any future </body>-less files. inject-qa.test.mjs covers
the injector, the verifier, and the widget XSS/normalization contract
with node stdlib only.

MERGE NOTE (binding release order): deploy only after the api release is
verified live returning 200-empty on GET /v1/public/questions —
Cloudflare negative-caches 404s for a year.
---
 scripts/inject-qa.js            | 259 ++++++++++++++++++++++
 scripts/inject-qa.test.mjs      | 371 ++++++++++++++++++++++++++++++++
 scripts/verify-qa-injection.mjs |  91 ++++++++
 vercel.json                     |   2 +-
 4 files changed, 722 insertions(+), 1 deletion(-)
 create mode 100644 scripts/inject-qa.js
 create mode 100644 scripts/inject-qa.test.mjs
 create mode 100644 scripts/verify-qa-injection.mjs

diff --git a/scripts/inject-qa.js b/scripts/inject-qa.js
new file mode 100644
index 0000000..deb8dcf
--- /dev/null
+++ b/scripts/inject-qa.js
@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+/*
+ * inject-qa.js — appends the community Q&A widget to EVERY built docs page.
+ *
+ * MAINTENANCE NOTES
+ * -----------------
+ * Sourcey's page templates live in node_modules with no repo-controlled
+ * hook, so this post-build injector is the only every-page injection point
+ * we own. It runs from vercel.json's buildCommand:
+ *
+ *   npx sourcey build && node scripts/inject-qa.js && node scripts/verify-qa-injection.mjs
+ *
+ * Behaviour:
+ * - Idempotent: pages already carrying the MARKER are skipped, so a double
+ *   run never double-injects.
+ * - Inserts the snippet immediately before the LAST </body> in each file.
+ * - Fails loudly (non-zero exit) when dist/ is missing or holds no HTML —
+ *   a silent no-op here would ship docs without the widget.
+ * - If a Sourcey upgrade ever emits an HTML file without </body>, this
+ *   script warns per file and leaves it untouched; the build then FAILS in
+ *   verify-qa-injection.mjs unless that file is explicitly allowlisted
+ *   there. That is deliberate: injection coverage regressions must be loud.
+ *
+ * WIDGET INVARIANTS (binding, mirrored by inject-qa.test.mjs)
+ * - XSS: every user/LLM-originated string (question bodies, answer bodies,
+ *   first names) is inserted via document.createTextNode ONLY. No
+ *   innerHTML, no attribute sinks, no CSS interpolation for untrusted
+ *   values. The only dynamic attribute is the Ask link's href, built from
+ *   the page_key AFTER charset validation (^\/[a-z0-9\-\/]{0,120}$) and
+ *   URL-encoding — question/answer/user strings never reach attributes.
+ * - page_key normalization mirrors the API: decode percent-encoding once
+ *   (invalid encoding -> render nothing), lowercase, collapse repeated
+ *   slashes, strip trailing slash then a .html suffix, "/" or "" ->
+ *   "/introduction". Keys that still fail validation render nothing.
+ * - Fetch/render failure removes only the widget container (the style tag
+ *   lives inside the container, so removal is atomic). Docs pages never
+ *   break because the Q&A API is down.
+ * - Reading is public; asking always deep-links into the signed-in app.
+ * - Theme-aware via Sourcey's `.dark` class on <html> (CSS variants only).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const MARKER = 'data-nitro-qa="1"';
+
+// NOTE: WIDGET_SOURCE sits inside a JS template literal — keep the widget
+// code free of backticks and "${", and never include a literal
+// "</script>" sequence in its strings.
+const WIDGET_SOURCE = `(function (w, d) {
+  'use strict';
+
+  var API_BASE = 'https://api.nitrosend.com';
+  var ASK_BASE = 'https://app.nitrosend.com/learning/community/ask';
+  var PAGE_KEY_RE = /^\\/[a-z0-9\\-\\/]{0,120}$/;
+
+  var CSS = '' +
+    '.nitro-qa{max-width:48rem;margin:3rem auto 2rem;padding:1.5rem 1rem 0;border-top:1px solid #e7e5e4;font-size:.9375rem;line-height:1.6;color:#44403c}' +
+    '.dark .nitro-qa{border-top-color:#292524;color:#d6d3d1}' +
+    '.nitro-qa-title{font-size:1.125rem;font-weight:600;margin:0 0 1rem;color:#1c1917}' +
+    '.dark .nitro-qa-title{color:#fafaf9}' +
+    '.nitro-qa-item{margin:0 0 1.5rem}' +
+    '.nitro-qa-meta{font-size:.8125rem;color:#78716c;margin:0 0 .25rem}' +
+    '.dark .nitro-qa-meta{color:#a8a29e}' +
+    '.nitro-qa-q{font-weight:600;margin:0 0 .5rem;white-space:pre-wrap;color:#1c1917}' +
+    '.dark .nitro-qa-q{color:#fafaf9}' +
+    '.nitro-qa-answer{margin:0 0 .75rem;padding-left:1rem;border-left:2px solid #e7e5e4}' +
+    '.dark .nitro-qa-answer{border-left-color:#292524}' +
+    '.nitro-qa-answer-label{font-size:.8125rem;color:#78716c;margin:0 0 .25rem}' +
+    '.dark .nitro-qa-answer-label{color:#a8a29e}' +
+    '.nitro-qa-answer-body{margin:0;white-space:pre-wrap}' +
+    '.nitro-qa-unanswered{font-size:.8125rem;font-style:italic;color:#78716c;margin:0}' +
+    '.dark .nitro-qa-unanswered{color:#a8a29e}' +
+    '.nitro-qa-empty,.nitro-qa-foot{margin:.5rem 0 0}' +
+    '.nitro-qa-ask{color:#ea580c;text-decoration:none;font-weight:500}' +
+    '.nitro-qa-ask:hover{text-decoration:underline}';
+
+  function normalizePageKey(pathname) {
+    var key = String(pathname == null ? '' : pathname);
+    if (key === '') return null;
+    try {
+      key = decodeURIComponent(key);
+    } catch (e) {
+      return null;
+    }
+    key = key.toLowerCase();
+    key = key.replace(/\\/+/g, '/');
+    key = key.replace(/\\/$/, '');
+    key = key.replace(/\\.html$/, '');
+    if (key === '' || key === '/') key = '/introduction';
+    if (!PAGE_KEY_RE.test(key)) return null;
+    return key;
+  }
+
+  // The ONLY insertion helpers. Untrusted strings pass exclusively through
+  // createTextNode here — never innerHTML, never attributes.
+  function el(tag, cls, text) {
+    var node = d.createElement(tag);
+    if (cls) node.className = cls;
+    if (text !== undefined && text !== null) {
+      node.appendChild(d.createTextNode(String(text)));
+    }
+    return node;
+  }
+
+  function askLink(pageKey, label) {
+    var a = el('a', 'nitro-qa-ask', label);
+    // pageKey is charset-validated above and URL-encoded here; no other
+    // dynamic value ever reaches an attribute.
+    a.href = ASK_BASE + '?page_key=' + encodeURIComponent(pageKey);
+    return a;
+  }
+
+  function answerLabel(answer) {
+    if (answer.source === 'ai') {
+      return answer.verified_at
+        ? 'Answered by NitroLLM \\u00b7 verified by the team'
+        : 'Answered by NitroLLM \\u00b7 not yet verified';
+    }
+    var name = answer.author && answer.author.first_name ? answer.author.first_name : 'a community member';
+    return 'Answered by ' + name;
+  }
+
+  function renderAnswer(answer) {
+    var box = el('div', 'nitro-qa-answer');
+    box.appendChild(el('p', 'nitro-qa-answer-label', answerLabel(answer)));
+    box.appendChild(el('p', 'nitro-qa-answer-body', answer.body));
+    return box;
+  }
+
+  function renderQuestion(question) {
+    var item = el('div', 'nitro-qa-item');
+    var name = question.user && question.user.first_name ? question.user.first_name : 'Someone';
+    var when = '';
+    try {
+      when = new Date(question.created_at).toLocaleDateString();
+    } catch (e) {
+      when = '';
+    }
+    item.appendChild(el('p', 'nitro-qa-meta', name + (when ? ' \\u00b7 ' + when : '')));
+    item.appendChild(el('p', 'nitro-qa-q', question.body));
+    var answers = question.answers || [];
+    for (var i = 0; i < answers.length; i++) {
+      item.appendChild(renderAnswer(answers[i]));
+    }
+    if (!question.answered) {
+      item.appendChild(el('p', 'nitro-qa-unanswered', 'Not answered yet.'));
+    }
+    return item;
+  }
+
+  function render(container, pageKey, questions) {
+    container.appendChild(el('h2', 'nitro-qa-title', 'Community Q&A'));
+    if (!questions.length) {
+      var empty = el('p', 'nitro-qa-empty');
+      empty.appendChild(d.createTextNode('No questions about this page yet. '));
+      empty.appendChild(askLink(pageKey, 'Ask the first question'));
+      container.appendChild(empty);
+      return;
+    }
+    for (var i = 0; i < questions.length; i++) {
+      container.appendChild(renderQuestion(questions[i]));
+    }
+    var foot = el('p', 'nitro-qa-foot');
+    foot.appendChild(askLink(pageKey, 'Ask a question about this page'));
+    container.appendChild(foot);
+  }
+
+  function main() {
+    if (typeof w.fetch !== 'function') return Promise.resolve();
+    var pageKey = normalizePageKey(w.location && w.location.pathname);
+    if (!pageKey) return Promise.resolve();
+    var host = d.querySelector('main') || d.body;
+    if (!host) return Promise.resolve();
+
+    var container = el('section', 'nitro-qa');
+    var style = d.createElement('style');
+    style.appendChild(d.createTextNode(CSS));
+    container.appendChild(style);
+    host.appendChild(container);
+
+    return w.fetch(API_BASE + '/v1/public/questions?page_key=' + encodeURIComponent(pageKey))
+      .then(function (res) {
+        if (!res || !res.ok) throw new Error('questions request failed');
+        return res.json();
+      })
+      .then(function (payload) {
+        render(container, pageKey, (payload && payload.questions) || []);
+      })
+      .catch(function () {
+        // Never break a docs page over the widget: remove it wholesale.
+        if (container && typeof container.remove === 'function') container.remove();
+      });
+  }
+
+  var done = main();
+  if (typeof w.__nitroQaOnDone === 'function') w.__nitroQaOnDone(done);
+})(window, document);`;
+
+const SNIPPET = '\n<script ' + MARKER + '>\n' + WIDGET_SOURCE + '\n</' + 'script>\n';
+
+function collectHtmlFiles(dir) {
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...collectHtmlFiles(full));
+    } else if (entry.isFile() && entry.name.endsWith('.html')) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+function injectFile(file) {
+  const html = fs.readFileSync(file, 'utf8');
+  if (html.includes(MARKER)) return 'skipped';
+
+  const at = html.lastIndexOf('</body>');
+  if (at === -1) {
+    console.warn(`[inject-qa] WARNING: ${file} has no </body>; left untouched. ` +
+      'The verifier will fail unless this file is allowlisted in verify-qa-injection.mjs.');
+    return 'no_body';
+  }
+
+  const injected = html.slice(0, at) + SNIPPET + html.slice(at);
+  fs.writeFileSync(file, injected);
+  return 'injected';
+}
+
+function injectDir(distDir) {
+  if (!fs.existsSync(distDir) || !fs.statSync(distDir).isDirectory()) {
+    throw new Error(`[inject-qa] dist directory not found: ${distDir} — run the build first.`);
+  }
+  const files = collectHtmlFiles(distDir);
+  if (files.length === 0) {
+    throw new Error(`[inject-qa] no HTML files found in ${distDir} — refusing to no-op on an empty build.`);
+  }
+
+  const summary = { injected: 0, skipped: 0, no_body: 0, total: files.length };
+  for (const file of files) {
+    summary[injectFile(file)] += 1;
+  }
+  return summary;
+}
+
+if (require.main === module) {
+  const distDir = path.resolve(process.argv[2] || path.join(__dirname, '..', 'dist'));
+  try {
+    const summary = injectDir(distDir);
+    console.log(`[inject-qa] ${summary.total} HTML files: ` +
+      `${summary.injected} injected, ${summary.skipped} already injected, ${summary.no_body} without </body>.`);
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+}
+
+module.exports = { MARKER, WIDGET_SOURCE, SNIPPET, injectDir, collectHtmlFiles };
diff --git a/scripts/inject-qa.test.mjs b/scripts/inject-qa.test.mjs
new file mode 100644
index 0000000..91c7887
--- /dev/null
+++ b/scripts/inject-qa.test.mjs
@@ -0,0 +1,371 @@
+#!/usr/bin/env node
+// inject-qa.test.mjs — zero-dependency tests (node stdlib only) for the
+// docs Q&A injection pipeline and the inlined widget's XSS invariant.
+// Run: node scripts/inject-qa.test.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import vm from 'node:vm';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const injectScript = path.join(scriptDir, 'inject-qa.js');
+const verifyScript = path.join(scriptDir, 'verify-qa-injection.mjs');
+const { MARKER, WIDGET_SOURCE } = createRequire(import.meta.url)('./inject-qa.js');
+
+const PAGE = '<!doctype html><html><head><title>t</title></head><body><main>content</main></body></html>';
+const NO_BODY_PAGE = '<!doctype html><html><head><title>t</title></head><main>content</main></html>';
+
+function makeDist(files) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'qa-dist-'));
+  for (const [rel, content] of Object.entries(files)) {
+    const full = path.join(dir, rel);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, content);
+  }
+  return dir;
+}
+
+function runInject(distDir) {
+  return spawnSync(process.execPath, [injectScript, distDir], { encoding: 'utf8' });
+}
+
+function runVerify(distDir, extraArgs = []) {
+  return spawnSync(process.execPath, [verifyScript, distDir, ...extraArgs], { encoding: 'utf8' });
+}
+
+function markerCount(file) {
+  const html = fs.readFileSync(file, 'utf8');
+  return html.split(MARKER).length - 1;
+}
+
+// --- injector -------------------------------------------------------------
+
+test('injects exactly one marker before </body> in every HTML file, nested included', () => {
+  const dist = makeDist({ 'index.html': PAGE, 'guides/sending.html': PAGE, 'notes.txt': 'not html' });
+
+  const result = runInject(dist);
+
+  assert.equal(result.status, 0, result.stderr);
+  for (const rel of ['index.html', 'guides/sending.html']) {
+    const html = fs.readFileSync(path.join(dist, rel), 'utf8');
+    assert.equal(markerCount(path.join(dist, rel)), 1, `${rel} should carry one marker`);
+    assert.ok(html.indexOf(MARKER) < html.lastIndexOf('</body>'), 'snippet sits before </body>');
+    assert.ok(html.trimEnd().endsWith('</html>'), 'document still closes');
+  }
+  assert.equal(fs.readFileSync(path.join(dist, 'notes.txt'), 'utf8'), 'not html', 'non-HTML untouched');
+});
+
+test('is idempotent: a second run never double-injects', () => {
+  const dist = makeDist({ 'index.html': PAGE, 'guides/sending.html': PAGE });
+
+  assert.equal(runInject(dist).status, 0);
+  const second = runInject(dist);
+
+  assert.equal(second.status, 0);
+  assert.match(second.stdout, /2 already injected/);
+  assert.equal(markerCount(path.join(dist, 'index.html')), 1);
+  assert.equal(markerCount(path.join(dist, 'guides/sending.html')), 1);
+});
+
+test('fails loudly when dist is missing', () => {
+  const result = runInject(path.join(os.tmpdir(), 'qa-definitely-missing-dist'));
+
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /not found/);
+});
+
+test('fails loudly when dist holds no HTML files', () => {
+  const dist = makeDist({ 'llms.txt': 'text only' });
+
+  const result = runInject(dist);
+
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /no HTML files/);
+});
+
+test('warns on a </body>-less file and leaves it untouched', () => {
+  const dist = makeDist({ 'index.html': PAGE, 'weird.html': NO_BODY_PAGE });
+
+  const result = runInject(dist);
+
+  assert.equal(result.status, 0);
+  assert.match(result.stderr, /weird\.html/);
+  assert.match(result.stderr, /no <\/body>/);
+  assert.equal(fs.readFileSync(path.join(dist, 'weird.html'), 'utf8'), NO_BODY_PAGE);
+  assert.equal(markerCount(path.join(dist, 'index.html')), 1);
+});
+
+// --- verifier -------------------------------------------------------------
+
+test('verifier passes a fully injected dist', () => {
+  const dist = makeDist({ 'index.html': PAGE, 'guides/sending.html': PAGE });
+  runInject(dist);
+
+  const result = runVerify(dist);
+
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /exactly one widget marker/);
+});
+
+test('verifier fails when any file has zero markers', () => {
+  const dist = makeDist({ 'index.html': PAGE, 'guides/sending.html': PAGE });
+  runInject(dist);
+  fs.writeFileSync(path.join(dist, 'guides', 'sending.html'), PAGE); // regress one file
+
+  const result = runVerify(dist);
+
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /sending\.html: widget marker missing/);
+});
+
+test('verifier fails when any file has two or more markers', () => {
+  const dist = makeDist({ 'index.html': PAGE });
+  runInject(dist);
+  const file = path.join(dist, 'index.html');
+  const html = fs.readFileSync(file, 'utf8');
+  fs.writeFileSync(file, html.replace('</body>', `<script ${MARKER}></` + 'script></body>'));
+
+  const result = runVerify(dist);
+
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /index\.html: 2 widget markers/);
+});
+
+test('verifier fails a </body>-less file unless explicitly allowlisted', () => {
+  const dist = makeDist({ 'index.html': PAGE, 'weird.html': NO_BODY_PAGE });
+  runInject(dist);
+
+  const without = runVerify(dist);
+  assert.notEqual(without.status, 0);
+  assert.match(without.stderr, /weird\.html: widget marker missing/);
+
+  const withAllow = runVerify(dist, ['--allow', 'weird.html']);
+  assert.equal(withAllow.status, 0, withAllow.stderr);
+});
+
+test('verifier fails on a missing or empty dist', () => {
+  assert.notEqual(runVerify(path.join(os.tmpdir(), 'qa-definitely-missing-dist')).status, 0);
+
+  const empty = makeDist({ 'llms.txt': 'no html here' });
+  const result = runVerify(empty);
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /no HTML files/);
+});
+
+// --- widget DOM (XSS invariant) ------------------------------------------
+
+// Minimal hand-rolled DOM stub. innerHTML/outerHTML setters THROW: the
+// widget completing at all proves no HTML sink was used for any value.
+class StubNode {
+  constructor(tag) {
+    this.tagName = String(tag).toUpperCase();
+    this.nodeType = 1;
+    this.children = [];
+    this.className = '';
+    this.parent = null;
+  }
+
+  appendChild(node) {
+    node.parent = this;
+    this.children.push(node);
+    return node;
+  }
+
+  remove() {
+    if (this.parent) {
+      this.parent.children = this.parent.children.filter((child) => child !== this);
+      this.parent = null;
+    }
+    this.removed = true;
+  }
+
+  set innerHTML(_value) {
+    throw new Error('XSS invariant violated: innerHTML assignment');
+  }
+
+  get innerHTML() {
+    throw new Error('XSS invariant violated: innerHTML read/write is out of bounds');
+  }
+
+  set outerHTML(_value) {
+    throw new Error('XSS invariant violated: outerHTML assignment');
+  }
+
+  set insertAdjacentHTML(_value) {
+    throw new Error('XSS invariant violated: insertAdjacentHTML');
+  }
+}
+
+function textNodes(node, out = []) {
+  if (node.nodeType === 3) {
+    out.push(node.textContent);
+    return out;
+  }
+  for (const child of node.children || []) textNodes(child, out);
+  return out;
+}
+
+function elementNodes(node, out = []) {
+  if (node.nodeType === 1) {
+    out.push(node);
+    for (const child of node.children) elementNodes(child, out);
+  }
+  return out;
+}
+
+function buildSandbox({ pathname, payload }) {
+  const body = new StubNode('body');
+  const main = new StubNode('main');
+  body.appendChild(main);
+
+  const document = {
+    body,
+    createElement: (tag) => new StubNode(tag),
+    createTextNode: (text) => ({ nodeType: 3, textContent: String(text) }),
+    querySelector: (selector) => (selector === 'main' ? main : null)
+  };
+
+  let ready = Promise.resolve();
+  const window = {
+    location: { pathname },
+    fetch: () => Promise.resolve({ ok: true, json: () => Promise.resolve(payload) }),
+    __nitroQaOnDone: (promise) => { ready = promise; }
+  };
+
+  return { window, document, main, body, ready: () => ready };
+}
+
+function runWidget(sandboxParts) {
+  const context = {
+    window: sandboxParts.window,
+    document: sandboxParts.document,
+    Promise,
+    Date,
+    encodeURIComponent,
+    decodeURIComponent,
+    String,
+    Error,
+    console
+  };
+  vm.runInNewContext(WIDGET_SOURCE, context);
+  return sandboxParts.ready();
+}
+
+const HOSTILE_QUESTION = '<img src=x onerror=alert(1)>';
+const HOSTILE_ANSWER = '</scr' + 'ipt><scr' + 'ipt>alert("pwn")</scr' + 'ipt>';
+const HOSTILE_NAME = '<svg onload=alert(2)>';
+
+const hostilePayload = {
+  questions: [
+    {
+      id: 1,
+      body: HOSTILE_QUESTION,
+      page_key: '/quickstart',
+      created_at: '2026-07-22T04:12:00Z',
+      user: { first_name: HOSTILE_NAME },
+      answered: true,
+      answers: [
+        {
+          id: 2,
+          body: HOSTILE_ANSWER,
+          source: 'ai',
+          verified_at: null,
+          created_at: '2026-07-22T04:13:00Z',
+          author: null
+        }
+      ]
+    }
+  ]
+};
+
+test('widget renders hostile strings strictly as text nodes', async () => {
+  const parts = buildSandbox({ pathname: '/quickstart', payload: hostilePayload });
+
+  await runWidget(parts);
+
+  const texts = textNodes(parts.body);
+  assert.ok(texts.includes(HOSTILE_QUESTION), 'question body is a text node');
+  assert.ok(texts.includes(HOSTILE_ANSWER), 'answer body is a text node');
+  assert.ok(texts.some((t) => t.includes(HOSTILE_NAME)), 'first name is inside a text node');
+
+  // No hostile value may reach an attribute-like sink.
+  for (const element of elementNodes(parts.body)) {
+    const href = element.href || '';
+    assert.ok(!href.includes('<'), `href stayed clean: ${href}`);
+    assert.ok(!String(element.className).includes('<'), 'className stayed clean');
+  }
+});
+
+test('widget URL-encodes the page_key into the Ask deep link only', async () => {
+  const parts = buildSandbox({ pathname: '/Guides//Sending-Emails.html/', payload: { questions: [] } });
+
+  await runWidget(parts);
+
+  const links = elementNodes(parts.body).filter((element) => element.tagName === 'A');
+  assert.equal(links.length, 1, 'quiet empty state renders exactly one ask link');
+  assert.ok(links[0].href.endsWith('?page_key=' + encodeURIComponent('/guides/sending-emails')), links[0].href);
+});
+
+test('widget page_key normalization matrix matches the API', async () => {
+  const cases = [
+    ['/quickstart', '/quickstart'],
+    ['/QuickStart.html', '/quickstart'],
+    ['/guides//sending-emails/', '/guides/sending-emails'],
+    ['/%71uickstart', '/quickstart'],
+    ['/', '/introduction']
+  ];
+
+  for (const [pathname, expected] of cases) {
+    const parts = buildSandbox({ pathname, payload: { questions: [] } });
+    await runWidget(parts);
+    const links = elementNodes(parts.body).filter((element) => element.tagName === 'A');
+    assert.equal(links.length, 1, `${pathname} mounts`);
+    assert.ok(
+      links[0].href.endsWith('?page_key=' + encodeURIComponent(expected)),
+      `${pathname} -> ${expected} (got ${links[0].href})`
+    );
+  }
+});
+
+test('widget renders nothing for keys that stay invalid after normalization', async () => {
+  for (const pathname of ['/%3Cscript%3E', '/spaced path', '/%ZZbroken', '/' + 'a'.repeat(140)]) {
+    const parts = buildSandbox({ pathname, payload: { questions: [] } });
+    await runWidget(parts);
+    assert.equal(parts.main.children.length, 0, `${pathname} must not mount the widget`);
+  }
+});
+
+test('widget removes its container (style included) when the fetch fails', async () => {
+  const parts = buildSandbox({ pathname: '/quickstart', payload: { questions: [] } });
+  parts.window.fetch = () => Promise.reject(new Error('network down'));
+
+  await runWidget(parts);
+
+  assert.equal(parts.main.children.length, 0, 'container removed on fetch failure');
+});
+
+test('widget removes its container on a non-OK response', async () => {
+  const parts = buildSandbox({ pathname: '/quickstart', payload: { questions: [] } });
+  parts.window.fetch = () => Promise.resolve({ ok: false, json: () => Promise.resolve({}) });
+
+  await runWidget(parts);
+
+  assert.equal(parts.main.children.length, 0, 'container removed on non-OK response');
+});
+
+test('widget labels AI answers and their verification state', async () => {
+  const verified = JSON.parse(JSON.stringify(hostilePayload));
+  verified.questions[0].answers[0].verified_at = '2026-07-22T05:00:00Z';
+  const parts = buildSandbox({ pathname: '/quickstart', payload: verified });
+
+  await runWidget(parts);
+
+  const texts = textNodes(parts.body);
+  assert.ok(texts.some((t) => t.includes('Answered by NitroLLM') && t.includes('verified by the team')));
+});
diff --git a/scripts/verify-qa-injection.mjs b/scripts/verify-qa-injection.mjs
new file mode 100644
index 0000000..24266df
--- /dev/null
+++ b/scripts/verify-qa-injection.mjs
@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// verify-qa-injection.mjs — hard gate after inject-qa.js in the Vercel
+// buildCommand. FAILS the build unless EVERY generated HTML file contains
+// exactly one widget marker. No grep pipelines, no sampling: zero markers
+// (missed injection) and 2+ markers (double injection) are both fatal.
+//
+// Files that legitimately cannot carry the widget (no </body> — none
+// today) must be listed in ALLOWLIST below, by dist-relative path, with a
+// reason. Allowlisted files are excused from the exactly-one rule but
+// still fail on 2+ markers.
+//
+// Usage: node scripts/verify-qa-injection.mjs [distDir] [--allow rel/path]...
+// (positional distDir + --allow exist for the test harness; production
+// runs with no arguments.)
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+// Single source of truth for the marker — drift between injector and
+// verifier would make the gate lie.
+const { MARKER, collectHtmlFiles } = createRequire(import.meta.url)('./inject-qa.js');
+
+// dist-relative paths, e.g. 'some/page.html'. Keep reasons inline.
+const ALLOWLIST = [
+  // (none — every Sourcey page currently emits </body>)
+];
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+
+function parseArgs(argv) {
+  const allow = [...ALLOWLIST];
+  let distDir = null;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--allow') {
+      allow.push(argv[++i]);
+    } else if (!distDir) {
+      distDir = argv[i];
+    }
+  }
+  return { distDir: path.resolve(distDir || path.join(scriptDir, '..', 'dist')), allow };
+}
+
+function countOccurrences(haystack, needle) {
+  let count = 0;
+  let at = haystack.indexOf(needle);
+  while (at !== -1) {
+    count += 1;
+    at = haystack.indexOf(needle, at + needle.length);
+  }
+  return count;
+}
+
+const { distDir, allow } = parseArgs(process.argv.slice(2));
+
+if (!fs.existsSync(distDir) || !fs.statSync(distDir).isDirectory()) {
+  console.error(`[verify-qa] dist directory not found: ${distDir}`);
+  process.exit(1);
+}
+
+const files = collectHtmlFiles(distDir);
+if (files.length === 0) {
+  console.error(`[verify-qa] no HTML files found in ${distDir} — an empty build must not pass.`);
+  process.exit(1);
+}
+
+const failures = [];
+for (const file of files) {
+  const rel = path.relative(distDir, file);
+  const count = countOccurrences(fs.readFileSync(file, 'utf8'), MARKER);
+  const allowlisted = allow.includes(rel);
+
+  if (count === 1) continue;
+  if (count === 0 && allowlisted) continue;
+
+  if (count === 0) {
+    failures.push(`${rel}: widget marker missing (not injected, not allowlisted)`);
+  } else {
+    failures.push(`${rel}: ${count} widget markers (double injection)`);
+  }
+}
+
+if (failures.length > 0) {
+  console.error(`[verify-qa] FAILED — ${failures.length} of ${files.length} HTML files are wrong:`);
+  for (const failure of failures) console.error(`  - ${failure}`);
+  process.exit(1);
+}
+
+console.log(`[verify-qa] OK — ${files.length} HTML files each carry exactly one widget marker` +
+  (allow.length ? ` (${allow.length} allowlisted)` : '') + '.');
diff --git a/vercel.json b/vercel.json
index 958f9a0..ae8b6c8 100644
--- a/vercel.json
+++ b/vercel.json
@@ -1,5 +1,5 @@
 {
-  "buildCommand": "npx sourcey build",
+  "buildCommand": "npx sourcey build && node scripts/inject-qa.js && node scripts/verify-qa-injection.mjs",
   "outputDirectory": "dist",
   "installCommand": "npm install",
   "cleanUrls": true,

From ed1e3bddc5084566a1a3e7a625cd1381581fcb28 Mon Sep 17 00:00:00 2001
From: George Hartley <georgehartley@gmail.com>
Date: Wed, 22 Jul 2026 16:13:00 +1000
Subject: [PATCH 2/2] fix(docs): point Ask deep link at the Learning Centre
 route
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The community-qa contract's deep link is
https://app.nitrosend.com/my/learn?ask=1&page_key=<encoded> (LC route
name my-learn) — /learning/community/ask does not exist and is not
planned. Tests now pin the full href.
---
 scripts/inject-qa.js       |  5 +++--
 scripts/inject-qa.test.mjs | 10 +++++++---
 2 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/scripts/inject-qa.js b/scripts/inject-qa.js
index deb8dcf..6c9543e 100644
--- a/scripts/inject-qa.js
+++ b/scripts/inject-qa.js
@@ -51,7 +51,8 @@ const WIDGET_SOURCE = `(function (w, d) {
   'use strict';
 
   var API_BASE = 'https://api.nitrosend.com';
-  var ASK_BASE = 'https://app.nitrosend.com/learning/community/ask';
+  // Learning Centre route (route name my-learn); ask=1 opens the ask flow.
+  var ASK_BASE = 'https://app.nitrosend.com/my/learn';
   var PAGE_KEY_RE = /^\\/[a-z0-9\\-\\/]{0,120}$/;
 
   var CSS = '' +
@@ -107,7 +108,7 @@ const WIDGET_SOURCE = `(function (w, d) {
     var a = el('a', 'nitro-qa-ask', label);
     // pageKey is charset-validated above and URL-encoded here; no other
     // dynamic value ever reaches an attribute.
-    a.href = ASK_BASE + '?page_key=' + encodeURIComponent(pageKey);
+    a.href = ASK_BASE + '?ask=1&page_key=' + encodeURIComponent(pageKey);
     return a;
   }
 
diff --git a/scripts/inject-qa.test.mjs b/scripts/inject-qa.test.mjs
index 91c7887..544b6e0 100644
--- a/scripts/inject-qa.test.mjs
+++ b/scripts/inject-qa.test.mjs
@@ -309,7 +309,10 @@ test('widget URL-encodes the page_key into the Ask deep link only', async () =>
 
   const links = elementNodes(parts.body).filter((element) => element.tagName === 'A');
   assert.equal(links.length, 1, 'quiet empty state renders exactly one ask link');
-  assert.ok(links[0].href.endsWith('?page_key=' + encodeURIComponent('/guides/sending-emails')), links[0].href);
+  assert.equal(
+    links[0].href,
+    'https://app.nitrosend.com/my/learn?ask=1&page_key=' + encodeURIComponent('/guides/sending-emails')
+  );
 });
 
 test('widget page_key normalization matrix matches the API', async () => {
@@ -326,8 +329,9 @@ test('widget page_key normalization matrix matches the API', async () => {
     await runWidget(parts);
     const links = elementNodes(parts.body).filter((element) => element.tagName === 'A');
     assert.equal(links.length, 1, `${pathname} mounts`);
-    assert.ok(
-      links[0].href.endsWith('?page_key=' + encodeURIComponent(expected)),
+    assert.equal(
+      links[0].href,
+      'https://app.nitrosend.com/my/learn?ask=1&page_key=' + encodeURIComponent(expected),
       `${pathname} -> ${expected} (got ${links[0].href})`
     );
   }