Preview a published baseline patch

Preview exact snippet and style replacements against an immutable published version without changing the editable draft.

app_topolo_web.sites.published_baseline.preview builds an isolated preview and publish-quality preflight from one exact immutable published version. It does not change the site draft, version history, or published state. The current d9 production action capture marks this action readOnly: true and requiresConfirmation: false.

Use the action only for a site published in the selected organization and workspace. Read the active published version and the exact current snippet or style object values first. Supply publish:write permission (app_topolo_web.publish:write), the site, organization and workspace IDs, the expected published version ID, an idempotency key of 8–200 characters, and at least one snippet or style-class patch. Each patch replaces an existing object by ID and includes that object's 64-character lowercase SHA-256 preimage. At most 20 snippet patches and 20 style-class patches are accepted. Extra fields are rejected.

The following request uses fictional site and workspace values. Its preimage hashes belong only to the synthetic fixture used in the worked cases. Read the actual stored objects and compute their canonical hashes before preparing a real request.

{
  "siteId": "site_synth_01",
  "organizationId": "org-synth-01",
  "workspaceId": "workspace-synth-01",
  "expectedVersionId": "version_synth_01",
  "idempotencyKey": "preview-synth-true-001",
  "label": "Synthetic patch example",
  "snippetPatches": [
    {
      "id": "metrics-snippet",
      "expectedSha256": "26ac07e5dc17ef37aba9e4b73075ae58f5d7aa3b26ef1a6a642ab97f960b50c2",
      "replacement": {
        "id": "metrics-snippet",
        "label": "Metrics",
        "slot": "head",
        "code": "window.metricsReady = true;",
        "enabled": false
      }
    }
  ],
  "styleClassPatches": [
    {
      "id": "hero-corners",
      "expectedSha256": "a2165c725e69778aa4cfcc63620933705d1c8223fc8b913c15e5ed27cd2f7282",
      "replacement": {
        "id": "hero-corners",
        "name": "Hero corners",
        "targetKind": "hero",
        "targetScope": "section",
        "style": {
          "borderRadius": 24
        }
      }
    }
  ]
}

Snippet slots are head, body_start, and body_end. Style-class replacements are limited to the declared Web target-kind enum, with target scope section or item; style is a string-keyed JSON object. At least one of the two patch arrays must be nonempty. Replacement IDs must match patch IDs and IDs must be unique within each patch type.

Action discovery uses permission_denied as the descriptor label for a 403 and grouped labels for 404/409 outcomes; those labels do not establish literal handler response values. The source-defined lookup errors are site_not_found or version_not_found (404). Published-state and preimage conflicts use site_not_published, stale_version or preimage_changed (409). The exact 403 denial body remains UNKNOWN. Re-read current state and rebuild the preview after a conflict; do not reuse an old hash after content changes.

Current d9 transport boundary: the declared action input still requires siteId; native action/CLI/MCP callers must supply it. The native SDK consumes that declared value into the trusted {siteId} route path, so the raw HTTP JSON body may omit it after path substitution. If a body siteId is supplied, it must match the path. This is a raw route transport detail, not optionality in the declared action schema.

Source: Reviewed against TopoloWeb d9c75819abedaf71f9436a1d200015883a291072 and the current declared schemas on 2026-10-23. The worked examples below are synthetic and unrun; they are not observed site results.

Responses and errors

These are source-derived contracts for production-associated d9c7581 (186133adb5823723307184dcbd77acb1814317a1), not observed site-action results. The current production catalog success body requires siteId, baseVersionId, canPublish, qualityReport, and preview; the handler returns HTTP 200. When canPublish is false, preview still returns this 200 response with the quality report.

