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/layouts/base.astro ADDED Viewed

@@ -0,0 +1,402 @@
+---
+/*
+ * The page shell. Every route renders through this.
+ *
+ * global.css is imported HERE and nowhere else — it is the single stylesheet entry point,
+ * and it pulls in the whole layer system in the correct order.
+ *
+ * Slots:
+ *   head    extra <head> content (analytics, structured data, a preload)
+ *   header  the site header region, once one exists
+ *   default page content
+ *   footer  the site footer region, once one exists
+ */
+import '../styles/global.css';
+/*
+ * The token layer, compiled from the client's design.json. There is no tokens.css to import -
+ * `webm design:extract` migrates an existing one, and the integration resolves this module.
+ */
+import 'virtual:webm/tokens.css';
+/*
+ * The client's own CSS - src/styles/custom/_index.css in their repo - which the package cannot
+ * reach by a relative path. LAST, so webm.components.custom and webm.overrides are written after
+ * the layers they override; the @layer statement decides the cascade either way, but a reader
+ * opening the built CSS should find the override at the bottom where they expect it.
+ */
+import 'virtual:webm/custom';
+import { LAYER_STATEMENT } from '../styles/layers.ts';
+import {
+  displayName,
+  shortName,
+  brandTitles,
+  gtmId as siteGtmId,
+} from '../includes/webmonterey/site.ts';
+import { header, footer, panels, structuredData } from 'virtual:webm/registry';
+import measuredShareImage from 'virtual:webm/share-image';
+import icons from 'virtual:webm/icons';
+/*
+ * Site-wide plumbing, wired in once here rather than per page.
+ *
+ * ORDER IS LOAD-BEARING: ConsentInit must be the first thing in <head>, above TagManager,
+ * so Consent Mode defaults are set before GTM loads. See the compliance includes.
+ *
+ * Each piece switches itself off: ConsentInit/CookieConsent render nothing when
+ * features.compliance is false, and TagManager renders nothing without a container ID.
+ */
+import ConsentInit from '../includes/webmonterey/compliance/ConsentInit.astro';
+import CookieConsent from '../includes/webmonterey/compliance/CookieConsent.astro';
+import TagManager from '../includes/google/tag-manager/TagManager.astro';
+import ScrollTop from '../includes/webmonterey/scroll-top/ScrollTop.astro';
+/*
+ * THE ENVIRONMENT WINS, webmonterey.json IS THE FALLBACK - and the fallback is the one that
+ * matters in production.
+ *
+ * `.env` is gitignored, so it does not exist on Workers Builds. A site that set its container id
+ * only in the environment therefore fired tags perfectly on a laptop and loaded nothing at all
+ * once deployed - no error, no broken page, just an analytics property that never received a
+ * hit. Reading webmonterey.json second means the id travels with the repo, which is safe because
+ * the id is public by design: it is in the source of every page it renders.
+ *
+ * The environment still takes precedence, so a branch can be pointed at a different container
+ * without editing tracked config.
+ */
+const gtmId = import.meta.env.PUBLIC_GTM_ID || siteGtmId;
+interface Props {
+  title: string;
+  description?: string;
+  /**
+   * Append ` | <shortName>` to the title. Default true.
+   *
+   * Set FALSE on a route that composes its own full title. A programme page titled "Bird Walks
+   * at the Marina Library" already names the client, and branding it again produces "Bird Walks
+   * at the Marina Library | FoML" - longer than a search result will show, with the page name
+   * truncated away to make room for a brand that was already in it.
+   *
+   * The automatic guard only catches a title that contains the SHORT name verbatim, which this
+   * one does not, so it has to be a decision the route can make.
+   *
+   * Defaults to `brandTitles` in webmonterey.json, so a site whose pages all author their own
+   * full titles sets it once rather than per route.
+   */
+  brandTitle?: boolean;
+  /**
+   * Keep this page out of search results.
+   *
+   * Emits `noindex, nofollow` and suppresses the canonical tag and Open Graph URL, so the
+   * page sends one unambiguous signal instead of "don't index me" alongside "here is my
+   * canonical address".
+   *
+   * A page marked this way must ALSO be excluded from the sitemap — see the `filter` in
+   * astro.config.mjs. Listing a noindex page in a sitemap is a contradiction search engines
+   * report as an error.
+   */
+  noindex?: boolean;
+  /**
+   * The social share image, as a path under `public/`. Defaults to `/open-graph.png`.
+   *
+   * MUST be a public/ path, never an imported asset run through `getImage`. On a prerendered
+   * route `getImage` returns a built `/_astro/…` file, but on a `prerender = false` route
+   * there is no build step to optimise into, so it returns the image SERVICE URL instead —
+   * `/_image?href=…`. With `imageService: 'compile'` (see astro.config.mjs) that endpoint is
+   * never deployed, so the card image 404s in production while every prerendered page looks
+   * fine. Files in public/ are copied verbatim and keep one URL however the page renders.
+   */
+  shareImage?: string;
+  /*
+   * Dimensions of `shareImage`, in pixels. THEY MUST TRAVEL WITH IT.
+   *
+   * These default to the size of the shipped `public/open-graph.png`. Files in public/ are
+   * copied verbatim and never processed, so nothing can measure the real image at build time
+   * and nothing will warn when these stop matching — a client dropping in a differently sized
+   * card image silently publishes false dimensions. Found exactly that way: a live site
+   * serving a 1280x672 image while declaring 1200x630.
+   *
+   * A crawler uses these to lay the card out before it fetches the image, so wrong values are
+   * worse than none. If the real size is not known, pass null for both and the two tags are
+   * omitted — the scrapers all measure the image themselves anyway.
+   */
+  shareImageWidth?: number | null;
+  shareImageHeight?: number | null;
+  /**
+   * Third-party analytics, and the consent UI that governs it. Default true.
+   *
+   * SET FALSE ON ANY PAGE WHOSE URL CAN CARRY A CREDENTIAL. Magic-link, password-reset,
+   * invitation and email-verification links arrive as `?t=<token>`; a share link carries its
+   * token in the path. Every one of those is a live credential sitting in the address.
+   *
+   * GTM's container script is NOT consent-gated. Consent Mode governs what tags may STORE, not
+   * whether the container loads, and the container reports the page URL. So on a consent-
+   * respecting site with nothing accepted, the token still reaches Google before the visitor
+   * has finished using it. That is a real leak, not a theoretical one.
+   *
+   * It also switches off the cookie banner, deliberately: with no third party on the page the
+   * banner governs nothing, and its analytics and marketing toggles would control something
+   * that is not there, over the top of somebody's file browser. A session cookie is strictly
+   * necessary and needs no consent.
+   *
+   * ConsentInit still renders, so Consent Mode defaults stay set for the pages that do load a
+   * container - a visitor moving from the portal back to the marketing site keeps one
+   * consistent state rather than an unset one.
+   */
+  analytics?: boolean;
+  /**
+   * The back-to-top control. Default true.
+   *
+   * It rendered on every page of every site with nothing to turn it off - a small thing, and
+   * exactly the shape of the problem: the package deciding something for six clients because
+   * nobody wrote down that they might disagree.
+   */
+  scrollTop?: boolean;
+}
+const {
+  title,
+  description,
+  brandTitle = brandTitles,
+  noindex = false,
+  shareImage = '/open-graph.png',
+  /*
+   * MEASURED, not assumed. Both default to the real size of public/open-graph.png, read from the
+   * file's own header at build time - so replacing the card art cannot leave the tags describing
+   * the old one, which is what happened on every generation-2 site.
+   *
+   * A page passing explicit values still wins, and an unreadable file leaves both null, which
+   * omits the tags rather than publishing a guess.
+   */
+  shareImageWidth = measuredShareImage?.width ?? null,
+  shareImageHeight = measuredShareImage?.height ?? null,
+  analytics = true,
+  scrollTop = true,
+} = Astro.props;
+/*
+ * Canonical URL. Only emitted once `site` is derived from `domain` in webmonterey.json.
+ * Astro.site is undefined until then, and a canonical pointing at localhost is worse than none.
+ */
+const canonical = !noindex && Astro.site ? new URL(Astro.url.pathname, Astro.site).href : undefined;
+/*
+ * Open Graph image. Absolute, because every scraper requires that — a relative og:image is
+ * simply ignored, which is indistinguishable from having none.
+ *
+ * So it is emitted only once `site` is derived from `domain` in webmonterey.json, the same
+ * gate the canonical tag uses. Until then `twitter:card` falls back to `summary`: declaring
+ * `summary_large_image` with no image is what produced a blank card on every page this
+ * starter has shipped, because the card type promises an image the markup never supplied.
+ */
+const shareImageUrl = Astro.site ? new URL(shareImage, Astro.site).href : undefined;
+/*
+ * `Page title | Client Name`, built here rather than typed into every page's JSON - one place
+ * to change it, and no page can forget.
+ *
+ * THE GUARD MATTERS. A page whose title already contains the client name - a homepage, most
+ * likely - would otherwise render "WebMonterey | WebMonterey". And displayName() falls back to
+ * the domain rather than ever publishing "CHANGEME" into a <title>, which is a thing a visitor
+ * and a search engine both see.
+ */
+/* shortName, not displayName: a long client name in every <title> truncates the page name away. */
+const siteName = shortName;
+const pageTitle =
+  brandTitle && siteName && !title.includes(siteName) ? `${title} | ${siteName}` : title;
+/*
+ * SITE OVERLAYS - dialogs, drawers, slide-in panels - rendered once at the end of <body>.
+ *
+ * A third chrome category beyond header and footer, and it is not a nicety: a mobile menu panel
+ * and a call-to-action drawer both have to live outside <main> to be positioned and to sit above
+ * everything, so a site with either has no way to render it through the block system. Generation
+ * 2 put them in its own base.astro; the package's layout is not the client's to edit, so they
+ * come through the registry instead.
+ */
+const Panels = panels;
+/*
+ * THE SITE'S CHROME, AS SLOT FALLBACK - and it belongs HERE, not in the block router.
+ *
+ * It was in the router first, and that meant only pages rendered from page JSON got a header:
+ * a site's OWN routes - a calendar, a /programs/[slug] - render <Base> directly and came out
+ * with no header, no footer and no announcement bar. So did the package's own /webm page. On a
+ * rebuild that is 27 pages quietly missing their navigation.
+ *
+ * As a slot fallback, any route that uses this layout gets the chrome, and a route that wants
+ * something else still overrides it by filling the slot. That is how generation 2 did it, and
+ * the reason is the same.
+ */
+const Header = header;
+const Footer = footer;
+/*
+ * THE SITE'S JSON-LD, if it declares one. The package emits none of its own: a candidate, a
+ * recording studio and a library charity are not variants of one shape, and the generic graph
+ * that tried to be grew a field a day and still fit nobody. The builders in
+ * includes/webmonterey/structured-data are the package's half - escaping, @id wiring, dropping
+ * empty fields - and the site composes what it claims. /webm:launch is where that gets written.
+ */
+const StructuredData = structuredData;
+---
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    {
+      /*
+      CASCADE ORDER. Must stay ahead of every stylesheet, which is why it is authored here as
+      inline HTML rather than left to global.css.
+      The identical statement in global.css is stripped by the bundler — a bare @layer
+      statement is not attached to any rule, so nothing carries it into the output chunk.
+      Layer order then falls back to order of first appearance, the bundler picks that, and a
+      component's scoped style arriving before global.css silently inverts reset and
+      components. `is:inline` keeps Astro's hands off it for the same reason.
+      >> Emitted from styles/layers.ts, which global.css is tested against. There is no
+      second list to keep in step by hand any more. <<
+    */
+    }
+    <style is:inline set:html={LAYER_STATEMENT}></style>
+    <!-- FIRST. Sets consent state and Consent Mode defaults before any third party loads. -->
+    <ConsentInit />
+    {analytics && gtmId && <TagManager id={gtmId} />}
+    {
+      /*
+      Marks the document JS-capable BEFORE first paint. Every .webm-reveal hidden state in
+      animations.css is scoped to `html.js`, so with JavaScript off — or if the bundle simply
+      fails to load — nothing is ever hidden and content is visible rather than stranded at
+      opacity: 0. A crawler that does not run scripts sees the page in full.
+      `is:inline` and synchronous on purpose: Astro would otherwise bundle and defer it, which
+      lands after first paint and reintroduces the flash this exists to prevent.
+      Below ConsentInit deliberately — it sets a class and touches nothing else, so it cannot
+      affect the Consent Mode defaults that must reach GTM first.
+    */
+    }
+    <script is:inline>
+      document.documentElement.classList.add('js');
+    </script>
+    <title>{pageTitle}</title>
+    {description && <meta name="description" content={description} />}
+    {noindex && <meta name="robots" content="noindex, nofollow" />}
+    {canonical && <link rel="canonical" href={canonical} />}
+    <meta property="og:type" content="website" />
+    {
+      /*
+      og:title CARRIES THE BRAND, matching <title>. The spec's tidier pairing is an unbranded
+      og:title plus og:site_name, and that was the first version of this - but it changes what a
+      previously-shared card says, and not every platform renders site_name. A rebuild should not
+      silently restyle links people have already posted.
+      og:site_name ships as well, because the tag is correct and some platforms use it for
+      attribution. The small redundancy is the price of not changing existing cards.
+    */
+    }
+    <meta property="og:title" content={pageTitle} />
+    <meta property="og:site_name" content={siteName} />
+    {description && <meta property="og:description" content={description} />}
+    {canonical && <meta property="og:url" content={canonical} />}
+    {
+      shareImageUrl && (
+        <>
+          <meta property="og:image" content={shareImageUrl} />
+          {shareImageWidth && <meta property="og:image:width" content={String(shareImageWidth)} />}
+          {shareImageHeight && (
+            <meta property="og:image:height" content={String(shareImageHeight)} />
+          )}
+          <meta name="twitter:image" content={shareImageUrl} />
+        </>
+      )
+    }
+    <meta name="twitter:card" content={shareImageUrl ? 'summary_large_image' : 'summary'} />
+    {
+      /*
+      ONLY THE ICONS THAT EXIST. Linking favicon.svg unconditionally meant a site without one
+      served the seeded placeholder - WebMonterey's own mark - as the client's icon, and browsers
+      prefer SVG over .ico so it was the one actually shown.
+      The PNG sizes are emitted only when an SVG is absent: a scalable icon makes them redundant,
+      and a site that has both does not need four links to say the same thing.
+    */
+    }
+    {icons['favicon.svg'] && <link rel="icon" href="/favicon.svg" type="image/svg+xml" />}
+    {icons['favicon.ico'] && <link rel="icon" href="/favicon.ico" sizes="32x32" />}
+    {
+      !icons['favicon.svg'] && icons['favicon-16x16.png'] && (
+        <link rel="icon" href="/favicon-16x16.png" type="image/png" sizes="16x16" />
+      )
+    }
+    {
+      !icons['favicon.svg'] && icons['favicon-32x32.png'] && (
+        <link rel="icon" href="/favicon-32x32.png" type="image/png" sizes="32x32" />
+      )
+    }
+    {icons['apple-touch-icon.png'] && <link rel="apple-touch-icon" href="/apple-touch-icon.png" />}
+    {icons['site.webmanifest'] && <link rel="manifest" href="/site.webmanifest" />}
+    {
+      /*
+      GATED HERE, not left to the component. Structured data describing a page that asks not to
+      be indexed is a contradiction, and the site's component should not have to remember that.
+    */
+    }
+    {
+      StructuredData && !noindex && (
+        <StructuredData title={title} description={description} image={shareImageUrl} />
+      )
+    }
+    <slot name="head" />
+  </head>
+  <body>
+    <a class="webm-skip-link" href="#webm-main">Skip to content</a>
+    <!-- GTM's noscript iframe must be the first thing in <body>. -->
+    {analytics && gtmId && <TagManager id={gtmId} noscript />}
+    <slot name="header">{Header && <Header />}</slot>
+    <!-- tabindex="-1" is required for the skip link to actually move focus in Safari. -->
+    <main id="webm-main" tabindex="-1">
+      <slot />
+    </main>
+    <slot name="footer">{Footer && <Footer />}</slot>
+    {Panels.map((Panel) => <Panel />)}
+    {scrollTop && <ScrollTop />}
+    {analytics && <CookieConsent />}
+    {
+      /*
+      Scroll reveal. Imported ONCE for the whole site — Astro dedupes a bundled <script>
+      across every component instance, so importing observe.ts anywhere else is harmless but
+      pointless. Nothing here runs unless a page actually renders a .webm-reveal element.
+    */
+    }
+    <script>
+      import { initAnimations } from '../includes/webmonterey/animations/observe.ts';
+      initAnimations();
+      /*
+       * A ClientRouter view transition swaps the DOM without a full reload, so the incoming
+       * page's elements need wiring again. initAnimations is idempotent, and this listener is
+       * inert on a site that has not enabled view transitions.
+       */
+      document.addEventListener('astro:page-load', () => initAnimations());
+    </script>
+  </body>
+</html>

