@evinvest/kitstart 0.1.0

package/README.md

@@ -0,0 +1,245 @@
+# @evinvest/kitstart
+
+The machinery of a local-service landing site — the part every brand of the
+vertical shares, lifted out of the aquafix reference site so a new brand is a
+`site.ts`, its copy and its own sections.
+
+What is here is **behaviour**, not look: routing between subdomains and
+locales, the place model and its publication gate, the lead funnel and its
+antispam, schema.org and sitemaps, analytics events. What a brand looks like
+stays in the brand.
+
+## Subpaths
+
+| Import | Runtime | What |
+|---|---|---|
+| `@evinvest/kitstart` | anywhere (edge, client, server) | `defineSite`, places, routing (`createRouting`), the lead schema and funnel (`createAcceptLead`), antispam, JSON-LD / sitemap / robots builders, analytics events, the copy contract |
+| `@evinvest/kitstart/server` | Node, `server-only` | `createServerEnv`, `createPlaceSource`, the lead store (`openLeadStore` by `LEADS_DB_URL`: `sqlite:` today, `postgres://` a stub that refuses at boot), `checkLeadStore`, `leadNotifier`, `sendMail`, `clientKey` |
+| `@evinvest/kitstart/proxy` | edge | `createProxy(site)`, `PROXY_MATCHER` |
+| `@evinvest/kitstart/next` | Next server (routes, RSC) | `quoteRoute`, `sitemapRoute`, `robotsRoute`, `ogRoute`, `healthRoute`, `createPlaceLoader`, `loadLocale`, `placeMetadata` / `brandMetadata` / `statusMetadata`, `metadataBase` |
+| `@evinvest/kitstart/next/config` | `next.config.ts`, `vitest.config.ts` | `withLanding`, `buildEnv` and the `assets/` readers |
+| `@evinvest/kitstart/react` | either side | `LangSwitch`, `CallBar`, `StatusScreen`, `PlaceDirectory`, `AreaChips`, `Coverage`, `MapFacade` (client), `QuoteFormShell`, `Faq`, `AnalyticsBoundary` (client), plus the kit and marketing pieces a landing composes with |
+| `@evinvest/kitstart/testing` | a brand's vitest | `describeLandingContract(site, { globalsCss, proxySource, text })`, `describeLeadStoreContract(name, harness)`, `storefrontPlace`, `serviceAreaPlace`, `testLead` |
+| `@evinvest/kitstart/testing/e2e` | a brand's Playwright | `defineSectionSuite(sections)`, `settle(page, selector)`, `BREAKPOINTS` |
+| bin `kitstart-size` | plain node | `kitstart-size [<build root>] [--route …] [--budget …]`: first-load JS of a place page against `tests/bundle_budget.txt`; fails closed |
+
+`vitest` and `@playwright/test` are not peers at all: they are the brand's
+own test runners, which it installs in its `devDependencies`. As peers —
+even optional ones — npm counted them among a brand's production
+dependencies, and a runner's advisory turned `npm audit --omit=dev` red.
+
+## A new brand
+
+`template/` (shipped in the tarball too) is the skeleton: a `single`-topology,
+service-area site before launch (no `site` in `assets/card.toml` → noindex,
+robots disallow), with every route file a few literal lines over a factory.
+Copy it, then follow its README. CI builds it on every PR exactly as a brand
+would — packed tarballs, `next build`, its own tests, `kitstart-size`, and a
+live standalone server answering `/`, `/fr`, a page, a 404, the form POST, the
+OG card and robots (`npm run check:template`).
+
+## Nix: `lib.mkLanding`
+
+The lib flake exports the flake a landing shares (`nix/mk-landing.nix`), so a
+brand's `flake.nix` is its own config plus one call — `template/flake.nix` is
+the whole of one:
+
+```nix
+inputs.ev.url = "github:EV-invest/lib?ref=@evinvest/kitstart-v0.1.0"; # the version in package-lock.json
+inputs.ev.inputs.v_flakes.follows = "v_flakes";
+
+landing = ev.lib.mkLanding {
+  pkgs, root, pname, sitePort, buildFiles,        # required
+  prodEnv ? { },                                  # baked into the image (deploy/config.nix)
+  v_flakes ? null,                                # without it: no `container`
+  nodejs ? pkgs.nodejs_22, nodeRuntime ? pkgs.nodejs-slim_22,
+  budgetFile ? "tests/bundle_budget.txt", gatedRoute ? "/[locale]/[location]",
+  requiredFiles ? [ ],                            # must be in the standalone output (OG fonts)
+  mounts ? [ "/data" ], criticality ? "high",
+  smoke ? { page = "/fr"; },                      # + host, og, quote = { field = value; }
+  containerAttr ? ".#container",
+  checkKitstartVersion ? true,
+  e2eConfig ? "tests/e2e",
+  packageSourceOverrides ? { },                   # lock key → `file:`/vendored tarball
+};
+# → { site, bundleBudget, packages.{default,site,container}, containers,
+#     checks.{site,bundle-budget}, apps.{default,help,dev,test,accept-test,size,container-smoke},
+#     devShell }
+```
+
+- `site`: the hermetic `next build` from `package-lock.json` through
+  `importNpmLock` (dependencies keyed on the manifest and the lock only;
+  foreign optional native binaries never fetched — the self-check's lock
+  carries a Windows-only package with a bogus integrity to prove it).
+  `packageSourceOverrides` serves lock entries the registry cannot yet —
+  `{ "node_modules/@evinvest/kitstart" = ./vendor/kitstart.tgz; }` builds a
+  brand against an unpublished kitstart; the self-check vendors one package
+  whose `resolved` 404s.
+- `container`: the OCI image on node-slim, `prodEnv` baked in.
+- `checks.bundle-budget`: `kitstart-size` on the Nix build.
+- `apps.test` (tsc — the app, then `e2eConfig` as its own project with its own
+  `tsconfig.json` — lint, vitest, build, size, Playwright on the flake's
+  pinned browsers), `accept-test` (Linux only), `size`, `dev`, `help`.
+- `apps.container-smoke`: boots the image with a host port docker picks
+  (`-p 127.0.0.1::<port>`: landing ports sit in Linux's ephemeral range), checks
+  `/health`, the 302, the page, the OG card and the form POST landing in the
+  mount, then boots it again with every `prodEnv` key blanked and wants 500 —
+  and once more with only the lead store's key (`LEADS_DB_PATH` /
+  `LEADS_DB_URL`) blanked, wanting 500 from the store's refusal alone.
+
+**Versions move together.** mkLanding refuses a lock whose
+`@evinvest/kitstart` differs from the lib revision's
+`ts/kitstart/package.json`: the size gate runs the lib's copy of the bin, and
+the two must be one release. Pin the flake to the matching
+`@evinvest/kitstart-vX.Y.Z` tag.
+
+## Widgets
+
+Structural only — where behaviour matters more than look. Marketing sections
+(hero, prices, reviews…) stay in the brand until two brands hold the same one.
+Each widget is a Server Component unless it needs the browser (`MapFacade`,
+`AnalyticsBoundary`), styled with the kit's token roles only, restyled through
+`className` — and, where a brand needs geometry inside one (`Faq`, `CallBar`,
+`StatusScreen`, `PlaceDirectory`, `Coverage`), through its named parts:
+`classNames={{ list: "rounded-none", answer: "px-2" }}`, merged after the
+kit's classes so the brand's utility wins. No descendant selectors: they
+break silently when a widget's markup moves. `QuoteFormShell` is headless: it owns the hidden fields and the
+honeypot the funnel reads; the visible fields are the brand's children.
+`StatusScreen` takes the brand's name and marks as props, so the client error
+boundary never imports the site config.
+
+Tailwind v4 does not scan `node_modules`; the brand's `globals.css` names the
+package:
+
+```css
+/* app/globals.css; from src/app/ it is ../../node_modules/… */
+@source "../node_modules/@evinvest/kitstart/dist";
+```
+
+Visual baselines: `test/visual/` renders each widget to a static page
+(`react-dom/server` over the kit's `tokens.css`), and `nix run
+.#kitstart-visual` captures and compares them byte for byte on Linux. PNGs
+come from the `kitstart-visual` CI artifact only.
+
+## Thin `app/` routes
+
+Segment config, `config.matcher` and `next/font/local` must be literals in the
+route file — Next reads them statically — so the literal stays in the brand's
+file and the handler comes from a factory:
+
+```ts
+// proxy.ts
+export const proxy = createProxy(site);
+// Files too: `decide` passes the routes outside `[locale]` and
+// `site.publicFiles` (`/icon.svg`), and 404s every other path, `/wp-login.php`
+// included — let past, it would be a cached bare 404 without the phone.
+export const config = { matcher: ["/((?!_next/).*)"] };
+
+// app/quote/route.ts
+export const dynamic = "force-dynamic";
+export const POST = quoteRoute(site, { env: serverEnv, notifier, unavailable });
+
+// app/sitemap.ts — reads the Host header, so it is dynamic; pages are not
+export const dynamic = "force-dynamic";
+export default sitemapRoute(site, places);
+
+// app/[locale]/[location]/layout.tsx — ISR: no page reads the request
+export function generateStaticParams() { return []; }
+export const revalidate = 600;
+```
+
+`createPlaceLoader(site, places)(params)` returns the `PlaceView` for a page,
+reading the link mode from the `location` param (`_royat` = host mode).
+
+**Dead paths.** Next 16 answers a `notFound()` with an empty shell it fills in
+after hydration — a blank page without JavaScript. So the proxy knows the dead
+paths itself (`decide` → `gone`) and rewrites each to `/<locale>/404/404`, a
+path no route matches, with the language and place in `GONE_HEADER`. The
+brand's `app/global-not-found.tsx` (`experimental.globalNotFound`, set by
+`withLanding`) reads that header — the only thing that does — and renders the
+404 on the server with `statusTarget(site, parseGoneHeader(…))`. The
+`notFound()` boundary under `[locale]` stays for what the proxy cannot foresee
+(a place the live source withdrew); it and `error.tsx` are client modules and
+take `brandStatusTarget({ locales, phone }, locale)`, never the site config,
+which would carry every place into every page's bundle. Redirects the proxy
+chooses per visitor answer `Cache-Control: private, no-store`.
+
+## Server invariants
+
+- **A page's place loader never throws on the live source.** Pages are cached
+  (ISR); a cold render that throws is Next's bare `Internal Server Error`
+  with no phone on it. A 5xx or an unreachable source serves the baked place
+  (`noindex` until the gate fields are back); only a 410, or a 404 in the
+  source's own JSON, withdraws a place — a bare 404 is an ingress, not the
+  source. The sitemap is the one strict reader (`getPlaceStrict` throws).
+- **The lead is durable before anything else happens.** Every `LeadStore`
+  adapter passes `describeLeadStoreContract` and migrates itself to
+  `LEAD_SCHEMA_VERSION` on open. SQLite keeps the Rust server's columns
+  (`job`, `zip`, `mobile`) and recognises every earlier table in place.
+- **Mail is checked at boot.** With `SMTP_URL` set, `leadNotifier` throws when
+  it is built if the URL is malformed (the error never repeats it), there is
+  no sender (`LEAD_NOTIFY_FROM`, or `leads@<domain>`) or no recipient
+  (`LEAD_NOTIFY_TO`, or the brand's email). Both are bare addresses
+  (`leads@brand.fr`), not `Name <…>`. Off loopback, a server without TLS gets
+  nothing; past `MAIL_PER_MINUTE` a minute the lead is stored and only logged.
+- **The rate limit knows whose address it counts.** `TRUSTED_PROXY` is
+  `cloudflare` (only `CF-Connecting-IP`) or `xff:<n>` (the n-th
+  `X-Forwarded-For` hop from the right); production refuses to boot without it.
+- **SQLite wants one writer node.** The file lives on a ReadWriteOnce volume
+  mounted by one node; pods on it take turns through `busy_timeout`. A shared
+  network filesystem is not a place for it — that is what the Postgres port
+  is for.
+
+## The site
+
+```ts
+import { createLocaleRegistry, defineSite, STOREFRONT_GATE } from "@evinvest/kitstart";
+
+export const site = defineSite({
+  brand: { id: "aquafix", name: "Aquafix", legalName: "Aquafix SAS", email, phone, domain: "aquafix.top", businessType: "Plumber" },
+  i18n: createLocaleRegistry({ locales: ["fr", "en"], labels, default: "fr", prefixDefaultLocale: true, hreflang: { fr: "fr-FR" } }),
+  ogLocale: { fr: "fr_FR", en: "en_GB" },
+  topology: { kind: "subdomains", apex: "directory" }, // or { kind: "single", place: "paris" }
+  pages: { home: "", prices: "/prices" },
+  places: PLACES,
+  publication: STOREFRONT_GATE,
+  lead: LEAD,
+});
+```
+
+`domain: null` is a site before launch: every page `noindex`, robots disallow
+everything, the sitemap empty.
+
+## Routing: the link mode rides in the path
+
+Pages are cached (ISR), so no page may read a request header. The proxy tells a
+page how to write its links through the route it rewrites to:
+
+| Request | Rendered route | Links |
+|---|---|---|
+| `royat.aquafix.top/fr/prices` | `/fr/_royat/prices` | `/fr/…` (host mode) |
+| `aquafix.top/fr/royat/prices` | as is | `/fr/royat/…` (path mode) |
+| single site `clean.example/fr/prices` | `/fr/_paris/prices` | `/fr/…` |
+
+`parsePlaceParam("_royat")` reads the mode back out of the `[location]` param.
+
+## Publishing
+
+`package.json` says `0.0.0` on purpose: `nix run .#publish -- minor` bumps it
+to `0.1.0`, the version `template/` asks for (`^0.1.0`). kitstart's peers
+must be on the registry first, so a release is two runs:
+
+1. `nix run .#publish -- minor --npm-only --only @evinvest/uikit --only @evinvest/marketing`,
+   then wait until `npm view @evinvest/uikit version` answers the new one;
+2. `nix run .#publish -- minor --npm-only --only @evinvest/kitstart`.
+
+The first publish of a new name in the scope needs an automation or classic
+token: a granular token cannot create a name. Bump the lib flake revision a
+brand pins (`mkLanding`) in the same PR as its npm version.
+
+## Shared fixtures with Rust
+
+`tests/fixtures/kitstart/` at the repo root holds the site configs, routing
+decisions and the JSON-LD / metadata / sitemap goldens (aquafix's, verbatim).
+This package's tests and the Rust `kitstart` feature both run them; a change to
+a builder's output is a change to those files, visible in review.

package/dist/cli/kitstart-size.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/kitstart-size.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// kitstart-size [<build root>] [--route /[locale]/[location]] [--budget tests/bundle_budget.txt]
+// — the first-load JS of a place page against the brand's budget. See `size.ts`.
+import { measure, parseArgs } from "./size.js";
+try {
+    process.exitCode = measure(parseArgs(process.argv.slice(2), process.cwd()));
+}
+catch (error) {
+    console.error(`✘ ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+}

package/dist/cli/size.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The one hard gate of a landing: the gzip weight of the JavaScript a place
+ * page makes the browser download before it is interactive, against the
+ * brand's committed budget. Run after `next build`; `mkLanding`'s
+ * `bundle-budget` check runs it against the Nix build.
+ */
+/** The page the visitor lands on; every place page shares its chunks. */
+export declare const GATED_ROUTE = "/[locale]/[location]";
+export declare const STATS = ".next/diagnostics/route-bundle-stats.json";
+export declare const BUDGET = "tests/bundle_budget.txt";
+/** The budget file is commented prose; the number is its last non-comment line. */
+export declare function parseBudget(text: string, file?: string): number;
+/**
+ * The chunks Next itself lists as the route's first load. Undocumented output,
+ * which is why a missing file or route is a failure and never a pass: a gate
+ * that reads nothing and reports zero is worse than no gate.
+ */
+export declare function firstLoadChunks(statsJson: string, route: string): string[];
+/** gzip at zlib's default level, which is what Next's own server compresses with. */
+export declare const gzipSize: (bytes: Buffer) => number;
+export interface SizeArgs {
+    /** Where `tests/bundle_budget.txt` is: the brand repo. */
+    repo: string;
+    /** Where `.next/` is: the repo, or the Nix build's output. */
+    root: string;
+    route: string;
+    budget: string;
+}
+export declare function parseArgs(argv: readonly string[], cwd: string): SizeArgs;
+/** Prints the chunks and the total; returns the exit code. */
+export declare function measure(args: SizeArgs, log?: Pick<Console, "log" | "error">): number;

package/dist/cli/size.js

@@ -0,0 +1,99 @@
+import { readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { gzipSync } from "node:zlib";
+/**
+ * The one hard gate of a landing: the gzip weight of the JavaScript a place
+ * page makes the browser download before it is interactive, against the
+ * brand's committed budget. Run after `next build`; `mkLanding`'s
+ * `bundle-budget` check runs it against the Nix build.
+ */
+/** The page the visitor lands on; every place page shares its chunks. */
+export const GATED_ROUTE = "/[locale]/[location]";
+export const STATS = ".next/diagnostics/route-bundle-stats.json";
+export const BUDGET = "tests/bundle_budget.txt";
+/** The budget file is commented prose; the number is its last non-comment line. */
+export function parseBudget(text, file = BUDGET) {
+    const lines = text
+        .split("\n")
+        .map(l => l.trim())
+        .filter(l => l !== "" && !l.startsWith("#"));
+    const last = lines.at(-1);
+    if (last === undefined || !/^\d+$/.test(last)) {
+        throw new Error(`${file}: the last non-comment line must be a byte count, got ${JSON.stringify(last)}`);
+    }
+    return Number(last);
+}
+function isRouteStats(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const route = Reflect.get(value, "route");
+    const chunks = Reflect.get(value, "firstLoadChunkPaths");
+    return typeof route === "string" && Array.isArray(chunks) && chunks.every(c => typeof c === "string");
+}
+/**
+ * The chunks Next itself lists as the route's first load. Undocumented output,
+ * which is why a missing file or route is a failure and never a pass: a gate
+ * that reads nothing and reports zero is worse than no gate.
+ */
+export function firstLoadChunks(statsJson, route) {
+    const parsed = JSON.parse(statsJson);
+    if (!Array.isArray(parsed))
+        throw new Error(`${STATS}: expected an array of routes`);
+    const entry = parsed.filter(isRouteStats).find(r => r.route === route);
+    if (!entry)
+        throw new Error(`${STATS}: no entry for ${route} — did the route move, or Next's diagnostics?`);
+    if (entry.firstLoadChunkPaths.length === 0)
+        throw new Error(`${STATS}: ${route} lists no chunks`);
+    return entry.firstLoadChunkPaths;
+}
+/** gzip at zlib's default level, which is what Next's own server compresses with. */
+export const gzipSize = (bytes) => gzipSync(bytes).length;
+export function parseArgs(argv, cwd) {
+    const args = { repo: cwd, root: cwd, route: GATED_ROUTE, budget: BUDGET };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const value = () => {
+            const next = argv[++i];
+            if (next === undefined)
+                throw new Error(`${arg} needs a value`);
+            return next;
+        };
+        if (arg === "--route")
+            args.route = value();
+        else if (arg === "--budget")
+            args.budget = value();
+        else if (arg !== undefined && !arg.startsWith("--"))
+            args.root = arg;
+        else
+            throw new Error(`unknown argument ${arg}`);
+    }
+    return args;
+}
+/** Prints the chunks and the total; returns the exit code. */
+export function measure(args, log = console) {
+    let stats;
+    try {
+        stats = readFileSync(join(args.root, STATS), "utf8");
+    }
+    catch {
+        log.error(`✘ ${join(args.root, STATS)} is missing — run \`next build\` first`);
+        return 1;
+    }
+    const budget = parseBudget(readFileSync(join(args.repo, args.budget), "utf8"), args.budget);
+    let total = 0;
+    let raw = 0;
+    for (const chunk of firstLoadChunks(stats, args.route)) {
+        const bytes = readFileSync(join(args.root, chunk));
+        const gz = gzipSize(bytes);
+        total += gz;
+        raw += bytes.length;
+        log.log(`  ${String(gz).padStart(8)} B gz  ${relative(args.root, join(args.root, chunk))}`);
+    }
+    const kb = (n) => (n / 1024).toFixed(1);
+    log.log(`  ${args.route}: ${kb(total)} KB gz (${kb(raw)} KB raw) / budget ${kb(budget)} KB gz`);
+    if (total > budget) {
+        log.error(`✘ over budget by ${total - budget} B. Raising ${args.budget} is a deliberate commit, with a reason.`);
+        return 1;
+    }
+    return 0;
+}

package/dist/core/accept.d.ts

@@ -0,0 +1,49 @@
+import { type RateLimiter } from "./antispam.js";
+import { type Lead } from "./lead.js";
+import type { Site } from "./site.js";
+/** Hidden fields the form carries besides what the visitor types. */
+export declare const LOCATION_FIELD = "location";
+export declare const LOCALE_FIELD = "locale";
+export declare const FORM_ID_FIELD = "form_id";
+export type Outcome<L extends string> = {
+    kind: "stored";
+    id: number;
+    lead: Lead;
+    locale: L;
+    formId: string;
+} | {
+    kind: "invalid";
+    why: string;
+    locale: L;
+    slug: string | null;
+} | {
+    kind: "failed";
+    locale: L;
+    slug: string | null;
+};
+export interface AcceptDeps {
+    /** The commit point: resolves once the lead is durable. */
+    insert: (lead: Lead) => Promise<number>;
+    /** Runs after the response is sent; see the route handler. */
+    defer: (task: () => Promise<void> | void) => void;
+    notify: (lead: Lead, id: number) => Promise<void>;
+    capture: (lead: Lead, formId: string) => void;
+    limiter: RateLimiter;
+    now: number;
+    log: Pick<Console, "warn" | "error">;
+}
+/**
+ * The funnel's commit point, independent of HTTP. Order is the invariant:
+ * validate → screen → **insert** → (deferred) notify and capture.
+ *
+ * Nothing that passes validation is thrown away. A submission the barriers
+ * suspect is stored with its `spamVerdict` and simply not notified: a
+ * mis-set clock, a fast thumb or a shared carrier NAT must not cost a real
+ * customer, and a reviewer can still find the row. A lead with no point, or
+ * one we no longer have (an old page, a stale form), is stored without one.
+ *
+ * A notification failure logs and changes nothing; a store failure is
+ * `failed`, never `stored` — a thank-you page for a lead that was never
+ * written is the worst outcome this system can produce.
+ */
+export declare function createAcceptLead<L extends string, P extends string>(site: Site<L, P>): (form: FormData, clientKey: string, deps: AcceptDeps) => Promise<Outcome<L>>;

package/dist/core/accept.js

@@ -0,0 +1,78 @@
+import { HONEYPOT_FIELD, LEGACY_HONEYPOT_FIELDS, RENDERED_AT_FIELD, screen } from "./antispam.js";
+import { MAX_FIELD, readCandidate, validateCandidate } from "./lead.js";
+/** Hidden fields the form carries besides what the visitor types. */
+export const LOCATION_FIELD = "location";
+export const LOCALE_FIELD = "locale";
+export const FORM_ID_FIELD = "form_id";
+const FORM_ID = /^[a-z0-9_-]{1,32}$/;
+function field(form, name) {
+    const value = form.get(name);
+    return typeof value === "string" ? value.trim().slice(0, MAX_FIELD) : null;
+}
+/**
+ * The funnel's commit point, independent of HTTP. Order is the invariant:
+ * validate → screen → **insert** → (deferred) notify and capture.
+ *
+ * Nothing that passes validation is thrown away. A submission the barriers
+ * suspect is stored with its `spamVerdict` and simply not notified: a
+ * mis-set clock, a fast thumb or a shared carrier NAT must not cost a real
+ * customer, and a reviewer can still find the row. A lead with no point, or
+ * one we no longer have (an old page, a stale form), is stored without one.
+ *
+ * A notification failure logs and changes nothing; a store failure is
+ * `failed`, never `stored` — a thank-you page for a lead that was never
+ * written is the worst outcome this system can produce.
+ */
+export function createAcceptLead(site) {
+    return (form, clientKey, deps) => accept(site, form, clientKey, deps);
+}
+async function accept(site, form, clientKey, deps) {
+    const rawSlug = field(form, LOCATION_FIELD);
+    const slug = rawSlug && site.placeSlugs.includes(rawSlug) ? rawSlug : null;
+    const rawLocale = field(form, LOCALE_FIELD);
+    const locale = site.i18n.isLocale(rawLocale) ? rawLocale : site.i18n.defaultLocale;
+    const candidate = readCandidate(site.lead, form, slug);
+    const why = validateCandidate(site.lead, candidate);
+    if (why) {
+        deps.log.warn(`quote: rejected a submission for ${slug ?? "no point"}: missing ${why}`);
+        return { kind: "invalid", why, locale, slug };
+    }
+    // After validation, so a typo corrected and resent does not spend the limit.
+    const verdict = screen({
+        honeypot: [HONEYPOT_FIELD, ...LEGACY_HONEYPOT_FIELDS].map(name => field(form, name)).find(v => v) ?? null,
+        renderedAt: field(form, RENDERED_AT_FIELD),
+        clientKey,
+        now: deps.now,
+        limiter: deps.limiter,
+    });
+    const lead = { ...candidate, spamVerdict: verdict === "ok" ? null : verdict };
+    let id;
+    try {
+        id = await deps.insert(lead);
+    }
+    catch (error) {
+        deps.log.error(`quote: the lead store rejected a submission for ${slug ?? "no point"}`, error);
+        return { kind: "failed", locale, slug };
+    }
+    // It reaches analytics as a property; anything but a short slug is dropped.
+    const posted = field(form, FORM_ID_FIELD);
+    const formId = posted !== null && FORM_ID.test(posted) ? posted : "quote";
+    // The render stamp comes from the client, so it only marks: a `too-fast`
+    // lead (or one from a page cached before the stamp existed) is still sent
+    // on, flagged. The honeypot and the rate limit are the server's own
+    // evidence, and those leads wait in the table for a reviewer.
+    if (lead.spamVerdict && lead.spamVerdict !== "too-fast") {
+        deps.log.warn(`quote: lead ${id} stored as suspected spam (${lead.spamVerdict}); not notified`);
+        return { kind: "stored", id, lead, locale, formId };
+    }
+    deps.defer(async () => {
+        try {
+            await deps.notify(lead, id);
+        }
+        catch (error) {
+            deps.log.error(`quote: lead ${id} is stored but its notification failed`, error);
+        }
+    });
+    deps.defer(() => deps.capture(lead, formId));
+    return { kind: "stored", id, lead, locale, formId };
+}

package/dist/core/analytics.d.ts

@@ -0,0 +1,43 @@
+import { type AnalyticsSink } from "@evinvest/analytics";
+/**
+ * The event model. Analytics records; it never decides what renders.
+ *
+ * `contact_intent_click` is an intention, not a lead: a click on `tel:` is
+ * visible, whether the call happened is not. It is named apart from
+ * `lead_form_submit` so the two numbers can never be read as one.
+ */
+export declare const EVENTS: {
+    readonly pageView: "location_page_view";
+    readonly intent: "contact_intent_click";
+    readonly leadSubmit: "lead_form_submit";
+};
+export type IntentChannel = "form_open" | "whatsapp" | "phone" | "booking";
+/**
+ * Every property name an event may carry. A customer's phone or address comes
+ * through the same pages, and once it reaches PostHog the only remedy is
+ * deleting the project's history — so the list is enforced by the sink (dev
+ * throws, prod drops) rather than by review.
+ */
+export declare const ALLOWED_PROPS: readonly ["brand_id", "location_id", "source", "device", "channel", "form_id"];
+/**
+ * The thank-you page is the form's receipt, not a visit to the point: counting
+ * it as `location_page_view` would add a page view to every lead.
+ */
+export declare function countsAsPageView(pathname: string): boolean;
+/**
+ * Where events go, and whose they are. `key: null` → every capture is a silent
+ * no-op. `brandId` travels in the target, not in an import of the site config:
+ * this module reaches the client island, and the config would ride with it.
+ */
+export interface AnalyticsTarget {
+    key: string | null;
+    host: string;
+    brandId: string;
+}
+/**
+ * Cookieless by construction: a beacon sink keeps its `distinct_id` in memory,
+ * writes no cookie and no storage, and needs no consent banner. `sendBeacon`
+ * because the events that matter most — a tap on `tel:` or `wa.me` — are
+ * followed by the page handing the visitor to another app.
+ */
+export declare function analyticsSink(target: AnalyticsTarget, locationId: string | null): AnalyticsSink;

package/dist/core/analytics.js

@@ -0,0 +1,42 @@
+import { createBeaconSink } from "@evinvest/analytics";
+import { THANKS } from "./routing.js";
+/**
+ * The event model. Analytics records; it never decides what renders.
+ *
+ * `contact_intent_click` is an intention, not a lead: a click on `tel:` is
+ * visible, whether the call happened is not. It is named apart from
+ * `lead_form_submit` so the two numbers can never be read as one.
+ */
+export const EVENTS = {
+    pageView: "location_page_view",
+    intent: "contact_intent_click",
+    leadSubmit: "lead_form_submit",
+};
+/**
+ * Every property name an event may carry. A customer's phone or address comes
+ * through the same pages, and once it reaches PostHog the only remedy is
+ * deleting the project's history — so the list is enforced by the sink (dev
+ * throws, prod drops) rather than by review.
+ */
+export const ALLOWED_PROPS = ["brand_id", "location_id", "source", "device", "channel", "form_id"];
+/**
+ * The thank-you page is the form's receipt, not a visit to the point: counting
+ * it as `location_page_view` would add a page view to every lead.
+ */
+export function countsAsPageView(pathname) {
+    return !pathname.replace(/\/+$/, "").endsWith(THANKS);
+}
+/**
+ * Cookieless by construction: a beacon sink keeps its `distinct_id` in memory,
+ * writes no cookie and no storage, and needs no consent banner. `sendBeacon`
+ * because the events that matter most — a tap on `tel:` or `wa.me` — are
+ * followed by the page handing the visitor to another app.
+ */
+export function analyticsSink(target, locationId) {
+    return createBeaconSink({
+        key: target.key ?? undefined,
+        host: target.host,
+        allowedProps: ALLOWED_PROPS,
+        globalProps: locationId ? { brand_id: target.brandId, location_id: locationId } : { brand_id: target.brandId },
+    });
+}

package/dist/core/antispam.d.ts

@@ -0,0 +1,60 @@
+import type { SpamVerdict } from "./lead.js";
+/**
+ * Three cheap barriers, none of which needs the visitor to run a script — the
+ * form has to work before any JavaScript arrives, so a challenge widget is not
+ * an option. A rejected submission is answered exactly like an accepted one,
+ * so a bot learns nothing from the response.
+ */
+/**
+ * The field a human never sees and a form-filling bot fills. A neutral name:
+ * a browser's autofill knows `website`, `url` or `company` and would fill the
+ * trap for a real person.
+ */
+export declare const HONEYPOT_FIELD = "hp_ref";
+/** The trap's name on pages cached before it was renamed; still read. */
+export declare const LEGACY_HONEYPOT_FIELDS: readonly string[];
+/** When the form was rendered, in ms since the epoch. */
+export declare const RENDERED_AT_FIELD = "t";
+/** Faster than this from render to submit is a script, not a person. */
+export declare const MIN_FILL_MS = 3000;
+export type Screening = "ok" | SpamVerdict;
+export declare function checkTiming(renderedAt: string | null, now: number): Screening;
+/** How many distinct keys a limiter tracks before new ones share one bucket. */
+export declare const RATE_LIMIT_MAX_KEYS = 10000;
+/** The shared bucket keys past the cap count against. */
+export declare const RATE_LIMIT_OVERFLOW_KEY = "\0overflow";
+/**
+ * A fixed-window counter per client address, in memory. Per process by design:
+ * it is a speed bump for one bot hammering one pod, not an accounting system,
+ * and a restart forgetting it costs nothing.
+ *
+ * Bounded: past `maxKeys` distinct addresses in one window, new ones count
+ * against one shared bucket — a flood of forged addresses throttles itself
+ * instead of growing the map. Expired windows are swept at most once a second.
+ */
+export declare class RateLimiter {
+    private readonly limit;
+    private readonly windowMs;
+    private readonly maxKeys;
+    private readonly hits;
+    private lastPrune;
+    constructor(limit: number, windowMs: number, maxKeys?: number);
+    /** `true` if this hit is allowed. */
+    hit(key: string, now: number): boolean;
+    /** Distinct buckets held now, for tests and diagnostics. */
+    get size(): number;
+    private prune;
+}
+/**
+ * The barriers in their order. Every submission past the honeypot spends the
+ * limiter — a script that omits the render stamp must not get unlimited
+ * `too-fast` rows — and the verdict ranks the server's own evidence first:
+ * honeypot, then rate-limited, then the client's stamp (too-fast).
+ */
+export declare function screen(input: {
+    honeypot: string | null;
+    renderedAt: string | null;
+    clientKey: string;
+    now: number;
+    limiter: RateLimiter;
+}): Screening;