@storyblok/live-preview 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Storyblok GmbH
+
+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

@@ -0,0 +1,79 @@
+<div align="center">
+
+![Storyblok ImagoType](https://raw.githubusercontent.com/storyblok/.github/refs/heads/main/profile/public/github-banner.png)
+
+<h1 align="center">@storyblok/live-preview</h1>
+ <p>
+   Lightweight helpers to enable Storyblok Live Preview and Visual Editor
+   updates across client-side and SSR frameworks.
+ </p>
+ <br />
+</div>
+
+<p align="center">
+  <a href="https://npmjs.com/package/@storyblok/live-preview">
+    <img src="https://img.shields.io/npm/v/@storyblok/live-preview/latest.svg?style=flat-square&color=8d60ff" alt="Storyblok Live Preview" />
+  </a>
+  <a href="https://npmjs.com/package/@storyblok/live-preview" rel="nofollow">
+    <img src="https://img.shields.io/npm/dt/@storyblok/live-preview.svg?style=appveyor&color=8d60ff" alt="npm">
+  </a>
+  <a href="https://storyblok.com/join-discord">
+   <img src="https://img.shields.io/discord/700316478792138842?label=Join%20Our%20Discord%20Community&style=appveyor&logo=discord&color=8d60ff">
+   </a>
+  <a href="https://twitter.com/intent/follow?screen_name=storyblok">
+    <img src="https://img.shields.io/badge/Follow-%40storyblok-8d60ff?style=appveyor&logo=twitter" alt="Follow @Storyblok" />
+  </a>
+</p>
+
+## Installation
+
+```bash
+npm install @storyblok/live-preview
+# or
+yarn add @storyblok/live-preview
+```
+
+## Usage
+
+### Live preview
+
+Covers the most common live preview use cases with minimal setup.
+
+```ts
+import { onStoryblokEditorEvent } from '@storyblok/live-preview';
+
+onStoryblokEditorEvent((story) => {
+  // update local state
+});
+```
+### Low-level Preview Bridge access
+For advanced use cases where full control is needed, the Preview Bridge can be accessed directly.
+```ts
+import { loadStoryblokBridge } from '@storyblok/live-preview';
+
+const bridge = await loadStoryblokBridge(bridgeOptions);
+
+bridge.on(['input', 'change', 'published'], (event) => {
+  // custom preview handling
+});
+```
+## Documentation
+
+This package is intentionally minimal.
+More helpers and examples will be added over time as usage expands.
+
+## Community
+
+For help, best practices, or discussions:
+
+* [Storyblok GitHub Discussions](https://github.com/storyblok/monoblok/discussions)
+* [Join the Storyblok Discord](https://storyblok.com/join-discord)
+
+## Support
+
+For bugs or feature requests, please
+[submit an issue](https://github.com/storyblok/monoblok/issues/new/choose).
+
+## License
+
+[MIT](/LICENSE)

package/dist/index.cjs

@@ -0,0 +1,201 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+//#region src/editable.ts
+function storyblokEditable(blok) {
+	const editable = blok?._editable;
+	if (!editable) return {};
+	if (!editable.startsWith("<!--#storyblok#") || !editable.endsWith("-->")) return {};
+	try {
+		const json = editable.slice(15, -3);
+		const options = JSON.parse(json);
+		return {
+			"data-blok-c": JSON.stringify(options),
+			"data-blok-uid": `${options.id}-${options.uid}`
+		};
+	} catch {
+		return {};
+	}
+}
+
+//#endregion
+//#region src/loadStoryblokBridge.ts
+let bridgePromise;
+let storedConfig;
+function configsAreEqual(config1, config2) {
+	return JSON.stringify(config1) === JSON.stringify(config2);
+}
+/**
+* Get or create a StoryblokBridge instance.
+*⚠️ The bridge is a singleton. Configuration is applied only on first load.
+* @param config Optional configuration for the StoryblokBridge.
+* @returns A promise that resolves to a StoryblokBridge instance.
+*/
+function loadStoryblokBridge(config) {
+	if (bridgePromise) {
+		if (config && !configsAreEqual(config, storedConfig)) throw new Error("[Storyblok] Preview Bridge already initialized with a different configuration. The bridge can only be created once per page and does not support runtime reconfiguration.");
+		return bridgePromise;
+	}
+	storedConfig = config;
+	bridgePromise = import("@storyblok/preview-bridge").then(({ default: StoryblokBridge }) => new StoryblokBridge(config)).catch((error) => {
+		bridgePromise = void 0;
+		storedConfig = void 0;
+		throw error;
+	});
+	return bridgePromise;
+}
+
+//#endregion
+//#region src/utils/isBrowser.ts
+function isBrowser() {
+	return typeof window !== "undefined";
+}
+
+//#endregion
+//#region src/utils/isInEditor.ts
+/**
+* Required query parameters that must be present in all Storyblok Visual Editor requests.
+*/
+const REQUIRED_STORYBLOK_PARAMS = [
+	"_storyblok",
+	"_storyblok_c",
+	"_storyblok_tk[space_id]"
+];
+/**
+* Validates whether a given URL is a legitimate request from the Storyblok Visual Editor.
+*
+* This function performs a multi-layered validation to ensure the request originates from
+* the Storyblok Visual Editor by checking for required query parameters and optionally
+* validating the space ID.
+*
+* @param url - The URL object to validate.
+* @param options - Optional validation configuration.
+* @param options.spaceId - If provided, validates that the request's space ID matches this value.
+*
+* @returns `true` if the URL contains all required Storyblok Visual Editor parameters
+*          and passes optional space ID validation; `false` otherwise.
+*
+* @example
+* ```typescript
+* const url = new URL('https://example.com/?_storyblok=123&_storyblok_c=456&_storyblok_tk[space_id]=789');
+*
+* // Basic validation
+* if (isInEditor(url)) {
+*   console.log('Valid Storyblok editor request');
+* }
+*
+* // Validation with space ID check
+* if (isInEditor(url, { spaceId: '789' })) {
+*   console.log('Valid request for specific space');
+* }
+* ```
+*/
+function isInEditor(url, options = {}) {
+	const params = url.searchParams;
+	if (!REQUIRED_STORYBLOK_PARAMS.every((param) => params.has(param))) return false;
+	if (options.spaceId && params.get("_storyblok_tk[space_id]") !== options.spaceId) return false;
+	return true;
+}
+
+//#endregion
+//#region src/utils/canUseStoryblokBridge.ts
+function canUseStoryblokBridge() {
+	if (!isBrowser()) return false;
+	return isInEditor(new URL(window.location.href));
+}
+
+//#endregion
+//#region src/onStoryblokEditorEvent.ts
+/**
+* Internal listener registry for Storyblok `input` events.
+* Each listener receives the updated story data from the Visual Editor.
+*/
+const inputListeners = /* @__PURE__ */ new Set();
+/**
+* Tracks whether the Storyblok Preview Bridge event listeners
+* have already been registered.
+*/
+let bridgeInitPromise;
+/**
+* Initializes the Storyblok Preview Bridge and attaches event listeners.
+*
+* This function ensures that the bridge is only initialized once per page.
+*
+* Registered events:
+* - `input` → Dispatches updated story data to all registered listeners.
+* - `change` → Forces a full page reload.
+* - `published` → Forces a full page reload.
+*
+* @param bridgeOptions Optional configuration for the Preview Bridge.
+*/
+async function initializeBridge(bridgeOptions) {
+	if (!canUseStoryblokBridge()) return;
+	if (bridgeInitPromise) return bridgeInitPromise;
+	bridgeInitPromise = (async () => {
+		(await loadStoryblokBridge(bridgeOptions)).on([
+			"input",
+			"change",
+			"published"
+		], (event) => {
+			if (!event) return;
+			if (event.action === "input" && event.story) {
+				for (const listener of inputListeners) listener(event.story);
+				return;
+			}
+			if (event.action === "change" || event.action === "published") window.location.reload();
+		});
+	})();
+	return bridgeInitPromise;
+}
+/**
+* Registers a callback for Storyblok Visual Editor live preview updates.
+*
+* This utility connects to the Storyblok Preview Bridge and listens
+* for Visual Editor events.
+*
+* Behavior:
+* - **input** → Calls the provided callback with the updated story data.
+* - **change** → Reloads the page.
+* - **published** → Reloads the page.
+*
+* Multiple listeners can be registered simultaneously. Each call returns
+* a cleanup function that removes the registered listener.
+*
+* @typeParam T - The Storyblok component schema type.
+*
+* @param callback
+* Callback executed when the Visual Editor sends an `input` event.
+*
+* @param bridgeOptions
+* Optional configuration for the Storyblok Preview Bridge.
+* This configuration is applied **only during the first initialization**.
+*
+* @returns
+* A cleanup function that removes the registered listener.
+*
+* @example
+* ```ts
+* const cleanup = await onStoryblokEditorEvent((story) => {
+*   console.log('Live updated story:', story)
+* })
+*
+* // later
+* cleanup()
+* ```
+*/
+async function onStoryblokEditorEvent(callback, bridgeOptions) {
+	await initializeBridge(bridgeOptions);
+	const listener = (story) => {
+		callback(story);
+	};
+	inputListeners.add(listener);
+	return () => {
+		inputListeners.delete(listener);
+	};
+}
+
+//#endregion
+exports.isInEditor = isInEditor;
+exports.loadStoryblokBridge = loadStoryblokBridge;
+exports.onStoryblokEditorEvent = onStoryblokEditorEvent;
+exports.storyblokEditable = storyblokEditable;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":[],"sources":["../src/editable.ts","../src/loadStoryblokBridge.ts","../src/utils/isBrowser.ts","../src/utils/isInEditor.ts","../src/utils/canUseStoryblokBridge.ts","../src/onStoryblokEditorEvent.ts"],"sourcesContent":["interface Blok {\n  _editable?: string;\n}\n\ninterface EditableOptions {\n  id: string;\n  uid: string;\n}\n\nexport default function storyblokEditable(blok?: Blok) {\n  const editable = blok?._editable;\n  if (!editable) {\n    return {};\n  }\n\n  const prefix = '<!--#storyblok#';\n  const suffix = '-->';\n\n  if (!editable.startsWith(prefix) || !editable.endsWith(suffix)) {\n    return {};\n  }\n\n  try {\n    const json = editable.slice(prefix.length, -suffix.length);\n    const options = JSON.parse(json) as EditableOptions;\n\n    return {\n      'data-blok-c': JSON.stringify(options),\n      'data-blok-uid': `${options.id}-${options.uid}`,\n    };\n  }\n  catch {\n    return {};\n  }\n}\n","import type StoryblokBridge from '@storyblok/preview-bridge';\nimport type { BridgeParams } from '@storyblok/preview-bridge';\n\nlet bridgePromise: Promise<StoryblokBridge> | undefined;\nlet storedConfig: BridgeParams | undefined;\nfunction configsAreEqual(config1: BridgeParams | undefined, config2: BridgeParams | undefined): boolean {\n  return JSON.stringify(config1) === JSON.stringify(config2);\n}\n\n/**\n * Get or create a StoryblokBridge instance.\n *⚠️ The bridge is a singleton. Configuration is applied only on first load.\n * @param config Optional configuration for the StoryblokBridge.\n * @returns A promise that resolves to a StoryblokBridge instance.\n */\nexport function loadStoryblokBridge(config?: BridgeParams) {\n  if (bridgePromise) {\n    if (config && !configsAreEqual(config, storedConfig)) {\n      throw new Error(\n        '[Storyblok] Preview Bridge already initialized with a different configuration. '\n        + 'The bridge can only be created once per page and does not support runtime reconfiguration.',\n      );\n    }\n    return bridgePromise;\n  }\n\n  storedConfig = config;\n\n  bridgePromise = import('@storyblok/preview-bridge')\n    .then(({ default: StoryblokBridge }) => new StoryblokBridge(config))\n    .catch((error) => {\n      bridgePromise = undefined;\n      storedConfig = undefined;\n      throw error;\n    });\n\n  return bridgePromise;\n}\n","export function isBrowser(): boolean {\n  return typeof window !== 'undefined';\n}\n","/**\n * Options for validating Storyblok Visual Editor requests.\n */\ninterface StoryblokValidationOptions {\n  /**\n   * Optional space ID to validate against the request.\n   * If provided, the request must match this space ID to be considered valid.\n   */\n  spaceId?: string;\n}\n\n/**\n * Required query parameters that must be present in all Storyblok Visual Editor requests.\n */\nconst REQUIRED_STORYBLOK_PARAMS = ['_storyblok', '_storyblok_c', '_storyblok_tk[space_id]'] as const;\n\n/**\n * Validates whether a given URL is a legitimate request from the Storyblok Visual Editor.\n *\n * This function performs a multi-layered validation to ensure the request originates from\n * the Storyblok Visual Editor by checking for required query parameters and optionally\n * validating the space ID.\n *\n * @param url - The URL object to validate.\n * @param options - Optional validation configuration.\n * @param options.spaceId - If provided, validates that the request's space ID matches this value.\n *\n * @returns `true` if the URL contains all required Storyblok Visual Editor parameters\n *          and passes optional space ID validation; `false` otherwise.\n *\n * @example\n * ```typescript\n * const url = new URL('https://example.com/?_storyblok=123&_storyblok_c=456&_storyblok_tk[space_id]=789');\n *\n * // Basic validation\n * if (isInEditor(url)) {\n *   console.log('Valid Storyblok editor request');\n * }\n *\n * // Validation with space ID check\n * if (isInEditor(url, { spaceId: '789' })) {\n *   console.log('Valid request for specific space');\n * }\n * ```\n */\nexport function isInEditor(\n  url: URL,\n  options: StoryblokValidationOptions = {},\n): boolean {\n  const params = url.searchParams;\n\n  // Early return: Check all required parameters exist\n  const hasRequiredParams = REQUIRED_STORYBLOK_PARAMS.every(param => params.has(param));\n\n  if (!hasRequiredParams) {\n    return false;\n  }\n\n  // Optional space ID validation\n  if (options.spaceId && params.get('_storyblok_tk[space_id]') !== options.spaceId) {\n    return false;\n  }\n\n  return true;\n}\n","import { isBrowser } from './isBrowser';\nimport { isInEditor } from './isInEditor';\n\nexport function canUseStoryblokBridge(): boolean {\n  if (!isBrowser()) {\n    return false;\n  }\n  return isInEditor(new URL(window.location.href));\n}\n","import type { BridgeParams } from '@storyblok/preview-bridge';\nimport type { ISbComponentType, ISbStoryData } from 'storyblok-js-client';\n\nimport { loadStoryblokBridge } from './loadStoryblokBridge';\nimport { canUseStoryblokBridge } from './utils/canUseStoryblokBridge';\n\n/**\n * Internal listener registry for Storyblok `input` events.\n * Each listener receives the updated story data from the Visual Editor.\n */\nconst inputListeners = new Set<(story: ISbStoryData) => void>();\n\n/**\n * Tracks whether the Storyblok Preview Bridge event listeners\n * have already been registered.\n */\nlet bridgeInitPromise: Promise<void> | undefined;\n\n/**\n * Initializes the Storyblok Preview Bridge and attaches event listeners.\n *\n * This function ensures that the bridge is only initialized once per page.\n *\n * Registered events:\n * - `input` → Dispatches updated story data to all registered listeners.\n * - `change` → Forces a full page reload.\n * - `published` → Forces a full page reload.\n *\n * @param bridgeOptions Optional configuration for the Preview Bridge.\n */\nasync function initializeBridge(bridgeOptions?: BridgeParams): Promise<void> {\n  if (!canUseStoryblokBridge()) {\n    return;\n  }\n\n  // If initialization already started, reuse it\n  if (bridgeInitPromise) {\n    return bridgeInitPromise;\n  }\n\n  bridgeInitPromise = (async () => {\n    const bridge = await loadStoryblokBridge(bridgeOptions);\n\n    bridge.on(['input', 'change', 'published'], (event) => {\n      if (!event) {\n        return;\n      }\n\n      if (event.action === 'input' && event.story) {\n        for (const listener of inputListeners) {\n          listener(event.story as ISbStoryData);\n        }\n        return;\n      }\n\n      if (event.action === 'change' || event.action === 'published') {\n        window.location.reload();\n      }\n    });\n  })();\n\n  return bridgeInitPromise;\n}\n\n/**\n * Registers a callback for Storyblok Visual Editor live preview updates.\n *\n * This utility connects to the Storyblok Preview Bridge and listens\n * for Visual Editor events.\n *\n * Behavior:\n * - **input** → Calls the provided callback with the updated story data.\n * - **change** → Reloads the page.\n * - **published** → Reloads the page.\n *\n * Multiple listeners can be registered simultaneously. Each call returns\n * a cleanup function that removes the registered listener.\n *\n * @typeParam T - The Storyblok component schema type.\n *\n * @param callback\n * Callback executed when the Visual Editor sends an `input` event.\n *\n * @param bridgeOptions\n * Optional configuration for the Storyblok Preview Bridge.\n * This configuration is applied **only during the first initialization**.\n *\n * @returns\n * A cleanup function that removes the registered listener.\n *\n * @example\n * ```ts\n * const cleanup = await onStoryblokEditorEvent((story) => {\n *   console.log('Live updated story:', story)\n * })\n *\n * // later\n * cleanup()\n * ```\n */\nexport async function onStoryblokEditorEvent<\n  T extends ISbComponentType<string> = ISbComponentType<string>,\n>(\n  callback: (story: ISbStoryData<T>) => void,\n  bridgeOptions?: BridgeParams,\n): Promise<() => void> {\n  await initializeBridge(bridgeOptions);\n\n  const listener = (story: ISbStoryData) => {\n    callback(story as ISbStoryData<T>);\n  };\n\n  inputListeners.add(listener);\n\n  return () => {\n    inputListeners.delete(listener);\n  };\n}\n"],"mappings":";;;AASA,SAAwB,kBAAkB,MAAa;CACrD,MAAM,WAAW,MAAM;AACvB,KAAI,CAAC,SACH,QAAO,EAAE;AAMX,KAAI,CAAC,SAAS,WAHC,kBAGiB,IAAI,CAAC,SAAS,SAF/B,MAE+C,CAC5D,QAAO,EAAE;AAGX,KAAI;EACF,MAAM,OAAO,SAAS,MAAM,IAAe,GAAe;EAC1D,MAAM,UAAU,KAAK,MAAM,KAAK;AAEhC,SAAO;GACL,eAAe,KAAK,UAAU,QAAQ;GACtC,iBAAiB,GAAG,QAAQ,GAAG,GAAG,QAAQ;GAC3C;SAEG;AACJ,SAAO,EAAE;;;;;;AC7Bb,IAAI;AACJ,IAAI;AACJ,SAAS,gBAAgB,SAAmC,SAA4C;AACtG,QAAO,KAAK,UAAU,QAAQ,KAAK,KAAK,UAAU,QAAQ;;;;;;;;AAS5D,SAAgB,oBAAoB,QAAuB;AACzD,KAAI,eAAe;AACjB,MAAI,UAAU,CAAC,gBAAgB,QAAQ,aAAa,CAClD,OAAM,IAAI,MACR,4KAED;AAEH,SAAO;;AAGT,gBAAe;AAEf,iBAAgB,OAAO,6BACpB,MAAM,EAAE,SAAS,sBAAsB,IAAI,gBAAgB,OAAO,CAAC,CACnE,OAAO,UAAU;AAChB,kBAAgB;AAChB,iBAAe;AACf,QAAM;GACN;AAEJ,QAAO;;;;;ACpCT,SAAgB,YAAqB;AACnC,QAAO,OAAO,WAAW;;;;;;;;ACa3B,MAAM,4BAA4B;CAAC;CAAc;CAAgB;CAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+B3F,SAAgB,WACd,KACA,UAAsC,EAAE,EAC/B;CACT,MAAM,SAAS,IAAI;AAKnB,KAAI,CAFsB,0BAA0B,OAAM,UAAS,OAAO,IAAI,MAAM,CAAC,CAGnF,QAAO;AAIT,KAAI,QAAQ,WAAW,OAAO,IAAI,0BAA0B,KAAK,QAAQ,QACvE,QAAO;AAGT,QAAO;;;;;AC5DT,SAAgB,wBAAiC;AAC/C,KAAI,CAAC,WAAW,CACd,QAAO;AAET,QAAO,WAAW,IAAI,IAAI,OAAO,SAAS,KAAK,CAAC;;;;;;;;;ACGlD,MAAM,iCAAiB,IAAI,KAAoC;;;;;AAM/D,IAAI;;;;;;;;;;;;;AAcJ,eAAe,iBAAiB,eAA6C;AAC3E,KAAI,CAAC,uBAAuB,CAC1B;AAIF,KAAI,kBACF,QAAO;AAGT,sBAAqB,YAAY;AAG/B,GAFe,MAAM,oBAAoB,cAAc,EAEhD,GAAG;GAAC;GAAS;GAAU;GAAY,GAAG,UAAU;AACrD,OAAI,CAAC,MACH;AAGF,OAAI,MAAM,WAAW,WAAW,MAAM,OAAO;AAC3C,SAAK,MAAM,YAAY,eACrB,UAAS,MAAM,MAAsB;AAEvC;;AAGF,OAAI,MAAM,WAAW,YAAY,MAAM,WAAW,YAChD,QAAO,SAAS,QAAQ;IAE1B;KACA;AAEJ,QAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCT,eAAsB,uBAGpB,UACA,eACqB;AACrB,OAAM,iBAAiB,cAAc;CAErC,MAAM,YAAY,UAAwB;AACxC,WAAS,MAAyB;;AAGpC,gBAAe,IAAI,SAAS;AAE5B,cAAa;AACX,iBAAe,OAAO,SAAS"}

package/dist/index.d.cts

@@ -0,0 +1,214 @@
+import StoryblokBridge, { BridgeParams, BridgeParams as BridgeParams$1 } from "@storyblok/preview-bridge";
+
+//#region src/editable.d.ts
+interface Blok {
+  _editable?: string;
+}
+declare function storyblokEditable(blok?: Blok): {
+  'data-blok-c'?: undefined;
+  'data-blok-uid'?: undefined;
+} | {
+  'data-blok-c': string;
+  'data-blok-uid': string;
+};
+//#endregion
+//#region src/loadStoryblokBridge.d.ts
+/**
+ * Get or create a StoryblokBridge instance.
+ *⚠️ The bridge is a singleton. Configuration is applied only on first load.
+ * @param config Optional configuration for the StoryblokBridge.
+ * @returns A promise that resolves to a StoryblokBridge instance.
+ */
+declare function loadStoryblokBridge(config?: BridgeParams$1): Promise<StoryblokBridge>;
+//#endregion
+//#region ../js-client/dist/index.d.mts
+interface ISbComponentType<T extends string> {
+  _uid?: string;
+  component?: T;
+  _editable?: string;
+}
+interface PreviewToken {
+  token: string;
+  timestamp: string;
+}
+interface LocalizedPath {
+  path: string;
+  name: string | null;
+  lang: string;
+  published: boolean;
+}
+interface ISbStoryData<Content = ISbComponentType<string> & {
+  [index: string]: any;
+}> extends ISbMultipleStoriesData {
+  alternates: ISbAlternateObject[];
+  breadcrumbs?: ISbLinkURLObject[];
+  content: Content;
+  created_at: string;
+  deleted_at?: string;
+  default_full_slug?: string | null;
+  default_root?: string;
+  disable_fe_editor?: boolean;
+  favourite_for_user_ids?: number[] | null;
+  first_published_at?: string | null;
+  full_slug: string;
+  group_id: string;
+  id: number;
+  imported_at?: string;
+  is_folder?: boolean;
+  is_startpage?: boolean;
+  lang: string;
+  last_author?: {
+    id: number;
+    userid: string;
+  };
+  last_author_id?: number;
+  localized_paths?: LocalizedPath[] | null;
+  meta_data: any;
+  name: string;
+  parent?: ISbStoryData;
+  parent_id: number | null;
+  path?: string;
+  pinned?: '1' | boolean;
+  position: number;
+  preview_token?: PreviewToken;
+  published?: boolean;
+  published_at: string | null;
+  release_id?: number | null;
+  scheduled_date?: string | null;
+  slug: string;
+  sort_by_date: string | null;
+  tag_list: string[];
+  translated_slugs?: {
+    path: string;
+    name: string | null;
+    lang: ISbStoryData['lang'];
+    published: boolean;
+  }[] | null;
+  unpublished_changes?: boolean;
+  updated_at?: string;
+  uuid: string;
+}
+interface ISbMultipleStoriesData {
+  by_ids?: string;
+  by_uuids?: string;
+  contain_component?: string;
+  excluding_ids?: string;
+  filter_query?: any;
+  folder_only?: boolean;
+  full_slug?: string;
+  in_release?: string;
+  in_trash?: boolean;
+  is_published?: boolean;
+  in_workflow_stages?: string;
+  page?: number;
+  pinned?: '1' | boolean;
+  search?: string;
+  sort_by?: string;
+  starts_with?: string;
+  story_only?: boolean;
+  text_search?: string;
+  with_parent?: number;
+  with_slug?: string;
+  with_tag?: string;
+}
+interface ISbAlternateObject {
+  id: number;
+  name: string;
+  slug: string;
+  published: boolean;
+  full_slug: string;
+  is_folder: boolean;
+  parent_id: number;
+}
+interface ISbLinkURLObject {
+  id: number;
+  name: string;
+  slug: string;
+  full_slug: string;
+  url: string;
+  uuid: string;
+}
+//#endregion
+//#region src/onStoryblokEditorEvent.d.ts
+/**
+ * Registers a callback for Storyblok Visual Editor live preview updates.
+ *
+ * This utility connects to the Storyblok Preview Bridge and listens
+ * for Visual Editor events.
+ *
+ * Behavior:
+ * - **input** → Calls the provided callback with the updated story data.
+ * - **change** → Reloads the page.
+ * - **published** → Reloads the page.
+ *
+ * Multiple listeners can be registered simultaneously. Each call returns
+ * a cleanup function that removes the registered listener.
+ *
+ * @typeParam T - The Storyblok component schema type.
+ *
+ * @param callback
+ * Callback executed when the Visual Editor sends an `input` event.
+ *
+ * @param bridgeOptions
+ * Optional configuration for the Storyblok Preview Bridge.
+ * This configuration is applied **only during the first initialization**.
+ *
+ * @returns
+ * A cleanup function that removes the registered listener.
+ *
+ * @example
+ * ```ts
+ * const cleanup = await onStoryblokEditorEvent((story) => {
+ *   console.log('Live updated story:', story)
+ * })
+ *
+ * // later
+ * cleanup()
+ * ```
+ */
+declare function onStoryblokEditorEvent<T extends ISbComponentType<string> = ISbComponentType<string>>(callback: (story: ISbStoryData<T>) => void, bridgeOptions?: BridgeParams$1): Promise<() => void>;
+//#endregion
+//#region src/utils/isInEditor.d.ts
+/**
+ * Options for validating Storyblok Visual Editor requests.
+ */
+interface StoryblokValidationOptions {
+  /**
+   * Optional space ID to validate against the request.
+   * If provided, the request must match this space ID to be considered valid.
+   */
+  spaceId?: string;
+}
+/**
+ * Validates whether a given URL is a legitimate request from the Storyblok Visual Editor.
+ *
+ * This function performs a multi-layered validation to ensure the request originates from
+ * the Storyblok Visual Editor by checking for required query parameters and optionally
+ * validating the space ID.
+ *
+ * @param url - The URL object to validate.
+ * @param options - Optional validation configuration.
+ * @param options.spaceId - If provided, validates that the request's space ID matches this value.
+ *
+ * @returns `true` if the URL contains all required Storyblok Visual Editor parameters
+ *          and passes optional space ID validation; `false` otherwise.
+ *
+ * @example
+ * ```typescript
+ * const url = new URL('https://example.com/?_storyblok=123&_storyblok_c=456&_storyblok_tk[space_id]=789');
+ *
+ * // Basic validation
+ * if (isInEditor(url)) {
+ *   console.log('Valid Storyblok editor request');
+ * }
+ *
+ * // Validation with space ID check
+ * if (isInEditor(url, { spaceId: '789' })) {
+ *   console.log('Valid request for specific space');
+ * }
+ * ```
+ */
+declare function isInEditor(url: URL, options?: StoryblokValidationOptions): boolean;
+//#endregion
+export { type BridgeParams, type ISbComponentType, type ISbStoryData, isInEditor, loadStoryblokBridge, onStoryblokEditorEvent, storyblokEditable };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -0,0 +1,214 @@
+import StoryblokBridge, { BridgeParams, BridgeParams as BridgeParams$1 } from "@storyblok/preview-bridge";
+
+//#region src/editable.d.ts
+interface Blok {
+  _editable?: string;
+}
+declare function storyblokEditable(blok?: Blok): {
+  'data-blok-c'?: undefined;
+  'data-blok-uid'?: undefined;
+} | {
+  'data-blok-c': string;
+  'data-blok-uid': string;
+};
+//#endregion
+//#region src/loadStoryblokBridge.d.ts
+/**
+ * Get or create a StoryblokBridge instance.
+ *⚠️ The bridge is a singleton. Configuration is applied only on first load.
+ * @param config Optional configuration for the StoryblokBridge.
+ * @returns A promise that resolves to a StoryblokBridge instance.
+ */
+declare function loadStoryblokBridge(config?: BridgeParams$1): Promise<StoryblokBridge>;
+//#endregion
+//#region ../js-client/dist/index.d.mts
+interface ISbComponentType<T extends string> {
+  _uid?: string;
+  component?: T;
+  _editable?: string;
+}
+interface PreviewToken {
+  token: string;
+  timestamp: string;
+}
+interface LocalizedPath {
+  path: string;
+  name: string | null;
+  lang: string;
+  published: boolean;
+}
+interface ISbStoryData<Content = ISbComponentType<string> & {
+  [index: string]: any;
+}> extends ISbMultipleStoriesData {
+  alternates: ISbAlternateObject[];
+  breadcrumbs?: ISbLinkURLObject[];
+  content: Content;
+  created_at: string;
+  deleted_at?: string;
+  default_full_slug?: string | null;
+  default_root?: string;
+  disable_fe_editor?: boolean;
+  favourite_for_user_ids?: number[] | null;
+  first_published_at?: string | null;
+  full_slug: string;
+  group_id: string;
+  id: number;
+  imported_at?: string;
+  is_folder?: boolean;
+  is_startpage?: boolean;
+  lang: string;
+  last_author?: {
+    id: number;
+    userid: string;
+  };
+  last_author_id?: number;
+  localized_paths?: LocalizedPath[] | null;
+  meta_data: any;
+  name: string;
+  parent?: ISbStoryData;
+  parent_id: number | null;
+  path?: string;
+  pinned?: '1' | boolean;
+  position: number;
+  preview_token?: PreviewToken;
+  published?: boolean;
+  published_at: string | null;
+  release_id?: number | null;
+  scheduled_date?: string | null;
+  slug: string;
+  sort_by_date: string | null;
+  tag_list: string[];
+  translated_slugs?: {
+    path: string;
+    name: string | null;
+    lang: ISbStoryData['lang'];
+    published: boolean;
+  }[] | null;
+  unpublished_changes?: boolean;
+  updated_at?: string;
+  uuid: string;
+}
+interface ISbMultipleStoriesData {
+  by_ids?: string;
+  by_uuids?: string;
+  contain_component?: string;
+  excluding_ids?: string;
+  filter_query?: any;
+  folder_only?: boolean;
+  full_slug?: string;
+  in_release?: string;
+  in_trash?: boolean;
+  is_published?: boolean;
+  in_workflow_stages?: string;
+  page?: number;
+  pinned?: '1' | boolean;
+  search?: string;
+  sort_by?: string;
+  starts_with?: string;
+  story_only?: boolean;
+  text_search?: string;
+  with_parent?: number;
+  with_slug?: string;
+  with_tag?: string;
+}
+interface ISbAlternateObject {
+  id: number;
+  name: string;
+  slug: string;
+  published: boolean;
+  full_slug: string;
+  is_folder: boolean;
+  parent_id: number;
+}
+interface ISbLinkURLObject {
+  id: number;
+  name: string;
+  slug: string;
+  full_slug: string;
+  url: string;
+  uuid: string;
+}
+//#endregion
+//#region src/onStoryblokEditorEvent.d.ts
+/**
+ * Registers a callback for Storyblok Visual Editor live preview updates.
+ *
+ * This utility connects to the Storyblok Preview Bridge and listens
+ * for Visual Editor events.
+ *
+ * Behavior:
+ * - **input** → Calls the provided callback with the updated story data.
+ * - **change** → Reloads the page.
+ * - **published** → Reloads the page.
+ *
+ * Multiple listeners can be registered simultaneously. Each call returns
+ * a cleanup function that removes the registered listener.
+ *
+ * @typeParam T - The Storyblok component schema type.
+ *
+ * @param callback
+ * Callback executed when the Visual Editor sends an `input` event.
+ *
+ * @param bridgeOptions
+ * Optional configuration for the Storyblok Preview Bridge.
+ * This configuration is applied **only during the first initialization**.
+ *
+ * @returns
+ * A cleanup function that removes the registered listener.
+ *
+ * @example
+ * ```ts
+ * const cleanup = await onStoryblokEditorEvent((story) => {
+ *   console.log('Live updated story:', story)
+ * })
+ *
+ * // later
+ * cleanup()
+ * ```
+ */
+declare function onStoryblokEditorEvent<T extends ISbComponentType<string> = ISbComponentType<string>>(callback: (story: ISbStoryData<T>) => void, bridgeOptions?: BridgeParams$1): Promise<() => void>;
+//#endregion
+//#region src/utils/isInEditor.d.ts
+/**
+ * Options for validating Storyblok Visual Editor requests.
+ */
+interface StoryblokValidationOptions {
+  /**
+   * Optional space ID to validate against the request.
+   * If provided, the request must match this space ID to be considered valid.
+   */
+  spaceId?: string;
+}
+/**
+ * Validates whether a given URL is a legitimate request from the Storyblok Visual Editor.
+ *
+ * This function performs a multi-layered validation to ensure the request originates from
+ * the Storyblok Visual Editor by checking for required query parameters and optionally
+ * validating the space ID.
+ *
+ * @param url - The URL object to validate.
+ * @param options - Optional validation configuration.
+ * @param options.spaceId - If provided, validates that the request's space ID matches this value.
+ *
+ * @returns `true` if the URL contains all required Storyblok Visual Editor parameters
+ *          and passes optional space ID validation; `false` otherwise.
+ *
+ * @example
+ * ```typescript
+ * const url = new URL('https://example.com/?_storyblok=123&_storyblok_c=456&_storyblok_tk[space_id]=789');
+ *
+ * // Basic validation
+ * if (isInEditor(url)) {
+ *   console.log('Valid Storyblok editor request');
+ * }
+ *
+ * // Validation with space ID check
+ * if (isInEditor(url, { spaceId: '789' })) {
+ *   console.log('Valid request for specific space');
+ * }
+ * ```
+ */
+declare function isInEditor(url: URL, options?: StoryblokValidationOptions): boolean;
+//#endregion
+export { type BridgeParams, type ISbComponentType, type ISbStoryData, isInEditor, loadStoryblokBridge, onStoryblokEditorEvent, storyblokEditable };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,196 @@
+//#region src/editable.ts
+function storyblokEditable(blok) {
+	const editable = blok?._editable;
+	if (!editable) return {};
+	if (!editable.startsWith("<!--#storyblok#") || !editable.endsWith("-->")) return {};
+	try {
+		const json = editable.slice(15, -3);
+		const options = JSON.parse(json);
+		return {
+			"data-blok-c": JSON.stringify(options),
+			"data-blok-uid": `${options.id}-${options.uid}`
+		};
+	} catch {
+		return {};
+	}
+}
+
+//#endregion
+//#region src/loadStoryblokBridge.ts
+let bridgePromise;
+let storedConfig;
+function configsAreEqual(config1, config2) {
+	return JSON.stringify(config1) === JSON.stringify(config2);
+}
+/**
+* Get or create a StoryblokBridge instance.
+*⚠️ The bridge is a singleton. Configuration is applied only on first load.
+* @param config Optional configuration for the StoryblokBridge.
+* @returns A promise that resolves to a StoryblokBridge instance.
+*/
+function loadStoryblokBridge(config) {
+	if (bridgePromise) {
+		if (config && !configsAreEqual(config, storedConfig)) throw new Error("[Storyblok] Preview Bridge already initialized with a different configuration. The bridge can only be created once per page and does not support runtime reconfiguration.");
+		return bridgePromise;
+	}
+	storedConfig = config;
+	bridgePromise = import("@storyblok/preview-bridge").then(({ default: StoryblokBridge }) => new StoryblokBridge(config)).catch((error) => {
+		bridgePromise = void 0;
+		storedConfig = void 0;
+		throw error;
+	});
+	return bridgePromise;
+}
+
+//#endregion
+//#region src/utils/isBrowser.ts
+function isBrowser() {
+	return typeof window !== "undefined";
+}
+
+//#endregion
+//#region src/utils/isInEditor.ts
+/**
+* Required query parameters that must be present in all Storyblok Visual Editor requests.
+*/
+const REQUIRED_STORYBLOK_PARAMS = [
+	"_storyblok",
+	"_storyblok_c",
+	"_storyblok_tk[space_id]"
+];
+/**
+* Validates whether a given URL is a legitimate request from the Storyblok Visual Editor.
+*
+* This function performs a multi-layered validation to ensure the request originates from
+* the Storyblok Visual Editor by checking for required query parameters and optionally
+* validating the space ID.
+*
+* @param url - The URL object to validate.
+* @param options - Optional validation configuration.
+* @param options.spaceId - If provided, validates that the request's space ID matches this value.
+*
+* @returns `true` if the URL contains all required Storyblok Visual Editor parameters
+*          and passes optional space ID validation; `false` otherwise.
+*
+* @example
+* ```typescript
+* const url = new URL('https://example.com/?_storyblok=123&_storyblok_c=456&_storyblok_tk[space_id]=789');
+*
+* // Basic validation
+* if (isInEditor(url)) {
+*   console.log('Valid Storyblok editor request');
+* }
+*
+* // Validation with space ID check
+* if (isInEditor(url, { spaceId: '789' })) {
+*   console.log('Valid request for specific space');
+* }
+* ```
+*/
+function isInEditor(url, options = {}) {
+	const params = url.searchParams;
+	if (!REQUIRED_STORYBLOK_PARAMS.every((param) => params.has(param))) return false;
+	if (options.spaceId && params.get("_storyblok_tk[space_id]") !== options.spaceId) return false;
+	return true;
+}
+
+//#endregion
+//#region src/utils/canUseStoryblokBridge.ts
+function canUseStoryblokBridge() {
+	if (!isBrowser()) return false;
+	return isInEditor(new URL(window.location.href));
+}
+
+//#endregion
+//#region src/onStoryblokEditorEvent.ts
+/**
+* Internal listener registry for Storyblok `input` events.
+* Each listener receives the updated story data from the Visual Editor.
+*/
+const inputListeners = /* @__PURE__ */ new Set();
+/**
+* Tracks whether the Storyblok Preview Bridge event listeners
+* have already been registered.
+*/
+let bridgeInitPromise;
+/**
+* Initializes the Storyblok Preview Bridge and attaches event listeners.
+*
+* This function ensures that the bridge is only initialized once per page.
+*
+* Registered events:
+* - `input` → Dispatches updated story data to all registered listeners.
+* - `change` → Forces a full page reload.
+* - `published` → Forces a full page reload.
+*
+* @param bridgeOptions Optional configuration for the Preview Bridge.
+*/
+async function initializeBridge(bridgeOptions) {
+	if (!canUseStoryblokBridge()) return;
+	if (bridgeInitPromise) return bridgeInitPromise;
+	bridgeInitPromise = (async () => {
+		(await loadStoryblokBridge(bridgeOptions)).on([
+			"input",
+			"change",
+			"published"
+		], (event) => {
+			if (!event) return;
+			if (event.action === "input" && event.story) {
+				for (const listener of inputListeners) listener(event.story);
+				return;
+			}
+			if (event.action === "change" || event.action === "published") window.location.reload();
+		});
+	})();
+	return bridgeInitPromise;
+}
+/**
+* Registers a callback for Storyblok Visual Editor live preview updates.
+*
+* This utility connects to the Storyblok Preview Bridge and listens
+* for Visual Editor events.
+*
+* Behavior:
+* - **input** → Calls the provided callback with the updated story data.
+* - **change** → Reloads the page.
+* - **published** → Reloads the page.
+*
+* Multiple listeners can be registered simultaneously. Each call returns
+* a cleanup function that removes the registered listener.
+*
+* @typeParam T - The Storyblok component schema type.
+*
+* @param callback
+* Callback executed when the Visual Editor sends an `input` event.
+*
+* @param bridgeOptions
+* Optional configuration for the Storyblok Preview Bridge.
+* This configuration is applied **only during the first initialization**.
+*
+* @returns
+* A cleanup function that removes the registered listener.
+*
+* @example
+* ```ts
+* const cleanup = await onStoryblokEditorEvent((story) => {
+*   console.log('Live updated story:', story)
+* })
+*
+* // later
+* cleanup()
+* ```
+*/
+async function onStoryblokEditorEvent(callback, bridgeOptions) {
+	await initializeBridge(bridgeOptions);
+	const listener = (story) => {
+		callback(story);
+	};
+	inputListeners.add(listener);
+	return () => {
+		inputListeners.delete(listener);
+	};
+}
+
+//#endregion
+export { isInEditor, loadStoryblokBridge, onStoryblokEditorEvent, storyblokEditable };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/editable.ts","../src/loadStoryblokBridge.ts","../src/utils/isBrowser.ts","../src/utils/isInEditor.ts","../src/utils/canUseStoryblokBridge.ts","../src/onStoryblokEditorEvent.ts"],"sourcesContent":["interface Blok {\n  _editable?: string;\n}\n\ninterface EditableOptions {\n  id: string;\n  uid: string;\n}\n\nexport default function storyblokEditable(blok?: Blok) {\n  const editable = blok?._editable;\n  if (!editable) {\n    return {};\n  }\n\n  const prefix = '<!--#storyblok#';\n  const suffix = '-->';\n\n  if (!editable.startsWith(prefix) || !editable.endsWith(suffix)) {\n    return {};\n  }\n\n  try {\n    const json = editable.slice(prefix.length, -suffix.length);\n    const options = JSON.parse(json) as EditableOptions;\n\n    return {\n      'data-blok-c': JSON.stringify(options),\n      'data-blok-uid': `${options.id}-${options.uid}`,\n    };\n  }\n  catch {\n    return {};\n  }\n}\n","import type StoryblokBridge from '@storyblok/preview-bridge';\nimport type { BridgeParams } from '@storyblok/preview-bridge';\n\nlet bridgePromise: Promise<StoryblokBridge> | undefined;\nlet storedConfig: BridgeParams | undefined;\nfunction configsAreEqual(config1: BridgeParams | undefined, config2: BridgeParams | undefined): boolean {\n  return JSON.stringify(config1) === JSON.stringify(config2);\n}\n\n/**\n * Get or create a StoryblokBridge instance.\n *⚠️ The bridge is a singleton. Configuration is applied only on first load.\n * @param config Optional configuration for the StoryblokBridge.\n * @returns A promise that resolves to a StoryblokBridge instance.\n */\nexport function loadStoryblokBridge(config?: BridgeParams) {\n  if (bridgePromise) {\n    if (config && !configsAreEqual(config, storedConfig)) {\n      throw new Error(\n        '[Storyblok] Preview Bridge already initialized with a different configuration. '\n        + 'The bridge can only be created once per page and does not support runtime reconfiguration.',\n      );\n    }\n    return bridgePromise;\n  }\n\n  storedConfig = config;\n\n  bridgePromise = import('@storyblok/preview-bridge')\n    .then(({ default: StoryblokBridge }) => new StoryblokBridge(config))\n    .catch((error) => {\n      bridgePromise = undefined;\n      storedConfig = undefined;\n      throw error;\n    });\n\n  return bridgePromise;\n}\n","export function isBrowser(): boolean {\n  return typeof window !== 'undefined';\n}\n","/**\n * Options for validating Storyblok Visual Editor requests.\n */\ninterface StoryblokValidationOptions {\n  /**\n   * Optional space ID to validate against the request.\n   * If provided, the request must match this space ID to be considered valid.\n   */\n  spaceId?: string;\n}\n\n/**\n * Required query parameters that must be present in all Storyblok Visual Editor requests.\n */\nconst REQUIRED_STORYBLOK_PARAMS = ['_storyblok', '_storyblok_c', '_storyblok_tk[space_id]'] as const;\n\n/**\n * Validates whether a given URL is a legitimate request from the Storyblok Visual Editor.\n *\n * This function performs a multi-layered validation to ensure the request originates from\n * the Storyblok Visual Editor by checking for required query parameters and optionally\n * validating the space ID.\n *\n * @param url - The URL object to validate.\n * @param options - Optional validation configuration.\n * @param options.spaceId - If provided, validates that the request's space ID matches this value.\n *\n * @returns `true` if the URL contains all required Storyblok Visual Editor parameters\n *          and passes optional space ID validation; `false` otherwise.\n *\n * @example\n * ```typescript\n * const url = new URL('https://example.com/?_storyblok=123&_storyblok_c=456&_storyblok_tk[space_id]=789');\n *\n * // Basic validation\n * if (isInEditor(url)) {\n *   console.log('Valid Storyblok editor request');\n * }\n *\n * // Validation with space ID check\n * if (isInEditor(url, { spaceId: '789' })) {\n *   console.log('Valid request for specific space');\n * }\n * ```\n */\nexport function isInEditor(\n  url: URL,\n  options: StoryblokValidationOptions = {},\n): boolean {\n  const params = url.searchParams;\n\n  // Early return: Check all required parameters exist\n  const hasRequiredParams = REQUIRED_STORYBLOK_PARAMS.every(param => params.has(param));\n\n  if (!hasRequiredParams) {\n    return false;\n  }\n\n  // Optional space ID validation\n  if (options.spaceId && params.get('_storyblok_tk[space_id]') !== options.spaceId) {\n    return false;\n  }\n\n  return true;\n}\n","import { isBrowser } from './isBrowser';\nimport { isInEditor } from './isInEditor';\n\nexport function canUseStoryblokBridge(): boolean {\n  if (!isBrowser()) {\n    return false;\n  }\n  return isInEditor(new URL(window.location.href));\n}\n","import type { BridgeParams } from '@storyblok/preview-bridge';\nimport type { ISbComponentType, ISbStoryData } from 'storyblok-js-client';\n\nimport { loadStoryblokBridge } from './loadStoryblokBridge';\nimport { canUseStoryblokBridge } from './utils/canUseStoryblokBridge';\n\n/**\n * Internal listener registry for Storyblok `input` events.\n * Each listener receives the updated story data from the Visual Editor.\n */\nconst inputListeners = new Set<(story: ISbStoryData) => void>();\n\n/**\n * Tracks whether the Storyblok Preview Bridge event listeners\n * have already been registered.\n */\nlet bridgeInitPromise: Promise<void> | undefined;\n\n/**\n * Initializes the Storyblok Preview Bridge and attaches event listeners.\n *\n * This function ensures that the bridge is only initialized once per page.\n *\n * Registered events:\n * - `input` → Dispatches updated story data to all registered listeners.\n * - `change` → Forces a full page reload.\n * - `published` → Forces a full page reload.\n *\n * @param bridgeOptions Optional configuration for the Preview Bridge.\n */\nasync function initializeBridge(bridgeOptions?: BridgeParams): Promise<void> {\n  if (!canUseStoryblokBridge()) {\n    return;\n  }\n\n  // If initialization already started, reuse it\n  if (bridgeInitPromise) {\n    return bridgeInitPromise;\n  }\n\n  bridgeInitPromise = (async () => {\n    const bridge = await loadStoryblokBridge(bridgeOptions);\n\n    bridge.on(['input', 'change', 'published'], (event) => {\n      if (!event) {\n        return;\n      }\n\n      if (event.action === 'input' && event.story) {\n        for (const listener of inputListeners) {\n          listener(event.story as ISbStoryData);\n        }\n        return;\n      }\n\n      if (event.action === 'change' || event.action === 'published') {\n        window.location.reload();\n      }\n    });\n  })();\n\n  return bridgeInitPromise;\n}\n\n/**\n * Registers a callback for Storyblok Visual Editor live preview updates.\n *\n * This utility connects to the Storyblok Preview Bridge and listens\n * for Visual Editor events.\n *\n * Behavior:\n * - **input** → Calls the provided callback with the updated story data.\n * - **change** → Reloads the page.\n * - **published** → Reloads the page.\n *\n * Multiple listeners can be registered simultaneously. Each call returns\n * a cleanup function that removes the registered listener.\n *\n * @typeParam T - The Storyblok component schema type.\n *\n * @param callback\n * Callback executed when the Visual Editor sends an `input` event.\n *\n * @param bridgeOptions\n * Optional configuration for the Storyblok Preview Bridge.\n * This configuration is applied **only during the first initialization**.\n *\n * @returns\n * A cleanup function that removes the registered listener.\n *\n * @example\n * ```ts\n * const cleanup = await onStoryblokEditorEvent((story) => {\n *   console.log('Live updated story:', story)\n * })\n *\n * // later\n * cleanup()\n * ```\n */\nexport async function onStoryblokEditorEvent<\n  T extends ISbComponentType<string> = ISbComponentType<string>,\n>(\n  callback: (story: ISbStoryData<T>) => void,\n  bridgeOptions?: BridgeParams,\n): Promise<() => void> {\n  await initializeBridge(bridgeOptions);\n\n  const listener = (story: ISbStoryData) => {\n    callback(story as ISbStoryData<T>);\n  };\n\n  inputListeners.add(listener);\n\n  return () => {\n    inputListeners.delete(listener);\n  };\n}\n"],"mappings":";AASA,SAAwB,kBAAkB,MAAa;CACrD,MAAM,WAAW,MAAM;AACvB,KAAI,CAAC,SACH,QAAO,EAAE;AAMX,KAAI,CAAC,SAAS,WAHC,kBAGiB,IAAI,CAAC,SAAS,SAF/B,MAE+C,CAC5D,QAAO,EAAE;AAGX,KAAI;EACF,MAAM,OAAO,SAAS,MAAM,IAAe,GAAe;EAC1D,MAAM,UAAU,KAAK,MAAM,KAAK;AAEhC,SAAO;GACL,eAAe,KAAK,UAAU,QAAQ;GACtC,iBAAiB,GAAG,QAAQ,GAAG,GAAG,QAAQ;GAC3C;SAEG;AACJ,SAAO,EAAE;;;;;;AC7Bb,IAAI;AACJ,IAAI;AACJ,SAAS,gBAAgB,SAAmC,SAA4C;AACtG,QAAO,KAAK,UAAU,QAAQ,KAAK,KAAK,UAAU,QAAQ;;;;;;;;AAS5D,SAAgB,oBAAoB,QAAuB;AACzD,KAAI,eAAe;AACjB,MAAI,UAAU,CAAC,gBAAgB,QAAQ,aAAa,CAClD,OAAM,IAAI,MACR,4KAED;AAEH,SAAO;;AAGT,gBAAe;AAEf,iBAAgB,OAAO,6BACpB,MAAM,EAAE,SAAS,sBAAsB,IAAI,gBAAgB,OAAO,CAAC,CACnE,OAAO,UAAU;AAChB,kBAAgB;AAChB,iBAAe;AACf,QAAM;GACN;AAEJ,QAAO;;;;;ACpCT,SAAgB,YAAqB;AACnC,QAAO,OAAO,WAAW;;;;;;;;ACa3B,MAAM,4BAA4B;CAAC;CAAc;CAAgB;CAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+B3F,SAAgB,WACd,KACA,UAAsC,EAAE,EAC/B;CACT,MAAM,SAAS,IAAI;AAKnB,KAAI,CAFsB,0BAA0B,OAAM,UAAS,OAAO,IAAI,MAAM,CAAC,CAGnF,QAAO;AAIT,KAAI,QAAQ,WAAW,OAAO,IAAI,0BAA0B,KAAK,QAAQ,QACvE,QAAO;AAGT,QAAO;;;;;AC5DT,SAAgB,wBAAiC;AAC/C,KAAI,CAAC,WAAW,CACd,QAAO;AAET,QAAO,WAAW,IAAI,IAAI,OAAO,SAAS,KAAK,CAAC;;;;;;;;;ACGlD,MAAM,iCAAiB,IAAI,KAAoC;;;;;AAM/D,IAAI;;;;;;;;;;;;;AAcJ,eAAe,iBAAiB,eAA6C;AAC3E,KAAI,CAAC,uBAAuB,CAC1B;AAIF,KAAI,kBACF,QAAO;AAGT,sBAAqB,YAAY;AAG/B,GAFe,MAAM,oBAAoB,cAAc,EAEhD,GAAG;GAAC;GAAS;GAAU;GAAY,GAAG,UAAU;AACrD,OAAI,CAAC,MACH;AAGF,OAAI,MAAM,WAAW,WAAW,MAAM,OAAO;AAC3C,SAAK,MAAM,YAAY,eACrB,UAAS,MAAM,MAAsB;AAEvC;;AAGF,OAAI,MAAM,WAAW,YAAY,MAAM,WAAW,YAChD,QAAO,SAAS,QAAQ;IAE1B;KACA;AAEJ,QAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCT,eAAsB,uBAGpB,UACA,eACqB;AACrB,OAAM,iBAAiB,cAAc;CAErC,MAAM,YAAY,UAAwB;AACxC,WAAS,MAAyB;;AAGpC,gBAAe,IAAI,SAAS;AAE5B,cAAa;AACX,iBAAe,OAAO,SAAS"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@storyblok/live-preview",
+  "type": "module",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Official Live Preview integration for the Storyblok Headless CMS",
+  "author": "Storyblok",
+  "license": "MIT",
+  "homepage": "https://github.com/storyblok/monoblok/tree/main/packages/live-preview#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/storyblok/monoblok.git",
+    "directory": "packages/live-preview"
+  },
+  "bugs": {
+    "url": "https://github.com/storyblok/monoblok/issues"
+  },
+  "keywords": [
+    "live-preview",
+    "storyblok"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@storyblok/preview-bridge": "^2.1.6"
+  },
+  "devDependencies": {
+    "@types/node": "^24.11.0",
+    "bumpp": "^10.4.1",
+    "eslint": "^9.39.2",
+    "tsdown": "^0.20.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18",
+    "@storyblok/eslint-config": "0.4.2",
+    "storyblok-js-client": "7.2.4"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc --noEmit"
+  }
+}