@cparkerwebm/webmonterey 1.2.0 → 1.4.0

package/src/cli/settings.ts

@@ -0,0 +1,106 @@
+/*
+ * The Claude Code project settings a client repo carries, and the one list of what they deny.
+ *
+ * WHY A MODULE, like mcp.ts. Three places have to agree about these rules: the scaffold writes
+ * them into a new site, `webm sync` merges any that are missing into an existing site on every
+ * install, and the tests assert both against this list rather than a literal that falls one
+ * behind. `.claude/settings.json` is otherwise the site's own - a client adds allow rules to it -
+ * so it is MERGED, never replaced: the package's deny rules are added when absent and everything
+ * else in the file is left exactly as found.
+ *
+ * WHAT THE DENY RULES ENFORCE. Two things a session in a client repo must never do, made
+ * mechanical rather than advisory:
+ *
+ *   - read a secret. .env, .dev.vars, keys, the npm config.
+ *   - edit the package. Rule 12 of the site's CLAUDE.md: a session in a client repo never edits
+ *     the package, not in node_modules and not in its checkout. The deliverable for an upstream
+ *     problem is a description of the fix, run later in the package repo.
+ *
+ * THE SYNTAX, verified against code.claude.com/docs/en/permissions rather than recalled:
+ *
+ *   - Read and Edit rules take gitignore patterns. As a DENY rule, `Edit(**\/node_modules/**)`
+ *     matches a node_modules directory at any depth under the working directory.
+ *   - `Edit` rules apply to every built-in tool that edits files - Edit, Write, MultiEdit and
+ *     NotebookEdit. A `Write(...)` rule is accepted, never consulted, and warned about at
+ *     startup, which is why none appears here and why the two that 1.2.0 scaffolded are removed.
+ *   - A `Read` deny also blocks Edit and Write on the same path. The Edit rules for the secret
+ *     files are therefore redundant, and kept: they say what is meant.
+ *   - THERE IS NO PATTERN FOR "ANY PATH OUTSIDE THE PROJECT". A rule names a path - `//absolute`,
+ *     `~/home-relative`, `/project-relative`, or cwd-relative - and nothing expresses the
+ *     complement of one. The package checkout sitting beside a client repo on the same machine
+ *     cannot be denied by rule without hardcoding where it is, and a public package does not
+ *     know. Rule 12 in CLAUDE.md carries that half in prose.
+ */
+
+import { MCP_NAMES } from './mcp.ts';
+
+/** Every rule a site's settings must deny. Order is the order they are written. */
+export const DENY_RULES: readonly string[] = [
+  'Read(**/.dev.vars)',
+  'Read(**/.dev.vars.*)',
+  'Read(**/.env)',
+  'Read(**/.env.*)',
+  'Read(**/*.pem)',
+  'Read(**/*.key)',
+  'Read(**/.npmrc)',
+  'Edit(**/.dev.vars)',
+  'Edit(**/.env)',
+  'Edit(**/node_modules/**)',
+];
+
+/**
+ * Rules an earlier scaffold wrote that Claude Code never consults and warns about at startup.
+ * Removed on sync, by exact string, so a rule the site wrote itself is never touched.
+ */
+export const STALE_RULES: readonly string[] = ['Write(**/.dev.vars)', 'Write(**/.env)'];
+
+const PERMISSIONS_NOTE =
+  'The deny list is package-managed: `webm sync` adds any rule that is missing on every ' +
+  'install and leaves everything else in this file alone. Edit(**/node_modules/**) is rule 12 ' +
+  'of CLAUDE.md made mechanical - a session in this repo never edits the package.';
+
+/** The whole file, for a new site. */
+export function projectSettings(repo: string): Record<string, unknown> {
+  return {
+    '//': `Project settings for ${repo}.`,
+    '//mcp':
+      'A server declared in .mcp.json is INERT until approved on each machine. Without this line the rules that say consult the Astro and MDN docs before using an API would depend on whoever cloned the repo happening to hit Approve.',
+    includeCoAuthoredBy: false,
+    enabledMcpjsonServers: [...MCP_NAMES],
+    '//permissions': PERMISSIONS_NOTE,
+    permissions: { deny: [...DENY_RULES] },
+  };
+}
+
+/**
+ * An existing settings file with the package's deny rules present and the stale ones gone.
+ *
+ * IDEMPOTENT, and additive everywhere else: a second pass reports nothing and changes nothing,
+ * and a rule the site added itself - an allow list, a deny of its own - survives untouched. The
+ * site's own rules keep their order; the package's are appended in DENY_RULES order.
+ */
+export function withDenyRules(settings: Record<string, unknown>): {
+  settings: Record<string, unknown>;
+  added: string[];
+  removed: string[];
+} {
+  const permissions =
+    settings.permissions && typeof settings.permissions === 'object'
+      ? { ...(settings.permissions as Record<string, unknown>) }
+      : {};
+  const current = Array.isArray(permissions.deny)
+    ? (permissions.deny as unknown[]).filter((r): r is string => typeof r === 'string')
+    : [];
+
+  const removed = current.filter((r) => STALE_RULES.includes(r));
+  const kept = current.filter((r) => !STALE_RULES.includes(r));
+  const added = DENY_RULES.filter((r) => !kept.includes(r));
+  if (!added.length && !removed.length) return { settings, added, removed };
+
+  permissions.deny = [...kept, ...added];
+  return {
+    settings: { ...settings, '//permissions': PERMISSIONS_NOTE, permissions },
+    added,
+    removed,
+  };
+}

