@tokenoftrust/storefront-runner 4.7.2 → 4.7.4

package/apps/storefront/src/components/content/storefront/content/ContactForm.astro

@@ -0,0 +1,206 @@
+---
+/**
+ * <ContactForm> — the `contact_form` page section. Email and message are always
+ * shown and required; `fields` adds optional name/phone. Submissions go to the
+ * platform-owned JSON endpoint (contract: lib/engagement/contact/contract.ts), so
+ * the section carries copy only: no recipient, endpoint or script prop.
+ *
+ * The endpoint is JSON-only, so a plain HTML post cannot reach it. The form is
+ * therefore revealed by script, and visitors without JS see an explanatory note
+ * instead of a submit button that cannot work.
+ *
+ * The endpoint is api-base-scoped (`apiBasePath`, never `basePath`, which a
+ * preview/candidate pin overrides with a render prefix that has no `/api` mirror).
+ */
+import type { ProseContactFormSection } from "@/lib/content/prose";
+import { withBase } from "@/lib/publication/shared/basePath";
+import { CONTACT_LIMITS } from "@/lib/engagement/contact/contract";
+
+interface Props {
+  section: ProseContactFormSection;
+  /** Distinguishes ids when several forms share a page. */
+  index?: number;
+}
+const { section, index = 0 } = Astro.props;
+const { apiBasePath } = Astro.locals;
+const endpoint = withBase(apiBasePath ?? "", "/api/contact");
+const id = `contact-form-${index}`;
+const fields = section.fields ?? [];
+const messageLabel = section.messageLabel ?? "How can we help?";
+const submitLabel = section.submitLabel ?? "Send message";
+const successMessage = section.successMessage ?? "Thanks. Your message is on its way.";
+---
+<section
+  class="contact-form"
+  data-contact-form
+  data-endpoint={endpoint}
+  data-success={successMessage}
+  aria-labelledby={section.heading ? `${id}-heading` : undefined}
+>
+  {section.heading && <h2 id={`${id}-heading`} class="contact-form__heading">{section.heading}</h2>}
+  <noscript>
+    <p class="contact-form__note">This contact form needs JavaScript. Enable it and reload, or use the contact details on this page.</p>
+  </noscript>
+  <form hidden novalidate data-contact-form-el>
+    {fields.includes("name") && (
+      <div class="contact-form__field">
+        <label for={`${id}-name`}>Name</label>
+        <input id={`${id}-name`} name="name" type="text" autocomplete="name" maxlength={CONTACT_LIMITS.name} />
+      </div>
+    )}
+    <div class="contact-form__field">
+      <label for={`${id}-email`}>Email</label>
+      <input id={`${id}-email`} name="email" type="email" inputmode="email" autocomplete="email" required maxlength={CONTACT_LIMITS.email} />
+    </div>
+    {fields.includes("phone") && (
+      <div class="contact-form__field">
+        <label for={`${id}-phone`}>Phone</label>
+        <input id={`${id}-phone`} name="phone" type="tel" inputmode="tel" autocomplete="tel" maxlength={CONTACT_LIMITS.phone} />
+      </div>
+    )}
+    <div class="contact-form__field">
+      <label for={`${id}-message`}>{messageLabel}</label>
+      <textarea id={`${id}-message`} name="message" rows="6" required maxlength={CONTACT_LIMITS.message}></textarea>
+    </div>
+    <div class="contact-form__trap" aria-hidden="true">
+      <input name="company" type="text" tabindex="-1" autocomplete="off" />
+    </div>
+    <button type="submit" class="contact-form__submit">{submitLabel}</button>
+  </form>
+  <p class="contact-form__status" role="status" aria-live="polite" data-contact-form-status></p>
+</section>
+
+<style>
+  .contact-form { margin-top: 1.5rem; }
+  .contact-form__heading { font-family: var(--font-display, inherit); font-size: var(--heading-h2, 1.5rem); font-weight: 600; }
+  .contact-form__field { display: flex; flex-direction: column; gap: 0.35rem; margin-top: 1rem; }
+  .contact-form__field label { font-weight: 600; }
+  .contact-form__field input,
+  .contact-form__field textarea {
+    width: 100%;
+    padding: 0.65rem 0.8rem;
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-md, 0.375rem);
+    background: var(--color-surface);
+    color: var(--color-text);
+    font: inherit;
+  }
+  .contact-form__field input[aria-invalid="true"],
+  .contact-form__field textarea[aria-invalid="true"] { border-color: var(--color-danger, currentColor); }
+  .contact-form__field input:focus-visible,
+  .contact-form__field textarea:focus-visible { outline: 2px solid var(--color-accent); outline-offset: 2px; }
+  .contact-form__trap { position: absolute; left: -10000px; width: 1px; height: 1px; overflow: hidden; }
+  .contact-form__submit {
+    margin-top: 1.25rem;
+    min-height: var(--tap-target, 44px);
+    padding: 0.65rem 1.4rem;
+    border: 0;
+    border-radius: var(--radius-md, 0.375rem);
+    background: var(--color-accent);
+    color: var(--color-accent-contrast, var(--color-primary-contrast));
+    font: inherit;
+    font-weight: 700;
+    cursor: pointer;
+  }
+  .contact-form__submit[disabled] { opacity: 0.6; cursor: progress; }
+  .contact-form__status { margin-top: 1rem; min-height: 1.5em; color: var(--color-text); }
+  .contact-form__status[data-state="error"] { color: var(--color-danger, var(--color-text)); font-weight: 600; }
+  .contact-form__note { color: var(--color-muted); }
+</style>
+
+<script>
+  import {
+    CONTACT_TOKEN_MAX_AGE_MS,
+    CONTACT_TOKEN_MIN_AGE_MS,
+    fetchContactToken,
+    submitContactMessage,
+    type ContactErrorCode,
+    type ContactField,
+  } from "@/lib/engagement/contact/contract";
+
+  const MESSAGES: Partial<Record<ContactErrorCode, string>> = {
+    rate_limited: "You have sent a few messages already. Wait a minute and try again.",
+    invalid_input: "Please check the highlighted field and try again.",
+    unavailable: "Messages can't be received right now. Your text is still here; try again shortly.",
+    store_failed: "We couldn't save your message. Your text is still here; try again.",
+    too_large: "That message is too long. Shorten it and try again.",
+  };
+  const GENERIC = "Something went wrong. Your text is still here; try again.";
+  const wait = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+  function setup(root: HTMLElement) {
+    const form = root.querySelector<HTMLFormElement>("[data-contact-form-el]");
+    const status = root.querySelector<HTMLElement>("[data-contact-form-status]");
+    const endpoint = root.dataset.endpoint;
+    if (!form || !status || !endpoint) return;
+    // The wire contract appends /api/contact itself; hand it the api base.
+    const apiBase = endpoint.replace(/\/api\/contact$/, "");
+    const say = (text: string, state: "ok" | "error" | "") => {
+      status.textContent = text;
+      status.dataset.state = state;
+    };
+    let token: { value: string; at: number } | null = null;
+    const loadToken = async () => {
+      token = { value: await fetchContactToken(apiBase), at: Date.now() };
+    };
+    const ready = loadToken();
+    form.hidden = false;
+    ready.catch(() => say("Messages can't be received right now. Try again shortly.", "error"));
+
+    form.addEventListener("submit", async (e) => {
+      e.preventDefault();
+      const button = form.querySelector<HTMLButtonElement>("button[type=submit]");
+      const value = (name: string) =>
+        (form.elements.namedItem(name) as HTMLInputElement | null)?.value.trim() ?? "";
+      form.querySelectorAll("[aria-invalid]").forEach((el) => el.removeAttribute("aria-invalid"));
+      const flag = (field: ContactField) => {
+        const el = form.elements.namedItem(field) as HTMLElement | null;
+        el?.setAttribute("aria-invalid", "true");
+        el?.focus();
+      };
+      if (!value("email") || !/^\S+@\S+$/.test(value("email"))) {
+        flag("email");
+        return say("Enter a valid email address.", "error");
+      }
+      if (!value("message")) {
+        flag("message");
+        return say("Enter a message.", "error");
+      }
+      if (button) button.disabled = true;
+      say("Sending...", "");
+      try {
+        if (!token || Date.now() - token.at > CONTACT_TOKEN_MAX_AGE_MS - 60_000) await loadToken();
+        const age = Date.now() - token!.at;
+        if (age < CONTACT_TOKEN_MIN_AGE_MS) await wait(CONTACT_TOKEN_MIN_AGE_MS - age + 100);
+        const name = value("name");
+        const phone = value("phone");
+        const result = await submitContactMessage(apiBase, {
+          token: token!.value,
+          ...(name ? { name } : {}),
+          email: value("email"),
+          ...(phone ? { phone } : {}),
+          message: value("message"),
+          company: (form.elements.namedItem("company") as HTMLInputElement | null)?.value ?? "",
+        });
+        if (result.body.ok) {
+          form.reset();
+          token = null;
+          say(root.dataset.success ?? "Thanks. Your message is on its way.", "ok");
+          loadToken().catch(() => {});
+          return;
+        }
+        const code = result.body.error;
+        if (code === "invalid_token" || code === "forbidden_origin") token = null;
+        if (result.body.field) flag(result.body.field);
+        say(MESSAGES[code] ?? GENERIC, "error");
+        if (!token) loadToken().catch(() => {});
+      } catch {
+        say(GENERIC, "error");
+      } finally {
+        if (button) button.disabled = false;
+      }
+    });
+  }
+
+  document.querySelectorAll<HTMLElement>("[data-contact-form]").forEach(setup);
+</script>

