@platforma-sdk/model 1.55.0 → 1.57.0

package/dist/block_storage.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"block_storage.cjs","sources":["../src/block_storage.ts"],"sourcesContent":["/**\n * BlockStorage - Typed storage abstraction for block persistent data.\n *\n * This module provides:\n * - A typed structure for block storage with versioning and plugin support\n * - Utility functions for manipulating storage\n * - Handler interfaces for model-level customization\n *\n * @module block_storage\n */\n\nimport type { Branded } from \"@milaboratories/pl-model-common\";\nimport type { DataMigrationResult, DataVersioned } from \"./block_migrations\";\n\n// =============================================================================\n// Core Types\n// =============================================================================\n\n/**\n * Discriminator key for BlockStorage format detection.\n * This unique hash-based key identifies data as BlockStorage vs legacy formats.\n */\nexport const BLOCK_STORAGE_KEY = \"__pl_a7f3e2b9__\";\n\n/**\n * Current BlockStorage schema version.\n * Increment this when the storage structure itself changes (not block state migrations).\n */\nexport const BLOCK_STORAGE_SCHEMA_VERSION = \"v1\";\n\n/**\n * Default data version for new blocks without migrations.\n * Unique identifier ensures blocks are created via DataModel API.\n */\nexport const DATA_MODEL_DEFAULT_VERSION = \"__pl_v1_d4e8f2a1__\";\n\n/**\n * Type for valid schema versions\n */\nexport type BlockStorageSchemaVersion = \"v1\"; // Add 'v2', 'v3', etc. as schema evolves\n\n/**\n * Branded type for plugin names - globally unique plugin type identifiers.\n * Using a branded type enforces explicit casting (`as PluginName`) which makes\n * it easy to find all plugin name definitions in the codebase and verify uniqueness.\n */\nexport type PluginName = Branded<string, \"PluginName\">;\n\n/**\n * Plugin registry - maps pluginId (unique within a block) to pluginName (globally unique plugin type).\n * Using a Record highlights that pluginIds must be unique within a block.\n */\nexport type PluginRegistry = Record<string, PluginName>;\n\n/**\n * Versioned data - used for both block data and plugin data\n */\nexport interface VersionedData<TData = unknown> {\n  /** Version of the data, used for migrations */\n  __dataVersion: string;\n  /** The persistent data */\n  __data: TData;\n}\n\n/**\n * Core BlockStorage type that holds:\n * - __pl_a7f3e2b9__: Schema version (discriminator key identifies BlockStorage format)\n * - __dataVersion: Version key for block data migrations\n * - __data: The block's user-facing data (state)\n * - __pluginRegistry: Map from pluginId to pluginName (optional)\n * - __plugins: Plugin-specific data keyed by pluginId (optional)\n */\nexport type BlockStorage<TState = unknown> = {\n  /** Schema version - the key itself is the discriminator */\n  readonly [BLOCK_STORAGE_KEY]: BlockStorageSchemaVersion;\n  /** Registry of plugins: pluginId -> pluginName */\n  __pluginRegistry?: PluginRegistry;\n  /** Plugin-specific data, keyed by pluginId */\n  __plugins?: Record<string, VersionedData<unknown>>;\n} & VersionedData<TState>;\n\n/**\n * Type guard to check if a value is a valid BlockStorage object.\n * Checks for the discriminator key and valid schema version.\n */\nexport function isBlockStorage(value: unknown): value is BlockStorage {\n  if (value === null || typeof value !== \"object\") return false;\n  const obj = value as Record<string, unknown>;\n  const schemaVersion = obj[BLOCK_STORAGE_KEY];\n  // Currently only 'v1' is valid, but this allows future versions\n  return schemaVersion === \"v1\"; // Add more versions as schema evolves\n}\n\n// =============================================================================\n// Factory Functions\n// =============================================================================\n\n/**\n * Creates a BlockStorage with the given initial data\n *\n * @param initialData - The initial data value (defaults to empty object)\n * @param version - The initial data version key (defaults to DATA_MODEL_DEFAULT_VERSION)\n * @returns A new BlockStorage instance with discriminator key\n */\nexport function createBlockStorage<TState = unknown>(\n  initialData: TState = {} as TState,\n  version: string = DATA_MODEL_DEFAULT_VERSION,\n): BlockStorage<TState> {\n  return {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: version,\n    __data: initialData,\n    __pluginRegistry: {},\n    __plugins: {},\n  };\n}\n\n/**\n * Normalizes raw storage data to BlockStorage format.\n * If the input is already a BlockStorage, returns it as-is (with defaults for missing fields).\n * If the input is legacy format (raw state), wraps it in BlockStorage structure.\n *\n * @param raw - Raw storage data (may be legacy format or BlockStorage)\n * @returns Normalized BlockStorage\n */\nexport function normalizeBlockStorage<TState = unknown>(raw: unknown): BlockStorage<TState> {\n  if (isBlockStorage(raw)) {\n    const storage = raw as BlockStorage<TState>;\n    return {\n      ...storage,\n      // Fix for early released version where __dataVersion was a number\n      __dataVersion:\n        typeof storage.__dataVersion === \"number\"\n          ? DATA_MODEL_DEFAULT_VERSION\n          : storage.__dataVersion,\n      // Ensure plugin fields have defaults\n      __pluginRegistry: storage.__pluginRegistry ?? {},\n      __plugins: storage.__plugins ?? {},\n    };\n  }\n  // Legacy format: raw is the state directly\n  return createBlockStorage(raw as TState);\n}\n\n// =============================================================================\n// Data Access & Update Functions\n// =============================================================================\n\n/**\n * Gets the data from BlockStorage\n *\n * @param storage - The BlockStorage instance\n * @returns The data value\n */\nexport function getStorageData<TState>(storage: BlockStorage<TState>): TState {\n  return storage.__data;\n}\n\n/**\n * Derives data from raw block storage.\n * This function is meant to be called from sdk/ui-vue to extract\n * user-facing data from the raw storage returned by the middle layer.\n *\n * The middle layer returns raw storage (opaque to it), and the UI\n * uses this function to derive the actual data value.\n *\n * @param rawStorage - Raw storage data from middle layer (may be any format)\n * @returns The extracted data value, or undefined if storage is undefined/null\n */\nexport function deriveDataFromStorage<TData = unknown>(rawStorage: unknown): TData {\n  // Normalize to BlockStorage format (handles legacy formats too)\n  const storage = normalizeBlockStorage<TData>(rawStorage);\n  return getStorageData(storage);\n}\n\n/** Payload for storage mutation operations. SDK defines specific operations. */\nexport type MutateStoragePayload<T = unknown> =\n  | { operation: \"update-block-data\"; value: T }\n  | { operation: \"update-plugin-data\"; pluginId: string; value: unknown };\n\n/**\n * Updates the data in BlockStorage (immutable)\n *\n * @param storage - The current BlockStorage\n * @param payload - The update payload with operation and value\n * @returns A new BlockStorage with updated data\n */\nexport function updateStorageData<TValue = unknown>(\n  storage: BlockStorage<TValue>,\n  payload: MutateStoragePayload<TValue>,\n): BlockStorage<TValue> {\n  switch (payload.operation) {\n    case \"update-block-data\":\n      return { ...storage, __data: payload.value };\n    case \"update-plugin-data\": {\n      const { pluginId, value } = payload;\n      const currentPlugins = storage.__plugins ?? {};\n      const existingEntry = currentPlugins[pluginId];\n      const version = existingEntry?.__dataVersion ?? DATA_MODEL_DEFAULT_VERSION;\n      return {\n        ...storage,\n        __plugins: {\n          ...currentPlugins,\n          [pluginId]: {\n            __dataVersion: version,\n            __data: value,\n          },\n        },\n      };\n    }\n    default:\n      throw new Error(`Unknown storage operation: ${(payload as { operation: string }).operation}`);\n  }\n}\n\n/**\n * Storage debug view returned by __pl_storage_debugView callback.\n * Used by developer tools to display block storage info.\n */\nexport interface StorageDebugView {\n  /** Current data version key */\n  dataVersion: string;\n  /** Raw data payload stored in BlockStorage */\n  data: unknown;\n}\n\n// =============================================================================\n// Atomic Migration\n// =============================================================================\n\n/**\n * Result of a successful atomic migration.\n */\nexport interface MigrationSuccess<TState> {\n  success: true;\n  /** The fully migrated storage - commit this to persist */\n  storage: BlockStorage<TState>;\n}\n\n/**\n * Result of a failed atomic migration.\n * The original storage is untouched - user must choose to abort or reset.\n */\nexport interface MigrationFailure {\n  success: false;\n  /** Description of what failed */\n  error: string;\n  /** Which step failed: 'block' or pluginId */\n  failedAt: string;\n}\n\nexport type MigrationResult<TState> = MigrationSuccess<TState> | MigrationFailure;\n\n/**\n * Configuration for atomic block storage migration.\n * Callbacks use DataVersioned format (the DataModel API format).\n * Conversion to internal VersionedData format is handled by migrateBlockStorage().\n */\nexport interface MigrateBlockStorageConfig {\n  /** Migrate block data from any version to latest */\n  migrateBlockData: (versioned: DataVersioned<unknown>) => DataMigrationResult<unknown>;\n  /** Migrate each plugin's data. Return undefined to remove the plugin. */\n  migratePluginData: (\n    pluginId: string,\n    versioned: DataVersioned<unknown>,\n  ) => DataMigrationResult<unknown> | undefined;\n  /** The new plugin registry after migration (pluginId -> pluginName) */\n  newPluginRegistry: PluginRegistry;\n  /** Factory to create initial data for new plugins */\n  createPluginData: (pluginId: string) => DataVersioned<unknown>;\n}\n\n/**\n * Performs atomic migration of block storage including block data and all plugins.\n *\n * Migration is atomic: either everything succeeds and a new storage is returned,\n * or an error is returned and the original storage is completely untouched.\n *\n * Migration steps:\n * 1. Migrate block data\n * 2. For each plugin in newPluginRegistry:\n *    - If plugin exists with same name: migrate its data\n *    - Otherwise (new or type changed): create with initial data\n *    Plugins not in newPluginRegistry are dropped.\n *\n * If any step throws, migration fails and original storage is preserved.\n * User can then choose to:\n * - Abort: keep original storage, don't update block\n * - Reset: call createBlockStorage() to start fresh\n *\n * @param storage - The original storage (will not be modified)\n * @param config - Migration configuration\n * @returns Migration result - either success with new storage, or failure with error info\n *\n * @example\n * const result = migrateBlockStorage(storage, {\n *   migrateBlockData: (versioned) => blockDataModel.migrate(versioned),\n *   migratePluginData: (pluginId, versioned) => getPluginModel(pluginId).migrate(versioned),\n *   newPluginRegistry: { table1: 'dataTable' as PluginName },\n *   createPluginData: (pluginId) => getPluginModel(pluginId).getDefaultData(),\n * });\n *\n * if (result.success) {\n *   commitStorage(result.storage);\n * } else {\n *   const userChoice = await askUser(`Migration failed: ${result.error}. Reset data?`);\n *   if (userChoice === 'reset') {\n *     commitStorage(createBlockStorage(initialData, currentVersion));\n *   }\n *   // else: abort, keep original\n * }\n */\nexport function migrateBlockStorage(\n  storage: BlockStorage<unknown>,\n  config: MigrateBlockStorageConfig,\n): MigrationResult<unknown> {\n  const { migrateBlockData, migratePluginData, newPluginRegistry, createPluginData } = config;\n\n  // Step 1: Migrate block data\n  let migratedData: unknown;\n  let newVersion: string;\n  try {\n    const result = migrateBlockData({ version: storage.__dataVersion, data: storage.__data });\n    migratedData = result.data;\n    newVersion = result.version;\n  } catch (error) {\n    return {\n      success: false,\n      error: error instanceof Error ? error.message : String(error),\n      failedAt: \"block\",\n    };\n  }\n\n  // Step 2: Migrate plugins\n  const oldPlugins = storage.__plugins ?? {};\n  const oldRegistry = storage.__pluginRegistry ?? {};\n  const newPlugins: Record<string, VersionedData<unknown>> = {};\n\n  for (const [pluginId, pluginName] of Object.entries(newPluginRegistry)) {\n    const existingEntry = oldPlugins[pluginId];\n    const existingName = oldRegistry[pluginId];\n\n    try {\n      if (existingEntry && existingName === pluginName) {\n        // Plugin exists with same type - migrate its data\n        const migrated = migratePluginData(pluginId, {\n          version: existingEntry.__dataVersion,\n          data: existingEntry.__data,\n        });\n        if (migrated) {\n          newPlugins[pluginId] = { __dataVersion: migrated.version, __data: migrated.data };\n        }\n        // If undefined returned, plugin is intentionally removed\n      } else {\n        // New plugin or type changed - create with initial data\n        const initial = createPluginData(pluginId);\n        newPlugins[pluginId] = { __dataVersion: initial.version, __data: initial.data };\n      }\n    } catch (error) {\n      return {\n        success: false,\n        error: error instanceof Error ? error.message : String(error),\n        failedAt: pluginId,\n      };\n    }\n  }\n\n  // Step 3: Build final storage atomically\n  const migratedStorage: BlockStorage = {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: newVersion,\n    __data: migratedData,\n    __pluginRegistry: newPluginRegistry,\n    __plugins: newPlugins,\n  };\n\n  return {\n    success: true,\n    storage: migratedStorage,\n  };\n}\n\n/**\n * Gets plugin-specific data from BlockStorage (for UI)\n *\n * @param storage - The BlockStorage instance\n * @param pluginId - The plugin instance id\n * @returns The plugin data or undefined if not set\n */\nexport function getPluginData<TData = unknown>(\n  storage: BlockStorage,\n  pluginId: string,\n): TData | undefined {\n  const pluginEntry = storage.__plugins?.[pluginId];\n  if (!pluginEntry) return undefined;\n  return pluginEntry.__data as TData;\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"block_storage.cjs","sources":["../src/block_storage.ts"],"sourcesContent":["/**\n * BlockStorage - Typed storage abstraction for block persistent data.\n *\n * This module provides:\n * - A typed structure for block storage with versioning and plugin support\n * - Utility functions for manipulating storage\n * - Handler interfaces for model-level customization\n *\n * @module block_storage\n */\n\nimport type { Branded } from \"@milaboratories/pl-model-common\";\nimport type { DataMigrationResult, DataVersioned } from \"./block_migrations\";\n\n// =============================================================================\n// Core Types\n// =============================================================================\n\n/**\n * Discriminator key for BlockStorage format detection.\n * This unique hash-based key identifies data as BlockStorage vs legacy formats.\n */\nexport const BLOCK_STORAGE_KEY = \"__pl_a7f3e2b9__\";\n\n/**\n * Current BlockStorage schema version.\n * Increment this when the storage structure itself changes (not block state migrations).\n */\nexport const BLOCK_STORAGE_SCHEMA_VERSION = \"v1\";\n\n/**\n * Default data version for new blocks without migrations.\n * Unique identifier ensures blocks are created via DataModel API.\n */\nexport const DATA_MODEL_DEFAULT_VERSION = \"__pl_v1_d4e8f2a1__\";\n\n/**\n * Type for valid schema versions\n */\nexport type BlockStorageSchemaVersion = \"v1\"; // Add 'v2', 'v3', etc. as schema evolves\n\n/**\n * Branded type for plugin names - globally unique plugin type identifiers.\n * Using a branded type enforces explicit casting (`as PluginName`) which makes\n * it easy to find all plugin name definitions in the codebase and verify uniqueness.\n */\nexport type PluginName = Branded<string, \"PluginName\">;\n\n/**\n * Plugin registry - maps pluginId (unique within a block) to pluginName (globally unique plugin type).\n * Using a Record highlights that pluginIds must be unique within a block.\n */\nexport type PluginRegistry = Record<string, PluginName>;\n\n/**\n * Versioned data - used for both block data and plugin data\n */\nexport interface VersionedData<TData = unknown> {\n  /** Version of the data, used for migrations */\n  __dataVersion: string;\n  /** The persistent data */\n  __data: TData;\n}\n\n/**\n * Core BlockStorage type that holds:\n * - __pl_a7f3e2b9__: Schema version (discriminator key identifies BlockStorage format)\n * - __dataVersion: Version key for block data migrations\n * - __data: The block's user-facing data (state)\n * - __pluginRegistry: Map from pluginId to pluginName (optional)\n * - __plugins: Plugin-specific data keyed by pluginId (optional)\n */\nexport type BlockStorage<TState = unknown> = {\n  /** Schema version - the key itself is the discriminator */\n  readonly [BLOCK_STORAGE_KEY]: BlockStorageSchemaVersion;\n  /** Registry of plugins: pluginId -> pluginName */\n  __pluginRegistry?: PluginRegistry;\n  /** Plugin-specific data, keyed by pluginId */\n  __plugins?: Record<string, VersionedData<unknown>>;\n} & VersionedData<TState>;\n\n/**\n * Type guard to check if a value is a valid BlockStorage object.\n * Checks for the discriminator key and valid schema version.\n */\nexport function isBlockStorage(value: unknown): value is BlockStorage {\n  if (value === null || typeof value !== \"object\") return false;\n  const obj = value as Record<string, unknown>;\n  const schemaVersion = obj[BLOCK_STORAGE_KEY];\n  // Currently only 'v1' is valid, but this allows future versions\n  return schemaVersion === \"v1\"; // Add more versions as schema evolves\n}\n\n// =============================================================================\n// Factory Functions\n// =============================================================================\n\n/**\n * Creates a BlockStorage with the given initial data\n *\n * @param initialData - The initial data value (defaults to empty object)\n * @param version - The initial data version key (defaults to DATA_MODEL_DEFAULT_VERSION)\n * @returns A new BlockStorage instance with discriminator key\n */\nexport function createBlockStorage<TState = unknown>(\n  initialData: TState = {} as TState,\n  version: string = DATA_MODEL_DEFAULT_VERSION,\n): BlockStorage<TState> {\n  return {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: version,\n    __data: initialData,\n    __pluginRegistry: {},\n    __plugins: {},\n  };\n}\n\n/**\n * Normalizes raw storage data to BlockStorage format.\n * If the input is already a BlockStorage, returns it as-is (with defaults for missing fields).\n * If the input is legacy format (raw state), wraps it in BlockStorage structure.\n *\n * @param raw - Raw storage data (may be legacy format or BlockStorage)\n * @returns Normalized BlockStorage\n */\nexport function normalizeBlockStorage<TState = unknown>(raw: unknown): BlockStorage<TState> {\n  if (isBlockStorage(raw)) {\n    const storage = raw as BlockStorage<TState>;\n    return {\n      ...storage,\n      // Fix for early released version where __dataVersion was a number\n      __dataVersion:\n        typeof storage.__dataVersion === \"number\"\n          ? DATA_MODEL_DEFAULT_VERSION\n          : storage.__dataVersion,\n      // Ensure plugin fields have defaults\n      __pluginRegistry: storage.__pluginRegistry ?? {},\n      __plugins: storage.__plugins ?? {},\n    };\n  }\n  // Legacy format: raw is the state directly\n  return createBlockStorage(raw as TState);\n}\n\n// =============================================================================\n// Data Access & Update Functions\n// =============================================================================\n\n/**\n * Gets the data from BlockStorage\n *\n * @param storage - The BlockStorage instance\n * @returns The data value\n */\nexport function getStorageData<TState>(storage: BlockStorage<TState>): TState {\n  return storage.__data;\n}\n\n/**\n * Derives data from raw block storage.\n * This function is meant to be called from sdk/ui-vue to extract\n * user-facing data from the raw storage returned by the middle layer.\n *\n * The middle layer returns raw storage (opaque to it), and the UI\n * uses this function to derive the actual data value.\n *\n * @param rawStorage - Raw storage data from middle layer (may be any format)\n * @returns The extracted data value, or undefined if storage is undefined/null\n */\nexport function deriveDataFromStorage<TData = unknown>(rawStorage: unknown): TData {\n  // Normalize to BlockStorage format (handles legacy formats too)\n  const storage = normalizeBlockStorage<TData>(rawStorage);\n  return getStorageData(storage);\n}\n\n/** Payload for storage mutation operations. SDK defines specific operations. */\nexport type MutateStoragePayload<T = unknown> =\n  | { operation: \"update-block-data\"; value: T }\n  | { operation: \"update-plugin-data\"; pluginId: string; value: unknown };\n\n/**\n * Updates the data in BlockStorage (immutable)\n *\n * @param storage - The current BlockStorage\n * @param payload - The update payload with operation and value\n * @returns A new BlockStorage with updated data\n */\nexport function updateStorageData<TValue = unknown>(\n  storage: BlockStorage<TValue>,\n  payload: MutateStoragePayload<TValue>,\n): BlockStorage<TValue> {\n  switch (payload.operation) {\n    case \"update-block-data\":\n      return { ...storage, __data: payload.value };\n    case \"update-plugin-data\": {\n      const { pluginId, value } = payload;\n      const currentPlugins = storage.__plugins ?? {};\n      const existingEntry = currentPlugins[pluginId];\n      const version = existingEntry?.__dataVersion ?? DATA_MODEL_DEFAULT_VERSION;\n      return {\n        ...storage,\n        __plugins: {\n          ...currentPlugins,\n          [pluginId]: {\n            __dataVersion: version,\n            __data: value,\n          },\n        },\n      };\n    }\n    default:\n      throw new Error(`Unknown storage operation: ${(payload as { operation: string }).operation}`);\n  }\n}\n\n/**\n * Storage debug view returned by __pl_storage_debugView callback.\n * Used by developer tools to display block storage info.\n */\nexport interface StorageDebugView {\n  /** Current data version key */\n  dataVersion: string;\n  /** Raw data payload stored in BlockStorage */\n  data: unknown;\n}\n\n// =============================================================================\n// Atomic Migration\n// =============================================================================\n\n/**\n * Result of a successful atomic migration.\n */\nexport interface MigrationSuccess<TState> {\n  success: true;\n  /** The fully migrated storage - commit this to persist */\n  storage: BlockStorage<TState>;\n}\n\n/**\n * Result of a failed atomic migration.\n * The original storage is untouched - user must choose to abort or reset.\n */\nexport interface MigrationFailure {\n  success: false;\n  /** Description of what failed */\n  error: string;\n  /** Which step failed: 'block' or pluginId */\n  failedAt: string;\n}\n\nexport type MigrationResult<TState> = MigrationSuccess<TState> | MigrationFailure;\n\n/**\n * Configuration for atomic block storage migration.\n * Callbacks use DataVersioned format (the DataModel API format).\n * Conversion to internal VersionedData format is handled by migrateBlockStorage().\n */\nexport interface MigrateBlockStorageConfig {\n  /** Migrate block data from any version to latest */\n  migrateBlockData: (versioned: DataVersioned<unknown>) => DataMigrationResult<unknown>;\n  /** Migrate each plugin's data. Return undefined to remove the plugin. */\n  migratePluginData: (\n    pluginId: string,\n    versioned: DataVersioned<unknown>,\n  ) => DataMigrationResult<unknown> | undefined;\n  /** The new plugin registry after migration (pluginId -> pluginName) */\n  newPluginRegistry: PluginRegistry;\n  /** Factory to create initial data for new plugins */\n  createPluginData: (pluginId: string) => DataVersioned<unknown>;\n}\n\n/**\n * Performs atomic migration of block storage including block data and all plugins.\n *\n * Migration is atomic: either everything succeeds and a new storage is returned,\n * or an error is returned and the original storage is completely untouched.\n *\n * Migration steps:\n * 1. Migrate block data\n * 2. For each plugin in newPluginRegistry:\n *    - If plugin exists with same name: migrate its data\n *    - Otherwise (new or type changed): create with initial data\n *    Plugins not in newPluginRegistry are dropped.\n *\n * If any step throws, migration fails and original storage is preserved.\n * User can then choose to:\n * - Abort: keep original storage, don't update block\n * - Reset: call createBlockStorage() to start fresh\n *\n * @param storage - The original storage (will not be modified)\n * @param config - Migration configuration\n * @returns Migration result - either success with new storage, or failure with error info\n *\n * @example\n * const result = migrateBlockStorage(storage, {\n *   migrateBlockData: (versioned) => blockDataModel.migrate(versioned),\n *   migratePluginData: (pluginId, versioned) => getPluginModel(pluginId).migrate(versioned),\n *   newPluginRegistry: { table1: 'dataTable' as PluginName },\n *   createPluginData: (pluginId) => getPluginModel(pluginId).getDefaultData(),\n * });\n *\n * if (result.success) {\n *   commitStorage(result.storage);\n * } else {\n *   const userChoice = await askUser(`Migration failed: ${result.error}. Reset data?`);\n *   if (userChoice === 'reset') {\n *     commitStorage(createBlockStorage(initialData, currentVersion));\n *   }\n *   // else: abort, keep original\n * }\n */\nexport function migrateBlockStorage(\n  storage: BlockStorage<unknown>,\n  config: MigrateBlockStorageConfig,\n): MigrationResult<unknown> {\n  const { migrateBlockData, migratePluginData, newPluginRegistry, createPluginData } = config;\n\n  // Step 1: Migrate block data\n  let migratedData: unknown;\n  let newVersion: string;\n  try {\n    const result = migrateBlockData({ version: storage.__dataVersion, data: storage.__data });\n    migratedData = result.data;\n    newVersion = result.version;\n  } catch (error) {\n    return {\n      success: false,\n      error: error instanceof Error ? error.message : String(error),\n      failedAt: \"block\",\n    };\n  }\n\n  // Step 2: Migrate plugins\n  const oldPlugins = storage.__plugins ?? {};\n  const oldRegistry = storage.__pluginRegistry ?? {};\n  const newPlugins: Record<string, VersionedData<unknown>> = {};\n\n  for (const [pluginId, pluginName] of Object.entries(newPluginRegistry)) {\n    const existingEntry = oldPlugins[pluginId];\n    const existingName = oldRegistry[pluginId];\n\n    try {\n      if (existingEntry && existingName === pluginName) {\n        // Plugin exists with same type - migrate its data\n        const migrated = migratePluginData(pluginId, {\n          version: existingEntry.__dataVersion,\n          data: existingEntry.__data,\n        });\n        if (migrated) {\n          newPlugins[pluginId] = { __dataVersion: migrated.version, __data: migrated.data };\n        }\n        // If undefined returned, plugin is intentionally removed\n      } else {\n        // New plugin or type changed - create with initial data\n        const initial = createPluginData(pluginId);\n        newPlugins[pluginId] = { __dataVersion: initial.version, __data: initial.data };\n      }\n    } catch (error) {\n      return {\n        success: false,\n        error: error instanceof Error ? error.message : String(error),\n        failedAt: pluginId,\n      };\n    }\n  }\n\n  // Step 3: Build final storage atomically\n  const migratedStorage: BlockStorage = {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: newVersion,\n    __data: migratedData,\n    __pluginRegistry: newPluginRegistry,\n    __plugins: newPlugins,\n  };\n\n  return {\n    success: true,\n    storage: migratedStorage,\n  };\n}\n\n/**\n * Gets plugin-specific data from block storage.\n * Accepts raw storage (any format) and normalizes internally.\n *\n * @param rawStorage - Raw block storage (may be legacy format or BlockStorage)\n * @param pluginId - The plugin instance id\n * @returns The plugin data\n * @throws If pluginId is not found in storage\n */\nexport function getPluginData<TData = unknown>(rawStorage: unknown, pluginId: string): TData {\n  const storage = normalizeBlockStorage(rawStorage);\n  const pluginEntry = storage.__plugins?.[pluginId];\n  if (!pluginEntry) throw new Error(`Plugin '${pluginId}' not found in block storage`);\n  return pluginEntry.__data as TData;\n}\n"],"names":[],"mappings":"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"}

