@taprootio/site-authoring 0.8.3 → 0.8.5

package/src/content/components.js

@@ -252,6 +252,8 @@ const IMAGE_BANNER = Object.freeze({
   // the site header; `viewport` fills exactly that space (TR00413).
   heightMode: enumOf("ratio", "viewport"),
   contentPosition: enumOf("bottom-start", "bottom", "bottom-end", "center", "top-start", "top", "top-end"),
+  contentGutter: enumOf("frame", "page"),
+  followingSpacing: enumOf("standard", "compact"),
   scrim: enumOf("auto", "none", "flat", "top", "bottom", "left", "right", "radial"),
   scrimStrength: enumOf("soft", "medium", "strong"),
   bannerScheme: enumOf("auto", "light", "dark"),
@@ -260,7 +262,7 @@ const IMAGE_BANNER = Object.freeze({
   // A built-in or application-registered Espalier texture name.
   texture: textureName(),
   textureScale: enumOf("fine", "medium", "coarse"),
-  imageMotion: enumOf("none", "slow-zoom", "drift-start", "drift-end"),
+  imageMotion: enumOf("none", "slow-zoom", "drift-start", "drift-end", "parallax-subtle", "parallax"),
 });
 
 const SPACER = Object.freeze({
@@ -371,6 +373,8 @@ const COMPONENT_DEFINITIONS = Object.freeze({
       "Identify the speaker with authorName; use authorTitle when it gives useful context.",
       "Author images need descriptive alt text unless they are purely decorative.",
       "Keep carousel intervals long enough for the full quotation to be read.",
+      "Set carousel:true for directional previous/next arrows, dot navigation and a play/pause control. Navigation or keyboard focus pauses rotation; reduced-motion users get manual navigation without sliding or automatic rotation.",
+      "Use real attributed reviews, or clearly label fictional demo reviews. Never imply invented testimonials are genuine customer endorsements.",
     ],
     {
       items: [{
@@ -494,6 +498,8 @@ const COMPONENT_DEFINITIONS = Object.freeze({
       compactRatio: "3/2",
       heightMode: "ratio",
       contentPosition: "center",
+      contentGutter: "frame",
+      followingSpacing: "standard",
       scrim: "auto",
       scrimStrength: "medium",
       bannerScheme: "auto",
@@ -505,6 +511,16 @@ const COMPONENT_DEFINITIONS = Object.freeze({
     [
       "Set altText to describe meaningful banner imagery; leave it empty only when the image is decorative.",
       "Choose a scrim and scheme that keep overlay text readable across the image.",
+      "For a full-bleed photograph with text aligned to the surrounding page well, set contentGutter to page. followingSpacing: compact reduces the top padding of an immediately following section so a bottom banner heading reads with its supporting paragraph. Use a banner-only contentPadding: none section followed by a standard text section; keep their theme contexts consistent. Defaults preserve frame-edge text and standard section spacing.",
+      "Compose around the actual photograph: identify the meaningful subject and a quiet area for copy. Do not cover faces, product details, or high-detail edges. A focal point controls cropping, not text placement; inspect wide and compact crops separately. Keep the subject's face, ears, and other identifying details inside the compact frame, including at both ends of parallax travel. Adjust focus toward the subject rather than reusing a generic center; reduce motion or choose a roomier crop if preserving the subject requires it.",
+      "Use contentPosition to place copy in that quiet area, not automatically in the center. Keep one dominant message and nearby supporting copy/actions; if the photo has no safe text area, use a split hero or a separate text section instead of forcing an overlay.",
+      "Use the rule of thirds as a composition guide: consider the subject near one third and a compact text group in quiet space on the opposite side. Golden-ratio proportions are optional alternatives, not a proven engagement formula. Neither guide overrides legibility, the actual subject, or the compact crop. Current contentPosition values are edge/center anchors, not exact third or golden-ratio coordinates; do not invent unsupported positioning properties.",
+      "Check contrast behind the actual letters at both motion endpoints and both themes: WCAG AA requires 4.5:1 for ordinary text and 3:1 for qualifying large text. A text shadow alone is not a contrast guarantee. Keep text and actions stationary; recheck at mobile widths and enlarged text.",
+      "Prefer parallax-subtle or parallax when motion is useful: motion follows the reader's scrolling and stops when they stop. Infinite ambient loops are an explicit art-direction choice, not the default recommendation.",
+      "imageMotion is optional and defaults to none. slow-zoom is a cinematic 18% zoom over 6 seconds, alternating; drift-start and drift-end travel horizontally over 8 seconds with a 14% safety crop.",
+      "These retuned ambient presets affect existing published banners when their shared runtime updates, without a per-site republish. Preview existing sites before rolling out the runtime.",
+      "parallax-subtle and parallax are scroll-linked image motion, not autoplay: scroll to see them. Published pages prefer CSS view timelines and use a platform-owned JavaScript fallback in unsupported browsers, including Firefox; authors need no custom code. Both paths respect reduced motion. They travel vertically by +/-4% and +/-8% of image height with 12% and 22% overscan. Keep focal subjects away from edges; overlay text remains stationary in its frame.",
+      "All image motion is disabled for prefers-reduced-motion. Without native view timelines and JavaScript, parallax remains static. Choose one motion per banner; never put essential text in the raster image.",
     ],
     {
       image: null,
@@ -516,7 +532,7 @@ const COMPONENT_DEFINITIONS = Object.freeze({
       scrim: "bottom",
       scrimStrength: "medium",
       texture: "paper",
-      imageMotion: "slow-zoom",
+      imageMotion: "parallax-subtle",
     },
   ),
 });

package/src/content/tiptap-prosemirror.ts

@@ -183,16 +183,19 @@ function renderFreeFormRootNodes(
 ): string {
   const rendered: string[] = [];
   let flow: ProseMirrorNode[] = [];
+  let compactFollowing = false;
   const flushFlow = () => {
     if (flow.length === 0) return;
-    rendered.push(renderSection(flow, {}, "implicit", options, "root"));
+    rendered.push(renderSection(flow, {}, "implicit", options, "root", compactFollowing));
+    compactFollowing = false;
     flow = [];
   };
 
   for (const node of nodes) {
     if (node.type === freeFormSectionRegistry.section.nodeType || isRootBandComponent(node)) {
       flushFlow();
-      rendered.push(renderNode(node, options, "root"));
+      rendered.push(renderNode(node, options, "root", compactFollowing));
+      compactFollowing = joinsFollowingSection(node);
       continue;
     }
     flow.push(node);
@@ -201,6 +204,20 @@ function renderFreeFormRootNodes(
   return rendered.join("");
 }
 
+function joinsFollowingSection(node: ProseMirrorNode): boolean {
+  if (node.type === "section") {
+    return node.attrs?.contentPadding === "none" && node.content?.length === 1
+      && joinsFollowingSection(node.content[0]);
+  }
+  if (node.type !== "componentBlock" || node.attrs?.componentType !== "image-banner") return false;
+  try {
+    const data = JSON.parse(stringAttr(node.attrs?.componentData) ?? "{}");
+    return data?.followingSpacing === "compact";
+  } catch {
+    return false;
+  }
+}
+
 function isRootBandComponent(node: ProseMirrorNode): boolean {
   if (node.type !== "componentBlock") return false;
   const componentType = stringAttr(node.attrs?.componentType);
@@ -215,6 +232,7 @@ function renderNode(
   node: ProseMirrorNode,
   options: RenderProseMirrorOptions,
   placement: RenderPlacement,
+  compactFollowing = false,
 ): string {
   switch (node.type) {
     case "doc":
@@ -272,6 +290,7 @@ function renderNode(
         "explicit",
         options,
         placement === "root" ? "section" : "nested",
+        compactFollowing,
       );
     case "rawHtml": {
       const html = stringAttr(node.attrs?.html) ?? "";
@@ -685,6 +704,7 @@ function renderSection(
   kind: "explicit" | "implicit",
   options: RenderProseMirrorOptions,
   contentPlacement: RenderPlacement,
+  compactFollowing = false,
 ): string {
   const definitions = freeFormSectionRegistry.section.attrs;
   const contentPadding = attrs.contentPadding === "none" ? "none" : definitions.contentPadding.default;
@@ -748,6 +768,7 @@ function renderSection(
     {
       "data-taproot-section": kind,
       "data-content-padding": contentPadding,
+      "data-following-spacing": compactFollowing && contentPadding === "standard" ? "compact" : undefined,
       "data-surface": surface,
       "data-entrance": entrance,
       "data-entrance-stagger": entranceStagger,

package/src/delivery-browser.js

@@ -0,0 +1,276 @@
+import { sanitizeDiagnostic } from "./errors.js";
+import { withholdCredentialLocation } from "./staging-check.js";
+
+/**
+ * The optional browser dimension of delivery verification (TR00824).
+ *
+ * HTTP evidence cannot say what a visitor's browser loaded: the shared runtime
+ * comes from a mutable major pointer that a returning browser may hold in its
+ * cache. This probe drives a real browser at the target twice — a fresh
+ * context, then a second navigation in the same context so the browser's own
+ * cache participates — and reports which runtime entry each load evaluated,
+ * whether the declared capability elements were defined, and whether the
+ * second load actually served the runtime entry from cache.
+ *
+ * Playwright is deliberately not a dependency of this package: basic CLI use
+ * must not carry a browser. The probe imports it only if the operator has
+ * installed it where this package's imports resolve (a global install of both
+ * packages, run through the installed command), and reports the dimension as
+ * unchecked with that recovery otherwise.
+ *
+ * Playwright's own request routing is not used: it disables the HTTP cache,
+ * which is the very thing the returning load measures. Instead a DevTools
+ * session on the browser itself — not on the page, because a page session
+ * sees only its own target and authored script can open a popup — intercepts
+ * every document request in the browser (the navigation, each redirect hop,
+ * a script-driven navigation, a frame, a popup) at the request stage, before
+ * it is transmitted, and fails any that would leave the target origin; the
+ * subresource cache is untouched. A page session reports whether the runtime
+ * entry came from the memory or disk cache. Without the browser session the
+ * boundary cannot be enforced, so the dimension is unchecked rather than
+ * probed without it. Every URL the probe reports passes through the
+ * credential withholding the staging check uses, so a handoff-bearing
+ * redirect never reaches the result. A staging cookie is attached only to the
+ * staging origin it was minted for.
+ */
+
+// Node resolves `playwright` from the CLI's own dependency chain: a copy run
+// through `npx` lives in npm's cache and cannot see a global Playwright, so
+// the recovery installs the CLI and Playwright side by side and reruns
+// through the installed `taproot-site` command rather than `npx`.
+export const BROWSER_INSTALL_HINT = "npm install --global @taprootio/site-authoring@latest playwright && npx playwright install chromium, then rerun with the installed taproot-site command (not npx)";
+const SETTLE_MILLISECONDS = 20_000;
+const EVIDENCE_CHARACTERS = 512;
+const BLOCKED_NAVIGATION = /ERR_BLOCKED_BY_CLIENT|ERR_ABORTED/u;
+
+async function defaultImportPlaywright() {
+  return await import("playwright");
+}
+
+/** A URL or entry name as evidence: credentials withheld, controls removed, bounded. */
+function evidence(value) {
+  return [...withholdCredentialLocation(typeof value === "string" ? value : "")].slice(0, EVIDENCE_CHARACTERS).join("");
+}
+
+async function observe(page, capabilities) {
+  return await page.evaluate((declared) => {
+    const root = document.querySelector("esp-root");
+    const entries = performance.getEntriesByType("resource")
+      .map((entry) => entry.name)
+      .filter((name) => /taproot-shared-runtime[^/]*\.js(?:$|\?)/u.test(name));
+    return {
+      rootDefined: customElements.get("esp-root") !== undefined,
+      themeReady: root?.hasAttribute("data-theme-ready") ?? false,
+      loadingHeld: root?.hasAttribute("data-taproot-loading") ?? false,
+      runtimeEntries: entries.slice(0, 4),
+      capabilitiesDefined: declared.filter((tag) => customElements.get(tag) !== undefined).length,
+      title: document.title,
+    };
+  }, capabilities);
+}
+
+const NOTHING_OBSERVED = Object.freeze({ rootDefined: false, themeReady: false, loadingHeld: false, runtimeEntries: [], capabilitiesDefined: 0 });
+
+/** Every URL the navigation passed through, from the first request to the final document. */
+function redirectChain(response) {
+  const hops = [];
+  let request = response?.request?.();
+  while (request && hops.length < 16) {
+    hops.unshift(request.url());
+    request = request.redirectedFrom?.();
+  }
+  return hops;
+}
+
+function sameOrigin(url, origin) {
+  try {
+    return new URL(url).origin === origin;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The DevTools sessions that enforce the navigation boundary (on the browser,
+ * so every target is covered) and observe cache reuse (on the page). Undefined
+ * when the browser offers no such sessions.
+ */
+async function startDevTools(browser, context, page, { origin, expectedEntryUrl }) {
+  if (typeof browser.newBrowserCDPSession !== "function" || typeof context.newCDPSession !== "function") return undefined;
+  let boundary;
+  let session;
+  try {
+    boundary = await browser.newBrowserCDPSession();
+    session = await context.newCDPSession(page);
+  } catch {
+    return undefined;
+  }
+  const state = { blocked: [], requests: new Map(), fromCache: undefined };
+  boundary.on("Fetch.requestPaused", (event) => {
+    const url = event?.request?.url ?? "";
+    if (sameOrigin(url, origin)) {
+      boundary.send("Fetch.continueRequest", { requestId: event.requestId }).catch(() => undefined);
+    } else {
+      if (state.blocked.length < 8) state.blocked.push(url);
+      boundary.send("Fetch.failRequest", { requestId: event.requestId, errorReason: "BlockedByClient" }).catch(() => undefined);
+    }
+  });
+  session.on("Network.requestWillBeSent", (event) => {
+    if (event?.request?.url === expectedEntryUrl) state.requests.set(event.requestId, event.request.url);
+  });
+  // A memory-cache hit is announced by requestServedFromCache; only a disk
+  // (or prefetch) cache hit is visible on the response itself.
+  session.on("Network.requestServedFromCache", (event) => {
+    if (state.requests.has(event?.requestId)) state.fromCache = true;
+  });
+  session.on("Network.responseReceived", (event) => {
+    if (event?.response?.url !== expectedEntryUrl || state.fromCache === true) return;
+    state.fromCache = Boolean(event.response.fromDiskCache || event.response.fromPrefetchCache);
+  });
+  await session.send("Network.enable");
+  await boundary.send("Fetch.enable", { patterns: [{ urlPattern: "*", resourceType: "Document", requestStage: "Request" }] });
+  return {
+    state,
+    reset() {
+      state.blocked = [];
+      state.requests.clear();
+      state.fromCache = undefined;
+    },
+  };
+}
+
+async function load(page, url, capabilities, origin, devtools) {
+  devtools.reset();
+  let response;
+  let blockedNavigation = false;
+  try {
+    response = await page.goto(url, { waitUntil: "domcontentloaded" });
+  } catch (error) {
+    // The boundary failed a document request before it was sent; the
+    // navigation error is the expected outcome, not a probe failure.
+    if (devtools.state.blocked.length === 0 && !BLOCKED_NAVIGATION.test(String(error?.message ?? ""))) throw error;
+    blockedNavigation = true;
+  }
+  if (!blockedNavigation) {
+    await page.waitForFunction(
+      () => {
+        const root = document.querySelector("esp-root");
+        return root !== null && !root.hasAttribute("data-taproot-loading");
+      },
+      undefined,
+      { timeout: SETTLE_MILLISECONDS },
+    ).catch(() => undefined);
+  }
+  const hops = blockedNavigation ? [] : [...new Set([...redirectChain(response), page.url()])];
+  const strayed = [...new Set([...devtools.state.blocked, ...hops.filter((hop) => !sameOrigin(hop, origin))])];
+  const observed = blockedNavigation ? NOTHING_OBSERVED : await observe(page, capabilities);
+  return { observed, strayed, finalUrl: blockedNavigation ? "" : page.url() };
+}
+
+function judge({ observed, strayed, finalUrl }, expectedEntryUrl, capabilityCount) {
+  const loadedEntry = observed.runtimeEntries.find((name) => name === expectedEntryUrl)
+    ?? observed.runtimeEntries[0]
+    ?? "";
+  return {
+    loadedEntry: evidence(loadedEntry),
+    expectedEntry: observed.runtimeEntries.includes(expectedEntryUrl),
+    rootDefined: observed.rootDefined,
+    themeReady: observed.themeReady,
+    capabilitiesDefined: observed.capabilitiesDefined,
+    capabilitiesDeclared: capabilityCount,
+    finalUrl: evidence(finalUrl),
+    ...(strayed.length > 0 ? { offOriginNavigation: strayed.slice(0, 4).map(evidence) } : {}),
+    ok: strayed.length === 0 && observed.rootDefined && observed.themeReady
+      && observed.runtimeEntries.includes(expectedEntryUrl)
+      && observed.capabilitiesDefined === capabilityCount,
+  };
+}
+
+/**
+ * @param options.baseUrl The delivery origin.
+ * @param options.expectedEntryUrl The runtime entry the major pointer names right now.
+ * @param options.capabilities Custom-element tags the home page declares.
+ * @param options.cookie Optional staging cookie, sent only to `baseUrl`'s host.
+ * @param options.importPlaywright Test seam; defaults to a dynamic import.
+ */
+export async function probeDeliveryWithBrowser({
+  baseUrl,
+  expectedEntryUrl,
+  capabilities = [],
+  cookie,
+  importPlaywright = defaultImportPlaywright,
+}) {
+  let playwright;
+  try {
+    playwright = await importPlaywright();
+  } catch {
+    return {
+      status: "unchecked",
+      reason: "playwright_unavailable",
+      install: BROWSER_INSTALL_HINT,
+      note: "Fresh and returning browser behaviour was not verified; install the CLI and Playwright together and rerun through the installed taproot-site command to check it.",
+    };
+  }
+  const origin = new URL(baseUrl).origin;
+  let browser;
+  try {
+    browser = await playwright.chromium.launch({ headless: true });
+    const context = await browser.newContext();
+    if (cookie) {
+      const [name, value] = cookie.split("=", 2);
+      // A __Host- cookie carries no Domain attribute by definition; the URL
+      // form binds it to the staging origin without one.
+      await context.addCookies([{ name, value, url: baseUrl, secure: true, httpOnly: true, sameSite: "Lax" }]);
+    }
+    const page = await context.newPage();
+    const devtools = await startDevTools(browser, context, page, { origin, expectedEntryUrl });
+    if (!devtools) {
+      await context.close();
+      return {
+        status: "unchecked",
+        reason: "navigation_boundary_unavailable",
+        note: "The browser offers no DevTools sessions, so document requests could not be held to the site origin; nothing was loaded.",
+      };
+    }
+    const fresh = judge(await load(page, baseUrl, capabilities, origin, devtools), expectedEntryUrl, capabilities.length);
+    if (fresh.offOriginNavigation) {
+      // A target that leaves its origin is not probed again.
+      await context.close();
+      return {
+        status: "checked",
+        fresh,
+        returning: { skipped: true, reason: "fresh_load_left_origin", ok: false },
+        staleRuntimeObserved: false,
+        returningCache: { status: "unchecked", reason: "fresh_load_left_origin" },
+        ok: false,
+      };
+    }
+    // The same context navigates again: its HTTP cache now holds whatever the
+    // first load fetched, which is exactly what a returning visitor has.
+    const returning = judge(await load(page, baseUrl, capabilities, origin, devtools), expectedEntryUrl, capabilities.length);
+    const cacheObserved = devtools.state.fromCache;
+    await context.close();
+    return {
+      status: "checked",
+      fresh,
+      returning: {
+        ...returning,
+        runtimeFromCache: cacheObserved === undefined ? "unchecked" : cacheObserved,
+      },
+      staleRuntimeObserved: fresh.ok && !returning.expectedEntry,
+      returningCache: cacheObserved === undefined
+        ? { status: "unchecked", reason: "cache_observation_unavailable" }
+        : { status: "checked", servedFromCache: cacheObserved },
+      ok: fresh.ok && returning.ok,
+    };
+  } catch (error) {
+    return {
+      status: "failed",
+      reason: "browser_probe_failed",
+      error: sanitizeDiagnostic(error instanceof Error ? error.name : "Error", "Error"),
+      note: "The browser dimension could not be completed and is not verified.",
+    };
+  } finally {
+    await browser?.close().catch(() => undefined);
+  }
+}