npm - @cparkerwebm/webmonterey - Versions diffs - 1.0.0 - Mend

@cparkerwebm/webmonterey 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (133) hide show

package/CHANGELOG.md +56 -0
package/LICENSE +21 -0
package/README.md +104 -0
package/agents/.gitkeep +0 -0
package/dist/webm.mjs +2381 -0
package/hooks/.gitkeep +0 -0
package/package.json +101 -0
package/schema/design.json +118 -0
package/skills/launch/SKILL.md +183 -0
package/skills/new-component/SKILL.md +85 -0
package/skills/start/SKILL.md +117 -0
package/skills/traps/SKILL.md +333 -0
package/skills/upgrade/SKILL.md +42 -0
package/src/actions/index.ts +348 -0
package/src/cli/checks.test.ts +711 -0
package/src/cli/checks.ts +822 -0
package/src/cli/codemods.test.ts +42 -0
package/src/cli/codemods.ts +51 -0
package/src/cli/compare.test.ts +144 -0
package/src/cli/compare.ts +222 -0
package/src/cli/design-extract.test.ts +96 -0
package/src/cli/design-extract.ts +229 -0
package/src/cli/doctor.ts +187 -0
package/src/cli/mcp.test.ts +57 -0
package/src/cli/mcp.ts +110 -0
package/src/cli/new.ts +148 -0
package/src/cli/package-root.ts +58 -0
package/src/cli/scaffold.test.ts +230 -0
package/src/cli/scaffold.ts +424 -0
package/src/cli/seed.ts +133 -0
package/src/cli/slug.test.ts +70 -0
package/src/cli/slug.ts +109 -0
package/src/cli/sync.test.ts +137 -0
package/src/cli/sync.ts +266 -0
package/src/cli/upgrade.ts +93 -0
package/src/design/__fixtures__/tokens-v1.4.1.css +227 -0
package/src/design/brand.ts +49 -0
package/src/design/compile.test.ts +98 -0
package/src/design/compile.ts +155 -0
package/src/design/defaults.ts +315 -0
package/src/design/index.ts +18 -0
package/src/design/resolve.test.ts +80 -0
package/src/design/resolve.ts +108 -0
package/src/design/types.ts +96 -0
package/src/emails/autoresponse.test.ts +82 -0
package/src/emails/autoresponse.ts +83 -0
package/src/emails/footer.test.ts +102 -0
package/src/emails/footer.ts +91 -0
package/src/emails/index.ts +24 -0
package/src/emails/subject.test.ts +66 -0
package/src/emails/subject.ts +80 -0
package/src/emails/submission-notification.ts +76 -0
package/src/env.d.ts +12 -0
package/src/includes/cloudflare/d1/client.ts +86 -0
package/src/includes/cloudflare/r2/README.md +68 -0
package/src/includes/cloudflare/r2/media.ts +41 -0
package/src/includes/cloudflare/r2/url.test.ts +44 -0
package/src/includes/cloudflare/r2/url.ts +34 -0
package/src/includes/cloudflare/turnstile/Turnstile.astro +161 -0
package/src/includes/cloudflare/turnstile/verify.ts +157 -0
package/src/includes/cloudflare/workers/env.ts +56 -0
package/src/includes/google/tag-manager/TagManager.astro +73 -0
package/src/includes/sinch/mailgun/redirect.test.ts +96 -0
package/src/includes/sinch/mailgun/redirect.ts +96 -0
package/src/includes/sinch/mailgun/send.ts +186 -0
package/src/includes/webmonterey/animations/animations.css +347 -0
package/src/includes/webmonterey/animations/observe.test.ts +88 -0
package/src/includes/webmonterey/animations/observe.ts +209 -0
package/src/includes/webmonterey/compliance/ConsentInit.astro +74 -0
package/src/includes/webmonterey/compliance/CookieConsent.astro +558 -0
package/src/includes/webmonterey/compliance/consent-styles.test.ts +83 -0
package/src/includes/webmonterey/compliance/consent.ts +142 -0
package/src/includes/webmonterey/config.test.ts +94 -0
package/src/includes/webmonterey/config.ts +346 -0
package/src/includes/webmonterey/copy-defaults.ts +148 -0
package/src/includes/webmonterey/copy.ts +13 -0
package/src/includes/webmonterey/credits/Credit.astro +80 -0
package/src/includes/webmonterey/credits/credit.test.ts +111 -0
package/src/includes/webmonterey/credits/credit.ts +59 -0
package/src/includes/webmonterey/forms/honeypot.test.ts +40 -0
package/src/includes/webmonterey/forms/honeypot.ts +66 -0
package/src/includes/webmonterey/prose/inline.test.ts +94 -0
package/src/includes/webmonterey/prose/inline.ts +71 -0
package/src/includes/webmonterey/scroll-top/ScrollTop.astro +209 -0
package/src/includes/webmonterey/site.ts +136 -0
package/src/includes/webmonterey/structured-data/nodes.ts +315 -0
package/src/includes/webmonterey/zoned-hour.test.ts +49 -0
package/src/integration/adapter.ts +53 -0
package/src/integration/app-middleware.ts +43 -0
package/src/integration/config.ts +96 -0
package/src/integration/content.ts +66 -0
package/src/integration/image-size.test.ts +83 -0
package/src/integration/image-size.ts +100 -0
package/src/integration/index.ts +386 -0
package/src/integration/virtual.d.ts +101 -0
package/src/layouts/base.astro +402 -0
package/src/package.test.ts +121 -0
package/src/pages/404.astro +33 -0
package/src/pages/[...slug].astro +126 -0
package/src/pages/robots.txt.ts +41 -0
package/src/pages/webm.astro +23 -0
package/src/scripts/.gitkeep +0 -0
package/src/styles/base.css +185 -0
package/src/styles/global.css +47 -0
package/src/styles/layers.test.ts +32 -0
package/src/styles/layers.ts +21 -0
package/src/styles/layout.css +235 -0
package/src/styles/reset.css +135 -0
package/src/styles/utilities.css +90 -0
package/src/worker.ts +76 -0
package/template/assets/logo.svg +14 -0
package/template/assets/open-graph.png +0 -0
package/template/migrations/0001_create_submissions.sql +40 -0
package/template/migrations/README.md +41 -0
package/template/public/android-chrome-192x192.png +0 -0
package/template/public/android-chrome-512x512.png +0 -0
package/template/public/apple-touch-icon.png +0 -0
package/template/public/favicon-16x16.png +0 -0
package/template/public/favicon-32x32.png +0 -0
package/template/public/favicon.ico +0 -0
package/template/public/favicon.svg +4 -0
package/template/public/open-graph.png +0 -0
package/template/scripts/check-node.mjs +72 -0
package/template/scripts/test-hooks.mjs +96 -0
package/template/site/.editorconfig +22 -0
package/template/site/.prettierignore +15 -0
package/template/site/.prettierrc.json +17 -0
package/template/site/CLAUDE.md +245 -0
package/template/site/CONTENT.md +135 -0
package/template/site/PRIVACY-POLICY-DRAFT.md +81 -0
package/template/site/public/_headers +70 -0
package/template/site/src/forms/contact.json +45 -0
package/template/workflows/ci.yml +52 -0