package/dist/block_storage.d.ts

@@ -210,11 +210,13 @@ export interface MigrateBlockStorageConfig {
  */
 export declare function migrateBlockStorage(storage: BlockStorage<unknown>, config: MigrateBlockStorageConfig): MigrationResult<unknown>;
 /**
- * Gets plugin-specific data from BlockStorage (for UI)
+ * Gets plugin-specific data from block storage.
+ * Accepts raw storage (any format) and normalizes internally.
  *
- * @param storage - The BlockStorage instance
+ * @param rawStorage - Raw block storage (may be legacy format or BlockStorage)
  * @param pluginId - The plugin instance id
- * @returns The plugin data or undefined if not set
+ * @returns The plugin data
+ * @throws If pluginId is not found in storage
  */
-export declare function getPluginData<TData = unknown>(storage: BlockStorage, pluginId: string): TData | undefined;
+export declare function getPluginData<TData = unknown>(rawStorage: unknown, pluginId: string): TData;
 //# sourceMappingURL=block_storage.d.ts.map

package/dist/block_storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"block_storage.d.ts","sourceRoot":"","sources":["../src/block_storage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"block_storage.d.ts","sourceRoot":"","sources":["../src/block_storage.ts"],"names":[],"mappings":"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"}

package/dist/block_storage.js

@@ -245,16 +245,19 @@ function migrateBlockStorage(storage, config) {
     };
 }
 /**
- * Gets plugin-specific data from BlockStorage (for UI)
+ * Gets plugin-specific data from block storage.
+ * Accepts raw storage (any format) and normalizes internally.
  *
- * @param storage - The BlockStorage instance
+ * @param rawStorage - Raw block storage (may be legacy format or BlockStorage)
  * @param pluginId - The plugin instance id
- * @returns The plugin data or undefined if not set
+ * @returns The plugin data
+ * @throws If pluginId is not found in storage
  */
-function getPluginData(storage, pluginId) {
+function getPluginData(rawStorage, pluginId) {
+    const storage = normalizeBlockStorage(rawStorage);
     const pluginEntry = storage.__plugins?.[pluginId];
     if (!pluginEntry)
-        return undefined;
+        throw new Error(`Plugin '${pluginId}' not found in block storage`);
     return pluginEntry.__data;
 }
 

package/dist/block_storage.js.map

@@ -1 +1 @@
-{"version":3,"file":"block_storage.js","sources":["../src/block_storage.ts"],"sourcesContent":["/**\n * BlockStorage - Typed storage abstraction for block persistent data.\n *\n * This module provides:\n * - A typed structure for block storage with versioning and plugin support\n * - Utility functions for manipulating storage\n * - Handler interfaces for model-level customization\n *\n * @module block_storage\n */\n\nimport type { Branded } from \"@milaboratories/pl-model-common\";\nimport type { DataMigrationResult, DataVersioned } from \"./block_migrations\";\n\n// =============================================================================\n// Core Types\n// =============================================================================\n\n/**\n * Discriminator key for BlockStorage format detection.\n * This unique hash-based key identifies data as BlockStorage vs legacy formats.\n */\nexport const BLOCK_STORAGE_KEY = \"__pl_a7f3e2b9__\";\n\n/**\n * Current BlockStorage schema version.\n * Increment this when the storage structure itself changes (not block state migrations).\n */\nexport const BLOCK_STORAGE_SCHEMA_VERSION = \"v1\";\n\n/**\n * Default data version for new blocks without migrations.\n * Unique identifier ensures blocks are created via DataModel API.\n */\nexport const DATA_MODEL_DEFAULT_VERSION = \"__pl_v1_d4e8f2a1__\";\n\n/**\n * Type for valid schema versions\n */\nexport type BlockStorageSchemaVersion = \"v1\"; // Add 'v2', 'v3', etc. as schema evolves\n\n/**\n * Branded type for plugin names - globally unique plugin type identifiers.\n * Using a branded type enforces explicit casting (`as PluginName`) which makes\n * it easy to find all plugin name definitions in the codebase and verify uniqueness.\n */\nexport type PluginName = Branded<string, \"PluginName\">;\n\n/**\n * Plugin registry - maps pluginId (unique within a block) to pluginName (globally unique plugin type).\n * Using a Record highlights that pluginIds must be unique within a block.\n */\nexport type PluginRegistry = Record<string, PluginName>;\n\n/**\n * Versioned data - used for both block data and plugin data\n */\nexport interface VersionedData<TData = unknown> {\n  /** Version of the data, used for migrations */\n  __dataVersion: string;\n  /** The persistent data */\n  __data: TData;\n}\n\n/**\n * Core BlockStorage type that holds:\n * - __pl_a7f3e2b9__: Schema version (discriminator key identifies BlockStorage format)\n * - __dataVersion: Version key for block data migrations\n * - __data: The block's user-facing data (state)\n * - __pluginRegistry: Map from pluginId to pluginName (optional)\n * - __plugins: Plugin-specific data keyed by pluginId (optional)\n */\nexport type BlockStorage<TState = unknown> = {\n  /** Schema version - the key itself is the discriminator */\n  readonly [BLOCK_STORAGE_KEY]: BlockStorageSchemaVersion;\n  /** Registry of plugins: pluginId -> pluginName */\n  __pluginRegistry?: PluginRegistry;\n  /** Plugin-specific data, keyed by pluginId */\n  __plugins?: Record<string, VersionedData<unknown>>;\n} & VersionedData<TState>;\n\n/**\n * Type guard to check if a value is a valid BlockStorage object.\n * Checks for the discriminator key and valid schema version.\n */\nexport function isBlockStorage(value: unknown): value is BlockStorage {\n  if (value === null || typeof value !== \"object\") return false;\n  const obj = value as Record<string, unknown>;\n  const schemaVersion = obj[BLOCK_STORAGE_KEY];\n  // Currently only 'v1' is valid, but this allows future versions\n  return schemaVersion === \"v1\"; // Add more versions as schema evolves\n}\n\n// =============================================================================\n// Factory Functions\n// =============================================================================\n\n/**\n * Creates a BlockStorage with the given initial data\n *\n * @param initialData - The initial data value (defaults to empty object)\n * @param version - The initial data version key (defaults to DATA_MODEL_DEFAULT_VERSION)\n * @returns A new BlockStorage instance with discriminator key\n */\nexport function createBlockStorage<TState = unknown>(\n  initialData: TState = {} as TState,\n  version: string = DATA_MODEL_DEFAULT_VERSION,\n): BlockStorage<TState> {\n  return {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: version,\n    __data: initialData,\n    __pluginRegistry: {},\n    __plugins: {},\n  };\n}\n\n/**\n * Normalizes raw storage data to BlockStorage format.\n * If the input is already a BlockStorage, returns it as-is (with defaults for missing fields).\n * If the input is legacy format (raw state), wraps it in BlockStorage structure.\n *\n * @param raw - Raw storage data (may be legacy format or BlockStorage)\n * @returns Normalized BlockStorage\n */\nexport function normalizeBlockStorage<TState = unknown>(raw: unknown): BlockStorage<TState> {\n  if (isBlockStorage(raw)) {\n    const storage = raw as BlockStorage<TState>;\n    return {\n      ...storage,\n      // Fix for early released version where __dataVersion was a number\n      __dataVersion:\n        typeof storage.__dataVersion === \"number\"\n          ? DATA_MODEL_DEFAULT_VERSION\n          : storage.__dataVersion,\n      // Ensure plugin fields have defaults\n      __pluginRegistry: storage.__pluginRegistry ?? {},\n      __plugins: storage.__plugins ?? {},\n    };\n  }\n  // Legacy format: raw is the state directly\n  return createBlockStorage(raw as TState);\n}\n\n// =============================================================================\n// Data Access & Update Functions\n// =============================================================================\n\n/**\n * Gets the data from BlockStorage\n *\n * @param storage - The BlockStorage instance\n * @returns The data value\n */\nexport function getStorageData<TState>(storage: BlockStorage<TState>): TState {\n  return storage.__data;\n}\n\n/**\n * Derives data from raw block storage.\n * This function is meant to be called from sdk/ui-vue to extract\n * user-facing data from the raw storage returned by the middle layer.\n *\n * The middle layer returns raw storage (opaque to it), and the UI\n * uses this function to derive the actual data value.\n *\n * @param rawStorage - Raw storage data from middle layer (may be any format)\n * @returns The extracted data value, or undefined if storage is undefined/null\n */\nexport function deriveDataFromStorage<TData = unknown>(rawStorage: unknown): TData {\n  // Normalize to BlockStorage format (handles legacy formats too)\n  const storage = normalizeBlockStorage<TData>(rawStorage);\n  return getStorageData(storage);\n}\n\n/** Payload for storage mutation operations. SDK defines specific operations. */\nexport type MutateStoragePayload<T = unknown> =\n  | { operation: \"update-block-data\"; value: T }\n  | { operation: \"update-plugin-data\"; pluginId: string; value: unknown };\n\n/**\n * Updates the data in BlockStorage (immutable)\n *\n * @param storage - The current BlockStorage\n * @param payload - The update payload with operation and value\n * @returns A new BlockStorage with updated data\n */\nexport function updateStorageData<TValue = unknown>(\n  storage: BlockStorage<TValue>,\n  payload: MutateStoragePayload<TValue>,\n): BlockStorage<TValue> {\n  switch (payload.operation) {\n    case \"update-block-data\":\n      return { ...storage, __data: payload.value };\n    case \"update-plugin-data\": {\n      const { pluginId, value } = payload;\n      const currentPlugins = storage.__plugins ?? {};\n      const existingEntry = currentPlugins[pluginId];\n      const version = existingEntry?.__dataVersion ?? DATA_MODEL_DEFAULT_VERSION;\n      return {\n        ...storage,\n        __plugins: {\n          ...currentPlugins,\n          [pluginId]: {\n            __dataVersion: version,\n            __data: value,\n          },\n        },\n      };\n    }\n    default:\n      throw new Error(`Unknown storage operation: ${(payload as { operation: string }).operation}`);\n  }\n}\n\n/**\n * Storage debug view returned by __pl_storage_debugView callback.\n * Used by developer tools to display block storage info.\n */\nexport interface StorageDebugView {\n  /** Current data version key */\n  dataVersion: string;\n  /** Raw data payload stored in BlockStorage */\n  data: unknown;\n}\n\n// =============================================================================\n// Atomic Migration\n// =============================================================================\n\n/**\n * Result of a successful atomic migration.\n */\nexport interface MigrationSuccess<TState> {\n  success: true;\n  /** The fully migrated storage - commit this to persist */\n  storage: BlockStorage<TState>;\n}\n\n/**\n * Result of a failed atomic migration.\n * The original storage is untouched - user must choose to abort or reset.\n */\nexport interface MigrationFailure {\n  success: false;\n  /** Description of what failed */\n  error: string;\n  /** Which step failed: 'block' or pluginId */\n  failedAt: string;\n}\n\nexport type MigrationResult<TState> = MigrationSuccess<TState> | MigrationFailure;\n\n/**\n * Configuration for atomic block storage migration.\n * Callbacks use DataVersioned format (the DataModel API format).\n * Conversion to internal VersionedData format is handled by migrateBlockStorage().\n */\nexport interface MigrateBlockStorageConfig {\n  /** Migrate block data from any version to latest */\n  migrateBlockData: (versioned: DataVersioned<unknown>) => DataMigrationResult<unknown>;\n  /** Migrate each plugin's data. Return undefined to remove the plugin. */\n  migratePluginData: (\n    pluginId: string,\n    versioned: DataVersioned<unknown>,\n  ) => DataMigrationResult<unknown> | undefined;\n  /** The new plugin registry after migration (pluginId -> pluginName) */\n  newPluginRegistry: PluginRegistry;\n  /** Factory to create initial data for new plugins */\n  createPluginData: (pluginId: string) => DataVersioned<unknown>;\n}\n\n/**\n * Performs atomic migration of block storage including block data and all plugins.\n *\n * Migration is atomic: either everything succeeds and a new storage is returned,\n * or an error is returned and the original storage is completely untouched.\n *\n * Migration steps:\n * 1. Migrate block data\n * 2. For each plugin in newPluginRegistry:\n *    - If plugin exists with same name: migrate its data\n *    - Otherwise (new or type changed): create with initial data\n *    Plugins not in newPluginRegistry are dropped.\n *\n * If any step throws, migration fails and original storage is preserved.\n * User can then choose to:\n * - Abort: keep original storage, don't update block\n * - Reset: call createBlockStorage() to start fresh\n *\n * @param storage - The original storage (will not be modified)\n * @param config - Migration configuration\n * @returns Migration result - either success with new storage, or failure with error info\n *\n * @example\n * const result = migrateBlockStorage(storage, {\n *   migrateBlockData: (versioned) => blockDataModel.migrate(versioned),\n *   migratePluginData: (pluginId, versioned) => getPluginModel(pluginId).migrate(versioned),\n *   newPluginRegistry: { table1: 'dataTable' as PluginName },\n *   createPluginData: (pluginId) => getPluginModel(pluginId).getDefaultData(),\n * });\n *\n * if (result.success) {\n *   commitStorage(result.storage);\n * } else {\n *   const userChoice = await askUser(`Migration failed: ${result.error}. Reset data?`);\n *   if (userChoice === 'reset') {\n *     commitStorage(createBlockStorage(initialData, currentVersion));\n *   }\n *   // else: abort, keep original\n * }\n */\nexport function migrateBlockStorage(\n  storage: BlockStorage<unknown>,\n  config: MigrateBlockStorageConfig,\n): MigrationResult<unknown> {\n  const { migrateBlockData, migratePluginData, newPluginRegistry, createPluginData } = config;\n\n  // Step 1: Migrate block data\n  let migratedData: unknown;\n  let newVersion: string;\n  try {\n    const result = migrateBlockData({ version: storage.__dataVersion, data: storage.__data });\n    migratedData = result.data;\n    newVersion = result.version;\n  } catch (error) {\n    return {\n      success: false,\n      error: error instanceof Error ? error.message : String(error),\n      failedAt: \"block\",\n    };\n  }\n\n  // Step 2: Migrate plugins\n  const oldPlugins = storage.__plugins ?? {};\n  const oldRegistry = storage.__pluginRegistry ?? {};\n  const newPlugins: Record<string, VersionedData<unknown>> = {};\n\n  for (const [pluginId, pluginName] of Object.entries(newPluginRegistry)) {\n    const existingEntry = oldPlugins[pluginId];\n    const existingName = oldRegistry[pluginId];\n\n    try {\n      if (existingEntry && existingName === pluginName) {\n        // Plugin exists with same type - migrate its data\n        const migrated = migratePluginData(pluginId, {\n          version: existingEntry.__dataVersion,\n          data: existingEntry.__data,\n        });\n        if (migrated) {\n          newPlugins[pluginId] = { __dataVersion: migrated.version, __data: migrated.data };\n        }\n        // If undefined returned, plugin is intentionally removed\n      } else {\n        // New plugin or type changed - create with initial data\n        const initial = createPluginData(pluginId);\n        newPlugins[pluginId] = { __dataVersion: initial.version, __data: initial.data };\n      }\n    } catch (error) {\n      return {\n        success: false,\n        error: error instanceof Error ? error.message : String(error),\n        failedAt: pluginId,\n      };\n    }\n  }\n\n  // Step 3: Build final storage atomically\n  const migratedStorage: BlockStorage = {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: newVersion,\n    __data: migratedData,\n    __pluginRegistry: newPluginRegistry,\n    __plugins: newPlugins,\n  };\n\n  return {\n    success: true,\n    storage: migratedStorage,\n  };\n}\n\n/**\n * Gets plugin-specific data from BlockStorage (for UI)\n *\n * @param storage - The BlockStorage instance\n * @param pluginId - The plugin instance id\n * @returns The plugin data or undefined if not set\n */\nexport function getPluginData<TData = unknown>(\n  storage: BlockStorage,\n  pluginId: string,\n): TData | undefined {\n  const pluginEntry = storage.__plugins?.[pluginId];\n  if (!pluginEntry) return undefined;\n  return pluginEntry.__data as TData;\n}\n"],"names":[],"mappings":"AAAA;;;;;;;;;AASG;AAKH;AACA;AACA;AAEA;;;AAGG;AACI,MAAM,iBAAiB,GAAG;AAEjC;;;AAGG;AACI,MAAM,4BAA4B,GAAG;AAE5C;;;AAGG;AACI,MAAM,0BAA0B,GAAG;AA+C1C;;;AAGG;AACG,SAAU,cAAc,CAAC,KAAc,EAAA;AAC3C,IAAA,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;AAAE,QAAA,OAAO,KAAK;IAC7D,MAAM,GAAG,GAAG,KAAgC;AAC5C,IAAA,MAAM,aAAa,GAAG,GAAG,CAAC,iBAAiB,CAAC;;AAE5C,IAAA,OAAO,aAAa,KAAK,IAAI,CAAC;AAChC;AAEA;AACA;AACA;AAEA;;;;;;AAMG;SACa,kBAAkB,CAChC,cAAsB,EAAY,EAClC,UAAkB,0BAA0B,EAAA;IAE5C,OAAO;QACL,CAAC,iBAAiB,GAAG,4BAA4B;AACjD,QAAA,aAAa,EAAE,OAAO;AACtB,QAAA,MAAM,EAAE,WAAW;AACnB,QAAA,gBAAgB,EAAE,EAAE;AACpB,QAAA,SAAS,EAAE,EAAE;KACd;AACH;AAEA;;;;;;;AAOG;AACG,SAAU,qBAAqB,CAAmB,GAAY,EAAA;AAClE,IAAA,IAAI,cAAc,CAAC,GAAG,CAAC,EAAE;QACvB,MAAM,OAAO,GAAG,GAA2B;QAC3C,OAAO;AACL,YAAA,GAAG,OAAO;;AAEV,YAAA,aAAa,EACX,OAAO,OAAO,CAAC,aAAa,KAAK;AAC/B,kBAAE;kBACA,OAAO,CAAC,aAAa;;AAE3B,YAAA,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,IAAI,EAAE;AAChD,YAAA,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,EAAE;SACnC;IACH;;AAEA,IAAA,OAAO,kBAAkB,CAAC,GAAa,CAAC;AAC1C;AAEA;AACA;AACA;AAEA;;;;;AAKG;AACG,SAAU,cAAc,CAAS,OAA6B,EAAA;IAClE,OAAO,OAAO,CAAC,MAAM;AACvB;AAEA;;;;;;;;;;AAUG;AACG,SAAU,qBAAqB,CAAkB,UAAmB,EAAA;;AAExE,IAAA,MAAM,OAAO,GAAG,qBAAqB,CAAQ,UAAU,CAAC;AACxD,IAAA,OAAO,cAAc,CAAC,OAAO,CAAC;AAChC;AAOA;;;;;;AAMG;AACG,SAAU,iBAAiB,CAC/B,OAA6B,EAC7B,OAAqC,EAAA;AAErC,IAAA,QAAQ,OAAO,CAAC,SAAS;AACvB,QAAA,KAAK,mBAAmB;YACtB,OAAO,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,KAAK,EAAE;QAC9C,KAAK,oBAAoB,EAAE;AACzB,YAAA,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,OAAO;AACnC,YAAA,MAAM,cAAc,GAAG,OAAO,CAAC,SAAS,IAAI,EAAE;AAC9C,YAAA,MAAM,aAAa,GAAG,cAAc,CAAC,QAAQ,CAAC;AAC9C,YAAA,MAAM,OAAO,GAAG,aAAa,EAAE,aAAa,IAAI,0BAA0B;YAC1E,OAAO;AACL,gBAAA,GAAG,OAAO;AACV,gBAAA,SAAS,EAAE;AACT,oBAAA,GAAG,cAAc;oBACjB,CAAC,QAAQ,GAAG;AACV,wBAAA,aAAa,EAAE,OAAO;AACtB,wBAAA,MAAM,EAAE,KAAK;AACd,qBAAA;AACF,iBAAA;aACF;QACH;AACA,QAAA;YACE,MAAM,IAAI,KAAK,CAAC,CAAA,2BAAA,EAA+B,OAAiC,CAAC,SAAS,CAAA,CAAE,CAAC;;AAEnG;AA2DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCG;AACG,SAAU,mBAAmB,CACjC,OAA8B,EAC9B,MAAiC,EAAA;IAEjC,MAAM,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,GAAG,MAAM;;AAG3F,IAAA,IAAI,YAAqB;AACzB,IAAA,IAAI,UAAkB;AACtB,IAAA,IAAI;AACF,QAAA,MAAM,MAAM,GAAG,gBAAgB,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,aAAa,EAAE,IAAI,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;AACzF,QAAA,YAAY,GAAG,MAAM,CAAC,IAAI;AAC1B,QAAA,UAAU,GAAG,MAAM,CAAC,OAAO;IAC7B;IAAE,OAAO,KAAK,EAAE;QACd,OAAO;AACL,YAAA,OAAO,EAAE,KAAK;AACd,YAAA,KAAK,EAAE,KAAK,YAAY,KAAK,GAAG,KAAK,CAAC,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC;AAC7D,YAAA,QAAQ,EAAE,OAAO;SAClB;IACH;;AAGA,IAAA,MAAM,UAAU,GAAG,OAAO,CAAC,SAAS,IAAI,EAAE;AAC1C,IAAA,MAAM,WAAW,GAAG,OAAO,CAAC,gBAAgB,IAAI,EAAE;IAClD,MAAM,UAAU,GAA2C,EAAE;AAE7D,IAAA,KAAK,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAE;AACtE,QAAA,MAAM,aAAa,GAAG,UAAU,CAAC,QAAQ,CAAC;AAC1C,QAAA,MAAM,YAAY,GAAG,WAAW,CAAC,QAAQ,CAAC;AAE1C,QAAA,IAAI;AACF,YAAA,IAAI,aAAa,IAAI,YAAY,KAAK,UAAU,EAAE;;AAEhD,gBAAA,MAAM,QAAQ,GAAG,iBAAiB,CAAC,QAAQ,EAAE;oBAC3C,OAAO,EAAE,aAAa,CAAC,aAAa;oBACpC,IAAI,EAAE,aAAa,CAAC,MAAM;AAC3B,iBAAA,CAAC;gBACF,IAAI,QAAQ,EAAE;AACZ,oBAAA,UAAU,CAAC,QAAQ,CAAC,GAAG,EAAE,aAAa,EAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,IAAI,EAAE;gBACnF;;YAEF;iBAAO;;AAEL,gBAAA,MAAM,OAAO,GAAG,gBAAgB,CAAC,QAAQ,CAAC;AAC1C,gBAAA,UAAU,CAAC,QAAQ,CAAC,GAAG,EAAE,aAAa,EAAE,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,IAAI,EAAE;YACjF;QACF;QAAE,OAAO,KAAK,EAAE;YACd,OAAO;AACL,gBAAA,OAAO,EAAE,KAAK;AACd,gBAAA,KAAK,EAAE,KAAK,YAAY,KAAK,GAAG,KAAK,CAAC,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC;AAC7D,gBAAA,QAAQ,EAAE,QAAQ;aACnB;QACH;IACF;;AAGA,IAAA,MAAM,eAAe,GAAiB;QACpC,CAAC,iBAAiB,GAAG,4BAA4B;AACjD,QAAA,aAAa,EAAE,UAAU;AACzB,QAAA,MAAM,EAAE,YAAY;AACpB,QAAA,gBAAgB,EAAE,iBAAiB;AACnC,QAAA,SAAS,EAAE,UAAU;KACtB;IAED,OAAO;AACL,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,OAAO,EAAE,eAAe;KACzB;AACH;AAEA;;;;;;AAMG;AACG,SAAU,aAAa,CAC3B,OAAqB,EACrB,QAAgB,EAAA;IAEhB,MAAM,WAAW,GAAG,OAAO,CAAC,SAAS,GAAG,QAAQ,CAAC;AACjD,IAAA,IAAI,CAAC,WAAW;AAAE,QAAA,OAAO,SAAS;IAClC,OAAO,WAAW,CAAC,MAAe;AACpC;;;;"}
+{"version":3,"file":"block_storage.js","sources":["../src/block_storage.ts"],"sourcesContent":["/**\n * BlockStorage - Typed storage abstraction for block persistent data.\n *\n * This module provides:\n * - A typed structure for block storage with versioning and plugin support\n * - Utility functions for manipulating storage\n * - Handler interfaces for model-level customization\n *\n * @module block_storage\n */\n\nimport type { Branded } from \"@milaboratories/pl-model-common\";\nimport type { DataMigrationResult, DataVersioned } from \"./block_migrations\";\n\n// =============================================================================\n// Core Types\n// =============================================================================\n\n/**\n * Discriminator key for BlockStorage format detection.\n * This unique hash-based key identifies data as BlockStorage vs legacy formats.\n */\nexport const BLOCK_STORAGE_KEY = \"__pl_a7f3e2b9__\";\n\n/**\n * Current BlockStorage schema version.\n * Increment this when the storage structure itself changes (not block state migrations).\n */\nexport const BLOCK_STORAGE_SCHEMA_VERSION = \"v1\";\n\n/**\n * Default data version for new blocks without migrations.\n * Unique identifier ensures blocks are created via DataModel API.\n */\nexport const DATA_MODEL_DEFAULT_VERSION = \"__pl_v1_d4e8f2a1__\";\n\n/**\n * Type for valid schema versions\n */\nexport type BlockStorageSchemaVersion = \"v1\"; // Add 'v2', 'v3', etc. as schema evolves\n\n/**\n * Branded type for plugin names - globally unique plugin type identifiers.\n * Using a branded type enforces explicit casting (`as PluginName`) which makes\n * it easy to find all plugin name definitions in the codebase and verify uniqueness.\n */\nexport type PluginName = Branded<string, \"PluginName\">;\n\n/**\n * Plugin registry - maps pluginId (unique within a block) to pluginName (globally unique plugin type).\n * Using a Record highlights that pluginIds must be unique within a block.\n */\nexport type PluginRegistry = Record<string, PluginName>;\n\n/**\n * Versioned data - used for both block data and plugin data\n */\nexport interface VersionedData<TData = unknown> {\n  /** Version of the data, used for migrations */\n  __dataVersion: string;\n  /** The persistent data */\n  __data: TData;\n}\n\n/**\n * Core BlockStorage type that holds:\n * - __pl_a7f3e2b9__: Schema version (discriminator key identifies BlockStorage format)\n * - __dataVersion: Version key for block data migrations\n * - __data: The block's user-facing data (state)\n * - __pluginRegistry: Map from pluginId to pluginName (optional)\n * - __plugins: Plugin-specific data keyed by pluginId (optional)\n */\nexport type BlockStorage<TState = unknown> = {\n  /** Schema version - the key itself is the discriminator */\n  readonly [BLOCK_STORAGE_KEY]: BlockStorageSchemaVersion;\n  /** Registry of plugins: pluginId -> pluginName */\n  __pluginRegistry?: PluginRegistry;\n  /** Plugin-specific data, keyed by pluginId */\n  __plugins?: Record<string, VersionedData<unknown>>;\n} & VersionedData<TState>;\n\n/**\n * Type guard to check if a value is a valid BlockStorage object.\n * Checks for the discriminator key and valid schema version.\n */\nexport function isBlockStorage(value: unknown): value is BlockStorage {\n  if (value === null || typeof value !== \"object\") return false;\n  const obj = value as Record<string, unknown>;\n  const schemaVersion = obj[BLOCK_STORAGE_KEY];\n  // Currently only 'v1' is valid, but this allows future versions\n  return schemaVersion === \"v1\"; // Add more versions as schema evolves\n}\n\n// =============================================================================\n// Factory Functions\n// =============================================================================\n\n/**\n * Creates a BlockStorage with the given initial data\n *\n * @param initialData - The initial data value (defaults to empty object)\n * @param version - The initial data version key (defaults to DATA_MODEL_DEFAULT_VERSION)\n * @returns A new BlockStorage instance with discriminator key\n */\nexport function createBlockStorage<TState = unknown>(\n  initialData: TState = {} as TState,\n  version: string = DATA_MODEL_DEFAULT_VERSION,\n): BlockStorage<TState> {\n  return {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: version,\n    __data: initialData,\n    __pluginRegistry: {},\n    __plugins: {},\n  };\n}\n\n/**\n * Normalizes raw storage data to BlockStorage format.\n * If the input is already a BlockStorage, returns it as-is (with defaults for missing fields).\n * If the input is legacy format (raw state), wraps it in BlockStorage structure.\n *\n * @param raw - Raw storage data (may be legacy format or BlockStorage)\n * @returns Normalized BlockStorage\n */\nexport function normalizeBlockStorage<TState = unknown>(raw: unknown): BlockStorage<TState> {\n  if (isBlockStorage(raw)) {\n    const storage = raw as BlockStorage<TState>;\n    return {\n      ...storage,\n      // Fix for early released version where __dataVersion was a number\n      __dataVersion:\n        typeof storage.__dataVersion === \"number\"\n          ? DATA_MODEL_DEFAULT_VERSION\n          : storage.__dataVersion,\n      // Ensure plugin fields have defaults\n      __pluginRegistry: storage.__pluginRegistry ?? {},\n      __plugins: storage.__plugins ?? {},\n    };\n  }\n  // Legacy format: raw is the state directly\n  return createBlockStorage(raw as TState);\n}\n\n// =============================================================================\n// Data Access & Update Functions\n// =============================================================================\n\n/**\n * Gets the data from BlockStorage\n *\n * @param storage - The BlockStorage instance\n * @returns The data value\n */\nexport function getStorageData<TState>(storage: BlockStorage<TState>): TState {\n  return storage.__data;\n}\n\n/**\n * Derives data from raw block storage.\n * This function is meant to be called from sdk/ui-vue to extract\n * user-facing data from the raw storage returned by the middle layer.\n *\n * The middle layer returns raw storage (opaque to it), and the UI\n * uses this function to derive the actual data value.\n *\n * @param rawStorage - Raw storage data from middle layer (may be any format)\n * @returns The extracted data value, or undefined if storage is undefined/null\n */\nexport function deriveDataFromStorage<TData = unknown>(rawStorage: unknown): TData {\n  // Normalize to BlockStorage format (handles legacy formats too)\n  const storage = normalizeBlockStorage<TData>(rawStorage);\n  return getStorageData(storage);\n}\n\n/** Payload for storage mutation operations. SDK defines specific operations. */\nexport type MutateStoragePayload<T = unknown> =\n  | { operation: \"update-block-data\"; value: T }\n  | { operation: \"update-plugin-data\"; pluginId: string; value: unknown };\n\n/**\n * Updates the data in BlockStorage (immutable)\n *\n * @param storage - The current BlockStorage\n * @param payload - The update payload with operation and value\n * @returns A new BlockStorage with updated data\n */\nexport function updateStorageData<TValue = unknown>(\n  storage: BlockStorage<TValue>,\n  payload: MutateStoragePayload<TValue>,\n): BlockStorage<TValue> {\n  switch (payload.operation) {\n    case \"update-block-data\":\n      return { ...storage, __data: payload.value };\n    case \"update-plugin-data\": {\n      const { pluginId, value } = payload;\n      const currentPlugins = storage.__plugins ?? {};\n      const existingEntry = currentPlugins[pluginId];\n      const version = existingEntry?.__dataVersion ?? DATA_MODEL_DEFAULT_VERSION;\n      return {\n        ...storage,\n        __plugins: {\n          ...currentPlugins,\n          [pluginId]: {\n            __dataVersion: version,\n            __data: value,\n          },\n        },\n      };\n    }\n    default:\n      throw new Error(`Unknown storage operation: ${(payload as { operation: string }).operation}`);\n  }\n}\n\n/**\n * Storage debug view returned by __pl_storage_debugView callback.\n * Used by developer tools to display block storage info.\n */\nexport interface StorageDebugView {\n  /** Current data version key */\n  dataVersion: string;\n  /** Raw data payload stored in BlockStorage */\n  data: unknown;\n}\n\n// =============================================================================\n// Atomic Migration\n// =============================================================================\n\n/**\n * Result of a successful atomic migration.\n */\nexport interface MigrationSuccess<TState> {\n  success: true;\n  /** The fully migrated storage - commit this to persist */\n  storage: BlockStorage<TState>;\n}\n\n/**\n * Result of a failed atomic migration.\n * The original storage is untouched - user must choose to abort or reset.\n */\nexport interface MigrationFailure {\n  success: false;\n  /** Description of what failed */\n  error: string;\n  /** Which step failed: 'block' or pluginId */\n  failedAt: string;\n}\n\nexport type MigrationResult<TState> = MigrationSuccess<TState> | MigrationFailure;\n\n/**\n * Configuration for atomic block storage migration.\n * Callbacks use DataVersioned format (the DataModel API format).\n * Conversion to internal VersionedData format is handled by migrateBlockStorage().\n */\nexport interface MigrateBlockStorageConfig {\n  /** Migrate block data from any version to latest */\n  migrateBlockData: (versioned: DataVersioned<unknown>) => DataMigrationResult<unknown>;\n  /** Migrate each plugin's data. Return undefined to remove the plugin. */\n  migratePluginData: (\n    pluginId: string,\n    versioned: DataVersioned<unknown>,\n  ) => DataMigrationResult<unknown> | undefined;\n  /** The new plugin registry after migration (pluginId -> pluginName) */\n  newPluginRegistry: PluginRegistry;\n  /** Factory to create initial data for new plugins */\n  createPluginData: (pluginId: string) => DataVersioned<unknown>;\n}\n\n/**\n * Performs atomic migration of block storage including block data and all plugins.\n *\n * Migration is atomic: either everything succeeds and a new storage is returned,\n * or an error is returned and the original storage is completely untouched.\n *\n * Migration steps:\n * 1. Migrate block data\n * 2. For each plugin in newPluginRegistry:\n *    - If plugin exists with same name: migrate its data\n *    - Otherwise (new or type changed): create with initial data\n *    Plugins not in newPluginRegistry are dropped.\n *\n * If any step throws, migration fails and original storage is preserved.\n * User can then choose to:\n * - Abort: keep original storage, don't update block\n * - Reset: call createBlockStorage() to start fresh\n *\n * @param storage - The original storage (will not be modified)\n * @param config - Migration configuration\n * @returns Migration result - either success with new storage, or failure with error info\n *\n * @example\n * const result = migrateBlockStorage(storage, {\n *   migrateBlockData: (versioned) => blockDataModel.migrate(versioned),\n *   migratePluginData: (pluginId, versioned) => getPluginModel(pluginId).migrate(versioned),\n *   newPluginRegistry: { table1: 'dataTable' as PluginName },\n *   createPluginData: (pluginId) => getPluginModel(pluginId).getDefaultData(),\n * });\n *\n * if (result.success) {\n *   commitStorage(result.storage);\n * } else {\n *   const userChoice = await askUser(`Migration failed: ${result.error}. Reset data?`);\n *   if (userChoice === 'reset') {\n *     commitStorage(createBlockStorage(initialData, currentVersion));\n *   }\n *   // else: abort, keep original\n * }\n */\nexport function migrateBlockStorage(\n  storage: BlockStorage<unknown>,\n  config: MigrateBlockStorageConfig,\n): MigrationResult<unknown> {\n  const { migrateBlockData, migratePluginData, newPluginRegistry, createPluginData } = config;\n\n  // Step 1: Migrate block data\n  let migratedData: unknown;\n  let newVersion: string;\n  try {\n    const result = migrateBlockData({ version: storage.__dataVersion, data: storage.__data });\n    migratedData = result.data;\n    newVersion = result.version;\n  } catch (error) {\n    return {\n      success: false,\n      error: error instanceof Error ? error.message : String(error),\n      failedAt: \"block\",\n    };\n  }\n\n  // Step 2: Migrate plugins\n  const oldPlugins = storage.__plugins ?? {};\n  const oldRegistry = storage.__pluginRegistry ?? {};\n  const newPlugins: Record<string, VersionedData<unknown>> = {};\n\n  for (const [pluginId, pluginName] of Object.entries(newPluginRegistry)) {\n    const existingEntry = oldPlugins[pluginId];\n    const existingName = oldRegistry[pluginId];\n\n    try {\n      if (existingEntry && existingName === pluginName) {\n        // Plugin exists with same type - migrate its data\n        const migrated = migratePluginData(pluginId, {\n          version: existingEntry.__dataVersion,\n          data: existingEntry.__data,\n        });\n        if (migrated) {\n          newPlugins[pluginId] = { __dataVersion: migrated.version, __data: migrated.data };\n        }\n        // If undefined returned, plugin is intentionally removed\n      } else {\n        // New plugin or type changed - create with initial data\n        const initial = createPluginData(pluginId);\n        newPlugins[pluginId] = { __dataVersion: initial.version, __data: initial.data };\n      }\n    } catch (error) {\n      return {\n        success: false,\n        error: error instanceof Error ? error.message : String(error),\n        failedAt: pluginId,\n      };\n    }\n  }\n\n  // Step 3: Build final storage atomically\n  const migratedStorage: BlockStorage = {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: newVersion,\n    __data: migratedData,\n    __pluginRegistry: newPluginRegistry,\n    __plugins: newPlugins,\n  };\n\n  return {\n    success: true,\n    storage: migratedStorage,\n  };\n}\n\n/**\n * Gets plugin-specific data from block storage.\n * Accepts raw storage (any format) and normalizes internally.\n *\n * @param rawStorage - Raw block storage (may be legacy format or BlockStorage)\n * @param pluginId - The plugin instance id\n * @returns The plugin data\n * @throws If pluginId is not found in storage\n */\nexport function getPluginData<TData = unknown>(rawStorage: unknown, pluginId: string): TData {\n  const storage = normalizeBlockStorage(rawStorage);\n  const pluginEntry = storage.__plugins?.[pluginId];\n  if (!pluginEntry) throw new Error(`Plugin '${pluginId}' not found in block storage`);\n  return pluginEntry.__data as TData;\n}\n"],"names":[],"mappings":"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"}

package/dist/index.cjs

@@ -122,7 +122,8 @@ exports.or = actions.or;
 exports.PFrameImpl = pframe.PFrameImpl;
 exports.fromPlOption = ref_util.fromPlOption;
 exports.fromPlRef = ref_util.fromPlRef;
-exports.RenderCtx = api.RenderCtx;
+exports.BlockRenderCtx = api.BlockRenderCtx;
+exports.PluginRenderCtx = api.PluginRenderCtx;
 exports.RenderCtxBase = api.RenderCtxBase;
 exports.RenderCtxLegacy = api.RenderCtxLegacy;
 exports.ResultPool = api.ResultPool;

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

@@ -8,7 +8,6 @@ export type { PluginInstance, ParamsInput } from "./block_model";
 export { DataModel, DataModelBuilder, DataUnrecoverableError, isDataUnrecoverableError, defaultRecover, makeDataVersioned, } from "./block_migrations";
 export type { LegacyV1State } from "./block_migrations";
 export { PluginModel } from "./plugin_model";
-export type { PluginRenderCtx } from "./plugin_model";
 export * from "./bconfig";
 export * from "./components";
 export * from "./config";

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,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,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,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,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,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,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

@@ -16,7 +16,7 @@ export { createPlSelectionModel } from './components/PlSelectionModel.js';
 export { Args, It, MainOutputs, StagingOutputs, UiState, and, extractArchiveAndGetURL, flatten, getBlobContent, getBlobContentAsJson, getBlobContentAsString, getDownloadedBlobContent, getFromCfg, getImmediate, getImportProgress, getJsonField, getLastLogs, getLogHandle, getOnDemandBlobContent, getProgressLog, getProgressLogWithInfo, getResourceField, getResourceValueAsJson, isEmpty, isolate, makeArray, makeObject, mapArrayValues, mapRecordValues, mapResourceFields, not, or } from './config/actions.js';
 export { PFrameImpl } from './pframe.js';
 export { fromPlOption, fromPlRef } from './ref_util.js';
-export { RenderCtx, RenderCtxBase, RenderCtxLegacy, ResultPool } from './render/api.js';
+export { BlockRenderCtx, PluginRenderCtx, RenderCtxBase, RenderCtxLegacy, ResultPool } from './render/api.js';
 export { TreeNodeAccessor, ifDef } from './render/accessor.js';
 export { RT_BINARY_PARTITIONED, RT_BINARY_SUPER_PARTITIONED, RT_JSON_PARTITIONED, RT_JSON_SUPER_PARTITIONED, RT_PARQUET_PARTITIONED, RT_PARQUET_SUPER_PARTITIONED, RT_RESOURCE_MAP, RT_RESOURCE_MAP_PARTITIONED, allPColumnsReady, convertOrParsePColumnData, getPartitionKeysList, getUniquePartitionKeys, isPColumnReady, parsePColumnData, parseResourceMap } from './render/util/pcolumn_data.js';
 export { Trace, TraceEntry, deriveLabels } from './render/util/label.js';

package/dist/package.json.cjs

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

package/dist/package.json.js

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

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 { DataModel } from \"./block_migrations\";\nimport type { PluginName } from \"./block_storage\";\nimport type { ResultPool } from \"./render\";\n\n/** Symbol for internal builder creation method */\nconst FROM_BUILDER = Symbol(\"fromBuilder\");\n\n// =============================================================================\n// Plugin Render Context\n// =============================================================================\n\n/**\n * Context passed to plugin output functions.\n * Provides access to plugin's persistent data, params derived from block context,\n * and the result pool for accessing workflow outputs.\n */\nexport interface PluginRenderCtx<Data, Params = undefined> {\n  /** Plugin's persistent data */\n  readonly data: Data;\n  /** Params derived from block's RenderCtx */\n  readonly params: Params;\n  /** Result pool for accessing workflow outputs */\n  readonly resultPool: ResultPool;\n}\n\n// =============================================================================\n// Plugin Type\n// =============================================================================\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<Data = unknown, Params = undefined, Outputs = {}> {\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: { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] };\n\n  private constructor(input: {\n    name: PluginName;\n    dataModel: DataModel<Data>;\n    outputs: { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] };\n  }) {\n    this.name = input.name;\n    this.dataModel = input.dataModel;\n    this.outputs = input.outputs;\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]<D, P, O>(input: {\n    name: PluginName;\n    dataModel: DataModel<D>;\n    outputs: { [K in keyof O]: (ctx: PluginRenderCtx<D, P>) => O[K] };\n  }): PluginModel<D, P, O> {\n    return new this<D, P, O>(input);\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<MyData, MyParams, MyConfig>({\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<Data, Params = undefined, Config = undefined>(options: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n  }): PluginModelBuilder<Data, Params, Config> {\n    return PluginModelBuilder[FROM_BUILDER]<Data, Params, Config>(options);\n  }\n}\n\n/**\n * Plugin factory returned by PluginModelBuilder.build().\n * Call create() with config to get a configured PluginModel instance.\n */\nclass PluginModelFactory<Data, Params, Config, Outputs> {\n  private readonly name: PluginName;\n  private readonly data: (config?: Config) => DataModel<Data>;\n  private readonly outputs: {\n    [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K];\n  };\n\n  constructor(input: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n    outputs: { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] };\n  }) {\n    this.name = input.name;\n    this.data = input.data;\n    this.outputs = input.outputs;\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    });\n  }\n}\n\n// =============================================================================\n// Plugin Model Builder\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,\n  Params = undefined,\n  Config = undefined,\n  Outputs extends Record<string, unknown> = {},\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<Data, Params>) => Outputs[K];\n  };\n\n  private constructor(input: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n    outputs?: { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] };\n  }) {\n    this.name = input.name;\n    this.data = input.data;\n    this.outputs =\n      input.outputs ??\n      ({} as { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] });\n  }\n\n  /**\n   * Internal method for creating PluginModelBuilder.\n   * Uses Symbol key to prevent external access.\n   * @internal\n   */\n  static [FROM_BUILDER]<D, P, C, O extends Record<string, unknown> = {}>(input: {\n    name: PluginName;\n    data: (config?: C) => DataModel<D>;\n    outputs?: { [K in keyof O]: (ctx: PluginRenderCtx<D, P>) => O[K] };\n  }): PluginModelBuilder<D, P, C, O> {\n    return new this<D, P, C, O>(input);\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<Data, Params>) => T,\n  ): PluginModelBuilder<Data, Params, Config, Outputs & { [K in Key]: T }> {\n    return new PluginModelBuilder<Data, Params, Config, Outputs & { [K in Key]: T }>({\n      name: this.name,\n      data: this.data,\n      outputs: {\n        ...this.outputs,\n        [key]: fn,\n      } as {\n        [K in keyof (Outputs & { [P in Key]: T })]: (\n          ctx: PluginRenderCtx<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(): PluginModelFactory<Data, Params, Config, Outputs> {\n    return new PluginModelFactory<Data, Params, Config, Outputs>({\n      name: this.name,\n      data: this.data,\n      outputs: this.outputs,\n    });\n  }\n}\n"],"names":[],"mappings":";;AAAA;;;;;;;AAOG;AAMH;AACA,MAAM,YAAY,GAAG,MAAM,CAAC,aAAa,CAAC;AAoB1C;AACA;AACA;AAEA;;;AAGG;MACU,WAAW,CAAA;;AAEb,IAAA,IAAI;;AAEJ,IAAA,SAAS;;AAET,IAAA,OAAO;AAEhB,IAAA,WAAA,CAAoB,KAInB,EAAA;AACC,QAAA,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI;AACtB,QAAA,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS;AAChC,QAAA,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO;IAC9B;AAEA;;;;AAIG;AACH,IAAA,QAAQ,YAAY,CAAC,CAAU,KAI9B,EAAA;AACC,QAAA,OAAO,IAAI,IAAI,CAAU,KAAK,CAAC;IACjC;AAEA;;;;;;;;;;;;;;;;AAgBG;IACH,OAAO,MAAM,CAA+C,OAG3D,EAAA;AACC,QAAA,OAAO,kBAAkB,CAAC,YAAY,CAAC,CAAuB,OAAO,CAAC;IACxE;AACD;AAED;;;AAGG;AACH,MAAM,kBAAkB,CAAA;AACL,IAAA,IAAI;AACJ,IAAA,IAAI;AACJ,IAAA,OAAO;AAIxB,IAAA,WAAA,CAAY,KAIX,EAAA;AACC,QAAA,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI;AACtB,QAAA,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI;AACtB,QAAA,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO;IAC9B;;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;AACtB,SAAA,CAAC;IACJ;AACD;AAED;AACA;AACA;AAEA;;;;;;;;;;;;;;;;;;;;;AAqBG;AACH,MAAM,kBAAkB,CAAA;AAML,IAAA,IAAI;AACJ,IAAA,IAAI;AACJ,IAAA,OAAO;AAIxB,IAAA,WAAA,CAAoB,KAInB,EAAA;AACC,QAAA,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI;AACtB,QAAA,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI;AACtB,QAAA,IAAI,CAAC,OAAO;AACV,YAAA,KAAK,CAAC,OAAO;AACZ,gBAAA,EAAmF;IACxF;AAEA;;;;AAIG;AACH,IAAA,QAAQ,YAAY,CAAC,CAAkD,KAItE,EAAA;AACC,QAAA,OAAO,IAAI,IAAI,CAAa,KAAK,CAAC;IACpC;AAEA;;;;;;;;;;AAUG;IACH,MAAM,CACJ,GAAQ,EACR,EAA6C,EAAA;QAE7C,OAAO,IAAI,kBAAkB,CAAoD;YAC/E,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,IAAI,CAAC,IAAI;AACf,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;AACtB,SAAA,CAAC;IACJ;AACD;;;;"}
+{"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 { DataModel } from \"./block_migrations\";\nimport type { PluginName } from \"./block_storage\";\nimport type { PluginRenderCtx } from \"./render\";\n\n/** Symbol for internal builder creation method */\nconst FROM_BUILDER = Symbol(\"fromBuilder\");\n\n// =============================================================================\n// Plugin Type\n// =============================================================================\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<Data = unknown, Params = undefined, Outputs = {}> {\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: { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] };\n\n  private constructor(input: {\n    name: PluginName;\n    dataModel: DataModel<Data>;\n    outputs: { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] };\n  }) {\n    this.name = input.name;\n    this.dataModel = input.dataModel;\n    this.outputs = input.outputs;\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]<D, P, O>(input: {\n    name: PluginName;\n    dataModel: DataModel<D>;\n    outputs: { [K in keyof O]: (ctx: PluginRenderCtx<D, P>) => O[K] };\n  }): PluginModel<D, P, O> {\n    return new this<D, P, O>(input);\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<MyData, MyParams, MyConfig>({\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<Data, Params = undefined, Config = undefined>(options: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n  }): PluginModelBuilder<Data, Params, Config> {\n    return PluginModelBuilder[FROM_BUILDER]<Data, Params, Config>(options);\n  }\n}\n\n/**\n * Plugin factory returned by PluginModelBuilder.build().\n * Call create() with config to get a configured PluginModel instance.\n */\nclass PluginModelFactory<Data, Params, Config, Outputs> {\n  private readonly name: PluginName;\n  private readonly data: (config?: Config) => DataModel<Data>;\n  private readonly outputs: {\n    [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K];\n  };\n\n  constructor(input: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n    outputs: { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] };\n  }) {\n    this.name = input.name;\n    this.data = input.data;\n    this.outputs = input.outputs;\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    });\n  }\n}\n\n// =============================================================================\n// Plugin Model Builder\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,\n  Params = undefined,\n  Config = undefined,\n  Outputs extends Record<string, unknown> = {},\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<Data, Params>) => Outputs[K];\n  };\n\n  private constructor(input: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n    outputs?: { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] };\n  }) {\n    this.name = input.name;\n    this.data = input.data;\n    this.outputs =\n      input.outputs ??\n      ({} as { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] });\n  }\n\n  /**\n   * Internal method for creating PluginModelBuilder.\n   * Uses Symbol key to prevent external access.\n   * @internal\n   */\n  static [FROM_BUILDER]<D, P, C, O extends Record<string, unknown> = {}>(input: {\n    name: PluginName;\n    data: (config?: C) => DataModel<D>;\n    outputs?: { [K in keyof O]: (ctx: PluginRenderCtx<D, P>) => O[K] };\n  }): PluginModelBuilder<D, P, C, O> {\n    return new this<D, P, C, O>(input);\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<Data, Params>) => T,\n  ): PluginModelBuilder<Data, Params, Config, Outputs & { [K in Key]: T }> {\n    return new PluginModelBuilder<Data, Params, Config, Outputs & { [K in Key]: T }>({\n      name: this.name,\n      data: this.data,\n      outputs: {\n        ...this.outputs,\n        [key]: fn,\n      } as {\n        [K in keyof (Outputs & { [P in Key]: T })]: (\n          ctx: PluginRenderCtx<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(): PluginModelFactory<Data, Params, Config, Outputs> {\n    return new PluginModelFactory<Data, Params, Config, Outputs>({\n      name: this.name,\n      data: this.data,\n      outputs: this.outputs,\n    });\n  }\n}\n"],"names":[],"mappings":";;AAAA;;;;;;;AAOG;AAMH;AACA,MAAM,YAAY,GAAG,MAAM,CAAC,aAAa,CAAC;AAE1C;AACA;AACA;AAEA;;;AAGG;MACU,WAAW,CAAA;;AAEb,IAAA,IAAI;;AAEJ,IAAA,SAAS;;AAET,IAAA,OAAO;AAEhB,IAAA,WAAA,CAAoB,KAInB,EAAA;AACC,QAAA,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI;AACtB,QAAA,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS;AAChC,QAAA,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO;IAC9B;AAEA;;;;AAIG;AACH,IAAA,QAAQ,YAAY,CAAC,CAAU,KAI9B,EAAA;AACC,QAAA,OAAO,IAAI,IAAI,CAAU,KAAK,CAAC;IACjC;AAEA;;;;;;;;;;;;;;;;AAgBG;IACH,OAAO,MAAM,CAA+C,OAG3D,EAAA;AACC,QAAA,OAAO,kBAAkB,CAAC,YAAY,CAAC,CAAuB,OAAO,CAAC;IACxE;AACD;AAED;;;AAGG;AACH,MAAM,kBAAkB,CAAA;AACL,IAAA,IAAI;AACJ,IAAA,IAAI;AACJ,IAAA,OAAO;AAIxB,IAAA,WAAA,CAAY,KAIX,EAAA;AACC,QAAA,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI;AACtB,QAAA,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI;AACtB,QAAA,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO;IAC9B;;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;AACtB,SAAA,CAAC;IACJ;AACD;AAED;AACA;AACA;AAEA;;;;;;;;;;;;;;;;;;;;;AAqBG;AACH,MAAM,kBAAkB,CAAA;AAML,IAAA,IAAI;AACJ,IAAA,IAAI;AACJ,IAAA,OAAO;AAIxB,IAAA,WAAA,CAAoB,KAInB,EAAA;AACC,QAAA,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI;AACtB,QAAA,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI;AACtB,QAAA,IAAI,CAAC,OAAO;AACV,YAAA,KAAK,CAAC,OAAO;AACZ,gBAAA,EAAmF;IACxF;AAEA;;;;AAIG;AACH,IAAA,QAAQ,YAAY,CAAC,CAAkD,KAItE,EAAA;AACC,QAAA,OAAO,IAAI,IAAI,CAAa,KAAK,CAAC;IACpC;AAEA;;;;;;;;;;AAUG;IACH,MAAM,CACJ,GAAQ,EACR,EAA6C,EAAA;QAE7C,OAAO,IAAI,kBAAkB,CAAoD;YAC/E,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,IAAI,CAAC,IAAI;AACf,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;AACtB,SAAA,CAAC;IACJ;AACD;;;;"}

