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

package/src/visual-bridge.tsx

@@ -0,0 +1,30 @@
+import { getCopyUntagged } from "./data";
+import { KIT_VERSION } from "./version";
+import { VisualBridge } from "./visual-bridge-client";
+import { copyTexts, type CopyText } from "./visual-match";
+import { visualMode } from "./visual-mode";
+
+/**
+ * Put once inside <body> in app/layout.tsx, inside a Suspense boundary:
+ *
+ *   <Suspense fallback={null}><VisualEditing /></Suspense>
+ *
+ * Renders nothing unless this browser opened the page from Site Manager's Visual Editor. Then it outlines the values
+ * Site Manager stores and passes clicks and edits to Site Manager, which saves them as drafts.
+ *
+ * Site Copy read through getCopy() carries exact tags in visual mode, so a site needs no marks of its own. Values a
+ * site reads some other way are found by their words; `autoMark={false}` turns that off for a site that marks every
+ * value itself with editMarks().
+ */
+export async function VisualEditing({ autoMark = true }: { autoMark?: boolean } = {}) {
+  try {
+    const ok = await visualMode();
+    if (!ok) return null;
+    // Untagged words for matching values a site reads some other way; values read through getCopy() carry exact tags.
+    let copy: CopyText[] = [];
+    if (autoMark) copy = copyTexts(await getCopyUntagged().catch(() => ({})));
+    return <VisualBridge adminOrigin={ok.adminOrigin} kit={KIT_VERSION} copy={copy} />;
+  } catch {
+    return null;
+  }
+}

package/src/visual-clicks.ts

@@ -0,0 +1,13 @@
+/*
+ * In Edit mode the page's links, buttons and forms don't act: a click selects the words, it never follows a link or
+ * submits a form. Browse mode lets them act. Pure, so it's checked without a browser.
+ */
+
+export const ACTIVATES =
+  'a[href], button, input[type="submit"], input[type="image"], input[type="reset"], input[type="button"], [role="link"], [role="button"], summary';
+
+/** True when a click, Enter or Space on this target would follow a link, press a button or submit a form. */
+export function blocksActivation(target: unknown): boolean {
+  const el = target as { closest?: (selector: string) => unknown } | null;
+  return !!el && typeof el.closest === "function" && !!el.closest(ACTIVATES);
+}

package/src/visual-lists.ts

@@ -0,0 +1,37 @@
+/*
+ * List controls in the Visual Editor: small Move Up, Move Down, Remove and Add buttons on an item of a list the site
+ * lets Site Manager reorder or resize (copy list rules, kit 1.26.0). Site Manager says which lists are on the page and
+ * which values each item holds; the page only finds where each item is and shows the buttons. Every change is made
+ * and saved by Site Manager.
+ */
+
+export type ListAction = "up" | "down" | "remove" | "add";
+export type PageListItem = { refs: string[] };
+export type PageList = { path: string; reorder: boolean; addRemove: boolean; shown: number; items: PageListItem[] };
+
+/** The buttons an item gets: by the list's rules, its place, and whether the list has room for another item. */
+export function actionsFor(list: PageList, index: number): ListAction[] {
+  const out: ListAction[] = [];
+  const count = Math.min(list.shown, list.items.length);
+  if (index >= count) return out;
+  if (list.reorder && index > 0) out.push("up");
+  if (list.reorder && index < count - 1) out.push("down");
+  if (list.addRemove && count > 1) out.push("remove");
+  if (list.addRemove && count < list.items.length) out.push("add");
+  return out;
+}
+
+type Containing = { contains(other: Containing | null): boolean; parentElement: Containing | null };
+
+/**
+ * The element that is an item: the nearest one holding every place its values show and none of another item's.
+ * Null when no such element exists (the values are spread among other items' elements).
+ */
+export function itemElement<E extends Containing>(mine: E[], others: E[]): E | null {
+  if (!mine.length) return null;
+  for (let el: E | null = mine[0]!; el; el = el.parentElement as E | null) {
+    if (!mine.every((m) => el!.contains(m))) continue;
+    return others.some((o) => el!.contains(o)) ? null : el;
+  }
+  return null;
+}

