@cparkerwebm/webmonterey 1.0.0

package/src/integration/image-size.test.ts

@@ -0,0 +1,83 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { writeFileSync, mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { imageSize } from './image-size.ts';
+
+const dir = mkdtempSync(join(tmpdir(), 'webm-img-'));
+
+function write(name: string, bytes: number[]): string {
+  const path = join(dir, name);
+  writeFileSync(path, new Uint8Array(bytes));
+  return path;
+}
+
+/** A PNG signature plus an IHDR chunk declaring the given size. Nothing else is read. */
+function png(width: number, height: number): number[] {
+  const size = (n: number) => [(n >> 24) & 255, (n >> 16) & 255, (n >> 8) & 255, n & 255];
+  return [
+    0x89,
+    0x50,
+    0x4e,
+    0x47,
+    0x0d,
+    0x0a,
+    0x1a,
+    0x0a,
+    0,
+    0,
+    0,
+    13,
+    0x49,
+    0x48,
+    0x44,
+    0x52,
+    ...size(width),
+    ...size(height),
+    8,
+    6,
+    0,
+    0,
+    0,
+  ];
+}
+
+test('a PNG reports its real dimensions', () => {
+  // 1280x672 is the case that motivated this: webmonterey.com shipped exactly that while
+  // declaring 1200x630 in its og:image tags, for its whole life.
+  assert.deepEqual(imageSize(write('a.png', png(1280, 672))), { width: 1280, height: 672 });
+  assert.deepEqual(imageSize(write('b.png', png(1200, 630))), { width: 1200, height: 630 });
+});
+
+test('a GIF reports its dimensions, little-endian', () => {
+  const gif = [
+    0x47, 0x49, 0x46, 0x38, 0x39, 0x61, 0x00, 0x04, 0xb0, 0x02, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+    0, 0,
+  ];
+  assert.deepEqual(imageSize(write('c.gif', gif)), { width: 1024, height: 688 });
+});
+
+test('a JPEG is walked to its frame header, skipping segments that are not one', () => {
+  const jpeg = [
+    0xff, 0xd8,
+    /* APP0, 16 bytes long, carrying no dimensions - it must be skipped by its length. */
+    0xff, 0xe0, 0x00, 0x10, 0x4a, 0x46, 0x49, 0x46, 0, 1, 1, 0, 0, 1, 0, 1, 0, 0,
+    /* SOF0: length, precision, then height and width. */
+    0xff, 0xc0, 0x00, 0x11, 0x08, 0x02, 0xa0, 0x05, 0x00, 3, 1, 0x22, 0, 2, 0x11, 1, 3, 0x11, 1,
+  ];
+  assert.deepEqual(imageSize(write('d.jpg', jpeg)), { width: 1280, height: 672 });
+});
+
+test('a file that is not an image, or is missing, returns null rather than a guess', () => {
+  assert.equal(
+    imageSize(
+      write(
+        'e.txt',
+        [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24],
+      ),
+    ),
+    null,
+  );
+  assert.equal(imageSize(join(dir, 'nope.png')), null);
+});

package/src/integration/image-size.ts

@@ -0,0 +1,100 @@
+/*
+ * Read an image's real dimensions from its header.
+ *
+ * WHY THIS EXISTS. og:image:width and og:image:height have to travel with the share image, and
+ * nothing in the toolchain can check them: files in public/ are copied verbatim and never
+ * processed, so a client dropping in a differently sized card publishes false dimensions and no
+ * build, test or linter says a word.
+ *
+ * Generations 1 and 2 handled it with a comment telling the reader to keep the numbers in step.
+ * They did not: webmonterey.com shipped a 1280x672 image declaring 1200x630 for its whole life,
+ * and the comment warning about it was sitting in the same file. A crawler uses these to lay the
+ * card out before it fetches the image, so wrong values are worse than none.
+ *
+ * Header parsing only - no dependency, and it reads a few dozen bytes rather than decoding.
+ */
+import { openSync, readSync, closeSync } from 'node:fs';
+
+export interface ImageSize {
+  width: number;
+  height: number;
+}
+
+/*
+ * Read the first `length` bytes, or fewer if the file is shorter.
+ *
+ * Uint8Array and DataView rather than Buffer's read helpers: the package builds under a tsconfig
+ * that does not pull in Node's Buffer typings, and these are the platform primitives anyway.
+ */
+function head(path: string, length: number): Uint8Array | null {
+  let fd: number | undefined;
+  try {
+    fd = openSync(path, 'r');
+    const bytes = new Uint8Array(length);
+    const read = readSync(fd, bytes, 0, length, 0);
+    return bytes.subarray(0, read);
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+const PNG_MAGIC = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+
+const startsWith = (bytes: Uint8Array, prefix: number[]): boolean =>
+  prefix.every((byte, i) => bytes[i] === byte);
+
+const ascii = (bytes: Uint8Array, start: number, end: number): string =>
+  String.fromCharCode(...bytes.subarray(start, end));
+
+/**
+ * PNG, GIF and JPEG. WebP and AVIF are deliberately absent: neither is a safe share image
+ * anyway - several crawlers still will not decode them - so a card should not be in one.
+ */
+export function imageSize(path: string): ImageSize | null {
+  const bytes = head(path, 65_536);
+  if (!bytes || bytes.length < 24) return null;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+
+  /* PNG: an 8-byte signature, then an IHDR chunk whose first two fields are the dimensions. */
+  if (startsWith(bytes, PNG_MAGIC) && ascii(bytes, 12, 16) === 'IHDR') {
+    return { width: view.getUint32(16), height: view.getUint32(20) };
+  }
+
+  /* GIF: 'GIF87a' or 'GIF89a', then width and height as little-endian 16-bit. */
+  if (ascii(bytes, 0, 3) === 'GIF') {
+    return { width: view.getUint16(6, true), height: view.getUint16(8, true) };
+  }
+
+  /*
+   * JPEG: a chain of length-prefixed segments. Walk them to a Start Of Frame, which is where the
+   * dimensions live. SOF0/1/2/3/5/6/7/9/10/11/13/14/15 all carry them; DHT (c4), DNL (c8) and
+   * JPG (cc) share the range and do not, so they are skipped explicitly.
+   */
+  if (bytes[0] === 0xff && bytes[1] === 0xd8) {
+    let offset = 2;
+    while (offset + 9 < bytes.length) {
+      if (bytes[offset] !== 0xff) {
+        offset++;
+        continue;
+      }
+      const marker = bytes[offset + 1]!;
+      if (
+        marker >= 0xc0 &&
+        marker <= 0xcf &&
+        marker !== 0xc4 &&
+        marker !== 0xc8 &&
+        marker !== 0xcc
+      ) {
+        return { width: view.getUint16(offset + 7), height: view.getUint16(offset + 5) };
+      }
+      /* Not a frame header - skip this segment by its own declared length. */
+      const length = view.getUint16(offset + 2);
+      if (length < 2) return null;
+      offset += 2 + length;
+    }
+  }
+
+  return null;
+}

package/src/integration/index.ts

@@ -0,0 +1,386 @@
+/*
+ * The WebMonterey Astro integration.
+ *
+ * A client's astro.config.mjs is this, and nothing else:
+ *
+ *     import { defineConfig } from 'astro/config';
+ *     import webmonterey, { adapter } from '@cparkerwebm/webmonterey';
+ *     export default defineConfig({ adapter: adapter(), integrations: [webmonterey()] });
+ *
+ * The adapter is named there and not set from in here - see integration/adapter.ts for why it
+ * cannot be, and what the build does when it is missing.
+ *
+ * Generation 2's astro.config.mjs was ninety lines, most of them comments explaining traps that
+ * a reader had to keep true by hand: derive `site` from webmonterey.json, keep NOINDEX_ROUTES in
+ * step with every `<Base noindex>`, remember imageService: 'compile'. Each of those is now a
+ * decision made once, here, and a fix propagates on `npm update` rather than never.
+ *
+ * >> WRITTEN AGAINST THE ASTRO INTEGRATION API FROM RECALL, NOT FROM THE DOCS MCP, which was not
+ * >> available in the session that wrote it. Verify hook names, `updateConfig` merge semantics
+ * >> and `injectRoute` options against docs.astro.build before this ships. Astro moves fast and
+ * >> much of the training corpus is two majors out of date - that is rule 9, and it applies to
+ * >> the package as much as to a client site.
+ */
+import type { AstroIntegration } from 'astro';
+import sitemap from '@astrojs/sitemap';
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+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';
+
+export interface WebmontereyOptions {
+  /**
+   * Routes kept out of the sitemap. Each must ALSO pass `noindex` to the base layout - this list
+   * only controls the sitemap.
+   *
+   * Deliberately NOT added to robots.txt. Disallowing a path there stops crawlers fetching it,
+   * so they never see the noindex tag, and an inbound link can get the URL indexed anyway with
+   * no description. To exclude a page you must let it be crawled.
+   */
+  noindexRoutes?: string[];
+  /** Skip the block router, for a site that defines all its own routes. Rare. */
+  router?: boolean;
+  /**
+   * Serve `/robots.txt`. Default true.
+   *
+   * Set false for a site that needs its own — a staging host disallowing everything, or a client
+   * with real crawl rules. Until 1.5 this route was injected unconditionally and a static
+   * `public/robots.txt` lost to it with nothing said.
+   */
+  robots?: boolean;
+  /**
+   * Serve `/webm`, the component scratch page, in `astro dev`. Default true.
+   *
+   * DEV ONLY. It is a workbench for building a block in isolation, and a workbench has no
+   * business on a client's production domain - it used to be injected into every build, noindex
+   * but live, with a comment asking people to remember to empty it. Now it simply does not exist
+   * outside the dev server.
+   */
+  diagnosticsPage?: boolean;
+  /**
+   * Add `@astrojs/sitemap`. Default true whenever `domain` is set.
+   *
+   * Set false for a site publishing a sitemap another way, rather than having two disagree.
+   */
+  sitemap?: boolean;
+}
+
+const VIRTUAL = {
+  site: 'virtual:webm/site',
+  design: 'virtual:webm/design',
+  tokens: 'virtual:webm/tokens.css',
+  registry: 'virtual:webm/registry',
+  forms: 'virtual:webm/forms',
+  custom: 'virtual:webm/custom',
+  shareImage: 'virtual:webm/share-image',
+  icons: 'virtual:webm/icons',
+} as const;
+
+/** Vite resolves virtual ids to a `\0`-prefixed form so other plugins leave them alone. */
+const resolved = (id: string) => `\0${id}`;
+
+export default function webmonterey(options: WebmontereyOptions = {}): AstroIntegration {
+  return {
+    name: '@cparkerwebm/webmonterey',
+
+    hooks: {
+      'astro:config:setup': ({
+        command,
+        config,
+        updateConfig,
+        injectRoute,
+        addMiddleware,
+        addWatchFile,
+        logger,
+      }) => {
+        const root = config.root.pathname;
+        const files = loadSiteFiles(root);
+        const site = resolveSiteUrl(files.site);
+        const app = appEnabled(files.site);
+        const appPath = resolveAppPath(files.site);
+
+        /*
+         * Editing either config file must rebuild. Without this a palette change in design.json
+         * shows nothing until the dev server is restarted, which reads as the compiler being
+         * broken.
+         */
+        addWatchFile(files.paths.site);
+        if (files.paths.design) addWatchFile(files.paths.design);
+
+        /*
+         * The adapter cannot be set from here - see integration/adapter.ts. Catch its absence with
+         * a message that says what to do, instead of letting the build fail later with
+         * "Cannot resolve entry module virtual:astro:legacy-ssr-entry", which names nothing the
+         * reader wrote.
+         */
+        if (!config.adapter) {
+          throw new Error(
+            '[webm] No adapter. astro.config.mjs must set one:\n\n' +
+              "    import webmonterey, { adapter } from '@cparkerwebm/webmonterey';\n\n" +
+              '    export default defineConfig({\n' +
+              '      adapter: adapter(),\n' +
+              '      integrations: [webmonterey()],\n' +
+              '    });\n\n' +
+              'It cannot be set by the integration: an adapter registered through updateConfig does ' +
+              'not run its own hooks, and the build then fails on the first on-demand route.',
+          );
+        }
+
+        if (!site) {
+          logger.warn(
+            'webmonterey.json "domain" is still CHANGEME. Canonical tags, Open Graph URLs and ' +
+              'the sitemap are suppressed until it is set - deliberately, since a canonical tag ' +
+              'pointing at localhost is worse than none.',
+          );
+        }
+
+        /* The app is authenticated, so it is never in the sitemap. Its PUBLIC path, not the folder. */
+        const noindex = [
+          '/webm',
+          ...(app ? [`/${appPath}`] : []),
+          ...(options.noindexRoutes ?? []),
+        ];
+
+        updateConfig({
+          site,
+
+          /*
+           * Static by default: marketing pages prerender to plain HTML on the edge. A route
+           * needing a binding opts out per file with `export const prerender = false` - and
+           * every such route must also appear in wrangler.jsonc's run_worker_first, or it
+           * returns 200 to curl and a 404 page to Chrome. `webm doctor` checks that.
+           */
+          output: 'static',
+
+          integrations:
+            site && options.sitemap !== false
+              ? [
+                  sitemap({
+                    filter: (page) => {
+                      const path = new URL(page).pathname.replace(/\/$/, '') || '/';
+                      return !noindex.some((n) => path === n || path.startsWith(`${n}/`));
+                    },
+                  }),
+                ]
+              : [],
+
+          vite: {
+            /*
+             * A site that adds a custom Worker entrypoint - the supported way to get a
+             * scheduled() handler alongside the adapter's fetch - imports
+             * @astrojs/cloudflare/handler. Vite pre-bundles that into node_modules/.vite/deps_ssr,
+             * and any re-optimisation (which `astro check`, or a build running alongside
+             * `astro dev`, triggers) changes its ?v= hash. The running dev server then 500s on
+             * EVERY request with "The file does not exist at .../handler-*.js".
+             *
+             * Excluding it is the fix the error message itself suggests. It is an adapter
+             * entrypoint that needs no bundling, so this costs nothing on a site that never adds
+             * one - and it means a site that does cannot walk into a dev server that has stopped
+             * serving anything at all.
+             *
+             * Found in friendsofthemarinalibrary.org, which has run a scheduled sweep this way
+             * since generation 2 and had to work it out by hand.
+             */
+            optimizeDeps: {
+              exclude: ['@astrojs/cloudflare/handler'],
+            },
+            ssr: {
+              /*
+               * PROCESS THIS PACKAGE'S SOURCE LIKE THE APP'S OWN.
+               *
+               * Vite externalizes node_modules by default, which is right for a compiled
+               * dependency and wrong for this one: the package ships .ts source that imports
+               * Astro and Cloudflare virtual modules - `cloudflare:workers` above all. Left
+               * external, rolldown sees a bare specifier it cannot resolve and the build dies
+               * with "Failed to resolve import cloudflare:workers", naming a file inside
+               * node_modules that the reader did not write.
+               *
+               * This only bites once a site wires the form pipeline, because that is the first
+               * thing to pull in includes/cloudflare/workers/env.ts. A site with no forms builds
+               * cleanly without it - which is exactly how it went unnoticed.
+               */
+              noExternal: ['@cparkerwebm/webmonterey'],
+            },
+            plugins: [
+              {
+                name: 'webm:virtual',
+                resolveId(id: string) {
+                  if (Object.values(VIRTUAL).includes(id as never)) return resolved(id);
+                  return null;
+                },
+                load(id: string) {
+                  switch (id) {
+                    case resolved(VIRTUAL.site):
+                      return `export default ${JSON.stringify(files.site)};`;
+                    case resolved(VIRTUAL.design):
+                      return `export default ${JSON.stringify(files.design)};`;
+                    case resolved(VIRTUAL.tokens):
+                      return compileToCss(files.design);
+                    case resolved(VIRTUAL.shareImage): {
+                      /*
+                       * The share image's REAL size, read from its header at build time.
+                       *
+                       * og:image:width and og:image:height have to match the file, and nothing
+                       * else in the toolchain can check: public/ is copied verbatim, so a client
+                       * dropping in a differently sized card publishes false dimensions and no
+                       * build or test says a word. webmonterey.com shipped a 1280x672 image
+                       * declaring 1200x630 for its whole life, with a comment warning about
+                       * exactly that sitting in the same file.
+                       *
+                       * null when the file is absent or unreadable, and base.astro then omits
+                       * both tags - the scrapers all measure the image themselves anyway, so
+                       * saying nothing beats saying something wrong.
+                       */
+                      const size = imageSize(join(root, 'public/open-graph.png'));
+                      return `export default ${JSON.stringify(size)};`;
+                    }
+                    case resolved(VIRTUAL.icons): {
+                      /*
+                       * WHICH ICON FILES THE SITE ACTUALLY HAS.
+                       *
+                       * The layout used to link favicon.svg unconditionally. A site without one
+                       * then served the SEEDED PLACEHOLDER - WebMonterey's own mark - as the
+                       * client's icon, and because browsers prefer SVG over .ico it was the one
+                       * actually shown. Caught on a rebuild where the client had .ico and PNGs
+                       * and no SVG at all.
+                       *
+                       * public/ is copied verbatim, so nothing else can see this.
+                       */
+                      const icons = Object.fromEntries(
+                        [
+                          'favicon.svg',
+                          'favicon.ico',
+                          'favicon-16x16.png',
+                          'favicon-32x32.png',
+                          'apple-touch-icon.png',
+                          'site.webmanifest',
+                        ].map((file) => [file, existsSync(join(root, 'public', file))]),
+                      );
+                      return `export default ${JSON.stringify(icons)};`;
+                    }
+                    case resolved(VIRTUAL.custom): {
+                      /*
+                       * THE CLIENT OVERRIDE SEAM, and it was disconnected until it was tested.
+                       *
+                       * base.astro imports the package's global.css by relative path, so the
+                       * site's own src/styles/index.css - which the scaffold wrote as the entry
+                       * point that pulls in custom/ - was imported by nothing at all. A client
+                       * could write a rule in custom/_index.css, see it in the repo, and never
+                       * see it on the page. No error, no warning: the file simply was not in the
+                       * graph. That is webm.components.custom, the layer whose entire job is
+                       * beating webm.components.core.
+                       *
+                       * A JS module that imports the real path, rather than the file's contents
+                       * inlined: a virtual module has no directory, so relative @import inside
+                       * the client's own CSS would not resolve if this returned text.
+                       */
+                      const custom = join(root, 'src/styles/custom/_index.css');
+                      return existsSync(custom) ? `import ${JSON.stringify(custom)};` : '';
+                    }
+                    case resolved(VIRTUAL.forms):
+                      return `export const FORMS = ${JSON.stringify(loadForms(root))};`;
+                    case resolved(VIRTUAL.registry):
+                      /*
+                       * Re-exported from the client repo, because every visible component lives
+                       * there - the package ships none. A site with no registry gets an empty
+                       * one rather than a resolution failure, so `webm new` can scaffold in any
+                       * order.
+                       */
+                      return [
+                        `let mod = { blocks: {}, registeredTypes: () => [] };`,
+                        `try { mod = await import(${JSON.stringify(root + 'src/components/registry.ts')}); } catch {}`,
+                        `export const blocks = mod.blocks ?? {};`,
+                        `export const registeredTypes = mod.registeredTypes ?? (() => Object.keys(blocks));`,
+                        /*
+                         * SITE CHROME. The package's layout has header and footer slots and
+                         * ships nothing to fill them, and the router that renders every page is
+                         * package-owned - so without this a site literally cannot get a header
+                         * onto its own pages short of overriding the router and duplicating it.
+                         *
+                         * Deliberately NOT entries in `blocks`: a registered type is addressable
+                         * from a page's JSON, and a page that lists its header as a block stacks
+                         * a second one under the real one. Chrome is rendered once by the layout,
+                         * so it is exported separately and named separately.
+                         */
+                        `export const header = mod.header ?? null;`,
+                        `export const footer = mod.footer ?? null;`,
+                        /* Overlays - a mobile menu, a CTA drawer - rendered at the end of body. */
+                        `export const panels = mod.panels ?? [];`,
+                        /*
+                         * The page header. A site that declares one gets it in place of the
+                         * router's plain <h1>; a site that does not keeps the <h1>.
+                         */
+                        `export const pageHeader = mod.pageHeader ?? 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
+                         * site's to say, and every attempt to say it generically grew a field a
+                         * day and still fit nobody. The builders in ./structured-data are the
+                         * mechanism; this component is the content. /webm:launch is where it
+                         * gets written.
+                         */
+                        `export const structuredData = mod.structuredData ?? null;`,
+                      ].join('\n');
+                    default:
+                      return null;
+                  }
+                },
+              },
+            ],
+          },
+        });
+
+        /*
+         * EVERY INJECTED ROUTE HAS AN OFF SWITCH.
+         *
+         * Two of these had none. A site wanting its own /robots.txt - a staging host disallowing
+         * everything, a client with crawl rules - had no way to say so, and a static
+         * public/robots.txt lost to the injected route silently.
+         *
+         * The default is unchanged in each case; the point is only that "no" is now sayable.
+         */
+        if (options.router !== false) {
+          injectRoute({ pattern: '/[...slug]', entrypoint: '@cparkerwebm/webmonterey/pages/slug' });
+        }
+        if (options.robots !== false) {
+          injectRoute({
+            pattern: '/robots.txt',
+            entrypoint: '@cparkerwebm/webmonterey/pages/robots',
+          });
+        }
+        /* The scratch page exists in the dev server and nowhere else - see the option's note. */
+        if (options.diagnosticsPage !== false && command === 'dev') {
+          injectRoute({ pattern: '/webm', entrypoint: '@cparkerwebm/webmonterey/pages/webm' });
+        }
+
+        /*
+         * THE WEB APP'S PUBLIC PATH. Only when the site has switched the app on AND named a path
+         * other than the folder - with the default there is nothing to rewrite, and a middleware
+         * that runs on every request of every site to do nothing is not free. See app-middleware.
+         */
+        if (app && appPath !== APP_DIR) {
+          addMiddleware({ entrypoint: '@cparkerwebm/webmonterey/app-middleware', order: 'pre' });
+        }
+
+        /*
+         * THE 404. Exported by the package since day one and injected by nobody, so every site
+         * built on it served Cloudflare's default "page not found" instead of the client's.
+         *
+         * Astro turns the `/404` route into 404.html, which the Workers asset router serves for
+         * any unmatched path. A site that wants its own overrides this the ordinary Astro way, by
+         * having src/pages/404.astro - a file in the site beats an injected route, which is the
+         * child-theme rule holding without anything special here.
+         */
+        injectRoute({ pattern: '/404', entrypoint: '@cparkerwebm/webmonterey/pages/404.astro' });
+      },
+    },
+  };
+}
+
+export { adapter, type AdapterOptions } from './adapter.ts';
+export type { SiteConfig, SiteFeatures, Organization } from '../includes/webmonterey/config.ts';
+export type { DesignSystem } from '../design/types.ts';

package/src/integration/virtual.d.ts

@@ -0,0 +1,101 @@
+/*
+ * The virtual modules the integration provides.
+ *
+ * These do not exist on disk. Each resolves at build time to something in the CLIENT repo, which
+ * a package cannot import relatively - see includes/webmonterey/config.ts.
+ */
+declare module 'virtual:webm/site' {
+  import type { SiteConfig } from '../includes/webmonterey/config.ts';
+  const config: SiteConfig;
+  export default config;
+}
+
+declare module 'virtual:webm/design' {
+  import type { DesignSystem } from '../design/types.ts';
+  const design: DesignSystem;
+  export default design;
+}
+
+/** The compiled token layer. Side-effect import only. */
+declare module 'virtual:webm/tokens.css';
+
+/** Which icon files exist in the site's public/. The layout links only what is really there. */
+declare module 'virtual:webm/icons' {
+  const icons: Record<string, boolean>;
+  export default icons;
+}
+
+/** The client's own stylesheet - src/styles/custom/. Side-effect import only. */
+declare module 'virtual:webm/custom';
+
+/**
+ * The real pixel size of `public/open-graph.png`, measured at build time, or null when there is
+ * no readable file there. Nothing else can check it: public/ is copied verbatim.
+ */
+declare module 'virtual:webm/share-image' {
+  const size: { width: number; height: number } | null;
+  export default size;
+}
+
+declare module 'virtual:webm/registry' {
+  import type { AstroComponentFactory } from 'astro/runtime/server/index.js';
+  /** Maps a block `type` in page JSON to the component that renders it. */
+  export const blocks: Record<string, AstroComponentFactory>;
+  /** Every registered block type, so the router can report an unknown one usefully. */
+  export const registeredTypes: () => string[];
+  /**
+   * The site header, rendered once into the layout's `header` slot on every package route.
+   *
+   * NOT a member of `blocks`. A registered type is addressable from a page's JSON, and a page
+   * listing its header as a block would stack a second one under the real one.
+   */
+  export const header: AstroComponentFactory | null;
+  /** The site footer. Same contract as `header`. */
+  export const footer: AstroComponentFactory | null;
+  /**
+   * Overlays rendered once at the end of `<body>` - a mobile menu panel, a CTA drawer.
+   *
+   * They have to sit outside `<main>` to be positioned above everything, so a site with either
+   * has no way to render it through the block system.
+   */
+  export const panels: AstroComponentFactory[];
+  /**
+   * Rendered in place of the router's plain `<h1>` when a page has `showTitle`.
+   *
+   * Receives the page's whole frontmatter, so a site's header can use fields the package has
+   * never heard of - a subtitle, header photos, a category. Without this seam a site that wants
+   * anything more than an `<h1>` has to fork the router, and a forked router stops receiving
+   * every later fix to block lookup, unknown-type reporting and FAQ extraction.
+   */
+  export const pageHeader: 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
+   * `@cparkerwebm/webmonterey/structured-data`, and receives `{ title, description, image }`
+   * for the page being rendered. Null means no structured data on this site.
+   */
+  export const structuredData: AstroComponentFactory | null;
+}
+
+declare module 'virtual:webm/forms' {
+  /** Every form definition in the client repo, keyed by id (the filename). */
+  export const FORMS: Record<
+    string,
+    {
+      name: string;
+      fields: { name: string; label: string; required?: boolean }[];
+      notify: { to: string[]; subject: string };
+      autoresponse?: { subject: string; body: string };
+      /**
+       * Opt this ONE form out of Turnstile, even with `features.turnstile` on.
+       *
+       * For a form whose component renders no widget - a newsletter box with a single inline
+       * field. Such a form mints no token, so verifying it rejects every real submission while
+       * looking completely normal. Omit it and the form is verified, which is the safe default.
+       */
+      turnstile?: boolean;
+      /** Rename the honeypot trap, or `false` to disable it. See includes/webmonterey/forms. */
+      honeypot?: string | false;
+    }
+  >;
+}