@platforma-sdk/model 1.54.13 → 1.56.0

package/src/block_storage_callbacks.ts

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

package/src/block_storage_facade.ts

@@ -0,0 +1,199 @@
+/**
+ * Block Storage Facade - Contract between bundled blocks and middle layer.
+ *
+ * ============================================================================
+ * VERSIONING
+ * ============================================================================
+ *
+ * Blocks declare their model API version via the `requiresModelAPIVersion` feature flag
+ * (see BlockCodeKnownFeatureFlags). This determines how the middle layer manages block state:
+ *
+ * - Version 1: Legacy BlockModel - state is {args, uiState}, managed directly by middle layer
+ * - Version 2: BlockModelV3 - uses blockStorage with VM-based callbacks (this facade)
+ *
+ * This facade (BlockStorageFacade) is used by blocks with `requiresModelAPIVersion: 2`.
+ * The version number matches the model API version for clarity.
+ *
+ * ============================================================================
+ * BACKWARD COMPATIBILITY WARNING
+ * ============================================================================
+ *
+ * This file documents the FACADE between the SDK (bundled into blocks) and the
+ * middle layer. Once a block is published, its SDK version is frozen. The middle
+ * layer must support ALL previously released callback signatures indefinitely.
+ *
+ * RULES:
+ * 1. NEVER change the signature of existing callbacks
+ * 2. NEVER remove existing callbacks
+ * 3. New callbacks CAN be added (old blocks won't register them, middle layer
+ *    should handle missing callbacks gracefully)
+ * 4. Callback return types can be EXTENDED (add optional fields) but not changed
+ * 5. Callback parameter types should remain compatible (middle layer may need
+ *    to handle both old and new formats)
+ *
+ * The facade consists of callbacks registered via `tryRegisterCallback()` with
+ * the `__pl_` prefix. These are registered by the SDK when a block loads and
+ * called by the middle layer to perform operations.
+ *
+ * ============================================================================
+ * WHAT CAN BE CHANGED FREELY
+ * ============================================================================
+ *
+ * - Middle layer code (lib/node/pl-middle-layer)
+ * - SDK internal implementation (as long as callback contracts are preserved)
+ * - SDK exports used ONLY by middle layer (not by blocks themselves)
+ * - New SDK features that don't affect existing callbacks
+ *
+ * @module block_storage_facade
+ */
+
+import type { MutateStoragePayload } from "./block_storage";
+import type { ConfigRenderLambda } from "./bconfig";
+import { createRenderLambda, tryRegisterCallback } from "./internal";
+import type { StringifiedJson } from "@milaboratories/pl-model-common";
+
+// =============================================================================
+// Facade Version
+// =============================================================================
+
+/**
+ * The current facade version. This value is used for `requiresModelAPIVersion`
+ * feature flag in BlockModelV3.
+ */
+export const BLOCK_STORAGE_FACADE_VERSION = 2;
+
+// =============================================================================
+// Facade Callback Names
+// =============================================================================
+
+/**
+ * All facade callback names as constants.
+ * These are the source of truth - the interface is derived from these.
+ *
+ * IMPORTANT: When adding a new callback:
+ * 1. Add the constant here
+ * 2. Add the callback signature to FacadeCallbackTypes below
+ * 3. The BlockStorageFacade type will automatically include it
+ */
+export const BlockStorageFacadeCallbacks = {
+  StorageApplyUpdate: "__pl_storage_applyUpdate",
+  StorageDebugView: "__pl_storage_debugView",
+  StorageMigrate: "__pl_storage_migrate",
+  ArgsDerive: "__pl_args_derive",
+  PrerunArgsDerive: "__pl_prerunArgs_derive",
+  StorageInitial: "__pl_storage_initial",
+} as const;
+
+/**
+ * Creates a map of lambda handles from a callbacks constant object.
+ * Keys are the callback string values (e.g., '__pl_storage_applyUpdate').
+ */
+function createFacadeHandles<T extends Record<string, string>>(
+  callbacks: T,
+): { [K in T[keyof T]]: ConfigRenderLambda } {
+  return Object.fromEntries(
+    Object.values(callbacks).map((handle) => [handle, createRenderLambda({ handle })]),
+  ) as { [K in T[keyof T]]: ConfigRenderLambda };
+}
+
+/**
+ * Lambda handles for facade callbacks.
+ * Used by the middle layer to invoke callbacks via executeSingleLambda().
+ */
+export const BlockStorageFacadeHandles = createFacadeHandles(BlockStorageFacadeCallbacks);
+
+// =============================================================================
+// Facade Interface (source of truth for callback signatures)
+// =============================================================================
+
+/**
+ * The complete facade interface between bundled blocks (SDK) and middle layer.
+ *
+ * This interface defines ALL callbacks that a block registers. The middle layer
+ * calls these callbacks to perform storage operations.
+ *
+ * ALL types are inlined to simplify versioning - when a callback changes,
+ * the entire signature is visible in one place.
+ *
+ * BACKWARD COMPATIBILITY:
+ * - This interface can only be EXTENDED, never shrunk
+ * - Existing callback signatures MUST NOT change
+ * - Middle layer should use Partial<BlockStorageFacade> when dealing with
+ *   blocks of unknown version (older blocks may not have all callbacks)
+ *
+ * Each callback is documented with:
+ * - Purpose and when it's called
+ * - Parameter descriptions
+ * - Return value description
+ */
+export interface BlockStorageFacade {
+  /**
+   * Apply state update to storage.
+   * Called when UI updates block state (setState) or plugin data.
+   * @param currentStorageJson - Current storage as JSON string
+   * @param payload - Update payload with operation type and value
+   * @returns Updated storage as JSON string
+   */
+  [BlockStorageFacadeCallbacks.StorageApplyUpdate]: (
+    currentStorageJson: StringifiedJson,
+    payload: MutateStoragePayload,
+  ) => StringifiedJson;
+
+  /**
+   * Get debug view of storage.
+   * Called by developer tools to inspect storage state.
+   * @param storageJson - Storage as JSON string (or undefined for new blocks)
+   * @returns JSON string containing StorageDebugView
+   */
+  [BlockStorageFacadeCallbacks.StorageDebugView]: (
+    storageJson: StringifiedJson | undefined,
+  ) => StringifiedJson;
+
+  /**
+   * Run storage migration.
+   * Called when block loads to migrate data to latest version.
+   * @param currentStorageJson - Current storage as JSON string (or undefined for new blocks)
+   * @returns Migration result - either error or success with new storage
+   */
+  [BlockStorageFacadeCallbacks.StorageMigrate]: (currentStorageJson: StringifiedJson | undefined) =>
+    | { error: string }
+    | {
+        error?: undefined;
+        newStorageJson: StringifiedJson;
+        info: string;
+      };
+
+  /**
+   * Derive args from storage.
+   * Called to get block configuration args from storage.
+   * @param storageJson - Storage as JSON string
+   * @returns Args derivation result - either error or derived value
+   */
+  [BlockStorageFacadeCallbacks.ArgsDerive]: (
+    storageJson: StringifiedJson,
+  ) => { error: string } | { error?: undefined; value: unknown };
+
+  /**
+   * Derive prerunArgs from storage.
+   * Called to get prerun args; falls back to args callback if not registered.
+   * @param storageJson - Storage as JSON string
+   * @returns Args derivation result - either error or derived value
+   */
+  [BlockStorageFacadeCallbacks.PrerunArgsDerive]: (
+    storageJson: StringifiedJson,
+  ) => { error: string } | { error?: undefined; value: unknown };
+
+  /**
+   * Get initial storage JSON for new blocks.
+   * Called when creating a new block to get complete initial storage.
+   * @returns Initial storage as JSON string
+   */
+  [BlockStorageFacadeCallbacks.StorageInitial]: () => StringifiedJson;
+}
+
+/** Register all facade callbacks at once. Ensures all required callbacks are provided. */
+export function registerFacadeCallbacks(callbacks: BlockStorageFacade): void {
+  for (const key of Object.values(BlockStorageFacadeCallbacks)) {
+    tryRegisterCallback(key, callbacks[key] as (...args: any[]) => any);
+  }
+}

