@taprootio/site-authoring 0.12.7 → 0.13.0

package/src/content/tiptap-prosemirror.ts

@@ -8,8 +8,16 @@
  */
 
 import freeFormSectionRegistry from "./free-form-section-registry.json" with { type: "json" };
+import {
+  explicitImageMaxHeight,
+  mediaOverrideStyleParts,
+  normalizeBorderWidthOverride,
+  normalizeCssLengthOverride,
+  normalizeMaxHeightOverride,
+  TIPTAP_SITE_DEFAULT,
+  type TiptapImageMaxHeightVh,
+} from "./media-presentation.js";
 
-export const TIPTAP_SITE_DEFAULT = "site-default";
 export const DEFAULT_TIPTAP_IMAGE_MAX_IMAGES_PER_ROW = 2;
 export const TIPTAP_IMAGE_MAX_IMAGES_PER_ROW_OPTIONS = [1, 2, 3] as const;
 export const TIPTAP_IMAGE_NARROW_CONTENT_REM = 40;
@@ -21,15 +29,11 @@ export function normalizeTiptapImageMaxImagesPerRow(value: unknown): number {
     : DEFAULT_TIPTAP_IMAGE_MAX_IMAGES_PER_ROW;
 }
 
-export const DEFAULT_TIPTAP_IMAGE_MAX_HEIGHT_VH = 60;
-export const TIPTAP_IMAGE_MAX_HEIGHT_OPTIONS = [45, 60, 75, 90] as const;
 const SECTION_CONTEXT_PATTERN = new RegExp(
   freeFormSectionRegistry.section.attrs.context.pattern,
   "u",
 );
 
-export type TiptapSiteDefault = typeof TIPTAP_SITE_DEFAULT;
-export type TiptapImageMaxHeightVh = typeof TIPTAP_IMAGE_MAX_HEIGHT_OPTIONS[number];
 export type TiptapImagePresentationPlacement =
   | "left"
   | "left-text-right"
