@cparkerwebm/webmonterey 1.2.0 → 1.4.0

package/src/integration/index.ts

@@ -31,7 +31,12 @@ import { fileURLToPath } from 'node:url';
 import { compileToCss } from '../design/compile.ts';
 import { imageSize } from './image-size.ts';
 import { loadForms, loadSiteFiles, resolveSiteUrl } from './config.ts';
-import { APP_DIR, appEnabled, resolveAppPath } from '../includes/webmonterey/config.ts';
+import {
+  APP_DIR,
+  appEnabled,
+  previewReason,
+  resolveAppPath,
+} from '../includes/webmonterey/config.ts';
 
 export interface WebmontereyOptions {
   /**
@@ -79,10 +84,14 @@ export interface WebmontereyOptions {
   /**
    * The branch Workers Builds deploys to production. Default `main`.
    *
-   * Every other branch is a PREVIEW, and a preview build is different on purpose: every page is
-   * noindex, there is no sitemap, robots.txt disallows everything, and Google Tag Manager does
-   * not load - so a client's review link can never be indexed, and clicking around it never
-   * lands in their analytics. Detected from WORKERS_CI_BRANCH, which Workers Builds injects.
+   * Every other branch is a PREVIEW - and so is every build, on any branch and from any machine,
+   * of a site whose webmonterey.json says `environment: "staging"`. A preview build is different
+   * on purpose: every page is noindex with no canonical, there is no sitemap, robots.txt
+   * disallows everything, and Google Tag Manager does not load - so a client's review link can
+   * never be indexed, a site that has not launched cannot be indexed before it exists, and
+   * clicking around either never lands in their analytics. The branch comes from
+   * WORKERS_CI_BRANCH, which Workers Builds injects; the decision is `isPreviewBuild` in
+   * includes/webmonterey/config.ts.
    */
   productionBranch?: string;
 }
@@ -133,14 +142,29 @@ export default function webmonterey(options: WebmontereyOptions = {}): AstroInte
         const appPath = resolveAppPath(files.site);
 
         /*
-         * BRANCH PREVIEW OR PRODUCTION. Workers Builds injects WORKERS_CI_BRANCH; anything that
-         * is not the production branch is a preview. A local build has no branch and is treated
-         * as production, which is what `npm run preview` and the e2e need. See the option.
+         * PREVIEW OR PRODUCTION, decided in one place - previewReason - from two signals. A site
+         * whose webmonterey.json says `environment: "staging"` is a preview in every build,
+         * whatever the branch and whatever the machine; and on a launched site any Workers
+         * Builds branch other than the production one is a preview too. A local build of a
+         * production site has no branch and is production output, which is what
+         * `npm run preview` and the e2e need. See the option, and the function.
          */
         const branch = process.env.WORKERS_CI_BRANCH ?? null;
