@milaboratories/pl-middle-layer 1.45.5 → 1.46.0

package/src/middle_layer/project.ts

@@ -24,7 +24,7 @@ import { SynchronizedTreeState, treeDumpStats } from '@milaboratories/pl-tree';
 import { setTimeout } from 'node:timers/promises';
 import { frontendData } from './frontend_path';
 import type { NavigationState } from '@milaboratories/pl-model-common';
-import { blockArgsAndUiState, blockOutputs } from './block';
+import { getBlockParameters, blockOutputs } from './block';
 import type { FrontendData } from '../model/frontend';
 import type { ProjectStructure } from '../model/project_model';
 import { projectFieldName } from '../model/project_model';
@@ -33,8 +33,8 @@ import type { BlockPackInfo } from '../model/block_pack';
 import type {
   ProjectOverview,
   AuthorMarker,
-  BlockStateInternal,
   BlockSettings,
+  BlockStateInternalV3,
 } from '@milaboratories/pl-model-middle-layer';
 import { activeConfigs } from './active_cfg';
 import { NavigationStates } from './navigation_states';
@@ -46,7 +46,7 @@ import { projectOverviewLight } from './project_overview_light';
 import { applyProjectMigrations } from '../mutator/migration';
 
 type BlockStateComputables = {
-  readonly fullState: Computable<BlockStateInternal>;
+  readonly fullState: Computable<BlockStateInternalV3>;
 };
 
 function stringifyForDump(object: unknown): string {
@@ -131,7 +131,7 @@ export class Project {
         await this.activeConfigs.getValue();
         await setTimeout(this.env.ops.projectRefreshInterval, this.abortController.signal);
 
-        // Block computables houskeeping
+        // Block computables housekeeping
         const overviewLight = await this.overviewLight.getValue();
         const existingBlocks = new Set(overviewLight.listOfBlocks);
         // Doing cleanup for deleted blocks
@@ -187,6 +187,12 @@ export class Project {
     const preparedBp = await this.env.bpPreparer.prepare(blockPackSpec);
     const blockCfgContainer = await this.env.bpPreparer.getBlockConfigContainer(blockPackSpec);
     const blockCfg = extractConfig(blockCfgContainer); // full content of this var should never be persisted
+
+    // Build NewBlockSpec based on model API version
+    const newBlockSpec = blockCfg.modelAPIVersion === 2
+      ? { storageMode: 'fromModel' as const, blockPack: preparedBp }
+      : { storageMode: 'legacy' as const, blockPack: preparedBp, legacyState: canonicalize({ args: blockCfg.initialArgs, uiState: blockCfg.initialUiState })! };
+
     await withProjectAuthored(this.env.projectHelper, this.env.pl, this.rid, author, (mut) => {
       return mut.addBlock(
         {
@@ -194,11 +200,7 @@ export class Project {
           label: blockLabel,
           renderingMode: blockCfg.renderingMode,
         },
-        {
-          args: canonicalize(blockCfg.initialArgs)!,
-          uiState: canonicalize(blockCfg.initialUiState)!,
-          blockPack: preparedBp,
-        },
+        newBlockSpec,
         before,
       );
     },
@@ -255,11 +257,17 @@ export class Project {
   ): Promise<void> {
     const preparedBp = await this.env.bpPreparer.prepare(blockPackSpec);
     const blockCfg = extractConfig(await this.env.bpPreparer.getBlockConfigContainer(blockPackSpec));
+    // resetState signals to mutator to reset storage
+    // For v2+ blocks: mutator gets initial storage directly via getInitialStorageInVM
+    // For v1 blocks: we pass the legacy state format
+    const resetState = resetArgs
+      ? { state: blockCfg.modelAPIVersion === 2 ? {} : { args: blockCfg.initialArgs, uiState: blockCfg.initialUiState } }
+      : undefined;
     await withProjectAuthored(this.env.projectHelper, this.env.pl, this.rid, author, (mut) =>
       mut.migrateBlockPack(
         blockId,
         preparedBp,
-        resetArgs ? { args: blockCfg.initialArgs, uiState: blockCfg.initialUiState } : undefined,
+        resetState,
       ),
     { name: 'updateBlockPack', lockId: this.projectLockId },
     );
@@ -326,49 +334,38 @@ export class Project {
     await this.projectTree.refreshState();
   }
 
-  // /** Update block label. */
-  // public async setBlockLabel(blockId: string, label: string, author?: AuthorMarker) {
-  //   await withProjectAuthored(this.env.pl, this.rid, author, (mut) => {
-  //     mut.setBlockLabel(blockId, label);
-  //   });
-  //   await this.projectTree.refreshState();
-  // }
-
   /**
+   * @deprecated Use mutateBlockStorage() for V3 blocks.
    * Sets block args, and changes whole project state accordingly.
    * Along with setting arguments one can specify author marker, that will be
    * transactionally associated with the block, to facilitate conflict resolution
    * in collaborative editing scenario.
    * */
   public async setBlockArgs(blockId: string, args: unknown, author?: AuthorMarker) {
-    await withProjectAuthored(this.env.projectHelper, this.env.pl, this.rid, author, (mut) =>
-      mut.setStates([{ blockId, args }]),
-    { name: 'setBlockArgs', lockId: this.projectLockId });
+    await withProjectAuthored(this.env.projectHelper, this.env.pl, this.rid, author, (mut) => {
+      const state = mut.mergeBlockState(blockId, { args });
+      mut.setStates([{ modelAPIVersion: 1, blockId, state }]);
+    }, { name: 'setBlockArgs', lockId: this.projectLockId });
     await this.projectTree.refreshState();
   }
 
   /**
+   * @deprecated Use mutateBlockStorage() for V3 blocks.
    * Sets ui block state associated with the block.
    * Along with setting arguments one can specify author marker, that will be
    * transactionally associated with the block, to facilitate conflict resolution
    * in collaborative editing scenario.
    * */
   public async setUiState(blockId: string, uiState: unknown, author?: AuthorMarker) {
-    await withProjectAuthored(this.env.projectHelper, this.env.pl, this.rid, author, (mut) =>
-      mut.setStates([{ blockId, uiState }]),
-    { name: 'setUiState', lockId: this.projectLockId });
+    await withProjectAuthored(this.env.projectHelper, this.env.pl, this.rid, author, (mut) => {
+      const state = mut.mergeBlockState(blockId, { uiState });
+      mut.setStates([{ modelAPIVersion: 1, blockId, state }]);
+    }, { name: 'setUiState', lockId: this.projectLockId });
     await this.projectTree.refreshState();
   }
 
   /**
-   * Sets navigation state.
-   * */
-  // eslint-disable-next-line @typescript-eslint/require-await
-  public async setNavigationState(blockId: string, state: NavigationState): Promise<void> {
-    this.navigationStates.setState(blockId, state);
-  }
-
-  /**
+   * @deprecated Use mutateBlockStorage() for V3 blocks.
    * Sets block args and ui state, and changes the whole project state accordingly.
    * Along with setting arguments one can specify author marker, that will be
    * transactionally associated with the block, to facilitate conflict resolution
@@ -376,16 +373,43 @@ export class Project {
    * */
   public async setBlockArgsAndUiState(
     blockId: string,
-    args: unknown,
-    uiState: unknown,
+    args: unknown, // keep for v1/v2 compatibility
+    uiState: unknown, // keep for v1/v2 compatibility
     author?: AuthorMarker,
   ) {
+    // Normalize to unified state format { args, uiState } for v1/v2 blocks
+    const state = { args, uiState };
     await withProjectAuthored(this.env.projectHelper, this.env.pl, this.rid, author, (mut) => {
-      mut.setStates([{ blockId, args, uiState }]);
+      mut.setStates([{ modelAPIVersion: 1, blockId, state }]);
     }, { name: 'setBlockArgsAndUiState', lockId: this.projectLockId });
     await this.projectTree.refreshState();
   }
 
+  /**
+   * Sets navigation state.
+   * */
+  // eslint-disable-next-line @typescript-eslint/require-await
+  public async setNavigationState(blockId: string, state: NavigationState): Promise<void> {
+    this.navigationStates.setState(blockId, state);
+  }
+
+  /**
+   * Mutates block storage for Model API v3 blocks.
+   * Applies a storage operation (e.g., 'update-data') which triggers
+   * args derivation (args(data) and prerunArgs(data)).
+   * The derived args are stored atomically with the data.
+   *
+   * @param blockId - The block ID
+   * @param payload - Storage mutation payload with operation and value
+   * @param author - Optional author marker for collaborative editing
+   */
+  public async mutateBlockStorage(blockId: string, payload: { operation: string; value: unknown }, author?: AuthorMarker) {
+    await withProjectAuthored(this.env.projectHelper, this.env.pl, this.rid, author, (mut) =>
+      mut.setStates([{ modelAPIVersion: 2, blockId, payload }]),
+    { name: 'mutateBlockStorage', lockId: this.projectLockId });
+    await this.projectTree.refreshState();
+  }
+
   /** Update block settings */
   public async setBlockSettings(blockId: string, newValue: BlockSettings) {
     await withProjectAuthored(this.env.projectHelper, this.env.pl, this.rid, undefined, (mut) => {
@@ -394,6 +418,20 @@ export class Project {
     await this.projectTree.refreshState();
   }
 
+  /**
+   * Sets raw block storage content directly.
+   * This bypasses all normalization and VM transformations.
+   *
+   * @param blockId The block to set storage for
+   * @param rawStorageJson Raw storage as JSON string
+   */
+  public async setBlockStorageRaw(blockId: string, rawStorageJson: string): Promise<void> {
+    await withProjectAuthored(this.env.projectHelper, this.env.pl, this.rid, undefined, (mut) => {
+      mut.setBlockStorageRaw(blockId, rawStorageJson);
+    }, { name: 'setBlockStorageRaw' });
+    await this.projectTree.refreshState();
+  }
+
   /** Resets arguments and ui state of the block to initial state */
   public async resetBlockArgsAndUiState(blockId: string, author?: AuthorMarker): Promise<void> {
     await this.env.pl.withWriteTx('BlockInputsReset', async (tx) => {
@@ -406,8 +444,16 @@ export class Project {
       );
       const bpData = await tx.getResourceData(bpRid, false);
       const config = extractConfig(cachedDeserialize<BlockPackInfo>(notEmpty(bpData.data)).config);
+
       await withProjectAuthored(this.env.projectHelper, tx, this.rid, author, (prj) => {
-        prj.setStates([{ blockId, args: config.initialArgs, uiState: config.initialUiState }]);
+        if (config.modelAPIVersion === 2) {
+          // V2+: Reset to initial storage via VM
+          prj.resetToInitialStorage(blockId);
+        } else {
+          // V1: Use legacy state format
+          const initialState = { args: config.initialArgs, uiState: config.initialUiState };
+          prj.setStates([{ modelAPIVersion: 1, blockId, state: initialState }]);
+        }
       }, { name: 'resetBlockArgsAndUiState', lockId: this.projectLockId });
       await tx.commit();
     });
@@ -423,7 +469,7 @@ export class Project {
       const fullState = Computable.make(
         (ctx) => {
           return {
-            argsAndUiState: blockArgsAndUiState(this.projectTree.entry(), blockId, ctx),
+            parameters: getBlockParameters(this.projectTree.entry(), blockId, ctx),
             outputs,
             navigationState: this.navigationStates.getState(blockId),
             overview: this.overview,
@@ -438,10 +484,10 @@ export class Project {
               : v.outputs;
 
             return {
-              ...v.argsAndUiState,
+              ...v.parameters,
               outputs: newOutputs,
               navigationState: v.navigationState,
-            } as BlockStateInternal;
+            } as BlockStateInternalV3;
           },
         },
       );
@@ -461,7 +507,7 @@ export class Project {
    * Returns a computable, that can be used to retrieve and watch full block state,
    * including outputs, arguments, ui state.
    * */
-  public getBlockState(blockId: string): Computable<BlockStateInternal> {
+  public getBlockState(blockId: string): Computable<BlockStateInternalV3> {
     return this.getBlockComputables(blockId).fullState;
   }
 

package/src/middle_layer/project_overview.ts

@@ -34,13 +34,11 @@ import { resourceIdToString, type ResourceId } from '@milaboratories/pl-client';
 import * as R from 'remeda';
 
 type BlockInfo = {
-  argsRid: ResourceId;
+  argsRid?: ResourceId;
   currentArguments: unknown;
   prod?: ProdState;
 };
 
-type _CalculationStatus = 'Running' | 'Done';
-
 type ProdState = {
   finished: boolean;
 
@@ -87,9 +85,9 @@ export function projectOverview(
         const cInputs = prj.traverse({
           field: projectFieldName(id, 'currentArgs'),
           assertFieldType: 'Dynamic',
-          errorIfFieldNotSet: true,
+          stableIfNotFound: true,
         });
-        const currentArguments = cInputs.getDataAsJson() as Record<string, unknown>;
+        const currentArguments = cInputs?.getDataAsJson<Record<string, unknown>>();
 
         let prod: ProdState | undefined = undefined;
 
@@ -129,7 +127,7 @@ export function projectOverview(
           };
         }
 
-        infos.set(id, { currentArguments, prod, argsRid: cInputs.resourceInfo.id });
+        infos.set(id, { currentArguments, prod, argsRid: cInputs?.resourceInfo.id });
       }
 
       const currentGraph = productionGraph(structure, (id) => {
@@ -138,7 +136,13 @@ export function projectOverview(
         const args = bInfo.currentArguments;
         return {
           args,
-          enrichmentTargets: env.projectHelper.getEnrichmentTargets(() => bpInfo.cfg, () => args, { argsRid: bInfo.argsRid, blockPackRid: bpInfo.bpResourceId }),
+          enrichmentTargets: bInfo.argsRid
+            ? env.projectHelper.getEnrichmentTargets(
+              () => bpInfo.cfg,
+              () => args,
+              { argsRid: bInfo.argsRid, blockPackRid: bpInfo.bpResourceId },
+            )
+            : undefined,
         };
       });
 
@@ -235,19 +239,24 @@ export function projectOverview(
                     },
                   }) as ComputableStableDefined<string[]>,
               ),
-              inputsValid: computableFromCfgOrRF(
-                env,
-                blockCtxArgsOnly,
-                cfg.inputsValid,
-                codeWithInfo,
-                bpId,
-              ).wrap({
-                recover: (cause) => {
-                  // I'm not sure that we should write an error here, because it just means "Invalid args"
-                  env.logger.error(new Error('Error in block model argsValid', { cause }));
-                  return false;
-                },
-              }) as ComputableStableDefined<boolean>,
+              // inputsValid: for modelAPIVersion 2, it's true if currentArgs exists (args derivation succeeded)
+              // For older blocks, use the inputsValid callback from config
+              inputsValid: cfg.modelAPIVersion === 2
+                ? info.currentArguments !== undefined
+                : cfg.inputsValid
+                  ? computableFromCfgOrRF(
+                    env,
+                    blockCtxArgsOnly,
+                    cfg.inputsValid,
+                    codeWithInfo,
+                    bpId,
+                  ).wrap({
+                    recover: (cause) => {
+                      env.logger.error(new Error('Error in block model inputsValid', { cause }));
+                      return false;
+                    },
+                  }) as ComputableStableDefined<boolean>
+                  : undefined,
               sdkVersion: codeWithInfo?.sdkVersion,
               featureFlags: codeWithInfo?.featureFlags ?? {},
               isIncompatibleWithRuntime: false,
@@ -262,6 +271,20 @@ export function projectOverview(
           })
           .getDataAsJson() as BlockSettings;
 
+        // Get block storage info by calling VM function (only for Model API v2 blocks)
+        const blockStorageInfo = ifNotUndef(bp, ({ cfg }) => {
+          if (cfg.modelAPIVersion !== 2) {
+            return undefined;
+          }
+          const storageNode = prj.traverse({
+            field: projectFieldName(id, 'blockStorage'),
+            assertFieldType: 'Dynamic',
+            stableIfNotFound: true,
+          });
+          const rawStorageJson = storageNode?.getDataAsString();
+          return env.projectHelper.getStorageInfoInVM(cfg, rawStorageJson);
+        });
+
         const updates = ifNotUndef(bp, ({ info }) =>
           env.blockUpdateWatcher.get({ currentSpec: info.source, settings }),
         );
@@ -292,6 +315,7 @@ export function projectOverview(
           featureFlags,
           isIncompatibleWithRuntime,
           navigationState: navigationStates.getState(id),
+          blockStorageInfo,
         };
       });
 

package/src/middle_layer/render.test.ts

@@ -25,6 +25,7 @@ export async function withMl(
     });
     ml.addRuntimeCapability('requiresUIAPIVersion', 1);
     ml.addRuntimeCapability('requiresUIAPIVersion', 2);
+    ml.addRuntimeCapability('requiresUIAPIVersion', 3);
     try {
       await cb(ml, workFolder);
     } finally {
@@ -159,7 +160,6 @@ test.skip('basic quickjs code', async () => {
       vm.newFunction('nextId', () => {
         return vm.newNumber(12); // vm.newArrayBuffer(new Uint8Array([1, 2]));
       }).consume((fn) => vm.setProp(vm.global, 'nextId', fn));
-      console.log('asdasdas');
 
       const nextId = vm.getString(
         scope.manage(

package/src/middle_layer/render.ts

@@ -21,7 +21,7 @@ export function computableFromCfgOrRF(
   ops: Partial<ComputableRenderingOps> = {},
 ): Computable<unknown> {
   if (isConfigLambda(cfgOrFh)) {
-    if (codeWithInfo === undefined) throw new Error('No code bundle.');
+    if (codeWithInfo === undefined) throw new Error('computableFromCfgOrRF: No code bundle.');
     return computableFromRF(env, ctx, cfgOrFh, codeWithInfo, configKey, ops);
   } else return computableFromCfg(env.driverKit, ctx, cfgOrFh, ops);
 }

package/src/model/block_storage_helper.ts

@@ -0,0 +1,213 @@
+/**
+ * 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';
+
+// Re-export types for convenience
+export type { BlockStorage, BlockStorageHandlers };
+
+// Re-export utilities that middle layer needs
+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 function parseBlockStorage<TState = unknown>(rawData: unknown): BlockStorage<TState> {
+  if (rawData === undefined || rawData === null) {
+    return createBlockStorage<TState>({} as TState);
+  }
+
+  // If it's a string, parse it first
+  if (typeof rawData === 'string') {
+    try {
+      const parsed = JSON.parse(rawData);
+      return normalizeBlockStorage<TState>(parsed);
+    } catch {
+      // If parsing fails, treat the string as the state itself
+      return createBlockStorage(rawData as unknown as TState);
+    }
+  }
+
+  return normalizeBlockStorage<TState>(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
+ */
+export function extractDataForDeveloper<TState>(storage: BlockStorage<TState>): TState {
+  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
+ */
+export function applyStateUpdate<TState>(
+  currentStorage: BlockStorage<TState> | undefined,
+  newState: TState,
+  handlers: BlockStorageHandlers<TState> = defaultBlockStorageHandlers as BlockStorageHandlers<TState>,
+): BlockStorage<TState> {
+  const storage = currentStorage ?? createBlockStorage<TState>({} as TState);
+  const transform = handlers.transformStateForStorage ?? defaultBlockStorageHandlers.transformStateForStorage;
+  return transform(storage, newState) as BlockStorage<TState>;
+}
+
+/**
+ * Serializes BlockStorage for writing to the resource tree.
+ *
+ * @param storage - The BlockStorage to serialize
+ * @returns JSON string
+ */
+export function serializeBlockStorage(storage: BlockStorage): string {
+  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
+ */
+export function needsMigration(storage: BlockStorage, targetVersion: number): boolean {
+  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
+ */
+export function migrateBlockStorage<TState>(
+  storage: BlockStorage<TState>,
+  fromVersion: number,
+  toVersion: number,
+  handlers: BlockStorageHandlers<TState> = defaultBlockStorageHandlers as BlockStorageHandlers<TState>,
+): BlockStorage<TState> {
+  const migrate = handlers.migrateStorage ?? defaultBlockStorageHandlers.migrateStorage;
+  return migrate(storage, fromVersion, toVersion) as 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 function isLegacyV1V2Format(rawData: unknown): rawData is LegacyV1V2State {
+  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 as Record<string, unknown>;
+  // 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
+ */
+export function convertLegacyToBlockStorage(legacyData: LegacyV1V2State): BlockStorage<LegacyV1V2State> {
+  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
+ */
+export function parseBlockStorageSmart<TState = unknown>(rawData: unknown): BlockStorage<TState> {
+  if (rawData === undefined || rawData === null) {
+    return createBlockStorage<TState>({} as TState);
+  }
+
+  // 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 as unknown as TState);
+    }
+  }
+
+  // Check for legacy V1/V2 format
+  if (isLegacyV1V2Format(parsed)) {
+    return convertLegacyToBlockStorage(parsed) as unknown as BlockStorage<TState>;
+  }
+
+  // Use standard normalization
+  return normalizeBlockStorage<TState>(parsed);
+}

package/src/model/index.ts

@@ -1,2 +1,3 @@
 export * from './block_pack_spec';
-export { type ProjectListEntry } from './project_model';
+export * from './block_storage_helper';
+export { type ProjectListEntry, type ProjectField } from './project_model';