@taprootio/site-authoring 0.8.2 → 0.8.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "Taproot site authoring CLI: sign in once in the browser, then pull, validate, push, preview, approve, and deploy a site from the terminal",
   "type": "module",
   "license": "ISC",
@@ -28,7 +28,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@taprootio/espalier": "4.13.0"
+    "@taprootio/espalier": "4.14.1"
   },
   "scripts": {
     "test": "node --test",

package/src/constants.js

@@ -1,5 +1,5 @@
 export const CLI_NAME = "@taprootio/site-authoring";
-export const CLI_VERSION = "0.8.2";
+export const CLI_VERSION = "0.8.4";
 export const CLI_BINARY_NAME = "taproot-site";
 export const RESULT_SCHEMA_VERSION = 1;
 export const CONFIG_FILE_NAME = "taproot-site.json";

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

@@ -68,6 +68,16 @@ export interface RenderProseMirrorOptions {
     /** The page shell emits this default once so rich-text formats inherit it. */
     maxHeightVh?: TiptapImageMaxHeightVh | number | null;
   };
+  /** Generator-only render hooks for structured nodes that need page context. */
+  nodeRenderers?: {
+    componentBlock?: (node: ProseMirrorNode) => string | undefined;
+    taprootImage?: (node: ProseMirrorNode) => string | undefined;
+    rawHtml?: (html: string, node: ProseMirrorNode) => string | undefined;
+  };
+  /** Records visible document-order content after each node is rendered. */
+  onRenderedNode?: (node: ProseMirrorNode, html: string) => void;
+  /** Claims the page's one LCP slot before rendering a section photo. */
+  claimSectionBackgroundImage?: () => boolean;
 }
 
 export function createEmptyProseMirrorDocument(): ProseMirrorDocument {
@@ -97,11 +107,62 @@ export function renderRichTextBodyToHtml(
   body: unknown,
   options: RenderProseMirrorOptions = {},
 ): string {
-  if (typeof body === "string") return body;
   if (!isProseMirrorDocument(body)) return "";
   return renderProseMirrorDocumentToHtml(body, options);
 }
 
+/**
+ * Extracts the reader-visible text from a ProseMirror document for metadata
+ * that only accepts plain text, such as Schema.org recipe instructions.
+ */
+export function extractRichTextBodyText(body: unknown): string {
+  if (!isProseMirrorDocument(body)) return "";
+  const parts: string[] = [];
+  collectText(body, parts);
+  return parts.join("").replace(/\s+/gu, " ").trim();
+}
+
+function collectText(node: ProseMirrorNode, parts: string[]): void {
+  if (node.type === "text") {
+    if (node.text) parts.push(node.text);
+    return;
+  }
+
+  // rawHtml is an intentional, already-sanitized node in the JSON document
+  // contract. It is not the retired outer HTML-body transport. Preserve its
+  // reader-visible text when a consumer (for example Recipe JSON-LD) needs a
+  // plain-text representation of the document.
+  if (node.type === "rawHtml") {
+    const html = stringAttr(node.attrs?.html);
+    if (html) parts.push(plainTextFromRawHtml(html));
+    return;
+  }
+
+  for (const child of node.content ?? []) {
+    collectText(child, parts);
+  }
+
+  if (node.type === "hardBreak" || isTextBlock(node.type)) {
+    parts.push(" ");
+  }
+}
+
+function isTextBlock(type: string): boolean {
+  return type === "paragraph"
+    || type === "heading"
+    || type === "listItem"
+    || type === "blockquote"
+    || type === "codeBlock"
+    || type === "tableCell"
+    || type === "tableHeader";
+}
+
+function plainTextFromRawHtml(html: string): string {
+  return html
+    .replace(/<(?:br\s*\/?|\/(?:p|div|li|h[1-6]|blockquote|pre|tr|table|section|article))\s*[^>]*>/giu, " ")
+    .replace(/<[^>]*>/gu, "");
+}
+
 type RenderPlacement = "root" | "section" | "nested";
 
 function renderNodes(
@@ -109,7 +170,11 @@ function renderNodes(
   options: RenderProseMirrorOptions,
   placement: RenderPlacement,
 ): string {
-  return nodes.map((node) => renderNode(node, options, placement)).join("");
+  return nodes.map((node) => {
+    const html = renderNode(node, options, placement);
+    options.onRenderedNode?.(node, html);
+    return html;
+  }).join("");
 }
 
 function renderFreeFormRootNodes(
@@ -118,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);
@@ -136,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);
@@ -150,6 +232,7 @@ function renderNode(
   node: ProseMirrorNode,
   options: RenderProseMirrorOptions,
   placement: RenderPlacement,
+  compactFollowing = false,
 ): string {
   switch (node.type) {
     case "doc":
@@ -193,11 +276,11 @@ function renderNode(
     case "table":
       return placement === "root" || placement === "section" ? renderTable(node, options) : "";
     case "taprootImage":
-      return renderTaprootImage(node, options);
+      return options.nodeRenderers?.taprootImage?.(node) ?? renderTaprootImage(node, options);
     case "inlineFacts":
       return renderInlineFacts(node, options, placement);
     case "componentBlock":
-      return renderComponentBlock(node);
+      return options.nodeRenderers?.componentBlock?.(node) ?? renderComponentBlock(node);
     case "integrationPlacement":
       return renderIntegrationPlacement(node, options);
     case "section":
@@ -207,9 +290,12 @@ function renderNode(
         "explicit",
         options,
         placement === "root" ? "section" : "nested",
+        compactFollowing,
       );
-    case "rawHtml":
-      return stringAttr(node.attrs?.html) ?? "";
+    case "rawHtml": {
+      const html = stringAttr(node.attrs?.html) ?? "";
+      return options.nodeRenderers?.rawHtml?.(html, node) ?? html;
+    }
     default:
       return renderNodes(node.content ?? [], options, "nested");
   }
@@ -618,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;
@@ -650,6 +737,9 @@ function renderSection(
     if (decorationStyle) sectionStyleParts.push(...decorationStyle);
   }
   const background = kind === "explicit" ? normalizeSectionBackground(attrs.background) : undefined;
+  const backgroundPicture = background
+    ? renderSectionBackgroundPicture(background, options.claimSectionBackgroundImage?.() === true)
+    : "";
   if (background) {
     sectionStyleParts.push(
       `--esp-section-background: color-mix(in oklab, var(--esp-color-background) ${background.scrimOpacityPercent}%, transparent)`,
@@ -678,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,
@@ -695,7 +786,7 @@ function renderSection(
       style:
         `--taproot-section-focus: ${background.focus}; --taproot-section-portrait-focus: ${background.portraitFocus}`,
     },
-    `${renderSectionBackgroundPicture(background)}${section}`,
+    `${backgroundPicture}${section}`,
   );
 }
 
@@ -845,7 +936,7 @@ function normalizeSectionFocus(
   return `${x * 100}% ${y * 100}%`;
 }
 
-function renderSectionBackgroundPicture(background: NormalizedSectionBackground): string {
+function renderSectionBackgroundPicture(background: NormalizedSectionBackground, hero: boolean): string {
   const portraitSource = background.portraitImage
     ? renderVoidElement("source", {
       media: "(max-width: 48rem)",
@@ -862,7 +953,8 @@ function renderSectionBackgroundPicture(background: NormalizedSectionBackground)
     height: background.image.height,
     alt: "",
     decoding: "async",
-    loading: "lazy",
+    loading: hero ? undefined : "lazy",
+    fetchpriority: hero ? "high" : undefined,
   });
   return renderElement(
     "picture",
@@ -1032,19 +1124,50 @@ function renderComponentBlock(node: ProseMirrorNode): string {
   );
 }
 
-function renderTaprootImage(node: ProseMirrorNode, options: RenderProseMirrorOptions): string {
+export interface ResolvedTiptapImage {
+  src: string;
+  urls: Array<{ minWidth: number; url: string; type?: string }>;
+  width: number;
+  height: number;
+  alt: string;
+  imageId: string;
+  preserveStoredSrc: boolean;
+  extraAttributes: Record<string, string | number | undefined>;
+}
+
+export function resolveTiptapImage(
+  node: ProseMirrorNode,
+  imageDefaults: RenderProseMirrorOptions["imageDefaults"],
+): ResolvedTiptapImage {
   const attrs = node.attrs ?? {};
-  const resolved = resolveImagePresentation(attrs, options.imageDefaults);
+  const crop = jsonAttr(attrs.crop);
+  const resolved = resolveImagePresentation(attrs, imageDefaults);
+  return {
+    src: stringAttr(attrs.src) ?? "",
+    urls: validResponsiveImageUrls(attrs.urls),
+    width: numberAttr(attrs.width) ?? 0,
+    height: numberAttr(attrs.height) ?? 0,
+    alt: stringAttr(attrs.alt) ?? "",
+    imageId: stringAttr(attrs.imageId) ?? "",
+    preserveStoredSrc: Boolean(crop && crop !== "null"),
+    extraAttributes: {
+      ...(crop ? { "data-crop": crop } : {}),
+      ...resolved,
+    },
+  };
+}
+
+function renderTaprootImage(node: ProseMirrorNode, options: RenderProseMirrorOptions): string {
+  const image = resolveTiptapImage(node, options.imageDefaults);
   const imageAttrs: Record<string, string | number | boolean | null | undefined> = {
-    "low-res": stringAttr(attrs.src),
-    "original-width": numberAttr(attrs.width),
-    "original-height": numberAttr(attrs.height),
-    "data-image-id": stringAttr(attrs.imageId),
-    "data-crop": jsonAttr(attrs.crop),
-    caption: stringAttr(attrs.alt),
-    ...resolved,
+    "low-res": image.src,
+    "original-width": image.width,
+    "original-height": image.height,
+    "data-image-id": image.imageId,
+    caption: image.alt,
+    ...image.extraAttributes,
   };
-  const optionsHtml = validResponsiveImageUrls(attrs.urls)
+  const optionsHtml = image.urls
     .map((url) =>
       renderVoidElement("esp-image-option", {
         width: url.minWidth,

package/src/presentation-reference.js

@@ -333,7 +333,17 @@ export function getAppearanceReference() {
     imageReferences:
       "Use site-owned image ids retained from pull or returned by media upload. URLs are server projections, never authored inputs.",
     logoContract:
-      "lightLogoId and darkLogoId are the current scheme-specific logo fields; there is no separate compact-logo setting.",
+      "lightLogoId and darkLogoId are the current scheme-specific logo fields; there is no separate compact-logo setting. "
+      + "Prefer transparent PNG or WebP artwork with genuine alpha so the header background shows through, including "
+      + "inside letter counters. Avoid baked-in background rectangles unless the brand intentionally uses a badge. "
+      + "Keep padding tight and verify the delivered image preserves transparency. Logo style and coloration are "
+      + "project-specific: choose monochrome, an accent, or multiple colors to suit the brand, not a universal recipe. "
+      + "Keep the lettering readable and test the visible artwork against each header scheme.",
+    faviconContract:
+      "Include a favicon when designing a site: upload a square, simplified brand mark and set brand.faviconId "
+      + "in settings/brand.json, then run theme push; faviconUrl is a read-only projection. Do not shrink a full wordmark into a favicon. "
+      + "Inspect at 16 and 32 pixels in light and dark browser tabs; a deliberate contrasting badge can help a favicon "
+      + "remain recognizable independently of the header theme. Verify the published icon loads, not just the setting.",
     logoContrastContract:
       "Evaluate lightLogoId against the rendered light-scheme header and darkLogoId against the rendered dark-scheme "
       + "header at desktop and compact/mobile widths. Transparent pixels provide no contrast: inspect the visible mark, "
@@ -602,6 +612,7 @@ export function formatPresentationReference(reference) {
       + reference.readOnlyProjections.map((field) => "  " + field.file + " :: " + field.path).join("\n")
       + "\n\nImages: " + reference.imageReferences + "\nLogos: " + reference.logoContract
       + "\nLogo contrast: " + reference.logoContrastContract
+      + "\nFavicon: " + reference.faviconContract
       + "\nHeader width: " + reference.headerWidthContract
       + "\nMobile menu and menu font: " + reference.menuContract
       + "\nFooter: " + reference.footerBoundary

package/src/reference-help.js

@@ -51,7 +51,7 @@ import {
 
 export { getAppearanceReference, getFooterReference, getThemeReference };
 
-export const REFERENCE_VERSION = 23;
+export const REFERENCE_VERSION = 24;
 export const PAGE_TYPES = Object.freeze(["free-form"]);
 
 function deepFreeze(value) {
@@ -134,7 +134,7 @@ const DESIGN_BLUEPRINTS = deepFreeze([
         purpose: "Make a single product story legible before offering supporting choices.",
         section: { entrance: "scale", entranceStagger: "none" },
         components: [
-          { type: "image-banner", properties: { ratio: "3/1", heightMode: "viewport", contentPosition: "bottom-start", scrim: "bottom", imageMotion: "slow-zoom" } },
+          { type: "image-banner", properties: { ratio: "3/1", heightMode: "viewport", contentPosition: "bottom-start", scrim: "bottom", imageMotion: "parallax" } },
           { type: "cta", properties: { variant: "primary", imagePosition: "right", borderWidth: 0 } },
         ],
       },
@@ -148,7 +148,7 @@ const DESIGN_BLUEPRINTS = deepFreeze([
         ],
       },
     ],
-    motionCeiling: "Use one slow image movement or short hover response per view; never conceal names, price context, or actions behind motion.",
+    motionCeiling: "Prefer one optional image parallax per view (imageMotion: parallax-subtle or parallax). Published pages use CSS view timelines where supported and a platform-owned scroll-linked JavaScript fallback otherwise; no custom code is needed. Movement stops when scrolling stops, pauses offscreen, and is disabled for reduced motion. Without JavaScript or native timelines the image stays static. Cinematic zoom is an explicit ambient-loop alternative. Never conceal names, price context, or actions behind motion.",
     mediaBrief: "Commission or license product, material, and in-use photography; document crop-safe banner areas and supply alt text for informative images.",
     integrationBoundaries: "Use outbound links for retail, commerce, search, or booking providers. This blueprint includes none of those systems and no custom code.",
     accessibilityCautions: ["Preserve text contrast over imagery with a tested scrim and do not make text depend on hover.", "Respect reduced-motion preferences and give every campaign action a visible text label."],
@@ -511,6 +511,7 @@ const WORKFLOW_REFERENCES = Object.freeze({
     details: Object.freeze([
       "Paths are relative to the configured workspace root, not the shell's current directory.",
       "PNG, JPEG, GIF, and WebP are accepted; retina names such as logo@2x.png and logo@3x.png are supported.",
+      "For header logos prefer genuine transparent PNG/WebP, check contrast in both themes, and include a simplified square favicon. See help appearance for branding guidance.",
       "Each result item includes media: { imageId, src, urls, width, height, alt }.",
       "The same src/urls delivery fields are saved in .taproot-site-media.json for page and component authoring.",
     ]),