Branch	Predicate	Status and body
Success	Authorization and parsing pass; the published site/version and exact preimages validate.	200 `{ siteId, baseVersionId, canPublish, qualityReport, preview }`; `canPublish` may be true or false.
Permission denied	`can(..., 'publish:write')` returns a denial.	403 `permission_denied` is the action-contract code; exact body is UNKNOWN because the route returns the `can()` response unchanged.
Invalid request	JSON/schema/refinement fails, including empty patch arrays.	400 `{ error: "invalid_published_baseline_patch" }`.
Body/path mismatch	A supplied body `siteId` differs from the trusted path.	400 `{ error: "site_identity_mismatch" }`.
Scope mismatch	Body organization/workspace differs from authenticated scope.	404 `{ error: "site_not_found" }`.
Domain error	Plan construction raises a typed patch error.	404 `site_not_found` or `version_not_found`; 400 `invalid_patch`; 409 `site_not_published`, `stale_version`, `preimage_changed`, `idempotency_conflict`, `patch_in_progress`, or `concurrent_publish`, each `{ error: "<code>" }`.

Preview has no idempotent replay branch. idempotencyKey is required by the input contract, but preview does not reserve or read a replay result. The response behavior is source-reviewed; treat the examples as illustrations, not live execution evidence.

Worked examples

Every case is SYNTHETIC / UNRUN. All identifiers, timestamps, content and hosts are fictional. example.invalid is an explicit fictional runtime-host override, not the production host configuration. Never reuse these fixture values against a real site.

SYNTHETIC / UNRUN — preview accepts the patched baseline

qualityReport has no error-severity issues; canPublish true.

Request:

{
  "siteId": "site_synth_01",
  "organizationId": "org-synth-01",
  "workspaceId": "workspace-synth-01",
  "expectedVersionId": "version_synth_01",
  "idempotencyKey": "preview-synth-true-001",
  "label": "Synthetic patch example",
  "snippetPatches": [
    {
      "id": "metrics-snippet",
      "expectedSha256": "26ac07e5dc17ef37aba9e4b73075ae58f5d7aa3b26ef1a6a642ab97f960b50c2",
      "replacement": {
        "id": "metrics-snippet",
        "label": "Metrics",
        "slot": "head",
        "code": "window.metricsReady = true;",
        "enabled": false
      }
    }
  ],
  "styleClassPatches": [
    {
      "id": "hero-corners",
      "expectedSha256": "a2165c725e69778aa4cfcc63620933705d1c8223fc8b913c15e5ed27cd2f7282",
      "replacement": {
        "id": "hero-corners",
        "name": "Hero corners",
        "targetKind": "hero",
        "targetScope": "section",
        "style": {
          "borderRadius": 24
        }
      }
    }
  ]
}

HTTP 200 response body:

