@evinvest/kitstart 0.1.0

package/dist/server/notify.js

@@ -0,0 +1,79 @@
+import "server-only";
+import { parseSmtpUrl, sendMail } from "./smtp.js";
+/** A plain default; a brand passes `format` to write it in its own language. */
+export function defaultLeadMail(brand, lead, id) {
+    const place = lead.placeSlug ?? "unknown";
+    return {
+        subject: `${brand.name} — new lead (${place})`,
+        text: [
+            `Lead #${id} — place ${place}${lead.spamVerdict ? ` — suspect (${lead.spamVerdict})` : ""}`,
+            "",
+            `Subject  : ${lead.subject}`,
+            `Locality : ${lead.locality}`,
+            `Mobile   : ${lead.mobile}`,
+            ...Object.entries(lead.extras).map(([name, value]) => `${name} : ${value}`),
+        ].join("\n"),
+    };
+}
+/**
+ * Checked when it is built — at boot, when a brand builds it there — not on
+ * the first lead: with SMTP configured, a sender needs a domain to be `leads@`
+ * of (or `LEAD_NOTIFY_FROM`), and a recipient needs the brand's mailbox (or
+ * `LEAD_NOTIFY_TO`). A site before launch has neither, and `leads@null` is a
+ * mail no relay delivers.
+ */
+/** Mails a notifier sends per minute, per process; past it the lead is only logged. */
+export const MAIL_PER_MINUTE = 20;
+export function leadNotifier(site, env, options = {}) {
+    const { brand } = site;
+    const log = options.log ?? console;
+    const now = options.now ?? Date.now;
+    const cap = options.mailPerMinute ?? MAIL_PER_MINUTE;
+    const format = options.format ?? ((lead, id) => defaultLeadMail(brand, lead, id));
+    let window = { start: Number.NEGATIVE_INFINITY, sent: 0 };
+    const spend = () => {
+        const t = now();
+        if (t - window.start >= 60_000)
+            window = { start: t, sent: 0 };
+        window.sent += 1;
+        return window.sent <= cap;
+    };
+    let mail = null;
+    if (env.smtpUrl) {
+        const from = env.notifyFrom ?? (brand.domain ? `leads@${brand.domain}` : null);
+        if (!from)
+            throw new Error("SMTP_URL is set but the site has no domain: set LEAD_NOTIFY_FROM");
+        const to = env.notifyTo ?? brand.email;
+        if (!to)
+            throw new Error("SMTP_URL is set but the brand has no email: set LEAD_NOTIFY_TO");
+        const helo = brand.domain ?? from.split("@")[1] ?? "localhost";
+        mail = { url: parseSmtpUrl(env.smtpUrl), from, to, helo };
+    }
+    return {
+        async notify(lead, id) {
+            const channels = [];
+            if (mail && !spend()) {
+                log.warn(`lead ${id}: over ${cap} notification mails a minute; stored, not mailed`);
+            }
+            else if (mail) {
+                const { subject, text } = format(lead, id);
+                channels.push(sendMail(mail.url, { from: mail.from, to: mail.to, subject, text }, { helo: mail.helo }));
+            }
+            if (env.smsToken) {
+                // No SMS provider is chosen; the token is read so a deployment can
+                // already carry it, and the lead is still mailed.
+                log.warn(`lead ${id}: SMS_TOKEN is set but no SMS provider is wired; not texted`);
+            }
+            if (channels.length === 0 && !mail) {
+                log.warn(`lead ${id}: no notification channel configured; the lead is stored and unsent`);
+                return;
+            }
+            if (channels.length === 0)
+                return;
+            const results = await Promise.allSettled(channels);
+            const failure = results.find(r => r.status === "rejected");
+            if (failure)
+                throw failure.reason;
+        },
+    };
+}

package/dist/server/place-source.d.ts

