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/includes/webmonterey/structured-data/nodes.ts ADDED Viewed

@@ -0,0 +1,315 @@
+/*
+ * STRUCTURED DATA, AS PARTS RATHER THAN AS A VERDICT.
+ *
+ * WHY THIS FILE EXISTS. The package used to ship one component that built nineteen node types and
+ * emitted them, and every site got an agency's idea of what a business is. It was absorbed whole
+ * from webmonterey.com on the reasoning that one site's improvement should become every site's -
+ * which is right about improvements and wrong about opinions. A candidate, a recording studio, a
+ * library charity and a compliance platform are not variants of one shape. Chasing that, the
+ * component gained `place`, `breadcrumbs`, a page `description`, then `description` and `image`
+ * on the Person node - six additions in a day - and afterwards a candidate site still could not
+ * say `affiliation` and was still replacing the whole thing.
+ *
+ * THE SPLIT. Serialising a graph is identical on every site: one `@graph` rather than loose
+ * islands so nodes can reference each other by `@id`, `<` escaped so a value cannot close the
+ * script tag, empty fields dropped, nothing emitted for a noindex page. That is thirty lines and
+ * it belongs here. WHICH nodes, with WHICH fields, is what the site is claiming about itself, and
+ * that belongs to the site.
+ *
+ * So this exports building blocks and a serializer, and the package emits NOTHING by default. A
+ * site composes its graph in a component it exports as `structuredData` from its registry; the
+ * layout renders that into <head> on every indexable route with { title, description, image }:
+ *
+ *     ---
+ *     import { graphContext, renderJsonLd, organizationNode, websiteNode, webPageNode }
+ *       from '@cparkerwebm/webmonterey/structured-data';
+ *     const { title, description, image } = Astro.props;
+ *     const ctx = graphContext(Astro.site!, Astro.url.pathname, { title, description });
+ *     const jsonLd = renderJsonLd([
+ *       organizationNode(ctx, image),
+ *       websiteNode(ctx),
+ *       webPageNode(ctx),
+ *       breadcrumbNode(ctx),
+ *     ]);
+ *     ---
+ *     {jsonLd && <script type="application/ld+json" set:html={jsonLd} />}
+ *
+ * The parts are here so sites do not each rewrite a PostalAddress. The composition is not, so
+ * the package never again has to grow a field to describe somebody else's business.
+ * /webm:launch is where a site's graph gets decided.
+ */
+import { client, domain, hasClient, organization as org } from '../site.ts';
+/** Everything a node builder needs to make stable @id values and absolute URLs. */
+export interface GraphContext {
+  /** The site origin, from Astro.site. */
+  site: URL;
+  /** This page's canonical URL, normalised the same way the canonical tag builds it. */
+  url: string;
+  title?: string;
+  description?: string;
+  /** `@id` of the organization node, for anything that references it. */
+  orgId: string;
+  /** `@id` of the website node. */
+  siteId: string;
+}
+export function graphContext(site: URL, pathname: string, extra: Partial<GraphContext> = {}) {
+  return {
+    site,
+    url: new URL(pathname, site).href,
+    orgId: new URL('#organization', site).href,
+    siteId: new URL('#website', site).href,
+    ...extra,
+  } as GraphContext;
+}
+/** Drop empty strings, empty arrays, null and undefined — never emit a blank field. */
+export function compact<T extends Record<string, unknown>>(input: T): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(input).filter(([, v]) => {
+      if (v === null || v === undefined) return false;
+      if (typeof v === 'string') return v.trim() !== '';
+      if (Array.isArray(v)) return v.length > 0;
+      return true;
+    }),
+  ) as Partial<T>;
+}
+/**
+ * The graph, as the string that goes inside one <script type="application/ld+json">.
+ *
+ * `<` is escaped to its \\u003c form. Inside a script element the HTML parser is still looking for
+ * `</script>`, so any value containing that sequence would close the block early and spill the
+ * rest into the document as markup. These values come from config rather than from visitors, but
+ * the escape costs nothing and the failure mode is markup injection.
+ *
+ * Returns null for an empty graph, so a caller renders no script rather than an empty one.
+ */
+export function renderJsonLd(nodes: unknown[]): string | null {
+  const graph = nodes.filter(Boolean);
+  if (graph.length === 0) return null;
+  return JSON.stringify({ '@context': 'https://schema.org', '@graph': graph }).replace(
+    /</g,
+    '\\u003c',
+  );
+}
+/** The address, or null when the config carries none. Shared by the organization and any Place. */
+export function addressNode() {
+  const address = compact({
+    '@type': 'PostalAddress',
+    streetAddress: org.streetAddress,
+    addressLocality: org.addressLocality,
+    addressRegion: org.addressRegion,
+    postalCode: org.postalCode,
+    addressCountry: org.addressCountry,
+  });
+  /*
+   * compact() leaves the discriminator behind, so a PostalAddress carrying only its own @type is
+   * an empty node. The length check is what actually decides whether there is an address at all.
+   */
+  return Object.keys(address).length > 1 ? address : null;
+}
+/** The organization. Its @type comes from config — Organization, NGO, LocalBusiness, whatever fits. */
+export function organizationNode(ctx: GraphContext, image?: string) {
+  return compact({
+    '@type': org.type || 'Organization',
+    '@id': ctx.orgId,
+    name: hasClient ? client : domain,
+    legalName: org.legalName,
+    description: org.description,
+    url: ctx.site.href,
+    image,
+    /*
+     * THE LOGO IS NOT THE SHARE IMAGE. Both were `image` once, which published a 1200x630 social
+     * banner as the organisation's mark - the thing a knowledge panel draws. Omitted when unset
+     * rather than falling back to the card: a wrong logo is worse than no logo, and Google wants
+     * at least 112x112.
+     */
+    logo: org.logo ? new URL(org.logo, ctx.site).href : '',
+    telephone: org.telephone,
+    email: org.email,
+    address: addressNode() ?? '',
+    areaServed: org.areaServed,
+    priceRange: org.priceRange,
+    openingHoursSpecification: org.hours?.opens
+      ? {
+          '@type': 'OpeningHoursSpecification',
+          dayOfWeek: org.hours.days,
+          opens: org.hours.opens,
+          closes: org.hours.closes,
+        }
+      : '',
+    sameAs: org.sameAs,
+    founder: org.founder?.name ? { '@id': new URL('#founder', ctx.site).href } : '',
+    employee: org.founder?.name ? { '@id': new URL('#founder', ctx.site).href } : '',
+    hasOfferCatalog: org.services?.length
+      ? {
+          '@type': 'OfferCatalog',
+          name: 'Services',
+          itemListElement: org.services.map((name) => ({
+            '@type': 'Offer',
+            itemOffered: { '@type': 'Service', name },
+          })),
+        }
+      : '',
+  });
+}
+/** The person behind the organization, from `organization.founder`. */
+export function personNode(ctx: GraphContext) {
+  if (!org.founder?.name) return null;
+  return compact({
+    '@type': 'Person',
+    '@id': new URL('#founder', ctx.site).href,
+    name: org.founder.name,
+    jobTitle: org.founder.jobTitle,
+    description: org.founder.description,
+    image: org.founder.image ? new URL(org.founder.image, ctx.site).href : '',
+    url: ctx.site.href,
+    worksFor: { '@id': ctx.orgId },
+    sameAs: org.founder.sameAs,
+  });
+}
+export function websiteNode(ctx: GraphContext) {
+  return compact({
+    '@type': 'WebSite',
+    '@id': ctx.siteId,
+    url: ctx.site.href,
+    name: hasClient ? client : domain,
+    description: org.description,
+    publisher: { '@id': ctx.orgId },
+    inLanguage: 'en',
+  });
+}
+export function webPageNode(ctx: GraphContext) {
+  return compact({
+    '@type': 'WebPage',
+    '@id': `${ctx.url}#webpage`,
+    url: ctx.url,
+    name: ctx.title,
+    description: ctx.description,
+    isPartOf: { '@id': ctx.siteId },
+    about: { '@id': ctx.orgId },
+    inLanguage: 'en',
+  });
+}
+/** A physical place — the ONE page that is the place, never site-wide. */
+export interface PlaceInput {
+  type: 'BookStore' | 'Store' | 'Place';
+  name: string;
+  streetAddress: string;
+  addressLocality: string;
+  addressRegion: string;
+  postalCode: string;
+  addressCountry: string;
+  telephone?: string;
+  openingHours: { days: string[]; opens: string; closes: string }[];
+}
+export function placeNode(ctx: GraphContext, place: PlaceInput, image?: string) {
+  return compact({
+    '@type': place.type,
+    '@id': `${ctx.url}#place`,
+    name: place.name,
+    url: ctx.url,
+    telephone: place.telephone,
+    image,
+    address: {
+      '@type': 'PostalAddress',
+      streetAddress: place.streetAddress,
+      addressLocality: place.addressLocality,
+      addressRegion: place.addressRegion,
+      postalCode: place.postalCode,
+      addressCountry: place.addressCountry,
+    },
+    openingHoursSpecification: place.openingHours.map((slot) => ({
+      '@type': 'OpeningHoursSpecification',
+      dayOfWeek: slot.days,
+      opens: slot.opens,
+      closes: slot.closes,
+    })),
+    parentOrganization: { '@id': ctx.orgId },
+  });
+}
+/**
+ * A breadcrumb trail, root first, INCLUDING the current page as the last crumb.
+ *
+ * A single-item trail is omitted: "Home" on its own is not a trail and Google ignores it.
+ * The caller supplies the names because only the route knows them - deriving from the URL gives
+ * a slug where a name belongs, which is how /programs/chess-club/ published its middle step as
+ * nothing at all.
+ */
+export function breadcrumbNode(ctx: GraphContext, trail?: { name: string; path: string }[]) {
+  /*
+   * NO TRAIL GIVEN? DERIVE A TWO-LEVEL ONE FROM THE PATH.
+   *
+   * This fallback is load-bearing and was nearly lost splitting this file out: dropping it took
+   * the BreadcrumbList off thirty-two inner pages across two sites at once, silently, because
+   * structured data has no visible surface to notice it on. Most pages pass nothing and rely on
+   * exactly this.
+   *
+   * Two levels is all derivation can honestly give - the middle segment of /programs/chess-club/
+   * is a slug here, not a name. A route that knows its own hierarchy passes the trail.
+   */
+  if (!trail) {
+    const segments = new URL(ctx.url).pathname.split('/').filter(Boolean);
+    if (segments.length === 0) return null;
+    return {
+      '@type': 'BreadcrumbList',
+      '@id': `${ctx.url}#breadcrumb`,
+      itemListElement: [
+        { '@type': 'ListItem', position: 1, name: 'Home', item: ctx.site.href },
+        {
+          '@type': 'ListItem',
+          position: 2,
+          name: ctx.title ?? segments[segments.length - 1],
+          /*
+           * The last crumb carries its URL too. Google treats `item` as optional on the final
+           * element, so omitting it is valid - but a breadcrumb whose last entry has no address is
+           * less useful to anything reading the graph, and generation 2 emitted it.
+           */
+          item: ctx.url,
+        },
+      ],
+    };
+  }
+  if (trail.length < 2) return null;
+  return {
+    '@type': 'BreadcrumbList',
+    '@id': `${ctx.url}#breadcrumb`,
+    itemListElement: trail.map((crumb, index) => ({
+      '@type': 'ListItem',
+      position: index + 1,
+      name: crumb.name,
+      item: new URL(crumb.path, ctx.site).href,
+    })),
+  };
+}
+/**
+ * FAQPage. Worth emitting for entity understanding and AI search, but NOT for Google rich
+ * results: those were restricted to government and health sites in August 2023.
+ *
+ * ONLY EVER PASS QUESTIONS VISIBLE ON THE PAGE. Structured data describing content a visitor
+ * cannot see is a manual-action risk, not a shortcut.
+ */
+export function faqNode(ctx: GraphContext, faq: Array<{ question: string; answer: string }>) {
+  if (!faq?.length) return null;
+  return {
+    '@type': 'FAQPage',
+    '@id': `${ctx.url}#faq`,
+    isPartOf: { '@id': `${ctx.url}#webpage` },
+    mainEntity: faq.map((item) => ({
+      '@type': 'Question',
+      name: item.question,
+      acceptedAnswer: { '@type': 'Answer', text: item.answer },
+    })),
+  };
+}

