Description
Answer any question about Contentstack Visual Experience: Live Preview, Visual Editor (also called Visual Builder) and Timeline. One flow covers all of it. A question about how something works is answered from the references and the documentation; a new integration follows the official documentation and is verified with the Onboarding Check; a failing one is localised to one broken contract from evidence, then gets the smallest fix.
When to Use
Use for any Visual Experience question: how a feature works or behaves, what a setting or check means, setting up an integration, or an integration that misbehaves.
Hand off to dx-delivery-sdk when the user wants Delivery SDK query code and preview is not involved.
Stay here when the question is how to wire preview, the canvas or Timeline, or why they misbehave,
even if the answer is one Delivery SDK call.
Terminology
Visual Builder and Visual Editor are the same product. Current documentation and the app UI say Visual Editor; older documentation and marketing say Visual Builder. Never treat the two names as a discrepancy. Mirror the term the user used.
- Visual Experience is the umbrella for Live Preview, Visual Editor and Timeline, and the name of the settings section: Settings → Visual Experience.
mode: "builder"(SDK option) andvisual_builder.onboarding-setup-visible(stack setting) keep their names. Do not rename them in an answer.
User Problem
Setup instructions reconstructed from memory drift from the documentation and miss the requirements that differ per rendering mode. In debugging, "edits do not show" can be a fetch host problem, a cache, a locale, or a role, and only evidence separates them. Guessing produces a long thread of speculative fixes.
Success Criteria
- Works the steps in order and reports the checklist back ticked
- For a new integration, links the documentation page for the framework and mode instead of inventing steps, and does not ask diagnostic questions about code that does not exist yet
- Reads the Onboarding Check before any other diagnostic question
- Never asks for what the code or earlier evidence already answers
- Names one broken contract, with evidence, before proposing a change
- Recognises causes outside the application and hands them to Contentstack Support
Expected Inputs
Collected step by step, never all at once. Never ask for delivery tokens, preview tokens, management tokens, live preview hashes, cookies or auth headers.
Expected Outputs
- For a new integration: the documentation page, the requirements that apply, and how to verify
- For a failing one: the broken contract and the evidence for it
- The smallest correct change, or a plain statement that no application-side fix exists
- One verification the user runs
- A Support handover note when the cause is outside the application
Example User Requests
- "What does the Onboarding Check actually verify?"
- "How do I set up Live Preview in our Next.js App Router site?"
- "We have Live Preview working. What do we add for Visual Builder?"
- "Live Preview loads but my edits never show up."
- "The preview pane is blank / says it could not connect."
- "Visual Builder shows Setup Complete but I can't click anything."
- "Preview worked yesterday and now shows published content."
- "Timeline always shows the current version."
Rules
Follow these on every turn that diagnoses a failure.
- Stop rule. Once one contract is localised, stop collecting evidence and move to the fix.
- Observed beats intended. The Onboarding Check reports what the deployed build did; the code reports what it intends. When they disagree, the check wins.
- Falsification rule. Before acting on a diagnosis, name the one artifact that would contradict it, and get it.
- Reproduction rule. No code change without a reproduced failure. State the contract, the evidence, and the action that reproduces it. No reproduction means a hypothesis: keep collecting.
- Transition rule. Worked then broke, a gate that advanced then regressed, a new error replacing an old one: restart at step 2 and ask what changed, including your own edits this session.
- No resilience while diagnosing. Add no fallbacks, retries or caches. A fallback to published content hides the exact signal being debugged.
Workflow Summary
Report this back ticked. An unticked step is a visible gap.
- 1. Identify the product.
- 2. Question, new integration, never worked, or regression? Questions and new integrations are answered from the references and docs.
- 3. Read the Onboarding Check.
- 4. Detect framework, rendering mode and fetch layer from the code.
- 5. Collect only the evidence steps 3 and 4 did not settle.
- 6. Localise to one contract.
- 7. Fix and verify, or hand to Contentstack Support.
Instructions
Step 1. Which product?
Ask explicitly. Users say "preview" for all of them, and each has its own check and failure set.
| Product | What it is |
|---|---|
| Live Preview | Preview pane with content refresh. Everything else builds on it. |
| Visual Editor | Live Preview plus on-canvas editing. Needs edit tags and mode: "builder" in init(). |
| Timeline | Preview at a point in time. Needs preview_timestamp forwarded with the hash. |
On Visual Editor or Timeline, confirm plain Live Preview works. If it does not, that is the problem.
Step 2. Question, new, never worked, or regression?
- A question about how something works, not a failure ("what does the Onboarding Check verify?", "does Timeline need anything extra?", "what is the difference between Live Preview and Visual Builder?"): answer it from the relevant reference file and link the documentation page. No diagnostic intake. If the answer reveals a failure, continue at step 3.
- Nothing integrated yet, or adding Visual Editor or Timeline: read the framework and rendering mode from the code, give the matching documentation page and the requirements that apply from references/setup-docs.md, and stop there. Do not ask diagnostic questions about code that does not exist yet. When the user has it in place, continue at step 3 to verify.
- Integrated, never worked: continue at step 3.
- Worked, now broken: continue at step 3 first. Once you have the Onboarding Check, ask what changed (release, dependency bump, settings, role, environment, CDN or hosting).
Step 3. Read the Onboarding Check
Ask for a screenshot of the check in the preview panel, before any other diagnostic question. Code access does not excuse this step. Users paraphrase step names, and each name maps to one gate. If the user already quoted a card or item name that matches the tables below word for word, use it and skip the screenshot.
All three products evaluate their gates as a chain that stops at the first failure. Read the first failing item. Everything before it passed; everything after it never ran.
Live Preview shows one card:
| Card | Localises to |
|---|---|
| Could Not Connect to Website | Network-level failure only: wrong or unreachable Base URL, DNS, bad certificate, mixed content, the browser blocking localhost |
| Live Preview SDK Not Initialized | No init handshake: init() never ran on the client, enable not truthy, or the frame is blank (frame headers, an auth or password screen) |
| Outdated Live Preview SDK Version | SDK below 1.4.0 |
| Preview Service Not Enabled | Content fetch never switched to the preview host and headers |
| Default Environment Not Set | Integration fine; the stack has no default preview environment |
| Setup Complete | Reachability, handshake, version and Preview Service all fine |
Visual Editor and Timeline show a status card while checking, then a full-pane overlay ("Set Up
Visual Editor", "Set Up Timeline") listing their items. Gates, verbatim item text and timing are in
references/onboarding-check.md. The two Visual Editor items that
catch users coming from a Live Preview guide: Verify Mode for Live Preview fails on
mode: "preview", and Validate the Base URL needs the Base URL origin to match the previewed page
exactly.
Three readings decide the branch:
- Setup Complete, nothing editable. The check never inspects
data-cslp. Go to contract 2. - Setup Complete, only fields from referenced entries not editable. Tags are not rebased to the
referenced entry:
cslp-not-rebased-to-referenced-entryin faq-visual-editor.md. - No check at all. Absence is not a pass. See "When the check does not appear" in onboarding-check.md, then verify the contracts by hand.
Step 4. Detect framework, mode and fetch layer
Read the code instead of asking. State what you found and ask only for confirmation.
| Check | Where | Why |
|---|---|---|
| Framework, router | package.json; app/ vs pages/ |
Decides where init() may run |
| SDK versions, one copy | package.json, lockfile, any <script type="module"> |
Two copies behave like a config bug |
| Route's rendering mode | dynamic, revalidate, getStaticProps, getServerSideProps, output: "export" |
The broken route's mode, not the app default |
ssr |
init( call site and the Stack's live_preview.ssr |
Stack config overrides init({ ssr }) |
stackSdk, mode |
init( call site |
stackSdk absent defaults ssr to true |
| Init placement | file containing init(, "use client" |
Contract 1 |
| Edit tags | addEditableTags |
Contract 2 |
| Fetch layer, host wiring | Delivery SDK, raw fetch, GraphQL client; preview_token, live_preview, hosts |
Contract 3 |
| Cache | fetch cache options, revalidate, CDN or middleware |
"Works locally, fails deployed" |
The code cannot tell you where the site is served or whether the deployed build matches the branch. Ask for both.
Mode decides how updates arrive:
| Mode | ssr |
Hash reaches the fetch via | Updates |
|---|---|---|---|
| CSR (incl. SSG at runtime) | false |
postMessage into stackSdk; ContentstackLivePreview.hash for GraphQL |
onEntryChange refetch |
| SSR | true |
live_preview query parameter on the request |
Parent reloads the iframe; onEntryChange never fires on edits |
Detail per mode, including SSG, ISR and GraphQL, is in references/rendering-modes.md. Init placement per framework is in references/frameworks.md.
Step 5. Collect what is still open
Ask for the rest in one message, skipping anything already settled:
- Browser console with the preview panel open, reproduced after a reload. Check it against references/console-noise.md first: some messages appear on healthy setups and are not evidence.
- Server logs, for SSR, middleware, BFF or proxy setups. A swallowed preview fetch error lives here.
- One content request, redacted: host, status, response headers. For CSR, take it from the browser Network tab; for SSR, middleware or BFF, take the server-side preview fetch from server logs or a proxy trace, since it never appears in the browser. A delivery CDN host for the stack's region during a preview session means the hash is not reaching the fetch, whatever the symptom.
And, one line each: one user or everyone (one user points at their role), localhost or deployed (deployed-only points at a cache or frame header), consistent or intermittent (intermittent under SSR points at a shared Stack instance), which locale and variant.
Step 6. Localise to one contract
| # | Contract | One-look check |
|---|---|---|
| 1 | init() runs on the client in the deployed build |
Live Preview check gets past "Live Preview SDK Not Initialized" |
| 2 | Edit tags are generated and land on DOM elements | Rendered elements carry data-cslp |
| 3 | The hash reaches the fetch, which switches host and headers | Content requests hit the region's *-preview host |
| 4 | The site is reachable in an iframe | The pane renders at all |
Contract 4 gates everything; contract 1 gates 2 and 3. Name the unmet one with its evidence.
- Contract 2 detail, key conventions and the empty-block contract: references/edit-tags.md.
- Behavioural symptoms: look them up in references/symptom-index.md, which routes to faq-integration.md, faq-preview-runtime.md, faq-visual-editor.md and faq-timeline.md.
Step 7. Fix and verify, or hand over
State contract, evidence and reproduction, then the smallest change at the right layer: init, tags, fetch, cache, routing, or stack configuration. The verification is the reproduction run again with the opposite result.
Some causes sit outside the application: provisioning, plan gating, browser policy. No site change fixes them. See references/contact-support.md and produce its handover note from what steps 1 to 6 already collected.
Output Format
New integration: follow "Reply shape" in references/setup-docs.md.
Failing integration: lead with the broken contract and its evidence. Then the smallest change as a snippet or diff, or a plain statement that no application-side fix exists. Then one verification.
When evidence is still missing, ask for the one artifact that separates the remaining candidates and say what each answer would mean.
Say whether a behaviour applies to preview only or to production too. Preview output reaching real visitors is a production incident.
Tooling Notes
Read-only inspection with Read, Grep and Glob. Useful greps: init(, addEditableTags,
onEntryChange, live_preview, preview_token, hostname constants, cache configuration.
Minimum versions: Live Preview Utils v3.0+ for Visual Editor (legacy contentstack JavaScript SDK
v3.20.3+); Live Preview Utils v4.4.4+ for setPageContext().
Without repository access, run the same steps against described code and screenshots. Do not claim to have inspected code.
Security
Defaults
- Never ask for, echo or reconstruct tokens or live preview hashes. Ask for redacted logs and screenshots. If a secret appears, tell the user to rotate it.
- A management token in client-side configuration is an exposure.
- Do not recommend enabling Live Preview in production builds. An edit button on a public site is a symptom of exactly that.
- Validate preview target hosts before suggesting header or CSP changes, and scope any relaxation to the preview deployment.
Secrets
Never reveal, echo or reconstruct preview tokens, delivery tokens, management tokens, live preview hashes, cookies or authorization headers. If one appears in the conversation, do not repeat it and recommend rotating it.
Environment Variables
Ask for environment variable names, never their values. Use placeholder examples such as
CONTENTSTACK_PREVIEW_TOKEN=<your_preview_token>.
Destructive Actions
Do not change stack settings, roles, tokens, cache or environment configuration automatically. Propose the change, state the blast radius, and require confirmation.