package/src/package.test.ts ADDED Viewed

@@ -0,0 +1,121 @@
+/*
+ * The package manifest is a contract with every client site. A broken export path fails at
+ * import time, in their build, not here - so it is worth a test.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+const ROOT = fileURLToPath(new URL('../', import.meta.url));
+/** package.json carries `//`-prefixed keys as inline documentation; JSON.parse handles them. */
+const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')) as {
+  name: string;
+  optionalDependencies?: Record<string, string>;
+  exports: Record<string, string>;
+  bin: Record<string, string>;
+  files: string[];
+  peerDependencies: Record<string, string>;
+  dependencies: Record<string, string>;
+};
+test('every export path exists on disk', () => {
+  for (const [subpath, target] of Object.entries(pkg.exports)) {
+    if (subpath.startsWith('//')) continue;
+    assert.ok(existsSync(join(ROOT, target)), `${subpath} -> ${target} does not exist`);
+  }
+});
+test('the bin exists and is the CLI', () => {
+  for (const target of Object.values(pkg.bin)) {
+    assert.ok(existsSync(join(ROOT, target)), `${target} does not exist`);
+  }
+});
+test('every published directory exists', () => {
+  for (const entry of pkg.files) {
+    assert.ok(existsSync(join(ROOT, entry)), `files lists ${entry}, which does not exist`);
+  }
+});
+test('astro is a peer, never a dependency', () => {
+  // Two copies of Astro in one tree break the integration in ways that are hard to read.
+  assert.ok(pkg.peerDependencies.astro, 'astro must be a peerDependency');
+  assert.equal(pkg.dependencies.astro, undefined, 'astro must not be a plain dependency');
+});
+test('the design subpath imports nothing from Astro', () => {
+  // This is what keeps it testable with node --test and usable from the platform without
+  // pulling a framework in to read a color.
+  for (const file of [
+    'compile.ts',
+    'defaults.ts',
+    'resolve.ts',
+    'brand.ts',
+    'types.ts',
+    'index.ts',
+  ]) {
+    const source = readFileSync(join(ROOT, 'src/design', file), 'utf8');
+    assert.ok(!/from '(astro|astro:)/.test(source), `src/design/${file} imports from astro`);
+  }
+});
+test('every directory the code reads out of the package is published', () => {
+  /*
+   * The inverse of "every published directory exists", and the one that actually bites: `files`
+   * is an allowlist, so a new directory is absent from the tarball by default. It works in this
+   * repo and in `npm link` - both of which read the working tree - and is missing the moment a
+   * real install happens. `template/` shipped that way until this test was written.
+   */
+  const sources = readdirSync(join(ROOT, 'src', 'cli'))
+    .filter((f) => f.endsWith('.ts') && !f.endsWith('.test.ts'))
+    .map((f) => readFileSync(join(ROOT, 'src', 'cli', f), 'utf8'))
+    .join('\n');
+  const published = new Set(JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')).files);
+  for (const match of sources.matchAll(/PACKAGE_ROOT,\s*'([a-z-]+)'/g)) {
+    const dir = match[1]!;
+    assert.ok(
+      published.has(dir),
+      `src/cli reads PACKAGE_ROOT/${dir}/ but "${dir}" is not in package.json files[] - ` +
+        `it works from a checkout and is absent from the tarball`,
+    );
+  }
+});
+test('the package does not depend on itself', () => {
+  /*
+   * IT DID, AND IT SHIPPED. package.json carried
+   *   "@cparkerwebm/webmonterey": "file:/Users/cparkerwebm/Workspace/webmonterey/...tgz"
+   * as a runtime dependency of itself, pointing at an absolute path on one laptop. Every install
+   * of the published 1.0.0 failed with ENOENT on a path that exists on no other machine.
+   *
+   * It hid for two sessions because every install until the first real publish was either a
+   * symlink or a file: reference, and in both of those the self-reference resolves to something
+   * that happens to exist. Only a registry install can see it.
+   */
+  assert.ok(
+    !(pkg.dependencies ?? {})[pkg.name],
+    `${pkg.name} lists itself as a dependency - every install will try to install it into itself`,
+  );
+});
+test('no dependency is a file: or link: path', () => {
+  /*
+   * A local path in a PUBLISHED package is always wrong: it resolves on the machine that
+   * published and nowhere else. This is the general form of the self-dependency above, and it is
+   * worth checking every field rather than just the one that bit.
+   */
+  const fields = [pkg.dependencies, pkg.peerDependencies, pkg.optionalDependencies];
+  for (const field of fields) {
+    for (const [name, spec] of Object.entries(field ?? {})) {
+      assert.ok(
+        !/^(file:|link:|\.{1,2}\/)/.test(spec),
+        `${name} is "${spec}" - a local path cannot resolve for anyone installing this`,
+      );
+    }
+  }
+});

package/src/pages/404.astro ADDED Viewed

@@ -0,0 +1,33 @@
+---
+import { copy } from '../includes/webmonterey/copy.ts';
+/*
+ * Served by Cloudflare for any path that matches no asset, via
+ * `"not_found_handling": "404-page"` in wrangler.jsonc.
+ *
+ * Deliberately not driven by page JSON - it must still render if the content layer is broken.
+ *
+ * NOINDEX, AND THAT IS NOT COSMETIC. Without it the layout emits a canonical tag pointing at
+ * /404/, which tells a crawler this error page is the preferred version of itself and invites it
+ * into the index. `noindex` suppresses the canonical and the Open Graph URL together, so the page
+ * sends one unambiguous signal instead of "do not index me" alongside "here is my address".
+ *
+ * The description is generic on purpose: the package cannot name a client's own sections, and a
+ * site wanting a better one overrides this route the ordinary Astro way, with src/pages/404.astro.
+ */
+import Base from '../layouts/base.astro';
+---
+<Base title={copy.notFound.title} description={copy.notFound.body} noindex>
+  {
+    /* The 404 carries the site's chrome too - a bare 404 is how a visitor decides the site is broken. */
+  }
+  <section class="webm-section" data-space="lg">
+    <div class="webm-container" data-width="text">
+      <div class="webm-stack">
+        <h1>{copy.notFound.title}</h1>
+        <p>That page doesn’t exist, or it has moved.</p>
+        <p><a href="/">Back to the home page</a></p>
+      </div>
+    </div>
+  </section>
+</Base>

package/src/pages/[...slug].astro ADDED Viewed

@@ -0,0 +1,126 @@
+---
+/*
+ * THE BLOCK ROUTER
+ *
+ * Every page on the site renders through this one route. It reads a page's JSON, walks its
+ * `blocks` array in order, and renders each one via the component registry.
+ *
+ * Adding a page = adding a JSON file. No route file is ever written per page.
+ */
+import type { GetStaticPaths, InferGetStaticPropsType } from 'astro';
+import { getCollection } from 'astro:content';
+import Base from '../layouts/base.astro';
+/*
+ * The registry lives in the CLIENT repo, because every visible component does - the package
+ * ships none. The integration resolves this module to src/components/registry.ts in the site
+ * being built.
+ */
+import { blocks, registeredTypes, pageHeader } from 'virtual:webm/registry';
+export const getStaticPaths = (async () => {
+  const pages = await getCollection('pages');
+  return pages.map((page) => ({
+    /*
+     * `home` is the only special case: it maps to `/`, not `/home`.
+     * A rest param of `undefined` is how Astro matches the site root.
+     */
+    params: { slug: page.id === 'home' ? undefined : page.id },
+    props: { page },
+  }));
+}) satisfies GetStaticPaths;
+type Props = InferGetStaticPropsType<typeof getStaticPaths>;
+const { page } = Astro.props as Props;
+/* Capitalized, because Astro renders a lowercase identifier as an HTML tag rather than a component. */
+/* Chrome is the LAYOUT's job - see base.astro. This route only supplies the page header. */
+const PageHeader = pageHeader;
+---
+{
+  /*
+  noindex and shareImage come from the PAGE, not just from a route that hardcodes them. A site
+  marking a confirmation page noindex in its own JSON had that silently ignored on rebuild - the
+  page came back indexable, with a canonical, which is the opposite of what it asked for.
+  Read defensively: a site using the package's own content schema may not define either field.
+*/
+}
+<Base
+  title={page.data.title}
+  description={page.data.description}
+  noindex={(page.data as { noindex?: boolean }).noindex ?? false}
+  {...(page.data as { shareImage?: string }).shareImage
+    ? { shareImage: (page.data as { shareImage?: string }).shareImage }
+    : {}}
+>
+  {
+    /*
+    The site's own chrome, rendered once per page. The package ships no header and no footer -
+    it ships no components at all - so these come from the client's registry.ts. A site with
+    neither gets a page with neither, which is the scaffold's normal state.
+  */
+  }
+  {/* See `showTitle` in src/content.config.ts for why this defaults on. */}
+  {
+    /*
+     * THE PAGE HEADER. A site that declares `pageHeader` in its registry gets it here, with the
+     * page's whole frontmatter - so a header can use a subtitle, photos, a category, anything the
+     * package has never heard of. Without it a site wanting more than an <h1> had to fork this
+     * route, and a fork stops receiving every later fix to block lookup and unknown-type
+     * reporting.
+     *
+     * The fallback stays a bare <h1> because a page whose only headings are its blocks' h2s has
+     * no h1 at all - a document-outline bug rather than a style preference.
+     */
+    page.data.showTitle &&
+      (PageHeader ? (
+        <PageHeader {...page.data} />
+      ) : (
+        <section class="webm-section" data-space="sm">
+          <div class="webm-container" data-width="text">
+            <h1>{page.data.title}</h1>
+          </div>
+        </section>
+      ))
+  }
+  {
+    page.data.blocks.map((block) => {
+      /*
+       * Object.hasOwn, not a plain lookup: `blocks[block.type]` walks the prototype chain, so
+       * a page JSON containing {"type": "constructor"} (or toString, valueOf, __proto__)
+       * returns a truthy function, sails past the guard below, and kills the build with an
+       * opaque "no valid renderer" error.
+       */
+      const Block = Object.hasOwn(blocks, block.type) ? blocks[block.type] : undefined;
+      if (!Block) {
+        /*
+         * The block is in the JSON but not in the registry, so it renders as nothing.
+         * Almost always a missing registry entry — see src/components/registry.ts.
+         */
+        const known = registeredTypes();
+        // Leading newline: without it this concatenates onto Astro's progress line
+        // ("├─ /about/index.htmlUnknown block…") and is easy to miss entirely.
+        console.warn(
+          `\n[webm] Unknown block type "${block.type}" in src/content/pages/${page.id}.json — ` +
+            `it is not in the component registry, so it will render as nothing. ` +
+            `Registered types: ${known.length ? known.join(', ') : '(none yet)'}`,
+        );
+        return null;
+      }
+      /*
+       * `type` is stripped before spreading. It identifies the component; it is not a prop.
+       * Left in, every component receives it, and a block rendering <button {...rest}> gets
+       * type="content-000001" — an invalid value browsers resolve to type="submit", silently
+       * changing what the button does inside a form.
+       */
+      const { type: _type, ...props } = block;
+      return <Block {...props} />;
+    })
+  }
+</Base>