package/src/emails/autoresponse.test.ts ADDED Viewed

@@ -0,0 +1,82 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { renderHtml, renderText } from './autoresponse.ts';
+import { renderHtml as renderNotificationHtml } from './submission-notification.ts';
+const input = {
+  body: 'Thanks for getting in touch.',
+  fields: [
+    { label: 'Your name', name: 'name', value: 'Ada' },
+    { label: 'Email address', name: 'email', value: 'ada@example.com' },
+  ],
+  client: 'Acme Co',
+  domain: 'example.com',
+};
+test('the visitor sees the client-authored copy first', () => {
+  assert.ok(renderText(input).startsWith('Thanks for getting in touch.'));
+  assert.ok(renderHtml(input).includes('Thanks for getting in touch.'));
+});
+test('their own submission is echoed back', () => {
+  const text = renderText(input);
+  assert.ok(text.includes('Your name'));
+  assert.ok(text.includes('Ada'));
+});
+test('it never carries the D1 reference', () => {
+  /*
+   * The notification includes "Reference: #id" so an enquiry can be found later. This message
+   * goes to an address the site does not control, so an internal row id must not ride along.
+   * The input type has no submissionId at all — this guards against one being added.
+   */
+  assert.ok(!renderText(input).includes('Reference'));
+  assert.ok(!renderHtml(input).includes('Reference'));
+  const notification = renderNotificationHtml({
+    form: 'contact',
+    formName: 'Contact',
+    fields: input.fields,
+    client: input.client,
+    domain: input.domain,
+    submissionId: 42,
+  });
+  assert.ok(notification.includes('Reference'), 'the notification still carries it');
+});
+test('the body copy is escaped', () => {
+  const html = renderHtml({ ...input, body: '<script>alert(1)</script>' });
+  assert.ok(!html.includes('<script>alert'));
+  assert.ok(html.includes('&lt;script&gt;'));
+});
+test('field values are escaped', () => {
+  const html = renderHtml({
+    ...input,
+    fields: [{ label: 'Name', name: 'name', value: '<img src=x onerror=alert(1)>' }],
+  });
+  assert.ok(!html.includes('<img src=x'));
+});
+test('an empty value renders a dash rather than a blank cell', () => {
+  const html = renderHtml({
+    ...input,
+    fields: [{ label: 'Phone', name: 'phone', value: '' }],
+  });
+  assert.ok(html.includes('&mdash;'));
+  assert.ok(
+    renderText({ ...input, fields: [{ label: 'Phone', name: 'phone', value: '' }] }).includes('-'),
+  );
+});
+test('it reuses the shared footer', () => {
+  assert.ok(renderText(input).includes('Powered by WebMonterey'));
+  assert.ok(renderHtml(input).includes('Powered by WebMonterey'));
+  assert.ok(renderText(input).includes('Acme Co'));
+});
+test('both parts are produced for deliverability', () => {
+  assert.ok(renderText(input).length > 0);
+  assert.ok(renderHtml(input).startsWith('<!doctype html>'));
+});

