@platforma-sdk/model 1.58.0 → 1.58.1

package/dist/block_storage_callbacks.d.ts

@@ -11,12 +11,12 @@
 import { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION, type BlockStorage, type MutateStoragePayload, type StorageDebugView, type PluginRegistry } from "./block_storage";
 import type { PluginHandle } from "./plugin_handle";
 import { type StringifiedJson } from "@milaboratories/pl-model-common";
-import type { DataMigrationResult, DataVersioned } from "./block_migrations";
+import type { DataVersioned } from "./block_migrations";
 /** Dependencies for storage migration */
 export interface MigrationHooks {
-    migrateBlockData: (versioned: DataVersioned<unknown>) => DataMigrationResult<unknown>;
+    migrateBlockData: (versioned: DataVersioned<unknown>) => DataVersioned<unknown>;
     getPluginRegistry: () => PluginRegistry;
-    migratePluginData: (handle: PluginHandle, versioned: DataVersioned<unknown>) => DataMigrationResult<unknown> | undefined;
+    migratePluginData: (handle: PluginHandle, versioned: DataVersioned<unknown>) => DataVersioned<unknown> | undefined;
     createPluginData: (handle: PluginHandle) => DataVersioned<unknown>;
 }
 /** Dependencies for initial storage creation */
@@ -79,6 +79,7 @@ export declare function migrateStorage(currentStorageJson: string | undefined, h
  *
  * @param hooks - Dependencies for creating initial block and plugin data
  * @returns Initial storage as branded JSON string
+ * @throws If initialDataFn or createPluginData throws
  */
 export declare function createInitialStorage(hooks: InitialStorageHooks): StringifiedJson<BlockStorage>;
 /**

package/dist/block_storage_callbacks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"block_storage_callbacks.d.ts","sourceRoot":"","sources":["../src/block_storage_callbacks.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"block_storage_callbacks.d.ts","sourceRoot":"","sources":["../src/block_storage_callbacks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,iBAAiB,EACjB,4BAA4B,EAC5B,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EAQpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,OAAO,EAAiB,KAAK,eAAe,EAAE,MAAM,iCAAiC,CAAC;AACtF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAMxD,yCAAyC;AACzC,MAAM,WAAW,cAAc;IAC7B,gBAAgB,EAAE,CAAC,SAAS,EAAE,aAAa,CAAC,OAAO,CAAC,KAAK,aAAa,CAAC,OAAO,CAAC,CAAC;IAChF,iBAAiB,EAAE,MAAM,cAAc,CAAC;IACxC,iBAAiB,EAAE,CACjB,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,aAAa,CAAC,OAAO,CAAC,KAC9B,aAAa,CAAC,OAAO,CAAC,GAAG,SAAS,CAAC;IACxC,gBAAgB,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,aAAa,CAAC,OAAO,CAAC,CAAC;CACpE;AAED,gDAAgD;AAChD,MAAM,WAAW,mBAAmB;IAClC,mBAAmB,EAAE,MAAM,aAAa,CAAC,OAAO,CAAC,CAAC;IAClD,iBAAiB,EAAE,MAAM,cAAc,CAAC;IACxC,gBAAgB,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,aAAa,CAAC,OAAO,CAAC,CAAC;CACpE;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,yCAAyC;IACzC,OAAO,EAAE,YAAY,CAAC;IACtB,+CAA+C;IAC/C,IAAI,EAAE,OAAO,CAAC;CACf;AAiDD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,kBAAkB,EAAE,MAAM,EAC1B,OAAO,EAAE,oBAAoB,GAC5B,eAAe,CAAC,YAAY,CAAC,CAO/B;AAkBD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,OAAO,GAAG,eAAe,CAAC,gBAAgB,CAAC,CAO1F;AAMD;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GACjB;IAAE,KAAK,CAAC,EAAE,SAAS,CAAC;IAAC,cAAc,EAAE,eAAe,CAAC,YAAY,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvF;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,kBAAkB,EAAE,MAAM,GAAG,SAAS,EACtC,KAAK,EAAE,cAAc,GACpB,eAAe,CAgCjB;AAMD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,mBAAmB,GAAG,eAAe,CAAC,YAAY,CAAC,CAkB9F;AAMD;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,CAAC,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAEzF;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,GACvC,gBAAgB,CAYlB;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,EACxC,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,GAC9C,gBAAgB,CAuBlB;AAGD,OAAO,EAAE,iBAAiB,EAAE,4BAA4B,EAAE,CAAC"}

package/dist/block_storage_callbacks.js

@@ -141,6 +141,7 @@ function migrateStorage(currentStorageJson, hooks) {
  *
  * @param hooks - Dependencies for creating initial block and plugin data
  * @returns Initial storage as branded JSON string
+ * @throws If initialDataFn or createPluginData throws
  */
 function createInitialStorage(hooks) {
     const blockDefault = hooks.getDefaultBlockData();

package/dist/block_storage_callbacks.js.map

@@ -1 +1 @@
-{"version":3,"file":"block_storage_callbacks.js","sources":["../src/block_storage_callbacks.ts"],"sourcesContent":["/**\n * BlockStorage Callback Implementations - wired to facade callbacks in BlockModelV3._done().\n *\n * Provides pure functions for storage operations (migration, initialization,\n * args derivation, updates, debug views). Each function takes its dependencies\n * explicitly as parameters.\n *\n * @module block_storage_callbacks\n * @internal\n */\n\nimport {\n  BLOCK_STORAGE_KEY,\n  BLOCK_STORAGE_SCHEMA_VERSION,\n  type BlockStorage,\n  type MutateStoragePayload,\n  type StorageDebugView,\n  type PluginRegistry,\n  type VersionedData,\n  createBlockStorage,\n  getStorageData,\n  isBlockStorage,\n  migrateBlockStorage,\n  normalizeBlockStorage,\n  updateStorageData,\n} from \"./block_storage\";\nimport type { PluginHandle } from \"./plugin_handle\";\n\nimport { stringifyJson, type StringifiedJson } from \"@milaboratories/pl-model-common\";\nimport type { DataMigrationResult, DataVersioned } from \"./block_migrations\";\n\n// =============================================================================\n// Hook interfaces for dependency injection\n// =============================================================================\n\n/** Dependencies for storage migration */\nexport interface MigrationHooks {\n  migrateBlockData: (versioned: DataVersioned<unknown>) => DataMigrationResult<unknown>;\n  getPluginRegistry: () => PluginRegistry;\n  migratePluginData: (\n    handle: PluginHandle,\n    versioned: DataVersioned<unknown>,\n  ) => DataMigrationResult<unknown> | undefined;\n  createPluginData: (handle: PluginHandle) => DataVersioned<unknown>;\n}\n\n/** Dependencies for initial storage creation */\nexport interface InitialStorageHooks {\n  getDefaultBlockData: () => DataVersioned<unknown>;\n  getPluginRegistry: () => PluginRegistry;\n  createPluginData: (handle: PluginHandle) => DataVersioned<unknown>;\n}\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    const storage = normalizeBlockStorage(parsed);\n    return { storage, data: getStorageData(storage) };\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 payload - Update payload with operation type and value\n * @returns Updated storage as StringifiedJson<BlockStorage>\n */\nexport function applyStorageUpdate(\n  currentStorageJson: string,\n  payload: MutateStoragePayload,\n): StringifiedJson<BlockStorage> {\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 stringifyJson(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// Facade Callback Implementations\n// =============================================================================\n\n/**\n * Gets storage debug view from raw storage data.\n * Returns structured debug 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 debug view\n */\nexport function getStorageDebugView(rawStorage: unknown): StringifiedJson<StorageDebugView> {\n  const { storage } = normalizeStorage(rawStorage);\n  const debugView: StorageDebugView = {\n    dataVersion: storage.__dataVersion,\n    data: storage.__data,\n  };\n  return stringifyJson(debugView);\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: StringifiedJson<BlockStorage>, info: string } - migration succeeded\n */\nexport type MigrationResult =\n  | { error: string }\n  | { error?: undefined; newStorageJson: StringifiedJson<BlockStorage>; info: string };\n\n/**\n * Runs storage migration using the provided hooks.\n * This is the main entry point for the middle layer to trigger migrations.\n *\n * @param currentStorageJson - Current storage as JSON string (or undefined)\n * @param hooks - Migration dependencies (block/plugin data migration and creation functions)\n * @returns MigrationResult\n */\nexport function migrateStorage(\n  currentStorageJson: string | undefined,\n  hooks: MigrationHooks,\n): MigrationResult {\n  // Normalize current storage\n  const { storage: currentStorage } = normalizeStorage(currentStorageJson);\n\n  const newPluginRegistry = hooks.getPluginRegistry();\n\n  // Perform atomic migration of block + all plugins\n  const migrationResult = migrateBlockStorage(currentStorage, {\n    migrateBlockData: hooks.migrateBlockData,\n    migratePluginData: hooks.migratePluginData,\n    newPluginRegistry,\n    createPluginData: hooks.createPluginData,\n  });\n\n  if (!migrationResult.success) {\n    return {\n      error: `Migration failed at '${migrationResult.failedAt}': ${migrationResult.error}`,\n    };\n  }\n\n  // Build info message\n  const oldVersion = currentStorage.__dataVersion;\n  const newVersion = migrationResult.storage.__dataVersion;\n  const info =\n    oldVersion === newVersion\n      ? `No migration needed (${oldVersion})`\n      : `Migrated ${oldVersion} -> ${newVersion}`;\n\n  return {\n    newStorageJson: stringifyJson(migrationResult.storage),\n    info,\n  };\n}\n\n// =============================================================================\n// Initial Storage Creation\n// =============================================================================\n\n/**\n * Creates complete initial storage (block data + all plugin data) atomically.\n *\n * @param hooks - Dependencies for creating initial block and plugin data\n * @returns Initial storage as branded JSON string\n */\nexport function createInitialStorage(hooks: InitialStorageHooks): StringifiedJson<BlockStorage> {\n  const blockDefault = hooks.getDefaultBlockData();\n  const pluginRegistry = hooks.getPluginRegistry();\n\n  const plugins: Record<PluginHandle, VersionedData<unknown>> = {};\n  for (const handle of Object.keys(pluginRegistry) as PluginHandle[]) {\n    const initial = hooks.createPluginData(handle);\n    plugins[handle] = { __dataVersion: initial.version, __data: initial.data };\n  }\n\n  const storage: BlockStorage = {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: blockDefault.version,\n    __data: blockDefault.data,\n    __pluginRegistry: pluginRegistry,\n    __plugins: plugins,\n  };\n  return stringifyJson(storage);\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 = { error: string } | { error?: undefined; value: unknown };\n\n/**\n * Derives args from storage using the provided args function.\n * This extracts data from storage and passes it to the block's args() function.\n *\n * @param storageJson - Storage as JSON string\n * @param argsFunction - The block's args derivation function\n * @returns ArgsDeriveResult with derived args or error\n */\nexport function deriveArgsFromStorage(\n  storageJson: string,\n  argsFunction: (data: unknown) => unknown,\n): ArgsDeriveResult {\n  // Extract data from storage\n  const { data } = normalizeStorage(storageJson);\n\n  // Call the args function with extracted data\n  try {\n    const result = argsFunction(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/**\n * Derives prerunArgs from storage.\n * Uses prerunArgsFunction if provided, otherwise falls back to argsFunction.\n *\n * @param storageJson - Storage as JSON string\n * @param argsFunction - The block's args derivation function (fallback)\n * @param prerunArgsFunction - Optional prerun args derivation function\n * @returns ArgsDeriveResult with derived prerunArgs or error\n */\nexport function derivePrerunArgsFromStorage(\n  storageJson: string,\n  argsFunction: (data: unknown) => unknown,\n  prerunArgsFunction?: (data: unknown) => unknown,\n): ArgsDeriveResult {\n  // Extract data from storage\n  const { data } = normalizeStorage(storageJson);\n\n  // Try prerunArgs function first if available\n  if (prerunArgsFunction) {\n    try {\n      const result = prerunArgsFunction(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 function\n  try {\n    const result = argsFunction(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// Export discriminator key and schema version for external checks\nexport { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION };\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"block_storage_callbacks.js","sources":["../src/block_storage_callbacks.ts"],"sourcesContent":["/**\n * BlockStorage Callback Implementations - wired to facade callbacks in BlockModelV3._done().\n *\n * Provides pure functions for storage operations (migration, initialization,\n * args derivation, updates, debug views). Each function takes its dependencies\n * explicitly as parameters.\n *\n * @module block_storage_callbacks\n * @internal\n */\n\nimport {\n  BLOCK_STORAGE_KEY,\n  BLOCK_STORAGE_SCHEMA_VERSION,\n  type BlockStorage,\n  type MutateStoragePayload,\n  type StorageDebugView,\n  type PluginRegistry,\n  type VersionedData,\n  createBlockStorage,\n  getStorageData,\n  isBlockStorage,\n  migrateBlockStorage,\n  normalizeBlockStorage,\n  updateStorageData,\n} from \"./block_storage\";\nimport type { PluginHandle } from \"./plugin_handle\";\n\nimport { stringifyJson, type StringifiedJson } from \"@milaboratories/pl-model-common\";\nimport type { DataVersioned } from \"./block_migrations\";\n\n// =============================================================================\n// Hook interfaces for dependency injection\n// =============================================================================\n\n/** Dependencies for storage migration */\nexport interface MigrationHooks {\n  migrateBlockData: (versioned: DataVersioned<unknown>) => DataVersioned<unknown>;\n  getPluginRegistry: () => PluginRegistry;\n  migratePluginData: (\n    handle: PluginHandle,\n    versioned: DataVersioned<unknown>,\n  ) => DataVersioned<unknown> | undefined;\n  createPluginData: (handle: PluginHandle) => DataVersioned<unknown>;\n}\n\n/** Dependencies for initial storage creation */\nexport interface InitialStorageHooks {\n  getDefaultBlockData: () => DataVersioned<unknown>;\n  getPluginRegistry: () => PluginRegistry;\n  createPluginData: (handle: PluginHandle) => DataVersioned<unknown>;\n}\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    const storage = normalizeBlockStorage(parsed);\n    return { storage, data: getStorageData(storage) };\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 payload - Update payload with operation type and value\n * @returns Updated storage as StringifiedJson<BlockStorage>\n */\nexport function applyStorageUpdate(\n  currentStorageJson: string,\n  payload: MutateStoragePayload,\n): StringifiedJson<BlockStorage> {\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 stringifyJson(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// Facade Callback Implementations\n// =============================================================================\n\n/**\n * Gets storage debug view from raw storage data.\n * Returns structured debug 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 debug view\n */\nexport function getStorageDebugView(rawStorage: unknown): StringifiedJson<StorageDebugView> {\n  const { storage } = normalizeStorage(rawStorage);\n  const debugView: StorageDebugView = {\n    dataVersion: storage.__dataVersion,\n    data: storage.__data,\n  };\n  return stringifyJson(debugView);\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: StringifiedJson<BlockStorage>, info: string } - migration succeeded\n */\nexport type MigrationResult =\n  | { error: string }\n  | { error?: undefined; newStorageJson: StringifiedJson<BlockStorage>; info: string };\n\n/**\n * Runs storage migration using the provided hooks.\n * This is the main entry point for the middle layer to trigger migrations.\n *\n * @param currentStorageJson - Current storage as JSON string (or undefined)\n * @param hooks - Migration dependencies (block/plugin data migration and creation functions)\n * @returns MigrationResult\n */\nexport function migrateStorage(\n  currentStorageJson: string | undefined,\n  hooks: MigrationHooks,\n): MigrationResult {\n  // Normalize current storage\n  const { storage: currentStorage } = normalizeStorage(currentStorageJson);\n\n  const newPluginRegistry = hooks.getPluginRegistry();\n\n  // Perform atomic migration of block + all plugins\n  const migrationResult = migrateBlockStorage(currentStorage, {\n    migrateBlockData: hooks.migrateBlockData,\n    migratePluginData: hooks.migratePluginData,\n    newPluginRegistry,\n    createPluginData: hooks.createPluginData,\n  });\n\n  if (!migrationResult.success) {\n    return {\n      error: `Migration failed at '${migrationResult.failedAt}': ${migrationResult.error}`,\n    };\n  }\n\n  // Build info message\n  const oldVersion = currentStorage.__dataVersion;\n  const newVersion = migrationResult.storage.__dataVersion;\n  const info =\n    oldVersion === newVersion\n      ? `No migration needed (${oldVersion})`\n      : `Migrated ${oldVersion} -> ${newVersion}`;\n\n  return {\n    newStorageJson: stringifyJson(migrationResult.storage),\n    info,\n  };\n}\n\n// =============================================================================\n// Initial Storage Creation\n// =============================================================================\n\n/**\n * Creates complete initial storage (block data + all plugin data) atomically.\n *\n * @param hooks - Dependencies for creating initial block and plugin data\n * @returns Initial storage as branded JSON string\n * @throws If initialDataFn or createPluginData throws\n */\nexport function createInitialStorage(hooks: InitialStorageHooks): StringifiedJson<BlockStorage> {\n  const blockDefault = hooks.getDefaultBlockData();\n  const pluginRegistry = hooks.getPluginRegistry();\n\n  const plugins: Record<PluginHandle, VersionedData<unknown>> = {};\n  for (const handle of Object.keys(pluginRegistry) as PluginHandle[]) {\n    const initial = hooks.createPluginData(handle);\n    plugins[handle] = { __dataVersion: initial.version, __data: initial.data };\n  }\n\n  const storage: BlockStorage = {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: blockDefault.version,\n    __data: blockDefault.data,\n    __pluginRegistry: pluginRegistry,\n    __plugins: plugins,\n  };\n  return stringifyJson(storage);\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 = { error: string } | { error?: undefined; value: unknown };\n\n/**\n * Derives args from storage using the provided args function.\n * This extracts data from storage and passes it to the block's args() function.\n *\n * @param storageJson - Storage as JSON string\n * @param argsFunction - The block's args derivation function\n * @returns ArgsDeriveResult with derived args or error\n */\nexport function deriveArgsFromStorage(\n  storageJson: string,\n  argsFunction: (data: unknown) => unknown,\n): ArgsDeriveResult {\n  // Extract data from storage\n  const { data } = normalizeStorage(storageJson);\n\n  // Call the args function with extracted data\n  try {\n    const result = argsFunction(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/**\n * Derives prerunArgs from storage.\n * Uses prerunArgsFunction if provided, otherwise falls back to argsFunction.\n *\n * @param storageJson - Storage as JSON string\n * @param argsFunction - The block's args derivation function (fallback)\n * @param prerunArgsFunction - Optional prerun args derivation function\n * @returns ArgsDeriveResult with derived prerunArgs or error\n */\nexport function derivePrerunArgsFromStorage(\n  storageJson: string,\n  argsFunction: (data: unknown) => unknown,\n  prerunArgsFunction?: (data: unknown) => unknown,\n): ArgsDeriveResult {\n  // Extract data from storage\n  const { data } = normalizeStorage(storageJson);\n\n  // Try prerunArgs function first if available\n  if (prerunArgsFunction) {\n    try {\n      const result = prerunArgsFunction(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 function\n  try {\n    const result = argsFunction(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// Export discriminator key and schema version for external checks\nexport { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION };\n"],"names":[],"mappings":"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"}

package/dist/index.cjs

@@ -48,9 +48,6 @@ exports.wrapOutputs = block_state_util.wrapOutputs;
 exports.isPluginOutputKey = plugin_handle.isPluginOutputKey;
 exports.pluginOutputKey = plugin_handle.pluginOutputKey;
 exports.pluginOutputPrefix = plugin_handle.pluginOutputPrefix;
-exports.BLOCK_STORAGE_KEY = block_storage.BLOCK_STORAGE_KEY;
-exports.BLOCK_STORAGE_SCHEMA_VERSION = block_storage.BLOCK_STORAGE_SCHEMA_VERSION;
-exports.DATA_MODEL_DEFAULT_VERSION = block_storage.DATA_MODEL_DEFAULT_VERSION;
 exports.createBlockStorage = block_storage.createBlockStorage;
 exports.deriveDataFromStorage = block_storage.deriveDataFromStorage;
 exports.getPluginData = block_storage.getPluginData;
@@ -65,6 +62,7 @@ exports.BlockStorageFacadeHandles = block_storage_facade.BlockStorageFacadeHandl
 exports.registerFacadeCallbacks = block_storage_facade.registerFacadeCallbacks;
 exports.BlockModel = block_model_legacy.BlockModel;
 exports.BlockModelV3 = block_model.BlockModelV3;
+exports.DataMigrationError = block_migrations.DataMigrationError;
 exports.DataModel = block_migrations.DataModel;
 exports.DataModelBuilder = block_migrations.DataModelBuilder;
 exports.DataUnrecoverableError = block_migrations.DataUnrecoverableError;

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 export * from "./block_state_patch";
 export * from "./block_state_util";
 export * from "./plugin_handle";
-export * from "./block_storage";
+export { type BlockStorageSchemaVersion, type PluginName, type PluginRegistry, type VersionedData, type BlockStorage, isBlockStorage, createBlockStorage, normalizeBlockStorage, getStorageData, deriveDataFromStorage, type MutateStoragePayload, updateStorageData, type StorageDebugView, type MigrationSuccess, type MigrationFailure, type MigrationResult, type MigrateBlockStorageConfig, migrateBlockStorage, getPluginData, } from "./block_storage";
 export * from "./block_storage_facade";
 export * from "./block_model_legacy";
 export { BlockModelV3 } from "./block_model";
 export type { PluginInstance, ParamsInput } from "./block_model";
-export { DataModel, DataModelBuilder, DataUnrecoverableError, isDataUnrecoverableError, defaultRecover, makeDataVersioned, } from "./block_migrations";
+export { DataModel, DataModelBuilder, DataMigrationError, DataUnrecoverableError, isDataUnrecoverableError, defaultRecover, makeDataVersioned, } from "./block_migrations";
 export type { LegacyV1State } from "./block_migrations";
 export * from "./plugin_model";
 export * from "./bconfig";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EACL,SAAS,EACT,gBAAgB,EAChB,sBAAsB,EACtB,wBAAwB,EACxB,cAAc,EACd,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAG/B,cAAc,iCAAiC,CAAC;AAChD,cAAc,+BAA+B,CAAC;AAE9C,OAAO,KAAK,gBAAgB,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,OAAO,EACL,KAAK,yBAAyB,EAC9B,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,cAAc,EACd,kBAAkB,EAClB,qBAAqB,EACrB,cAAc,EACd,qBAAqB,EACrB,KAAK,oBAAoB,EACzB,iBAAiB,EACjB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,yBAAyB,EAC9B,mBAAmB,EACnB,aAAa,GACd,MAAM,iBAAiB,CAAC;AACzB,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EACL,SAAS,EACT,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EACtB,wBAAwB,EACxB,cAAc,EACd,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAG/B,cAAc,iCAAiC,CAAC;AAChD,cAAc,+BAA+B,CAAC;AAE9C,OAAO,KAAK,gBAAgB,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,10 +1,10 @@
 export { OutputError, readOutput, wrapOutputs } from './block_state_util.js';
 export { isPluginOutputKey, pluginOutputKey, pluginOutputPrefix } from './plugin_handle.js';
-export { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION, DATA_MODEL_DEFAULT_VERSION, createBlockStorage, deriveDataFromStorage, getPluginData, getStorageData, isBlockStorage, migrateBlockStorage, normalizeBlockStorage, updateStorageData } from './block_storage.js';
+export { createBlockStorage, deriveDataFromStorage, getPluginData, getStorageData, isBlockStorage, migrateBlockStorage, normalizeBlockStorage, updateStorageData } from './block_storage.js';
 export { BLOCK_STORAGE_FACADE_VERSION, BlockStorageFacadeCallbacks, BlockStorageFacadeHandles, registerFacadeCallbacks } from './block_storage_facade.js';
 export { BlockModel } from './block_model_legacy.js';
 export { BlockModelV3 } from './block_model.js';
-export { DataModel, DataModelBuilder, DataUnrecoverableError, defaultRecover, isDataUnrecoverableError, makeDataVersioned } from './block_migrations.js';
+export { DataMigrationError, DataModel, DataModelBuilder, DataUnrecoverableError, defaultRecover, isDataUnrecoverableError, makeDataVersioned } from './block_migrations.js';
 export { PluginModel } from './plugin_model.js';
 export { downgradeCfgOrLambda, extractConfig } from './bconfig/normalization.js';
 export { isConfigLambda } from './bconfig/types.js';

package/dist/package.json.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var version = "1.58.0";
+var version = "1.58.1";
 
 exports.version = version;
 //# sourceMappingURL=package.json.cjs.map

package/dist/package.json.js

@@ -1,4 +1,4 @@
-var version = "1.58.0";
+var version = "1.58.1";
 
 export { version };
 //# sourceMappingURL=package.json.js.map

package/dist/plugin_model.cjs

@@ -45,7 +45,7 @@ class PluginModel {
      * @returns PluginModelBuilder for chaining output definitions
      *
      * @example
-     * const dataModelChain = new DataModelBuilder().from<MyData>(DATA_MODEL_DEFAULT_VERSION);
+     * const dataModelChain = new DataModelBuilder().from<MyData>("v1");
      *
      * const myPlugin = PluginModel.define({
      *   name: 'myPlugin' as PluginName,
@@ -90,7 +90,7 @@ class PluginModelFactory {
  * @typeParam Outputs - Accumulated output types
  *
  * @example
- * const dataModelChain = new DataModelBuilder().from<TableData>(DATA_MODEL_DEFAULT_VERSION);
+ * const dataModelChain = new DataModelBuilder().from<TableData>("v1");
  *
  * const dataTable = PluginModel.define<TableData, TableParams, TableConfig>({
  *     name: 'dataTable' as PluginName,

package/dist/plugin_model.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"plugin_model.cjs","sources":["../src/plugin_model.ts"],"sourcesContent":["/**\n * PluginModel - Builder for creating plugin types with data model and outputs.\n *\n * Plugins are UI components with their own model logic and persistent state.\n * Block developers register plugin instances via BlockModelV3.plugin() method.\n *\n * @module plugin_model\n */\n\nimport type { BlockCodeKnownFeatureFlags } from \"@milaboratories/pl-model-common\";\nimport type { DataModel } from \"./block_migrations\";\nimport type { PluginName } from \"./block_storage\";\nimport type { PluginFactoryLike } from \"./plugin_handle\";\nimport type { PluginRenderCtx } from \"./render\";\n\n/** Symbol for internal builder creation method */\nconst FROM_BUILDER = Symbol(\"fromBuilder\");\n\nexport type PluginData = Record<string, unknown>;\nexport type PluginParams = undefined | Record<string, unknown>;\nexport type PluginOutputs = Record<string, unknown>;\nexport type PluginConfig = undefined | Record<string, unknown>;\n\n/**\n * Configured plugin instance returned by PluginModelFactory.create().\n * Contains the plugin's name, data model, and output definitions.\n */\nexport class PluginModel<\n  Data extends PluginData = PluginData,\n  Params extends PluginParams = undefined,\n  Outputs extends PluginOutputs = PluginOutputs,\n> {\n  /** Globally unique plugin name */\n  readonly name: PluginName;\n  /** Data model instance for this plugin */\n  readonly dataModel: DataModel<Data>;\n  /** Output definitions - functions that compute outputs from plugin context */\n  readonly outputs: {\n    [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n  };\n  /** Feature flags declared by this plugin */\n  readonly featureFlags?: BlockCodeKnownFeatureFlags;\n\n  private constructor(options: {\n    name: PluginName;\n    dataModel: DataModel<Data>;\n    outputs: {\n      [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n    };\n    featureFlags?: BlockCodeKnownFeatureFlags;\n  }) {\n    this.name = options.name;\n    this.dataModel = options.dataModel;\n    this.outputs = options.outputs;\n    this.featureFlags = options.featureFlags;\n  }\n\n  /**\n   * Internal method for creating PluginModel from factory.\n   * Uses Symbol key to prevent external access.\n   * @internal\n   */\n  static [FROM_BUILDER]<\n    Data extends PluginData,\n    Params extends PluginParams,\n    Outputs extends PluginOutputs,\n  >(options: {\n    name: PluginName;\n    dataModel: DataModel<Data>;\n    outputs: {\n      [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n    };\n    featureFlags?: BlockCodeKnownFeatureFlags;\n  }): PluginModel<Data, Params, Outputs> {\n    return new PluginModel<Data, Params, Outputs>(options);\n  }\n\n  /**\n   * Creates a new PluginModelBuilder for building plugin definitions.\n   *\n   * @param options.name - Globally unique plugin name\n   * @param options.data - Factory function that creates the data model from config\n   * @returns PluginModelBuilder for chaining output definitions\n   *\n   * @example\n   * const dataModelChain = new DataModelBuilder().from<MyData>(DATA_MODEL_DEFAULT_VERSION);\n   *\n   * const myPlugin = PluginModel.define({\n   *   name: 'myPlugin' as PluginName,\n   *   data: (cfg) => dataModelChain.init(() => ({ value: cfg.defaultValue })),\n   * })\n   *   .output('computed', (ctx) => ctx.data.value * ctx.params.multiplier)\n   *   .build();\n   */\n  static define<\n    Data extends PluginData,\n    Params extends PluginParams,\n    Config extends PluginConfig,\n  >(options: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n    featureFlags?: BlockCodeKnownFeatureFlags;\n  }): PluginModelBuilder<Data, Params, {}, Config> {\n    return PluginModelBuilder[FROM_BUILDER](options);\n  }\n}\n\n/** Plugin factory returned by PluginModelBuilder.build(). */\nexport interface PluginFactory<\n  Data extends PluginData = PluginData,\n  Params extends PluginParams = undefined,\n  Outputs extends PluginOutputs = PluginOutputs,\n  Config extends PluginConfig = undefined,\n> extends PluginFactoryLike {\n  create(config?: Config): PluginModel<Data, Params, Outputs>;\n  /**\n   * @internal Phantom field for structural type extraction.\n   * Enables InferFactoryData/InferFactoryOutputs to work via PluginFactoryLike.\n   */\n  readonly __types?: { data: Data; params: Params; outputs: Outputs; config: Config };\n}\n\nclass PluginModelFactory<\n  Data extends PluginData = PluginData,\n  Params extends PluginParams = undefined,\n  Outputs extends PluginOutputs = PluginOutputs,\n  Config extends PluginConfig = undefined,\n> implements PluginFactory<Data, Params, Outputs, Config> {\n  private readonly name: PluginName;\n  private readonly data: (config?: Config) => DataModel<Data>;\n  private readonly outputs: {\n    [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n  };\n  private readonly featureFlags?: BlockCodeKnownFeatureFlags;\n\n  constructor(options: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n    outputs: {\n      [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n    };\n    featureFlags?: BlockCodeKnownFeatureFlags;\n  }) {\n    this.name = options.name;\n    this.data = options.data;\n    this.outputs = options.outputs;\n    this.featureFlags = options.featureFlags;\n  }\n\n  /** Create a configured PluginModel instance */\n  create(config?: Config): PluginModel<Data, Params, Outputs> {\n    return PluginModel[FROM_BUILDER]<Data, Params, Outputs>({\n      name: this.name,\n      dataModel: this.data(config),\n      outputs: this.outputs,\n      featureFlags: this.featureFlags,\n    });\n  }\n}\n\n/**\n * Builder for creating PluginType with type-safe output definitions.\n *\n * Use `PluginModel.define()` to create a builder instance.\n *\n * @typeParam Data - Plugin's persistent data type\n * @typeParam Params - Params derived from block's RenderCtx (optional)\n * @typeParam Config - Static configuration passed to plugin factory (optional)\n * @typeParam Outputs - Accumulated output types\n *\n * @example\n * const dataModelChain = new DataModelBuilder().from<TableData>(DATA_MODEL_DEFAULT_VERSION);\n *\n * const dataTable = PluginModel.define<TableData, TableParams, TableConfig>({\n *     name: 'dataTable' as PluginName,\n *     data: (cfg) => {\n *       return dataModelChain.init(() => ({ state: createInitialState(cfg.ops) }));\n *     },\n *   })\n *   .output('model', (ctx) => createTableModel(ctx))\n *   .build();\n */\nclass PluginModelBuilder<\n  Data extends PluginData = PluginData,\n  Params extends PluginParams = undefined,\n  Outputs extends PluginOutputs = PluginOutputs,\n  Config extends PluginConfig = undefined,\n> {\n  private readonly name: PluginName;\n  private readonly data: (config?: Config) => DataModel<Data>;\n  private readonly outputs: {\n    [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n  };\n  private readonly featureFlags?: BlockCodeKnownFeatureFlags;\n\n  private constructor(options: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n    outputs?: {\n      [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n    };\n    featureFlags?: BlockCodeKnownFeatureFlags;\n  }) {\n    this.name = options.name;\n    this.data = options.data;\n    this.outputs =\n      options.outputs ??\n      ({} as {\n        [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n      });\n    this.featureFlags = options.featureFlags;\n  }\n\n  /**\n   * Internal method for creating PluginModelBuilder.\n   * Uses Symbol key to prevent external access.\n   * @internal\n   */\n  static [FROM_BUILDER]<\n    Data extends PluginData,\n    Params extends PluginParams,\n    Outputs extends PluginOutputs,\n    Config extends PluginConfig,\n  >(options: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n    outputs?: {\n      [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n    };\n    featureFlags?: BlockCodeKnownFeatureFlags;\n  }): PluginModelBuilder<Data, Params, Outputs, Config> {\n    return new PluginModelBuilder(options);\n  }\n\n  /**\n   * Adds an output to the plugin.\n   *\n   * @param key - Output name\n   * @param fn - Function that computes the output value from plugin context\n   * @returns PluginModel with the new output added\n   *\n   * @example\n   * .output('model', (ctx) => createModel(ctx.params.columns, ctx.data.state))\n   * .output('isReady', (ctx) => ctx.params.columns !== undefined)\n   */\n  output<const Key extends string, T>(\n    key: Key,\n    fn: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => T,\n  ): PluginModelBuilder<Data, Params, Outputs & { [K in Key]: T }, Config> {\n    return new PluginModelBuilder<Data, Params, Outputs & { [K in Key]: T }, Config>({\n      name: this.name,\n      data: this.data,\n      featureFlags: this.featureFlags,\n      outputs: {\n        ...this.outputs,\n        [key]: fn,\n      } as {\n        [K in keyof (Outputs & { [P in Key]: T })]: (\n          ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>,\n        ) => (Outputs & { [P in Key]: T })[K];\n      },\n    });\n  }\n\n  /**\n   * Finalizes the plugin definition and returns a ConfigurablePluginModel.\n   *\n   * @returns Callable plugin factory that accepts config and returns PluginModel\n   *\n   * @example\n   * const myPlugin = new PluginModelBuilder('myPlugin', () => dataModel)\n   *   .output('value', (ctx) => ctx.data.value)\n   *   .build();\n   *\n   * // Later, call create() with config to get a configured instance:\n   * const configured = myPlugin.create({ defaultValue: 'test' });\n   */\n  build(): PluginFactory<Data, Params, Outputs, Config> {\n    return new PluginModelFactory<Data, Params, Outputs, Config>({\n      name: this.name,\n      data: this.data,\n      outputs: this.outputs,\n      featureFlags: this.featureFlags,\n    });\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"plugin_model.cjs","sources":["../src/plugin_model.ts"],"sourcesContent":["/**\n * PluginModel - Builder for creating plugin types with data model and outputs.\n *\n * Plugins are UI components with their own model logic and persistent state.\n * Block developers register plugin instances via BlockModelV3.plugin() method.\n *\n * @module plugin_model\n */\n\nimport type { BlockCodeKnownFeatureFlags } from \"@milaboratories/pl-model-common\";\nimport type { DataModel } from \"./block_migrations\";\nimport type { PluginName } from \"./block_storage\";\nimport type { PluginFactoryLike } from \"./plugin_handle\";\nimport type { PluginRenderCtx } from \"./render\";\n\n/** Symbol for internal builder creation method */\nconst FROM_BUILDER = Symbol(\"fromBuilder\");\n\nexport type PluginData = Record<string, unknown>;\nexport type PluginParams = undefined | Record<string, unknown>;\nexport type PluginOutputs = Record<string, unknown>;\nexport type PluginConfig = undefined | Record<string, unknown>;\n\n/**\n * Configured plugin instance returned by PluginModelFactory.create().\n * Contains the plugin's name, data model, and output definitions.\n */\nexport class PluginModel<\n  Data extends PluginData = PluginData,\n  Params extends PluginParams = undefined,\n  Outputs extends PluginOutputs = PluginOutputs,\n> {\n  /** Globally unique plugin name */\n  readonly name: PluginName;\n  /** Data model instance for this plugin */\n  readonly dataModel: DataModel<Data>;\n  /** Output definitions - functions that compute outputs from plugin context */\n  readonly outputs: {\n    [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n  };\n  /** Feature flags declared by this plugin */\n  readonly featureFlags?: BlockCodeKnownFeatureFlags;\n\n  private constructor(options: {\n    name: PluginName;\n    dataModel: DataModel<Data>;\n    outputs: {\n      [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n    };\n    featureFlags?: BlockCodeKnownFeatureFlags;\n  }) {\n    this.name = options.name;\n    this.dataModel = options.dataModel;\n    this.outputs = options.outputs;\n    this.featureFlags = options.featureFlags;\n  }\n\n  /**\n   * Internal method for creating PluginModel from factory.\n   * Uses Symbol key to prevent external access.\n   * @internal\n   */\n  static [FROM_BUILDER]<\n    Data extends PluginData,\n    Params extends PluginParams,\n    Outputs extends PluginOutputs,\n  >(options: {\n    name: PluginName;\n    dataModel: DataModel<Data>;\n    outputs: {\n      [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n    };\n    featureFlags?: BlockCodeKnownFeatureFlags;\n  }): PluginModel<Data, Params, Outputs> {\n    return new PluginModel<Data, Params, Outputs>(options);\n  }\n\n  /**\n   * Creates a new PluginModelBuilder for building plugin definitions.\n   *\n   * @param options.name - Globally unique plugin name\n   * @param options.data - Factory function that creates the data model from config\n   * @returns PluginModelBuilder for chaining output definitions\n   *\n   * @example\n   * const dataModelChain = new DataModelBuilder().from<MyData>(\"v1\");\n   *\n   * const myPlugin = PluginModel.define({\n   *   name: 'myPlugin' as PluginName,\n   *   data: (cfg) => dataModelChain.init(() => ({ value: cfg.defaultValue })),\n   * })\n   *   .output('computed', (ctx) => ctx.data.value * ctx.params.multiplier)\n   *   .build();\n   */\n  static define<\n    Data extends PluginData,\n    Params extends PluginParams,\n    Config extends PluginConfig,\n  >(options: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n    featureFlags?: BlockCodeKnownFeatureFlags;\n  }): PluginModelBuilder<Data, Params, {}, Config> {\n    return PluginModelBuilder[FROM_BUILDER](options);\n  }\n}\n\n/** Plugin factory returned by PluginModelBuilder.build(). */\nexport interface PluginFactory<\n  Data extends PluginData = PluginData,\n  Params extends PluginParams = undefined,\n  Outputs extends PluginOutputs = PluginOutputs,\n  Config extends PluginConfig = undefined,\n> extends PluginFactoryLike {\n  create(config?: Config): PluginModel<Data, Params, Outputs>;\n  /**\n   * @internal Phantom field for structural type extraction.\n   * Enables InferFactoryData/InferFactoryOutputs to work via PluginFactoryLike.\n   */\n  readonly __types?: { data: Data; params: Params; outputs: Outputs; config: Config };\n}\n\nclass PluginModelFactory<\n  Data extends PluginData = PluginData,\n  Params extends PluginParams = undefined,\n  Outputs extends PluginOutputs = PluginOutputs,\n  Config extends PluginConfig = undefined,\n> implements PluginFactory<Data, Params, Outputs, Config> {\n  private readonly name: PluginName;\n  private readonly data: (config?: Config) => DataModel<Data>;\n  private readonly outputs: {\n    [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n  };\n  private readonly featureFlags?: BlockCodeKnownFeatureFlags;\n\n  constructor(options: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n    outputs: {\n      [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n    };\n    featureFlags?: BlockCodeKnownFeatureFlags;\n  }) {\n    this.name = options.name;\n    this.data = options.data;\n    this.outputs = options.outputs;\n    this.featureFlags = options.featureFlags;\n  }\n\n  /** Create a configured PluginModel instance */\n  create(config?: Config): PluginModel<Data, Params, Outputs> {\n    return PluginModel[FROM_BUILDER]<Data, Params, Outputs>({\n      name: this.name,\n      dataModel: this.data(config),\n      outputs: this.outputs,\n      featureFlags: this.featureFlags,\n    });\n  }\n}\n\n/**\n * Builder for creating PluginType with type-safe output definitions.\n *\n * Use `PluginModel.define()` to create a builder instance.\n *\n * @typeParam Data - Plugin's persistent data type\n * @typeParam Params - Params derived from block's RenderCtx (optional)\n * @typeParam Config - Static configuration passed to plugin factory (optional)\n * @typeParam Outputs - Accumulated output types\n *\n * @example\n * const dataModelChain = new DataModelBuilder().from<TableData>(\"v1\");\n *\n * const dataTable = PluginModel.define<TableData, TableParams, TableConfig>({\n *     name: 'dataTable' as PluginName,\n *     data: (cfg) => {\n *       return dataModelChain.init(() => ({ state: createInitialState(cfg.ops) }));\n *     },\n *   })\n *   .output('model', (ctx) => createTableModel(ctx))\n *   .build();\n */\nclass PluginModelBuilder<\n  Data extends PluginData = PluginData,\n  Params extends PluginParams = undefined,\n  Outputs extends PluginOutputs = PluginOutputs,\n  Config extends PluginConfig = undefined,\n> {\n  private readonly name: PluginName;\n  private readonly data: (config?: Config) => DataModel<Data>;\n  private readonly outputs: {\n    [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n  };\n  private readonly featureFlags?: BlockCodeKnownFeatureFlags;\n\n  private constructor(options: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n    outputs?: {\n      [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n    };\n    featureFlags?: BlockCodeKnownFeatureFlags;\n  }) {\n    this.name = options.name;\n    this.data = options.data;\n    this.outputs =\n      options.outputs ??\n      ({} as {\n        [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n      });\n    this.featureFlags = options.featureFlags;\n  }\n\n  /**\n   * Internal method for creating PluginModelBuilder.\n   * Uses Symbol key to prevent external access.\n   * @internal\n   */\n  static [FROM_BUILDER]<\n    Data extends PluginData,\n    Params extends PluginParams,\n    Outputs extends PluginOutputs,\n    Config extends PluginConfig,\n  >(options: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n    outputs?: {\n      [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n    };\n    featureFlags?: BlockCodeKnownFeatureFlags;\n  }): PluginModelBuilder<Data, Params, Outputs, Config> {\n    return new PluginModelBuilder(options);\n  }\n\n  /**\n   * Adds an output to the plugin.\n   *\n   * @param key - Output name\n   * @param fn - Function that computes the output value from plugin context\n   * @returns PluginModel with the new output added\n   *\n   * @example\n   * .output('model', (ctx) => createModel(ctx.params.columns, ctx.data.state))\n   * .output('isReady', (ctx) => ctx.params.columns !== undefined)\n   */\n  output<const Key extends string, T>(\n    key: Key,\n    fn: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => T,\n  ): PluginModelBuilder<Data, Params, Outputs & { [K in Key]: T }, Config> {\n    return new PluginModelBuilder<Data, Params, Outputs & { [K in Key]: T }, Config>({\n      name: this.name,\n      data: this.data,\n      featureFlags: this.featureFlags,\n      outputs: {\n        ...this.outputs,\n        [key]: fn,\n      } as {\n        [K in keyof (Outputs & { [P in Key]: T })]: (\n          ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>,\n        ) => (Outputs & { [P in Key]: T })[K];\n      },\n    });\n  }\n\n  /**\n   * Finalizes the plugin definition and returns a ConfigurablePluginModel.\n   *\n   * @returns Callable plugin factory that accepts config and returns PluginModel\n   *\n   * @example\n   * const myPlugin = new PluginModelBuilder('myPlugin', () => dataModel)\n   *   .output('value', (ctx) => ctx.data.value)\n   *   .build();\n   *\n   * // Later, call create() with config to get a configured instance:\n   * const configured = myPlugin.create({ defaultValue: 'test' });\n   */\n  build(): PluginFactory<Data, Params, Outputs, Config> {\n    return new PluginModelFactory<Data, Params, Outputs, Config>({\n      name: this.name,\n      data: this.data,\n      outputs: this.outputs,\n      featureFlags: this.featureFlags,\n    });\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/plugin_model.d.ts

@@ -54,7 +54,7 @@ export declare class PluginModel<Data extends PluginData = PluginData, Params ex
      * @returns PluginModelBuilder for chaining output definitions
      *
      * @example
-     * const dataModelChain = new DataModelBuilder().from<MyData>(DATA_MODEL_DEFAULT_VERSION);
+     * const dataModelChain = new DataModelBuilder().from<MyData>("v1");
      *
      * const myPlugin = PluginModel.define({
      *   name: 'myPlugin' as PluginName,
@@ -94,7 +94,7 @@ export interface PluginFactory<Data extends PluginData = PluginData, Params exte
  * @typeParam Outputs - Accumulated output types
  *
  * @example
- * const dataModelChain = new DataModelBuilder().from<TableData>(DATA_MODEL_DEFAULT_VERSION);
+ * const dataModelChain = new DataModelBuilder().from<TableData>("v1");
  *
  * const dataTable = PluginModel.define<TableData, TableParams, TableConfig>({
  *     name: 'dataTable' as PluginName,

package/dist/plugin_model.js

@@ -43,7 +43,7 @@ class PluginModel {
      * @returns PluginModelBuilder for chaining output definitions
      *
      * @example
-     * const dataModelChain = new DataModelBuilder().from<MyData>(DATA_MODEL_DEFAULT_VERSION);
+     * const dataModelChain = new DataModelBuilder().from<MyData>("v1");
      *
      * const myPlugin = PluginModel.define({
      *   name: 'myPlugin' as PluginName,
@@ -88,7 +88,7 @@ class PluginModelFactory {
  * @typeParam Outputs - Accumulated output types
  *
  * @example
- * const dataModelChain = new DataModelBuilder().from<TableData>(DATA_MODEL_DEFAULT_VERSION);
+ * const dataModelChain = new DataModelBuilder().from<TableData>("v1");
  *
  * const dataTable = PluginModel.define<TableData, TableParams, TableConfig>({
  *     name: 'dataTable' as PluginName,

package/dist/plugin_model.js.map

@@ -1 +1 @@
-{"version":3,"file":"plugin_model.js","sources":["../src/plugin_model.ts"],"sourcesContent":["/**\n * PluginModel - Builder for creating plugin types with data model and outputs.\n *\n * Plugins are UI components with their own model logic and persistent state.\n * Block developers register plugin instances via BlockModelV3.plugin() method.\n *\n * @module plugin_model\n */\n\nimport type { BlockCodeKnownFeatureFlags } from \"@milaboratories/pl-model-common\";\nimport type { DataModel } from \"./block_migrations\";\nimport type { PluginName } from \"./block_storage\";\nimport type { PluginFactoryLike } from \"./plugin_handle\";\nimport type { PluginRenderCtx } from \"./render\";\n\n/** Symbol for internal builder creation method */\nconst FROM_BUILDER = Symbol(\"fromBuilder\");\n\nexport type PluginData = Record<string, unknown>;\nexport type PluginParams = undefined | Record<string, unknown>;\nexport type PluginOutputs = Record<string, unknown>;\nexport type PluginConfig = undefined | Record<string, unknown>;\n\n/**\n * Configured plugin instance returned by PluginModelFactory.create().\n * Contains the plugin's name, data model, and output definitions.\n */\nexport class PluginModel<\n  Data extends PluginData = PluginData,\n  Params extends PluginParams = undefined,\n  Outputs extends PluginOutputs = PluginOutputs,\n> {\n  /** Globally unique plugin name */\n  readonly name: PluginName;\n  /** Data model instance for this plugin */\n  readonly dataModel: DataModel<Data>;\n  /** Output definitions - functions that compute outputs from plugin context */\n  readonly outputs: {\n    [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n  };\n  /** Feature flags declared by this plugin */\n  readonly featureFlags?: BlockCodeKnownFeatureFlags;\n\n  private constructor(options: {\n    name: PluginName;\n    dataModel: DataModel<Data>;\n    outputs: {\n      [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n    };\n    featureFlags?: BlockCodeKnownFeatureFlags;\n  }) {\n    this.name = options.name;\n    this.dataModel = options.dataModel;\n    this.outputs = options.outputs;\n    this.featureFlags = options.featureFlags;\n  }\n\n  /**\n   * Internal method for creating PluginModel from factory.\n   * Uses Symbol key to prevent external access.\n   * @internal\n   */\n  static [FROM_BUILDER]<\n    Data extends PluginData,\n    Params extends PluginParams,\n    Outputs extends PluginOutputs,\n  >(options: {\n    name: PluginName;\n    dataModel: DataModel<Data>;\n    outputs: {\n      [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n    };\n    featureFlags?: BlockCodeKnownFeatureFlags;\n  }): PluginModel<Data, Params, Outputs> {\n    return new PluginModel<Data, Params, Outputs>(options);\n  }\n\n  /**\n   * Creates a new PluginModelBuilder for building plugin definitions.\n   *\n   * @param options.name - Globally unique plugin name\n   * @param options.data - Factory function that creates the data model from config\n   * @returns PluginModelBuilder for chaining output definitions\n   *\n   * @example\n   * const dataModelChain = new DataModelBuilder().from<MyData>(DATA_MODEL_DEFAULT_VERSION);\n   *\n   * const myPlugin = PluginModel.define({\n   *   name: 'myPlugin' as PluginName,\n   *   data: (cfg) => dataModelChain.init(() => ({ value: cfg.defaultValue })),\n   * })\n   *   .output('computed', (ctx) => ctx.data.value * ctx.params.multiplier)\n   *   .build();\n   */\n  static define<\n    Data extends PluginData,\n    Params extends PluginParams,\n    Config extends PluginConfig,\n  >(options: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n    featureFlags?: BlockCodeKnownFeatureFlags;\n  }): PluginModelBuilder<Data, Params, {}, Config> {\n    return PluginModelBuilder[FROM_BUILDER](options);\n  }\n}\n\n/** Plugin factory returned by PluginModelBuilder.build(). */\nexport interface PluginFactory<\n  Data extends PluginData = PluginData,\n  Params extends PluginParams = undefined,\n  Outputs extends PluginOutputs = PluginOutputs,\n  Config extends PluginConfig = undefined,\n> extends PluginFactoryLike {\n  create(config?: Config): PluginModel<Data, Params, Outputs>;\n  /**\n   * @internal Phantom field for structural type extraction.\n   * Enables InferFactoryData/InferFactoryOutputs to work via PluginFactoryLike.\n   */\n  readonly __types?: { data: Data; params: Params; outputs: Outputs; config: Config };\n}\n\nclass PluginModelFactory<\n  Data extends PluginData = PluginData,\n  Params extends PluginParams = undefined,\n  Outputs extends PluginOutputs = PluginOutputs,\n  Config extends PluginConfig = undefined,\n> implements PluginFactory<Data, Params, Outputs, Config> {\n  private readonly name: PluginName;\n  private readonly data: (config?: Config) => DataModel<Data>;\n  private readonly outputs: {\n    [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n  };\n  private readonly featureFlags?: BlockCodeKnownFeatureFlags;\n\n  constructor(options: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n    outputs: {\n      [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n    };\n    featureFlags?: BlockCodeKnownFeatureFlags;\n  }) {\n    this.name = options.name;\n    this.data = options.data;\n    this.outputs = options.outputs;\n    this.featureFlags = options.featureFlags;\n  }\n\n  /** Create a configured PluginModel instance */\n  create(config?: Config): PluginModel<Data, Params, Outputs> {\n    return PluginModel[FROM_BUILDER]<Data, Params, Outputs>({\n      name: this.name,\n      dataModel: this.data(config),\n      outputs: this.outputs,\n      featureFlags: this.featureFlags,\n    });\n  }\n}\n\n/**\n * Builder for creating PluginType with type-safe output definitions.\n *\n * Use `PluginModel.define()` to create a builder instance.\n *\n * @typeParam Data - Plugin's persistent data type\n * @typeParam Params - Params derived from block's RenderCtx (optional)\n * @typeParam Config - Static configuration passed to plugin factory (optional)\n * @typeParam Outputs - Accumulated output types\n *\n * @example\n * const dataModelChain = new DataModelBuilder().from<TableData>(DATA_MODEL_DEFAULT_VERSION);\n *\n * const dataTable = PluginModel.define<TableData, TableParams, TableConfig>({\n *     name: 'dataTable' as PluginName,\n *     data: (cfg) => {\n *       return dataModelChain.init(() => ({ state: createInitialState(cfg.ops) }));\n *     },\n *   })\n *   .output('model', (ctx) => createTableModel(ctx))\n *   .build();\n */\nclass PluginModelBuilder<\n  Data extends PluginData = PluginData,\n  Params extends PluginParams = undefined,\n  Outputs extends PluginOutputs = PluginOutputs,\n  Config extends PluginConfig = undefined,\n> {\n  private readonly name: PluginName;\n  private readonly data: (config?: Config) => DataModel<Data>;\n  private readonly outputs: {\n    [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n  };\n  private readonly featureFlags?: BlockCodeKnownFeatureFlags;\n\n  private constructor(options: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n    outputs?: {\n      [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n    };\n    featureFlags?: BlockCodeKnownFeatureFlags;\n  }) {\n    this.name = options.name;\n    this.data = options.data;\n    this.outputs =\n      options.outputs ??\n      ({} as {\n        [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n      });\n    this.featureFlags = options.featureFlags;\n  }\n\n  /**\n   * Internal method for creating PluginModelBuilder.\n   * Uses Symbol key to prevent external access.\n   * @internal\n   */\n  static [FROM_BUILDER]<\n    Data extends PluginData,\n    Params extends PluginParams,\n    Outputs extends PluginOutputs,\n    Config extends PluginConfig,\n  >(options: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n    outputs?: {\n      [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n    };\n    featureFlags?: BlockCodeKnownFeatureFlags;\n  }): PluginModelBuilder<Data, Params, Outputs, Config> {\n    return new PluginModelBuilder(options);\n  }\n\n  /**\n   * Adds an output to the plugin.\n   *\n   * @param key - Output name\n   * @param fn - Function that computes the output value from plugin context\n   * @returns PluginModel with the new output added\n   *\n   * @example\n   * .output('model', (ctx) => createModel(ctx.params.columns, ctx.data.state))\n   * .output('isReady', (ctx) => ctx.params.columns !== undefined)\n   */\n  output<const Key extends string, T>(\n    key: Key,\n    fn: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => T,\n  ): PluginModelBuilder<Data, Params, Outputs & { [K in Key]: T }, Config> {\n    return new PluginModelBuilder<Data, Params, Outputs & { [K in Key]: T }, Config>({\n      name: this.name,\n      data: this.data,\n      featureFlags: this.featureFlags,\n      outputs: {\n        ...this.outputs,\n        [key]: fn,\n      } as {\n        [K in keyof (Outputs & { [P in Key]: T })]: (\n          ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>,\n        ) => (Outputs & { [P in Key]: T })[K];\n      },\n    });\n  }\n\n  /**\n   * Finalizes the plugin definition and returns a ConfigurablePluginModel.\n   *\n   * @returns Callable plugin factory that accepts config and returns PluginModel\n   *\n   * @example\n   * const myPlugin = new PluginModelBuilder('myPlugin', () => dataModel)\n   *   .output('value', (ctx) => ctx.data.value)\n   *   .build();\n   *\n   * // Later, call create() with config to get a configured instance:\n   * const configured = myPlugin.create({ defaultValue: 'test' });\n   */\n  build(): PluginFactory<Data, Params, Outputs, Config> {\n    return new PluginModelFactory<Data, Params, Outputs, Config>({\n      name: this.name,\n      data: this.data,\n      outputs: this.outputs,\n      featureFlags: this.featureFlags,\n    });\n  }\n}\n"],"names":[],"mappings":"AAAA;;;;;;;AAOG;AAQH;AACA,MAAM,YAAY,GAAG,MAAM,CAAC,aAAa,CAAC;AAO1C;;;AAGG;MACU,WAAW,CAAA;;AAMb,IAAA,IAAI;;AAEJ,IAAA,SAAS;;AAET,IAAA,OAAO;;AAIP,IAAA,YAAY;AAErB,IAAA,WAAA,CAAoB,OAOnB,EAAA;AACC,QAAA,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI;AACxB,QAAA,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS;AAClC,QAAA,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO;AAC9B,QAAA,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY;IAC1C;AAEA;;;;AAIG;AACH,IAAA,QAAQ,YAAY,CAAC,CAInB,OAOD,EAAA;AACC,QAAA,OAAO,IAAI,WAAW,CAAwB,OAAO,CAAC;IACxD;AAEA;;;;;;;;;;;;;;;;AAgBG;IACH,OAAO,MAAM,CAIX,OAID,EAAA;AACC,QAAA,OAAO,kBAAkB,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC;IAClD;AACD;AAiBD,MAAM,kBAAkB,CAAA;AAML,IAAA,IAAI;AACJ,IAAA,IAAI;AACJ,IAAA,OAAO;AAGP,IAAA,YAAY;AAE7B,IAAA,WAAA,CAAY,OAOX,EAAA;AACC,QAAA,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI;AACxB,QAAA,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI;AACxB,QAAA,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO;AAC9B,QAAA,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY;IAC1C;;AAGA,IAAA,MAAM,CAAC,MAAe,EAAA;AACpB,QAAA,OAAO,WAAW,CAAC,YAAY,CAAC,CAAwB;YACtD,IAAI,EAAE,IAAI,CAAC,IAAI;AACf,YAAA,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;YAC5B,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,YAAY,EAAE,IAAI,CAAC,YAAY;AAChC,SAAA,CAAC;IACJ;AACD;AAED;;;;;;;;;;;;;;;;;;;;;AAqBG;AACH,MAAM,kBAAkB,CAAA;AAML,IAAA,IAAI;AACJ,IAAA,IAAI;AACJ,IAAA,OAAO;AAGP,IAAA,YAAY;AAE7B,IAAA,WAAA,CAAoB,OAOnB,EAAA;AACC,QAAA,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI;AACxB,QAAA,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI;AACxB,QAAA,IAAI,CAAC,OAAO;AACV,YAAA,OAAO,CAAC,OAAO;AACd,gBAAA,EAEC;AACJ,QAAA,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY;IAC1C;AAEA;;;;AAIG;AACH,IAAA,QAAQ,YAAY,CAAC,CAKnB,OAOD,EAAA;AACC,QAAA,OAAO,IAAI,kBAAkB,CAAC,OAAO,CAAC;IACxC;AAEA;;;;;;;;;;AAUG;IACH,MAAM,CACJ,GAAQ,EACR,EAAgE,EAAA;QAEhE,OAAO,IAAI,kBAAkB,CAAoD;YAC/E,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,YAAY,EAAE,IAAI,CAAC,YAAY;AAC/B,YAAA,OAAO,EAAE;gBACP,GAAG,IAAI,CAAC,OAAO;gBACf,CAAC,GAAG,GAAG,EAAE;AAKV,aAAA;AACF,SAAA,CAAC;IACJ;AAEA;;;;;;;;;;;;AAYG;IACH,KAAK,GAAA;QACH,OAAO,IAAI,kBAAkB,CAAgC;YAC3D,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,YAAY,EAAE,IAAI,CAAC,YAAY;AAChC,SAAA,CAAC;IACJ;AACD;;;;"}
+{"version":3,"file":"plugin_model.js","sources":["../src/plugin_model.ts"],"sourcesContent":["/**\n * PluginModel - Builder for creating plugin types with data model and outputs.\n *\n * Plugins are UI components with their own model logic and persistent state.\n * Block developers register plugin instances via BlockModelV3.plugin() method.\n *\n * @module plugin_model\n */\n\nimport type { BlockCodeKnownFeatureFlags } from \"@milaboratories/pl-model-common\";\nimport type { DataModel } from \"./block_migrations\";\nimport type { PluginName } from \"./block_storage\";\nimport type { PluginFactoryLike } from \"./plugin_handle\";\nimport type { PluginRenderCtx } from \"./render\";\n\n/** Symbol for internal builder creation method */\nconst FROM_BUILDER = Symbol(\"fromBuilder\");\n\nexport type PluginData = Record<string, unknown>;\nexport type PluginParams = undefined | Record<string, unknown>;\nexport type PluginOutputs = Record<string, unknown>;\nexport type PluginConfig = undefined | Record<string, unknown>;\n\n/**\n * Configured plugin instance returned by PluginModelFactory.create().\n * Contains the plugin's name, data model, and output definitions.\n */\nexport class PluginModel<\n  Data extends PluginData = PluginData,\n  Params extends PluginParams = undefined,\n  Outputs extends PluginOutputs = PluginOutputs,\n> {\n  /** Globally unique plugin name */\n  readonly name: PluginName;\n  /** Data model instance for this plugin */\n  readonly dataModel: DataModel<Data>;\n  /** Output definitions - functions that compute outputs from plugin context */\n  readonly outputs: {\n    [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n  };\n  /** Feature flags declared by this plugin */\n  readonly featureFlags?: BlockCodeKnownFeatureFlags;\n\n  private constructor(options: {\n    name: PluginName;\n    dataModel: DataModel<Data>;\n    outputs: {\n      [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n    };\n    featureFlags?: BlockCodeKnownFeatureFlags;\n  }) {\n    this.name = options.name;\n    this.dataModel = options.dataModel;\n    this.outputs = options.outputs;\n    this.featureFlags = options.featureFlags;\n  }\n\n  /**\n   * Internal method for creating PluginModel from factory.\n   * Uses Symbol key to prevent external access.\n   * @internal\n   */\n  static [FROM_BUILDER]<\n    Data extends PluginData,\n    Params extends PluginParams,\n    Outputs extends PluginOutputs,\n  >(options: {\n    name: PluginName;\n    dataModel: DataModel<Data>;\n    outputs: {\n      [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n    };\n    featureFlags?: BlockCodeKnownFeatureFlags;\n  }): PluginModel<Data, Params, Outputs> {\n    return new PluginModel<Data, Params, Outputs>(options);\n  }\n\n  /**\n   * Creates a new PluginModelBuilder for building plugin definitions.\n   *\n   * @param options.name - Globally unique plugin name\n   * @param options.data - Factory function that creates the data model from config\n   * @returns PluginModelBuilder for chaining output definitions\n   *\n   * @example\n   * const dataModelChain = new DataModelBuilder().from<MyData>(\"v1\");\n   *\n   * const myPlugin = PluginModel.define({\n   *   name: 'myPlugin' as PluginName,\n   *   data: (cfg) => dataModelChain.init(() => ({ value: cfg.defaultValue })),\n   * })\n   *   .output('computed', (ctx) => ctx.data.value * ctx.params.multiplier)\n   *   .build();\n   */\n  static define<\n    Data extends PluginData,\n    Params extends PluginParams,\n    Config extends PluginConfig,\n  >(options: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n    featureFlags?: BlockCodeKnownFeatureFlags;\n  }): PluginModelBuilder<Data, Params, {}, Config> {\n    return PluginModelBuilder[FROM_BUILDER](options);\n  }\n}\n\n/** Plugin factory returned by PluginModelBuilder.build(). */\nexport interface PluginFactory<\n  Data extends PluginData = PluginData,\n  Params extends PluginParams = undefined,\n  Outputs extends PluginOutputs = PluginOutputs,\n  Config extends PluginConfig = undefined,\n> extends PluginFactoryLike {\n  create(config?: Config): PluginModel<Data, Params, Outputs>;\n  /**\n   * @internal Phantom field for structural type extraction.\n   * Enables InferFactoryData/InferFactoryOutputs to work via PluginFactoryLike.\n   */\n  readonly __types?: { data: Data; params: Params; outputs: Outputs; config: Config };\n}\n\nclass PluginModelFactory<\n  Data extends PluginData = PluginData,\n  Params extends PluginParams = undefined,\n  Outputs extends PluginOutputs = PluginOutputs,\n  Config extends PluginConfig = undefined,\n> implements PluginFactory<Data, Params, Outputs, Config> {\n  private readonly name: PluginName;\n  private readonly data: (config?: Config) => DataModel<Data>;\n  private readonly outputs: {\n    [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n  };\n  private readonly featureFlags?: BlockCodeKnownFeatureFlags;\n\n  constructor(options: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n    outputs: {\n      [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n    };\n    featureFlags?: BlockCodeKnownFeatureFlags;\n  }) {\n    this.name = options.name;\n    this.data = options.data;\n    this.outputs = options.outputs;\n    this.featureFlags = options.featureFlags;\n  }\n\n  /** Create a configured PluginModel instance */\n  create(config?: Config): PluginModel<Data, Params, Outputs> {\n    return PluginModel[FROM_BUILDER]<Data, Params, Outputs>({\n      name: this.name,\n      dataModel: this.data(config),\n      outputs: this.outputs,\n      featureFlags: this.featureFlags,\n    });\n  }\n}\n\n/**\n * Builder for creating PluginType with type-safe output definitions.\n *\n * Use `PluginModel.define()` to create a builder instance.\n *\n * @typeParam Data - Plugin's persistent data type\n * @typeParam Params - Params derived from block's RenderCtx (optional)\n * @typeParam Config - Static configuration passed to plugin factory (optional)\n * @typeParam Outputs - Accumulated output types\n *\n * @example\n * const dataModelChain = new DataModelBuilder().from<TableData>(\"v1\");\n *\n * const dataTable = PluginModel.define<TableData, TableParams, TableConfig>({\n *     name: 'dataTable' as PluginName,\n *     data: (cfg) => {\n *       return dataModelChain.init(() => ({ state: createInitialState(cfg.ops) }));\n *     },\n *   })\n *   .output('model', (ctx) => createTableModel(ctx))\n *   .build();\n */\nclass PluginModelBuilder<\n  Data extends PluginData = PluginData,\n  Params extends PluginParams = undefined,\n  Outputs extends PluginOutputs = PluginOutputs,\n  Config extends PluginConfig = undefined,\n> {\n  private readonly name: PluginName;\n  private readonly data: (config?: Config) => DataModel<Data>;\n  private readonly outputs: {\n    [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n  };\n  private readonly featureFlags?: BlockCodeKnownFeatureFlags;\n\n  private constructor(options: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n    outputs?: {\n      [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n    };\n    featureFlags?: BlockCodeKnownFeatureFlags;\n  }) {\n    this.name = options.name;\n    this.data = options.data;\n    this.outputs =\n      options.outputs ??\n      ({} as {\n        [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n      });\n    this.featureFlags = options.featureFlags;\n  }\n\n  /**\n   * Internal method for creating PluginModelBuilder.\n   * Uses Symbol key to prevent external access.\n   * @internal\n   */\n  static [FROM_BUILDER]<\n    Data extends PluginData,\n    Params extends PluginParams,\n    Outputs extends PluginOutputs,\n    Config extends PluginConfig,\n  >(options: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n    outputs?: {\n      [K in keyof Outputs]: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => Outputs[K];\n    };\n    featureFlags?: BlockCodeKnownFeatureFlags;\n  }): PluginModelBuilder<Data, Params, Outputs, Config> {\n    return new PluginModelBuilder(options);\n  }\n\n  /**\n   * Adds an output to the plugin.\n   *\n   * @param key - Output name\n   * @param fn - Function that computes the output value from plugin context\n   * @returns PluginModel with the new output added\n   *\n   * @example\n   * .output('model', (ctx) => createModel(ctx.params.columns, ctx.data.state))\n   * .output('isReady', (ctx) => ctx.params.columns !== undefined)\n   */\n  output<const Key extends string, T>(\n    key: Key,\n    fn: (ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>) => T,\n  ): PluginModelBuilder<Data, Params, Outputs & { [K in Key]: T }, Config> {\n    return new PluginModelBuilder<Data, Params, Outputs & { [K in Key]: T }, Config>({\n      name: this.name,\n      data: this.data,\n      featureFlags: this.featureFlags,\n      outputs: {\n        ...this.outputs,\n        [key]: fn,\n      } as {\n        [K in keyof (Outputs & { [P in Key]: T })]: (\n          ctx: PluginRenderCtx<PluginFactoryLike<Data, Params>>,\n        ) => (Outputs & { [P in Key]: T })[K];\n      },\n    });\n  }\n\n  /**\n   * Finalizes the plugin definition and returns a ConfigurablePluginModel.\n   *\n   * @returns Callable plugin factory that accepts config and returns PluginModel\n   *\n   * @example\n   * const myPlugin = new PluginModelBuilder('myPlugin', () => dataModel)\n   *   .output('value', (ctx) => ctx.data.value)\n   *   .build();\n   *\n   * // Later, call create() with config to get a configured instance:\n   * const configured = myPlugin.create({ defaultValue: 'test' });\n   */\n  build(): PluginFactory<Data, Params, Outputs, Config> {\n    return new PluginModelFactory<Data, Params, Outputs, Config>({\n      name: this.name,\n      data: this.data,\n      outputs: this.outputs,\n      featureFlags: this.featureFlags,\n    });\n  }\n}\n"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platforma-sdk/model",
-  "version": "1.58.0",
+  "version": "1.58.1",
   "description": "Platforma.bio SDK / Block Model",
   "files": [
     "./dist/**/*",
@@ -25,9 +25,9 @@
     "utility-types": "^3.11.0",
     "zod": "~3.23.8",
     "@milaboratories/helpers": "1.13.5",
+    "@milaboratories/pl-error-like": "1.12.8",
     "@milaboratories/pl-model-common": "1.25.0",
-    "@milaboratories/ptabler-expression-js": "1.1.22",
-    "@milaboratories/pl-error-like": "1.12.8"
+    "@milaboratories/ptabler-expression-js": "1.1.22"
   },
   "devDependencies": {
     "@vitest/coverage-istanbul": "^4.0.16",
@@ -35,8 +35,8 @@
     "typescript": "~5.6.3",
     "vitest": "^4.0.16",
     "@milaboratories/build-configs": "1.5.0",
-    "@milaboratories/ts-builder": "1.2.11",
-    "@milaboratories/ts-configs": "1.2.1"
+    "@milaboratories/ts-configs": "1.2.1",
+    "@milaboratories/ts-builder": "1.2.11"
   },
   "scripts": {
     "build": "ts-builder build --target node",

package/src/block_migrations.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { DataModelBuilder, defaultRecover, makeDataVersioned } from "./block_migrations";
+import { DATA_MODEL_LEGACY_VERSION } from "./block_storage";
 
 describe("makeDataVersioned", () => {
   it("creates correct DataVersioned shape", () => {
@@ -18,7 +19,6 @@ describe("DataModel migrations", () => {
     const result = dataModel.migrate(makeDataVersioned("legacy", { count: 42 }));
     expect(result.version).toBe("v2");
     expect(result.data).toStrictEqual({ count: 0, label: "" });
-    expect(result.warning).toBe(`Unknown version 'legacy'`);
   });
 
   it("throws at build time on duplicate version key", () => {
@@ -33,7 +33,7 @@ describe("DataModel migrations", () => {
     ).toThrow("Duplicate version 'v1' in migration chain");
   });
 
-  it("returns initial data on migration failure", () => {
+  it("throws on migration failure", () => {
     const dataModel = new DataModelBuilder()
       .from<{ numbers: number[] }>("v1")
       .migrate<{ numbers: number[]; label: string }>("v2", (v1) => {
@@ -42,10 +42,9 @@ describe("DataModel migrations", () => {
       })
       .init(() => ({ numbers: [], label: "" }));
 
-    const result = dataModel.migrate(makeDataVersioned("v1", { numbers: [666] }));
-    expect(result.version).toBe("v2");
-    expect(result.data).toStrictEqual({ numbers: [], label: "" });
-    expect(result.warning).toBe(`Migration v1→v2 failed: Forbidden number`);
+    expect(() => dataModel.migrate(makeDataVersioned("v1", { numbers: [666] }))).toThrow(
+      "Forbidden number",
+    );
   });
 
   describe("recover()", () => {
@@ -70,7 +69,6 @@ describe("DataModel migrations", () => {
       const result = dataModel.migrate(makeDataVersioned("legacy", { count: 5 }));
       expect(result.version).toBe("v2");
       expect(result.data).toStrictEqual({ count: 5, label: "default" });
-      expect(result.warning).toBeUndefined();
     });
 
     it("recover() between migrations — recovered data goes through subsequent migrations", () => {
@@ -97,7 +95,6 @@ describe("DataModel migrations", () => {
       const result = dataModel.migrate(makeDataVersioned("legacy", { count: 7 }));
       expect(result.version).toBe("v3");
       expect(result.data).toStrictEqual({ count: 7, label: "recovered", description: "added" });
-      expect(result.warning).toBeUndefined();
     });
 
     it("recover() at the end of chain — recovered data is the final type", () => {
@@ -122,10 +119,9 @@ describe("DataModel migrations", () => {
       const result = dataModel.migrate(makeDataVersioned("legacy", { count: 9 }));
       expect(result.version).toBe("v2");
       expect(result.data).toStrictEqual({ count: 9, label: "recovered" });
-      expect(result.warning).toBeUndefined();
     });
 
-    it("recover() delegates to defaultRecover for truly unknown versions", () => {
+    it("recover() delegates to defaultRecover for truly unknown versions — resets to initial data", () => {
       const dataModel = new DataModelBuilder()
         .from<{ count: number }>("v1")
         .migrate<{ count: number; label: string }>("v2", (v1) => ({ ...v1, label: "" }))
@@ -135,7 +131,6 @@ describe("DataModel migrations", () => {
       const result = dataModel.migrate(makeDataVersioned("unknown", { count: 7 }));
       expect(result.version).toBe("v2");
       expect(result.data).toStrictEqual({ count: 0, label: "" });
-      expect(result.warning).toBe(`Unknown version 'unknown'`);
     });
 
     it("migration failure after recover() resets to initial data", () => {
@@ -164,7 +159,6 @@ describe("DataModel migrations", () => {
       const result = dataModel.migrate(makeDataVersioned("legacy", { count: 7 }));
       expect(result.version).toBe("v3");
       expect(result.data).toStrictEqual({ count: 0, label: "", description: "" });
-      expect(result.warning).toBe("Migration v2→v3 failed: v3 failed");
     });
 
     it("recover() cannot be called twice — enforced by type (no recover() on WithRecover)", () => {
@@ -172,4 +166,107 @@ describe("DataModel migrations", () => {
       // Verified by the absence of recover() in DataModelMigrationChainWithRecover.
     });
   });
+
+  describe("upgradeLegacy()", () => {
+    type LegacyArgs = { inputFile: string; threshold: number };
+    type LegacyUiState = { selectedTab: string };
+    type BlockData = { inputFile: string; threshold: number; selectedTab: string };
+
+    it("upgrades legacy { args, uiState } data with custom initial version", () => {
+      const dataModel = new DataModelBuilder()
+        .from<BlockData>("v1")
+        .upgradeLegacy<LegacyArgs, LegacyUiState>(({ args, uiState }) => ({
+          inputFile: args.inputFile,
+          threshold: args.threshold,
+          selectedTab: uiState.selectedTab,
+        }))
+        .init(() => ({ inputFile: "", threshold: 0, selectedTab: "main" }));
+
+      // Legacy data arrives at DATA_MODEL_LEGACY_VERSION (how normalizeBlockStorage wraps it)
+      const result = dataModel.migrate(
+        makeDataVersioned(DATA_MODEL_LEGACY_VERSION, {
+          args: { inputFile: "test.fa", threshold: 5 },
+          uiState: { selectedTab: "results" },
+        }),
+      );
+      expect(result.version).toBe("v1");
+      expect(result.data).toStrictEqual({
+        inputFile: "test.fa",
+        threshold: 5,
+        selectedTab: "results",
+      });
+    });
+
+    it("passes through non-legacy data at custom initial version unchanged", () => {
+      const dataModel = new DataModelBuilder()
+        .from<BlockData>("v1")
+        .upgradeLegacy<LegacyArgs, LegacyUiState>(({ args, uiState }) => ({
+          inputFile: args.inputFile,
+          threshold: args.threshold,
+          selectedTab: uiState.selectedTab,
+        }))
+        .init(() => ({ inputFile: "", threshold: 0, selectedTab: "main" }));
+
+      // Non-legacy data at the user's version passes through unchanged
+      const result = dataModel.migrate(
+        makeDataVersioned("v1", {
+          inputFile: "existing.fa",
+          threshold: 10,
+          selectedTab: "overview",
+        }),
+      );
+      expect(result.version).toBe("v1");
+      expect(result.data).toStrictEqual({
+        inputFile: "existing.fa",
+        threshold: 10,
+        selectedTab: "overview",
+      });
+    });
+
+    it("upgrades legacy data and runs subsequent migrations", () => {
+      type BlockDataV2 = BlockData & { description: string };
+
+      const dataModel = new DataModelBuilder()
+        .from<BlockData>("v1")
+        .upgradeLegacy<LegacyArgs, LegacyUiState>(({ args, uiState }) => ({
+          inputFile: args.inputFile,
+          threshold: args.threshold,
+          selectedTab: uiState.selectedTab,
+        }))
+        .migrate<BlockDataV2>("v2", (v1) => ({ ...v1, description: "auto" }))
+        .init(() => ({ inputFile: "", threshold: 0, selectedTab: "main", description: "" }));
+
+      const result = dataModel.migrate(
+        makeDataVersioned(DATA_MODEL_LEGACY_VERSION, {
+          args: { inputFile: "test.fa", threshold: 3 },
+          uiState: { selectedTab: "tab1" },
+        }),
+      );
+      expect(result.version).toBe("v2");
+      expect(result.data).toStrictEqual({
+        inputFile: "test.fa",
+        threshold: 3,
+        selectedTab: "tab1",
+        description: "auto",
+      });
+    });
+
+    it("throws when legacy upgrade fails", () => {
+      const dataModel = new DataModelBuilder()
+        .from<BlockData>("v1")
+        .upgradeLegacy<LegacyArgs, LegacyUiState>(() => {
+          throw new Error("bad legacy data");
+        })
+        .init(() => ({ inputFile: "", threshold: 0, selectedTab: "main" }));
+
+      expect(() =>
+        dataModel.migrate(
+          makeDataVersioned(DATA_MODEL_LEGACY_VERSION, {
+            args: { inputFile: "test.fa", threshold: 5 },
+            uiState: { selectedTab: "results" },
+          }),
+        ),
+      ).toThrow("bad legacy data");
+    });
+  });
 });