@cparkerwebm/webmonterey 1.0.0 → 1.2.0

package/src/pages/webmaster.astro

@@ -0,0 +1,121 @@
+---
+/*
+ * /webmaster - the page every site has, saying who built it and who to call.
+ *
+ * Injected by the integration on every site (with a `webmaster: false` off switch), rendered
+ * through the site's own layout so it carries the client's header, footer and tokens. INDEXABLE
+ * and in the sitemap, on purpose: the footer credit links here rather than off the site, and this
+ * page carries the one outbound link to the agency - a followed link on a real page with real
+ * copy, which is a backlink rather than a footer decoration. It is also the answer to "something
+ * is wrong with the website, who do I contact?" on the site itself.
+ *
+ * Every word is overridable through `copy.webmaster` in webmonterey.json, like everything else
+ * the package puts in front of a visitor.
+ *
+ * ITS OWN STRUCTURED DATA, and the site's is switched off for this route. The graph here is about
+ * the agency - a WebPage whose subject is the agency's Organization, using the same `@id` the
+ * agency's own site declares, so every client page points at one entity rather than a hundred
+ * copies. The site's structuredData component would also emit a WebPage for this URL, and two
+ * nodes claiming the same `@id` is worse than one.
+ *
+ * The share image is served from the package at /webmaster/og.png, so a redesign reaches every
+ * site on `npm update` and nothing has to be seeded into public/. Its og:image dimensions are
+ * measured from the file by the integration, never typed in.
+ */
+import Base from '../layouts/base.astro';
+import { copy } from '../includes/webmonterey/copy.ts';
+import {
+  AGENCY,
+  creditUrl,
+  WEBMASTER_OG_PATH,
+} from '../includes/webmonterey/webmaster/webmaster.ts';
+import { domain, hasDomain } from '../includes/webmonterey/site.ts';
+import { compact, renderJsonLd } from '../includes/webmonterey/structured-data/nodes.ts';
+import { pageHeader } from 'virtual:webm/registry';
+import ogImage from 'virtual:webm/webmaster-og';
+import build from 'virtual:webm/build';
+
+const PageHeader = pageHeader;
+const text = copy.webmaster;
+const agencyHref = hasDomain ? creditUrl(domain, 'website') : AGENCY.url;
+
+/*
+ * The graph needs a real origin for stable @id values, which is the same gate the canonical tag
+ * and the site's own structured data use. Until `domain` is set there is no page @id to claim.
+ */
+let jsonLd: string | null = null;
+/* No graph on a preview: the page is noindex there and an @id on a workers.dev host is noise. */
+if (Astro.site && !build.preview) {
+  const url = new URL(Astro.url.pathname, Astro.site).href;
+  jsonLd = renderJsonLd([
+    compact({
+      '@type': 'WebPage',
+      '@id': `${url}#webpage`,
+      url,
+      name: text.title,
+      description: text.description,
+      isPartOf: { '@id': new URL('#website', Astro.site).href },
+      about: { '@id': AGENCY.id },
+      inLanguage: 'en',
+    }),
+    compact({
+      '@type': 'ProfessionalService',
+      '@id': AGENCY.id,
+      name: AGENCY.name,
+      url: AGENCY.url,
+      description: AGENCY.description,
+      address: { '@type': 'PostalAddress', ...AGENCY.address },
+      sameAs: [...AGENCY.sameAs],
+    }),
+  ]);
+}
+---
+
+<Base
+  title={text.title}
+  description={text.description}
+  shareImage={WEBMASTER_OG_PATH}
+  shareImageWidth={ogImage.width}
+  shareImageHeight={ogImage.height}
+  structuredData={false}
+>
+  <Fragment slot="head">
+    {jsonLd && <script type="application/ld+json" set:html={jsonLd} />}
+  </Fragment>
+
+  {
+    /*
+     * The site's page header if it declares one, so this page looks like every other page on the
+     * site; the router's plain <h1> otherwise. Same fallback the block router uses.
+     */
+    PageHeader ? (
+      <PageHeader title={text.title} description={text.description} />
+    ) : (
+      <section class="webm-section" data-space="sm">
+        <div class="webm-container" data-width="text">
+          <h1>{text.title}</h1>
+        </div>
+      </section>
+    )
+  }
+
+  <section class="webm-section" data-space="lg">
+    <div class="webm-container" data-width="text">
+      <div class="webm-stack">
+        {
+          /*
+           * The agency is named as a link in the first paragraph - the one outbound link on the
+           * site, followed, with the UTM parameters. Opens in a new tab because it leaves the
+           * site; noopener without noreferrer, because the referrer is the attribution.
+           */
+        }
+        <p>
+          {text.intro.before}
+          <a href={agencyHref} target="_blank" rel="noopener">{AGENCY.name}</a>
+          {text.intro.after}
+        </p>
+        {text.body.map((paragraph) => <p>{paragraph}</p>)}
+      </div>
+    </div>
+  </section>
+</Base>