package/src/includes/webmonterey/zoned-hour.test.ts ADDED Viewed

@@ -0,0 +1,49 @@
+/*
+ * The hour-in-zone primitive that every scheduled job depends on.
+ *
+ * Cron runs in UTC with no timezone setting anywhere in Cloudflare, so a job that must land at a
+ * local hour fires hourly and asks this function whether it is time. Get this wrong and the job
+ * runs at the wrong hour for half the year, or never runs at all - and neither reports anything.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { zonedHour, DEFAULT_TIME_ZONE } from './config.ts';
+test('Pacific is UTC-8 in winter', () => {
+  // 2026-01-15T18:00Z is 10:00 PST.
+  assert.equal(zonedHour(new Date('2026-01-15T18:00:00Z'), 'America/Los_Angeles'), 10);
+});
+test('Pacific is UTC-7 in summer, so a fixed UTC hour would drift', () => {
+  /*
+   * The whole reason this exists. The SAME UTC instant is 10:00 in winter and 11:00 in summer, so
+   * an evening job pinned to a UTC hour goes out at 8pm for half the year and 9pm for the other.
+   */
+  assert.equal(zonedHour(new Date('2026-07-15T18:00:00Z'), 'America/Los_Angeles'), 11);
+});
+test('midnight is 0, never 24', () => {
+  /*
+   * hourCycle: 'h23' is what makes this true. The obvious `hour12: false` renders midnight as 24
+   * in several implementations - a job scheduled for hour 0 then never fires, and one testing
+   * `hour < 1` fires twice. Wrong for a year before anyone notices.
+   */
+  assert.equal(zonedHour(new Date('2026-01-15T08:00:00Z'), 'America/Los_Angeles'), 0);
+  assert.equal(zonedHour(new Date('2026-07-15T07:00:00Z'), 'America/Los_Angeles'), 0);
+});
+test('the day rolls over at the right moment, not at UTC midnight', () => {
+  // 2026-03-02T07:59Z is 23:59 on the 1st in Pacific; one minute later it is midnight on the 2nd.
+  assert.equal(zonedHour(new Date('2026-03-02T07:59:00Z'), 'America/Los_Angeles'), 23);
+  assert.equal(zonedHour(new Date('2026-03-02T08:00:00Z'), 'America/Los_Angeles'), 0);
+});
+test('the fleet default is Pacific, which is the whole target region', () => {
+  assert.equal(DEFAULT_TIME_ZONE, 'America/Los_Angeles');
+  assert.equal(zonedHour(new Date('2026-01-15T18:00:00Z'), DEFAULT_TIME_ZONE), 10);
+});
+test('another zone can be asked for explicitly', () => {
+  assert.equal(zonedHour(new Date('2026-01-15T18:00:00Z'), 'UTC'), 18);
+  assert.equal(zonedHour(new Date('2026-01-15T18:00:00Z'), 'America/New_York'), 13);
+});

