@craftware/crafty-sdk 0.2.2 → 0.3.0

package/dist/visual-editing/origin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"origin.js","sourceRoot":"","sources":["../../src/visual-editing/origin.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,MAAM,CAAC,MAAM,qBAAqB,GAAmC,CAAC,uCAAuC,CAAC,CAAC;AAE/G,SAAS,QAAQ,CAAC,KAAa;IAC7B,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,MAAc,EAAE,SAAyC;IAC5F,IAAI,MAAM,KAAK,EAAE,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACvC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE;QAChC,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAChC,OAAO,QAAQ,CAAC,OAAO,CAAC,KAAK,MAAM,CAAC;QACtC,CAAC;QAED,OAAO,CAAC,SAAS,GAAG,CAAC,CAAC;QAEtB,OAAO,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAC7C,MAAM,SAAS,GAAG,GAAG,CAAC,QAAQ,CAAC,eAAgD,CAAC;IAChF,MAAM,KAAK,GAAG,SAAS,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAE3E,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;QAC9C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC;IAEvC,OAAO,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9C,CAAC"}

package/dist/visual-editing/overlay.d.ts

@@ -0,0 +1,13 @@
+export declare const FLASH_CLASS = "crafty-ve-flash";
+export type Overlay = {
+    show(element: Element, label: string): void;
+    hide(): void;
+    /** Re-measures the highlighted element, e.g. after its content changed. */
+    reposition(): void;
+    flash(elements: Element[], durationMs: number): void;
+    ensureAttached(): void;
+    contains(node: Node | null): boolean;
+    destroy(): void;
+};
+export declare function createOverlay(doc: Document): Overlay;
+//# sourceMappingURL=overlay.d.ts.map

package/dist/visual-editing/overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../../src/visual-editing/overlay.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,WAAW,oBAAoB,CAAC;AAU7C,MAAM,MAAM,OAAO,GAAG;IACpB,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,IAAI,IAAI,IAAI,CAAC;IACb,2EAA2E;IAC3E,UAAU,IAAI,IAAI,CAAC;IACnB,KAAK,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACrD,cAAc,IAAI,IAAI,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,OAAO,CAAC;IACrC,OAAO,IAAI,IAAI,CAAC;CACjB,CAAC;AAEF,wBAAgB,aAAa,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAiHpD"}

package/dist/visual-editing/overlay.js