@@ -1202,13 +1206,11 @@ function resolveImagePresentation(
   defaults: RenderProseMirrorOptions["imageDefaults"],
 ): Record<string, string | number | undefined> {
   const explicitMaxHeight = explicitImageMaxHeight(attrs.maxHeightVh);
-  const maxHeightOverride = normalizeCssLengthOverride(attrs.maxHeight, { allowNone: true });
-  const borderWidthOverride = normalizeCssLengthOverride(attrs.borderWidth);
+  const maxHeightOverride = normalizeMaxHeightOverride(attrs.maxHeight);
+  const borderWidthOverride = normalizeBorderWidthOverride(attrs.borderWidth);
   const placement = resolvePlacement(attrs, defaults?.placement);
   const placementAttrs = imagePresentationAttributesForPlacement(placement);
-  const styleParts: string[] = [];
-  if (maxHeightOverride) styleParts.push(`--taproot-article-image-max-height: ${maxHeightOverride}`);
-  if (borderWidthOverride) styleParts.push(`--esp-image-border: ${imageBorderValue(borderWidthOverride)}`);
+  const styleParts = mediaOverrideStyleParts({ maxHeight: maxHeightOverride, borderWidth: borderWidthOverride });
   return {
     "data-tiptap-image": normalizeTiptapImageMaxImagesPerRow(defaults?.maxImagesPerRow),
     // The page shell owns the inherited site default so HTML and structured
@@ -1226,11 +1228,6 @@ function resolveImagePresentation(
   };
 }
 
-function explicitImageMaxHeight(value: unknown): TiptapImageMaxHeightVh | null {
-  if (value === TIPTAP_SITE_DEFAULT || value === undefined || value === null) return null;
-  return isImageMaxHeightOption(value) ? imageMaxHeightOption(value) : null;
-}
-
 function resolvePlacement(
   attrs: Record<string, JsonValue | undefined>,
   defaultValue: unknown,
@@ -1257,55 +1254,6 @@ function isAbsentPresentationValue(value: unknown): boolean {
   return value === undefined || value === null;
 }
 
-export function normalizeImageMaxHeight(value: unknown): TiptapImageMaxHeightVh {
-  return isImageMaxHeightOption(value) ? imageMaxHeightOption(value) : DEFAULT_TIPTAP_IMAGE_MAX_HEIGHT_VH;
-}
-
-function isImageMaxHeightOption(value: unknown): boolean {
-  return TIPTAP_IMAGE_MAX_HEIGHT_OPTIONS.includes(imageMaxHeightOption(value));
-}
-
-function imageMaxHeightOption(value: unknown): TiptapImageMaxHeightVh {
-  return (typeof value === "number" ? value : Number(value)) as TiptapImageMaxHeightVh;
-}
-
-const CSS_LENGTH_UNITS = "px|em|rem|ch|ex|vw|vh|svh|lvh|dvh|svw|lvw|dvw|vmin|vmax|%";
-const CSS_LENGTH_RE = new RegExp(`^\\d+(?:\\.\\d+)?(?:${CSS_LENGTH_UNITS})$`, "i");
-const CSS_VAR_RE = /^var\(--[a-z0-9-]+\)$/i;
-const CSS_CALC_TERM = `(?:\\d+(?:\\.\\d+)?(?:${CSS_LENGTH_UNITS})|\\d+(?:\\.\\d+)?|var\\(--[a-z0-9-]+\\))`;
-const CSS_CALC_RE = new RegExp(
-  `^calc\\(\\s*${CSS_CALC_TERM}(?:\\s*[+\\-*/]\\s*${CSS_CALC_TERM})*\\s*\\)$`,
-  "i",
-);
-
-/**
- * Validate a user-supplied CSS length for per-image presentation overrides
- * (max height, border width). These values are emitted into inline styles on
- * published pages, so anything outside this strict grammar is rejected:
- * unitless `0`, a non-negative length, `var(--token)`, `calc(...)` of those
- * terms, and — when `allowNone` is set — the `none` keyword (max-height).
- * Returns the trimmed value, or null when invalid or set to the site default.
- */
-export function normalizeCssLengthOverride(
-  value: unknown,
-  options?: { allowNone?: boolean },
-): string | null {
-  if (typeof value !== "string") return null;
-  const trimmed = value.trim();
-  if (!trimmed || trimmed === TIPTAP_SITE_DEFAULT) return null;
-  if (trimmed === "0") return trimmed;
-  if (options?.allowNone && trimmed.toLowerCase() === "none") return "none";
-  if (CSS_LENGTH_RE.test(trimmed)) return trimmed;
-  if (CSS_VAR_RE.test(trimmed)) return trimmed;
-  if (CSS_CALC_RE.test(trimmed)) return trimmed;
-  return null;
-}
-
-/** CSS value for the esp-image border hook given a width; zero collapses to none. */
-export function imageBorderValue(width: string): string {
-  return /^0(?:\.0+)?(?:[a-z%]+)?$/i.test(width) ? "none" : `${width} solid var(--esp-color-border)`;
-}
-
 export function normalizeImagePresentationPlacement(value: unknown): TiptapImagePresentationPlacement {
   switch (value) {
     case "left":

package/src/content/video-embed-url.js

@@ -0,0 +1,104 @@
+// Generated from shared/video-embed-url.ts by scripts/sync-field-validation.mjs. Do not edit.
+/**
+ * The one owner of which video links the embed card accepts.
+ *
+ * A link is reduced to a provider and an id when it is authored, and only that
+ * pair is stored. Every player URL is built here from the validated pair, never
+ * from the text an author pasted. Anything that is not a YouTube watch, share,
+ * Shorts or embed link, or a Vimeo video link, is refused.
+ *
+ * It is pure and dependency-free. The generator, the editor and the
+ * site-authoring CLI cannot all import this file, so
+ * `node scripts/sync-field-validation.mjs` writes their copies; edit only this
+ * file and re-run it. `shared/video-embed-url-corpus.json` is the evidence
+ * every copy agrees.
+ */
+export const VIDEO_EMBED_PROVIDERS = ["youtube", "vimeo"];
+/** The one line shown for any link that is not accepted. */
+export const VIDEO_EMBED_REFUSAL = "Use a YouTube or Vimeo video link, such as youtube.com/watch?v=… or vimeo.com/123456789.";
+/** The origin each provider's player loads from; a page with an embed may frame exactly these. */
+export const VIDEO_EMBED_FRAME_ORIGINS = {
+    youtube: "https://www.youtube-nocookie.com",
+    vimeo: "https://player.vimeo.com",
+};
+const YOUTUBE_ID = /^[A-Za-z0-9_-]{11}$/u;
+/** Two 11-character path segments of `/embed/` links that are playlists and live streams, not video ids. */
+const YOUTUBE_NON_VIDEO_IDS = new Set(["videoseries", "live_stream"]);
+const VIMEO_ID = /^[1-9][0-9]{0,11}$/u;
+const YOUTUBE_HOSTS = new Set([
+    "youtube.com",
+    "www.youtube.com",
+    "m.youtube.com",
+    "youtube-nocookie.com",
+    "www.youtube-nocookie.com",
+]);
+const VIMEO_HOSTS = new Set(["vimeo.com", "www.vimeo.com"]);
+export function isVideoEmbedProvider(value) {
+    return value === "youtube" || value === "vimeo";
+}
+export function isVideoEmbedId(provider, videoId) {
+    if (typeof videoId !== "string")
+        return false;
+    if (provider === "youtube")
+        return YOUTUBE_ID.test(videoId) && !YOUTUBE_NON_VIDEO_IDS.has(videoId);
+    if (provider === "vimeo")
+        return VIMEO_ID.test(videoId);
+    return false;
+}
+/** The player URL for a validated provider and id, or an empty string when either is not valid. */
+export function videoEmbedPlayerUrl(provider, videoId) {
+    if (!isVideoEmbedProvider(provider) || !isVideoEmbedId(provider, videoId))
+        return "";
+    return provider === "youtube"
+        ? `${VIDEO_EMBED_FRAME_ORIGINS.youtube}/embed/${videoId}?autoplay=1`
+        : `${VIDEO_EMBED_FRAME_ORIGINS.vimeo}/video/${videoId}?dnt=1&autoplay=1`;
+}
+/** Reduces an accepted video link to its provider and id; every other value gives `null`. */
+export function parseVideoEmbedUrl(input) {
+    if (typeof input !== "string")
+        return null;
+    const text = input.trim();
+    if (text === "" || text.length > 2048)
+        return null;
+    let url;
+    try {
+        url = new URL(text);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:")
+        return null;
+    if (url.username !== "" || url.password !== "" || url.port !== "")
+        return null;
+    const host = url.hostname.toLowerCase();
+    const pathname = url.pathname.length > 1 && url.pathname.endsWith("/") ? url.pathname.slice(0, -1) : url.pathname;
+    if (pathname.includes("//"))
+        return null;
+    const segments = pathname.slice(1).split("/");
+    if (host === "youtu.be") {
+        return segments.length === 1 ? target("youtube", segments[0]) : null;
+    }
+    if (YOUTUBE_HOSTS.has(host)) {
+        if (segments.length === 1 && segments[0] === "watch")
+            return target("youtube", url.searchParams.get("v"));
+        if (segments.length === 2 && (segments[0] === "shorts" || segments[0] === "embed")) {
+            return target("youtube", segments[1]);
+        }
+        return null;
+    }
+    // An unlisted Vimeo video needs its `h` privacy hash to play; only the id is
+    // stored, so a link that carries one is refused rather than saved broken.
+    if (VIMEO_HOSTS.has(host)) {
+        return segments.length === 1 && !url.searchParams.has("h") ? target("vimeo", segments[0]) : null;
+    }
+    if (host === "player.vimeo.com") {
+        return segments.length === 2 && segments[0] === "video" && !url.searchParams.has("h")
+            ? target("vimeo", segments[1])
+            : null;
+    }
+    return null;
+}
+function target(provider, videoId) {
+    return videoId !== null && videoId !== undefined && isVideoEmbedId(provider, videoId) ? { provider, videoId } : null;
+}

package/src/content/vocabulary.js

@@ -1,6 +1,11 @@
 import { isContactOrWebUrl } from "../contact-url.js";
 import { sanitizeDiagnostic } from "../errors.js";
 import freeFormSectionRegistry from "./free-form-section-registry.json" with { type: "json" };
+import {
+  normalizeCssLengthOverride,
+  TIPTAP_IMAGE_MAX_HEIGHT_OPTIONS,
+  TIPTAP_SITE_DEFAULT,
+} from "./media-presentation.js";
 
 /**
  * The primitives the content module shares: the accepted ProseMirror
@@ -186,11 +191,12 @@ export const CONTENT_LIMITS = Object.freeze({
 // Renderer-mirrored constants and predicates
 // ---------------------------------------------------------------------------
 
-/** `TIPTAP_SITE_DEFAULT` — the "no explicit choice" sentinel. */
-export const TIPTAP_SITE_DEFAULT = "site-default";
+// The sentinel, the max height options and the CSS length grammar are the
+// renderer's own, from the shared media presentation module.
+export { normalizeCssLengthOverride, TIPTAP_SITE_DEFAULT };
 
 /** `TIPTAP_IMAGE_MAX_HEIGHT_OPTIONS` — anything else normalises to 60 (silent). */
-export const IMAGE_MAX_HEIGHT_OPTIONS = Object.freeze([45, 60, 75, 90]);
+export const IMAGE_MAX_HEIGHT_OPTIONS = Object.freeze([...TIPTAP_IMAGE_MAX_HEIGHT_OPTIONS]);
 
 /** The canonical `TiptapImagePresentationPlacement` union. */
 export const IMAGE_PRESENTATION_PLACEMENTS = Object.freeze([
@@ -244,35 +250,6 @@ export function isSafeUrl(url) {
   }
 }
 
-// The renderer's CSS grammar, character for character. These values are
-// emitted into inline styles on published pages, which is why the grammar is
-// this narrow — and why a value outside it is dropped rather than escaped.
-const CSS_LENGTH_UNITS = "px|em|rem|ch|ex|vw|vh|svh|lvh|dvh|svw|lvw|dvw|vmin|vmax|%";
-const CSS_LENGTH_RE = new RegExp(`^\\d+(?:\\.\\d+)?(?:${CSS_LENGTH_UNITS})$`, "i");
-const CSS_VAR_RE = /^var\(--[a-z0-9-]+\)$/i;
-const CSS_CALC_TERM = `(?:\\d+(?:\\.\\d+)?(?:${CSS_LENGTH_UNITS})|\\d+(?:\\.\\d+)?|var\\(--[a-z0-9-]+\\))`;
-const CSS_CALC_RE = new RegExp(
-  `^calc\\(\\s*${CSS_CALC_TERM}(?:\\s*[+\\-*/]\\s*${CSS_CALC_TERM})*\\s*\\)$`,
-  "i",
-);
-
-/**
- * Mirrors the renderer's `normalizeCssLengthOverride`: returns the trimmed
- * value, or null when the value is invalid *or* is the site-default sentinel.
- * Callers that need to tell those two apart check the sentinel themselves.
- */
-export function normalizeCssLengthOverride(value, options) {
-  if (typeof value !== "string") return null;
-  const trimmed = value.trim();
-  if (!trimmed || trimmed === TIPTAP_SITE_DEFAULT) return null;
-  if (trimmed === "0") return trimmed;
-  if (options?.allowNone && trimmed.toLowerCase() === "none") return "none";
-  if (CSS_LENGTH_RE.test(trimmed)) return trimmed;
-  if (CSS_VAR_RE.test(trimmed)) return trimmed;
-  if (CSS_CALC_RE.test(trimmed)) return trimmed;
-  return null;
-}
-
 /**
  * The lowercase canonical UUID the API round-trips. Deliberately looser than
  * `config.js`'s site-id pattern on the version nibble: image ids are server

package/src/field-schema.json

@@ -133,7 +133,7 @@
         {
           "properties": {
             "id": { "$ref": "#/$defs/id" },
-            "type": { "enum": ["email", "tel", "url"] },
+            "type": { "enum": ["email", "url"] },
             "label": { "$ref": "#/$defs/label" },
             "hint": { "$ref": "#/$defs/hint" },
             "required": { "$ref": "#/$defs/required" },
@@ -141,6 +141,16 @@
           },
           "additionalProperties": false
         },
+        {
+          "properties": {
+            "id": { "$ref": "#/$defs/id" },
+            "type": { "const": "tel" },
+            "label": { "$ref": "#/$defs/label" },
+            "hint": { "$ref": "#/$defs/hint" },
+            "required": { "$ref": "#/$defs/required" }
+          },
+          "additionalProperties": false
+        },
         {
           "properties": {
             "id": { "$ref": "#/$defs/id" },

package/src/field-validation.js

@@ -44,7 +44,10 @@ export const CONSTRAINTS_BY_TYPE = {
     text: ["required", "min_length", "max_length", "format"],
     long_text: ["required", "min_length", "max_length"],
     email: ["required", "max_length"],
-    tel: ["required", "max_length"],
+    // A published phone field submits E.164, which the visitor did not type, so a
+    // character limit could refuse a number they cannot shorten; the 7–15 digit
+    // check bounds it instead (TR01090).
+    tel: ["required"],
     url: ["required", "max_length"],
     number: ["required", "min", "max", "format"],
     date: ["required", "min", "max"],
@@ -653,7 +656,10 @@ function validateValue(field, value, context) {
 const isTextType = (type) => type === "text" || type === "long_text" || type === "email" || type === "tel" || type === "url";
 function maxLengthOf(field) {
     const ceiling = field.type === "long_text" ? MAX_LONG_TEXT_LENGTH : MAX_SHORT_TEXT_LENGTH;
-    return Math.min(field.max_length ?? ceiling, ceiling);
+    // A definition stored before tel lost max_length (TR01090) may still carry
+    // one; only a type that accepts the constraint is held to it.
+    const limit = CONSTRAINTS_BY_TYPE[field.type].includes("max_length") ? field.max_length : undefined;
+    return Math.min(limit ?? ceiling, ceiling);
 }
 function validateString(field, value) {
     if (field.min_length !== undefined && value.length < field.min_length)

package/src/fixture-contract.js

@@ -40,8 +40,19 @@ export const FIXTURE_ROOT_FIELDS = Object.freeze(
   [...FIXTURE_REQUIRED_ROOT_FIELDS, ...FIXTURE_OPTIONAL_ROOT_FIELDS].sort(),
 );
 
-/** Every field the versioned `fixture` block may declare. All are required. */
-export const FIXTURE_METADATA_FIELDS = Object.freeze(["contractVersion", "imageIds", "deliveryOrigins"]);
+/** Fields of the versioned `fixture` block that must be present. */
+export const FIXTURE_REQUIRED_METADATA_FIELDS = Object.freeze(["contractVersion", "imageIds", "deliveryOrigins"]);
+
+/**
+ * Fields of the `fixture` block that may be omitted. `videoIds` lists the
+ * `ready` videos a fixture's pages may place; a fixture that places none omits it.
+ */
+export const FIXTURE_OPTIONAL_METADATA_FIELDS = Object.freeze(["videoIds"]);
+
+/** Every field the versioned `fixture` block may declare. */
+export const FIXTURE_METADATA_FIELDS = Object.freeze(
+  [...FIXTURE_REQUIRED_METADATA_FIELDS, ...FIXTURE_OPTIONAL_METADATA_FIELDS],
+);
 
 /**
  * Delivery origins are restricted to the reserved example domain rather than

package/src/fixture-init.js

@@ -70,6 +70,7 @@ export async function initializeFixture(invocation, validate) {
 
   const identities = new Map();
   const imageIds = new Set();
+  const videoIds = new Set();
   const origins = new Map();
   const uuid = /[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}/giu;
   function identity(value) {
@@ -105,6 +106,7 @@ export async function initializeFixture(invocation, validate) {
         }
         const result = sanitize(child, depth + 1);
         if (/(?:imageId|logoId|canvasImageId|faviconId)$/iu.test(key) && isCanonicalUuid(result)) imageIds.add(result);
+        if (key === "videoId" && isCanonicalUuid(result)) videoIds.add(result);
         return [key, result];
       }),
     );
@@ -226,6 +228,7 @@ export async function initializeFixture(invocation, validate) {
     fixture: {
       contractVersion: FIXTURE_CONTRACT_VERSION,
       imageIds: [...imageIds].sort(),
+      ...(videoIds.size > 0 ? { videoIds: [...videoIds].sort() } : {}),
       deliveryOrigins: [...origins.values()],
     },
   });

package/src/image-metadata.js

@@ -36,7 +36,7 @@ const JPEG_SOI = Buffer.from([0xff, 0xd8]);
 function unsupportedFormat(fileName) {
   return new SiteAuthoringError(
     "media.unsupported_format",
-    `'${fileName}' is not a PNG, JPEG, GIF, or WebP image. Taproot accepts raster uploads only.`,
+    `'${fileName}' is not a PNG, JPEG, GIF, or WebP image, or an MP4, MOV, or WebM video. Taproot accepts raster images and those video containers only.`,
     { field: fileName },
   );
 }

package/src/reference-help.js

@@ -71,7 +71,7 @@ import {
 
 export { getAppearanceReference, getFooterReference, getThemeReference };
 
-export const REFERENCE_VERSION = 31;
+export const REFERENCE_VERSION = 32;
 
 // The date-limit examples `help forms` prints; tests run them through the form validator.
 export const FORM_DATE_WINDOW_FIELD = Object.freeze({
@@ -829,7 +829,7 @@ const WORKFLOW_REFERENCES = Object.freeze({
   }),
   media: Object.freeze({
     title: "Media upload contract",
-    summary: "Upload workspace-root-relative raster files and receive component-ready media objects.",
+    summary: "Upload workspace-root-relative raster files and videos and receive component-ready media objects and video ids.",
     usage: `${CLI_BINARY_NAME} media upload [path...]`,
     details: Object.freeze([
       "Paths are relative to the configured workspace root, not the shell's current directory.",
@@ -838,6 +838,8 @@ const WORKFLOW_REFERENCES = Object.freeze({
       "Prepare variants locally with any image tool before uploading: a transparent logo, its @2x copy, a scheme-specific dark logo when one asset does not read on both headers, and a square favicon. The CLI uploads what you give it; it has no recolor, crop, or SVG upload command.",
       "Assign both schemes after uploading: lightLogoId and darkLogoId in settings/taproot-styles.json and brand.faviconId in settings/brand.json take the returned image ids; theme push writes them. See help walkthrough for the full design pass.",
       "Each result item includes media: { imageId, src, urls, width, height, alt }.",
+      "MP4, MOV, and WebM files are uploaded as videos (up to 250 MB each; the site's licence sets the cap, and the container is read from the file's bytes, not its name). The CLI reads each file with mediabunny. A file that is H.264 and AAC but not already an MP4 with its index first is rewritten as one without re-encoding; anything else is sent as it is and judged by the server. When the server refuses a file, its one-line message is printed as media.video_refused. A video is ready to play as soon as the upload is confirmed. The CLI sets no poster, because Node has no video decoder: the Videos page picks one automatically for a video uploaded there, and lets the owner choose another frame, so set a CLI-uploaded video's poster there. The command reports videos.items: { file, videoId, contentType, byteLength, deduplicated, durationMilliseconds, component }, where component.markdown is the component:video fence and component.block the componentBlock node that place it. Needs the site's licence to include video.",
+      "Place an uploaded video on a page with a video component: a component:video fence in Markdown or a componentBlock of type video, with the returned videoId and optional poster, caption, and aspectRatio. See help component video. pages push refuses a video that is not in the site's library; validate checks it against fixture.videoIds.",
       "The same src/urls delivery fields are saved in .taproot-site-media.json for page and component authoring.",
     ]),
     example: Object.freeze({
@@ -925,7 +927,9 @@ const WORKFLOW_REFERENCES = Object.freeze({
         SETTINGS_GROUPS.map((group) => `${group.settingsType} to '${SETTINGS_DIRECTORY}/${group.file}'`).join("; ")
       }.`,
       `The fixture block carries ${FIXTURE_METADATA_FIELDS.join(", ")}. Every image a page references by imageId must `
-      + "be listed in fixture.imageIds, and every absolute delivery URL a page uses must sit on a declared origin.",
+      + "be listed in fixture.imageIds, and every absolute delivery URL a page uses must sit on a declared origin. "
+      + "videoIds is optional: list the ready videos a page may place with a video component, and validate refuses a "
+      + "video component whose videoId is not listed. A live push makes the same check against the site's video library.",
       `Each deliveryOrigins entry is an origin-only HTTPS URL (no path, query, fragment, or credentials) on `
       + `${FIXTURE_DELIVERY_ORIGIN_DOMAIN} or a subdomain of it, at most ${FIXTURE_MAXIMUM_DELIVERY_ORIGINS} of them, `
       + "with no duplicates. Fixtures are copied and shipped, so a real delivery host in one would be a live "
@@ -1025,6 +1029,12 @@ export function getComponentReference(type) {
     accessibility: definition.accessibility,
     example,
     markdownExample,
+    ...(definition.authoring
+      ? {
+        authoringNotes: definition.authoring.notes,
+        authoringMarkdownExample: definition.authoring.markdownExample,
+      }
+      : {}),
     componentBlockExample: {
       type: "componentBlock",
       attrs: {
@@ -1841,7 +1851,11 @@ export function formatReferenceResult(result) {
         component.accessibility.map((note) => `  - ${note}`).join("\n")
       }\n\nValid componentData object:\n${
         JSON.stringify(component.example, null, 2)
-      }\n\nMarkdown component fence:\n${component.markdownExample}\n\nRemember: componentData stores JSON.stringify(the object), not the object itself. Use --json for the exact nested schema and a complete componentBlock example.\n`;
+      }\n\nMarkdown component fence:\n${component.markdownExample}${
+        component.authoringNotes === undefined
+          ? ""
+          : `\n\nAuthoring by link:\n${component.authoringNotes.map((note) => `  - ${note}`).join("\n")}\n${component.authoringMarkdownExample}`
+      }\n\nRemember: componentData stores JSON.stringify(the object), not the object itself. Use --json for the exact nested schema and a complete componentBlock example.\n`;
     }
     case "workflow": {
       const reference = result.reference;

package/src/session.js

@@ -373,7 +373,28 @@ export async function openSession(invocation = {}) {
     // Deliberately swallowed; see above.
   }
 
-  const client = new SiteApiClient(buildClientOptions(invocation, apiBaseUrl, exchanged.key));
+  // The exchanged credential lasts about an hour. A long operation (a video
+  // upload and its encoding) re-exchanges the same stored sign-in for the same
+  // site and capabilities shortly before it lapses, rather than failing midway
+  // with the work already done.
+  const client = new SiteApiClient({
+    ...buildClientOptions(invocation, apiBaseUrl, exchanged.key),
+    credentialRenewal: {
+      expiresAtMilliseconds: Date.parse(exchanged.expiresAt),
+      renew: async () => {
+        const renewed = await withRefusalGuidance(
+          onProgress,
+          "sign-in token exchange",
+          async () =>
+            await exchangeSiteAuthoringToken(accountClient, {
+              siteId: config.siteId,
+              capabilities: narrowedCapabilities(invocation, config.authoringSurface),
+            }),
+        );
+        return { key: renewed.key, expiresAtMilliseconds: Date.parse(renewed.expiresAt) };
+      },
+    },
+  });
   return {
     config,
     client,

package/src/transport.js

@@ -22,6 +22,8 @@ import {
   REFUSAL_UNCLASSIFIED,
   ROLLOUT_REFUSAL_FIELD,
 } from "./constants.js";
+import { Readable } from "node:stream";
+
 import { validateApiBaseUrl } from "./config.js";
 import { hasControlCharacter, sanitizeDiagnostic, SiteAuthoringError } from "./errors.js";
 
@@ -43,6 +45,9 @@ const ALLOWED_METHODS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE"]);
 // `REPLACEABLE_POST_PATHS` below.
 const IDEMPOTENT_METHODS = new Set(["GET"]);
 
+/** An exchanged credential is renewed once it is this close to expiring. */
+const CREDENTIAL_RENEWAL_MARGIN_MILLISECONDS = 5 * 60_000;
+
 const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
 const RETRYABLE_RESPONSE_ERRORS = new Set([
   "transport.invalid_json",
@@ -611,9 +616,20 @@ export class SiteApiClient {
    */
   #authorization;
 
+  /**
+   * How an exchanged credential is replaced before it expires, or `undefined`
+   * for a credential that is not exchanged (a key in the environment). The
+   * exchanged credential lives about an hour, and a video upload plus its
+   * encoding can outlast that.
+   */
+  #renewCredential;
+  #credentialExpiresAtMilliseconds;
+  #renewing;
+
   constructor({
     apiBaseUrl,
     token,
+    credentialRenewal,
     fetch = globalThis.fetch,
     sleep = defaultSleep,
     signal,
@@ -643,6 +659,12 @@ export class SiteApiClient {
     this.apiPathPrefix = new URL(this.apiBaseUrl).pathname;
     this.anonymous = anonymous;
     this.#authorization = anonymous ? undefined : `Bearer ${token}`;
+    // A renewal whose first expiry is not a real time could never say when it
+    // is due, and would exchange on every request, so it is not installed.
+    if (!anonymous && credentialRenewal !== undefined && Number.isFinite(credentialRenewal.expiresAtMilliseconds)) {
+      this.#renewCredential = credentialRenewal.renew;
+      this.#credentialExpiresAtMilliseconds = credentialRenewal.expiresAtMilliseconds;
+    }
     this.fetch = fetch;
     this.sleep = sleep;
     this.signal = signal;
@@ -665,6 +687,42 @@ export class SiteApiClient {
     return await this.#request(path, options, false);
   }
 
+  /**
+   * Replaces an exchanged credential that is within five minutes of expiring,
+   * once however many requests ask at the same time, before the request that
+   * would have carried the old one. A failed renewal is the request's failure:
+   * sending a credential known to be expiring would only be refused later.
+   */
+  async #renewCredentialIfDue() {
+    if (
+      this.#renewCredential === undefined
+      || this.now() < this.#credentialExpiresAtMilliseconds - CREDENTIAL_RENEWAL_MARGIN_MILLISECONDS
+    ) return;
+    this.#renewing ??= (async () => {
+      try {
+        const renewed = await this.#renewCredential();
+        if (!isWellFormedCredential(renewed?.key) || !Number.isFinite(renewed?.expiresAtMilliseconds)) {
+          throw new SiteAuthoringError(
+            "auth.renewal_invalid",
+            "Taproot returned an invalid renewed credential.",
+          );
+        }
+        this.#authorization = `Bearer ${renewed.key}`;
+        this.#credentialExpiresAtMilliseconds = renewed.expiresAtMilliseconds;
+        // A credential that is due again the moment it arrives (a lifetime
+        // shorter than the margin, or a clock far ahead of the server's) would
+        // be exchanged for on every request, each minting a key. It is used as
+        // it is, and the server's own refusal speaks if it has truly lapsed.
+        if (renewed.expiresAtMilliseconds - CREDENTIAL_RENEWAL_MARGIN_MILLISECONDS <= this.now()) {
+          this.#renewCredential = undefined;
+        }
+      } finally {
+        this.#renewing = undefined;
+      }
+    })();
+    await this.#renewing;
+  }
+
   /**
    * Replays only the POST shapes whose server contract answers a replay instead
    * of duplicating work — see `REPLACEABLE_POST_PATHS`. This is deliberately not
@@ -711,6 +769,7 @@ export class SiteApiClient {
     }
     const replayable = IDEMPOTENT_METHODS.has(method) || replaceableMutation;
     const serializedBody = body === undefined ? undefined : JSON.stringify(body);
+    await this.#renewCredentialIfDue();
     // Whether any attempt of a mutation has ended without an authoritative
     // outcome. Accumulated, not read off the final attempt: a claim whose first
     // send committed the mint and died on the reply, and whose retry then failed
@@ -843,10 +902,19 @@ export class SiteApiClient {
    * shape that may be replayed.
    */
   async upload({ url: uploadUrl, requiredHeaders } = {}, bodyBytes) {
+    // A video original is streamed from disk: `{ byteLength, stream, timeoutMilliseconds }`,
+    // where `stream()` returns a fresh readable of exactly `byteLength` bytes so a
+    // retried attempt reads the file again from the start.
+    const streamed = bodyBytes !== null
+      && typeof bodyBytes === "object"
+      && !ArrayBuffer.isView(bodyBytes)
+      && typeof bodyBytes.stream === "function"
+      && Number.isSafeInteger(bodyBytes.byteLength)
+      && bodyBytes.byteLength >= 0;
     if (
       typeof uploadUrl !== "string"
       || uploadUrl.length === 0
-      || !ArrayBuffer.isView(bodyBytes)
+      || !(streamed || ArrayBuffer.isView(bodyBytes))
     ) {
       throw new SiteAuthoringError("upload.contract_invalid", "Taproot returned an invalid upload capability.");
     }
@@ -920,9 +988,15 @@ export class SiteApiClient {
         response = await this.fetch(url, {
           method: "PUT",
           redirect: "error",
-          signal: operationSignal(this.signal, LIMITS.uploadMilliseconds, this.timeoutSignal),
+          signal: operationSignal(
+            this.signal,
+            (streamed ? bodyBytes.timeoutMilliseconds : undefined) ?? LIMITS.uploadMilliseconds,
+            this.timeoutSignal,
+          ),
           headers,
-          body: bodyBytes,
+          ...(streamed
+            ? { body: Readable.toWeb(bodyBytes.stream()), duplex: "half" }
+            : { body: bodyBytes }),
         });
       } catch {
         if (attempt + 1 < LIMITS.uploadAttempts && !this.signal?.aborted) {