package/src/visual-match.ts

@@ -0,0 +1,77 @@
+/*
+ * Automatic marks for the Visual Editor. In visual mode the bridge gets the site's Site Copy text (drafts included,
+ * so it matches what the page shows) and marks the elements and text nodes on the page whose words are exactly one
+ * value. Sites then need no marks of their own; marks a site does add with editMarks() always win.
+ *
+ * Pure functions here, so they can be tested without a browser; the bridge walks the page with them.
+ */
+
+import type { CopyValue } from "./types";
+
+/** One Site Copy value the bridge can look for: its key, its words as plain text, and the page it belongs to. */
+export type CopyText = { k: string; t: string; p: string | null };
+
+// Shorter values ("Yes", "OK") are too likely to match words that aren't that value.
+const MIN_CHARS = 3;
+
+const ENTITIES: Record<string, string> = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " " };
+
+function decode(s: string): string {
+  return s.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (whole, e: string) => {
+    if (e[0] === "#") {
+      const n = e[1] === "x" || e[1] === "X" ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10);
+      return Number.isFinite(n) && n > 0 && n <= 0x10ffff ? String.fromCodePoint(n) : whole;
+    }
+    return ENTITIES[e.toLowerCase()] ?? whole;
+  });
+}
+
+/** Rich text's words as the page shows them: tags dropped, entities read. */
+export function htmlText(html: string): string {
+  return decode(html.replace(/<(script|style)[\s\S]*?<\/\1>/gi, "").replace(/<[^>]*>/g, " "));
+}
+
+/**
+ * The form words are compared in. All whitespace is dropped, since the page and the stored value break lines and
+ * space blocks differently (rich text's paragraphs have no space between them in the page's text).
+ */
+export const comparable = (s: string): string => s.replace(/[\s ​]+/g, "");
+
+/** The text and rich values of getCopy(), ready to send to the bridge. Photos, links and record picks aren't words on the page. */
+export function copyTexts(all: Record<string, CopyValue>): CopyText[] {
+  const out: CopyText[] = [];
+  for (const [k, v] of Object.entries(all)) {
+    const t = v.kind === "text" ? v.text : v.kind === "rich" ? (v.html ? htmlText(v.html) : null) : null;
+    if (t && comparable(t).length >= MIN_CHARS) out.push({ k, t, p: v.pagePath ?? null });
+  }
+  return out;
+}
+
+const trimPath = (p: string) => (p.length > 1 ? p.replace(/\/+$/, "") : p);
+
+/**
+ * Words to ref, for one page. Only values that belong to this page or to no page (header, footer, site-wide wording)
+ * count: another page's value with the same words (a nav label that matches a page's eyebrow) is a different value.
+ * Where the same words are more than one value, this page's wins over a site-wide one; still more than one at that
+ * level, the words are left unmarked, since there is no telling which one this is.
+ */
+export function matchIndex(values: CopyText[], path: string): Map<string, string> {
+  const here = trimPath(path);
+  const best = new Map<string, { tier: number; ref: string | null }>();
+  for (const v of values) {
+    const words = comparable(v.t);
+    if (words.length < MIN_CHARS) continue;
+    const tier = v.p === null ? 1 : trimPath(v.p) === here ? 0 : -1;
+    if (tier < 0) continue;
+    const ref = `copy/${v.k}`;
+    const seen = best.get(words);
+    if (!seen || tier < seen.tier) best.set(words, { tier, ref });
+    else if (tier === seen.tier && seen.ref !== ref) seen.ref = null;
+  }
+  const out = new Map<string, string>();
+  for (const [words, { ref }] of best) if (ref) out.set(words, ref);
+  return out;
+}
+
+/** The longest words in the index, so the walk can skip comparing anything longer. */
+export const longest = (index: Map<string, string>): number => Math.max(0, ...Array.from(index.keys(), (k) => k.length));

package/src/visual-messages.ts

