@platforma-sdk/model 1.51.9 → 1.52.3

package/src/block_storage_vm.ts

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

package/src/builder.ts

@@ -1,24 +1,24 @@
-import type { BlockRenderingMode, BlockSection, AnyFunction, PlRef, BlockCodeKnownFeatureFlags, BlockConfigContainer, OutputWithStatus } from '@milaboratories/pl-model-common';
+import type { BlockRenderingMode, BlockSection, AnyFunction, PlRef, BlockCodeKnownFeatureFlags, BlockConfigContainer } from '@milaboratories/pl-model-common';
 import type { Checked, ConfigResult, TypedConfig } from './config';
 import { getImmediate } from './config';
 import { getPlatformaInstance, isInUI, tryRegisterCallback } from './internal';
 import type { Platforma, PlatformaApiVersion, PlatformaV1, PlatformaV2 } from './platforma';
-import type { InferRenderFunctionReturn, RenderFunction } from './render';
-import { RenderCtx } from './render';
+import type { InferRenderFunctionReturn, RenderFunctionLegacy } from './render';
+import { RenderCtxLegacy } from './render';
 import { PlatformaSDKVersion } from './version';
 import type {
   TypedConfigOrConfigLambda,
   ConfigRenderLambda,
   StdCtxArgsOnly,
   DeriveHref,
-  ResolveCfgType,
-  ExtractFunctionHandleReturn,
   ConfigRenderLambdaFlags,
+  InferOutputsFromConfigs,
 } from './bconfig';
 import {
   downgradeCfgOrLambda,
   isConfigLambda,
 } from './bconfig';
+import type { PlatformaExtended } from './platforma';
 
 type SectionsExpectedType = readonly BlockSection[];
 
@@ -27,12 +27,6 @@ type SectionsCfgChecked<Cfg extends TypedConfig, Args, UiState> = Checked<
   ConfigResult<Cfg, StdCtxArgsOnly<Args, UiState>> extends SectionsExpectedType ? true : false
 >;
 
-// TODO (Unused type in code)
-// type SectionsRFChecked<RF extends Function> = Checked<
-//   RF,
-//   InferRenderFunctionReturn<RF> extends SectionsExpectedType ? true : false
-// >;
-
 type InputsValidExpectedType = boolean;
 
 type InputsValidCfgChecked<Cfg extends TypedConfig, Args, UiState> = Checked<
@@ -40,12 +34,6 @@ type InputsValidCfgChecked<Cfg extends TypedConfig, Args, UiState> = Checked<
   ConfigResult<Cfg, StdCtxArgsOnly<Args, UiState>> extends InputsValidExpectedType ? true : false
 >;
 
-// TODO (Unused type in code)
-// type InputsValidRFChecked<RF extends Function> = Checked<
-//   RF,
-//   InferRenderFunctionReturn<RF> extends InputsValidExpectedType ? true : false
-// >;
-
 type NoOb = Record<string, never>;
 
 /** Main entry point that each block should use in it's "config" module. Don't forget
@@ -126,7 +114,7 @@ export class BlockModel<
    *            workflows outputs and interact with platforma drivers
    * @param flags additional flags that may alter lambda rendering procedure
    * */
