@platforma-sdk/model 1.51.6 → 1.52.0

package/dist/block_model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"block_model.js","sources":["../src/block_model.ts"],"sourcesContent":["import type {\n  BlockRenderingMode,\n  BlockSection,\n  OutputWithStatus,\n  PlRef,\n  BlockCodeKnownFeatureFlags,\n  BlockConfigContainer,\n} from '@milaboratories/pl-model-common';\nimport { getPlatformaInstance, isInUI, createAndRegisterRenderLambda, createRenderLambda } from './internal';\nimport type { DataModel } from './block_migrations';\nimport type { PlatformaV3 } from './platforma';\nimport type { InferRenderFunctionReturn, RenderFunction } from './render';\nimport { RenderCtx } from './render';\nimport { PlatformaSDKVersion } from './version';\n// Import storage VM integration (side-effect: registers internal callbacks)\nimport './block_storage_vm';\nimport type {\n  ConfigRenderLambda,\n  DeriveHref,\n  ConfigRenderLambdaFlags,\n  InferOutputsFromLambdas,\n} from './bconfig';\nimport {\n  downgradeCfgOrLambda,\n  isConfigLambda,\n} from './bconfig';\nimport type { PlatformaExtended } from './platforma';\n\ntype SectionsExpectedType = readonly BlockSection[];\n\ntype NoOb = Record<string, never>;\n\ninterface BlockModelV3Config<\n  Args,\n  OutputsCfg extends Record<string, ConfigRenderLambda>,\n  Data,\n> {\n  renderingMode: BlockRenderingMode;\n  dataModel: DataModel<Data>;\n  outputs: OutputsCfg;\n  sections: ConfigRenderLambda;\n  title: ConfigRenderLambda | undefined;\n  subtitle: ConfigRenderLambda | undefined;\n  tags: ConfigRenderLambda | undefined;\n  enrichmentTargets: ConfigRenderLambda | undefined;\n  featureFlags: BlockCodeKnownFeatureFlags;\n  args: ConfigRenderLambda<Args> | undefined;\n  prerunArgs: ConfigRenderLambda<unknown> | undefined;\n}\n\n/** Options for creating a BlockModelV3 */\nexport interface BlockModelV3Options<Data extends Record<string, unknown>> {\n  /** The data model that defines initial data and migrations */\n  dataModel: DataModel<Data>;\n  /** Rendering mode for the block (default: 'Heavy') */\n  renderingMode?: BlockRenderingMode;\n}\n\n/** Main entry point that each block should use in it's \"config\" module. Don't forget\n * to call {@link done()} at the end of configuration. Value returned by this builder must be\n * exported as constant with name \"platforma\" from the \"config\" module.\n * API version is 3 (for UI) and 2 (for model) */\nexport class BlockModelV3<\n  Args,\n  OutputsCfg extends Record<string, ConfigRenderLambda>,\n  Data extends Record<string, unknown> = Record<string, unknown>,\n  Href extends `/${string}` = '/',\n> {\n  private constructor(\n    private readonly config: BlockModelV3Config<Args, OutputsCfg, Data>,\n  ) {}\n\n  public static readonly INITIAL_BLOCK_FEATURE_FLAGS: BlockCodeKnownFeatureFlags = {\n    supportsLazyState: true,\n    requiresUIAPIVersion: 3,\n    requiresModelAPIVersion: 2,\n  };\n\n  /**\n   * Creates a new BlockModelV3 builder with the specified data model and options.\n   *\n   * @example\n   * const dataModel = DataModel.create<BlockData>(() => ({ numbers: [], labels: [] }));\n   * BlockModelV3.create({ dataModel })\n   *   .args((data) => ({ numbers: data.numbers }))\n   *   .sections(() => [{ type: 'link', href: '/', label: 'Main' }])\n   *   .done();\n   *\n   * @param options Configuration options including required data model\n   */\n  public static create<Data extends Record<string, unknown>>(\n    options: BlockModelV3Options<Data>,\n  ): BlockModelV3<NoOb, {}, Data> {\n    const { dataModel, renderingMode = 'Heavy' } = options;\n\n    // Register data model callbacks for VM use (initialData and upgrade)\n    dataModel.registerCallbacks();\n\n    return new BlockModelV3<NoOb, {}, Data>({\n      renderingMode,\n      dataModel,\n      outputs: {},\n      // Register default sections callback (returns empty array)\n      sections: createAndRegisterRenderLambda({ handle: 'sections', lambda: () => [] }, true),\n      title: undefined,\n      subtitle: undefined,\n      tags: undefined,\n      enrichmentTargets: undefined,\n      featureFlags: { ...BlockModelV3.INITIAL_BLOCK_FEATURE_FLAGS },\n      args: undefined,\n      prerunArgs: undefined,\n    });\n  }\n\n  /**\n   * Add output cell wrapped with additional status information to the configuration\n   *\n   * @param key output cell name, that can be later used to retrieve the rendered value\n   * @param rf  callback calculating output value using context, that allows to access\n   *            workflows outputs and interact with platforma drivers\n   * @param flags additional flags that may alter lambda rendering procedure\n   * */\n  public output<const Key extends string, const RF extends RenderFunction<Args, Data>>(\n    key: Key,\n    rf: RF,\n    flags: ConfigRenderLambdaFlags & { withStatus: true }\n  ): BlockModelV3<\n    Args,\n      OutputsCfg & { [K in Key]: ConfigRenderLambda<InferRenderFunctionReturn<RF>> & { withStatus: true } },\n      Data,\n      Href\n  >;\n  /**\n   * Add output cell to the configuration\n   *\n   * @param key output cell name, that can be later used to retrieve the rendered value\n   * @param rf  callback calculating output value using context, that allows to access\n   *            workflows outputs and interact with platforma drivers\n   * @param flags additional flags that may alter lambda rendering procedure\n   * */\n  public output<const Key extends string, const RF extends RenderFunction<Args, Data>>(\n    key: Key,\n    rf: RF,\n    flags?: ConfigRenderLambdaFlags\n  ): BlockModelV3<\n    Args,\n    OutputsCfg & { [K in Key]: ConfigRenderLambda<InferRenderFunctionReturn<RF>> },\n    Data,\n    Href\n  >;\n  public output(\n    key: string,\n    cfgOrRf: RenderFunction<Args, Data>,\n    flags: ConfigRenderLambdaFlags = {},\n  ): BlockModelV3<Args, OutputsCfg, Data, Href> {\n    return new BlockModelV3({\n      ...this.config,\n      outputs: {\n        ...this.config.outputs,\n        [key]: createAndRegisterRenderLambda({ handle: `output#${key}`, lambda: () => cfgOrRf(new RenderCtx()), ...flags }),\n      },\n    });\n  }\n\n  /** Shortcut for {@link output} with retentive flag set to true. */\n  public retentiveOutput<const Key extends string, const RF extends RenderFunction<Args, Data>>(\n    key: Key,\n    rf: RF,\n  ): BlockModelV3<\n      Args,\n    OutputsCfg & { [K in Key]: ConfigRenderLambda<InferRenderFunctionReturn<RF>> },\n    Data,\n    Href\n    > {\n    return this.output(key, rf, { retentive: true });\n  }\n\n  /** Shortcut for {@link output} with withStatus flag set to true. */\n  public outputWithStatus<const Key extends string, const RF extends RenderFunction<Args, Data>>(\n    key: Key,\n    rf: RF,\n  ) {\n    return this.output(key, rf, { withStatus: true });\n  }\n\n  /**\n   * Sets a function to derive block args from data.\n   * This is called during setData to compute the args that will be used for block execution.\n   *\n   * @example\n   * .args<BlockArgs>((data) => ({ numbers: data.numbers }))\n   *\n   * @example\n   * .args<BlockArgs>((data) => {\n   *   if (data.numbers.length === 0) throw new Error('Numbers required'); // block not ready\n   *   return { numbers: data.numbers };\n   * })\n   */\n  public args<Args>(lambda: (data: Data) => Args): BlockModelV3<Args, OutputsCfg, Data, Href> {\n    return new BlockModelV3<Args, OutputsCfg, Data, Href>({\n      ...this.config,\n      args: createAndRegisterRenderLambda<Args>({ handle: 'args', lambda }),\n    });\n  }\n\n  /**\n   * Sets a function to derive pre-run args from data (optional).\n   * This is called during setData to compute the args that will be used for staging/pre-run phase.\n   *\n   * If not defined, defaults to using the args() function result.\n   * If defined, uses its return value for the staging / prerun phase.\n   *\n   * The staging / prerun phase runs only if currentPrerunArgs differs from the executed\n   * version of prerunArgs (same comparison logic as currentArgs vs prodArgs).\n   *\n   * @example\n   * .prerunArgs((data) => ({ numbers: data.numbers }))\n   *\n   * @example\n   * .prerunArgs((data) => {\n   *   // Return undefined to skip staging for this block\n   *   if (!data.isReady) return undefined;\n   *   return { numbers: data.numbers };\n   * })\n   */\n  public prerunArgs(fn: (data: Data) => unknown): BlockModelV3<Args, OutputsCfg, Data, Href> {\n    return new BlockModelV3<Args, OutputsCfg, Data, Href>({\n      ...this.config,\n      prerunArgs: createAndRegisterRenderLambda({ handle: 'prerunArgs', lambda: fn }),\n    });\n  }\n\n  /** Sets the lambda to generate list of sections in the left block overviews panel. */\n  public sections<\n    const Ret extends SectionsExpectedType,\n    const RF extends RenderFunction<Args, Data, Ret>,\n  >(rf: RF): BlockModelV3<Args, OutputsCfg, Data, DeriveHref<ReturnType<RF>>> {\n    return new BlockModelV3<Args, OutputsCfg, Data, DeriveHref<ReturnType<RF>>>({\n      ...this.config,\n      // Replace the default sections callback with the user-provided one\n      sections: createAndRegisterRenderLambda({ handle: 'sections', lambda: () => rf(new RenderCtx()) }, true),\n    });\n  }\n\n  /** Sets a rendering function to derive block title, shown for the block in the left blocks-overview panel. */\n  public title(\n    rf: RenderFunction<Args, Data, string>,\n  ): BlockModelV3<Args, OutputsCfg, Data, Href> {\n    return new BlockModelV3<Args, OutputsCfg, Data, Href>({\n      ...this.config,\n      title: createAndRegisterRenderLambda({ handle: 'title', lambda: () => rf(new RenderCtx()) }),\n    });\n  }\n\n  public subtitle(\n    rf: RenderFunction<Args, Data, string>,\n  ): BlockModelV3<Args, OutputsCfg, Data, Href> {\n    return new BlockModelV3<Args, OutputsCfg, Data, Href>({\n      ...this.config,\n      subtitle: createAndRegisterRenderLambda({ handle: 'subtitle', lambda: () => rf(new RenderCtx()) }),\n    });\n  }\n\n  public tags(\n    rf: RenderFunction<Args, Data, string[]>,\n  ): BlockModelV3<Args, OutputsCfg, Data, Href> {\n    return new BlockModelV3<Args, OutputsCfg, Data, Href>({\n      ...this.config,\n      tags: createAndRegisterRenderLambda({ handle: 'tags', lambda: () => rf(new RenderCtx()) }),\n    });\n  }\n\n  /** Sets or overrides feature flags for the block. */\n  public withFeatureFlags(flags: Partial<BlockCodeKnownFeatureFlags>): BlockModelV3<Args, OutputsCfg, Data, Href> {\n    return new BlockModelV3<Args, OutputsCfg, Data, Href>({\n      ...this.config,\n      featureFlags: { ...this.config.featureFlags, ...flags },\n    });\n  }\n\n  /**\n   * Defines how to derive list of upstream references this block is meant to enrich with its exports from block args.\n   * Influences dependency graph construction.\n   */\n  public enriches(\n    lambda: (args: Args) => PlRef[],\n  ): BlockModelV3<Args, OutputsCfg, Data, Href> {\n    return new BlockModelV3<Args, OutputsCfg, Data, Href>({\n      ...this.config,\n      enrichmentTargets: createAndRegisterRenderLambda({ handle: 'enrichmentTargets', lambda: lambda }),\n    });\n  }\n\n  /** Renders all provided block settings into a pre-configured platforma API\n   * instance, that can be used in frontend to interact with block data, and\n   * other features provided by the platforma to the block. */\n  public done(): PlatformaExtended<PlatformaV3<\n    Args,\n    InferOutputsFromLambdas<OutputsCfg>,\n    Data,\n    Href\n  >> {\n    return this.withFeatureFlags({\n      ...this.config.featureFlags,\n    })._done();\n  }\n\n  public _done(): PlatformaExtended<PlatformaV3<\n    Args,\n    InferOutputsFromLambdas<OutputsCfg>,\n    Data,\n    Href\n  >> {\n    if (this.config.args === undefined) throw new Error('Args rendering function not set.');\n\n    const apiVersion = 3;\n\n    const migrationCount = this.config.dataModel.migrationCount;\n\n    const blockConfig: BlockConfigContainer = {\n      v4: {\n        configVersion: 4,\n        modelAPIVersion: 2,\n        sdkVersion: PlatformaSDKVersion,\n        renderingMode: this.config.renderingMode,\n        args: this.config.args,\n        prerunArgs: this.config.prerunArgs,\n        // Reference to __pl_data_initial callback registered by DataModel\n        initialData: createRenderLambda({ handle: '__pl_data_initial' }),\n        sections: this.config.sections,\n        title: this.config.title,\n        outputs: this.config.outputs,\n        enrichmentTargets: this.config.enrichmentTargets,\n        featureFlags: this.config.featureFlags,\n        // Generate migration descriptors (indices for metadata)\n        migrations: migrationCount > 0\n          ? Array.from({ length: migrationCount }, (_, i) => ({ index: i }))\n          : undefined,\n      },\n\n      // fields below are added to allow previous desktop versions read generated configs\n      sdkVersion: PlatformaSDKVersion,\n      renderingMode: this.config.renderingMode,\n      sections: this.config.sections,\n      outputs: Object.fromEntries(\n        Object.entries(this.config.outputs).map(([key, value]) => [key, downgradeCfgOrLambda(value)]),\n      ),\n    };\n\n    globalThis.platformaApiVersion = apiVersion;\n\n    if (!isInUI())\n    // we are in the configuration rendering routine, not in actual UI\n      return { config: blockConfig } as any;\n    // normal operation inside the UI\n    else return {\n      ...getPlatformaInstance({ sdkVersion: PlatformaSDKVersion, apiVersion }),\n      blockModelInfo: {\n        outputs: Object.fromEntries(\n          Object.entries(this.config.outputs)\n            .map(([key, value]) => [key, {\n              withStatus: Boolean(isConfigLambda(value) && value.withStatus),\n            }]),\n        ),\n      },\n    } as any;\n  }\n}\n\n// Type tests for BlockModelV3\n\nexport type Expect<T extends true> = T;\n\nexport type Equal<X, Y> =\n  (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2) ? true : false;\n\nexport type Merge<A, B> = {\n  [K in keyof A | keyof B]: K extends keyof B ? B[K] : K extends keyof A ? A[K] : never;\n};\n\n// Helper types for testing\ntype _TestArgs = { inputFile: string; threshold: number };\ntype _TestData = { selectedTab: string };\ntype _TestOutputs = { result: ConfigRenderLambda<string>; count: ConfigRenderLambda<number> };\n\n// Test: Merge type works correctly\ntype _MergeTest1 = Expect<Equal<Merge<{ a: 1 }, { b: 2 }>, { a: 1; b: 2 }>>;\ntype _MergeTest2 = Expect<Equal<Merge<{ a: 1 }, { a: 2 }>, { a: 2 }>>;\ntype _MergeTest3 = Expect<Equal<Merge<{ a: 1; b: 1 }, { b: 2; c: 3 }>, { a: 1; b: 2; c: 3 }>>;\n\n// Test: create() returns a BlockModelV3 instance\n// Note: Due to function overloads, ReturnType uses the last overload signature.\n// We verify the structure is correct using a simpler assignability test.\ntype _CreateResult = ReturnType<typeof BlockModelV3.create>;\ntype _CreateIsBlockModelV3 = _CreateResult extends BlockModelV3<infer _A, infer _O, infer _S> ? true : false;\ntype _CreateTest = Expect<_CreateIsBlockModelV3>;\n\n// Test: BlockModelV3Config interface structure\ntype _ConfigTest = Expect<Equal<\n  BlockModelV3Config<_TestArgs, _TestOutputs, _TestData>,\n  {\n    renderingMode: BlockRenderingMode;\n    args: ConfigRenderLambda<_TestArgs> | undefined;\n    prerunArgs: ConfigRenderLambda<unknown> | undefined;\n    dataModel: DataModel<_TestData>;\n    outputs: _TestOutputs;\n    sections: ConfigRenderLambda;\n    title: ConfigRenderLambda | undefined;\n    subtitle: ConfigRenderLambda | undefined;\n    tags: ConfigRenderLambda | undefined;\n    enrichmentTargets: ConfigRenderLambda | undefined;\n    featureFlags: BlockCodeKnownFeatureFlags;\n  }\n>>;\n\n// Test: Default Href is '/'\ntype _HrefDefaultTest = BlockModelV3<_TestArgs, {}, _TestData> extends BlockModelV3<_TestArgs, {}, _TestData, '/'> ? true : false;\ntype _VerifyHrefDefault = Expect<_HrefDefaultTest>;\n\n// Test: Custom Href can be specified\ntype _CustomHref = '/settings' | '/main';\ntype _HrefCustomBuilder = BlockModelV3<_TestArgs, {}, _TestData, _CustomHref>;\ntype _HrefCustomTest = _HrefCustomBuilder extends BlockModelV3<_TestArgs, {}, _TestData, _CustomHref> ? true : false;\ntype _VerifyHrefCustom = Expect<_HrefCustomTest>;\n\n// Test: Output type accumulation with & intersection\ntype _OutputsAccumulation = { a: ConfigRenderLambda<string> } & { b: ConfigRenderLambda<number> };\ntype _VerifyOutputsHaveKeys = Expect<Equal<keyof _OutputsAccumulation, 'a' | 'b'>>;\n\n// Test: Builder with all type parameters specified compiles\ntype _FullBuilder = BlockModelV3<_TestArgs, _TestOutputs, _TestData, '/main'>;\ntype _FullBuilderTest = _FullBuilder extends BlockModelV3<_TestArgs, _TestOutputs, _TestData, '/main'> ? true : false;\ntype _VerifyFullBuilder = Expect<_FullBuilderTest>;\n\n// Test: InferOutputsFromLambdas maps outputs correctly\ntype _InferOutputsTest = InferOutputsFromLambdas<{ myOutput: ConfigRenderLambda<number> }>;\ntype _VerifyInferOutputs = Expect<Equal<\n  _InferOutputsTest,\n  { myOutput: OutputWithStatus<number> & { __unwrap: true } }\n>>;\n"],"names":[],"mappings":"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"}

