@taprootio/site-authoring 0.12.7 → 0.14.0

package/README.md

@@ -356,7 +356,17 @@ closed with `pages.push_conflict` when a page's stored-state revision has
 moved since this workspace last reconciled with it, naming both revisions;
 `pull` first, or push after a refused pull has shown you the site's version.
 `media upload [path...]` uploads raster files and records component-ready
-delivery fields. `nav push`, `theme push`, and `footer push` replace the whole
+delivery fields; MP4, MOV, and WebM files are uploaded as videos. Taproot does not
+encode: the command reads each file with mediabunny, rewrites an H.264 and AAC
+file that is not an MP4 with its index first as one (copying the tracks, never
+re-encoding), declares its codecs, and prints the server's one-line refusal as
+it came for anything it will not accept (a non-H.264 or non-AAC file, one over
+the licence's upload cap). A video is ready when its upload confirms; the CLI sets no poster (Node has no video decoder), so
+choose one on the Videos page, where an upload made there gets one automatically, and set its
+title and caption there too: the poster, caption and shape are the video's own and show wherever
+it is placed. The command reports its `videoId`, title, caption and file name for a `video`
+component (`help component video`), and
+`pages push` refuses a page that places a video the site does not have. `nav push`, `theme push`, and `footer push` replace the whole
 navigation tree, the complete light/dark theme pair with its appearance
 settings, and the closed footer document. `pull` writes each scheme's
 complete effective theme — the stored theme resolved over the same defaults

package/package.json

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

package/src/api.js

@@ -801,23 +801,104 @@ export function normalizeImage(value) {
   };
 }
 
+export async function requestVideoUpload(client, siteId, body) {
+  return requireObject(
+    await client.request(sitePath(siteId, "videos/request-upload"), { method: "POST", body }),
+    "api.video_contract",
+    "video upload request",
+  );
+}
+
+export async function confirmVideoUpload(client, siteId, uploadId) {
+  return normalizeVideo(
+    await client.request(sitePath(siteId, "videos/confirm-upload"), { method: "POST", body: { uploadId } }),
+  );
+}
+
+/**
+ * Copies a YouTube or Vimeo thumbnail into the site's images and returns that image,
+ * which is still being processed (TR01109). `posterFromImage` shapes it for a component.
+ */
+export async function importVideoEmbedPoster(client, siteId, provider, videoId) {
+  const response = requireObject(
+    await client.request(sitePath(siteId, "videos/import-embed-poster"), {
+      method: "POST",
+      body: { provider, videoId },
+    }),
+    "api.video_contract",
+    "video embed poster",
+  );
+  return normalizeImage(response.image);
+}
+
+/** The object a component's poster field holds, from an image whose processing is complete. */
+export function posterFromImage(image) {
+  return { imageId: image.imageId, src: image.url, urls: image.responsiveUrls, width: image.width, height: image.height, alt: "" };
+}
+
+export function normalizeVideo(value) {
+  const video = requireObject(value, "api.video_contract", "video");
+  return {
+    videoId: requireCanonicalUuid(video.videoId, "api.video_contract", "video.videoId"),
+    title: text(video.title),
+    caption: text(video.caption),
+    fileName: text(video.fileName),
+    bytes: safeCount(video.bytes),
+    durationMilliseconds: safeCount(video.durationMs),
+    width: safeCount(video.width),
+    height: safeCount(video.height),
+    sourceUrl: text(video.sourceUrl),
+  };
+}
+
+/**
+ * The site's videos through `ListVideos`, paged like the image library and
+ * bounded the same way. A video is ready the moment it is listed.
+ */
+export async function listVideos(client, siteId, requestOptions = {}) {
+  const videos = [];
+  let pageToken = "";
+  for (let request = 0; request < MAXIMUM_LIST_REQUESTS; request += 1) {
+    const search = query([["pageSize", LIST_PAGE_SIZE], ["pageToken", pageToken]]);
+    const response = requireObject(
+      await client.request(sitePath(siteId, `videos${search}`), requestOptions),
+      "api.video_contract",
+      "site videos",
+    );
+    const batch = Array.isArray(response.videos) ? response.videos : [];
+    for (const entry of batch) videos.push(normalizeVideo(entry));
+    pageToken = typeof response.nextPageToken === "string" ? response.nextPageToken : "";
+    if (pageToken === "" || batch.length === 0) return { videos, truncated: false };
+    if (videos.length >= MAXIMUM_IMAGES) break;
+  }
+  return { videos, truncated: true };
+}
+
 /**
  * Processing is observed through `ListSiteImages`; `GetImageById` is
  * session-only under TR00602's read list, so a key-authorized client watches
  * the library rather than one image.
  *
+ * `imageIds` (at most 100) reads exactly those images instead of the library, in any
+ * purpose: the way to watch an image the library never lists, such as the embed
+ * poster the server copied for a push.
+ *
  * `requestOptions` carries a poller's `{ deadline, now }` into *every* page of
  * the listing. Without it a single read of a large library could spend far more
  * than the caller's whole budget — the page bound alone permits hundreds of
  * requests, each with its own request timeout and retry budget — and the
  * deadline would only be noticed once the read finally returned.
  */