package/template/migrations/README.md

@@ -35,7 +35,7 @@ Wrangler tracks applied migrations in a `d1_migrations` table inside the databas
 The database must exist and be bound in `wrangler.jsonc`:
 
 ```sh
-npx wrangler d1 create webm-<domain-dashed>-db --update-config
+npx wrangler d1 create <slug> --update-config
 ```
 
 `--update-config` writes the `d1_databases` binding into `wrangler.jsonc` for you.

package/template/scripts/test-hooks.mjs

@@ -5,7 +5,7 @@
  * would otherwise force a choice between "no tests" and "rewrite every import in the app to
  * suit the test runner". The app wins that argument, so the adaptation lives here.
  *
- *   1. EXTENSIONLESS RELATIVE IMPORTS — `from '../credits/credit'`. Node ESM requires the
+ *   1. EXTENSIONLESS RELATIVE IMPORTS — `from '../webmaster/webmaster'`. Node ESM requires the
  *      extension; bundlers resolve it. The resolve hook appends `.ts` when the bare specifier
  *      does not resolve but the `.ts` file exists.
  *

package/template/site/CLAUDE.md

@@ -103,8 +103,12 @@ Private data — user logins, form submissions — goes to **Cloudflare D1**, ne
 
 ### 5. The prefix is `webm-`, never `wm-`
 
-Custom properties (`--webm-action`), class names (`.webm-section`), Cloudflare resource names
-(`webm-<slug>`), the CLI, the skills namespace. No exceptions.
+Custom properties (`--webm-action`), class names (`.webm-section`), the CLI, the skills
+namespace. No exceptions.
+
+Cloud resources are the other convention: the GitHub repo, Worker, D1, R2 and KV all carry **one
+name**, the domain minus its TLD (`example.com` → `example`). A second resource of one kind takes
+a purpose suffix (`example-portal`).
 
 ### 6. Cloudflare bindings come from `cloudflare:workers`
 

package/src/includes/webmonterey/credits/Credit.astro

@@ -1,80 +0,0 @@
----
-/*
- * The WebMonterey agency credit. Goes in the site footer.
- *
- *   <Credit />   ->   Powered by WebMonterey
- *
- * The wording and the UTM-tagged link both come from credit.ts, which the email footer also
- * imports — the two surfaces must say the same thing, and email cannot reuse this component
- * (scoped CSS does not survive an email client).
- */
-import { CREDIT_TEXT, creditUrl } from './credit.ts';
-import { domain, hasDomain } from '../site.ts';
-
-interface Props {
-  class?: string;
-}
-
-const { class: className } = Astro.props;
-
-// Fail loudly at build rather than emit a credit link pointing at a placeholder.
-if (!hasDomain) {
-  throw new Error(
-    '[webm] webmonterey.json "domain" is still CHANGEME. Set the production domain - the ' +
-      'agency credit link uses it for utm_content attribution.',
-  );
-}
-
-const href = creditUrl(domain, 'website');
----
-
-<p class:list={['webm-credit', className]}>
-  {
-    /*
-    OPENS IN A NEW TAB, and `target` is the half that was missing.
-
-    This element carried `rel="noopener"` and no `target`, which does nothing at all - noopener
-    only means anything alongside a target - and the credit navigated away from the client's site
-    in the same tab. Verified broken on live client sites before this was fixed.
-
-    `noopener` stays: without it the opened page gets a `window.opener` handle back into this one.
-    Deliberately NOT `noreferrer` - the referrer is the attribution, and stripping it would leave
-    only the utm_content.
-
-    The visually-hidden note is not decoration. A link that moves the user to another tab without
-    saying so is a semantics bug, and semantics are correctness rather than styling. The email
-    footer deliberately does NOT carry it - the hiding technique needs a stylesheet, and email
-    clients strip those. See emails/footer.ts.
-
-    NO `title` ATTRIBUTE, and that is the correct state rather than an omission. `title` 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
-    plus the hidden note IS the accessible name.
-  */
-  }
-  <a href={href} target="_blank" rel="noopener">
-    {CREDIT_TEXT}<span class="webm-visually-hidden"> (opens in a new tab)</span>
-  </a>
-</p>
-
-<style>
-  @layer webm.components.core {
-    .webm-credit {
-      font-size: var(--webm-font-size-xs);
-      color: var(--webm-text-muted);
-    }
-
-    /*
-     * Underline at the text's own color. An underline in --webm-border-subtle is ~1.3:1 on
-     * white — effectively invisible, leaving nothing to mark the link as clickable.
-     */
-    .webm-credit a {
-      color: inherit;
-      text-decoration-color: currentColor;
-    }
-
-    .webm-credit a:hover {
-      color: var(--webm-link-hover);
-    }
-  }
-</style>