package/src/cli/sync.test.ts

@@ -11,6 +11,7 @@ import {
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { sync } from './sync.ts';
+import { DENY_RULES, STALE_RULES } from './settings.ts';
 
 const site = () => mkdtempSync(join(tmpdir(), 'webm-sync-'));
 
@@ -43,6 +44,7 @@ test('the package ships exactly the skills the release claims', () => {
     'start',
     'traps',
     'upgrade',
+    'webmaster',
   ]);
 });
 
@@ -135,3 +137,63 @@ test('the migrations README rides along, so the --remote trap is documented in t
   sync(dir);
   assert.match(readFileSync(join(dir, 'migrations', 'README.md'), 'utf8'), /--remote/);
 });
+
+test('the package deny rules are MERGED into .claude/settings.json, never replacing it', () => {
+  const dir = site();
+  mkdirSync(join(dir, '.claude'), { recursive: true });
+  const path = join(dir, '.claude/settings.json');
+  writeFileSync(
+    path,
+    JSON.stringify({
+      '//': 'theirs',
+      enabledMcpjsonServers: ['astro-docs'],
+      permissions: {
+        allow: ['Bash(npm run *)'],
+        deny: ['Read(**/.env)', 'Write(**/.env)', 'Edit(/secrets/**)'],
+      },
+    }),
+  );
+
+  const first = sync(dir);
+  const written = JSON.parse(readFileSync(path, 'utf8'));
+  assert.ok(first.settings.added.includes('Edit(**/node_modules/**)'), 'rule 12 lands');
+  assert.deepEqual(first.settings.removed, ['Write(**/.env)'], 'the rule Claude Code warns about');
+  assert.equal(written['//'], 'theirs');
+  assert.deepEqual(written.enabledMcpjsonServers, ['astro-docs'], 'not touched by this');
+  assert.deepEqual(
+    written.permissions.allow,
+    ['Bash(npm run *)'],
+    "the site's allow list survives",
+  );
+  assert.ok(written.permissions.deny.includes('Edit(/secrets/**)'), "the site's own deny survives");
+  for (const rule of DENY_RULES) assert.ok(written.permissions.deny.includes(rule), rule);
+  for (const rule of STALE_RULES) assert.ok(!written.permissions.deny.includes(rule), rule);
+  assert.equal(
+    written.permissions.deny.filter((r: string) => r === 'Read(**/.env)').length,
+    1,
+    'a rule already there is not doubled',
+  );
+
+  /* Idempotent: the second pass reports nothing and rewrites nothing. */
+  const before = readFileSync(path, 'utf8');
+  const second = sync(dir);
+  assert.deepEqual(second.settings, { added: [], removed: [], created: false, skipped: null });
+  assert.equal(readFileSync(path, 'utf8'), before);
+});
+
+test('a site with no settings file gets the scaffold defaults', () => {
+  const dir = site();
+  const result = sync(dir);
+  assert.equal(result.settings.created, true);
+  const written = JSON.parse(readFileSync(join(dir, '.claude/settings.json'), 'utf8'));
+  assert.deepEqual(written.permissions.deny, [...DENY_RULES]);
+});
+
+test('a settings file that will not parse is left alone and reported', () => {
+  const dir = site();
+  mkdirSync(join(dir, '.claude'), { recursive: true });
+  writeFileSync(join(dir, '.claude/settings.json'), '{ not json');
+  const result = sync(dir);
+  assert.ok(result.settings.skipped);
+  assert.equal(readFileSync(join(dir, '.claude/settings.json'), 'utf8'), '{ not json');
+});