package/src/integration/adapter.ts ADDED Viewed

@@ -0,0 +1,53 @@
+/*
+ * The Cloudflare adapter, pre-configured.
+ *
+ * WHY THIS IS A SEPARATE EXPORT AND NOT SET BY THE INTEGRATION.
+ *
+ * An adapter set through `updateConfig` from inside `astro:config:setup` does NOT get its own
+ * integration hooks run. Astro accepts the config, the build starts, and then dies with:
+ *
+ *   [UNRESOLVED_ENTRY] Cannot resolve entry module virtual:astro:legacy-ssr-entry
+ *
+ * the moment any route is on-demand. A fully static site never notices, which is exactly how it
+ * survived: examples/minimal had no `prerender = false` route and no form, so it built cleanly
+ * while the form pipeline - the thing the package exists to provide - could not build at all.
+ *
+ * Reproduced against bare Astro: identical config, adapter in `defineConfig` builds, adapter via
+ * `updateConfig` fails. Generation 1 already knew this and shipped `@cparkerwebm/webmonterey/adapter`
+ * for the same reason.
+ *
+ * So the client's astro.config.mjs names the adapter itself:
+ *
+ *     import { defineConfig } from 'astro/config';
+ *     import webmonterey, { adapter } from '@cparkerwebm/webmonterey';
+ *
+ *     export default defineConfig({
+ *       adapter: adapter(),
+ *       integrations: [webmonterey()],
+ *     });
+ *
+ * Two lines rather than one, and the site does not take a direct dependency on
+ * @astrojs/cloudflare - the package still owns which adapter and how it is configured.
+ */
+import cloudflare from '@astrojs/cloudflare';
+export interface AdapterOptions {
+  /**
+   * Override only with a reason.
+   *
+   * 'compile' optimizes images at BUILD with sharp. The adapter's own default is
+   * 'cloudflare-binding', which transforms at request time through Cloudflare Images - a separate,
+   * paid product. For a static marketing site that is slower and an unnecessary dependency: every
+   * image is known at build, so it should be resized once rather than per request.
+   *
+   * Switch only for genuine runtime transforms - user uploads, or remote images whose dimensions
+   * are unknown until requested.
+   */
+  imageService?: 'compile' | 'cloudflare-binding' | 'passthrough';
+}
+export function adapter(options: AdapterOptions = {}) {
+  return cloudflare({ imageService: options.imageService ?? 'compile' });
+}
+export default adapter;

