@platforma-sdk/model 1.54.13 → 1.56.0

package/dist/block_storage_callbacks.js

@@ -0,0 +1,218 @@
+import { BLOCK_STORAGE_SCHEMA_VERSION, migrateBlockStorage, updateStorageData, createBlockStorage, isBlockStorage, normalizeBlockStorage, getStorageData, BLOCK_STORAGE_KEY } from './block_storage.js';
+import { stringifyJson } from '@milaboratories/pl-model-common';
+
+/**
+ * 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
+ */
+/**
+ * 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) {
+    // 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>
+ */
+function applyStorageUpdate(currentStorageJson, payload) {
+    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) {
+    if (data === null || typeof data !== "object")
+        return false;
+    if (isBlockStorage(data))
+        return false;
+    const obj = data;
+    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
+ */
+function getStorageDebugView(rawStorage) {
+    const { storage } = normalizeStorage(rawStorage);
+    const debugView = {
+        dataVersion: storage.__dataVersion,
+        data: storage.__data,
+    };
+    return stringifyJson(debugView);
+}
+/**
+ * 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
+ */
+function migrateStorage(currentStorageJson, hooks) {
+    // 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
+ */
+function createInitialStorage(hooks) {
+    const blockDefault = hooks.getDefaultBlockData();
+    const pluginRegistry = hooks.getPluginRegistry();
+    const plugins = {};
+    for (const pluginId of Object.keys(pluginRegistry)) {
+        const initial = hooks.createPluginData(pluginId);
+        plugins[pluginId] = { __dataVersion: initial.version, __data: initial.data };
+    }
+    const storage = {
+        [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,
+        __dataVersion: blockDefault.version,
+        __data: blockDefault.data,
+        __pluginRegistry: pluginRegistry,
+        __plugins: plugins,
+    };
+    return stringifyJson(storage);
+}
+/**
+ * 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
+ */
+function deriveArgsFromStorage(storageJson, argsFunction) {
+    // 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
+ */
+function derivePrerunArgsFromStorage(storageJson, argsFunction, prerunArgsFunction) {
+    // 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 { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION, applyStorageUpdate, createInitialStorage, deriveArgsFromStorage, derivePrerunArgsFromStorage, getStorageDebugView, migrateStorage };
+//# sourceMappingURL=block_storage_callbacks.js.map

package/dist/block_storage_callbacks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"block_storage_callbacks.js","sources":["../src/block_storage_callbacks.ts"],"sourcesContent":["/**\n * BlockStorage Callback Implementations - wired to facade callbacks in BlockModelV3._done().\n *\n * Provides pure functions for storage operations (migration, initialization,\n * args derivation, updates, debug views). Each function takes its dependencies\n * explicitly as parameters.\n *\n * @module block_storage_callbacks\n * @internal\n */\n\nimport {\n  BLOCK_STORAGE_KEY,\n  BLOCK_STORAGE_SCHEMA_VERSION,\n  type BlockStorage,\n  type MutateStoragePayload,\n  type StorageDebugView,\n  type PluginRegistry,\n  type VersionedData,\n  createBlockStorage,\n  getStorageData,\n  isBlockStorage,\n  migrateBlockStorage,\n  normalizeBlockStorage,\n  updateStorageData,\n} from \"./block_storage\";\n\nimport { stringifyJson, type StringifiedJson } from \"@milaboratories/pl-model-common\";\nimport type { DataMigrationResult, DataVersioned } from \"./block_migrations\";\n\n// =============================================================================\n// Hook interfaces for dependency injection\n// =============================================================================\n\n/** Dependencies for storage migration */\nexport interface MigrationHooks {\n  migrateBlockData: (versioned: DataVersioned<unknown>) => DataMigrationResult<unknown>;\n  getPluginRegistry: () => PluginRegistry;\n  migratePluginData: (\n    pluginId: string,\n    versioned: DataVersioned<unknown>,\n  ) => DataMigrationResult<unknown> | undefined;\n  createPluginData: (pluginId: string) => DataVersioned<unknown>;\n}\n\n/** Dependencies for initial storage creation */\nexport interface InitialStorageHooks {\n  getDefaultBlockData: () => DataVersioned<unknown>;\n  getPluginRegistry: () => PluginRegistry;\n  createPluginData: (pluginId: string) => DataVersioned<unknown>;\n}\n\n/**\n * Result of storage normalization\n */\nexport interface NormalizeStorageResult {\n  /** The normalized BlockStorage object */\n  storage: BlockStorage;\n  /** The extracted data (what developers see) */\n  data: unknown;\n}\n\n/**\n * Normalizes raw storage data and extracts state.\n * Handles all formats:\n * - New BlockStorage format (has discriminator)\n * - Legacy V1/V2 format ({ args, uiState })\n * - Raw V3 state (any other format)\n *\n * @param rawStorage - Raw data from blockStorage field (may be JSON string or object)\n * @returns Object with normalized storage and extracted state\n */\nfunction normalizeStorage(rawStorage: unknown): NormalizeStorageResult {\n  // Handle undefined/null\n  if (rawStorage === undefined || rawStorage === null) {\n    const storage = createBlockStorage({});\n    return { storage, data: {} };\n  }\n\n  // Parse JSON string if needed\n  let parsed = rawStorage;\n  if (typeof rawStorage === \"string\") {\n    try {\n      parsed = JSON.parse(rawStorage);\n    } catch {\n      // If parsing fails, treat string as the data\n      const storage = createBlockStorage(rawStorage);\n      return { storage, data: rawStorage };\n    }\n  }\n\n  // Check for BlockStorage format (has discriminator)\n  if (isBlockStorage(parsed)) {\n    const storage = normalizeBlockStorage(parsed);\n    return { storage, data: getStorageData(storage) };\n  }\n\n  // Check for legacy V1/V2 format: { args, uiState }\n  if (isLegacyModelV1ApiFormat(parsed)) {\n    // For legacy format, the whole object IS the data\n    const storage = createBlockStorage(parsed);\n    return { storage, data: parsed };\n  }\n\n  // Raw V3 data - wrap it\n  const storage = createBlockStorage(parsed);\n  return { storage, data: parsed };\n}\n\n/**\n * Applies a state update to existing storage.\n * Used when setData is called from the frontend.\n *\n * @param currentStorageJson - Current storage as JSON string (must be defined)\n * @param payload - Update payload with operation type and value\n * @returns Updated storage as StringifiedJson<BlockStorage>\n */\nexport function applyStorageUpdate(\n  currentStorageJson: string,\n  payload: MutateStoragePayload,\n): StringifiedJson<BlockStorage> {\n  const { storage: currentStorage } = normalizeStorage(currentStorageJson);\n\n  // Update data while preserving other storage fields (version, plugins)\n  const updatedStorage = updateStorageData(currentStorage, payload);\n\n  return stringifyJson(updatedStorage);\n}\n\n/**\n * Checks if data is in legacy Model API v1 format.\n * Legacy format has { args, uiState? } at top level without the BlockStorage discriminator.\n */\nfunction isLegacyModelV1ApiFormat(data: unknown): data is { args?: unknown } {\n  if (data === null || typeof data !== \"object\") return false;\n  if (isBlockStorage(data)) return false;\n\n  const obj = data as Record<string, unknown>;\n  return \"args\" in obj;\n}\n\n// =============================================================================\n// Facade Callback Implementations\n// =============================================================================\n\n/**\n * Gets storage debug view from raw storage data.\n * Returns structured debug info about the storage state.\n *\n * @param rawStorage - Raw data from blockStorage field (may be JSON string or object)\n * @returns JSON string with storage debug view\n */\nexport function getStorageDebugView(rawStorage: unknown): StringifiedJson<StorageDebugView> {\n  const { storage } = normalizeStorage(rawStorage);\n  const debugView: StorageDebugView = {\n    dataVersion: storage.__dataVersion,\n    data: storage.__data,\n  };\n  return stringifyJson(debugView);\n}\n\n// =============================================================================\n// Migration Support\n// =============================================================================\n\n/**\n * Result of storage migration.\n * Returned by __pl_storage_migrate callback.\n *\n * - Error result: { error: string } - serious failure (no context, etc.)\n * - Success result: { newStorageJson: StringifiedJson<BlockStorage>, info: string } - migration succeeded\n */\nexport type MigrationResult =\n  | { error: string }\n  | { error?: undefined; newStorageJson: StringifiedJson<BlockStorage>; info: string };\n\n/**\n * Runs storage migration using the provided hooks.\n * This is the main entry point for the middle layer to trigger migrations.\n *\n * @param currentStorageJson - Current storage as JSON string (or undefined)\n * @param hooks - Migration dependencies (block/plugin data migration and creation functions)\n * @returns MigrationResult\n */\nexport function migrateStorage(\n  currentStorageJson: string | undefined,\n  hooks: MigrationHooks,\n): MigrationResult {\n  // Normalize current storage\n  const { storage: currentStorage } = normalizeStorage(currentStorageJson);\n\n  const newPluginRegistry = hooks.getPluginRegistry();\n\n  // Perform atomic migration of block + all plugins\n  const migrationResult = migrateBlockStorage(currentStorage, {\n    migrateBlockData: hooks.migrateBlockData,\n    migratePluginData: hooks.migratePluginData,\n    newPluginRegistry,\n    createPluginData: hooks.createPluginData,\n  });\n\n  if (!migrationResult.success) {\n    return {\n      error: `Migration failed at '${migrationResult.failedAt}': ${migrationResult.error}`,\n    };\n  }\n\n  // Build info message\n  const oldVersion = currentStorage.__dataVersion;\n  const newVersion = migrationResult.storage.__dataVersion;\n  const info =\n    oldVersion === newVersion\n      ? `No migration needed (${oldVersion})`\n      : `Migrated ${oldVersion} -> ${newVersion}`;\n\n  return {\n    newStorageJson: stringifyJson(migrationResult.storage),\n    info,\n  };\n}\n\n// =============================================================================\n// Initial Storage Creation\n// =============================================================================\n\n/**\n * Creates complete initial storage (block data + all plugin data) atomically.\n *\n * @param hooks - Dependencies for creating initial block and plugin data\n * @returns Initial storage as branded JSON string\n */\nexport function createInitialStorage(hooks: InitialStorageHooks): StringifiedJson<BlockStorage> {\n  const blockDefault = hooks.getDefaultBlockData();\n  const pluginRegistry = hooks.getPluginRegistry();\n\n  const plugins: Record<string, VersionedData<unknown>> = {};\n  for (const pluginId of Object.keys(pluginRegistry)) {\n    const initial = hooks.createPluginData(pluginId);\n    plugins[pluginId] = { __dataVersion: initial.version, __data: initial.data };\n  }\n\n  const storage: BlockStorage = {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: blockDefault.version,\n    __data: blockDefault.data,\n    __pluginRegistry: pluginRegistry,\n    __plugins: plugins,\n  };\n  return stringifyJson(storage);\n}\n\n// =============================================================================\n// Args Derivation from Storage\n// =============================================================================\n\n/**\n * Result of args derivation from storage.\n * Returned by __pl_args_derive and __pl_prerunArgs_derive callbacks.\n */\nexport type ArgsDeriveResult = { error: string } | { error?: undefined; value: unknown };\n\n/**\n * Derives args from storage using the provided args function.\n * This extracts data from storage and passes it to the block's args() function.\n *\n * @param storageJson - Storage as JSON string\n * @param argsFunction - The block's args derivation function\n * @returns ArgsDeriveResult with derived args or error\n */\nexport function deriveArgsFromStorage(\n  storageJson: string,\n  argsFunction: (data: unknown) => unknown,\n): ArgsDeriveResult {\n  // Extract data from storage\n  const { data } = normalizeStorage(storageJson);\n\n  // Call the args function with extracted data\n  try {\n    const result = argsFunction(data);\n    return { value: result };\n  } catch (e) {\n    const errorMsg = e instanceof Error ? e.message : String(e);\n    return { error: `args() threw: ${errorMsg}` };\n  }\n}\n\n/**\n * Derives prerunArgs from storage.\n * Uses prerunArgsFunction if provided, otherwise falls back to argsFunction.\n *\n * @param storageJson - Storage as JSON string\n * @param argsFunction - The block's args derivation function (fallback)\n * @param prerunArgsFunction - Optional prerun args derivation function\n * @returns ArgsDeriveResult with derived prerunArgs or error\n */\nexport function derivePrerunArgsFromStorage(\n  storageJson: string,\n  argsFunction: (data: unknown) => unknown,\n  prerunArgsFunction?: (data: unknown) => unknown,\n): ArgsDeriveResult {\n  // Extract data from storage\n  const { data } = normalizeStorage(storageJson);\n\n  // Try prerunArgs function first if available\n  if (prerunArgsFunction) {\n    try {\n      const result = prerunArgsFunction(data);\n      return { value: result };\n    } catch (e) {\n      const errorMsg = e instanceof Error ? e.message : String(e);\n      return { error: `prerunArgs() threw: ${errorMsg}` };\n    }\n  }\n\n  // Fall back to args function\n  try {\n    const result = argsFunction(data);\n    return { value: result };\n  } catch (e) {\n    const errorMsg = e instanceof Error ? e.message : String(e);\n    return { error: `args() threw (fallback): ${errorMsg}` };\n  }\n}\n\n// Export discriminator key and schema version for external checks\nexport { BLOCK_STORAGE_KEY, BLOCK_STORAGE_SCHEMA_VERSION };\n"],"names":[],"mappings":"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"}

package/dist/block_storage_facade.cjs

@@ -0,0 +1,104 @@
+'use strict';
+
+var internal = require('./internal.cjs');
+
+/**
+ * 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
+ */
+// =============================================================================
+// Facade Version
+// =============================================================================
+/**
+ * The current facade version. This value is used for `requiresModelAPIVersion`
+ * feature flag in BlockModelV3.
+ */
+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
+ */
+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",
+};
+/**
+ * Creates a map of lambda handles from a callbacks constant object.
+ * Keys are the callback string values (e.g., '__pl_storage_applyUpdate').
+ */
+function createFacadeHandles(callbacks) {
+    return Object.fromEntries(Object.values(callbacks).map((handle) => [handle, internal.createRenderLambda({ handle })]));
+}
+/**
+ * Lambda handles for facade callbacks.
+ * Used by the middle layer to invoke callbacks via executeSingleLambda().
+ */
+const BlockStorageFacadeHandles = createFacadeHandles(BlockStorageFacadeCallbacks);
+/** Register all facade callbacks at once. Ensures all required callbacks are provided. */
+function registerFacadeCallbacks(callbacks) {
+    for (const key of Object.values(BlockStorageFacadeCallbacks)) {
+        internal.tryRegisterCallback(key, callbacks[key]);
+    }
+}
+
+exports.BLOCK_STORAGE_FACADE_VERSION = BLOCK_STORAGE_FACADE_VERSION;
+exports.BlockStorageFacadeCallbacks = BlockStorageFacadeCallbacks;
+exports.BlockStorageFacadeHandles = BlockStorageFacadeHandles;
+exports.registerFacadeCallbacks = registerFacadeCallbacks;
+//# sourceMappingURL=block_storage_facade.cjs.map

package/dist/block_storage_facade.cjs.map

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

package/dist/block_storage_facade.d.ts

@@ -0,0 +1,168 @@
+/**
+ * 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 type { StringifiedJson } from "@milaboratories/pl-model-common";
+/**
+ * The current facade version. This value is used for `requiresModelAPIVersion`
+ * feature flag in BlockModelV3.
+ */
+export declare const BLOCK_STORAGE_FACADE_VERSION = 2;
+/**
+ * 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 declare const BlockStorageFacadeCallbacks: {
+    readonly StorageApplyUpdate: "__pl_storage_applyUpdate";
+    readonly StorageDebugView: "__pl_storage_debugView";
+    readonly StorageMigrate: "__pl_storage_migrate";
+    readonly ArgsDerive: "__pl_args_derive";
+    readonly PrerunArgsDerive: "__pl_prerunArgs_derive";
+    readonly StorageInitial: "__pl_storage_initial";
+};
+/**
+ * Lambda handles for facade callbacks.
+ * Used by the middle layer to invoke callbacks via executeSingleLambda().
+ */
+export declare const BlockStorageFacadeHandles: {
+    __pl_storage_applyUpdate: ConfigRenderLambda<unknown>;
+    __pl_storage_debugView: ConfigRenderLambda<unknown>;
+    __pl_storage_migrate: ConfigRenderLambda<unknown>;
+    __pl_args_derive: ConfigRenderLambda<unknown>;
+    __pl_prerunArgs_derive: ConfigRenderLambda<unknown>;
+    __pl_storage_initial: ConfigRenderLambda<unknown>;
+};
+/**
+ * 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 declare function registerFacadeCallbacks(callbacks: BlockStorageFacade): void;
+//# sourceMappingURL=block_storage_facade.d.ts.map

package/dist/block_storage_facade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block_storage_facade.d.ts","sourceRoot":"","sources":["../src/block_storage_facade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAEpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAMvE;;;GAGG;AACH,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAM9C;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B;;;;;;;CAO9B,CAAC;AAcX;;;GAGG;AACH,eAAO,MAAM,yBAAyB;;;;;;;CAAmD,CAAC;AAM1F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,CAAC,2BAA2B,CAAC,kBAAkB,CAAC,EAAE,CAChD,kBAAkB,EAAE,eAAe,EACnC,OAAO,EAAE,oBAAoB,KAC1B,eAAe,CAAC;IAErB;;;;;OAKG;IACH,CAAC,2BAA2B,CAAC,gBAAgB,CAAC,EAAE,CAC9C,WAAW,EAAE,eAAe,GAAG,SAAS,KACrC,eAAe,CAAC;IAErB;;;;;OAKG;IACH,CAAC,2BAA2B,CAAC,cAAc,CAAC,EAAE,CAAC,kBAAkB,EAAE,eAAe,GAAG,SAAS,KAC1F;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GACjB;QACE,KAAK,CAAC,EAAE,SAAS,CAAC;QAClB,cAAc,EAAE,eAAe,CAAC;QAChC,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IAEN;;;;;OAKG;IACH,CAAC,2BAA2B,CAAC,UAAU,CAAC,EAAE,CACxC,WAAW,EAAE,eAAe,KACzB;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,KAAK,CAAC,EAAE,SAAS,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;IAE/D;;;;;OAKG;IACH,CAAC,2BAA2B,CAAC,gBAAgB,CAAC,EAAE,CAC9C,WAAW,EAAE,eAAe,KACzB;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,KAAK,CAAC,EAAE,SAAS,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;IAE/D;;;;OAIG;IACH,CAAC,2BAA2B,CAAC,cAAc,CAAC,EAAE,MAAM,eAAe,CAAC;CACrE;AAED,0FAA0F;AAC1F,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,kBAAkB,GAAG,IAAI,CAI3E"}

package/dist/block_storage_facade.js

@@ -0,0 +1,99 @@
+import { createRenderLambda, tryRegisterCallback } from './internal.js';
+
+/**
+ * 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
+ */
+// =============================================================================
+// Facade Version
+// =============================================================================
+/**
+ * The current facade version. This value is used for `requiresModelAPIVersion`
+ * feature flag in BlockModelV3.
+ */
+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
+ */
+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",
+};
+/**
+ * Creates a map of lambda handles from a callbacks constant object.
+ * Keys are the callback string values (e.g., '__pl_storage_applyUpdate').
+ */
+function createFacadeHandles(callbacks) {
+    return Object.fromEntries(Object.values(callbacks).map((handle) => [handle, createRenderLambda({ handle })]));
+}
+/**
+ * Lambda handles for facade callbacks.
+ * Used by the middle layer to invoke callbacks via executeSingleLambda().
+ */
+const BlockStorageFacadeHandles = createFacadeHandles(BlockStorageFacadeCallbacks);
+/** Register all facade callbacks at once. Ensures all required callbacks are provided. */
+function registerFacadeCallbacks(callbacks) {
+    for (const key of Object.values(BlockStorageFacadeCallbacks)) {
+        tryRegisterCallback(key, callbacks[key]);
+    }
+}
+
+export { BLOCK_STORAGE_FACADE_VERSION, BlockStorageFacadeCallbacks, BlockStorageFacadeHandles, registerFacadeCallbacks };
+//# sourceMappingURL=block_storage_facade.js.map