package/src/emails/autoresponse.ts ADDED Viewed

@@ -0,0 +1,83 @@
+/*
+ * The confirmation email sent to the VISITOR after they submit a form.
+ *
+ * The second template, and the reason footer.ts and subject.ts are shared modules rather than
+ * code inside submission-notification.ts. Nothing about the footer or the subject format is
+ * re-implemented here.
+ *
+ * IT IS NOT THE NOTIFICATION WITH THE RECIPIENTS SWAPPED. Three things invert:
+ *
+ *   - `to` is the visitor, so this is the one message on the site that reaches an address the
+ *     site does not control. It must never carry the D1 reference, internal notes, or any
+ *     field the visitor did not themselves type.
+ *   - Reply-To is the CLIENT's address, so a visitor replying reaches a human. The
+ *     notification does the opposite and points at the enquirer.
+ *   - It leads with copy, because the recipient did not ask for a data dump — they want
+ *     confirmation that the thing they just did worked.
+ *
+ * The echo of their own submission is deliberate: it is the only record they have, since the
+ * form cleared when it submitted.
+ */
+import { escapeHtml, renderFooterHtml, renderFooterText } from './footer.ts';
+import { DEFAULT_COPY } from '../includes/webmonterey/copy-defaults.ts';
+export interface AutoresponseEmailInput {
+  /** Client-authored copy from the form definition's `autoresponse.body`. */
+  body: string;
+  /** The submitted fields, echoed back in display order. */
+  fields: Array<{ label: string; name: string; value: string }>;
+  /** The client's display name, for the footer's copyright line. */
+  client: string;
+  /** The site's production domain, named in the footer. */
+  domain: string;
+}
+/** The heading above the echoed fields, in both parts. */
+const ECHO_HEADING = '${DEFAULT_COPY.email.autoresponseHeading}';
+export function renderText(input: AutoresponseEmailInput): string {
+  const lines = [
+    input.body,
+    '',
+    ECHO_HEADING,
+    '',
+    ...input.fields.map((f) => `${f.label}:\n${f.value || '-'}\n`),
+  ];
+  lines.push(renderFooterText({ client: input.client, domain: input.domain }));
+  return lines.join('\n');
+}
+export function renderHtml(input: AutoresponseEmailInput): string {
+  const rows = input.fields
+    .map(
+      (f) => `      <tr>
+        <th align="left" style="padding:8px 16px 8px 0;vertical-align:top;color:#3f3f3f;font-weight:600;white-space:nowrap;">${escapeHtml(f.label)}</th>
+        <td style="padding:8px 0;vertical-align:top;color:#222;">${escapeHtml(f.value) || '&mdash;'}</td>
+      </tr>`,
+    )
+    .join('\n');
+  /*
+   * Inline styles and a table layout, for the same reason as the notification: email clients
+   * strip <style> blocks, so the site's design tokens cannot reach here.
+   *
+   * The body copy is escaped like everything else. It comes from the form definition rather
+   * than from a visitor, but it is still authored text arriving through JSON, and there is no
+   * case where raw HTML in it would be intended.
+   */
+  return `<!doctype html>
+<html>
+  <body style="margin:0;padding:24px;background:#f1eae8;font-family:system-ui,-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;">
+    <div style="max-width:640px;margin:0 auto;padding:32px;background:#fff;border-radius:8px;">
+      <p style="margin:0 0 24px;font-size:15px;line-height:1.6;color:#222;">${escapeHtml(input.body)}</p>
+      <p style="margin:0 0 8px;font-size:13px;font-weight:600;color:#3f3f3f;">${ECHO_HEADING}</p>
+      <table style="width:100%;border-collapse:collapse;font-size:14px;">
+${rows}
+      </table>
+    </div>
+${renderFooterHtml({ client: input.client, domain: input.domain })}
+  </body>
+</html>`;
+}

