@improba/page-builder 0.1.3 → 0.2.1

package/dist/types/core/iframe-bridge.d.ts

@@ -0,0 +1,85 @@
+export declare const IFRAME_BRIDGE_NAMESPACE = "@improba/page-builder/iframe-bridge";
+export declare const IFRAME_BRIDGE_VERSION: 1;
+type IframeBridgeChannel = 'keydown' | 'pointer' | 'lifecycle';
+export type IframeBridgeSessionToken = string;
+interface IframeBridgeEnvelope<TChannel extends IframeBridgeChannel, TPayload> {
+    namespace: typeof IFRAME_BRIDGE_NAMESPACE;
+    version: typeof IFRAME_BRIDGE_VERSION;
+    sessionToken: IframeBridgeSessionToken;
+    channel: TChannel;
+    payload: TPayload;
+}
+export interface IframeBridgeKeydownPayload {
+    key: string;
+    code: string;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    shiftKey: boolean;
+    altKey: boolean;
+    defaultPrevented: boolean;
+    isEditable: boolean;
+}
+export type IframeBridgePointerInteraction = 'hover' | 'select' | 'context';
+interface IframeBridgePointerBasePayload {
+    interaction: IframeBridgePointerInteraction;
+    nodeId: number | null;
+}
+interface IframeBridgePointerContextPayload extends IframeBridgePointerBasePayload {
+    interaction: 'context';
+    clientX: number;
+    clientY: number;
+}
+interface IframeBridgePointerHoverOrSelectPayload extends IframeBridgePointerBasePayload {
+    interaction: 'hover' | 'select';
+}
+export type IframeBridgePointerPayload = IframeBridgePointerContextPayload | IframeBridgePointerHoverOrSelectPayload;
+export interface IframeBridgeLifecyclePayload {
+    state: 'ready';
+}
+export type IframeBridgeKeydownMessage = IframeBridgeEnvelope<'keydown', IframeBridgeKeydownPayload>;
+export type IframeBridgePointerMessage = IframeBridgeEnvelope<'pointer', IframeBridgePointerPayload>;
+export type IframeBridgeLifecycleMessage = IframeBridgeEnvelope<'lifecycle', IframeBridgeLifecyclePayload>;
+export type IframeBridgeMessage = IframeBridgeKeydownMessage | IframeBridgePointerMessage | IframeBridgeLifecycleMessage;
+export declare function createIframeBridgeSessionToken(): IframeBridgeSessionToken;
+export declare function createIframeBridgeReadyMessage(sessionToken: IframeBridgeSessionToken): IframeBridgeLifecycleMessage;
+export declare function createIframeBridgePointerMessage(payload: IframeBridgePointerPayload, sessionToken: IframeBridgeSessionToken): IframeBridgePointerMessage;
+export declare function createIframeBridgeKeydownMessage(payload: IframeBridgeKeydownPayload, sessionToken: IframeBridgeSessionToken): IframeBridgeKeydownMessage;
+export interface ParseIframeBridgeMessageOptions {
+    expectedSessionToken?: IframeBridgeSessionToken;
+    allowLegacyNoSessionToken?: boolean;
+}
+export declare function parseIframeBridgeMessage(value: unknown, options?: ParseIframeBridgeMessageOptions): IframeBridgeMessage | null;
+export interface IframeBridgeParentOptions {
+    hostWindow: Window;
+    expectedSource: Window;
+    expectedOrigin: string;
+    expectedSessionToken?: IframeBridgeSessionToken;
+    allowLegacyNoSessionToken?: boolean;
+    onReady?: () => void;
+    onPointer?: (payload: IframeBridgePointerPayload) => void;
+    onKeydown?: (payload: IframeBridgeKeydownPayload) => void;
+}
+export interface IframeBridgeParent {
+    dispose: () => void;
+}
+export declare function createIframeBridgeParent(options: IframeBridgeParentOptions): IframeBridgeParent;
+export interface IframeBridgeChild {
+    postReady: () => void;
+    postPointer: (payload: IframeBridgePointerPayload) => void;
+    postKeydown: (payload: IframeBridgeKeydownPayload) => void;
+}
+export interface IframeBridgeChildOptions {
+    targetWindow: Window;
+    targetOrigin: string;
+    sessionToken: IframeBridgeSessionToken;
+}
+export declare function createIframeBridgeChild(options: IframeBridgeChildOptions): IframeBridgeChild;
+export interface MountIframeBridgeDomListenersOptions {
+    frameDocument: Document;
+    contentRoot: HTMLElement;
+    bridge: IframeBridgeChild;
+    resolveNodeId: (target: EventTarget | null) => number | null;
+    isEditableTarget: (target: EventTarget | null) => boolean;
+}
+export declare function mountIframeBridgeDomListeners(options: MountIframeBridgeDomListenersOptions): () => void;
+export {};

