@taprootio/site-authoring 0.12.6 → 0.13.0

package/README.md

@@ -188,7 +188,7 @@ Which verbs apply depends on the site:
   `pull` snapshots its four settings documents, `theme push`, `footer push`,
   and `media upload` author them, and `deploy` stages and promotes them.
   Its pages, navigation, and redirects come from the Docs artifact, so
-  `pages push`, `nav push`, the `redirects` verbs, `approve`, and the
+  `pages push`, `nav push`, the `redirects` and `forms` verbs, `approve`, and the
   `preview` verbs refuse with `surface.presentation_only` before any request.
 - A **prebuilt Docs** site (`none`) serves its artifact unchanged and takes no
   verb; each refuses with `surface.none`.
@@ -356,7 +356,15 @@ 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; the command
+reports its `videoId` 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
@@ -373,6 +381,16 @@ validates the file offline and replaces the whole map; `help redirects`
 states the entry shape (`path`, `kind` redirect or gone, `target`, `status`
 defaulting to 301), the normalization rule, and every refusal.
 
+`forms pull` writes each live form to `forms/<key>.json` and records the
+version it read; `forms push` validates every file, refuses a form the site
+changed since (`forms.concurrent_modification`) and creates or updates the
+rest, appending a version when the definition changed. `forms validate` checks
+the files offline against the shared field schema with no credential. Both
+verbs write one canonical key order, so a pulled file pushed back is unchanged.
+Submissions are never pulled. `help forms` states the file shape and every
+refusal, and placing a form on a page is the free-form `form`
+component.
+
 `preview page <page-path-or-id>` renders one persisted draft behind the
 staging gate and mints a browser handoff URL, reported only in the final JSON
 result. **Each handoff is single-use.** Opening the URL consumes it; a reused,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.12.6",
+  "version": "0.13.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": "4.20.1"
+    "@taprootio/espalier": "5.0.0",
+    "mediabunny": "1.61.1"
   },
   "scripts": {
     "test": "node --test",

package/src/api.js

@@ -801,23 +801,102 @@ 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),
+    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",

package/src/capabilities.js

