@stack-mode/site-manager-kit 0.0.0-stage → 1.44.0

package/src/forms.ts

@@ -0,0 +1,76 @@
+"use server";
+
+import { createHash } from "node:crypto";
+import { headers } from "next/headers";
+import { bpRaw } from "./client";
+import { checkFormToken } from "./form-token";
+import { ATTRIBUTION_FIELD_NAMES, attributionFrom } from "./attribution-fields";
+import { SLOT_FIELD, type SpamReason, type SubmitResult } from "./form-types";
+
+const GUARD_FIELDS = new Set(["bp_hp", "bp_ts"]);
+
+async function isBot(): Promise<boolean> {
+  try {
+    const { checkBotId } = await import("botid/server");
+    const r = await checkBotId();
+    return r.isBot && !r.isVerifiedBot;
+  } catch {
+    // BotID isn't set up on this site. The honeypot and time check still apply.
+    return false;
+  }
+}
+
+export type SubmitOptions = {
+  /**
+   * The site checked how long the form was open itself (its own signed timer), or the send has no form at all (a
+   * remembered visitor's one-click download), so there's no FormGuard timer to check. The honeypot (when sent) and
+   * BotID still apply. Use only after the site's own checks; anything else should render FormGuard.
+   */
+  timedBySite?: boolean;
+};
+
+/**
+ * Sends one form to Site Manager from the site's server. Checks BotID, the honeypot and the 3-second render
+ * time first, hashes the visitor's IP (Site Manager never sees it), then forwards the fields.
+ *
+ * It returns the result, so use it from server code, or use formAction with useActionState in a client form.
+ */
+export async function submitForm(formKey: string, formData: FormData, opts: SubmitOptions = {}): Promise<SubmitResult> {
+  // Spam checks: a filled honeypot, a form sent too fast (or with a missing or stale timer), or BotID. Suspected
+  // spam still goes to Site Manager, marked, for its spam folder (where a real person caught by mistake can be
+  // rescued), and the visitor sees the usual thank-you, so bots learn nothing.
+  const token = opts.timedBySite ? { ok: true as const } : checkFormToken(String(formData.get("bp_ts") ?? ""));
+  const spam: SpamReason | null = String(formData.get("bp_hp") ?? "").trim() !== "" ? "honeypot" : !token.ok ? (token.reason === "too_fast" ? "too_fast" : "bot") : (await isBot()) ? "bot" : null;
+
+  const h = await headers();
+  const ip = h.get("x-real-ip") ?? h.get("x-forwarded-for")?.split(",")[0]?.trim() ?? "";
+  const data: Record<string, string> = {};
+  for (const [k, v] of formData.entries()) {
+    if (GUARD_FIELDS.has(k) || ATTRIBUTION_FIELD_NAMES.has(k) || k === SLOT_FIELD || k.startsWith("$ACTION") || typeof v !== "string") continue;
+    data[k] = v;
+  }
+
+  const { status, json } = await bpRaw(`/forms/${encodeURIComponent(formKey)}/submit`, {
+    data,
+    pageUrl: h.get("referer") ?? undefined,
+    ipHash: ip ? createHash("sha256").update(ip).digest("hex") : undefined,
+    userAgent: h.get("user-agent")?.slice(0, 500) ?? undefined,
+    attribution: attributionFrom(formData),
+    slot: typeof formData.get(SLOT_FIELD) === "string" && formData.get(SLOT_FIELD) ? String(formData.get(SLOT_FIELD)) : undefined,
+    // A Site Manager from before the spam folder ignores `spam` but still refuses a filled honeypot, so spam is
+    // never delivered as a lead there either.
+    ...(spam ? { spam, hp: `kit:${spam}` } : {}),
+  });
+  const body = json as { data?: { id: string; successMessage: string }; error?: { code: string; fields?: Record<string, string> } } | null;
+  if (spam) return { ok: true, id: body?.data?.id ?? "", successMessage: body?.data?.successMessage ?? "Thanks! We'll be in touch soon." };
+  if (status === 201 && body?.data) return { ok: true, id: body.data.id, successMessage: body.data.successMessage };
+  if (status === 422) return { ok: false, error: "invalid", fields: body?.error?.fields ?? {} };
+  if (status === 409) return { ok: false, error: "slot_taken", fields: body?.error?.fields ?? {} };
+  if (status === 429) return { ok: false, error: "rate_limited" };
+  return { ok: false, error: "unavailable" };
+}
+
+/** The same, shaped for React's useActionState: `useActionState(formAction.bind(null, "inquiry"), null)`. */
+export async function formAction(formKey: string, _prev: SubmitResult | null, formData: FormData): Promise<SubmitResult> {
+  return submitForm(formKey, formData);
+}

