@keypuncherlabs/live-preview 1.1.0

package/README.md

@@ -0,0 +1,112 @@
+# @keypuncherlabs/live-preview
+
+Push **live, validated CSS** from a parent application into an embedded preview
+(such as a Storybook hosted on a different subdomain or origin) over
+`window.postMessage`.
+
+It is framework-agnostic, has no runtime dependencies, and is built
+security-first — previews are often hosted on origins you do not fully control,
+so every message is gated by an origin allowlist and the CSS is validated at
+every hop before it is injected.
+
+## Why
+
+When the preview lives on a different origin, you cannot reach into its DOM
+directly. This library gives you a tiny, safe channel:
+
+- **Sender** (parent app): validate CSS, then post it to a specific iframe and
+  origin.
+- **Receiver** (embedded app): accept CSS only from allowlisted origins,
+  re-validate it, and inject it into a single `<style>` element via
+  `textContent` (never `innerHTML`).
+- **Relay** (nested-iframe host, e.g. a Storybook *manager*): forward CSS one hop
+  down to the real preview frame, since a grandparent window can only post to its
+  direct child.
+
+Message type on the wire: `live-preview-css`. Receivers/relays announce
+readiness with `live-preview-ready` so the parent can (re)send without racing
+startup.
+
+## Security model
+
+- **Origin allowlist is required.** The receiver and relay reject any message
+  whose `event.origin` is not listed. Pass `['*']` only to deliberately opt out
+  (e.g. local development).
+- **Explicit target origin.** The sender never posts to `'*'`; it always
+  addresses a concrete origin so a swapped/navigated iframe cannot receive CSS.
+- **CSS is validated at every hop.** `validateCss` rejects (does not "clean")
+  anything dangerous: `<style>`/`<script>`/HTML markup (breakout attempts),
+  `expression()`, `javascript:`/`vbscript:`, `-moz-binding`, `behavior:`, control
+  characters, `@import` (off by default), non-`https`/`data` `url()` schemes (off
+  by default), and oversized payloads.
+- **Safe injection.** CSS is written with `textContent` into one reused `<style>`
+  node, so markup cannot be injected and the DOM does not grow.
+
+## Usage
+
+### Parent app (sender)
+
+```ts
+import { createLivePreviewSender } from '@keypuncherlabs/live-preview';
+
+const iframe = document.querySelector('iframe')!;
+const sender = createLivePreviewSender({
+  targetWindow: iframe.contentWindow!,
+  targetOrigin: new URL(iframe.src).origin, // never '*'
+});
+
+// Resend whenever the preview reports it is ready.
+window.addEventListener('message', (e) => {
+  if (e.origin === new URL(iframe.src).origin && e.data?.type === 'live-preview-ready') {
+    sender.sendCss(currentCss);
+  }
+});
+
+const result = sender.sendCss(':root { --color-primary: #06f; }');
+if (!result.valid) console.warn(result.errors);
+```
+
+### Embedded app (receiver)
+
+```ts
+import { startLivePreviewReceiver } from '@keypuncherlabs/live-preview';
+
+startLivePreviewReceiver({
+  allowedOrigins: ['https://app.example.com'],
+  styleId: 'live-preview-styles',
+  onReject: (reason) => console.warn(reason),
+});
+```
+
+### Nested iframe host (relay)
+
+```ts
+import { createLivePreviewRelay } from '@keypuncherlabs/live-preview';
+
+createLivePreviewRelay({
+  allowedOrigins: ['https://app.example.com'],
+  getTargetWindow: () =>
+    (document.getElementById('preview-iframe') as HTMLIFrameElement | null)?.contentWindow,
+  targetOrigin: window.location.origin,
+});
+```
+
+## Validation options
+
+`validateCss(input, options)` and the `validation` option on the sender/receiver/
+relay accept:
+
+- `maxLength` — size cap (default 100,000 chars).
+- `allowAtImport` — permit `@import` (default `false`).
+- `allowExternalUrls` — permit any `url()` scheme except `javascript:`/`vbscript:`/
+  `file:` (default `false`).
+- `allowedUrlSchemes` — schemes allowed when `allowExternalUrls` is off (default
+  `['https', 'data']`; relative URLs and fragments always pass).
+
+## Building
+
+Run `nx build live-preview` to build the library.
+
+## Running unit tests
+
+Run `nx test live-preview` to execute the unit tests via [Jest](https://jestjs.io).

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@keypuncherlabs/live-preview",
+  "version": "1.1.0",
+  "type": "commonjs",
+  "description": "Send validated CSS into an embedded preview (e.g. a Storybook on another origin) over postMessage. Framework-agnostic, dependency-free, security-first.",
+  "keywords": [
+    "live-preview",
+    "postmessage",
+    "iframe",
+    "css-injection",
+    "storybook",
+    "cross-origin",
+    "design-tokens"
+  ],
+  "license": "MIT",
+  "sideEffects": false,
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,5 @@
+export * from './lib/protocol';
+export * from './lib/validate-css';
+export * from './lib/sender';
+export * from './lib/receiver';
+export * from './lib/relay';

package/src/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./lib/protocol"), exports);
+tslib_1.__exportStar(require("./lib/validate-css"), exports);
+tslib_1.__exportStar(require("./lib/sender"), exports);
+tslib_1.__exportStar(require("./lib/receiver"), exports);
+tslib_1.__exportStar(require("./lib/relay"), exports);
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../libs/public/keypuncherlabs/live-preview/src/index.ts"],"names":[],"mappings":";;;AAAA,yDAA+B;AAC/B,6DAAmC;AACnC,uDAA6B;AAC7B,yDAA+B;AAC/B,sDAA4B"}

package/src/lib/protocol.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Wire protocol shared by the sender (parent app), the receiver (embedded app),
+ * and the relay (a nested-iframe host such as a Storybook manager).
+ *
+ * Messages travel over `window.postMessage`, so they must be plain,
+ * structured-clonable objects. The `type` discriminator is namespaced with the
+ * `live-preview-` prefix so it is easy to identify and unlikely to collide with
+ * other postMessage traffic on the same window.
+ */
+/** Message type for pushing a CSS payload into an embedded preview. */
+export declare const LIVE_PREVIEW_CSS_TYPE: "live-preview-css";
+/** Message type a receiver/relay emits upward once it is ready to apply CSS. */
+export declare const LIVE_PREVIEW_READY_TYPE: "live-preview-ready";
+/** Carries a CSS string from a parent app to an embedded preview. */
+export interface LivePreviewCssMessage {
+    type: typeof LIVE_PREVIEW_CSS_TYPE;
+    css: string;
+}
+/**
+ * Announces that a receiver (or relay) has attached its listener. A parent app
+ * can wait for this before sending so the initial CSS is not lost to a startup
+ * race.
+ */
+export interface LivePreviewReadyMessage {
+    type: typeof LIVE_PREVIEW_READY_TYPE;
+}
+export type LivePreviewMessage = LivePreviewCssMessage | LivePreviewReadyMessage;
+/** Narrows arbitrary `postMessage` data to a CSS message. */
+export declare function isCssMessage(value: unknown): value is LivePreviewCssMessage;
+/** Narrows arbitrary `postMessage` data to a ready message. */
+export declare function isReadyMessage(value: unknown): value is LivePreviewReadyMessage;

package/src/lib/protocol.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * Wire protocol shared by the sender (parent app), the receiver (embedded app),
+ * and the relay (a nested-iframe host such as a Storybook manager).
+ *
+ * Messages travel over `window.postMessage`, so they must be plain,
+ * structured-clonable objects. The `type` discriminator is namespaced with the
+ * `live-preview-` prefix so it is easy to identify and unlikely to collide with
+ * other postMessage traffic on the same window.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIVE_PREVIEW_READY_TYPE = exports.LIVE_PREVIEW_CSS_TYPE = void 0;
+exports.isCssMessage = isCssMessage;
+exports.isReadyMessage = isReadyMessage;
+/** Message type for pushing a CSS payload into an embedded preview. */
+exports.LIVE_PREVIEW_CSS_TYPE = 'live-preview-css';
+/** Message type a receiver/relay emits upward once it is ready to apply CSS. */
+exports.LIVE_PREVIEW_READY_TYPE = 'live-preview-ready';
+/** Narrows arbitrary `postMessage` data to a CSS message. */
+function isCssMessage(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.type === exports.LIVE_PREVIEW_CSS_TYPE &&
+        typeof value.css === 'string');
+}
+/** Narrows arbitrary `postMessage` data to a ready message. */
+function isReadyMessage(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.type === exports.LIVE_PREVIEW_READY_TYPE);
+}
+//# sourceMappingURL=protocol.js.map