@@ -0,0 +1,48 @@
+import "server-only";
+import type { Place } from "../core/place/types.js";
+import type { Site } from "../core/site.js";
+/**
+ * The live half of each place: `GET <base>/locations/<slug>?locale=<l>`,
+ * merged over the baked config.
+ *
+ * The invariant that shapes it: pages are cached (ISR), and under ISR a cold
+ * render that throws is Next's bare-text `Internal Server Error` — no phone,
+ * no error boundary. So a page's loader never throws on the source: a 5xx and
+ * an unreachable source both serve the baked place (a warm page keeps its last
+ * good render anyway). Only a 404 changes the answer — the place is gone. The
+ * sitemap is the one strict reader: see `listPlaces`.
+ */
+export interface PlaceSourceOptions {
+    /** The source's base URL, read when asked; `null` → the baked config only. */
+    baseUrl: () => string | null;
+    /**
+     * TTL on the fetch itself, not on the page: a segment-level `revalidate`
+     * does not reach an explicit `force-cache` fetch, which would then cache
+     * forever. The source sees one request per place per window.
+     */
+    revalidateSeconds?: number;
+    timeoutMs?: number;
+    log?: Pick<Console, "error">;
+}
+export declare class PlaceSourceError extends Error {
+    readonly name = "PlaceSourceError";
+}
+export interface PlaceSource<L extends string> {
+    /** One place, or `null` when it does not exist — the caller's `notFound()`. Never throws on the source. */
+    getPlace(slug: string, locale: L): Promise<Place<L> | null>;
+    /**
+     * Every place the source still has (a 404 is a place it retired). `"page"`
+     * stands on the baked places through an outage; `"sitemap"` throws, because
+     * a sitemap that silently drops places tells a crawler they are gone, and a
+     * 5xx tells it to keep its last copy.
+     */
+    listPlaces(locale: L, mode: "page" | "sitemap"): Promise<Place<L>[]>;
+    /**
+     * One place, strictly — for a sitemap, which lists one host's place and
+     * must fail (a 5xx a crawler retries) rather than shrink. `null` only when
+     * the source withdrew it.
+     */
+    getPlaceStrict(slug: string, locale: L): Promise<Place<L> | null>;
+}
+export declare const PLACE_REVALIDATE_SECONDS = 600;
+export declare function createPlaceSource<L extends string, P extends string>(site: Site<L, P>, options: PlaceSourceOptions): PlaceSource<L>;

package/dist/server/place-source.js

@@ -0,0 +1,107 @@
+import "server-only";
+import { mergeLive, parsePlaceLive } from "../core/place/live.js";
+export class PlaceSourceError extends Error {
+    name = "PlaceSourceError";
+}
+export const PLACE_REVALIDATE_SECONDS = 600;
+const TIMEOUT_MS = 3_000;
+export function createPlaceSource(site, options) {
+    const revalidate = options.revalidateSeconds ?? PLACE_REVALIDATE_SECONDS;
+    const timeoutMs = options.timeoutMs ?? TIMEOUT_MS;
+    const log = options.log ?? console;
+    async function fetchOne(base, baked, locale) {
+        const init = { cache: "force-cache", next: { revalidate }, signal: AbortSignal.timeout(timeoutMs) };
+        let response;
+        try {
+            response = await fetch(`${base}/locations/${encodeURIComponent(baked.slug)}?locale=${locale}`, init);
+        }
+        catch (cause) {
+            return { kind: "unreachable", cause };
+        }
+        // Withdrawn is the source's own word: a 410, or a 404 it answered in its
+        // JSON. A bare 404 is as likely an ingress with no route yet — a failing
+        // source, which keeps the baked place.
+        if (response.status === 410)
+            return { kind: "missing" };
+        if (response.status === 404) {
+            return response.headers.get("content-type")?.includes("application/json") ? { kind: "missing" } : { kind: "failed", status: 404 };
+        }
+        if (!response.ok)
+            return { kind: "failed", status: response.status };
+        try {
+            return { kind: "live", place: mergeLive(baked, parsePlaceLive(await response.json(), site.i18n.locales)) };
+        }
+        catch (cause) {
+            // A body that is not the source's shape is the source failing, not the place.
+            return { kind: "unreachable", cause };
+        }
+    }
+    const baked = (slug) => site.places.find(p => p.slug === slug);
+    return {
+        async getPlace(slug, locale) {
+            const place = baked(slug);
+            if (!place)
+                return null;
+            const base = options.baseUrl();
+            if (!base)
+                return place;
+            const fetched = await fetchOne(base, place, locale);
+            switch (fetched.kind) {
+                case "live":
+                    return fetched.place;
+                case "missing":
+                    return null;
+                // The gate fields may be missing from the baked place — then the page
+                // is served `noindex` until the source is back, never a 404 or a 500.
+                case "unreachable":
+                    log.error(`live place ${slug}: source unreachable, serving baked`, fetched.cause);
+                    return place;
+                case "failed":
+                    log.error(`live place ${slug}: source answered ${fetched.status}, serving baked`);
+                    return place;
+            }
+        },
+        async getPlaceStrict(slug, locale) {
+            const place = baked(slug);
+            if (!place)
+                return null;
+            const base = options.baseUrl();
+            if (!base)
+                return place;
+            const fetched = await fetchOne(base, place, locale);
+            switch (fetched.kind) {
+                case "live":
+                    return fetched.place;
+                case "missing":
+                    return null;
+                case "unreachable":
+                    throw new PlaceSourceError(`place ${slug} unreachable`, { cause: fetched.cause });
+                case "failed":
+                    throw new PlaceSourceError(`place ${slug}: source answered ${fetched.status}`);
+            }
+        },
+        async listPlaces(locale, mode) {
+            const base = options.baseUrl();
+            if (!base)
+                return [...site.places];
+            const results = await Promise.all(site.places.map(async (place) => {
+                const fetched = await fetchOne(base, place, locale);
+                switch (fetched.kind) {
+                    case "live":
+                        return fetched.place;
+                    case "missing":
+                        return null;
+                    case "unreachable":
+                        if (mode === "sitemap")
+                            throw new PlaceSourceError(`place list: ${place.slug} unreachable`, { cause: fetched.cause });
+                        return place;
+                    case "failed":
+                        if (mode === "sitemap")
+                            throw new PlaceSourceError(`place list: ${place.slug} answered ${fetched.status}`);
+                        return place;
+                }
+            }));
+            return results.filter((p) => p !== null);
+        },
+    };
+}