package/src/integration/app-middleware.ts ADDED Viewed

@@ -0,0 +1,43 @@
+/*
+ * THE WEB APP'S PUBLIC PATH, when it differs from the folder.
+ *
+ * The app lives at src/pages/webapp/ on every site, and by default is served at /webapp/. A
+ * client whose customers log in does not want the framework's folder name in their address bar,
+ * so webmonterey.json's `app.path` lets them say `portal` - and this is the piece that makes
+ * that true: `/portal/dashboard` is rewritten to render `/webapp/dashboard` while the browser
+ * URL stays put.
+ *
+ * INJECTED BY THE INTEGRATION, not written by the site, and only when `app.enabled` is on AND
+ * the path differs from the folder. With the default path there is nothing to rewrite and this
+ * module is never loaded. A site's own src/middleware.ts, if it has one, runs after this.
+ *
+ * The folder name is also REDIRECTED to the public path, so one page cannot answer at two URLs
+ * - a canonical problem search engines report, and a leak of the framework's naming into a
+ * client's product.
+ *
+ * Everything under the folder must be `prerender = false`. A rewrite can only land on a route the
+ * Worker renders; a prerendered page under src/pages/webapp/ is a static file the asset router
+ * serves at its own path and this never sees. `webm doctor` checks.
+ */
+import { defineMiddleware } from 'astro:middleware';
+import site from 'virtual:webm/site';
+import { APP_DIR, appEnabled, resolveAppPath } from '../includes/webmonterey/config.ts';
+const publicPath = resolveAppPath(site);
+const active = appEnabled(site) && publicPath !== APP_DIR;
+const under = (pathname: string, segment: string) =>
+  pathname === `/${segment}` || pathname.startsWith(`/${segment}/`);
+export const onRequest = defineMiddleware((context, next) => {
+  if (!active) return next();
+  const { pathname } = context.url;
+  if (under(pathname, publicPath)) {
+    return context.rewrite(`/${APP_DIR}${pathname.slice(publicPath.length + 1)}`);
+  }
+  if (under(pathname, APP_DIR)) {
+    return context.redirect(`/${publicPath}${pathname.slice(APP_DIR.length + 1)}`, 301);
+  }
+  return next();
+});