@@ -0,0 +1,107 @@
+const STYLE_ELEMENT_ID = "crafty-visual-editing-style";
+const ACCENT = "#4f46e5";
+export const FLASH_CLASS = "crafty-ve-flash";
+const STYLES = [
+    "[data-crafty-field]{cursor:pointer}",
+    `.crafty-ve-box{position:fixed;top:0;left:0;pointer-events:none;z-index:2147483647;box-sizing:border-box;border:2px solid ${ACCENT};border-radius:4px;background:rgba(79,70,229,.06)}`,
+    ".crafty-ve-box[hidden]{display:none}",
+    `.crafty-ve-label{position:absolute;left:-2px;bottom:100%;margin-bottom:4px;padding:2px 8px;max-width:320px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;border-radius:4px;background:${ACCENT};color:#fff;font:500 12px/1.5 system-ui,-apple-system,sans-serif}`,
+    `.${FLASH_CLASS}{outline:2px dashed ${ACCENT} !important;outline-offset:2px !important}`
+].join("\n");
+export function createOverlay(doc) {
+    const win = doc.defaultView;
+    const style = doc.createElement("style");
+    style.id = STYLE_ELEMENT_ID;
+    style.textContent = STYLES;
+    const box = doc.createElement("div");
+    box.setAttribute("data-crafty-overlay", "");
+    box.className = "crafty-ve-box";
+    box.hidden = true;
+    const label = doc.createElement("span");
+    label.className = "crafty-ve-label";
+    box.appendChild(label);
+    let target = null;
+    let flashed = [];
+    let flashTimer;
+    const Observer = win?.ResizeObserver;
+    const place = () => {
+        if (target === null) {
+            return;
+        }
+        const rect = target.getBoundingClientRect();
+        box.style.top = `${rect.top}px`;
+        box.style.left = `${rect.left}px`;
+        box.style.width = `${rect.width}px`;
+        box.style.height = `${rect.height}px`;
+    };
+    const resizeObserver = typeof Observer === "function" ? new Observer(() => place()) : null;
+    const track = (element) => {
+        if (target === element) {
+            return;
+        }
+        if (target !== null) {
+            resizeObserver?.unobserve(target);
+        }
+        target = element;
+        if (target !== null) {
+            resizeObserver?.observe(target);
+        }
+    };
+    const clearFlash = () => {
+        flashed.forEach((element) => element.classList.remove(FLASH_CLASS));
+        flashed = [];
+        if (flashTimer !== undefined) {
+            win?.clearTimeout(flashTimer);
+            flashTimer = undefined;
+        }
+    };
+    const ensureAttached = () => {
+        if (!style.isConnected) {
+            (doc.head ?? doc.documentElement).appendChild(style);
+        }
+        if (!box.isConnected) {
+            (doc.body ?? doc.documentElement).appendChild(box);
+        }
+    };
+    ensureAttached();
+    win?.addEventListener("scroll", place, { capture: true, passive: true });
+    win?.addEventListener("resize", place, { passive: true });
+    return {
+        show(element, text) {
+            ensureAttached();
+            track(element);
+            if (label.textContent !== text) {
+                label.textContent = text;
+            }
+            box.hidden = false;
+            place();
+        },
+        hide() {
+            track(null);
+            box.hidden = true;
+        },
+        reposition() {
+            place();
+        },
+        flash(elements, durationMs) {
+            clearFlash();
+            flashed = [...elements];
+            flashed.forEach((element) => element.classList.add(FLASH_CLASS));
+            flashTimer = win?.setTimeout(clearFlash, durationMs);
+        },
+        ensureAttached,
+        contains(node) {
+            return node !== null && (box === node || box.contains(node) || style === node || style.contains(node));
+        },
+        destroy() {
+            clearFlash();
+            win?.removeEventListener("scroll", place, { capture: true });
+            win?.removeEventListener("resize", place);
+            resizeObserver?.disconnect();
+            box.remove();
+            style.remove();
+            target = null;
+        }
+    };
+}
+//# sourceMappingURL=overlay.js.map

package/dist/visual-editing/overlay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.js","sourceRoot":"","sources":["../../src/visual-editing/overlay.ts"],"names":[],"mappings":"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"}

package/dist/visual-editing/protocol.d.ts

@@ -0,0 +1,79 @@
+export declare const PROTOCOL_VERSION = 1;
+export type CraftyTargetType = "block" | "entry";
+export type CraftyFieldRef = {
+    type: CraftyTargetType;
+    id: number;
+    field: string;
+};
+export type CraftyMarkedField = CraftyFieldRef & {
+    label?: string;
+};
+export type CraftyShownPage = {
+    id: number;
+    slug: string;
+};
+export type CraftyShownEntry = {
+    id: number;
+    collection: string;
+};
+export type ReadyPayload = {
+    sdkVersion: string;
+    path: string;
+    fields: CraftyMarkedField[];
+    page: CraftyShownPage | null;
+    entries: CraftyShownEntry[];
+};
+type Version = typeof PROTOCOL_VERSION;
+type EmptyPayload = Record<string, never>;
+/** iframe -> admin. `crafty:ready` is a snapshot that may be re-sent; the last one wins. */
+export type OutboundMessage = {
+    v: Version;
+    type: "crafty:ready";
+    payload: ReadyPayload;
+} | {
+    v: Version;
+    type: "crafty:select";
+    payload: CraftyMarkedField;
+} | {
+    v: Version;
+    type: "crafty:navigate";
+    payload: {
+        path: string;
+    };
+} | {
+    v: Version;
+    type: "crafty:preview-invalid";
+    payload: EmptyPayload;
+};
+/** admin -> iframe. */
+export type InboundMessage = {
+    v: Version;
+    type: "crafty:token";
+    payload: {
+        token: string;
+    };
+} | {
+    v: Version;
+    type: "crafty:refresh";
+    payload: EmptyPayload;
+} | {
+    v: Version;
+    type: "crafty:highlight";
+    payload: CraftyFieldRef;
+} | {
+    v: Version;
+    type: "crafty:preview-field";
+    payload: CraftyFieldRef & {
+        value: string;
+    };
+} | {
+    v: Version;
+    type: "crafty:preview-reset";
+    payload: CraftyFieldRef;
+};
+export declare function parseFieldRef(value: unknown): CraftyFieldRef | null;
+export declare function parseMarkedField(value: unknown): CraftyMarkedField | null;
+export declare function parseInboundMessage(data: unknown): InboundMessage | null;
+export declare function parseOutboundMessage(data: unknown): OutboundMessage | null;
+export {};
+//# sourceMappingURL=protocol.d.ts.map