@@ -0,0 +1,160 @@
+/*
+ * Messages between a page in visual mode and Site Manager's Visual Editor. Every message is { bp: 1, type, ...fields };
+ * anything else is dropped. Site Manager checks the same shapes in src/lib/visual/messages.ts; change both together.
+ */
+
+export const LIMITS = { ref: 200, path: 2000, text: 10000, html: 50000, refs: 500, label: 120 } as const;
+
+import type { ListAction, PageList } from "./visual-lists";
+
+export type EditMode = "inline" | "panel" | "link";
+// label: what the value is, in the words people see in Site Manager. Older Site Managers leave it out.
+export type Editable = { ref: string; mode: EditMode; maxLength?: number; label?: string };
+export type Rect = { x: number; y: number; w: number; h: number };
+
+export type KitMessage =
+  | { bp: 1; type: "ready"; kit: string; path: string; refs: string[] }
+  | { bp: 1; type: "navigated"; path: string; refs: string[] }
+  // plain: the element holds only text, so it can be edited in place.
+  | { bp: 1; type: "select"; ref: string; rect: Rect; plain: boolean }
+  // html: a formatted value edited in place; Site Manager sanitizes it before saving.
+  | { bp: 1; type: "commit"; ref: string; text: string; html?: string; accents?: [number, number][]; strong?: [number, number][]; em?: [number, number][] }
+  | { bp: 1; type: "cancel"; ref: string }
+  // The words of an edit in place so far, so Site Manager can check them while they're typed.
+  | { bp: 1; type: "typing"; ref: string; text: string }
+  // Ctrl+Z or Ctrl+Shift+Z (Ctrl+Y) pressed in the page while nothing is being typed.
+  | { bp: 1; type: "key"; key: "undo" | "redo" }
+  // The person asked to edit this value in Site Manager's side panel instead (the expand button on the editing bar).
+  | { bp: 1; type: "expand"; ref: string }
+  // A list button on an item was pressed. Site Manager makes and saves the change.
+  | { bp: 1; type: "listAction"; path: string; index: number; action: ListAction };
+
+export type AdminMessage =
+  | { bp: 1; type: "hello"; editable: Editable[] }
+  | { bp: 1; type: "mode"; editing: boolean }
+  | { bp: 1; type: "inline"; ref: string; maxLength: number }
+  // Edit a formatted value (rich text) in place, with a small Bold, Italic and Link bar.
+  | { bp: 1; type: "inlineRich"; ref: string }
+  // Edit a heading in place with an Accent button for its gold words: its words and ranges as stored.
+  // strong and marks (1.37.0): the words marked Bold, and which of Accent and Bold the value offers (both when left out).
+  // em (1.40.0): the words marked Italic.
+  | { bp: 1; type: "inlineHeading"; ref: string; maxLength: number; text: string; accents: [number, number][]; strong?: [number, number][]; em?: [number, number][]; marks?: ("accent" | "strong" | "em")[] }
+  | { bp: 1; type: "refresh" }
+  | { bp: 1; type: "navigate"; path: string }
+  | { bp: 1; type: "focus"; ref: string }
+  // The words typed so far in the side panel, shown on the page unsaved; null puts the original words back.
+  | { bp: 1; type: "preview"; ref: string; text: string | null }
+  // A value was saved as a draft with these words, which the page already shows: keep them, no refresh needed.
+  | { bp: 1; type: "saved"; ref: string; text: string }
+  // The values on this page with unsaved drafts, marked with a small dot.
+  | { bp: 1; type: "drafts"; refs: string[] }
+  // The lists on this page that can be reordered or resized, and the values each item holds.
+  | { bp: 1; type: "lists"; lists: PageList[] }
+  // A photo chosen in the side panel, shown in place of the value's photo, unsaved; null puts the photo back.
+  | { bp: 1; type: "previewImage"; ref: string; url: string | null };
+
+const str = (v: unknown, max: number): v is string => typeof v === "string" && v.length > 0 && v.length <= max;
+const count = (v: unknown): v is number => typeof v === "number" && Number.isInteger(v) && v > 0 && v <= LIMITS.text;
+const MODES: readonly unknown[] = ["inline", "panel", "link"];
+
+function isEditable(v: unknown): v is Editable {
+  if (!v || typeof v !== "object") return false;
+  const e = v as Record<string, unknown>;
+  return (
+    str(e.ref, LIMITS.ref) &&
+    MODES.includes(e.mode) &&
+    (e.maxLength === undefined || count(e.maxLength)) &&
+    (e.label === undefined || str(e.label, LIMITS.label))
+  );
+}
+
+function isPageList(v: unknown): v is PageList {
+  if (!v || typeof v !== "object") return false;
+  const l = v as Record<string, unknown>;
+  return (
+    str(l.path, LIMITS.ref) &&
+    typeof l.reorder === "boolean" &&
+    typeof l.addRemove === "boolean" &&
+    typeof l.shown === "number" &&
+    Number.isInteger(l.shown) &&
+    l.shown >= 0 &&
+    Array.isArray(l.items) &&
+    l.items.length <= 50 &&
+    l.items.every((i) => {
+      const refs = (i as { refs?: unknown } | null)?.refs;
+      return Array.isArray(refs) && refs.length <= 50 && refs.every((r) => str(r, LIMITS.ref));
+    })
+  );
+}
+
+const ranges = (v: unknown) =>
+  Array.isArray(v) && v.length <= 50 && v.every((a) => Array.isArray(a) && a.length === 2 && a.every((n) => Number.isInteger(n) && n >= 0 && n <= LIMITS.text));
+
+/** True only for a well formed message from Site Manager. */
+export function isAdminMessage(data: unknown): data is AdminMessage {
+  if (!data || typeof data !== "object") return false;
+  const m = data as Record<string, unknown>;
+  if (m.bp !== 1) return false;
+  switch (m.type) {
+    case "hello":
+      return Array.isArray(m.editable) && m.editable.length <= LIMITS.refs && m.editable.every(isEditable);
+    case "mode":
+      return typeof m.editing === "boolean";
+    case "inline":
+      return str(m.ref, LIMITS.ref) && count(m.maxLength);
+    case "inlineRich":
+      return str(m.ref, LIMITS.ref);
+    case "inlineHeading":
+      return (
+        str(m.ref, LIMITS.ref) &&
+        count(m.maxLength) &&
+        typeof m.text === "string" &&
+        m.text.length <= LIMITS.text &&
+        Array.isArray(m.accents) &&
+        m.accents.length <= 50 &&
+        ranges(m.accents) &&
+        (m.strong === undefined || ranges(m.strong)) &&
+        (m.em === undefined || ranges(m.em)) &&
+        (m.marks === undefined || (Array.isArray(m.marks) && m.marks.length <= 3 && m.marks.every((k) => k === "accent" || k === "strong" || k === "em")))
+      );
+    case "refresh":
+      return true;
+    case "navigate":
+      return str(m.path, LIMITS.path) && m.path.startsWith("/") && !m.path.startsWith("//") && !m.path.includes("\\");
+    case "focus":
+      return str(m.ref, LIMITS.ref);
+    case "saved":
+      return str(m.ref, LIMITS.ref) && typeof m.text === "string" && m.text.length <= LIMITS.text;
+    case "drafts":
+      return Array.isArray(m.refs) && m.refs.length <= LIMITS.refs && m.refs.every((r) => str(r, LIMITS.ref));
+    case "previewImage":
+      // Only an address a page can load: https, or a path on the site.
+      return str(m.ref, LIMITS.ref) && (m.url === null || (str(m.url, LIMITS.path) && /^(https:\/\/|\/(?!\/))/.test(m.url)));
+    case "lists":
+      return Array.isArray(m.lists) && m.lists.length <= 50 && m.lists.every(isPageList);
+    case "preview":
+      // An empty string is allowed: someone cleared the box.
+      return str(m.ref, LIMITS.ref) && (m.text === null || (typeof m.text === "string" && m.text.length <= LIMITS.text));
+    default:
+      return false;
+  }
+}
+
+/**
+ * The one check every message from Site Manager goes through: from the window that showed the page, at the signed
+ * admin origin, well formed. Anything else (another frame, another origin, a forged shape) is null.
+ */
+export function adminMessageFrom(e: { source: unknown; origin: string; data: unknown }, from: unknown, adminOrigin: string): AdminMessage | null {
+  if (!from || e.source !== from || e.origin !== adminOrigin) return null;
+  return isAdminMessage(e.data) ? e.data : null;
+}
+
+/** The marked refs on the page: unique, in page order, at most 500. */
+export function collectRefs(values: Iterable<string | null>): string[] {
+  const out = new Set<string>();
+  for (const v of values) {
+    if (out.size >= LIMITS.refs) break;
+    if (v && v.length <= LIMITS.ref) out.add(v);
+  }
+  return [...out];
+}