package/src/integration/config.ts ADDED Viewed

@@ -0,0 +1,96 @@
+/*
+ * Reading the client's config files.
+ *
+ * Kept separate from the integration so it is testable without Astro, and so `webm doctor` and
+ * `webm sync` read the config exactly the way the build does rather than reimplementing it.
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import type { SiteConfig } from '../includes/webmonterey/config.ts';
+import type { DesignSystem } from '../design/types.ts';
+export class ConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ConfigError';
+  }
+}
+function readJson<T>(path: string, what: string, required: boolean): T | null {
+  if (!existsSync(path)) {
+    if (required) {
+      throw new ConfigError(`${what} not found at ${path}. Every site needs one.`);
+    }
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as T;
+  } catch (error) {
+    /*
+     * Name the file. A JSON syntax error surfaces from deep inside the build otherwise, and the
+     * message alone ("Unexpected token }") does not say which of the two config files it came
+     * from.
+     */
+    throw new ConfigError(
+      `${what} at ${path} is not valid JSON: ${error instanceof Error ? error.message : error}`,
+    );
+  }
+}
+export interface SiteFiles {
+  site: SiteConfig;
+  design: DesignSystem;
+  /** Absolute paths, for addWatchFile - editing either must trigger a rebuild. */
+  paths: { site: string; design: string | null };
+}
+/**
+ * Load webmonterey.json and design.json from a site root.
+ *
+ * design.json is OPTIONAL. A site with no design file compiles the default token set, which is
+ * exactly what a freshly minted site should look like before anyone has chosen a palette.
+ * webmonterey.json is required, because `domain` alone switches on canonical tags, Open Graph
+ * URLs, the sitemap and the credit's attribution.
+ */
+export function loadSiteFiles(root: string): SiteFiles {
+  const sitePath = join(root, 'webmonterey.json');
+  const designPath = join(root, 'design.json');
+  const site = readJson<SiteConfig>(sitePath, 'webmonterey.json', true)!;
+  const design = readJson<DesignSystem>(designPath, 'design.json', false);
+  return {
+    site,
+    design: design ?? {},
+    paths: { site: sitePath, design: design ? designPath : null },
+  };
+}
+/**
+ * The production origin, or undefined while `domain` is still the placeholder.
+ *
+ * Deliberately undefined rather than a localhost guess. With `site` unset Astro suppresses
+ * canonical tags and the sitemap integration is not added - both better than a canonical tag
+ * pointing at localhost, or a sitemap that cannot be built because it has no absolute URL.
+ */
+export function resolveSiteUrl(config: SiteConfig): string | undefined {
+  const domain = config.domain;
+  return domain && domain !== 'CHANGEME' ? `https://${domain}` : undefined;
+}
+/**
+ * Every form definition in a site, keyed by id.
+ *
+ * The id is the FILENAME, which is what page JSON and the action's `form` field reference. There
+ * is no registry to keep in step - adding src/forms/quote.json is the whole job.
+ */
+export function loadForms(root: string): Record<string, unknown> {
+  const dir = join(root, 'src/forms');
+  if (!existsSync(dir)) return {};
+  const out: Record<string, unknown> = {};
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith('.json')) continue;
+    out[file.replace(/\.json$/, '')] = readJson(join(dir, file), `src/forms/${file}`, true);
+  }
+  return out;
+}