-  public output<const Key extends string, const RF extends RenderFunction<Args, UiState>>(
+  public output<const Key extends string, const RF extends RenderFunctionLegacy<Args, UiState>>(
     key: Key,
     rf: RF,
     flags: ConfigRenderLambdaFlags & { withStatus: true }
@@ -144,7 +132,7 @@ export class BlockModel<
    *            workflows outputs and interact with platforma drivers
    * @param flags additional flags that may alter lambda rendering procedure
    * */
-  public output<const Key extends string, const RF extends RenderFunction<Args, UiState>>(
+  public output<const Key extends string, const RF extends RenderFunctionLegacy<Args, UiState>>(
     key: Key,
     rf: RF,
     flags?: ConfigRenderLambdaFlags
@@ -161,7 +149,7 @@ export class BlockModel<
   ): BlockModel<Args, OutputsCfg, UiState, Href> {
     if (typeof cfgOrRf === 'function') {
       const handle = `output#${key}`;
-      tryRegisterCallback(handle, () => cfgOrRf(new RenderCtx()));
+      tryRegisterCallback(handle, () => cfgOrRf(new RenderCtxLegacy()));
       return new BlockModel({
         ...this.config,
         outputs: {
@@ -185,7 +173,7 @@ export class BlockModel<
   }
 
   /** Shortcut for {@link output} with retentive flag set to true. */
-  public retentiveOutput<const Key extends string, const RF extends RenderFunction<Args, UiState>>(
+  public retentiveOutput<const Key extends string, const RF extends RenderFunctionLegacy<Args, UiState>>(
     key: Key,
     rf: RF,
   ) {
@@ -193,7 +181,7 @@ export class BlockModel<
   }
 
   /** Shortcut for {@link output} with withStatus flag set to true. */
-  public outputWithStatus<const Key extends string, const RF extends RenderFunction<Args, UiState>>(
+  public outputWithStatus<const Key extends string, const RF extends RenderFunctionLegacy<Args, UiState>>(
     key: Key,
     rf: RF,
   ) {
@@ -201,7 +189,7 @@ export class BlockModel<
   }
 
   /** Shortcut for {@link output} with retentive and withStatus flags set to true. */
-  public retentiveOutputWithStatus<const Key extends string, const RF extends RenderFunction<Args, UiState>>(
+  public retentiveOutputWithStatus<const Key extends string, const RF extends RenderFunctionLegacy<Args, UiState>>(
     key: Key,
     rf: RF,
   ) {
@@ -214,14 +202,14 @@ export class BlockModel<
     cfg: Cfg & InputsValidCfgChecked<Cfg, Args, UiState>
   ): BlockModel<Args, OutputsCfg, UiState, Href>;
   /** Sets custom configuration predicate on the block args at which block can be executed */
-  public argsValid<RF extends RenderFunction<Args, UiState, boolean>>(
+  public argsValid<RF extends RenderFunctionLegacy<Args, UiState, boolean>>(
     rf: RF
   ): BlockModel<Args, OutputsCfg, UiState, Href>;
   public argsValid(
     cfgOrRf: TypedConfig | AnyFunction,
   ): BlockModel<Args, OutputsCfg, UiState, `/${string}`> {
     if (typeof cfgOrRf === 'function') {
-      tryRegisterCallback('inputsValid', () => cfgOrRf(new RenderCtx()));
+      tryRegisterCallback('inputsValid', () => cfgOrRf(new RenderCtxLegacy()));
       return new BlockModel<Args, OutputsCfg, UiState>({
         ...this.config,
         inputsValid: {
@@ -245,7 +233,7 @@ export class BlockModel<
   /** Sets the config to generate list of section in the left block overviews panel */
   public sections<
     const Ret extends SectionsExpectedType,
-    const RF extends RenderFunction<Args, UiState, Ret>,
+    const RF extends RenderFunctionLegacy<Args, UiState, Ret>,
   >(rf: RF): BlockModel<Args, OutputsCfg, UiState, DeriveHref<ReturnType<RF>>>;
   public sections<const Cfg extends TypedConfig>(
     cfg: Cfg & SectionsCfgChecked<Cfg, Args, UiState>
@@ -261,7 +249,7 @@ export class BlockModel<
     if (Array.isArray(arrOrCfgOrRf)) {
       return this.sections(getImmediate(arrOrCfgOrRf));
     } else if (typeof arrOrCfgOrRf === 'function') {
-      tryRegisterCallback('sections', () => arrOrCfgOrRf(new RenderCtx()));
+      tryRegisterCallback('sections', () => arrOrCfgOrRf(new RenderCtxLegacy()));
       return new BlockModel<Args, OutputsCfg, UiState>({
         ...this.config,
         sections: {
@@ -279,9 +267,9 @@ export class BlockModel<
 
   /** Sets a rendering function to derive block title, shown for the block in the left blocks-overview panel. */
   public title(
-    rf: RenderFunction<Args, UiState, string>,
+    rf: RenderFunctionLegacy<Args, UiState, string>,
   ): BlockModel<Args, OutputsCfg, UiState, Href> {
-    tryRegisterCallback('title', () => rf(new RenderCtx()));
+    tryRegisterCallback('title', () => rf(new RenderCtxLegacy()));
     return new BlockModel<Args, OutputsCfg, UiState, Href>({
       ...this.config,
       title: {
@@ -292,9 +280,9 @@ export class BlockModel<
   }
 
   public subtitle(
-    rf: RenderFunction<Args, UiState, string>,
+    rf: RenderFunctionLegacy<Args, UiState, string>,
   ): BlockModel<Args, OutputsCfg, UiState, Href> {
-    tryRegisterCallback('subtitle', () => rf(new RenderCtx()));
+    tryRegisterCallback('subtitle', () => rf(new RenderCtxLegacy()));
     return new BlockModel<Args, OutputsCfg, UiState, Href>({
       ...this.config,
       subtitle: {
@@ -305,9 +293,9 @@ export class BlockModel<
   }
 
   public tags(
-    rf: RenderFunction<Args, UiState, string[]>,
+    rf: RenderFunctionLegacy<Args, UiState, string[]>,
   ): BlockModel<Args, OutputsCfg, UiState, Href> {
-    tryRegisterCallback('tags', () => rf(new RenderCtx()));
+    tryRegisterCallback('tags', () => rf(new RenderCtxLegacy()));
     return new BlockModel<Args, OutputsCfg, UiState, Href>({
       ...this.config,
       tags: {
@@ -407,7 +395,10 @@ export class BlockModel<
     if (this.config.initialArgs === undefined) throw new Error('Initial arguments not set.');
 
     const config: BlockConfigContainer = {
+      v4: undefined,
       v3: {
+        configVersion: 3,
+        modelAPIVersion: 1,
         sdkVersion: PlatformaSDKVersion,
         renderingMode: this.config.renderingMode,
         initialArgs: this.config.initialArgs,
@@ -452,29 +443,3 @@ export class BlockModel<
     };
   }
 }
-
-export type InferOutputType<CfgOrFH, Args, UiState> = CfgOrFH extends TypedConfig
-  ? ResolveCfgType<CfgOrFH, Args, UiState>
-  : CfgOrFH extends ConfigRenderLambda
-    ? ExtractFunctionHandleReturn<CfgOrFH>
-    : never;
-
-type InferOutputsFromConfigs<
-  Args,
-  OutputsCfg extends Record<string, TypedConfigOrConfigLambda>,
-  UiState,
-> = {
-  [Key in keyof OutputsCfg]:
-    & OutputWithStatus<InferOutputType<OutputsCfg[Key], Args, UiState>>
-    & { __unwrap: (OutputsCfg[Key] extends { withStatus: true } ? false : true) };
-};
-
-export type PlatformaExtended<Pl extends Platforma = Platforma> = Pl & {
-  blockModelInfo: BlockModelInfo;
-};
-
-export type BlockModelInfo = {
-  outputs: Record<string, {
-    withStatus: boolean;
-  }>;
-};

package/src/components/PFrameForGraphs.ts

@@ -17,7 +17,7 @@ import {
   readAnnotationJson,
   stringifyJson,
 } from '@milaboratories/pl-model-common';
-import type { PColumnDataUniversal, PColumnEntryUniversal, PColumnEntryWithLabel, RenderCtx } from '../render';
+import type { PColumnDataUniversal, PColumnEntryUniversal, PColumnEntryWithLabel, RenderCtxBase } from '../render';
 import { getAllRelatedColumns, getRelatedColumns } from '../pframe_utils/columns';
 
 /** Create id for column copy with added keys in axes domains */
@@ -179,7 +179,7 @@ function getAdditionalColumnsForColumn<T extends Omit<PColumn<PColumnDataUnivers
  and modified label (with added domain values in case if more than one copy with different domains exist).
  */
 export function createPFrameForGraphs<A, U>(
-  ctx: RenderCtx<A, U>,
+  ctx: RenderCtxBase<A, U>,
   blockColumns?: PColumn<PColumnDataUniversal>[],
 ): PFrameHandle | undefined {
   const suitableSpec = (spec: PColumnSpec) => !isHiddenFromUIColumn(spec) && !isHiddenFromGraphColumn(spec);

package/src/components/PlDataTable.ts

@@ -34,7 +34,7 @@ import type {
   AxisLabelProvider,
   ColumnProvider,
   PColumnDataUniversal,
-  RenderCtx,
+  RenderCtxBase,
   TreeNodeAccessor,
 } from '../render';
 import {
@@ -631,7 +631,7 @@ export function isColumnOptional(spec: { annotations?: Annotation }): boolean {
  * @returns PlAgDataTableV2 table source
  */
 export function createPlDataTableV2<A, U>(
-  ctx: RenderCtx<A, U>,
+  ctx: RenderCtxBase<A, U>,
   columns: PColumn<PColumnDataUniversal>[],
   tableState: PlDataTableStateV2 | undefined,
   ops?: CreatePlDataTableOps,
@@ -765,7 +765,7 @@ export function createPlDataTableV2<A, U>(
 
 /** Create sheet entries for PlDataTable */
 export function createPlDataTableSheet<A, U>(
-  ctx: RenderCtx<A, U>,
+  ctx: RenderCtxBase<A, U>,
   axis: AxisSpec,
   values: (string | number)[],
 ): PlDataTableSheet {

package/src/index.ts

@@ -1,6 +1,9 @@
 export * from './block_state_patch';
 export * from './block_state_util';
+export * from './block_storage';
 export * from './builder';
+export { BlockModelV3 } from './block_model';
+export { DataModel } from './block_migrations';
 export * from './bconfig';
 export * from './components';
 export * from './config';

package/src/internal.ts

@@ -2,6 +2,7 @@ import type { OutputWithStatus } from '@milaboratories/pl-model-common';
 import { } from './global';
 import type { Platforma, PlatformaApiVersion } from './platforma';
 import type { FutureHandle, GlobalCfgRenderCtx } from './render/internal';
+import type { ConfigRenderLambda, ConfigRenderLambdaFlags } from './bconfig';
 
 /** Utility code helping to identify whether the code is running in actual UI environment */
 export function isInUI() {
@@ -41,6 +42,56 @@ export function tryRegisterCallback(key: string, callback: (...args: any[]) => a
   return true;
 }
 
+/**
+ * Registers a callback, replacing any existing callback with the same key.
+ * Use this for callbacks that have a default value but can be overridden.
+ *
+ * @param key - The callback registry key
+ * @param callback - The callback function to register
+ * @returns true if registered, false if not in render context
+ */
+export function replaceCallback(key: string, callback: (...args: any[]) => any): boolean {
+  const ctx = tryGetCfgRenderCtx();
+  if (ctx === undefined) return false;
+  ctx.callbackRegistry[key] = callback;
+  return true;
+}
+
+//
+// ConfigRenderLambda helpers
+//
+
+/** Options for creating a ConfigRenderLambda descriptor */
+export type CreateLambdaOptions = ConfigRenderLambdaFlags & {
+  /** The callback registry key */
+  handle: string;
+};
+
+/** Creates a ConfigRenderLambda descriptor without registering a callback. */
+export function createRenderLambda<T = unknown>(opts: CreateLambdaOptions): ConfigRenderLambda<T> {
+  const { handle, ...flags } = opts;
+  return {
+    __renderLambda: true,
+    handle,
+    ...flags,
+  } as ConfigRenderLambda<T>;
+}
+
+/** Registers a callback and returns a ConfigRenderLambda descriptor. */
+export function createAndRegisterRenderLambda<T = unknown>(opts: CreateLambdaOptions & {
+  lambda: (...args: any[]) => any;
+}, replace?: boolean): ConfigRenderLambda<T> {
+  const { handle, lambda, ...flags } = opts;
+
+  if (replace) {
+    replaceCallback(handle, lambda);
+  } else {
+    tryRegisterCallback(handle, lambda);
+  }
+
+  return createRenderLambda<T>({ handle, ...flags });
+}
+
 const futureResolves = new Map<string, ((value: unknown) => void)[]>();
 
 export function registerFutureAwait(handle: FutureHandle, onResolve: (value: unknown) => void) {