@marianmeres/widget-provider 1.0.2

package/AGENTS.md

@@ -0,0 +1,45 @@
+# @marianmeres/widget-provider — Agent Guide
+
+## Quick Reference
+- **Stack**: Deno, TypeScript, browser DOM APIs
+- **Runtime**: Deno (primary), npm (secondary via build)
+- **Dependency**: `@marianmeres/store` (reactive state)
+- **Test**: `deno test` | **Build**: `deno task npm:build` | **Publish**: `deno task publish`
+
+## Project Structure
+```
+/src
+  mod.ts              — Public entry point (re-exports)
+  types.ts            — All type definitions and constants
+  style-presets.ts    — CSS preset configs and apply functions
+  widget-provider.ts  — Core provideWidget() implementation
+/tests                — Deno tests (unit tests for pure functions)
+/scripts              — npm build script
+/example              — Dev example app
+```
+
+## What This Library Does
+Embeds an iframe-based widget into a host page with:
+- Style presets (float, fullscreen, inline) for positioning
+- postMessage-based bidirectional communication (namespaced with `@@__widget_provider__@@`)
+- Show/hide animations (fade-scale, slide-up)
+- Optional trigger button (auto-toggles with widget visibility)
+- Reactive state via `@marianmeres/store` (Svelte-compatible subscribe)
+
+## Critical Conventions
+1. All message types are prefixed with `MSG_PREFIX` (`@@__widget_provider__@@`)
+2. Types live in `types.ts`, style logic in `style-presets.ts`, core logic in `widget-provider.ts`
+3. `mod.ts` is the sole public entry point — all public exports go through it
+4. Use Deno formatting: tabs, 90 char line width (`deno fmt`)
+5. `provideWidget()` is the only user-facing factory — returns `WidgetProviderApi`
+
+## Before Making Changes
+- [ ] Check existing patterns in similar files
+- [ ] Run `deno test`
+- [ ] Run `deno fmt`
+- [ ] Ensure all public exports are re-exported from `mod.ts`
+
+## Documentation Index
+- [Architecture](./docs/architecture.md)
+- [Conventions](./docs/conventions.md)
+- [Tasks](./docs/tasks.md)

package/API.md