package/src/lib/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../../../../../../libs/public/keypuncherlabs/live-preview/src/lib/protocol.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AA0BH,oCAOC;AAGD,wCAMC;AAxCD,uEAAuE;AAC1D,QAAA,qBAAqB,GAAG,kBAA2B,CAAC;AAEjE,gFAAgF;AACnE,QAAA,uBAAuB,GAAG,oBAA6B,CAAC;AAmBrE,6DAA6D;AAC7D,SAAgB,YAAY,CAAC,KAAc;IACzC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAA4B,CAAC,IAAI,KAAK,6BAAqB;QAC5D,OAAQ,KAA2B,CAAC,GAAG,KAAK,QAAQ,CACrD,CAAC;AACJ,CAAC;AAED,+DAA+D;AAC/D,SAAgB,cAAc,CAAC,KAAc;IAC3C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAA4B,CAAC,IAAI,KAAK,+BAAuB,CAC/D,CAAC;AACJ,CAAC"}

package/src/lib/receiver.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Embedded-app side of the live preview channel.
+ *
+ * The receiver listens for `live-preview-css` messages and injects the CSS into
+ * a single dedicated `<style>` element. Because the embedding page may live on a
+ * different origin than the parent app, two trust gates apply to every message:
+ *
+ *  1. `event.origin` must be in the configured allowlist. The allowlist is
+ *     required — there is no implicit default. Pass `['*']` only to deliberately
+ *     opt out (e.g. local development).
+ *  2. The CSS is re-validated here even though the sender already validated it;
+ *     this layer never assumes an upstream hop is trustworthy.
+ *
+ * Injection uses `textContent` (never `innerHTML`) and reuses one style node, so
+ * markup cannot be injected and the DOM does not grow on repeated updates.
+ */
+import { type CssValidationOptions } from './validate-css';
+export declare const DEFAULT_STYLE_ID = "live-preview-styles";
+export interface LivePreviewReceiverOptions {
+    /**
+     * Origins permitted to send CSS, e.g. `['https://app.example.com']`. Required.
+     * Use `['*']` only to intentionally accept any origin (development).
+     */
+    allowedOrigins: string[];
+    /** Document to inject into. Defaults to the ambient `document`. */
+    target?: Document;
+    /** Window to attach the message listener to. Defaults to the ambient `window`. */
+    source?: Window;
+    /** Id of the injected `<style>` element. Defaults to {@link DEFAULT_STYLE_ID}. */
+    styleId?: string;
+    /** Validation overrides applied to incoming CSS. */
+    validation?: CssValidationOptions;
+    /** Called after CSS is successfully applied. */
+    onApply?: (css: string) => void;
+    /** Called when a message is rejected, with a human-readable reason. */
+    onReject?: (reason: string) => void;
+}
+export interface LivePreviewReceiver {
+    /** Detach the listener. */
+    stop: () => void;
+}
+export declare function startLivePreviewReceiver(options: LivePreviewReceiverOptions): LivePreviewReceiver;