package/dist/plugin_model.d.ts

@@ -8,22 +8,9 @@
  */
 import type { DataModel } from "./block_migrations";
 import type { PluginName } from "./block_storage";
-import type { ResultPool } from "./render";
+import type { PluginRenderCtx } from "./render";
 /** Symbol for internal builder creation method */
 declare const FROM_BUILDER: unique symbol;
-/**
- * Context passed to plugin output functions.
- * Provides access to plugin's persistent data, params derived from block context,
- * and the result pool for accessing workflow outputs.
- */
-export interface PluginRenderCtx<Data, Params = undefined> {
-    /** Plugin's persistent data */
-    readonly data: Data;
-    /** Params derived from block's RenderCtx */
-    readonly params: Params;
-    /** Result pool for accessing workflow outputs */
-    readonly resultPool: ResultPool;
-}
 /**
  * Configured plugin instance returned by PluginModelFactory.create().
  * Contains the plugin's name, data model, and output definitions.

package/dist/plugin_model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin_model.d.ts","sourceRoot":"","sources":["../src/plugin_model.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"plugin_model.d.ts","sourceRoot":"","sources":["../src/plugin_model.ts"],"names":[],"mappings":"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"}

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 { DataModel } from \"./block_migrations\";\nimport type { PluginName } from \"./block_storage\";\nimport type { ResultPool } from \"./render\";\n\n/** Symbol for internal builder creation method */\nconst FROM_BUILDER = Symbol(\"fromBuilder\");\n\n// =============================================================================\n// Plugin Render Context\n// =============================================================================\n\n/**\n * Context passed to plugin output functions.\n * Provides access to plugin's persistent data, params derived from block context,\n * and the result pool for accessing workflow outputs.\n */\nexport interface PluginRenderCtx<Data, Params = undefined> {\n  /** Plugin's persistent data */\n  readonly data: Data;\n  /** Params derived from block's RenderCtx */\n  readonly params: Params;\n  /** Result pool for accessing workflow outputs */\n  readonly resultPool: ResultPool;\n}\n\n// =============================================================================\n// Plugin Type\n// =============================================================================\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<Data = unknown, Params = undefined, Outputs = {}> {\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: { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] };\n\n  private constructor(input: {\n    name: PluginName;\n    dataModel: DataModel<Data>;\n    outputs: { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] };\n  }) {\n    this.name = input.name;\n    this.dataModel = input.dataModel;\n    this.outputs = input.outputs;\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]<D, P, O>(input: {\n    name: PluginName;\n    dataModel: DataModel<D>;\n    outputs: { [K in keyof O]: (ctx: PluginRenderCtx<D, P>) => O[K] };\n  }): PluginModel<D, P, O> {\n    return new this<D, P, O>(input);\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<MyData, MyParams, MyConfig>({\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<Data, Params = undefined, Config = undefined>(options: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n  }): PluginModelBuilder<Data, Params, Config> {\n    return PluginModelBuilder[FROM_BUILDER]<Data, Params, Config>(options);\n  }\n}\n\n/**\n * Plugin factory returned by PluginModelBuilder.build().\n * Call create() with config to get a configured PluginModel instance.\n */\nclass PluginModelFactory<Data, Params, Config, Outputs> {\n  private readonly name: PluginName;\n  private readonly data: (config?: Config) => DataModel<Data>;\n  private readonly outputs: {\n    [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K];\n  };\n\n  constructor(input: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n    outputs: { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] };\n  }) {\n    this.name = input.name;\n    this.data = input.data;\n    this.outputs = input.outputs;\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    });\n  }\n}\n\n// =============================================================================\n// Plugin Model Builder\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,\n  Params = undefined,\n  Config = undefined,\n  Outputs extends Record<string, unknown> = {},\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<Data, Params>) => Outputs[K];\n  };\n\n  private constructor(input: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n    outputs?: { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] };\n  }) {\n    this.name = input.name;\n    this.data = input.data;\n    this.outputs =\n      input.outputs ??\n      ({} as { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] });\n  }\n\n  /**\n   * Internal method for creating PluginModelBuilder.\n   * Uses Symbol key to prevent external access.\n   * @internal\n   */\n  static [FROM_BUILDER]<D, P, C, O extends Record<string, unknown> = {}>(input: {\n    name: PluginName;\n    data: (config?: C) => DataModel<D>;\n    outputs?: { [K in keyof O]: (ctx: PluginRenderCtx<D, P>) => O[K] };\n  }): PluginModelBuilder<D, P, C, O> {\n    return new this<D, P, C, O>(input);\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<Data, Params>) => T,\n  ): PluginModelBuilder<Data, Params, Config, Outputs & { [K in Key]: T }> {\n    return new PluginModelBuilder<Data, Params, Config, Outputs & { [K in Key]: T }>({\n      name: this.name,\n      data: this.data,\n      outputs: {\n        ...this.outputs,\n        [key]: fn,\n      } as {\n        [K in keyof (Outputs & { [P in Key]: T })]: (\n          ctx: PluginRenderCtx<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(): PluginModelFactory<Data, Params, Config, Outputs> {\n    return new PluginModelFactory<Data, Params, Config, Outputs>({\n      name: this.name,\n      data: this.data,\n      outputs: this.outputs,\n    });\n  }\n}\n"],"names":[],"mappings":"AAAA;;;;;;;AAOG;AAMH;AACA,MAAM,YAAY,GAAG,MAAM,CAAC,aAAa,CAAC;AAoB1C;AACA;AACA;AAEA;;;AAGG;MACU,WAAW,CAAA;;AAEb,IAAA,IAAI;;AAEJ,IAAA,SAAS;;AAET,IAAA,OAAO;AAEhB,IAAA,WAAA,CAAoB,KAInB,EAAA;AACC,QAAA,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI;AACtB,QAAA,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS;AAChC,QAAA,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO;IAC9B;AAEA;;;;AAIG;AACH,IAAA,QAAQ,YAAY,CAAC,CAAU,KAI9B,EAAA;AACC,QAAA,OAAO,IAAI,IAAI,CAAU,KAAK,CAAC;IACjC;AAEA;;;;;;;;;;;;;;;;AAgBG;IACH,OAAO,MAAM,CAA+C,OAG3D,EAAA;AACC,QAAA,OAAO,kBAAkB,CAAC,YAAY,CAAC,CAAuB,OAAO,CAAC;IACxE;AACD;AAED;;;AAGG;AACH,MAAM,kBAAkB,CAAA;AACL,IAAA,IAAI;AACJ,IAAA,IAAI;AACJ,IAAA,OAAO;AAIxB,IAAA,WAAA,CAAY,KAIX,EAAA;AACC,QAAA,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI;AACtB,QAAA,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI;AACtB,QAAA,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO;IAC9B;;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;AACtB,SAAA,CAAC;IACJ;AACD;AAED;AACA;AACA;AAEA;;;;;;;;;;;;;;;;;;;;;AAqBG;AACH,MAAM,kBAAkB,CAAA;AAML,IAAA,IAAI;AACJ,IAAA,IAAI;AACJ,IAAA,OAAO;AAIxB,IAAA,WAAA,CAAoB,KAInB,EAAA;AACC,QAAA,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI;AACtB,QAAA,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI;AACtB,QAAA,IAAI,CAAC,OAAO;AACV,YAAA,KAAK,CAAC,OAAO;AACZ,gBAAA,EAAmF;IACxF;AAEA;;;;AAIG;AACH,IAAA,QAAQ,YAAY,CAAC,CAAkD,KAItE,EAAA;AACC,QAAA,OAAO,IAAI,IAAI,CAAa,KAAK,CAAC;IACpC;AAEA;;;;;;;;;;AAUG;IACH,MAAM,CACJ,GAAQ,EACR,EAA6C,EAAA;QAE7C,OAAO,IAAI,kBAAkB,CAAoD;YAC/E,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,IAAI,CAAC,IAAI;AACf,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;AACtB,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 { DataModel } from \"./block_migrations\";\nimport type { PluginName } from \"./block_storage\";\nimport type { PluginRenderCtx } from \"./render\";\n\n/** Symbol for internal builder creation method */\nconst FROM_BUILDER = Symbol(\"fromBuilder\");\n\n// =============================================================================\n// Plugin Type\n// =============================================================================\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<Data = unknown, Params = undefined, Outputs = {}> {\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: { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] };\n\n  private constructor(input: {\n    name: PluginName;\n    dataModel: DataModel<Data>;\n    outputs: { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] };\n  }) {\n    this.name = input.name;\n    this.dataModel = input.dataModel;\n    this.outputs = input.outputs;\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]<D, P, O>(input: {\n    name: PluginName;\n    dataModel: DataModel<D>;\n    outputs: { [K in keyof O]: (ctx: PluginRenderCtx<D, P>) => O[K] };\n  }): PluginModel<D, P, O> {\n    return new this<D, P, O>(input);\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<MyData, MyParams, MyConfig>({\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<Data, Params = undefined, Config = undefined>(options: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n  }): PluginModelBuilder<Data, Params, Config> {\n    return PluginModelBuilder[FROM_BUILDER]<Data, Params, Config>(options);\n  }\n}\n\n/**\n * Plugin factory returned by PluginModelBuilder.build().\n * Call create() with config to get a configured PluginModel instance.\n */\nclass PluginModelFactory<Data, Params, Config, Outputs> {\n  private readonly name: PluginName;\n  private readonly data: (config?: Config) => DataModel<Data>;\n  private readonly outputs: {\n    [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K];\n  };\n\n  constructor(input: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n    outputs: { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] };\n  }) {\n    this.name = input.name;\n    this.data = input.data;\n    this.outputs = input.outputs;\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    });\n  }\n}\n\n// =============================================================================\n// Plugin Model Builder\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,\n  Params = undefined,\n  Config = undefined,\n  Outputs extends Record<string, unknown> = {},\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<Data, Params>) => Outputs[K];\n  };\n\n  private constructor(input: {\n    name: PluginName;\n    data: (config?: Config) => DataModel<Data>;\n    outputs?: { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] };\n  }) {\n    this.name = input.name;\n    this.data = input.data;\n    this.outputs =\n      input.outputs ??\n      ({} as { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] });\n  }\n\n  /**\n   * Internal method for creating PluginModelBuilder.\n   * Uses Symbol key to prevent external access.\n   * @internal\n   */\n  static [FROM_BUILDER]<D, P, C, O extends Record<string, unknown> = {}>(input: {\n    name: PluginName;\n    data: (config?: C) => DataModel<D>;\n    outputs?: { [K in keyof O]: (ctx: PluginRenderCtx<D, P>) => O[K] };\n  }): PluginModelBuilder<D, P, C, O> {\n    return new this<D, P, C, O>(input);\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<Data, Params>) => T,\n  ): PluginModelBuilder<Data, Params, Config, Outputs & { [K in Key]: T }> {\n    return new PluginModelBuilder<Data, Params, Config, Outputs & { [K in Key]: T }>({\n      name: this.name,\n      data: this.data,\n      outputs: {\n        ...this.outputs,\n        [key]: fn,\n      } as {\n        [K in keyof (Outputs & { [P in Key]: T })]: (\n          ctx: PluginRenderCtx<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(): PluginModelFactory<Data, Params, Config, Outputs> {\n    return new PluginModelFactory<Data, Params, Config, Outputs>({\n      name: this.name,\n      data: this.data,\n      outputs: this.outputs,\n    });\n  }\n}\n"],"names":[],"mappings":"AAAA;;;;;;;AAOG;AAMH;AACA,MAAM,YAAY,GAAG,MAAM,CAAC,aAAa,CAAC;AAE1C;AACA;AACA;AAEA;;;AAGG;MACU,WAAW,CAAA;;AAEb,IAAA,IAAI;;AAEJ,IAAA,SAAS;;AAET,IAAA,OAAO;AAEhB,IAAA,WAAA,CAAoB,KAInB,EAAA;AACC,QAAA,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI;AACtB,QAAA,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS;AAChC,QAAA,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO;IAC9B;AAEA;;;;AAIG;AACH,IAAA,QAAQ,YAAY,CAAC,CAAU,KAI9B,EAAA;AACC,QAAA,OAAO,IAAI,IAAI,CAAU,KAAK,CAAC;IACjC;AAEA;;;;;;;;;;;;;;;;AAgBG;IACH,OAAO,MAAM,CAA+C,OAG3D,EAAA;AACC,QAAA,OAAO,kBAAkB,CAAC,YAAY,CAAC,CAAuB,OAAO,CAAC;IACxE;AACD;AAED;;;AAGG;AACH,MAAM,kBAAkB,CAAA;AACL,IAAA,IAAI;AACJ,IAAA,IAAI;AACJ,IAAA,OAAO;AAIxB,IAAA,WAAA,CAAY,KAIX,EAAA;AACC,QAAA,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI;AACtB,QAAA,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI;AACtB,QAAA,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO;IAC9B;;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;AACtB,SAAA,CAAC;IACJ;AACD;AAED;AACA;AACA;AAEA;;;;;;;;;;;;;;;;;;;;;AAqBG;AACH,MAAM,kBAAkB,CAAA;AAML,IAAA,IAAI;AACJ,IAAA,IAAI;AACJ,IAAA,OAAO;AAIxB,IAAA,WAAA,CAAoB,KAInB,EAAA;AACC,QAAA,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI;AACtB,QAAA,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI;AACtB,QAAA,IAAI,CAAC,OAAO;AACV,YAAA,KAAK,CAAC,OAAO;AACZ,gBAAA,EAAmF;IACxF;AAEA;;;;AAIG;AACH,IAAA,QAAQ,YAAY,CAAC,CAAkD,KAItE,EAAA;AACC,QAAA,OAAO,IAAI,IAAI,CAAa,KAAK,CAAC;IACpC;AAEA;;;;;;;;;;AAUG;IACH,MAAM,CACJ,GAAQ,EACR,EAA6C,EAAA;QAE7C,OAAO,IAAI,kBAAkB,CAAoD;YAC/E,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,IAAI,CAAC,IAAI;AACf,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;AACtB,SAAA,CAAC;IACJ;AACD;;;;"}