package/dist/server/smtp.d.ts

@@ -0,0 +1,38 @@
+import "server-only";
+/**
+ * A minimal SMTP submission client: one message, plain text, AUTH PLAIN,
+ * STARTTLS when offered. Enough to tell a plumber a lead arrived, without a
+ * mail library in the dependency tree.
+ *
+ * `smtps://user:pass@host:465` is implicit TLS; `smtp://…:587` upgrades with
+ * STARTTLS, and refuses to send anything when the server offers no TLS —
+ * unless the host is loopback, a local mail catcher.
+ */
+export interface Mail {
+    from: string;
+    to: string;
+    subject: string;
+    text: string;
+}
+/**
+ * Sends one message or rejects. Every way the conversation can die rejects
+ * rather than hangs: an error or a close on either socket (the raw one, and
+ * the TLS one over it after STARTTLS), and one deadline over the whole
+ * exchange — a server that accepts the connection and then says nothing must
+ * not hold a request's `after()` task forever.
+ *
+ * Off loopback, TLS is required: implicit (`smtps://`) or STARTTLS. A server
+ * that offers neither gets nothing — not the credentials, and not the
+ * customer's phone number in the body. The lead is already stored, so a
+ * refusal here is loud in the log and costs nothing else.
+ *
+ * `helo` is the name this client greets a remote relay with — the site's own
+ * domain; a loopback catcher is greeted as `localhost`.
+ */
+/** `SMTP_URL`, checked; the error never repeats it, since it carries the password. */
+export declare function parseSmtpUrl(value: string | URL): URL;
+export interface SendOptions {
+    helo: string;
+    timeoutMs?: number;
+}
+export declare function sendMail(smtpUrl: string | URL, mail: Mail, options: SendOptions): Promise<void>;

package/dist/server/smtp.js