package/src/visual-mode.ts

@@ -0,0 +1,18 @@
+import { cookies, draftMode } from "next/headers";
+import { verifyVisualCookie, VISUAL_COOKIE } from "./preview";
+
+/**
+ * The signed admin origin when this request comes from Site Manager's Visual Editor, else null. Cookies are read only
+ * once draft mode is on, so a visitor's page never becomes dynamic because of this check.
+ */
+export async function visualMode(): Promise<{ adminOrigin: string } | null> {
+  try {
+    if (!(await draftMode()).isEnabled) return null;
+    const id = process.env.BLUEPRINT_SITE_ID?.trim();
+    if (!id) return null;
+    const ok = verifyVisualCookie(process.env.BLUEPRINT_REVALIDATE_SECRET, (await cookies()).get(VISUAL_COOKIE)?.value, id);
+    return ok ? { adminOrigin: ok.adminOrigin } : null;
+  } catch {
+    return null;
+  }
+}

package/src/visual-preview.ts

@@ -0,0 +1,69 @@
+/*
+ * Live preview in the Visual Editor: while someone types a value in Site Manager's side panel, the page shows the
+ * words in place, unsaved, so they see line breaks and overflow as they type. Only text nodes are changed, through
+ * nodeValue, so the words are never read as HTML and the elements around them (an accent span, a link) keep their
+ * styling. React keeps owning the same nodes, so a refresh after Save Draft updates them as usual.
+ */
+
+/** The part of a DOM Text node this needs, so the logic can be checked without a browser. */
+export type TextLike = { nodeValue: string | null };
+
+type Slot = { node: TextLike; before: string };
+
+const lead = (s: string) => /^\s*/.exec(s)![0];
+const trail = (s: string) => /\s*$/.exec(s)![0];
+
+export class LivePreview {
+  // Per ref, each place the value shows on the page, as the text nodes it was made of and what they said.
+  private shown = new Map<string, Slot[][]>();
+
+  /** True while any value shows unsaved words. Marking the page again waits: the words no longer match the value. */
+  get active(): boolean {
+    return this.shown.size > 0;
+  }
+
+  /**
+   * Shows text where ref is. find runs only the first time, so every keystroke changes the same nodes and the
+   * original words are kept from before the first one. False when the value has no plain text place on the page.
+   */
+  show(ref: string, text: string, find: () => TextLike[][]): boolean {
+    let places = this.shown.get(ref);
+    if (!places) {
+      places = find()
+        .map((nodes) => nodes.map((node) => ({ node, before: node.nodeValue ?? "" })))
+        .filter((slots) => slots.length > 0);
+      if (!places.length) return false;
+      this.shown.set(ref, places);
+    }
+    for (const slots of places) {
+      // The words go in the first node that had any, keeping the spaces that separated it from what's beside it.
+      let first = slots.findIndex((s) => s.before.trim() !== "");
+      if (first < 0) first = 0;
+      slots.forEach((s, i) => {
+        if (i === first) s.node.nodeValue = lead(s.before) + text.trim() + trail(s.before);
+        else if (s.before.trim() !== "") s.node.nodeValue = "";
+      });
+    }
+    return true;
+  }
+
+  /** Puts the original words back (Cancel, or the panel closed without saving). */
+  restore(ref: string): void {
+    for (const slots of this.shown.get(ref) ?? []) for (const s of slots) s.node.nodeValue = s.before;
+    this.shown.delete(ref);
+  }
+
+  restoreAll(): void {
+    for (const ref of [...this.shown.keys()]) this.restore(ref);
+  }
+
+  /** Lets go without restoring: the page is being refreshed with the saved words, or has moved on. */
+  forget(): void {
+    this.shown.clear();
+  }
+
+  /** Lets go of one value without restoring: its words were saved and stay on the page. */
+  keep(ref: string): void {
+    this.shown.delete(ref);
+  }
+}