{
  "siteId": "site_synth_01",
  "baseVersionId": "version_synth_01",
  "canPublish": true,
  "qualityReport": {
    "generatedAt": "2026-10-23T01:30:00.000Z",
    "score": 92,
    "issues": [
      {
        "id": "asset_library_empty",
        "severity": "info",
        "title": "No assets in the library yet",
        "detail": "Load at least a logo or hero reference so the site can move beyond pure text-only scaffolding."
      },
      {
        "id": "no_form_signal",
        "severity": "info",
        "title": "No captured form submissions yet",
        "detail": "This is normal for a fresh site, but launch monitoring should confirm the lead path is working."
      }
    ]
  },
  "preview": {
    "site": {
      "id": "site_synth_01",
      "slug": "sample-site",
      "name": "Northstar Studio",
      "status": "published",
      "updatedAt": "2026-10-23T00:30:00.000Z",
      "currentVersionId": "version_synth_01",
      "draftPreviewToken": "draft-preview-synth-01"
    },
    "documentPage": {
      "id": "page-home",
      "kind": "page",
      "pageId": "page-home",
      "label": "Home",
      "path": [
        "page-home"
      ],
      "source": {
        "kind": "page",
        "id": "page-home"
      },
      "value": {
        "id": "page-home",
        "slug": "/",
        "title": "Northstar Studio",
        "description": "A fictional service studio offering thoughtful planning and direct support for teams preparing their next launch."
      },
      "children": [
        {
          "kind": "slot",
          "slotKind": "page-body",
          "id": "page-home:body",
          "pageId": "page-home",
          "label": "Page body",
          "path": [
            "page-home",
            "slot:body"
          ],
          "parentNodeId": "page-home",
          "source": {
            "kind": "page",
            "id": "page-home"
          },
          "accepts": [
            "layout",
            "block"
          ],
          "children": [
            {
              "kind": "block",
              "id": "hero-home",
              "pageId": "page-home",
              "label": "A clear service path",
              "path": [
                "page-home",
                "slot:body",
                "sections:0"
              ],
              "source": {
                "kind": "section",
                "id": "hero-home"
              },
              "blockKind": "hero",
              "sectionKind": "hero",
              "sectionId": "hero-home",
              "value": {
                "id": "hero-home",
                "kind": "hero",
                "title": "A clear service path",
                "body": "Northstar Studio helps fictional teams plan a clear service launch with practical steps, careful review, and a direct path to a first conversation.",
                "primaryAction": {
                  "label": "Contact Northstar",
                  "href": "mailto:hello@example.invalid",
                  "linkKind": "custom",
                  "targetBlank": false
                }
              },
              "children": []
            }
          ]
        }
      ]
    },
    "theme": {
      "primary": "#111111",
      "secondary": "#333333",
      "surface": "#ffffff",
      "ink": "#111111",
      "muted": "#444444",
      "accent": "#005fcc",
      "accentSoft": "#111111",
      "glow": "#111111",
      "headingFont": "Inter, system-ui, sans-serif",
      "bodyFont": "Inter, system-ui, sans-serif",
      "radius": "16px"
    },
    "navigation": [],
    "footerNavigation": [],
    "menus": [],
    "styleClasses": [
      {
        "id": "hero-corners",
        "name": "Hero corners",
        "targetKind": "hero",
        "targetScope": "section",
        "style": {
          "borderRadius": 24
        }
      }
    ],
    "collections": [],
    "codeSnippets": [
      {
        "id": "metrics-snippet",
        "label": "Metrics",
        "slot": "head",
        "code": "window.metricsReady = true;",
        "enabled": false
      }
    ],
    "seo": {
      "metaTitle": "Northstar Studio | Example",
      "metaDescription": "A fictional service studio sharing clear launch planning, careful review, and a direct path to a first conversation for example.invalid readers.",
      "canonicalUrl": "https://www.example.invalid/"
    },
    "preview": true,
    "canonicalUrl": "https://sample-site.example.invalid",
    "hostname": "sample-site.example.invalid",
    "indexable": true
  }
}

SYNTHETIC / UNRUN — preview returns a refusal-ready report

Same preview path with the synthetic baseline hero lacking primaryAction; canPublish false remains a 200 preview response.

Request:

{
  "siteId": "site_synth_01",
  "organizationId": "org-synth-01",
  "workspaceId": "workspace-synth-01",
  "expectedVersionId": "version_synth_01",
  "idempotencyKey": "preview-synth-false-001",
  "label": "Synthetic patch example",
  "snippetPatches": [
    {
      "id": "metrics-snippet",
      "expectedSha256": "26ac07e5dc17ef37aba9e4b73075ae58f5d7aa3b26ef1a6a642ab97f960b50c2",
      "replacement": {
        "id": "metrics-snippet",
        "label": "Metrics",
        "slot": "head",
        "code": "window.metricsReady = true;",
        "enabled": false
      }
    }
  ],
  "styleClassPatches": [
    {
      "id": "hero-corners",
      "expectedSha256": "a2165c725e69778aa4cfcc63620933705d1c8223fc8b913c15e5ed27cd2f7282",
      "replacement": {
        "id": "hero-corners",
        "name": "Hero corners",
        "targetKind": "hero",
        "targetScope": "section",
        "style": {
          "borderRadius": 24
        }
      }
    }
  ]
}

HTTP 200 response body:

{
  "siteId": "site_synth_01",
  "baseVersionId": "version_synth_01",
  "canPublish": false,
  "qualityReport": {
    "generatedAt": "2026-10-23T01:30:00.000Z",
    "score": 72,
    "issues": [
      {
        "id": "hero_action_missing",
        "severity": "error",
        "title": "Hero section has no primary action",
        "detail": "The landing experience should expose one clear next step from the first screen."
      },
      {
        "id": "asset_library_empty",
        "severity": "info",
        "title": "No assets in the library yet",
        "detail": "Load at least a logo or hero reference so the site can move beyond pure text-only scaffolding."
      },
      {
        "id": "no_form_signal",
        "severity": "info",
        "title": "No captured form submissions yet",
        "detail": "This is normal for a fresh site, but launch monitoring should confirm the lead path is working."
      }
    ]
  },
  "preview": {
    "site": {
      "id": "site_synth_01",
      "slug": "sample-site",
      "name": "Northstar Studio",
      "status": "published",
      "updatedAt": "2026-10-23T00:30:00.000Z",
      "currentVersionId": "version_synth_01",
      "draftPreviewToken": "draft-preview-synth-01"
    },
    "documentPage": {
      "id": "page-home",
      "kind": "page",
      "pageId": "page-home",
      "label": "Home",
      "path": [
        "page-home"
      ],
      "source": {
        "kind": "page",
        "id": "page-home"
      },
      "value": {
        "id": "page-home",
        "slug": "/",
        "title": "Northstar Studio",
        "description": "A fictional service studio offering thoughtful planning and direct support for teams preparing their next launch."
      },
      "children": [
        {
          "kind": "slot",
          "slotKind": "page-body",
          "id": "page-home:body",
          "pageId": "page-home",
          "label": "Page body",
          "path": [
            "page-home",
            "slot:body"
          ],
          "parentNodeId": "page-home",
          "source": {
            "kind": "page",
            "id": "page-home"
          },
          "accepts": [
            "layout",
            "block"
          ],
          "children": [
            {
              "kind": "block",
              "id": "hero-home",
              "pageId": "page-home",
              "label": "A clear service path",
              "path": [
                "page-home",
                "slot:body",
                "sections:0"
              ],
              "source": {
                "kind": "section",
                "id": "hero-home"
              },
              "blockKind": "hero",
              "sectionKind": "hero",
              "sectionId": "hero-home",
              "value": {
                "id": "hero-home",
                "kind": "hero",
                "title": "A clear service path",
                "body": "Northstar Studio helps fictional teams plan a clear service launch with practical steps, careful review, and a direct path to a first conversation."
              },
              "children": []
            }
          ]
        }
      ]
    },
    "theme": {
      "primary": "#111111",
      "secondary": "#333333",
      "surface": "#ffffff",
      "ink": "#111111",
      "muted": "#444444",
      "accent": "#005fcc",
      "accentSoft": "#111111",
      "glow": "#111111",
      "headingFont": "Inter, system-ui, sans-serif",
      "bodyFont": "Inter, system-ui, sans-serif",
      "radius": "16px"
    },
    "navigation": [],
    "footerNavigation": [],
    "menus": [],
    "styleClasses": [
      {
        "id": "hero-corners",
        "name": "Hero corners",
        "targetKind": "hero",
        "targetScope": "section",
        "style": {
          "borderRadius": 24
        }
      }
    ],
    "collections": [],
    "codeSnippets": [
      {
        "id": "metrics-snippet",
        "label": "Metrics",
        "slot": "head",
        "code": "window.metricsReady = true;",
        "enabled": false
      }
    ],
    "seo": {
      "metaTitle": "Northstar Studio | Example",
      "metaDescription": "A fictional service studio sharing clear launch planning, careful review, and a direct path to a first conversation for example.invalid readers.",
      "canonicalUrl": "https://www.example.invalid/"
    },
    "preview": true,
    "canonicalUrl": "https://sample-site.example.invalid",
    "hostname": "sample-site.example.invalid",
    "indexable": true
  }
}

Change log

2026-10-23: Documented the current published-baseline preview contract, exact source error distinctions and complete synthetic worked request/response cases. No site operation was executed for these examples.