package/dist/visual-editing/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/visual-editing/protocol.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,OAAO,CAAC;AACjD,MAAM,MAAM,cAAc,GAAG;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AACnF,MAAM,MAAM,iBAAiB,GAAG,cAAc,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AACpE,MAAM,MAAM,eAAe,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAC3D,MAAM,MAAM,gBAAgB,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAElE,MAAM,MAAM,YAAY,GAAG;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,IAAI,EAAE,eAAe,GAAG,IAAI,CAAC;IAC7B,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B,CAAC;AAEF,KAAK,OAAO,GAAG,OAAO,gBAAgB,CAAC;AACvC,KAAK,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE1C,4FAA4F;AAC5F,MAAM,MAAM,eAAe,GACvB;IAAE,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,GAC3D;IAAE,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,iBAAiB,CAAA;CAAE,GACjE;IAAE,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAClE;IAAE,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,wBAAwB,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAAC;AAE1E,uBAAuB;AACvB,MAAM,MAAM,cAAc,GACtB;IAAE,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAChE;IAAE,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,GAC7D;IAAE,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,kBAAkB,CAAC;IAAC,OAAO,EAAE,cAAc,CAAA;CAAE,GACjE;IAAE,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,sBAAsB,CAAC;IAAC,OAAO,EAAE,cAAc,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GACzF;IAAE,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,sBAAsB,CAAC;IAAC,OAAO,EAAE,cAAc,CAAA;CAAE,CAAC;AAqB1E,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,GAAG,IAAI,CAgBnE;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,GAAG,IAAI,CAWzE;AAyCD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,GAAG,IAAI,CAwCxE;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,GAAG,IAAI,CAoD1E"}

package/dist/visual-editing/protocol.js

