@milaboratories/pl-middle-layer 1.45.5 → 1.46.1

package/dist/middle_layer/render.cjs

@@ -14,7 +14,7 @@ function isActive(cfg) {
 function computableFromCfgOrRF(env, ctx, cfgOrFh, codeWithInfo, configKey, ops = {}) {
     if (model.isConfigLambda(cfgOrFh)) {
         if (codeWithInfo === undefined)
-            throw new Error('No code bundle.');
+            throw new Error('computableFromCfgOrRF: No code bundle.');
         return index.computableFromRF(env, ctx, cfgOrFh, codeWithInfo, configKey, ops);
     }
     else

package/dist/middle_layer/render.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"render.cjs","sources":["../../src/middle_layer/render.ts"],"sourcesContent":["import type { BlockCodeWithInfo, TypedConfigOrConfigLambda } from '@platforma-sdk/model';\nimport { isConfigLambda } from '@platforma-sdk/model';\nimport type { Computable, ComputableRenderingOps } from '@milaboratories/computable';\nimport { computableFromCfg } from '../cfg_render/executor';\nimport type { MiddleLayerEnvironment } from './middle_layer';\nimport { computableFromRF } from '../js_render';\nimport type { BlockContextAny } from './block_ctx';\nimport { hasActiveCfgComponents } from '../cfg_render/util';\n\nexport function isActive(cfg: TypedConfigOrConfigLambda): boolean {\n  if (isConfigLambda(cfg)) return cfg.isActive === true;\n  else return hasActiveCfgComponents(cfg);\n}\n\nexport function computableFromCfgOrRF(\n  env: MiddleLayerEnvironment,\n  ctx: BlockContextAny,\n  cfgOrFh: TypedConfigOrConfigLambda,\n  codeWithInfo: BlockCodeWithInfo | undefined,\n  configKey: string,\n  ops: Partial<ComputableRenderingOps> = {},\n): Computable<unknown> {\n  if (isConfigLambda(cfgOrFh)) {\n    if (codeWithInfo === undefined) throw new Error('No code bundle.');\n    return computableFromRF(env, ctx, cfgOrFh, codeWithInfo, configKey, ops);\n  } else return computableFromCfg(env.driverKit, ctx, cfgOrFh, ops);\n}\n"],"names":["isConfigLambda","hasActiveCfgComponents","computableFromRF","computableFromCfg"],"mappings":";;;;;;;AASM,SAAU,QAAQ,CAAC,GAA8B,EAAA;IACrD,IAAIA,oBAAc,CAAC,GAAG,CAAC;AAAE,QAAA,OAAO,GAAG,CAAC,QAAQ,KAAK,IAAI;;AAChD,QAAA,OAAOC,2BAAsB,CAAC,GAAG,CAAC;AACzC;AAEM,SAAU,qBAAqB,CACnC,GAA2B,EAC3B,GAAoB,EACpB,OAAkC,EAClC,YAA2C,EAC3C,SAAiB,EACjB,MAAuC,EAAE,EAAA;AAEzC,IAAA,IAAID,oBAAc,CAAC,OAAO,CAAC,EAAE;QAC3B,IAAI,YAAY,KAAK,SAAS;AAAE,YAAA,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC;AAClE,QAAA,OAAOE,sBAAgB,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,GAAG,CAAC;IAC1E;;AAAO,QAAA,OAAOC,0BAAiB,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC;AACnE;;;;;"}
+{"version":3,"file":"render.cjs","sources":["../../src/middle_layer/render.ts"],"sourcesContent":["import type { BlockCodeWithInfo, TypedConfigOrConfigLambda } from '@platforma-sdk/model';\nimport { isConfigLambda } from '@platforma-sdk/model';\nimport type { Computable, ComputableRenderingOps } from '@milaboratories/computable';\nimport { computableFromCfg } from '../cfg_render/executor';\nimport type { MiddleLayerEnvironment } from './middle_layer';\nimport { computableFromRF } from '../js_render';\nimport type { BlockContextAny } from './block_ctx';\nimport { hasActiveCfgComponents } from '../cfg_render/util';\n\nexport function isActive(cfg: TypedConfigOrConfigLambda): boolean {\n  if (isConfigLambda(cfg)) return cfg.isActive === true;\n  else return hasActiveCfgComponents(cfg);\n}\n\nexport function computableFromCfgOrRF(\n  env: MiddleLayerEnvironment,\n  ctx: BlockContextAny,\n  cfgOrFh: TypedConfigOrConfigLambda,\n  codeWithInfo: BlockCodeWithInfo | undefined,\n  configKey: string,\n  ops: Partial<ComputableRenderingOps> = {},\n): Computable<unknown> {\n  if (isConfigLambda(cfgOrFh)) {\n    if (codeWithInfo === undefined) throw new Error('computableFromCfgOrRF: No code bundle.');\n    return computableFromRF(env, ctx, cfgOrFh, codeWithInfo, configKey, ops);\n  } else return computableFromCfg(env.driverKit, ctx, cfgOrFh, ops);\n}\n"],"names":["isConfigLambda","hasActiveCfgComponents","computableFromRF","computableFromCfg"],"mappings":";;;;;;;AASM,SAAU,QAAQ,CAAC,GAA8B,EAAA;IACrD,IAAIA,oBAAc,CAAC,GAAG,CAAC;AAAE,QAAA,OAAO,GAAG,CAAC,QAAQ,KAAK,IAAI;;AAChD,QAAA,OAAOC,2BAAsB,CAAC,GAAG,CAAC;AACzC;AAEM,SAAU,qBAAqB,CACnC,GAA2B,EAC3B,GAAoB,EACpB,OAAkC,EAClC,YAA2C,EAC3C,SAAiB,EACjB,MAAuC,EAAE,EAAA;AAEzC,IAAA,IAAID,oBAAc,CAAC,OAAO,CAAC,EAAE;QAC3B,IAAI,YAAY,KAAK,SAAS;AAAE,YAAA,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC;AACzF,QAAA,OAAOE,sBAAgB,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,GAAG,CAAC;IAC1E;;AAAO,QAAA,OAAOC,0BAAiB,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC;AACnE;;;;;"}

package/dist/middle_layer/render.js

@@ -12,7 +12,7 @@ function isActive(cfg) {
 function computableFromCfgOrRF(env, ctx, cfgOrFh, codeWithInfo, configKey, ops = {}) {
     if (isConfigLambda(cfgOrFh)) {
         if (codeWithInfo === undefined)
-            throw new Error('No code bundle.');
+            throw new Error('computableFromCfgOrRF: No code bundle.');
         return computableFromRF(env, ctx, cfgOrFh, codeWithInfo, configKey, ops);
     }
     else

package/dist/middle_layer/render.js.map

@@ -1 +1 @@
-{"version":3,"file":"render.js","sources":["../../src/middle_layer/render.ts"],"sourcesContent":["import type { BlockCodeWithInfo, TypedConfigOrConfigLambda } from '@platforma-sdk/model';\nimport { isConfigLambda } from '@platforma-sdk/model';\nimport type { Computable, ComputableRenderingOps } from '@milaboratories/computable';\nimport { computableFromCfg } from '../cfg_render/executor';\nimport type { MiddleLayerEnvironment } from './middle_layer';\nimport { computableFromRF } from '../js_render';\nimport type { BlockContextAny } from './block_ctx';\nimport { hasActiveCfgComponents } from '../cfg_render/util';\n\nexport function isActive(cfg: TypedConfigOrConfigLambda): boolean {\n  if (isConfigLambda(cfg)) return cfg.isActive === true;\n  else return hasActiveCfgComponents(cfg);\n}\n\nexport function computableFromCfgOrRF(\n  env: MiddleLayerEnvironment,\n  ctx: BlockContextAny,\n  cfgOrFh: TypedConfigOrConfigLambda,\n  codeWithInfo: BlockCodeWithInfo | undefined,\n  configKey: string,\n  ops: Partial<ComputableRenderingOps> = {},\n): Computable<unknown> {\n  if (isConfigLambda(cfgOrFh)) {\n    if (codeWithInfo === undefined) throw new Error('No code bundle.');\n    return computableFromRF(env, ctx, cfgOrFh, codeWithInfo, configKey, ops);\n  } else return computableFromCfg(env.driverKit, ctx, cfgOrFh, ops);\n}\n"],"names":[],"mappings":";;;;;AASM,SAAU,QAAQ,CAAC,GAA8B,EAAA;IACrD,IAAI,cAAc,CAAC,GAAG,CAAC;AAAE,QAAA,OAAO,GAAG,CAAC,QAAQ,KAAK,IAAI;;AAChD,QAAA,OAAO,sBAAsB,CAAC,GAAG,CAAC;AACzC;AAEM,SAAU,qBAAqB,CACnC,GAA2B,EAC3B,GAAoB,EACpB,OAAkC,EAClC,YAA2C,EAC3C,SAAiB,EACjB,MAAuC,EAAE,EAAA;AAEzC,IAAA,IAAI,cAAc,CAAC,OAAO,CAAC,EAAE;QAC3B,IAAI,YAAY,KAAK,SAAS;AAAE,YAAA,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC;AAClE,QAAA,OAAO,gBAAgB,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,GAAG,CAAC;IAC1E;;AAAO,QAAA,OAAO,iBAAiB,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC;AACnE;;;;"}
+{"version":3,"file":"render.js","sources":["../../src/middle_layer/render.ts"],"sourcesContent":["import type { BlockCodeWithInfo, TypedConfigOrConfigLambda } from '@platforma-sdk/model';\nimport { isConfigLambda } from '@platforma-sdk/model';\nimport type { Computable, ComputableRenderingOps } from '@milaboratories/computable';\nimport { computableFromCfg } from '../cfg_render/executor';\nimport type { MiddleLayerEnvironment } from './middle_layer';\nimport { computableFromRF } from '../js_render';\nimport type { BlockContextAny } from './block_ctx';\nimport { hasActiveCfgComponents } from '../cfg_render/util';\n\nexport function isActive(cfg: TypedConfigOrConfigLambda): boolean {\n  if (isConfigLambda(cfg)) return cfg.isActive === true;\n  else return hasActiveCfgComponents(cfg);\n}\n\nexport function computableFromCfgOrRF(\n  env: MiddleLayerEnvironment,\n  ctx: BlockContextAny,\n  cfgOrFh: TypedConfigOrConfigLambda,\n  codeWithInfo: BlockCodeWithInfo | undefined,\n  configKey: string,\n  ops: Partial<ComputableRenderingOps> = {},\n): Computable<unknown> {\n  if (isConfigLambda(cfgOrFh)) {\n    if (codeWithInfo === undefined) throw new Error('computableFromCfgOrRF: No code bundle.');\n    return computableFromRF(env, ctx, cfgOrFh, codeWithInfo, configKey, ops);\n  } else return computableFromCfg(env.driverKit, ctx, cfgOrFh, ops);\n}\n"],"names":[],"mappings":";;;;;AASM,SAAU,QAAQ,CAAC,GAA8B,EAAA;IACrD,IAAI,cAAc,CAAC,GAAG,CAAC;AAAE,QAAA,OAAO,GAAG,CAAC,QAAQ,KAAK,IAAI;;AAChD,QAAA,OAAO,sBAAsB,CAAC,GAAG,CAAC;AACzC;AAEM,SAAU,qBAAqB,CACnC,GAA2B,EAC3B,GAAoB,EACpB,OAAkC,EAClC,YAA2C,EAC3C,SAAiB,EACjB,MAAuC,EAAE,EAAA;AAEzC,IAAA,IAAI,cAAc,CAAC,OAAO,CAAC,EAAE;QAC3B,IAAI,YAAY,KAAK,SAAS;AAAE,YAAA,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC;AACzF,QAAA,OAAO,gBAAgB,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,GAAG,CAAC;IAC1E;;AAAO,QAAA,OAAO,iBAAiB,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC;AACnE;;;;"}

package/dist/middle_layer/render.test.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render.test.d.ts","sourceRoot":"","sources":["../../src/middle_layer/render.test.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,wBAAsB,MAAM,CAC1B,EAAE,EAAE,CAAC,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GACzD,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED,wBAAsB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAa,iBAsBzF"}
+{"version":3,"file":"render.test.d.ts","sourceRoot":"","sources":["../../src/middle_layer/render.test.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,wBAAsB,MAAM,CAC1B,EAAE,EAAE,CAAC,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GACzD,OAAO,CAAC,IAAI,CAAC,CAsBf;AAED,wBAAsB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,MAAa,iBAsBzF"}

package/dist/model/block_storage_helper.cjs

@@ -0,0 +1,210 @@
+'use strict';
+
+var model = require('@platforma-sdk/model');
+
+/**
+ * Block Storage Helper - Middle layer utilities for BlockStorage operations.
+ *
+ * This module provides the bridge between the SDK's BlockStorage abstraction
+ * and the middle layer's storage operations. Block developers never interact
+ * with this - they only see `state`.
+ *
+ * @module block_storage_helper
+ */
+/**
+ * Parses raw blockStorage data (from resource tree) into BlockStorage.
+ * Handles both legacy format (raw state) and new format (BlockStorage).
+ *
+ * @param rawData - Raw data from blockStorage field (may be string or parsed object)
+ * @returns Normalized BlockStorage object
+ */
+function parseBlockStorage(rawData) {
+    if (rawData === undefined || rawData === null) {
+        return model.createBlockStorage({});
+    }
+    // If it's a string, parse it first
+    if (typeof rawData === 'string') {
+        try {
+            const parsed = JSON.parse(rawData);
+            return model.normalizeBlockStorage(parsed);
+        }
+        catch {
+            // If parsing fails, treat the string as the state itself
+            return model.createBlockStorage(rawData);
+        }
+    }
+    return model.normalizeBlockStorage(rawData);
+}
+/**
+ * Extracts the user-facing data from BlockStorage.
+ * This is what block developers see in their .args() callbacks.
+ *
+ * @param storage - The BlockStorage object
+ * @returns The data value that developers work with
+ */
+function extractDataForDeveloper(storage) {
+    return model.getStorageData(storage);
+}
+/**
+ * Creates a new BlockStorage with updated state.
+ * Used when setState is called from the frontend.
+ *
+ * @param currentStorage - Current BlockStorage (or undefined for new blocks)
+ * @param newState - New state from developer
+ * @param handlers - Optional custom handlers (defaults to standard handlers)
+ * @returns Updated BlockStorage
+ */
+function applyStateUpdate(currentStorage, newState, handlers = model.defaultBlockStorageHandlers) {
+    const storage = currentStorage ?? model.createBlockStorage({});
+    const transform = handlers.transformStateForStorage ?? model.defaultBlockStorageHandlers.transformStateForStorage;
+    return transform(storage, newState);
+}
+/**
+ * Serializes BlockStorage for writing to the resource tree.
+ *
+ * @param storage - The BlockStorage to serialize
+ * @returns JSON string
+ */
+function serializeBlockStorage(storage) {
+    return JSON.stringify(storage);
+}
+/**
+ * Checks if the storage needs migration based on version.
+ *
+ * @param storage - Current BlockStorage
+ * @param targetVersion - Target schema version
+ * @returns true if migration is needed
+ */
+function needsMigration(storage, targetVersion) {
+    return model.getStorageDataVersion(storage) < targetVersion;
+}
+/**
+ * Migrates BlockStorage from one version to another.
+ *
+ * @param storage - Current BlockStorage
+ * @param fromVersion - Source version
+ * @param toVersion - Target version
+ * @param handlers - Optional custom handlers
+ * @returns Migrated BlockStorage
+ */
+function migrateBlockStorage(storage, fromVersion, toVersion, handlers = model.defaultBlockStorageHandlers) {
+    const migrate = handlers.migrateStorage ?? model.defaultBlockStorageHandlers.migrateStorage;
+    return migrate(storage, fromVersion, toVersion);
+}
+/**
+ * Checks if the raw data is in legacy V1/V2 format.
+ * V1/V2 blocks stored { args, uiState } directly, not wrapped in BlockStorage.
+ *
+ * @param rawData - Raw data from blockStorage field
+ * @returns true if data is in legacy format
+ */
+function isLegacyV1V2Format(rawData) {
+    if (rawData === null || typeof rawData !== 'object')
+        return false;
+    // If it has the discriminator, it's BlockStorage format
+    if (model.isBlockStorage(rawData))
+        return false;
+    const obj = rawData;
+    // Legacy format has 'args' and/or 'uiState' at top level, no discriminator
+    return ('args' in obj || 'uiState' in obj);
+}
+/**
+ * Converts legacy V1/V2 format to BlockStorage.
+ * For backward compatibility with existing blocks.
+ *
+ * @param legacyData - Data in { args, uiState } format
+ * @returns BlockStorage with legacy data as state
+ */
+function convertLegacyToBlockStorage(legacyData) {
+    return model.createBlockStorage(legacyData, 1);
+}
+/**
+ * Smart parser that handles all storage formats:
+ * - New BlockStorage format
+ * - Legacy V1/V2 format ({ args, uiState })
+ * - Raw state (any other format)
+ *
+ * @param rawData - Raw data from blockStorage field
+ * @returns Normalized BlockStorage
+ */
+function parseBlockStorageSmart(rawData) {
+    if (rawData === undefined || rawData === null) {
+        return model.createBlockStorage({});
+    }
+    // If it's a string, parse it first
+    let parsed = rawData;
+    if (typeof rawData === 'string') {
+        try {
+            parsed = JSON.parse(rawData);
+        }
+        catch {
+            // If parsing fails, treat the string as the state itself
+            return model.createBlockStorage(rawData);
+        }
+    }
+    // Check for legacy V1/V2 format
+    if (isLegacyV1V2Format(parsed)) {
+        return convertLegacyToBlockStorage(parsed);
+    }
+    // Use standard normalization
+    return model.normalizeBlockStorage(parsed);
+}
+
+Object.defineProperty(exports, "BLOCK_STORAGE_KEY", {
+    enumerable: true,
+    get: function () { return model.BLOCK_STORAGE_KEY; }
+});
+Object.defineProperty(exports, "BLOCK_STORAGE_SCHEMA_VERSION", {
+    enumerable: true,
+    get: function () { return model.BLOCK_STORAGE_SCHEMA_VERSION; }
+});
+Object.defineProperty(exports, "createBlockStorage", {
+    enumerable: true,
+    get: function () { return model.createBlockStorage; }
+});
+Object.defineProperty(exports, "defaultBlockStorageHandlers", {
+    enumerable: true,
+    get: function () { return model.defaultBlockStorageHandlers; }
+});
+Object.defineProperty(exports, "getPluginData", {
+    enumerable: true,
+    get: function () { return model.getPluginData; }
+});
+Object.defineProperty(exports, "getStorageData", {
+    enumerable: true,
+    get: function () { return model.getStorageData; }
+});
+Object.defineProperty(exports, "getStorageDataVersion", {
+    enumerable: true,
+    get: function () { return model.getStorageDataVersion; }
+});
+Object.defineProperty(exports, "isBlockStorage", {
+    enumerable: true,
+    get: function () { return model.isBlockStorage; }
+});
+Object.defineProperty(exports, "normalizeBlockStorage", {
+    enumerable: true,
+    get: function () { return model.normalizeBlockStorage; }
+});
+Object.defineProperty(exports, "setPluginData", {
+    enumerable: true,
+    get: function () { return model.setPluginData; }
+});
+Object.defineProperty(exports, "updateStorageData", {
+    enumerable: true,
+    get: function () { return model.updateStorageData; }
+});
+Object.defineProperty(exports, "updateStorageDataVersion", {
+    enumerable: true,
+    get: function () { return model.updateStorageDataVersion; }
+});
+exports.applyStateUpdate = applyStateUpdate;
+exports.convertLegacyToBlockStorage = convertLegacyToBlockStorage;
+exports.extractDataForDeveloper = extractDataForDeveloper;
+exports.isLegacyV1V2Format = isLegacyV1V2Format;
+exports.migrateBlockStorage = migrateBlockStorage;
+exports.needsMigration = needsMigration;
+exports.parseBlockStorage = parseBlockStorage;
+exports.parseBlockStorageSmart = parseBlockStorageSmart;
+exports.serializeBlockStorage = serializeBlockStorage;
+//# sourceMappingURL=block_storage_helper.cjs.map

package/dist/model/block_storage_helper.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"block_storage_helper.cjs","sources":["../../src/model/block_storage_helper.ts"],"sourcesContent":["/**\n * Block Storage Helper - Middle layer utilities for BlockStorage operations.\n *\n * This module provides the bridge between the SDK's BlockStorage abstraction\n * and the middle layer's storage operations. Block developers never interact\n * with this - they only see `state`.\n *\n * @module block_storage_helper\n */\n\nimport type {\n  BlockStorage,\n  BlockStorageHandlers,\n} from '@platforma-sdk/model';\nimport {\n  BLOCK_STORAGE_KEY,\n  BLOCK_STORAGE_SCHEMA_VERSION,\n  createBlockStorage,\n  defaultBlockStorageHandlers,\n  getPluginData,\n  getStorageData,\n  getStorageDataVersion,\n  isBlockStorage,\n  normalizeBlockStorage,\n  setPluginData,\n  updateStorageData,\n  updateStorageDataVersion,\n} from '@platforma-sdk/model';\n\n// Re-export types for convenience\nexport type { BlockStorage, BlockStorageHandlers };\n\n// Re-export utilities that middle layer needs\nexport {\n  BLOCK_STORAGE_KEY,\n  BLOCK_STORAGE_SCHEMA_VERSION,\n  createBlockStorage,\n  defaultBlockStorageHandlers,\n  getPluginData,\n  getStorageData,\n  getStorageDataVersion,\n  isBlockStorage,\n  normalizeBlockStorage,\n  setPluginData,\n  updateStorageData,\n  updateStorageDataVersion,\n};\n\n/**\n * Parses raw blockStorage data (from resource tree) into BlockStorage.\n * Handles both legacy format (raw state) and new format (BlockStorage).\n *\n * @param rawData - Raw data from blockStorage field (may be string or parsed object)\n * @returns Normalized BlockStorage object\n */\nexport function parseBlockStorage<TState = unknown>(rawData: unknown): BlockStorage<TState> {\n  if (rawData === undefined || rawData === null) {\n    return createBlockStorage<TState>({} as TState);\n  }\n\n  // If it's a string, parse it first\n  if (typeof rawData === 'string') {\n    try {\n      const parsed = JSON.parse(rawData);\n      return normalizeBlockStorage<TState>(parsed);\n    } catch {\n      // If parsing fails, treat the string as the state itself\n      return createBlockStorage(rawData as unknown as TState);\n    }\n  }\n\n  return normalizeBlockStorage<TState>(rawData);\n}\n\n/**\n * Extracts the user-facing data from BlockStorage.\n * This is what block developers see in their .args() callbacks.\n *\n * @param storage - The BlockStorage object\n * @returns The data value that developers work with\n */\nexport function extractDataForDeveloper<TState>(storage: BlockStorage<TState>): TState {\n  return getStorageData(storage);\n}\n\n/**\n * Creates a new BlockStorage with updated state.\n * Used when setState is called from the frontend.\n *\n * @param currentStorage - Current BlockStorage (or undefined for new blocks)\n * @param newState - New state from developer\n * @param handlers - Optional custom handlers (defaults to standard handlers)\n * @returns Updated BlockStorage\n */\nexport function applyStateUpdate<TState>(\n  currentStorage: BlockStorage<TState> | undefined,\n  newState: TState,\n  handlers: BlockStorageHandlers<TState> = defaultBlockStorageHandlers as BlockStorageHandlers<TState>,\n): BlockStorage<TState> {\n  const storage = currentStorage ?? createBlockStorage<TState>({} as TState);\n  const transform = handlers.transformStateForStorage ?? defaultBlockStorageHandlers.transformStateForStorage;\n  return transform(storage, newState) as BlockStorage<TState>;\n}\n\n/**\n * Serializes BlockStorage for writing to the resource tree.\n *\n * @param storage - The BlockStorage to serialize\n * @returns JSON string\n */\nexport function serializeBlockStorage(storage: BlockStorage): string {\n  return JSON.stringify(storage);\n}\n\n/**\n * Checks if the storage needs migration based on version.\n *\n * @param storage - Current BlockStorage\n * @param targetVersion - Target schema version\n * @returns true if migration is needed\n */\nexport function needsMigration(storage: BlockStorage, targetVersion: number): boolean {\n  return getStorageDataVersion(storage) < targetVersion;\n}\n\n/**\n * Migrates BlockStorage from one version to another.\n *\n * @param storage - Current BlockStorage\n * @param fromVersion - Source version\n * @param toVersion - Target version\n * @param handlers - Optional custom handlers\n * @returns Migrated BlockStorage\n */\nexport function migrateBlockStorage<TState>(\n  storage: BlockStorage<TState>,\n  fromVersion: number,\n  toVersion: number,\n  handlers: BlockStorageHandlers<TState> = defaultBlockStorageHandlers as BlockStorageHandlers<TState>,\n): BlockStorage<TState> {\n  const migrate = handlers.migrateStorage ?? defaultBlockStorageHandlers.migrateStorage;\n  return migrate(storage, fromVersion, toVersion) as BlockStorage<TState>;\n}\n\n/**\n * V1/V2 legacy format - state stored as { args, uiState }\n */\nexport interface LegacyV1V2State {\n  args?: unknown;\n  uiState?: unknown;\n}\n\n/**\n * Checks if the raw data is in legacy V1/V2 format.\n * V1/V2 blocks stored { args, uiState } directly, not wrapped in BlockStorage.\n *\n * @param rawData - Raw data from blockStorage field\n * @returns true if data is in legacy format\n */\nexport function isLegacyV1V2Format(rawData: unknown): rawData is LegacyV1V2State {\n  if (rawData === null || typeof rawData !== 'object') return false;\n  // If it has the discriminator, it's BlockStorage format\n  if (isBlockStorage(rawData)) return false;\n\n  const obj = rawData as Record<string, unknown>;\n  // Legacy format has 'args' and/or 'uiState' at top level, no discriminator\n  return ('args' in obj || 'uiState' in obj);\n}\n\n/**\n * Converts legacy V1/V2 format to BlockStorage.\n * For backward compatibility with existing blocks.\n *\n * @param legacyData - Data in { args, uiState } format\n * @returns BlockStorage with legacy data as state\n */\nexport function convertLegacyToBlockStorage(legacyData: LegacyV1V2State): BlockStorage<LegacyV1V2State> {\n  return createBlockStorage(legacyData, 1);\n}\n\n/**\n * Smart parser that handles all storage formats:\n * - New BlockStorage format\n * - Legacy V1/V2 format ({ args, uiState })\n * - Raw state (any other format)\n *\n * @param rawData - Raw data from blockStorage field\n * @returns Normalized BlockStorage\n */\nexport function parseBlockStorageSmart<TState = unknown>(rawData: unknown): BlockStorage<TState> {\n  if (rawData === undefined || rawData === null) {\n    return createBlockStorage<TState>({} as TState);\n  }\n\n  // If it's a string, parse it first\n  let parsed = rawData;\n  if (typeof rawData === 'string') {\n    try {\n      parsed = JSON.parse(rawData);\n    } catch {\n      // If parsing fails, treat the string as the state itself\n      return createBlockStorage(rawData as unknown as TState);\n    }\n  }\n\n  // Check for legacy V1/V2 format\n  if (isLegacyV1V2Format(parsed)) {\n    return convertLegacyToBlockStorage(parsed) as unknown as BlockStorage<TState>;\n  }\n\n  // Use standard normalization\n  return normalizeBlockStorage<TState>(parsed);\n}\n"],"names":["createBlockStorage","normalizeBlockStorage","getStorageData","defaultBlockStorageHandlers","getStorageDataVersion","isBlockStorage"],"mappings":"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"}

package/dist/model/block_storage_helper.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Block Storage Helper - Middle layer utilities for BlockStorage operations.
+ *
+ * This module provides the bridge between the SDK's BlockStorage abstraction
+ * and the middle layer's storage operations. Block developers never interact
+ * with this - they only see `state`.
+ *
+ * @module block_storage_helper
+ */
+import type { BlockStorage, BlockStorageHandlers } from '@platforma-sdk/model';
+import { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION, createBlockStorage, defaultBlockStorageHandlers, getPluginData, getStorageData, getStorageDataVersion, isBlockStorage, normalizeBlockStorage, setPluginData, updateStorageData, updateStorageDataVersion } from '@platforma-sdk/model';
+export type { BlockStorage, BlockStorageHandlers };
+export { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION, createBlockStorage, defaultBlockStorageHandlers, getPluginData, getStorageData, getStorageDataVersion, isBlockStorage, normalizeBlockStorage, setPluginData, updateStorageData, updateStorageDataVersion, };
+/**
+ * Parses raw blockStorage data (from resource tree) into BlockStorage.
+ * Handles both legacy format (raw state) and new format (BlockStorage).
+ *
+ * @param rawData - Raw data from blockStorage field (may be string or parsed object)
+ * @returns Normalized BlockStorage object
+ */
+export declare function parseBlockStorage<TState = unknown>(rawData: unknown): BlockStorage<TState>;
+/**
+ * Extracts the user-facing data from BlockStorage.
+ * This is what block developers see in their .args() callbacks.
+ *
+ * @param storage - The BlockStorage object
+ * @returns The data value that developers work with
+ */
+export declare function extractDataForDeveloper<TState>(storage: BlockStorage<TState>): TState;
+/**
+ * Creates a new BlockStorage with updated state.
+ * Used when setState is called from the frontend.
+ *
+ * @param currentStorage - Current BlockStorage (or undefined for new blocks)
+ * @param newState - New state from developer
+ * @param handlers - Optional custom handlers (defaults to standard handlers)
+ * @returns Updated BlockStorage
+ */
+export declare function applyStateUpdate<TState>(currentStorage: BlockStorage<TState> | undefined, newState: TState, handlers?: BlockStorageHandlers<TState>): BlockStorage<TState>;
+/**
+ * Serializes BlockStorage for writing to the resource tree.
+ *
+ * @param storage - The BlockStorage to serialize
+ * @returns JSON string
+ */
+export declare function serializeBlockStorage(storage: BlockStorage): string;
+/**
+ * Checks if the storage needs migration based on version.
+ *
+ * @param storage - Current BlockStorage
+ * @param targetVersion - Target schema version
+ * @returns true if migration is needed
+ */
+export declare function needsMigration(storage: BlockStorage, targetVersion: number): boolean;
+/**
+ * Migrates BlockStorage from one version to another.
+ *
+ * @param storage - Current BlockStorage
+ * @param fromVersion - Source version
+ * @param toVersion - Target version
+ * @param handlers - Optional custom handlers
+ * @returns Migrated BlockStorage
+ */
+export declare function migrateBlockStorage<TState>(storage: BlockStorage<TState>, fromVersion: number, toVersion: number, handlers?: BlockStorageHandlers<TState>): BlockStorage<TState>;
+/**
+ * V1/V2 legacy format - state stored as { args, uiState }
+ */
+export interface LegacyV1V2State {
+    args?: unknown;
+    uiState?: unknown;
+}
+/**
+ * Checks if the raw data is in legacy V1/V2 format.
+ * V1/V2 blocks stored { args, uiState } directly, not wrapped in BlockStorage.
+ *
+ * @param rawData - Raw data from blockStorage field
+ * @returns true if data is in legacy format
+ */
+export declare function isLegacyV1V2Format(rawData: unknown): rawData is LegacyV1V2State;
+/**
+ * Converts legacy V1/V2 format to BlockStorage.
+ * For backward compatibility with existing blocks.
+ *
+ * @param legacyData - Data in { args, uiState } format
+ * @returns BlockStorage with legacy data as state
+ */
+export declare function convertLegacyToBlockStorage(legacyData: LegacyV1V2State): BlockStorage<LegacyV1V2State>;
+/**
+ * Smart parser that handles all storage formats:
+ * - New BlockStorage format
+ * - Legacy V1/V2 format ({ args, uiState })
+ * - Raw state (any other format)
+ *
+ * @param rawData - Raw data from blockStorage field
+ * @returns Normalized BlockStorage
+ */
+export declare function parseBlockStorageSmart<TState = unknown>(rawData: unknown): BlockStorage<TState>;
+//# sourceMappingURL=block_storage_helper.d.ts.map

package/dist/model/block_storage_helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block_storage_helper.d.ts","sourceRoot":"","sources":["../../src/model/block_storage_helper.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,oBAAoB,EACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,iBAAiB,EACjB,4BAA4B,EAC5B,kBAAkB,EAClB,2BAA2B,EAC3B,aAAa,EACb,cAAc,EACd,qBAAqB,EACrB,cAAc,EACd,qBAAqB,EACrB,aAAa,EACb,iBAAiB,EACjB,wBAAwB,EACzB,MAAM,sBAAsB,CAAC;AAG9B,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,CAAC;AAGnD,OAAO,EACL,iBAAiB,EACjB,4BAA4B,EAC5B,kBAAkB,EAClB,2BAA2B,EAC3B,aAAa,EACb,cAAc,EACd,qBAAqB,EACrB,cAAc,EACd,qBAAqB,EACrB,aAAa,EACb,iBAAiB,EACjB,wBAAwB,GACzB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,YAAY,CAAC,MAAM,CAAC,CAiB1F;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,MAAM,CAErF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EACrC,cAAc,EAAE,YAAY,CAAC,MAAM,CAAC,GAAG,SAAS,EAChD,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,oBAAoB,CAAC,MAAM,CAA+D,GACnG,YAAY,CAAC,MAAM,CAAC,CAItB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAEnE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAEpF;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EACxC,OAAO,EAAE,YAAY,CAAC,MAAM,CAAC,EAC7B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,QAAQ,GAAE,oBAAoB,CAAC,MAAM,CAA+D,GACnG,YAAY,CAAC,MAAM,CAAC,CAGtB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,eAAe,CAQ/E;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,eAAe,GAAG,YAAY,CAAC,eAAe,CAAC,CAEtG;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,YAAY,CAAC,MAAM,CAAC,CAuB/F"}

package/dist/model/block_storage_helper.js

@@ -0,0 +1,153 @@
+import { defaultBlockStorageHandlers, createBlockStorage, normalizeBlockStorage, getStorageData, getStorageDataVersion, isBlockStorage } from '@platforma-sdk/model';
+export { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION, createBlockStorage, defaultBlockStorageHandlers, getPluginData, getStorageData, getStorageDataVersion, isBlockStorage, normalizeBlockStorage, setPluginData, updateStorageData, updateStorageDataVersion } from '@platforma-sdk/model';
+
+/**
+ * Block Storage Helper - Middle layer utilities for BlockStorage operations.
+ *
+ * This module provides the bridge between the SDK's BlockStorage abstraction
+ * and the middle layer's storage operations. Block developers never interact
+ * with this - they only see `state`.
+ *
+ * @module block_storage_helper
+ */
+/**
+ * Parses raw blockStorage data (from resource tree) into BlockStorage.
+ * Handles both legacy format (raw state) and new format (BlockStorage).
+ *
+ * @param rawData - Raw data from blockStorage field (may be string or parsed object)
+ * @returns Normalized BlockStorage object
+ */
+function parseBlockStorage(rawData) {
+    if (rawData === undefined || rawData === null) {
+        return createBlockStorage({});
+    }
+    // If it's a string, parse it first
+    if (typeof rawData === 'string') {
+        try {
+            const parsed = JSON.parse(rawData);
+            return normalizeBlockStorage(parsed);
+        }
+        catch {
+            // If parsing fails, treat the string as the state itself
+            return createBlockStorage(rawData);
+        }
+    }
+    return normalizeBlockStorage(rawData);
+}
+/**
+ * Extracts the user-facing data from BlockStorage.
+ * This is what block developers see in their .args() callbacks.
+ *
+ * @param storage - The BlockStorage object
+ * @returns The data value that developers work with
+ */
+function extractDataForDeveloper(storage) {
+    return getStorageData(storage);
+}
+/**
+ * Creates a new BlockStorage with updated state.
+ * Used when setState is called from the frontend.
+ *
+ * @param currentStorage - Current BlockStorage (or undefined for new blocks)
+ * @param newState - New state from developer
+ * @param handlers - Optional custom handlers (defaults to standard handlers)
+ * @returns Updated BlockStorage
+ */
+function applyStateUpdate(currentStorage, newState, handlers = defaultBlockStorageHandlers) {
+    const storage = currentStorage ?? createBlockStorage({});
+    const transform = handlers.transformStateForStorage ?? defaultBlockStorageHandlers.transformStateForStorage;
+    return transform(storage, newState);
+}
+/**
+ * Serializes BlockStorage for writing to the resource tree.
+ *
+ * @param storage - The BlockStorage to serialize
+ * @returns JSON string
+ */
+function serializeBlockStorage(storage) {
+    return JSON.stringify(storage);
+}
+/**
+ * Checks if the storage needs migration based on version.
+ *
+ * @param storage - Current BlockStorage
+ * @param targetVersion - Target schema version
+ * @returns true if migration is needed
+ */
+function needsMigration(storage, targetVersion) {
+    return getStorageDataVersion(storage) < targetVersion;
+}
+/**
+ * Migrates BlockStorage from one version to another.
+ *
+ * @param storage - Current BlockStorage
+ * @param fromVersion - Source version
+ * @param toVersion - Target version
+ * @param handlers - Optional custom handlers
+ * @returns Migrated BlockStorage
+ */
+function migrateBlockStorage(storage, fromVersion, toVersion, handlers = defaultBlockStorageHandlers) {
+    const migrate = handlers.migrateStorage ?? defaultBlockStorageHandlers.migrateStorage;
+    return migrate(storage, fromVersion, toVersion);
+}
+/**
+ * Checks if the raw data is in legacy V1/V2 format.
+ * V1/V2 blocks stored { args, uiState } directly, not wrapped in BlockStorage.
+ *
+ * @param rawData - Raw data from blockStorage field
+ * @returns true if data is in legacy format
+ */
+function isLegacyV1V2Format(rawData) {
+    if (rawData === null || typeof rawData !== 'object')
+        return false;
+    // If it has the discriminator, it's BlockStorage format
+    if (isBlockStorage(rawData))
+        return false;
+    const obj = rawData;
+    // Legacy format has 'args' and/or 'uiState' at top level, no discriminator
+    return ('args' in obj || 'uiState' in obj);
+}
+/**
+ * Converts legacy V1/V2 format to BlockStorage.
+ * For backward compatibility with existing blocks.
+ *
+ * @param legacyData - Data in { args, uiState } format
+ * @returns BlockStorage with legacy data as state
+ */
+function convertLegacyToBlockStorage(legacyData) {
+    return createBlockStorage(legacyData, 1);
+}
+/**
+ * Smart parser that handles all storage formats:
+ * - New BlockStorage format
+ * - Legacy V1/V2 format ({ args, uiState })
+ * - Raw state (any other format)
+ *
+ * @param rawData - Raw data from blockStorage field
+ * @returns Normalized BlockStorage
+ */
+function parseBlockStorageSmart(rawData) {
+    if (rawData === undefined || rawData === null) {
+        return createBlockStorage({});
+    }
+    // If it's a string, parse it first
+    let parsed = rawData;
+    if (typeof rawData === 'string') {
+        try {
+            parsed = JSON.parse(rawData);
+        }
+        catch {
+            // If parsing fails, treat the string as the state itself
+            return createBlockStorage(rawData);
+        }
+    }
+    // Check for legacy V1/V2 format
+    if (isLegacyV1V2Format(parsed)) {
+        return convertLegacyToBlockStorage(parsed);
+    }
+    // Use standard normalization
+    return normalizeBlockStorage(parsed);
+}
+
+export { applyStateUpdate, convertLegacyToBlockStorage, extractDataForDeveloper, isLegacyV1V2Format, migrateBlockStorage, needsMigration, parseBlockStorage, parseBlockStorageSmart, serializeBlockStorage };
+//# sourceMappingURL=block_storage_helper.js.map

package/dist/model/block_storage_helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"block_storage_helper.js","sources":["../../src/model/block_storage_helper.ts"],"sourcesContent":["/**\n * Block Storage Helper - Middle layer utilities for BlockStorage operations.\n *\n * This module provides the bridge between the SDK's BlockStorage abstraction\n * and the middle layer's storage operations. Block developers never interact\n * with this - they only see `state`.\n *\n * @module block_storage_helper\n */\n\nimport type {\n  BlockStorage,\n  BlockStorageHandlers,\n} from '@platforma-sdk/model';\nimport {\n  BLOCK_STORAGE_KEY,\n  BLOCK_STORAGE_SCHEMA_VERSION,\n  createBlockStorage,\n  defaultBlockStorageHandlers,\n  getPluginData,\n  getStorageData,\n  getStorageDataVersion,\n  isBlockStorage,\n  normalizeBlockStorage,\n  setPluginData,\n  updateStorageData,\n  updateStorageDataVersion,\n} from '@platforma-sdk/model';\n\n// Re-export types for convenience\nexport type { BlockStorage, BlockStorageHandlers };\n\n// Re-export utilities that middle layer needs\nexport {\n  BLOCK_STORAGE_KEY,\n  BLOCK_STORAGE_SCHEMA_VERSION,\n  createBlockStorage,\n  defaultBlockStorageHandlers,\n  getPluginData,\n  getStorageData,\n  getStorageDataVersion,\n  isBlockStorage,\n  normalizeBlockStorage,\n  setPluginData,\n  updateStorageData,\n  updateStorageDataVersion,\n};\n\n/**\n * Parses raw blockStorage data (from resource tree) into BlockStorage.\n * Handles both legacy format (raw state) and new format (BlockStorage).\n *\n * @param rawData - Raw data from blockStorage field (may be string or parsed object)\n * @returns Normalized BlockStorage object\n */\nexport function parseBlockStorage<TState = unknown>(rawData: unknown): BlockStorage<TState> {\n  if (rawData === undefined || rawData === null) {\n    return createBlockStorage<TState>({} as TState);\n  }\n\n  // If it's a string, parse it first\n  if (typeof rawData === 'string') {\n    try {\n      const parsed = JSON.parse(rawData);\n      return normalizeBlockStorage<TState>(parsed);\n    } catch {\n      // If parsing fails, treat the string as the state itself\n      return createBlockStorage(rawData as unknown as TState);\n    }\n  }\n\n  return normalizeBlockStorage<TState>(rawData);\n}\n\n/**\n * Extracts the user-facing data from BlockStorage.\n * This is what block developers see in their .args() callbacks.\n *\n * @param storage - The BlockStorage object\n * @returns The data value that developers work with\n */\nexport function extractDataForDeveloper<TState>(storage: BlockStorage<TState>): TState {\n  return getStorageData(storage);\n}\n\n/**\n * Creates a new BlockStorage with updated state.\n * Used when setState is called from the frontend.\n *\n * @param currentStorage - Current BlockStorage (or undefined for new blocks)\n * @param newState - New state from developer\n * @param handlers - Optional custom handlers (defaults to standard handlers)\n * @returns Updated BlockStorage\n */\nexport function applyStateUpdate<TState>(\n  currentStorage: BlockStorage<TState> | undefined,\n  newState: TState,\n  handlers: BlockStorageHandlers<TState> = defaultBlockStorageHandlers as BlockStorageHandlers<TState>,\n): BlockStorage<TState> {\n  const storage = currentStorage ?? createBlockStorage<TState>({} as TState);\n  const transform = handlers.transformStateForStorage ?? defaultBlockStorageHandlers.transformStateForStorage;\n  return transform(storage, newState) as BlockStorage<TState>;\n}\n\n/**\n * Serializes BlockStorage for writing to the resource tree.\n *\n * @param storage - The BlockStorage to serialize\n * @returns JSON string\n */\nexport function serializeBlockStorage(storage: BlockStorage): string {\n  return JSON.stringify(storage);\n}\n\n/**\n * Checks if the storage needs migration based on version.\n *\n * @param storage - Current BlockStorage\n * @param targetVersion - Target schema version\n * @returns true if migration is needed\n */\nexport function needsMigration(storage: BlockStorage, targetVersion: number): boolean {\n  return getStorageDataVersion(storage) < targetVersion;\n}\n\n/**\n * Migrates BlockStorage from one version to another.\n *\n * @param storage - Current BlockStorage\n * @param fromVersion - Source version\n * @param toVersion - Target version\n * @param handlers - Optional custom handlers\n * @returns Migrated BlockStorage\n */\nexport function migrateBlockStorage<TState>(\n  storage: BlockStorage<TState>,\n  fromVersion: number,\n  toVersion: number,\n  handlers: BlockStorageHandlers<TState> = defaultBlockStorageHandlers as BlockStorageHandlers<TState>,\n): BlockStorage<TState> {\n  const migrate = handlers.migrateStorage ?? defaultBlockStorageHandlers.migrateStorage;\n  return migrate(storage, fromVersion, toVersion) as BlockStorage<TState>;\n}\n\n/**\n * V1/V2 legacy format - state stored as { args, uiState }\n */\nexport interface LegacyV1V2State {\n  args?: unknown;\n  uiState?: unknown;\n}\n\n/**\n * Checks if the raw data is in legacy V1/V2 format.\n * V1/V2 blocks stored { args, uiState } directly, not wrapped in BlockStorage.\n *\n * @param rawData - Raw data from blockStorage field\n * @returns true if data is in legacy format\n */\nexport function isLegacyV1V2Format(rawData: unknown): rawData is LegacyV1V2State {\n  if (rawData === null || typeof rawData !== 'object') return false;\n  // If it has the discriminator, it's BlockStorage format\n  if (isBlockStorage(rawData)) return false;\n\n  const obj = rawData as Record<string, unknown>;\n  // Legacy format has 'args' and/or 'uiState' at top level, no discriminator\n  return ('args' in obj || 'uiState' in obj);\n}\n\n/**\n * Converts legacy V1/V2 format to BlockStorage.\n * For backward compatibility with existing blocks.\n *\n * @param legacyData - Data in { args, uiState } format\n * @returns BlockStorage with legacy data as state\n */\nexport function convertLegacyToBlockStorage(legacyData: LegacyV1V2State): BlockStorage<LegacyV1V2State> {\n  return createBlockStorage(legacyData, 1);\n}\n\n/**\n * Smart parser that handles all storage formats:\n * - New BlockStorage format\n * - Legacy V1/V2 format ({ args, uiState })\n * - Raw state (any other format)\n *\n * @param rawData - Raw data from blockStorage field\n * @returns Normalized BlockStorage\n */\nexport function parseBlockStorageSmart<TState = unknown>(rawData: unknown): BlockStorage<TState> {\n  if (rawData === undefined || rawData === null) {\n    return createBlockStorage<TState>({} as TState);\n  }\n\n  // If it's a string, parse it first\n  let parsed = rawData;\n  if (typeof rawData === 'string') {\n    try {\n      parsed = JSON.parse(rawData);\n    } catch {\n      // If parsing fails, treat the string as the state itself\n      return createBlockStorage(rawData as unknown as TState);\n    }\n  }\n\n  // Check for legacy V1/V2 format\n  if (isLegacyV1V2Format(parsed)) {\n    return convertLegacyToBlockStorage(parsed) as unknown as BlockStorage<TState>;\n  }\n\n  // Use standard normalization\n  return normalizeBlockStorage<TState>(parsed);\n}\n"],"names":[],"mappings":"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"}

package/dist/model/index.d.ts

@@ -1,3 +1,4 @@
 export * from './block_pack_spec';
-export { type ProjectListEntry } from './project_model';
+export * from './block_storage_helper';
+export { type ProjectListEntry, type ProjectField } from './project_model';
 //# sourceMappingURL=index.d.ts.map

package/dist/model/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/model/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/model/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC"}