package/src/emails/footer.test.ts ADDED Viewed

@@ -0,0 +1,102 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { escapeHtml, renderFooterHtml, renderFooterText } from './footer.ts';
+const input = { client: 'Acme Co', domain: 'example.com' };
+test('escapeHtml neutralises the four dangerous characters', () => {
+  assert.equal(escapeHtml('<a href="x">&</a>'), '&lt;a href=&quot;x&quot;&gt;&amp;&lt;/a&gt;');
+});
+test('escapeHtml escapes the ampersand first', () => {
+  // Escaping & last would double-escape the entities the other replacements just produced.
+  assert.equal(escapeHtml('&lt;'), '&amp;lt;');
+});
+test('the text footer is three lines below a leading blank', () => {
+  const lines = renderFooterText(input).split('\n');
+  assert.equal(lines[0], '');
+  assert.equal(lines.length, 4);
+  assert.match(lines[1], /^© \d{4} Acme Co$/);
+  assert.equal(
+    lines[2],
+    'This is an automated notification for your account at the example.com website.',
+  );
+  assert.equal(lines[3], 'Powered by WebMonterey');
+});
+test('the year is the render year, not a build constant', () => {
+  assert.ok(renderFooterText(input).includes(String(new Date().getFullYear())));
+});
+test('the HTML footer escapes an interpolated client name', () => {
+  const html = renderFooterHtml({ client: '<script>alert(1)</script>', domain: 'example.com' });
+  assert.ok(!html.includes('<script>'));
+  assert.ok(html.includes('&lt;script&gt;'));
+});
+test('the HTML footer escapes an interpolated domain', () => {
+  const html = renderFooterHtml({ client: 'Acme', domain: '"onmouseover="x' });
+  assert.ok(!html.includes('"onmouseover="x</a>'));
+  assert.ok(html.includes('&quot;'));
+});
+/** The credit link out of the rendered footer, told apart from the client's own site link. */
+function creditHref(html: string): string {
+  const href = html.match(/href="(https:\/\/webmonterey\.com[^"]*)"/)?.[1];
+  assert.ok(href, 'the credit link should be present');
+  return href;
+}
+test('the credit link is tagged as coming from email', () => {
+  const href = creditHref(renderFooterHtml(input));
+  // The HTML is escaped, so read the params back out of the escaped form.
+  assert.match(href, /utm_medium=email/);
+  /* Underscored, not dotted: a mail client linkifies a domain inside a query string. */
+  assert.match(href, /utm_content=example_com/);
+  assert.ok(!href.includes('/credits'), 'the credit link must not reintroduce a /credits path');
+});
+test("the client's TLD appears nowhere in the email credit URL", () => {
+  /*
+   * THE assertion that catches the bug this guards. A dotted utm_content is a domain sitting
+   * in a query string; a mail client linkifies it and truncates the href there, so the credit
+   * link arrives broken. Checked against the query rather than the whole URL because the
+   * destination host is webmonterey.com and is allowed to look like a host.
+   */
+  const { search } = new URL(
+    creditHref(renderFooterHtml({ ...input, domain: 'sub.example.co.uk' })),
+  );
+  assert.equal(search.includes('.uk'), false);
+  assert.equal(search.includes('.'), false, 'no dot may reach the query string at all');
+  assert.match(search, /utm_content=sub_example_co_uk/);
+});
+test('both surfaces use the same wording', () => {
+  assert.ok(renderFooterText(input).includes('Powered by WebMonterey'));
+  assert.ok(renderFooterHtml(input).includes('Powered by WebMonterey'));
+});
+/*
+ * Both footer links open in a new tab.
+ *
+ * The web component carried `rel="noopener"` and no `target`, which does nothing - noopener only
+ * means anything alongside a target - so the credit navigated away from the client's site in the
+ * same tab. It was found broken on live sites. These assert the email side cannot regress the
+ * same way; the Astro component is covered by a build-output check in examples/minimal.
+ */
+test('every link in the HTML footer opens in a new tab', () => {
+  const html = renderFooterHtml({ client: 'Acme Co', domain: 'acme.com' });
+  const anchors = [...html.matchAll(/<a\b[^>]*>/g)].map((m) => m[0]);
+  assert.ok(anchors.length >= 2, 'expected the site link and the credit link');
+  for (const a of anchors) {
+    assert.match(a, /target="_blank"/, `missing target: ${a}`);
+    assert.match(a, /rel="[^"]*noopener/, `target without noopener: ${a}`);
+  }
+});
+test('the credit link keeps its referrer - that is the attribution', () => {
+  const html = renderFooterHtml({ client: 'Acme Co', domain: 'acme.com' });
+  assert.ok(!html.includes('noreferrer'), 'noreferrer would strip the attribution signal');
+});