package/src/includes/webmonterey/credits/credit.test.ts

@@ -1,111 +0,0 @@
-import { test } from 'node:test';
-import assert from 'node:assert/strict';
-import { readFileSync } from 'node:fs';
-
-import { contentTag, CREDIT_TEXT, creditUrl } from './credit.ts';
-
-/*
- * Credit.astro read as SOURCE, because it cannot be imported here: it pulls in ../site.ts, which
- * imports virtual:webm/site, which only resolves inside an Astro build. A source assertion is the
- * weaker tool and it is the one available - and the alternative in place until now was nothing.
- *
- * WHY IT NEEDS ONE AT ALL. This anchor once carried rel="noopener" and no target, which does
- * nothing whatsoever - noopener only means anything alongside a target - so the credit navigated
- * the visitor away from the client's site in the same tab. That shipped to live sites. The
- * regression test written afterwards guards the EMAIL footer, in emails/footer.test.ts; the
- * component where the bug actually happened had no test until this one.
- */
-const componentSource = readFileSync(new URL('./Credit.astro', import.meta.url), 'utf8');
-/** The template with its {/* *\/} comment blocks removed, so prose about the rule is not read as the rule. */
-const template = componentSource.replace(/\{\s*\/\*[\s\S]*?\*\/\s*\}/g, '');
-const anchors: string[] = template.match(/<a\s[^>]*>/g) ?? [];
-/** The single credit anchor. Asserted to be the only one below. */
-const anchor = (): string => anchors[0] ?? '';
-
-test('creditUrl points at the main site, not a /credits page', () => {
-  const url = new URL(creditUrl('example.com'));
-  assert.equal(url.origin, 'https://webmonterey.com');
-  assert.equal(url.pathname, '/', 'the credit link must not reintroduce a /credits path');
-});
-
-test('creditUrl carries all four UTM parameters', () => {
-  const { searchParams } = new URL(creditUrl('example.com'));
-  assert.equal(searchParams.get('utm_source'), 'client');
-  assert.equal(searchParams.get('utm_campaign'), 'credits');
-  assert.equal(searchParams.get('utm_content'), 'example_com');
-});
-
-test('utm_medium separates the two surfaces', () => {
-  const site = new URL(creditUrl('example.com', 'website'));
-  const email = new URL(creditUrl('example.com', 'email'));
-  assert.equal(site.searchParams.get('utm_medium'), 'website');
-  assert.equal(email.searchParams.get('utm_medium'), 'email');
-});
-
-test('utm_medium defaults to website', () => {
-  assert.equal(new URL(creditUrl('example.com')).searchParams.get('utm_medium'), 'website');
-});
-
-test('utm_content is the production domain, with every dot as an underscore', () => {
-  // Not the host the page is served from — a preview build must not fragment attribution.
-  const url = new URL(creditUrl('sub.example.co.uk', 'email'));
-  assert.equal(url.searchParams.get('utm_content'), 'sub_example_co_uk');
-});
-
-test('both surfaces tag the same client the same way', () => {
-  const site = new URL(creditUrl('example.com', 'website'));
-  const email = new URL(creditUrl('example.com', 'email'));
-  assert.equal(site.searchParams.get('utm_content'), email.searchParams.get('utm_content'));
-});
-
-test('no dot survives into the credit URL, so nothing can linkify it', () => {
-  const url = new URL(creditUrl('example.com', 'email'));
-  assert.equal(url.searchParams.get('utm_content'), 'example_com');
-  /*
-   * Scoped to the QUERY STRING, not the whole URL: the destination host is webmonterey.com
-   * and is allowed to look like a host. It is the parameter value that must not.
-   */
-  assert.equal(url.search.includes('.'), false);
-});
-
-test('contentTag leaves a domain that has no dots alone', () => {
-  assert.equal(contentTag('localhost'), 'localhost');
-});
-
-test('contentTag changes nothing but the dots', () => {
-  // The value still has to be recognisably the site it came from in the report.
-  assert.equal(contentTag('steven-glaze.com'), 'steven-glaze_com');
-});
-
-test('CREDIT_TEXT is the shared wording', () => {
-  assert.equal(CREDIT_TEXT, 'Powered by WebMonterey');
-});
-
-/* ── the footer credit's link, mirroring emails/footer.test.ts ────────────────────────────── */
-
-test('the site credit renders exactly one link', () => {
-  assert.equal(anchors.length, 1, `expected one anchor, found ${anchors.length}`);
-});
-
-test('the site credit opens in a new tab', () => {
-  // The half that was missing. Without it the visitor leaves the client's site to read ours.
-  assert.match(anchor(), /target="_blank"/);
-});
-
-test('the new tab cannot reach back into the client page', () => {
-  assert.match(anchor(), /rel="[^"]*noopener/);
-});
-
-/*
- * Locking a decision rather than an implementation detail: the referrer IS the attribution, so
- * stripping it would leave only utm_content. This is the kind of thing someone adds in good faith
- * while "hardening" a target=_blank link.
- */
-test('the credit link deliberately does not send noreferrer', () => {
-  assert.doesNotMatch(anchor(), /noreferrer/);
-});
-
-test('the new tab is announced, not just implemented', () => {
-  // A link that moves the user to another tab without saying so is a semantics bug.
-  assert.match(template, /webm-visually-hidden[^>]*>\s*\(opens in a new tab\)/);
-});