@@ -0,0 +1,204 @@
+# API
+
+## Functions
+
+### `provideWidget(options)`
+
+Create and embed an iframe-based widget. Returns a control API object.
+
+**Parameters:**
+- `options` (`WidgetProviderOptions`) — Configuration object (see below)
+
+**Returns:** `WidgetProviderApi`
+
+**Example:**
+```typescript
+import { provideWidget } from '@marianmeres/widget-provider';
+
+const widget = provideWidget({
+    widgetUrl: 'https://example.com/widget',
+    stylePreset: 'float',
+    animate: 'slide-up',
+    trigger: { content: '<span>Chat</span>' },
+});
+```
+
+---
+
+### `resolveAllowedOrigins(explicit, widgetUrl)`
+
+Resolve the list of allowed origins for postMessage validation.
+
+**Parameters:**
+- `explicit` (`string | string[] | undefined`) — Explicitly configured origin(s)
+- `widgetUrl` (`string`) — The widget URL to derive origin from
+
+**Returns:** `string[]` — Array of allowed origin strings
+
+**Example:**
+```typescript
+resolveAllowedOrigins(undefined, 'https://example.com/app');
+// => ['https://example.com']
+
+resolveAllowedOrigins(['https://a.com', 'https://b.com'], 'https://c.com/app');
+// => ['https://a.com', 'https://b.com']
+```
+
+---
+
+### `isOriginAllowed(origin, allowed)`
+
+Check whether a given origin is in the allowed list.
+
+**Parameters:**
+- `origin` (`string`) — Origin to check
+- `allowed` (`string[]`) — List of allowed origins (use `"*"` to allow any)
+
+**Returns:** `boolean`
+
+---
+
+### `resolveAnimateConfig(opt)`
+
+Resolve animation option into a concrete `AnimateConfig` or `null`.
+
+**Parameters:**
+- `opt` (`boolean | AnimatePreset | { preset?: AnimatePreset; transition?: string } | undefined`)
+
+**Returns:** `AnimateConfig | null`
+
+---
+
+## Types
+
+### `WidgetProviderOptions`
+
+```typescript
+interface WidgetProviderOptions {
+    /** The URL of the SPA to embed (required) */
+    widgetUrl: string;
+    /** DOM element to append the widget into. Default: document.body */
+    parentContainer?: HTMLElement;
+    /** Positioning mode. Default: "inline" */
+    stylePreset?: StylePreset;
+    /** CSS overrides applied to the container wrapper div */
+    styleOverrides?: StyleOverrides;
+    /** Allowed origin(s) for postMessage validation. Derived from widgetUrl if omitted */
+    allowedOrigin?: string | string[];
+    /** Whether the widget starts visible. Default: true */
+    visible?: boolean;
+    /** Iframe sandbox attribute. Default: "allow-scripts allow-same-origin" */
+    sandbox?: string;
+    /** Additional iframe attributes (e.g. allow, referrerpolicy) */
+    iframeAttrs?: Record<string, string>;
+    /** Opt-in show/hide animation: true | AnimatePreset | { preset?, transition? } */
+    animate?: boolean | AnimatePreset | { preset?: AnimatePreset; transition?: string };
+    /** Built-in floating trigger button: true | { content?, style? } */
+    trigger?: boolean | { content?: string; style?: Partial<CSSStyleDeclaration> };
+}
+```
+
+---
+
+### `WidgetProviderApi`
+
+The object returned by `provideWidget()`.
+
+| Method / Property | Signature | Description |
+|-------------------|-----------|-------------|
+| `show()` | `() => void` | Show the widget container |
+| `hide()` | `() => void` | Hide the widget container |
+| `toggle()` | `() => void` | Toggle visibility |
+| `destroy()` | `() => void` | Remove iframe, listeners, DOM elements. Irreversible |
+| `setPreset(preset)` | `(preset: StylePreset) => void` | Switch style preset at runtime |
+| `maximize()` | `() => void` | Switch to fullscreen preset |
+| `minimize()` | `() => void` | Switch back to initial preset |
+| `requestNativeFullscreen()` | `() => Promise<void>` | Browser fullscreen for iframe |
+| `exitNativeFullscreen()` | `() => Promise<void>` | Exit browser fullscreen |
+| `send(type, payload?)` | `<T>(type: string, payload?: T) => void` | Send message to iframe |
+| `onMessage(type, handler)` | `<T>(type: string, handler: (payload: T) => void) => Unsubscribe` | Listen for iframe messages |
+| `subscribe(cb)` | `(cb: (state: WidgetState) => void) => Unsubscribe` | Reactive state subscription |
+| `get()` | `() => WidgetState` | Get current state snapshot |
+| `iframe` | `readonly HTMLIFrameElement` | Direct iframe element reference |
+| `container` | `readonly HTMLElement` | Direct container div reference |
+| `trigger` | `readonly HTMLElement \| null` | Trigger button reference, or null |
+
+---
+
+### `WidgetState`
+
+```typescript
+interface WidgetState {
+    visible: boolean;
+    ready: boolean;
+    destroyed: boolean;
+    preset: StylePreset;
+}
+```
+
+---
+
+### `WidgetMessage<T>`
+
+```typescript
+interface WidgetMessage<T = unknown> {
+    type: string;
+    payload?: T;
+}
+```
+
+---
+
+### `StylePreset`
+
+```typescript
+type StylePreset = "float" | "fullscreen" | "inline";
+```
+
+---
+
+### `AnimatePreset`
+
+```typescript
+type AnimatePreset = "fade-scale" | "slide-up";
+```
+
+---
+
+### `StyleOverrides`
+
+```typescript
+type StyleOverrides = Partial<CSSStyleDeclaration>;
+```
+
+---
+
+### `AnimateConfig`
+
+```typescript
+interface AnimateConfig {
+    transition: string;
+    hidden: Partial<CSSStyleDeclaration>;
+    visible: Partial<CSSStyleDeclaration>;
+}
+```
+
+---
+
+## Constants
+
+### `MSG_PREFIX`
+
+`"@@__widget_provider__@@"` — Namespace prefix for all postMessage types.
+
+### `STYLE_PRESETS`
+
+`Record<StylePreset, Partial<CSSStyleDeclaration>>` — CSS property objects for each positioning mode.
+
+### `ANIMATE_PRESETS`
+
+`Record<AnimatePreset, AnimateConfig>` — Animation configurations for show/hide transitions.
+
+### `IFRAME_BASE`
+
+`Partial<CSSStyleDeclaration>` — Base CSS applied to all iframes (100% width/height, no border).

package/CLAUDE.md

