@taprootio/site-authoring 0.7.2 → 0.8.1

package/README.md

@@ -144,14 +144,35 @@ capabilities the command needs — a content push never holds deploy. The
 sign-in expires 24 hours after its last successful exchange, and never past
 any expiry the approving owner chose.
 
-`sites` lists what the sign-in may author; `use <name or id>` records the
-choice as `siteId` in `taproot-site.json`, creating the file in the current
-directory when there is none. `whoami` answers from local state alone: which
-Taproot, which account, which site, what the last exchange granted, and when
-the sign-in expires. `logout` discards the stored sign-in locally and revokes
-nothing; the credential stays valid until an owner revokes it under
-Account → Settings → API keys. The secret itself is never displayed, logged,
-or placed in any result: credentials are named by id and display prefix only.
+`sites` lists every standard and Docs site on the account with the authoring
+verbs each accepts; `use <name or id>` records the choice as `siteId` in
+`taproot-site.json`, together with the site's `authoringSurface`, creating
+the file in the current directory when there is none. `whoami` answers from
+local state alone: which Taproot, which account, which site and surface, what
+the last exchange granted, and when the sign-in expires.
+
+Which verbs apply depends on the site:
+
+- A **standard** site takes every verb.
+- A **managed Docs** site (`docs-presentation`) takes design and theming only:
+  `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
+  `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`.
+
+The recorded surface is a convenience, not the authority: Taproot re-resolves
+it on every write. After a Docs site becomes prebuilt, its sign-in exchange
+answers Not found like any site the account can no longer author, and the
+CLI adds a hint to run `use` again because the recording says the site was
+authorable before.
+
+`logout` discards the stored sign-in locally and revokes nothing; the
+credential stays valid until an owner revokes it under Account → Settings →
+API keys. The secret itself is never displayed, logged, or placed in any
+result: credentials are named by id and display prefix only.
 
 ### `TAPROOT_SITE_KEY` overrides the sign-in
 
@@ -184,15 +205,17 @@ explicitly and bypasses discovery. `login`, `logout`, `sites`, `use`,
 {
   "configVersion": 1,
   "siteId": "11111111-1111-4111-8111-111111111111",
+  "authoringSurface": "standard",
   "workspaceDir": "site"
 }
 ```
 
-| Field           | Rule                                                                                                                                          |
-| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| `configVersion` | Must be `1`.                                                                                                                                  |
-| `siteId`        | Optional. The canonical lowercase UUID of the site the next command writes to. `use` writes it; a present but malformed value is refused.     |
-| `workspaceDir`  | Required. A relative POSIX path beneath the configuration directory that `pull` writes into. Every existing segment must be a real directory. |
+| Field              | Rule                                                                                                                                                                                                    |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `configVersion`    | Must be `1`.                                                                                                                                                                                            |
+| `siteId`           | Optional. The canonical lowercase UUID of the site the next command writes to. `use` writes it; a present but malformed value is refused.                                                               |
+| `authoringSurface` | Optional. `standard`, `docs-presentation`, or `none`: the verbs the site accepts, as `use` recorded them. A present but unknown value is refused; Taproot re-resolves the surface on every write.        |
+| `workspaceDir`     | Required. A relative POSIX path beneath the configuration directory that `pull` writes into. Every existing segment must be a real directory.                                                           |
 
 The file is a small, closed JSON object. Unknown fields, duplicate keys, links
 in the path, and unsupported versions are refused before any credential is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.7.2",
+  "version": "0.8.1",
   "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": "4.12.0"
