@milaboratories/milaboratories.pool-explorer.model 1.0.125 → 1.1.0

package/dist/bundle.js

@@ -4,14 +4,84 @@
     (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["block-model"] = {}));
 })(this, (function (exports) { 'use strict';
 
-    //
-    // Helpers
-    //
-    //
-    // Json
-    //
-    function getImmediate(value) {
-        return { type: 'Immediate', value };
+    /**
+     * BlockStorage - Typed storage abstraction for block persistent data.
+     *
+     * This module provides:
+     * - A typed structure for block storage with versioning and plugin support
+     * - Utility functions for manipulating storage
+     * - Handler interfaces for model-level customization
+     *
+     * @module block_storage
+     */
+    // =============================================================================
+    // Core Types
+    // =============================================================================
+    /**
+     * Discriminator key for BlockStorage format detection.
+     * This unique hash-based key identifies data as BlockStorage vs legacy formats.
+     */
+    const BLOCK_STORAGE_KEY = '__pl_a7f3e2b9__';
+    /**
+     * Current BlockStorage schema version.
+     * Increment this when the storage structure itself changes (not block state migrations).
+     */
+    const BLOCK_STORAGE_SCHEMA_VERSION = 'v1';
+    /**
+     * Type guard to check if a value is a valid BlockStorage object.
+     * Checks for the discriminator key and valid schema version.
+     */
+    function isBlockStorage(value) {
+        if (value === null || typeof value !== 'object')
+            return false;
+        const obj = value;
+        const schemaVersion = obj[BLOCK_STORAGE_KEY];
+        // Currently only 'v1' is valid, but this allows future versions
+        return schemaVersion === 'v1'; // Add more versions as schema evolves
+    }
+    // =============================================================================
+    // Factory Functions
+    // =============================================================================
+    /**
+     * Creates a BlockStorage with the given initial data
+     *
+     * @param initialData - The initial data value (defaults to empty object)
+     * @param version - The initial data version (defaults to 1)
+     * @returns A new BlockStorage instance with discriminator key
+     */
+    function createBlockStorage(initialData = {}, version = 1) {
+        return {
+            [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,
+            __dataVersion: version,
+            __data: initialData,
+        };
+    }
+    // =============================================================================
+    // Data Access & Update Functions
+    // =============================================================================
+    /**
+     * Gets the data from BlockStorage
+     *
+     * @param storage - The BlockStorage instance
+     * @returns The data value
+     */
+    function getStorageData(storage) {
+        return storage.__data;
+    }
+    /**
+     * Updates the data in BlockStorage (immutable)
+     *
+     * @param storage - The current BlockStorage
+     * @param payload - The update payload with operation and value
+     * @returns A new BlockStorage with updated data
+     */
+    function updateStorageData(storage, payload) {
+        switch (payload.operation) {
+            case 'update-data':
+                return { ...storage, __data: payload.value };
+            default:
+                throw new Error(`Unknown storage operation: ${payload.operation}`);
+        }
     }
 
     /** Utility code helping to identify whether the code is running in actual UI environment */
@@ -48,6 +118,41 @@
         ctx.callbackRegistry[key] = callback;
         return true;
     }
+    /**
+     * Registers a callback, replacing any existing callback with the same key.
+     * Use this for callbacks that have a default value but can be overridden.
+     *
+     * @param key - The callback registry key
+     * @param callback - The callback function to register
+     * @returns true if registered, false if not in render context
+     */
+    function replaceCallback(key, callback) {
+        const ctx = tryGetCfgRenderCtx();
+        if (ctx === undefined)
+            return false;
+        ctx.callbackRegistry[key] = callback;
+        return true;
+    }
+    /** Creates a ConfigRenderLambda descriptor without registering a callback. */
+    function createRenderLambda(opts) {
+        const { handle, ...flags } = opts;
+        return {
+            __renderLambda: true,
+            handle,
+            ...flags,
+        };
+    }
+    /** Registers a callback and returns a ConfigRenderLambda descriptor. */
+    function createAndRegisterRenderLambda(opts, replace) {
+        const { handle, lambda, ...flags } = opts;
+        if (replace) {
+            replaceCallback(handle, lambda);
+        }
+        else {
+            tryRegisterCallback(handle, lambda);
+        }
+        return createRenderLambda({ handle, ...flags });
+    }
     const futureResolves = new Map();
     function registerFutureAwait(handle, onResolve) {
         if (!(handle in getCfgRenderCtx().callbackRegistry)) {
@@ -6088,10 +6193,15 @@
             }
             return result;
         };
-        // Checks if a result has all unique labels
-        const hasUniqueLabels = (result) => result !== undefined && new Set(result.map((c) => c.label)).size === values.length;
+        const countUniqueLabels = (result) => result === undefined ? 0 : new Set(result.map((c) => c.label)).size;
         // Post-processing: try removing types one by one (lowest importance first) to minimize the label set
+        // Accepts removal if it doesn't decrease the number of unique labels (cardinality)
         const minimizeTypeSet = (typeSet) => {
+            const initialResult = calculate(typeSet);
+            if (initialResult === undefined) {
+                return typeSet;
+            }
+            const currentCardinality = countUniqueLabels(initialResult);
             // Get types sorted by importance ascending (lowest first), excluding forced elements
             const removableSorted = [...typeSet]
                 .filter((t) => !forceTraceElements?.has(t.split('@')[0])
@@ -6101,7 +6211,7 @@
                 const reducedSet = new Set(typeSet);
                 reducedSet.delete(typeToRemove);
                 const candidateResult = calculate(reducedSet);
-                if (hasUniqueLabels(candidateResult)) {
+                if (candidateResult !== undefined && countUniqueLabels(candidateResult) >= currentCardinality) {
                     typeSet.delete(typeToRemove);
                 }
             }
@@ -6132,7 +6242,7 @@
             if (additionalType >= 0)
                 currentSet.add(mainTypes[additionalType]);
             const candidateResult = calculate(currentSet);
-            if (hasUniqueLabels(candidateResult)) {
+            if (candidateResult !== undefined && countUniqueLabels(candidateResult) === values.length) {
                 minimizeTypeSet(currentSet);
                 return calculate(currentSet);
             }
@@ -7248,28 +7358,19 @@
         }
     }
     /** Main entry point to the API available within model lambdas (like outputs, sections, etc..) */
-    class RenderCtx {
+    class RenderCtxBase {
         ctx;
         constructor() {
             this.ctx = getCfgRenderCtx();
         }
-        _argsCache;
-        get args() {
-            if (this._argsCache === undefined) {
-                const raw = this.ctx.args;
-                const value = typeof raw === 'function' ? raw() : raw;
-                this._argsCache = { v: JSON.parse(value) };
-            }
-            return this._argsCache.v;
-        }
-        _uiStateCache;
-        get uiState() {
-            if (this._uiStateCache === undefined) {
-                const raw = this.ctx.uiState;
+        _dataCache;
+        get data() {
+            if (this._dataCache === undefined) {
+                const raw = this.ctx.data;
                 const value = typeof raw === 'function' ? raw() : raw;
-                this._uiStateCache = { v: value ? JSON.parse(value) : {} };
+                this._dataCache = { v: value ? JSON.parse(value) : {} };
             }
-            return this._uiStateCache.v;
+            return this._dataCache.v;
         }
         // lazy rendering because this feature is rarely used
         _activeArgsCache;
@@ -7380,8 +7481,21 @@
             this.ctx.logError(msg);
         }
     }
+    /** Main entry point to the API available within model lambdas (like outputs, sections, etc..) for v3+ blocks */
+    class RenderCtx extends RenderCtxBase {
+        _argsCache;
+        get args() {
+            if (this._argsCache === undefined) {
+                const raw = this.ctx.args;
+                const value = typeof raw === 'function' ? raw() : raw;
+                // args can be undefined when derivation fails (e.g., validation error in args())
+                this._argsCache = { v: value === undefined ? undefined : JSON.parse(value) };
+            }
+            return this._argsCache.v;
+        }
+    }
 
-    var version = "1.51.6";
+    var version = "1.52.0";
 
     const PlatformaSDKVersion = version;
 
@@ -7397,56 +7511,315 @@
         return data;
     }
 
+    /**
+     * BlockStorage VM Integration - Internal module for VM-based storage operations.
+     *
+     * This module auto-registers internal callbacks that the middle layer can invoke
+     * to perform storage transformations. Block developers never interact with these
+     * directly - they only see `state`.
+     *
+     * Registered callbacks (all prefixed with `__pl_` for internal SDK use):
+     * - `__pl_storage_normalize`: (rawStorage) => { storage, data }
+     * - `__pl_storage_applyUpdate`: (currentStorageJson, payload) => updatedStorageJson
+     * - `__pl_storage_getInfo`: (rawStorage) => JSON string with storage info
+     * - `__pl_storage_migrate`: (currentStorageJson) => MigrationResult
+     * - `__pl_args_derive`: (storageJson) => ArgsDeriveResult
+     * - `__pl_prerunArgs_derive`: (storageJson) => ArgsDeriveResult
+     *
+     * Callbacks registered by DataModel.registerCallbacks():
+     * - `__pl_data_initial`: () => initial data
+     * - `__pl_data_upgrade`: (versioned) => UpgradeResult
+     * - `__pl_storage_initial`: () => initial BlockStorage as JSON string
+     *
+     * @module block_storage_vm
+     * @internal
+     */
+    /**
+     * Normalizes raw storage data and extracts state.
+     * Handles all formats:
+     * - New BlockStorage format (has discriminator)
+     * - Legacy V1/V2 format ({ args, uiState })
+     * - Raw V3 state (any other format)
+     *
+     * @param rawStorage - Raw data from blockStorage field (may be JSON string or object)
+     * @returns Object with normalized storage and extracted state
+     */
+    function normalizeStorage(rawStorage) {
+        // Handle undefined/null
+        if (rawStorage === undefined || rawStorage === null) {
+            const storage = createBlockStorage({});
+            return { storage, data: {} };
+        }
+        // Parse JSON string if needed
+        let parsed = rawStorage;
+        if (typeof rawStorage === 'string') {
+            try {
+                parsed = JSON.parse(rawStorage);
+            }
+            catch {
+                // If parsing fails, treat string as the data
+                const storage = createBlockStorage(rawStorage);
+                return { storage, data: rawStorage };
+            }
+        }
+        // Check for BlockStorage format (has discriminator)
+        if (isBlockStorage(parsed)) {
+            return { storage: parsed, data: getStorageData(parsed) };
+        }
+        // Check for legacy V1/V2 format: { args, uiState }
+        if (isLegacyModelV1ApiFormat(parsed)) {
+            // For legacy format, the whole object IS the data
+            const storage = createBlockStorage(parsed);
+            return { storage, data: parsed };
+        }
+        // Raw V3 data - wrap it
+        const storage = createBlockStorage(parsed);
+        return { storage, data: parsed };
+    }
+    /**
+     * Applies a state update to existing storage.
+     * Used when setData is called from the frontend.
+     *
+     * @param currentStorageJson - Current storage as JSON string (must be defined)
+     * @param newData - New data from application
+     * @returns Updated storage as JSON string
+     */
+    function applyStorageUpdate(currentStorageJson, payload) {
+        const { storage: currentStorage } = normalizeStorage(currentStorageJson);
+        // Update data while preserving other storage fields (version, plugins)
+        const updatedStorage = updateStorageData(currentStorage, payload);
+        return JSON.stringify(updatedStorage);
+    }
+    /**
+     * Checks if data is in legacy Model API v1 format.
+     * Legacy format has { args, uiState? } at top level without the BlockStorage discriminator.
+     */
+    function isLegacyModelV1ApiFormat(data) {
+        if (data === null || typeof data !== 'object')
+            return false;
+        if (isBlockStorage(data))
+            return false;
+        const obj = data;
+        return 'args' in obj;
+    }
+    // =============================================================================
+    // Auto-register internal callbacks when module is loaded in VM
+    // =============================================================================
+    // Register normalize callback
+    tryRegisterCallback('__pl_storage_normalize', (rawStorage) => {
+        return normalizeStorage(rawStorage);
+    });
+    // Register apply update callback (requires existing storage)
+    tryRegisterCallback('__pl_storage_applyUpdate', (currentStorageJson, payload) => {
+        return applyStorageUpdate(currentStorageJson, payload);
+    });
+    /**
+     * Gets storage info from raw storage data.
+     * Returns structured info about the storage state.
+     *
+     * @param rawStorage - Raw data from blockStorage field (may be JSON string or object)
+     * @returns JSON string with storage info
+     */
+    function getStorageInfo(rawStorage) {
+        const { storage } = normalizeStorage(rawStorage);
+        const info = {
+            dataVersion: storage.__dataVersion,
+        };
+        return JSON.stringify(info);
+    }
+    // Register get info callback
+    tryRegisterCallback('__pl_storage_getInfo', (rawStorage) => {
+        return getStorageInfo(rawStorage);
+    });
+    /**
+     * Runs storage migration using the DataModel's upgrade callback.
+     * This is the main entry point for the middle layer to trigger migrations.
+     *
+     * Uses the '__pl_data_upgrade' callback registered by DataModel.registerCallbacks() which:
+     * - Handles all migration logic internally
+     * - Returns { version, data, warning? } - warning present if reset to initial data
+     *
+     * @param currentStorageJson - Current storage as JSON string (or undefined)
+     * @returns MigrationResult
+     */
+    function migrateStorage(currentStorageJson) {
+        // Get the callback registry context
+        const ctx = tryGetCfgRenderCtx();
+        if (ctx === undefined) {
+            return { error: 'Not in config rendering context' };
+        }
+        // Normalize storage to get current data and version
+        const { storage: currentStorage, data: currentData } = normalizeStorage(currentStorageJson);
+        const currentVersion = currentStorage.__dataVersion;
+        // Helper to create storage with given data and version
+        const createStorageJson = (data, version) => {
+            return JSON.stringify({
+                ...currentStorage,
+                __dataVersion: version,
+                __data: data,
+            });
+        };
+        // Get the upgrade callback (registered by DataModel.registerCallbacks())
+        const upgradeCallback = ctx.callbackRegistry['__pl_data_upgrade'];
+        if (typeof upgradeCallback !== 'function') {
+            return { error: '__pl_data_upgrade callback not found (DataModel not registered)' };
+        }
+        // Call the migrator's upgrade function
+        let result;
+        try {
+            result = upgradeCallback({ version: currentVersion, data: currentData });
+        }
+        catch (e) {
+            const errorMsg = e instanceof Error ? e.message : String(e);
+            return { error: `upgrade() threw: ${errorMsg}` };
+        }
+        // Build info message
+        const info = result.version === currentVersion
+            ? `No migration needed (v${currentVersion})`
+            : result.warning
+                ? `Reset to initial data (v${result.version})`
+                : `Migrated v${currentVersion}→v${result.version}`;
+        return {
+            newStorageJson: createStorageJson(result.data, result.version),
+            info,
+            warn: result.warning,
+        };
+    }
+    // Register migrate callback
+    tryRegisterCallback('__pl_storage_migrate', (currentStorageJson) => {
+        return migrateStorage(currentStorageJson);
+    });
+    /**
+     * Derives args from storage using the registered 'args' callback.
+     * This extracts data from storage and passes it to the block's args() function.
+     *
+     * @param storageJson - Storage as JSON string
+     * @returns ArgsDeriveResult with derived args or error
+     */
+    function deriveArgsFromStorage(storageJson) {
+        const ctx = tryGetCfgRenderCtx();
+        if (ctx === undefined) {
+            return { error: 'Not in config rendering context' };
+        }
+        // Extract data from storage
+        const { data } = normalizeStorage(storageJson);
+        // Get the args callback (registered by BlockModelV3.args())
+        const argsCallback = ctx.callbackRegistry['args'];
+        if (typeof argsCallback !== 'function') {
+            return { error: 'args callback not found' };
+        }
+        // Call the args callback with extracted data
+        try {
+            const result = argsCallback(data);
+            return { value: result };
+        }
+        catch (e) {
+            const errorMsg = e instanceof Error ? e.message : String(e);
+            return { error: `args() threw: ${errorMsg}` };
+        }
+    }
+    // Register args derivation callback
+    tryRegisterCallback('__pl_args_derive', (storageJson) => {
+        return deriveArgsFromStorage(storageJson);
+    });
+    /**
+     * Derives prerunArgs from storage using the registered 'prerunArgs' callback.
+     * Falls back to 'args' callback if 'prerunArgs' is not defined.
+     *
+     * @param storageJson - Storage as JSON string
+     * @returns ArgsDeriveResult with derived prerunArgs or error
+     */
+    function derivePrerunArgsFromStorage(storageJson) {
+        const ctx = tryGetCfgRenderCtx();
+        if (ctx === undefined) {
+            return { error: 'Not in config rendering context' };
+        }
+        // Extract data from storage
+        const { data } = normalizeStorage(storageJson);
+        // Try prerunArgs callback first
+        const prerunArgsCallback = ctx.callbackRegistry['prerunArgs'];
+        if (typeof prerunArgsCallback === 'function') {
+            try {
+                const result = prerunArgsCallback(data);
+                return { value: result };
+            }
+            catch (e) {
+                const errorMsg = e instanceof Error ? e.message : String(e);
+                return { error: `prerunArgs() threw: ${errorMsg}` };
+            }
+        }
+        // Fall back to args callback
+        const argsCallback = ctx.callbackRegistry['args'];
+        if (typeof argsCallback !== 'function') {
+            return { error: 'args callback not found (fallback from missing prerunArgs)' };
+        }
+        try {
+            const result = argsCallback(data);
+            return { value: result };
+        }
+        catch (e) {
+            const errorMsg = e instanceof Error ? e.message : String(e);
+            return { error: `args() threw (fallback): ${errorMsg}` };
+        }
+    }
+    // Register prerunArgs derivation callback
+    tryRegisterCallback('__pl_prerunArgs_derive', (storageJson) => {
+        return derivePrerunArgsFromStorage(storageJson);
+    });
+
     /** Main entry point that each block should use in it's "config" module. Don't forget
      * to call {@link done()} at the end of configuration. Value returned by this builder must be
-     * exported as constant with name "platforma" from the "config" module. */
-    class BlockModel {
+     * exported as constant with name "platforma" from the "config" module.
+     * API version is 3 (for UI) and 2 (for model) */
+    class BlockModelV3 {
         config;
         constructor(config) {
             this.config = config;
         }
-        static get INITIAL_BLOCK_FEATURE_FLAGS() {
-            return {
-                supportsLazyState: true,
-                requiresUIAPIVersion: 1,
-                requiresModelAPIVersion: 1,
-            };
-        }
-        static create(renderingMode = 'Heavy') {
-            return new BlockModel({
+        static INITIAL_BLOCK_FEATURE_FLAGS = {
+            supportsLazyState: true,
+            requiresUIAPIVersion: 3,
+            requiresModelAPIVersion: 2,
+        };
+        /**
+         * Creates a new BlockModelV3 builder with the specified data model and options.
+         *
+         * @example
+         * const dataModel = DataModel.create<BlockData>(() => ({ numbers: [], labels: [] }));
+         * BlockModelV3.create({ dataModel })
+         *   .args((data) => ({ numbers: data.numbers }))
+         *   .sections(() => [{ type: 'link', href: '/', label: 'Main' }])
+         *   .done();
+         *
+         * @param options Configuration options including required data model
+         */
+        static create(options) {
+            const { dataModel, renderingMode = 'Heavy' } = options;
+            // Register data model callbacks for VM use (initialData and upgrade)
+            dataModel.registerCallbacks();
+            return new BlockModelV3({
                 renderingMode,
-                initialUiState: {},
+                dataModel,
                 outputs: {},
-                inputsValid: getImmediate(true),
-                sections: getImmediate([]),
-                featureFlags: BlockModel.INITIAL_BLOCK_FEATURE_FLAGS,
+                // Register default sections callback (returns empty array)
+                sections: createAndRegisterRenderLambda({ handle: 'sections', lambda: () => [] }, true),
+                title: undefined,
+                subtitle: undefined,
+                tags: undefined,
+                enrichmentTargets: undefined,
+                featureFlags: { ...BlockModelV3.INITIAL_BLOCK_FEATURE_FLAGS },
+                args: undefined,
+                prerunArgs: undefined,
             });
         }
         output(key, cfgOrRf, flags = {}) {
-            if (typeof cfgOrRf === 'function') {
-                const handle = `output#${key}`;
-                tryRegisterCallback(handle, () => cfgOrRf(new RenderCtx()));
-                return new BlockModel({
-                    ...this.config,
-                    outputs: {
-                        ...this.config.outputs,
-                        [key]: {
-                            __renderLambda: true,
-                            handle,
-                            ...flags,
-                        },
-                    },
-                });
-            }
-            else {
-                return new BlockModel({
-                    ...this.config,
-                    outputs: {
-                        ...this.config.outputs,
-                        [key]: cfgOrRf,
-                    },
-                });
-            }
+            return new BlockModelV3({
+                ...this.config,
+                outputs: {
+                    ...this.config.outputs,
+                    [key]: createAndRegisterRenderLambda({ handle: `output#${key}`, lambda: () => cfgOrRf(new RenderCtx()), ...flags }),
+                },
+            });
         }
         /** Shortcut for {@link output} with retentive flag set to true. */
         retentiveOutput(key, rf) {
@@ -7456,109 +7829,83 @@
         outputWithStatus(key, rf) {
             return this.output(key, rf, { withStatus: true });
         }
-        /** Shortcut for {@link output} with retentive and withStatus flags set to true. */
-        retentiveOutputWithStatus(key, rf) {
-            return this.output(key, rf, { retentive: true, withStatus: true });
-        }
-        argsValid(cfgOrRf) {
-            if (typeof cfgOrRf === 'function') {
-                tryRegisterCallback('inputsValid', () => cfgOrRf(new RenderCtx()));
-                return new BlockModel({
-                    ...this.config,
-                    inputsValid: {
-                        __renderLambda: true,
-                        handle: 'inputsValid',
-                    },
-                });
-            }
-            else {
-                return new BlockModel({
-                    ...this.config,
-                    inputsValid: cfgOrRf,
-                });
-            }
-        }
-        sections(arrOrCfgOrRf) {
-            if (Array.isArray(arrOrCfgOrRf)) {
-                return this.sections(getImmediate(arrOrCfgOrRf));
-            }
-            else if (typeof arrOrCfgOrRf === 'function') {
-                tryRegisterCallback('sections', () => arrOrCfgOrRf(new RenderCtx()));
-                return new BlockModel({
-                    ...this.config,
-                    sections: {
-                        __renderLambda: true,
-                        handle: 'sections',
-                    },
-                });
-            }
-            else {
-                return new BlockModel({
-                    ...this.config,
-                    sections: arrOrCfgOrRf,
-                });
-            }
-        }
-        /** Sets a rendering function to derive block title, shown for the block in the left blocks-overview panel. */
-        title(rf) {
-            tryRegisterCallback('title', () => rf(new RenderCtx()));
-            return new BlockModel({
+        /**
+         * Sets a function to derive block args from data.
+         * This is called during setData to compute the args that will be used for block execution.
+         *
+         * @example
+         * .args<BlockArgs>((data) => ({ numbers: data.numbers }))
+         *
+         * @example
+         * .args<BlockArgs>((data) => {
+         *   if (data.numbers.length === 0) throw new Error('Numbers required'); // block not ready
+         *   return { numbers: data.numbers };
+         * })
+         */
+        args(lambda) {
+            return new BlockModelV3({
                 ...this.config,
-                title: {
-                    __renderLambda: true,
-                    handle: 'title',
-                },
+                args: createAndRegisterRenderLambda({ handle: 'args', lambda }),
             });
         }
-        subtitle(rf) {
-            tryRegisterCallback('subtitle', () => rf(new RenderCtx()));
-            return new BlockModel({
+        /**
+         * Sets a function to derive pre-run args from data (optional).
+         * This is called during setData to compute the args that will be used for staging/pre-run phase.
+         *
+         * If not defined, defaults to using the args() function result.
+         * If defined, uses its return value for the staging / prerun phase.
+         *
+         * The staging / prerun phase runs only if currentPrerunArgs differs from the executed
+         * version of prerunArgs (same comparison logic as currentArgs vs prodArgs).
+         *
+         * @example
+         * .prerunArgs((data) => ({ numbers: data.numbers }))
+         *
+         * @example
+         * .prerunArgs((data) => {
+         *   // Return undefined to skip staging for this block
+         *   if (!data.isReady) return undefined;
+         *   return { numbers: data.numbers };
+         * })
+         */
+        prerunArgs(fn) {
+            return new BlockModelV3({
                 ...this.config,
-                subtitle: {
-                    __renderLambda: true,
-                    handle: 'subtitle',
-                },
+                prerunArgs: createAndRegisterRenderLambda({ handle: 'prerunArgs', lambda: fn }),
             });
         }
-        tags(rf) {
-            tryRegisterCallback('tags', () => rf(new RenderCtx()));
-            return new BlockModel({
+        /** Sets the lambda to generate list of sections in the left block overviews panel. */
+        sections(rf) {
+            return new BlockModelV3({
                 ...this.config,
-                tags: {
-                    __renderLambda: true,
-                    handle: 'tags',
-                },
+                // Replace the default sections callback with the user-provided one
+                sections: createAndRegisterRenderLambda({ handle: 'sections', lambda: () => rf(new RenderCtx()) }, true),
             });
         }
-        /**
-         * Sets initial args for the block, this value must be specified.
-         * @deprecated use {@link withArgs}
-         * */
-        initialArgs(value) {
-            return this.withArgs(value);
+        /** Sets a rendering function to derive block title, shown for the block in the left blocks-overview panel. */
+        title(rf) {
+            return new BlockModelV3({
+                ...this.config,
+                title: createAndRegisterRenderLambda({ handle: 'title', lambda: () => rf(new RenderCtx()) }),
+            });
         }
-        /** Sets initial args for the block, this value must be specified. */
-        withArgs(initialArgs) {
-            return new BlockModel({
+        subtitle(rf) {
+            return new BlockModelV3({
                 ...this.config,
-                initialArgs,
+                subtitle: createAndRegisterRenderLambda({ handle: 'subtitle', lambda: () => rf(new RenderCtx()) }),
             });
         }
-        /** Defines type and sets initial value for block UiState. */
-        withUiState(initialUiState) {
-            return new BlockModel({
+        tags(rf) {
+            return new BlockModelV3({
                 ...this.config,
-                initialUiState,
+                tags: createAndRegisterRenderLambda({ handle: 'tags', lambda: () => rf(new RenderCtx()) }),
             });
         }
         /** Sets or overrides feature flags for the block. */
         withFeatureFlags(flags) {
-            return new BlockModel({
+            return new BlockModelV3({
                 ...this.config,
-                featureFlags: {
-                    ...this.config.featureFlags,
-                    ...flags,
-                },
+                featureFlags: { ...this.config.featureFlags, ...flags },
             });
         }
         /**
@@ -7566,58 +7913,58 @@
          * Influences dependency graph construction.
          */
         enriches(lambda) {
-            tryRegisterCallback('enrichmentTargets', lambda);
-            return new BlockModel({
+            return new BlockModelV3({
                 ...this.config,
-                enrichmentTargets: {
-                    __renderLambda: true,
-                    handle: 'enrichmentTargets',
-                },
+                enrichmentTargets: createAndRegisterRenderLambda({ handle: 'enrichmentTargets', lambda: lambda }),
             });
         }
         /** Renders all provided block settings into a pre-configured platforma API
-         * instance, that can be used in frontend to interact with block state, and
+         * instance, that can be used in frontend to interact with block data, and
          * other features provided by the platforma to the block. */
-        done(apiVersion = 1) {
+        done() {
             return this.withFeatureFlags({
                 ...this.config.featureFlags,
-                requiresUIAPIVersion: apiVersion,
-            }).#done();
-        }
-        #done() {
-            if (this.config.initialArgs === undefined)
-                throw new Error('Initial arguments not set.');
-            const config = {
-                v3: {
+            })._done();
+        }
+        _done() {
+            if (this.config.args === undefined)
+                throw new Error('Args rendering function not set.');
+            const apiVersion = 3;
+            const migrationCount = this.config.dataModel.migrationCount;
+            const blockConfig = {
+                v4: {
+                    configVersion: 4,
+                    modelAPIVersion: 2,
                     sdkVersion: PlatformaSDKVersion,
                     renderingMode: this.config.renderingMode,
-                    initialArgs: this.config.initialArgs,
-                    initialUiState: this.config.initialUiState,
-                    inputsValid: this.config.inputsValid,
+                    args: this.config.args,
+                    prerunArgs: this.config.prerunArgs,
+                    // Reference to __pl_data_initial callback registered by DataModel
+                    initialData: createRenderLambda({ handle: '__pl_data_initial' }),
                     sections: this.config.sections,
                     title: this.config.title,
-                    subtitle: this.config.subtitle,
-                    tags: this.config.tags,
                     outputs: this.config.outputs,
                     enrichmentTargets: this.config.enrichmentTargets,
                     featureFlags: this.config.featureFlags,
+                    // Generate migration descriptors (indices for metadata)
+                    migrations: migrationCount > 0
+                        ? Array.from({ length: migrationCount }, (_, i) => ({ index: i }))
+                        : undefined,
                 },
                 // fields below are added to allow previous desktop versions read generated configs
                 sdkVersion: PlatformaSDKVersion,
                 renderingMode: this.config.renderingMode,
-                initialArgs: this.config.initialArgs,
-                inputsValid: downgradeCfgOrLambda(this.config.inputsValid),
-                sections: downgradeCfgOrLambda(this.config.sections),
+                sections: this.config.sections,
                 outputs: Object.fromEntries(Object.entries(this.config.outputs).map(([key, value]) => [key, downgradeCfgOrLambda(value)])),
             };
-            globalThis.platformaApiVersion = this.config.featureFlags.requiresUIAPIVersion;
+            globalThis.platformaApiVersion = apiVersion;
             if (!isInUI())
                 // we are in the configuration rendering routine, not in actual UI
-                return { config };
+                return { config: blockConfig };
             // normal operation inside the UI
             else
                 return {
-                    ...getPlatformaInstance({ sdkVersion: PlatformaSDKVersion, apiVersion: platformaApiVersion }),
+                    ...getPlatformaInstance({ sdkVersion: PlatformaSDKVersion, apiVersion }),
                     blockModelInfo: {
                         outputs: Object.fromEntries(Object.entries(this.config.outputs)
                             .map(([key, value]) => [key, {
@@ -7628,6 +7975,137 @@
         }
     }
 
+    /** Internal builder for chaining migrations */
+    class DataModelBuilder {
+        migrationSteps;
+        constructor(steps = []) {
+            this.migrationSteps = steps;
+        }
+        /** Start a migration chain from an initial type */
+        static from() {
+            return new DataModelBuilder();
+        }
+        /** Add a migration step */
+        migrate(fn) {
+            return new DataModelBuilder([...this.migrationSteps, fn]);
+        }
+        /** Finalize with initial data, creating the DataModel */
+        create(initialData, ..._) {
+            return DataModel._fromBuilder(this.migrationSteps, initialData);
+        }
+    }
+    /**
+     * DataModel defines the block's data structure, initial values, and migrations.
+     * Used by BlockModelV3 to manage data state.
+     *
+     * @example
+     * // Simple data model (no migrations)
+     * const dataModel = DataModel.create<BlockData>(() => ({
+     *   numbers: [],
+     *   labels: [],
+     * }));
+     *
+     * // Data model with migrations
+     * const dataModel = DataModel
+     *   .from<V1>()
+     *   .migrate((data) => ({ ...data, labels: [] }))  // v1 → v2
+     *   .migrate((data) => ({ ...data, description: '' }))  // v2 → v3
+     *   .create<BlockData>(() => ({ numbers: [], labels: [], description: '' }));
+     */
+    class DataModel {
+        steps;
+        _initialData;
+        constructor(steps, initialData) {
+            this.steps = steps;
+            this._initialData = initialData;
+        }
+        /** Start a migration chain from an initial type */
+        static from() {
+            return DataModelBuilder.from();
+        }
+        /** Create a data model with just initial data (no migrations) */
+        static create(initialData) {
+            return new DataModel([], initialData);
+        }
+        /** Create from builder (internal use) */
+        static _fromBuilder(steps, initialData) {
+            return new DataModel(steps, initialData);
+        }
+        /**
+         * Latest version number.
+         * Version 1 = initial state, each migration adds 1.
+         */
+        get version() {
+            return this.steps.length + 1;
+        }
+        /** Number of migration steps */
+        get migrationCount() {
+            return this.steps.length;
+        }
+        /** Get initial data */
+        initialData() {
+            return this._initialData();
+        }
+        /** Get default data wrapped with current version */
+        getDefaultData() {
+            return { version: this.version, data: this._initialData() };
+        }
+        /**
+         * Upgrade versioned data from any version to the latest.
+         * Applies only the migrations needed (skips already-applied ones).
+         * If a migration fails, returns default data with a warning.
+         */
+        upgrade(versioned) {
+            const { version: fromVersion, data } = versioned;
+            if (fromVersion > this.version) {
+                throw new Error(`Cannot downgrade from version ${fromVersion} to ${this.version}`);
+            }
+            if (fromVersion === this.version) {
+                return { version: this.version, data: data };
+            }
+            // Apply migrations starting from (fromVersion - 1) index
+            // Version 1 -> no migrations applied yet -> start at index 0
+            // Version 2 -> migration[0] already applied -> start at index 1
+            const startIndex = fromVersion - 1;
+            const migrationsToApply = this.steps.slice(startIndex);
+            let currentData = data;
+            for (let i = 0; i < migrationsToApply.length; i++) {
+                const stepIndex = startIndex + i;
+                const fromVer = stepIndex + 1;
+                const toVer = stepIndex + 2;
+                try {
+                    currentData = migrationsToApply[i](currentData);
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    return {
+                        ...this.getDefaultData(),
+                        warning: `Migration v${fromVer}→v${toVer} failed: ${errorMessage}`,
+                    };
+                }
+            }
+            return { version: this.version, data: currentData };
+        }
+        /**
+         * Register callbacks for use in the VM.
+         * Called by BlockModelV3.create() to set up internal callbacks.
+         *
+         * All callbacks are prefixed with `__pl_` to indicate internal SDK use:
+         * - `__pl_data_initial`: returns initial data for new blocks
+         * - `__pl_data_upgrade`: upgrades versioned data from any version to latest
+         * - `__pl_storage_initial`: returns initial BlockStorage as JSON string
+         */
+        registerCallbacks() {
+            tryRegisterCallback('__pl_data_initial', () => this._initialData());
+            tryRegisterCallback('__pl_data_upgrade', (versioned) => this.upgrade(versioned));
+            tryRegisterCallback('__pl_storage_initial', () => {
+                const { version, data } = this.getDefaultData();
+                const storage = createBlockStorage(data, version);
+                return JSON.stringify(storage);
+            });
+        }
+    }
+
     var stringify = {exports: {}};
 
     var hasRequiredStringify;
@@ -7708,8 +8186,11 @@
         errors: z.lazy(() => ErrorShape.array()).optional(),
     });
 
-    const platforma = BlockModel.create('Heavy')
-        .withArgs({ titleArg: 'The title' })
+    const dataModel = DataModel.create(() => ({ titleArgs: 'The title' }));
+    const platforma = BlockModelV3.create({ dataModel, renderingMode: 'Heavy' })
+        .args((data) => {
+        return { titleArgs: data.titleArgs };
+    })
         .output('allSpecs', (ctx) => ctx.resultPool.getSpecs())
         .sections((_ctx) => {
         return [{ type: 'link', href: '/', label: 'Main' }];