@@ -23,7 +23,7 @@ export const SITE_AUTHORING_CAPABILITIES = Object.freeze([
 
 /** What each capability lets an exchanged credential do, for help and `whoami`. */
 export const SITE_AUTHORING_CAPABILITY_SUMMARIES = Object.freeze({
-  "delegation.content": "write pages and media",
+  "delegation.content": "write pages, media, and form definitions",
   "delegation.design": "set the theme, navigation, and footer",
   "delegation.deployments": "stage and deploy",
 });

package/src/cli.js

@@ -20,6 +20,9 @@ import {
   VERB_STAGING_REVIEW,
   VERB_ENV,
   VERB_FOOTER_PUSH,
+  VERB_FORMS_PULL,
+  VERB_FORMS_PUSH,
+  VERB_FORMS_VALIDATE,
   VERB_HELP,
   VERB_LOGIN,
   VERB_LOGOUT,
@@ -71,14 +74,14 @@ import { VERB_HANDLERS } from "./verbs/index.js";
 /**
  * The verbs the local version gate applies to (TR00703).
  *
- * Exactly the three that make no request. Every other verb reaches Taproot,
+ * Exactly the ones that make no request. Every other verb reaches Taproot,
  * whose own refusal is authoritative and better informed than this recording,
  * so gating them here would only duplicate an answer — and gating `login`,
  * `logout`, or `env` would take away the commands an operator needs while they
  * are outdated. `--help` and `--version` are outside it for the same reason:
  * they are how someone finds out what they have.
  */
-const VERSION_GATED_OFFLINE_VERBS = Object.freeze([VERB_HELP, VERB_VALIDATE, VERB_WHOAMI]);
+const VERSION_GATED_OFFLINE_VERBS = Object.freeze([VERB_HELP, VERB_VALIDATE, VERB_FORMS_VALIDATE, VERB_WHOAMI]);
 
 // One entry per verb, in help order. `tokens` is the exact leading positional
 // sequence; matching prefers the longest sequence, so a two-token family can
@@ -281,6 +284,47 @@ const VERBS = Object.freeze([
       + "goes live with that deploy: staging first, production when promoted. "
       + "See 'taproot-site help redirects'.",
   },
+  {
+    name: VERB_FORMS_PULL,
+    surface: SURFACE_STANDARD,
+    // Forms are authored with the pages that place them, so they ride the
+    // content capability; the site's forms permissions decide what it may do.
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["forms", "pull"],
+    summary: "Write each live form to forms/<key>.json and record the versions read.",
+    note: "Needs a pulled workspace ('pull' first). It replaces a form's file with the site's copy and records the "
+      + "version, which 'forms push' uses to refuse a change made on the site since. An archived form is listed "
+      + "and not written. Submissions are never pulled: they are visitors' personal data and stay on the site. "
+      + "See 'taproot-site help forms'.",
+  },
+  {
+    name: VERB_FORMS_PUSH,
+    surface: SURFACE_STANDARD,
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["forms", "push"],
+    positionals: "formKeys",
+    summary: "Validate forms/<key>.json and create or update each form on the site.",
+    note: "Every file is validated and compared with the site before anything is written. A form whose site "
+      + "version moved since the last pull is refused (forms.concurrent_modification), and a form the site has "
+      + "that this workspace never pulled is refused (forms.pull_required). Editing a definition appends a version; "
+      + "a page keeps the version it was published with until the next deploy. An after_submit page_path is looked "
+      + "up on the site, and a path that names no page is refused (forms.page_not_found), as is a generated, 404, legal, profile or integration page (forms.page_not_allowed). Name form keys to narrow "
+      + "the push. See 'taproot-site help forms'.",
+  },
+  {
+    name: VERB_FORMS_VALIDATE,
+    tokens: ["forms", "validate"],
+    offline: true,
+    // Offline, but it reads taproot-site.json to find the workspace.
+    readsLocalState: true,
+    positionals: "formKeys",
+    summary: "Validate the workspace's form files offline, against the shared field schema.",
+    note: "Reads forms/<key>.json and checks the file contract and every field definition with the same validator "
+      + "'forms push' and the published form use. Name form keys to narrow it; with none, every file under forms/ "
+      + "is checked. It cannot prove that the site accepts the key, that an after_submit page_path names a page, or "
+      + "that the caller may write forms. "
+      + "See 'taproot-site help forms'.",
+  },
   {
     name: VERB_THEME_PUSH,
     surface: SURFACE_DOCS_PRESENTATION,
@@ -323,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.",
@@ -556,6 +600,8 @@ function verbHelp(verb) {
     ? " [production | local | <url>]"
     : verb.positionals === "siteSelector"
     ? " <site-name-or-id>"
+    : verb.positionals === "formKeys"
+    ? " [form-key...]"
     : verb.positionals
     ? ` [${verb.positionals === "paths" ? "path" : "page-path"}...]`
     : "";
@@ -706,6 +752,7 @@ function parseReferenceArguments(arguments_) {
       || topic === "footer"
       || topic === "fixture"
       || topic === "redirects"
+      || topic === "forms"
       || topic === "walkthrough"
       || topic === "delivery"
       || topic === "import"
@@ -773,6 +820,7 @@ function referenceResult(parsed) {
     }
     case "nav":
     case "redirects":
+    case "forms":
     case "media":
     case "preview":
     case "fixture":

package/src/constants.js

@@ -87,6 +87,9 @@ export const VERB_NAV_PUSH = "nav push";
 export const VERB_REDIRECTS_CHECK = "redirects check";
 export const VERB_REDIRECTS_PULL = "redirects pull";
 export const VERB_REDIRECTS_PUSH = "redirects push";
+export const VERB_FORMS_PULL = "forms pull";
+export const VERB_FORMS_PUSH = "forms push";
+export const VERB_FORMS_VALIDATE = "forms validate";
 export const VERB_THEME_PUSH = "theme push";
 export const VERB_FOOTER_PUSH = "footer push";
 export const VERB_MEDIA_UPLOAD = "media upload";
@@ -222,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,52 @@ 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.
+ */
+const VIDEO = Object.freeze({
+  videoId: Object.freeze({ kind: "uuid", required: true }),
+  poster: image(),
+  caption: boundedStr(300),
+  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(),
+});
+
+/**
+ * `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(),
@@ -286,14 +338,31 @@ const SPACER = Object.freeze({
   dividerWidth: num({ integer: true, minimum: 1 }),
 });
 
+/**
+ * A form defined under Site → Forms (or with `forms push`), placed by key. The
+ * key is checked against the site's forms when the page is published, not here:
+ * this table only knows the shape.
+ */
+const FORM = Object.freeze({
+  formKey: str(),
+});
+
 function deepFreeze(value) {
   if (value === null || typeof value !== "object" || Object.isFrozen(value)) return value;
   for (const child of Object.values(value)) deepFreeze(child);
   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 } : {}),
+  });
 }
 
 /**
@@ -555,6 +624,62 @@ const COMPONENT_DEFINITIONS = Object.freeze({
       imageMotion: "parallax-subtle",
     },
   ),
+  "form": component(
+    FORM,
+    "Form",
+    "A form from Site → Forms that visitors fill in and submit.",
+    { formKey: "" },
+    [
+      "Set formKey to the key of an existing form ('forms push' creates it); an unknown or archived key fails the publish.",
+      "The button text and what happens after a response is sent belong to the form, not the page: set submit_label and after_submit in the form's file (see 'help forms').",
+      "The form's field labels are its accessible names; write each so it makes sense out of context.",
+    ],
+    { formKey: "contact" },
+  ),
+  "video": component(
+    VIDEO,
+    "Video",
+    "A video from the site's library that plays when the visitor presses play; nothing loads before then.",
+    {},
+    [
+      "Add a caption that tells a visitor what the video is about; the caption 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.",
+      "Leave aspectRatio out to follow the video's own shape; set it only to crop the frame to a different one.",
+    ],
+    {
+      videoId: "7c5e2b1a-9d3f-4a68-b0c4-1e2f3a4b5c6d",
+      caption: "A walk through the studio before your first class.",
+      aspectRatio: "16:9",
+    },
+    { 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));
@@ -576,6 +701,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 {
@@ -585,6 +714,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",
@@ -689,6 +820,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:
@@ -709,6 +844,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 (
@@ -723,6 +861,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"
@@ -826,6 +968,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.
  *
@@ -894,6 +1061,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": 7,
+  "version": 12,
   "section": {
     "nodeType": "section",
     "label": "Section",
@@ -554,6 +554,21 @@
       "label": "Image Banner",
       "measure": "wide",
       "rootPlacement": "root-band"
+    },
+    "form": {
+      "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);