package/src/glossary.ts

@@ -0,0 +1,19 @@
+import type { GlossaryTerm } from "./types";
+
+type Json = Record<string, unknown>;
+
+/**
+ * schema.org `DefinedTerm` structured data for a term's own page, in the glossary named `setName` at `setUrl`.
+ * Render it with `jsonLdScript`.
+ */
+export function definedTermJsonLd(t: Pick<GlossaryTerm, "term" | "shortDefinition" | "url" | "alsoKnownAs">, set: { setName: string; setUrl?: string | null }): Json {
+  return {
+    "@context": "https://schema.org",
+    "@type": "DefinedTerm",
+    name: t.term,
+    description: t.shortDefinition,
+    ...(t.url ? { url: t.url } : {}),
+    ...(t.alsoKnownAs.length ? { alternateName: t.alsoKnownAs } : {}),
+    inDefinedTermSet: { "@type": "DefinedTermSet", name: set.setName, ...(set.setUrl ? { url: set.setUrl } : {}) },
+  };
+}

package/src/health-route.ts

@@ -0,0 +1,34 @@
+import { SIGNATURE_HEADER, verify } from "./signature";
+import { KIT_VERSION } from "./version";
+
+async function botIdInstalled(): Promise<boolean> {
+  try {
+    await import("botid/server");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The deployment serving this site (Vercel sets these), so Site Manager can tell a new deploy happened. */
+function deployId(): string | null {
+  return process.env.VERCEL_DEPLOYMENT_ID?.trim() || process.env.VERCEL_GIT_COMMIT_SHA?.trim() || null;
+}
+
+/**
+ * Site Manager calls this to show Form protection and Site connection in its System Status. Put in
+ * app/api/blueprint/health/route.ts:
+ *
+ *   export { GET } from "site-manager-kit/health-route";
+ *
+ * Signed with the revalidate secret over an empty body. Unsigned requests get a 401. `deployId` changing tells Site
+ * Manager the site was deployed, so it runs its wiring check the same day.
+ */
+export async function GET(req: Request): Promise<Response> {
+  const check = verify(process.env.BLUEPRINT_REVALIDATE_SECRET, req.headers.get(SIGNATURE_HEADER), "");
+  if (!check.ok) return Response.json({ error: check.reason }, { status: 401 });
+  return Response.json(
+    { kitVersion: KIT_VERSION, botId: await botIdInstalled(), formSecret: !!process.env.BLUEPRINT_FORM_SECRET?.trim(), revalidate: true, deployId: deployId() },
+    { headers: { "cache-control": "no-store" } },
+  );
+}

package/src/image.ts

@@ -0,0 +1,12 @@
+import type { Image } from "./types";
+
+/**
+ * Props for next/image from a Site Manager image: `<Image {...imageProps(plan.image)} sizes="..." />`.
+ * With the size known it gets width and height, so the page doesn't jump while it loads; without, it uses `fill`,
+ * so put it in a sized, positioned box. Null when there's no image, so the caller decides what to show instead.
+ */
+export function imageProps(image: Image | null | undefined): ({ src: string; alt: string } & ({ width: number; height: number } | { fill: true })) | null {
+  if (!image?.url) return null;
+  if (image.width && image.height) return { src: image.url, alt: image.alt, width: image.width, height: image.height };
+  return { src: image.url, alt: image.alt, fill: true };
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+// Server-side helpers for a Next.js site that reads its content from Site Manager.
+// Route handlers, the form action and the form guard have their own entry points:
+//   site-manager-kit/revalidate-route, site-manager-kit/health-route, site-manager-kit/forms, site-manager-kit/waitlist,
+//   site-manager-kit/form-guard, site-manager-kit/redirects, site-manager-kit/preview-route, site-manager-kit/rss-route,
+//   site-manager-kit/visual, site-manager-kit/copy-keys-route, site-manager-kit/chat-route. A site's src/copy-keys.ts uses site-manager-kit/copy-keys.
+//   next.config.ts uses
+//   site-manager-kit/config, and the root layout site-manager-kit/analytics, site-manager-kit/attribution and
+//   site-manager-kit/preview-banner, site-manager-kit/visual-editing and site-manager-kit/chat.
+
+export { bp, bpWithMeta, BlueprintError, siteId, tagsFor } from "./client";
+export * from "./data";
+export { blogPostingJsonLd, buildRss, getBlogCategories, getBlogCategory, getBlogFeed, getBlogTags, getPost, getPosts } from "./blog";
+export { buildMetadata, defaultMetadata, pageMetadata, titleWithSuffix, TITLE_CHAR_LIMIT } from "./metadata";
+export { buildSitemap, sitemap } from "./sitemap";
+export { buildRobots, robots } from "./robots";
+export { buildRedirectMap, handleRedirect, matchRedirect, normalizePath } from "./redirects";
+export { formatMoney } from "./money";
+export { availabilityText, comparisonRows, effectiveRentText, type ComparisonRow } from "./floor-plans";
+export { bathsText, hoaText, listingAddress, listingPrice, lotText } from "./listings";
+export { estimatePayment } from "./payment";
+export { serviceJsonLd } from "./services";
+export { leaseTermsText, pickupText } from "./residents";
+export { faqJsonLd, jsonLdScript } from "./faq";
+export { absoluteUrl, breadcrumbJsonLd, breadcrumbsFor, businessJsonLd, eventJsonLd, floorPlanJsonLd, listingJsonLd, openingHours, placeMapUrl, plainText, StructuredData } from "./structured-data";
+export { definedTermJsonLd } from "./glossary";
+export { announcementsLiveAt } from "./announcements";
+export { fileSizeText } from "./downloads";
+export { imageProps } from "./image";
+export { sign, verify, SIGNATURE_HEADER } from "./signature";
+export { SLOT_FIELD, type SubmitResult } from "./form-types";
+export { readWaitlistForm, waitlistChoices, WAITLIST_FIELDS, type WaitlistInput } from "./waitlist-form";
+export { formatUsPhone, maskPhoneInput, normalizeUsPhone, phoneDigits } from "./phone";
+export { attributionFrom, firstTouch, ATTRIBUTION_FIELDS } from "./attribution-fields";
+export type * from "./types";
+export { parseChatLines, type ChatConfig, type ChatEvent, type ChatSlots } from "./chat-types";
+export { KIT_VERSION } from "./version";

package/src/indexnow.ts

@@ -0,0 +1,40 @@
+import { NextResponse, type NextRequest } from "next/server";
+import { bp } from "./client";
+
+// IndexNow: Site Manager tells search engines (Bing and others; not Google) when pages change, and they check the
+// site serves the same key at /{key}.txt. The key comes from Site Manager, kept in memory for an hour.
+
+const TTL_MS = 60 * 60_000;
+let cache: { at: number; key: string | null } | null = null;
+
+/** The IndexNow key Site Manager uses for this site, or null when IndexNow isn't set up. */
+export async function indexNowKey(): Promise<string | null> {
+  if (cache && Date.now() - cache.at < TTL_MS) return cache.key;
+  try {
+    const r = await bp<{ key: string | null }>("/indexnow", { cache: "no-store" });
+    cache = { at: Date.now(), key: r?.key ?? null };
+  } catch {
+    // Site Manager unreachable: don't remember the failure, try again next time.
+    return null;
+  }
+  return cache.key;
+}
+
+/** Clears the remembered key (tests, or after Site Manager's key changes). */
+export function resetIndexNowKey() {
+  cache = null;
+}
+
+const KEY_FILE = /^\/([A-Za-z0-9-]{8,128})\.txt$/;
+
+/**
+ * For `src/proxy.ts`: answers `/{key}.txt` with the key when it matches Site Manager's, or undefined to carry on.
+ * Any other .txt address passes through untouched.
+ */
+export async function handleIndexNow(request: NextRequest): Promise<NextResponse | undefined> {
+  const m = KEY_FILE.exec(request.nextUrl.pathname);
+  if (!m) return undefined;
+  const key = await indexNowKey();
+  if (!key || key !== m[1]) return undefined;
+  return new NextResponse(key, { headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "public, max-age=3600" } });
+}

package/src/listings.ts

@@ -0,0 +1,38 @@
+import { formatMoney } from "./money";
+import type { Listing } from "./types";
+
+// Display text for listing facts. Each returns null when Site Manager doesn't know the value, so the page can
+// leave the line out instead of showing a guess.
+
+/** "2.5" stays "2.5"; "3.0" becomes "3". */
+export function bathsText(baths: string | null): string | null {
+  if (baths === null) return null;
+  return baths.replace(/\.0+$/, "");
+}
+
+/** "1.02 acres" or "8,276 sq ft". */
+export function lotText(lot: Listing["lot"]): string | null {
+  if (!lot) return null;
+  const [whole, frac] = lot.size.split(".");
+  const trimmed = frac && Number(frac) !== 0 ? `${Number(whole).toLocaleString("en-US")}.${frac.replace(/0+$/, "")}` : Number(whole).toLocaleString("en-US");
+  return lot.unit === "acres" ? `${trimmed} ${trimmed === "1" ? "acre" : "acres"}` : `${trimmed} sq ft`;
+}
+
+/** "$85 per month". */
+export function hoaText(hoa: Listing["hoa"]): string | null {
+  if (!hoa) return null;
+  return `${formatMoney(hoa.amount)} per ${hoa.frequency === "monthly" ? "month" : hoa.frequency === "quarterly" ? "quarter" : "year"}`;
+}
+
+/** "1180 Paddock Lane, Reno, NV 89521", skipping what isn't set. */
+export function listingAddress(l: Pick<Listing, "address">): string {
+  const a = l.address;
+  const street = [a.line1, a.line2].filter(Boolean).join(" ");
+  const regionZip = [a.region, a.postalCode].filter(Boolean).join(" ");
+  return [street, a.city, regionZip].filter(Boolean).join(", ");
+}
+
+/** The price to headline: the sold price once sold, otherwise the list price. */
+export function listingPrice(l: Pick<Listing, "status" | "price" | "soldPrice">): string | null {
+  return l.status === "sold" && l.soldPrice ? l.soldPrice : l.price;
+}

package/src/metadata.ts

@@ -0,0 +1,55 @@
+import type { Metadata } from "next";
+import { bp, tagsFor } from "./client";
+import { getSite } from "./data";
+import type { PageMeta, Site } from "./types";
+
+// Site Manager measures titles in pixels in its admin. The server can't, so the suffix rule here uses the
+// character limit it matches: about 60 characters fit in 580px.
+export const TITLE_CHAR_LIMIT = 60;
+
+/** The title with the site's suffix when it still fits, otherwise the title alone. */
+export function titleWithSuffix(title: string, suffix: string | null | undefined): string {
+  const t = title.trim();
+  if (!suffix) return t;
+  return `${t}${suffix}`.length <= TITLE_CHAR_LIMIT ? `${t}${suffix}` : t;
+}
+
+/** Pure: Site Manager's page data to Next metadata. Anything set in `overrides` wins. */
+export function buildMetadata(meta: PageMeta, overrides: Metadata = {}): Metadata {
+  const title = titleWithSuffix(meta.title, meta.titleSuffix);
+  const description = meta.description ?? undefined;
+  const images = meta.ogImage ? [{ url: meta.ogImage.url, width: meta.ogImage.width ?? undefined, height: meta.ogImage.height ?? undefined, alt: meta.ogImage.alt }] : undefined;
+  // Share previews use their own title and description when Site Manager has them.
+  const shareTitle = meta.ogTitle?.trim() || title;
+  const shareDescription = meta.ogDescription?.trim() || description;
+  return {
+    title: { absolute: title },
+    description,
+    alternates: meta.canonical ? { canonical: meta.canonical } : undefined,
+    robots: { index: !meta.noindex, follow: !meta.nofollow, ...(meta.maxImagePreview ? { "max-image-preview": meta.maxImagePreview } : {}) },
+    openGraph: { title: shareTitle, description: shareDescription, url: meta.canonical ?? undefined, siteName: meta.siteName, images, type: "website", locale: "en_US" },
+    // X reads Open Graph when its own tags are missing, so they're only written when the share text differs.
+    twitter: { card: "summary_large_image", ...(meta.ogTitle?.trim() ? { title: shareTitle } : {}), ...(meta.ogDescription?.trim() ? { description: shareDescription } : {}) },
+    ...overrides,
+  };
+}
+
+/** Pure: the fallback when Site Manager has no page for this path. */
+export function defaultMetadata(site: Site | null, overrides: Metadata = {}): Metadata {
+  const name = site?.business.displayName ?? site?.name;
+  return { ...(name ? { title: { absolute: name }, openGraph: { siteName: name, type: "website", locale: "en_US" } } : {}), ...overrides };
+}
+
+/**
+ * Metadata for one path, for a page's `generateMetadata`. A path Site Manager doesn't know gets the site's
+ * defaults, and a Site Manager outage never breaks the page: it falls back to the overrides alone.
+ */
+export async function pageMetadata(path: string, overrides: Metadata = {}): Promise<Metadata> {
+  try {
+    const meta = await bp<PageMeta>(`/pages/meta?path=${encodeURIComponent(path)}`, { tags: tagsFor("seo") });
+    if (meta) return buildMetadata(meta, overrides);
+    return defaultMetadata(await getSite(), overrides);
+  } catch {
+    return overrides;
+  }
+}

package/src/money.ts

@@ -0,0 +1,10 @@
+/** "$1,450" or "$1,450.00" from Site Manager's decimal strings. No float math on the amount. */
+export function formatMoney(value: string | null | undefined, opts: { cents?: boolean } = {}): string | null {
+  if (value === null || value === undefined) return null;
+  const m = value.trim().match(/^(-?)(\d+)(?:\.(\d{1,2}))?$/);
+  if (!m) return null;
+  const [, sign, whole, frac = "00"] = m;
+  const cents = frac.padEnd(2, "0");
+  const grouped = whole.replace(/^0+(?=\d)/, "").replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+  return `${sign}$${grouped}${opts.cents || cents !== "00" ? `.${cents}` : ""}`;
+}

package/src/not-found-reporter.tsx

@@ -0,0 +1,16 @@
+"use client";
+
+import { useEffect } from "react";
+
+/**
+ * Put in the site's `app/not-found.tsx`: reports the missing address (and where the visitor came from) to the site's
+ * own `/api/not-found` route once, after the page shows. Renders nothing.
+ */
+export function NotFoundReporter({ endpoint = "/api/not-found" }: { endpoint?: string }) {
+  useEffect(() => {
+    const body = JSON.stringify({ path: window.location.pathname, referrer: document.referrer || null });
+    // keepalive lets the report finish if the visitor leaves straight away.
+    fetch(endpoint, { method: "POST", headers: { "content-type": "application/json" }, body, keepalive: true }).catch(() => {});
+  }, [endpoint]);
+  return null;
+}

package/src/not-found.ts

@@ -0,0 +1,53 @@
+import { bp } from "./client";
+
+// Missing-page reports for Site Manager's Not Found list (Search Listings, Redirects). The site's not-found page
+// can't see the address it's showing on the server, so the browser tells the site's own route, which tells Site
+// Manager with the site's key. Fire and forget: a failure never shows to the visitor.
+
+const MAX = 500;
+
+/** Reports one server instance passes on per minute; a flood past this is dropped before it reaches Site Manager. */
+const PER_MINUTE = 120;
+let window = { start: 0, count: 0 };
+
+/** Whether one more report fits this minute (exported for tests). */
+export function reportAllowed(now = Date.now()): boolean {
+  if (now - window.start >= 60_000) window = { start: now, count: 0 };
+  return ++window.count <= PER_MINUTE;
+}
+
+export function resetReportLimit() {
+  window = { start: 0, count: 0 };
+}
+
+/** Server only: reports one visit to an address the site doesn't have. Never throws. */
+export async function reportNotFound(path: string, referrer?: string | null): Promise<void> {
+  if (typeof path !== "string" || !path.startsWith("/") || path.length > MAX) return;
+  await bp("/not-found", { method: "POST", body: { path, referrer: referrer ? String(referrer).slice(0, 2000) : null } }).catch(() => {});
+}
+
+/**
+ * The site's `app/api/not-found/route.ts`: `export { notFoundRoute as POST } from "site-manager-kit/not-found"`.
+ * Only this site's own pages may call it: browsers send Origin with every POST, so a call without one, or from
+ * another site, is dropped. At most 120 reports a minute per server instance. It always answers 204.
+ */
+export async function notFoundRoute(request: Request): Promise<Response> {
+  const done = new Response(null, { status: 204 });
+  const origin = request.headers.get("origin");
+  const host = request.headers.get("host");
+  try {
+    if (!origin || !host || new URL(origin).host !== host) return done;
+  } catch {
+    return done;
+  }
+  if (!reportAllowed()) return done;
+  const raw = await request.text().catch(() => "");
+  if (raw.length > 3000) return done;
+  try {
+    const body = JSON.parse(raw) as { path?: unknown; referrer?: unknown };
+    if (typeof body.path === "string") await reportNotFound(body.path, typeof body.referrer === "string" ? body.referrer : null);
+  } catch {
+    // Not JSON: nothing to report.
+  }
+  return done;
+}

package/src/payment.ts

@@ -0,0 +1,70 @@
+import type { HoaDues, PaymentDefaults, PaymentEstimate } from "./types";
+
+/*
+ * Estimated monthly payment for a listing price, in integer math only (cents and BigInt fixed point), so no float
+ * rounding reaches an amount. Site Manager has the same function for its settings example (src/lib/payment.ts);
+ * both are tested against the same figures. Always label the result as an estimate on the page.
+ */
+
+const SCALE = BigInt(10) ** BigInt(18);
+const MICRO = BigInt(1_000_000);
+const HUNDRED = BigInt(100);
+
+/** "1450", "$1,450.5" -> 145050 cents. Throws on anything that isn't an amount. */
+export function toCents(value: string): bigint {
+  const m = value
+    .trim()
+    .replace(/^\$/, "")
+    .replace(/,/g, "")
+    .match(/^(\d{1,10})(?:\.(\d{1,2}))?$/);
+  if (!m) throw new Error(`Not an amount: ${value}`);
+  return BigInt(m[1]) * HUNDRED + BigInt((m[2] ?? "").padEnd(2, "0"));
+}
+
+export function fromCents(cents: bigint): string {
+  const negative = cents < BigInt(0);
+  const abs = negative ? -cents : cents;
+  return `${negative ? "-" : ""}${abs / HUNDRED}.${(abs % HUNDRED).toString().padStart(2, "0")}`;
+}
+
+/** "6.75" -> 6750000 (millionths). */
+function toMicro(value: string): bigint {
+  const m = value.trim().match(/^(\d{1,6})(?:\.(\d{1,6}))?$/);
+  if (!m) throw new Error(`Not a number: ${value}`);
+  return BigInt(m[1]) * MICRO + BigInt((m[2] ?? "").padEnd(6, "0"));
+}
+
+/** a / b rounded half up, for non-negative values. */
+const divRound = (a: bigint, b: bigint) => (a * BigInt(2) + b) / (BigInt(2) * b);
+
+/** Monthly principal and interest in cents for a loan in cents. */
+export function monthlyPrincipalAndInterest(loanCents: bigint, ratePercent: string, termYears: number): bigint {
+  const n = termYears * 12;
+  if (!Number.isInteger(n) || n <= 0) throw new Error("The term must be a whole number of years");
+  if (loanCents <= BigInt(0)) return BigInt(0);
+  const r = (toMicro(ratePercent) * SCALE) / (MICRO * BigInt(1200));
+  if (r === BigInt(0)) return divRound(loanCents, BigInt(n));
+  let pow = SCALE;
+  for (let i = 0; i < n; i++) pow = (pow * (SCALE + r)) / SCALE;
+  return divRound(loanCents * r * pow, (pow - SCALE) * SCALE);
+}
+
+/**
+ * The estimated monthly payment for a price: principal and interest from the site's defaults, plus property tax,
+ * insurance and HOA dues when known (each null when not). Null when the price, rate, down payment or term isn't
+ * known, so the page shows no estimate rather than a made-up one.
+ */
+export function estimatePayment(price: string | null | undefined, d: PaymentDefaults, hoa: HoaDues | null = null): PaymentEstimate | null {
+  if (!price || d.ratePercent === null || d.downPaymentPercent === null || d.termYears === null) return null;
+  const priceCents = toCents(price);
+  if (priceCents <= BigInt(0)) return null;
+  const down = divRound(priceCents * toMicro(d.downPaymentPercent), MICRO * HUNDRED);
+  const loan = priceCents > down ? priceCents - down : BigInt(0);
+  const pi = monthlyPrincipalAndInterest(loan, d.ratePercent, d.termYears);
+  const tax = d.taxRatePercent === null ? null : divRound(priceCents * toMicro(d.taxRatePercent), MICRO * BigInt(1200));
+  const insurance = d.insuranceYearly === null ? null : divRound(toCents(d.insuranceYearly), BigInt(12));
+  const hoaMonthly = hoa === null ? null : divRound(toCents(hoa.amount), BigInt(hoa.frequency === "monthly" ? 1 : hoa.frequency === "quarterly" ? 3 : 12));
+  const total = [pi, tax, insurance, hoaMonthly].reduce<bigint>((sum, v) => sum + (v ?? BigInt(0)), BigInt(0));
+  const money = (c: bigint | null) => (c === null ? null : fromCents(c));
+  return { downPayment: fromCents(down), loanAmount: fromCents(loan), principalAndInterest: fromCents(pi), tax: money(tax), insurance: money(insurance), hoa: money(hoaMonthly), total: fromCents(total) };
+}

package/src/phone-input.tsx

@@ -0,0 +1,26 @@
+"use client";
+
+import { useState, type InputHTMLAttributes } from "react";
+import { maskPhoneInput } from "./phone";
+
+/**
+ * A phone field that formats as the visitor types: (555) 123-4567. Use it for a form's phone fields; Site Manager
+ * checks for 10 US digits and stores that same format. Everything else (name, required, className) passes through.
+ */
+export function PhoneInput({ defaultValue, onChange, ...rest }: Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "value"> & { defaultValue?: string }) {
+  const [value, setValue] = useState(defaultValue ? maskPhoneInput("", String(defaultValue)) : "");
+  return (
+    <input
+      {...rest}
+      type="tel"
+      inputMode="tel"
+      autoComplete={rest.autoComplete ?? "tel"}
+      placeholder={rest.placeholder ?? "(555) 123-4567"}
+      value={value}
+      onChange={(e) => {
+        setValue(maskPhoneInput(value, e.target.value));
+        onChange?.(e);
+      }}
+    />
+  );
+}

package/src/phone.ts

@@ -0,0 +1,37 @@
+// US phone numbers, one format everywhere: (555) 123-4567. The same rules as Site Manager's own (src/lib/phone.ts
+// there), so what a visitor types, what Site Manager stores and what it shows all match.
+
+/** The 10 digits of a US number, dropping a leading country code 1. Extra digits beyond 10 are ignored. */
+export function phoneDigits(raw: string): string {
+  let d = raw.replace(/\D/g, "");
+  if (d.length > 10 && d.startsWith("1")) d = d.slice(1);
+  return d.slice(0, 10);
+}
+
+/** As typed: "(555) 123-4567", built up as the digits come in. `complete` once there are 10. */
+export function formatUsPhone(raw: string): { text: string; complete: boolean } {
+  const d = phoneDigits(raw);
+  let text = "";
+  if (d.length > 0) text = `(${d.slice(0, 3)}`;
+  if (d.length >= 3) text += ")";
+  if (d.length > 3) text += ` ${d.slice(3, 6)}`;
+  if (d.length > 6) text += `-${d.slice(6)}`;
+  return { text, complete: d.length === 10 };
+}
+
+/**
+ * The next value of a masked input. Backspace over a ")" or "-" removes the digit before it too, so the mask never
+ * traps the cursor.
+ */
+export function maskPhoneInput(prev: string, next: string): string {
+  if (next.length < prev.length && phoneDigits(next) === phoneDigits(prev)) return formatUsPhone(phoneDigits(prev).slice(0, -1)).text;
+  return formatUsPhone(next).text;
+}
+
+/** The stored form of a phone number, or null when it isn't a 10-digit US number. */
+export function normalizeUsPhone(raw: string): string | null {
+  const f = formatUsPhone(raw);
+  return f.complete && raw.replace(/\D/g, "").length <= 11 ? f.text : null;
+}
+
+export const PHONE_ERROR = "Enter a 10-digit phone number";

package/src/preview-banner.tsx

@@ -0,0 +1,49 @@
+import { draftMode } from "next/headers";
+
+/**
+ * Put once inside <body> in app/layout.tsx. While a preview is open it shows a small bar saying so, with a way out;
+ * otherwise it renders nothing. It uses the browser's own system colors, so it reads on any design.
+ */
+export async function PreviewBanner({ exitPath = "/" }: { exitPath?: string }) {
+  let on = false;
+  try {
+    on = (await draftMode()).isEnabled;
+  } catch {
+    return null;
+  }
+  if (!on) return null;
+  return (
+    <div
+      role="status"
+      style={{
+        position: "fixed",
+        insetInline: 0,
+        bottom: 16,
+        zIndex: 2147483647,
+        display: "flex",
+        justifyContent: "center",
+        pointerEvents: "none",
+      }}
+    >
+      <div
+        style={{
+          pointerEvents: "auto",
+          display: "flex",
+          alignItems: "center",
+          gap: 16,
+          padding: "10px 16px",
+          borderRadius: 999,
+          background: "CanvasText",
+          color: "Canvas",
+          font: "500 14px/1.3 system-ui, sans-serif",
+          boxShadow: "0 8px 24px color-mix(in srgb, CanvasText 25%, transparent)",
+        }}
+      >
+        <span>Preview: showing unpublished changes from Site Manager</span>
+        <a href={`/api/blueprint/preview?exit=1&path=${encodeURIComponent(exitPath)}`} style={{ color: "inherit", fontWeight: 700 }}>
+          Exit preview
+        </a>
+      </div>
+    </div>
+  );
+}

package/src/preview-route.ts

@@ -0,0 +1,48 @@
+import { cookies, draftMode } from "next/headers";
+import { siteId } from "./client";
+import { safePath, signVisualCookie, verifyPreviewToken, VISUAL_COOKIE } from "./preview";
+
+/**
+ * Opens a preview of unpublished changes from Site Manager. Put in app/api/blueprint/preview/route.ts:
+ *
+ *   export { GET } from "site-manager-kit/preview-route";
+ *
+ * `?token=` is a signed link from Site Manager (it lasts an hour). It turns on Next.js draft mode for this browser
+ * and opens the page; while it's on, every Site Manager read skips the cache and includes drafts and scheduled
+ * changes. `?exit=1&path=/` turns it off again. Anything else gets a 401 and changes nothing.
+ *
+ * A Visual Editor link also names the Site Manager address it was made on. It sets the visual cookie, which lets
+ * that address (and only that one) show this site in a frame while the preview lasts.
+ */
+export async function GET(req: Request): Promise<Response> {
+  const url = new URL(req.url);
+  const draft = await draftMode();
+  if (url.searchParams.get("exit") === "1") {
+    draft.disable();
+    (await cookies()).set({ name: VISUAL_COOKIE, value: "", ...frameCookie(url), maxAge: 0 });
+    return redirect(url, safePath(url.searchParams.get("path")) ?? "/");
+  }
+  const secret = process.env.BLUEPRINT_REVALIDATE_SECRET;
+  const ok = verifyPreviewToken(secret, url.searchParams.get("token"), siteId());
+  if (!ok) return Response.json({ error: "invalid_preview_link" }, { status: 401, headers: { "cache-control": "no-store" } });
+  draft.enable();
+  if (!ok.adminOrigin || !secret) return redirect(url, ok.path);
+  // Inside a frame on another site, cookies only stick when they are SameSite=None, Secure and, on browsers that
+  // split third-party cookies by top site, Partitioned. Next sets the draft cookie without Partitioned, so set it again.
+  const jar = await cookies();
+  const bypass = jar.get("__prerender_bypass")?.value;
+  if (bypass) jar.set({ name: "__prerender_bypass", value: bypass, httpOnly: true, ...frameCookie(url) });
+  jar.set({ name: VISUAL_COOKIE, value: signVisualCookie(secret, siteId(), ok.adminOrigin), httpOnly: true, maxAge: 3600, ...frameCookie(url) });
+  return redirect(url, ok.path, { "content-security-policy": `frame-ancestors 'self' ${ok.adminOrigin}` });
+}
+
+// Browsers accept Secure cookies from http://localhost, so local work behaves like the live site.
+function frameCookie(url: URL) {
+  const secure = url.protocol === "https:" || url.hostname === "localhost" || url.hostname.endsWith(".localhost");
+  return { path: "/", secure, sameSite: secure ? ("none" as const) : ("lax" as const), partitioned: secure };
+}
+
+// Relative to this site, so a preview can never send anyone somewhere else.
+function redirect(from: URL, path: string, headers: Record<string, string> = {}) {
+  return new Response(null, { status: 307, headers: { location: new URL(path, from.origin).toString(), "cache-control": "no-store", ...headers } });
+}