-export async function listSiteImages(client, siteId, requestOptions = {}) {
+export async function listSiteImages(client, siteId, requestOptions = {}, { imageIds = [] } = {}) {
   const images = [];
   let pageToken = "";
   let summary = { totalImages: 0, processingImages: 0 };
   for (let request = 0; request < MAXIMUM_LIST_REQUESTS; request += 1) {
-    const search = query([["pageSize", LIST_PAGE_SIZE], ["pageToken", pageToken]]);
+    // Asking by id reads exactly those images, whatever their purpose. The library lists the
+    // owner's own images only, so a copied embed poster is never in it.
+    const search = imageIds.length > 0
+      ? query([["imageIds", imageIds]])
+      : query([["pageSize", LIST_PAGE_SIZE], ["pageToken", pageToken]]);
     const response = requireObject(
       await client.request(sitePath(siteId, `images${search}`), requestOptions),
       "api.image_contract",
@@ -946,6 +1027,10 @@ export async function getPublishingReadiness(client, siteId, selection = {}) {
     blockedPageCount: safeCount(response.blockedPageCount),
     hasCandidateChanges: response.hasCandidateChanges === true,
     hasSuccessfulStagingDeployment: response.hasSuccessfulStagingDeployment === true,
+    // Site-wide inputs frozen with every release that differ from production's.
+    redirectsChanged: response.redirectsChanged === true,
+    formsChanged: response.formsChanged === true,
+    videosChanged: response.videosChanged === true,
     blockers,
   };
 }

package/src/cli.js

@@ -367,7 +367,7 @@ const VERBS = Object.freeze([
     // (TR00790).
     surfaceCapabilities: { [SURFACE_DOCS_PRESENTATION]: [CAPABILITY_DESIGN] },
     tokens: ["media", "upload"],
-    summary: "Upload media and wait for processing to finish.",
+    summary: "Upload images and videos; images are waited on until processed, and a video is ready when it confirms.",
     positionals: "paths",
     note: "Positional arguments name the files or directories to upload;"
       + " with none, the workspace's media/ directory is walked.",

package/src/constants.js

@@ -225,6 +225,9 @@ export const LIMITS = Object.freeze({
   redirectMapResponseBytes: 8 * 1024 * 1024,
   requestMilliseconds: 60_000,
   uploadMilliseconds: 5 * 60_000,
+  // A video is up to the licence's upload cap (at most 250 MB) over one PUT, which
+  // takes minutes where an image takes seconds.
+  videoUploadMilliseconds: 2 * 60 * 60_000,
   deploymentMilliseconds: 30 * 60_000,
   previewMilliseconds: 5 * 60_000,
   pollIntervalMilliseconds: 2_000,

package/src/content/components.js

@@ -15,6 +15,8 @@ import {
   isUuid,
   pointerSegment,
 } from "./vocabulary.js";
+import { normalizeCssLengthOverride } from "./media-presentation.js";
+import { isVideoEmbedId, parseVideoEmbedUrl, VIDEO_EMBED_REFUSAL } from "./video-embed-url.js";
 
 /**
  * The eight canonical `componentBlock` data shapes. Seven remain mirrored
@@ -54,6 +56,8 @@ const LATEST_POST_PAGE_TYPES = Object.freeze([
 const REGISTERED_TEXTURE_NAME_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u;
 
 const str = (options = {}) => Object.freeze({ kind: "string", ...options });
+/** A string bounded in length, optionally constrained to a pattern the published renderer also applies. */
+const boundedStr = (maximumLength, options = {}) => str({ maximumLength, ...options });
 const bool = () => Object.freeze({ kind: "boolean" });
 const num = (options = {}) => Object.freeze({ kind: "number", ...options });
 const enumOf = (...values) => Object.freeze({ kind: "enum", values: Object.freeze(values) });
@@ -61,6 +65,8 @@ const list = (item) => Object.freeze({ kind: "array", item });
 const shape = (fields, options = {}) => Object.freeze({ kind: "object", fields: Object.freeze(fields), ...options });
 const image = () => Object.freeze({ kind: "image" });
 const safeUrl = (options = {}) => Object.freeze({ kind: "safe-url", ...options });
+/** A CSS length the published renderer accepts as a per-block override; `allowNone` adds `none` (a max height). */
+const cssLength = (options = {}) => Object.freeze({ kind: "css-length", ...options });
 const textureName = () => Object.freeze({ kind: "texture-name", maximumLength: 64 });
 const withOmission = (spec, whenOmitted) => Object.freeze({ ...spec, whenOmitted: Object.freeze(whenOmitted) });
 
@@ -279,6 +285,47 @@ const IMAGE_BANNER = Object.freeze({
   imageMotion: enumOf("none", "slow-zoom", "drift-start", "drift-end", "parallax-subtle", "parallax"),
 });
 
+/** The `W:H` form of a video's aspect ratio, as the published renderer and the editor accept it. */
+const VIDEO_ASPECT_RATIO_PATTERN = "^[1-9][0-9]{0,2}:[1-9][0-9]{0,2}$";
+const VIDEO_ASPECT_RATIO_RE = new RegExp(VIDEO_ASPECT_RATIO_PATTERN, "u");
+
+/** Shown with both video blocks: the two optional fields follow the same site settings images use. */
+const MEDIA_PRESENTATION_HELP =
+  "Leave maxHeight and borderWidth out to follow the site's image max height and border; set maxHeight (a viewport or fixed height such as 50vh or 30rem, or none) or borderWidth (such as 4px, or 0 for no border) to override them for this block. The frame is never wider than the video's own pixel size.";
+
+/**
+ * `VideoData`. The page names a library video by id and nothing about where it
+ * is served: the generator resolves the id at publish time and refuses a video
+ * that is not `ready` or not this site's own. Delivery URLs are not authorable
+ * here, so a `delivery` key is refused like any other unknown field. The poster,
+ * caption and ratio are the video's own (TR01184), so a block carrying one is
+ * refused the same way.
+ */
+const VIDEO = Object.freeze({
+  videoId: Object.freeze({ kind: "uuid", required: true }),
+  maxHeight: cssLength({ allowNone: true }),
+  borderWidth: cssLength(),
+});
+
+/**
+ * `VideoEmbedData`. A YouTube or Vimeo video is stored as its provider and id,
+ * never as a link: the published page builds the player URL from the pair. A
+ * Markdown component fence may name the video by `url` instead, and
+ * `expandComponentAuthoringShorthand` reduces it to the pair before validation.
+ */
+const VIDEO_EMBED = Object.freeze({
+  provider: Object.freeze({ ...enumOf("youtube", "vimeo"), required: true }),
+  videoId: boundedStr(32, { required: true, nonWhitespace: true }),
+  title: boundedStr(200, { required: true, nonWhitespace: true }),
+  poster: image(),
+  aspectRatio: str({
+    pattern: VIDEO_ASPECT_RATIO_RE,
+    patternSource: VIDEO_ASPECT_RATIO_PATTERN,
+    patternDescription: "two whole numbers of at most three digits joined by a colon, such as 16:9",
+  }),
+  maxHeight: cssLength({ allowNone: true }),
+  borderWidth: cssLength(),
+});
 const SPACER = Object.freeze({
   height: enumOf("small", "medium", "large"),
   showDivider: bool(),
@@ -301,8 +348,16 @@ function deepFreeze(value) {
   return Object.freeze(value);
 }
 
-function component(fields, displayName, summary, defaultData, accessibility, example) {
-  return deepFreeze({ fields, displayName, summary, defaultData, accessibility, example });
+function component(fields, displayName, summary, defaultData, accessibility, example, authoring) {
+  return deepFreeze({
+    fields,
+    displayName,
+    summary,
+    defaultData,
+    accessibility,
+    example,
+    ...(authoring ? { authoring } : {}),
+  });
 }
 
 /**
@@ -576,6 +631,47 @@ const COMPONENT_DEFINITIONS = Object.freeze({
     ],
     { formKey: "contact" },
   ),
+  "video": component(
+    VIDEO,
+    "Video",
+    "A video from the site's library that plays when the visitor presses play; the page reads only the start of the file before then.",
+    {},
+    [
+      "The poster, the caption and the shape are the video's own and show wherever it is placed: set the title, caption and poster on the site's Videos page. The caption tells a visitor what the video is about and is also the player's accessible name.",
+      "A video with spoken content needs captions or a transcript in the page text; the player does not generate them.",
+    ],
+    {
+      videoId: "7c5e2b1a-9d3f-4a68-b0c4-1e2f3a4b5c6d",
+    },
+    { notes: [MEDIA_PRESENTATION_HELP] },
+  ),
+  "video-embed": component(
+    VIDEO_EMBED,
+    "Video embed",
+    "A YouTube or Vimeo video shown as a poster and a play button; nothing from the provider loads until the visitor presses play.",
+    {},
+    [
+      "Set title to what the video is about; it names the play button and the player for assistive technology.",
+      "A video with spoken content needs captions turned on at the provider or a transcript in the page text.",
+      "Leave poster out and 'pages push' copies the provider's thumbnail into the site's images and sets it (once per video), or set poster to one of the site's images. The published page never loads anything from the provider before the visitor presses play; if the copy is refused the block is sent with no poster.",
+    ],
+    {
+      provider: "youtube",
+      videoId: "dQw4w9WgXcQ",
+      title: "A walk through the studio before your first class.",
+      aspectRatio: "16:9",
+    },
+    {
+      notes: [
+        MEDIA_PRESENTATION_HELP,
+        "In a Markdown fence, give the video as url (a YouTube or Vimeo link) and title instead of provider and videoId; the CLI reduces the link to provider and videoId before it validates or sends the page.",
+        "A link that is not an accepted YouTube or Vimeo video gets a one-line refusal that names the links it accepts.",
+        "url together with provider or videoId is refused: give the video one way.",
+        "Stored blocks and .pm.json sources hold only provider and videoId; url is never stored.",
+      ],
+      markdownExample: "```component:video-embed\n{\"url\": \"https://youtu.be/dQw4w9WgXcQ\", \"title\": \"A walk through the studio before your first class.\"}\n```",
+    },
+  ),
 });
 
 export const COMPONENT_TYPES = Object.freeze(Object.keys(COMPONENT_DEFINITIONS));
@@ -597,6 +693,10 @@ function referenceSchema(spec) {
       return {
         type: "string",
         ...(spec.nonWhitespace ? { minLength: 1, description: "Must contain non-whitespace text." } : {}),
+        ...(spec.maximumLength !== undefined ? { maxLength: spec.maximumLength } : {}),
+        ...(spec.patternSource !== undefined
+          ? { pattern: spec.patternSource, description: `Must be ${spec.patternDescription}.` }
+          : {}),
       };
     case "safe-url":
       return {
@@ -606,6 +706,8 @@ function referenceSchema(spec) {
           spec.allowEmpty === false ? "An" : "Empty, or an"
         } explicit HTTP(S), mailto, or tel URL; a root-relative path that does not begin with //; a fragment; a query; or a relative URL. Backslashes and ASCII control characters are rejected. Contact URLs require a non-empty body and refuse tel:// and mailto:// authority forms.`,
       };
+    case "css-length":
+      return { type: "string", description: `Must be ${describe(spec)}.` };
     case "texture-name":
       return {
         type: "string",
@@ -710,6 +812,10 @@ function describe(spec) {
       return `${
         spec.allowEmpty === false ? "a" : "an empty string or a"
       } safe HTTP(S), mailto, tel, non-protocol-relative root path, fragment, query, or relative URL; backslashes and ASCII control characters are rejected`;
+    case "css-length":
+      return spec.allowNone
+        ? "a CSS height such as 60vh or 32rem, or none"
+        : "a CSS width such as 2px or 0.25rem, or 0 for no border";
     case "texture-name":
       return "a lowercase hyphenated texture identifier of at most 64 characters";
     default:
@@ -730,6 +836,9 @@ function validateValue(spec, value, path, errors) {
     case "string":
       if (typeof value !== "string") fail("a string");
       else if (spec.nonWhitespace && value.trim() === "") fail("a string containing non-whitespace text");
+      else if (spec.maximumLength !== undefined && value.length > spec.maximumLength) {
+        fail(`a string of at most ${spec.maximumLength} characters`);
+      } else if (spec.pattern !== undefined && !spec.pattern.test(value)) fail(spec.patternDescription);
       return;
     case "safe-url":
       if (
@@ -744,6 +853,10 @@ function validateValue(spec, value, path, errors) {
         fail(describe(spec));
       }
       return;
+    case "css-length":
+      // The renderer drops a value outside this grammar silently, so it is refused here instead.
+      if (normalizeCssLengthOverride(value, { allowNone: spec.allowNone === true }) === null) fail(describe(spec));
+      return;
     case "texture-name":
       if (
         typeof value !== "string"
@@ -847,6 +960,31 @@ function validateFields(fields, value, path, errors) {
   }
 }
 
+/**
+ * Lets a Markdown component fence name a video embed by link. Returns the
+ * fence's JSON source with `url` replaced by the `provider` and `videoId` it
+ * reduces to, or `{ error }` with the one-line reason a link is refused. Any
+ * other component, and a source that is not a JSON object, comes back as it was
+ * so validation reports it in its usual words.
+ */
+export function expandComponentAuthoringShorthand(componentType, source) {
+  if (componentType !== "video-embed") return { source };
+  let parsed;
+  try {
+    parsed = JSON.parse(source);
+  } catch {
+    return { source };
+  }
+  if (!isPlainObject(parsed) || !Object.hasOwn(parsed, "url")) return { source };
+  if (Object.hasOwn(parsed, "provider") || Object.hasOwn(parsed, "videoId")) {
+    return { error: "Give the video as url, or as provider and videoId, not both." };
+  }
+  const target = parseVideoEmbedUrl(parsed.url);
+  if (!target) return { error: VIDEO_EMBED_REFUSAL };
+  const { url: _url, ...rest } = parsed;
+  return { source: JSON.stringify({ provider: target.provider, videoId: target.videoId, ...rest }) };
+}
+
 /**
  * Validates a `componentBlock`'s `componentType` and `componentData` pair.
  *
@@ -915,6 +1053,17 @@ export function validateComponentBlock(componentType, componentData, basePath) {
       }
     }
   }
+  if (
+    componentType === "video-embed" && typeof parsed.provider === "string" && typeof parsed.videoId === "string"
+    && (parsed.provider === "youtube" || parsed.provider === "vimeo")
+    && !isVideoEmbedId(parsed.provider, parsed.videoId)
+  ) {
+    errors.push(contentError(
+      `${dataPath}/videoId`,
+      CODES.componentData,
+      `Component data field 'videoId' must be a valid ${parsed.provider} video id. ${VIDEO_EMBED_REFUSAL}`,
+    ));
+  }
   return errors;
 }
 

package/src/content/free-form-section-registry.json

@@ -1,5 +1,5 @@
 {
-  "version": 9,
+  "version": 12,
   "section": {
     "nodeType": "section",
     "label": "Section",
@@ -559,6 +559,16 @@
       "label": "Form",
       "measure": "wide",
       "rootPlacement": "flow"
+    },
+    "video": {
+      "label": "Video",
+      "measure": "wide",
+      "rootPlacement": "flow"
+    },
+    "video-embed": {
+      "label": "Video embed",
+      "measure": "wide",
+      "rootPlacement": "flow"
     }
   },
   "integrationPlacement": {

package/src/content/markdown.js

@@ -1,5 +1,10 @@
 import { SiteAuthoringError } from "../errors.js";
-import { canonicalizeComponentData, isComponentType, validateComponentBlock } from "./components.js";
+import {
+  canonicalizeComponentData,
+  expandComponentAuthoringShorthand,
+  isComponentType,
+  validateComponentBlock,
+} from "./components.js";
 import {
   FREE_FORM_SECTION_REGISTRY,
   normalizeFreeFormSectionBackground,
@@ -869,7 +874,12 @@ function componentNode(componentType, body, line) {
       line.number,
     );
   }
-  const source = body.trim() === "" ? "{}" : body;
+  const authored = body.trim() === "" ? "{}" : body;
+  const expanded = expandComponentAuthoringShorthand(componentType, authored);
+  if (expanded.error !== undefined) {
+    throw fail(CODES.componentData, "component block", expanded.error, line.number);
+  }
+  const source = expanded.source;
   const errors = validateComponentBlock(componentType, source, "");
   if (errors.length > 0) {
     throw fail(errors[0].code, "component block", errors[0].message, line.number);

package/src/content/media-presentation.js

@@ -0,0 +1,123 @@
+// Generated from shared/media-presentation.ts by scripts/sync-field-validation.mjs. Do not edit.
+/**
+ * The one owner of how an image, a video and a video embed are sized and
+ * bordered: the site-default option lists and normalizers, the per-block
+ * override grammar, and the CSS values built from them.
+ *
+ * Images, the Video block and the Video embed block read the same two site
+ * settings (max height, border width) and take the same two optional per-block
+ * overrides, so they share these functions and the custom properties they set.
+ *
+ * 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. The API mirrors the site-setting ranges in
+ * `SiteSettings.cs`.
+ */
+/** The "no explicit choice" sentinel stored in place of an override. */
+export const TIPTAP_SITE_DEFAULT = "site-default";
+export const DEFAULT_TIPTAP_IMAGE_MAX_HEIGHT_VH = 60;
+export const TIPTAP_IMAGE_MAX_HEIGHT_OPTIONS = [45, 60, 75, 90];
+// Mirrors TiptapImageBorder in the API's SiteSettings.cs. 2px matches
+// esp-image's built-in border so untouched sites keep their current look.
+export const TIPTAP_IMAGE_BORDER_WIDTH_MIN = 0;
+export const TIPTAP_IMAGE_BORDER_WIDTH_MAX = 20;
+export const DEFAULT_TIPTAP_IMAGE_BORDER_WIDTH_PX = 2;
+/** The custom property every sized media block reads its max height from. */
+export const MEDIA_MAX_HEIGHT_PROPERTY = "--taproot-article-image-max-height";
+/** The custom property every bordered media block reads its border from. */
+export const MEDIA_BORDER_PROPERTY = "--esp-image-border";
+/** A number, or text read as one (a cleared field reads as 0); anything else is not a number. */
+function optionNumber(value) {
+    if (typeof value === "number")
+        return value;
+    return typeof value === "string" ? Number(value) : Number.NaN;
+}
+function isMaxHeightOption(value) {
+    return TIPTAP_IMAGE_MAX_HEIGHT_OPTIONS.includes(optionNumber(value));
+}
+/** The site max height (in vh) for any stored value; anything outside the options is the default. */
+export function normalizeImageMaxHeight(value) {
+    return isMaxHeightOption(value)
+        ? optionNumber(value)
+        : DEFAULT_TIPTAP_IMAGE_MAX_HEIGHT_VH;
+}
+/** An explicit per-image max height choice, or null for the site default, the sentinel or an invalid value. */
+export function explicitImageMaxHeight(value) {
+    if (value === TIPTAP_SITE_DEFAULT || value === undefined || value === null)
+        return null;
+    return isMaxHeightOption(value) ? optionNumber(value) : null;
+}
+/** The site border width in pixels for any stored value; anything outside the range is the default. */
+export function normalizeImageBorderWidthPx(value) {
+    const parsed = optionNumber(value);
+    if (!Number.isFinite(parsed))
+        return DEFAULT_TIPTAP_IMAGE_BORDER_WIDTH_PX;
+    const width = Math.trunc(parsed);
+    return width >= TIPTAP_IMAGE_BORDER_WIDTH_MIN && width <= TIPTAP_IMAGE_BORDER_WIDTH_MAX
+        ? width
+        : DEFAULT_TIPTAP_IMAGE_BORDER_WIDTH_PX;
+}
+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-block 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, 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 validated max height override of a block (a CSS length or "none"), or null for the site default. */
+export function normalizeMaxHeightOverride(value) {
+    return normalizeCssLengthOverride(value, { allowNone: true });
+}
+/** The validated border width override of a block (a CSS length), or null for the site default. */
+export function normalizeBorderWidthOverride(value) {
+    return normalizeCssLengthOverride(value);
+}
+/** CSS value for the border hook given a width; zero collapses to none. */
+export function imageBorderValue(width) {
+    return /^0(?:\.0+)?(?:[a-z%]+)?$/i.test(width) ? "none" : `${width} solid var(--esp-color-border)`;
+}
+/** The site-default border as CSS, from the stored pixel width. */
+export function siteDefaultBorderValue(widthPx) {
+    return imageBorderValue(`${normalizeImageBorderWidthPx(widthPx)}px`);
+}
+/**
+ * The inline custom-property declarations that carry a block's overrides.
+ * Only an explicit, valid override is emitted, so an absent one keeps
+ * following the site default.
+ */
+export function mediaOverrideStyleParts(overrides) {
+    const parts = [];
+    const maxHeight = normalizeMaxHeightOverride(overrides.maxHeight);
+    const borderWidth = normalizeBorderWidthOverride(overrides.borderWidth);
+    // A unitless zero would make the video frame's width calc invalid; 0px means the same to an image.
+    if (maxHeight)
+        parts.push(`${MEDIA_MAX_HEIGHT_PROPERTY}: ${maxHeight === "0" ? "0px" : maxHeight}`);
+    if (borderWidth)
+        parts.push(`${MEDIA_BORDER_PROPERTY}: ${imageBorderValue(borderWidth)}`);
+    return parts;
+}