package/src/cli/sync.ts

@@ -26,6 +26,9 @@
  *                                  a real D1 database must NEVER change - SQLite has already run
  *                                  it and wrangler tracks it by name. Later versions add 0002,
  *                                  they do not rewrite 0001.
+ *   MERGE     .claude/settings.json The package's deny rules are added when absent and the file
+ *                                  is otherwise left as found - a client's allow list is theirs.
+ *                                  See cli/settings.ts for the rules and why they are rules.
  *   SEED      public/, content     Written once by `webm new` and then the client's outright.
  *                                  Not handled here at all - see cli/scaffold.ts.
  *
@@ -46,8 +49,9 @@ import {
   writeFileSync,
   readdirSync,
 } from 'node:fs';
-import { basename, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { PACKAGE_ROOT, packageVersion } from './package-root.ts';
+import { DENY_RULES, projectSettings, withDenyRules } from './settings.ts';
 
 /**
  * The namespace. Rule 5's prefix: the CLI is `webm`, the tokens are --webm-*, the classes are
@@ -68,6 +72,11 @@ interface SyncResult {
   workflows: string[];
   /** Migrations copied because the site did not have them. Never includes an existing file. */
   migrations: string[];
+  /**
+   * What changed in .claude/settings.json: deny rules added, stale ones removed, the file
+   * created when there was none, or why it was left alone.
+   */
+  settings: { added: string[]; removed: string[]; created: boolean; skipped: string | null };
 }
 
 /**
@@ -119,6 +128,46 @@ function addMissing(source: string, target: string): string[] {
   return added.sort();
 }
 
+/**
+ * MERGE. The package's deny rules into the site's settings, and nothing else.
+ *
+ * `.claude/settings.json` is the site's: a client adds allow rules to it, and a full replace would
+ * throw those away on the next install. So the file is read, the rules in cli/settings.ts are
+ * added where absent, the two rules Claude Code warns about at startup are dropped, and the file
+ * is written back only when that changed something - a second pass is a no-op. A file that will
+ * not parse is left exactly as it is and reported: Claude Code cannot read it either, and
+ * rewriting it would hide that.
+ *
+ * Created from the scaffold's defaults when there is none, so a site that predates the file gets
+ * the rules on its next install rather than never.
+ */
+function ensureSettings(siteRoot: string): SyncResult['settings'] {
+  const path = join(siteRoot, '.claude', 'settings.json');
+  if (!existsSync(path)) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(projectSettings(basename(siteRoot)), null, 2) + '\n');
+    return { added: [...DENY_RULES], removed: [], created: true, skipped: null };
+  }
+
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>;
+  } catch {
+    return {
+      added: [],
+      removed: [],
+      created: false,
+      skipped: '.claude/settings.json is not valid JSON, so it was left alone',
+    };
+  }
+
+  const { settings, added, removed } = withDenyRules(parsed);
+  if (added.length || removed.length) {
+    writeFileSync(path, JSON.stringify(settings, null, 2) + '\n');
+  }
+  return { added, removed, created: false, skipped: null };
+}
+
 function listSkills(dir: string): string[] {
   if (!existsSync(dir)) return [];
   return readdirSync(dir, { withFileTypes: true })
@@ -207,6 +256,7 @@ export function sync(siteRoot: string): SyncResult {
      */
     workflows: syncDir(join(template, 'workflows'), join(siteRoot, '.github/workflows')),
     migrations: addMissing(join(template, 'migrations'), join(siteRoot, 'migrations')),
+    settings: ensureSettings(siteRoot),
   };
 }
 