package/src/emails/footer.ts ADDED Viewed

@@ -0,0 +1,91 @@
+/*
+ * The footer every transactional email ends with. Three lines, below the white card:
+ *
+ *   (c) 2026 Client Name
+ *   This is an automated notification for your account at the example.com website.
+ *   Powered by WebMonterey
+ *
+ * A separate module because submission-notification.ts is the FIRST template, not the only
+ * one — an autoresponder or a receipt would otherwise copy this block, and the copies drift.
+ * Same reasoning the Mailgun sender already carries.
+ *
+ * The year is computed HERE rather than passed in. These only ever render on
+ * `prerender = false` routes, so `new Date()` is real request time, not a frozen build
+ * constant — and a caller that has to remember to pass the year eventually forgets, which
+ * shows up as a stale copyright the following January.
+ */
+import { CREDIT_TEXT, creditUrl } from '../includes/webmonterey/credits/credit.ts';
+import { DEFAULT_COPY, fill } from '../includes/webmonterey/copy-defaults.ts';
+export interface EmailFooterInput {
+  /** The client's display name, for the copyright line. */
+  client: string;
+  /** The site's production domain, named in the disclaimer and used for attribution. */
+  domain: string;
+}
+/** Minimal HTML escape. Shared with the templates; every interpolated value is untrusted. */
+export function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+function disclaimer(domain: string): string {
+  return `${fill(DEFAULT_COPY.email.footerNotice, { domain })}`;
+}
+/**
+ * The plain-text footer.
+ *
+ * DELIBERATELY CARRIES NO LINK. The credit appears as words only, so this surface contributes no
+ * attribution and `utm_medium=email` only ever fires from the HTML version. That is accepted: a
+ * UTM-laden URL on its own line is ugly in plain text, and it is the one place a mail client
+ * genuinely would linkify and truncate it.
+ *
+ * Do not "fix" this by adding the URL.
+ */
+export function renderFooterText(input: EmailFooterInput): string {
+  return [
+    '',
+    `© ${new Date().getFullYear()} ${input.client}`,
+    disclaimer(input.domain),
+    CREDIT_TEXT,
+  ].join('\n');
+}
+export function renderFooterHtml(input: EmailFooterInput): string {
+  const year = new Date().getFullYear();
+  const href = creditUrl(input.domain, 'email');
+  /*
+   * Inline styles and explicit colors: email clients strip <style> blocks entirely, so the
+   * site's design tokens cannot reach here. Deliberately NOT a table — this is three
+   * centred lines and every client renders that consistently.
+   *
+   * BOTH LINKS OPEN IN A NEW TAB AND NEITHER ANNOUNCES IT, unlike the site footer, which
+   * appends a visually-hidden "(opens in a new tab)". That asymmetry is deliberate, and the
+   * reason is the same one that forced inline styles: the hiding technique cannot come with
+   * it. `.webm-visually-hidden` is a stylesheet rule, and clients strip <style>; the inline
+   * equivalent leans on `clip-path`, which Outlook and several webmail clients do not honour,
+   * so the note would land as literal visible text in the footer of every notification.
+   * Announcing it in words is the alternative and it is worse: a mail client opening a link
+   * in a browser is the expected behavior, so the warning would be noise about something no
+   * reader was surprised by. Nothing is lost that email a11y actually asks for.
+   *
+   * `title` is absent from both links ON PURPOSE, here and in Credit.astro. It is not reliably
+   * announced by screen readers, is unreachable by keyboard and touch entirely, and either
+   * duplicates the link text or competes with it for the accessible name. The link text is the
+   * accessible name; that is the mechanism that works.
+   *
+   * `rel="noopener"` without `noreferrer`, also on purpose: the referrer IS the attribution.
+   * Stripping it would leave only utm_content. See credit.ts.
+   */
+  return `    <div style="max-width:640px;margin:0 auto;padding:24px 32px 8px;text-align:center;font-size:13px;line-height:1.6;color:#3f3f3f;">
+      <p style="margin:0;">&copy; ${year} ${escapeHtml(input.client)}</p>
+      <p style="margin:0;">This is an automated notification for your account at the <a href="https://${escapeHtml(input.domain)}" target="_blank" rel="noopener" style="color:#3f3f3f;">${escapeHtml(input.domain)}</a> website.</p>
+      <p style="margin:8px 0 0;"><a href="${href}" target="_blank" rel="noopener" style="color:#222;font-weight:700;text-decoration:none;">${CREDIT_TEXT}</a></p>
+    </div>`;
+}

