@taprootio/site-authoring 0.20.0 → 0.22.0

package/src/setting-reference.js

@@ -0,0 +1,438 @@
+import { APPEARANCE_FOOTER_COLOR_FIELDS, APPEARANCE_SCALAR_FIELDS } from "./appearance-contract.js";
+import {
+  SETTINGS_GROUPS,
+  SETTINGS_TYPE_BRAND,
+  SETTINGS_TYPE_SITE_HEADER,
+  SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES,
+  SETTINGS_TYPE_TAPROOT_STYLES,
+} from "./settings-catalog.js";
+
+/**
+ * What every setting the CLI pulls means, which app control it is, and where it
+ * renders (TR01222).
+ *
+ * This is the one owner of that prose. `help settings` prints all of it, `help
+ * appearance` prints the entry beside each writable field, and a test fails
+ * when a field in `settings-catalog.js` has no entry here, so the help cannot
+ * drift behind a new field. Descriptions state current behavior; where the
+ * platform's rendering is a known limit, the entry says so plainly.
+ */
+
+const BRAND = "Brand & style > Brand";
+const HEADER = "Header & navigation";
+const FEATURES = "Features";
+
+function entry(appLabel, description, renders, defaultValue) {
+  return Object.freeze({
+    appLabel,
+    description,
+    ...(renders === undefined ? {} : { renders }),
+    ...(defaultValue === undefined ? {} : { default: defaultValue }),
+  });
+}
+
+/** Both schemes' image fields share a sentence shape. */
+const LOGO_RENDERS = "The brand slot of the header, at the height brandLogoSize sets, and the footer's brand once the "
+  + "footer is enabled with its brand on. On a standard site a scheme with no logo of its own uses the other "
+  + "scheme's, and a site with no logo shows its brand text alone. On a profile site an unset light logo is the "
+  + "Taproot logo and an unset dark logo is the light one. Assign the highest-resolution file you have: the "
+  + "platform keeps one normalized master and serves resized WebP renditions, so an @2x suffix is only a filename "
+  + "and a second, smaller copy is never needed.";
+
+/** The canvas image's rendering limits, stated once for both schemes. */
+const CANVAS_RENDERS = "Only the empty side margins of a page, the left and right canvas columns of the page "
+  + "shell, never behind the content. The browser's default background rules apply, so the image tiles at its natural "
+  + "pixel size from the top-left of each margin; nothing resizes it to the margin, and the file delivered is the "
+  + "largest rendition (a WebP up to 2000 px wide). A standard site's pages have margins 0 px wide at every "
+  + "viewport, so the image does not appear on one today.";
+
+const OPACITY_RENDERS = "Sets the opacity of the canvas image layer in the same side margins; it applies only while a "
+  + "canvas image is set.";
+
+/** The page background image's rendering, stated once for the theme reference, `help settings` and the README. */
+export const PAGE_BACKGROUND_IMAGE_RENDERING = "One layer across the whole page box, behind the content. The header and "
+  + "footer paint their own opaque backgrounds over it, so it shows behind the main content only.";
+
+export const PAGE_BACKGROUND_VERSUS_CANVAS = Object.freeze({
+  pageBackground:
+    "Page style > Background image is the theme's pageBackgroundImage (with pageBackgroundImageOpacity) in "
+    + "settings.lightTheme and settings.darkTheme. " + PAGE_BACKGROUND_IMAGE_RENDERING + " Today its value is a CSS "
+    + "url(...) of a delivered image, taken from the src that .taproot-site-media.json records; there is no image-id "
+    + "field for it.",
+  canvas:
+    "Page canvas > Canvas image is lightCanvasImageId and darkCanvasImageId in settings/taproot-styles.json, with "
+    + "their opacity fields. It paints only the side margins outside the page content.",
+  shared:
+    "Neither sets a size, repeat or position, so both tile at the image's natural pixel size from the top-left. The "
+    + "published site copies the file the URL names into its own assets; it does not resize it.",
+});
+
+const TAPROOT_STYLES_ENTRIES = {
+  lightTheme: entry(
+    "Brand & style (light scheme)",
+    "The complete Espalier theme for the light scheme: colors, fonts, scales and the page background image.",
+    "Every published page, in the light scheme. help theme lists the fields.",
+  ),
+  darkTheme: entry(
+    "Brand & style (dark scheme)",
+    "The complete Espalier theme for the dark scheme: colors, fonts, scales and the page background image.",
+    "Every published page, in the dark scheme. help theme lists the fields.",
+  ),
+  defaultScheme: entry(
+    `${BRAND} > Default scheme`,
+    "The color scheme a first-time visitor sees: light, dark, or system to follow the visitor's device.",
+    "The starting scheme of every published page. A visitor who uses the theme toggle keeps their own choice.",
+  ),
+  lightLogoId: entry(
+    `${BRAND} > Logo`,
+    "The site-owned image used as the brand logo in the light scheme.",
+    LOGO_RENDERS,
+  ),
+  lightLogoUrl: entry(`${BRAND} > Logo`, "Read-only: the delivery URL of lightLogoId."),
+  darkLogoId: entry(
+    `${BRAND} > Logo`,
+    "The site-owned image used as the brand logo in the dark scheme.",
+    LOGO_RENDERS,
+  ),
+  darkLogoUrl: entry(`${BRAND} > Logo`, "Read-only: the delivery URL of darkLogoId."),
+  lightCanvasImageId: entry(
+    "Brand & style > Page canvas > Canvas image",
+    "The site-owned image painted in the side margins of a page in the light scheme.",
+    CANVAS_RENDERS,
+  ),
+  lightCanvasImageUrl: entry(
+    "Brand & style > Page canvas > Canvas image",
+    "Read-only: the delivery URL of lightCanvasImageId.",
+  ),
+  darkCanvasImageId: entry(
+    "Brand & style > Page canvas > Canvas image",
+    "The site-owned image painted in the side margins of a page in the dark scheme.",
+    CANVAS_RENDERS,
+  ),
+  darkCanvasImageUrl: entry(
+    "Brand & style > Page canvas > Canvas image",
+    "Read-only: the delivery URL of darkCanvasImageId.",
+  ),
+  lightCanvasImageOpacity: entry(
+    "Brand & style > Page canvas > Canvas image",
+    "How strongly the light canvas image shows, from 0 (invisible) to 1 (fully opaque).",
+    OPACITY_RENDERS,
+  ),
+  darkCanvasImageOpacity: entry(
+    "Brand & style > Page canvas > Canvas image",
+    "How strongly the dark canvas image shows, from 0 (invisible) to 1 (fully opaque).",
+    OPACITY_RENDERS,
+  ),
+};
+
+const BRAND_ENTRIES = {
+  faviconId: entry(
+    `${BRAND} > Favicon`,
+    "The square site-owned image the platform turns into the site's icon set.",
+    "Linked from the head of every published page as favicon.ico, square PNGs from 16 to 512 px and a 180 px Apple "
+      + "touch icon. A site with no favicon still serves /favicon.ico: a neutral mark on a standard site, the Taproot mark on a "
+      + "profile site. Use a simplified square mark, not a "
+      + "full wordmark.",
+  ),
+  faviconUrl: entry(`${BRAND} > Favicon`, "Read-only: the delivery URL of faviconId."),
+};
+
+const HEADER_ENTRIES = {
+  headerLayout: entry(
+    `${HEADER} > Layout`,
+    "How the brand, menu and buttons are arranged: standard (one row), centered-brand, minimal (the menu stays in "
+      + "the drawer) or centered-menu (brand at the start, buttons at the end, menu centered).",
+    "The header at the top of every published page.",
+  ),
+  headerWidth: entry(
+    `${HEADER} > Width`,
+    "contained keeps the brand and buttons at the page content edges; wide moves them to the viewport edges.",
+    "The header bar's content. Its background spans the viewport either way.",
+  ),
+  navDrawerStyle: entry(
+    `${HEADER} > Mobile menu`,
+    "How the navigation opens when it does not fit inline: full-screen over the whole viewport (the default) or as a "
+      + "side panel.",
+    "The drawer opened by the header's burger button, on narrow screens and wherever the menu is drawer-only.",
+  ),
+  navDrawerTransition: entry(
+    `${HEADER} > Menu transition`,
+    "How the full-screen drawer appears: fade, slide-down, slide-up, slide-left or slide-right.",
+    "Applies only while navDrawerStyle is full-screen.",
+  ),
+  brandText: entry(
+    `${BRAND} > Brand text`,
+    "The site name printed in the header brand.",
+    "The header, beside or instead of the logo, when showBrandText is on, and the footer's brand once the footer is "
+      + "enabled.",
+  ),
+  showBrandText: entry(
+    `${HEADER} > Brand text`,
+    "Whether brandText is printed in the header.",
+    "The header brand.",
+  ),
+  logoAlt: entry(
+    `${BRAND} > Logo alternative text`,
+    "The alternative text of the header logo image, read aloud and shown if the image fails.",
+    "The header logo and the footer's brand logo.",
+  ),
+  brandColor: entry(
+    `${BRAND} > Brand color`,
+    "The color of the brand text in both schemes, as a theme token or a custom color. Empty uses the header default.",
+    "The header brand text and the footer's brand text. lightBrandColor or darkBrandColor overrides it for one scheme.",
+  ),
+  lightBrandColor: entry(
+    `${BRAND} > Brand color`,
+    "The brand text color in the light scheme. Empty falls back to brandColor, then to darkBrandColor.",
+    "The header and footer brand text in the light scheme.",
+  ),
+  darkBrandColor: entry(
+    `${BRAND} > Brand color`,
+    "The brand text color in the dark scheme. Empty falls back to brandColor, then to the light color.",
+    "The header and footer brand text in the dark scheme.",
+  ),
+  navMenuDisplay: entry(
+    `${HEADER} > Navigation`,
+    "auto shows the menu inline when it fits and falls back to the drawer; drawer always uses the burger and drawer.",
+    "The header menu.",
+  ),
+  headerPosition: entry(
+    `${HEADER} > Position`,
+    "normal lets the header scroll away with the page; sticky keeps it at the top once it reaches it.",
+    "The header at the top of every published page.",
+  ),
+  showThemeToggle: entry(
+    `${HEADER} > Theme toggle`,
+    "Whether visitors get a light/dark toggle in the header.",
+    "The header buttons.",
+  ),
+  brandLogoSize: entry(
+    `${HEADER} > Logo size`,
+    "How tall the header logo is: standard (0.72 of the header height), large (0.85) or full (the whole header height).",
+    "The header logo.",
+  ),
+  brandHoverGrow: entry(
+    `${HEADER} > Hover emphasis`,
+    "Whether the header brand grows slightly while the pointer is over it.",
+    "The header brand.",
+  ),
+};
+
+const PREFERENCES_ENTRIES = {
+  commentsMode: entry(
+    `${FEATURES} > Comments`,
+    "Who may comment on articles, recipes, place reviews and albums, and whether a comment needs approval. pull records the enum member name, such as SITE_COMMENTS_MODE_AUTHENTICATED.",
+    "The comments section under those pages.",
+    "SITE_COMMENTS_MODE_AUTHENTICATED",
+  ),
+  tiptapImagePlacement: entry(
+    `${FEATURES} > Image placement`,
+    "The site's default placement for images in a page body: left, left-text-right, center, right or right-text-left.",
+    "Images in page bodies.",
+    "left",
+  ),
+  timeZone: entry(
+    `${FEATURES} > Time zone`,
+    "The site's IANA time zone, which decides what \"today\" means for relative date limits on forms.",
+    "Form date pickers and the check at submit. A change applies after a deployment.",
+    "UTC",
+  ),
+  allowSearch: entry(
+    `${FEATURES} > Search`,
+    "Whether the published site offers site search.",
+    "The header search button. A change applies after a deployment.",
+    false,
+  ),
+  showFollowButton: entry(
+    `${FEATURES} > Follow button`,
+    "Whether pages show a Follow button. Readers need a Taproot account to follow an author, so leave it off until "
+      + "reader sign-up is available.",
+    "The byline of article, album, recipe and place-review pages and the profile home. A change applies after a "
+      + "deployment.",
+    false,
+  ),
+  albumSeamless: entry(
+    `${FEATURES} > Album layout`,
+    "Whether album images sit edge to edge (seamless) by default. An album can set its own seamless value.",
+    "Album pages.",
+    false,
+  ),
+  hideLightboxComments: entry(
+    `${FEATURES} > Comments in the lightbox`,
+    "True hides comments inside the image lightbox; the app shows this as a switch that reads the other way round.",
+    "The image lightbox.",
+    false,
+  ),
+  tiptapImageMaxHeightVh: entry(
+    `${FEATURES} > Image height`,
+    "The tallest an image in a page body may be, as a percent of the screen height (45, 60, 75 or 90).",
+    "Images in page bodies.",
+    60,
+  ),
+  tiptapImageMaxImagesPerRow: entry(
+    `${FEATURES} > Consecutive images per row`,
+    "How many consecutive images in a page body share a row: 1, 2 or 3.",
+    "Images in page bodies.",
+    2,
+  ),
+  tiptapImageBorderWidth: entry(
+    `${FEATURES} > Image border width`,
+    "The border around images in a page body in pixels, from 0 (no border) to 20.",
+    "Images in page bodies.",
+    2,
+  ),
+  albumBorderWidth: entry(
+    `${FEATURES} > Album border width`,
+    "The default border around album images in pixels, from 0 to 20. An album can set its own borderWidth.",
+    "Album pages.",
+    0,
+  ),
+  albumMaxImagesPerRow: entry(
+    `${FEATURES} > Maximum images per album row`,
+    "The most images an album shows side by side in one row, from 1 to 5.",
+    "Album pages.",
+    2,
+  ),
+  albumMaxRowHeightVh: entry(
+    `${FEATURES} > Album maximum row height`,
+    "The tallest an album row may be, as a percent of the screen height (1 to 100). A partial last row stays no "
+      + "taller than the rows before it.",
+    "Album pages.",
+    90,
+  ),
+  footerSettings: entry(
+    "Footer",
+    "The whole footer: link columns, aside and bottom text, brand, feature image and per-scheme colors and background.",
+    "The footer of every published page, but only once footerSettings.enabled is true. help footer has the closed "
+      + "schema.",
+    { enabled: false },
+  ),
+};
+
+export const SETTING_FIELD_REFERENCE = Object.freeze({
+  [SETTINGS_TYPE_TAPROOT_STYLES]: Object.freeze(TAPROOT_STYLES_ENTRIES),
+  [SETTINGS_TYPE_BRAND]: Object.freeze(BRAND_ENTRIES),
+  [SETTINGS_TYPE_SITE_HEADER]: Object.freeze(HEADER_ENTRIES),
+  [SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES]: Object.freeze(PREFERENCES_ENTRIES),
+});
+
+/** The description, app control and rendering note for one catalog field, for the references that list it. */
+export function describeSettingField(settingsType, name) {
+  const known = SETTING_FIELD_REFERENCE[settingsType]?.[name];
+  if (known === undefined) throw new TypeError(`No setting reference for ${settingsType} ${name}.`);
+  return known;
+}
+
+const WRITABLE_SCALARS = new Set(
+  APPEARANCE_SCALAR_FIELDS.map((field) => `${field.settingsType}:${field.name}`),
+);
+const THEME_FOOTER_COLORS = APPEARANCE_FOOTER_COLOR_FIELDS.length;
+
+/** How the CLI changes a field: the verb that writes it, or that it is read-only here. */
+function writeVerb(group, field) {
+  if (field.wireType === "theme" || WRITABLE_SCALARS.has(`${group.settingsType}:${field.name}`)) return "theme push";
+  if (field.name === "footerSettings") {
+    return `footer push (content); theme push (the ${THEME_FOOTER_COLORS} scheme colors)`;
+  }
+  if (field.name.endsWith("Url")) return "read-only projection of the matching id; never authored";
+  return "read-only: pull records it, change it in the app";
+}
+
+/**
+ * App controls that save into lightTheme and darkTheme rather than a field of
+ * their own, so a lookup by label still finds a path. Both schemes carry each
+ * field; the app edits the scheme it is showing.
+ */
+export const THEME_CONTROLS = Object.freeze([
+  Object.freeze({
+    appLabel: "Brand & style > Color harmony (and its hue and chroma controls)",
+    fields: Object.freeze(["seedColor", "angles", "variantChroma"]),
+  }),
+  Object.freeze({
+    appLabel: "Brand & style > Semantic color mappings > Color source",
+    fields: Object.freeze(["semanticMappings"]),
+  }),
+  Object.freeze({
+    appLabel: "Brand & style > Page style > Background image",
+    fields: Object.freeze(["pageBackgroundImage", "pageBackgroundImageOpacity"]),
+    renders: PAGE_BACKGROUND_IMAGE_RENDERING,
+  }),
+  Object.freeze({
+    appLabel: "Brand & style > Brand > Brand font and Brand weight",
+    fields: Object.freeze(["fontBrand", "fontWeightBrand"]),
+  }),
+  Object.freeze({
+    appLabel: "Brand & style > Brand > Menu font and Menu weight",
+    fields: Object.freeze(["fontMenu", "fontWeightMenu"]),
+  }),
+  Object.freeze({
+    appLabel: "Brand & style > Typography > Headings and Headings weight",
+    fields: Object.freeze(["fontHeadings", "fontWeightHeadings"]),
+  }),
+  Object.freeze({
+    appLabel: "Brand & style > Typography > Body and Body weight",
+    fields: Object.freeze(["fontBody", "fontWeightBody"]),
+  }),
+  Object.freeze({
+    appLabel: "Brand & style > Typography > Monospace and Monospace weight",
+    fields: Object.freeze(["fontMonospace", "fontWeightMonospace"]),
+  }),
+]);
+
+/** The reference `help settings` prints: every catalog field with its meaning, app control and write path. */
+export function getSettingsReference() {
+  const scalarDefaults = new Map(
+    APPEARANCE_SCALAR_FIELDS.map((field) => [`${field.settingsType}:${field.name}`, field.default]),
+  );
+  return {
+    title: "Site settings: what each field is, which app control it is, and where it renders",
+    referenceKind: "settings",
+    usage: "pull | theme push | footer push",
+    groups: SETTINGS_GROUPS.map((group) => ({
+      file: `settings/${group.file}`,
+      fields: group.fields.map((field) => {
+        const known = SETTING_FIELD_REFERENCE[group.settingsType][field.name];
+        const scalarKey = `${group.settingsType}:${field.name}`;
+        const defaultValue = scalarDefaults.has(scalarKey) ? scalarDefaults.get(scalarKey) : known.default;
+        return {
+          path: `settings.${field.name}`,
+          wireType: field.wireType,
+          appLabel: known.appLabel,
+          description: known.description,
+          ...(defaultValue === undefined ? {} : { default: defaultValue }),
+          ...(known.renders === undefined ? {} : { renders: known.renders }),
+          write: writeVerb(group, field),
+        };
+      }),
+    })),
+    themeControls: THEME_CONTROLS.map((control) => ({
+      ...control,
+      file: "settings/taproot-styles.json",
+      paths: ["settings.lightTheme", "settings.darkTheme"],
+    })),
+    pageBackgroundVersusCanvas: PAGE_BACKGROUND_VERSUS_CANVAS,
+  };
+}
+
+export function formatSettingsReference(reference) {
+  const groups = reference.groups.map((group) =>
+    `${group.file}\n${
+      group.fields.map((field) =>
+        `  ${field.path}  (${field.wireType}; ${field.write}${
+          field.default === undefined ? "" : `; default ${JSON.stringify(field.default)}`
+        })\n    app: ${field.appLabel}\n    ${field.description}${
+          field.renders === undefined ? "" : `\n    renders: ${field.renders}`
+        }`
+      ).join("\n")
+    }`
+  ).join("\n\n");
+  const controls = reference.themeControls.map((control) =>
+    `  ${control.appLabel}\n    ${control.file} :: ${control.paths.join(" and ")} :: ${control.fields.join(", ")}${
+      control.renders === undefined ? "" : `\n    renders: ${control.renders}`
+    }`
+  ).join("\n");
+  const contrast = reference.pageBackgroundVersusCanvas;
+  return `${reference.title}\nUsage: ${reference.usage}\n\nPage background image versus canvas image:\n  - ${
+    contrast.pageBackground
+  }\n  - ${contrast.canvas}\n  - ${contrast.shared}\n\nApp controls stored inside the theme (help theme describes each field):\n${controls}\n\n${groups}\n`;
+}