@@ -0,0 +1,197 @@
+import "server-only";
+import { connect as tcp } from "node:net";
+import { connect as tlsConnect } from "node:tls";
+import { randomUUID } from "node:crypto";
+/** The whole conversation, connect to QUIT. */
+const TOTAL_TIMEOUT_MS = 20_000;
+class Replies {
+    socket;
+    buffer = "";
+    waiting = [];
+    queued = [];
+    onData = (chunk) => this.feed(chunk.toString("utf8"));
+    constructor(socket) {
+        this.socket = socket;
+        socket.on("data", this.onData);
+    }
+    feed(data) {
+        this.buffer += data;
+        let end;
+        let lines = [];
+        while ((end = this.buffer.indexOf("\r\n")) >= 0) {
+            const line = this.buffer.slice(0, end);
+            this.buffer = this.buffer.slice(end + 2);
+            lines.push(line);
+            // `250-…` continues a reply, `250 …` ends it.
+            if (/^\d{3}(?: |$)/.test(line)) {
+                const reply = { code: Number(line.slice(0, 3)), text: lines.join("\n") };
+                lines = [];
+                const next = this.waiting.shift();
+                if (next)
+                    next(reply);
+                else
+                    this.queued.push(reply);
+            }
+        }
+        if (lines.length)
+            this.buffer = `${lines.join("\r\n")}\r\n${this.buffer}`;
+    }
+    next() {
+        const ready = this.queued.shift();
+        if (ready)
+            return Promise.resolve(ready);
+        return new Promise(resolve => this.waiting.push(resolve));
+    }
+    /** Before STARTTLS: the raw socket is about to carry ciphertext. */
+    detach() {
+        this.socket.off("data", this.onData);
+        this.buffer = "";
+        this.queued = [];
+    }
+    attach(socket) {
+        this.socket = socket;
+        socket.on("data", this.onData);
+    }
+}
+function encodeHeader(value) {
+    // RFC 2047: a subject with an accent or a place name is not 7-bit.
+    return /^[\x20-\x7e]*$/.test(value) ? value : `=?UTF-8?B?${Buffer.from(value, "utf8").toString("base64")}?=`;
+}
+async function open(url, watch) {
+    const implicit = url.protocol === "smtps:";
+    const port = Number(url.port || (implicit ? 465 : 587));
+    const host = hostOf(url);
+    const socket = implicit ? tlsConnect({ host, port, servername: host }) : tcp({ host, port });
+    watch(socket);
+    await new Promise(resolve => socket.once(implicit ? "secureConnect" : "connect", () => resolve()));
+    return socket;
+}
+function message(mail) {
+    const body = Buffer.from(mail.text, "utf8").toString("base64").replace(/.{76}/g, "$&\r\n");
+    const domain = mail.from.split("@")[1] ?? "localhost";
+    return [
+        `From: ${mail.from}`,
+        `To: ${mail.to}`,
+        `Subject: ${encodeHeader(mail.subject)}`,
+        `Date: ${new Date().toUTCString()}`,
+        // Without one, some relays add their own and some spam filters score it.
+        `Message-ID: <${randomUUID()}@${domain}>`,
+        "MIME-Version: 1.0",
+        "Content-Type: text/plain; charset=utf-8",
+        "Content-Transfer-Encoding: base64",
+        "",
+        body,
+    ].join("\r\n");
+}
+const LOOPBACK = ["localhost", "127.0.0.1", "::1"];
+/** `URL.hostname` keeps an IPv6 literal's brackets; sockets want it bare. */
+const hostOf = (url) => url.hostname.replace(/^\[(.*)\]$/, "$1");
+/**
+ * Sends one message or rejects. Every way the conversation can die rejects
+ * rather than hangs: an error or a close on either socket (the raw one, and
+ * the TLS one over it after STARTTLS), and one deadline over the whole
+ * exchange — a server that accepts the connection and then says nothing must
+ * not hold a request's `after()` task forever.
+ *
+ * Off loopback, TLS is required: implicit (`smtps://`) or STARTTLS. A server
+ * that offers neither gets nothing — not the credentials, and not the
+ * customer's phone number in the body. The lead is already stored, so a
+ * refusal here is loud in the log and costs nothing else.
+ *
+ * `helo` is the name this client greets a remote relay with — the site's own
+ * domain; a loopback catcher is greeted as `localhost`.
+ */
+/** `SMTP_URL`, checked; the error never repeats it, since it carries the password. */
+export function parseSmtpUrl(value) {
+    let url;
+    try {
+        url = value instanceof URL ? value : new URL(value);
+    }
+    catch {
+        throw new Error("SMTP_URL is not a URL");
+    }
+    if (url.protocol !== "smtp:" && url.protocol !== "smtps:")
+        throw new Error(`SMTP_URL: unsupported scheme ${url.protocol}`);
+    if (!url.hostname)
+        throw new Error("SMTP_URL: no host");
+    return url;
+}
+export async function sendMail(smtpUrl, mail, options) {
+    const timeoutMs = options.timeoutMs ?? TOTAL_TIMEOUT_MS;
+    const url = parseSmtpUrl(smtpUrl);
+    const deadline = AbortSignal.timeout(timeoutMs);
+    let fail = () => undefined;
+    const failed = new Promise((_, reject) => (fail = reject));
+    // Handled here so a failure after the last exchange is not an unhandled
+    // rejection; every step still races against it.
+    failed.catch(() => undefined);
+    const sockets = [];
+    const watch = (s) => {
+        sockets.push(s);
+        s.on("error", fail);
+        s.once("close", () => fail(new Error("smtp: connection closed")));
+    };
+    deadline.addEventListener("abort", () => {
+        fail(new Error(`smtp: no answer within ${timeoutMs} ms`));
+        for (const s of sockets)
+            s.destroy();
+    });
+    let socket = await Promise.race([open(url, watch), failed]);
+    const replies = new Replies(socket);
+    const step = (p) => Promise.race([p, failed]);
+    const expect = async (ok, what) => {
+        const reply = await step(replies.next());
+        if (!ok(reply.code))
+            throw new Error(`smtp: ${what} refused: ${reply.text}`);
+        return reply;
+    };
+    const say = (line) => socket.write(`${line}\r\n`);
+    const hello = url.hostname.includes(".") ? options.helo : "localhost";
+    const loopback = LOOPBACK.includes(hostOf(url));
+    let done = false;
+    try {
+        await expect(c => c === 220, "greeting");
+        say(`EHLO ${hello}`);
+        const caps = await expect(c => c === 250, "EHLO");
+        let encrypted = url.protocol === "smtps:";
+        if (!encrypted && /STARTTLS/i.test(caps.text)) {
+            say("STARTTLS");
+            await expect(c => c === 220, "STARTTLS");
+            replies.detach();
+            const raw = socket;
+            socket = tlsConnect({ socket: raw, servername: hostOf(url) });
+            watch(socket);
+            await step(new Promise(resolve => socket.once("secureConnect", () => resolve())));
+            encrypted = true;
+            replies.attach(socket);
+            say(`EHLO ${hello}`);
+            await expect(c => c === 250, "EHLO after STARTTLS");
+        }
+        if (!encrypted && !loopback)
+            throw new Error("smtp: the server offers no TLS; refusing to send a lead in the clear");
+        if (url.username) {
+            const plain = Buffer.from(`\0${decodeURIComponent(url.username)}\0${decodeURIComponent(url.password)}`).toString("base64");
+            say(`AUTH PLAIN ${plain}`);
+            await expect(c => c === 235, "AUTH");
+        }
+        say(`MAIL FROM:<${mail.from}>`);
+        await expect(c => c === 250, "MAIL FROM");
+        say(`RCPT TO:<${mail.to}>`);
+        await expect(c => c === 250 || c === 251, "RCPT TO");
+        say("DATA");
+        await expect(c => c === 354, "DATA");
+        // Dot-stuffing: a line that starts with "." would otherwise end the data.
+        say(`${message(mail).replace(/\r\n\./g, "\r\n..")}\r\n.`);
+        await expect(c => c === 250, "message");
+        done = true;
+        say("QUIT");
+    }
+    finally {
+        // After the message is accepted, the server closing on QUIT is expected.
+        if (!done)
+            for (const s of sockets)
+                s.destroy();
+        else
+            socket.end();
+    }
+}

