@taprootio/site-authoring 0.27.1 → 0.29.0

package/src/footer-contract.js

@@ -4,6 +4,8 @@ import {
   isContactOrWebUrl,
 } from "./contact-url.js";
 import { hasControlCharacter, isCanonicalUuid, SiteAuthoringError } from "./errors.js";
+import { isSocialLinkUrl, SOCIAL_LINK_URL_MAX_LENGTH, trimSocialLinkInput } from "./social-link-url.js";
+import socialPlatforms from "./social-platforms.json" with { type: "json" };
 import { FOOTER_COLOR_TOKENS, requireAppearanceColor } from "./theme-validation.js";
 
 export const FOOTER_LIMITS = Object.freeze({
@@ -12,6 +14,7 @@ export const FOOTER_LIMITS = Object.freeze({
   groupsPerColumn: 6,
   linksPerGroup: 12,
   bottomLinks: 8,
+  socialLinks: 12,
   richTextParagraphs: 12,
   richTextRuns: 200,
   groupHeadingLength: 80,
@@ -56,10 +59,12 @@ export const FOOTER_FIELD_INVENTORY = Object.freeze({
     "bottomContent",
     "featureImage",
     "showBrandText",
+    "socialLinks",
   ]),
   FooterLinkColumn: Object.freeze(["id", "groups"]),
   FooterLinkGroup: Object.freeze(["id", "heading", "links"]),
   FooterLink: Object.freeze(["id", "label", "pageResourceId", "externalUrl"]),
+  FooterSocialLink: Object.freeze(["id", "platform", "url", "label"]),
   FooterRichText: Object.freeze(["paragraphs"]),
   FooterRichTextParagraph: Object.freeze(["runs"]),
   FooterRichTextRun: Object.freeze(["text", "bold", "italic", "underline", "link"]),
@@ -82,6 +87,13 @@ export const FOOTER_FIELD_INVENTORY = Object.freeze({
   FooterFeatureResponsiveImageUrl: Object.freeze(["minWidth", "url"]),
 });
 
+/** The platform keys a footer social link may name, in the vocabulary's order; `other` is the Website link. */
+export const SOCIAL_PLATFORM_KEYS = Object.freeze(socialPlatforms.platforms.map((platform) => platform.key));
+export const OTHER_SOCIAL_PLATFORM = "other";
+export const SOCIAL_LINK_URL_REQUIREMENT =
+  `must be an absolute https URL without credentials, at most ${SOCIAL_LINK_URL_MAX_LENGTH} characters, `
+  + "to a domain name of unaccented letters, digits and hyphens, like https://www.instagram.com/yourname";
+
 export const FOOTER_READ_ONLY_FIELDS = Object.freeze([
   "light.backgroundImageUrl",
   "dark.backgroundImageUrl",
@@ -314,6 +326,40 @@ function footerLink(value, path, seenLinkIds, knownPageResourceIds, tolerateStor
   };
 }
 
+// Mirrors the server's social-link rules (TR01324) in the same order: the id
+// shares the footer's seen set, the platform is a vocabulary key, the address
+// is judged after the shared trim, and a label is optional text that is
+// refused when it is only whitespace and required for a Website link.
+function socialLink(value, path, seenLinkIds, tolerateStoredValues) {
+  value = object(value, path);
+  closed(value, "FooterSocialLink", path);
+  const id = stableId(value.id, `${path}.id`, seenLinkIds, "link");
+  // A stored platform that later leaves the vocabulary must still pull, as a
+  // stored bottom-link address does; only an authored document is refused.
+  if (typeof value.platform !== "string" || (!tolerateStoredValues && !SOCIAL_PLATFORM_KEYS.includes(value.platform))) {
+    fail("footer.field_invalid", `${path}.platform must be one of ${SOCIAL_PLATFORM_KEYS.join(", ")}.`, `${path}.platform`);
+  }
+  if (typeof value.url !== "string") {
+    fail("footer.url_invalid", `${path}.url ${SOCIAL_LINK_URL_REQUIREMENT}.`, `${path}.url`);
+  }
+  const url = trimSocialLinkInput(value.url);
+  if (!tolerateStoredValues && !isSocialLinkUrl(url)) {
+    fail("footer.url_invalid", `${path}.url ${SOCIAL_LINK_URL_REQUIREMENT}.`, `${path}.url`);
+  }
+  const rawLabel = value.label === undefined ? "" : value.label;
+  const label = normalizedSingleLine(rawLabel, FOOTER_LIMITS.linkLabelLength, `${path}.label`, { tolerateStoredValues });
+  if (!tolerateStoredValues) {
+    // Blank is judged with the shared whitespace set, as the page component and the handler judge it.
+    if (rawLabel.length > 0 && trimSocialLinkInput(label) === "") {
+      fail("footer.text_required", `${path}.label: A label must have text, or leave it out.`, `${path}.label`);
+    }
+    if (trimSocialLinkInput(label) === "" && value.platform === OTHER_SOCIAL_PLATFORM) {
+      fail("footer.text_required", `${path}.label: A Website link needs a label.`, `${path}.label`);
+    }
+  }
+  return { id, platform: value.platform, url, label };
+}
+
 function footerLinks(values, path, maximum, seenLinkIds, knownPageResourceIds, tolerateStoredValues) {
   return array(values, path, maximum).map((value, index) =>
     footerLink(value, `${path}[${index}]`, seenLinkIds, knownPageResourceIds, tolerateStoredValues)
@@ -463,6 +509,7 @@ export function footerDefaults() {
     bottomContent: { paragraphs: [] },
     featureImage: undefined,
     showBrandText: true,
+    socialLinks: [],
   };
 }
 
@@ -571,6 +618,8 @@ function normalizeFooterDocument(
     ),
     ...(normalizedFeatureImage === undefined ? {} : { featureImage: normalizedFeatureImage }),
     showBrandText: boolean(value.showBrandText, true, "footerSettings.showBrandText"),
+    socialLinks: array(value.socialLinks, "footerSettings.socialLinks", FOOTER_LIMITS.socialLinks)
+      .map((link, index) => socialLink(link, `footerSettings.socialLinks[${index}]`, seenLinkIds, tolerateStoredValues)),
   };
 }
 
@@ -684,4 +733,14 @@ export const FOOTER_EXAMPLE = Object.freeze({
     alt: "A sunlit creative studio with books, artwork, and a writing desk",
   }),
   showBrandText: true,
+  // The icon row between the bottom content and the bottom links. A label is
+  // the link's text; without one the platform's name is read out.
+  socialLinks: Object.freeze([
+    Object.freeze({
+      id: "7c1f3a52-9d4e-4b8a-8f1e-2a6c9d0e4b11",
+      platform: "instagram",
+      url: "https://www.instagram.com/examplestudio",
+      label: "Example Studio on Instagram",
+    }),
+  ]),
 });

package/src/footer-draft-hash.js

@@ -88,7 +88,7 @@ export function stableJson(value) {
 // the canonical form.
 export function computeFooterDraftHash(settings = {}) {
   const canonical = [];
-  append(canonical, "footer-draft-v3");
+  append(canonical, "footer-draft-v4");
   append(canonical, settings.enabled === true);
   append(canonical, settings.showBrand ?? true);
   append(canonical, settings.showBrandText ?? true);
@@ -113,6 +113,7 @@ export function computeFooterDraftHash(settings = {}) {
   if (hasAsideCta) appendLink(canonical, settings.asideCta);
   appendRichText(canonical, settings.bottomContent);
   appendLinks(canonical, settings.bottomLinks);
+  appendSocialLinks(canonical, settings.socialLinks);
   appendScheme(canonical, settings.light);
   appendScheme(canonical, settings.dark);
 
@@ -132,6 +133,18 @@ function appendLinks(canonical, rawLinks) {
   for (const link of links) appendLink(canonical, link);
 }
 
+function appendSocialLinks(canonical, rawLinks) {
+  const links = Array.isArray(rawLinks) ? rawLinks : [];
+  append(canonical, links.length);
+  for (const rawLink of links) {
+    const link = rawLink ?? {};
+    append(canonical, normalizeId(link.id));
+    append(canonical, link.platform ?? "");
+    append(canonical, link.url ?? "");
+    append(canonical, link.label ?? "");
+  }
+}
+
 // Coalesce rather than default so the canonical form stays total even for a
 // null entry: a parameter default covers only undefined.
 function appendLink(canonical, rawLink) {

package/src/presentation-reference.js

@@ -35,6 +35,8 @@ import {
   FOOTER_FIELD_INVENTORY,
   FOOTER_LIMITS,
   FOOTER_READ_ONLY_FIELDS,
+  SOCIAL_LINK_URL_REQUIREMENT,
+  SOCIAL_PLATFORM_KEYS,
   validateFooterDocument,
 } from "./footer-contract.js";
 import {
@@ -589,6 +591,11 @@ const FOOTER_FIELD_DETAILS = Object.freeze({
     maximumParagraphs: FOOTER_LIMITS.richTextParagraphs,
   },
   "FooterSettings.bottomLinks": { type: "FooterLink[]", default: [], maximumItems: FOOTER_LIMITS.bottomLinks },
+  "FooterSettings.socialLinks": {
+    type: "FooterSocialLink[]",
+    default: [],
+    maximumItems: FOOTER_LIMITS.socialLinks,
+  },
   "FooterSettings.light": { type: "FooterSchemeSettings", default: "scheme defaults" },
   "FooterSettings.dark": { type: "FooterSchemeSettings", default: "scheme defaults" },
   "FooterSettings.featureImage": { type: "FooterFeatureImageSettings|null", default: null },
@@ -609,6 +616,14 @@ const FOOTER_FIELD_DETAILS = Object.freeze({
     exclusiveWith: "pageResourceId",
     maximumLength: FOOTER_LIMITS.externalUrlLength,
   },
+  "FooterSocialLink.id": { type: "canonical-lowercase-uuid", required: true },
+  "FooterSocialLink.platform": { type: "social-platform-key", required: true, values: SOCIAL_PLATFORM_KEYS },
+  "FooterSocialLink.url": { type: "https-url", required: true, maximumLength: FOOTER_LIMITS.externalUrlLength },
+  "FooterSocialLink.label": {
+    type: "plain-text",
+    requiredWhen: "platform is other",
+    maximumLength: FOOTER_LIMITS.linkLabelLength,
+  },
   "FooterRichText.paragraphs": { type: "FooterRichTextParagraph[]", default: [] },
   "FooterRichTextParagraph.runs": { type: "FooterRichTextRun[]", default: [] },
   "FooterRichTextRun.text": { type: "string", required: true },
@@ -703,6 +718,12 @@ export function getFooterReference() {
       "Each link has exactly one target: a tracked pageResourceId, or an externalUrl that is an absolute "
       + "credential-free http/https URL, or a mailto:/tel: contact URL such as tel:+15555550123. A contact URL is "
       + "published exactly as authored, so write the number the way it should be dialled.",
+    socialLinkRule:
+      "Each social link names a platform key (" + SOCIAL_PLATFORM_KEYS.join(", ") + ") and a url that "
+      + SOCIAL_LINK_URL_REQUIREMENT + ". The label is the link's text and what screen readers announce; "
+      + "leave it empty to use the platform's name, and give one to every other (Website) link. Domain names "
+      + "with accented or non-English letters are not supported here; use a bottom link for that site. "
+      + "The row renders between the bottom content and the bottom links.",
     imageRule:
       "Image ids come from pull or media upload. Feature images require alt text; background art is decorative.",
     readOnlyProjections: FOOTER_READ_ONLY_FIELDS,
@@ -837,7 +858,8 @@ export function formatPresentationReference(reference) {
     ).join("\n\n");
     return reference.title + "\nUsage: " + reference.usage + "\nWorkspace: "
       + reference.workspaceFile + " :: " + reference.workspacePath + "\n\nClosed schema:\n"
-      + messages + "\n\nTargets: " + reference.targetRule + "\nImages: " + reference.imageRule
+      + messages + "\n\nTargets: " + reference.targetRule + "\nSocial links: " + reference.socialLinkRule
+      + "\nImages: " + reference.imageRule
       + "\nConcurrency: " + reference.concurrency
       + "\nTheme interaction: " + reference.themeInteraction + "\nRead-only projections: "
       + reference.readOnlyProjections.join(", ") + "\n\nWorkflow:\n"

package/src/reference-help.js

@@ -95,7 +95,7 @@ import {
 
 export { getAppearanceReference, getFooterReference, getSettingsReference, getThemeReference };
 
-export const REFERENCE_VERSION = 45;
+export const REFERENCE_VERSION = 48;
 
 // The date-limit examples `help forms` prints; tests run them through the form validator.
 export const FORM_DATE_WINDOW_FIELD = Object.freeze({
@@ -755,7 +755,7 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "those away, so '/x/../visit' would be checked as itself and served as '/visit' — past the occupancy, "
       + "chain, and loop rules that were asked about a different path. Write the resolved path instead.",
       "origin is reported by the site and ignored on push: 'authored' is what you declared, 'path_history' is "
-      + "what a page or tag rename recorded. Pull the map, edit it, push the whole thing back — an entry you "
+      + "what a page rename recorded. Pull the map, edit it, push the whole thing back — an entry you "
       + "did not change keeps its origin.",
       "Refused, offline and again at the site, each naming the entry index: a chain (a target that is itself a "
       + "source in the same map); a loop (an entry targeting itself); a duplicate path; a gone entry carrying a "
@@ -786,7 +786,8 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "check does not see may belong to a release the edge has not switched to yet; deploy --staging waits for "
       + "staging to serve the new release and reports stagingServed.",
       "A source cannot name a file the site generates: '/index.html' or any page's own 'index.html', '/404.html', "
-      + "'/sitemap.xml', '/robots.txt', '/favicon.ico', a path under the sitemap or robots names, or the "
+      + "'/sitemap.xml', '/robots.txt', '/favicon.ico', the published archive's data files ('/published/months.json' "
+      + "and '/published/<year>/<month>.json'), the map page's data file ('/map/places.json'), a path under any of those names, or the "
       + "search-engine key file Taproot publishes when a site tells search engines about its releases (32 "
       + "lowercase hexadecimal characters followed by '.txt', in any capitals). Nothing under "
       + "'/taproot/<version>/' (for example '/taproot/5.0.62/manifest.json') can be a source either: the platform "
@@ -870,8 +871,8 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "refused as forms.page_not_found, so push the page first. It need not be published to save the form, but "
       + "a deploy whose release does not publish that page is refused, naming the form and the page. The path in "
       + "each release is the one the page has in that release, so the published form never asks the site where "
-      + "to go. The page must be one you created, the home page included: a generated page (folder, tag or "
-      + "archive index), the 404 page, a legal page (help page legal), a profile home and an integration-managed page are refused as forms.page_not_allowed. The button text and the confirmation belong to the form, not to the page that places it: "
+      + "to go. The page must be one you created, the home page included: a generated page (a folder index or "
+      + "the published archive), the 404 page, a legal page (help page legal), a profile home and an integration-managed page are refused as forms.page_not_allowed. The button text and the confirmation belong to the form, not to the page that places it: "
       + "the 'form' component takes only formKey.",
       "A form's contact address is the value of one email field, stored with each submission. That is what lets the "
       + "owner find and delete every row for a visitor who asks. With exactly one email field, that field is the "
@@ -1937,6 +1938,7 @@ function schemaConstraints(schema) {
   const constraints = [];
   if (schema.minimum !== undefined) constraints.push(`minimum ${schema.minimum}`);
   if (schema.maximum !== undefined) constraints.push(`maximum ${schema.maximum}`);
+  if (schema.minItems !== undefined) constraints.push(`minimum ${schema.minItems} items`);
   if (schema.maxItems !== undefined) constraints.push(`maximum ${schema.maxItems} items`);
   if (schema.minLength !== undefined) constraints.push(`minimum length ${schema.minLength}`);
   if (schema.maxLength !== undefined) constraints.push(`maximum length ${schema.maxLength}`);
@@ -1952,7 +1954,12 @@ function schemaConstraints(schema) {
 
 function formatSchemaLine(name, schema, required, indent) {
   const constraints = schemaConstraints(schema);
-  const label = schema.markdownType ? "media path | null in Markdown; object | null in .pm.json" : schemaLabel(schema);
+  // A required image (TR01322) takes no null in either form.
+  const label = schema.markdownType
+    ? Array.isArray(schema.type)
+      ? "media path | null in Markdown; object | null in .pm.json"
+      : "media path in Markdown; object in .pm.json"
+    : schemaLabel(schema);
   return `${indent}${name.padEnd(Math.max(1, 28 - indent.length))} ${label}; ${
     required ? "required" : "optional"
   }${constraints.length > 0 ? `; ${constraints.join("; ")}` : ""}`;

package/src/site-checks.js

@@ -159,7 +159,9 @@ function addHtmlLinks(links, html, currentPagePath) {
 }
 function isUrlProperty(name) {
     const lower = name.toLowerCase();
-    return lower === "href" || lower === "url" || lower === "link" || lower === "pagepath";
+    // Component buttons and cards (cta, card-grid, product-grid; TR01323).
+    return lower === "href" || lower === "url" || lower === "link" || lower === "pagepath"
+        || lower === "buttonurl" || lower === "linkurl";
 }
 function addEncodedComponentLinks(links, value, currentPagePath) {
     const decoded = htmlDecodeRepeatedly(value);
@@ -282,6 +284,13 @@ export function normalizeRedirectPath(value) {
 const GENERATED_ROOT_FILES = ["404.html", "sitemap.xml", "robots.txt", "favicon.ico"];
 // The IndexNow key file (TR01304) is named by a pattern, so it cannot join the list above.
 const INDEX_NOW_KEY_FILE = /^[a-f0-9]{32}\.txt$/u;
+// The /published archive's data files (TR01309): months.json and yyyy/mm.json, with anything beneath either;
+// a marker at one of those names fails every publish in the generator's occupancy check. The API mirror is
+// SiteRedirectMap.IsPublishedArchiveDataPath.
+const PUBLISHED_ARCHIVE_ROOT = "published";
+const ARCHIVE_MONTHS_FILE = "months.json";
+const ARCHIVE_YEAR_SEGMENT = /^\d{4}$/u;
+const ARCHIVE_MONTH_FILE = /^\d{2}\.json$/iu;
 const INTEGRATION_DATA_ROOT = "integrations";
 const MAX_MARKER_SEGMENT_BYTES = 200;
 const MAX_OUTPUT_PATH_LENGTH = 1_024;
@@ -290,6 +299,18 @@ function isWindowsDeviceSegment(segment) {
     const stem = segment.split(".", 1)[0].toLowerCase();
     return WINDOWS_DEVICE_STEMS.has(stem) || /^(?:com|lpt)[1-9]$/u.test(stem);
 }
+function isPublishedArchiveDataPath(segments) {
+    if (segments.length < 2 || segments[0].toLowerCase() !== PUBLISHED_ARCHIVE_ROOT)
+        return false;
+    if (segments[1].toLowerCase() === ARCHIVE_MONTHS_FILE)
+        return true;
+    return segments.length >= 3 && ARCHIVE_YEAR_SEGMENT.test(segments[1]) && ARCHIVE_MONTH_FILE.test(segments[2]);
+}
+// The /map page's data file (TR01321), with anything beneath it, for the same reason.
+// The API mirrors this in SiteRedirectMap.IsPlaceMapDataPath.
+function isPlaceMapDataPath(segments) {
+    return segments.length >= 2 && segments[0].toLowerCase() === "map" && segments[1].toLowerCase() === "places.json";
+}
 function isStorable(decoded) {
     const output = `${decoded}/index.html`;
     if (output !== output.normalize("NFC") || output.length > MAX_OUTPUT_PATH_LENGTH || output.startsWith("/")
@@ -319,7 +340,9 @@ export function redirectSourceRule(edgePath) {
         return refuse(RULE_REDIRECT_SOURCE_INTEGRATION_DATA);
     if (isRuntimeMirrorPath(decoded))
         return refuse(RULE_REDIRECT_SOURCE_RUNTIME_MIRROR);
-    if (GENERATED_ROOT_FILES.includes(first.toLowerCase()) || INDEX_NOW_KEY_FILE.test(first.toLowerCase())) {
+    if (GENERATED_ROOT_FILES.includes(first.toLowerCase()) || INDEX_NOW_KEY_FILE.test(first.toLowerCase())
+        || isPublishedArchiveDataPath(segments)
+        || isPlaceMapDataPath(segments)) {
         return refuse(RULE_REDIRECT_SOURCE_GENERATED_FILE);
     }
     if (!isStorable(decoded))

package/src/social-link-url.js

@@ -0,0 +1,160 @@
+// Generated from shared/social-link-url.ts by scripts/sync-field-validation.mjs. Do not edit.
+/**
+ * The one owner of which addresses a social link accepts (TR01324).
+ *
+ * A social link is an absolute https URL to a plain domain name. The rule is
+ * literal on purpose: every verdict a URL parser might decide differently in
+ * JavaScript and .NET (case folding, IDNA mapping, IPv4 shorthand, length
+ * limits, whitespace) is decided here by explicit character checks first, and
+ * the parser is only asked whether what remains parses at all. That keeps the
+ * CLI, the generator, the editor and the API's own port in agreement, which
+ * `shared/social-link-url-corpus.json` proves in each of them.
+ *
+ * It is pure and dependency-free. The generator and the site-authoring CLI
+ * cannot import this file, so `node scripts/sync-field-validation.mjs` writes
+ * their copies; edit only this file and re-run it. The editor imports it by
+ * relative path.
+ */
+/** The longest address stored anywhere a social link lives. */
+export const SOCIAL_LINK_URL_MAX_LENGTH = 2048;
+/**
+ * The whitespace a social link may not contain and a typed value is trimmed
+ * of: the .NET `char.IsWhiteSpace` set, which the footer's single-line
+ * normalisation already mirrors, plus U+FEFF, which JavaScript's `trim` strips
+ * and .NET's does not.
+ */
+export function isSocialLinkWhiteSpace(codeUnit) {
+    return (codeUnit >= 0x0009 && codeUnit <= 0x000d)
+        || codeUnit === 0x0020
+        || codeUnit === 0x0085
+        || codeUnit === 0x00a0
+        || codeUnit === 0x1680
+        || (codeUnit >= 0x2000 && codeUnit <= 0x200a)
+        || codeUnit === 0x2028
+        || codeUnit === 0x2029
+        || codeUnit === 0x202f
+        || codeUnit === 0x205f
+        || codeUnit === 0x3000
+        || codeUnit === 0xfeff;
+}
+/** Strips the whitespace set above from both ends; what a typed address is judged on. */
+export function trimSocialLinkInput(value) {
+    let start = 0;
+    let end = value.length;
+    while (start < end && isSocialLinkWhiteSpace(value.charCodeAt(start)))
+        start += 1;
+    while (end > start && isSocialLinkWhiteSpace(value.charCodeAt(end - 1)))
+        end -= 1;
+    return value.slice(start, end);
+}
+/**
+ * Control characters, the backslash, and the default-ignorable and format
+ * code points that can hide inside an address; none has a place in a link.
+ */
+function isRefusedCodeUnit(codeUnit) {
+    return codeUnit <= 0x001f
+        || (codeUnit >= 0x007f && codeUnit <= 0x009f)
+        || codeUnit === 0x005c
+        || codeUnit === 0x00ad
+        || codeUnit === 0x034f
+        || (codeUnit >= 0x200b && codeUnit <= 0x200f)
+        || (codeUnit >= 0x202a && codeUnit <= 0x202e)
+        || (codeUnit >= 0x2060 && codeUnit <= 0x206f)
+        || (codeUnit >= 0xfe00 && codeUnit <= 0xfe0f)
+        || codeUnit >= 0xfff0;
+}
+/** Folds only A to Z, so no runtime's case mapping (U+212A to k, U+0130) can reach a verdict; the editors' field copy reads it too. */
+export function asciiLower(value) {
+    let result = "";
+    for (let index = 0; index < value.length; index += 1) {
+        const codeUnit = value.charCodeAt(index);
+        result += codeUnit >= 0x41 && codeUnit <= 0x5a ? String.fromCharCode(codeUnit + 0x20) : value[index];
+    }
+    return result;
+}
+const LABEL_RE = /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/;
+/** A final label that is a number in decimal or hex makes the host an IPv4 form, which is refused. */
+const NUMERIC_FINAL_LABEL_RE = /^(?:[0-9]+|0[xX][0-9a-fA-F]*)$/;
+const PORT_RE = /^[0-9]+$/;
+const HOST_MAX_LENGTH = 253;
+const LABEL_MAX_LENGTH = 63;
+function isAcceptedAuthority(authority) {
+    if (authority.length === 0)
+        return false;
+    for (let index = 0; index < authority.length; index += 1) {
+        const codeUnit = authority.charCodeAt(index);
+        if (codeUnit > 0x7f)
+            return false;
+        const character = authority[index];
+        if (character === "@" || character === "%" || character === "_")
+            return false;
+    }
+    let host = authority;
+    const colon = authority.indexOf(":");
+    if (colon !== -1) {
+        host = authority.slice(0, colon);
+        const port = authority.slice(colon + 1);
+        if (!PORT_RE.test(port))
+            return false;
+        const portNumber = Number(port);
+        if (portNumber < 1 || portNumber > 65535)
+            return false;
+    }
+    if (host.length > HOST_MAX_LENGTH)
+        return false;
+    const labels = host.split(".");
+    if (labels.length < 2)
+        return false;
+    for (const label of labels) {
+        if (label.length < 1 || label.length > LABEL_MAX_LENGTH || !LABEL_RE.test(label))
+            return false;
+        if (asciiLower(label).startsWith("xn--"))
+            return false;
+    }
+    return !NUMERIC_FINAL_LABEL_RE.test(labels[labels.length - 1]);
+}
+/**
+ * Whether a value, exactly as written, is an address a social link accepts.
+ * Typed input is trimmed with `trimSocialLinkInput` first; a hand-written
+ * document is judged as it is.
+ */
+export function isSocialLinkUrl(value) {
+    if (typeof value !== "string" || value.length === 0 || value.length > SOCIAL_LINK_URL_MAX_LENGTH)
+        return false;
+    for (let index = 0; index < value.length; index += 1) {
+        const codeUnit = value.charCodeAt(index);
+        if (isSocialLinkWhiteSpace(codeUnit) || isRefusedCodeUnit(codeUnit))
+            return false;
+        if (codeUnit >= 0xd800 && codeUnit <= 0xdbff) {
+            const next = index + 1 < value.length ? value.charCodeAt(index + 1) : 0;
+            if (next < 0xdc00 || next > 0xdfff)
+                return false;
+            index += 1;
+        }
+        else if (codeUnit >= 0xdc00 && codeUnit <= 0xdfff) {
+            return false;
+        }
+    }
+    if (asciiLower(value.slice(0, 8)) !== "https://")
+        return false;
+    const rest = value.slice(8);
+    let authorityEnd = rest.length;
+    for (const terminator of ["/", "?", "#"]) {
+        const at = rest.indexOf(terminator);
+        if (at !== -1 && at < authorityEnd)
+            authorityEnd = at;
+    }
+    if (!isAcceptedAuthority(rest.slice(0, authorityEnd)))
+        return false;
+    try {
+        new URL(value);
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+/** The address as published: the parsed form, as the footer emits its own links. */
+export function socialLinkHref(value) {
+    return new URL(value).toString();
+}

package/src/social-platforms.json

@@ -0,0 +1,16 @@
+{
+  "platforms": [
+    { "key": "instagram", "name": "Instagram", "icon": "brand-instagram" },
+    { "key": "facebook", "name": "Facebook", "icon": "brand-facebook" },
+    { "key": "yelp", "name": "Yelp", "icon": "brand-yelp" },
+    { "key": "youtube", "name": "YouTube", "icon": "brand-youtube" },
+    { "key": "tiktok", "name": "TikTok", "icon": "brand-tiktok" },
+    { "key": "linkedin", "name": "LinkedIn", "icon": "brand-linkedin" },
+    { "key": "x", "name": "X", "icon": "brand-x" },
+    { "key": "threads", "name": "Threads", "icon": "brand-threads" },
+    { "key": "bluesky", "name": "Bluesky", "icon": "brand-bluesky" },
+    { "key": "mastodon", "name": "Mastodon", "icon": "brand-mastodon" },
+    { "key": "pinterest", "name": "Pinterest", "icon": "brand-pinterest" },
+    { "key": "other", "name": "Website", "icon": "external-link" }
+  ]
+}

package/src/typed-page-reference.js

@@ -77,7 +77,7 @@ const FIELD_HELP = Object.freeze({
     description:
       "The Taproot place being reviewed. The site fills in its name, address and coordinates from this record. Find "
       + "it with 'places search <name and city>' and 'places select <googlePlaceId> <sessionToken>'. The site publishes the "
-      + "place's category in the byline and files the review under /places/<category>; change it for this site with "
+      + "place's category in the byline; change it for this site with "
       + "'places category set <placeId> <category>'.",
   },
   place: {
@@ -263,7 +263,7 @@ const TYPE_DETAILS = Object.freeze({
   },
   [TEMPLATE_PLACE_REVIEW]: {
     displayName: "Place review",
-    summary: "A review of a place with a three-step rating, listed on the site's places archive.",
+    summary: "A review of a place with a three-step rating; its address card opens the place on Google Maps, and its location byline opens the site's map page when it has one.",
     body: "Everything after the front matter is the review body.",
     markdownExample: PLACE_REVIEW_EXAMPLE,
     documentExample: documentExample(
@@ -284,20 +284,14 @@ const TYPE_DETAILS = Object.freeze({
   [TEMPLATE_GENERATED]: {
     displayName: "Generated page",
     summary:
-      "A listing Taproot generates from the site's content: a tag, the tags index, a published year or month, a place "
-      + "archive, or a folder. You cannot create one; you customize its title, breadcrumb, description and introduction.",
+      "A listing Taproot generates from the site's content: the published archive, the map or a folder. You cannot create "
+      + "one; you customize its title, breadcrumb, description and introduction. A folder index is a search "
+      + "destination when it has an introduction or renders at least three cards; otherwise it carries noindex.",
     documentExample: documentExample(
       TEMPLATE_GENERATED,
       {},
       {
-        kind: "GENERATED_PAGE_KIND_TAG",
-        tagId: "0198a3f2-7c4e-4a10-9b2d-3f6e5d4c3b2a",
-        year: 0,
-        month: 0,
-        countryCode: "",
-        regionCode: "",
-        citySlug: "",
-        categorySlug: "",
+        kind: "GENERATED_PAGE_KIND_FOLDER_INDEX",
         customTitle: "Trail notes",
         breadcrumbTitle: "",
         customDescription: "Field notes from the trails I walk most often.",
@@ -305,8 +299,7 @@ const TYPE_DETAILS = Object.freeze({
       },
     ),
     dataFields: [
-      "kind and the identity fields (tagId, year, month, countryCode, regionCode, citySlug, categorySlug): what the "
-      + "page is, written by pull. Leave them as pulled; a push that changes them is refused (pages.generated_identity)",
+      "kind: what the page is, written by pull. Leave it as pulled; a push that changes it is refused (pages.generated_identity)",
       "customTitle: string; empty uses the generated title (the page's reader-facing title)",
       "breadcrumbTitle: string; empty uses the generated label (used on pages beneath this one)",
       "customDescription: string, at most 1000 characters, about 160 shown in search results; empty uses the "

package/src/typed-pages.js

@@ -32,7 +32,7 @@ export const TEMPLATE_ALBUM = "album";
 export const TEMPLATE_PLACE_REVIEW = "place-review";
 export const TEMPLATE_LEGAL = "legal";
 /**
- * A page Taproot generates (a tag, a month, a folder). It is update-only: the
+ * A page Taproot generates (the published archive, the map or a folder). It is update-only: the
  * owner's title, breadcrumb, description and introduction are authored, and
  * pages push refuses to create one or to change what it is (TR01195).
  */
@@ -111,9 +111,18 @@ const RECIPE_HEADINGS = Object.freeze(["ingredients", "instructions"]);
 
 /** The generated page kinds the site reports, as the API names them (never the unknown kind). */
 export const GENERATED_PAGE_KINDS = Object.freeze([
+  "GENERATED_PAGE_KIND_PUBLISHED_INDEX",
+  "GENERATED_PAGE_KIND_FOLDER_INDEX",
+  "GENERATED_PAGE_KIND_MAP_INDEX",
+]);
+/**
+ * The kinds Taproot no longer generates (TR01308, TR01309, TR01310), which an older
+ * pull may have written. Named, so a typo or the unknown kind is refused as a bad
+ * document and is never mistaken for a page Taproot retired.
+ */
+export const RETIRED_GENERATED_PAGE_KINDS = Object.freeze([
   "GENERATED_PAGE_KIND_TAG",
   "GENERATED_PAGE_KIND_TAGS_INDEX",
-  "GENERATED_PAGE_KIND_PUBLISHED_INDEX",
   "GENERATED_PAGE_KIND_PUBLISHED_YEAR",
   "GENERATED_PAGE_KIND_PUBLISHED_MONTH",
   "GENERATED_PAGE_KIND_PLACES_INDEX",
@@ -121,18 +130,10 @@ export const GENERATED_PAGE_KINDS = Object.freeze([
   "GENERATED_PAGE_KIND_PLACES_STATE",
   "GENERATED_PAGE_KIND_PLACES_CITY",
   "GENERATED_PAGE_KIND_PLACES_CATEGORY",
-  "GENERATED_PAGE_KIND_FOLDER_INDEX",
 ]);
 /** What a generated page is: system-managed, so a push must send it back unchanged. */
 export const GENERATED_IDENTITY_KEYS = Object.freeze([
   "kind",
-  "tagId",
-  "year",
-  "month",
-  "countryCode",
-  "regionCode",
-  "citySlug",
-  "categorySlug",
 ]);
 const GENERATED_KEYS = [
   ...GENERATED_IDENTITY_KEYS,
@@ -142,17 +143,10 @@ const GENERATED_KEYS = [
   "introductionBody",
 ];
 const GENERATED_TEXT_KEYS = [
-  "tagId",
-  "countryCode",
-  "regionCode",
-  "citySlug",
-  "categorySlug",
   "customTitle",
   "breadcrumbTitle",
   "customDescription",
 ];
-const GENERATED_MAXIMUM_YEAR = 9999;
-const GENERATED_MAXIMUM_MONTH = 12;
 const EMPTY_DOCUMENT = Object.freeze({ type: "doc", content: Object.freeze([]) });
 
 function fail(code, message, field) {
@@ -368,13 +362,6 @@ const DATA_BUILDERS = Object.freeze({
   [TEMPLATE_GENERATED]: (raw) =>
     definedEntries([
       ["kind", raw.kind],
-      ["tagId", raw.tagId ?? ""],
-      ["year", raw.year ?? 0],
-      ["month", raw.month ?? 0],
-      ["countryCode", raw.countryCode ?? ""],
-      ["regionCode", raw.regionCode ?? ""],
-      ["citySlug", raw.citySlug ?? ""],
-      ["categorySlug", raw.categorySlug ?? ""],
       ["customTitle", raw.customTitle ?? ""],
       ["breadcrumbTitle", raw.breadcrumbTitle ?? ""],
       ["customDescription", raw.customDescription ?? ""],
@@ -479,9 +466,6 @@ function canonicalSourceData(template, data, file) {
     for (const key of GENERATED_TEXT_KEYS) {
       if (data[key] !== undefined) requireString(data[key], file, `${path}.${key}`);
     }
-    if (data.tagId !== undefined && data.tagId !== "") requireIdentifier(data.tagId, file, `${path}.tagId`);
-    if (data.year !== undefined) requireCount(data.year, file, `${path}.year`, GENERATED_MAXIMUM_YEAR);
-    if (data.month !== undefined) requireCount(data.month, file, `${path}.month`, GENERATED_MAXIMUM_MONTH);
     // The API trims a description, so the length that counts is the trimmed one.
     const customDescription = data.customDescription?.trim();
     requireDescriptionLength(customDescription, `${file}:${path}.customDescription`);
@@ -658,8 +642,6 @@ const PAGE_PROJECTIONS = Object.freeze({
       ? DATA_BUILDERS[TEMPLATE_GENERATED]({
         kind: raw.kind,
         ...Object.fromEntries(GENERATED_TEXT_KEYS.map((key) => [key, typeof raw[key] === "string" ? raw[key] : ""])),
-        year: Number.isSafeInteger(raw.year) ? raw.year : 0,
-        month: Number.isSafeInteger(raw.month) ? raw.month : 0,
         introductionBody: presentIntroduction(raw.introductionBody),
       })
       : undefined,