@blocklify/preview 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Blocklify
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,21 @@
-# Temporary Holding Version
+# @blocklify/preview
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Frontend SDK for [Blocklify](https://github.com/): Content API client + live-preview React helpers for your theme.
+
+## Install
+
+```bash
+bun add @blocklify/preview
+# or: npm install @blocklify/preview
+```
+
+Peer dependencies: `react`, `react-dom` (≥18).
+
+## Live preview (theme blocks)
+
+1. Mount `BlocklifyPreview` on a `/preview` route with your `blockMap`.
+2. In each theme block, accept `BlocklifyBlockProps` and spread `{...BlocklifyEditable}` on the root element.
+3. Read CMS custom fields from `block` (e.g. `block.headline`).
+4. Register that preview URL under Space → Live preview URLs.
+
+See the in-app guide at `/docs/getting-started#live-preview`.

package/dist/client.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Lightweight client for the Blocklify Content API.
+ * Use from your website or app to fetch entries and components with an access token.
+ *
+ * @example
+ * const client = createBlocklifyClient({
+ *   baseUrl: process.env.BLOCKLIFY_API_URL!,
+ *   accessToken: process.env.BLOCKLIFY_ACCESS_TOKEN!,
+ * });
+ * const entries = await client.getEntries({ published: true });
+ * const home = await client.getEntry("home");
+ */
+export type BlocklifyClientConfig = {
+    /** Blocklify app base URL (e.g. https://your-blocklify-app.com, no trailing slash) */
+    baseUrl: string;
+    /** Access token (from Admin → Access tokens). Prefix: blocklify_... */
+    accessToken: string;
+};
+export type BlocklifyEntry = {
+    id: string;
+    spaceId: string;
+    slug: string;
+    name: string;
+    content: Record<string, unknown> & {
+        body?: Array<{
+            type: string;
+            [k: string]: unknown;
+        }>;
+        blocks?: Array<{
+            type: string;
+            [k: string]: unknown;
+        }>;
+        title?: string;
+    };
+    isPublished: boolean;
+    publishedAt: string | null;
+    contentType: {
+        id: string;
+        type: string;
+        name?: string;
+        schema?: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+};
+export type BlocklifyComponent = {
+    id: string;
+    spaceId: string;
+    name: string;
+    type: string;
+    schema: {
+        fields?: Array<{
+            name: string;
+            type: string;
+            [k: string]: unknown;
+        }>;
+    };
+    isRoot: boolean;
+    isNestable: boolean;
+};
+export type BlocklifySiteAsset = {
+    id: string;
+    url: string;
+    filename: string;
+    mimeType: string;
+    alt: string | null;
+};
+export type BlocklifySiteSettings = {
+    defaultPageTitle: string | null;
+    favicon: BlocklifySiteAsset | null;
+    logo: BlocklifySiteAsset | null;
+    custom: Array<{
+        key: string;
+        value: string;
+    }>;
+};
+export declare function createBlocklifyClient(config: BlocklifyClientConfig): {
+    /** List entries. Use published: true for production; omit for preview (drafts + published). */
+    getEntries(options?: {
+        published?: boolean;
+        spaceId?: string;
+    }): Promise<BlocklifyEntry[]>;
+    /** Get one entry by slug. Use for live preview. Returns null when entry is not found (404). */
+    getEntry(slug: string, options?: {
+        spaceId?: string;
+    }): Promise<BlocklifyEntry | null>;
+    /** List components (block definitions) for the space. */
+    getComponents(options?: {
+        spaceId?: string;
+    }): Promise<BlocklifyComponent[]>;
+    /** Site settings (default title, favicon, logo, custom key–value pairs). */
+    getSiteSettings(options?: {
+        spaceId?: string;
+    }): Promise<BlocklifySiteSettings>;
+};

package/dist/client.js

@@ -0,0 +1,83 @@
+/**
+ * Lightweight client for the Blocklify Content API.
+ * Use from your website or app to fetch entries and components with an access token.
+ *
+ * @example
+ * const client = createBlocklifyClient({
+ *   baseUrl: process.env.BLOCKLIFY_API_URL!,
+ *   accessToken: process.env.BLOCKLIFY_ACCESS_TOKEN!,
+ * });
+ * const entries = await client.getEntries({ published: true });
+ * const home = await client.getEntry("home");
+ */
+function buildHeaders(accessToken) {
+    return {
+        Authorization: `Bearer ${accessToken}`,
+        "Content-Type": "application/json",
+    };
+}
+function ensureNoTrailingSlash(url) {
+    return url.replace(/\/+$/, "");
+}
+export function createBlocklifyClient(config) {
+    const baseUrl = ensureNoTrailingSlash(config.baseUrl);
+    const headers = buildHeaders(config.accessToken);
+    async function request(path, options) {
+        const url = new URL(path.startsWith("http") ? path : baseUrl + path);
+        if (options?.searchParams) {
+            Object.entries(options.searchParams).forEach(([k, v]) => url.searchParams.set(k, v));
+        }
+        const res = await fetch(url.toString(), {
+            method: options?.method ?? "GET",
+            headers,
+            cache: "no-store",
+        });
+        if (!res.ok) {
+            const err = (await res.json().catch(() => ({})));
+            throw new Error(err.error ?? `API error ${res.status}`);
+        }
+        return res.json();
+    }
+    return {
+        /** List entries. Use published: true for production; omit for preview (drafts + published). */
+        getEntries(options) {
+            const searchParams = {};
+            if (options?.published === true)
+                searchParams.published = "true";
+            if (options?.spaceId)
+                searchParams.space = options.spaceId;
+            return request("/api/entries", { searchParams });
+        },
+        /** Get one entry by slug. Use for live preview. Returns null when entry is not found (404). */
+        async getEntry(slug, options) {
+            const searchParams = {};
+            if (options?.spaceId)
+                searchParams.space = options.spaceId;
+            const query = new URLSearchParams(searchParams).toString();
+            const path = `/api/entries/${encodeURIComponent(slug)}${query ? `?${query}` : ""}`;
+            const url = new URL(path.startsWith("http") ? path : baseUrl + path);
+            const res = await fetch(url.toString(), { method: "GET", headers, cache: "no-store" });
+            if (res.status === 404)
+                return null;
+            if (!res.ok) {
+                const err = (await res.json().catch(() => ({})));
+                throw new Error(err.error ?? `API error ${res.status}`);
+            }
+            return res.json();
+        },
+        /** List components (block definitions) for the space. */
+        getComponents(options) {
+            const searchParams = {};
+            if (options?.spaceId)
+                searchParams.space = options.spaceId;
+            return request("/api/components", { searchParams });
+        },
+        /** Site settings (default title, favicon, logo, custom key–value pairs). */
+        getSiteSettings(options) {
+            const searchParams = {};
+            if (options?.spaceId)
+                searchParams.space = options.spaceId;
+            return request("/api/site-settings", { searchParams });
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @blocklify/preview — install in your frontend / theme to fetch content and enable live preview.
+ *
+ * @example
+ * import {
+ *   BlocklifyPreview,
+ *   createBlocklifyClient,
+ *   type BlocklifyBlockProps,
+ * } from "@blocklify/preview";
+ */
+export { createBlocklifyClient, type BlocklifyClientConfig, type BlocklifyComponent, type BlocklifyEntry, type BlocklifySiteAsset, type BlocklifySiteSettings, } from "./client.js";
+export { BlocklifyEditable, BlocklifyPreview, BlocklifyPreviewRenderer, BLOCKLIFY_PEER_FOCUS, BLOCKLIFY_PREVIEW_STYLES, BLOCKLIFY_SCROLL_TO_BLOCK, getDataBlokC, PREVIEW_EDITABLE_CSS, useBlocklifyPreview, type BlocklifyBlock, type BlocklifyBlockProps, type BlocklifyPreviewProps, type BlockMap, type DataBlokCPayload, } from "./preview.js";
+export { default } from "./preview.js";

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * @blocklify/preview — install in your frontend / theme to fetch content and enable live preview.
+ *
+ * @example
+ * import {
+ *   BlocklifyPreview,
+ *   createBlocklifyClient,
+ *   type BlocklifyBlockProps,
+ * } from "@blocklify/preview";
+ */
+export { createBlocklifyClient, } from "./client.js";
+export { BlocklifyEditable, BlocklifyPreview, BlocklifyPreviewRenderer, BLOCKLIFY_PEER_FOCUS, BLOCKLIFY_PREVIEW_STYLES, BLOCKLIFY_SCROLL_TO_BLOCK, getDataBlokC, PREVIEW_EDITABLE_CSS, useBlocklifyPreview, } from "./preview.js";
+export { default } from "./preview.js";

package/dist/preview.d.ts

@@ -0,0 +1,111 @@
+import React from "react";
+/**
+ * Blocklify live-preview connector. Editable wrapper styles (border, hover) are defined here (PREVIEW_EDITABLE_CSS)
+ * and sent from the admin to the iframe via postMessage (blocklify-preview-styles). The other app only needs
+ * to use this lib and listen for that message; it will receive and inject the same styles so no duplication.
+ */
+/** Block shape sent by Blocklify (draft content or API). Your block components receive this. */
+export type BlocklifyBlock = {
+    type: string;
+    _uid?: string;
+    [k: string]: unknown;
+};
+/** Props passed to block components: block, optional BlocklifyEditable (spread on root in iframe), optional blockMap (for nested blocks). */
+export type BlocklifyBlockProps = {
+    block: BlocklifyBlock;
+    BlocklifyEditable?: Record<string, unknown>;
+    blockMap?: BlockMap;
+};
+/** Map block type string → component that receives { block, BlocklifyEditable? }. Spread BlocklifyEditable on the root element for click-to-focus in the preview iframe. */
+export type BlockMap = Record<string, React.ComponentType<BlocklifyBlockProps>>;
+/** Storyblok-style payload for data-blok-c (JSON string). */
+export type DataBlokCPayload = {
+    name: string;
+    uid: string;
+    space?: string;
+    id?: string;
+};
+/**
+ * Builds the value for the data-blok-c attribute (Storyblok-style JSON string).
+ * Use when you need to set data-blok-c yourself; otherwise BlocklifyEditable includes it.
+ */
+export declare function getDataBlokC(block: BlocklifyBlock, options?: {
+    spaceId?: string;
+    blockId?: string;
+}): string;
+/**
+ * Returns props to spread on the root element of a block so it becomes clickable in the preview iframe (like Storyblok’s storyblokEditable).
+ * Sets data-blok-c (Storyblok-style JSON: name, uid, space?, id?) and data-blok-uid for compatibility.
+ * Only returns non-empty when in iframe with onBlockClick; otherwise returns {} so components work unchanged outside preview.
+ * Use in the preview renderer; components just spread the BlocklifyEditable prop they receive.
+ * Clicks send the block's _uid so the editor can open the form for the correct block.
+ */
+export declare function BlocklifyEditable(block: BlocklifyBlock, index: number, onBlockClick: ((uid: string) => void) | undefined, options?: {
+    spaceId?: string;
+    blockId?: string;
+}): Record<string, unknown>;
+/** Message type the admin sends to the iframe with editable wrapper CSS (single source of truth in Blocklify). */
+export declare const BLOCKLIFY_PREVIEW_STYLES = "blocklify-preview-styles";
+/** Message type the admin sends when peer-focused blocks change, so the preview can render colored borders. */
+export declare const BLOCKLIFY_PEER_FOCUS = "blocklify-peer-focus";
+/** Message type the admin sends to scroll a block into view in the preview iframe (e.g. when focusing a field in the editor). */
+export declare const BLOCKLIFY_SCROLL_TO_BLOCK = "blocklify-scroll-to-block";
+/** Single source of truth for editable block styling in the preview iframe. Sent by the admin via postMessage so the other app doesn’t need to duplicate it. */
+export declare const PREVIEW_EDITABLE_CSS = "\n:root {\n    --radius: 0.5rem;\n}\n[data-blocklify-iframe-editable],\n[data-blok-uid] {\n    cursor: pointer !important;\n    border: 2px solid #2563eb !important;\n    border-radius: var(--radius) !important;\n    padding: 6px !important;\n    margin-bottom: 10px !important;\n    box-sizing: border-box !important;\n    transition: border-color 0.2s ease, background-color 0.2s ease !important;\n    position: relative !important;\n    min-height: 24px !important;\n}\n[data-blocklify-iframe-editable]:hover,\n[data-blok-uid]:hover {\n    border-color: #1d4ed8 !important;\n    background-color: rgba(37, 99, 235, 0.06) !important;\n}\n@keyframes blocklify-preview-focus-blink {\n    0% {\n        box-shadow: 0 0 0 0 rgba(37, 99, 235, 0);\n        border-color: #2563eb !important;\n    }\n    35% {\n        box-shadow: 0 0 0 4px rgba(37, 99, 235, 0.45);\n        border-color: #1d4ed8 !important;\n    }\n    100% {\n        box-shadow: 0 0 0 0 rgba(37, 99, 235, 0);\n        border-color: #2563eb !important;\n    }\n}\n.blocklify-preview-focus-blink {\n    animation: blocklify-preview-focus-blink 0.55s ease-out 1 !important;\n}\n@media (prefers-reduced-motion: reduce) {\n    .blocklify-preview-focus-blink {\n        animation: none !important;\n    }\n}\n";
+/**
+ * Hook that connects your preview page to the Blocklify admin iframe:
+ * - Listens for draft content via postMessage (type: "blocklify-draft").
+ * - Sends block clicks back to the editor (type: "blocklify-block-click").
+ * Use this when your preview page is loaded inside the Blocklify admin iframe.
+ */
+export declare function useBlocklifyPreview(blocksFieldName?: string): {
+    blocks: BlocklifyBlock[];
+    isInIframe: boolean;
+    onBlockClick: (uid: string) => void;
+    showEmptyMessage: boolean;
+    /** Space id from the draft message (for data-blok-c when admin sends spaceId). */
+    spaceId: string | null;
+    /** Use this when rendering editable wrappers: parent-sent CSS or PREVIEW_EDITABLE_CSS. */
+    editableCss: string;
+    /** Peer-focused blocks: uid → { name, color }. Inject as colored borders to show who is editing what. */
+    peerFocusedBlocks: Record<string, {
+        name: string;
+        color: string;
+    }>;
+};
+type BlocklifyPreviewRendererProps = {
+    blocks: BlocklifyBlock[];
+    blockMap: BlockMap;
+    onBlockClick?: (uid: string) => void;
+    /** Space id for data-blok-c (Storyblok-style). Pass from useBlocklifyPreview().spaceId when admin sends it. */
+    spaceId?: string | null;
+    /** CSS for editable wrappers. When in iframe, pass editableCss from useBlocklifyPreview (from parent or default). */
+    editableCss?: string;
+    /** Optional: pass to each component so nested blocks (e.g. Page, Grid) can render. */
+    blockMapForNested?: BlockMap;
+};
+/**
+ * Renders blocks using your blockMap. Passes BlocklifyEditable (from BlocklifyEditable()) so components can spread it on their root for click-to-focus in the iframe.
+ * Styles are injected from editableCss (sent by admin via postMessage). No wrapper div – components apply {...BlocklifyEditable} themselves.
+ */
+export declare function BlocklifyPreviewRenderer({ blocks, blockMap, onBlockClick, spaceId, editableCss, blockMapForNested, }: BlocklifyPreviewRendererProps): import("react/jsx-runtime").JSX.Element;
+export type BlocklifyPreviewProps = {
+    /** Map of block type → component that receives { block }. Define your blocks in your app and pass this. */
+    blockMap: BlockMap;
+    /** Key in draft content that holds the blocks array (default "body"). */
+    blocksFieldName?: string;
+    /** Message shown when the preview iframe has not received draft content yet. */
+    emptyMessage?: string;
+    /** Optional className for the root wrapper. */
+    className?: string;
+};
+/**
+ * Preview connector for Blocklify. Use this on your frontend’s preview page (e.g. /preview).
+ * You only need to define your block components and a blockMap; this component handles:
+ * - Receiving draft content from the Blocklify admin via postMessage
+ * - Sending block clicks back to the editor
+ * - Empty state message and editable borders when embedded in the admin iframe
+ */
+export declare function BlocklifyPreview({ blockMap, blocksFieldName, emptyMessage, className, }: BlocklifyPreviewProps): import("react/jsx-runtime").JSX.Element;
+/** Default export so both "import BlocklifyPreview from '...'" and "import { BlocklifyPreview } from '...'" work. */
+export default BlocklifyPreview;

package/dist/preview.js

@@ -0,0 +1,256 @@
+"use client";
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
+/**
+ * Builds the value for the data-blok-c attribute (Storyblok-style JSON string).
+ * Use when you need to set data-blok-c yourself; otherwise BlocklifyEditable includes it.
+ */
+export function getDataBlokC(block, options) {
+    const payload = {
+        name: block.type,
+        uid: block._uid ?? "",
+        ...(options?.spaceId != null && options.spaceId !== "" && { space: options.spaceId }),
+        ...((options?.blockId ?? block.id) != null &&
+            (options?.blockId ?? block.id) !== "" && {
+            id: String(options?.blockId ?? block.id),
+        }),
+    };
+    return JSON.stringify(payload);
+}
+/**
+ * Returns props to spread on the root element of a block so it becomes clickable in the preview iframe (like Storyblok’s storyblokEditable).
+ * Sets data-blok-c (Storyblok-style JSON: name, uid, space?, id?) and data-blok-uid for compatibility.
+ * Only returns non-empty when in iframe with onBlockClick; otherwise returns {} so components work unchanged outside preview.
+ * Use in the preview renderer; components just spread the BlocklifyEditable prop they receive.
+ * Clicks send the block's _uid so the editor can open the form for the correct block.
+ */
+export function BlocklifyEditable(block, index, onBlockClick, options) {
+    if (!onBlockClick)
+        return {};
+    const uid = block._uid ?? "";
+    return {
+        "data-blocklify-iframe-editable": true,
+        "data-blok-c": getDataBlokC(block, options),
+        ...(uid && { "data-blok-uid": uid }),
+        role: "button",
+        tabIndex: 0,
+        title: "Click to focus in editor",
+        "aria-label": `Edit block ${index + 1}, ${block.type}`,
+        onClick: (e) => {
+            e.preventDefault();
+            e.stopPropagation();
+            onBlockClick(uid);
+        },
+        onKeyDown: (e) => {
+            if (e.key === "Enter" || e.key === " ") {
+                e.preventDefault();
+                onBlockClick(uid);
+            }
+        },
+    };
+}
+const BLOCKLIFY_DRAFT = "blocklify-draft";
+const BLOCKLIFY_BLOCK_CLICK = "blocklify-block-click";
+/** Message type the admin sends to the iframe with editable wrapper CSS (single source of truth in Blocklify). */
+export const BLOCKLIFY_PREVIEW_STYLES = "blocklify-preview-styles";
+/** Message type the admin sends when peer-focused blocks change, so the preview can render colored borders. */
+export const BLOCKLIFY_PEER_FOCUS = "blocklify-peer-focus";
+/** Message type the admin sends to scroll a block into view in the preview iframe (e.g. when focusing a field in the editor). */
+export const BLOCKLIFY_SCROLL_TO_BLOCK = "blocklify-scroll-to-block";
+const PREVIEW_FOCUS_BLINK_CLASS = "blocklify-preview-focus-blink";
+const PREVIEW_FOCUS_BLINK_MS = 550;
+function pulsePreviewBlock(el) {
+    el.classList.remove(PREVIEW_FOCUS_BLINK_CLASS);
+    void el.offsetWidth;
+    el.classList.add(PREVIEW_FOCUS_BLINK_CLASS);
+    window.setTimeout(() => {
+        el.classList.remove(PREVIEW_FOCUS_BLINK_CLASS);
+    }, PREVIEW_FOCUS_BLINK_MS);
+}
+function scrollPreviewBlockIntoView(uid) {
+    if (typeof document === "undefined" || !uid)
+        return;
+    const escaped = typeof CSS !== "undefined" && typeof CSS.escape === "function" ? CSS.escape(uid) : uid;
+    const el = document.querySelector(`[data-blok-uid="${escaped}"]`) ??
+        document.querySelector(`[data-blocklify-uid="${escaped}"]`);
+    if (!(el instanceof HTMLElement))
+        return;
+    el.scrollIntoView({ behavior: "smooth", block: "center", inline: "nearest" });
+    pulsePreviewBlock(el);
+}
+/** Single source of truth for editable block styling in the preview iframe. Sent by the admin via postMessage so the other app doesn’t need to duplicate it. */
+export const PREVIEW_EDITABLE_CSS = `
+:root {
+    --radius: 0.5rem;
+}
+[data-blocklify-iframe-editable],
+[data-blok-uid] {
+    cursor: pointer !important;
+    border: 2px solid #2563eb !important;
+    border-radius: var(--radius) !important;
+    padding: 6px !important;
+    margin-bottom: 10px !important;
+    box-sizing: border-box !important;
+    transition: border-color 0.2s ease, background-color 0.2s ease !important;
+    position: relative !important;
+    min-height: 24px !important;
+}
+[data-blocklify-iframe-editable]:hover,
+[data-blok-uid]:hover {
+    border-color: #1d4ed8 !important;
+    background-color: rgba(37, 99, 235, 0.06) !important;
+}
+@keyframes blocklify-preview-focus-blink {
+    0% {
+        box-shadow: 0 0 0 0 rgba(37, 99, 235, 0);
+        border-color: #2563eb !important;
+    }
+    35% {
+        box-shadow: 0 0 0 4px rgba(37, 99, 235, 0.45);
+        border-color: #1d4ed8 !important;
+    }
+    100% {
+        box-shadow: 0 0 0 0 rgba(37, 99, 235, 0);
+        border-color: #2563eb !important;
+    }
+}
+.${PREVIEW_FOCUS_BLINK_CLASS} {
+    animation: blocklify-preview-focus-blink 0.55s ease-out 1 !important;
+}
+@media (prefers-reduced-motion: reduce) {
+    .${PREVIEW_FOCUS_BLINK_CLASS} {
+        animation: none !important;
+    }
+}
+`;
+function subscribeIsInIframe() {
+    // iframe embedding does not change for the lifetime of the page.
+    return () => { };
+}
+function getIsInIframeSnapshot() {
+    return window.self !== window.top;
+}
+function getIsInIframeServerSnapshot() {
+    return false;
+}
+/**
+ * Hook that connects your preview page to the Blocklify admin iframe:
+ * - Listens for draft content via postMessage (type: "blocklify-draft").
+ * - Sends block clicks back to the editor (type: "blocklify-block-click").
+ * Use this when your preview page is loaded inside the Blocklify admin iframe.
+ */
+export function useBlocklifyPreview(blocksFieldName = "body") {
+    const [draftContent, setDraftContent] = useState(null);
+    /** CSS for editable wrappers: from parent (postMessage) or fallback to PREVIEW_EDITABLE_CSS. */
+    const [receivedEditableCss, setReceivedEditableCss] = useState(null);
+    const [peerFocusedBlocks, setPeerFocusedBlocks] = useState({});
+    const isInIframe = useSyncExternalStore(subscribeIsInIframe, getIsInIframeSnapshot, getIsInIframeServerSnapshot);
+    const [spaceId, setSpaceId] = useState(null);
+    useEffect(() => {
+        if (!isInIframe)
+            return;
+        const onMessage = (event) => {
+            if (event.data?.type === BLOCKLIFY_DRAFT && event.data.content != null) {
+                setDraftContent(event.data.content);
+                setSpaceId(typeof event.data.spaceId === "string" && event.data.spaceId.trim() !== ""
+                    ? event.data.spaceId
+                    : null);
+            }
+            if (event.data?.type === BLOCKLIFY_PREVIEW_STYLES &&
+                typeof event.data.css === "string") {
+                setReceivedEditableCss(event.data.css);
+            }
+            if (event.data?.type === BLOCKLIFY_PEER_FOCUS && event.data.peers != null) {
+                setPeerFocusedBlocks(event.data.peers);
+            }
+            if (event.data?.type === BLOCKLIFY_SCROLL_TO_BLOCK &&
+                typeof event.data.uid === "string" &&
+                event.data.uid.trim() !== "") {
+                // Wait a frame so draft content / DOM from a concurrent update can settle.
+                requestAnimationFrame(() => {
+                    scrollPreviewBlockIntoView(event.data.uid);
+                });
+            }
+        };
+        window.addEventListener("message", onMessage);
+        return () => window.removeEventListener("message", onMessage);
+    }, [isInIframe]);
+    const onBlockClick = useCallback((uid) => {
+        if (typeof window === "undefined" || window === window.parent)
+            return;
+        window.parent.postMessage({ type: BLOCKLIFY_BLOCK_CLICK, uid, blocksFieldName }, "*");
+    }, [blocksFieldName]);
+    const rawBlocks = draftContent?.[blocksFieldName];
+    const blocks = Array.isArray(rawBlocks)
+        ? rawBlocks.filter((b) => b != null &&
+            typeof b === "object" &&
+            typeof b.type === "string")
+        : [];
+    const showEmptyMessage = isInIframe && blocks.length === 0 && draftContent === null;
+    return {
+        blocks,
+        isInIframe,
+        onBlockClick,
+        showEmptyMessage,
+        /** Space id from the draft message (for data-blok-c when admin sends spaceId). */
+        spaceId,
+        /** Use this when rendering editable wrappers: parent-sent CSS or PREVIEW_EDITABLE_CSS. */
+        editableCss: receivedEditableCss ?? PREVIEW_EDITABLE_CSS,
+        /** Peer-focused blocks: uid → { name, color }. Inject as colored borders to show who is editing what. */
+        peerFocusedBlocks,
+    };
+}
+/** Fallback when a block type has no component in the blockMap – never pass undefined to React. */
+function UnknownBlockFallback({ block, BlocklifyEditable = {}, }) {
+    return (_jsxs("section", { style: {
+            padding: "1rem 1.25rem",
+            opacity: 0.9,
+            border: "2px dashed #94a3b8",
+            borderRadius: 8,
+            backgroundColor: "rgba(148, 163, 184, 0.08)",
+            color: "#64748b",
+            fontSize: "0.875rem",
+        }, ...BlocklifyEditable, children: [_jsxs("strong", { style: { color: "#475569" }, children: ["Block type \"", block.type, "\" not found."] }), _jsx("p", { style: { margin: "0.5rem 0 0", lineHeight: 1.5 }, children: "Add a component for this block type to your project's blockMap (e.g. in your preview page) to render it here." })] }));
+}
+/**
+ * Renders blocks using your blockMap. Passes BlocklifyEditable (from BlocklifyEditable()) so components can spread it on their root for click-to-focus in the iframe.
+ * Styles are injected from editableCss (sent by admin via postMessage). No wrapper div – components apply {...BlocklifyEditable} themselves.
+ */
+export function BlocklifyPreviewRenderer({ blocks, blockMap, onBlockClick, spaceId, editableCss = PREVIEW_EDITABLE_CSS, blockMapForNested, }) {
+    const safeBlockMap = blockMap ?? {};
+    const nestedMap = blockMapForNested ?? safeBlockMap;
+    const resolveComponent = (type) => safeBlockMap[type] ??
+        (type.endsWith("_block") ? safeBlockMap[type.slice(0, -6)] : undefined) ??
+        UnknownBlockFallback;
+    return (_jsxs(_Fragment, { children: [_jsx("style", { id: "blocklify-preview-editable-styles", dangerouslySetInnerHTML: { __html: editableCss } }), blocks.map((block, i) => {
+                const Component = resolveComponent(block.type);
+                const key = block._uid ?? i;
+                const blocklifyEditable = BlocklifyEditable(block, i, onBlockClick, {
+                    spaceId: spaceId ?? undefined,
+                    blockId: block.id,
+                });
+                return (_jsx(Component, { block: block, BlocklifyEditable: blocklifyEditable, ...(nestedMap && { blockMap: nestedMap }) }, key));
+            })] }));
+}
+/**
+ * Preview connector for Blocklify. Use this on your frontend’s preview page (e.g. /preview).
+ * You only need to define your block components and a blockMap; this component handles:
+ * - Receiving draft content from the Blocklify admin via postMessage
+ * - Sending block clicks back to the editor
+ * - Empty state message and editable borders when embedded in the admin iframe
+ */
+export function BlocklifyPreview({ blockMap, blocksFieldName = "body", emptyMessage = "Waiting for content from editor…", className, }) {
+    const { blocks, isInIframe, onBlockClick, showEmptyMessage, spaceId, editableCss, peerFocusedBlocks } = useBlocklifyPreview(blocksFieldName);
+    const peerFocusCss = Object.entries(peerFocusedBlocks)
+        .map(([uid, { color }]) => `[data-blok-uid="${uid}"] { border-color: ${color} !important; box-shadow: 0 0 0 2px ${color} !important; }`)
+        .join("\n");
+    return (_jsxs("div", { className: className ?? "min-h-screen bg-surface text-text blocklify-preview-non-interactive", children: [_jsx("style", { children: `
+                .blocklify-preview-non-interactive a,
+                .blocklify-preview-non-interactive button {
+                    pointer-events: none;
+                    cursor: default;
+                }
+            ` }), peerFocusCss && (_jsx("style", { id: "blocklify-peer-focus-styles", children: peerFocusCss })), showEmptyMessage && (_jsx("div", { className: "flex min-h-screen items-center justify-center", children: _jsx("p", { className: "text-sm text-text-muted", children: emptyMessage }) })), _jsx(BlocklifyPreviewRenderer, { blocks: blocks, blockMap: blockMap, onBlockClick: isInIframe ? onBlockClick : undefined, spaceId: spaceId, editableCss: editableCss, blockMapForNested: blockMap })] }));
+}
+/** Default export so both "import BlocklifyPreview from '...'" and "import { BlocklifyPreview } from '...'" work. */
+export default BlocklifyPreview;

package/package.json

@@ -1,6 +1,63 @@
 {
-  "name": "@blocklify/preview",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@blocklify/preview",
+    "version": "0.1.0",
+    "description": "Blocklify frontend SDK: Content API client and live-preview React helpers for theme blocks.",
+    "license": "MIT",
+    "type": "module",
+    "sideEffects": false,
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./client": {
+            "types": "./dist/client.d.ts",
+            "import": "./dist/client.js"
+        },
+        "./preview": {
+            "types": "./dist/preview.d.ts",
+            "import": "./dist/preview.js"
+        }
+    },
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/BodhiMooij/blocklify.git",
+        "directory": "packages/preview"
+    },
+    "scripts": {
+        "build": "tsc -p tsconfig.json",
+        "prepublishOnly": "bun run build"
+    },
+    "peerDependencies": {
+        "react": ">=18",
+        "react-dom": ">=18"
+    },
+    "peerDependenciesMeta": {
+        "react": {
+            "optional": false
+        },
+        "react-dom": {
+            "optional": false
+        }
+    },
+    "devDependencies": {
+        "@types/react": "19.2.14",
+        "@types/react-dom": "19.2.3",
+        "typescript": "^5"
+    },
+    "keywords": [
+        "blocklify",
+        "cms",
+        "live-preview",
+        "headless"
+    ]
+}