package/src/visual-tags.ts

@@ -0,0 +1,90 @@
+/*
+ * Exact tags for the Visual Editor. In visual mode only, each Site Copy text the site reads carries an invisible tag
+ * naming its value, so the page can say exactly which words are which value instead of matching words. The tag is
+ * zero width characters: a start marker, the ref's UTF-8 bytes as base-4 digits, an end marker. The bridge removes
+ * every tag from the page before anyone sees or copies it.
+ */
+
+const DIGITS = ["​", "‌", "‍", "⁠"] as const;
+// Marker pairs no ordinary text contains: a word joiner and a zero width no-break space around the digits.
+const START = "⁠⁠";
+const END = "⁠";
+const MAX_REF = 200;
+
+const TAG = new RegExp(`${START}([${DIGITS.join("")}]+)${END}`, "g");
+const ANY_MARK = /[​‌‍⁠]/;
+
+export function encodeTag(ref: string): string {
+  const bytes = new TextEncoder().encode(ref);
+  let out = START;
+  for (const b of bytes) out += DIGITS[(b >> 6) & 3]! + DIGITS[(b >> 4) & 3]! + DIGITS[(b >> 2) & 3]! + DIGITS[b & 3]!;
+  return out + END;
+}
+
+function decode(digits: string): string | null {
+  if (digits.length % 4 !== 0) return null;
+  const bytes = new Uint8Array(digits.length / 4);
+  for (let i = 0; i < bytes.length; i++) {
+    let b = 0;
+    for (let j = 0; j < 4; j++) b = (b << 2) | DIGITS.indexOf(digits[i * 4 + j] as (typeof DIGITS)[number]);
+    bytes[i] = b;
+  }
+  try {
+    const ref = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    return ref.length > 0 && ref.length <= MAX_REF ? ref : null;
+  } catch {
+    return null;
+  }
+}
+
+/** A tag found in a string: the ref it names and where it ends in the clean text. */
+export type FoundTag = { ref: string; at: number };
+
+/** The text with its tags removed, and the tags in order. A broken tag is removed but not reported. */
+export function readTags(text: string): { clean: string; tags: FoundTag[] } {
+  if (!ANY_MARK.test(text)) return { clean: text, tags: [] };
+  const tags: FoundTag[] = [];
+  let clean = "";
+  let last = 0;
+  for (const m of text.matchAll(TAG)) {
+    clean += text.slice(last, m.index);
+    const ref = decode(m[1]!);
+    if (ref) tags.push({ ref, at: clean.length });
+    last = m.index! + m[0].length;
+  }
+  clean += text.slice(last);
+  return { clean, tags };
+}
+
+/** The text alone, for attributes and anywhere else a tag must never show. */
+export function stripTags(text: string): string {
+  return ANY_MARK.test(text) ? text.replace(TAG, "") : text;
+}
+
+/** True when the text may hold a tag; a cheap test before the full read. */
+export const mayHaveTag = (text: string) => text.includes(START);
+
+/** Puts the tag inside rich HTML's last text, before its closing tags, so it lands in the element the words are in. */
+export function tagHtml(html: string, ref: string): string {
+  const m = /(?:<\/[a-zA-Z][a-zA-Z0-9]*>\s*)+$/.exec(html);
+  const at = m ? m.index : html.length;
+  return html.slice(0, at) + encodeTag(ref) + html.slice(at);
+}
+
+type CopyLike = { kind: string; text?: string | null; html?: string | null; image?: { alt: string } | null };
+
+/**
+ * Site Copy with each non-empty text and rich value tagged as `copy/<key>`, and each photo tagged in its alt text (the
+ * one thing about a photo the page always renders). Links and picks are untouched.
+ */
+export function tagCopy<T extends CopyLike>(all: Record<string, T>): Record<string, T> {
+  const out: Record<string, T> = {};
+  for (const [key, v] of Object.entries(all)) {
+    const ref = `copy/${key}`;
+    if (v.kind === "text" && v.text) out[key] = { ...v, text: v.text + encodeTag(ref) } as T;
+    else if (v.kind === "rich" && v.html) out[key] = { ...v, html: tagHtml(v.html, ref) } as T;
+    else if (v.kind === "image" && v.image) out[key] = { ...v, image: { ...v.image, alt: (v.image.alt ?? "") + encodeTag(ref) } } as T;
+    else out[key] = v;
+  }
+  return out;
+}