package/dist/testing/e2e.d.ts

@@ -0,0 +1,52 @@
+import type { Expect, Page, TestType } from "@playwright/test";
+/**
+ * `@evinvest/kitstart/testing/e2e` — the section-baseline runner a brand's
+ * Playwright suite calls. One baseline per section at both designed
+ * breakpoints; every section reached by its own URL (a `#` the site itself
+ * links to), never by scrolling to it — a scroll is a moving target the runner
+ * would have to guess is over.
+ *
+ * Types only from `@playwright/test`: the brand passes its own `test` and
+ * `expect`, so this module loads nothing at run time and cannot end up with a
+ * second copy of the runner (Playwright refuses to run with two).
+ */
+/**
+ * Waits until a section is what a visitor sees: web fonts applied, every
+ * image in it loaded (lazy ones forced), the network idle, and every finite
+ * animation finished — `animations: "disabled"` freezes CSS animations, not
+ * ones driven through the Web Animations API.
+ */
+export declare function settle(page: Page, selector: string): Promise<void>;
+export interface Section {
+    name: string;
+    /** Relative to the config's `baseURL`, or absolute for another host. */
+    url: string;
+    selector: string;
+    /** `md:hidden` in the design: shot only in the `mobile` project. */
+    mobileOnly?: boolean;
+    /** Shot without the section stylesheet (the call bar hides itself in it). */
+    bare?: boolean;
+}
+/** The two designed breakpoints, as Playwright projects. */
+export declare const BREAKPOINTS: readonly [{
+    readonly name: "desktop";
+    readonly viewport: {
+        readonly width: 1440;
+        readonly height: 900;
+    };
+}, {
+    readonly name: "mobile";
+    readonly viewport: {
+        readonly width: 390;
+        readonly height: 844;
+    };
+}];
+type AnyTest = TestType<any, any>;
+/** The brand's own runner: `import { test, expect } from "@playwright/test"`. */
+export interface Runner {
+    test: AnyTest;
+    expect: Expect;
+}
+/** One `test` per section, each a `toHaveScreenshot` of the settled section. */
+export declare function defineSectionSuite({ test, expect }: Runner, sections: readonly Section[]): void;
+export {};

