@taprootio/site-authoring 0.24.0 → 0.27.0

package/README.md

@@ -235,8 +235,8 @@ 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` and `forms` verbs, `approve`, and the
-  `preview` verbs refuse with `surface.presentation_only` before any request.
+  `pages push`, `nav push`, the `redirects`, `forms` and `marketing` verbs, `link build`,
+  `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`.
 
@@ -641,6 +641,54 @@ and takes effect without publishing or a new form version. Delivery requires
 Taproot's rollout and email provider readiness; opt-in does not enable either
 or backfill earlier submissions. The CLI never pulls visitor answers.
 
+### Campaigns, placements and tracked links
+
+A campaign groups the links of one push, and a placement names the spot a
+link appears, such as a newsletter footer. Both are bounded sets of public
+keys the site's release admits, so a page view that carries a matching
+`utm_campaign` or `utm_content` is counted under it. Each is one JSON file:
+`marketing/campaigns.json` is `{ campaigns: [{ key, name, note?, starts_on?,
+ends_on? }] }` and `marketing/placements.json` is `{ placements: [{ key, name
+}] }`.
+
+```bash
+taproot-site marketing pull          # write both files, with a baseline
+# edit marketing/campaigns.json and marketing/placements.json
+taproot-site marketing push          # create, update and restore
+taproot-site marketing push --archive  # also archive what the files leave out
+taproot-site link build --path /recipes/spring-salad --source newsletter \
+  --campaign spring-launch --placement nl-footer
+```
+
+`marketing pull` replaces both files with the site's live records, each with
+the read-only `state` (live, publishing, goes_live_with_first_publish,
+not_in_current_release) and `counted_from`, the day its key first went live.
+Archived records are listed and not written. `marketing push` validates both
+files, compares every record with the site, and then creates a key the site
+lacks, updates the labels of an existing key, and restores an archived key a
+file names. A key is public URL text and never changes or returns to use, so a
+changed key is a new record; the old one is archived only when you pass
+`--archive`, and only if this workspace pulled it. A record that changed on the
+site since the pull is refused (`marketing.concurrent_modification`), as is a
+key the site has that this workspace never pulled (`marketing.pull_required`).
+Quota and key refusals are shown as Taproot words them. Like `forms push`, it
+has no plan step: it reads the site, refuses a stale baseline, and writes.
+Creating or restoring a key queues the silent release that starts counting it;
+nothing is deployed or waited for.
+
+`link build` prints one address and saves nothing. It uses the Marketing link
+builder's own rules, compiled from the app: the source decides the medium
+(`reader` is not offered), a `utm_source`, `utm_medium`, `utm_campaign` or `utm_content` already on the path is replaced (other `utm_` pairs are kept), and a
+campaign or placement is checked against `marketing/*.json` when the workspace
+has them, and otherwise against the live site. A key that is not live yet is
+allowed, with a note that page views count under the source only until it is
+(a note read from a file is as of the last `marketing pull` or push).
+The host is the signed-in site's public address; pass `--domain <host>` when
+only a site credential is available. The `delegation.content` capability
+carries what these verbs need (`site.analytics.view`, plus the publish
+permission to change anything); `whoami` reports whether the last exchange
+held it. `help marketing` and `help link` state the contracts.
+
 `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.24.0",
+  "version": "0.27.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,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@taprootio/espalier": "6.5.0",
+    "@taprootio/espalier": "6.7.0",
     "mediabunny": "1.61.1"
   },
   "scripts": {

package/src/analytics-campaign.json

@@ -0,0 +1,31 @@
+{
+  "version": 1,
+  "keyPattern": "^[a-z0-9-]{3,32}$",
+  "keyMinLength": 3,
+  "keyMaxLength": 32,
+  "maxActivePerSite": 50,
+  "artifactPath": "_taproot/analytics-campaigns.json",
+  "artifactVersion": 1,
+  "collectorMarker": "c1",
+  "maxDigitRun": 8,
+  "maxTotalPerSite": 500,
+  "nameMaxLength": 80,
+  "noteMaxLength": 500,
+  "vectors": [
+    {"value": "spring-26", "valid": true},
+    {"value": "abc", "valid": true},
+    {"value": "ab", "valid": false},
+    {"value": "a-very-long-campaign-key-that-is-over-32", "valid": false},
+    {"value": "Spring-26", "valid": false},
+    {"value": "spring_26", "valid": false},
+    {"value": "spring 26", "valid": false},
+    {"value": "spring|26", "valid": false},
+    {"value": "spring.26", "valid": false},
+    {"value": "", "valid": false},
+    {"value": "-leading", "valid": true},
+    {"value": "x12345678y", "valid": true},
+    {"value": "promo-123456789", "valid": false},
+    {"value": "spring-26\n", "valid": false},
+    {"value": "0123456789", "valid": false}
+  ]
+}

package/src/analytics-link-label.json

@@ -0,0 +1,22 @@
+{
+  "version": 1,
+  "keyGrammar": "campaign",
+  "artifactPath": "_taproot/analytics-links.json",
+  "artifactVersion": 1,
+  "collectorMarker": "c2",
+  "maxActivePerSite": 200,
+  "maxTotalPerSite": 2000,
+  "nameMaxLength": 80,
+  "vectors": [
+    {"value": "nl-footer", "valid": true},
+    {"value": "abc", "valid": true},
+    {"value": "ab", "valid": false},
+    {"value": "NL-footer", "valid": false},
+    {"value": "nl_footer", "valid": false},
+    {"value": "nl footer", "valid": false},
+    {"value": "nl|footer", "valid": false},
+    {"value": "a-label-key-that-is-longer-than-32", "valid": false},
+    {"value": "promo-123456789", "valid": false},
+    {"value": "", "valid": false}
+  ]
+}

package/src/analytics-source-vocabulary.json

@@ -0,0 +1,17 @@
+{
+  "version": 1,
+  "media": ["social", "email", "share"],
+  "sources": [
+    { "key": "linkedin", "name": "LinkedIn", "medium": "social", "aliases": ["linkedin.com", "lnkd.in", "com.linkedin.android"] },
+    { "key": "x", "name": "X", "medium": "social", "aliases": ["x.com", "twitter.com", "t.co", "com.twitter.android"] },
+    { "key": "facebook", "name": "Facebook", "medium": "social", "aliases": ["facebook.com", "fb.com", "fb.me", "com.facebook.katana", "com.facebook.lite"] },
+    { "key": "instagram", "name": "Instagram", "medium": "social", "aliases": ["instagram.com", "com.instagram.android"] },
+    { "key": "threads", "name": "Threads", "medium": "social", "aliases": ["threads.net", "threads.com", "com.instagram.barcelona"] },
+    { "key": "bluesky", "name": "Bluesky", "medium": "social", "aliases": ["bsky.app", "bsky.social", "xyz.blueskyweb.app"] },
+    { "key": "mastodon", "name": "Mastodon", "medium": "social", "aliases": ["mastodon.social", "mastodon.online", "org.joinmastodon.android"] },
+    { "key": "reddit", "name": "Reddit", "medium": "social", "aliases": ["reddit.com", "redd.it", "com.reddit.frontpage"] },
+    { "key": "youtube", "name": "YouTube", "medium": "social", "aliases": ["youtube.com", "youtu.be", "com.google.android.youtube"] },
+    { "key": "newsletter", "name": "Newsletter", "medium": "email", "aliases": [] },
+    { "key": "reader", "name": "Reader shares", "medium": "share", "aliases": [] }
+  ]
+}

package/src/capabilities.js

@@ -24,7 +24,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, media, and form definitions",
+  "delegation.content": "write pages, media, form definitions, campaigns, and placements",
   "delegation.design": "set the theme, navigation, and footer",
   "delegation.deployments": "stage and deploy",
 });

package/src/changelog.json

@@ -1,5 +1,43 @@
 {
   "entries": [
+    {
+      "version": "0.27.0",
+      "note": "Embedded forms inherit configurable background, border and shadow defaults from the site, with per-form overrides.",
+      "behavior": [
+        "Form definitions accept sparse presentation.background, presentation.border and presentation.shadow boolean overrides. Omitted values inherit the site; explicit false disables the decoration. An empty presentation object is omitted by the form editor.",
+        "Site publishing preferences expose formBoxBackground, formBoxBorder and formBoxShadow. Background and shadow default on; border defaults off. Stage publishing preferences and the form version to apply appearance changes.",
+        "Forms pull and push preserve appearance overrides, including explicit false.",
+        "The help reference version is 44."
+      ],
+      "help": [
+        "forms",
+        "settings"
+      ]
+    },
+    {
+      "version": "0.26.0",
+      "note": "marketing pull and marketing push keep a site's campaigns and placements as files, and link build prints a tracked address, so an agent can run a site's attribution over the CLI.",
+      "behavior": [
+        "New verbs: taproot-site marketing pull, marketing push [--archive] and link build --path <page> --source <key> [--campaign <key>] [--placement <key>] [--domain <host>]. A key now carries the permissions they need: delegation.content includes site.analytics.view, so a credential minted before this release gains read access to the site's campaigns and placements and, with the publish permission it already held, may change them.",
+        "marketing pull writes marketing/campaigns.json and marketing/placements.json (key, name, a campaign's note, starts_on and ends_on, and the read-only state and counted_from) and records a baseline in the pull manifest; a plain pull carries it forward. marketing push validates both files, compares every record with the site, and creates a new key, updates the labels of an existing one, or restores an archived key the file names. A key is public and never changes, so a changed key is a new record; a record the file leaves out is archived only with --archive, and only if the workspace pulled it. A record that changed on the site since the pull is refused (marketing.concurrent_modification, marketing.pull_required). Quota and key refusals are shown as Taproot returns them. There is no plan or apply step, as with forms push.",
+        "link build prints one address and saves nothing, with the Marketing link builder's own rules: the source decides the medium, the reader source is not offered, a utm_source, utm_medium, utm_campaign or utm_content on the path is replaced, and a campaign or placement is checked against marketing/*.json when the workspace has it, otherwise against the site. One that is not live yet is allowed with the builder's note that page views count under the source only until it is. The host is the signed-in site's public address; pass --domain when only a site credential is available.",
+        "whoami reports whether the last exchange allows campaigns and placements (marketing.access).",
+        "The help reference version is 43.",
+        "Built against Espalier 6.7.0. The default site theme is rebuilt against it and its content is unchanged except for the recorded Espalier version, so pulled and validated themes behave as before."
+      ],
+      "help": [
+        "marketing",
+        "link"
+      ]
+    },
+    {
+      "version": "0.25.0",
+      "note": "Redirects from /s/ addresses are ordinary redirects now that tracked share links are retired.",
+      "behavior": [
+        "A redirect whose source is /s/<anything> saves and validates like any other source. The redirect.source_share_link site-check rule is gone, so offline checks and the server no longer refuse it."
+      ],
+      "help": []
+    },
     {
       "version": "0.24.0",
       "note": "Site-specific consent enables legal draft authoring through JSON; legal approval and publication remain in the app.",

package/src/cli.js

@@ -33,8 +33,11 @@ import {
   VERB_FORMS_PUSH,
   VERB_FORMS_VALIDATE,
   VERB_HELP,
+  VERB_LINK_BUILD,
   VERB_LOGIN,
   VERB_LOGOUT,
+  VERB_MARKETING_PULL,
+  VERB_MARKETING_PUSH,
   VERB_MEDIA_UPLOAD,
   VERB_NAV_PUSH,
   VERB_PAGES_DELETE,
@@ -88,12 +91,15 @@ import {
   REFERENCE_VERSION,
 } from "./reference-help.js";
 import { FONT_CATEGORIES, getFontCatalogReference } from "./font-catalog.js";
+import { LINK_SOURCES } from "./marketing-contract.js";
 import { assertCliCurrent } from "./session.js";
 import { ApiError } from "./transport.js";
 import { formatThemeResolve } from "./theme-resolve.js";
 import { MAXIMUM_THEME_OPEN_MAP_KEY_SCALARS } from "./theme-validation.js";
 import { VERB_HANDLERS } from "./verbs/index.js";
 
+const LINK_SOURCE_KEYS = LINK_SOURCES.map((source) => source.key);
+
 /**
  * The verbs the local version gate applies to (TR00703).
  *
@@ -591,6 +597,45 @@ const VERBS = Object.freeze([
       + "that the caller may write forms. "
       + "See 'taproot-site help forms'.",
   },
+  {
+    name: VERB_MARKETING_PULL,
+    surface: SURFACE_STANDARD,
+    // Campaigns and placements ride the content capability, which carries the analytics-view permission that
+    // reads them and the publish permission that changes them (TR01301).
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["marketing", "pull"],
+    summary: "Write the site's live campaigns and placements to marketing/ and record what was read.",
+    note: "Needs a pulled workspace ('pull' first). It replaces marketing/campaigns.json and marketing/placements.json "
+      + "with the site's records, each with its read-only state and the day its key was first counted from, and records "
+      + "a baseline that 'marketing push' fences against. Archived records are listed and not written. "
+      + "See 'taproot-site help marketing'.",
+  },
+  {
+    name: VERB_MARKETING_PUSH,
+    surface: SURFACE_STANDARD,
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["marketing", "push"],
+    archiveOption: true,
+    summary: "Create, update and restore the campaigns and placements the marketing files name.",
+    note: "Every file is validated and compared with the site before anything is written. A key is public URL text "
+      + "and never changes, so a new key is a new record; a record the file leaves out is archived only with "
+      + "--archive, and only if this workspace pulled it. A file that names an archived key restores it. Creating or "
+      + "restoring a key queues the silent release that starts counting it; run 'marketing pull' later to see it live. "
+      + "A quota or key refusal is reported as Taproot returns it. See 'taproot-site help marketing'.",
+  },
+  {
+    name: VERB_LINK_BUILD,
+    surface: SURFACE_STANDARD,
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["link", "build"],
+    linkOptions: true,
+    summary: "Print one tracked address for a page, a source, and an optional campaign and placement.",
+    note: "Saves nothing. The medium is set by the source ('reader' is not offered: a published page's own share "
+      + "action sets it). The host is the signed-in site's public address; pass --domain when only a site credential "
+      + "is available. A campaign or placement is checked against marketing/*.json when the workspace has the file, "
+      + "and otherwise against the live site; one that is not live yet is allowed with a note that page views count "
+      + "under the source only until it is. See 'taproot-site help link'.",
+  },
   {
     name: VERB_THEME_PUSH,
     surface: SURFACE_DOCS_PRESENTATION,
@@ -978,6 +1023,17 @@ function verbHelp(verb) {
   const dryRunOption = verb.dryRun
     ? "\n  --dry-run        Read the site and report what a push would change, without writing."
     : "";
+  const archiveOption = verb.archiveOption
+    ? "\n  --archive        Archive a campaign or placement the file leaves out (never done without this)."
+    : "";
+  const linkOptions = verb.linkOptions
+    ? `\n  --path <page>        The page on this site; / or '' for the home page. A query or #fragment you add is kept (required).
+  --source <key>       Where you will post the link: ${LINK_SOURCE_KEYS.join(", ")} (required).
+  --campaign <key>     A campaign key to group links from one push (optional).
+  --placement <key>    A placement key naming the spot the link will appear (optional).
+                       Write --option=<value> for a value that starts with hyphens.
+  --domain <host>      The site's public host; for a site credential with no sign-in to read it from.`
+    : "";
   const planOption = verb.planHash
     ? "\n  --plan <hash>    The planHash 'plan' reported; required."
     : "";
@@ -1060,7 +1116,7 @@ function verbHelp(verb) {
 ${verb.summary}
 ${boundary}
 
-${options}${targetOption}${handoffOption}${reviewPathOption}${sinceOption}${deliveryTargetOption}${metaOptions}${authorOptions}${jsonOption}${resolveOptions}${dryRunOption}${planOption}${nameOption}${note}
+${options}${targetOption}${handoffOption}${reviewPathOption}${sinceOption}${deliveryTargetOption}${metaOptions}${authorOptions}${jsonOption}${resolveOptions}${dryRunOption}${archiveOption}${linkOptions}${planOption}${nameOption}${note}
 `;
 }
 
@@ -1077,6 +1133,39 @@ function matchVerb(arguments_) {
   return matched;
 }
 
+/** The `link build` options and the invocation field each fills. */
+const LINK_OPTION_FIELDS = Object.freeze({
+  "--path": "linkPath",
+  "--source": "linkSource",
+  "--campaign": "linkCampaign",
+  "--placement": "linkPlacement",
+  "--domain": "linkDomain",
+});
+
+/**
+ * The value after a `link build` option. An option-like value is refused so a missing value never swallows the
+ * next flag; only --path may be empty, which names the home page.
+ */
+function parseLinkOption(rest, index, argument) {
+  // `--campaign=--launch` is the one way to pass a value that starts with `--`, which a valid key may (a key may
+  // begin with a hyphen); a separated value that looks like an option is refused so a missing value never swallows
+  // the next flag.
+  const [name, inline] = argument.includes("=") ? [argument.slice(0, argument.indexOf("=")), argument.slice(argument.indexOf("=") + 1)] : [argument, undefined];
+  const value = inline ?? rest[index + 1];
+  const field = name.slice(2);
+  if (typeof value !== "string" || (inline === undefined && value.startsWith("--")) || (value === "" && name !== "--path")) {
+    throw usageError("cli.option_value", `${name} requires a value.`, { field });
+  }
+  if (Buffer.byteLength(value, "utf8") > LIMITS.configPathBytes || hasAsciiControl(value)) {
+    throw usageError(
+      "cli.option_value",
+      `${name} must be at most ${LIMITS.configPathBytes} bytes with no control characters.`,
+      { field },
+    );
+  }
+  return { name, value, consumed: inline === undefined ? 1 : 0 };
+}
+
 function usageError(code, message, options = {}) {
   return new SiteAuthoringError(code, message, { ...options, exitCode: 2 });
 }
