create-foldkit-app 0.27.0 → 0.27.1

package/dist/utils/files.js

@@ -1,7 +1,7 @@
 import { Array, Effect, FileSystem, Match, Option, Path, Record, Ref, Schema, String, pipe, } from 'effect';
 import { HttpClient, HttpClientRequest, } from 'effect/unstable/http';
 import { fileURLToPath } from 'node:url';
-import { devCommand, installCommand } from './packages.js';
+import { devCommand, installCommand, runScriptCommand, } from './packages.js';
 const GITHUB_API_BASE_URL = 'https://api.github.com/repos/foldkit/foldkit/contents/examples';
 const getTemplateRoot = Effect.gen(function* () {
     const path = yield* Path.Path;
@@ -94,7 +94,7 @@ export const createProject = (name, projectPath, scaffold, packageManager) => Ef
         Ssr: () => Effect.void,
     }));
 });
-export const applyPackageManager = (readme, packageManager) => pipe(readme, String.replace('{{installCommand}}', installCommand(packageManager)), String.replace('{{devCommand}}', devCommand(packageManager)));
+export const applyPackageManager = (readme, packageManager) => pipe(readme, String.replaceAll('{{installCommand}}', installCommand(packageManager)), String.replaceAll('{{devCommand}}', devCommand(packageManager)), String.replaceAll('{{buildCommand}}', runScriptCommand(packageManager, 'build')), String.replaceAll('{{previewCommand}}', runScriptCommand(packageManager, 'preview')), String.replaceAll('{{startCommand}}', runScriptCommand(packageManager, 'start')));
 const modifyBaseFiles = (projectPath, name, packageManager) => Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;

package/dist/utils/packages.js

@@ -9,6 +9,13 @@ const DEV_COMMANDS = {
     bun: 'bun dev',
 };
 export const devCommand = (packageManager) => DEV_COMMANDS[packageManager];
+const RUN_SCRIPT_PREFIXES = {
+    pnpm: 'pnpm',
+    npm: 'npm run',
+    yarn: 'yarn',
+    bun: 'bun run',
+};
+export const runScriptCommand = (packageManager, script) => `${RUN_SCRIPT_PREFIXES[packageManager]} ${script}`;
 const GITHUB_RAW_BASE_URL = 'https://raw.githubusercontent.com/foldkit/foldkit/main/examples';
 const NPM_REGISTRY_BASE_URL = 'https://registry.npmjs.org';
 const FOLDKIT_SCOPE_PREFIX = '@foldkit/';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-foldkit-app",
-  "version": "0.27.0",
+  "version": "0.27.1",
   "description": "Create Foldkit applications",
   "type": "module",
   "main": "./dist/index.js",

package/templates/package-managers/pnpm/pnpm-workspace.yaml

@@ -1,2 +1,3 @@
 allowBuilds:
+  esbuild: true
   msgpackr-extract: false

package/templates/rendering/ssg/README.md