package/src/lib/receiver.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * Embedded-app side of the live preview channel.
+ *
+ * The receiver listens for `live-preview-css` messages and injects the CSS into
+ * a single dedicated `<style>` element. Because the embedding page may live on a
+ * different origin than the parent app, two trust gates apply to every message:
+ *
+ *  1. `event.origin` must be in the configured allowlist. The allowlist is
+ *     required — there is no implicit default. Pass `['*']` only to deliberately
+ *     opt out (e.g. local development).
+ *  2. The CSS is re-validated here even though the sender already validated it;
+ *     this layer never assumes an upstream hop is trustworthy.
+ *
+ * Injection uses `textContent` (never `innerHTML`) and reuses one style node, so
+ * markup cannot be injected and the DOM does not grow on repeated updates.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_STYLE_ID = void 0;
+exports.startLivePreviewReceiver = startLivePreviewReceiver;
+const protocol_1 = require("./protocol");
+const validate_css_1 = require("./validate-css");
+exports.DEFAULT_STYLE_ID = 'live-preview-styles';
+const isOriginAllowed = (origin, allowed) => allowed.includes('*') || allowed.includes(origin);
+const getOrCreateStyle = (doc, styleId) => {
+    const existing = doc.getElementById(styleId);
+    if (existing instanceof HTMLStyleElement) {
+        return existing;
+    }
+    const style = doc.createElement('style');
+    style.id = styleId;
+    style.setAttribute('data-live-preview', '');
+    doc.head.appendChild(style);
+    return style;
+};
+function startLivePreviewReceiver(options) {
+    const { allowedOrigins, target = document, source = window, styleId = exports.DEFAULT_STYLE_ID, validation, onApply, onReject, } = options;
+    if (!allowedOrigins || allowedOrigins.length === 0) {
+        throw new Error('startLivePreviewReceiver requires a non-empty allowedOrigins list');
+    }
+    const handleMessage = (event) => {
+        if (!isOriginAllowed(event.origin, allowedOrigins)) {
+            return; // Silently ignore untrusted origins — not actionable to the page.
+        }
+        if (!(0, protocol_1.isCssMessage)(event.data)) {
+            return;
+        }
+        const result = (0, validate_css_1.validateCss)(event.data.css, validation);
+        if (!result.valid) {
+            onReject === null || onReject === void 0 ? void 0 : onReject(`rejected css from ${event.origin}: ${result.errors.join('; ')}`);
+            return;
+        }
+        getOrCreateStyle(target, styleId).textContent = result.css;
+        onApply === null || onApply === void 0 ? void 0 : onApply(result.css);
+    };
+    source.addEventListener('message', handleMessage);
+    // Announce readiness upward so a parent can (re)send the current CSS without
+    // racing this listener's attachment.
+    if (source.parent && source.parent !== source) {
+        const ready = { type: protocol_1.LIVE_PREVIEW_READY_TYPE };
+        source.parent.postMessage(ready, '*');
+    }
+    return {
+        stop() {
+            source.removeEventListener('message', handleMessage);
+        },
+    };
+}
+//# sourceMappingURL=receiver.js.map

