@platforma-sdk/model 1.51.6 → 1.52.0

package/dist/block_storage.js

@@ -0,0 +1,225 @@
+/**
+ * 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,
+    };
+}
+/**
+ * Normalizes raw storage data to BlockStorage format.
+ * If the input is already a BlockStorage, returns it as-is.
+ * If the input is legacy format (raw state), wraps it in BlockStorage structure.
+ *
+ * @param raw - Raw storage data (may be legacy format or BlockStorage)
+ * @returns Normalized BlockStorage
+ */
+function normalizeBlockStorage(raw) {
+    if (isBlockStorage(raw)) {
+        return raw;
+    }
+    // Legacy format: raw is the state directly
+    return createBlockStorage(raw, 1);
+}
+// =============================================================================
+// Data Access & Update Functions
+// =============================================================================
+/**
+ * Gets the data from BlockStorage
+ *
+ * @param storage - The BlockStorage instance
+ * @returns The data value
+ */
+function getStorageData(storage) {
+    return storage.__data;
+}
+/**
+ * Derives data from raw block storage.
+ * This function is meant to be called from sdk/ui-vue to extract
+ * user-facing data from the raw storage returned by the middle layer.
+ *
+ * The middle layer returns raw storage (opaque to it), and the UI
+ * uses this function to derive the actual data value.
+ *
+ * @param rawStorage - Raw storage data from middle layer (may be any format)
+ * @returns The extracted data value, or undefined if storage is undefined/null
+ */
+function deriveDataFromStorage(rawStorage) {
+    // Normalize to BlockStorage format (handles legacy formats too)
+    const storage = normalizeBlockStorage(rawStorage);
+    return getStorageData(storage);
+}
+/**
+ * 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}`);
+    }
+}
+/**
+ * Gets the data version from BlockStorage
+ *
+ * @param storage - The BlockStorage instance
+ * @returns The data version number
+ */
+function getStorageDataVersion(storage) {
+    return storage.__dataVersion;
+}
+/**
+ * Updates the data version in BlockStorage (immutable)
+ *
+ * @param storage - The current BlockStorage
+ * @param version - The new version number
+ * @returns A new BlockStorage with updated version
+ */
+function updateStorageDataVersion(storage, version) {
+    return { ...storage, __dataVersion: version };
+}
+// =============================================================================
+// Plugin Data Functions
+// =============================================================================
+/**
+ * Gets plugin-specific data from BlockStorage
+ *
+ * @param storage - The BlockStorage instance
+ * @param pluginName - The plugin name (without `@plugin/` prefix)
+ * @returns The plugin data or undefined if not set
+ */
+function getPluginData(storage, pluginName) {
+    const key = `@plugin/${pluginName}`;
+    return storage[key];
+}
+/**
+ * Sets plugin-specific data in BlockStorage (immutable)
+ *
+ * @param storage - The current BlockStorage
+ * @param pluginName - The plugin name (without `@plugin/` prefix)
+ * @param data - The plugin data to store
+ * @returns A new BlockStorage with updated plugin data
+ */
+function setPluginData(storage, pluginName, data) {
+    const key = `@plugin/${pluginName}`;
+    return { ...storage, [key]: data };
+}
+/**
+ * Removes plugin-specific data from BlockStorage (immutable)
+ *
+ * @param storage - The current BlockStorage
+ * @param pluginName - The plugin name (without `@plugin/` prefix)
+ * @returns A new BlockStorage with the plugin data removed
+ */
+function removePluginData(storage, pluginName) {
+    const key = `@plugin/${pluginName}`;
+    const { [key]: _, ...rest } = storage;
+    return rest;
+}
+/**
+ * Gets all plugin names that have data stored
+ *
+ * @param storage - The BlockStorage instance
+ * @returns Array of plugin names (without `@plugin/` prefix)
+ */
+function getPluginNames(storage) {
+    return Object.keys(storage)
+        .filter((key) => key.startsWith('@plugin/'))
+        .map((key) => key.slice('@plugin/'.length));
+}
+// =============================================================================
+// Generic Storage Access
+// =============================================================================
+/**
+ * Gets a value from BlockStorage by key
+ *
+ * @param storage - The BlockStorage instance
+ * @param key - The key to retrieve
+ * @returns The value at the given key
+ */
+function getFromStorage(storage, key) {
+    return storage[key];
+}
+/**
+ * Updates a value in BlockStorage by key (immutable)
+ *
+ * @param storage - The current BlockStorage
+ * @param key - The key to update
+ * @param value - The new value
+ * @returns A new BlockStorage with the updated value
+ */
+function updateStorage(storage, key, value) {
+    return { ...storage, [key]: value };
+}
+/**
+ * Default implementations of storage handlers
+ */
+const defaultBlockStorageHandlers = {
+    transformStateForStorage: (storage, newState) => updateStorageData(storage, { operation: 'update-data', value: newState }),
+    deriveStateForArgs: (storage) => getStorageData(storage),
+    migrateStorage: (storage, _fromVersion, toVersion) => updateStorageDataVersion(storage, toVersion),
+};
+/**
+ * Merges custom handlers with defaults
+ *
+ * @param customHandlers - Custom handlers to merge
+ * @returns Complete handlers with defaults for missing functions
+ */
+function mergeBlockStorageHandlers(customHandlers) {
+    return {
+        ...defaultBlockStorageHandlers,
+        ...customHandlers,
+    };
+}
+
+export { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION, createBlockStorage, defaultBlockStorageHandlers, deriveDataFromStorage, getFromStorage, getPluginData, getPluginNames, getStorageData, getStorageDataVersion, isBlockStorage, mergeBlockStorageHandlers, normalizeBlockStorage, removePluginData, setPluginData, updateStorage, updateStorageData, updateStorageDataVersion };
+//# sourceMappingURL=block_storage.js.map