@@ -0,0 +1,61 @@
+# My Foldkit App
+
+A statically generated Foldkit application built with Effect.
+
+## Getting Started
+
+```bash
+{{installCommand}}
+{{devCommand}}
+```
+
+## Building and previewing
+
+```bash
+{{buildCommand}}
+{{previewCommand}}
+```
+
+The build script runs `scripts/build.mjs`, which builds the client bundle, builds
+the server bundle, prerenders every path `src/entry.server.ts` lists, and gives
+all three steps the same build id.
+
+## The build id
+
+The build id does not make hydration correct. It makes hydration refuse when it
+would otherwise be incorrect.
+
+The generated page carries the id, and the client bundle carries its own copy.
+Hydration compares the two before it reads the Flags payload or adopts DOM.
+When they differ, startup stops and the document body is marked `inert`,
+`aria-hidden`, and `data-foldkit-refused`. A nondismissable modal shield covers
+its controls and existing top-layer content, then takes focus without closing
+author-owned dialogs. Nothing moves, so no custom element reconnects and no
+frame reloads.
+
+Without that check, stale HTML from an earlier deployment can be hydrated by the
+newer client. Where the old markup happens to line up with the new markup,
+an input the old page called `email` can be adopted for whatever the new build
+puts in that position, carrying what the visitor typed into it.
+
+The comparison happens when a client boots against a page. A tab whose client
+is already running when a deployment lands is not rechecked.
+
+`scripts/build.mjs` takes care of this: it produces one id per build and passes
+it to every step. Supply `FOLDKIT_BUILD_ID` when those steps run in separate
+jobs, or when you want the served id to name a deployment you can look up later:
+
+```bash
+FOLDKIT_BUILD_ID="$CI_DEPLOYMENT_ID" {{buildCommand}}
+```
+
+The id is public HTML and must never contain a secret or be derived from one.
+Every step of one deployment must share an id. By contrast, two deployments
+must never share one. Reusing an id produces no warning: the ids agree, so
+hydration proceeds. When in doubt, leave `FOLDKIT_BUILD_ID` unset and let the
+build script generate one.
+
+## Learn More
+
+- [Foldkit Documentation](https://github.com/foldkit/foldkit)
+- [Effect Documentation](https://effect.website)

package/templates/rendering/ssg/package.json

@@ -4,7 +4,7 @@
   "type": "module",
   "scripts": {
     "dev": "vite",
-    "build": "vite build --outDir dist/client && vite build --ssr src/entry.server.ts --outDir dist/server && tsx scripts/prerender.ts",
+    "build": "node scripts/build.mjs",
     "preview": "vite preview --outDir dist/client",
     "typecheck": "tsc --noEmit",
     "format": "prettier -w .",

package/templates/rendering/ssg/scripts/build.mjs

@@ -0,0 +1,40 @@
+import { spawnSync } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+
+// NOTE: one id names this build, and every command below is given that same
+// id, so the client bundle and the server bundle of a deployment agree on which
+// deployment they are. `renderToString` stamps it on the prerendered pages and
+// `Runtime.hydrate` compares it before adopting any DOM, so a page left over
+// from an earlier deployment is refused and contained rather than reconciled
+// against a client that no longer means the same thing by it.
+//
+// The id is published in the HTML every visitor receives. It identifies a
+// deployment and is never a credential, so keep secrets out of it. Set
+// FOLDKIT_BUILD_ID to name builds from a value the deployment already has, such
+// as a commit or a release tag; without one, each build takes a fresh id.
+// NOTE: `??` alone would take an empty FOLDKIT_BUILD_ID as a real value, and
+// the plugin treats empty as absent, so the build would compile no id at all and
+// fail later at the render. Empty is unset here too.
+const supplied = process.env.FOLDKIT_BUILD_ID
+const buildId =
+  supplied === undefined || supplied === '' ? randomUUID() : supplied
+
+const steps = [
+  ['vite', ['build', '--outDir', 'dist/client']],
+  [
+    'vite',
+    ['build', '--ssr', 'src/entry.server.ts', '--outDir', 'dist/server'],
+  ],
+  ['tsx', ['scripts/prerender.ts']],
+]
+
+for (const [command, args] of steps) {
+  const { status } = spawnSync(command, args, {
+    stdio: 'inherit',
+    shell: process.platform === 'win32',
+    env: { ...process.env, FOLDKIT_BUILD_ID: buildId },
+  })
+  if (status !== 0) {
+    process.exit(status ?? 1)
+  }
+}

package/templates/rendering/ssg/src/entry.server.ts

@@ -10,7 +10,7 @@ export const renderPage = (request: Request): Promise<Server.EntryResult> =>
     Effect.gen(function* () {
       const renderedApplication = yield* Server.renderToString(
         { routing: {}, init, view },
-        { url: request.url },
+        { url: request.url, buildId: import.meta.env.FOLDKIT_BUILD_ID },
       )
 
       return Server.Rendered(renderedApplication)

package/templates/rendering/ssg/src/entry.ts

@@ -25,4 +25,4 @@ const application = Runtime.makeApplication({
   },
 })
 
-Runtime.hydrate(application)
+Runtime.hydrate(application, { buildId: import.meta.env.FOLDKIT_BUILD_ID })

package/templates/rendering/ssg/src/vite-env.d.ts

@@ -0,0 +1,19 @@
+/// <reference types="vite/client" />
+
+// `@foldkit/vite-plugin` compiles the deployment's build id in here, from its
+// `buildId` option or the `FOLDKIT_BUILD_ID` environment variable. The server
+// entry hands it to `renderToString` and the client entry to `Runtime.hydrate`,
+// which is how hydration tells a page from this deployment apart from one served
+// by another.
+//
+// Declared as required rather than optional because this project's build always
+// supplies one. A build that did not would produce `undefined` here, and both
+// entries refuse it at runtime; typing it as optional would only push that
+// failure past the compiler and into the served page.
+interface ImportMetaEnv {
+  readonly FOLDKIT_BUILD_ID: string
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}

package/templates/rendering/ssr/README.md

@@ -0,0 +1,65 @@
+# My Foldkit App
+
+A server-rendered Foldkit application built with Effect.
+
+## Getting Started
+
+```bash
+{{installCommand}}
+{{devCommand}}
+```
+
+## Building and serving
+
+```bash
+{{buildCommand}}
+{{startCommand}}
+```
+
+The build script runs `scripts/build.mjs`, which builds the client bundle and the
+server bundle and gives both the same build id.
+
+`PORT` sets the port the server listens on. `ORIGIN` sets the public origin it
+serves, which the server entry sees as `Request.url`; set it when deploying
+behind a proxy or a TLS terminator. It defaults to `http://localhost:<PORT>`.
+
+## The build id
+
+The build id does not make hydration correct. It makes hydration refuse when it
+would otherwise be incorrect.
+
+The server stamps the id on the page, and the client bundle carries its own
+copy. Hydration compares the two before it reads the Flags payload or adopts
+DOM. When they differ, startup stops and the document body is marked `inert`,
+`aria-hidden`, and `data-foldkit-refused`. A nondismissable modal shield covers
+its controls and existing top-layer content, then takes focus without closing
+author-owned dialogs. Nothing moves, so no custom element reconnects and no
+frame reloads.
+
+Without that check, stale HTML from an earlier deployment can be hydrated by the
+newer client. Where the old markup happens to line up with the new markup,
+an input the old page called `email` can be adopted for whatever the new build
+puts in that position, carrying what the visitor typed into it.
+
+The comparison happens when a client boots against a page. A tab whose client
+is already running when a deployment lands is not rechecked.
+
+`scripts/build.mjs` takes care of this: it produces one id per build and passes
+it to both build commands. Supply `FOLDKIT_BUILD_ID` when the two commands run
+in separate jobs, or when you want the served id to name a deployment you can
+look up later:
+
+```bash
+FOLDKIT_BUILD_ID="$CI_DEPLOYMENT_ID" {{buildCommand}}
+```
+
+The id is public HTML and must never contain a secret or be derived from one.
+The client and server halves of one deployment must share an id. By contrast,
+two deployments must never share one. Reusing an id produces no warning: the
+ids agree, so hydration proceeds. When in doubt, leave `FOLDKIT_BUILD_ID` unset
+and let the build script generate one.
+
+## Learn More
+
+- [Foldkit Documentation](https://github.com/foldkit/foldkit)
+- [Effect Documentation](https://effect.website)

package/templates/rendering/ssr/package.json

@@ -4,11 +4,11 @@
   "type": "module",
   "scripts": {
     "dev": "vite",
-    "build": "vite build --outDir dist/client && vite build --ssr server/main.ts --outDir dist/server",
+    "build": "node scripts/build.mjs",
     "start": "node dist/server/main.js",
     "typecheck": "tsc --noEmit",
     "format": "prettier -w .",
     "test": "vitest run",
-    "lint": "oxlint src server"
+    "lint": "oxlint src server scripts"
   }
 }

package/templates/rendering/ssr/scripts/build.mjs

@@ -0,0 +1,36 @@
+import { spawnSync } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+
+// NOTE: one id names this build, and every command below is given that same
+// id, so the client bundle and the server bundle of a deployment agree on which
+// deployment they are. `renderToString` stamps it on the rendered root and
+// `Runtime.hydrate` compares it before adopting any DOM, so a page left over
+// from an earlier deployment is refused and contained rather than reconciled
+// against a client that no longer means the same thing by it.
+//
+// The id is published in the HTML every visitor receives. It identifies a
+// deployment and is never a credential, so keep secrets out of it. Set
+// FOLDKIT_BUILD_ID to name builds from a value the deployment already has, such
+// as a commit or a release tag; without one, each build takes a fresh id.
+// NOTE: `??` alone would take an empty FOLDKIT_BUILD_ID as a real value, and
+// the plugin treats empty as absent, so the build would compile no id at all and
+// fail later at the render. Empty is unset here too.
+const supplied = process.env.FOLDKIT_BUILD_ID
+const buildId =
+  supplied === undefined || supplied === '' ? randomUUID() : supplied
+
+const steps = [
+  ['vite', ['build', '--outDir', 'dist/client']],
+  ['vite', ['build', '--ssr', 'server/main.ts', '--outDir', 'dist/server']],
+]
+
+for (const [command, args] of steps) {
+  const { status } = spawnSync(command, args, {
+    stdio: 'inherit',
+    shell: process.platform === 'win32',
+    env: { ...process.env, FOLDKIT_BUILD_ID: buildId },
+  })
+  if (status !== 0) {
+    process.exit(status ?? 1)
+  }
+}

package/templates/rendering/ssr/server/main.ts

@@ -25,42 +25,65 @@ const PROJECT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '../..')
 const CLIENT_DIR = resolve(PROJECT_DIR, 'dist/client')
 const DEFAULT_PORT = 3000
 
+const PORT = Config.withDefault(Config.port('PORT'), DEFAULT_PORT)
+
+// NOTE: the origin this deployment serves, which the entry sees as
+// `Request.url`. It is configuration, not something a request carries: a client
+// may send an absolute-form target, or a network-path reference such as
+// `//elsewhere.example/page`, and a `Host` header naming any site at all.
+// Deriving the origin from the request would let the client choose the
+// redirects, canonical URLs, and cookie domains the entry builds from it, so a
+// target that resolves anywhere but this origin is refused before it reaches
+// renderPage. Set ORIGIN to the public origin when deploying behind a proxy or
+// TLS terminator.
+const ORIGIN = Config.option(Config.string('ORIGIN'))
+
 const renderRequest = (
   request: HttpServerRequest.HttpServerRequest,
   template: string,
+  requestUrl: string,
 ) =>
   Effect.gen(function* () {
     const webRequest = yield* HttpServerRequest.toWeb(request)
-    const result = yield* Effect.promise(() => renderPage(webRequest))
+    const result = yield* Effect.promise(() =>
+      renderPage(new Request(requestUrl, webRequest)),
+    )
     return HttpServerResponse.fromWeb(Server.toResponse(template, result))
   })
 
-// NOTE: Vary: Accept keeps a shared cache from serving one client's
-// representation to another when a static miss is answered by content
-// negotiation. It is merged with any Vary the render already set, parsing
-// Vary as field-name tokens so Accept-Language or Accept-Encoding is never
-// mistaken for the Accept field.
-const withVaryAccept = (
+// NOTE: every outcome a static miss negotiates declares both headers the
+// negotiation read. The same extensionless URL answers 404 to a script request
+// and HTML to a navigation, so declaring only one would let a shared cache
+// serve either response to the other kind of request.
+const withNegotiatedVary = (
   response: HttpServerResponse.HttpServerResponse,
 ): HttpServerResponse.HttpServerResponse =>
   HttpServerResponse.setHeader(
     response,
     'vary',
-    Server.varyWithAccept(
-      Option.getOrUndefined(HttpHeaders.get('vary')(response.headers)),
+    Server.varyWith(
+      Server.varyWithAccept(
+        Option.getOrUndefined(HttpHeaders.get('vary')(response.headers)),
+      ),
+      'Sec-Fetch-Dest',
     ),
   )
 
 const isRouteNotFound = (error: HttpServerError.HttpServerError): boolean =>
   error.reason._tag === 'RouteNotFound'
 
-type RequestKind = 'Render' | 'StaticOrRender' | 'MethodNotAllowed'
+type RequestKind = 'Render' | 'StaticOrRender' | 'HostSettled'
 
-// NOTE: `/` and `/index.html` (and the encoded paths that resolve to them)
-// are application requests even though a file exists for them: the file on
-// disk is the unfilled template, and serving it raw would hand the browser an
-// unstamped shell that Runtime.hydrate refuses. Only GET and HEAD render; every
-// other method (OPTIONS, POST, ...) is refused with 405 rather than rendered.
+// NOTE: one rule for every method, matching the Vite dev host so a form action
+// or a `Server.Responded` reply cannot work in development and fail only after
+// deployment. Static files answer GET and HEAD; every other request reaches the
+// server entry, which decides what to do with it. An entry that has no answer
+// for a method returns its own response rather than the host guessing one.
+//
+// `/` and `/index.html` (and the encoded paths that resolve to them) are
+// application requests even though a file exists for them: the file on disk is
+// the unfilled template, and serving it raw would hand the browser an unstamped
+// shell that Runtime.hydrate refuses.
 const requestKind = ({
   method,
   url,
@@ -70,11 +93,31 @@ const requestKind = ({
     M.whenOr('GET', 'HEAD', () =>
       Server.resolvesToIndexHtml(url) ? 'Render' : 'StaticOrRender',
     ),
-    M.orElse(() => 'MethodNotAllowed'),
+    M.orElse(() =>
+      Server.isHostSettledMethod(method) ? 'HostSettled' : 'Render',
+    ),
+  )
+
+// NOTE: CONNECT, TRACE, and TRACK never reach the entry, in this host or under
+// Vite: the WHATWG `Request` constructor rejects them, so forwarding one answers
+// 500 instead of refusing. OPTIONS does reach the entry in both, which is where
+// a preflight is answered.
+const hostSettledResponse = () =>
+  HttpServerResponse.setHeader(
+    HttpServerResponse.empty({
+      status: Server.HOST_METHOD_ANSWERS.refusedStatus,
+    }),
+    'allow',
+    Server.HOST_METHOD_ANSWERS.allow,
   )
 
 const makeHandler = Effect.gen(function* () {
   const fs = yield* FileSystem.FileSystem
+  const port = yield* PORT
+  const origin = Option.getOrElse(
+    yield* ORIGIN,
+    () => `http://localhost:${port}`,
+  )
   const template = yield* fs.readFileString(resolve(CLIENT_DIR, 'index.html'))
   const staticFiles = yield* HttpStaticServer.make({
     root: CLIENT_DIR,
@@ -83,45 +126,78 @@ const makeHandler = Effect.gen(function* () {
 
   // NOTE: a static miss is Accept-negotiated because a deep link into a client
   // route has no file on disk but an HTML client should still get the app
-  // shell. It renders, anything else 404s, and both carry Vary: Accept.
-  const serveStaticOrRender = (request: HttpServerRequest.HttpServerRequest) =>
+  // shell. It renders, anything else 404s, and both carry Vary: Accept. A miss
+  // that names an asset never renders: browsers fetch scripts and stylesheets
+  // with `Accept: */*`, so a hashed asset from a previous deployment would
+  // otherwise be answered with the app shell at 200 and read as a blank page
+  // rather than the 404 it is. That refusal does not depend on Accept, so it
+  // carries no Vary.
+  const serveStaticOrRender = (
+    request: HttpServerRequest.HttpServerRequest,
+    requestUrl: string,
+  ) =>
     staticFiles.pipe(
       Effect.catchIf(isRouteNotFound, () =>
-        Server.acceptsHtml(request.headers['accept'])
-          ? renderRequest(request, template).pipe(Effect.map(withVaryAccept))
-          : Effect.succeed(
-              withVaryAccept(HttpServerResponse.empty({ status: 404 })),
+        M.value(
+          Server.classifyRequest(
+            request.url,
+            request.headers['sec-fetch-dest'],
+          ),
+        ).pipe(
+          M.when('PathAsset', () =>
+            Effect.succeed(HttpServerResponse.empty({ status: 404 })),
+          ),
+          M.when('DestinationAsset', () =>
+            Effect.succeed(
+              withNegotiatedVary(HttpServerResponse.empty({ status: 404 })),
             ),
+          ),
+          M.when('Page', () =>
+            Server.acceptsHtml(request.headers['accept'])
+              ? renderRequest(request, template, requestUrl).pipe(
+                  Effect.map(withNegotiatedVary),
+                )
+              : Effect.succeed(
+                  withNegotiatedVary(HttpServerResponse.empty({ status: 404 })),
+                ),
+          ),
+          M.exhaustive,
+        ),
       ),
     )
 
-  return HttpServerRequest.HttpServerRequest.use(request =>
-    M.value(requestKind(request)).pipe(
-      M.when('Render', () => renderRequest(request, template)),
-      M.when('StaticOrRender', () => serveStaticOrRender(request)),
-      M.when('MethodNotAllowed', () =>
-        Effect.succeed(
-          HttpServerResponse.setHeader(
-            HttpServerResponse.empty({ status: 405 }),
-            'allow',
-            'GET, HEAD',
-          ),
-        ),
+  return HttpServerRequest.HttpServerRequest.use(request => {
+    const requestUrl = Server.resolveRequestUrl(request.url, origin)
+    if (requestUrl === undefined) {
+      return Effect.succeed(HttpServerResponse.empty({ status: 400 }))
+    }
+    const resolved = new URL(requestUrl)
+    const normalizedRequest = request.modify({
+      url: `${resolved.pathname}${resolved.search}`,
+    })
+    const response = M.value(requestKind(normalizedRequest)).pipe(
+      M.when('Render', () =>
+        renderRequest(normalizedRequest, template, requestUrl),
+      ),
+      M.when('StaticOrRender', () =>
+        serveStaticOrRender(normalizedRequest, requestUrl),
       ),
+      M.when('HostSettled', () => Effect.succeed(hostSettledResponse())),
       M.exhaustive,
-    ),
-  )
+    )
+    return Effect.provideService(
+      response,
+      HttpServerRequest.HttpServerRequest,
+      normalizedRequest,
+    )
+  })
 })
 
 const Main = Layer.unwrap(
   Effect.map(makeHandler, handler => HttpServer.serve(handler)),
 ).pipe(
   HttpServer.withLogAddress,
-  Layer.provide(
-    NodeHttpServer.layerConfig(createServer, {
-      port: Config.withDefault(Config.port('PORT'), DEFAULT_PORT),
-    }),
-  ),
+  Layer.provide(NodeHttpServer.layerConfig(createServer, { port: PORT })),
   Layer.provide(NodeHttpPlatform.layer),
   Layer.provide(NodeServices.layer),
 )

package/templates/rendering/ssr/src/entry.server.ts

@@ -14,12 +14,29 @@ const flagsForRequest = (cookieHeader: string): Flags => ({
 // HTML and travel to the browser with it. The hydrating client reads them
 // back and calls init with the exact values this render used; the client
 // computes no Flags of its own.
+// NOTE: a preflight reaches this entry in development and in production alike,
+// so an application's CORS policy goes here rather than in the host: it can
+// allow one origin for one route and refuse it for another. This answer allows
+// nothing and only reports which methods the host forwards.
+const preflightResponse = (): Response =>
+  new Response(null, {
+    status: 204,
+    headers: { allow: Server.HOST_METHOD_ANSWERS.allow },
+  })
+
 export const renderPage = (request: Request): Promise<Server.EntryResult> =>
   Effect.runPromise(
     Effect.gen(function* () {
+      if (request.method === 'OPTIONS') {
+        return Server.Responded(preflightResponse())
+      }
+
       const renderedApplication = yield* Server.renderToString(
         { Flags, init, view },
-        { flags: flagsForRequest(request.headers.get('cookie') ?? '') },
+        {
+          flags: flagsForRequest(request.headers.get('cookie') ?? ''),
+          buildId: import.meta.env.FOLDKIT_BUILD_ID,
+        },
       )
 
       return Server.Rendered(renderedApplication, {

package/templates/rendering/ssr/src/entry.ts

@@ -14,4 +14,4 @@ const application = Runtime.makeApplication({
   },
 })
 
-Runtime.hydrate(application)
+Runtime.hydrate(application, { buildId: import.meta.env.FOLDKIT_BUILD_ID })

package/templates/rendering/ssr/src/vite-env.d.ts

@@ -0,0 +1,19 @@
+/// <reference types="vite/client" />
+
+// `@foldkit/vite-plugin` compiles the deployment's build id in here, from its
+// `buildId` option or the `FOLDKIT_BUILD_ID` environment variable. The server
+// entry hands it to `renderToString` and the client entry to `Runtime.hydrate`,
+// which is how hydration tells a page from this deployment apart from one served
+// by another.
+//
+// Declared as required rather than optional because this project's build always
+// supplies one. A build that did not would produce `undefined` here, and both
+// entries refuse it at runtime; typing it as optional would only push that
+// failure past the compiler and into the served page.
+interface ImportMetaEnv {
+  readonly FOLDKIT_BUILD_ID: string
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}