package/dist/testing/e2e.js

@@ -0,0 +1,57 @@
+/**
+ * `@evinvest/kitstart/testing/e2e` — the section-baseline runner a brand's
+ * Playwright suite calls. One baseline per section at both designed
+ * breakpoints; every section reached by its own URL (a `#` the site itself
+ * links to), never by scrolling to it — a scroll is a moving target the runner
+ * would have to guess is over.
+ *
+ * Types only from `@playwright/test`: the brand passes its own `test` and
+ * `expect`, so this module loads nothing at run time and cannot end up with a
+ * second copy of the runner (Playwright refuses to run with two).
+ */
+/**
+ * Waits until a section is what a visitor sees: web fonts applied, every
+ * image in it loaded (lazy ones forced), the network idle, and every finite
+ * animation finished — `animations: "disabled"` freezes CSS animations, not
+ * ones driven through the Web Animations API.
+ */
+export async function settle(page, selector) {
+    await page.evaluate(() => document.fonts.ready);
+    await page.locator(selector).evaluate(root => Promise.all(Array.from(root.querySelectorAll("img"), img => {
+        img.loading = "eager";
+        if (img.complete)
+            return null;
+        return new Promise(done => {
+            img.addEventListener("load", done, { once: true });
+            img.addEventListener("error", done, { once: true });
+        });
+    })));
+    await page.waitForLoadState("networkidle");
+    await page.waitForFunction(() => document
+        .getAnimations()
+        .filter(a => (a.effect?.getComputedTiming().iterations ?? 1) !== Infinity)
+        .every(a => a.playState === "finished" || a.playState === "idle"), undefined, { timeout: 10_000 });
+}
+/** The two designed breakpoints, as Playwright projects. */
+export const BREAKPOINTS = [
+    { name: "desktop", viewport: { width: 1440, height: 900 } },
+    { name: "mobile", viewport: { width: 390, height: 844 } },
+];
+/** One `test` per section, each a `toHaveScreenshot` of the settled section. */
+export function defineSectionSuite({ test, expect }, sections) {
+    // The site scrolls smoothly for everyone who has not asked it not to;
+    // `use.reducedMotion` does not reach the page, `emulateMedia` does.
+    test.beforeEach(async ({ page }) => {
+        await page.emulateMedia({ reducedMotion: "reduce" });
+    });
+    for (const section of sections) {
+        test(`section: ${section.name}`, async ({ page }, info) => {
+            test.skip(Boolean(section.mobileOnly) && info.project.name !== "mobile");
+            await page.goto(section.url);
+            const locator = page.locator(section.selector);
+            await expect(locator).toBeVisible();
+            await settle(page, section.selector);
+            await expect(locator).toHaveScreenshot(`${section.name}-${info.project.name}.png`, section.bare ? { stylePath: [] } : {});
+        });
+    }
+}