package/src/index.ts

@@ -1,17 +1,21 @@
 export * from "./block_state_patch";
 export * from "./block_state_util";
 export * from "./block_storage";
-export * from "./builder";
+export * from "./block_storage_facade";
+export * from "./block_model_legacy";
 export { BlockModelV3 } from "./block_model";
+export type { PluginInstance, ParamsInput } from "./block_model";
 export {
   DataModel,
   DataModelBuilder,
   DataUnrecoverableError,
   isDataUnrecoverableError,
-  defineDataVersions,
   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";
@@ -19,7 +23,7 @@ export * from "./pframe";
 export * from "./platforma";
 export * from "./ref_util";
 export * from "./render";
-export * from "./sdk_info";
+export * from "./version";
 export * from "./raw_globals";
 export * from "./block_api_v1";
 export * from "./block_api_v2";

package/src/platforma.ts

@@ -7,8 +7,9 @@ import type {
   DriverKit,
   OutputWithStatus,
 } from "@milaboratories/pl-model-common";
-import type { SdkInfo } from "./sdk_info";
+import type { SdkInfo } from "./version";
 import type { BlockStatePatch } from "./block_state_patch";
+import type { PluginInstance } from "./block_model";
 
 /** Defines all methods to interact with the platform environment from within a block UI. @deprecated */
 export interface PlatformaV1<
@@ -43,18 +44,21 @@ export interface PlatformaV2<
 }
 
 export interface PlatformaV3<