package/src/includes/webmonterey/credits/credit.ts

@@ -1,59 +0,0 @@
-/*
- * The agency credit's wording and link, in ONE place.
- *
- * Two surfaces render this credit and they cannot share a component: the site footer is an
- * .astro component with scoped CSS, and transactional email is a string with inline styles
- * (email clients strip <style> blocks). Without this module the wording exists twice, and the
- * next time it changes one copy gets missed — which is exactly how "a WebMonterey website"
- * would have survived in email after the footer moved to "Powered by WebMonterey".
- *
- * utm_content is ALWAYS the production domain from webmonterey.json, never the host the page
- * happens to be served from. A preview build at `feature-x-webm-example-com.workers.dev`
- * still reports the client's own domain, so staging traffic does not fragment the attribution.
- *
- * IT IS WRITTEN WITH UNDERSCORES — `example_com`, not `example.com`. A dot makes the value look
- * like a hostname, and analytics UIs read it as one rather than as the label it is. Underscores
- * keep it a label. Every dot goes, subdomains included: `sub.example.co.uk` is `sub_example_co_uk`.
- *
- * This comment used to also claim a mail client would linkify `example.com` inside the query
- * string and truncate the URL there. That does not apply: auto-linkification acts on plain text,
- * and here the URL only ever appears inside an href. Corrected rather than deleted, because a
- * justification that does not survive scrutiny invites someone to reverse the decision it
- * defends — and the analytics reason on its own is enough.
- *
- * The link points at the WebMonterey home page, not a /credits landing page. The UTM
- * parameters carry the whole story, so the destination stays the main site and there is no
- * separate page to keep alive. utm_medium is what separates the two surfaces: `website` from
- * the footer, `email` from a transactional template.
- */
-
-/** The credit wording. Rendered verbatim on the site and in email. */
-export const CREDIT_TEXT = 'Powered by WebMonterey';
-
-/**
- * Which surface the click came from. Kept separate from utm_content so the report can tell
- * a footer click from an email click without splitting it per client.
- */
-export type CreditMedium = 'website' | 'email';
-
-/**
- * The client's domain as a UTM label rather than as a domain. Dots only — the value is
- * otherwise left exactly as webmonterey.json wrote it, so what lands in the report is still
- * recognisably the site it came from.
- */
-export function contentTag(domain: string): string {
-  return domain.replace(/\./g, '_');
-}
-
-/** The attributed credit link for one client site. */
-export function creditUrl(domain: string, medium: CreditMedium = 'website'): string {
-  const params = new URLSearchParams({
-    utm_source: 'client',
-    utm_medium: medium,
-    utm_campaign: 'credits',
-    /* See the note above: a dot here is a link waiting to be made out of the query string. */
-    utm_content: contentTag(domain),
-  });
-
-  return `https://webmonterey.com/?${params}`;
-}