@taprootio/site-authoring 0.2.0 → 0.4.0

package/src/cli.js

@@ -1,6 +1,7 @@
 import {
   CLI_BINARY_NAME,
   CLI_NAME,
+  CLI_UPGRADE_COMMAND,
   CLI_VERSION,
   DEFAULT_LOGIN_KEY_NAME,
   DEPLOY_TARGET_PRODUCTION,
@@ -22,6 +23,8 @@ import {
   VERB_PREVIEW_PAGE,
   VERB_PREVIEW_REVOKE,
   VERB_PULL,
+  VERB_REDIRECTS_PULL,
+  VERB_REDIRECTS_PUSH,
   VERB_SITES,
   VERB_STATUS,
   VERB_THEME_PUSH,
@@ -56,8 +59,21 @@ import {
   CAPABILITY_DEPLOYMENTS,
   CAPABILITY_DESIGN,
 } from "./capabilities.js";
+import { assertCliCurrent } from "./session.js";
 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,
+ * 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]);
+
 // 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
 // never be shadowed by a one-token verb.
@@ -75,7 +91,9 @@ const VERBS = Object.freeze([
     offline: true,
     note: "Reads manifest.fixture.json plus the fixture's page, navigation, theme, appearance, header, brand, and footer files. "
       + "This proves local structure and semantics only. It does not prove authorization, live site ownership, concurrency, "
-      + "persisted round trips, or rendering; run a real pull and authorized preview before deployment.",
+      + "persisted round trips, or rendering; run a real pull and authorized preview before deployment. "
+      + `See '${CLI_BINARY_NAME} help fixture' for the manifest contract and for the path of the complete example `
+      + "fixture this package ships, which needs no credential and no pulled site.",
   },
   {
     name: VERB_LOGIN,
@@ -195,8 +213,9 @@ const VERBS = Object.freeze([
       + "The homepage is recorded with an empty path, so address it as '/'. "
       + "A selected path resolves to its one authoritative source from metadata alone, and that page is then validated "
       + "exactly as a whole push would validate it — site binding, manifest integrity, live create-or-update "
-      + "resolution, system-page rules, path uniqueness against the live site, media ownership, and two workspace "
-      + "files claiming one path all still fail closed. What a selection does not do is convert or validate the "
+      + "resolution, system-page rules, path uniqueness against the live site, media ownership, a live page whose "
+      + "stored-state revision moved since this workspace last reconciled with it (pages.push_conflict), and two "
+      + "workspace files claiming one path all still fail closed. What a selection does not do is convert or validate the "
       + "documents of pages it is not sending: an unrelated page left on an obsolete contract is reported by the "
       + "whole-workspace push, not used to block this one. The result states the selection and how many sources were "
       + "discovered and validated. "
@@ -210,10 +229,35 @@ const VERBS = Object.freeze([
   },
   {
     name: VERB_NAV_PUSH,
-    capabilities: [CAPABILITY_DESIGN],
+    // Content is for the read, not the write: every PAGE nav item is checked
+    // against the live page list before the tree is replaced, and that list is
+    // gated on site.pages.edit_any (TR00691).
+    capabilities: [CAPABILITY_CONTENT, CAPABILITY_DESIGN],
     tokens: ["nav", "push"],
     summary: "Replace the whole navigation tree from the local workspace.",
   },
+  {
+    name: VERB_REDIRECTS_PULL,
+    // A redirect is a content path, and both halves of the map — read and
+    // replace — are gated on site.pages.edit_any, which only Content carries.
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["redirects", "pull"],
+    summary: "Snapshot the site's whole redirect map into redirects.json.",
+    note: "Also part of 'pull'. Run it on its own to re-read the map after a page rename, or after a push was "
+      + "refused as a conflict, without re-pulling every page. It records the map's revision in the pull "
+      + "manifest; 'redirects push' sends that revision so a stale replace is refused rather than deleting an "
+      + "entry a rename recorded. See 'taproot-site help redirects'.",
+  },
+  {
+    name: VERB_REDIRECTS_PUSH,
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["redirects", "push"],
+    summary: "Validate redirects.json and replace the whole redirect map.",
+    note: "Run 'redirects pull' first. The whole file is validated locally by entry index — path normalization, "
+      + "targets, statuses, duplicates, chains, and loops — before anything is sent, and the site refuses a "
+      + "source a live page occupies. Entries take effect on the next deploy. "
+      + "See 'taproot-site help redirects'.",
+  },
   {
     name: VERB_THEME_PUSH,
     capabilities: [CAPABILITY_DESIGN],
@@ -251,7 +295,18 @@ const VERBS = Object.freeze([
   },
   {
     name: VERB_DEPLOY,
-    capabilities: [CAPABILITY_DEPLOYMENTS],
+    // Deployments is the only capability this verb *writes* with; the other two
+    // are for reads and re-reads the server makes on its behalf (TR00691).
+    // Content: --staging builds the candidate from the live page list
+    // (DeploySiteRequest.staged_page_ids names the ids explicitly), and that
+    // list is gated on site.pages.edit_any.
+    // Design: --production promotes a completed staging deployment, and the
+    // pipeline re-authorizes that deployment's *stored* candidate — every
+    // selected settings group and its navigation — against site.theme.manage,
+    // which only Design carries. Every candidate this CLI stages from a pulled
+    // workspace carries settings, navigation, or both, so a promotion without
+    // Design is refused.
+    capabilities: [CAPABILITY_CONTENT, CAPABILITY_DESIGN, CAPABILITY_DEPLOYMENTS],
     tokens: ["deploy"],
     summary: "Deploy to staging, or promote staging to production.",
     target: true,
@@ -265,6 +320,8 @@ const VERBS = Object.freeze([
     json: true,
     note: "Select the persisted draft by page path (as recorded by pull) or canonical lowercase UUID. "
       + "The homepage is recorded with an empty path, so address it as '/'. "
+      + "Preview before approving: approve consumes the draft, so a page that has been approved has no draft "
+      + "left to render and answers preview.no_draft. Review it on staging after a deploy instead. "
       + "The handoff URL in the result is single-use and expires two minutes after it is minted: opening it "
       + "consumes it, and a reused, shared, or bookmarked preview URL answers Not found. Run preview page again "
       + "for another. "
@@ -286,13 +343,30 @@ const VERBS = Object.freeze([
     // Content.
     capabilities: [CAPABILITY_CONTENT, CAPABILITY_DEPLOYMENTS],
     tokens: ["status"],
-    summary: "Report deployments, readiness, and image processing.",
+    summary: "Report the platform authoring switch, the CLI release, deployments, readiness, and image processing.",
     note: "Broken references are not included: that read remains"
       + " session-only on the server, so the result reports it as uncovered"
       + " rather than pretending an empty list means a clean site.",
   },
 ]);
 
+/**
+ * The shipped verb table's capability declarations, keyed by verb name.
+ *
+ * Exported so the tests enforce the table rather than restate it. The claim
+ * each entry makes — "this is the smallest set this verb's requests need" —
+ * went four releases without anything checking it, and it was wrong twice:
+ * `nav push` and `deploy` were each short of a read they make on every run, and
+ * `deploy` was short again of the promotion re-authorization the server runs on
+ * state the request only names (TR00691). A verb with no entry needs no site
+ * credential at all.
+ */
+export const VERB_CAPABILITIES = Object.freeze(Object.fromEntries(
+  VERBS
+    .filter((verb) => verb.capabilities !== undefined)
+    .map((verb) => [verb.name, Object.freeze([...verb.capabilities])]),
+));
+
 const COMMON_OPTIONS = `Options:
   --config <path>  Place before a config-reading verb; bypass parent discovery.
   --quiet          Suppress human progress. The JSON result is unchanged.
@@ -318,6 +392,15 @@ whoami, and env need no configuration and no site. The offline help family is
 human-readable by default; add --json for stable reference data. Exit codes: 0
 success, 1 failure, 2 usage fault.
 
+Troubleshooting: a command that fails with field=CliUpgradeRequired (or
+refusal=cli_outdated) means this CLI is behind the latest published release,
+which is the only release Taproot accepts. Nothing is wrong with the
+credential, the request, or the site, and no retry of this version succeeds.
+Run '${CLI_UPGRADE_COMMAND}' and try again; if the
+release is minutes old, npm may not serve it yet, so wait and retry the
+upgrade. Once a run has recorded a newer release, help, validate, and whoami
+refuse the same way offline. --version and --help always answer.
+
 Verbs:
 ${VERBS.map((verb) => `  ${verb.tokens.join(" ").padEnd(14)} ${verb.summary}`).join("\n")}
 
@@ -373,11 +456,22 @@ function verbHelp(verb) {
   // would have had to gain.
   const selfContained = verb.offline && !verb.readsLocalState;
   const prefix = selfContained ? CLI_BINARY_NAME : `${CLI_BINARY_NAME} [--config <path>]`;
+  // The offline boundary states the version gate too (TR00703). It is the one
+  // thing these verbs read that is not their own input, and a boundary sentence
+  // that omitted it would be describing a verb that no longer exists.
+  // `env` is offline too and deliberately outside the gate — switching Taproots
+  // is one of the things an outdated CLI must still be able to do — so the
+  // sentence is attached per verb rather than to offline-ness.
+  const upgradeGate = VERSION_GATED_OFFLINE_VERBS.includes(verb.name)
+    ? " It refuses only when a previous sign-in exchange recorded a newer published release than this CLI, because "
+      + "Taproot accepts only the latest; with nothing recorded it runs."
+    : "";
   const boundary = selfContained
-    ? "This offline verb reads no configuration or credential and performs no network request or write."
+    ? "This offline verb uses no credential and reads no configuration, and performs no network request and no "
+      + `write.${upgradeGate}`
     : verb.offline
     ? "This verb answers entirely from local state — the stored sign-in and the configuration — and makes no "
-      + "network request and no write."
+      + `network request and no write.${upgradeGate}`
     : verb.credentialFree
     ? `This verb reads the configuration but requires no existing credential. `
       + `${PUBLISH_KEY_ENVIRONMENT_VARIABLE} always takes precedence over the stored credential, so setting it leaves `
@@ -464,6 +558,8 @@ function parseReferenceArguments(arguments_) {
       || topic === "theme"
       || topic === "appearance"
       || topic === "footer"
+      || topic === "fixture"
+      || topic === "redirects"
     )
     && (subject !== undefined || extra.length > 0)) {
     throw usageError("help.usage", `The '${topic}' topic does not accept a name.`);
@@ -513,8 +609,10 @@ function referenceResult(parsed) {
       return { ...result, topic: "component", component };
     }
     case "nav":
+    case "redirects":
     case "media":
     case "preview":
+    case "fixture":
       return { ...result, topic: "workflow", referenceKind: parsed.topic, reference: getWorkflowReference(parsed.topic) };
     case "theme":
       return { ...result, topic: "presentation", referenceKind: "theme", reference: getThemeReference() };
@@ -750,9 +848,16 @@ function parseArguments(arguments_) {
   return {
     mode: "run",
     verb: verb.name,
-    // The smallest capability set this verb's requests need. It reaches the
-    // exchange so a content push never holds deploy, and a pull never holds
-    // delete (TR00645).
+    // The smallest capability set this verb's requests need — every permission
+    // the server resolves for them, not only the ones the verb's writes name.
+    // It reaches the exchange so a content push never holds deploy, and a pull
+    // never holds delete (TR00645). Two things count beyond the writes
+    // (TR00691): a read (nav push and deploy each list the site's pages first,
+    // and that list is gated on a Content permission), and a re-authorization
+    // of server-held state (deploy --production re-checks the promoted
+    // candidate's stored settings and navigation against a Design permission).
+    // `VERB_CAPABILITIES` below is what the tests pin against the routes each
+    // verb actually calls.
     capabilities: verb.capabilities,
     configPath,
     quiet,
@@ -811,10 +916,14 @@ export async function runCli({
       return 0;
     }
     if (parsed.mode === "reference") {
+      await assertCliCurrent(environment);
       const result = referenceResult(parsed);
       stdout.write(parsed.json ? `${serializeResult(result)}\n` : formatReferenceResult(result));
       return 0;
     }
+    if (VERSION_GATED_OFFLINE_VERBS.includes(parsed.verb)) {
+      await assertCliCurrent(environment);
+    }
     // Own properties only: a verb name must never resolve through the
     // prototype chain to something like `constructor`.
     const handler = Object.hasOwn(handlers, parsed.verb) ? handlers[parsed.verb] : undefined;

package/src/constants.js

@@ -1,5 +1,5 @@
 export const CLI_NAME = "@taprootio/site-authoring";
-export const CLI_VERSION = "0.2.0";
+export const CLI_VERSION = "0.4.0";
 export const CLI_BINARY_NAME = "taproot-site";
 export const RESULT_SCHEMA_VERSION = 1;
 export const CONFIG_FILE_NAME = "taproot-site.json";
@@ -82,6 +82,8 @@ export const VERB_LOGIN = "login";
 export const VERB_LOGOUT = "logout";
 export const VERB_PAGES_PUSH = "pages push";
 export const VERB_NAV_PUSH = "nav push";
+export const VERB_REDIRECTS_PULL = "redirects pull";
+export const VERB_REDIRECTS_PUSH = "redirects push";
 export const VERB_THEME_PUSH = "theme push";
 export const VERB_FOOTER_PUSH = "footer push";
 export const VERB_MEDIA_UPLOAD = "media upload";
@@ -99,7 +101,7 @@ export const DEPLOY_TARGET_STAGING = "staging";
 export const DEPLOY_TARGET_PRODUCTION = "production";
 
 /**
- * The refusal vocabulary TR00602/TR00603 speak, collapsed into the four
+ * The refusal vocabulary TR00602/TR00603/TR00691 speak, collapsed into the five
  * distinct client behaviors plus an explicit "we do not know" value. The CLI
  * keeps these apart because an agent's correct next move differs for each:
  * see `ApiError.refusalKind()` in transport.js.
@@ -108,6 +110,8 @@ export const REFUSAL_PLATFORM_PAUSED = "platform_paused";
 export const REFUSAL_CREDENTIAL_REJECTED = "credential_rejected";
 export const REFUSAL_PLAN_LIMIT = "plan_limit";
 export const REFUSAL_THROTTLED = "throttled";
+export const REFUSAL_CAPABILITY_MISSING = "capability_missing";
+export const REFUSAL_CLI_OUTDATED = "cli_outdated";
 export const REFUSAL_UNCLASSIFIED = "unclassified";
 
 export const REFUSAL_KINDS = Object.freeze([
@@ -115,6 +119,8 @@ export const REFUSAL_KINDS = Object.freeze([
   REFUSAL_CREDENTIAL_REJECTED,
   REFUSAL_PLAN_LIMIT,
   REFUSAL_THROTTLED,
+  REFUSAL_CAPABILITY_MISSING,
+  REFUSAL_CLI_OUTDATED,
   REFUSAL_UNCLASSIFIED,
 ]);
 
@@ -125,6 +131,53 @@ export const ROLLOUT_REFUSAL_FIELD = "SiteAuthoringRollout";
 export const CREDENTIAL_REFUSAL_FIELD = "ExternalApiKey";
 export const PLAN_LIMIT_REFUSAL_FIELD = "UpgradePrompt";
 
+/**
+ * The field Taproot refuses an outdated CLI with (TR00703).
+ *
+ * Named so the name alone is the instruction, because for every CLI published
+ * before this check that is the whole message: an unknown refusal field prints
+ * as "Taproot rejected the request field '<name>'." and nothing else.
+ */
+export const CLI_UPGRADE_REFUSAL_FIELD = "CliUpgradeRequired";
+
+/**
+ * How an operator gets current. Composed from {@link CLI_NAME} so the command
+ * in a refusal cannot drift from the package that refusal is about.
+ */
+export const CLI_UPGRADE_COMMAND = `npm install -g ${CLI_NAME}@latest`;
+
+/**
+ * The platform switch behind every `platform_paused` refusal, and where the one
+ * person who can undo it goes to look (TR00692).
+ *
+ * Held here rather than written out at each site because four surfaces say it —
+ * the pre-write warning, `status`, `whoami`, and the refusal guidance — and a
+ * setting key spelled four ways is a key an operator cannot search for. The key
+ * is a wire identity and is never reworded; the location is display text.
+ */
+export const EXTERNAL_WRITES_SETTING_KEY = "site_authoring.external_writes_enabled";
+export const EXTERNAL_WRITES_SETTING_LOCATION =
+  "Admin → Platform settings → Site Authoring (\"External site authoring writes enabled\")";
+
+/**
+ * The `google.rpc.ErrorInfo` reason a key-mode permission denial carries
+ * (TR00691, `SiteAuthoringKeyDenial` on the server). A wire identity, matched
+ * exactly.
+ */
+export const CAPABILITY_REFUSAL_REASON = "SITE_AUTHORING_CAPABILITY_MISSING";
+
+/**
+ * The `field` a capability refusal reports on the JSON error.
+ *
+ * The server sends this refusal as `ErrorInfo`, not as a field violation — the
+ * request is well formed and the credential is too narrow, so a `BadRequest`
+ * would misstate the status. Automation still wants one shape to branch on, so
+ * the CLI names the field itself, exactly as `platform_paused` carries
+ * `SiteAuthoringRollout`. It is the CLI's own label rather than a value read
+ * off the wire, which is why nothing matches an incoming field against it.
+ */
+export const CAPABILITY_REFUSAL_FIELD = "GrantedCapabilities";
+
 // gRPC `ResourceExhausted`. Transcoded responses carry the numeric code in the
 // body; the HTTP mapping is 429.
 export const GRPC_RESOURCE_EXHAUSTED = 8;
@@ -144,6 +197,10 @@ export const LIMITS = Object.freeze({
   configDiscoveryParents: 32,
   workspacePathBytes: 4 * 1024,
   apiResponseBytes: 1024 * 1024,
+  // The redirect map is the one read whose valid size exceeds the ordinary
+  // response bound: two thousand entries with long absolute targets. Sized
+  // with the workspace file that holds it (WORKSPACE_LIMITS.redirectsBytes).
+  redirectMapResponseBytes: 8 * 1024 * 1024,
   requestMilliseconds: 60_000,
   uploadMilliseconds: 5 * 60_000,
   deploymentMilliseconds: 30 * 60_000,

package/src/contact-url.js

@@ -0,0 +1,63 @@
+import { hasControlCharacter } from "./errors.js";
+
+/**
+ * The one rule for an outbound target on a footer link or a navigation item.
+ *
+ * A local business's phone number and address are the two things a visitor
+ * looks for in a header and a footer, and page links have accepted `tel:` and
+ * `mailto:` since D12. This is the same permissive scheme set the published
+ * renderer already applies to page content (`generator/src/url-safety.ts`,
+ * `shared/tiptap-prosemirror.ts`, `ux/client/src/common/sanitize-html.ts`),
+ * narrowed to what a *stored* target may be: absolute, so there is no base to
+ * resolve against at publish time, and credential-free, so a footer cannot
+ * carry someone's password into published HTML.
+ *
+ * `tel:` and `mailto:` are opaque URLs whose body is content — a number with
+ * its punctuation, an address with its plus-tag. Callers emit the value
+ * verbatim after this check rather than round-tripping it through
+ * `URL.toString()`, which re-encodes both.
+ */
+
+/** Longest external target a footer link or a navigation item may carry. */
+export const CONTACT_OR_WEB_URL_MAX_LENGTH = 2_048;
+
+/**
+ * The requirement clause every layer says when it refuses a target, so the
+ * CLI, the editors, and the server all name the same four schemes.
+ */
+export const CONTACT_OR_WEB_URL_REQUIREMENT =
+  "must be an absolute http or https URL without credentials, or a mailto or tel contact URL";
+
+const WEB_PROTOCOLS = new Set(["http:", "https:"]);
+const CONTACT_PROTOCOLS = new Set(["mailto:", "tel:"]);
+
+/**
+ * Whether `value` is a target the footer and navigation contracts accept.
+ *
+ * ASCII controls, C1 controls, and backslashes are refused before the scheme
+ * is looked at: browsers normalize them inconsistently, and a line break in a
+ * `mailto:` is the header-injection vector.
+ */
+export function isContactOrWebUrl(value, maximumLength = CONTACT_OR_WEB_URL_MAX_LENGTH) {
+  if (typeof value !== "string" || value.length === 0 || value.length > maximumLength) return false;
+  if (hasControlCharacter(value) || value.includes("\\")) return false;
+
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return false;
+  }
+
+  if (WEB_PROTOCOLS.has(parsed.protocol)) {
+    return parsed.username === "" && parsed.password === "" && parsed.hostname !== "";
+  }
+  // The body is everything after `tel:` or `mailto:`; an empty one is a link
+  // to nothing, which publishes as a dead anchor rather than a refusal. A
+  // body that opens with `//` is an authority, which a contact URL has no use
+  // for, and the four layers agree on refusing it rather than on how each
+  // parser validates one.
+  return CONTACT_PROTOCOLS.has(parsed.protocol)
+    && parsed.pathname !== ""
+    && !value.slice(value.indexOf(":") + 1).startsWith("//");
+}

package/src/content/components.js

@@ -149,7 +149,11 @@ const CTA = Object.freeze({
   buttonText: str(),
   buttonUrl: actionUrl(),
   variant: enumOf("primary", "danger"),
-  borderWidth: num({ integer: true, minimum: 0 }),
+  borderWidth: num({
+    integer: true,
+    minimum: 0,
+    description: "Pixel border around the call-to-action panel; 0 leaves it unbordered.",
+  }),
   imagePosition: enumOf("top", "left", "right"),
   mediaImage: image(),
 });
@@ -167,7 +171,11 @@ const FEATURE_GRID = Object.freeze({
   ),
   columns: num({ values: Object.freeze([2, 3, 4]) }),
   iconSize: enumOf("small", "medium", "large", "xlarge"),
-  borderWidth: num({ integer: true, minimum: 0 }),
+  borderWidth: num({
+    integer: true,
+    minimum: 0,
+    description: "Pixel border around each item, as on a card grid; the grid itself is never framed. 0 boxes nothing.",
+  }),
 });
 
 /** `TestimonialData` and its `TestimonialItem`. */
@@ -184,7 +192,11 @@ const TESTIMONIAL = Object.freeze({
   columns: num({ values: Object.freeze([1, 2, 3]) }),
   carousel: bool(),
   interval: num({ integer: true, minimum: 2000 }),
-  borderWidth: num({ integer: true, minimum: 0 }),
+  borderWidth: num({
+    integer: true,
+    minimum: 0,
+    description: "Pixel border around the whole set of quotations — the grid or the carousel; 0 leaves it unbordered.",
+  }),
 });
 
 /** `LatestPostsData` — resolved at generation time. */
@@ -212,7 +224,11 @@ const CARD_GRID = Object.freeze({
     { kind: "value", value: Object.freeze([]) },
   ),
   columns: num({ values: Object.freeze([2, 3]) }),
-  borderWidth: num({ integer: true, minimum: 0 }),
+  borderWidth: num({
+    integer: true,
+    minimum: 0,
+    description: "Pixel border around each card; the grid itself is never framed. 0 boxes nothing.",
+  }),
 });
 
 /** `ImageBannerData`. */
@@ -372,6 +388,7 @@ const COMPONENT_DEFINITIONS = Object.freeze({
     [
       "Each linked item needs a title that remains meaningful as link text.",
       "Icon images need descriptive alt text when they convey information; otherwise use an empty alt value.",
+      "Item title and description are plain text: an item's url makes the whole item the link, and no link can be placed inside the text. Put linked prose in a paragraph beside the grid.",
     ],
     {
       items: [
@@ -428,6 +445,7 @@ const COMPONENT_DEFINITIONS = Object.freeze({
     [
       "Every linked card needs a title that describes its destination.",
       "Card images need descriptive alt text unless they are decorative.",
+      "Card title and description are plain text: a card's linkUrl makes the whole card the link, and no link can be placed inside the text. Put linked prose in a paragraph beside the grid.",
     ],
     {
       cards: [
@@ -544,6 +562,10 @@ function referenceSchema(spec) {
       if (spec.values) schema.enum = [...spec.values];
       if (spec.minimum !== undefined) schema.minimum = spec.minimum;
       if (spec.maximum !== undefined) schema.maximum = spec.maximum;
+      // A numeric field whose units say nothing about what the number does —
+      // `borderWidth` is the case — carries its meaning here so `help
+      // component` prints it beside the constraints.
+      if (spec.description) schema.description = spec.description;
       return schema;
     }
     case "array":

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

@@ -370,7 +370,7 @@
   "inlineFacts": {
     "nodeType": "inlineFacts",
     "label": "Inline facts",
-    "help": "A compact ordered row of labeled facts whose values may be native links.",
+    "help": "A compact ordered row of facts whose values may be native links. A fact that names itself needs no label.",
     "attrs": {
       "items": {
         "type": "array",
@@ -388,7 +388,8 @@
           },
           "label": {
             "type": "plain-text",
-            "required": true,
+            "required": false,
+            "default": null,
             "minScalars": 1,
             "maxScalars": 120,
             "nonWhitespace": true

package/src/content/inline-facts.js

@@ -64,9 +64,13 @@ export function normalizeInlineFactsItems(
       }
     }
 
+    // The value is the fact; the label names it when the value does not name
+    // itself. An omitted or null label is the standalone fact, while an empty
+    // string stays refused so a half-authored item is still caught.
     for (const name of ["value", "label"]) {
       const field = definition.fields[name];
       const entry = item[name];
+      if (!field.required && (entry === undefined || entry === null)) continue;
       if (typeof entry !== "string" || (field.nonWhitespace && entry.trim() === "")) {
         report(`${itemPath}/${name}`, CODES.attrInvalid, `Inline fact ${name} must contain non-whitespace text.`);
       } else if (scalarLength(entry, field.maxScalars) > field.maxScalars) {
@@ -88,7 +92,7 @@ export function normalizeInlineFactsItems(
 
     items.push(Object.freeze({
       value: item.value,
-      label: item.label,
+      ...(typeof item.label === "string" ? { label: item.label } : {}),
       ...(typeof item.url === "string" ? { url: item.url.trim() } : {}),
     }));
   });

package/src/content/tiptap-prosemirror.ts

@@ -496,10 +496,20 @@ function countUnicodeScalars(value: string): number {
 
 type NormalizedInlineFact = {
   value: string;
-  label: string;
+  label?: string;
   url?: string;
 };
 
+/**
+ * The row is a list, not a description list: a fact whose value names itself
+ * carries no label, and `dl` has no valid shape for a `dd` without a `dt`.
+ * The label keeps its leading source position so the CSS `order` rules that
+ * lift the value above it stay unchanged for a labelled fact. The list roles
+ * are explicit because `list-style: none` makes WebKit drop them, and the
+ * label is separated from the value by a space: search indexers take adjacent
+ * inline elements as one word, and a whitespace-only anonymous flex item is
+ * not rendered, so the row looks the same.
+ */
 function renderInlineFacts(
   node: ProseMirrorNode,
   options: RenderProseMirrorOptions,
@@ -512,17 +522,18 @@ function renderInlineFacts(
     const value = fact.url
       ? renderElement("a", { href: fact.url }, escapeHtml(fact.value))
       : escapeHtml(fact.value);
+    const label = fact.label === undefined
+      ? ""
+      : `${renderElement("span", { class: "taproot-inline-fact__label" }, escapeHtml(fact.label))} `;
     return renderElement(
-      "div",
-      { class: "taproot-inline-fact" },
-      `${renderElement("dt", { class: "taproot-inline-fact__label" }, escapeHtml(fact.label))}${
-        renderElement("dd", { class: "taproot-inline-fact__value" }, value)
-      }`,
+      "li",
+      { class: "taproot-inline-fact", role: "listitem" },
+      `${label}${renderElement("span", { class: "taproot-inline-fact__value" }, value)}`,
     );
   }).join("");
   return renderElement(
-    "dl",
-    withProseMeasure({ class: "taproot-inline-facts" }, node.type, options),
+    "ul",
+    withProseMeasure({ class: "taproot-inline-facts", role: "list" }, node.type, options),
     items,
   );
 }
@@ -544,14 +555,17 @@ function normalizeInlineFacts(node: ProseMirrorNode): NormalizedInlineFact[] | u
   for (const value of node.attrs.items) {
     if (!isRecord(value) || !hasOnlyKeys(value, fieldKeys)) return undefined;
     const factValue = stringAttr(value.value);
-    const label = stringAttr(value.label);
     if (
       !factValue
-      || !label
       || factValue.trim() === ""
-      || label.trim() === ""
       || countUnicodeScalars(factValue) > definition.fields.value.maxScalars
-      || countUnicodeScalars(label) > definition.fields.label.maxScalars
+    ) return undefined;
+    // An omitted or null label is the standalone fact; an empty string is a
+    // half-authored one and still fails the row closed.
+    const label = value.label === undefined || value.label === null ? undefined : stringAttr(value.label);
+    if (
+      value.label !== undefined && value.label !== null
+      && (!label || label.trim() === "" || countUnicodeScalars(label) > definition.fields.label.maxScalars)
     ) return undefined;
     const url = value.url === undefined || value.url === null ? undefined : stringAttr(value.url);
     if (value.url !== undefined && value.url !== null && (!url || !isSafeUrl(url))) return undefined;