Placement modes — auto vs manual

Each widget’s placement.mode is one of two:

Mode	Behavior	Merchant action
auto	Pick anchor; system chooses specific DOM position based on theme	Pick one of 6 cards (excl. Custom Position)
manual	Merchant places via manual block in theme editor	Pick Custom Position card

When to choose auto

• Merchant wants out-of-the-box, no theme code touching
• Target location is a Shopify platform standard structure (product page ATC, cart, footer, etc.)
• Theme is in the built-in 65-theme matrix (most cases)

In auto mode:

• Merchant picks “Product page” / “Footer” / “Cart Drawer” etc. cards
• System uses Cascade table to find specific DOM nodes
• When theme doesn’t support, diagnostic verdict shows “No available placement on this page” — merchant can switch theme or fill customAnchorSelectors

When to choose manual

• Merchant wants exact control (e.g. mount in a custom section’s specific div)
• Theme isn’t in the 65-theme matrix and customAnchorSelectors isn’t flexible enough
• Want to manually place the same widget at different positions across multiple templates

In manual mode:

• Merchant picks “Custom Position” card → editor displays widget ID + embed code
• Merchant copies widget ID → enters Shopify theme editor → drags the tt-blocks manual block into any section → pastes the widget ID in block settings
• After theme save, widget renders at that position

Data form:

"placement": {
  "mode": "manual",
  "manual": {
    "addedToThemes": [
      { "themeId": "123", "template": "product", "blockId": "xxx" }
    ]
  }
}

addedToThemes records which themes / templates / block instances the widget has been added to — useful for syncing after theme switches.

Mode switch field retention

When merchant switches placement card (i.e. changes placement.mode):

• visibility 9 dimensions / component tree / color scheme and other fields are fully retained
• Only the sub-structure under placement changes (auto.anchor ↔ manual.addedToThemes)

Note: SET_PLACEMENT triggers dirty state (the editor’s top SaveBar appears, prompting save).

Actual hit anchor diagnostics

In auto mode, merchants can view the actual hit DOM anchor key in the Display tab StickyBar. In manual mode there’s no anchor resolution; the diagnostic panel shows “Custom Position”.

Relationship to Anchors and cascade table

• This page covers mode (auto vs manual) — the top-level toggle of the placement field
• Anchors and cascade table covers the full anchor key list and cascade behavior under auto mode