@@ -1126,6 +1215,8 @@ function parseReferenceArguments(arguments_) {
       || topic === "fixture"
       || topic === "redirects"
       || topic === "forms"
+      || topic === "marketing"
+      || topic === "link"
       || topic === "walkthrough"
       || topic === "delivery"
       || topic === "import"
@@ -1197,6 +1288,8 @@ function referenceResult(parsed) {
     case "nav":
     case "redirects":
     case "forms":
+    case "marketing":
+    case "link":
     case "media":
     case "preview":
     case "fixture":
@@ -1451,6 +1544,8 @@ function parseArguments(arguments_) {
   let fromSite = false;
   let keyName;
   let planHash;
+  let archive = false;
+  const linkValues = {};
   let metaTitle;
   let metaDescription;
   let metaAuthor;
@@ -1553,6 +1648,21 @@ function parseArguments(arguments_) {
       index += 1;
       continue;
     }
+    if (verb.archiveOption && argument === "--archive") {
+      if (archive) throw usageError("cli.duplicate_option", "--archive may be supplied only once.");
+      archive = true;
+      continue;
+    }
+    if (verb.linkOptions && Object.hasOwn(LINK_OPTION_FIELDS, argument.split("=")[0])) {
+      const { name, value, consumed } = parseLinkOption(rest, index, argument);
+      const field = LINK_OPTION_FIELDS[name];
+      if (linkValues[field] !== undefined) {
+        throw usageError("cli.duplicate_option", `${name} may be supplied only once.`, { field: name.slice(2) });
+      }
+      linkValues[field] = value;
+      index += consumed;
+      continue;
+    }
     if (verb.dryRun && argument === "--dry-run") {
       if (dryRun) throw usageError("cli.duplicate_option", "--dry-run may be supplied only once.");
       dryRun = true;
@@ -1796,6 +1906,8 @@ function parseArguments(arguments_) {
     ...(themeContext === undefined ? {} : { themeContext }),
     ...(fromSite ? { fromSite } : {}),
     ...(planHash === undefined ? {} : { planHash }),
+    ...(archive ? { archive } : {}),
+    ...linkValues,
     ...(metaTitle === undefined ? {} : { metaTitle }),
     ...(metaDescription === undefined ? {} : { metaDescription }),
     ...(metaAuthor === undefined ? {} : { metaAuthor }),
@@ -1893,6 +2005,8 @@ export async function runCli({
       ...(parsed.themeContext === undefined ? {} : { themeContext: parsed.themeContext }),
       ...(parsed.fromSite === undefined ? {} : { fromSite: parsed.fromSite }),
       ...(parsed.planHash === undefined ? {} : { planHash: parsed.planHash }),
+      ...(parsed.archive ? { archive: true } : {}),
+      ...Object.fromEntries(Object.values(LINK_OPTION_FIELDS).filter((field) => parsed[field] !== undefined).map((field) => [field, parsed[field]])),
       // Only when given, like the other optional fields, so each verb keeps its default (TR00925).
       ...(parsed.deliveryUrl === undefined ? {} : { deliveryUrl: parsed.deliveryUrl }),
       ...(parsed.propagationWaitSeconds === undefined ? {} : { propagationWaitSeconds: parsed.propagationWaitSeconds }),

package/src/constants.js

@@ -94,6 +94,9 @@ 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_MARKETING_PULL = "marketing pull";
+export const VERB_MARKETING_PUSH = "marketing push";
+export const VERB_LINK_BUILD = "link build";
 export const VERB_THEME_PUSH = "theme push";
 export const VERB_THEME_RESOLVE = "theme resolve";
 export const VERB_FOOTER_PUSH = "footer push";

package/src/field-schema.json

@@ -22,6 +22,17 @@
       "type": "string",
       "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
     },
+    "presentation": {
+      "description": "Sparse embedded-form appearance choices. Omitted properties inherit the site's staged defaults; explicit false disables a choice. Omit the object when all choices inherit.",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": false,
+      "properties": {
+        "background": { "type": "boolean" },
+        "border": { "type": "boolean" },
+        "shadow": { "type": "boolean" }
+      }
+    },
     "submit_label": {
       "description": "The text on the submit button. Omit it for Taproot's default. Must contain more than whitespace; the validator also rejects a blank label, which a schema cannot express.",
       "type": "string",

package/src/field-validation.js

@@ -106,7 +106,7 @@ export function contactFieldId(definition) {
     const emails = definition.fields.filter((field) => field.type === "email");
     return emails.length === 1 ? emails[0].id : undefined;
 }
-const DEFINITION_KEYS = ["fields", "contact_field", "submit_label", "after_submit", "newsletter_audience_id"];
+const DEFINITION_KEYS = ["fields", "contact_field", "submit_label", "after_submit", "newsletter_audience_id", "presentation"];
 const BASE_FIELD_KEYS = ["id", "type", "label", "hint"];
 const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const isInteger = (value) => typeof value === "number" && Number.isInteger(value);
@@ -427,6 +427,22 @@ export function validateDefinition(definition) {
 }
 /** The button text and the after-submit choice, which sit beside the fields in a definition. */
 function validateFormSettings(definition, errors) {
+    if ("presentation" in definition) {
+        const presentation = definition.presentation;
+        if (!isPlainObject(presentation) || Object.keys(presentation).length === 0) {
+            errors.push({ path: "presentation", code: "invalid_presentation" });
+        }
+        else {
+            for (const key of sortedKeys(presentation)) {
+                if (key !== "background" && key !== "border" && key !== "shadow") {
+                    errors.push({ path: `presentation.${key}`, code: "unknown_property" });
+                }
+                else if (typeof presentation[key] !== "boolean") {
+                    errors.push({ path: `presentation.${key}`, code: "invalid_presentation_value" });
+                }
+            }
+        }
+    }
     const audience = definition.newsletter_audience_id;
     if (audience !== undefined && (typeof audience !== "string" || !isResourceId(audience))) {
         errors.push({ path: "newsletter_audience_id", code: "invalid_newsletter_audience" });

package/src/forms-contract.js

@@ -6,7 +6,7 @@ import { contactFieldId, validateDefinition } from "./field-validation.js";
  *
  * A form is one JSON file, `forms/<key>.json`, holding what an author decides:
  * its key, name, sink, retention, owner-notification preference and definition. The definition holds the fields
- * and the form's own settings (`contact_field`, `submit_label`, `after_submit`),
+ * and the form's own settings (`contact_field`, `submit_label`, `after_submit`, `presentation`),
  * exactly as the site stores it, so one validator reads one shape. The
  * definition's own rules belong to `shared/field-validation.ts` and are run
  * here through the generated copy, so this file never restates them. The one
@@ -289,6 +289,20 @@ export function projectFormForWorkspace(form, pathById) {
   if (form.definition.after_submit !== undefined) {
     definition.after_submit = canonicalAfterSubmit(form.definition.after_submit, pathById);
   }
+  if (form.definition.newsletter_audience_id !== undefined) {
+    definition.newsletter_audience_id = form.definition.newsletter_audience_id;
+  }
+  if (form.definition.presentation !== undefined) {
+    const presentation = {};
+    for (const name of ["background", "border", "shadow", ...Object.keys(form.definition.presentation).sort()]) {
+      if (form.definition.presentation[name] !== undefined) presentation[name] = form.definition.presentation[name];
+    }
+    definition.presentation = presentation;
+  }
+  // Preserve future properties on pull so an older workspace cannot silently erase them.
+  for (const name of Object.keys(form.definition).sort()) {
+    if (name !== "contact_field" && definition[name] === undefined) definition[name] = form.definition[name];
+  }
   return {
     key: form.key,
     ...projectFormSettings(form),