package/src/lib/receiver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"receiver.js","sourceRoot":"","sources":["../../../../../../../libs/public/keypuncherlabs/live-preview/src/lib/receiver.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AAmDH,4DAiDC;AAlGD,yCAIoB;AACpB,iDAAwE;AAE3D,QAAA,gBAAgB,GAAG,qBAAqB,CAAC;AA2BtD,MAAM,eAAe,GAAG,CAAC,MAAc,EAAE,OAAiB,EAAW,EAAE,CACrE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAEpD,MAAM,gBAAgB,GAAG,CAAC,GAAa,EAAE,OAAe,EAAoB,EAAE;IAC5E,MAAM,QAAQ,GAAG,GAAG,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IAC7C,IAAI,QAAQ,YAAY,gBAAgB,EAAE,CAAC;QACzC,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,MAAM,KAAK,GAAG,GAAG,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IACzC,KAAK,CAAC,EAAE,GAAG,OAAO,CAAC;IACnB,KAAK,CAAC,YAAY,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC;IAC5C,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IAC5B,OAAO,KAAK,CAAC;AACf,CAAC,CAAC;AAEF,SAAgB,wBAAwB,CACtC,OAAmC;IAEnC,MAAM,EACJ,cAAc,EACd,MAAM,GAAG,QAAQ,EACjB,MAAM,GAAG,MAAM,EACf,OAAO,GAAG,wBAAgB,EAC1B,UAAU,EACV,OAAO,EACP,QAAQ,GACT,GAAG,OAAO,CAAC;IAEZ,IAAI,CAAC,cAAc,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAC;IACvF,CAAC;IAED,MAAM,aAAa,GAAG,CAAC,KAAmB,EAAQ,EAAE;QAClD,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,MAAM,EAAE,cAAc,CAAC,EAAE,CAAC;YACnD,OAAO,CAAC,kEAAkE;QAC5E,CAAC;QACD,IAAI,CAAC,IAAA,uBAAY,EAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9B,OAAO;QACT,CAAC;QAED,MAAM,MAAM,GAAG,IAAA,0BAAW,EAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;QACvD,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YAClB,QAAQ,aAAR,QAAQ,uBAAR,QAAQ,CAAG,qBAAqB,KAAK,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC7E,OAAO;QACT,CAAC;QAED,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC;QAC3D,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC,CAAC;IAEF,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;IAElD,6EAA6E;IAC7E,qCAAqC;IACrC,IAAI,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAC9C,MAAM,KAAK,GAA4B,EAAE,IAAI,EAAE,kCAAuB,EAAE,CAAC;QACzE,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACxC,CAAC;IAED,OAAO;QACL,IAAI;YACF,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;QACvD,CAAC;KACF,CAAC;AACJ,CAAC"}