package/src/visual.ts

@@ -0,0 +1,59 @@
+import { draftMode } from "next/headers";
+import type { NextRequest, NextResponse } from "next/server";
+import { verifyVisualCookie, VISUAL_COOKIE } from "./preview";
+
+/*
+ * Marking values for Site Manager's Visual Editor. A marked element is a value Site Manager already stores; the
+ * Visual Editor only changes the value, never the page around it. Marks exist only in a preview, so visitors never
+ * see them.
+ */
+
+export const REF_PATTERN = /^[a-z_]+\/[A-Za-z0-9_\-./]{1,200}$/;
+
+type Mark = (ref: string) => Record<string, string>;
+
+const none: Mark = () => ({});
+
+/**
+ * Attributes for marking a value, or nothing outside a preview:
+ *
+ *   const mark = await editMarks();
+ *   <h1 {...mark("copy/hero_title")}>{title}</h1>
+ *
+ * A bad ref gives nothing rather than an error, so a typo can never break a visitor's page.
+ */
+export async function editMarks(): Promise<Mark> {
+  try {
+    if (!(await draftMode()).isEnabled) return none;
+  } catch {
+    return none;
+  }
+  return (ref): Record<string, string> => (REF_PATTERN.test(ref) ? { "data-bp-edit": ref } : {});
+}
+
+function adminOrigin(request: NextRequest): string | null {
+  const id = process.env.BLUEPRINT_SITE_ID?.trim();
+  if (!id) return null;
+  return verifyVisualCookie(process.env.BLUEPRINT_REVALIDATE_SECRET, request.cookies.get(VISUAL_COOKIE)?.value, id)?.adminOrigin ?? null;
+}
+
+/** The frame-ancestors value for sites that build their own Content-Security-Policy: "'self'", plus the Visual Editor's address while it's open. */
+export function frameAncestors(request: NextRequest): string {
+  const origin = adminOrigin(request);
+  return origin ? `'self' ${origin}` : "'self'";
+}
+
+/**
+ * For the site's `src/proxy.ts`. While the Visual Editor is open in this browser, lets its Site Manager address show
+ * the page in a frame. Browsers ignore X-Frame-Options when frame-ancestors is sent, so every other response keeps
+ * the site's usual SAMEORIGIN. Redirects are left alone: they have no page to show.
+ */
+export function visualFrameHeaders(request: NextRequest, response: NextResponse): NextResponse {
+  if (response.headers.has("location")) return response;
+  const origin = adminOrigin(request);
+  if (!origin) return response;
+  const existing = response.headers.get("content-security-policy");
+  const value = `frame-ancestors 'self' ${origin}`;
+  response.headers.set("content-security-policy", existing ? `${existing}; ${value}` : value);
+  return response;
+}