package/src/emails/index.ts ADDED Viewed

@@ -0,0 +1,24 @@
+/*
+ * @cparkerwebm/webmonterey/emails
+ *
+ * Transactional templates - form notifications and autoresponses - as plain functions.
+ *
+ * PLAIN FUNCTIONS RETURNING STRINGS, not a component framework. Email HTML is tables and inline
+ * styles - Outlook has enforced that for fifteen years - so a framework's main advantages do not
+ * survive the constraint, and @react-email/render would mean React SSR inside a Worker on every
+ * send. Zero dependencies, runs in a Worker, testable with `node --test`.
+ *
+ * Styling comes from `emailPalette()` in ./design, which resolves every var() chain to a literal.
+ * A custom property in an email is inert; `--webm-link: var(--webm-action)` is useless in a mail
+ * client and `#006abe` is not.
+ */
+export { renderFooterHtml, renderFooterText, escapeHtml } from './footer.ts';
+export { renderSubject, renderTopic, toAsciiSubject } from './subject.ts';
+export {
+  renderHtml as renderNotificationHtml,
+  renderText as renderNotificationText,
+} from './submission-notification.ts';
+export {
+  renderHtml as renderAutoresponseHtml,
+  renderText as renderAutoresponseText,
+} from './autoresponse.ts';

package/src/emails/subject.test.ts ADDED Viewed

@@ -0,0 +1,66 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { renderSubject, renderTopic, toAsciiSubject } from './subject.ts';
+test('toAsciiSubject transliterates accents rather than dropping them', () => {
+  assert.equal(toAsciiSubject('José'), 'Jose');
+  assert.equal(toAsciiSubject('naïve café'), 'naive cafe');
+});
+test('toAsciiSubject folds smart punctuation to ASCII', () => {
+  assert.equal(toAsciiSubject('“quoted” — it’s here…'), '"quoted" - it\'s here...');
+});
+test('toAsciiSubject strips CR and LF — header injection', () => {
+  // The whole point: a newline would end the Subject: header and let what follows be read
+  // as a new one. Bcc: must not survive in any form.
+  const injected = toAsciiSubject('Enquiry\r\nBcc: attacker@example.com');
+  assert.ok(!injected.includes('\r'));
+  assert.ok(!injected.includes('\n'));
+  /*
+   * Note the missing space: control characters are DELETED by the printable-ASCII filter
+   * before `\s+` ever runs, so the words either side join rather than being separated. That
+   * is only ever visible on a payload like this one, and stripping is the property that
+   * matters — but assert the real output so a future rewrite that turns CR/LF into a space
+   * (and might therefore be preserving them somewhere) shows up here.
+   */
+  assert.equal(injected, 'EnquiryBcc: attacker@example.com');
+});
+test('toAsciiSubject collapses whitespace and trims', () => {
+  assert.equal(toAsciiSubject('  a\t\t b  '), 'a b');
+});
+test('renderTopic fills placeholders from fields', () => {
+  const out = renderTopic('New enquiry from {{name}}', [{ name: 'name', value: 'Ada' }]);
+  assert.equal(out, 'New enquiry from Ada');
+});
+test('renderTopic tolerates whitespace inside the braces', () => {
+  assert.equal(renderTopic('Hi {{ name }}', [{ name: 'name', value: 'Ada' }]), 'Hi Ada');
+});
+test('renderTopic empties an unmatched placeholder rather than showing it', () => {
+  assert.equal(renderTopic('From {{missing}}!', []), 'From !');
+});
+test('renderSubject prefixes with the client name', () => {
+  assert.equal(renderSubject('Acme Co', 'New enquiry', []), '[Acme Co] New enquiry');
+});
+test('renderSubject omits the prefix entirely when there is no client', () => {
+  // Never "[CHANGEME] ..." and never a stray "[] " — callers pass null on an unconfigured site.
+  assert.equal(renderSubject(null, 'New enquiry', []), 'New enquiry');
+});
+test('renderSubject ASCII-folds the client name too', () => {
+  assert.equal(renderSubject('Café Ltd', 'Enquiry', []), '[Cafe Ltd] Enquiry');
+});
+test('renderSubject sanitises values arriving through placeholders', () => {
+  const subject = renderSubject('Acme', 'Enquiry from {{name}}', [
+    { name: 'name', value: 'Ada\r\nBcc: attacker@example.com' },
+  ]);
+  assert.ok(!/[\r\n]/.test(subject));
+});