+    "@taprootio/espalier": "4.13.0"
   },
   "scripts": {
     "test": "node --test",

package/src/api.js

@@ -21,6 +21,7 @@ import {
 // would turn a successful mint into an orphaned key.
 import { KEY_PREFIX } from "./credentials.js";
 import { isCanonicalUuid, normalizePreviewDiagnostic, sanitizeDiagnostic, SiteAuthoringError } from "./errors.js";
+import { docsPublicationModeFromWire, siteKindFromWire, surfaceFromWire } from "./surface.js";
 import {
   DEFAULT_REDIRECT_STATUS,
   GONE_STATUS,
@@ -1740,11 +1741,12 @@ export async function startCliAuthorization(client, { keyName }, requestOptions
  * a contract error that hides a live credential.
  */
 /**
- * The sites the sign-in credential's account may author (TR00645).
+ * The sign-in credential's account sites, each with the authoring surface it
+ * accepts (TR00645, TR00790).
  *
- * The server has already filtered these to sites an exchange would accept, so
- * anything listed here is a site `use` can select and the next command can
- * author — a picker that offered otherwise would be worse than no picker.
+ * Every STANDARD and DOCS site on the account is listed, including a Docs site
+ * that accepts no verb: `use` can select any of them, and the surface is what
+ * tells the next command whether it applies before a request is made.
  */
 export async function listAuthorableSites(client, requestOptions = {}) {
   const response = requireObject(
@@ -1759,6 +1761,11 @@ export async function listAuthorableSites(client, requestOptions = {}) {
       siteId: requireCanonicalUuid(value.siteId, "sites.contract", "siteId"),
       name: typeof value.name === "string" ? value.name : "",
       primaryDomain: typeof value.primaryDomain === "string" ? value.primaryDomain : "",
+      // The verbs the site accepts (TR00790). Read fail-closed: a value this
+      // CLI does not recognize is a site it cannot claim to author.
+      siteType: siteKindFromWire(value.siteType),
+      docsPublicationMode: docsPublicationModeFromWire(value.docsPublicationMode),
+      authoringSurface: surfaceFromWire(value.authoringSurface),
     };
   });
 }
@@ -1798,6 +1805,10 @@ export async function exchangeSiteAuthoringToken(client, { siteId, capabilities
     capabilities: Array.isArray(response.capabilities)
       ? response.capabilities.filter((entry) => typeof entry === "string")
       : [],
+    // What the site accepts at the moment of exchange (TR00790). Advisory in
+    // the same sense as the platform switch: the server re-resolves it on
+    // every write, and this lets a verb refuse before the request instead.
+    authoringSurface: surfaceFromWire(response.authoringSurface),
     // The sign-in's refreshed deadline. Not a secret, and absent on a server
     // that predates the sliding window.
     ...(typeof response.signInExpiresAt === "string" && response.signInExpiresAt.length > 0

package/src/cli.js

@@ -1,4 +1,5 @@
 import { CAPABILITY_CONTENT, CAPABILITY_DEPLOYMENTS, CAPABILITY_DESIGN } from "./capabilities.js";
+import { capabilitiesForSurface } from "./surface.js";
 import {
   CLI_BINARY_NAME,
   CLI_NAME,
@@ -11,6 +12,8 @@ import {
   LOGIN_KEY_NAME_MAXIMUM,
   PUBLISH_KEY_ENVIRONMENT_VARIABLE,
   RESULT_SCHEMA_VERSION,
+  SURFACE_DOCS_PRESENTATION,
+  SURFACE_STANDARD,
   VERB_APPROVE,
   VERB_DEPLOY,
   VERB_ENV,
@@ -135,11 +138,13 @@ const VERBS = Object.freeze([
   {
     name: VERB_SITES,
     tokens: ["sites"],
-    summary: "List the sites this sign-in may author.",
+    summary: "List this account's sites and the authoring verbs each accepts.",
     configFree: true,
     note: "Runs on the stored sign-in rather than a site credential, and is one of exactly two things that credential "
-      + "can do. The list is already filtered to sites an exchange would accept, so anything shown here is a site "
-      + "'use' can select and the next command can author.",
+      + "can do. Every standard and Docs site on the account is listed with its kind and authoring surface: a "
+      + "standard site takes every verb; a managed Docs site takes design and theming only (pull, theme push, "
+      + "footer push, media upload, deploy, status), because its pages, navigation, and redirects come from the "
+      + "Docs artifact; a prebuilt Docs site takes no verb at all. 'use' can select any of them.",
   },
   {
     name: VERB_USE,
@@ -148,8 +153,9 @@ const VERBS = Object.freeze([
     configFree: true,
     positionals: "siteSelector",
     note: "Accepts a site id, an exact name, or an unambiguous case-insensitive name, and records the choice as "
-      + "siteId in taproot-site.json — creating that file in the current directory when there is not one yet. "
-      + "Two sites sharing a name is refused rather than guessed: pass the site id instead.",
+      + "siteId in taproot-site.json — creating that file in the current directory when there is not one yet — "
+      + "together with the site's authoringSurface, which is what lets a later verb refuse offline when the site "
+      + "cannot take it. Two sites sharing a name is refused rather than guessed: pass the site id instead.",
   },
   {
     name: VERB_WHOAMI,
@@ -185,6 +191,7 @@ const VERBS = Object.freeze([
   },
   {
     name: VERB_PULL,
+    surface: SURFACE_DOCS_PRESENTATION,
     // Pages and the four settings groups, and every one of those gates on
     // site.theme.manage — so a read-only snapshot still needs Design.
     capabilities: [CAPABILITY_CONTENT, CAPABILITY_DESIGN],
@@ -205,6 +212,7 @@ const VERBS = Object.freeze([
   },
   {
     name: VERB_PAGES_PUSH,
+    surface: SURFACE_STANDARD,
     capabilities: [CAPABILITY_CONTENT],
     tokens: ["pages", "push"],
     summary: "Create and update pages from the local workspace.",
@@ -231,6 +239,7 @@ const VERBS = Object.freeze([
   },
   {
     name: VERB_NAV_PUSH,
+    surface: SURFACE_STANDARD,
     // 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).
@@ -240,6 +249,7 @@ const VERBS = Object.freeze([
   },
   {
     name: VERB_REDIRECTS_CHECK,
+    surface: SURFACE_STANDARD,
     capabilities: [CAPABILITY_CONTENT, CAPABILITY_DEPLOYMENTS],
     tokens: ["redirects", "check"],
     summary: "Check the current redirect map through the authenticated staging edge.",
@@ -248,6 +258,7 @@ const VERBS = Object.freeze([
   },
   {
     name: VERB_REDIRECTS_PULL,
+    surface: SURFACE_STANDARD,
     // 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],
@@ -260,6 +271,7 @@ const VERBS = Object.freeze([
   },
   {
     name: VERB_REDIRECTS_PUSH,
+    surface: SURFACE_STANDARD,
     capabilities: [CAPABILITY_CONTENT],
     tokens: ["redirects", "push"],
     summary: "Validate redirects.json and replace the whole redirect map.",
@@ -270,6 +282,7 @@ const VERBS = Object.freeze([
   },
   {
     name: VERB_THEME_PUSH,
+    surface: SURFACE_DOCS_PRESENTATION,
     capabilities: [CAPABILITY_DESIGN],
     tokens: ["theme", "push"],
     summary: "Validate and push the workspace's complete theme and appearance settings.",
@@ -278,6 +291,7 @@ const VERBS = Object.freeze([
   },
   {
     name: VERB_FOOTER_PUSH,
+    surface: SURFACE_DOCS_PRESENTATION,
     capabilities: [CAPABILITY_DESIGN],
     tokens: ["footer", "push"],
     summary: "Validate and replace the workspace's complete footer document.",
@@ -286,7 +300,14 @@ const VERBS = Object.freeze([
   },
   {
     name: VERB_MEDIA_UPLOAD,
+    surface: SURFACE_DOCS_PRESENTATION,
     capabilities: [CAPABILITY_CONTENT],
+    // On a managed Docs site Content is not on offer, and narrowing the
+    // request above by intersection would leave nothing — which the exchange
+    // reads as "the whole surface envelope", Deployments included. Design
+    // carries site.media.manage too, so that is what this verb asks for there
+    // (TR00790).
+    surfaceCapabilities: { [SURFACE_DOCS_PRESENTATION]: [CAPABILITY_DESIGN] },
     tokens: ["media", "upload"],
     summary: "Upload media and wait for processing to finish.",
     positionals: "paths",
@@ -295,6 +316,7 @@ const VERBS = Object.freeze([
   },
   {
     name: VERB_APPROVE,
+    surface: SURFACE_STANDARD,
     capabilities: [CAPABILITY_CONTENT],
     tokens: ["approve"],
     summary: "Publish drafts. This stages the site; it does not deploy it.",
@@ -305,6 +327,7 @@ const VERBS = Object.freeze([
   },
   {
     name: VERB_DEPLOY,
+    surface: SURFACE_DOCS_PRESENTATION,
     // 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 redirect checks read the current redirect map;
@@ -322,6 +345,7 @@ const VERBS = Object.freeze([
   },
   {
     name: VERB_PREVIEW_PAGE,
+    surface: SURFACE_STANDARD,
     capabilities: [CAPABILITY_CONTENT],
     tokens: ["preview", "page"],
     summary: "Render one persisted draft and mint a short-lived staging handoff.",
@@ -339,6 +363,7 @@ const VERBS = Object.freeze([
   },
   {
     name: VERB_PREVIEW_REVOKE,
+    surface: SURFACE_STANDARD,
     capabilities: [CAPABILITY_CONTENT],
     tokens: ["preview", "revoke"],
     summary: "Revoke an active authoring preview and schedule its artifacts for cleanup.",
@@ -348,6 +373,7 @@ const VERBS = Object.freeze([
   },
   {
     name: VERB_STATUS,
+    surface: SURFACE_DOCS_PRESENTATION,
     // Readiness and the deployment log are Deployments; the image list is
     // Content, as is the broken-reference report.
     capabilities: [CAPABILITY_CONTENT, CAPABILITY_DEPLOYMENTS],
@@ -376,6 +402,30 @@ export const VERB_CAPABILITIES = Object.freeze(Object.fromEntries(
     .map((verb) => [verb.name, Object.freeze([...verb.capabilities])]),
 ));
 
+/**
+ * The shipped verb table's surface declarations, keyed by verb name (TR00790):
+ * `standard` for verbs only a STANDARD site takes, `docs-presentation` for
+ * verbs a managed Docs site takes too. A verb with no entry is not a site verb.
+ */
+export const VERB_SURFACES = Object.freeze(Object.fromEntries(
+  VERBS
+    .filter((verb) => verb.surface !== undefined)
+    .map((verb) => [verb.name, verb.surface]),
+));
+
+/**
+ * The capabilities each site verb's exchange asks for on a given surface
+ * (TR00790): the verb's declared set narrowed to what the surface offers, or
+ * the verb's own per-surface declaration where narrowing alone would be wrong.
+ * Exported so the tests can pin that no verb ever asks for nothing — an empty
+ * request means "everything the surface offers" on the wire.
+ */
+export function verbCapabilitiesForSurface(verbName, surface) {
+  const verb = VERBS.find((candidate) => candidate.name === verbName);
+  if (verb?.capabilities === undefined) return undefined;
+  return verb.surfaceCapabilities?.[surface] ?? capabilitiesForSurface(surface, 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.
@@ -419,6 +469,12 @@ Configuration:
   pass --config <path> before the verb. It is a closed JSON object:
     configVersion  must be 1
     siteId         optional; the canonical lowercase site UUID that 'use' writes
+    authoringSurface  optional; 'standard', 'docs-presentation', or 'none' — the
+                   verbs the site accepts, as 'use' recorded them. A verb the
+                   surface cannot take is refused before any request
+                   (surface.presentation_only, surface.none); Taproot re-checks
+                   on every write, so run 'use' again after a Docs site changes
+                   publication mode.
     workspaceDir   a relative POSIX path beneath the configuration directory
                    that pull writes into; every existing segment must be a real
                    directory
@@ -902,6 +958,11 @@ function parseArguments(arguments_) {
     // `VERB_CAPABILITIES` below is what the tests pin against the routes each
     // verb actually calls.
     capabilities: verb.capabilities,
+    // The narrowest site surface the verb applies to (TR00790). `openSession`
+    // refuses a verb its site cannot take before any request; `VERB_SURFACES`
+    // below is what the tests pin.
+    surface: verb.surface,
+    surfaceCapabilities: verb.surfaceCapabilities,
     configPath,
     quiet,
     deployTarget,
@@ -987,6 +1048,8 @@ export async function runCli({
       allowRawHtml: parsed.allowRawHtml,
       keyName: parsed.keyName,
       capabilities: parsed.capabilities,
+      surface: parsed.surface,
+      surfaceCapabilities: parsed.surfaceCapabilities,
       // Positionals land under the verb's own seam name (paths for media
       // upload, pagePaths for approve) and only when some were given, so a
       // bare invocation keeps each verb's documented default behavior.

package/src/config.js

@@ -3,6 +3,7 @@ import { lstat, open, realpath } from "node:fs/promises";
 import path from "node:path";
 
 import {
+  AUTHORING_SURFACES,
   CLI_BINARY_NAME,
   CONFIG_FILE_NAME,
   CONFIG_VERSION,
@@ -13,10 +14,12 @@ import {
 } from "./constants.js";
 import { hasAsciiControl, isCanonicalUuid, SiteAuthoringError } from "./errors.js";
 import { parseJsonWithDuplicateGuard } from "./json-guard.js";
+import { isKnownSurface } from "./surface.js";
 
 const CONFIG_KEYS = new Set([
   "configVersion",
   "siteId",
+  "authoringSurface",
   "workspaceDir",
 ]);
 const WINDOWS_DEVICE_BASENAME = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])$/iu;
@@ -398,6 +401,17 @@ export async function loadSiteConfig({ cwd = process.cwd(), configPath } = {}) {
   if (parsed.siteId !== undefined && !isCanonicalUuid(parsed.siteId)) {
     throw new SiteAuthoringError("config.site_id", "siteId must be a canonical lowercase UUID.", { field: "siteId" });
   }
+  // The surface `use` recorded (TR00790). Optional, because a configuration
+  // written before the field existed still names a site; a verb then learns
+  // the surface from its exchange instead. Present-but-unknown is refused:
+  // a surface this CLI cannot read is not one it can gate on.
+  if (parsed.authoringSurface !== undefined && !isKnownSurface(parsed.authoringSurface)) {
+    throw new SiteAuthoringError(
+      "config.authoring_surface",
+      `authoringSurface must be one of: ${AUTHORING_SURFACES.join(", ")}.`,
+      { field: "authoringSurface" },
+    );
+  }
   const workspaceDirectoryText = validateWorkspaceDirectoryText(parsed.workspaceDir);
   const configDirectory = path.dirname(canonicalConfigPath);
   const { workspaceDir, workspaceExists } = await resolveWorkspaceDirectory(configDirectory, workspaceDirectoryText);
@@ -406,6 +420,7 @@ export async function loadSiteConfig({ cwd = process.cwd(), configPath } = {}) {
     configPath: canonicalConfigPath,
     configDirectory,
     siteId: parsed.siteId,
+    authoringSurface: parsed.authoringSurface,
     workspaceDir,
     workspaceExists,
   });

package/src/constants.js

@@ -1,5 +1,5 @@
 export const CLI_NAME = "@taprootio/site-authoring";
-export const CLI_VERSION = "0.7.2";
+export const CLI_VERSION = "0.8.1";
 export const CLI_BINARY_NAME = "taproot-site";
 export const RESULT_SCHEMA_VERSION = 1;
 export const CONFIG_FILE_NAME = "taproot-site.json";
@@ -98,6 +98,15 @@ export const VERB_USE = "use";
 export const VERB_WHOAMI = "whoami";
 export const VERB_ENV = "env";
 
+// Which authoring verbs a site accepts (TR00790), as `use` records it in the
+// configuration and as the exchange reports it. Spelled for humans rather
+// than copied from the wire enum, because the configuration is a file people
+// read and edit.
+export const SURFACE_STANDARD = "standard";
+export const SURFACE_DOCS_PRESENTATION = "docs-presentation";
+export const SURFACE_NONE = "none";
+export const AUTHORING_SURFACES = Object.freeze([SURFACE_STANDARD, SURFACE_DOCS_PRESENTATION, SURFACE_NONE]);
+
 export const DEPLOY_TARGET_STAGING = "staging";
 export const DEPLOY_TARGET_PRODUCTION = "production";
 

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

@@ -1,5 +1,5 @@
 {
-  "version": 4,
+  "version": 5,
   "section": {
     "nodeType": "section",
     "label": "Section",
@@ -480,6 +480,11 @@
       "label": "Section",
       "measure": "wide",
       "placement": "explicit-band"
+    },
+    "integrationPlacement": {
+      "label": "Integration component",
+      "measure": "wide",
+      "placement": "flow"
     }
   },
   "components": {
@@ -523,5 +528,43 @@
       "measure": "wide",
       "rootPlacement": "root-band"
     }
+  },
+  "integrationPlacement": {
+    "nodeType": "integrationPlacement",
+    "label": "Integration component",
+    "help": "An installed component whose configuration and sanitized fragment are selected as immutable page revisions.",
+    "attrs": {
+      "placementId": {
+        "type": "uuid",
+        "required": true
+      },
+      "installationId": {
+        "type": "uuid",
+        "required": true
+      },
+      "componentId": {
+        "type": "identifier",
+        "required": true,
+        "maximumLength": 64
+      },
+      "config": {
+        "type": "json-string",
+        "required": true,
+        "maximumBytes": 16384
+      },
+      "configurationRevision": {
+        "type": "integer",
+        "required": false,
+        "nullable": true,
+        "minimum": 1,
+        "maximum": 9007199254740991,
+        "serverAssigned": true
+      }
+    },
+    "placement": {
+      "root": true,
+      "section": true,
+      "measure": "wide"
+    }
   }
 }

package/src/content/tiptap-prosemirror.ts

@@ -47,7 +47,20 @@ export interface ProseMirrorDocument extends ProseMirrorNode {
   content?: ProseMirrorNode[];
 }
 
+/** Sanitized immutable page input supplied by Taproot, never trusted from node attributes. */
+export interface SelectedIntegrationPlacement {
+  placementId: string;
+  installationId: string;
+  componentId: string;
+  status: string;
+  fragmentRevision: number;
+  html: string;
+  frozen: boolean;
+}
+
 export interface RenderProseMirrorOptions {
+  integrationPlacements?: readonly SelectedIntegrationPlacement[];
+  integrationPreview?: boolean;
   /** Normalize free-form root flow into full-bleed Espalier sections. */
   freeFormSections?: boolean;
   imageDefaults?: {
@@ -185,6 +198,8 @@ function renderNode(
       return renderInlineFacts(node, options, placement);
     case "componentBlock":
       return renderComponentBlock(node);
+    case "integrationPlacement":
+      return renderIntegrationPlacement(node, options);
     case "section":
       return renderSection(
         node.content ?? [],
@@ -200,6 +215,29 @@ function renderNode(
   }
 }
 
+function renderIntegrationPlacement(node: ProseMirrorNode, options: RenderProseMirrorOptions): string {
+  const placementId = stringAttr(node.attrs?.placementId);
+  const installationId = stringAttr(node.attrs?.installationId);
+  const componentId = stringAttr(node.attrs?.componentId);
+  const selected = options.integrationPlacements?.find((item) =>
+    item.placementId === placementId && item.installationId === installationId && item.componentId === componentId
+  );
+  if (!selected || selected.status === "removed" || selected.status === "deleted") {
+    return options.integrationPreview && !selected
+      ? "<p role=\"status\">Save this page to request content from the integration.</p>"
+      : "";
+  }
+  if (!selected.fragmentRevision || !selected.html) {
+    return options.integrationPreview && !selected.frozen
+      ? "<p role=\"status\">Content pending from the integration.</p>"
+      : "";
+  }
+  return renderElement("taproot-integration-placement", {
+    "data-placement-id": selected.placementId,
+    "data-component": selected.componentId,
+  }, selected.html);
+}
+
 function renderTextNode(node: ProseMirrorNode): string {
   let rendered = escapeHtml(node.text ?? "");
   for (const mark of node.marks ?? []) {

package/src/content/validate-document.js

@@ -277,6 +277,7 @@ const BLOCKS = Object.freeze([
   "horizontalRule",
   "taprootImage",
   "componentBlock",
+  "integrationPlacement",
   "rawHtml",
 ]);
 const SECTION_BLOCKS = Object.freeze([
@@ -382,6 +383,22 @@ const NODE_RULES = Object.freeze({
   horizontalRule: rule({}),
   taprootImage: rule({ attrs: IMAGE_ATTRS, rejectedAttrs: IMAGE_TRANSIENT_ATTRS, imageDelivery: true }),
   componentBlock: rule({ attrs: COMPONENT_ATTRS, component: true }),
+  integrationPlacement: rule({
+    attrs: Object.freeze({
+      placementId: spec((value) => typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu.test(value)
+        ? null : "a UUID belonging only to this host page", { required: true }),
+      installationId: spec((value) => typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu.test(value)
+        ? null : "an installed integration UUID", { required: true }),
+      componentId: spec((value) => typeof value === "string" && /^[A-Za-z0-9_.-]{1,64}$/u.test(value)
+        ? null : "a bounded declared component identifier", { required: true }),
+      config: spec((value) => {
+        if (typeof value !== "string" || Buffer.byteLength(value, "utf8") > 16384) return "bounded configuration JSON";
+        try { JSON.parse(value); return null; } catch { return "valid configuration JSON"; }
+      }, { required: true }),
+      configurationRevision: spec((value) => value == null || Number.isSafeInteger(value) && value > 0
+        ? null : "a positive server-assigned configuration revision"),
+    }),
+  }),
   section: rule({
     attrs: SECTION_ATTRS,
     children: SECTION_BLOCKS,

package/src/content/vocabulary.js

@@ -49,6 +49,7 @@ export const NODE_TYPES = Object.freeze([
   "horizontalRule",
   "taprootImage",
   "componentBlock",
+  "integrationPlacement",
   "section",
   freeFormSectionRegistry.inlineFacts.nodeType,
   "rawHtml",
@@ -353,6 +354,7 @@ function hasMeaningfulContent(node, depth = 0) {
   if (
     node.type === "taprootImage"
     || node.type === "componentBlock"
+    || node.type === "integrationPlacement"
     || node.type === freeFormSectionRegistry.inlineFacts.nodeType
   ) return true;
   if (!Array.isArray(node.content)) return false;

package/src/fixture-init.js

@@ -42,6 +42,11 @@ export async function initializeFixture(invocation, validate) {
   if (source.manifestVersion !== MANIFEST_VERSION || source.pagesTruncated || source.settingsSkipped?.length) {
     refuse("A complete current pull is required before fixture initialization. Run 'taproot-site pull'.");
   }
+  // A managed Docs site's workspace holds settings only (TR00790); the fixture
+  // contract binds pages and navigation, which that site never has.
+  if (source.authoringSurface !== undefined) {
+    refuse("Offline fixtures describe standard sites; a Docs site's workspace holds its settings only.");
+  }
   if (typeof invocation.fixturePath !== "string" || !invocation.fixturePath.trim()) {
     refuse("Choose a new fixture directory.");
   }

package/src/reference-help.js

@@ -51,7 +51,7 @@ import {
 
 export { getAppearanceReference, getFooterReference, getThemeReference };
 
-export const REFERENCE_VERSION = 20;
+export const REFERENCE_VERSION = 21;
 export const PAGE_TYPES = Object.freeze(["free-form"]);
 export const REFERENCE_TOPICS = Object.freeze([
   Object.freeze({ name: "pages", usage: `${CLI_BINARY_NAME} help pages`, summary: "List authorable page types." }),
@@ -946,6 +946,17 @@ const FREE_FORM_REFERENCE = Object.freeze({
       attrs: Object.freeze(sectionAttributeReference()),
       content: "one or more ordinary non-section block nodes; sections may not nest",
     }),
+    integrationPlacementNode: Object.freeze({
+      type: "integrationPlacement",
+      attrs: Object.freeze({
+        placementId: "New UUID for a new or copied placement; retain identity when moving within the same page.",
+        installationId: "UUID of the eligible installation consented for this site.",
+        componentId: "Component identifier from the installation's consented manifest.",
+        config: "JSON string validated against the component's bounded configuration schema.",
+        configurationRevision: "Server-assigned revision. Preserve when unchanged; omit after editing config or copying.",
+      }),
+      authority: "The caller needs permission to edit the host page; installation management alone is insufficient.",
+    }),
     tableNode: TABLE_REFERENCE,
     inlineFactsNode: INLINE_FACTS_REFERENCE,
     rawHtml: Object.freeze({