@@ -0,0 +1,3 @@
+# Project Instructions
+
+See [AGENTS.md](./AGENTS.md) for complete project documentation and AI agent instructions.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marian Meres
+
+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,76 @@
+# @marianmeres/widget-provider
+
+[![NPM](https://img.shields.io/npm/v/@marianmeres/widget-provider)](https://www.npmjs.com/package/@marianmeres/widget-provider)
+[![JSR](https://jsr.io/badges/@marianmeres/widget-provider)](https://jsr.io/@marianmeres/widget-provider)
+[![License](https://img.shields.io/npm/l/@marianmeres/widget-provider)](LICENSE)
+
+Embed an iframe-based widget into a host page with built-in positioning presets,
+bidirectional postMessage communication, show/hide animations, and reactive state.
+
+## Installation
+
+```bash
+npm install @marianmeres/widget-provider
+```
+
+Or via JSR:
+
+```bash
+deno add jsr:@marianmeres/widget-provider
+```
+
+## Usage
+
+```typescript
+import { provideWidget } from '@marianmeres/widget-provider';
+
+const widget = provideWidget({
+    widgetUrl: 'https://example.com/my-widget',
+    stylePreset: 'float',        // "float" | "fullscreen" | "inline"
+    animate: true,               // fade-scale animation
+    trigger: true,               // show floating trigger button when hidden
+});
+
+// Control visibility
+widget.show();
+widget.hide();
+widget.toggle();
+
+// Send messages to the iframe
+widget.send('greet', { name: 'World' });
+
+// Listen for messages from the iframe
+const unsub = widget.onMessage('response', (payload) => {
+    console.log(payload);
+});
+
+// Subscribe to reactive state changes
+widget.subscribe((state) => {
+    console.log(state.visible, state.ready);
+});
+
+// Clean up
+widget.destroy();
+```
+
+### Style Presets
+
+| Preset | Description |
+|--------|-------------|
+| `"inline"` | Flows within parent container (default) |
+| `"float"` | Fixed bottom-right chat-widget style |
+| `"fullscreen"` | Covers viewport with backdrop overlay |
+
+### Message Protocol
+
+Messages between the host and iframe are namespaced with `@@__widget_provider__@@`
+prefix. The iframe can send built-in control messages: `ready`, `maximize`, `minimize`,
+`hide`, `close`, `setPreset`, `nativeFullscreen`, `exitNativeFullscreen`.
+
+## API
+
+See [API.md](API.md) for complete API documentation.
+
+## License
+
+[MIT](LICENSE)

package/dist/mod.d.ts

@@ -0,0 +1,4 @@
+export { provideWidget, resolveAllowedOrigins, isOriginAllowed, resolveAnimateConfig, } from "./widget-provider.js";
+export type { WidgetProviderOptions, WidgetProviderApi, WidgetState, WidgetMessage, StylePreset, StyleOverrides, AnimatePreset, MessageHandler, Unsubscribe, } from "./types.js";
+export { MSG_PREFIX } from "./types.js";
+export { STYLE_PRESETS, IFRAME_BASE, ANIMATE_PRESETS, type AnimateConfig, } from "./style-presets.js";

package/dist/mod.js

@@ -0,0 +1,3 @@
+export { provideWidget, resolveAllowedOrigins, isOriginAllowed, resolveAnimateConfig, } from "./widget-provider.js";
+export { MSG_PREFIX } from "./types.js";
+export { STYLE_PRESETS, IFRAME_BASE, ANIMATE_PRESETS, } from "./style-presets.js";

package/dist/style-presets.d.ts

@@ -0,0 +1,18 @@
+import type { AnimatePreset, StylePreset } from "./types.js";
+type CSSProps = Partial<CSSStyleDeclaration>;
+/** CSS transition and visibility states for a show/hide animation */
+export interface AnimateConfig {
+    transition: string;
+    hidden: CSSProps;
+    visible: CSSProps;
+}
+/** Built-in animation configurations keyed by {@linkcode AnimatePreset} name */
+export declare const ANIMATE_PRESETS: Record<AnimatePreset, AnimateConfig>;
+/** Base CSS styles applied to every widget iframe (100% size, no border) */
+export declare const IFRAME_BASE: CSSProps;
+export declare const TRIGGER_BASE: CSSProps;
+/** CSS property objects for each positioning mode keyed by {@linkcode StylePreset} name */
+export declare const STYLE_PRESETS: Record<StylePreset, CSSProps>;
+export declare function applyPreset(container: HTMLElement, preset: StylePreset, overrides: Partial<CSSStyleDeclaration>): void;
+export declare function applyIframeBaseStyles(iframe: HTMLIFrameElement): void;
+export {};

package/dist/style-presets.js

@@ -0,0 +1,86 @@
+/** Built-in animation configurations keyed by {@linkcode AnimatePreset} name */
+export const ANIMATE_PRESETS = {
+    "fade-scale": {
+        transition: "opacity 200ms ease, transform 200ms ease",
+        hidden: { opacity: "0", transform: "scale(0.9)" },
+        visible: { opacity: "1", transform: "scale(1)" },
+    },
+    "slide-up": {
+        transition: "opacity 200ms ease, transform 200ms ease",
+        hidden: { opacity: "0", transform: "translateY(20px)" },
+        visible: { opacity: "1", transform: "translateY(0)" },
+    },
+};
+const BASE_CONTAINER = {
+    boxSizing: "border-box",
+    overflow: "hidden",
+};
+/** Base CSS styles applied to every widget iframe (100% size, no border) */
+export const IFRAME_BASE = {
+    width: "100%",
+    height: "100%",
+    border: "none",
+    display: "block",
+};
+const PRESET_FLOAT = {
+    ...BASE_CONTAINER,
+    position: "fixed",
+    bottom: "20px",
+    right: "20px",
+    width: "380px",
+    height: "520px",
+    zIndex: "10000",
+    borderRadius: "12px",
+    boxShadow: "0 4px 24px rgba(0,0,0,0.15)",
+};
+const PRESET_FULLSCREEN = {
+    ...BASE_CONTAINER,
+    position: "fixed",
+    top: "0",
+    left: "0",
+    width: "100vw",
+    height: "100vh",
+    zIndex: "10000",
+    padding: "2rem",
+    backgroundColor: "rgba(0,0,0,0.5)",
+};
+const PRESET_INLINE = {
+    ...BASE_CONTAINER,
+    position: "relative",
+    width: "100%",
+    height: "100%",
+};
+export const TRIGGER_BASE = {
+    position: "fixed",
+    bottom: "20px",
+    right: "20px",
+    width: "56px",
+    height: "56px",
+    borderRadius: "50%",
+    border: "none",
+    background: "#1a73e8",
+    color: "white",
+    cursor: "pointer",
+    zIndex: "10001",
+    boxShadow: "0 4px 12px rgba(0,0,0,0.15)",
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    padding: "0",
+};
+/** CSS property objects for each positioning mode keyed by {@linkcode StylePreset} name */
+export const STYLE_PRESETS = {
+    float: PRESET_FLOAT,
+    fullscreen: PRESET_FULLSCREEN,
+    inline: PRESET_INLINE,
+};
+export function applyPreset(container, preset, overrides) {
+    const base = STYLE_PRESETS[preset];
+    if (!base) {
+        throw new Error(`Unknown style preset: "${preset}"`);
+    }
+    Object.assign(container.style, base, overrides);
+}
+export function applyIframeBaseStyles(iframe) {
+    Object.assign(iframe.style, IFRAME_BASE);
+}

package/dist/types.d.ts

@@ -0,0 +1,109 @@
+/** Namespace prefix for all widget-provider postMessage types */
+export declare const MSG_PREFIX = "@@__widget_provider__@@";
+/** The structured envelope for all host <-> iframe messages */
+export interface WidgetMessage<T = unknown> {
+    type: string;
+    payload?: T;
+}
+/** Built-in positioning modes for the widget container */
+export type StylePreset = "float" | "fullscreen" | "inline";
+/** Named animation presets for show/hide transitions */
+export type AnimatePreset = "fade-scale" | "slide-up";
+/** CSS overrides applied on top of a style preset */
+export type StyleOverrides = Partial<CSSStyleDeclaration>;
+/** Callback for handling a typed message payload from the widget iframe */
+export type MessageHandler<T = unknown> = (payload: T) => void;
+/** Function that removes a previously registered listener or subscription */
+export type Unsubscribe = () => void;
+/** Configuration options for {@linkcode provideWidget} */
+export interface WidgetProviderOptions {
+    /** The URL of the SPA to embed */
+    widgetUrl: string;
+    /** DOM element to append the widget into. Defaults to document.body */
+    parentContainer?: HTMLElement;
+    /**
+     * Positioning mode. Defaults to "inline".
+     * - "float": fixed bottom-right chat-widget style
+     * - "fullscreen": covers viewport with optional backdrop
+     * - "inline": flows within parent container
+     */
+    stylePreset?: StylePreset;
+    /** CSS overrides applied to the container wrapper div */
+    styleOverrides?: StyleOverrides;
+    /**
+     * Allowed origin(s) for postMessage validation.
+     * If omitted, derived from widgetUrl.
+     * Use "*" to allow any origin (not recommended for production).
+     */
+    allowedOrigin?: string | string[];
+    /** Whether the widget starts visible. Defaults to true */
+    visible?: boolean;
+    /** Iframe sandbox attribute. Defaults to "allow-scripts allow-same-origin" */
+    sandbox?: string;
+    /** Additional iframe attributes (e.g. allow, referrerpolicy) */
+    iframeAttrs?: Record<string, string>;
+    /**
+     * Opt-in show/hide animation.
+     * - `true` → default "fade-scale" preset
+     * - string → named preset ("fade-scale" | "slide-up")
+     * - object → named preset + CSS transition override
+     */
+    animate?: boolean | AnimatePreset | {
+        preset?: AnimatePreset;
+        /** CSS transition shorthand override */
+        transition?: string;
+    };
+    /**
+     * Built-in floating trigger button.
+     * If `true`, uses default styles/icon. If object, allows customization.
+     * Automatically shown when widget is hidden, hidden when widget is visible.
+     */
+    trigger?: boolean | {
+        /** HTML content for the button (e.g. SVG icon). Defaults to a chat bubble SVG. */
+        content?: string;
+        /** CSS overrides for the trigger button */
+        style?: Partial<CSSStyleDeclaration>;
+    };
+}
+/** Reactive state tracked in the store */
+export interface WidgetState {
+    visible: boolean;
+    ready: boolean;
+    destroyed: boolean;
+    preset: StylePreset;
+}
+/** Control API returned by {@linkcode provideWidget} */
+export interface WidgetProviderApi {
+    /** Show the widget container */
+    show(): void;
+    /** Hide the widget container */
+    hide(): void;
+    /** Toggle visibility */
+    toggle(): void;
+    /** Remove iframe, event listeners, container from DOM. Irreversible. */
+    destroy(): void;
+    /** Switch to a specific style preset at runtime */
+    setPreset(preset: StylePreset): void;
+    /** Shortcut: switch to fullscreen preset */
+    maximize(): void;
+    /** Shortcut: switch back to the initial preset */
+    minimize(): void;
+    /** Request native browser fullscreen for the iframe */
+    requestNativeFullscreen(): Promise<void>;
+    /** Exit native browser fullscreen */
+    exitNativeFullscreen(): Promise<void>;
+    /** Send a typed message to the iframe */
+    send<T = unknown>(type: string, payload?: T): void;
+    /** Listen for a typed message from the iframe. Returns unsubscribe. */
+    onMessage<T = unknown>(type: string, handler: MessageHandler<T>): Unsubscribe;
+    /** Svelte-compatible store subscribe for reactive state */
+    subscribe(cb: (state: WidgetState) => void): Unsubscribe;
+    /** Direct getter for current state */
+    get(): WidgetState;
+    /** Direct reference to the iframe element */
+    readonly iframe: HTMLIFrameElement;
+    /** Direct reference to the container wrapper div */
+    readonly container: HTMLElement;
+    /** Direct reference to the trigger button element, or null if not configured */
+    readonly trigger: HTMLElement | null;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+/** Namespace prefix for all widget-provider postMessage types */
+export const MSG_PREFIX = "@@__widget_provider__@@";

package/dist/widget-provider.d.ts

@@ -0,0 +1,20 @@
+import { type AnimateConfig } from "./style-presets.js";
+import { type WidgetProviderApi, type WidgetProviderOptions } from "./types.js";
+/**
+ * Resolve the list of allowed origins for postMessage validation.
+ * Uses explicit value if provided, otherwise derives from widgetUrl. Falls back to `["*"]`.
+ */
+export declare function resolveAllowedOrigins(explicit: string | string[] | undefined, widgetUrl: string): string[];
+/** Check whether a given origin is permitted by the allowed origins list. */
+export declare function isOriginAllowed(origin: string, allowed: string[]): boolean;
+/** Resolve the `animate` option into a concrete {@linkcode AnimateConfig} or `null` if disabled. */
+export declare function resolveAnimateConfig(opt: WidgetProviderOptions["animate"]): AnimateConfig | null;
+/**
+ * Create and embed an iframe-based widget into the host page.
+ *
+ * Creates a sandboxed iframe, applies the chosen style preset, wires up
+ * bidirectional postMessage communication, and returns a control API.
+ *
+ * @throws {Error} If `widgetUrl` is not provided.
+ */
+export declare function provideWidget(options: WidgetProviderOptions): WidgetProviderApi;

package/dist/widget-provider.js

@@ -0,0 +1,296 @@
+import { createStore } from "@marianmeres/store";
+import { ANIMATE_PRESETS, applyIframeBaseStyles, applyPreset, STYLE_PRESETS, TRIGGER_BASE, } from "./style-presets.js";
+import { MSG_PREFIX, } from "./types.js";
+const DEFAULT_TRIGGER_ICON = `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/></svg>`;
+/**
+ * Resolve the list of allowed origins for postMessage validation.
+ * Uses explicit value if provided, otherwise derives from widgetUrl. Falls back to `["*"]`.
+ */
+export function resolveAllowedOrigins(explicit, widgetUrl) {
+    if (explicit) {
+        return Array.isArray(explicit) ? explicit : [explicit];
+    }
+    try {
+        return [new URL(widgetUrl).origin];
+    }
+    catch {
+        return ["*"];
+    }
+}
+/** Check whether a given origin is permitted by the allowed origins list. */
+export function isOriginAllowed(origin, allowed) {
+    if (allowed.includes("*"))
+        return true;
+    return allowed.includes(origin);
+}
+/** Resolve the `animate` option into a concrete {@linkcode AnimateConfig} or `null` if disabled. */
+export function resolveAnimateConfig(opt) {
+    if (!opt)
+        return null;
+    if (opt === true)
+        return ANIMATE_PRESETS["fade-scale"];
+    if (typeof opt === "string")
+        return ANIMATE_PRESETS[opt] ?? null;
+    const base = ANIMATE_PRESETS[opt.preset ?? "fade-scale"];
+    if (!base)
+        return null;
+    return opt.transition ? { ...base, transition: opt.transition } : base;
+}
+/**
+ * Create and embed an iframe-based widget into the host page.
+ *
+ * Creates a sandboxed iframe, applies the chosen style preset, wires up
+ * bidirectional postMessage communication, and returns a control API.
+ *
+ * @throws {Error} If `widgetUrl` is not provided.
+ */
+export function provideWidget(options) {
+    const { widgetUrl, parentContainer, stylePreset = "inline", styleOverrides = {}, allowedOrigin, visible = true, sandbox = "allow-scripts allow-same-origin", iframeAttrs = {}, } = options;
+    if (!widgetUrl) {
+        throw new Error("widgetUrl is required");
+    }
+    const origins = resolveAllowedOrigins(allowedOrigin, widgetUrl);
+    const initialPreset = stylePreset;
+    const anim = resolveAnimateConfig(options.animate);
+    // reactive state
+    const state = createStore({
+        visible,
+        ready: false,
+        destroyed: false,
+        preset: stylePreset,
+    });
+    // DOM
+    const container = document.createElement("div");
+    const iframe = document.createElement("iframe");
+    applyPreset(container, stylePreset, styleOverrides);
+    applyIframeBaseStyles(iframe);
+    iframe.src = widgetUrl;
+    if (sandbox) {
+        iframe.setAttribute("sandbox", sandbox);
+    }
+    iframe.setAttribute("allowfullscreen", "");
+    for (const [k, v] of Object.entries(iframeAttrs)) {
+        iframe.setAttribute(k, v);
+    }
+    container.appendChild(iframe);
+    if (anim) {
+        container.style.transition = anim.transition;
+    }
+    if (!visible) {
+        container.style.display = "none";
+        if (anim) {
+            Object.assign(container.style, anim.hidden);
+        }
+    }
+    // messaging
+    const messageHandlers = new Map();
+    function handleMessage(event) {
+        if (!isOriginAllowed(event.origin, origins))
+            return;
+        if (event.source !== iframe.contentWindow)
+            return;
+        const data = event.data;
+        if (!data || typeof data.type !== "string")
+            return;
+        if (!data.type.startsWith(MSG_PREFIX))
+            return;
+        // built-in control messages
+        const bareType = data.type.slice(MSG_PREFIX.length);
+        switch (bareType) {
+            case "ready":
+                state.update((s) => ({ ...s, ready: true }));
+                break;
+            case "maximize":
+                maximize();
+                break;
+            case "minimize":
+                minimize();
+                break;
+            case "hide":
+                hide();
+                break;
+            case "close":
+                destroy();
+                break;
+            case "setPreset":
+                if (typeof data.payload === "string" &&
+                    data.payload in STYLE_PRESETS) {
+                    setPreset(data.payload);
+                }
+                break;
+            case "nativeFullscreen":
+                requestNativeFullscreen();
+                break;
+            case "exitNativeFullscreen":
+                exitNativeFullscreen();
+                break;
+        }
+        const handlers = messageHandlers.get(data.type);
+        if (handlers) {
+            for (const h of handlers) {
+                try {
+                    h(data.payload);
+                }
+                catch (e) {
+                    console.warn("[widget-provider] message handler error:", e);
+                }
+            }
+        }
+    }
+    globalThis.addEventListener("message", handleMessage);
+    // append to DOM
+    const appendTarget = parentContainer || document.body;
+    appendTarget.appendChild(container);
+    // trigger button
+    const triggerOpts = options.trigger;
+    let triggerEl = null;
+    if (triggerOpts) {
+        triggerEl = document.createElement("button");
+        Object.assign(triggerEl.style, TRIGGER_BASE);
+        if (typeof triggerOpts === "object" && triggerOpts.style) {
+            Object.assign(triggerEl.style, triggerOpts.style);
+        }
+        const content = typeof triggerOpts === "object" && triggerOpts.content
+            ? triggerOpts.content
+            : DEFAULT_TRIGGER_ICON;
+        triggerEl.innerHTML = content;
+        if (visible) {
+            triggerEl.style.display = "none";
+        }
+        triggerEl.addEventListener("click", () => show());
+        appendTarget.appendChild(triggerEl);
+    }
+    // API
+    function show() {
+        if (state.get().destroyed)
+            return;
+        if (anim) {
+            Object.assign(container.style, anim.hidden);
+            container.style.display = "";
+            container.offsetHeight; // force reflow
+            Object.assign(container.style, anim.visible);
+        }
+        else {
+            container.style.display = "";
+        }
+        if (triggerEl)
+            triggerEl.style.display = "none";
+        state.update((s) => ({ ...s, visible: true }));
+    }
+    function hide() {
+        if (state.get().destroyed)
+            return;
+        if (triggerEl)
+            triggerEl.style.display = "";
+        state.update((s) => ({ ...s, visible: false }));
+        if (anim) {
+            Object.assign(container.style, anim.hidden);
+            const done = () => {
+                if (!state.get().visible) {
+                    container.style.display = "none";
+                }
+            };
+            container.addEventListener("transitionend", done, {
+                once: true,
+            });
+            setTimeout(done, 250);
+        }
+        else {
+            container.style.display = "none";
+        }
+    }
+    function toggle() {
+        if (state.get().visible)
+            hide();
+        else
+            show();
+    }
+    function setPreset(preset) {
+        if (state.get().destroyed)
+            return;
+        if (!(preset in STYLE_PRESETS))
+            return;
+        container.style.cssText = "";
+        applyPreset(container, preset, styleOverrides);
+        if (anim) {
+            container.style.transition = anim.transition;
+        }
+        if (!state.get().visible) {
+            container.style.display = "none";
+            if (anim) {
+                Object.assign(container.style, anim.hidden);
+            }
+        }
+        state.update((s) => ({ ...s, preset }));
+    }
+    function maximize() {
+        setPreset("fullscreen");
+    }
+    function minimize() {
+        setPreset(initialPreset);
+    }
+    function requestNativeFullscreen() {
+        if (state.get().destroyed)
+            return Promise.resolve();
+        return iframe.requestFullscreen();
+    }
+    function exitNativeFullscreen() {
+        if (!document.fullscreenElement)
+            return Promise.resolve();
+        return document.exitFullscreen();
+    }
+    function destroy() {
+        if (state.get().destroyed)
+            return;
+        globalThis.removeEventListener("message", handleMessage);
+        messageHandlers.clear();
+        iframe.src = "about:blank";
+        container.remove();
+        triggerEl?.remove();
+        state.update((s) => ({
+            visible: false,
+            ready: false,
+            destroyed: true,
+            preset: s.preset,
+        }));
+    }
+    function send(type, payload) {
+        if (state.get().destroyed)
+            return;
+        iframe.contentWindow?.postMessage({ type: `${MSG_PREFIX}${type}`, payload }, origins[0] || "*");
+    }
+    function onMessage(type, handler) {
+        const prefixedType = `${MSG_PREFIX}${type}`;
+        if (!messageHandlers.has(prefixedType)) {
+            messageHandlers.set(prefixedType, new Set());
+        }
+        messageHandlers.get(prefixedType).add(handler);
+        return () => {
+            messageHandlers.get(prefixedType)?.delete(handler);
+        };
+    }
+    return {
+        show,
+        hide,
+        toggle,
+        destroy,
+        setPreset,
+        maximize,
+        minimize,
+        requestNativeFullscreen,
+        exitNativeFullscreen,
+        send,
+        onMessage,
+        subscribe: state.subscribe,
+        get: state.get,
+        get iframe() {
+            return iframe;
+        },
+        get container() {
+            return container;
+        },
+        get trigger() {
+            return triggerEl;
+        },
+    };
+}

package/docs/architecture.md

@@ -0,0 +1,50 @@
+# Architecture
+
+## Overview
+
+Single-function library that creates an iframe-based widget embedded in a host page. The host communicates with the iframe via `postMessage`, with origin validation and namespaced message types.
+
+## Component Map
+
+```
+Host Page (provideWidget caller)
+  │
+  ├── Container <div>        ← styled by preset (float/fullscreen/inline)
+  │     └── <iframe>         ← loads widgetUrl, sandboxed
+  │
+  ├── Trigger <button>       ← optional, auto-toggles visibility
+  │
+  └── State Store            ← @marianmeres/store (visible, ready, destroyed, preset)
+        └── postMessage listener ← origin-validated, prefix-filtered
+```
+
+## Data Flow
+
+```
+Host → iframe:  widget.send(type, payload) → postMessage with MSG_PREFIX
+iframe → Host:  postMessage with MSG_PREFIX → handleMessage → built-in handlers + onMessage callbacks
+
+Built-in control messages (from iframe):
+  ready, maximize, minimize, hide, close, setPreset, nativeFullscreen, exitNativeFullscreen
+```
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/widget-provider.ts` | `provideWidget()` factory — creates DOM, wires messaging, returns API |
+| `src/types.ts` | All types, interfaces, `MSG_PREFIX` constant |
+| `src/style-presets.ts` | CSS preset objects, animation configs, apply functions |
+| `src/mod.ts` | Public barrel export |
+
+## External Dependencies
+
+| Dependency | Purpose |
+|------------|---------|
+| `@marianmeres/store` | Reactive state store (Svelte-compatible subscribe pattern) |
+
+## Security Boundaries
+
+- **Origin validation**: `resolveAllowedOrigins()` derives from `widgetUrl` or uses explicit config. `isOriginAllowed()` checks incoming messages.
+- **Iframe sandbox**: Defaults to `allow-scripts allow-same-origin`. Configurable via `sandbox` option.
+- **Message namespace**: All messages prefixed with `@@__widget_provider__@@` to avoid collisions.

package/docs/conventions.md

@@ -0,0 +1,65 @@
+# Conventions
+
+## File Organisation
+
+- Types and interfaces → `src/types.ts`
+- Style/CSS logic → `src/style-presets.ts`
+- Core implementation → `src/widget-provider.ts`
+- Public exports → `src/mod.ts` (barrel)
+
+## Naming
+
+- Factory function: `provideWidget()` (not `createWidget`)
+- Type names: PascalCase (`WidgetProviderOptions`, `StylePreset`)
+- Constants: UPPER_SNAKE (`MSG_PREFIX`, `STYLE_PRESETS`, `ANIMATE_PRESETS`)
+- Internal helpers: camelCase, not exported from `mod.ts`
+
+## Patterns
+
+### Message Protocol
+All messages use `WidgetMessage` envelope with `MSG_PREFIX`:
+
+```typescript
+// Sending
+send("myEvent", { data: 123 });
+// Wire format: { type: "@@__widget_provider__@@myEvent", payload: { data: 123 } }
+
+// Receiving
+onMessage("myEvent", (payload) => { ... });
+```
+
+### Style Presets
+Presets are plain `Partial<CSSStyleDeclaration>` objects applied via `Object.assign`:
+
+```typescript
+// Adding a new preset:
+// 1. Add to StylePreset union in types.ts
+// 2. Create CSS object in style-presets.ts
+// 3. Add to STYLE_PRESETS record
+```
+
+### State Management
+State is a `@marianmeres/store` instance with `WidgetState` shape. Subscribe with Svelte-compatible pattern:
+
+```typescript
+widget.subscribe((state) => { /* reactive */ });
+widget.get(); // snapshot
+```
+
+## Anti-Patterns
+
+- Do not create multiple `provideWidget()` instances targeting the same container
+- Do not call API methods after `destroy()`
+- Do not use `"*"` for `allowedOrigin` in production
+
+## Testing
+
+- Pure utility functions (`resolveAllowedOrigins`, `isOriginAllowed`) are tested directly
+- DOM-dependent `provideWidget()` requires browser environment (not tested in Deno unit tests)
+- Run: `deno test`
+
+## Formatting
+
+- Tabs for indentation
+- 90 char line width
+- Run `deno fmt` before committing

package/docs/tasks.md

@@ -0,0 +1,71 @@
+# Tasks
+
+## Add a New Style Preset
+
+### Steps
+1. Add preset name to `StylePreset` union in `src/types.ts`
+2. Create CSS object in `src/style-presets.ts` (extend `BASE_CONTAINER`)
+3. Add to `STYLE_PRESETS` record in `src/style-presets.ts`
+
+### Template
+```typescript
+// src/types.ts
+export type StylePreset = "float" | "fullscreen" | "inline" | "new-preset";
+
+// src/style-presets.ts
+const PRESET_NEW: CSSProps = {
+    ...BASE_CONTAINER,
+    // CSS properties
+};
+
+export const STYLE_PRESETS: Record<StylePreset, CSSProps> = {
+    // ... existing
+    "new-preset": PRESET_NEW,
+};
+```
+
+### Checklist
+- [ ] Type union updated
+- [ ] CSS object created
+- [ ] STYLE_PRESETS record updated
+- [ ] `deno test` passes
+
+## Add a New Animation Preset
+
+### Steps
+1. Add preset name to `AnimatePreset` union in `src/types.ts`
+2. Add `AnimateConfig` entry in `ANIMATE_PRESETS` in `src/style-presets.ts`
+
+### Checklist
+- [ ] Type union updated
+- [ ] Preset config added with `transition`, `hidden`, `visible` properties
+
+## Add a New Built-in Control Message
+
+### Steps
+1. Add `case` to `switch (bareType)` in `handleMessage()` in `src/widget-provider.ts`
+2. Implement handler function if needed
+
+### Template
+```typescript
+case "myControl":
+    myControlFunction();
+    break;
+```
+
+### Checklist
+- [ ] Case added to switch
+- [ ] Handler implemented
+- [ ] No-op if destroyed
+
+## Build and Publish
+
+### Steps
+1. Run `deno test` to verify
+2. Run `deno task release` to bump version
+3. Run `deno task publish` to publish to JSR + npm
+
+### Checklist
+- [ ] Tests pass
+- [ ] Version bumped
+- [ ] Published to both registries

package/package.json

@@ -0,0 +1,25 @@
+{
+	"name": "@marianmeres/widget-provider",
+	"version": "1.0.2",
+	"type": "module",
+	"main": "dist/mod.js",
+	"types": "dist/mod.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/mod.d.ts",
+			"import": "./dist/mod.js"
+		}
+	},
+	"author": "Marian Meres",
+	"license": "MIT",
+	"dependencies": {
+		"@marianmeres/store": "^2.4.4"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/marianmeres/widget-provider.git"
+	},
+	"bugs": {
+		"url": "https://github.com/marianmeres/widget-provider/issues"
+	}
+}