package/src/emails/subject.ts ADDED Viewed

@@ -0,0 +1,80 @@
+/*
+ * Subject lines for transactional email.
+ *
+ * FORMAT:  [Client Name] Topic
+ *
+ * The bracketed prefix is applied HERE rather than written into each form's `notify.subject`,
+ * so a form definition only ever states its topic. Putting it in the JSON would make it a
+ * thing to remember for every new form and every new client site, and the first one forgotten
+ * is invisible until a client's inbox rules quietly stop matching.
+ *
+ * The prefix is the CLIENT NAME, not the domain — it is read by a person triaging their inbox,
+ * and "[Steven Glaze]" sorts and scans better than "[stevenglaze.com]".
+ */
+/**
+ * Force a subject fragment to single-line ASCII.
+ *
+ * TWO reasons, and the second one matters more than it looks:
+ *
+ * 1. A non-ASCII subject has to be MIME encoded-word encoded, and anything that fails to
+ *    decode it shows the recipient a raw `=?UTF-8?Q?...?=`. Visitor input reaches this
+ *    string through `{{name}}`-style placeholders, so a smart quote pasted out of Word is
+ *    enough to trigger it.
+ *
+ * 2. A subject is a mail HEADER. A CR or LF inside one is the classic header-injection
+ *    vector — it ends the Subject: header early and lets whatever follows be read as a new
+ *    header (Bcc:, say). Mailgun's form-encoded API makes that unlikely to reach the wire,
+ *    but the correct place to be sure is where untrusted text enters a header, not one layer
+ *    down in someone else's parser.
+ *
+ * Accents are transliterated rather than dropped, so "José" reads as "Jose" and not "Jos".
+ */
+export function toAsciiSubject(value: string): string {
+  return (
+    value
+      // Decompose accented characters into base letter + combining mark, then drop the marks.
+      .normalize('NFKD')
+      .replace(/[̀-ͯ]/g, '')
+      // Punctuation NFKD leaves alone but that is still not ASCII.
+      .replace(/[‘’‚‛]/g, "'")
+      .replace(/[“”„‟]/g, '"')
+      .replace(/[–—―]/g, '-')
+      .replace(/…/g, '...')
+      .replace(/[   ]/g, ' ')
+      // Anything left outside printable ASCII, including CR/LF and other control characters.
+      .replace(/[^\x20-\x7e]/g, '')
+      .replace(/\s+/g, ' ')
+      .trim()
+  );
+}
+/**
+ * Replace `{{field}}` placeholders in a topic template.
+ * An unmatched placeholder becomes an empty string rather than being left visible.
+ */
+export function renderTopic(
+  template: string,
+  fields: Array<{ name: string; value: string }>,
+): string {
+  return template.replace(/\{\{\s*([\w-]+)\s*\}\}/g, (_match, key: string) => {
+    return fields.find((f) => f.name === key)?.value ?? '';
+  });
+}
+/**
+ * Build the full subject line: `[Client Name] Topic`.
+ *
+ * The prefix is omitted entirely rather than rendered as `[CHANGEME]` on an unconfigured
+ * starter — see the callers' handling in src/actions/index.ts.
+ */
+export function renderSubject(
+  client: string | null,
+  topicTemplate: string,
+  fields: Array<{ name: string; value: string }>,
+): string {
+  const topic = toAsciiSubject(renderTopic(topicTemplate, fields));
+  const prefix = client ? toAsciiSubject(client) : '';
+  return prefix ? `[${prefix}] ${topic}`.trim() : topic;
+}