package/src/lib/relay.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Nested-iframe glue for hosts that sit between the parent app and the actual
+ * preview document — most notably a Storybook *manager*, which the parent posts
+ * to but which renders stories in a nested `#storybook-preview-iframe`.
+ *
+ * A grandparent window can only `postMessage` its direct child, so CSS has to be
+ * relayed one hop down. The relay:
+ *
+ *  - accepts `live-preview-css` only from allowlisted parent origins,
+ *  - re-validates the CSS (defense in depth) before forwarding,
+ *  - forwards it to a child window resolved lazily (the child may not exist yet
+ *    when the relay starts), and
+ *  - forwards the child's `live-preview-ready` ping back up to its own parent so
+ *    the original sender's readiness handshake works end to end.
+ */
+import { type CssValidationOptions } from './validate-css';
+export interface LivePreviewRelayOptions {
+    /** Parent origins permitted to send CSS. Required. `['*']` opts out (dev). */
+    allowedOrigins: string[];
+    /** Resolves the child window to forward to (e.g. the nested preview iframe). */
+    getTargetWindow: () => Window | null | undefined;
+    /** Exact origin of the child window. Usually `window.location.origin`. */
+    targetOrigin: string;
+    /** Window to listen on. Defaults to the ambient `window`. */
+    source?: Window;
+    /** Validation overrides applied to relayed CSS. */
+    validation?: CssValidationOptions;
+    /** Called when CSS is rejected before forwarding, with a reason. */
+    onReject?: (reason: string) => void;
+}
+export interface LivePreviewRelay {
+    /** Detach the listener. */
+    stop: () => void;
+}
+export declare function createLivePreviewRelay(options: LivePreviewRelayOptions): LivePreviewRelay;

package/src/lib/relay.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Nested-iframe glue for hosts that sit between the parent app and the actual
+ * preview document — most notably a Storybook *manager*, which the parent posts
+ * to but which renders stories in a nested `#storybook-preview-iframe`.
+ *
+ * A grandparent window can only `postMessage` its direct child, so CSS has to be
+ * relayed one hop down. The relay:
+ *
+ *  - accepts `live-preview-css` only from allowlisted parent origins,
+ *  - re-validates the CSS (defense in depth) before forwarding,
+ *  - forwards it to a child window resolved lazily (the child may not exist yet
+ *    when the relay starts), and
+ *  - forwards the child's `live-preview-ready` ping back up to its own parent so
+ *    the original sender's readiness handshake works end to end.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLivePreviewRelay = createLivePreviewRelay;
+const protocol_1 = require("./protocol");
+const validate_css_1 = require("./validate-css");
+const isOriginAllowed = (origin, allowed) => allowed.includes('*') || allowed.includes(origin);
+function createLivePreviewRelay(options) {
+    const { allowedOrigins, getTargetWindow, targetOrigin, source = window, validation, onReject, } = options;
+    if (!allowedOrigins || allowedOrigins.length === 0) {
+        throw new Error('createLivePreviewRelay requires a non-empty allowedOrigins list');
+    }
+    if (!targetOrigin || targetOrigin === '*') {
+        throw new Error('createLivePreviewRelay requires an explicit targetOrigin (cannot be "*")');
+    }
+    const handleMessage = (event) => {
+        // A ready ping bubbling up from the child preview: pass it to our parent so
+        // the original sender can complete its handshake.
+        if ((0, protocol_1.isReadyMessage)(event.data)) {
+            if (source.parent && source.parent !== source) {
+                source.parent.postMessage(event.data, '*');
+            }
+            return;
+        }
+        if (!isOriginAllowed(event.origin, allowedOrigins)) {
+            return;
+        }
+        if (!(0, protocol_1.isCssMessage)(event.data)) {
+            return;
+        }
+        const result = (0, validate_css_1.validateCss)(event.data.css, validation);
+        if (!result.valid) {
+            onReject === null || onReject === void 0 ? void 0 : onReject(`relay rejected css from ${event.origin}: ${result.errors.join('; ')}`);
+            return;
+        }
+        const child = getTargetWindow();
+        if (!child) {
+            return; // Preview frame not mounted yet; the sender resends on ready.
+        }
+        const message = { type: protocol_1.LIVE_PREVIEW_CSS_TYPE, css: result.css };
+        child.postMessage(message, targetOrigin);
+    };
+    source.addEventListener('message', handleMessage);
+    return {
+        stop() {
+            source.removeEventListener('message', handleMessage);
+        },
+    };
+}
+//# sourceMappingURL=relay.js.map