package/src/settings-catalog.js

@@ -200,12 +200,11 @@ export function projectSettingsGroup(group, response) {
     if (field.wireType === "theme") {
       // A stored theme is what was written, possibly before a required key
       // existed; the workspace gets the complete theme consumers actually
-      // render, resolved the way they resolve it (TR00775). The read-only
-      // provenance flag says whether Taproot's house look still layers under it.
+      // render, resolved the way they resolve it (TR00775): as stored, over
+      // Espalier's defaults alone (TR01060).
       projected[field.name] = projectPulledTheme(
         projected[field.name],
         field.name === "lightTheme" ? "light" : "dark",
-        { managedExternally: source[`${field.name}ManagedExternally`] === true },
       );
     }
   }

package/src/site-check-findings.js

@@ -0,0 +1,188 @@
+import { sanitizeDiagnostic } from "./errors.js";
+import { boundedByBytes } from "./session.js";
+import rules from "./site-check-rules.json" with { type: "json" };
+import { isFormKey } from "./forms-contract.js";
+import { DESCRIPTION_WARN_LENGTH, pageStructureFindings, TITLE_WARN_LENGTH } from "./page-structure-checks.js";
+import { missingPageLinkFindings, normalizedPathSet } from "./site-checks.js";
+import { documentTemplate, TEMPLATE_FREE_FORM, TEMPLATE_GENERATED } from "./typed-pages.js";
+import { displayPagePath } from "./workspace.js";
+
+/**
+ * The CLI's side of the site validation pipeline (TR01085). The rules, their
+ * severities and where they run are `shared/site-check-rules.json`; `validate`
+ * evaluates the ones that name it offline, and lists the rest as checked by the
+ * site, where `status` shows them. A finding carries a rule id and values; the
+ * words below are this surface's own.
+ */
+export const SITE_CHECK_RULES = Object.freeze(rules.rules);
+
+/** The CLI's sentence for each rule, keyed by rule id. A rule without an entry falls back to its id. */
+export const SITE_CHECK_WORDING = Object.freeze({
+  "link.page_missing": (finding) => `links to ${finding.subject}, which is not a page of this site`,
+  "image.missing": () => "places an image that is no longer available",
+  "form.none_chosen": () => "has a Form block with no form chosen",
+  "form.unreadable": () => "places a form by an old key or an id the site cannot read",
+  "form.missing": () => "places a form that does not exist",
+  "form.archived": (finding) => `places the form '${finding.detail}', which is archived`,
+  "form.key_unknown": (finding) =>
+    isFormKey(finding.subject)
+      ? `places the form '${finding.subject}', but the workspace has no forms/${finding.subject}.json (add that form file, run 'forms pull' if the site has it, or fix the key)`
+      : `places the form '${finding.subject}', which is not a form key (lowercase letters, digits and single hyphens)`,
+  "form.not_supported_on_site_type": () => "places a form, but forms are available on standard sites only",
+  "form.after_submit_page_unpublished": (finding) =>
+    `the form '${finding.detail}' sends visitors to ${finding.subject || "a page that no longer exists"}, which the release does not publish`,
+  "form.after_submit_page_not_allowed": (finding) =>
+    `the form '${finding.detail}' sends visitors to ${finding.subject}, which is not a page you created`,
+  "redirect.source_invalid": () => "has a source that is not an absolute site path",
+  "redirect.source_index_html": () => "has a source ending in index.html",
+  "redirect.source_integration_data": () => "has a source under the integration data root",
+  "redirect.source_share_link": () => "has a source under the share-link root",
+  "redirect.source_runtime_mirror": () => "has a source under the published-site runtime",
+  "redirect.source_generated_file": () => "has a source naming a file the site generates",
+  "redirect.source_not_storable": () => "has a source the publisher cannot store",
+  "seo.h1_missing": () =>
+    "has no h1: no level 1 heading, banner title or hero title opens the page, so search engines find no page title",
+  "seo.h1_demoted": (finding) =>
+    `has the level 1 heading '${finding.subject}', which publishes as an h2 because ${H1_CLAIMANT[finding.detail] ?? "another element"} is already the page's h1`,
+  "seo.h1_multiple": (finding) =>
+    `has the hero title '${finding.subject}', which is a second h1 because ${H1_CLAIMANT[finding.detail] ?? "another element"} is already the page's h1`,
+  "seo.heading_renumbered": (finding) => {
+    const [authored, published] = finding.detail.split(">");
+    return `has the heading '${finding.subject}' written as an h${authored}, which publishes as an h${published} so no level is skipped`;
+  },
+  "seo.heading_before_title": (finding) =>
+    `has the heading '${finding.subject}' before the page's h1; it publishes as an h${finding.detail}`,
+  "a11y.image_alt_missing": () => "places an image with no alt text",
+  "a11y.link_text_empty": (finding) => `has a link to ${finding.subject} with no text`,
+  "seo.title_long": (finding) =>
+    `has a title of ${finding.detail} characters; search results show about ${TITLE_WARN_LENGTH}`,
+  "seo.description_missing": () => "has no description; search results use the start of the page instead",
+  "seo.description_long": (finding) =>
+    `has a description of ${finding.detail} characters; search results show about ${DESCRIPTION_WARN_LENGTH}`,
+  "seo.social_image_fallback": (finding) =>
+    finding.detail === "first_image"
+      ? "has no cover image; link previews use the page's first image only when it is public and at least 1200 pixels wide"
+      : "has no cover image and no images, so link previews show no picture",
+});
+
+/** What a finding's `detail` names as the element that already claims the page's h1. */
+const H1_CLAIMANT = Object.freeze({
+  heading: "the first level 1 heading",
+  banner: "the banner at the top",
+  hero: "the hero title",
+});
+
+/** The sentence for a finding, falling back to the rule id for a rule this release has no words for. */
+export function describeSiteFinding(finding) {
+  const words = SITE_CHECK_WORDING[finding.ruleId];
+  return words === undefined ? `was flagged by the site check '${finding.ruleId}'` : words(finding);
+}
+
+// Progress names this many; the JSON list is bounded by bytes instead.
+const MAXIMUM_PROGRESS_LINES = 20;
+
+const rulesRunningAt = (point) => SITE_CHECK_RULES.filter((rule) => rule.runsAt.includes(point)).map((rule) => rule.id);
+
+// The document rules `validate` runs offline, as the set the shared evaluator filters by.
+const OFFLINE_DOCUMENT_RULES = new Set(
+  SITE_CHECK_RULES.filter((rule) => rule.scope === "document" && rule.runsAt.includes("validate")).map((rule) => rule.id),
+);
+
+/** The page-structure findings for one planned page, or none for a document the rules cannot read. */
+function structureFindingsFor(page) {
+  if (page.document === null || typeof page.document !== "object") return [];
+  const template = documentTemplate(page.document);
+  // A generated page's title and description come from the site, not from an author.
+  if (template === TEMPLATE_GENERATED) return [];
+  const freeForm = template === TEMPLATE_FREE_FORM;
+  return pageStructureFindings(
+    {
+      freeForm,
+      body: freeForm ? page.document : undefined,
+      title: page.title,
+      description: page.declaredDescription ?? page.description,
+    },
+    OFFLINE_DOCUMENT_RULES,
+  );
+}
+
+/**
+ * Evaluates the offline page rules over the planned pages. `pagePaths` is every
+ * page path the workspace knows, and `pagesComplete` says whether that list is
+ * the whole site: a truncated manifest cannot say a link is broken.
+ */
+export function evaluateOfflineSiteChecks({
+  planned,
+  pagePaths,
+  pagesComplete = true,
+  formKeysChecked = true,
+  onProgress = () => {},
+}) {
+  const known = normalizedPathSet([...pagePaths, ...(planned ?? []).map((page) => page.pagePath)]);
+
+  const found = [];
+  for (const page of planned ?? []) {
+    if (page.document === null || typeof page.document !== "object") continue;
+    // The link rule needs every page path; the structure rules read only the page itself.
+    const linkFindings = pagesComplete ? missingPageLinkFindings(page.document, page.pagePath ?? "", known) : [];
+    for (const finding of [...linkFindings, ...structureFindingsFor(page)]) found.push({ page, finding });
+  }
+  // Errors first, then in catalogue order, so the bounded list and the progress lines keep the rules that
+  // matter most when a large site raises a frequent one (a missing description) on every page.
+  const catalogueOrder = (ruleId) => SITE_CHECK_RULES.findIndex((rule) => rule.id === ruleId);
+  const severityOrder = (finding) => (finding.severity === "error" ? 0 : 1);
+  found.sort((left, right) =>
+    severityOrder(left.finding) - severityOrder(right.finding)
+    || catalogueOrder(left.finding.ruleId) - catalogueOrder(right.finding.ruleId)
+  );
+
+  const items = [];
+  for (const { page, finding } of found) {
+    const subject = [...sanitizeDiagnostic(finding.subject, "")].slice(0, 300).join("");
+    const item = {
+      rule: finding.ruleId,
+      severity: finding.severity,
+      file: page.file,
+      path: displayPagePath(page.pagePath),
+      subject,
+      ...(finding.detail === "" ? {} : { detail: finding.detail }),
+    };
+    if (items.length < MAXIMUM_PROGRESS_LINES) {
+      onProgress(`Warning: ${item.file} ${describeSiteFinding({ ...finding, subject })}.`);
+    }
+    items.push(item);
+  }
+  if (items.length > MAXIMUM_PROGRESS_LINES) {
+    onProgress(`Warning: ${items.length - MAXIMUM_PROGRESS_LINES} more site check finding(s); see findings.`);
+  }
+  const reported = boundedByBytes(items, 8 * 1024);
+  const errors = items.filter((item) => item.severity === "error").length;
+  return {
+    findings: {
+      total: items.length,
+      errors,
+      warnings: items.length - errors,
+      items: reported.items,
+      ...(reported.truncated ? { truncated: true } : {}),
+    },
+    siteChecks: {
+      ranOffline: rulesRunningAt("validate"),
+      // Rules that need the site's own records; `taproot-site status` shows what the site finds.
+      checkedBySite: SITE_CHECK_RULES.filter((rule) => !rule.runsAt.includes("validate") && rule.runsAt.includes("health"))
+        .map((rule) => rule.id),
+      // Rules the deploy itself applies; the deploy refusal names them, and no read reports them beforehand.
+      checkedAtDeploy: SITE_CHECK_RULES.filter((rule) =>
+        !rule.runsAt.includes("validate") && !rule.runsAt.includes("health") && rule.runsAt.includes("deploy")
+      ).map((rule) => rule.id),
+      // Rules only the page editor evaluates: a cover, a description field, or a description's length (which the CLI reports as descriptionWarnings).
+      checkedInEditor: SITE_CHECK_RULES.filter((rule) =>
+        !rule.runsAt.includes("validate") && !rule.runsAt.includes("health") && !rule.runsAt.includes("deploy")
+        && rule.runsAt.includes("edit")
+      ).map((rule) => rule.id),
+      // A rule that had nothing to read: a truncated page manifest, or a workspace with no form files.
+      ...(pagesComplete && formKeysChecked
+        ? {}
+        : { skipped: [...(pagesComplete ? [] : ["link.page_missing"]), ...(formKeysChecked ? [] : ["form.key_unknown"])] }),
+    },
+  };
+}