package/dist/render/api.cjs

@@ -3,6 +3,7 @@
 var plModelCommon = require('@milaboratories/pl-model-common');
 var canonicalize = require('canonicalize');
 var internal = require('../internal.cjs');
+var block_storage = require('../block_storage.cjs');
 var accessor = require('./accessor.cjs');
 var internal$1 = require('./internal.cjs');
 var column_collection = require('./util/column_collection.cjs');
@@ -513,7 +514,7 @@ class RenderCtxBase {
     }
 }
 /** Main entry point to the API available within model lambdas (like outputs, sections, etc..) for v3+ blocks */
-class RenderCtx extends RenderCtxBase {
+class BlockRenderCtx extends RenderCtxBase {
     argsCache;
     get args() {
         if (this.argsCache === undefined) {
@@ -545,8 +546,47 @@ class RenderCtxLegacy extends RenderCtxBase {
         return this.uiStateCache.v;
     }
 }
+/**
+ * Render context for plugin output functions.
+ * Reads plugin data from blockStorage and derives params from pre-wrapped input callbacks.
+ */
+class PluginRenderCtx {
+    ctx;
+    pluginId;
+    wrappedInputs;
+    constructor(pluginId, wrappedInputs) {
+        this.ctx = internal.getCfgRenderCtx();
+        this.pluginId = pluginId;
+        this.wrappedInputs = wrappedInputs;
+    }
+    dataCache;
+    /** Plugin's persistent data from blockStorage.__plugins.{pluginId}.__data */
+    get data() {
+        if (this.dataCache === undefined) {
+            const raw = this.ctx.blockStorage();
+            const pluginData = block_storage.getPluginData(plModelCommon.parseJson(raw), this.pluginId);
+            this.dataCache = { v: pluginData };
+        }
+        return this.dataCache.v;
+    }
+    paramsCache;
+    /** Params derived from block context via pre-wrapped input callbacks */
+    get params() {
+        if (this.paramsCache === undefined) {
+            const result = {};
+            for (const [key, fn] of Object.entries(this.wrappedInputs)) {
+                result[key] = fn();
+            }
+            this.paramsCache = { v: result };
+        }
+        return this.paramsCache.v;
+    }
+    /** Result pool — same as block, from cfgRenderCtx methods */
+    resultPool = new ResultPool();
+}
 
-exports.RenderCtx = RenderCtx;
+exports.BlockRenderCtx = BlockRenderCtx;
+exports.PluginRenderCtx = PluginRenderCtx;
 exports.RenderCtxBase = RenderCtxBase;
 exports.RenderCtxLegacy = RenderCtxLegacy;
 exports.ResultPool = ResultPool;