package/src/lib/relay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay.js","sourceRoot":"","sources":["../../../../../../../libs/public/keypuncherlabs/live-preview/src/lib/relay.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;AAiCH,wDAwDC;AAvFD,yCAKoB;AACpB,iDAAwE;AAsBxE,MAAM,eAAe,GAAG,CAAC,MAAc,EAAE,OAAiB,EAAW,EAAE,CACrE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAEpD,SAAgB,sBAAsB,CAAC,OAAgC;IACrE,MAAM,EACJ,cAAc,EACd,eAAe,EACf,YAAY,EACZ,MAAM,GAAG,MAAM,EACf,UAAU,EACV,QAAQ,GACT,GAAG,OAAO,CAAC;IAEZ,IAAI,CAAC,cAAc,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,KAAK,CAAC,iEAAiE,CAAC,CAAC;IACrF,CAAC;IACD,IAAI,CAAC,YAAY,IAAI,YAAY,KAAK,GAAG,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,0EAA0E,CAAC,CAAC;IAC9F,CAAC;IAED,MAAM,aAAa,GAAG,CAAC,KAAmB,EAAQ,EAAE;QAClD,4EAA4E;QAC5E,kDAAkD;QAClD,IAAI,IAAA,yBAAc,EAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/B,IAAI,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;gBAC9C,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YAC7C,CAAC;YACD,OAAO;QACT,CAAC;QAED,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,MAAM,EAAE,cAAc,CAAC,EAAE,CAAC;YACnD,OAAO;QACT,CAAC;QACD,IAAI,CAAC,IAAA,uBAAY,EAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9B,OAAO;QACT,CAAC;QAED,MAAM,MAAM,GAAG,IAAA,0BAAW,EAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;QACvD,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YAClB,QAAQ,aAAR,QAAQ,uBAAR,QAAQ,CAAG,2BAA2B,KAAK,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACnF,OAAO;QACT,CAAC;QAED,MAAM,KAAK,GAAG,eAAe,EAAE,CAAC;QAChC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,CAAC,8DAA8D;QACxE,CAAC;QAED,MAAM,OAAO,GAA0B,EAAE,IAAI,EAAE,gCAAqB,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC;QACxF,KAAK,CAAC,WAAW,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IAC3C,CAAC,CAAC;IAEF,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;IAElD,OAAO;QACL,IAAI;YACF,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;QACvD,CAAC;KACF,CAAC;AACJ,CAAC"}

package/src/lib/sender.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Parent-app side of the live preview channel.
+ *
+ * A sender is bound to one target window (typically an embedded `<iframe>`'s
+ * `contentWindow`) and one explicit target origin. CSS is validated before it
+ * leaves this window, and the post is always addressed to a concrete origin —
+ * never `'*'` — so a navigated-away or swapped iframe can never receive it.
+ */
+import { type CssValidationOptions, type CssValidationResult } from './validate-css';
+export interface LivePreviewSenderOptions {
+    /** The window to post to, e.g. `iframe.contentWindow`. */
+    targetWindow: Window;
+    /**
+     * The exact origin of the embedded preview, e.g. `https://preview.example.com`.
+     * Wildcards are rejected: posting CSS to `'*'` would leak it to whatever
+     * document currently occupies the frame.
+     */
+    targetOrigin: string;
+    /** Validation overrides applied before sending. */
+    validation?: CssValidationOptions;
+}
+export interface LivePreviewSender {
+    /**
+     * Validate and post a CSS payload. Returns the validation result; when
+     * invalid, nothing is sent and `result.errors` explains why.
+     */
+    sendCss(css: string): CssValidationResult;
+}
+export declare function createLivePreviewSender(options: LivePreviewSenderOptions): LivePreviewSender;

package/src/lib/sender.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * Parent-app side of the live preview channel.
+ *
+ * A sender is bound to one target window (typically an embedded `<iframe>`'s
+ * `contentWindow`) and one explicit target origin. CSS is validated before it
+ * leaves this window, and the post is always addressed to a concrete origin —
+ * never `'*'` — so a navigated-away or swapped iframe can never receive it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLivePreviewSender = createLivePreviewSender;
+const protocol_1 = require("./protocol");
+const validate_css_1 = require("./validate-css");
+function createLivePreviewSender(options) {
+    const { targetWindow, targetOrigin, validation } = options;
+    if (!targetOrigin || targetOrigin === '*') {
+        throw new Error('createLivePreviewSender requires an explicit targetOrigin (cannot be "*")');
+    }
+    return {
+        sendCss(css) {
+            const result = (0, validate_css_1.validateCss)(css, validation);
+            if (!result.valid) {
+                return result;
+            }
+            const message = { type: protocol_1.LIVE_PREVIEW_CSS_TYPE, css: result.css };
+            targetWindow.postMessage(message, targetOrigin);
+            return result;
+        },
+    };
+}
+//# sourceMappingURL=sender.js.map

