@platforma-sdk/model 1.51.9 → 1.52.0

package/dist/bconfig/lambdas.d.ts

@@ -1,10 +1,14 @@
 import type { ConfigResult, PlResourceEntry, TypedConfig } from '../config';
-export type StdCtxArgsOnly<Args, UiState = undefined> = {
+import type { OutputWithStatus } from '@milaboratories/pl-model-common';
+import type { TypedConfigOrConfigLambda } from './types';
+export type StdCtxArgsOnly<Args, Data = undefined> = {
     readonly $blockId: string;
     readonly $args: Args;
-    readonly $ui: UiState;
+    /** @deprecated Use $data instead. Kept for V1/V2 block compatibility. */
+    readonly $ui: Data;
+    readonly $data: Data;
 };
-export type StdCtx<Args, UiState = undefined> = StdCtxArgsOnly<Args, UiState> & {
+export type StdCtx<Args, Data = undefined> = StdCtxArgsOnly<Args, Data> & {
     readonly $prod: PlResourceEntry;
     readonly $staging: PlResourceEntry;
 };
@@ -13,7 +17,7 @@ export type ResolveCfgType<Cfg extends TypedConfig, Args, UiState = undefined> =
 export type ConfigRenderLambdaFlags = {
     /**
      * Tells the system that corresponding computable should be created with StableOnlyRetentive rendering mode.
-     * This flag can be overriden by the system.
+     * This flag can be overridden by the system.
      * */
     retentive?: boolean;
     /**
@@ -37,4 +41,22 @@ export interface ConfigRenderLambda<Return = unknown> extends ConfigRenderLambda
     handle: string;
 }
 export type ExtractFunctionHandleReturn<Func extends ConfigRenderLambda> = Func extends ConfigRenderLambda<infer Return> ? Return : never;
+/** Infers the output type from a TypedConfig or ConfigRenderLambda */
+export type InferOutputType<CfgOrFH, Args, UiState> = CfgOrFH extends TypedConfig ? ResolveCfgType<CfgOrFH, Args, UiState> : CfgOrFH extends ConfigRenderLambda ? ExtractFunctionHandleReturn<CfgOrFH> : never;
+/** Maps outputs configuration to inferred output types with status wrapper */
+export type InferOutputsFromConfigs<Args, OutputsCfg extends Record<string, TypedConfigOrConfigLambda>, UiState> = {
+    [Key in keyof OutputsCfg]: OutputWithStatus<InferOutputType<OutputsCfg[Key], Args, UiState>> & {
+        __unwrap: (OutputsCfg[Key] extends {
+            withStatus: true;
+        } ? false : true);
+    };
+};
+/** Maps lambda-only outputs configuration to inferred output types (for V3 blocks) */
+export type InferOutputsFromLambdas<OutputsCfg extends Record<string, ConfigRenderLambda>> = {
+    [Key in keyof OutputsCfg]: OutputWithStatus<ExtractFunctionHandleReturn<OutputsCfg[Key]>> & {
+        __unwrap: (OutputsCfg[Key] extends {
+            withStatus: true;
+        } ? false : true);
+    };
+};
 //# sourceMappingURL=lambdas.d.ts.map

package/dist/bconfig/lambdas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lambdas.d.ts","sourceRoot":"","sources":["../../src/bconfig/lambdas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE5E,MAAM,MAAM,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,IAAI;IACtD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,IAAI,cAAc,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG;IAC9E,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,cAAc,CAAC,GAAG,SAAS,WAAW,EAAE,IAAI,EAAE,OAAO,GAAG,SAAS,IAAI,YAAY,CAC3F,GAAG,EACH,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CACtB,CAAC;AAEF,wEAAwE;AACxE,MAAM,MAAM,uBAAuB,GAAG;IACpC;;;SAGK;IACL,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;SAGK;IACL,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF,+BAA+B;AAC/B,MAAM,WAAW,kBAAkB,CAAC,MAAM,GAAG,OAAO,CAAE,SAAQ,uBAAuB;IACnF,kBAAkB;IAClB,cAAc,EAAE,IAAI,CAAC;IAErB,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,2BAA2B,CAAC,IAAI,SAAS,kBAAkB,IACrE,IAAI,SAAS,kBAAkB,CAAC,MAAM,MAAM,CAAC,GAAG,MAAM,GAAG,KAAK,CAAC"}
+{"version":3,"file":"lambdas.d.ts","sourceRoot":"","sources":["../../src/bconfig/lambdas.ts"],"names":[],"mappings":"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"}

package/dist/bconfig/v3.d.ts

@@ -1,6 +1,8 @@
-import type { BlockConfigV3Generic } from '@milaboratories/pl-model-common';
+import type { BlockConfigV3Generic, BlockConfigV4Generic } from '@milaboratories/pl-model-common';
 import type { TypedConfigOrConfigLambda } from './types';
 import type { ConfigRenderLambda } from './lambdas';
 export type BlockConfigV3<Args = unknown, UiState = unknown, Outputs extends Record<string, TypedConfigOrConfigLambda> = Record<string, TypedConfigOrConfigLambda>> = BlockConfigV3Generic<Args, UiState, TypedConfigOrConfigLambda, ConfigRenderLambda, Outputs>;
-export type BlockConfig = BlockConfigV3;
+export type BlockConfigV4<Args = unknown, Data extends Record<string, unknown> = Record<string, unknown>, Outputs extends Record<string, TypedConfigOrConfigLambda> = Record<string, TypedConfigOrConfigLambda>> = BlockConfigV4Generic<Args, Data, TypedConfigOrConfigLambda, ConfigRenderLambda, Outputs>;
+/** Union of all block config versions with discriminator for type narrowing */
+export type BlockConfig = BlockConfigV3 | BlockConfigV4;
 //# sourceMappingURL=v3.d.ts.map

package/dist/bconfig/v3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"v3.d.ts","sourceRoot":"","sources":["../../src/bconfig/v3.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAC5E,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAEpD,MAAM,MAAM,aAAa,CACvB,IAAI,GAAG,OAAO,EACd,OAAO,GAAG,OAAO,EACjB,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,GAAG,MAAM,CAChE,MAAM,EACN,yBAAyB,CAC1B,IACC,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,OAAO,CAAC,CAAC;AAEhG,MAAM,MAAM,WAAW,GAAG,aAAa,CAAC"}
+{"version":3,"file":"v3.d.ts","sourceRoot":"","sources":["../../src/bconfig/v3.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAClG,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAEpD,MAAM,MAAM,aAAa,CACvB,IAAI,GAAG,OAAO,EACd,OAAO,GAAG,OAAO,EACjB,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,GAAG,MAAM,CAChE,MAAM,EACN,yBAAyB,CAC1B,IACC,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,OAAO,CAAC,CAAC;AAEhG,MAAM,MAAM,aAAa,CACvB,IAAI,GAAG,OAAO,EACd,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9D,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,GAAG,MAAM,CAChE,MAAM,EACN,yBAAyB,CAC1B,IACC,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,OAAO,CAAC,CAAC;AAE7F,+EAA+E;AAC/E,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,aAAa,CAAC"}

package/dist/block_api_v3.d.ts

@@ -0,0 +1,32 @@
+import type { BlockOutputsBase, NavigationState, ValueWithUTag, ValueWithUTagAndAuthor, AuthorMarker, ResultOrError, BlockStateV3 } from '@milaboratories/pl-model-common';
+import type { Operation } from 'fast-json-patch';
+import type { MutateStoragePayload } from './block_storage';
+/** Defines methods to read and write current block data. */
+export interface BlockApiV3<_Args = unknown, Outputs extends BlockOutputsBase = BlockOutputsBase, _Data = unknown, Href extends `/${string}` = `/${string}`> {
+    /**
+     * Use this method to retrieve block state during UI initialization. Then use
+     * {@link onStateUpdates} method to subscribe for updates.
+     * */
+    loadBlockState(): Promise<ResultOrError<ValueWithUTag<BlockStateV3<Outputs, _Data, Href>>>>;
+    /**
+     * Get all json patches (rfc6902) that were applied to the block state.
+     * */
+    getPatches(uTag: string): Promise<ResultOrError<ValueWithUTagAndAuthor<Operation[]>>>;
+    /**
+     * Mutates block storage with the given operation.
+     *
+     * This method returns when the data is safely saved so in case the window is
+     * closed there will be no information losses. This function under the hood
+     * may delay actual persistence of the supplied values.
+     * */
+    mutateStorage(payload: MutateStoragePayload, author?: AuthorMarker): Promise<ResultOrError<void>>;
+    /**
+     * Sets block navigation state.
+     * */
+    setNavigationState(state: NavigationState<Href>): Promise<ResultOrError<void>>;
+    /**
+     * Disposes the block API.
+     * */
+    dispose(): Promise<ResultOrError<void>>;
+}
+//# sourceMappingURL=block_api_v3.d.ts.map

package/dist/block_api_v3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block_api_v3.d.ts","sourceRoot":"","sources":["../src/block_api_v3.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,sBAAsB,EACtB,YAAY,EACZ,aAAa,EACb,YAAY,EACb,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,4DAA4D;AAC5D,MAAM,WAAW,UAAU,CACzB,KAAK,GAAG,OAAO,EACf,OAAO,SAAS,gBAAgB,GAAG,gBAAgB,EACnD,KAAK,GAAG,OAAO,EACf,IAAI,SAAS,IAAI,MAAM,EAAE,GAAG,IAAI,MAAM,EAAE;IAExC;;;SAGK;IACL,cAAc,IAAI,OAAO,CAAC,aAAa,CAAC,aAAa,CAAC,YAAY,CAAC,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAE5F;;SAEK;IACL,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,sBAAsB,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC;IAEtF;;;;;;SAMK;IACL,aAAa,CAAC,OAAO,EAAE,oBAAoB,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC;IAElG;;SAEK;IACL,kBAAkB,CAAC,KAAK,EAAE,eAAe,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC;IAE/E;;SAEK;IACL,OAAO,IAAI,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC;CACzC"}

package/dist/block_migrations.cjs

@@ -0,0 +1,138 @@
+'use strict';
+
+var internal = require('./internal.cjs');
+var block_storage = require('./block_storage.cjs');
+
+/** Internal builder for chaining migrations */
+class DataModelBuilder {
+    migrationSteps;
+    constructor(steps = []) {
+        this.migrationSteps = steps;
+    }
+    /** Start a migration chain from an initial type */
+    static from() {
+        return new DataModelBuilder();
+    }
+    /** Add a migration step */
+    migrate(fn) {
+        return new DataModelBuilder([...this.migrationSteps, fn]);
+    }
+    /** Finalize with initial data, creating the DataModel */
+    create(initialData, ..._) {
+        return DataModel._fromBuilder(this.migrationSteps, initialData);
+    }
+}
+/**
+ * DataModel defines the block's data structure, initial values, and migrations.
+ * Used by BlockModelV3 to manage data state.
+ *
+ * @example
+ * // Simple data model (no migrations)
+ * const dataModel = DataModel.create<BlockData>(() => ({
+ *   numbers: [],
+ *   labels: [],
+ * }));
+ *
+ * // Data model with migrations
+ * const dataModel = DataModel
+ *   .from<V1>()
+ *   .migrate((data) => ({ ...data, labels: [] }))  // v1 → v2
+ *   .migrate((data) => ({ ...data, description: '' }))  // v2 → v3
+ *   .create<BlockData>(() => ({ numbers: [], labels: [], description: '' }));
+ */
+class DataModel {
+    steps;
+    _initialData;
+    constructor(steps, initialData) {
+        this.steps = steps;
+        this._initialData = initialData;
+    }
+    /** Start a migration chain from an initial type */
+    static from() {
+        return DataModelBuilder.from();
+    }
+    /** Create a data model with just initial data (no migrations) */
+    static create(initialData) {
+        return new DataModel([], initialData);
+    }
+    /** Create from builder (internal use) */
+    static _fromBuilder(steps, initialData) {
+        return new DataModel(steps, initialData);
+    }
+    /**
+     * Latest version number.
+     * Version 1 = initial state, each migration adds 1.
+     */
+    get version() {
+        return this.steps.length + 1;
+    }
+    /** Number of migration steps */
+    get migrationCount() {
+        return this.steps.length;
+    }
+    /** Get initial data */
+    initialData() {
+        return this._initialData();
+    }
+    /** Get default data wrapped with current version */
+    getDefaultData() {
+        return { version: this.version, data: this._initialData() };
+    }
+    /**
+     * Upgrade versioned data from any version to the latest.
+     * Applies only the migrations needed (skips already-applied ones).
+     * If a migration fails, returns default data with a warning.
+     */
+    upgrade(versioned) {
+        const { version: fromVersion, data } = versioned;
+        if (fromVersion > this.version) {
+            throw new Error(`Cannot downgrade from version ${fromVersion} to ${this.version}`);
+        }
+        if (fromVersion === this.version) {
+            return { version: this.version, data: data };
+        }
+        // Apply migrations starting from (fromVersion - 1) index
+        // Version 1 -> no migrations applied yet -> start at index 0
+        // Version 2 -> migration[0] already applied -> start at index 1
+        const startIndex = fromVersion - 1;
+        const migrationsToApply = this.steps.slice(startIndex);
+        let currentData = data;
+        for (let i = 0; i < migrationsToApply.length; i++) {
+            const stepIndex = startIndex + i;
+            const fromVer = stepIndex + 1;
+            const toVer = stepIndex + 2;
+            try {
+                currentData = migrationsToApply[i](currentData);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                return {
+                    ...this.getDefaultData(),
+                    warning: `Migration v${fromVer}→v${toVer} failed: ${errorMessage}`,
+                };
+            }
+        }
+        return { version: this.version, data: currentData };
+    }
+    /**
+     * Register callbacks for use in the VM.
+     * Called by BlockModelV3.create() to set up internal callbacks.
+     *
+     * All callbacks are prefixed with `__pl_` to indicate internal SDK use:
+     * - `__pl_data_initial`: returns initial data for new blocks
+     * - `__pl_data_upgrade`: upgrades versioned data from any version to latest
+     * - `__pl_storage_initial`: returns initial BlockStorage as JSON string
+     */
+    registerCallbacks() {
+        internal.tryRegisterCallback('__pl_data_initial', () => this._initialData());
+        internal.tryRegisterCallback('__pl_data_upgrade', (versioned) => this.upgrade(versioned));
+        internal.tryRegisterCallback('__pl_storage_initial', () => {
+            const { version, data } = this.getDefaultData();
+            const storage = block_storage.createBlockStorage(data, version);
+            return JSON.stringify(storage);
+        });
+    }
+}
+
+exports.DataModel = DataModel;
+//# sourceMappingURL=block_migrations.cjs.map

package/dist/block_migrations.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"block_migrations.cjs","sources":["../src/block_migrations.ts"],"sourcesContent":["import { tryRegisterCallback } from './internal';\nimport { createBlockStorage } from './block_storage';\n\nexport type MigrationFn<From, To> = (prev: Readonly<From>) => To;\n\n/** Versioned data wrapper for persistence */\nexport type Versioned<T> = {\n  version: number;\n  data: T;\n};\n\n/** Result of upgrade operation, may include warning if migration failed */\nexport type UpgradeResult<T> = Versioned<T> & {\n  warning?: string;\n};\n\n/** Internal builder for chaining migrations */\nclass DataModelBuilder<State> {\n  private readonly migrationSteps: Array<(x: unknown) => unknown>;\n\n  private constructor(steps: Array<(x: unknown) => unknown> = []) {\n    this.migrationSteps = steps;\n  }\n\n  /** Start a migration chain from an initial type */\n  static from<T = unknown>(): DataModelBuilder<T> {\n    return new DataModelBuilder<T>();\n  }\n\n  /** Add a migration step */\n  migrate<Next>(fn: MigrationFn<State, Next>): DataModelBuilder<Next> {\n    return new DataModelBuilder<Next>([...this.migrationSteps, fn as any]);\n  }\n\n  /** Finalize with initial data, creating the DataModel */\n  create<S>(\n    initialData: () => S,\n    ..._: [State] extends [S] ? [] : [never]\n  ): DataModel<S> {\n    return DataModel._fromBuilder<S>(this.migrationSteps, initialData);\n  }\n}\n\n/**\n * DataModel defines the block's data structure, initial values, and migrations.\n * Used by BlockModelV3 to manage data state.\n *\n * @example\n * // Simple data model (no migrations)\n * const dataModel = DataModel.create<BlockData>(() => ({\n *   numbers: [],\n *   labels: [],\n * }));\n *\n * // Data model with migrations\n * const dataModel = DataModel\n *   .from<V1>()\n *   .migrate((data) => ({ ...data, labels: [] }))  // v1 → v2\n *   .migrate((data) => ({ ...data, description: '' }))  // v2 → v3\n *   .create<BlockData>(() => ({ numbers: [], labels: [], description: '' }));\n */\nexport class DataModel<State> {\n  private readonly steps: Array<(x: unknown) => unknown>;\n  private readonly _initialData: () => State;\n\n  private constructor(steps: Array<(x: unknown) => unknown>, initialData: () => State) {\n    this.steps = steps;\n    this._initialData = initialData;\n  }\n\n  /** Start a migration chain from an initial type */\n  static from<S>(): DataModelBuilder<S> {\n    return DataModelBuilder.from<S>();\n  }\n\n  /** Create a data model with just initial data (no migrations) */\n  static create<S>(initialData: () => S): DataModel<S> {\n    return new DataModel<S>([], initialData);\n  }\n\n  /** Create from builder (internal use) */\n  static _fromBuilder<S>(\n    steps: Array<(x: unknown) => unknown>,\n    initialData: () => S,\n  ): DataModel<S> {\n    return new DataModel<S>(steps, initialData);\n  }\n\n  /**\n   * Latest version number.\n   * Version 1 = initial state, each migration adds 1.\n   */\n  get version(): number {\n    return this.steps.length + 1;\n  }\n\n  /** Number of migration steps */\n  get migrationCount(): number {\n    return this.steps.length;\n  }\n\n  /** Get initial data */\n  initialData(): State {\n    return this._initialData();\n  }\n\n  /** Get default data wrapped with current version */\n  getDefaultData(): Versioned<State> {\n    return { version: this.version, data: this._initialData() };\n  }\n\n  /**\n   * Upgrade versioned data from any version to the latest.\n   * Applies only the migrations needed (skips already-applied ones).\n   * If a migration fails, returns default data with a warning.\n   */\n  upgrade(versioned: Versioned<unknown>): UpgradeResult<State> {\n    const { version: fromVersion, data } = versioned;\n\n    if (fromVersion > this.version) {\n      throw new Error(\n        `Cannot downgrade from version ${fromVersion} to ${this.version}`,\n      );\n    }\n\n    if (fromVersion === this.version) {\n      return { version: this.version, data: data as State };\n    }\n\n    // Apply migrations starting from (fromVersion - 1) index\n    // Version 1 -> no migrations applied yet -> start at index 0\n    // Version 2 -> migration[0] already applied -> start at index 1\n    const startIndex = fromVersion - 1;\n    const migrationsToApply = this.steps.slice(startIndex);\n\n    let currentData: unknown = data;\n    for (let i = 0; i < migrationsToApply.length; i++) {\n      const stepIndex = startIndex + i;\n      const fromVer = stepIndex + 1;\n      const toVer = stepIndex + 2;\n      try {\n        currentData = migrationsToApply[i](currentData);\n      } catch (error) {\n        const errorMessage = error instanceof Error ? error.message : String(error);\n        return {\n          ...this.getDefaultData(),\n          warning: `Migration v${fromVer}→v${toVer} failed: ${errorMessage}`,\n        };\n      }\n    }\n\n    return { version: this.version, data: currentData as State };\n  }\n\n  /**\n   * Register callbacks for use in the VM.\n   * Called by BlockModelV3.create() to set up internal callbacks.\n   *\n   * All callbacks are prefixed with `__pl_` to indicate internal SDK use:\n   * - `__pl_data_initial`: returns initial data for new blocks\n   * - `__pl_data_upgrade`: upgrades versioned data from any version to latest\n   * - `__pl_storage_initial`: returns initial BlockStorage as JSON string\n   */\n  registerCallbacks(): void {\n    tryRegisterCallback('__pl_data_initial', () => this._initialData());\n    tryRegisterCallback('__pl_data_upgrade', (versioned: Versioned<unknown>) => this.upgrade(versioned));\n    tryRegisterCallback('__pl_storage_initial', () => {\n      const { version, data } = this.getDefaultData();\n      const storage = createBlockStorage(data, version);\n      return JSON.stringify(storage);\n    });\n  }\n}\n"],"names":["tryRegisterCallback","createBlockStorage"],"mappings":"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"}

package/dist/block_migrations.d.ts

@@ -0,0 +1,79 @@
+export type MigrationFn<From, To> = (prev: Readonly<From>) => To;
+/** Versioned data wrapper for persistence */
+export type Versioned<T> = {
+    version: number;
+    data: T;
+};
+/** Result of upgrade operation, may include warning if migration failed */
+export type UpgradeResult<T> = Versioned<T> & {
+    warning?: string;
+};
+/** Internal builder for chaining migrations */
+declare class DataModelBuilder<State> {
+    private readonly migrationSteps;
+    private constructor();
+    /** Start a migration chain from an initial type */
+    static from<T = unknown>(): DataModelBuilder<T>;
+    /** Add a migration step */
+    migrate<Next>(fn: MigrationFn<State, Next>): DataModelBuilder<Next>;
+    /** Finalize with initial data, creating the DataModel */
+    create<S>(initialData: () => S, ..._: [State] extends [S] ? [] : [never]): DataModel<S>;
+}
+/**
+ * DataModel defines the block's data structure, initial values, and migrations.
+ * Used by BlockModelV3 to manage data state.
+ *
+ * @example
+ * // Simple data model (no migrations)
+ * const dataModel = DataModel.create<BlockData>(() => ({
+ *   numbers: [],
+ *   labels: [],
+ * }));
+ *
+ * // Data model with migrations
+ * const dataModel = DataModel
+ *   .from<V1>()
+ *   .migrate((data) => ({ ...data, labels: [] }))  // v1 → v2
+ *   .migrate((data) => ({ ...data, description: '' }))  // v2 → v3
+ *   .create<BlockData>(() => ({ numbers: [], labels: [], description: '' }));
+ */
+export declare class DataModel<State> {
+    private readonly steps;
+    private readonly _initialData;
+    private constructor();
+    /** Start a migration chain from an initial type */
+    static from<S>(): DataModelBuilder<S>;
+    /** Create a data model with just initial data (no migrations) */
+    static create<S>(initialData: () => S): DataModel<S>;
+    /** Create from builder (internal use) */
+    static _fromBuilder<S>(steps: Array<(x: unknown) => unknown>, initialData: () => S): DataModel<S>;
+    /**
+     * Latest version number.
+     * Version 1 = initial state, each migration adds 1.
+     */
+    get version(): number;
+    /** Number of migration steps */
+    get migrationCount(): number;
+    /** Get initial data */
+    initialData(): State;
+    /** Get default data wrapped with current version */
+    getDefaultData(): Versioned<State>;
+    /**
+     * Upgrade versioned data from any version to the latest.
+     * Applies only the migrations needed (skips already-applied ones).
+     * If a migration fails, returns default data with a warning.
+     */
+    upgrade(versioned: Versioned<unknown>): UpgradeResult<State>;
+    /**
+     * Register callbacks for use in the VM.
+     * Called by BlockModelV3.create() to set up internal callbacks.
+     *
+     * All callbacks are prefixed with `__pl_` to indicate internal SDK use:
+     * - `__pl_data_initial`: returns initial data for new blocks
+     * - `__pl_data_upgrade`: upgrades versioned data from any version to latest
+     * - `__pl_storage_initial`: returns initial BlockStorage as JSON string
+     */
+    registerCallbacks(): void;
+}
+export {};
+//# sourceMappingURL=block_migrations.d.ts.map

package/dist/block_migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block_migrations.d.ts","sourceRoot":"","sources":["../src/block_migrations.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,WAAW,CAAC,IAAI,EAAE,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;AAEjE,6CAA6C;AAC7C,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,CAAC,CAAC;CACT,CAAC;AAEF,2EAA2E;AAC3E,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,GAAG;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,+CAA+C;AAC/C,cAAM,gBAAgB,CAAC,KAAK;IAC1B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiC;IAEhE,OAAO;IAIP,mDAAmD;IACnD,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,OAAO,KAAK,gBAAgB,CAAC,CAAC,CAAC;IAI/C,2BAA2B;IAC3B,OAAO,CAAC,IAAI,EAAE,EAAE,EAAE,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,gBAAgB,CAAC,IAAI,CAAC;IAInE,yDAAyD;IACzD,MAAM,CAAC,CAAC,EACN,WAAW,EAAE,MAAM,CAAC,EACpB,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,GACvC,SAAS,CAAC,CAAC,CAAC;CAGhB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,SAAS,CAAC,KAAK;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IACvD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAc;IAE3C,OAAO;IAKP,mDAAmD;IACnD,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,gBAAgB,CAAC,CAAC,CAAC;IAIrC,iEAAiE;IACjE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC;IAIpD,yCAAyC;IACzC,MAAM,CAAC,YAAY,CAAC,CAAC,EACnB,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,EACrC,WAAW,EAAE,MAAM,CAAC,GACnB,SAAS,CAAC,CAAC,CAAC;IAIf;;;OAGG;IACH,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,gCAAgC;IAChC,IAAI,cAAc,IAAI,MAAM,CAE3B;IAED,uBAAuB;IACvB,WAAW,IAAI,KAAK;IAIpB,oDAAoD;IACpD,cAAc,IAAI,SAAS,CAAC,KAAK,CAAC;IAIlC;;;;OAIG;IACH,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC,OAAO,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC;IAsC5D;;;;;;;;OAQG;IACH,iBAAiB,IAAI,IAAI;CAS1B"}

package/dist/block_migrations.js

@@ -0,0 +1,136 @@
+import { tryRegisterCallback } from './internal.js';
+import { createBlockStorage } from './block_storage.js';
+
+/** Internal builder for chaining migrations */
+class DataModelBuilder {
+    migrationSteps;
+    constructor(steps = []) {
+        this.migrationSteps = steps;
+    }
+    /** Start a migration chain from an initial type */
+    static from() {
+        return new DataModelBuilder();
+    }
+    /** Add a migration step */
+    migrate(fn) {
+        return new DataModelBuilder([...this.migrationSteps, fn]);
+    }
+    /** Finalize with initial data, creating the DataModel */
+    create(initialData, ..._) {
+        return DataModel._fromBuilder(this.migrationSteps, initialData);
+    }
+}
+/**
+ * DataModel defines the block's data structure, initial values, and migrations.
+ * Used by BlockModelV3 to manage data state.
+ *
+ * @example
+ * // Simple data model (no migrations)
+ * const dataModel = DataModel.create<BlockData>(() => ({
+ *   numbers: [],
+ *   labels: [],
+ * }));
+ *
+ * // Data model with migrations
+ * const dataModel = DataModel
+ *   .from<V1>()
+ *   .migrate((data) => ({ ...data, labels: [] }))  // v1 → v2
+ *   .migrate((data) => ({ ...data, description: '' }))  // v2 → v3
+ *   .create<BlockData>(() => ({ numbers: [], labels: [], description: '' }));
+ */
+class DataModel {
+    steps;
+    _initialData;
+    constructor(steps, initialData) {
+        this.steps = steps;
+        this._initialData = initialData;
+    }
+    /** Start a migration chain from an initial type */
+    static from() {
+        return DataModelBuilder.from();
+    }
+    /** Create a data model with just initial data (no migrations) */
+    static create(initialData) {
+        return new DataModel([], initialData);
+    }
+    /** Create from builder (internal use) */
+    static _fromBuilder(steps, initialData) {
+        return new DataModel(steps, initialData);
+    }
+    /**
+     * Latest version number.
+     * Version 1 = initial state, each migration adds 1.
+     */
+    get version() {
+        return this.steps.length + 1;
+    }
+    /** Number of migration steps */
+    get migrationCount() {
+        return this.steps.length;
+    }
+    /** Get initial data */
+    initialData() {
+        return this._initialData();
+    }
+    /** Get default data wrapped with current version */
+    getDefaultData() {
+        return { version: this.version, data: this._initialData() };
+    }
+    /**
+     * Upgrade versioned data from any version to the latest.
+     * Applies only the migrations needed (skips already-applied ones).
+     * If a migration fails, returns default data with a warning.
+     */
+    upgrade(versioned) {
+        const { version: fromVersion, data } = versioned;
+        if (fromVersion > this.version) {
+            throw new Error(`Cannot downgrade from version ${fromVersion} to ${this.version}`);
+        }
+        if (fromVersion === this.version) {
+            return { version: this.version, data: data };
+        }
+        // Apply migrations starting from (fromVersion - 1) index
+        // Version 1 -> no migrations applied yet -> start at index 0
+        // Version 2 -> migration[0] already applied -> start at index 1
+        const startIndex = fromVersion - 1;
+        const migrationsToApply = this.steps.slice(startIndex);
+        let currentData = data;
+        for (let i = 0; i < migrationsToApply.length; i++) {
+            const stepIndex = startIndex + i;
+            const fromVer = stepIndex + 1;
+            const toVer = stepIndex + 2;
+            try {
+                currentData = migrationsToApply[i](currentData);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                return {
+                    ...this.getDefaultData(),
+                    warning: `Migration v${fromVer}→v${toVer} failed: ${errorMessage}`,
+                };
+            }
+        }
+        return { version: this.version, data: currentData };
+    }
+    /**
+     * Register callbacks for use in the VM.
+     * Called by BlockModelV3.create() to set up internal callbacks.
+     *
+     * All callbacks are prefixed with `__pl_` to indicate internal SDK use:
+     * - `__pl_data_initial`: returns initial data for new blocks
+     * - `__pl_data_upgrade`: upgrades versioned data from any version to latest
+     * - `__pl_storage_initial`: returns initial BlockStorage as JSON string
+     */
+    registerCallbacks() {
+        tryRegisterCallback('__pl_data_initial', () => this._initialData());
+        tryRegisterCallback('__pl_data_upgrade', (versioned) => this.upgrade(versioned));
+        tryRegisterCallback('__pl_storage_initial', () => {
+            const { version, data } = this.getDefaultData();
+            const storage = createBlockStorage(data, version);
+            return JSON.stringify(storage);
+        });
+    }
+}
+
+export { DataModel };
+//# sourceMappingURL=block_migrations.js.map

package/dist/block_migrations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"block_migrations.js","sources":["../src/block_migrations.ts"],"sourcesContent":["import { tryRegisterCallback } from './internal';\nimport { createBlockStorage } from './block_storage';\n\nexport type MigrationFn<From, To> = (prev: Readonly<From>) => To;\n\n/** Versioned data wrapper for persistence */\nexport type Versioned<T> = {\n  version: number;\n  data: T;\n};\n\n/** Result of upgrade operation, may include warning if migration failed */\nexport type UpgradeResult<T> = Versioned<T> & {\n  warning?: string;\n};\n\n/** Internal builder for chaining migrations */\nclass DataModelBuilder<State> {\n  private readonly migrationSteps: Array<(x: unknown) => unknown>;\n\n  private constructor(steps: Array<(x: unknown) => unknown> = []) {\n    this.migrationSteps = steps;\n  }\n\n  /** Start a migration chain from an initial type */\n  static from<T = unknown>(): DataModelBuilder<T> {\n    return new DataModelBuilder<T>();\n  }\n\n  /** Add a migration step */\n  migrate<Next>(fn: MigrationFn<State, Next>): DataModelBuilder<Next> {\n    return new DataModelBuilder<Next>([...this.migrationSteps, fn as any]);\n  }\n\n  /** Finalize with initial data, creating the DataModel */\n  create<S>(\n    initialData: () => S,\n    ..._: [State] extends [S] ? [] : [never]\n  ): DataModel<S> {\n    return DataModel._fromBuilder<S>(this.migrationSteps, initialData);\n  }\n}\n\n/**\n * DataModel defines the block's data structure, initial values, and migrations.\n * Used by BlockModelV3 to manage data state.\n *\n * @example\n * // Simple data model (no migrations)\n * const dataModel = DataModel.create<BlockData>(() => ({\n *   numbers: [],\n *   labels: [],\n * }));\n *\n * // Data model with migrations\n * const dataModel = DataModel\n *   .from<V1>()\n *   .migrate((data) => ({ ...data, labels: [] }))  // v1 → v2\n *   .migrate((data) => ({ ...data, description: '' }))  // v2 → v3\n *   .create<BlockData>(() => ({ numbers: [], labels: [], description: '' }));\n */\nexport class DataModel<State> {\n  private readonly steps: Array<(x: unknown) => unknown>;\n  private readonly _initialData: () => State;\n\n  private constructor(steps: Array<(x: unknown) => unknown>, initialData: () => State) {\n    this.steps = steps;\n    this._initialData = initialData;\n  }\n\n  /** Start a migration chain from an initial type */\n  static from<S>(): DataModelBuilder<S> {\n    return DataModelBuilder.from<S>();\n  }\n\n  /** Create a data model with just initial data (no migrations) */\n  static create<S>(initialData: () => S): DataModel<S> {\n    return new DataModel<S>([], initialData);\n  }\n\n  /** Create from builder (internal use) */\n  static _fromBuilder<S>(\n    steps: Array<(x: unknown) => unknown>,\n    initialData: () => S,\n  ): DataModel<S> {\n    return new DataModel<S>(steps, initialData);\n  }\n\n  /**\n   * Latest version number.\n   * Version 1 = initial state, each migration adds 1.\n   */\n  get version(): number {\n    return this.steps.length + 1;\n  }\n\n  /** Number of migration steps */\n  get migrationCount(): number {\n    return this.steps.length;\n  }\n\n  /** Get initial data */\n  initialData(): State {\n    return this._initialData();\n  }\n\n  /** Get default data wrapped with current version */\n  getDefaultData(): Versioned<State> {\n    return { version: this.version, data: this._initialData() };\n  }\n\n  /**\n   * Upgrade versioned data from any version to the latest.\n   * Applies only the migrations needed (skips already-applied ones).\n   * If a migration fails, returns default data with a warning.\n   */\n  upgrade(versioned: Versioned<unknown>): UpgradeResult<State> {\n    const { version: fromVersion, data } = versioned;\n\n    if (fromVersion > this.version) {\n      throw new Error(\n        `Cannot downgrade from version ${fromVersion} to ${this.version}`,\n      );\n    }\n\n    if (fromVersion === this.version) {\n      return { version: this.version, data: data as State };\n    }\n\n    // Apply migrations starting from (fromVersion - 1) index\n    // Version 1 -> no migrations applied yet -> start at index 0\n    // Version 2 -> migration[0] already applied -> start at index 1\n    const startIndex = fromVersion - 1;\n    const migrationsToApply = this.steps.slice(startIndex);\n\n    let currentData: unknown = data;\n    for (let i = 0; i < migrationsToApply.length; i++) {\n      const stepIndex = startIndex + i;\n      const fromVer = stepIndex + 1;\n      const toVer = stepIndex + 2;\n      try {\n        currentData = migrationsToApply[i](currentData);\n      } catch (error) {\n        const errorMessage = error instanceof Error ? error.message : String(error);\n        return {\n          ...this.getDefaultData(),\n          warning: `Migration v${fromVer}→v${toVer} failed: ${errorMessage}`,\n        };\n      }\n    }\n\n    return { version: this.version, data: currentData as State };\n  }\n\n  /**\n   * Register callbacks for use in the VM.\n   * Called by BlockModelV3.create() to set up internal callbacks.\n   *\n   * All callbacks are prefixed with `__pl_` to indicate internal SDK use:\n   * - `__pl_data_initial`: returns initial data for new blocks\n   * - `__pl_data_upgrade`: upgrades versioned data from any version to latest\n   * - `__pl_storage_initial`: returns initial BlockStorage as JSON string\n   */\n  registerCallbacks(): void {\n    tryRegisterCallback('__pl_data_initial', () => this._initialData());\n    tryRegisterCallback('__pl_data_upgrade', (versioned: Versioned<unknown>) => this.upgrade(versioned));\n    tryRegisterCallback('__pl_storage_initial', () => {\n      const { version, data } = this.getDefaultData();\n      const storage = createBlockStorage(data, version);\n      return JSON.stringify(storage);\n    });\n  }\n}\n"],"names":[],"mappings":"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"}