package/dist/types/core/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Vue-free core utilities for server-side (Node.js) usage.
+ *
+ * This barrel intentionally excludes:
+ * - registry.ts / drop-slot.ts (import Vue's Component type)
+ * - sanitizeRichTextHtml (requires DOM APIs)
+ * - iframe-bridge.ts (browser-only)
+ * - reportDevDiagnostic (uses import.meta.env.DEV)
+ */
+export { cloneTree, findNodeById, findParent, removeNode, insertNode, moveNode, createNode, walkTree, countNodes, getMaxId, interpolateProps, extractPlainText, } from './tree';
+export { validateNode, validatePageData } from './validation';
+export type { IValidationError, IValidationResult } from './validation';
+export { normalizeSafeHtmlTag, sanitizeUrlByKind } from './sanitize';
+export { PageBuilderError, isPageBuilderError, createPageBuilderError, toErrorMessage, } from './errors';
+export type { PageBuilderErrorCode, PageBuilderErrorOptions } from './errors';
+export { flattenTree, computeWindowRange, sliceWindow, createStableNodeKey, createVirtualTreeIndexMaps, } from './virtual-tree';
+export type { IVirtualTreeRow, IVirtualWindowRange, IVirtualTreeIndexMaps, IFlattenTreeOptions, } from './virtual-tree';
+export type { INode, IPageData, IPageMeta, IPageSavePayload, } from '../types/node';

package/dist/types/core/registry.d.ts

@@ -0,0 +1,43 @@
+import type { Component } from 'vue';
+import type { IComponentDefinition } from '@/types/component';
+/**
+ * Register a component for use in the page builder.
+ * Throws if a component with the same name is already registered.
+ */
+export declare function registerComponent(definition: IComponentDefinition): void;
+/**
+ * Register multiple components at once.
+ */
+export declare function registerComponents(definitions: IComponentDefinition[]): void;
+/**
+ * Replace an existing component registration.
+ */
+export declare function replaceComponent(definition: IComponentDefinition): void;
+/**
+ * Unregister a component by name.
+ */
+export declare function unregisterComponent(name: string): boolean;
+/**
+ * Retrieve a component definition by name. Returns undefined if not found.
+ */
+export declare function getComponent(name: string): IComponentDefinition | undefined;
+/**
+ * Retrieve the Vue component for rendering. Throws if not found.
+ */
+export declare function resolveComponent(name: string): Component;
+/**
+ * Get all registered component definitions.
+ */
+export declare function getRegisteredComponents(): IComponentDefinition[];
+/**
+ * Get all registered component definitions grouped by category.
+ */
+export declare function getComponentsByCategory(): Map<string, IComponentDefinition[]>;
+/**
+ * Check if a component is registered.
+ */
+export declare function hasComponent(name: string): boolean;
+/**
+ * Clear all registered components. Mainly useful for testing.
+ */
+export declare function clearRegistry(): void;

package/dist/types/core/sanitize.d.ts

@@ -0,0 +1,3 @@
+export declare function sanitizeRichTextHtml(html: string): string;
+export declare function normalizeSafeHtmlTag(tag: unknown, fallback?: string): string;
+export declare function sanitizeUrlByKind(url: string, kind: 'link' | 'media' | 'background'): string;

package/dist/types/core/tree.d.ts

@@ -0,0 +1,56 @@
+import type { INode } from '@/types/node';
+/**
+ * Deep clone a node tree using structured clone.
+ */
+export declare function cloneTree(node: INode): INode;
+/**
+ * Find a node by ID in the tree. Returns undefined if not found.
+ */
+export declare function findNodeById(root: INode, id: number): INode | undefined;
+/**
+ * Find the parent of a node by the child's ID.
+ * Returns the parent node and the child's index, or undefined.
+ */
+export declare function findParent(root: INode, childId: number): {
+    parent: INode;
+    index: number;
+} | undefined;
+/**
+ * Remove a node by ID from the tree. Returns the removed node or undefined.
+ */
+export declare function removeNode(root: INode, id: number): INode | undefined;
+/**
+ * Insert a node as a child of a target node at a specific index and slot.
+ */
+export declare function insertNode(root: INode, parentId: number, node: INode, index: number, slot?: string): boolean;
+/**
+ * Move a node within the tree to a new parent at a specific index.
+ */
+export declare function moveNode(root: INode, nodeId: number, newParentId: number, index: number, slot?: string): boolean;
+/**
+ * Create a new node with default values and a given ID.
+ */
+export declare function createNode(id: number, name: string, options?: Partial<Pick<INode, 'slot' | 'props' | 'children' | 'readonly'>>): INode;
+/**
+ * Walk the tree depth-first and call visitor for each node.
+ * Return `false` from visitor to stop the entire traversal (not just the subtree).
+ */
+export declare function walkTree(root: INode, visitor: (node: INode, depth: number) => boolean | void, depth?: number): boolean;
+/**
+ * Count the total number of nodes in the tree.
+ */
+export declare function countNodes(root: INode): number;
+/**
+ * Get the maximum ID in the tree.
+ */
+export declare function getMaxId(root: INode): number;
+/**
+ * Interpolate template variables in node props.
+ * Replaces `{{ VAR }}` patterns with values from the variables map.
+ */
+export declare function interpolateProps(props: Record<string, unknown>, variables: Record<string, string>): Record<string, unknown>;
+/**
+ * Extract plain text from a node tree by collecting text content
+ * from PbText (and similar) components and stripping HTML tags.
+ */
+export declare function extractPlainText(node: INode): string;

package/dist/types/core/validation.d.ts

@@ -0,0 +1,10 @@
+export interface IValidationError {
+    path: string;
+    message: string;
+}
+export interface IValidationResult {
+    isValid: boolean;
+    errors: IValidationError[];
+}
+export declare function validateNode(node: unknown, path?: string): IValidationResult;
+export declare function validatePageData(pageData: unknown): IValidationResult;

package/dist/types/core/virtual-tree.d.ts

@@ -0,0 +1,44 @@
+import type { INode } from '@/types/node';
+export interface IVirtualTreeRow {
+    node: INode;
+    id: number;
+    key: string;
+    depth: number;
+    index: number;
+    parentId: number | null;
+}
+export interface IVirtualWindowRange {
+    start: number;
+    end: number;
+    size: number;
+    total: number;
+}
+export interface IVirtualTreeIndexMaps {
+    keyByIndex: string[];
+    indexByKey: Map<string, number>;
+    indexByNodeId: Map<number, number>;
+}
+export interface IFlattenTreeOptions {
+    createKey?: (node: INode) => string;
+}
+export declare function createStableNodeKey(nodeId: number): string;
+/**
+ * Flatten a node tree in depth-first pre-order with depth metadata.
+ * Uses an iterative stack to avoid recursion depth issues on large trees.
+ */
+export declare function flattenTree(root: INode, options?: IFlattenTreeOptions): IVirtualTreeRow[];
+/**
+ * Compute a clamped window range over a flat list.
+ */
+export declare function computeWindowRange(total: number, startIndex: number, windowSize: number, overscan?: number): IVirtualWindowRange;
+/**
+ * Slice a list using a computed virtual window.
+ */
+export declare function sliceWindow<T>(rows: readonly T[], startIndex: number, windowSize: number, overscan?: number): {
+    rows: T[];
+    range: IVirtualWindowRange;
+};
+/**
+ * Build stable key/index lookup maps from flattened tree rows.
+ */
+export declare function createVirtualTreeIndexMaps(rows: readonly IVirtualTreeRow[]): IVirtualTreeIndexMaps;

package/dist/types/i18n/context.d.ts

@@ -0,0 +1,13 @@
+import { type ComputedRef, type InjectionKey } from 'vue';
+import { type TranslationDictionary, type Translator } from './translator';
+export interface PageBuilderI18nOptions {
+    locale?: string;
+    messages?: TranslationDictionary;
+}
+export interface PageBuilderI18nContext {
+    locale: ComputedRef<string>;
+    t: Translator;
+}
+export declare const PAGE_BUILDER_I18N_OPTIONS_KEY: InjectionKey<PageBuilderI18nOptions>;
+export declare const PAGE_BUILDER_I18N_KEY: InjectionKey<PageBuilderI18nContext>;
+export declare function usePageBuilderI18n(): PageBuilderI18nContext;

package/dist/types/i18n/index.d.ts

@@ -0,0 +1,3 @@
+export { DEFAULT_LOCALE, defaultTranslations } from './messages';
+export { createTranslator, mergeTranslations, translate, type TranslationParams, type TranslationDictionary, type Translator, } from './translator';
+export { PAGE_BUILDER_I18N_KEY, PAGE_BUILDER_I18N_OPTIONS_KEY, usePageBuilderI18n, type PageBuilderI18nOptions, type PageBuilderI18nContext, } from './context';

package/dist/types/i18n/messages.d.ts

@@ -0,0 +1,3 @@
+import type { TranslationDictionary } from './translator';
+export declare const DEFAULT_LOCALE = "en";
+export declare const defaultTranslations: TranslationDictionary;

package/dist/types/i18n/translator.d.ts

@@ -0,0 +1,14 @@
+export type TranslationParams = Record<string, string | number>;
+export type TranslationDictionary = Record<string, Record<string, string>>;
+export type Translator = (key: string, params?: TranslationParams) => string;
+interface TranslateOptions {
+    locale: string;
+    dictionary: TranslationDictionary;
+    key: string;
+    params?: TranslationParams;
+    fallbackLocale?: string;
+}
+export declare function mergeTranslations(...dictionaries: Array<TranslationDictionary | undefined | null>): TranslationDictionary;
+export declare function translate(options: TranslateOptions): string;
+export declare function createTranslator(localeSource: string | (() => string), dictionarySource: TranslationDictionary | (() => TranslationDictionary), fallbackLocale?: string): Translator;
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,27 @@
+export { PageBuilderPlugin } from './plugin';
+export type { PageBuilderPluginOptions } from './plugin';
+export { DEFAULT_LOCALE, defaultTranslations, createTranslator, mergeTranslations, translate, usePageBuilderI18n, } from './i18n';
+export type { TranslationDictionary, TranslationParams, Translator, PageBuilderI18nOptions } from './i18n';
+export { default as PageBuilder } from './components/PageBuilder.vue';
+export { default as PageReader } from './components/reader/PageReader.vue';
+export { default as PageEditor } from './components/editor/PageEditor.vue';
+export { default as NodeRenderer } from './components/reader/NodeRenderer.vue';
+export { registerComponent, registerComponents, replaceComponent, unregisterComponent, getComponent, resolveComponent, getRegisteredComponents, getComponentsByCategory, hasComponent, clearRegistry, } from './core/registry';
+export { cloneTree, findNodeById, findParent, removeNode, insertNode, moveNode, createNode, walkTree, countNodes, getMaxId, interpolateProps, extractPlainText, } from './core/tree';
+export { PageBuilderError, isPageBuilderError, } from './core/errors';
+export type { PageBuilderErrorCode, PageBuilderErrorOptions, } from './core/errors';
+export { validateNode, validatePageData } from './core/validation';
+export type { IValidationError, IValidationResult } from './core/validation';
+export { sanitizeRichTextHtml, normalizeSafeHtmlTag, sanitizeUrlByKind } from './core/sanitize';
+export { flattenTree, computeWindowRange, sliceWindow, createStableNodeKey, createVirtualTreeIndexMaps, } from './core/virtual-tree';
+export type { IVirtualTreeRow, IVirtualWindowRange, IVirtualTreeIndexMaps, IFlattenTreeOptions, } from './core/virtual-tree';
+export { usePageBuilder } from './composables/use-page-builder';
+export type { UsePageBuilderOptions, UsePageBuilderReturn } from './composables/use-page-builder';
+export { useEditor } from './composables/use-editor';
+export { useNodeTree } from './composables/use-node-tree';
+export type { UseNodeTreeOptions } from './composables/use-node-tree';
+export { useDragDrop } from './composables/use-drag-drop';
+export type { DragState } from './composables/use-drag-drop';
+export { builtInComponents, PbColumn, PbRow, PbText, PbImage, PbVideo, PbSection, PbContainer } from './built-in';
+export { VIEWPORT_PRESETS, builderOptionsPropType, PAGE_BUILDER_KEY, EDITOR_KEY, NODE_TREE_KEY, DRAG_DROP_KEY, } from './types';
+export type { INode, IPageData, IPageMeta, IPageSavePayload, IComponentDefinition, ISlotDefinition, IPropDefinition, ComponentCategory, PropEditorType, PageBuilderMode, IEditorState, IEditorHistoryEntry, IPageBuilderEvents, ViewportPreset, IViewportDimensions, } from './types';

package/dist/types/plugin.d.ts

@@ -0,0 +1,18 @@
+import type { App } from 'vue';
+import type { IComponentDefinition } from '@/types/component';
+import { type TranslationDictionary } from '@/i18n';
+export interface PageBuilderPluginOptions {
+    /** Custom components to register in addition to built-in ones. */
+    components?: IComponentDefinition[];
+    /** If false, built-in components (PbColumn, PbRow, etc.) won't be registered. Default: true. */
+    registerBuiltIn?: boolean;
+    /** Global component name for <PageBuilder>. Default: 'PageBuilder'. Set to false to skip global registration. */
+    globalName?: string | false;
+    /** Default locale for editor UI text. Can be overridden per <PageBuilder> instance. */
+    locale?: string;
+    /** Additional/overridden translation messages grouped by locale. */
+    messages?: TranslationDictionary;
+}
+export declare const PageBuilderPlugin: {
+    install(app: App, options?: PageBuilderPluginOptions): void;
+};

package/dist/types/types/component.d.ts

@@ -0,0 +1,68 @@
+import type { Component, PropType } from 'vue';
+/**
+ * Metadata describing a page builder component.
+ * Every component registered in the page builder must provide this.
+ */
+export interface IComponentDefinition {
+    /** Unique name used as key in the registry and in INode.name. */
+    name: string;
+    /** Human-readable label shown in the editor palette. */
+    label: string;
+    /** Short description for the editor tooltip. */
+    description?: string;
+    /** Category for grouping in the component palette. */
+    category: ComponentCategory;
+    /** URL or import path of a preview icon/thumbnail for the palette. */
+    icon?: string;
+    /** The Vue component to render. */
+    component: Component;
+    /** Named slots this component exposes for child nodes. */
+    slots: ISlotDefinition[];
+    /** Editable props schema for the right-drawer property editor. */
+    editableProps: IPropDefinition[];
+    /** Default props applied when the component is first added. */
+    defaultProps?: Record<string, unknown>;
+    /** If true, this component cannot be added by users (used for internal wrappers). */
+    hidden?: boolean;
+}
+export type ComponentCategory = 'layout' | 'content' | 'media' | 'navigation' | 'form' | 'data' | 'custom';
+export interface ISlotDefinition {
+    /** Slot name matching Vue's named slot system. */
+    name: string;
+    /** Human-readable label. */
+    label: string;
+    /** Component names allowed in this slot. Empty array = all allowed. */
+    allowedComponents?: string[];
+}
+export interface IPropDefinition {
+    /** Prop key (matches the component prop name). */
+    key: string;
+    /** Human-readable label for the property editor. */
+    label: string;
+    /** Editor widget type. */
+    type: PropEditorType;
+    /** Default value. */
+    defaultValue?: unknown;
+    /** Whether this prop is required. */
+    required?: boolean;
+    /** For 'select' type — available options. */
+    options?: {
+        label: string;
+        value: string | number | boolean;
+    }[];
+    /** Validation rules. */
+    validation?: {
+        min?: number;
+        max?: number;
+        pattern?: string;
+        message?: string;
+    };
+}
+export type PropEditorType = 'text' | 'textarea' | 'richtext' | 'number' | 'boolean' | 'select' | 'color' | 'image' | 'url' | 'json';
+/**
+ * Vue prop type helper for builderOptions.
+ * Components expose this as a static property so the registry can read it.
+ */
+export declare const builderOptionsPropType: {
+    type: PropType<IComponentDefinition>;
+};

package/dist/types/types/editor.d.ts

@@ -0,0 +1,54 @@
+import type { INode, IPageSavePayload } from './node';
+/** Operating mode for the page builder. */
+export type PageBuilderMode = 'read' | 'edit';
+/**
+ * Editor UI state managed by the useEditor composable.
+ * Drag-and-drop state is managed separately by useDragDrop.
+ */
+export interface IEditorState {
+    /** Currently selected node, or null. */
+    selectedNodeId: number | null;
+    /** Currently hovered node, or null. */
+    hoveredNodeId: number | null;
+    /** Whether the left drawer (component palette) is open. */
+    leftDrawerOpen: boolean;
+    /** Whether the right drawer (property editor) is open. */
+    rightDrawerOpen: boolean;
+    /** Undo/redo history stack. */
+    history: IEditorHistoryEntry[];
+    /** Current position in the history stack. */
+    historyIndex: number;
+    /** Dirty flag — true if unsaved changes exist. */
+    isDirty: boolean;
+    /** Viewport scale for the canvas iframe. */
+    canvasScale: number;
+    /** Viewport preset. */
+    viewport: ViewportPreset;
+}
+export interface IEditorHistoryEntry {
+    timestamp: number;
+    label: string;
+    snapshot: string;
+}
+export type ViewportPreset = 'desktop' | 'tablet' | 'mobile' | 'custom';
+export interface IViewportDimensions {
+    width: number;
+    height: number;
+    label: string;
+}
+export interface IViewportSize {
+    width: number;
+    height: number;
+}
+export declare const VIEWPORT_PRESETS: Record<ViewportPreset, IViewportDimensions>;
+/**
+ * Events emitted by the page builder in edit mode.
+ */
+export interface IPageBuilderEvents {
+    /** Emitted when the user saves (Ctrl+S or save button). */
+    save: [payload: IPageSavePayload];
+    /** Emitted when the tree structure changes. */
+    change: [tree: INode];
+    /** Emitted when a node is selected. */
+    select: [nodeId: number | null];
+}

package/dist/types/types/index.d.ts

@@ -0,0 +1,6 @@
+export type { INode, IPageData, IPageMeta, IPageSavePayload, } from './node';
+export type { IComponentDefinition, ISlotDefinition, IPropDefinition, ComponentCategory, PropEditorType, } from './component';
+export { builderOptionsPropType } from './component';
+export type { PageBuilderMode, IEditorState, IEditorHistoryEntry, IPageBuilderEvents, ViewportPreset, IViewportDimensions, } from './editor';
+export { VIEWPORT_PRESETS } from './editor';
+export { PAGE_BUILDER_KEY, EDITOR_KEY, NODE_TREE_KEY, DRAG_DROP_KEY, } from './keys';

package/dist/types/types/keys.d.ts

@@ -0,0 +1,13 @@
+import type { InjectionKey } from 'vue';
+import type { UsePageBuilderReturn } from '@/composables/use-page-builder';
+import type { useEditor } from '@/composables/use-editor';
+import type { useNodeTree } from '@/composables/use-node-tree';
+import type { useDragDrop } from '@/composables/use-drag-drop';
+/**
+ * Typed injection keys for provide/inject across the editor component tree.
+ * Use these instead of raw strings for type-safe inject() calls.
+ */
+export declare const PAGE_BUILDER_KEY: InjectionKey<UsePageBuilderReturn>;
+export declare const EDITOR_KEY: InjectionKey<ReturnType<typeof useEditor>>;
+export declare const NODE_TREE_KEY: InjectionKey<ReturnType<typeof useNodeTree>>;
+export declare const DRAG_DROP_KEY: InjectionKey<ReturnType<typeof useDragDrop>>;

package/dist/types/types/node.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Core tree node representing a single component instance in the page tree.
+ *
+ * The page structure is a recursive tree of INode objects.
+ * Each node maps to a registered component and can contain children
+ * distributed across named slots.
+ */
+export interface INode {
+    /** Unique identifier within the tree. Used for selection, drag-drop, and reconciliation. */
+    id: number;
+    /** Component name — must match a key in the component registry. */
+    name: string;
+    /** Target slot name in the parent component. `null` for the root node. */
+    slot: string | null;
+    /** Props passed to the component instance. Supports template variables via `{{ VAR }}`. */
+    props: Record<string, unknown>;
+    /** Child nodes, rendered into the component's slots. */
+    children: INode[];
+    /** If true, this node cannot be edited, moved, or deleted in edit mode. */
+    readonly?: boolean;
+}
+/**
+ * Full page data structure returned by the backend.
+ * This is the single JSON payload the frontend receives.
+ */
+export interface IPageData {
+    /** Page metadata */
+    meta: IPageMeta;
+    /** The root node of the page content tree. */
+    content: INode;
+    /** The root node of the page layout tree. Layout wraps content. */
+    layout: INode;
+    /** Maximum node ID used in the tree. Incremented when adding new nodes. */
+    maxId: number;
+    /** Variables injected into component props via `{{ VAR }}` syntax. */
+    variables: Record<string, string>;
+}
+export interface IPageMeta {
+    id: string;
+    name: string;
+    url: string;
+    status: 'draft' | 'published' | 'archived';
+    updatedAt?: string;
+    createdAt?: string;
+}
+/**
+ * Serialized page data sent back to the backend on save.
+ * Only the mutable parts are included.
+ */
+export interface IPageSavePayload {
+    content: INode;
+    layout: INode;
+    maxId: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@improba/page-builder",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "A Vue 3 page builder component library — WYSIWYG editor with read/edit modes, custom component registry, and SSR support.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -12,6 +12,11 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./core": {
+      "types": "./dist/types/core/index.d.ts",
+      "import": "./dist/core.js",
+      "require": "./dist/core.cjs"
+    },
     "./style.css": "./dist/style.css"
   },
   "files": [
@@ -25,7 +30,7 @@
   "scripts": {
     "dev": "vite serve playground",
     "build": "vite build",
-    "build:types": "vue-tsc --declaration --emitDeclarationOnly --outDir dist/types",
+    "build:types": "vue-tsc -p tsconfig.build.json",
     "docs:api": "typedoc --options typedoc.json",
     "docs:api:clean": "rm -rf docs/api && npm run docs:api",
     "docs:screenshots": "playwright test tests/e2e/capture-screenshots.spec.ts",
@@ -48,6 +53,9 @@
     "release": "./scripts/release.sh",
     "prepublishOnly": "npm run release:prepare"
   },
+  "dependencies": {
+    "lucide": "^1.8.0"
+  },
   "peerDependencies": {
     "vue": "^3.4.0"
   },

package/dist/index.css

@@ -1 +0,0 @@
-.ipb-error-boundary[data-v-5b429c0c]{width:100%;padding:.75rem;border:1px solid #f3d1d1;border-radius:.375rem;background-color:#fff5f5;color:#7a1f1f}.ipb-error-boundary__message[data-v-5b429c0c]{margin:0;font-size:.9rem;line-height:1.4}.ipb-error-boundary__details[data-v-5b429c0c]{margin:.5rem 0 0;font-size:.75rem;line-height:1.4;white-space:pre-wrap;word-break:break-word;color:#5f1b1b}.ipb-node-renderer__invalid[data-v-40a28160]{width:100%;padding:.75rem;border:1px solid #f3d1d1;border-radius:.375rem;background-color:#fff5f5;color:#7a1f1f;font-size:.825rem;line-height:1.35}.ipb-page-reader[data-v-d9bf9b29]{width:100%;min-height:100%}.ipb-page-reader__invalid[data-v-d9bf9b29]{padding:.75rem;border:1px solid #f3d1d1;border-radius:.375rem;background-color:#fff5f5;color:#7a1f1f;font-size:.875rem}.ipb-toolbar[data-v-7086d88b]{display:flex;align-items:center;justify-content:space-between;height:48px;padding:0 16px;background:var(--ipb-toolbar-bg, #fff);border-bottom:1px solid var(--ipb-border-color, #e0e0e0);flex-shrink:0}.ipb-toolbar__left[data-v-7086d88b],.ipb-toolbar__center[data-v-7086d88b],.ipb-toolbar__right[data-v-7086d88b]{display:flex;align-items:center;gap:8px}.ipb-toolbar__btn[data-v-7086d88b]{padding:6px 12px;border:1px solid var(--ipb-border-color, #e0e0e0);border-radius:4px;background:transparent;cursor:pointer;font-size:13px;transition:background .15s}.ipb-toolbar__btn[data-v-7086d88b]:focus-visible,.ipb-toolbar__size-input[data-v-7086d88b]:focus-visible{outline:2px solid var(--ipb-focus-color, #2563eb);outline-offset:1px}.ipb-toolbar__custom-size[data-v-7086d88b]{display:inline-flex;align-items:center;gap:8px;margin-left:8px;padding-left:8px;border-left:1px solid var(--ipb-border-color, #e0e0e0)}.ipb-toolbar__size-control[data-v-7086d88b]{display:inline-flex;align-items:center;gap:4px;font-size:12px;color:var(--ipb-text-secondary, #4b5563)}.ipb-toolbar__size-input[data-v-7086d88b]{width:72px;padding:4px 6px;border:1px solid var(--ipb-border-color, #e0e0e0);border-radius:4px;font-size:12px}.ipb-toolbar__viewport-size[data-v-7086d88b]{margin-left:8px;color:var(--ipb-text-secondary, #6b7280);font-size:12px;font-variant-numeric:tabular-nums}.ipb-toolbar__btn[data-v-7086d88b]:hover:not(:disabled){background:var(--ipb-hover-bg, #f5f5f5)}.ipb-toolbar__btn[data-v-7086d88b]:disabled{opacity:.4;cursor:not-allowed}.ipb-toolbar__btn--active[data-v-7086d88b]{background:var(--ipb-active-bg, #e8f0fe);border-color:var(--ipb-primary-color, #1a73e8);color:var(--ipb-primary-color, #1a73e8)}.ipb-toolbar__btn--primary[data-v-7086d88b]{background:var(--ipb-primary-color, #1a73e8);color:#fff;border-color:var(--ipb-primary-color, #1a73e8)}.ipb-toolbar__btn--primary[data-v-7086d88b]:hover{background:var(--ipb-primary-hover, #1557b0)}.ipb-toolbar__dirty-indicator[data-v-7086d88b]{color:var(--ipb-warning-color, #f59e0b);font-size:10px}.ipb-tree-panel[data-v-f50f228d]{min-width:0}.ipb-tree-panel__list[data-v-f50f228d]{display:flex;flex-direction:column;gap:2px}.ipb-tree-panel__row-wrapper[data-v-f50f228d]{display:flex;flex-direction:column;gap:0}.ipb-tree-panel__drop-line[data-v-f50f228d]{min-height:8px;margin:0 8px;padding:3px 0;flex-shrink:0;display:flex;align-items:center;cursor:default}.ipb-tree-panel__drop-line[data-v-f50f228d]:before{content:"";display:block;width:100%;height:2px;border-radius:1px;background:var(--ipb-primary-color, #1d4ed8)}.ipb-tree-panel__item[data-v-f50f228d]{display:flex;align-items:center;gap:6px;width:100%;min-width:0;padding:6px 8px;border:0;border-radius:4px;background:transparent;color:inherit;text-align:left;cursor:pointer;font-size:12px;line-height:1.3}.ipb-tree-panel__item[data-v-f50f228d]:hover{background:var(--ipb-hover-bg, #f5f5f5)}.ipb-tree-panel__item[data-v-f50f228d]:focus-visible{outline:2px solid var(--ipb-focus-color, #2563eb);outline-offset:-1px}.ipb-tree-panel__item--selected[data-v-f50f228d]{background:var(--ipb-primary-soft, rgba(37, 99, 235, .14));color:var(--ipb-primary-color, #1d4ed8)}.ipb-tree-panel__item--readonly[data-v-f50f228d]{opacity:.8}.ipb-tree-panel__item--drop-target[data-v-f50f228d]{background:var(--ipb-primary-soft, rgba(37, 99, 235, .2));outline:2px dashed var(--ipb-primary-color, #1d4ed8);outline-offset:2px}.ipb-tree-panel__item--draggable[data-v-f50f228d]{cursor:grab}.ipb-tree-panel__item--draggable[data-v-f50f228d]:active{cursor:grabbing}.ipb-tree-panel__name[data-v-f50f228d]{font-weight:500;white-space:nowrap}.ipb-tree-panel__id[data-v-f50f228d]{color:var(--ipb-text-muted, #6b7280);font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,monospace;font-size:11px;white-space:nowrap}.ipb-tree-panel__readonly[data-v-f50f228d]{margin-left:auto;font-size:10px;text-transform:uppercase;letter-spacing:.03em;color:var(--ipb-text-muted, #6b7280);border:1px solid var(--ipb-border-color, #d1d5db);border-radius:3px;padding:1px 4px}.ipb-left-drawer[data-v-2bb04ccb]{width:48px;background:var(--ipb-drawer-bg, #fff);border-right:1px solid var(--ipb-border-color, #e0e0e0);transition:width .2s ease;overflow:hidden;flex-shrink:0;display:flex;flex-direction:column}.ipb-left-drawer--open[data-v-2bb04ccb]{width:260px}.ipb-left-drawer__header[data-v-2bb04ccb]{display:flex;align-items:center;justify-content:space-between;gap:8px;min-width:0;padding:12px;border-bottom:1px solid var(--ipb-border-color, #e0e0e0)}.ipb-left-drawer__title[data-v-2bb04ccb]{font-weight:600;font-size:14px;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.ipb-left-drawer__toggle[data-v-2bb04ccb]{flex-shrink:0;background:none;border:none;cursor:pointer;font-size:12px;padding:4px}.ipb-left-drawer__toggle[data-v-2bb04ccb]:focus-visible,.ipb-left-drawer__section-toggle[data-v-2bb04ccb]:focus-visible{outline:2px solid var(--ipb-focus-color, #2563eb);outline-offset:1px;border-radius:4px}.ipb-left-drawer__content[data-v-2bb04ccb]{flex:1;overflow-y:auto;padding:12px;display:flex;flex-direction:column;gap:12px}.ipb-left-drawer__section[data-v-2bb04ccb]{min-width:0}.ipb-left-drawer__search[data-v-2bb04ccb]{margin-top:8px;margin-bottom:8px}.ipb-left-drawer__search-input[data-v-2bb04ccb]{width:100%;padding:6px 8px;border:1px solid var(--ipb-border-color, #e0e0e0);border-radius:4px;background:var(--ipb-input-bg, #fff);color:var(--ipb-text-color, #111827);font-size:12px}.ipb-left-drawer__search-input[data-v-2bb04ccb]:focus-visible{outline:2px solid var(--ipb-focus-color, #2563eb);outline-offset:1px}.ipb-left-drawer__section--tree[data-v-2bb04ccb]{padding-top:8px;border-top:1px solid var(--ipb-border-color, #e0e0e0)}.ipb-left-drawer__section-header[data-v-2bb04ccb]{display:flex;align-items:center;justify-content:space-between;margin-bottom:8px}.ipb-left-drawer__section-title[data-v-2bb04ccb]{margin:0;font-size:12px;text-transform:uppercase;letter-spacing:.05em;color:var(--ipb-text-muted, #6b7280)}.ipb-left-drawer__section-toggle[data-v-2bb04ccb]{background:none;border:none;cursor:pointer;padding:2px 4px;font-size:14px;line-height:1}.ipb-left-drawer__category-title[data-v-2bb04ccb]{font-size:11px;font-weight:600;margin:10px 0 8px}.ipb-left-drawer__component-list[data-v-2bb04ccb]{display:flex;flex-direction:column;gap:4px}.ipb-left-drawer__component-item[data-v-2bb04ccb]{display:flex;align-items:center;gap:8px;padding:8px;border-radius:4px;cursor:grab;transition:background .15s;font-size:13px;width:100%;border:0;background:transparent;color:inherit;text-align:left}.ipb-left-drawer__component-item[data-v-2bb04ccb]:hover{background:var(--ipb-hover-bg, #f5f5f5)}.ipb-left-drawer__component-item[data-v-2bb04ccb]:focus-visible{outline:2px solid var(--ipb-focus-color, #2563eb);outline-offset:-1px}.ipb-left-drawer__component-icon[data-v-2bb04ccb]{font-size:16px;width:24px;text-align:center}.ipb-left-drawer__empty[data-v-2bb04ccb]{margin:8px 0 0;font-size:12px;color:var(--ipb-text-muted, #6b7280)}.ipb-prop-editor[data-v-f48156f6]{width:100%;padding:6px 8px;border:1px solid var(--ipb-border-color, #e0e0e0);border-radius:4px;font-size:13px;box-sizing:border-box}.ipb-prop-editor[data-v-f48156f6]:focus-visible{outline:2px solid var(--ipb-focus-color, #2563eb);outline-offset:1px}.ipb-prop-editor[data-v-11786ace]{width:100%;padding:6px 8px;border:1px solid var(--ipb-border-color, #e0e0e0);border-radius:4px;font-size:13px;box-sizing:border-box}.ipb-prop-editor[data-v-11786ace]:focus-visible{outline:2px solid var(--ipb-focus-color, #2563eb);outline-offset:1px}.ipb-prop-editor--boolean[data-v-cfba94a9]{display:inline-flex;align-items:center;gap:8px;font-size:13px;-webkit-user-select:none;user-select:none}.ipb-prop-editor--boolean input[data-v-cfba94a9]:focus-visible{outline:2px solid var(--ipb-focus-color, #2563eb);outline-offset:2px}.ipb-prop-editor[data-v-8c477cbd]{width:100%;padding:6px 8px;border:1px solid var(--ipb-border-color, #e0e0e0);border-radius:4px;font-size:13px;box-sizing:border-box;background:var(--ipb-drawer-bg, #fff)}.ipb-prop-editor[data-v-8c477cbd]:focus-visible{outline:2px solid var(--ipb-focus-color, #2563eb);outline-offset:1px}.ipb-prop-editor--color[data-v-b0f904c5]{display:flex;align-items:center;gap:8px}.ipb-prop-editor__picker[data-v-b0f904c5]{width:40px;height:32px;padding:2px;border:1px solid var(--ipb-border-color, #e0e0e0);border-radius:4px;background:var(--ipb-drawer-bg, #fff)}.ipb-prop-editor__text[data-v-b0f904c5]{flex:1;min-width:0;padding:6px 8px;border:1px solid var(--ipb-border-color, #e0e0e0);border-radius:4px;font-size:13px;box-sizing:border-box}.ipb-prop-editor__picker[data-v-b0f904c5]:focus-visible,.ipb-prop-editor__text[data-v-b0f904c5]:focus-visible{outline:2px solid var(--ipb-focus-color, #2563eb);outline-offset:1px}.ipb-richtext-editor[data-v-d9cdfb46]{border:1px solid var(--ipb-border-color, #e0e0e0);border-radius:4px;overflow:hidden}.ipb-richtext-editor__toolbar[data-v-d9cdfb46]{display:flex;flex-wrap:wrap;gap:4px;padding:6px;border-bottom:1px solid var(--ipb-border-color, #e0e0e0);background:var(--ipb-surface-muted, #f8fafc)}.ipb-richtext-editor__toolbar button[data-v-d9cdfb46]{min-width:30px;height:28px;padding:0 8px;border:1px solid var(--ipb-border-color, #d1d5db);border-radius:4px;background:var(--ipb-drawer-bg, #fff);cursor:pointer;font-size:12px}.ipb-richtext-editor__toolbar button[data-v-d9cdfb46]:hover{background:var(--ipb-surface-hover, #f3f4f6)}.ipb-richtext-editor__toolbar button[data-v-d9cdfb46]:focus-visible,.ipb-richtext-editor__content[data-v-d9cdfb46]:focus-visible{outline:2px solid var(--ipb-focus-color, #2563eb);outline-offset:1px}.ipb-richtext-editor__content[data-v-d9cdfb46]{min-height:120px;padding:8px;font-size:13px;line-height:1.5;outline:none}.ipb-richtext-editor__content[data-v-d9cdfb46]:empty:before{content:attr(data-placeholder);color:var(--ipb-text-muted, #9ca3af);pointer-events:none}.ipb-media-picker[data-v-743fe73e]{display:flex;flex-direction:column;gap:8px}.ipb-media-picker__controls[data-v-743fe73e]{display:grid;grid-template-columns:minmax(0,1fr) auto auto;gap:8px;align-items:center}.ipb-media-picker__input[data-v-743fe73e]{min-width:0;width:100%;padding:6px 8px;border:1px solid var(--ipb-border-color, #e0e0e0);border-radius:4px;font-size:13px;box-sizing:border-box}.ipb-media-picker__btn[data-v-743fe73e]{padding:6px 8px;border:1px solid var(--ipb-border-color, #e0e0e0);border-radius:4px;background:var(--ipb-drawer-bg, #fff);cursor:pointer;font-size:12px}.ipb-media-picker__input[data-v-743fe73e]:focus-visible,.ipb-media-picker__btn[data-v-743fe73e]:focus-visible{outline:2px solid var(--ipb-focus-color, #2563eb);outline-offset:1px}.ipb-media-picker__btn[data-v-743fe73e]:disabled{opacity:.5;cursor:not-allowed}.ipb-media-picker__preview[data-v-743fe73e]{border:1px dashed var(--ipb-border-color, #e0e0e0);border-radius:4px;padding:6px;min-height:88px;display:flex;align-items:center;justify-content:center;background:var(--ipb-bg-subtle, #fafafa)}.ipb-media-picker__image[data-v-743fe73e]{max-width:100%;max-height:140px;object-fit:contain;display:block}.ipb-media-picker__empty[data-v-743fe73e]{margin:0;font-size:12px;color:var(--ipb-text-muted, #6b7280);text-align:center}.ipb-right-drawer[data-v-a25cd890]{width:48px;background:var(--ipb-drawer-bg, #fff);border-left:1px solid var(--ipb-border-color, #e0e0e0);transition:width .2s ease;overflow:hidden;flex-shrink:0;display:flex;flex-direction:column}.ipb-right-drawer--open[data-v-a25cd890]{width:320px}.ipb-right-drawer__header[data-v-a25cd890]{display:flex;align-items:center;justify-content:space-between;gap:8px;min-width:0;padding:12px;border-bottom:1px solid var(--ipb-border-color, #e0e0e0)}.ipb-right-drawer__title[data-v-a25cd890]{font-weight:600;font-size:14px;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.ipb-right-drawer__toggle[data-v-a25cd890]{flex-shrink:0;background:none;border:none;cursor:pointer;font-size:12px;padding:4px}.ipb-right-drawer__toggle[data-v-a25cd890]:focus-visible,.ipb-right-drawer__btn[data-v-a25cd890]:focus-visible{outline:2px solid var(--ipb-focus-color, #2563eb);outline-offset:1px}.ipb-right-drawer__content[data-v-a25cd890]{flex:1;overflow-y:auto;padding:16px}.ipb-right-drawer__section[data-v-a25cd890]{margin-bottom:20px}.ipb-right-drawer__section-title[data-v-a25cd890]{font-size:16px;font-weight:600;margin:0 0 4px}.ipb-right-drawer__section-subtitle[data-v-a25cd890]{font-size:12px;text-transform:uppercase;letter-spacing:.05em;color:var(--ipb-text-muted, #6b7280);margin:0 0 12px}.ipb-right-drawer__description[data-v-a25cd890]{font-size:13px;color:var(--ipb-text-muted, #6b7280);margin:0}.ipb-right-drawer__prop[data-v-a25cd890]{margin-bottom:12px}.ipb-right-drawer__prop-label[data-v-a25cd890]{display:block;font-size:12px;font-weight:500;margin-bottom:4px}.ipb-right-drawer__prop-editor[data-v-a25cd890]{width:100%}.ipb-right-drawer__actions[data-v-a25cd890]{display:flex;gap:8px;padding-top:16px;border-top:1px solid var(--ipb-border-color, #e0e0e0)}.ipb-right-drawer__btn[data-v-a25cd890]{flex:1;padding:8px;border:1px solid var(--ipb-border-color, #e0e0e0);border-radius:4px;background:transparent;cursor:pointer;font-size:13px}.ipb-right-drawer__btn--danger[data-v-a25cd890]{color:var(--ipb-danger-color, #dc2626);border-color:var(--ipb-danger-color, #dc2626)}.ipb-right-drawer__btn--danger[data-v-a25cd890]:disabled{opacity:.4;cursor:not-allowed}.ipb-right-drawer__empty[data-v-a25cd890]{padding:24px 16px;text-align:center;color:var(--ipb-text-muted, #6b7280);font-size:13px}.ipb-node-context-menu[data-v-7a59845f]{position:absolute;z-index:30;display:flex;flex-direction:column;min-width:148px;padding:6px;border:1px solid var(--ipb-border-color, #d1d5db);border-radius:8px;background:#fff;box-shadow:0 8px 24px #0f172a29}.ipb-node-context-menu__item[data-v-7a59845f]{border:0;border-radius:6px;background:transparent;color:var(--ipb-text-color, #111827);font-size:13px;line-height:1.4;text-align:left;padding:7px 10px;cursor:pointer}.ipb-node-context-menu__item[data-v-7a59845f]:hover:not(:disabled){background:#3b82f61a}.ipb-node-context-menu__item[data-v-7a59845f]:focus-visible{outline:2px solid var(--ipb-focus-color, #2563eb);outline-offset:-1px}.ipb-node-context-menu__item--danger[data-v-7a59845f]{color:var(--ipb-danger-color, #dc2626)}.ipb-node-context-menu__item[data-v-7a59845f]:disabled{opacity:.45;cursor:not-allowed}.ipb-canvas[data-v-3d599a49]{flex:1;display:flex;align-items:flex-start;justify-content:center;padding:24px;overflow:auto;background:var(--ipb-canvas-bg, #e5e7eb)}.ipb-canvas__viewport[data-v-3d599a49]{position:relative;flex:0 0 auto;background:#fff;box-shadow:0 1px 3px #0000001f,0 1px 2px #0000000f;border-radius:4px;overflow:hidden;transition:width .2s ease,height .2s ease}.ipb-iframe-canvas__stage[data-v-3d599a49]{position:relative;width:100%;height:100%;background:#fff}.ipb-iframe-canvas__frame[data-v-3d599a49]{width:100%;height:100%;border:0;display:block;background:#fff}.ipb-iframe-canvas__fallback[data-v-3d599a49]{position:relative;width:100%;height:100%;background:#fff}.ipb-canvas__overlay[data-v-3d599a49]{position:absolute;pointer-events:none;border-radius:4px;box-sizing:border-box}.ipb-canvas__overlay--hovered[data-v-3d599a49]{border:1px dashed rgba(59,130,246,.75);background:#3b82f614;z-index:10}.ipb-canvas__overlay--drop[data-v-3d599a49]{border:2px dashed rgba(16,185,129,.9);background:#10b98124;z-index:12}.ipb-canvas__overlay--selected[data-v-3d599a49]{border:2px solid rgba(37,99,235,.95);background:#2563eb24;box-shadow:0 0 0 1px #ffffffd9 inset;z-index:11}.ipb-page-editor[data-v-2a96c483]{display:flex;flex-direction:column;height:100vh;width:100vw;overflow:hidden;background:var(--ipb-editor-bg, #f0f2f5)}.ipb-page-editor__body[data-v-2a96c483]{display:flex;flex:1;overflow:hidden}.ipb-page-builder__warning[data-v-84b8d079]{margin-bottom:.5rem;padding:.625rem .75rem;border:1px solid #f8d7a8;border-radius:.375rem;background-color:#fff8ec;color:#7d4a00;font-size:.875rem}