package/src/lib/sender.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sender.js","sourceRoot":"","sources":["../../../../../../../libs/public/keypuncherlabs/live-preview/src/lib/sender.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AA0BH,0DAqBC;AA7CD,yCAA+E;AAC/E,iDAAkG;AAuBlG,SAAgB,uBAAuB,CAAC,OAAiC;IACvE,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IAE3D,IAAI,CAAC,YAAY,IAAI,YAAY,KAAK,GAAG,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CACb,2EAA2E,CAC5E,CAAC;IACJ,CAAC;IAED,OAAO;QACL,OAAO,CAAC,GAAW;YACjB,MAAM,MAAM,GAAG,IAAA,0BAAW,EAAC,GAAG,EAAE,UAAU,CAAC,CAAC;YAC5C,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;gBAClB,OAAO,MAAM,CAAC;YAChB,CAAC;YAED,MAAM,OAAO,GAA0B,EAAE,IAAI,EAAE,gCAAqB,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC;YACxF,YAAY,CAAC,WAAW,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;YAChD,OAAO,MAAM,CAAC;QAChB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/src/lib/validate-css.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Safety validation for CSS that crosses an origin boundary.
+ *
+ * This util is meant to be embedded in pages on origins you do not fully
+ * control, so the CSS arriving over `postMessage` must be treated as untrusted
+ * input. `validateCss` is a pure, DOM-free string check (it runs in Node too)
+ * and is applied at every hop — by the sender before posting and again by the
+ * receiver/relay before injecting — so a single trusted layer is never assumed.
+ *
+ * It is intentionally conservative: it rejects rather than tries to "clean" the
+ * input. Anything that looks like an attempt to break out of a `<style>` element
+ * or pull in active/external content is refused. The companion injection step
+ * still uses `textContent` (never `innerHTML`), so even valid CSS cannot inject
+ * markup.
+ */
+/** Default ceiling on payload size, guarding against memory-exhaustion DoS. */
+export declare const DEFAULT_MAX_CSS_LENGTH = 100000;
+/** URL schemes allowed inside `url(...)` by default (plus relative / `#`). */
+export declare const DEFAULT_ALLOWED_URL_SCHEMES: readonly ["https", "data"];
+export interface CssValidationOptions {
+    /** Max allowed length in characters. Defaults to {@link DEFAULT_MAX_CSS_LENGTH}. */
+    maxLength?: number;
+    /** Allow `@import` rules. Off by default (they trigger external fetches). */
+    allowAtImport?: boolean;
+    /**
+     * Allow any `url(...)` scheme except the always-forbidden ones. Off by
+     * default. When off, only {@link allowedUrlSchemes} (plus relative/`#`) pass.
+     */
+    allowExternalUrls?: boolean;
+    /** Permitted `url(...)` schemes when `allowExternalUrls` is off. */
+    allowedUrlSchemes?: readonly string[];
+}
+export interface CssValidationResult {
+    /** True when the input is safe to inject as-is. */
+    valid: boolean;
+    /** The original CSS when valid, otherwise an empty string. */
+    css: string;
+    /** Human-readable reasons the input was rejected (empty when valid). */
+    errors: string[];
+}
+/**
+ * Validate a CSS string. Never throws; returns a result describing why the
+ * input was rejected.
+ */
+export declare function validateCss(input: unknown, options?: CssValidationOptions): CssValidationResult;