package/dist/block_storage.cjs

@@ -0,0 +1,244 @@
+'use strict';
+
+/**
+ * BlockStorage - Typed storage abstraction for block persistent data.
+ *
+ * This module provides:
+ * - A typed structure for block storage with versioning and plugin support
+ * - Utility functions for manipulating storage
+ * - Handler interfaces for model-level customization
+ *
+ * @module block_storage
+ */
+// =============================================================================
+// Core Types
+// =============================================================================
+/**
+ * Discriminator key for BlockStorage format detection.
+ * This unique hash-based key identifies data as BlockStorage vs legacy formats.
+ */
+const BLOCK_STORAGE_KEY = '__pl_a7f3e2b9__';
+/**
+ * Current BlockStorage schema version.
+ * Increment this when the storage structure itself changes (not block state migrations).
+ */
+const BLOCK_STORAGE_SCHEMA_VERSION = 'v1';
+/**
+ * Type guard to check if a value is a valid BlockStorage object.
+ * Checks for the discriminator key and valid schema version.
+ */
+function isBlockStorage(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const obj = value;
+    const schemaVersion = obj[BLOCK_STORAGE_KEY];
+    // Currently only 'v1' is valid, but this allows future versions
+    return schemaVersion === 'v1'; // Add more versions as schema evolves
+}
+// =============================================================================
+// Factory Functions
+// =============================================================================
+/**
+ * Creates a BlockStorage with the given initial data
+ *
+ * @param initialData - The initial data value (defaults to empty object)
+ * @param version - The initial data version (defaults to 1)
+ * @returns A new BlockStorage instance with discriminator key
+ */
+function createBlockStorage(initialData = {}, version = 1) {
+    return {
+        [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,
+        __dataVersion: version,
+        __data: initialData,
+    };
+}
+/**
+ * Normalizes raw storage data to BlockStorage format.
+ * If the input is already a BlockStorage, returns it as-is.
+ * If the input is legacy format (raw state), wraps it in BlockStorage structure.
+ *
+ * @param raw - Raw storage data (may be legacy format or BlockStorage)
+ * @returns Normalized BlockStorage
+ */
+function normalizeBlockStorage(raw) {
+    if (isBlockStorage(raw)) {
+        return raw;
+    }
+    // Legacy format: raw is the state directly
+    return createBlockStorage(raw, 1);
+}
+// =============================================================================
+// Data Access & Update Functions
+// =============================================================================
+/**
+ * Gets the data from BlockStorage
+ *
+ * @param storage - The BlockStorage instance
+ * @returns The data value
+ */
+function getStorageData(storage) {
+    return storage.__data;
+}
+/**
+ * Derives data from raw block storage.
+ * This function is meant to be called from sdk/ui-vue to extract
+ * user-facing data from the raw storage returned by the middle layer.
+ *
+ * The middle layer returns raw storage (opaque to it), and the UI
+ * uses this function to derive the actual data value.
+ *
+ * @param rawStorage - Raw storage data from middle layer (may be any format)
+ * @returns The extracted data value, or undefined if storage is undefined/null
+ */
+function deriveDataFromStorage(rawStorage) {
+    // Normalize to BlockStorage format (handles legacy formats too)
+    const storage = normalizeBlockStorage(rawStorage);
+    return getStorageData(storage);
+}
+/**
+ * Updates the data in BlockStorage (immutable)
+ *
+ * @param storage - The current BlockStorage
+ * @param payload - The update payload with operation and value
+ * @returns A new BlockStorage with updated data
+ */
+function updateStorageData(storage, payload) {
+    switch (payload.operation) {
+        case 'update-data':
+            return { ...storage, __data: payload.value };
+        default:
+            throw new Error(`Unknown storage operation: ${payload.operation}`);
+    }
+}
+/**
+ * Gets the data version from BlockStorage
+ *
+ * @param storage - The BlockStorage instance
+ * @returns The data version number
+ */
+function getStorageDataVersion(storage) {
+    return storage.__dataVersion;
+}
+/**
+ * Updates the data version in BlockStorage (immutable)
+ *
+ * @param storage - The current BlockStorage
+ * @param version - The new version number
+ * @returns A new BlockStorage with updated version
+ */
+function updateStorageDataVersion(storage, version) {
+    return { ...storage, __dataVersion: version };
+}
+// =============================================================================
+// Plugin Data Functions
+// =============================================================================
+/**
+ * Gets plugin-specific data from BlockStorage
+ *
+ * @param storage - The BlockStorage instance
+ * @param pluginName - The plugin name (without `@plugin/` prefix)
+ * @returns The plugin data or undefined if not set
+ */
+function getPluginData(storage, pluginName) {
+    const key = `@plugin/${pluginName}`;
+    return storage[key];
+}
+/**
+ * Sets plugin-specific data in BlockStorage (immutable)
+ *
+ * @param storage - The current BlockStorage
+ * @param pluginName - The plugin name (without `@plugin/` prefix)
+ * @param data - The plugin data to store
+ * @returns A new BlockStorage with updated plugin data
+ */
+function setPluginData(storage, pluginName, data) {
+    const key = `@plugin/${pluginName}`;
+    return { ...storage, [key]: data };
+}
+/**
+ * Removes plugin-specific data from BlockStorage (immutable)
+ *
+ * @param storage - The current BlockStorage
+ * @param pluginName - The plugin name (without `@plugin/` prefix)
+ * @returns A new BlockStorage with the plugin data removed
+ */
+function removePluginData(storage, pluginName) {
+    const key = `@plugin/${pluginName}`;
+    const { [key]: _, ...rest } = storage;
+    return rest;
+}
+/**
+ * Gets all plugin names that have data stored
+ *
+ * @param storage - The BlockStorage instance
+ * @returns Array of plugin names (without `@plugin/` prefix)
+ */
+function getPluginNames(storage) {
+    return Object.keys(storage)
+        .filter((key) => key.startsWith('@plugin/'))
+        .map((key) => key.slice('@plugin/'.length));
+}
+// =============================================================================
+// Generic Storage Access
+// =============================================================================
+/**
+ * Gets a value from BlockStorage by key
+ *
+ * @param storage - The BlockStorage instance
+ * @param key - The key to retrieve
+ * @returns The value at the given key
+ */
+function getFromStorage(storage, key) {
+    return storage[key];
+}
+/**
+ * Updates a value in BlockStorage by key (immutable)
+ *
+ * @param storage - The current BlockStorage
+ * @param key - The key to update
+ * @param value - The new value
+ * @returns A new BlockStorage with the updated value
+ */
+function updateStorage(storage, key, value) {
+    return { ...storage, [key]: value };
+}
+/**
+ * Default implementations of storage handlers
+ */
+const defaultBlockStorageHandlers = {
+    transformStateForStorage: (storage, newState) => updateStorageData(storage, { operation: 'update-data', value: newState }),
+    deriveStateForArgs: (storage) => getStorageData(storage),
+    migrateStorage: (storage, _fromVersion, toVersion) => updateStorageDataVersion(storage, toVersion),
+};
+/**
+ * Merges custom handlers with defaults
+ *
+ * @param customHandlers - Custom handlers to merge
+ * @returns Complete handlers with defaults for missing functions
+ */
+function mergeBlockStorageHandlers(customHandlers) {
+    return {
+        ...defaultBlockStorageHandlers,
+        ...customHandlers,
+    };
+}
+
+exports.BLOCK_STORAGE_KEY = BLOCK_STORAGE_KEY;
+exports.BLOCK_STORAGE_SCHEMA_VERSION = BLOCK_STORAGE_SCHEMA_VERSION;
+exports.createBlockStorage = createBlockStorage;
+exports.defaultBlockStorageHandlers = defaultBlockStorageHandlers;
+exports.deriveDataFromStorage = deriveDataFromStorage;
+exports.getFromStorage = getFromStorage;
+exports.getPluginData = getPluginData;
+exports.getPluginNames = getPluginNames;
+exports.getStorageData = getStorageData;
+exports.getStorageDataVersion = getStorageDataVersion;
+exports.isBlockStorage = isBlockStorage;
+exports.mergeBlockStorageHandlers = mergeBlockStorageHandlers;
+exports.normalizeBlockStorage = normalizeBlockStorage;
+exports.removePluginData = removePluginData;
+exports.setPluginData = setPluginData;
+exports.updateStorage = updateStorage;
+exports.updateStorageData = updateStorageData;
+exports.updateStorageDataVersion = updateStorageDataVersion;
+//# sourceMappingURL=block_storage.cjs.map

package/dist/block_storage.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"block_storage.cjs","sources":["../src/block_storage.ts"],"sourcesContent":["/**\n * BlockStorage - Typed storage abstraction for block persistent data.\n *\n * This module provides:\n * - A typed structure for block storage with versioning and plugin support\n * - Utility functions for manipulating storage\n * - Handler interfaces for model-level customization\n *\n * @module block_storage\n */\n\n// =============================================================================\n// Core Types\n// =============================================================================\n\n/**\n * Discriminator key for BlockStorage format detection.\n * This unique hash-based key identifies data as BlockStorage vs legacy formats.\n */\nexport const BLOCK_STORAGE_KEY = '__pl_a7f3e2b9__';\n\n/**\n * Current BlockStorage schema version.\n * Increment this when the storage structure itself changes (not block state migrations).\n */\nexport const BLOCK_STORAGE_SCHEMA_VERSION = 'v1';\n\n/**\n * Type for valid schema versions\n */\nexport type BlockStorageSchemaVersion = 'v1'; // Add 'v2', 'v3', etc. as schema evolves\n\n/**\n * Plugin key type - keys starting with `@plugin/` are reserved for plugin data\n */\nexport type PluginKey = `@plugin/${string}`;\n\n/**\n * Core BlockStorage type that holds:\n * - __pl_a7f3e2b9__: Schema version (discriminator key identifies BlockStorage format)\n * - __dataVersion: Version number for block data migrations\n * - __data: The block's user-facing data (state)\n * - @plugin/*: Optional plugin-specific data\n */\nexport type BlockStorage<TState = unknown> = {\n  /** Schema version - the key itself is the discriminator */\n  readonly [BLOCK_STORAGE_KEY]: BlockStorageSchemaVersion;\n  /** Version of the block data, used for migrations */\n  __dataVersion: number;\n  /** The block's user-facing data (state) */\n  __data: TState;\n} & {\n  /** Plugin-specific data, keyed by `@plugin/<pluginName>` */\n  [K in PluginKey]?: unknown;\n};\n\n/**\n * Type guard to check if a value is a valid BlockStorage object.\n * Checks for the discriminator key and valid schema version.\n */\nexport function isBlockStorage(value: unknown): value is BlockStorage {\n  if (value === null || typeof value !== 'object') return false;\n  const obj = value as Record<string, unknown>;\n  const schemaVersion = obj[BLOCK_STORAGE_KEY];\n  // Currently only 'v1' is valid, but this allows future versions\n  return schemaVersion === 'v1'; // Add more versions as schema evolves\n}\n\n// =============================================================================\n// Factory Functions\n// =============================================================================\n\n/**\n * Creates a BlockStorage with the given initial data\n *\n * @param initialData - The initial data value (defaults to empty object)\n * @param version - The initial data version (defaults to 1)\n * @returns A new BlockStorage instance with discriminator key\n */\nexport function createBlockStorage<TState = unknown>(\n  initialData: TState = {} as TState,\n  version: number = 1,\n): BlockStorage<TState> {\n  return {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: version,\n    __data: initialData,\n  };\n}\n\n/**\n * Normalizes raw storage data to BlockStorage format.\n * If the input is already a BlockStorage, returns it as-is.\n * If the input is legacy format (raw state), wraps it in BlockStorage structure.\n *\n * @param raw - Raw storage data (may be legacy format or BlockStorage)\n * @returns Normalized BlockStorage\n */\nexport function normalizeBlockStorage<TState = unknown>(raw: unknown): BlockStorage<TState> {\n  if (isBlockStorage(raw)) {\n    return raw as BlockStorage<TState>;\n  }\n  // Legacy format: raw is the state directly\n  return createBlockStorage(raw as TState, 1);\n}\n\n// =============================================================================\n// Data Access & Update Functions\n// =============================================================================\n\n/**\n * Gets the data from BlockStorage\n *\n * @param storage - The BlockStorage instance\n * @returns The data value\n */\nexport function getStorageData<TState>(storage: BlockStorage<TState>): TState {\n  return storage.__data;\n}\n\n/**\n * Derives data from raw block storage.\n * This function is meant to be called from sdk/ui-vue to extract\n * user-facing data from the raw storage returned by the middle layer.\n *\n * The middle layer returns raw storage (opaque to it), and the UI\n * uses this function to derive the actual data value.\n *\n * @param rawStorage - Raw storage data from middle layer (may be any format)\n * @returns The extracted data value, or undefined if storage is undefined/null\n */\nexport function deriveDataFromStorage<TData = unknown>(\n  rawStorage: unknown,\n): TData {\n  // Normalize to BlockStorage format (handles legacy formats too)\n  const storage = normalizeBlockStorage<TData>(rawStorage);\n  return getStorageData(storage);\n}\n\n/** Payload for storage mutation operations. SDK defines specific operations. */\nexport type MutateStoragePayload<T = unknown> = { operation: 'update-data'; value: T };\n\n/**\n * Updates the data in BlockStorage (immutable)\n *\n * @param storage - The current BlockStorage\n * @param payload - The update payload with operation and value\n * @returns A new BlockStorage with updated data\n */\nexport function updateStorageData<TValue = unknown>(\n  storage: BlockStorage<TValue>,\n  payload: MutateStoragePayload<TValue>,\n): BlockStorage<TValue> {\n  switch (payload.operation) {\n    case 'update-data':\n      return { ...storage, __data: payload.value };\n    default:\n      throw new Error(`Unknown storage operation: ${(payload as { operation: string }).operation}`);\n  }\n}\n\n/**\n * Gets the data version from BlockStorage\n *\n * @param storage - The BlockStorage instance\n * @returns The data version number\n */\nexport function getStorageDataVersion(storage: BlockStorage): number {\n  return storage.__dataVersion;\n}\n\n/**\n * Updates the data version in BlockStorage (immutable)\n *\n * @param storage - The current BlockStorage\n * @param version - The new version number\n * @returns A new BlockStorage with updated version\n */\nexport function updateStorageDataVersion<TState>(\n  storage: BlockStorage<TState>,\n  version: number,\n): BlockStorage<TState> {\n  return { ...storage, __dataVersion: version };\n}\n\n// =============================================================================\n// Plugin Data Functions\n// =============================================================================\n\n/**\n * Gets plugin-specific data from BlockStorage\n *\n * @param storage - The BlockStorage instance\n * @param pluginName - The plugin name (without `@plugin/` prefix)\n * @returns The plugin data or undefined if not set\n */\nexport function getPluginData<TData = unknown>(\n  storage: BlockStorage,\n  pluginName: string,\n): TData | undefined {\n  const key: PluginKey = `@plugin/${pluginName}`;\n  return storage[key] as TData | undefined;\n}\n\n/**\n * Sets plugin-specific data in BlockStorage (immutable)\n *\n * @param storage - The current BlockStorage\n * @param pluginName - The plugin name (without `@plugin/` prefix)\n * @param data - The plugin data to store\n * @returns A new BlockStorage with updated plugin data\n */\nexport function setPluginData<TState>(\n  storage: BlockStorage<TState>,\n  pluginName: string,\n  data: unknown,\n): BlockStorage<TState> {\n  const key: PluginKey = `@plugin/${pluginName}`;\n  return { ...storage, [key]: data };\n}\n\n/**\n * Removes plugin-specific data from BlockStorage (immutable)\n *\n * @param storage - The current BlockStorage\n * @param pluginName - The plugin name (without `@plugin/` prefix)\n * @returns A new BlockStorage with the plugin data removed\n */\nexport function removePluginData<TState>(\n  storage: BlockStorage<TState>,\n  pluginName: string,\n): BlockStorage<TState> {\n  const key: PluginKey = `@plugin/${pluginName}`;\n  const { [key]: _, ...rest } = storage;\n  return rest as BlockStorage<TState>;\n}\n\n/**\n * Gets all plugin names that have data stored\n *\n * @param storage - The BlockStorage instance\n * @returns Array of plugin names (without `@plugin/` prefix)\n */\nexport function getPluginNames(storage: BlockStorage): string[] {\n  return Object.keys(storage)\n    .filter((key): key is PluginKey => key.startsWith('@plugin/'))\n    .map((key) => key.slice('@plugin/'.length));\n}\n\n// =============================================================================\n// Generic Storage Access\n// =============================================================================\n\n/**\n * Gets a value from BlockStorage by key\n *\n * @param storage - The BlockStorage instance\n * @param key - The key to retrieve\n * @returns The value at the given key\n */\nexport function getFromStorage<\n  TState,\n  K extends keyof BlockStorage<TState>,\n>(storage: BlockStorage<TState>, key: K): BlockStorage<TState>[K] {\n  return storage[key];\n}\n\n/**\n * Updates a value in BlockStorage by key (immutable)\n *\n * @param storage - The current BlockStorage\n * @param key - The key to update\n * @param value - The new value\n * @returns A new BlockStorage with the updated value\n */\nexport function updateStorage<\n  TState,\n  K extends keyof BlockStorage<TState>,\n>(\n  storage: BlockStorage<TState>,\n  key: K,\n  value: BlockStorage<TState>[K],\n): BlockStorage<TState> {\n  return { ...storage, [key]: value };\n}\n\n// =============================================================================\n// Storage Handlers (for Phase 2 - Model-Level Customization)\n// =============================================================================\n\n/**\n * Interface for model-configurable storage operations.\n * These handlers allow block models to customize how storage is managed.\n */\nexport interface BlockStorageHandlers<TState = unknown> {\n  /**\n   * Called when setState is invoked - transforms the new state before storing.\n   * Default behavior: replaces the state directly.\n   *\n   * @param currentStorage - The current BlockStorage\n   * @param newState - The new state being set\n   * @returns The updated BlockStorage\n   */\n  transformStateForStorage?: (\n    currentStorage: BlockStorage<TState>,\n    newState: TState,\n  ) => BlockStorage<TState>;\n\n  /**\n   * Called when reading state for args derivation.\n   * Default behavior: returns the state directly.\n   *\n   * @param storage - The current BlockStorage\n   * @returns The state to use for args derivation\n   */\n  deriveStateForArgs?: (storage: BlockStorage<TState>) => TState;\n\n  /**\n   * Called during storage schema migration.\n   * Default behavior: updates stateVersion only.\n   *\n   * @param oldStorage - The storage before migration\n   * @param fromVersion - The version migrating from\n   * @param toVersion - The version migrating to\n   * @returns The migrated BlockStorage\n   */\n  migrateStorage?: (\n    oldStorage: BlockStorage<TState>,\n    fromVersion: number,\n    toVersion: number,\n  ) => BlockStorage<TState>;\n}\n\n/**\n * Default implementations of storage handlers\n */\nexport const defaultBlockStorageHandlers: Required<BlockStorageHandlers<unknown>> = {\n  transformStateForStorage: <TState>(\n    storage: BlockStorage<TState>,\n    newState: TState,\n  ): BlockStorage<TState> => updateStorageData(storage, { operation: 'update-data', value: newState }),\n\n  deriveStateForArgs: <TState>(storage: BlockStorage<TState>): TState => getStorageData(storage),\n\n  migrateStorage: <TState>(\n    storage: BlockStorage<TState>,\n    _fromVersion: number,\n    toVersion: number,\n  ): BlockStorage<TState> => updateStorageDataVersion(storage, toVersion),\n};\n\n/**\n * Merges custom handlers with defaults\n *\n * @param customHandlers - Custom handlers to merge\n * @returns Complete handlers with defaults for missing functions\n */\nexport function mergeBlockStorageHandlers<TState>(\n  customHandlers?: BlockStorageHandlers<TState>,\n): Required<BlockStorageHandlers<TState>> {\n  return {\n    ...defaultBlockStorageHandlers,\n    ...customHandlers,\n  } as Required<BlockStorageHandlers<TState>>;\n}\n"],"names":[],"mappings":"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"}

