@craftware/crafty-sdk 0.2.2 → 0.4.0

package/skills/crafty-cms/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: crafty-cms
-description: "Build on Crafty CMS — configure sites, pages, blocks, collections, entries, forms, and media through the Crafty MCP server, then develop a frontend with the @craftware/crafty-sdk JavaScript SDK. Use when connecting an agent to a Crafty MCP server; calling Crafty MCP tools like list_sites, create_page, publish_form, or upload_media; installing or importing @craftware/crafty-sdk or createCraftyClient; fetching Crafty pages, entries, collections, or media; rendering page blocks; or submitting Crafty forms."
+description: "Build on Crafty CMS — configure sites, pages, blocks, collections, entries, forms, and media through the Crafty MCP server, then develop a frontend with the @craftware/crafty-sdk JavaScript SDK. Use when connecting an agent to a Crafty MCP server; calling Crafty MCP tools like list_sites, create_page, publish_form, or upload_media; installing or importing @craftware/crafty-sdk or createCraftyClient; fetching Crafty pages, entries, collections, or media; rendering page blocks; submitting Crafty forms; or preparing a site for the Crafty visual editor (crafty.attrs, enableVisualEditing, preview tokens, configure_visual_editor)."
 license: MIT
 metadata:
   author: craftware
@@ -64,6 +64,7 @@ Collections/entries: `list_collections` → `create_entry` (`collection_slug`, `
 Forms: `create_form` (`site_id`, `name`, `slug`, `fields`) → `publish_form` → `list_form_submissions`.
 Media: `upload_media` (`url`, `site_id`, optional `collection_name`).
 Cache: `set_api_cache_status` (`site_id`, `enabled`) to toggle per-site; `flush_api_cache` (`site_id`, optional `resource`) to invalidate cached responses after bulk edits.
+Visual editor: `configure_visual_editor` (`site_id`, optional `environment`, `frontend_url`, `routes`, `render_mode`, `upload_media_collection`) — see `references/visual-editor.md`.
 
 > `update_page` **replaces all blocks** when `blocks` is supplied. `update_entry` creates a revision. `create_page` always starts as `draft`.
 
@@ -117,6 +118,17 @@ crafty deploy   # uploads dist/ to the configured environment
 
 > `crafty.json` is safe to commit. `.env` (which contains your API key) must be gitignored — use `.env.example` with placeholder values.
 
+## Visual editor (click-to-edit) — always ask
+
+Whenever you integrate Crafty into a frontend, ask the user exactly once:
+
+> **¿Quieres dejar el sitio preparado para el editor visual de Crafty?**
+
+- **Yes** → follow `references/visual-editor.md` completely: mark content with `crafty.attrs()` (buttons and links with `hrefField`; JSON paths with the stored index), deliver the preview token for the site's render mode, call `enableVisualEditing()` (pass `client` for `ssr` sites; React/Vue sites re-fetch and remount in `onRefresh`, hybrid sites cache the latest fetch), allow framing (`frame-ancestors`), check images are public, confirm which host really serves the domain before setting `frontend_url`, run `configure_visual_editor`, and verify (including hydration errors).
+- **No** → add nothing and tell the user it can be enabled later by asking «habilita el editor visual de Crafty».
+
+A later request like «habilita el editor visual de Crafty» on an existing site runs the Yes flow without asking again.
+
 ## Key distinction: MCP auth vs SDK API key
 
 These are two different credentials — do not mix them:
@@ -133,8 +145,10 @@ These are two different credentials — do not mix them:
 - **`update_entry` / `update_page` wipe fields you don't send** → both MCP tools do a **full replace**, not a merge. If you send only the new fields, all existing fields are deleted in that revision. Always fetch the current entry first (`get_entry`), merge your changes into the full field map, then call `update_entry` with the complete merged object.
 - **Content not visible via the SDK** → it isn't published. Pages/forms must be published (`publish_page` / `publish_form`).
 - **Confusing the two tokens** → the SDK `apiKey` (X-API-Key) is not an MCP Bearer token.
+- **Stale skill copy** → a project copy of this skill (e.g. `.claude/skills/crafty-cms`) does not update with the SDK. After upgrading `@craftware/crafty-sdk`, copy `node_modules/@craftware/crafty-sdk/skills/crafty-cms` over it.
 
 ## References
 
 - `references/mcp-configuration.md` — connecting every client, scopes, and the full MCP tool catalog with workflows.
 - `references/sdk-development.md` — the complete SDK surface, block helpers, error handling, and examples.
+- `references/visual-editor.md` — preparing a site for the visual editor: the mandatory question, marking, preview tokens, bridge, headers, `configure_visual_editor`, verification.

package/skills/crafty-cms/references/mcp-configuration.md

@@ -140,6 +140,7 @@ Form submissions may contain personal data, so they require their own scope.
 | `upload_media` | `url`, `site_id` | `collection_name` (default `library`), `file_name` | downloads the file from the URL |
 | `create_form` | `site_id`, `name`, `slug` | `description`, `fields` | `fields: [{ key, type, label, required? }]`; starts as `draft` |
 | `update_form` | `form_id` | `name`, `slug`, `description`, `fields`, `notification_emails` | only supplied fields change; `fields`/`notification_emails` replace |
+| `configure_visual_editor` | `site_id` | `environment` (default `production`), `frontend_url`, `routes` (`page_pattern`, `home_slug`, `collections`, `fixed`), `render_mode` (`ssr`/`hybrid`/`static`/`unknown`), `upload_media_collection` | visual editor settings of one environment; only sent keys change, `null` resets to the fallback; with only `site_id` it just reads; returns the effective settings |
 
 ### Publish (`crafty:publish`)
 
@@ -176,6 +177,12 @@ Form submissions may contain personal data, so they require their own scope.
 1. `upload_media` with `url` and `site_id` (optionally `collection_name`).
 2. `list_media` to confirm and retrieve URLs.
 
+**Visual editor**
+
+1. Prepare the frontend (see `visual-editor.md`).
+2. `configure_visual_editor` with `site_id`, `frontend_url`, `routes`, and `render_mode`.
+3. Ask the user to open **Editar sitio** in the admin to confirm click-to-edit works.
+
 **API response cache management**
 
 The public API has a tag-based response cache (enabled per environment). Per-site overrides take priority over the global setting.

package/skills/crafty-cms/references/sdk-development.md

@@ -23,7 +23,7 @@ const crafty = createCraftyClient({
 });
 ```
 
-`createCraftyClient(config)` returns a plain object with six resources: `collections`, `entries`, `pages`, `forms`, `mediaCollections`, `mediaFiles`.
+`createCraftyClient(config)` returns a plain object with six resources (`collections`, `entries`, `pages`, `forms`, `mediaCollections`, `mediaFiles`) and the visual editor helpers `attrs`, `attrsHtml` and `previewFromRequest`.
 
 ### Config options
 
@@ -35,6 +35,8 @@ const crafty = createCraftyClient({
 | `fetch` | no | Custom fetch. Defaults to `globalThis.fetch`. If none is available, construction throws `CraftyError` (`NETWORK_ERROR`). |
 | `headers` | no | Default headers merged into every request. |
 | `timeoutMs` | no | Default per-request timeout. A timeout is only armed when the value is a number `> 0`. |
+| `preview` | no | Visual editor preview token sent as `X-Crafty-Preview`. Omit in the browser (read from `?crafty_preview=`, kept in `sessionStorage`); pass `previewFromRequest(req)` on the server; `false` never sends one. |
+| `onPreviewInvalid` | no | Called when a request that carried a token gets `X-Crafty-Preview-Status: invalid` (the response is the public content). |
 
 ## Per-call options
 
@@ -191,6 +193,16 @@ try {
 }
 ```
 
+## Visual editor helpers
+
+- `attrs(target, field, { label? })` / `crafty.attrs(...)` → `{ "data-crafty-block" | "data-crafty-entry", "data-crafty-field", "data-crafty-label"? }` to spread on the element that renders the value; `{}` when the target has no valid id. `field` is a field key or a JSON path (`sections[3].title`).
+- `attrsHtml(target, field, { label? })` → the same attributes as an escaped HTML string.
+- `previewFromRequest(req)` → preview token of an incoming request (URL string, `URL`, Web `Request`, Node `req.url`, Express `req.query`) or `null`.
+- `readPreviewToken()` → token in the browser, or `null`.
+- `enableVisualEditing(options)` from `@craftware/crafty-sdk/visual-editing` → connects the page to the editor; no-op outside the admin iframe. Options: `onRefresh`, `adminOrigins`, `page`, `entries`, `touchHighlightMs`.
+
+Full integration checklist: `visual-editor.md`.
+
 ## Notes
 
 - `Accept: application/json` is set automatically unless overridden.

package/skills/crafty-cms/references/visual-editor.md

@@ -0,0 +1,297 @@
+# Preparing a site for the Crafty visual editor
+
+The visual editor lets a non-technical user open their real site inside the Crafty admin, click (or tap) a text or image, edit it in a side panel, watch the change live, and publish. It only works when the frontend is prepared with `@craftware/crafty-sdk` **0.3.0 or later**; use **0.4.0 or later** so buttons and links select instead of navigating and `hrefField` is available. This guide is the complete checklist.
+
+## The mandatory question
+
+Whenever you integrate Crafty into a frontend (a new site, new pages or sections, or moving hardcoded content into Crafty), ask the user this exact question once, before you finish:
+
+> **¿Quieres dejar el sitio preparado para el editor visual de Crafty?**
+
+- **Yes** → run the whole "Yes flow" below.
+- **No** → run the "No flow".
+- If the user later asks "habilita el editor visual de Crafty" (or anything equivalent) for an existing site, do not ask again: run the Yes flow.
+
+## No flow
+
+Add nothing: no `attrs()`, no `enableVisualEditing()`, no preview token handling, no headers, no `configure_visual_editor` call. End your final message with this sentence for the user:
+
+> El editor visual de Crafty no quedó activado. Cuando quieras activarlo, pide: «habilita el editor visual de Crafty».
+
+## Yes flow
+
+Do every step. Keep changes minimal and in the site's existing style.
+
+### 1. Decide the render mode
+
+| `render_mode` | How to recognise it | Token strategy (step 4) |
+|---|---|---|
+| `ssr` | Content is fetched on the server for every request: Next.js dynamic routes / Server Components without static caching, Nuxt SSR, Astro `output: "server"`, Remix loaders, Express/Fastify templates. | Read it per request with `previewFromRequest()`. |
+| `hybrid` | HTML is prerendered at build time **and** the browser fetches Crafty again on load (the Vite + prerender + client refresh pattern). | Automatic in the browser. |
+| `static` | Content is baked at build time only; the browser never calls the Crafty API. | Add a browser re-fetch that only runs in preview. |
+| `unknown` | You cannot tell. | Treat it like `hybrid` and tell the user. |
+
+### 2. Upgrade the SDK
+
+```bash
+npm install @craftware/crafty-sdk@^0.4.0
+```
+
+The package ships this skill. If the project keeps its own copy (for example `.claude/skills/crafty-cms`), refresh it after every SDK upgrade so it matches the installed version:
+
+```bash
+rm -rf .claude/skills/crafty-cms
+cp -R node_modules/@craftware/crafty-sdk/skills/crafty-cms .claude/skills/crafty-cms
+```
+
+### 3. Mark every editable element
+
+Use `attrs(target, field, { label })` (also available as `crafty.attrs` on the client). `target` is the block or entry the value came from; `field` is the field key or the JSON path of the value.
+
+Rules:
+
+- Mark only content that comes from Crafty. Never mark hardcoded text.
+- Put the attributes on the innermost element whose **entire text** is the field value (`<h1>`, `<p>`, `<span>`, the `<a>` or `<button>` label, `<li>`). Live preview replaces that element's text, so an element that also contains icons or other fields must not be marked; wrap the value in a `<span>` and mark the span.
+- Images from a media `reference` field: mark the `<img>` with the field key (`image`, `photo`).
+- Buttons and links (CTAs): mark the label and pass the destination field as `hrefField`, so the editor shows the text and an «Enlace» input together and saves each as its own draft. A click anywhere on a link selects its marked label (the editor never follows links); on a real `<button>`, `<summary>` or `<label>` only a click on the marked element selects, so menus and accordions keep working. A link whose only editable value is its destination (a `url` field) is marked on the `<a>` itself; destinations update after saving the draft, not live while typing.
+
+```tsx
+<Link to={cta.href} className="btn">
+  <span {...attrs(entry, `sections[${i}].cta.label`, { label: "Texto del botón", hrefField: `sections[${i}].cta.href`, hrefLabel: "Enlace del botón" })}>{cta.label}</span>
+  <Arrow />
+</Link>
+```
+- Values inside `json` fields: use the exact path of the rendered value, e.g. `sections[2].title`, `hero.title_segments[0].text`, `extra.ctaPrimaryLabel`. Array indexes are positions in the **stored** JSON. When you render the array as stored, the loop index is that position (`` `sections[${i}].title` ``). When you filter, sort, split or reorder it (featured vs regular products, items sorted by `order`, only visible sections), keep the stored index with each item **before** transforming it and use that, never the rendered index:
+
+```tsx
+// Keep the stored position before filtering or sorting.
+const items = section.items.map((item, index) => ({ item, index }));
+const featured = items.filter(({ item }) => item.featured).sort((a, b) => a.item.order - b.item.order);
+
+featured.map(({ item, index }) => (
+  <h3 key={index} {...attrs(entry, `sections[${sectionIndex}].items[${index}].title`, { label: "Título del producto" })}>{item.title}</h3>
+));
+```
+
+  Section components that receive one slice of a JSON field can take a path-scoped helper instead of the whole path:
+
+```ts
+// editable(entry).at(`sections[${i}]`)("title", "Título") -> attrs(entry, `sections[${i}].title`, { label: "Título" })
+export function editable(target, base = "") {
+  const join = (path) => (base ? `${base}.${path}` : path);
+  const edit = (field, label, options = {}) => attrs(target, join(field), { ...options, ...(label ? { label } : {}), ...(options.hrefField ? { hrefField: join(options.hrefField) } : {}) });
+  edit.at = (path) => editable(target, join(path));
+  return edit;
+}
+```
+- Editable types: `string`, `text`, `longText`, `url`, `number`, media `reference`, and string/number values inside `json`. Do not mark booleans, dates, selects, multi-references, or array items that are objects.
+- `label` is a short Spanish name the client understands ("Título principal", "Texto del botón"). Without it the editor shows the field key.
+- Pass blocks and entries as the API returns them. If an entry has fields named `order`, `data` and `type` at once, pass `{ kind: "entry", id: entry.id }` instead.
+
+React / Next.js / Astro (JSX):
+
+```tsx
+import { attrs } from "@craftware/crafty-sdk";
+
+<h1 {...attrs(block, "title", { label: "Título principal" })}>{block.data.title}</h1>
+<img {...attrs(block, "image", { label: "Imagen principal" })} src={imageUrl} alt="" />
+
+{sections.map((section, i) => (
+  <section key={i}>
+    <h2 {...attrs(entry, `sections[${i}].title`, { label: "Título de la sección" })}>{section.title}</h2>
+    <p {...attrs(entry, `sections[${i}].body`, { label: "Texto de la sección" })}>{section.body}</p>
+  </section>
+))}
+```
+
+Vue:
+
+```vue
+<h1 v-bind="attrs(entry, 'hero.title', { label: 'Título principal' })">{{ entry.hero.title }}</h1>
+```
+
+HTML string templates (vanilla TS):
+
+```ts
+import { attrsHtml } from "@craftware/crafty-sdk";
+
+html += `<h1 ${attrsHtml(entry, "extra.title", { label: "Título" })}>${escapeHtml(extra.title)}</h1>`;
+```
+
+### 4. Deliver the preview token
+
+The editor loads the site with `?crafty_preview=<token>`. Requests that carry it as `X-Crafty-Preview` get unpublished drafts and bypass the API cache.
+
+- **hybrid / SPA:** nothing to do. A client created in the browser reads the token from the URL, keeps it in `sessionStorage`, and sends it on every request. Make sure the browser re-fetch really runs on every page load.
+- **ssr:** create the client **per request** with the token, never share a module-level client that received one, and never cache a preview response:
+
+```ts
+import { createCraftyClient, previewFromRequest } from "@craftware/crafty-sdk";
+
+// Express / Node: previewFromRequest(req)   Web Request: previewFromRequest(request)
+// Next.js App Router: previewFromRequest({ query: await searchParams })
+const preview = previewFromRequest(req);
+const crafty = createCraftyClient({ baseUrl: process.env.CRAFTY_URL!, apiKey: process.env.CRAFTY_API_KEY!, preview });
+
+if (preview) {
+  res.setHeader("Cache-Control", "no-store"); // Next.js: call noStore() / use dynamic rendering for this request
+}
+```
+
+  Server-rendered pages should also tell the editor what they show (step 5, `page` / `entries`).
+- **static:** the built HTML has no drafts, so re-fetch in the browser only when previewing and re-render:
+
+```ts
+import { readPreviewToken } from "@craftware/crafty-sdk";
+
+if (readPreviewToken()) {
+  const fresh = await crafty.entries.list("site-pages");
+  renderPage(fresh.data); // the same function the build uses
+}
+```
+
+  If the site cannot re-render in the browser, set `render_mode` to `static` anyway and tell the user that the editor will show changes only after saving and reloading, and the public site only after a deploy.
+
+### 5. Turn on the bridge
+
+Call it once in the browser entry (it keeps watching the DOM, so it can run before or after the first render):
+
+```ts
+import { enableVisualEditing } from "@craftware/crafty-sdk/visual-editing";
+
+enableVisualEditing({
+  onRefresh: () => reloadCraftyContent(), // re-fetch + re-render; omit it to let the editor reload the page
+});
+```
+
+- It does nothing for normal visitors (it needs the admin iframe, a token, and an allowed admin origin), so ship it to production.
+- Even then it stays inert until the backend confirms the token — a response with `X-Crafty-Preview-Status: active`, normally the site's own first Crafty request for that page. **`ssr` sites where the browser never calls the Crafty API itself must pass `client`** (a `CraftyClient`, typically the same one already created for that render mode) so the bridge can confirm the token itself with one lightweight request (`pages.list({ per_page: 1 })`): `enableVisualEditing({ client: crafty })`. `hybrid` and `static` sites already make a browser-side request that carries the header, so `client` is optional for them. If the API answers `invalid`, the bridge stays off and tells the admin instead of activating.
+- If the site fetches Crafty through something other than this SDK's client (so neither path above ever runs), report `X-Crafty-Preview-Status` yourself with `notifyPreviewActive()` / `notifyPreviewInvalid()` from `@craftware/crafty-sdk/visual-editing` (also exports `getPreviewStatus()` and the `PREVIEW_ACTIVE_EVENT` / `PREVIEW_INVALID_EVENT` event names).
+- `onRefresh`: register it when the site can re-fetch Crafty and re-render without a reload (SPAs, hybrid sites). Otherwise omit it.
+- **React, Vue and other frameworks:** live preview writes text straight into the DOM, into nodes the framework owns. Reconciling against those nodes after a refresh can leave stale text or crash (for example when the element also renders `<strong>` from an emphasis helper). In `onRefresh`, re-fetch and then **remount** the tree (change a `key` on the root) instead of patching it:
+
+```tsx
+// main.tsx (React)
+let remount = () => {};
+function Root() {
+  const [version, setVersion] = useState(0);
+  remount = () => setVersion((v) => v + 1);
+  return <App key={version} />;
+}
+enableVisualEditing({
+  onRefresh: async () => {
+    await refreshCrafty(); // re-fetch and update the content cache below
+    remount();
+  },
+});
+```
+
+  Vue: the same with `<App :key="version" />` on the root component.
+- **Hybrid sites: cache the latest fetch.** A remount (or a client-side navigation) must render the content fetched last (with drafts), not the build-time data embedded in the HTML. Keep the latest response per collection or page in a module-level cache, read it first when a component mounts, and update it in the refresh:
+
+```ts
+const cache = new Map<string, unknown>();
+export async function loadCollection(slug: string) {
+  const fresh = await crafty.entries.list(slug);
+  cache.set(slug, fresh.data);
+  return fresh.data;
+}
+export const cachedCollection = (slug: string, buildTime: unknown) => cache.get(slug) ?? buildTime;
+export const refreshCrafty = () => Promise.all([...cache.keys()].map(loadCollection));
+```
+- SSR: pass what the server rendered, e.g. `enableVisualEditing({ client: crafty, page: { id: page.id, slug: page.slug }, entries: [{ id: post.id, collection: "blog" }] })`.
+- `adminOrigins`: only when the tenant's admin is not on `https://<tenant>.crafty.do` (custom admin domain, or local development such as `http://<tenant>.crafty.test`). It replaces the default list.
+- No bundler:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@craftware/crafty-sdk@0.4/dist/crafty-visual-editing.global.js"></script>
+<script>CraftyVisualEditing.enableVisualEditing();</script>
+```
+
+  Pin an exact version (`@0.4.0`) with an `integrity="sha384-…" crossorigin="anonymous"` attribute (jsDelivr shows the hash) when the site uses Subresource Integrity.
+
+### 6. Allow the admin to frame the site
+
+The site must accept being framed by the admin. Sites deployed to Crafty Hosting get this header from Crafty; for any other host add it (and remove any `X-Frame-Options: DENY` / `SAMEORIGIN`):
+
+```
+Content-Security-Policy: frame-ancestors 'self' https://<tenant>.crafty.do
+```
+
+- Netlify / Cloudflare Pages (`_headers` in the build output):
+
+```
+/*
+  Content-Security-Policy: frame-ancestors 'self' https://<tenant>.crafty.do
+```
+
+- Vercel (`vercel.json`):
+
+```json
+{ "headers": [{ "source": "/(.*)", "headers": [{ "key": "Content-Security-Policy", "value": "frame-ancestors 'self' https://<tenant>.crafty.do" }] }] }
+```
+
+- Nginx: `add_header Content-Security-Policy "frame-ancestors 'self' https://<tenant>.crafty.do" always;`
+
+If the site already sends a `Content-Security-Policy`, add the `frame-ancestors` directive to it instead of sending a second header.
+
+### 7. Make sure images come from public repositories
+
+Static and hybrid sites keep image URLs in their HTML; private repositories give expiring URLs. Check with `list_media` (each file has `is_public`) or `crafty.mediaCollections.list()`. If images the site shows live in a private repository, tell the user: «Las imágenes del repositorio X son privadas y sus enlaces caducan en sitios estáticos. Márcalo como público en Crafty → Media.» Uploads made from the visual editor go to the public "Editor visual" repository by default.
+
+### 8. Configure Crafty
+
+Call `configure_visual_editor` (scope `crafty:write`) with what you learned:
+
+```json
+{
+  "site_id": 3,
+  "environment": "production",
+  "frontend_url": "https://www.example.com",
+  "routes": {
+    "page_pattern": "/{slug}",
+    "home_slug": "home",
+    "collections": { "blog": "/blog/{slug}" },
+    "fixed": ["/", "/en", "/blog"]
+  },
+  "render_mode": "hybrid"
+}
+```
+
+- `frontend_url`: the public URL of that environment where **this** build runs (omit it when it is the site's domain in production or the Crafty Hosting URL). Before setting a domain, check which host actually serves it: a domain can point at a different app than the one you prepared (another server, an older site), and then the editor frames a page without the SDK.
+
+```bash
+curl -sI https://www.example.com/ | grep -iE "^(server|x-frame-options|content-security-policy|set-cookie|location)"
+curl -sI https://<site>.pages.crafty.do/ | grep -iE "^(server|x-frame-options|content-security-policy)"
+```
+
+  Crafty Hosting answers with `content-security-policy: frame-ancestors 'self' https://<tenant>.crafty.do`. `x-frame-options: deny`, a foreign framework cookie (for example `laravel_session`) or a different `server` means another app serves that domain: do not use it as `frontend_url`; use the Crafty Hosting URL (omit `frontend_url`) or the URL that really serves this build.
+- `routes.page_pattern` / `home_slug`: only if the site renders Crafty **pages**; patterns start with `/` and contain `{slug}`.
+- `routes.collections`: collections whose entries have their own URL; patterns contain `{slug}` or `{id}`.
+- `routes.fixed`: every other URL that shows Crafty content (home in other languages, listing pages, single-page sites: just `["/"]`).
+- `render_mode`: from step 1.
+- Repeat with `environment: "development"` (or others) when they have their own URL.
+- Calling it with only `site_id` returns the current settings without changing anything.
+
+### 9. Verify
+
+1. Build and type-check the site.
+2. Run it locally and open a page with `?crafty_preview=test`. In DevTools:
+   - `document.querySelectorAll("[data-crafty-field]").length` is greater than 0 on every page type (home, a page, a collection entry).
+   - Requests to the Crafty API carry `X-Crafty-Preview: test`, and the responses say `X-Crafty-Preview-Status: invalid` (expected: `test` is not a real token; the content stays public).
+   - Nothing is highlighted: outside the admin iframe the bridge stays off.
+   - The console has no hydration errors (React #418/#423, Vue "Hydration mismatch"). Compare with a build without your changes: if they were already there, say so to the user instead of hiding them; if they are new, the marked markup differs between the prerender and the client render.
+   - Prerendered (hybrid/static) pages first show the published content and then the drafts once the browser re-fetch finishes. A short flash of published text in preview is expected; if drafts never appear, the preview re-fetch is missing or a remount reads build-time data (see the cache in step 5).
+3. After deploying, ask the user to open Crafty → the site → **Editar sitio** (`https://<tenant>.crafty.do/sites/<site_id>/visual-editor?path=/`). If hovering highlights texts and a click opens the field, the editor received `crafty:ready`. If it shows «Este sitio aún no tiene edición con clic activada», go through the troubleshooting list.
+
+End with a short summary for the user in Spanish: what was marked, the render mode, and what they must do after publishing (nothing for `ssr`/`hybrid`; a deploy for `static`).
+
+## Troubleshooting
+
+- **The editor shows «Este sitio aún no tiene edición con clic activada»** — the iframe is blocked (browser console: `frame-ancestors` or `X-Frame-Options`), `enableVisualEditing()` is not in the bundle of that page, the SDK is older than 0.3.0, the admin origin is not allowed (custom admin domain → `adminOrigins`), a redirect dropped the query string (trailing-slash or locale redirects must keep `?crafty_preview=`), or the site is `ssr` and never confirmed the token because `client` was not passed to `enableVisualEditing()`.
+- **«Esta URL no mostró la página …»** — `routes` do not match the site's URLs; fix them with `configure_visual_editor`.
+- **Saved drafts do not appear in the editor** — SSR: the client was created once at module level or the response was cached; static: the preview re-fetch is missing.
+- **Text reverts or the page crashes after saving** — a framework reconciled DOM that live preview had changed; remount in `onRefresh` (step 5).
+- **Typing does not update the text live** — the attributes are on a wrapper that contains more than the value, or the field is rich text (`longText` shows after saving the draft).
+- **Clicking a menu link opens its text instead of the page** — expected: with the bridge active, marked menu labels are selected for editing, not followed. Change pages with the editor's route selector (unmarked internal links still navigate).
+- **Clicking an editable card navigates away** — the SDK is older than 0.4.0 (earlier versions only selected when the click landed exactly on the marked element) or nothing inside the link is marked; mark its label.