package/dist/block_storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"block_storage.js","sources":["../src/block_storage.ts"],"sourcesContent":["/**\n * BlockStorage - Typed storage abstraction for block persistent data.\n *\n * This module provides:\n * - A typed structure for block storage with versioning and plugin support\n * - Utility functions for manipulating storage\n * - Handler interfaces for model-level customization\n *\n * @module block_storage\n */\n\n// =============================================================================\n// Core Types\n// =============================================================================\n\n/**\n * Discriminator key for BlockStorage format detection.\n * This unique hash-based key identifies data as BlockStorage vs legacy formats.\n */\nexport const BLOCK_STORAGE_KEY = '__pl_a7f3e2b9__';\n\n/**\n * Current BlockStorage schema version.\n * Increment this when the storage structure itself changes (not block state migrations).\n */\nexport const BLOCK_STORAGE_SCHEMA_VERSION = 'v1';\n\n/**\n * Type for valid schema versions\n */\nexport type BlockStorageSchemaVersion = 'v1'; // Add 'v2', 'v3', etc. as schema evolves\n\n/**\n * Plugin key type - keys starting with `@plugin/` are reserved for plugin data\n */\nexport type PluginKey = `@plugin/${string}`;\n\n/**\n * Core BlockStorage type that holds:\n * - __pl_a7f3e2b9__: Schema version (discriminator key identifies BlockStorage format)\n * - __dataVersion: Version number for block data migrations\n * - __data: The block's user-facing data (state)\n * - @plugin/*: Optional plugin-specific data\n */\nexport type BlockStorage<TState = unknown> = {\n  /** Schema version - the key itself is the discriminator */\n  readonly [BLOCK_STORAGE_KEY]: BlockStorageSchemaVersion;\n  /** Version of the block data, used for migrations */\n  __dataVersion: number;\n  /** The block's user-facing data (state) */\n  __data: TState;\n} & {\n  /** Plugin-specific data, keyed by `@plugin/<pluginName>` */\n  [K in PluginKey]?: unknown;\n};\n\n/**\n * Type guard to check if a value is a valid BlockStorage object.\n * Checks for the discriminator key and valid schema version.\n */\nexport function isBlockStorage(value: unknown): value is BlockStorage {\n  if (value === null || typeof value !== 'object') return false;\n  const obj = value as Record<string, unknown>;\n  const schemaVersion = obj[BLOCK_STORAGE_KEY];\n  // Currently only 'v1' is valid, but this allows future versions\n  return schemaVersion === 'v1'; // Add more versions as schema evolves\n}\n\n// =============================================================================\n// Factory Functions\n// =============================================================================\n\n/**\n * Creates a BlockStorage with the given initial data\n *\n * @param initialData - The initial data value (defaults to empty object)\n * @param version - The initial data version (defaults to 1)\n * @returns A new BlockStorage instance with discriminator key\n */\nexport function createBlockStorage<TState = unknown>(\n  initialData: TState = {} as TState,\n  version: number = 1,\n): BlockStorage<TState> {\n  return {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: version,\n    __data: initialData,\n  };\n}\n\n/**\n * Normalizes raw storage data to BlockStorage format.\n * If the input is already a BlockStorage, returns it as-is.\n * If the input is legacy format (raw state), wraps it in BlockStorage structure.\n *\n * @param raw - Raw storage data (may be legacy format or BlockStorage)\n * @returns Normalized BlockStorage\n */\nexport function normalizeBlockStorage<TState = unknown>(raw: unknown): BlockStorage<TState> {\n  if (isBlockStorage(raw)) {\n    return raw as BlockStorage<TState>;\n  }\n  // Legacy format: raw is the state directly\n  return createBlockStorage(raw as TState, 1);\n}\n\n// =============================================================================\n// Data Access & Update Functions\n// =============================================================================\n\n/**\n * Gets the data from BlockStorage\n *\n * @param storage - The BlockStorage instance\n * @returns The data value\n */\nexport function getStorageData<TState>(storage: BlockStorage<TState>): TState {\n  return storage.__data;\n}\n\n/**\n * Derives data from raw block storage.\n * This function is meant to be called from sdk/ui-vue to extract\n * user-facing data from the raw storage returned by the middle layer.\n *\n * The middle layer returns raw storage (opaque to it), and the UI\n * uses this function to derive the actual data value.\n *\n * @param rawStorage - Raw storage data from middle layer (may be any format)\n * @returns The extracted data value, or undefined if storage is undefined/null\n */\nexport function deriveDataFromStorage<TData = unknown>(\n  rawStorage: unknown,\n): TData {\n  // Normalize to BlockStorage format (handles legacy formats too)\n  const storage = normalizeBlockStorage<TData>(rawStorage);\n  return getStorageData(storage);\n}\n\n/** Payload for storage mutation operations. SDK defines specific operations. */\nexport type MutateStoragePayload<T = unknown> = { operation: 'update-data'; value: T };\n\n/**\n * Updates the data in BlockStorage (immutable)\n *\n * @param storage - The current BlockStorage\n * @param payload - The update payload with operation and value\n * @returns A new BlockStorage with updated data\n */\nexport function updateStorageData<TValue = unknown>(\n  storage: BlockStorage<TValue>,\n  payload: MutateStoragePayload<TValue>,\n): BlockStorage<TValue> {\n  switch (payload.operation) {\n    case 'update-data':\n      return { ...storage, __data: payload.value };\n    default:\n      throw new Error(`Unknown storage operation: ${(payload as { operation: string }).operation}`);\n  }\n}\n\n/**\n * Gets the data version from BlockStorage\n *\n * @param storage - The BlockStorage instance\n * @returns The data version number\n */\nexport function getStorageDataVersion(storage: BlockStorage): number {\n  return storage.__dataVersion;\n}\n\n/**\n * Updates the data version in BlockStorage (immutable)\n *\n * @param storage - The current BlockStorage\n * @param version - The new version number\n * @returns A new BlockStorage with updated version\n */\nexport function updateStorageDataVersion<TState>(\n  storage: BlockStorage<TState>,\n  version: number,\n): BlockStorage<TState> {\n  return { ...storage, __dataVersion: version };\n}\n\n// =============================================================================\n// Plugin Data Functions\n// =============================================================================\n\n/**\n * Gets plugin-specific data from BlockStorage\n *\n * @param storage - The BlockStorage instance\n * @param pluginName - The plugin name (without `@plugin/` prefix)\n * @returns The plugin data or undefined if not set\n */\nexport function getPluginData<TData = unknown>(\n  storage: BlockStorage,\n  pluginName: string,\n): TData | undefined {\n  const key: PluginKey = `@plugin/${pluginName}`;\n  return storage[key] as TData | undefined;\n}\n\n/**\n * Sets plugin-specific data in BlockStorage (immutable)\n *\n * @param storage - The current BlockStorage\n * @param pluginName - The plugin name (without `@plugin/` prefix)\n * @param data - The plugin data to store\n * @returns A new BlockStorage with updated plugin data\n */\nexport function setPluginData<TState>(\n  storage: BlockStorage<TState>,\n  pluginName: string,\n  data: unknown,\n): BlockStorage<TState> {\n  const key: PluginKey = `@plugin/${pluginName}`;\n  return { ...storage, [key]: data };\n}\n\n/**\n * Removes plugin-specific data from BlockStorage (immutable)\n *\n * @param storage - The current BlockStorage\n * @param pluginName - The plugin name (without `@plugin/` prefix)\n * @returns A new BlockStorage with the plugin data removed\n */\nexport function removePluginData<TState>(\n  storage: BlockStorage<TState>,\n  pluginName: string,\n): BlockStorage<TState> {\n  const key: PluginKey = `@plugin/${pluginName}`;\n  const { [key]: _, ...rest } = storage;\n  return rest as BlockStorage<TState>;\n}\n\n/**\n * Gets all plugin names that have data stored\n *\n * @param storage - The BlockStorage instance\n * @returns Array of plugin names (without `@plugin/` prefix)\n */\nexport function getPluginNames(storage: BlockStorage): string[] {\n  return Object.keys(storage)\n    .filter((key): key is PluginKey => key.startsWith('@plugin/'))\n    .map((key) => key.slice('@plugin/'.length));\n}\n\n// =============================================================================\n// Generic Storage Access\n// =============================================================================\n\n/**\n * Gets a value from BlockStorage by key\n *\n * @param storage - The BlockStorage instance\n * @param key - The key to retrieve\n * @returns The value at the given key\n */\nexport function getFromStorage<\n  TState,\n  K extends keyof BlockStorage<TState>,\n>(storage: BlockStorage<TState>, key: K): BlockStorage<TState>[K] {\n  return storage[key];\n}\n\n/**\n * Updates a value in BlockStorage by key (immutable)\n *\n * @param storage - The current BlockStorage\n * @param key - The key to update\n * @param value - The new value\n * @returns A new BlockStorage with the updated value\n */\nexport function updateStorage<\n  TState,\n  K extends keyof BlockStorage<TState>,\n>(\n  storage: BlockStorage<TState>,\n  key: K,\n  value: BlockStorage<TState>[K],\n): BlockStorage<TState> {\n  return { ...storage, [key]: value };\n}\n\n// =============================================================================\n// Storage Handlers (for Phase 2 - Model-Level Customization)\n// =============================================================================\n\n/**\n * Interface for model-configurable storage operations.\n * These handlers allow block models to customize how storage is managed.\n */\nexport interface BlockStorageHandlers<TState = unknown> {\n  /**\n   * Called when setState is invoked - transforms the new state before storing.\n   * Default behavior: replaces the state directly.\n   *\n   * @param currentStorage - The current BlockStorage\n   * @param newState - The new state being set\n   * @returns The updated BlockStorage\n   */\n  transformStateForStorage?: (\n    currentStorage: BlockStorage<TState>,\n    newState: TState,\n  ) => BlockStorage<TState>;\n\n  /**\n   * Called when reading state for args derivation.\n   * Default behavior: returns the state directly.\n   *\n   * @param storage - The current BlockStorage\n   * @returns The state to use for args derivation\n   */\n  deriveStateForArgs?: (storage: BlockStorage<TState>) => TState;\n\n  /**\n   * Called during storage schema migration.\n   * Default behavior: updates stateVersion only.\n   *\n   * @param oldStorage - The storage before migration\n   * @param fromVersion - The version migrating from\n   * @param toVersion - The version migrating to\n   * @returns The migrated BlockStorage\n   */\n  migrateStorage?: (\n    oldStorage: BlockStorage<TState>,\n    fromVersion: number,\n    toVersion: number,\n  ) => BlockStorage<TState>;\n}\n\n/**\n * Default implementations of storage handlers\n */\nexport const defaultBlockStorageHandlers: Required<BlockStorageHandlers<unknown>> = {\n  transformStateForStorage: <TState>(\n    storage: BlockStorage<TState>,\n    newState: TState,\n  ): BlockStorage<TState> => updateStorageData(storage, { operation: 'update-data', value: newState }),\n\n  deriveStateForArgs: <TState>(storage: BlockStorage<TState>): TState => getStorageData(storage),\n\n  migrateStorage: <TState>(\n    storage: BlockStorage<TState>,\n    _fromVersion: number,\n    toVersion: number,\n  ): BlockStorage<TState> => updateStorageDataVersion(storage, toVersion),\n};\n\n/**\n * Merges custom handlers with defaults\n *\n * @param customHandlers - Custom handlers to merge\n * @returns Complete handlers with defaults for missing functions\n */\nexport function mergeBlockStorageHandlers<TState>(\n  customHandlers?: BlockStorageHandlers<TState>,\n): Required<BlockStorageHandlers<TState>> {\n  return {\n    ...defaultBlockStorageHandlers,\n    ...customHandlers,\n  } as Required<BlockStorageHandlers<TState>>;\n}\n"],"names":[],"mappings":"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"}