package/dist/block_storage.d.ts

@@ -0,0 +1,208 @@
+/**
+ * BlockStorage - Typed storage abstraction for block persistent data.
+ *
+ * This module provides:
+ * - A typed structure for block storage with versioning and plugin support
+ * - Utility functions for manipulating storage
+ * - Handler interfaces for model-level customization
+ *
+ * @module block_storage
+ */
+/**
+ * Discriminator key for BlockStorage format detection.
+ * This unique hash-based key identifies data as BlockStorage vs legacy formats.
+ */
+export declare const BLOCK_STORAGE_KEY = "__pl_a7f3e2b9__";
+/**
+ * Current BlockStorage schema version.
+ * Increment this when the storage structure itself changes (not block state migrations).
+ */
+export declare const BLOCK_STORAGE_SCHEMA_VERSION = "v1";
+/**
+ * Type for valid schema versions
+ */
+export type BlockStorageSchemaVersion = 'v1';
+/**
+ * Plugin key type - keys starting with `@plugin/` are reserved for plugin data
+ */
+export type PluginKey = `@plugin/${string}`;
+/**
+ * Core BlockStorage type that holds:
+ * - __pl_a7f3e2b9__: Schema version (discriminator key identifies BlockStorage format)
+ * - __dataVersion: Version number for block data migrations
+ * - __data: The block's user-facing data (state)
+ * - @plugin/*: Optional plugin-specific data
+ */
+export type BlockStorage<TState = unknown> = {
+    /** Schema version - the key itself is the discriminator */
+    readonly [BLOCK_STORAGE_KEY]: BlockStorageSchemaVersion;
+    /** Version of the block data, used for migrations */
+    __dataVersion: number;
+    /** The block's user-facing data (state) */
+    __data: TState;
+} & {
+    [K in PluginKey]?: unknown;
+};
+/**
+ * Type guard to check if a value is a valid BlockStorage object.
+ * Checks for the discriminator key and valid schema version.
+ */
+export declare function isBlockStorage(value: unknown): value is BlockStorage;
+/**
+ * Creates a BlockStorage with the given initial data
+ *
+ * @param initialData - The initial data value (defaults to empty object)
+ * @param version - The initial data version (defaults to 1)
+ * @returns A new BlockStorage instance with discriminator key
+ */
+export declare function createBlockStorage<TState = unknown>(initialData?: TState, version?: number): BlockStorage<TState>;
+/**
+ * Normalizes raw storage data to BlockStorage format.
+ * If the input is already a BlockStorage, returns it as-is.
+ * If the input is legacy format (raw state), wraps it in BlockStorage structure.
+ *
+ * @param raw - Raw storage data (may be legacy format or BlockStorage)
+ * @returns Normalized BlockStorage
+ */
+export declare function normalizeBlockStorage<TState = unknown>(raw: unknown): BlockStorage<TState>;
+/**
+ * Gets the data from BlockStorage
+ *
+ * @param storage - The BlockStorage instance
+ * @returns The data value
+ */
+export declare function getStorageData<TState>(storage: BlockStorage<TState>): TState;
+/**
+ * Derives data from raw block storage.
+ * This function is meant to be called from sdk/ui-vue to extract
+ * user-facing data from the raw storage returned by the middle layer.
+ *
+ * The middle layer returns raw storage (opaque to it), and the UI
+ * uses this function to derive the actual data value.
+ *
+ * @param rawStorage - Raw storage data from middle layer (may be any format)
+ * @returns The extracted data value, or undefined if storage is undefined/null
+ */
+export declare function deriveDataFromStorage<TData = unknown>(rawStorage: unknown): TData;
+/** Payload for storage mutation operations. SDK defines specific operations. */
+export type MutateStoragePayload<T = unknown> = {
+    operation: 'update-data';
+    value: T;
+};
+/**
+ * Updates the data in BlockStorage (immutable)
+ *
+ * @param storage - The current BlockStorage
+ * @param payload - The update payload with operation and value
+ * @returns A new BlockStorage with updated data
+ */
+export declare function updateStorageData<TValue = unknown>(storage: BlockStorage<TValue>, payload: MutateStoragePayload<TValue>): BlockStorage<TValue>;
+/**
+ * Gets the data version from BlockStorage
+ *
+ * @param storage - The BlockStorage instance
+ * @returns The data version number
+ */
+export declare function getStorageDataVersion(storage: BlockStorage): number;
+/**
+ * Updates the data version in BlockStorage (immutable)
+ *
+ * @param storage - The current BlockStorage
+ * @param version - The new version number
+ * @returns A new BlockStorage with updated version
+ */
+export declare function updateStorageDataVersion<TState>(storage: BlockStorage<TState>, version: number): BlockStorage<TState>;
+/**
+ * Gets plugin-specific data from BlockStorage
+ *
+ * @param storage - The BlockStorage instance
+ * @param pluginName - The plugin name (without `@plugin/` prefix)
+ * @returns The plugin data or undefined if not set
+ */
+export declare function getPluginData<TData = unknown>(storage: BlockStorage, pluginName: string): TData | undefined;
+/**
+ * Sets plugin-specific data in BlockStorage (immutable)
+ *
+ * @param storage - The current BlockStorage
+ * @param pluginName - The plugin name (without `@plugin/` prefix)
+ * @param data - The plugin data to store
+ * @returns A new BlockStorage with updated plugin data
+ */
+export declare function setPluginData<TState>(storage: BlockStorage<TState>, pluginName: string, data: unknown): BlockStorage<TState>;
+/**
+ * Removes plugin-specific data from BlockStorage (immutable)
+ *
+ * @param storage - The current BlockStorage
+ * @param pluginName - The plugin name (without `@plugin/` prefix)
+ * @returns A new BlockStorage with the plugin data removed
+ */
+export declare function removePluginData<TState>(storage: BlockStorage<TState>, pluginName: string): BlockStorage<TState>;
+/**
+ * Gets all plugin names that have data stored
+ *
+ * @param storage - The BlockStorage instance
+ * @returns Array of plugin names (without `@plugin/` prefix)
+ */
+export declare function getPluginNames(storage: BlockStorage): string[];
+/**
+ * Gets a value from BlockStorage by key
+ *
+ * @param storage - The BlockStorage instance
+ * @param key - The key to retrieve
+ * @returns The value at the given key
+ */
+export declare function getFromStorage<TState, K extends keyof BlockStorage<TState>>(storage: BlockStorage<TState>, key: K): BlockStorage<TState>[K];
+/**
+ * Updates a value in BlockStorage by key (immutable)
+ *
+ * @param storage - The current BlockStorage
+ * @param key - The key to update
+ * @param value - The new value
+ * @returns A new BlockStorage with the updated value
+ */
+export declare function updateStorage<TState, K extends keyof BlockStorage<TState>>(storage: BlockStorage<TState>, key: K, value: BlockStorage<TState>[K]): BlockStorage<TState>;
+/**
+ * Interface for model-configurable storage operations.
+ * These handlers allow block models to customize how storage is managed.
+ */
+export interface BlockStorageHandlers<TState = unknown> {
+    /**
+     * Called when setState is invoked - transforms the new state before storing.
+     * Default behavior: replaces the state directly.
+     *
+     * @param currentStorage - The current BlockStorage
+     * @param newState - The new state being set
+     * @returns The updated BlockStorage
+     */
+    transformStateForStorage?: (currentStorage: BlockStorage<TState>, newState: TState) => BlockStorage<TState>;
+    /**
+     * Called when reading state for args derivation.
+     * Default behavior: returns the state directly.
+     *
+     * @param storage - The current BlockStorage
+     * @returns The state to use for args derivation
+     */
+    deriveStateForArgs?: (storage: BlockStorage<TState>) => TState;
+    /**
+     * Called during storage schema migration.
+     * Default behavior: updates stateVersion only.
+     *
+     * @param oldStorage - The storage before migration
+     * @param fromVersion - The version migrating from
+     * @param toVersion - The version migrating to
+     * @returns The migrated BlockStorage
+     */
+    migrateStorage?: (oldStorage: BlockStorage<TState>, fromVersion: number, toVersion: number) => BlockStorage<TState>;
+}
+/**
+ * Default implementations of storage handlers
+ */
+export declare const defaultBlockStorageHandlers: Required<BlockStorageHandlers<unknown>>;
+/**
+ * Merges custom handlers with defaults
+ *
+ * @param customHandlers - Custom handlers to merge
+ * @returns Complete handlers with defaults for missing functions
+ */
+export declare function mergeBlockStorageHandlers<TState>(customHandlers?: BlockStorageHandlers<TState>): Required<BlockStorageHandlers<TState>>;
+//# sourceMappingURL=block_storage.d.ts.map

package/dist/block_storage.d.ts.map

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