package/src/waitlist-form.ts

@@ -0,0 +1,39 @@
+import type { WaitlistOptions } from "./types";
+
+// The waitlist form's pure parts, kept out of the "use server" file so they can be tested and shared.
+
+/** The fields a waitlist form sends. `choice` is "plan:<slug>" or "beds:<n>", for a form with one picker. */
+export const WAITLIST_FIELDS = ["choice", "floorPlan", "bedrooms", "email", "name", "phone", "moveIn"] as const;
+
+export type WaitlistInput = { floorPlan?: string; bedrooms?: number; email: string; name?: string; phone?: string; moveIn?: string };
+
+const text = (fd: FormData, k: string) => {
+  const v = fd.get(k);
+  return typeof v === "string" && v.trim() ? v.trim() : undefined;
+};
+
+/**
+ * Reads a submitted waitlist form. A plan page usually sends a hidden `floorPlan`; a general form sends one `choice`
+ * from waitlistChoices(). A choice wins over the separate fields.
+ */
+export function readWaitlistForm(fd: FormData): WaitlistInput {
+  const choice = text(fd, "choice");
+  let floorPlan = text(fd, "floorPlan");
+  let bedrooms = text(fd, "bedrooms");
+  if (choice?.startsWith("plan:")) [floorPlan, bedrooms] = [choice.slice(5), undefined];
+  else if (choice?.startsWith("beds:")) [floorPlan, bedrooms] = [undefined, choice.slice(5)];
+  const beds = bedrooms !== undefined && /^\d{1,2}$/.test(bedrooms) ? Number(bedrooms) : undefined;
+  return { floorPlan, bedrooms: floorPlan ? undefined : beds, email: text(fd, "email") ?? "", name: text(fd, "name"), phone: text(fd, "phone"), moveIn: text(fd, "moveIn") };
+}
+
+/**
+ * Options for one waitlist picker: each bedroom count ("Any 2 bedroom plan") and then each plan. Plans with a home
+ * available now are left out unless asked for, since a visitor can apply for those today.
+ */
+export function waitlistChoices(options: WaitlistOptions, opts: { includeAvailable?: boolean } = {}): { value: string; label: string }[] {
+  const plans = options.floorPlans.filter((p) => opts.includeAvailable || !p.available);
+  return [
+    ...options.bedrooms.map((b) => ({ value: `beds:${b.value}`, label: b.value === 0 ? "Any studio" : `Any ${b.label.replace(/s$/, "")} plan` })),
+    ...plans.map((p) => ({ value: `plan:${p.slug}`, label: p.name })),
+  ];
+}