package/src/emails/submission-notification.ts ADDED Viewed

@@ -0,0 +1,76 @@
+/*
+ * The notification email sent to the client when someone submits a form.
+ *
+ * Plain functions returning strings rather than a template engine — an email body is a
+ * string, and adding a dependency to build one would break the vanilla rule for no gain.
+ *
+ * Both a text and an HTML part are produced. Sending both materially improves deliverability;
+ * text-only mail is more likely to be filtered, and HTML-only is worse.
+ *
+ * NO HEADING IN THE BODY. The subject line already says what this is —
+ * `[Client Name] New contact enquiry from Jane` — and repeating it as an <h1> directly under
+ * it just pushes the actual fields further down the preview pane. Subject lines are built by
+ * subject.ts; the shared three-line footer is footer.ts.
+ */
+import { escapeHtml, renderFooterHtml, renderFooterText } from './footer.ts';
+import { DEFAULT_COPY, fill } from '../includes/webmonterey/copy-defaults.ts';
+export interface SubmissionEmailInput {
+  /** Form id, e.g. 'contact'. */
+  form: string;
+  /** Human name of the form, from its definition. */
+  formName: string;
+  /** The submitted fields, in display order. */
+  fields: Array<{ label: string; name: string; value: string }>;
+  /** The client's display name, for the footer's copyright line. */
+  client: string;
+  /** The site's production domain, named in the footer. */
+  domain: string;
+  /** D1 row id, so a specific enquiry can be found later. */
+  submissionId?: number;
+}
+export function renderText(input: SubmissionEmailInput): string {
+  const lines = [...input.fields.map((f) => `${f.label}:\n${f.value || '-'}\n`)];
+  if (input.submissionId !== undefined) {
+    lines.push(`${fill(DEFAULT_COPY.email.reference, { id: input.submissionId ?? '' })}`);
+  }
+  lines.push(renderFooterText({ client: input.client, domain: input.domain }));
+  return lines.join('\n');
+}
+export function renderHtml(input: SubmissionEmailInput): string {
+  const rows = input.fields
+    .map(
+      (f) => `      <tr>
+        <th align="left" style="padding:8px 16px 8px 0;vertical-align:top;color:#3f3f3f;font-weight:600;white-space:nowrap;">${escapeHtml(f.label)}</th>
+        <td style="padding:8px 0;vertical-align:top;color:#222;">${escapeHtml(f.value) || '&mdash;'}</td>
+      </tr>`,
+    )
+    .join('\n');
+  const reference =
+    input.submissionId !== undefined
+      ? `<p style="margin:24px 0 0;color:#3f3f3f;font-size:13px;">${fill(DEFAULT_COPY.email.reference, { id: input.submissionId ?? '' })}</p>`
+      : '';
+  /*
+   * Inline styles and a table layout on purpose. Email clients strip <style> blocks and have
+   * no meaningful CSS support — the site's design tokens cannot be used here.
+   */
+  return `<!doctype html>
+<html>
+  <body style="margin:0;padding:24px;background:#f1eae8;font-family:system-ui,-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;">
+    <div style="max-width:640px;margin:0 auto;padding:32px;background:#fff;border-radius:8px;">
+      <table style="width:100%;border-collapse:collapse;font-size:14px;">
+${rows}
+      </table>
+      ${reference}
+    </div>
+${renderFooterHtml({ client: input.client, domain: input.domain })}
+  </body>
+</html>`;
+}

package/src/env.d.ts ADDED Viewed

@@ -0,0 +1,12 @@
+/// <reference types="astro/client" />
+/// <reference types="@cloudflare/workers-types" />
+/*
+ * Cloudflare's runtime types (D1Database, R2Bucket, KVNamespace) and Astro's virtual modules
+ * (astro:content, astro:actions) are ambient inside a site's build but not inside this package,
+ * where there is no site to generate them from. Referencing them here is what lets `tsc --noEmit`
+ * check the package on its own.
+ *
+ * A client site still gets its own worker-configuration.d.ts from `wrangler types`, which is what
+ * types THAT site's bindings. This file types the shapes the package uses generically.
+ */