package/src/integration/content.ts ADDED Viewed

@@ -0,0 +1,66 @@
+/*
+ * The content collection, for a client's src/content.config.ts.
+ *
+ * Astro requires that file at a FIXED path in the client repo, so the package cannot own it.
+ * What the package can own is the page schema - everything except the block union, which is
+ * necessarily site-local because every component is.
+ *
+ * A client's content.config.ts becomes:
+ *
+ *     import { webmontereyCollections } from '@cparkerwebm/webmonterey/content';
+ *     import { schema as content000001 } from './components/content/content-000001/schema.ts';
+ *     export const collections = webmontereyCollections([content000001]);
+ *
+ * WHY THE UNION MATTERS: it is what makes a typo in page JSON a BUILD ERROR rather than a blank
+ * space on the page. Generation 2 used `z.looseObject({ type: z.string() })` until v1.3 purely
+ * because there was no component to build a union from, and that version accepted any typo
+ * silently - the block rendered as nothing, with only a console warning.
+ */
+import { defineCollection } from 'astro:content';
+import { glob } from 'astro/loaders';
+import { z } from 'astro/zod';
+/*
+ * The option type for a discriminated union.
+ *
+ * DERIVED FROM THE FUNCTION, not imported. astro/zod is zod 4, where the option constraint is
+ * `core.$ZodTypeDiscriminable` - an internal export that is not re-exported and would break on a
+ * patch release. Zod 3's `ZodDiscriminatedUnionOption` no longer exists, so any snippet using it
+ * is pre-v4 and wrong.
+ */
+type BlockSchema = Parameters<typeof z.discriminatedUnion>[1][number];
+/**
+ * @param blockSchemas Every component's schema. Each must be an object schema with a literal
+ *   `type` matching its folder ID. Zod needs at least one member for a discriminated union.
+ */
+export function webmontereyCollections(blockSchemas: readonly [BlockSchema, ...BlockSchema[]]) {
+  const blockSchema = z.discriminatedUnion('type', [...blockSchemas]);
+  const pages = defineCollection({
+    /*
+     * One JSON file per page; the filename is the route.
+     *   src/content/pages/home.json         ->  /
+     *   src/content/pages/about.json        ->  /about
+     *   src/content/pages/services/seo.json ->  /services/seo
+     * `home` is the only special case - see the router.
+     */
+    loader: glob({ base: './src/content/pages', pattern: '**/*.json' }),
+    schema: z.object({
+      /** Used for <title>, and rendered as the page's h1 unless `showTitle` is false. */
+      title: z.string(),
+      /*
+       * Defaults TRUE so a page is structurally complete by default: a page whose only headings
+       * are the h2s of its prose blocks has no h1 at all, which is a document-outline bug rather
+       * than a style preference. Set false on a page whose first block renders its own h1.
+       */
+      showTitle: z.boolean().default(true),
+      /** Meta description. Optional, but set it on any page that matters for search. */
+      description: z.string().optional(),
+      /** Ordered list of blocks. Each `type` must exist in the component registry. */
+      blocks: z.array(blockSchema).default([]),
+    }),
+  });
+  return { pages };
+}