package/src/lib/validate-css.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * Safety validation for CSS that crosses an origin boundary.
+ *
+ * This util is meant to be embedded in pages on origins you do not fully
+ * control, so the CSS arriving over `postMessage` must be treated as untrusted
+ * input. `validateCss` is a pure, DOM-free string check (it runs in Node too)
+ * and is applied at every hop — by the sender before posting and again by the
+ * receiver/relay before injecting — so a single trusted layer is never assumed.
+ *
+ * It is intentionally conservative: it rejects rather than tries to "clean" the
+ * input. Anything that looks like an attempt to break out of a `<style>` element
+ * or pull in active/external content is refused. The companion injection step
+ * still uses `textContent` (never `innerHTML`), so even valid CSS cannot inject
+ * markup.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_ALLOWED_URL_SCHEMES = exports.DEFAULT_MAX_CSS_LENGTH = void 0;
+exports.validateCss = validateCss;
+/** Default ceiling on payload size, guarding against memory-exhaustion DoS. */
+exports.DEFAULT_MAX_CSS_LENGTH = 100000;
+/** URL schemes allowed inside `url(...)` by default (plus relative / `#`). */
+exports.DEFAULT_ALLOWED_URL_SCHEMES = ['https', 'data'];
+/** Schemes that are never allowed inside `url(...)`, even with opt-outs. */
+const FORBIDDEN_URL_SCHEMES = ['javascript', 'vbscript', 'file'];
+// Matches any ASCII control character except tab (\t \x09), newline (\n \x0a)
+// and carriage return (\r \x0d), which are legitimate whitespace in CSS. Built
+// from escapes so no literal control bytes live in this source file.
+const CONTROL_CHARS = new RegExp('[\\x00-\\x08\\x0b\\x0c\\x0e-\\x1f\\x7f]');
+// Active-content / breakout constructs that have no place in injected CSS.
+const FORBIDDEN_PATTERNS = [
+    { pattern: /<\/?\s*style/i, message: 'contains a <style> tag (possible breakout)' },
+    { pattern: /<\s*script/i, message: 'contains a <script> tag' },
+    { pattern: /<\/?\s*[a-z]/i, message: 'contains HTML-like markup' },
+    { pattern: /expression\s*\(/i, message: 'contains an expression() call' },
+    { pattern: /javascript\s*:/i, message: 'contains a javascript: reference' },
+    { pattern: /vbscript\s*:/i, message: 'contains a vbscript: reference' },
+    { pattern: /-moz-binding/i, message: 'contains a -moz-binding declaration' },
+    { pattern: /behavior\s*:/i, message: 'contains a behavior: declaration' },
+    { pattern: CONTROL_CHARS, message: 'contains control characters' },
+];
+// Captures the scheme of every url(...) target so each can be checked.
+const URL_PATTERN = /url\(\s*(['"]?)([^'")]*)\1\s*\)/gi;
+const schemeOf = (target) => {
+    const match = /^\s*([a-z][a-z0-9+.-]*)\s*:/i.exec(target);
+    return match ? match[1].toLowerCase() : null;
+};
+/**
+ * Validate a CSS string. Never throws; returns a result describing why the
+ * input was rejected.
+ */
+function validateCss(input, options = {}) {
+    const errors = [];
+    const { maxLength = exports.DEFAULT_MAX_CSS_LENGTH, allowAtImport = false, allowExternalUrls = false, allowedUrlSchemes = exports.DEFAULT_ALLOWED_URL_SCHEMES, } = options;
+    if (typeof input !== 'string') {
+        return { valid: false, css: '', errors: ['css must be a string'] };
+    }
+    if (input.length > maxLength) {
+        errors.push(`css exceeds the maximum length of ${maxLength} characters`);
+    }
+    for (const { pattern, message } of FORBIDDEN_PATTERNS) {
+        if (pattern.test(input)) {
+            errors.push(`css ${message}`);
+        }
+    }
+    if (!allowAtImport && /@import\b/i.test(input)) {
+        errors.push('css contains an @import rule');
+    }
+    if (!allowExternalUrls) {
+        const allowed = allowedUrlSchemes.map((scheme) => scheme.toLowerCase());
+        for (const match of input.matchAll(URL_PATTERN)) {
+            const scheme = schemeOf(match[2]);
+            // No scheme => relative URL or fragment, which is fine.
+            if (scheme !== null && !allowed.includes(scheme)) {
+                errors.push(`css contains a disallowed url() scheme: ${scheme}:`);
+            }
+        }
+    }
+    else {
+        for (const match of input.matchAll(URL_PATTERN)) {
+            const scheme = schemeOf(match[2]);
+            if (scheme !== null && FORBIDDEN_URL_SCHEMES.includes(scheme)) {
+                errors.push(`css contains a forbidden url() scheme: ${scheme}:`);
+            }
+        }
+    }
+    if (errors.length > 0) {
+        return { valid: false, css: '', errors };
+    }
+    return { valid: true, css: input, errors: [] };
+}
+//# sourceMappingURL=validate-css.js.map

package/src/lib/validate-css.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-css.js","sourceRoot":"","sources":["../../../../../../../libs/public/keypuncherlabs/live-preview/src/lib/validate-css.ts"],"names":[],"mappings":"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"}