package/dist/testing/fixtures.d.ts

@@ -0,0 +1,11 @@
+import type { Lead } from "../core/lead.js";
+import type { Place } from "../core/place/types.js";
+/**
+ * Places and leads for a brand's tests, in the two shapes the model has. Each
+ * takes overrides, so a test names only what it is about.
+ */
+export declare function storefrontPlace<L extends string>(locales: readonly L[], over?: Partial<Place<L>> & {
+    slug?: string;
+}): Place<L>;
+export declare function serviceAreaPlace<L extends string>(locales: readonly L[], over?: Partial<Place<L>>): Place<L>;
+export declare function testLead(over?: Partial<Lead>): Lead;

package/dist/testing/fixtures.js

@@ -0,0 +1,53 @@
+/** One string in every locale. */
+function sameIn(locales, text) {
+    const out = {};
+    for (const l of locales)
+        out[l] = text;
+    if (!complete(out, locales))
+        throw new Error("sameIn: a locale was skipped");
+    return out;
+}
+function complete(record, locales) {
+    return locales.every(l => typeof record[l] === "string");
+}
+/**
+ * Places and leads for a brand's tests, in the two shapes the model has. Each
+ * takes overrides, so a test names only what it is about.
+ */
+export function storefrontPlace(locales, over = {}) {
+    const name = sameIn(locales, "Royat");
+    return {
+        slug: "royat",
+        gbpName: "Test Storefront — Royat",
+        name,
+        presence: {
+            kind: "storefront",
+            address: { street: "2 Av. Abbé Védrine", postalCode: "63130", locality: "Royat", region: "Auvergne-Rhône-Alpes", country: "FR" },
+            geo: null,
+            storefrontPhoto: null,
+            landmark: null,
+        },
+        serviceArea: null,
+        channels: { phone: null, whatsapp: null },
+        hours: null,
+        rating: null,
+        ...over,
+    };
+}
+export function serviceAreaPlace(locales, over = {}) {
+    const name = sameIn(locales, "Paris");
+    return {
+        slug: "paris",
+        gbpName: "Test Service — Paris",
+        name,
+        presence: { kind: "service-area" },
+        serviceArea: [{ kind: "localities", names: ["Paris", "Boulogne-Billancourt"] }],
+        channels: { phone: null, whatsapp: null },
+        hours: [{ days: ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"], opens: "08:00", closes: "19:00" }],
+        rating: null,
+        ...over,
+    };
+}
+export function testLead(over = {}) {
+    return { subject: "other", locality: "63130", mobile: "06 12 34 56 78", extras: {}, placeSlug: null, spamVerdict: null, ...over };
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@evinvest/kitstart/testing` — the suites a brand runs from its own vitest:
+ * the landing contract over its site config, the lead store contract over any
+ * adapter, and fixtures in both place shapes. `vitest` is not a peer: the
+ * brand installs it in its own `devDependencies`, like `@playwright/test` for
+ * `./testing/e2e`.
+ * The Playwright half is `./testing/e2e`.
+ */
+export { describeLandingContract, type LandingContractOptions } from "./landing-contract.js";
+export { servedPaths } from "./served-files.js";
+export { describeLeadStoreContract, type LeadStoreHarness } from "./lead-store-contract.js";
+export { serviceAreaPlace, storefrontPlace, testLead } from "./fixtures.js";

package/dist/testing/index.js

@@ -0,0 +1,12 @@
+/**
+ * `@evinvest/kitstart/testing` — the suites a brand runs from its own vitest:
+ * the landing contract over its site config, the lead store contract over any
+ * adapter, and fixtures in both place shapes. `vitest` is not a peer: the
+ * brand installs it in its own `devDependencies`, like `@playwright/test` for
+ * `./testing/e2e`.
+ * The Playwright half is `./testing/e2e`.
+ */
+export { describeLandingContract } from "./landing-contract.js";
+export { servedPaths } from "./served-files.js";
+export { describeLeadStoreContract } from "./lead-store-contract.js";
+export { serviceAreaPlace, storefrontPlace, testLead } from "./fixtures.js";