package/src/waitlist.ts

@@ -0,0 +1,48 @@
+"use server";
+
+import { createHash } from "node:crypto";
+import { headers } from "next/headers";
+import { bpRaw } from "./client";
+import { checkFormToken } from "./form-token";
+import type { WaitlistResult } from "./types";
+import { readWaitlistForm } from "./waitlist-form";
+
+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;
+  }
+}
+
+/**
+ * Adds a visitor to a floor plan's waitlist, or a bedroom count's, from the site's server. The same spam checks as
+ * forms (FormGuard's honeypot and render time, and BotID) run first; suspected spam gets the usual thank-you and is
+ * dropped. The answer is the same whether or not the visitor was already waiting.
+ */
+export async function joinWaitlist(formData: FormData): Promise<WaitlistResult> {
+  const token = checkFormToken(String(formData.get("bp_ts") ?? ""));
+  const spam = String(formData.get("bp_hp") ?? "").trim() !== "" ? "honeypot" : !token.ok ? (token.reason === "too_fast" ? "too_fast" : "bot") : (await isBot()) ? "bot" : null;
+  if (spam) return { ok: true, waitingFor: null };
+
+  const h = await headers();
+  const ip = h.get("x-real-ip") ?? h.get("x-forwarded-for")?.split(",")[0]?.trim() ?? "";
+  const { status, json } = await bpRaw("/waitlist", {
+    ...readWaitlistForm(formData),
+    pageUrl: h.get("referer") ?? undefined,
+    ipHash: ip ? createHash("sha256").update(ip).digest("hex") : undefined,
+  });
+  const body = json as { data?: { waitingFor: string | null }; error?: { fields?: Record<string, string> } } | null;
+  if (status === 201 || status === 200) return { ok: true, waitingFor: body?.data?.waitingFor ?? null };
+  if (status === 422) return { ok: false, error: "invalid", 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(waitlistAction, null)`. */
+export async function waitlistAction(_prev: WaitlistResult | null, formData: FormData): Promise<WaitlistResult> {
+  return joinWaitlist(formData);
+}