@@ -245,6 +295,19 @@ export function run(argv: string[]): number {
   for (const m of result.migrations) {
     console.log(`  + migrations/${m}  (apply it: npx wrangler d1 migrations apply <DB> --remote)`);
   }
+  if (result.settings.created) {
+    console.log(`  + .claude/settings.json`);
+  } else if (result.settings.skipped) {
+    console.log(`  ${result.settings.skipped}`);
+  } else if (result.settings.added.length || result.settings.removed.length) {
+    const parts = [
+      result.settings.added.length && `+${result.settings.added.length} deny`,
+      result.settings.removed.length && `-${result.settings.removed.length} stale`,
+    ].filter(Boolean);
+    console.log(
+      `  .claude/settings.json: ${parts.join(', ')} (package-managed rules; yours are kept)`,
+    );
+  }
 
   if (ensureGitignored(siteRoot)) {
     console.log(`  gitignored .claude/skills/${NAMESPACE}/`);

package/src/includes/webmonterey/config.test.ts

@@ -3,9 +3,11 @@ import assert from 'node:assert/strict';
 import {
   APP_DIR,
   isConfigured,
+  isPreviewBuild,
   isStagingDeployment,
   isValidTimeZone,
   PLACEHOLDER,
+  previewReason,
   resolveAppPath,
   resolveDisplayName,
   workerFirstPaths,
@@ -92,3 +94,52 @@ test('shortName falls back to the display name when unset', () => {
   assert.equal(isConfigured('FoML'), true);
   assert.equal(isConfigured(''), false);
 });
+
+/* --- preview builds ------------------------------------------------------ */
+
+test('a staging site is a preview with no branch at all - the laptop build', () => {
+  assert.equal(isPreviewBuild({ environment: 'staging', branch: null }), true);
+  assert.equal(previewReason({ environment: 'staging', branch: null }), 'staging');
+});
+
+test('a staging site is a preview on main - the case that was crawlable', () => {
+  /* autire.webmonterey.workers.dev: main on Workers Builds, environment staging, and indexable
+   * because only a non-production BRANCH used to be a preview. */
+  assert.equal(isPreviewBuild({ environment: 'staging', branch: 'main' }), true);
+  assert.equal(previewReason({ environment: 'staging', branch: 'main' }), 'staging');
+});
+
+test('a production site with no branch is production output', () => {
+  assert.equal(isPreviewBuild({ environment: 'production', branch: null }), false);
+  assert.equal(previewReason({ environment: 'production', branch: null }), null);
+});
+
+test('a production site on main is production output', () => {
+  assert.equal(isPreviewBuild({ environment: 'production', branch: 'main' }), false);
+});
+
+test('a feature branch of a production site is still a preview', () => {
+  /* webmonterey.json is committed, so the branch inherits production from main. The branch rule
+   * is what keeps a launched site's review links out of the index. */
+  assert.equal(isPreviewBuild({ environment: 'production', branch: 'feature/x' }), true);
+  assert.equal(previewReason({ environment: 'production', branch: 'feature/x' }), 'branch');
+});
+
+test('productionBranch renames which branch is production', () => {
+  const on = { environment: 'production', productionBranch: 'release' } as const;
+  assert.equal(isPreviewBuild({ ...on, branch: 'release' }), false);
+  assert.equal(isPreviewBuild({ ...on, branch: 'main' }), true);
+});
+
+test('staging wins over the production branch, whatever it is called', () => {
+  assert.equal(
+    previewReason({ environment: 'staging', branch: 'release', productionBranch: 'release' }),
+    'staging',
+  );
+});
+
+test('an unset environment is production, so a site predating the field builds as before', () => {
+  assert.equal(isPreviewBuild({ environment: undefined, branch: null }), false);
+  assert.equal(isPreviewBuild({ environment: undefined, branch: 'main' }), false);
+  assert.equal(isPreviewBuild({ environment: undefined, branch: 'feature/x' }), true);
+});

package/src/includes/webmonterey/config.ts

@@ -125,6 +125,14 @@ export interface SiteConfig {
    * Read it anywhere via `environment`, `isStaging` and `isProduction` from webmonterey/site.
    * The first consumer is transactional email, which redirects every recipient to `stagingEmail`
    * on a staging deployment rather than mailing the client's real contacts from a preview.
+   *
+   * THE SECOND CONSUMER IS INDEXABILITY. A staging site is a PREVIEW BUILD on every hostname and
+   * in every build - laptop, `main` on Workers Builds, anywhere: every page is noindex with no
+   * canonical, there is no sitemap, robots.txt disallows everything, and Google Tag Manager does
+   * not load. Until this switch existed a site that had not launched was crawlable on its
+   * workers.dev URL the moment `main` deployed, because only a non-production BRANCH was a
+   * preview. See `isPreviewBuild`. Flipping this to production is therefore what makes a site
+   * indexable, which is why /webm:launch does it only once the custom domain is live.
    */
   environment?: 'production' | 'staging';
 
@@ -344,3 +352,44 @@ export function isStagingDeployment(
   /* Match the label, not a substring: a client domain ending "notworkers.dev" is not a preview. */
   return Boolean(hostname && /(^|\.)workers\.dev$/i.test(hostname));
 }
+
+/** Which signal made a build a preview, or null for production output. */
+export type PreviewReason = 'staging' | 'branch' | null;
+
+/**
+ * Why this build is a preview - noindex on every page, no canonical, no sitemap, robots.txt
+ * disallowing everything, no analytics - or null when it is production output.
+ *
+ * TWO INDEPENDENT SIGNALS, for the same reason `isStagingDeployment` has two.
+ *
+ * `environment` is what the deployment is FOR. A site that has not launched says `staging`, and
+ * a site that has not launched must not be indexable ANYWHERE: not on a feature branch, not on
+ * `main`, not from a laptop. Before this signal existed only a non-production branch was a
+ * preview, so `main` on Workers Builds was production output for every site that had not gone
+ * live yet - indexable pages with a canonical, a sitemap and `Allow: /` on a public workers.dev
+ * hostname. autire.webmonterey.workers.dev was crawlable that way.
+ *
+ * The branch covers the opposite case: webmonterey.json is committed, so a feature branch of a
+ * LAUNCHED site inherits `production` from main and would build indexable pages under a review
+ * URL. Workers Builds injects WORKERS_CI_BRANCH; anything other than the production branch is a
+ * preview whatever the config says.
+ *
+ * An unset environment is production, as it is everywhere else - see SiteConfig.environment for
+ * why that default is the safe one - so a site predating the field builds exactly as before.
+ * `branch` is null when nothing injected one, which is every laptop build.
+ */
+export function previewReason(input: {
+  environment: SiteConfig['environment'] | undefined;
+  branch: string | null | undefined;
+  productionBranch?: string;
+}): PreviewReason {
+  if (input.environment === 'staging') return 'staging';
+  const branch = input.branch ?? null;
+  if (branch !== null && branch !== (input.productionBranch ?? 'main')) return 'branch';
+  return null;
+}
+
+/** Whether this build is a preview. `previewReason` says which signal decided it. */
+export function isPreviewBuild(input: Parameters<typeof previewReason>[0]): boolean {
+  return previewReason(input) !== null;
+}

package/src/includes/webmonterey/copy-defaults.ts

@@ -67,7 +67,10 @@ export interface Copy {
     /** `{domain}` is replaced with the site's domain. */
     footerNotice: string;
   };
-  /** The /webmaster page. `intro` wraps the agency link: `before` <a>WebMonterey</a> `after`. */
+  /**
+   * The /webmaster page. `intro` wraps the agency link: `before` <a>WebMonterey</a> `after`.
+   * `intro` and `body` take the inline prose subset - `**bold**`, `_italic_`, `[text](/url)`.
+   */
   webmaster: {
     title: string;
     description: string;
@@ -135,14 +138,15 @@ export const DEFAULT_COPY: Copy = {
   webmaster: {
     title: 'Our Webmaster',
     description:
-      'This website was designed, built and managed by WebMonterey, a webmaster maintenance service in Monterey, California.',
+      'This custom website was designed, built and managed by WebMonterey, a webmaster service in Monterey, California.',
     intro: {
-      before: 'This website was designed, built and managed by',
+      before: 'This custom website was designed, built and managed by',
       after:
-        ', a webmaster maintenance service in Monterey, California. WebMonterey handles the hosting, security, updates and ongoing care of the site so that we can focus on what we do.',
+        ', a webmaster service in Monterey, California. WebMonterey handles the hosting, security, strategy and ongoing care of the site so that we can focus on what we do.',
     },
+    /* Bold on purpose: the contact instruction is the paragraph a visitor with a problem needs. */
     body: [
-      "If you have a question about this website, notice something that isn't working, or have trouble using a page, please let WebMonterey know and they will take care of it.",
+      "**If you have a question about this website, notice something that isn't working, or have trouble using a page, please let WebMonterey know and they will take care of it.**",
     ],
   },
 };

package/src/includes/webmonterey/webmaster/webmaster.test.ts

@@ -2,7 +2,15 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { readFileSync } from 'node:fs';
 
-import { AGENCY, contentTag, CREDIT_TEXT, creditUrl, WEBMASTER_PATH } from './webmaster.ts';
+import {
+  AGENCY,
+  contentTag,
+  CREDIT_TEXT,
+  creditUrl,
+  introHtml,
+  webmasterPageProps,
+  WEBMASTER_PATH,
+} from './webmaster.ts';
 
 /*
  * Webmaster.astro read as SOURCE, because it cannot be imported here: an .astro file only
@@ -72,3 +80,55 @@ test('an internal link does not open a new tab and carries no rel', () => {
   assert.doesNotMatch(anchor(), /rel=/);
   assert.doesNotMatch(template, /opens in a new tab/);
 });
+
+/* ── the intro paragraph, as one HTML string for a site that owns the layout ─────────────── */
+
+test('introHtml is before, a space, the agency link, then after', () => {
+  const html = introHtml({ before: 'Built by', after: ', a service.' }, 'https://x.test/?a=1&b=2');
+  assert.equal(
+    html,
+    'Built by <a href="https://x.test/?a=1&amp;b=2" target="_blank" rel="noopener">WebMonterey</a>, a service.',
+  );
+});
+
+test('introHtml escapes the copy and the href', () => {
+  const html = introHtml({ before: '<b>a & b</b>', after: '"q"' }, 'https://x.test/?"');
+  assert.ok(!html.includes('<b>'), 'copy markup must not pass through');
+  assert.ok(html.includes('&lt;b&gt;a &amp; b&lt;/b&gt;'));
+  assert.ok(html.includes('href="https://x.test/?&quot;"'));
+  assert.ok(html.endsWith('&quot;q&quot;'));
+});
+
+test('the copy carries the inline prose subset, in the intro and the body', () => {
+  const props = webmasterPageProps(
+    {
+      title: 'T',
+      description: 'D',
+      intro: { before: 'Built by', after: ', **really**.' },
+      body: ["**If it isn't working, say so.**", 'See [the policy](/privacy).'],
+    },
+    'https://x.test/',
+  );
+  assert.equal(props.title, 'T');
+  assert.equal(props.description, 'D');
+  assert.ok(props.intro.endsWith('</a>, <strong>really</strong>.'));
+  assert.deepEqual(props.body, [
+    '<strong>If it isn&#39;t working, say so.</strong>',
+    'See <a href="/privacy">the policy</a>.',
+  ]);
+});
+
+test('the built-in page renders the same intro string a site layout receives', () => {
+  /*
+   * One source for the agency link. The page used to build its own <a> in the template, which
+   * is how a second copy of the attributes would drift; now both layouts render introHtml.
+   */
+  const page = readFileSync(new URL('../../../pages/webmaster.astro', import.meta.url), 'utf8');
+  const template = page.slice(page.lastIndexOf('---'));
+  assert.match(template, /<p set:html=\{props\.intro\} \/>/);
+  assert.doesNotMatch(template, /<a\s/, 'the page must not assemble the agency link itself');
+  const html = introHtml({ before: '', after: '' }, 'https://x.test/');
+  assert.match(html, /target="_blank"/);
+  assert.match(html, /rel="noopener"/);
+  assert.doesNotMatch(html, /noreferrer/);
+});

package/src/includes/webmonterey/webmaster/webmaster.ts

@@ -25,6 +25,8 @@
  * means a change to the name, the address or a profile is one edit.
  */
 
+import { escapeHtml, renderInline } from '../prose/inline.ts';
+
 /** The credit wording. Rendered verbatim on the site and in email. */
 export const CREDIT_TEXT = 'Powered by WebMonterey';
 
@@ -44,7 +46,7 @@ export const AGENCY = {
   name: 'WebMonterey',
   url: 'https://webmonterey.com/',
   description:
-    'A webmaster maintenance service in Monterey, California: design, build, hosting, security and ongoing care for small-business websites.',
+    'A webmaster service in Monterey, California: design, build, hosting, security and ongoing care for small-business websites.',
   address: { addressLocality: 'Monterey', addressRegion: 'CA', addressCountry: 'US' },
   sameAs: [
     /* The Google Business Profile, by its Knowledge Graph id - the stable form of the share link. */
@@ -87,3 +89,57 @@ export function creditUrl(domain: string, medium: CreditMedium = 'website'): str
 
   return `${AGENCY.url}?${params}`;
 }
+
+/**
+ * What the site's `webmasterPage` component receives, when a site exports one from its
+ * registry: the merged copy, already resolved. The component lays it out and carries no copy of
+ * its own - the words are the package's on every site, the shape of the page is the client's.
+ *
+ * `intro` and `body` are HTML, rendered with `set:html`. They are the output of `renderInline`,
+ * so a paragraph in `copy.webmaster` may carry the same inline subset page prose does -
+ * `**bold**`, `_italic_`, `[text](/url)` - and everything else is escaped.
+ */
+export interface WebmasterPageProps {
+  /** `copy.webmaster.title`, also the document title. Text. */
+  title: string;
+  /** `copy.webmaster.description`, also the meta description. Text. */
+  description: string;
+  /** The first paragraph's inner HTML, with the agency link already resolved. */
+  intro: string;
+  /** The remaining paragraphs' inner HTML, one entry per `<p>`. */
+  body: string[];
+}
+
+/**
+ * The intro paragraph's inner HTML: `before` <a>WebMonterey</a> `after`.
+ *
+ * ONE STRING, because it is the only part of the copy that is not plain text. A site taking
+ * over the page layout still gets the agency link exactly as the built-in page renders it - a
+ * followed link, opening in a new tab, `noopener` without `noreferrer` because the referrer is
+ * the attribution - rather than reassembling three fragments and forgetting one of the
+ * attributes. The built-in page renders this same string, so the two cannot drift. The space
+ * between `before` and the link is deliberate: Astro drops the whitespace between an expression
+ * and an element on separate lines, and "managed byWebMonterey" shipped.
+ */
+export function introHtml(intro: { before: string; after: string }, href: string): string {
+  const link = `<a href="${escapeHtml(href)}" target="_blank" rel="noopener">${escapeHtml(AGENCY.name)}</a>`;
+  return `${renderInline(intro.before)} ${link}${renderInline(intro.after)}`;
+}
+
+/** The whole prop set, from the merged copy and the attributed agency link. */
+export function webmasterPageProps(
+  text: {
+    title: string;
+    description: string;
+    intro: { before: string; after: string };
+    body: string[];
+  },
+  href: string,
+): WebmasterPageProps {
+  return {
+    title: text.title,
+    description: text.description,
+    intro: introHtml(text.intro, href),
+    body: text.body.map(renderInline),
+  };
+}