package/dist/block_storage_vm.cjs

@@ -0,0 +1,264 @@
+'use strict';
+
+var block_storage = require('./block_storage.cjs');
+var internal = require('./internal.cjs');
+
+/**
+ * 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 = block_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 = block_storage.createBlockStorage(rawStorage);
+            return { storage, data: rawStorage };
+        }
+    }
+    // Check for BlockStorage format (has discriminator)
+    if (block_storage.isBlockStorage(parsed)) {
+        return { storage: parsed, data: block_storage.getStorageData(parsed) };
+    }
+    // Check for legacy V1/V2 format: { args, uiState }
+    if (isLegacyModelV1ApiFormat(parsed)) {
+        // For legacy format, the whole object IS the data
+        const storage = block_storage.createBlockStorage(parsed);
+        return { storage, data: parsed };
+    }
+    // Raw V3 data - wrap it
+    const storage = block_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 = block_storage.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 (block_storage.isBlockStorage(data))
+        return false;
+    const obj = data;
+    return 'args' in obj;
+}
+// =============================================================================
+// Auto-register internal callbacks when module is loaded in VM
+// =============================================================================
+// Register normalize callback
+internal.tryRegisterCallback('__pl_storage_normalize', (rawStorage) => {
+    return normalizeStorage(rawStorage);
+});
+// Register apply update callback (requires existing storage)
+internal.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
+internal.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 = internal.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
+internal.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 = internal.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
+internal.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 = internal.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
+internal.tryRegisterCallback('__pl_prerunArgs_derive', (storageJson) => {
+    return derivePrerunArgsFromStorage(storageJson);
+});
+
+exports.BLOCK_STORAGE_KEY = block_storage.BLOCK_STORAGE_KEY;
+exports.BLOCK_STORAGE_SCHEMA_VERSION = block_storage.BLOCK_STORAGE_SCHEMA_VERSION;
+//# sourceMappingURL=block_storage_vm.cjs.map

package/dist/block_storage_vm.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"block_storage_vm.cjs","sources":["../src/block_storage_vm.ts"],"sourcesContent":["/**\n * BlockStorage VM Integration - Internal module for VM-based storage operations.\n *\n * This module auto-registers internal callbacks that the middle layer can invoke\n * to perform storage transformations. Block developers never interact with these\n * directly - they only see `state`.\n *\n * Registered callbacks (all prefixed with `__pl_` for internal SDK use):\n * - `__pl_storage_normalize`: (rawStorage) => { storage, data }\n * - `__pl_storage_applyUpdate`: (currentStorageJson, payload) => updatedStorageJson\n * - `__pl_storage_getInfo`: (rawStorage) => JSON string with storage info\n * - `__pl_storage_migrate`: (currentStorageJson) => MigrationResult\n * - `__pl_args_derive`: (storageJson) => ArgsDeriveResult\n * - `__pl_prerunArgs_derive`: (storageJson) => ArgsDeriveResult\n *\n * Callbacks registered by DataModel.registerCallbacks():\n * - `__pl_data_initial`: () => initial data\n * - `__pl_data_upgrade`: (versioned) => UpgradeResult\n * - `__pl_storage_initial`: () => initial BlockStorage as JSON string\n *\n * @module block_storage_vm\n * @internal\n */\n\nimport {\n  BLOCK_STORAGE_KEY,\n  BLOCK_STORAGE_SCHEMA_VERSION,\n  type BlockStorage,\n  type MutateStoragePayload,\n  createBlockStorage,\n  getStorageData,\n  isBlockStorage,\n  updateStorageData,\n} from './block_storage';\nimport { tryGetCfgRenderCtx, tryRegisterCallback } from './internal';\n\n/**\n * Result of storage normalization\n */\nexport interface NormalizeStorageResult {\n  /** The normalized BlockStorage object */\n  storage: BlockStorage;\n  /** The extracted data (what developers see) */\n  data: unknown;\n}\n\n/**\n * Normalizes raw storage data and extracts state.\n * Handles all formats:\n * - New BlockStorage format (has discriminator)\n * - Legacy V1/V2 format ({ args, uiState })\n * - Raw V3 state (any other format)\n *\n * @param rawStorage - Raw data from blockStorage field (may be JSON string or object)\n * @returns Object with normalized storage and extracted state\n */\nfunction normalizeStorage(rawStorage: unknown): NormalizeStorageResult {\n  // Handle undefined/null\n  if (rawStorage === undefined || rawStorage === null) {\n    const storage = createBlockStorage({});\n    return { storage, data: {} };\n  }\n\n  // Parse JSON string if needed\n  let parsed = rawStorage;\n  if (typeof rawStorage === 'string') {\n    try {\n      parsed = JSON.parse(rawStorage);\n    } catch {\n      // If parsing fails, treat string as the data\n      const storage = createBlockStorage(rawStorage);\n      return { storage, data: rawStorage };\n    }\n  }\n\n  // Check for BlockStorage format (has discriminator)\n  if (isBlockStorage(parsed)) {\n    return { storage: parsed, data: getStorageData(parsed) };\n  }\n\n  // Check for legacy V1/V2 format: { args, uiState }\n  if (isLegacyModelV1ApiFormat(parsed)) {\n    // For legacy format, the whole object IS the data\n    const storage = createBlockStorage(parsed);\n    return { storage, data: parsed };\n  }\n\n  // Raw V3 data - wrap it\n  const storage = createBlockStorage(parsed);\n  return { storage, data: parsed };\n}\n\n/**\n * Applies a state update to existing storage.\n * Used when setData is called from the frontend.\n *\n * @param currentStorageJson - Current storage as JSON string (must be defined)\n * @param newData - New data from application\n * @returns Updated storage as JSON string\n */\nfunction applyStorageUpdate(currentStorageJson: string, payload: MutateStoragePayload): string {\n  const { storage: currentStorage } = normalizeStorage(currentStorageJson);\n\n  // Update data while preserving other storage fields (version, plugins)\n  const updatedStorage = updateStorageData(currentStorage, payload);\n\n  return JSON.stringify(updatedStorage);\n}\n\n/**\n * Checks if data is in legacy Model API v1 format.\n * Legacy format has { args, uiState? } at top level without the BlockStorage discriminator.\n */\nfunction isLegacyModelV1ApiFormat(data: unknown): data is { args?: unknown } {\n  if (data === null || typeof data !== 'object') return false;\n  if (isBlockStorage(data)) return false;\n\n  const obj = data as Record<string, unknown>;\n  return 'args' in obj;\n}\n\n// =============================================================================\n// Auto-register internal callbacks when module is loaded in VM\n// =============================================================================\n\n// Register normalize callback\ntryRegisterCallback('__pl_storage_normalize', (rawStorage: unknown) => {\n  return normalizeStorage(rawStorage);\n});\n\n// Register apply update callback (requires existing storage)\ntryRegisterCallback('__pl_storage_applyUpdate', (currentStorageJson: string, payload: MutateStoragePayload) => {\n  return applyStorageUpdate(currentStorageJson, payload);\n});\n\n/**\n * Storage info result returned by __pl_storage_getInfo callback.\n */\nexport interface StorageInfo {\n  /** Current data version (1-based, starts at 1) */\n  dataVersion: number;\n}\n\n/**\n * Gets storage info from raw storage data.\n * Returns structured info about the storage state.\n *\n * @param rawStorage - Raw data from blockStorage field (may be JSON string or object)\n * @returns JSON string with storage info\n */\nfunction getStorageInfo(rawStorage: unknown): string {\n  const { storage } = normalizeStorage(rawStorage);\n  const info: StorageInfo = {\n    dataVersion: storage.__dataVersion,\n  };\n  return JSON.stringify(info);\n}\n\n// Register get info callback\ntryRegisterCallback('__pl_storage_getInfo', (rawStorage: unknown) => {\n  return getStorageInfo(rawStorage);\n});\n\n// =============================================================================\n// Migration Support\n// =============================================================================\n\n/**\n * Result of storage migration.\n * Returned by __pl_storage_migrate callback.\n *\n * - Error result: { error: string } - serious failure (no context, etc.)\n * - Success result: { newStorageJson: string, info: string, warn?: string } - migration succeeded or reset to initial\n */\nexport type MigrationResult =\n  | { error: string }\n  | { error?: undefined; newStorageJson: string; info: string; warn?: string };\n\n/** Result from Migrator.upgrade() */\ninterface UpgradeResult {\n  version: number;\n  data: unknown;\n  warning?: string;\n}\n\n/**\n * Runs storage migration using the DataModel's upgrade callback.\n * This is the main entry point for the middle layer to trigger migrations.\n *\n * Uses the '__pl_data_upgrade' callback registered by DataModel.registerCallbacks() which:\n * - Handles all migration logic internally\n * - Returns { version, data, warning? } - warning present if reset to initial data\n *\n * @param currentStorageJson - Current storage as JSON string (or undefined)\n * @returns MigrationResult\n */\nfunction migrateStorage(currentStorageJson: string | undefined): MigrationResult {\n  // Get the callback registry context\n  const ctx = tryGetCfgRenderCtx();\n  if (ctx === undefined) {\n    return { error: 'Not in config rendering context' };\n  }\n\n  // Normalize storage to get current data and version\n  const { storage: currentStorage, data: currentData } = normalizeStorage(currentStorageJson);\n  const currentVersion = currentStorage.__dataVersion;\n\n  // Helper to create storage with given data and version\n  const createStorageJson = (data: unknown, version: number): string => {\n    return JSON.stringify({\n      ...currentStorage,\n      __dataVersion: version,\n      __data: data,\n    });\n  };\n\n  // Get the upgrade callback (registered by DataModel.registerCallbacks())\n  const upgradeCallback = ctx.callbackRegistry['__pl_data_upgrade'] as ((v: { version: number; data: unknown }) => UpgradeResult) | undefined;\n  if (typeof upgradeCallback !== 'function') {\n    return { error: '__pl_data_upgrade callback not found (DataModel not registered)' };\n  }\n\n  // Call the migrator's upgrade function\n  let result: UpgradeResult;\n  try {\n    result = upgradeCallback({ version: currentVersion, data: currentData });\n  } catch (e) {\n    const errorMsg = e instanceof Error ? e.message : String(e);\n    return { error: `upgrade() threw: ${errorMsg}` };\n  }\n\n  // Build info message\n  const info = result.version === currentVersion\n    ? `No migration needed (v${currentVersion})`\n    : result.warning\n      ? `Reset to initial data (v${result.version})`\n      : `Migrated v${currentVersion}→v${result.version}`;\n\n  return {\n    newStorageJson: createStorageJson(result.data, result.version),\n    info,\n    warn: result.warning,\n  };\n}\n\n// Register migrate callback\ntryRegisterCallback('__pl_storage_migrate', (currentStorageJson: string | undefined) => {\n  return migrateStorage(currentStorageJson);\n});\n\n// =============================================================================\n// Args Derivation from Storage\n// =============================================================================\n\n/**\n * Result of args derivation from storage.\n * Returned by __pl_args_derive and __pl_prerunArgs_derive callbacks.\n */\nexport type ArgsDeriveResult =\n  | { error: string }\n  | { error?: undefined; value: unknown };\n\n/**\n * Derives args from storage using the registered 'args' callback.\n * This extracts data from storage and passes it to the block's args() function.\n *\n * @param storageJson - Storage as JSON string\n * @returns ArgsDeriveResult with derived args or error\n */\nfunction deriveArgsFromStorage(storageJson: string): ArgsDeriveResult {\n  const ctx = tryGetCfgRenderCtx();\n  if (ctx === undefined) {\n    return { error: 'Not in config rendering context' };\n  }\n\n  // Extract data from storage\n  const { data } = normalizeStorage(storageJson);\n\n  // Get the args callback (registered by BlockModelV3.args())\n  const argsCallback = ctx.callbackRegistry['args'] as ((data: unknown) => unknown) | undefined;\n  if (typeof argsCallback !== 'function') {\n    return { error: 'args callback not found' };\n  }\n\n  // Call the args callback with extracted data\n  try {\n    const result = argsCallback(data);\n    return { value: result };\n  } catch (e) {\n    const errorMsg = e instanceof Error ? e.message : String(e);\n    return { error: `args() threw: ${errorMsg}` };\n  }\n}\n\n// Register args derivation callback\ntryRegisterCallback('__pl_args_derive', (storageJson: string) => {\n  return deriveArgsFromStorage(storageJson);\n});\n\n/**\n * Derives prerunArgs from storage using the registered 'prerunArgs' callback.\n * Falls back to 'args' callback if 'prerunArgs' is not defined.\n *\n * @param storageJson - Storage as JSON string\n * @returns ArgsDeriveResult with derived prerunArgs or error\n */\nfunction derivePrerunArgsFromStorage(storageJson: string): ArgsDeriveResult {\n  const ctx = tryGetCfgRenderCtx();\n  if (ctx === undefined) {\n    return { error: 'Not in config rendering context' };\n  }\n\n  // Extract data from storage\n  const { data } = normalizeStorage(storageJson);\n\n  // Try prerunArgs callback first\n  const prerunArgsCallback = ctx.callbackRegistry['prerunArgs'] as ((data: unknown) => unknown) | undefined;\n  if (typeof prerunArgsCallback === 'function') {\n    try {\n      const result = prerunArgsCallback(data);\n      return { value: result };\n    } catch (e) {\n      const errorMsg = e instanceof Error ? e.message : String(e);\n      return { error: `prerunArgs() threw: ${errorMsg}` };\n    }\n  }\n\n  // Fall back to args callback\n  const argsCallback = ctx.callbackRegistry['args'] as ((data: unknown) => unknown) | undefined;\n  if (typeof argsCallback !== 'function') {\n    return { error: 'args callback not found (fallback from missing prerunArgs)' };\n  }\n\n  try {\n    const result = argsCallback(data);\n    return { value: result };\n  } catch (e) {\n    const errorMsg = e instanceof Error ? e.message : String(e);\n    return { error: `args() threw (fallback): ${errorMsg}` };\n  }\n}\n\n// Register prerunArgs derivation callback\ntryRegisterCallback('__pl_prerunArgs_derive', (storageJson: string) => {\n  return derivePrerunArgsFromStorage(storageJson);\n});\n\n// Export discriminator key and schema version for external checks\nexport { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION };\n"],"names":["createBlockStorage","isBlockStorage","getStorageData","updateStorageData","tryRegisterCallback","tryGetCfgRenderCtx"],"mappings":"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"}

package/dist/block_storage_vm.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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
+ */
+import { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION, type BlockStorage } from './block_storage';
+/**
+ * Result of storage normalization
+ */
+export interface NormalizeStorageResult {
+    /** The normalized BlockStorage object */
+    storage: BlockStorage;
+    /** The extracted data (what developers see) */
+    data: unknown;
+}
+/**
+ * Storage info result returned by __pl_storage_getInfo callback.
+ */
+export interface StorageInfo {
+    /** Current data version (1-based, starts at 1) */
+    dataVersion: number;
+}
+/**
+ * Result of storage migration.
+ * Returned by __pl_storage_migrate callback.
+ *
+ * - Error result: { error: string } - serious failure (no context, etc.)
+ * - Success result: { newStorageJson: string, info: string, warn?: string } - migration succeeded or reset to initial
+ */
+export type MigrationResult = {
+    error: string;
+} | {
+    error?: undefined;
+    newStorageJson: string;
+    info: string;
+    warn?: string;
+};
+/**
+ * Result of args derivation from storage.
+ * Returned by __pl_args_derive and __pl_prerunArgs_derive callbacks.
+ */
+export type ArgsDeriveResult = {
+    error: string;
+} | {
+    error?: undefined;
+    value: unknown;
+};
+export { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION };
+//# sourceMappingURL=block_storage_vm.d.ts.map

package/dist/block_storage_vm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block_storage_vm.d.ts","sourceRoot":"","sources":["../src/block_storage_vm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EACL,iBAAiB,EACjB,4BAA4B,EAC5B,KAAK,YAAY,EAMlB,MAAM,iBAAiB,CAAC;AAGzB;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,yCAAyC;IACzC,OAAO,EAAE,YAAY,CAAC;IACtB,+CAA+C;IAC/C,IAAI,EAAE,OAAO,CAAC;CACf;AA2FD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;CACrB;AA0BD;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GACjB;IAAE,KAAK,CAAC,EAAE,SAAS,CAAC;IAAC,cAAc,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AA8E/E;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GACjB;IAAE,KAAK,CAAC,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAwF1C,OAAO,EAAE,iBAAiB,EAAE,4BAA4B,EAAE,CAAC"}