@@ -0,0 +1,150 @@
+export const PROTOCOL_VERSION = 1;
+/** Same limits as the Crafty admin and backend (content_drafts.field / label). */
+const MAX_FIELD_LENGTH = 255;
+const MAX_LABEL_LENGTH = 120;
+const MAX_TOKEN_LENGTH = 4096;
+const MAX_VALUE_LENGTH = 100_000;
+const MAX_PATH_LENGTH = 2048;
+const FIELD_PATTERN = /^[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+|\[\d+\])*$/;
+const TOKEN_PATTERN = /^[\x21-\x7E]+$/;
+const CONTROL_CHARACTERS = /[\u0000-\u001F\u007F]/;
+const PATH_BASE = "https://crafty.invalid";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPositiveInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+export function parseFieldRef(value) {
+    if (!isRecord(value)) {
+        return null;
+    }
+    const { type, id, field } = value;
+    if ((type !== "block" && type !== "entry") || !isPositiveInteger(id) || typeof field !== "string") {
+        return null;
+    }
+    const trimmed = field.trim();
+    return trimmed === "" || trimmed.length > MAX_FIELD_LENGTH || !FIELD_PATTERN.test(trimmed)
+        ? null
+        : { type, id, field: trimmed };
+}
+export function parseMarkedField(value) {
+    const ref = parseFieldRef(value);
+    if (ref === null) {
+        return null;
+    }
+    const rawLabel = isRecord(value) ? value.label : undefined;
+    const label = typeof rawLabel === "string" ? rawLabel.trim().slice(0, MAX_LABEL_LENGTH).trim() : "";
+    return label === "" ? ref : { ...ref, label };
+}
+function isSameOriginPath(value) {
+    if (!value.startsWith("/") || value.startsWith("//") || value.startsWith("/\\")) {
+        return false;
+    }
+    try {
+        const url = new URL(value, PATH_BASE);
+        // Dot segments can still resolve to a protocol-relative path ("/.//evil.example").
+        return url.origin === PATH_BASE && !url.pathname.startsWith("//") && !url.pathname.startsWith("/\\");
+    }
+    catch {
+        return false;
+    }
+}
+function parsePath(value) {
+    if (typeof value !== "string" || value.length > MAX_PATH_LENGTH || CONTROL_CHARACTERS.test(value)) {
+        return null;
+    }
+    return isSameOriginPath(value) ? value : null;
+}
+function parseShownEntry(value) {
+    return isRecord(value) && isPositiveInteger(value.id) && typeof value.collection === "string"
+        ? { id: value.id, collection: value.collection }
+        : null;
+}
+function readEnvelope(data) {
+    if (!isRecord(data) || data.v !== PROTOCOL_VERSION || typeof data.type !== "string") {
+        return null;
+    }
+    const payload = data.payload === undefined ? {} : data.payload;
+    return isRecord(payload) ? { type: data.type, payload } : null;
+}
+export function parseInboundMessage(data) {
+    const message = readEnvelope(data);
+    if (message === null) {
+        return null;
+    }
+    const { payload } = message;
+    switch (message.type) {
+        case "crafty:token": {
+            const token = typeof payload.token === "string" ? payload.token.trim() : "";
+            return token !== "" && token.length <= MAX_TOKEN_LENGTH && TOKEN_PATTERN.test(token)
+                ? { v: PROTOCOL_VERSION, type: "crafty:token", payload: { token } }
+                : null;
+        }
+        case "crafty:refresh":
+            return { v: PROTOCOL_VERSION, type: "crafty:refresh", payload: {} };
+        case "crafty:highlight": {
+            const ref = parseFieldRef(payload);
+            return ref ? { v: PROTOCOL_VERSION, type: "crafty:highlight", payload: ref } : null;
+        }
+        case "crafty:preview-field": {
+            const ref = parseFieldRef(payload);
+            const value = payload.value;
+            return ref && typeof value === "string" && value.length <= MAX_VALUE_LENGTH
+                ? { v: PROTOCOL_VERSION, type: "crafty:preview-field", payload: { ...ref, value } }
+                : null;
+        }
+        case "crafty:preview-reset": {
+            const ref = parseFieldRef(payload);
+            return ref ? { v: PROTOCOL_VERSION, type: "crafty:preview-reset", payload: ref } : null;
+        }
+        default:
+            return null;
+    }
+}
+export function parseOutboundMessage(data) {
+    const message = readEnvelope(data);
+    if (message === null) {
+        return null;
+    }
+    const { payload } = message;
+    switch (message.type) {
+        case "crafty:ready": {
+            const path = parsePath(payload.path);
+            const rawPage = payload.page;
+            if (typeof payload.sdkVersion !== "string" || path === null || !Array.isArray(payload.fields) || !Array.isArray(payload.entries)) {
+                return null;
+            }
+            return {
+                v: PROTOCOL_VERSION,
+                type: "crafty:ready",
+                payload: {
+                    sdkVersion: payload.sdkVersion,
+                    path,
+                    fields: payload.fields
+                        .map((field) => parseMarkedField(field))
+                        .filter((field) => field !== null),
+                    page: isRecord(rawPage) && isPositiveInteger(rawPage.id) && typeof rawPage.slug === "string"
+                        ? { id: rawPage.id, slug: rawPage.slug }
+                        : null,
+                    entries: payload.entries
+                        .map((entry) => parseShownEntry(entry))
+                        .filter((entry) => entry !== null)
+                }
+            };
+        }
+        case "crafty:select": {
+            const field = parseMarkedField(payload);
+            return field ? { v: PROTOCOL_VERSION, type: "crafty:select", payload: field } : null;
+        }
+        case "crafty:navigate": {
+            const path = parsePath(payload.path);
+            return path ? { v: PROTOCOL_VERSION, type: "crafty:navigate", payload: { path } } : null;
+        }
+        case "crafty:preview-invalid":
+            return { v: PROTOCOL_VERSION, type: "crafty:preview-invalid", payload: {} };
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=protocol.js.map

package/dist/visual-editing/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/visual-editing/protocol.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAkClC,kFAAkF;AAClF,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAC7B,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAC7B,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAC9B,MAAM,gBAAgB,GAAG,OAAO,CAAC;AACjC,MAAM,eAAe,GAAG,IAAI,CAAC;AAC7B,MAAM,aAAa,GAAG,+CAA+C,CAAC;AACtE,MAAM,aAAa,GAAG,gBAAgB,CAAC;AACvC,MAAM,kBAAkB,GAAG,uBAAuB,CAAC;AACnD,MAAM,SAAS,GAAG,wBAAwB,CAAC;AAE3C,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAc;IACvC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC;AAC3E,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;IAElC,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,iBAAiB,CAAC,EAAE,CAAC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAClG,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAE7B,OAAO,OAAO,KAAK,EAAE,IAAI,OAAO,CAAC,MAAM,GAAG,gBAAgB,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC;QACxF,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,MAAM,GAAG,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAEjC,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACjB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3D,MAAM,KAAK,GAAG,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAEpG,OAAO,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,GAAG,EAAE,KAAK,EAAE,CAAC;AAChD,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAa;IACrC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAChF,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QAEtC,mFAAmF;QACnF,OAAO,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IACvG,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,eAAe,IAAI,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAClG,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAChD,CAAC;AAED,SAAS,eAAe,CAAC,KAAc;IACrC,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ;QAC3F,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE;QAChD,CAAC,CAAC,IAAI,CAAC;AACX,CAAC;AAED,SAAS,YAAY,CAAC,IAAa;IACjC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,KAAK,gBAAgB,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACpF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC;IAE/D,OAAO,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACjE,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,IAAa;IAC/C,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAEnC,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAE5B,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,cAAc,CAAC,CAAC,CAAC;YACpB,MAAM,KAAK,GAAG,OAAO,OAAO,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAE5E,OAAO,KAAK,KAAK,EAAE,IAAI,KAAK,CAAC,MAAM,IAAI,gBAAgB,IAAI,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC;gBAClF,CAAC,CAAC,EAAE,CAAC,EAAE,gBAAgB,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,EAAE;gBACnE,CAAC,CAAC,IAAI,CAAC;QACX,CAAC;QACD,KAAK,gBAAgB;YACnB,OAAO,EAAE,CAAC,EAAE,gBAAgB,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;QACtE,KAAK,kBAAkB,CAAC,CAAC,CAAC;YACxB,MAAM,GAAG,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;YAEnC,OAAO,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,gBAAgB,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QACtF,CAAC;QACD,KAAK,sBAAsB,CAAC,CAAC,CAAC;YAC5B,MAAM,GAAG,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;YACnC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;YAE5B,OAAO,GAAG,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,IAAI,gBAAgB;gBACzE,CAAC,CAAC,EAAE,CAAC,EAAE,gBAAgB,EAAE,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,EAAE,GAAG,GAAG,EAAE,KAAK,EAAE,EAAE;gBACnF,CAAC,CAAC,IAAI,CAAC;QACX,CAAC;QACD,KAAK,sBAAsB,CAAC,CAAC,CAAC;YAC5B,MAAM,GAAG,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;YAEnC,OAAO,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,gBAAgB,EAAE,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QAC1F,CAAC;QACD;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,IAAa;IAChD,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAEnC,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAE5B,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,cAAc,CAAC,CAAC,CAAC;YACpB,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACrC,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;YAE7B,IAAI,OAAO,OAAO,CAAC,UAAU,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;gBACjI,OAAO,IAAI,CAAC;YACd,CAAC;YAED,OAAO;gBACL,CAAC,EAAE,gBAAgB;gBACnB,IAAI,EAAE,cAAc;gBACpB,OAAO,EAAE;oBACP,UAAU,EAAE,OAAO,CAAC,UAAU;oBAC9B,IAAI;oBACJ,MAAM,EAAE,OAAO,CAAC,MAAM;yBACnB,GAAG,CAAC,CAAC,KAAc,EAAE,EAAE,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;yBAChD,MAAM,CAAC,CAAC,KAAK,EAA8B,EAAE,CAAC,KAAK,KAAK,IAAI,CAAC;oBAChE,IAAI,EACF,QAAQ,CAAC,OAAO,CAAC,IAAI,iBAAiB,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ;wBACpF,CAAC,CAAC,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE;wBACxC,CAAC,CAAC,IAAI;oBACV,OAAO,EAAE,OAAO,CAAC,OAAO;yBACrB,GAAG,CAAC,CAAC,KAAc,EAAE,EAAE,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;yBAC/C,MAAM,CAAC,CAAC,KAAK,EAA6B,EAAE,CAAC,KAAK,KAAK,IAAI,CAAC;iBAChE;aACF,CAAC;QACJ,CAAC;QACD,KAAK,eAAe,CAAC,CAAC,CAAC;YACrB,MAAM,KAAK,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;YAExC,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,gBAAgB,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QACvF,CAAC;QACD,KAAK,iBAAiB,CAAC,CAAC,CAAC;YACvB,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAErC,OAAO,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,gBAAgB,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QAC3F,CAAC;QACD,KAAK,wBAAwB;YAC3B,OAAO,EAAE,CAAC,EAAE,gBAAgB,EAAE,IAAI,EAAE,wBAAwB,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;QAC9E;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craftware/crafty-sdk",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "private": false,
   "type": "module",
   "sideEffects": false,
@@ -12,7 +12,12 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
-    }
+    },
+    "./visual-editing": {
+      "types": "./dist/visual-editing/index.d.ts",
+      "import": "./dist/visual-editing/index.js"
+    },
+    "./package.json": "./package.json"
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -25,14 +30,18 @@
     "node": ">=20"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "node scripts/write-version.mjs && tsc -p tsconfig.json && node scripts/build-cdn.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && vitest run",
     "codegen": "node scripts/codegen.mjs",
     "changeset": "npx -y @changesets/cli@2.29.7",
     "changeset:add": "npm run changeset -- add",
     "changeset:version": "npm run changeset -- version"
   },
   "devDependencies": {
-    "typescript": "^5.8.2"
+    "esbuild": "^0.28.2",
+    "happy-dom": "^20.14.5",
+    "typescript": "^5.8.2",
+    "vitest": "^4.1.11"
   }
 }

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()`, deliver the preview token for the site's render mode, call `enableVisualEditing()` (pass `client` for `ssr` sites, so the bridge can confirm the token itself), allow framing (`frame-ancestors`), check images are public, run `configure_visual_editor`, and verify.
+- **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:
@@ -138,3 +150,4 @@ These are two different credentials — do not mix them:
 
 - `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.