-        const preview = branch !== null && branch !== (options.productionBranch ?? 'main');
-        if (preview) {
-          logger.info(`branch "${branch}" is a preview: noindex, no sitemap, no analytics`);
+        const productionBranch = options.productionBranch ?? 'main';
+        const reason = previewReason({
+          environment: files.site.environment,
+          branch,
+          productionBranch,
+        });
+        const preview = reason !== null;
+        if (reason === 'staging') {
+          logger.info(
+            'environment is "staging" in webmonterey.json: a preview build - noindex, no sitemap, no analytics',
+          );
+        } else if (reason === 'branch') {
+          logger.info(
+            `branch "${branch}" is not ${productionBranch}: a preview build - noindex, no sitemap, no analytics`,
+          );
         }
 
         /*
@@ -255,7 +279,7 @@ export default function webmonterey(options: WebmontereyOptions = {}): AstroInte
                 load(id: string) {
                   switch (id) {
                     case resolved(VIRTUAL.build):
-                      return `export default ${JSON.stringify({ preview, branch })};`;
+                      return `export default ${JSON.stringify({ preview, reason, branch })};`;
                     case resolved(VIRTUAL.site):
                       return `export default ${JSON.stringify(files.site)};`;
                     case resolved(VIRTUAL.design):
@@ -363,6 +387,15 @@ export default function webmonterey(options: WebmontereyOptions = {}): AstroInte
                          * router's plain <h1>; a site that does not keeps the <h1>.
                          */
                         `export const pageHeader = mod.pageHeader ?? null;`,
+                        /*
+                         * THE /webmaster PAGE'S BODY. The route, the copy, the share image and
+                         * the agency graph stay the package's; a site whose document pages use
+                         * a richer layout than an <h1> and a stack of paragraphs hands over the
+                         * layout only. Without this a site's own src/pages/webmaster.astro
+                         * collides with the injected route, and on one site the injected route
+                         * won.
+                         */
+                        `export const webmasterPage = mod.webmasterPage ?? null;`,
                         /*
                          * THE SITE'S JSON-LD, rendered into <head> on every route. The package
                          * emits none of its own: what a business claims about itself is the

package/src/integration/virtual.d.ts

@@ -5,11 +5,14 @@
  * a package cannot import relatively - see includes/webmonterey/config.ts.
  */
 /**
- * What this build is FOR. `preview` is true on any Workers Builds branch other than the
- * production one - every page noindex, no sitemap, no analytics. A local build is not a preview.
+ * What this build is FOR. `preview` is true when webmonterey.json says `environment: "staging"`,
+ * or on any Workers Builds branch other than the production one - every page noindex, no
+ * sitemap, no analytics. `reason` says which signal decided it. A local build of a production
+ * site is not a preview. See `isPreviewBuild` in includes/webmonterey/config.ts.
  */
 declare module 'virtual:webm/build' {
-  const build: { preview: boolean; branch: string | null };
+  import type { PreviewReason } from '../includes/webmonterey/config.ts';
+  const build: { preview: boolean; reason: PreviewReason; branch: string | null };
   export default build;
 }
 
@@ -83,6 +86,17 @@ declare module 'virtual:webm/registry' {
    * every later fix to block lookup, unknown-type reporting and FAQ extraction.
    */
   export const pageHeader: AstroComponentFactory | null;
+  /**
+   * The body of the `/webmaster` page, when the site wants it laid out like its own document
+   * pages rather than as the package's `<h1>` and stack of paragraphs.
+   *
+   * Receives `WebmasterPageProps` from `includes/webmonterey/webmaster/webmaster.ts`:
+   * `{ title, description, intro, body }`, the merged `copy.webmaster` - `intro` and `body` as
+   * HTML through the inline prose renderer, the agency link already in `intro`. The component
+   * lays the words out and carries no copy of its own. The route, the `<head>`, the share image and the JSON-LD stay the package's.
+   * Null means the built-in layout, `pageHeader` seam included.
+   */
+  export const webmasterPage: AstroComponentFactory | null;
   /**
    * The site's JSON-LD, rendered into <head> on every indexable route. The package emits none of
    * its own; this component composes a graph from the builders in

package/src/layouts/base.astro

@@ -183,12 +183,15 @@ const {
 } = Astro.props;
 
 /*
- * A BRANCH PREVIEW IS NOINDEX, EVERY PAGE. The review link a client gets is a public workers.dev
- * URL, and a search engine that finds one indexes a duplicate of the site under the wrong
- * hostname. noindex also suppresses the canonical and og:url below, so the preview sends one
- * signal rather than "do not index me" beside "my real address is over there". GTM is skipped on
- * a preview for the same reason in the other direction: a client clicking through their review
- * link must not show up in their own analytics.
+ * A PREVIEW BUILD IS NOINDEX, EVERY PAGE. A preview is a staging site (`environment` in
+ * webmonterey.json) on any hostname, or a non-production branch of a launched one - see
+ * isPreviewBuild in includes/webmonterey/config.ts. The review link a client gets is a public
+ * workers.dev URL, and a search engine that finds one indexes a duplicate of the site under the
+ * wrong hostname - or, for a site that has not launched, indexes the site before it exists.
+ * noindex also suppresses the canonical and og:url below, so the preview sends one signal rather
+ * than "do not index me" beside "my real address is over there". GTM is skipped on a preview for
+ * the same reason in the other direction: a client clicking through their review link must not
+ * show up in their own analytics.
  */
 const noindex = noindexProp || build.preview;
 const analyticsOn = analytics && !build.preview;

package/src/pages/robots.txt.ts

@@ -25,9 +25,11 @@ import build from 'virtual:webm/build';
 
 export const GET: APIRoute = ({ site }) => {
   /*
-   * A BRANCH PREVIEW DISALLOWS EVERYTHING. Every page on a preview is already noindex; this is
-   * the belt to that brace, and it is the one place Disallow is right - there is nothing on a
-   * preview a crawler should ever fetch, and no noindex tag it needs to see.
+   * A PREVIEW DISALLOWS EVERYTHING - a staging site on any hostname, or a non-production branch
+   * of a launched one (isPreviewBuild in includes/webmonterey/config.ts). Every page on a preview
+   * is already noindex; this is the belt to that brace, and it is the one place Disallow is
+   * right - there is nothing on a preview a crawler should ever fetch, and no noindex tag it
+   * needs to see.
    */
   if (build.preview) {
     return new Response('User-agent: *\nDisallow: /\n', {

package/src/pages/webmaster.astro

@@ -27,17 +27,25 @@ import { copy } from '../includes/webmonterey/copy.ts';
 import {
   AGENCY,
   creditUrl,
+  webmasterPageProps,
   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 { pageHeader, webmasterPage } from 'virtual:webm/registry';
 import ogImage from 'virtual:webm/webmaster-og';
 import build from 'virtual:webm/build';
 
 const PageHeader = pageHeader;
+const WebmasterPage = webmasterPage;
 const text = copy.webmaster;
 const agencyHref = hasDomain ? creditUrl(domain, 'website') : AGENCY.url;
+/*
+ * The words, resolved once for both layouts: the intro with the agency link in it, every
+ * paragraph through the inline prose renderer, so `**bold**` in copy.webmaster works here
+ * exactly as it does in page JSON.
+ */
+const props = webmasterPageProps(text, agencyHref);
 
 /*
  * The graph needs a real origin for stable @id values, which is the same gate the canonical tag
@@ -85,37 +93,51 @@ if (Astro.site && !build.preview) {
 
   {
     /*
-     * 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.
+     * THE BODY IS THE SITE'S IF IT WANTS IT. A site whose document pages - privacy, terms - use a
+     * richer layout than an <h1> and a stack of paragraphs exports `webmasterPage` from its
+     * registry and gets the merged copy handed to it: the same title, description and paragraphs
+     * as below, with the agency link already resolved into `intro`. Everything above this
+     * expression - the route, the <head>, the share image, the agency graph - stays the
+     * package's, so the page reads the same on every site and looks like the one it is on.
      */
-    PageHeader ? (
-      <PageHeader title={text.title} description={text.description} />
+    WebmasterPage ? (
+      <WebmasterPage {...props} />
     ) : (
-      <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">
+      <Fragment>
         {
           /*
-           * 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.
+           * 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>
+          )
         }
-        <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>
+
+        <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. See introHtml in webmaster.ts - the same string a site's own
+               * layout receives, so the two cannot disagree about the link.
+               */}
+              <p set:html={props.intro} />
+              {props.body.map((paragraph) => (
+                <p set:html={paragraph} />
+              ))}
+            </div>
+          </div>
+        </section>
+      </Fragment>
+    )
+  }
 </Base>

package/template/site/CLAUDE.md

@@ -14,7 +14,8 @@ The relationship is a WordPress parent theme and child theme.
 
 **A fix to the package reaches this site on `npm update`.** That is the entire point of the
 package existing, and it is why the default answer to "the shared behavior is wrong" is to fix
-it upstream rather than to work around it here.
+it upstream rather than to work around it here. Upstream means the package's own repo, in a
+session opened there — never from here. Rule 12 says what a session in this repo does instead.
 
 ## The one rule that protects that
 
@@ -198,7 +199,29 @@ alone renders.
 ### 11. Never edit inside `node_modules`
 
 A change there survives until the next install and not one second longer. If the package is
-wrong, fix the package — see the top of this file.
+wrong, the package gets fixed — by a session in the package repo, not this one. See rule 12.
+
+### 12. A session in a client repo never edits the package
+
+Not in `node_modules`, and not in the package's own checkout if it happens to be on this machine.
+When something in the package is wrong, the deliverable from a session in this repo is a
+**description of the fix** — what is wrong, where (file and line in the installed package), what
+the behavior should be, and how to verify it — written as a prompt the user can run in a session
+opened in the package repo. The package is versioned, tested and published on its own; this site
+takes the fix with `npm update`.
+
+This session stays inside this site's scope. An override in `design.json`, `src/styles/custom/`
+or `src/actions/index.ts` is fine; reaching upstream is not.
+
+Why this is a rule: "fix it upstream", read from inside a client repo, invited exactly the wrong
+thing. The package source sat next door on the same machine, a session opened it mid-task and
+edited it — a change nobody reviewed, in a repo nobody had open, on no branch, which then had to
+be published before this site could even use it. The client-site session ended with the site
+depending on a package version that did not exist.
+
+`.claude/settings.json` denies `Edit` under any `node_modules/`, so the first half is mechanical
+and `webm sync` keeps it that way. Claude Code has no rule syntax for "any path outside this
+project", so the second half is this paragraph.
 
 ## Structure
 
@@ -208,7 +231,10 @@ webmonterey.json            domain, client name, environment, features.
 src/
   components/               EVERY visible component. The package ships none.
     registry.ts             maps a block `type` to its component. A block whose type is
-                            not here renders as nothing, silently.
+                            not here renders as nothing, silently. Also exports the chrome:
+                            `header`, `footer`, `panels`, `pageHeader`, `structuredData`, and
+                            `webmasterPage` - the body of /webmaster, laid out like this
+                            site's document pages, with the package's copy handed in.
   content/pages/*.json      the words. One file per route; home.json is `/`.
   forms/*.json              form definitions. Filename is the form id.
   actions/index.ts          re-exports the package pipeline. Wrap to customize.
@@ -241,6 +267,7 @@ replaced wholesale. This client's own skills go beside it at `.claude/skills/<na
 | `/webm:start`         | standing a new site up: repo, Cloudflare resources, first deploy          |
 | `/webm:launch`        | launch checklist: structured data, sending domain, secrets, DNS, cutover  |
 | `/webm:upgrade`       | taking a new package version                                              |
+| `/webm:webmaster`     | laying out the package's `/webmaster` page like this site's own pages     |
 
 Content edits: branch, edit `src/content/pages/*.json`, `npm run check`, push — the branch
 preview is the client's review link. Merge when approved. Never change a block's `type`.