+  Data = unknown,
   Args = unknown,
   Outputs extends Record<string, OutputWithStatus<unknown>> = Record<
     string,
     OutputWithStatus<unknown>
   >,
-  Data = unknown,
   Href extends `/${string}` = `/${string}`,
+  Plugins extends Record<string, unknown> = Record<string, unknown>,
 >
-  extends BlockApiV3<Args, Outputs, Data, Href>, DriverKit {
+  extends BlockApiV3<Data, Args, Outputs, Href>, DriverKit {
   /** Information about SDK version current platforma environment was compiled with. */
   readonly sdkInfo: SdkInfo;
   readonly apiVersion: 3;
+  /** @internal Type brand for plugin type inference. Not used at runtime. */
+  readonly __pluginsBrand?: Plugins;
 }
 
 export type Platforma<
@@ -63,12 +67,12 @@ export type Platforma<
     string,
     OutputWithStatus<unknown>
   >,
-  UiState = unknown,
+  UiStateOrData = unknown,
   Href extends `/${string}` = `/${string}`,
 > =
-  | PlatformaV1<Args, Outputs, UiState, Href>
-  | PlatformaV2<Args, Outputs, UiState, Href>
-  | PlatformaV3<Args, Outputs, UiState, Href>;
+  | PlatformaV1<Args, Outputs, UiStateOrData, Href>
+  | PlatformaV2<Args, Outputs, UiStateOrData, Href>
+  | PlatformaV3<UiStateOrData, Args, Outputs, Href>;
 
 export type PlatformaExtended<Pl extends Platforma = Platforma> = Pl & {
   blockModelInfo: BlockModelInfo;
@@ -106,6 +110,7 @@ export type InferHrefType<Pl extends Platforma> =
 export type PlatformaFactory = (config: { sdkVersion: string }) => Platforma;
 
 export type InferBlockState<Pl extends Platforma> = BlockStateV3<
+  InferDataType<Pl>,
   InferOutputsType<Pl>,
   InferHrefType<Pl>
 >;
@@ -116,3 +121,17 @@ export type InferBlockStatePatch<Pl extends Platforma> = BlockStatePatch<
   InferUiState<Pl>,
   InferHrefType<Pl>
 >;
+
+/** Extract plugin IDs as a string literal union from a Platforma type. */
+export type InferPluginNames<Pl> =
+  Pl extends PlatformaV3<any, any, any, any, infer P> ? string & keyof P : never;
+
+/** Extract the Data type for a specific plugin by its ID. */
+export type InferPluginData<Pl, PluginId extends string> =
+  Pl extends PlatformaV3<any, any, any, any, infer P>
+    ? PluginId extends keyof P
+      ? P[PluginId] extends PluginInstance<infer D, any, any>
+        ? D
+        : never
+      : never
+    : never;