package/apps/storefront/src/components/content/storefront/content/ProseSections.astro

@@ -16,6 +16,7 @@ import type { ProseSection } from "@/lib/content/prose";
 import { normalizeProse, withHeadingIds } from "@/lib/content/prose";
 import RichText from "@/components/content/storefront/content/RichText.astro";
 import Callout from "@/components/content/storefront/content/Callout.astro";
+import ContactForm from "@/components/content/storefront/content/ContactForm.astro";
 import NeedsReviewCallout from "@/components/content/storefront/content/NeedsReviewCallout.astro";
 
 interface Props {
@@ -28,7 +29,7 @@ const rendered = withHeadingIds(normalizeProse(sections));
 ---
 <div class="prose-sections max-w-[68ch] text-[var(--color-text)]" data-widget="prose-sections">
   {
-    rendered.map((s) => {
+    rendered.map((s, i) => {
       switch (s.kind) {
         case "heading":
           return (s.level ?? 2) === 3 ? (
@@ -109,6 +110,8 @@ const rendered = withHeadingIds(normalizeProse(sections));
               )}
             </address>
           );
+        case "contact_form":
+          return <ContactForm section={s} index={i} />;
         case "needs_review":
           return includeNeedsReview ? (
             <NeedsReviewCallout flag={{ reason: s.reason, severity: s.severity, owner: s.owner, href: s.href }} />

package/apps/storefront/src/lib/content/prose.ts

@@ -65,6 +65,20 @@ export interface ProseContactSection {
   address?: string[];
 }
 
+/**
+ * A working contact form. Email and message are always shown and required;
+ * `fields` adds the optional name/phone inputs. The destination, endpoint and
+ * script are platform-owned: this section carries copy only.
+ */
+export interface ProseContactFormSection {
+  kind: "contact_form";
+  heading?: string;
+  fields?: ("name" | "phone")[];
+  messageLabel?: string;
+  submitLabel?: string;
+  successMessage?: string;
+}
+
 /** A needs-review flag embedded in the flow (see needsReview.ts). */
 export type ProseNeedsReviewSection = { kind: "needs_review" } & NeedsReview;
 
@@ -75,6 +89,7 @@ export type ProseSection =
   | ProseDefinitionsSection
   | ProseCalloutSection
   | ProseContactSection
+  | ProseContactFormSection
   | ProseNeedsReviewSection;
 
 /** A full structured page (policy / about / compliance). */
@@ -129,6 +144,9 @@ export function normalizeProse(
       case "contact":
         if (s.email || s.phone || (s.address && s.address.length)) out.push(s);
         break;
+      case "contact_form":
+        out.push(normalizeContactForm(s));
+        break;
       case "needs_review":
         if (s.reason.trim()) out.push(s);
         break;
@@ -137,6 +155,28 @@ export function normalizeProse(
   return out;
 }
 
+const copy = (v: unknown): string | undefined =>
+  typeof v === "string" && v.trim() ? v.trim() : undefined;
+
+/** Rebuild from the known copy props only: unknown props (a recipient, an endpoint) never survive. */
+function normalizeContactForm(s: ProseContactFormSection): ProseContactFormSection {
+  const raw: unknown = s.fields;
+  const fields = (["name", "phone"] as const).filter(
+    (f) => Array.isArray(raw) && raw.includes(f),
+  );
+  const out: ProseContactFormSection = { kind: "contact_form" };
+  const heading = copy(s.heading);
+  const messageLabel = copy(s.messageLabel);
+  const submitLabel = copy(s.submitLabel);
+  const successMessage = copy(s.successMessage);
+  if (heading) out.heading = heading;
+  if (fields.length) out.fields = [...fields];
+  if (messageLabel) out.messageLabel = messageLabel;
+  if (submitLabel) out.submitLabel = submitLabel;
+  if (successMessage) out.successMessage = successMessage;
+  return out;
+}
+
 /** Fill in a derived `id` for every heading that lacks one (for TOC anchoring). */
 export function withHeadingIds(
   sections: ReadonlyArray<ProseSection>,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "4.7.2",
+  "version": "4.7.4",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/cli/src/visual-parity.mjs

@@ -255,8 +255,9 @@ function pageShape(value, file) {
       case "definitions": if (!Array.isArray(section.items) || !section.items.length || section.items.some((item) => !item || !string(item.term) || !rich(item.description))) findings.push(finding("parity-section-shape", at, "definitions require string terms and RichText descriptions", "supply valid definition items")); break;
       case "callout": if (!rich(section.body) || !["info", "warning", "legal", "success"].includes(section.tone) || section.title !== undefined && !string(section.title)) findings.push(finding("parity-section-shape", at, "callout requires supported tone, RichText body, and optional string title", "supply a valid callout")); break;
       case "contact": if (section.heading !== undefined && !string(section.heading) || section.email !== undefined && !string(section.email) || section.phone !== undefined && !string(section.phone) || section.address !== undefined && (!Array.isArray(section.address) || section.address.some((line) => !string(line))) || !string(section.email) && !string(section.phone) && !(Array.isArray(section.address) && section.address.length)) findings.push(finding("parity-section-shape", at, "contact requires string members and email, phone, or address", "supply valid contact details")); break;
+      case "contact_form": if (["heading", "messageLabel", "submitLabel", "successMessage"].some((key) => section[key] !== undefined && !string(section[key])) || section.fields !== undefined && (!Array.isArray(section.fields) || section.fields.some((field) => field !== "name" && field !== "phone"))) findings.push(finding("parity-section-shape", at, "contact_form requires optional string copy and fields limited to name or phone", "supply a valid contact_form section")); break;
       case "needs_review": if (!string(section.reason) || section.severity !== undefined && !["blocker", "note"].includes(section.severity) || section.owner !== undefined && !string(section.owner) || section.href !== undefined && !string(section.href)) findings.push(finding("parity-section-shape", at, "needs_review requires reason and valid optional severity/owner/href", "supply a valid needs_review section")); break;
-      default: findings.push(finding("parity-section-kind", `${at}/kind`, "section kind is not supported by the renderer", "use heading, paragraph, list, definitions, callout, contact, or needs_review"));
+      default: findings.push(finding("parity-section-kind", `${at}/kind`, "section kind is not supported by the renderer", "use heading, paragraph, list, definitions, callout, contact, contact_form, or needs_review"));
     }
   });
   const bodyHtml = typeof value.body_html === "string" && value.body_html.trim() !== "";

package/packages/public-runtime/src/integration/lifecycle-boot.ts

@@ -5,7 +5,8 @@
  * the renderer-published boot descriptor global, guarantees ONE lifecycle per document
  * with a window-level singleton (so a nested layout that re-runs the boot island cannot
  * double-init), wires same-document navigations to the reserved completed-navigation
- * event, disposes on document teardown, and is a guarded no-op off the browser.
+ * event, disposes on every `pagehide`, boots a fresh lifecycle when the back-forward
+ * cache restores the page, and is a guarded no-op off the browser.
  *
  * The entry module for each integration is the same-origin, exact-version asset the
  * boot descriptor carries (`integration.entry.url`): the default loader dynamically
@@ -440,20 +441,38 @@ function deferFetchCapability(
     })) as typeof fetch;
 }
 
+/** The window property marking that this window's event wiring is installed (once per window). */
+const LIFECYCLE_WIRED_GLOBAL = "__TOT_INTEGRATION_LIFECYCLE_WIRED__";
+
 /**
- * Boot the lifecycle for `win` exactly once. A second call returns the same instance
- * (nested-layout safety). Returns `null` when there is no boot descriptor to act on.
+ * Boot the lifecycle for `win`. While a live lifecycle exists a second call returns it
+ * (nested-layout safety). A disposed one — the page was hidden into the back-forward
+ * cache — is replaced by a fresh lifecycle. Returns `null` when there is no boot
+ * descriptor to act on.
  */
 export function bootIntegrationLifecycle(
   win: LifecycleWindow,
   options: BootLifecycleOptions = {},
 ): IntegrationLifecycle | null {
   const existing = win[LIFECYCLE_SINGLETON_GLOBAL];
-  if (existing instanceof IntegrationLifecycle) return existing;
+  if (existing instanceof IntegrationLifecycle && !existing.isDisposed) return existing;
 
   const descriptor = readDescriptor(win);
   if (!descriptor) return null;
 
+  const lifecycle = createDocumentLifecycle(win, descriptor, options);
+  win[LIFECYCLE_SINGLETON_GLOBAL] = lifecycle;
+  wireWindow(win, options);
+  void lifecycle.init();
+  return lifecycle;
+}
+
+function createDocumentLifecycle(
+  win: LifecycleWindow,
+  descriptor: IntegrationBootDescriptor,
+  options: BootLifecycleOptions,
+): IntegrationLifecycle {
+
   const hostFetch = options.fetchCapability ??
     (typeof win.fetch === "function" ? win.fetch.bind(win) : undefined);
   const schedulePlatformAdapterStart =
@@ -508,7 +527,7 @@ export function bootIntegrationLifecycle(
   // The managed-analytics bridge over the SAME broker the adapters subscribe to — the
   // only seam that emits this document's governed page view. The lifecycle owns when it
   // fires (after every adapter has subscribed, and re-attempted on a consent grant).
-  const lifecycle = new IntegrationLifecycle({
+  return new IntegrationLifecycle({
     descriptor,
     loadModule,
     isEligible,
@@ -536,39 +555,48 @@ export function bootIntegrationLifecycle(
       pageView: () => documentPageView(win, descriptor, options.now ?? Date.now),
     },
   });
-  win[LIFECYCLE_SINGLETON_GLOBAL] = lifecycle;
+}
 
-  wireNavigation(win, lifecycle);
-  wireTeardown(win, lifecycle);
-  void lifecycle.init();
-  return lifecycle;
+/** The window's current live lifecycle, if any. */
+function liveLifecycle(win: LifecycleWindow): IntegrationLifecycle | undefined {
+  const current = win[LIFECYCLE_SINGLETON_GLOBAL];
+  return current instanceof IntegrationLifecycle && !current.isDisposed ? current : undefined;
 }
 
 /**
- * Wire same-document navigations to the reserved completed-navigation event. In a
- * traditional MPA a real document load re-inits by construction, so only the two
- * navigations that DON'T reload the document — hash changes and history back/forward —
- * need a completed-navigation signal, and neither re-initializes integrations.
+ * Install this window's event wiring once; every listener acts on the CURRENT lifecycle.
+ *
+ * Same-document navigations — hash changes and history back/forward — emit the reserved
+ * completed-navigation event and never re-initialize integrations; a real document load
+ * re-inits by construction.
+ *
+ * Every `pagehide` disposes the lifecycle, so integrations clean up and abandon any
+ * deferred work (a held navigation never resumes after the shopper left). A
+ * `pageshow` from the back-forward cache boots a fresh lifecycle, so the restored page
+ * has live integrations again.
  */
-function wireNavigation(win: LifecycleWindow, lifecycle: IntegrationLifecycle): void {
+function wireWindow(win: LifecycleWindow, options: BootLifecycleOptions): void {
+  if (win[LIFECYCLE_WIRED_GLOBAL] === true) return;
+  win[LIFECYCLE_WIRED_GLOBAL] = true;
   let lastPath = win.location.pathname + win.location.hash;
   win.addEventListener("hashchange", () => {
     const to = win.location.pathname + win.location.hash;
-    lifecycle.notifyNavigationCompleted({ from: lastPath, to, kind: "hash" });
+    liveLifecycle(win)?.notifyNavigationCompleted({ from: lastPath, to, kind: "hash" });
     lastPath = to;
   });
   win.addEventListener("popstate", () => {
     const to = win.location.pathname + win.location.hash;
     const kind: NavigationKind = "back-forward";
-    lifecycle.notifyNavigationCompleted({ from: lastPath, to, kind });
+    liveLifecycle(win)?.notifyNavigationCompleted({ from: lastPath, to, kind });
     lastPath = to;
   });
-}
-
-/** Dispose the lifecycle when the document is torn down, so integrations clean up once. */
-function wireTeardown(win: LifecycleWindow, lifecycle: IntegrationLifecycle): void {
   win.addEventListener("pagehide", () => {
-    void lifecycle.dispose();
+    const current = win[LIFECYCLE_SINGLETON_GLOBAL];
+    if (current instanceof IntegrationLifecycle) void current.dispose();
+  });
+  win.addEventListener("pageshow", (event) => {
+    if ((event as { persisted?: unknown } | null)?.persisted !== true) return;
+    bootIntegrationLifecycle(win, options);
   });
 }
 

package/packages/public-runtime/src/integration/lifecycle-runtime.ts

@@ -224,6 +224,11 @@ export class IntegrationLifecycle {
     return this.state === "initialized";
   }
 
+  /** True once dispose has started; a disposed lifecycle never runs again. */
+  get isDisposed(): boolean {
+    return this.isTerminal();
+  }
+
   /**
    * Initialize every integration EXACTLY ONCE per document, in the plan's resolved order.
    * A second call — including one from a nested layout that re-runs the boot island — is a