@platforma-sdk/model 1.79.17 → 1.79.20

package/dist/block_model_legacy.js.map

@@ -1 +1 @@
-{"version":3,"file":"block_model_legacy.js","names":["#done"],"sources":["../src/block_model_legacy.ts"],"sourcesContent":["import type {\n  BlockRenderingMode,\n  BlockSection,\n  AnyFunction,\n  PlRef,\n  BlockCodeKnownFeatureFlags,\n  BlockConfigContainer,\n} from \"@milaboratories/pl-model-common\";\nimport { REQUIRES_PFRAMES_VERSION } from \"@milaboratories/pl-model-common\";\nimport type { Checked, ConfigResult, TypedConfig } from \"./config\";\nimport { getImmediate } from \"./config\";\nimport { getPlatformaInstance, isInUI, tryRegisterCallback } from \"./internal\";\nimport type { Platforma, PlatformaApiVersion, PlatformaV1, PlatformaV2 } from \"./platforma\";\nimport type { InferRenderFunctionReturn, RenderFunctionLegacy } from \"./render\";\nimport { RenderCtxLegacy } from \"./render\";\nimport { PlatformaSDKVersion } from \"./version\";\nimport type {\n  TypedConfigOrConfigLambda,\n  ConfigRenderLambda,\n  StdCtxArgsOnly,\n  DeriveHref,\n  ConfigRenderLambdaFlags,\n  InferOutputsFromConfigs,\n} from \"./bconfig\";\nimport { downgradeCfgOrLambda, isConfigLambda } from \"./bconfig\";\nimport type { PlatformaExtended } from \"./platforma\";\n\ntype SectionsExpectedType = readonly BlockSection[];\n\ntype SectionsCfgChecked<Cfg extends TypedConfig, Args, UiState> = Checked<\n  Cfg,\n  ConfigResult<Cfg, StdCtxArgsOnly<Args, UiState>> extends SectionsExpectedType ? true : false\n>;\n\ntype InputsValidExpectedType = boolean;\n\ntype InputsValidCfgChecked<Cfg extends TypedConfig, Args, UiState> = Checked<\n  Cfg,\n  ConfigResult<Cfg, StdCtxArgsOnly<Args, UiState>> extends InputsValidExpectedType ? true : false\n>;\n\ntype NoOb = Record<string, never>;\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. */\nexport class BlockModel<\n  Args,\n  OutputsCfg extends Record<string, TypedConfigOrConfigLambda>,\n  UiState,\n  Href extends `/${string}` = \"/\",\n> {\n  private constructor(\n    private config: {\n      readonly renderingMode: BlockRenderingMode;\n      readonly initialArgs?: Args;\n      readonly initialUiState: UiState;\n      readonly outputs: OutputsCfg;\n      readonly inputsValid: TypedConfigOrConfigLambda;\n      readonly sections: TypedConfigOrConfigLambda;\n      readonly title?: ConfigRenderLambda;\n      readonly subtitle?: ConfigRenderLambda;\n      readonly tags?: ConfigRenderLambda;\n      readonly enrichmentTargets?: ConfigRenderLambda;\n      readonly featureFlags: BlockCodeKnownFeatureFlags;\n    },\n  ) {}\n\n  public static get INITIAL_BLOCK_FEATURE_FLAGS(): BlockCodeKnownFeatureFlags {\n    return {\n      supportsLazyState: true,\n      supportsPframeQueryRanking: true,\n      requiresUIAPIVersion: 1,\n      requiresModelAPIVersion: 1,\n      requiresCreatePTable: 2,\n      requiresPFramesVersion: REQUIRES_PFRAMES_VERSION,\n    };\n  }\n\n  /** Initiates configuration builder */\n  public static create(renderingMode: BlockRenderingMode): BlockModel<NoOb, {}, NoOb>;\n  /** Initiates configuration builder */\n  public static create(): BlockModel<NoOb, {}, NoOb>;\n  /**\n   * Initiates configuration builder\n   * @deprecated use create method without generic parameter\n   */\n  public static create<Args>(renderingMode: BlockRenderingMode): BlockModel<Args, {}, NoOb>;\n  /**\n   * Initiates configuration builder\n   * @deprecated use create method without generic parameter\n   */\n  public static create<Args>(): BlockModel<Args, {}, NoOb>;\n  public static create(renderingMode: BlockRenderingMode = \"Heavy\"): BlockModel<NoOb, {}, NoOb> {\n    return new BlockModel<NoOb, {}, NoOb>({\n      renderingMode,\n      initialUiState: {},\n      outputs: {},\n      inputsValid: getImmediate(true),\n      sections: getImmediate([]),\n      featureFlags: BlockModel.INITIAL_BLOCK_FEATURE_FLAGS,\n    });\n  }\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 cfg configuration describing how to render cell value from the blocks\n   *            workflow outputs\n   * @deprecated use lambda-based API\n   * */\n  public output<const Key extends string, const Cfg extends TypedConfig>(\n    key: Key,\n    cfg: Cfg,\n  ): BlockModel<Args, OutputsCfg & { [K in Key]: Cfg }, UiState, Href>;\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 RenderFunctionLegacy<Args, UiState>>(\n    key: Key,\n    rf: RF,\n    flags: ConfigRenderLambdaFlags & { withStatus: true },\n  ): BlockModel<\n    Args,\n    OutputsCfg & {\n      [K in Key]: ConfigRenderLambda<InferRenderFunctionReturn<RF>> & { withStatus: true };\n    },\n    UiState,\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 RenderFunctionLegacy<Args, UiState>>(\n    key: Key,\n    rf: RF,\n    flags?: ConfigRenderLambdaFlags,\n  ): BlockModel<\n    Args,\n    OutputsCfg & { [K in Key]: ConfigRenderLambda<InferRenderFunctionReturn<RF>> },\n    UiState,\n    Href\n  >;\n  public output(\n    key: string,\n    cfgOrRf: TypedConfig | AnyFunction,\n    flags: ConfigRenderLambdaFlags = {},\n  ): BlockModel<Args, OutputsCfg, UiState, Href> {\n    if (typeof cfgOrRf === \"function\") {\n      const handle = `output#${key}`;\n      tryRegisterCallback(handle, () => cfgOrRf(new RenderCtxLegacy()));\n      return new BlockModel({\n        ...this.config,\n        outputs: {\n          ...this.config.outputs,\n          [key]: {\n            __renderLambda: true,\n            handle,\n            ...flags,\n          },\n        },\n      });\n    } else {\n      return new BlockModel({\n        ...this.config,\n        outputs: {\n          ...this.config.outputs,\n          [key]: cfgOrRf,\n        },\n      });\n    }\n  }\n\n  /** Shortcut for {@link output} with retentive flag set to true. */\n  public retentiveOutput<\n    const Key extends string,\n    const RF extends RenderFunctionLegacy<Args, UiState>,\n  >(key: Key, rf: RF) {\n    return this.output(key, rf, { retentive: true });\n  }\n\n  /** Shortcut for {@link output} with withStatus flag set to true. */\n  public outputWithStatus<\n    const Key extends string,\n    const RF extends RenderFunctionLegacy<Args, UiState>,\n  >(key: Key, rf: RF) {\n    return this.output(key, rf, { withStatus: true });\n  }\n\n  /** Shortcut for {@link output} with retentive and withStatus flags set to true. */\n  public retentiveOutputWithStatus<\n    const Key extends string,\n    const RF extends RenderFunctionLegacy<Args, UiState>,\n  >(key: Key, rf: RF) {\n    return this.output(key, rf, { retentive: true, withStatus: true });\n  }\n\n  /** Sets custom configuration predicate on the block args at which block can be executed\n   * @deprecated use lambda-based API */\n  public argsValid<Cfg extends TypedConfig>(\n    cfg: Cfg & InputsValidCfgChecked<Cfg, Args, UiState>,\n  ): BlockModel<Args, OutputsCfg, UiState, Href>;\n  /** Sets custom configuration predicate on the block args at which block can be executed */\n  public argsValid<RF extends RenderFunctionLegacy<Args, UiState, boolean>>(\n    rf: RF,\n  ): BlockModel<Args, OutputsCfg, UiState, Href>;\n  public argsValid(\n    cfgOrRf: TypedConfig | AnyFunction,\n  ): BlockModel<Args, OutputsCfg, UiState, `/${string}`> {\n    if (typeof cfgOrRf === \"function\") {\n      tryRegisterCallback(\"inputsValid\", () => cfgOrRf(new RenderCtxLegacy()));\n      return new BlockModel<Args, OutputsCfg, UiState>({\n        ...this.config,\n        inputsValid: {\n          __renderLambda: true,\n          handle: \"inputsValid\",\n        },\n      });\n    } else {\n      return new BlockModel<Args, OutputsCfg, UiState>({\n        ...this.config,\n        inputsValid: cfgOrRf,\n      });\n    }\n  }\n\n  /** Sets the config to generate list of section in the left block overviews panel\n   * @deprecated use lambda-based API */\n  public sections<const S extends SectionsExpectedType>(\n    rf: S,\n  ): BlockModel<Args, OutputsCfg, UiState, DeriveHref<S>>;\n  /** Sets the config to generate list of section in the left block overviews panel */\n  public sections<\n    const Ret extends SectionsExpectedType,\n    const RF extends RenderFunctionLegacy<Args, UiState, Ret>,\n  >(rf: RF): BlockModel<Args, OutputsCfg, UiState, DeriveHref<ReturnType<RF>>>;\n  public sections<const Cfg extends TypedConfig>(\n    cfg: Cfg & SectionsCfgChecked<Cfg, Args, UiState>,\n  ): BlockModel<\n    Args,\n    OutputsCfg,\n    UiState,\n    DeriveHref<ConfigResult<Cfg, StdCtxArgsOnly<Args, UiState>>>\n  >;\n  public sections(\n    arrOrCfgOrRf: SectionsExpectedType | TypedConfig | AnyFunction,\n  ): BlockModel<Args, OutputsCfg, UiState, `/${string}`> {\n    if (Array.isArray(arrOrCfgOrRf)) {\n      return this.sections(getImmediate(arrOrCfgOrRf));\n    } else if (typeof arrOrCfgOrRf === \"function\") {\n      tryRegisterCallback(\"sections\", () => arrOrCfgOrRf(new RenderCtxLegacy()));\n      return new BlockModel<Args, OutputsCfg, UiState>({\n        ...this.config,\n        sections: {\n          __renderLambda: true,\n          handle: \"sections\",\n        },\n      });\n    } else {\n      return new BlockModel<Args, OutputsCfg, UiState>({\n        ...this.config,\n        sections: arrOrCfgOrRf as TypedConfig,\n      });\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: RenderFunctionLegacy<Args, UiState, string>,\n  ): BlockModel<Args, OutputsCfg, UiState, Href> {\n    tryRegisterCallback(\"title\", () => rf(new RenderCtxLegacy()));\n    return new BlockModel<Args, OutputsCfg, UiState, Href>({\n      ...this.config,\n      title: {\n        __renderLambda: true,\n        handle: \"title\",\n      },\n    });\n  }\n\n  public subtitle(\n    rf: RenderFunctionLegacy<Args, UiState, string>,\n  ): BlockModel<Args, OutputsCfg, UiState, Href> {\n    tryRegisterCallback(\"subtitle\", () => rf(new RenderCtxLegacy()));\n    return new BlockModel<Args, OutputsCfg, UiState, Href>({\n      ...this.config,\n      subtitle: {\n        __renderLambda: true,\n        handle: \"subtitle\",\n      },\n    });\n  }\n\n  public tags(\n    rf: RenderFunctionLegacy<Args, UiState, string[]>,\n  ): BlockModel<Args, OutputsCfg, UiState, Href> {\n    tryRegisterCallback(\"tags\", () => rf(new RenderCtxLegacy()));\n    return new BlockModel<Args, OutputsCfg, UiState, Href>({\n      ...this.config,\n      tags: {\n        __renderLambda: true,\n        handle: \"tags\",\n      },\n    });\n  }\n\n  /**\n   * Sets initial args for the block, this value must be specified.\n   * @deprecated use {@link withArgs}\n   * */\n  public initialArgs(value: Args): BlockModel<Args, OutputsCfg, UiState, Href> {\n    return this.withArgs(value);\n  }\n\n  /** Sets initial args for the block, this value must be specified. */\n  public withArgs<Args>(initialArgs: Args): BlockModel<Args, OutputsCfg, UiState, Href> {\n    return new BlockModel<Args, OutputsCfg, UiState, Href>({\n      ...this.config,\n      initialArgs,\n    });\n  }\n\n  /** Defines type and sets initial value for block UiState. */\n  public withUiState<UiState>(\n    initialUiState: UiState,\n  ): BlockModel<Args, OutputsCfg, UiState, Href> {\n    return new BlockModel<Args, OutputsCfg, UiState, Href>({\n      ...this.config,\n      initialUiState,\n    });\n  }\n\n  /** Sets or overrides feature flags for the block. */\n  public withFeatureFlags(\n    flags: Partial<BlockCodeKnownFeatureFlags>,\n  ): BlockModel<Args, OutputsCfg, UiState, Href> {\n    return new BlockModel<Args, OutputsCfg, UiState, Href>({\n      ...this.config,\n      featureFlags: {\n        ...this.config.featureFlags,\n        ...flags,\n      },\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(lambda: (args: Args) => PlRef[]): BlockModel<Args, OutputsCfg, UiState, Href> {\n    tryRegisterCallback(\"enrichmentTargets\", lambda);\n    return new BlockModel<Args, OutputsCfg, UiState, Href>({\n      ...this.config,\n      enrichmentTargets: {\n        __renderLambda: true,\n        handle: \"enrichmentTargets\",\n      },\n    });\n  }\n\n  public done(\n    apiVersion?: 1,\n  ): PlatformaExtended<\n    PlatformaV1<Args, InferOutputsFromConfigs<Args, OutputsCfg, UiState>, UiState, Href>\n  >;\n\n  public done(\n    apiVersion: 2,\n  ): PlatformaExtended<\n    PlatformaV2<Args, InferOutputsFromConfigs<Args, OutputsCfg, UiState>, UiState, Href>\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 state, and\n   * other features provided by the platforma to the block. */\n  public done(\n    apiVersion: PlatformaApiVersion = 1,\n  ): PlatformaExtended<\n    Platforma<Args, InferOutputsFromConfigs<Args, OutputsCfg, UiState>, UiState, Href>\n  > {\n    return this.withFeatureFlags({\n      ...this.config.featureFlags,\n      requiresUIAPIVersion: apiVersion,\n    }).#done();\n  }\n\n  #done(): PlatformaExtended<\n    Platforma<Args, InferOutputsFromConfigs<Args, OutputsCfg, UiState>, UiState, Href>\n  > {\n    if (this.config.initialArgs === undefined) throw new Error(\"Initial arguments not set.\");\n\n    const config: BlockConfigContainer = {\n      v4: undefined,\n      v3: {\n        configVersion: 3,\n        modelAPIVersion: 1,\n        sdkVersion: PlatformaSDKVersion,\n        renderingMode: this.config.renderingMode,\n        initialArgs: this.config.initialArgs,\n        initialUiState: this.config.initialUiState,\n        inputsValid: this.config.inputsValid,\n        sections: this.config.sections,\n        title: this.config.title,\n        subtitle: this.config.subtitle,\n        tags: this.config.tags,\n        outputs: this.config.outputs,\n        enrichmentTargets: this.config.enrichmentTargets,\n        featureFlags: this.config.featureFlags,\n      },\n\n      // fields below are added to allow previous desktop versions read generated configs\n      sdkVersion: PlatformaSDKVersion,\n      renderingMode: this.config.renderingMode,\n      initialArgs: this.config.initialArgs,\n      inputsValid: downgradeCfgOrLambda(this.config.inputsValid),\n      sections: downgradeCfgOrLambda(this.config.sections),\n      outputs: Object.fromEntries(\n        Object.entries(this.config.outputs).map(([key, value]) => [\n          key,\n          downgradeCfgOrLambda(value),\n        ]),\n      ),\n    };\n\n    globalThis.platformaApiVersion = this.config.featureFlags\n      .requiresUIAPIVersion as PlatformaApiVersion;\n\n    if (!isInUI()) {\n      // we are in the configuration rendering routine, not in actual UI\n      return { config } as any;\n    } else {\n      // normal operation inside the UI\n      return {\n        ...getPlatformaInstance({\n          sdkVersion: PlatformaSDKVersion,\n          apiVersion: platformaApiVersion,\n        }),\n        blockModelInfo: {\n          outputs: Object.fromEntries(\n            Object.entries(this.config.outputs).map(([key, value]) => [\n              key,\n              {\n                withStatus: Boolean(isConfigLambda(value) && value.withStatus),\n              },\n            ]),\n          ),\n          pluginIds: [],\n          featureFlags: this.config.featureFlags,\n          pluginPublicOutputs: {},\n        },\n      };\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;AA8CA,IAAa,aAAb,MAAa,WAKX;CACA,YACE,QAaA;AAbQ,OAAA,SAAA;;CAeV,WAAkB,8BAA0D;AAC1E,SAAO;GACL,mBAAmB;GACnB,4BAA4B;GAC5B,sBAAsB;GACtB,yBAAyB;GACzB,sBAAsB;GACtB,wBAAwB;GACzB;;CAiBH,OAAc,OAAO,gBAAoC,SAAqC;AAC5F,SAAO,IAAI,WAA2B;GACpC;GACA,gBAAgB,EAAE;GAClB,SAAS,EAAE;GACX,aAAa,aAAa,KAAK;GAC/B,UAAU,aAAa,EAAE,CAAC;GAC1B,cAAc,WAAW;GAC1B,CAAC;;CAqDJ,OACE,KACA,SACA,QAAiC,EAAE,EACU;AAC7C,MAAI,OAAO,YAAY,YAAY;GACjC,MAAM,SAAS,UAAU;AACzB,uBAAoB,cAAc,QAAQ,IAAI,iBAAiB,CAAC,CAAC;AACjE,UAAO,IAAI,WAAW;IACpB,GAAG,KAAK;IACR,SAAS;KACP,GAAG,KAAK,OAAO;MACd,MAAM;MACL,gBAAgB;MAChB;MACA,GAAG;MACJ;KACF;IACF,CAAC;QAEF,QAAO,IAAI,WAAW;GACpB,GAAG,KAAK;GACR,SAAS;IACP,GAAG,KAAK,OAAO;KACd,MAAM;IACR;GACF,CAAC;;;CAKN,gBAGE,KAAU,IAAQ;AAClB,SAAO,KAAK,OAAO,KAAK,IAAI,EAAE,WAAW,MAAM,CAAC;;;CAIlD,iBAGE,KAAU,IAAQ;AAClB,SAAO,KAAK,OAAO,KAAK,IAAI,EAAE,YAAY,MAAM,CAAC;;;CAInD,0BAGE,KAAU,IAAQ;AAClB,SAAO,KAAK,OAAO,KAAK,IAAI;GAAE,WAAW;GAAM,YAAY;GAAM,CAAC;;CAYpE,UACE,SACqD;AACrD,MAAI,OAAO,YAAY,YAAY;AACjC,uBAAoB,qBAAqB,QAAQ,IAAI,iBAAiB,CAAC,CAAC;AACxE,UAAO,IAAI,WAAsC;IAC/C,GAAG,KAAK;IACR,aAAa;KACX,gBAAgB;KAChB,QAAQ;KACT;IACF,CAAC;QAEF,QAAO,IAAI,WAAsC;GAC/C,GAAG,KAAK;GACR,aAAa;GACd,CAAC;;CAsBN,SACE,cACqD;AACrD,MAAI,MAAM,QAAQ,aAAa,CAC7B,QAAO,KAAK,SAAS,aAAa,aAAa,CAAC;WACvC,OAAO,iBAAiB,YAAY;AAC7C,uBAAoB,kBAAkB,aAAa,IAAI,iBAAiB,CAAC,CAAC;AAC1E,UAAO,IAAI,WAAsC;IAC/C,GAAG,KAAK;IACR,UAAU;KACR,gBAAgB;KAChB,QAAQ;KACT;IACF,CAAC;QAEF,QAAO,IAAI,WAAsC;GAC/C,GAAG,KAAK;GACR,UAAU;GACX,CAAC;;;CAKN,MACE,IAC6C;AAC7C,sBAAoB,eAAe,GAAG,IAAI,iBAAiB,CAAC,CAAC;AAC7D,SAAO,IAAI,WAA4C;GACrD,GAAG,KAAK;GACR,OAAO;IACL,gBAAgB;IAChB,QAAQ;IACT;GACF,CAAC;;CAGJ,SACE,IAC6C;AAC7C,sBAAoB,kBAAkB,GAAG,IAAI,iBAAiB,CAAC,CAAC;AAChE,SAAO,IAAI,WAA4C;GACrD,GAAG,KAAK;GACR,UAAU;IACR,gBAAgB;IAChB,QAAQ;IACT;GACF,CAAC;;CAGJ,KACE,IAC6C;AAC7C,sBAAoB,cAAc,GAAG,IAAI,iBAAiB,CAAC,CAAC;AAC5D,SAAO,IAAI,WAA4C;GACrD,GAAG,KAAK;GACR,MAAM;IACJ,gBAAgB;IAChB,QAAQ;IACT;GACF,CAAC;;;;;;CAOJ,YAAmB,OAA0D;AAC3E,SAAO,KAAK,SAAS,MAAM;;;CAI7B,SAAsB,aAAgE;AACpF,SAAO,IAAI,WAA4C;GACrD,GAAG,KAAK;GACR;GACD,CAAC;;;CAIJ,YACE,gBAC6C;AAC7C,SAAO,IAAI,WAA4C;GACrD,GAAG,KAAK;GACR;GACD,CAAC;;;CAIJ,iBACE,OAC6C;AAC7C,SAAO,IAAI,WAA4C;GACrD,GAAG,KAAK;GACR,cAAc;IACZ,GAAG,KAAK,OAAO;IACf,GAAG;IACJ;GACF,CAAC;;;;;;CAOJ,SAAgB,QAA8E;AAC5F,sBAAoB,qBAAqB,OAAO;AAChD,SAAO,IAAI,WAA4C;GACrD,GAAG,KAAK;GACR,mBAAmB;IACjB,gBAAgB;IAChB,QAAQ;IACT;GACF,CAAC;;;;;CAkBJ,KACE,aAAkC,GAGlC;AACA,SAAO,KAAK,iBAAiB;GAC3B,GAAG,KAAK,OAAO;GACf,sBAAsB;GACvB,CAAC,EAAA,MAAQ;;CAGZ,QAEE;AACA,MAAI,KAAK,OAAO,gBAAgB,KAAA,EAAW,OAAM,IAAI,MAAM,6BAA6B;EAExF,MAAM,SAA+B;GACnC,IAAI,KAAA;GACJ,IAAI;IACF,eAAe;IACf,iBAAiB;IACjB,YAAY;IACZ,eAAe,KAAK,OAAO;IAC3B,aAAa,KAAK,OAAO;IACzB,gBAAgB,KAAK,OAAO;IAC5B,aAAa,KAAK,OAAO;IACzB,UAAU,KAAK,OAAO;IACtB,OAAO,KAAK,OAAO;IACnB,UAAU,KAAK,OAAO;IACtB,MAAM,KAAK,OAAO;IAClB,SAAS,KAAK,OAAO;IACrB,mBAAmB,KAAK,OAAO;IAC/B,cAAc,KAAK,OAAO;IAC3B;GAGD,YAAY;GACZ,eAAe,KAAK,OAAO;GAC3B,aAAa,KAAK,OAAO;GACzB,aAAa,qBAAqB,KAAK,OAAO,YAAY;GAC1D,UAAU,qBAAqB,KAAK,OAAO,SAAS;GACpD,SAAS,OAAO,YACd,OAAO,QAAQ,KAAK,OAAO,QAAQ,CAAC,KAAK,CAAC,KAAK,WAAW,CACxD,KACA,qBAAqB,MAAM,CAC5B,CAAC,CACH;GACF;AAED,aAAW,sBAAsB,KAAK,OAAO,aAC1C;AAEH,MAAI,CAAC,QAAQ,CAEX,QAAO,EAAE,QAAQ;MAGjB,QAAO;GACL,GAAG,qBAAqB;IACtB,YAAY;IACZ,YAAY;IACb,CAAC;GACF,gBAAgB;IACd,SAAS,OAAO,YACd,OAAO,QAAQ,KAAK,OAAO,QAAQ,CAAC,KAAK,CAAC,KAAK,WAAW,CACxD,KACA,EACE,YAAY,QAAQ,eAAe,MAAM,IAAI,MAAM,WAAW,EAC/D,CACF,CAAC,CACH;IACD,WAAW,EAAE;IACb,cAAc,KAAK,OAAO;IAC1B,qBAAqB,EAAE;IACxB;GACF"}
+{"version":3,"file":"block_model_legacy.js","names":["#done"],"sources":["../src/block_model_legacy.ts"],"sourcesContent":["import type {\n  BlockRenderingMode,\n  BlockSection,\n  AnyFunction,\n  PlRef,\n  BlockCodeKnownFeatureFlags,\n  BlockConfigContainer,\n} from \"@milaboratories/pl-model-common\";\nimport { REQUIRES_PFRAMES_VERSION } from \"@milaboratories/pl-model-common\";\nimport type { Checked, ConfigResult, TypedConfig } from \"./config\";\nimport { getImmediate } from \"./config\";\nimport { getPlatformaInstance, isInUI, tryRegisterCallback } from \"./internal\";\nimport type { Platforma, PlatformaApiVersion, PlatformaV1, PlatformaV2 } from \"./platforma\";\nimport type { InferRenderFunctionReturn, RenderFunctionLegacy } from \"./render\";\nimport { RenderCtxLegacy } from \"./render\";\nimport { PlatformaSDKVersion } from \"./version\";\nimport type {\n  TypedConfigOrConfigLambda,\n  ConfigRenderLambda,\n  StdCtxArgsOnly,\n  DeriveHref,\n  ConfigRenderLambdaFlags,\n  InferOutputsFromConfigs,\n} from \"./bconfig\";\nimport { downgradeCfgOrLambda, isConfigLambda } from \"./bconfig\";\nimport type { PlatformaExtended } from \"./platforma\";\n\ntype SectionsExpectedType = readonly BlockSection[];\n\ntype SectionsCfgChecked<Cfg extends TypedConfig, Args, UiState> = Checked<\n  Cfg,\n  ConfigResult<Cfg, StdCtxArgsOnly<Args, UiState>> extends SectionsExpectedType ? true : false\n>;\n\ntype InputsValidExpectedType = boolean;\n\ntype InputsValidCfgChecked<Cfg extends TypedConfig, Args, UiState> = Checked<\n  Cfg,\n  ConfigResult<Cfg, StdCtxArgsOnly<Args, UiState>> extends InputsValidExpectedType ? true : false\n>;\n\ntype NoOb = Record<string, never>;\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. */\nexport class BlockModel<\n  Args,\n  OutputsCfg extends Record<string, TypedConfigOrConfigLambda>,\n  UiState,\n  Href extends `/${string}` = \"/\",\n> {\n  private constructor(\n    private config: {\n      readonly renderingMode: BlockRenderingMode;\n      readonly initialArgs?: Args;\n      readonly initialUiState: UiState;\n      readonly outputs: OutputsCfg;\n      readonly inputsValid: TypedConfigOrConfigLambda;\n      readonly sections: TypedConfigOrConfigLambda;\n      readonly title?: ConfigRenderLambda;\n      readonly subtitle?: ConfigRenderLambda;\n      readonly tags?: ConfigRenderLambda;\n      readonly enrichmentTargets?: ConfigRenderLambda;\n      readonly featureFlags: BlockCodeKnownFeatureFlags;\n    },\n  ) {}\n\n  public static get INITIAL_BLOCK_FEATURE_FLAGS(): BlockCodeKnownFeatureFlags {\n    return {\n      supportsLazyState: true,\n      supportsPframeQueryRanking: true,\n      requiresUIAPIVersion: 1,\n      requiresModelAPIVersion: 1,\n      requiresCreatePTable: 2,\n      requiresPFramesVersion: REQUIRES_PFRAMES_VERSION,\n    };\n  }\n\n  /** Initiates configuration builder */\n  public static create(renderingMode: BlockRenderingMode): BlockModel<NoOb, {}, NoOb>;\n  /** Initiates configuration builder */\n  public static create(): BlockModel<NoOb, {}, NoOb>;\n  /**\n   * Initiates configuration builder\n   * @deprecated use create method without generic parameter\n   */\n  public static create<Args>(renderingMode: BlockRenderingMode): BlockModel<Args, {}, NoOb>;\n  /**\n   * Initiates configuration builder\n   * @deprecated use create method without generic parameter\n   */\n  public static create<Args>(): BlockModel<Args, {}, NoOb>;\n  public static create(renderingMode: BlockRenderingMode = \"Heavy\"): BlockModel<NoOb, {}, NoOb> {\n    return new BlockModel<NoOb, {}, NoOb>({\n      renderingMode,\n      initialUiState: {},\n      outputs: {},\n      inputsValid: getImmediate(true),\n      sections: getImmediate([]),\n      featureFlags: BlockModel.INITIAL_BLOCK_FEATURE_FLAGS,\n    });\n  }\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 cfg configuration describing how to render cell value from the blocks\n   *            workflow outputs\n   * @deprecated use lambda-based API\n   * */\n  public output<const Key extends string, const Cfg extends TypedConfig>(\n    key: Key,\n    cfg: Cfg,\n  ): BlockModel<Args, OutputsCfg & { [K in Key]: Cfg }, UiState, Href>;\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 RenderFunctionLegacy<Args, UiState>>(\n    key: Key,\n    rf: RF,\n    flags: ConfigRenderLambdaFlags & { withStatus: true },\n  ): BlockModel<\n    Args,\n    OutputsCfg & {\n      [K in Key]: ConfigRenderLambda<InferRenderFunctionReturn<RF>> & { withStatus: true };\n    },\n    UiState,\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 RenderFunctionLegacy<Args, UiState>>(\n    key: Key,\n    rf: RF,\n    flags?: ConfigRenderLambdaFlags,\n  ): BlockModel<\n    Args,\n    OutputsCfg & { [K in Key]: ConfigRenderLambda<InferRenderFunctionReturn<RF>> },\n    UiState,\n    Href\n  >;\n  public output(\n    key: string,\n    cfgOrRf: TypedConfig | AnyFunction,\n    flags: ConfigRenderLambdaFlags = {},\n  ): BlockModel<Args, OutputsCfg, UiState, Href> {\n    if (typeof cfgOrRf === \"function\") {\n      const handle = `output#${key}`;\n      tryRegisterCallback(handle, () => cfgOrRf(new RenderCtxLegacy()));\n      return new BlockModel({\n        ...this.config,\n        outputs: {\n          ...this.config.outputs,\n          [key]: {\n            __renderLambda: true,\n            handle,\n            ...flags,\n          },\n        },\n      });\n    } else {\n      return new BlockModel({\n        ...this.config,\n        outputs: {\n          ...this.config.outputs,\n          [key]: cfgOrRf,\n        },\n      });\n    }\n  }\n\n  /** Shortcut for {@link output} with retentive flag set to true. */\n  public retentiveOutput<\n    const Key extends string,\n    const RF extends RenderFunctionLegacy<Args, UiState>,\n  >(key: Key, rf: RF) {\n    return this.output(key, rf, { retentive: true });\n  }\n\n  /** Shortcut for {@link output} with withStatus flag set to true. */\n  public outputWithStatus<\n    const Key extends string,\n    const RF extends RenderFunctionLegacy<Args, UiState>,\n  >(key: Key, rf: RF) {\n    return this.output(key, rf, { withStatus: true });\n  }\n\n  /** Shortcut for {@link output} with retentive and withStatus flags set to true. */\n  public retentiveOutputWithStatus<\n    const Key extends string,\n    const RF extends RenderFunctionLegacy<Args, UiState>,\n  >(key: Key, rf: RF) {\n    return this.output(key, rf, { retentive: true, withStatus: true });\n  }\n\n  /** Sets custom configuration predicate on the block args at which block can be executed\n   * @deprecated use lambda-based API */\n  public argsValid<Cfg extends TypedConfig>(\n    cfg: Cfg & InputsValidCfgChecked<Cfg, Args, UiState>,\n  ): BlockModel<Args, OutputsCfg, UiState, Href>;\n  /** Sets custom configuration predicate on the block args at which block can be executed */\n  public argsValid<RF extends RenderFunctionLegacy<Args, UiState, boolean>>(\n    rf: RF,\n  ): BlockModel<Args, OutputsCfg, UiState, Href>;\n  public argsValid(\n    cfgOrRf: TypedConfig | AnyFunction,\n  ): BlockModel<Args, OutputsCfg, UiState, `/${string}`> {\n    if (typeof cfgOrRf === \"function\") {\n      tryRegisterCallback(\"inputsValid\", () => cfgOrRf(new RenderCtxLegacy()));\n      return new BlockModel<Args, OutputsCfg, UiState>({\n        ...this.config,\n        inputsValid: {\n          __renderLambda: true,\n          handle: \"inputsValid\",\n        },\n      });\n    } else {\n      return new BlockModel<Args, OutputsCfg, UiState>({\n        ...this.config,\n        inputsValid: cfgOrRf,\n      });\n    }\n  }\n\n  /** Sets the config to generate list of section in the left block overviews panel\n   * @deprecated use lambda-based API */\n  public sections<const S extends SectionsExpectedType>(\n    rf: S,\n  ): BlockModel<Args, OutputsCfg, UiState, DeriveHref<S>>;\n  /** Sets the config to generate list of section in the left block overviews panel */\n  public sections<\n    const Ret extends SectionsExpectedType,\n    const RF extends RenderFunctionLegacy<Args, UiState, Ret>,\n  >(rf: RF): BlockModel<Args, OutputsCfg, UiState, DeriveHref<ReturnType<RF>>>;\n  public sections<const Cfg extends TypedConfig>(\n    cfg: Cfg & SectionsCfgChecked<Cfg, Args, UiState>,\n  ): BlockModel<\n    Args,\n    OutputsCfg,\n    UiState,\n    DeriveHref<ConfigResult<Cfg, StdCtxArgsOnly<Args, UiState>>>\n  >;\n  public sections(\n    arrOrCfgOrRf: SectionsExpectedType | TypedConfig | AnyFunction,\n  ): BlockModel<Args, OutputsCfg, UiState, `/${string}`> {\n    if (Array.isArray(arrOrCfgOrRf)) {\n      return this.sections(getImmediate(arrOrCfgOrRf));\n    } else if (typeof arrOrCfgOrRf === \"function\") {\n      tryRegisterCallback(\"sections\", () => arrOrCfgOrRf(new RenderCtxLegacy()));\n      return new BlockModel<Args, OutputsCfg, UiState>({\n        ...this.config,\n        sections: {\n          __renderLambda: true,\n          handle: \"sections\",\n        },\n      });\n    } else {\n      return new BlockModel<Args, OutputsCfg, UiState>({\n        ...this.config,\n        sections: arrOrCfgOrRf as TypedConfig,\n      });\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: RenderFunctionLegacy<Args, UiState, string>,\n  ): BlockModel<Args, OutputsCfg, UiState, Href> {\n    tryRegisterCallback(\"title\", () => rf(new RenderCtxLegacy()));\n    return new BlockModel<Args, OutputsCfg, UiState, Href>({\n      ...this.config,\n      title: {\n        __renderLambda: true,\n        handle: \"title\",\n      },\n    });\n  }\n\n  public subtitle(\n    rf: RenderFunctionLegacy<Args, UiState, string>,\n  ): BlockModel<Args, OutputsCfg, UiState, Href> {\n    tryRegisterCallback(\"subtitle\", () => rf(new RenderCtxLegacy()));\n    return new BlockModel<Args, OutputsCfg, UiState, Href>({\n      ...this.config,\n      subtitle: {\n        __renderLambda: true,\n        handle: \"subtitle\",\n      },\n    });\n  }\n\n  public tags(\n    rf: RenderFunctionLegacy<Args, UiState, string[]>,\n  ): BlockModel<Args, OutputsCfg, UiState, Href> {\n    tryRegisterCallback(\"tags\", () => rf(new RenderCtxLegacy()));\n    return new BlockModel<Args, OutputsCfg, UiState, Href>({\n      ...this.config,\n      tags: {\n        __renderLambda: true,\n        handle: \"tags\",\n      },\n    });\n  }\n\n  /**\n   * Sets initial args for the block, this value must be specified.\n   * @deprecated use {@link withArgs}\n   * */\n  public initialArgs(value: Args): BlockModel<Args, OutputsCfg, UiState, Href> {\n    return this.withArgs(value);\n  }\n\n  /** Sets initial args for the block, this value must be specified. */\n  public withArgs<Args>(initialArgs: Args): BlockModel<Args, OutputsCfg, UiState, Href> {\n    return new BlockModel<Args, OutputsCfg, UiState, Href>({\n      ...this.config,\n      initialArgs,\n    });\n  }\n\n  /** Defines type and sets initial value for block UiState. */\n  public withUiState<UiState>(\n    initialUiState: UiState,\n  ): BlockModel<Args, OutputsCfg, UiState, Href> {\n    return new BlockModel<Args, OutputsCfg, UiState, Href>({\n      ...this.config,\n      initialUiState,\n    });\n  }\n\n  /** Sets or overrides feature flags for the block. */\n  public withFeatureFlags(\n    flags: Partial<BlockCodeKnownFeatureFlags>,\n  ): BlockModel<Args, OutputsCfg, UiState, Href> {\n    return new BlockModel<Args, OutputsCfg, UiState, Href>({\n      ...this.config,\n      featureFlags: {\n        ...this.config.featureFlags,\n        ...flags,\n      },\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(lambda: (args: Args) => PlRef[]): BlockModel<Args, OutputsCfg, UiState, Href> {\n    tryRegisterCallback(\"enrichmentTargets\", lambda);\n    return new BlockModel<Args, OutputsCfg, UiState, Href>({\n      ...this.config,\n      enrichmentTargets: {\n        __renderLambda: true,\n        handle: \"enrichmentTargets\",\n      },\n    });\n  }\n\n  public done(\n    apiVersion?: 1,\n  ): PlatformaExtended<\n    PlatformaV1<Args, InferOutputsFromConfigs<Args, OutputsCfg, UiState>, UiState, Href>\n  >;\n\n  public done(\n    apiVersion: 2,\n  ): PlatformaExtended<\n    PlatformaV2<Args, InferOutputsFromConfigs<Args, OutputsCfg, UiState>, UiState, Href>\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 state, and\n   * other features provided by the platforma to the block. */\n  public done(\n    apiVersion: PlatformaApiVersion = 1,\n  ): PlatformaExtended<\n    Platforma<Args, InferOutputsFromConfigs<Args, OutputsCfg, UiState>, UiState, Href>\n  > {\n    return this.withFeatureFlags({\n      ...this.config.featureFlags,\n      requiresUIAPIVersion: apiVersion,\n    }).#done();\n  }\n\n  #done(): PlatformaExtended<\n    Platforma<Args, InferOutputsFromConfigs<Args, OutputsCfg, UiState>, UiState, Href>\n  > {\n    if (this.config.initialArgs === undefined) throw new Error(\"Initial arguments not set.\");\n\n    const config: BlockConfigContainer = {\n      v4: undefined,\n      v3: {\n        configVersion: 3,\n        modelAPIVersion: 1,\n        sdkVersion: PlatformaSDKVersion,\n        renderingMode: this.config.renderingMode,\n        initialArgs: this.config.initialArgs,\n        initialUiState: this.config.initialUiState,\n        inputsValid: this.config.inputsValid,\n        sections: this.config.sections,\n        title: this.config.title,\n        subtitle: this.config.subtitle,\n        tags: this.config.tags,\n        outputs: this.config.outputs,\n        enrichmentTargets: this.config.enrichmentTargets,\n        featureFlags: this.config.featureFlags,\n      },\n\n      // fields below are added to allow previous desktop versions read generated configs\n      sdkVersion: PlatformaSDKVersion,\n      renderingMode: this.config.renderingMode,\n      initialArgs: this.config.initialArgs,\n      inputsValid: downgradeCfgOrLambda(this.config.inputsValid),\n      sections: downgradeCfgOrLambda(this.config.sections),\n      outputs: Object.fromEntries(\n        Object.entries(this.config.outputs).map(([key, value]) => [\n          key,\n          downgradeCfgOrLambda(value),\n        ]),\n      ),\n    };\n\n    globalThis.platformaApiVersion = this.config.featureFlags\n      .requiresUIAPIVersion as PlatformaApiVersion;\n\n    if (!isInUI()) {\n      // we are in the configuration rendering routine, not in actual UI\n      return { config } as any;\n    } else {\n      // normal operation inside the UI\n      return {\n        ...getPlatformaInstance({\n          sdkVersion: PlatformaSDKVersion,\n          apiVersion: platformaApiVersion,\n        }),\n        blockModelInfo: {\n          outputs: Object.fromEntries(\n            Object.entries(this.config.outputs).map(([key, value]) => [\n              key,\n              {\n                withStatus: Boolean(isConfigLambda(value) && value.withStatus),\n              },\n            ]),\n          ),\n          pluginIds: [],\n          featureFlags: this.config.featureFlags,\n          pluginPublicOutputs: {},\n        },\n      };\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/block_state_patch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"block_state_patch.d.ts","names":[],"sources":["../src/block_state_patch.ts"],"mappings":";;;;KAGY,KAAA;EAAA,mCAED,GAAA,EAAK,CAAA,EAFC;EAAA,SAIN,KAAA,EAAO,CAAA;AAAA;;KAIN,QAAA,WAAmB,MAAA,mCACjB,CAAA,GAAI,KAAA,CAAM,CAAA,EAAG,CAAA,CAAE,CAAA,WACrB,CAAA;;KAGI,eAAA,iCAEM,gBAAA,GAAmB,gBAAA,iEAGjC,QAAA,CAAS,UAAA,CAAW,IAAA,EAAM,OAAA,EAAS,OAAA,EAAS,IAAA"}
+{"version":3,"file":"block_state_patch.d.ts","names":[],"sources":["../src/block_state_patch.ts"],"mappings":";;;;KAGY,KAAA;EAAA,mCAED,GAAA,EAAK,CAAA,EAFC;EAAA,SAIN,KAAA,EAAO,CAAC;AAAA;;KAIP,QAAA,WAAmB,MAAA,mCACjB,CAAA,GAAI,KAAA,CAAM,CAAA,EAAG,CAAA,CAAE,CAAA,WACrB,CAAA;;KAGI,eAAA,iCAEM,gBAAA,GAAmB,gBAAA,iEAGjC,QAAA,CAAS,UAAA,CAAW,IAAA,EAAM,OAAA,EAAS,OAAA,EAAS,IAAA"}

package/dist/block_state_util.cjs

@@ -1,5 +1,7 @@
 //#region src/block_state_util.ts
 var OutputError = class extends Error {
+	errors;
+	moreErrors;
 	constructor(errors, moreErrors) {
 		super(`${errors.length}${moreErrors ? "+" : ""} errors, first error: ` + errors[0].message);
 		this.errors = errors;

package/dist/block_state_util.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"block_state_util.cjs","names":[],"sources":["../src/block_state_util.ts"],"sourcesContent":["import type { BlockOutputsBase, OutputWithStatus } from \"@milaboratories/pl-model-common\";\nimport type { ErrorLike } from \"@milaboratories/pl-error-like\";\n\nexport class OutputError extends Error {\n  constructor(\n    public readonly errors: ErrorLike[],\n    public readonly moreErrors: boolean,\n  ) {\n    super(`${errors.length}${moreErrors ? \"+\" : \"\"} errors, first error: ` + errors[0].message);\n  }\n}\n\nexport function readOutput<T>(outputValue: OutputWithStatus<T>): T {\n  if (!outputValue.ok) throw new OutputError(outputValue.errors, outputValue.moreErrors);\n  return outputValue.value;\n}\n\ntype ExtractValueType<V extends OutputWithStatus<unknown>> = Extract<V, { ok: true }>[\"value\"];\ntype SimpleOutputs<Outputs extends BlockOutputsBase> = {\n  [Key in keyof Outputs]: ExtractValueType<Outputs[Key]>;\n};\n\nexport function wrapOutputs<Outputs extends BlockOutputsBase>(\n  outputs: Outputs,\n): SimpleOutputs<Outputs> {\n  return new Proxy(outputs, {\n    get(target, key, receiver) {\n      if (typeof key === \"symbol\" || !(key in target)) return Reflect.get(target, key, receiver);\n      return readOutput(target[key]);\n    },\n  }) as SimpleOutputs<Outputs>;\n}\n"],"mappings":";AAGA,IAAa,cAAb,cAAiC,MAAM;CACrC,YACE,QACA,YACA;AACA,QAAM,GAAG,OAAO,SAAS,aAAa,MAAM,GAAG,0BAA0B,OAAO,GAAG,QAAQ;AAH3E,OAAA,SAAA;AACA,OAAA,aAAA;;;AAMpB,SAAgB,WAAc,aAAqC;AACjE,KAAI,CAAC,YAAY,GAAI,OAAM,IAAI,YAAY,YAAY,QAAQ,YAAY,WAAW;AACtF,QAAO,YAAY;;AAQrB,SAAgB,YACd,SACwB;AACxB,QAAO,IAAI,MAAM,SAAS,EACxB,IAAI,QAAQ,KAAK,UAAU;AACzB,MAAI,OAAO,QAAQ,YAAY,EAAE,OAAO,QAAS,QAAO,QAAQ,IAAI,QAAQ,KAAK,SAAS;AAC1F,SAAO,WAAW,OAAO,KAAK;IAEjC,CAAC"}
+{"version":3,"file":"block_state_util.cjs","names":[],"sources":["../src/block_state_util.ts"],"sourcesContent":["import type { BlockOutputsBase, OutputWithStatus } from \"@milaboratories/pl-model-common\";\nimport type { ErrorLike } from \"@milaboratories/pl-error-like\";\n\nexport class OutputError extends Error {\n  constructor(\n    public readonly errors: ErrorLike[],\n    public readonly moreErrors: boolean,\n  ) {\n    super(`${errors.length}${moreErrors ? \"+\" : \"\"} errors, first error: ` + errors[0].message);\n  }\n}\n\nexport function readOutput<T>(outputValue: OutputWithStatus<T>): T {\n  if (!outputValue.ok) throw new OutputError(outputValue.errors, outputValue.moreErrors);\n  return outputValue.value;\n}\n\ntype ExtractValueType<V extends OutputWithStatus<unknown>> = Extract<V, { ok: true }>[\"value\"];\ntype SimpleOutputs<Outputs extends BlockOutputsBase> = {\n  [Key in keyof Outputs]: ExtractValueType<Outputs[Key]>;\n};\n\nexport function wrapOutputs<Outputs extends BlockOutputsBase>(\n  outputs: Outputs,\n): SimpleOutputs<Outputs> {\n  return new Proxy(outputs, {\n    get(target, key, receiver) {\n      if (typeof key === \"symbol\" || !(key in target)) return Reflect.get(target, key, receiver);\n      return readOutput(target[key]);\n    },\n  }) as SimpleOutputs<Outputs>;\n}\n"],"mappings":";AAGA,IAAa,cAAb,cAAiC,MAAM;CAEnB;CACA;CAFlB,YACE,QACA,YACA;EACA,MAAM,GAAG,OAAO,SAAS,aAAa,MAAM,GAAG,0BAA0B,OAAO,EAAE,CAAC,OAAO;EAH1E,KAAA,SAAA;EACA,KAAA,aAAA;CAGlB;AACF;AAEA,SAAgB,WAAc,aAAqC;CACjE,IAAI,CAAC,YAAY,IAAI,MAAM,IAAI,YAAY,YAAY,QAAQ,YAAY,UAAU;CACrF,OAAO,YAAY;AACrB;AAOA,SAAgB,YACd,SACwB;CACxB,OAAO,IAAI,MAAM,SAAS,EACxB,IAAI,QAAQ,KAAK,UAAU;EACzB,IAAI,OAAO,QAAQ,YAAY,EAAE,OAAO,SAAS,OAAO,QAAQ,IAAI,QAAQ,KAAK,QAAQ;EACzF,OAAO,WAAW,OAAO,IAAI;CAC/B,EACF,CAAC;AACH"}

package/dist/block_state_util.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"block_state_util.d.ts","names":[],"sources":["../src/block_state_util.ts"],"mappings":";;;;cAGa,WAAA,SAAoB,KAAA;EAAA,SAEb,MAAA,EAAQ,SAAA;EAAA,SACR,UAAA;cADA,MAAA,EAAQ,SAAA,IACR,UAAA;AAAA;AAAA,iBAMJ,UAAA,GAAA,CAAc,WAAA,EAAa,gBAAA,CAAiB,CAAA,IAAK,CAAA;AAAA,KAK5D,gBAAA,WAA2B,gBAAA,aAA6B,OAAA,CAAQ,CAAA;EAAK,EAAA;AAAA;AAAA,KACrE,aAAA,iBAA8B,gBAAA,oBACnB,OAAA,GAAU,gBAAA,CAAiB,OAAA,CAAQ,GAAA;AAAA,iBAGnC,WAAA,iBAA4B,gBAAA,CAAA,CAC1C,OAAA,EAAS,OAAA,GACR,aAAA,CAAc,OAAA"}
+{"version":3,"file":"block_state_util.d.ts","names":[],"sources":["../src/block_state_util.ts"],"mappings":";;;;cAGa,WAAA,SAAoB,KAAA;EAAA,SAEb,MAAA,EAAQ,SAAA;EAAA,SACR,UAAA;cADA,MAAA,EAAQ,SAAA,IACR,UAAA;AAAA;AAAA,iBAMJ,UAAA,IAAc,WAAA,EAAa,gBAAA,CAAiB,CAAA,IAAK,CAAA;AAAA,KAK5D,gBAAA,WAA2B,gBAAA,aAA6B,OAAA,CAAQ,CAAA;EAAK,EAAA;AAAA;AAAA,KACrE,aAAA,iBAA8B,gBAAA,oBACnB,OAAA,GAAU,gBAAA,CAAiB,OAAA,CAAQ,GAAA;AAAA,iBAGnC,WAAA,iBAA4B,gBAAA,EAC1C,OAAA,EAAS,OAAA,GACR,aAAA,CAAc,OAAA"}

package/dist/block_state_util.js

@@ -1,5 +1,7 @@
 //#region src/block_state_util.ts
 var OutputError = class extends Error {
+	errors;
+	moreErrors;
 	constructor(errors, moreErrors) {
 		super(`${errors.length}${moreErrors ? "+" : ""} errors, first error: ` + errors[0].message);
 		this.errors = errors;

package/dist/block_state_util.js.map

@@ -1 +1 @@
-{"version":3,"file":"block_state_util.js","names":[],"sources":["../src/block_state_util.ts"],"sourcesContent":["import type { BlockOutputsBase, OutputWithStatus } from \"@milaboratories/pl-model-common\";\nimport type { ErrorLike } from \"@milaboratories/pl-error-like\";\n\nexport class OutputError extends Error {\n  constructor(\n    public readonly errors: ErrorLike[],\n    public readonly moreErrors: boolean,\n  ) {\n    super(`${errors.length}${moreErrors ? \"+\" : \"\"} errors, first error: ` + errors[0].message);\n  }\n}\n\nexport function readOutput<T>(outputValue: OutputWithStatus<T>): T {\n  if (!outputValue.ok) throw new OutputError(outputValue.errors, outputValue.moreErrors);\n  return outputValue.value;\n}\n\ntype ExtractValueType<V extends OutputWithStatus<unknown>> = Extract<V, { ok: true }>[\"value\"];\ntype SimpleOutputs<Outputs extends BlockOutputsBase> = {\n  [Key in keyof Outputs]: ExtractValueType<Outputs[Key]>;\n};\n\nexport function wrapOutputs<Outputs extends BlockOutputsBase>(\n  outputs: Outputs,\n): SimpleOutputs<Outputs> {\n  return new Proxy(outputs, {\n    get(target, key, receiver) {\n      if (typeof key === \"symbol\" || !(key in target)) return Reflect.get(target, key, receiver);\n      return readOutput(target[key]);\n    },\n  }) as SimpleOutputs<Outputs>;\n}\n"],"mappings":";AAGA,IAAa,cAAb,cAAiC,MAAM;CACrC,YACE,QACA,YACA;AACA,QAAM,GAAG,OAAO,SAAS,aAAa,MAAM,GAAG,0BAA0B,OAAO,GAAG,QAAQ;AAH3E,OAAA,SAAA;AACA,OAAA,aAAA;;;AAMpB,SAAgB,WAAc,aAAqC;AACjE,KAAI,CAAC,YAAY,GAAI,OAAM,IAAI,YAAY,YAAY,QAAQ,YAAY,WAAW;AACtF,QAAO,YAAY;;AAQrB,SAAgB,YACd,SACwB;AACxB,QAAO,IAAI,MAAM,SAAS,EACxB,IAAI,QAAQ,KAAK,UAAU;AACzB,MAAI,OAAO,QAAQ,YAAY,EAAE,OAAO,QAAS,QAAO,QAAQ,IAAI,QAAQ,KAAK,SAAS;AAC1F,SAAO,WAAW,OAAO,KAAK;IAEjC,CAAC"}
+{"version":3,"file":"block_state_util.js","names":[],"sources":["../src/block_state_util.ts"],"sourcesContent":["import type { BlockOutputsBase, OutputWithStatus } from \"@milaboratories/pl-model-common\";\nimport type { ErrorLike } from \"@milaboratories/pl-error-like\";\n\nexport class OutputError extends Error {\n  constructor(\n    public readonly errors: ErrorLike[],\n    public readonly moreErrors: boolean,\n  ) {\n    super(`${errors.length}${moreErrors ? \"+\" : \"\"} errors, first error: ` + errors[0].message);\n  }\n}\n\nexport function readOutput<T>(outputValue: OutputWithStatus<T>): T {\n  if (!outputValue.ok) throw new OutputError(outputValue.errors, outputValue.moreErrors);\n  return outputValue.value;\n}\n\ntype ExtractValueType<V extends OutputWithStatus<unknown>> = Extract<V, { ok: true }>[\"value\"];\ntype SimpleOutputs<Outputs extends BlockOutputsBase> = {\n  [Key in keyof Outputs]: ExtractValueType<Outputs[Key]>;\n};\n\nexport function wrapOutputs<Outputs extends BlockOutputsBase>(\n  outputs: Outputs,\n): SimpleOutputs<Outputs> {\n  return new Proxy(outputs, {\n    get(target, key, receiver) {\n      if (typeof key === \"symbol\" || !(key in target)) return Reflect.get(target, key, receiver);\n      return readOutput(target[key]);\n    },\n  }) as SimpleOutputs<Outputs>;\n}\n"],"mappings":";AAGA,IAAa,cAAb,cAAiC,MAAM;CAEnB;CACA;CAFlB,YACE,QACA,YACA;EACA,MAAM,GAAG,OAAO,SAAS,aAAa,MAAM,GAAG,0BAA0B,OAAO,EAAE,CAAC,OAAO;EAH1E,KAAA,SAAA;EACA,KAAA,aAAA;CAGlB;AACF;AAEA,SAAgB,WAAc,aAAqC;CACjE,IAAI,CAAC,YAAY,IAAI,MAAM,IAAI,YAAY,YAAY,QAAQ,YAAY,UAAU;CACrF,OAAO,YAAY;AACrB;AAOA,SAAgB,YACd,SACwB;CACxB,OAAO,IAAI,MAAM,SAAS,EACxB,IAAI,QAAQ,KAAK,UAAU;EACzB,IAAI,OAAO,QAAQ,YAAY,EAAE,OAAO,SAAS,OAAO,QAAQ,IAAI,QAAQ,KAAK,QAAQ;EACzF,OAAO,WAAW,OAAO,IAAI;CAC/B,EACF,CAAC;AACH"}

package/dist/block_storage.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"block_storage.cjs","names":["isDataUnrecoverableError"],"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\nimport type { Branded } from \"@milaboratories/pl-model-common\";\nimport {\n  type DataVersioned,\n  type TransferRecord,\n  isDataUnrecoverableError,\n} from \"./block_migrations\";\nimport type { PluginHandle, PluginFactoryLike, InferFactoryData } from \"./plugin_handle\";\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 * Default data version for new blocks without migrations.\n * Unique identifier ensures blocks are created via DataModel API.\n */\nexport const DATA_MODEL_LEGACY_VERSION = \"__pl_v1_d4e8f2a1__\";\n\n/**\n * Type for valid schema versions\n */\nexport type BlockStorageSchemaVersion = \"v1\"; // Add 'v2', 'v3', etc. as schema evolves\n\n/**\n * Branded type for plugin names - globally unique plugin type identifiers.\n * Using a branded type enforces explicit casting (`as PluginName`) which makes\n * it easy to find all plugin name definitions in the codebase and verify uniqueness.\n */\nexport type PluginName = Branded<string, \"PluginName\">;\n\n/**\n * Plugin registry - maps pluginId (unique within a block) to pluginName (globally unique plugin type).\n * Using a Record highlights that pluginIds must be unique within a block.\n */\nexport type PluginRegistry = Record<PluginHandle, PluginName>;\n\n/**\n * Versioned data - used for both block data and plugin data\n */\nexport interface VersionedData<TData = unknown> {\n  /** Version of the data, used for migrations */\n  __dataVersion: string;\n  /** The persistent data */\n  __data: TData;\n}\n\n/**\n * Core BlockStorage type that holds:\n * - __pl_a7f3e2b9__: Schema version (discriminator key identifies BlockStorage format)\n * - __dataVersion: Version key for block data migrations\n * - __data: The block's user-facing data (state)\n * - __pluginRegistry: Map from pluginId to pluginName (optional)\n * - __plugins: Plugin-specific data keyed by pluginId (optional)\n */\nexport type BlockStorage<TState = unknown> = {\n  /** Schema version - the key itself is the discriminator */\n  readonly [BLOCK_STORAGE_KEY]: BlockStorageSchemaVersion;\n  /** Registry of plugins: pluginId -> pluginName */\n  __pluginRegistry?: PluginRegistry;\n  /** Plugin-specific data, keyed by plugin handle */\n  __plugins?: Record<PluginHandle, VersionedData<unknown>>;\n} & VersionedData<TState>;\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 key (defaults to DATA_MODEL_LEGACY_VERSION)\n * @returns A new BlockStorage instance with discriminator key\n */\nexport function createBlockStorage<TState = unknown>(\n  initialData: TState = {} as TState,\n  version: string = DATA_MODEL_LEGACY_VERSION,\n): BlockStorage<TState> {\n  return {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: version,\n    __data: initialData,\n    __pluginRegistry: {},\n    __plugins: {},\n  };\n}\n\n/**\n * Normalizes raw storage data to BlockStorage format.\n * If the input is already a BlockStorage, returns it as-is (with defaults for missing fields).\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    const storage = raw as BlockStorage<TState>;\n    return {\n      ...storage,\n      // Fix for early released version where __dataVersion was a number\n      __dataVersion:\n        typeof storage.__dataVersion === \"number\"\n          ? DATA_MODEL_LEGACY_VERSION\n          : storage.__dataVersion,\n      // Ensure plugin fields have defaults\n      __pluginRegistry: storage.__pluginRegistry ?? {},\n      __plugins: storage.__plugins ?? {},\n    };\n  }\n  // Legacy format: raw is the state directly\n  return createBlockStorage(raw as TState);\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>(rawStorage: unknown): 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> =\n  | { operation: \"update-block-data\"; value: T }\n  | { operation: \"update-plugin-data\"; pluginId: PluginHandle; value: unknown };\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-block-data\":\n      return { ...storage, __data: payload.value };\n    case \"update-plugin-data\": {\n      const { pluginId, value } = payload;\n      const currentPlugins = storage.__plugins ?? {};\n      const existingEntry = currentPlugins[pluginId];\n      const version = existingEntry?.__dataVersion ?? DATA_MODEL_LEGACY_VERSION;\n      return {\n        ...storage,\n        __plugins: {\n          ...currentPlugins,\n          [pluginId]: {\n            __dataVersion: version,\n            __data: value,\n          },\n        },\n      };\n    }\n    default:\n      throw new Error(`Unknown storage operation: ${(payload as { operation: string }).operation}`);\n  }\n}\n\n// =============================================================================\n// Atomic Migration\n// =============================================================================\n\n/**\n * Result of a successful atomic migration.\n */\nexport interface MigrationSuccess<TState> {\n  success: true;\n  /** The fully migrated storage - commit this to persist */\n  storage: BlockStorage<TState>;\n}\n\n/**\n * Result of a failed atomic migration.\n * The original storage is untouched - user must choose to abort or reset.\n */\nexport interface MigrationFailure {\n  success: false;\n  /** Description of what failed */\n  error: string;\n  /** Which step failed: 'block' or pluginId */\n  failedAt: string;\n}\n\nexport type MigrationResult<TState> = MigrationSuccess<TState> | MigrationFailure;\n\n/**\n * Configuration for atomic block storage migration.\n * Callbacks use DataVersioned format (the DataModel API format).\n * Conversion to internal VersionedData format is handled by migrateBlockStorage().\n */\nexport interface MigrateBlockStorageConfig {\n  /** Migrate block data from any version to latest. Returns migrated data and transfers. */\n  migrateBlockData: (versioned: DataVersioned<unknown>) => DataVersioned<unknown> & {\n    transfers: TransferRecord;\n  };\n  /** Migrate each plugin's data. Return undefined to remove the plugin. Throws on failure. */\n  migratePluginData: (\n    handle: PluginHandle,\n    versioned: DataVersioned<unknown>,\n  ) => DataVersioned<unknown> | undefined;\n  /** The new plugin registry after migration (pluginId -> pluginName) */\n  newPluginRegistry: PluginRegistry;\n  /** Factory to create initial data for new plugins. Transfer is provided when a\n   *  .transfer() was defined for this plugin in the block's migration chain. */\n  createPluginData: (\n    handle: PluginHandle,\n    transfer?: DataVersioned<unknown>,\n  ) => DataVersioned<unknown>;\n}\n\n/**\n * Performs atomic migration of block storage including block data and all plugins.\n *\n * Migration is atomic: either everything succeeds and a new storage is returned,\n * or an error is returned and the original storage is completely untouched.\n *\n * Migration steps:\n * 1. Migrate block data\n * 2. For each plugin in newPluginRegistry:\n *    - If plugin exists with same name: migrate its data\n *    - Otherwise (new or type changed): create with initial data\n *    Plugins not in newPluginRegistry are dropped.\n *\n * If any step throws, migration fails and original storage is preserved.\n * User can then choose to:\n * - Abort: keep original storage, don't update block\n * - Reset: call createBlockStorage() to start fresh\n *\n * @param storage - The original storage (will not be modified)\n * @param config - Migration configuration\n * @returns Migration result - either success with new storage, or failure with error info\n *\n * @example\n * const result = migrateBlockStorage(storage, {\n *   migrateBlockData: (versioned) => blockDataModel.migrate(versioned),\n *   migratePluginData: (pluginId, versioned) => getPluginModel(pluginId).migrate(versioned),\n *   newPluginRegistry: { table1: 'dataTable' as PluginName },\n *   createPluginData: (pluginId) => getPluginModel(pluginId).getDefaultData(),\n * });\n *\n * if (result.success) {\n *   commitStorage(result.storage);\n * } else {\n *   const userChoice = await askUser(`Migration failed: ${result.error}. Reset data?`);\n *   if (userChoice === 'reset') {\n *     commitStorage(createBlockStorage(initialData, currentVersion));\n *   }\n *   // else: abort, keep original\n * }\n */\nexport function migrateBlockStorage(\n  storage: BlockStorage<unknown>,\n  config: MigrateBlockStorageConfig,\n): MigrationResult<unknown> {\n  const { migrateBlockData, migratePluginData, newPluginRegistry, createPluginData } = config;\n\n  // Step 1: Migrate block data and collect transfers\n  let migratedData: unknown;\n  let newVersion: string;\n  let transfers: TransferRecord;\n  try {\n    const result = migrateBlockData({ version: storage.__dataVersion, data: storage.__data });\n    migratedData = result.data;\n    newVersion = result.version;\n    transfers = result.transfers;\n  } catch (error) {\n    return {\n      success: false,\n      error: error instanceof Error ? error.message : String(error),\n      failedAt: \"block\",\n    };\n  }\n\n  // Step 2: Migrate plugins\n  const oldPlugins = storage.__plugins ?? {};\n  const oldRegistry = storage.__pluginRegistry ?? {};\n  const newPlugins: Record<PluginHandle, VersionedData<unknown>> = {};\n\n  for (const [key, pluginName] of Object.entries(newPluginRegistry)) {\n    const handle = key as PluginHandle;\n    const existingEntry = oldPlugins[handle];\n    const existingName = oldRegistry[handle];\n\n    try {\n      if (existingEntry && existingName === pluginName) {\n        // Plugin exists with same type - migrate its data\n        const migrated = migratePluginData(handle, {\n          version: existingEntry.__dataVersion,\n          data: existingEntry.__data,\n        });\n        if (migrated) {\n          newPlugins[handle] = { __dataVersion: migrated.version, __data: migrated.data };\n        }\n        // If undefined returned, plugin is intentionally removed\n      } else if (existingEntry) {\n        // Plugin type changed — pass old data with DATA_MODEL_LEGACY_VERSION.\n        // If the new plugin has upgradeLegacy(), it migrates the old data.\n        // If not, defaultRecover throws DataUnrecoverableError → fall back to init.\n        let recovered = false;\n        try {\n          const migrated = migratePluginData(handle, {\n            version: DATA_MODEL_LEGACY_VERSION,\n            data: existingEntry.__data,\n          });\n          if (migrated) {\n            newPlugins[handle] = { __dataVersion: migrated.version, __data: migrated.data };\n            recovered = true;\n          }\n        } catch (recoverError) {\n          if (!isDataUnrecoverableError(recoverError)) throw recoverError;\n        }\n        if (!recovered) {\n          const transfer = transfers[handle];\n          const initial = createPluginData(handle, transfer);\n          newPlugins[handle] = { __dataVersion: initial.version, __data: initial.data };\n        }\n      } else {\n        // New plugin - create with initial data, passing transfer if available\n        const transfer = transfers[handle];\n        const initial = createPluginData(handle, transfer);\n        newPlugins[handle] = { __dataVersion: initial.version, __data: initial.data };\n      }\n    } catch (error) {\n      return {\n        success: false,\n        error: error instanceof Error ? error.message : String(error),\n        failedAt: handle,\n      };\n    }\n  }\n\n  // Step 3: Build final storage atomically\n  const migratedStorage: BlockStorage = {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: newVersion,\n    __data: migratedData,\n    __pluginRegistry: newPluginRegistry,\n    __plugins: newPlugins,\n  };\n\n  return {\n    success: true,\n    storage: migratedStorage,\n  };\n}\n\n/**\n * Gets plugin-specific data from block storage.\n * Accepts raw storage (any format) and normalizes internally.\n *\n * When called with a typed PluginHandle<F>, the return type is automatically\n * inferred from the factory's phantom `__types.data` field.\n *\n * @param rawStorage - Raw block storage (may be legacy format or BlockStorage)\n * @param handle - The plugin handle (branded plugin instance id)\n * @returns The plugin data, typed via factory inference\n * @throws If plugin is not found in storage\n */\nexport function getPluginData<F extends PluginFactoryLike>(\n  rawStorage: unknown,\n  handle: PluginHandle<F>,\n): InferFactoryData<F> {\n  const storage = normalizeBlockStorage(rawStorage);\n  const pluginEntry = storage.__plugins?.[handle];\n  if (!pluginEntry) throw new Error(`Plugin '${handle}' not found in block storage`);\n  return pluginEntry.__data as InferFactoryData<F>;\n}\n"],"mappings":"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"}
+{"version":3,"file":"block_storage.cjs","names":["obj","isDataUnrecoverableError"],"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\nimport type { Branded } from \"@milaboratories/pl-model-common\";\nimport {\n  type DataVersioned,\n  type TransferRecord,\n  isDataUnrecoverableError,\n} from \"./block_migrations\";\nimport type { PluginHandle, PluginFactoryLike, InferFactoryData } from \"./plugin_handle\";\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 * Default data version for new blocks without migrations.\n * Unique identifier ensures blocks are created via DataModel API.\n */\nexport const DATA_MODEL_LEGACY_VERSION = \"__pl_v1_d4e8f2a1__\";\n\n/**\n * Type for valid schema versions\n */\nexport type BlockStorageSchemaVersion = \"v1\"; // Add 'v2', 'v3', etc. as schema evolves\n\n/**\n * Branded type for plugin names - globally unique plugin type identifiers.\n * Using a branded type enforces explicit casting (`as PluginName`) which makes\n * it easy to find all plugin name definitions in the codebase and verify uniqueness.\n */\nexport type PluginName = Branded<string, \"PluginName\">;\n\n/**\n * Plugin registry - maps pluginId (unique within a block) to pluginName (globally unique plugin type).\n * Using a Record highlights that pluginIds must be unique within a block.\n */\nexport type PluginRegistry = Record<PluginHandle, PluginName>;\n\n/**\n * Versioned data - used for both block data and plugin data\n */\nexport interface VersionedData<TData = unknown> {\n  /** Version of the data, used for migrations */\n  __dataVersion: string;\n  /** The persistent data */\n  __data: TData;\n}\n\n/**\n * Core BlockStorage type that holds:\n * - __pl_a7f3e2b9__: Schema version (discriminator key identifies BlockStorage format)\n * - __dataVersion: Version key for block data migrations\n * - __data: The block's user-facing data (state)\n * - __pluginRegistry: Map from pluginId to pluginName (optional)\n * - __plugins: Plugin-specific data keyed by pluginId (optional)\n */\nexport type BlockStorage<TState = unknown> = {\n  /** Schema version - the key itself is the discriminator */\n  readonly [BLOCK_STORAGE_KEY]: BlockStorageSchemaVersion;\n  /** Registry of plugins: pluginId -> pluginName */\n  __pluginRegistry?: PluginRegistry;\n  /** Plugin-specific data, keyed by plugin handle */\n  __plugins?: Record<PluginHandle, VersionedData<unknown>>;\n} & VersionedData<TState>;\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 key (defaults to DATA_MODEL_LEGACY_VERSION)\n * @returns A new BlockStorage instance with discriminator key\n */\nexport function createBlockStorage<TState = unknown>(\n  initialData: TState = {} as TState,\n  version: string = DATA_MODEL_LEGACY_VERSION,\n): BlockStorage<TState> {\n  return {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: version,\n    __data: initialData,\n    __pluginRegistry: {},\n    __plugins: {},\n  };\n}\n\n/**\n * Normalizes raw storage data to BlockStorage format.\n * If the input is already a BlockStorage, returns it as-is (with defaults for missing fields).\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    const storage = raw as BlockStorage<TState>;\n    return {\n      ...storage,\n      // Fix for early released version where __dataVersion was a number\n      __dataVersion:\n        typeof storage.__dataVersion === \"number\"\n          ? DATA_MODEL_LEGACY_VERSION\n          : storage.__dataVersion,\n      // Ensure plugin fields have defaults\n      __pluginRegistry: storage.__pluginRegistry ?? {},\n      __plugins: storage.__plugins ?? {},\n    };\n  }\n  // Legacy format: raw is the state directly\n  return createBlockStorage(raw as TState);\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>(rawStorage: unknown): 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> =\n  | { operation: \"update-block-data\"; value: T }\n  | { operation: \"update-plugin-data\"; pluginId: PluginHandle; value: unknown };\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-block-data\":\n      return { ...storage, __data: payload.value };\n    case \"update-plugin-data\": {\n      const { pluginId, value } = payload;\n      const currentPlugins = storage.__plugins ?? {};\n      const existingEntry = currentPlugins[pluginId];\n      const version = existingEntry?.__dataVersion ?? DATA_MODEL_LEGACY_VERSION;\n      return {\n        ...storage,\n        __plugins: {\n          ...currentPlugins,\n          [pluginId]: {\n            __dataVersion: version,\n            __data: value,\n          },\n        },\n      };\n    }\n    default:\n      throw new Error(`Unknown storage operation: ${(payload as { operation: string }).operation}`);\n  }\n}\n\n// =============================================================================\n// Atomic Migration\n// =============================================================================\n\n/**\n * Result of a successful atomic migration.\n */\nexport interface MigrationSuccess<TState> {\n  success: true;\n  /** The fully migrated storage - commit this to persist */\n  storage: BlockStorage<TState>;\n}\n\n/**\n * Result of a failed atomic migration.\n * The original storage is untouched - user must choose to abort or reset.\n */\nexport interface MigrationFailure {\n  success: false;\n  /** Description of what failed */\n  error: string;\n  /** Which step failed: 'block' or pluginId */\n  failedAt: string;\n}\n\nexport type MigrationResult<TState> = MigrationSuccess<TState> | MigrationFailure;\n\n/**\n * Configuration for atomic block storage migration.\n * Callbacks use DataVersioned format (the DataModel API format).\n * Conversion to internal VersionedData format is handled by migrateBlockStorage().\n */\nexport interface MigrateBlockStorageConfig {\n  /** Migrate block data from any version to latest. Returns migrated data and transfers. */\n  migrateBlockData: (versioned: DataVersioned<unknown>) => DataVersioned<unknown> & {\n    transfers: TransferRecord;\n  };\n  /** Migrate each plugin's data. Return undefined to remove the plugin. Throws on failure. */\n  migratePluginData: (\n    handle: PluginHandle,\n    versioned: DataVersioned<unknown>,\n  ) => DataVersioned<unknown> | undefined;\n  /** The new plugin registry after migration (pluginId -> pluginName) */\n  newPluginRegistry: PluginRegistry;\n  /** Factory to create initial data for new plugins. Transfer is provided when a\n   *  .transfer() was defined for this plugin in the block's migration chain. */\n  createPluginData: (\n    handle: PluginHandle,\n    transfer?: DataVersioned<unknown>,\n  ) => DataVersioned<unknown>;\n}\n\n/**\n * Performs atomic migration of block storage including block data and all plugins.\n *\n * Migration is atomic: either everything succeeds and a new storage is returned,\n * or an error is returned and the original storage is completely untouched.\n *\n * Migration steps:\n * 1. Migrate block data\n * 2. For each plugin in newPluginRegistry:\n *    - If plugin exists with same name: migrate its data\n *    - Otherwise (new or type changed): create with initial data\n *    Plugins not in newPluginRegistry are dropped.\n *\n * If any step throws, migration fails and original storage is preserved.\n * User can then choose to:\n * - Abort: keep original storage, don't update block\n * - Reset: call createBlockStorage() to start fresh\n *\n * @param storage - The original storage (will not be modified)\n * @param config - Migration configuration\n * @returns Migration result - either success with new storage, or failure with error info\n *\n * @example\n * const result = migrateBlockStorage(storage, {\n *   migrateBlockData: (versioned) => blockDataModel.migrate(versioned),\n *   migratePluginData: (pluginId, versioned) => getPluginModel(pluginId).migrate(versioned),\n *   newPluginRegistry: { table1: 'dataTable' as PluginName },\n *   createPluginData: (pluginId) => getPluginModel(pluginId).getDefaultData(),\n * });\n *\n * if (result.success) {\n *   commitStorage(result.storage);\n * } else {\n *   const userChoice = await askUser(`Migration failed: ${result.error}. Reset data?`);\n *   if (userChoice === 'reset') {\n *     commitStorage(createBlockStorage(initialData, currentVersion));\n *   }\n *   // else: abort, keep original\n * }\n */\nexport function migrateBlockStorage(\n  storage: BlockStorage<unknown>,\n  config: MigrateBlockStorageConfig,\n): MigrationResult<unknown> {\n  const { migrateBlockData, migratePluginData, newPluginRegistry, createPluginData } = config;\n\n  // Step 1: Migrate block data and collect transfers\n  let migratedData: unknown;\n  let newVersion: string;\n  let transfers: TransferRecord;\n  try {\n    const result = migrateBlockData({ version: storage.__dataVersion, data: storage.__data });\n    migratedData = result.data;\n    newVersion = result.version;\n    transfers = result.transfers;\n  } catch (error) {\n    return {\n      success: false,\n      error: error instanceof Error ? error.message : String(error),\n      failedAt: \"block\",\n    };\n  }\n\n  // Step 2: Migrate plugins\n  const oldPlugins = storage.__plugins ?? {};\n  const oldRegistry = storage.__pluginRegistry ?? {};\n  const newPlugins: Record<PluginHandle, VersionedData<unknown>> = {};\n\n  for (const [key, pluginName] of Object.entries(newPluginRegistry)) {\n    const handle = key as PluginHandle;\n    const existingEntry = oldPlugins[handle];\n    const existingName = oldRegistry[handle];\n\n    try {\n      if (existingEntry && existingName === pluginName) {\n        // Plugin exists with same type - migrate its data\n        const migrated = migratePluginData(handle, {\n          version: existingEntry.__dataVersion,\n          data: existingEntry.__data,\n        });\n        if (migrated) {\n          newPlugins[handle] = { __dataVersion: migrated.version, __data: migrated.data };\n        }\n        // If undefined returned, plugin is intentionally removed\n      } else if (existingEntry) {\n        // Plugin type changed — pass old data with DATA_MODEL_LEGACY_VERSION.\n        // If the new plugin has upgradeLegacy(), it migrates the old data.\n        // If not, defaultRecover throws DataUnrecoverableError → fall back to init.\n        let recovered = false;\n        try {\n          const migrated = migratePluginData(handle, {\n            version: DATA_MODEL_LEGACY_VERSION,\n            data: existingEntry.__data,\n          });\n          if (migrated) {\n            newPlugins[handle] = { __dataVersion: migrated.version, __data: migrated.data };\n            recovered = true;\n          }\n        } catch (recoverError) {\n          if (!isDataUnrecoverableError(recoverError)) throw recoverError;\n        }\n        if (!recovered) {\n          const transfer = transfers[handle];\n          const initial = createPluginData(handle, transfer);\n          newPlugins[handle] = { __dataVersion: initial.version, __data: initial.data };\n        }\n      } else {\n        // New plugin - create with initial data, passing transfer if available\n        const transfer = transfers[handle];\n        const initial = createPluginData(handle, transfer);\n        newPlugins[handle] = { __dataVersion: initial.version, __data: initial.data };\n      }\n    } catch (error) {\n      return {\n        success: false,\n        error: error instanceof Error ? error.message : String(error),\n        failedAt: handle,\n      };\n    }\n  }\n\n  // Step 3: Build final storage atomically\n  const migratedStorage: BlockStorage = {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: newVersion,\n    __data: migratedData,\n    __pluginRegistry: newPluginRegistry,\n    __plugins: newPlugins,\n  };\n\n  return {\n    success: true,\n    storage: migratedStorage,\n  };\n}\n\n/**\n * Gets plugin-specific data from block storage.\n * Accepts raw storage (any format) and normalizes internally.\n *\n * When called with a typed PluginHandle<F>, the return type is automatically\n * inferred from the factory's phantom `__types.data` field.\n *\n * @param rawStorage - Raw block storage (may be legacy format or BlockStorage)\n * @param handle - The plugin handle (branded plugin instance id)\n * @returns The plugin data, typed via factory inference\n * @throws If plugin is not found in storage\n */\nexport function getPluginData<F extends PluginFactoryLike>(\n  rawStorage: unknown,\n  handle: PluginHandle<F>,\n): InferFactoryData<F> {\n  const storage = normalizeBlockStorage(rawStorage);\n  const pluginEntry = storage.__plugins?.[handle];\n  if (!pluginEntry) throw new Error(`Plugin '${handle}' not found in block storage`);\n  return pluginEntry.__data as InferFactoryData<F>;\n}\n"],"mappings":"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"}

package/dist/block_storage.d.ts

@@ -196,5 +196,5 @@ declare function migrateBlockStorage(storage: BlockStorage<unknown>, config: Mig
  */
 declare function getPluginData<F extends PluginFactoryLike>(rawStorage: unknown, handle: PluginHandle<F>): InferFactoryData<F>;
 //#endregion
-export { BlockStorage, BlockStorageSchemaVersion, MigrateBlockStorageConfig, MigrationFailure, MigrationResult, MigrationSuccess, MutateStoragePayload, PluginName, PluginRegistry, VersionedData, createBlockStorage, deriveDataFromStorage, getPluginData, getStorageData, isBlockStorage, migrateBlockStorage, normalizeBlockStorage, updateStorageData };
+export { BLOCK_STORAGE_KEY, BlockStorage, BlockStorageSchemaVersion, MigrateBlockStorageConfig, MigrationFailure, MigrationResult, MigrationSuccess, MutateStoragePayload, PluginName, PluginRegistry, VersionedData, createBlockStorage, deriveDataFromStorage, getPluginData, getStorageData, isBlockStorage, migrateBlockStorage, normalizeBlockStorage, updateStorageData };
 //# sourceMappingURL=block_storage.d.ts.map

package/dist/block_storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"block_storage.d.ts","names":[],"sources":["../src/block_storage.ts"],"mappings":";;;;;;;AAmDA;;cAxBa,iBAAA;;;;KAiBD,yBAAA;;AAkBZ;;;;KAXY,UAAA,GAAa,OAAA;;;;;KAMb,cAAA,GAAiB,MAAA,CAAO,YAAA,EAAc,UAAA;AAoBlD;;;AAAA,UAfiB,aAAA;EAiBL;EAfV,aAAA;EAmBmB;EAjBnB,MAAA,EAAQ,KAAA;AAAA;;;;;;;;;KAWE,YAAA;EAMV,qEAJU,iBAAA,GAAoB,yBAAA,EAIX;EAFnB,gBAAA,GAAmB,cAAA,EAGjB;EADF,SAAA,GAAY,MAAA,CAAO,YAAA,EAAc,aAAA;AAAA,IAC/B,aAAA,CAAc,MAAA;;AAMlB;;;iBAAgB,cAAA,CAAe,KAAA,YAAiB,KAAA,IAAS,YAAA;;;;;;AAmBzD;;iBAAgB,kBAAA,kBAAA,CACd,WAAA,GAAa,MAAA,EACb,OAAA,YACC,YAAA,CAAa,MAAA;;;;;;;;;iBAkBA,qBAAA,kBAAA,CAAwC,GAAA,YAAe,YAAA,CAAa,MAAA;;;;;AAApF;;iBA6BgB,cAAA,QAAA,CAAuB,OAAA,EAAS,YAAA,CAAa,MAAA,IAAU,MAAA;;;;;;;;AAAvE;;;;iBAegB,qBAAA,iBAAA,CAAuC,UAAA,YAAsB,KAAA;;KAOjE,oBAAA;EACN,SAAA;EAAgC,KAAA,EAAO,CAAA;AAAA;EACvC,SAAA;EAAiC,QAAA,EAAU,YAAA;EAAc,KAAA;AAAA;;AAT/D;;;;;;iBAkBgB,iBAAA,kBAAA,CACd,OAAA,EAAS,YAAA,CAAa,MAAA,GACtB,OAAA,EAAS,oBAAA,CAAqB,MAAA,IAC7B,YAAA,CAAa,MAAA;;;AAdhB;UA8CiB,gBAAA;EACf,OAAA;EA7C2D;EA+C3D,OAAA,EAAS,YAAA,CAAa,MAAA;AAAA;;;;;UAOP,gBAAA;EACf,OAAA;EAvDkE;EAyDlE,KAAA;EAhDc;EAkDd,QAAA;AAAA;AAAA,KAGU,eAAA,WAA0B,gBAAA,CAAiB,MAAA,IAAU,gBAAA;;;;;;UAOhD,yBAAA;EAzDF;EA2Db,gBAAA,GAAmB,SAAA,EAAW,aAAA,cAA2B,aAAA;IACvD,SAAA,EAAW,cAAA;EAAA;EA9Db;EAiEA,iBAAA,GACE,MAAA,EAAQ,YAAA,EACR,SAAA,EAAW,aAAA,cACR,aAAA;EAnEyB;EAqE9B,iBAAA,EAAmB,cAAA;EApElB;;EAuED,gBAAA,GACE,MAAA,EAAQ,YAAA,EACR,QAAA,GAAW,aAAA,cACR,aAAA;AAAA;AA1CP;;;;;;;;;;;AAUA;;;;;;;;;AAQA;;;;;;;;;;;;;;AAOA;;;;;;AAzBA,iBAqFgB,mBAAA,CACd,OAAA,EAAS,YAAA,WACT,MAAA,EAAQ,yBAAA,GACP,eAAA;;;;;;;;;;;;;iBAyGa,aAAA,WAAwB,iBAAA,CAAA,CACtC,UAAA,WACA,MAAA,EAAQ,YAAA,CAAa,CAAA,IACpB,gBAAA,CAAiB,CAAA"}
+{"version":3,"file":"block_storage.d.ts","names":[],"sources":["../src/block_storage.ts"],"mappings":";;;;;;AA4CqC;AAOrC;;cAxBa,iBAAA;;;;KAiBD,yBAAA;AAagD;AAK5D;;;;AAL4D,KANhD,UAAA,GAAa,OAAO;;;;;KAMpB,cAAA,GAAiB,MAAA,CAAO,YAAA,EAAc,UAAA;AAoBlD;;;AAAA,UAfiB,aAAA;EAiBL;EAfV,aAAA;EAmBmB;EAjBnB,MAAA,EAAQ,KAAK;AAAA;;;;;;;;;KAWH,YAAA;EAMV,qEAJU,iBAAA,GAAoB,yBAAA,EAIX;EAFnB,gBAAA,GAAmB,cAAA,EAGjB;EADF,SAAA,GAAY,MAAA,CAAO,YAAA,EAAc,aAAA;AAAA,IAC/B,aAAA,CAAc,MAAA;AAAM;AAMxB;;;AANwB,iBAMR,cAAA,CAAe,KAAA,YAAiB,KAAA,IAAS,YAAY;;;;;AAAA;AAmBrE;;iBAAgB,kBAAA,mBACd,WAAA,GAAa,MAAA,EACb,OAAA,YACC,YAAA,CAAa,MAAA;;;;;;;;;iBAkBA,qBAAA,mBAAwC,GAAA,YAAe,YAAY,CAAC,MAAA;;;;AAlB9D;AAkBtB;;iBA6BgB,cAAA,SAAuB,OAAA,EAAS,YAAA,CAAa,MAAA,IAAU,MAAA;;;;;;;AA7BmB;AA6B1F;;;;iBAegB,qBAAA,kBAAuC,UAAA,YAAsB,KAAK;;KAOtE,oBAAA;EACN,SAAA;EAAgC,KAAA,EAAO,CAAA;AAAA;EACvC,SAAA;EAAiC,QAAA,EAAU,YAAY;EAAE,KAAA;AAAA;AAxBc;AAe7E;;;;;;AAf6E,iBAiC7D,iBAAA,mBACd,OAAA,EAAS,YAAA,CAAa,MAAA,GACtB,OAAA,EAAS,oBAAA,CAAqB,MAAA,IAC7B,YAAA,CAAa,MAAA;;AArBkE;AAOlF;UA8CiB,gBAAA;EACf,OAAA;EA7C2D;EA+C3D,OAAA,EAAS,YAAY,CAAC,MAAA;AAAA;;;;;UAOP,gBAAA;EACf,OAAA;EAvDkE;EAyDlE,KAAA;EAhDc;EAkDd,QAAA;AAAA;AAAA,KAGU,eAAA,WAA0B,gBAAA,CAAiB,MAAA,IAAU,gBAAA;;;;;;UAOhD,yBAAA;EAzDF;EA2Db,gBAAA,GAAmB,SAAA,EAAW,aAAA,cAA2B,aAAA;IACvD,SAAA,EAAW,cAAA;EAAA;EA9Db;EAiEA,iBAAA,GACE,MAAA,EAAQ,YAAA,EACR,SAAA,EAAW,aAAA,cACR,aAAA;EAnEyB;EAqE9B,iBAAA,EAAmB,cAAA;EApElB;;EAuED,gBAAA,GACE,MAAA,EAAQ,YAAA,EACR,QAAA,GAAW,aAAA,cACR,aAAA;AAAA;AA1CP;;;;;;;;;;AAG8B;AAO9B;;;;;;;;AAKU;AAGV;;;;;;;;;;;;;AAAiF;AAOjF;;;;;;AAzBA,iBAqFgB,mBAAA,CACd,OAAA,EAAS,YAAA,WACT,MAAA,EAAQ,yBAAA,GACP,eAAA;;;;;;;;;;;;;iBAyGa,aAAA,WAAwB,iBAAA,EACtC,UAAA,WACA,MAAA,EAAQ,YAAA,CAAa,CAAA,IACpB,gBAAA,CAAiB,CAAA"}

package/dist/block_storage.js.map

@@ -1 +1 @@
-{"version":3,"file":"block_storage.js","names":[],"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\nimport type { Branded } from \"@milaboratories/pl-model-common\";\nimport {\n  type DataVersioned,\n  type TransferRecord,\n  isDataUnrecoverableError,\n} from \"./block_migrations\";\nimport type { PluginHandle, PluginFactoryLike, InferFactoryData } from \"./plugin_handle\";\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 * Default data version for new blocks without migrations.\n * Unique identifier ensures blocks are created via DataModel API.\n */\nexport const DATA_MODEL_LEGACY_VERSION = \"__pl_v1_d4e8f2a1__\";\n\n/**\n * Type for valid schema versions\n */\nexport type BlockStorageSchemaVersion = \"v1\"; // Add 'v2', 'v3', etc. as schema evolves\n\n/**\n * Branded type for plugin names - globally unique plugin type identifiers.\n * Using a branded type enforces explicit casting (`as PluginName`) which makes\n * it easy to find all plugin name definitions in the codebase and verify uniqueness.\n */\nexport type PluginName = Branded<string, \"PluginName\">;\n\n/**\n * Plugin registry - maps pluginId (unique within a block) to pluginName (globally unique plugin type).\n * Using a Record highlights that pluginIds must be unique within a block.\n */\nexport type PluginRegistry = Record<PluginHandle, PluginName>;\n\n/**\n * Versioned data - used for both block data and plugin data\n */\nexport interface VersionedData<TData = unknown> {\n  /** Version of the data, used for migrations */\n  __dataVersion: string;\n  /** The persistent data */\n  __data: TData;\n}\n\n/**\n * Core BlockStorage type that holds:\n * - __pl_a7f3e2b9__: Schema version (discriminator key identifies BlockStorage format)\n * - __dataVersion: Version key for block data migrations\n * - __data: The block's user-facing data (state)\n * - __pluginRegistry: Map from pluginId to pluginName (optional)\n * - __plugins: Plugin-specific data keyed by pluginId (optional)\n */\nexport type BlockStorage<TState = unknown> = {\n  /** Schema version - the key itself is the discriminator */\n  readonly [BLOCK_STORAGE_KEY]: BlockStorageSchemaVersion;\n  /** Registry of plugins: pluginId -> pluginName */\n  __pluginRegistry?: PluginRegistry;\n  /** Plugin-specific data, keyed by plugin handle */\n  __plugins?: Record<PluginHandle, VersionedData<unknown>>;\n} & VersionedData<TState>;\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 key (defaults to DATA_MODEL_LEGACY_VERSION)\n * @returns A new BlockStorage instance with discriminator key\n */\nexport function createBlockStorage<TState = unknown>(\n  initialData: TState = {} as TState,\n  version: string = DATA_MODEL_LEGACY_VERSION,\n): BlockStorage<TState> {\n  return {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: version,\n    __data: initialData,\n    __pluginRegistry: {},\n    __plugins: {},\n  };\n}\n\n/**\n * Normalizes raw storage data to BlockStorage format.\n * If the input is already a BlockStorage, returns it as-is (with defaults for missing fields).\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    const storage = raw as BlockStorage<TState>;\n    return {\n      ...storage,\n      // Fix for early released version where __dataVersion was a number\n      __dataVersion:\n        typeof storage.__dataVersion === \"number\"\n          ? DATA_MODEL_LEGACY_VERSION\n          : storage.__dataVersion,\n      // Ensure plugin fields have defaults\n      __pluginRegistry: storage.__pluginRegistry ?? {},\n      __plugins: storage.__plugins ?? {},\n    };\n  }\n  // Legacy format: raw is the state directly\n  return createBlockStorage(raw as TState);\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>(rawStorage: unknown): 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> =\n  | { operation: \"update-block-data\"; value: T }\n  | { operation: \"update-plugin-data\"; pluginId: PluginHandle; value: unknown };\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-block-data\":\n      return { ...storage, __data: payload.value };\n    case \"update-plugin-data\": {\n      const { pluginId, value } = payload;\n      const currentPlugins = storage.__plugins ?? {};\n      const existingEntry = currentPlugins[pluginId];\n      const version = existingEntry?.__dataVersion ?? DATA_MODEL_LEGACY_VERSION;\n      return {\n        ...storage,\n        __plugins: {\n          ...currentPlugins,\n          [pluginId]: {\n            __dataVersion: version,\n            __data: value,\n          },\n        },\n      };\n    }\n    default:\n      throw new Error(`Unknown storage operation: ${(payload as { operation: string }).operation}`);\n  }\n}\n\n// =============================================================================\n// Atomic Migration\n// =============================================================================\n\n/**\n * Result of a successful atomic migration.\n */\nexport interface MigrationSuccess<TState> {\n  success: true;\n  /** The fully migrated storage - commit this to persist */\n  storage: BlockStorage<TState>;\n}\n\n/**\n * Result of a failed atomic migration.\n * The original storage is untouched - user must choose to abort or reset.\n */\nexport interface MigrationFailure {\n  success: false;\n  /** Description of what failed */\n  error: string;\n  /** Which step failed: 'block' or pluginId */\n  failedAt: string;\n}\n\nexport type MigrationResult<TState> = MigrationSuccess<TState> | MigrationFailure;\n\n/**\n * Configuration for atomic block storage migration.\n * Callbacks use DataVersioned format (the DataModel API format).\n * Conversion to internal VersionedData format is handled by migrateBlockStorage().\n */\nexport interface MigrateBlockStorageConfig {\n  /** Migrate block data from any version to latest. Returns migrated data and transfers. */\n  migrateBlockData: (versioned: DataVersioned<unknown>) => DataVersioned<unknown> & {\n    transfers: TransferRecord;\n  };\n  /** Migrate each plugin's data. Return undefined to remove the plugin. Throws on failure. */\n  migratePluginData: (\n    handle: PluginHandle,\n    versioned: DataVersioned<unknown>,\n  ) => DataVersioned<unknown> | undefined;\n  /** The new plugin registry after migration (pluginId -> pluginName) */\n  newPluginRegistry: PluginRegistry;\n  /** Factory to create initial data for new plugins. Transfer is provided when a\n   *  .transfer() was defined for this plugin in the block's migration chain. */\n  createPluginData: (\n    handle: PluginHandle,\n    transfer?: DataVersioned<unknown>,\n  ) => DataVersioned<unknown>;\n}\n\n/**\n * Performs atomic migration of block storage including block data and all plugins.\n *\n * Migration is atomic: either everything succeeds and a new storage is returned,\n * or an error is returned and the original storage is completely untouched.\n *\n * Migration steps:\n * 1. Migrate block data\n * 2. For each plugin in newPluginRegistry:\n *    - If plugin exists with same name: migrate its data\n *    - Otherwise (new or type changed): create with initial data\n *    Plugins not in newPluginRegistry are dropped.\n *\n * If any step throws, migration fails and original storage is preserved.\n * User can then choose to:\n * - Abort: keep original storage, don't update block\n * - Reset: call createBlockStorage() to start fresh\n *\n * @param storage - The original storage (will not be modified)\n * @param config - Migration configuration\n * @returns Migration result - either success with new storage, or failure with error info\n *\n * @example\n * const result = migrateBlockStorage(storage, {\n *   migrateBlockData: (versioned) => blockDataModel.migrate(versioned),\n *   migratePluginData: (pluginId, versioned) => getPluginModel(pluginId).migrate(versioned),\n *   newPluginRegistry: { table1: 'dataTable' as PluginName },\n *   createPluginData: (pluginId) => getPluginModel(pluginId).getDefaultData(),\n * });\n *\n * if (result.success) {\n *   commitStorage(result.storage);\n * } else {\n *   const userChoice = await askUser(`Migration failed: ${result.error}. Reset data?`);\n *   if (userChoice === 'reset') {\n *     commitStorage(createBlockStorage(initialData, currentVersion));\n *   }\n *   // else: abort, keep original\n * }\n */\nexport function migrateBlockStorage(\n  storage: BlockStorage<unknown>,\n  config: MigrateBlockStorageConfig,\n): MigrationResult<unknown> {\n  const { migrateBlockData, migratePluginData, newPluginRegistry, createPluginData } = config;\n\n  // Step 1: Migrate block data and collect transfers\n  let migratedData: unknown;\n  let newVersion: string;\n  let transfers: TransferRecord;\n  try {\n    const result = migrateBlockData({ version: storage.__dataVersion, data: storage.__data });\n    migratedData = result.data;\n    newVersion = result.version;\n    transfers = result.transfers;\n  } catch (error) {\n    return {\n      success: false,\n      error: error instanceof Error ? error.message : String(error),\n      failedAt: \"block\",\n    };\n  }\n\n  // Step 2: Migrate plugins\n  const oldPlugins = storage.__plugins ?? {};\n  const oldRegistry = storage.__pluginRegistry ?? {};\n  const newPlugins: Record<PluginHandle, VersionedData<unknown>> = {};\n\n  for (const [key, pluginName] of Object.entries(newPluginRegistry)) {\n    const handle = key as PluginHandle;\n    const existingEntry = oldPlugins[handle];\n    const existingName = oldRegistry[handle];\n\n    try {\n      if (existingEntry && existingName === pluginName) {\n        // Plugin exists with same type - migrate its data\n        const migrated = migratePluginData(handle, {\n          version: existingEntry.__dataVersion,\n          data: existingEntry.__data,\n        });\n        if (migrated) {\n          newPlugins[handle] = { __dataVersion: migrated.version, __data: migrated.data };\n        }\n        // If undefined returned, plugin is intentionally removed\n      } else if (existingEntry) {\n        // Plugin type changed — pass old data with DATA_MODEL_LEGACY_VERSION.\n        // If the new plugin has upgradeLegacy(), it migrates the old data.\n        // If not, defaultRecover throws DataUnrecoverableError → fall back to init.\n        let recovered = false;\n        try {\n          const migrated = migratePluginData(handle, {\n            version: DATA_MODEL_LEGACY_VERSION,\n            data: existingEntry.__data,\n          });\n          if (migrated) {\n            newPlugins[handle] = { __dataVersion: migrated.version, __data: migrated.data };\n            recovered = true;\n          }\n        } catch (recoverError) {\n          if (!isDataUnrecoverableError(recoverError)) throw recoverError;\n        }\n        if (!recovered) {\n          const transfer = transfers[handle];\n          const initial = createPluginData(handle, transfer);\n          newPlugins[handle] = { __dataVersion: initial.version, __data: initial.data };\n        }\n      } else {\n        // New plugin - create with initial data, passing transfer if available\n        const transfer = transfers[handle];\n        const initial = createPluginData(handle, transfer);\n        newPlugins[handle] = { __dataVersion: initial.version, __data: initial.data };\n      }\n    } catch (error) {\n      return {\n        success: false,\n        error: error instanceof Error ? error.message : String(error),\n        failedAt: handle,\n      };\n    }\n  }\n\n  // Step 3: Build final storage atomically\n  const migratedStorage: BlockStorage = {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: newVersion,\n    __data: migratedData,\n    __pluginRegistry: newPluginRegistry,\n    __plugins: newPlugins,\n  };\n\n  return {\n    success: true,\n    storage: migratedStorage,\n  };\n}\n\n/**\n * Gets plugin-specific data from block storage.\n * Accepts raw storage (any format) and normalizes internally.\n *\n * When called with a typed PluginHandle<F>, the return type is automatically\n * inferred from the factory's phantom `__types.data` field.\n *\n * @param rawStorage - Raw block storage (may be legacy format or BlockStorage)\n * @param handle - The plugin handle (branded plugin instance id)\n * @returns The plugin data, typed via factory inference\n * @throws If plugin is not found in storage\n */\nexport function getPluginData<F extends PluginFactoryLike>(\n  rawStorage: unknown,\n  handle: PluginHandle<F>,\n): InferFactoryData<F> {\n  const storage = normalizeBlockStorage(rawStorage);\n  const pluginEntry = storage.__plugins?.[handle];\n  if (!pluginEntry) throw new Error(`Plugin '${handle}' not found in block storage`);\n  return pluginEntry.__data as InferFactoryData<F>;\n}\n"],"mappings":"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"}
+{"version":3,"file":"block_storage.js","names":["obj"],"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\nimport type { Branded } from \"@milaboratories/pl-model-common\";\nimport {\n  type DataVersioned,\n  type TransferRecord,\n  isDataUnrecoverableError,\n} from \"./block_migrations\";\nimport type { PluginHandle, PluginFactoryLike, InferFactoryData } from \"./plugin_handle\";\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 * Default data version for new blocks without migrations.\n * Unique identifier ensures blocks are created via DataModel API.\n */\nexport const DATA_MODEL_LEGACY_VERSION = \"__pl_v1_d4e8f2a1__\";\n\n/**\n * Type for valid schema versions\n */\nexport type BlockStorageSchemaVersion = \"v1\"; // Add 'v2', 'v3', etc. as schema evolves\n\n/**\n * Branded type for plugin names - globally unique plugin type identifiers.\n * Using a branded type enforces explicit casting (`as PluginName`) which makes\n * it easy to find all plugin name definitions in the codebase and verify uniqueness.\n */\nexport type PluginName = Branded<string, \"PluginName\">;\n\n/**\n * Plugin registry - maps pluginId (unique within a block) to pluginName (globally unique plugin type).\n * Using a Record highlights that pluginIds must be unique within a block.\n */\nexport type PluginRegistry = Record<PluginHandle, PluginName>;\n\n/**\n * Versioned data - used for both block data and plugin data\n */\nexport interface VersionedData<TData = unknown> {\n  /** Version of the data, used for migrations */\n  __dataVersion: string;\n  /** The persistent data */\n  __data: TData;\n}\n\n/**\n * Core BlockStorage type that holds:\n * - __pl_a7f3e2b9__: Schema version (discriminator key identifies BlockStorage format)\n * - __dataVersion: Version key for block data migrations\n * - __data: The block's user-facing data (state)\n * - __pluginRegistry: Map from pluginId to pluginName (optional)\n * - __plugins: Plugin-specific data keyed by pluginId (optional)\n */\nexport type BlockStorage<TState = unknown> = {\n  /** Schema version - the key itself is the discriminator */\n  readonly [BLOCK_STORAGE_KEY]: BlockStorageSchemaVersion;\n  /** Registry of plugins: pluginId -> pluginName */\n  __pluginRegistry?: PluginRegistry;\n  /** Plugin-specific data, keyed by plugin handle */\n  __plugins?: Record<PluginHandle, VersionedData<unknown>>;\n} & VersionedData<TState>;\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 key (defaults to DATA_MODEL_LEGACY_VERSION)\n * @returns A new BlockStorage instance with discriminator key\n */\nexport function createBlockStorage<TState = unknown>(\n  initialData: TState = {} as TState,\n  version: string = DATA_MODEL_LEGACY_VERSION,\n): BlockStorage<TState> {\n  return {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: version,\n    __data: initialData,\n    __pluginRegistry: {},\n    __plugins: {},\n  };\n}\n\n/**\n * Normalizes raw storage data to BlockStorage format.\n * If the input is already a BlockStorage, returns it as-is (with defaults for missing fields).\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    const storage = raw as BlockStorage<TState>;\n    return {\n      ...storage,\n      // Fix for early released version where __dataVersion was a number\n      __dataVersion:\n        typeof storage.__dataVersion === \"number\"\n          ? DATA_MODEL_LEGACY_VERSION\n          : storage.__dataVersion,\n      // Ensure plugin fields have defaults\n      __pluginRegistry: storage.__pluginRegistry ?? {},\n      __plugins: storage.__plugins ?? {},\n    };\n  }\n  // Legacy format: raw is the state directly\n  return createBlockStorage(raw as TState);\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>(rawStorage: unknown): 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> =\n  | { operation: \"update-block-data\"; value: T }\n  | { operation: \"update-plugin-data\"; pluginId: PluginHandle; value: unknown };\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-block-data\":\n      return { ...storage, __data: payload.value };\n    case \"update-plugin-data\": {\n      const { pluginId, value } = payload;\n      const currentPlugins = storage.__plugins ?? {};\n      const existingEntry = currentPlugins[pluginId];\n      const version = existingEntry?.__dataVersion ?? DATA_MODEL_LEGACY_VERSION;\n      return {\n        ...storage,\n        __plugins: {\n          ...currentPlugins,\n          [pluginId]: {\n            __dataVersion: version,\n            __data: value,\n          },\n        },\n      };\n    }\n    default:\n      throw new Error(`Unknown storage operation: ${(payload as { operation: string }).operation}`);\n  }\n}\n\n// =============================================================================\n// Atomic Migration\n// =============================================================================\n\n/**\n * Result of a successful atomic migration.\n */\nexport interface MigrationSuccess<TState> {\n  success: true;\n  /** The fully migrated storage - commit this to persist */\n  storage: BlockStorage<TState>;\n}\n\n/**\n * Result of a failed atomic migration.\n * The original storage is untouched - user must choose to abort or reset.\n */\nexport interface MigrationFailure {\n  success: false;\n  /** Description of what failed */\n  error: string;\n  /** Which step failed: 'block' or pluginId */\n  failedAt: string;\n}\n\nexport type MigrationResult<TState> = MigrationSuccess<TState> | MigrationFailure;\n\n/**\n * Configuration for atomic block storage migration.\n * Callbacks use DataVersioned format (the DataModel API format).\n * Conversion to internal VersionedData format is handled by migrateBlockStorage().\n */\nexport interface MigrateBlockStorageConfig {\n  /** Migrate block data from any version to latest. Returns migrated data and transfers. */\n  migrateBlockData: (versioned: DataVersioned<unknown>) => DataVersioned<unknown> & {\n    transfers: TransferRecord;\n  };\n  /** Migrate each plugin's data. Return undefined to remove the plugin. Throws on failure. */\n  migratePluginData: (\n    handle: PluginHandle,\n    versioned: DataVersioned<unknown>,\n  ) => DataVersioned<unknown> | undefined;\n  /** The new plugin registry after migration (pluginId -> pluginName) */\n  newPluginRegistry: PluginRegistry;\n  /** Factory to create initial data for new plugins. Transfer is provided when a\n   *  .transfer() was defined for this plugin in the block's migration chain. */\n  createPluginData: (\n    handle: PluginHandle,\n    transfer?: DataVersioned<unknown>,\n  ) => DataVersioned<unknown>;\n}\n\n/**\n * Performs atomic migration of block storage including block data and all plugins.\n *\n * Migration is atomic: either everything succeeds and a new storage is returned,\n * or an error is returned and the original storage is completely untouched.\n *\n * Migration steps:\n * 1. Migrate block data\n * 2. For each plugin in newPluginRegistry:\n *    - If plugin exists with same name: migrate its data\n *    - Otherwise (new or type changed): create with initial data\n *    Plugins not in newPluginRegistry are dropped.\n *\n * If any step throws, migration fails and original storage is preserved.\n * User can then choose to:\n * - Abort: keep original storage, don't update block\n * - Reset: call createBlockStorage() to start fresh\n *\n * @param storage - The original storage (will not be modified)\n * @param config - Migration configuration\n * @returns Migration result - either success with new storage, or failure with error info\n *\n * @example\n * const result = migrateBlockStorage(storage, {\n *   migrateBlockData: (versioned) => blockDataModel.migrate(versioned),\n *   migratePluginData: (pluginId, versioned) => getPluginModel(pluginId).migrate(versioned),\n *   newPluginRegistry: { table1: 'dataTable' as PluginName },\n *   createPluginData: (pluginId) => getPluginModel(pluginId).getDefaultData(),\n * });\n *\n * if (result.success) {\n *   commitStorage(result.storage);\n * } else {\n *   const userChoice = await askUser(`Migration failed: ${result.error}. Reset data?`);\n *   if (userChoice === 'reset') {\n *     commitStorage(createBlockStorage(initialData, currentVersion));\n *   }\n *   // else: abort, keep original\n * }\n */\nexport function migrateBlockStorage(\n  storage: BlockStorage<unknown>,\n  config: MigrateBlockStorageConfig,\n): MigrationResult<unknown> {\n  const { migrateBlockData, migratePluginData, newPluginRegistry, createPluginData } = config;\n\n  // Step 1: Migrate block data and collect transfers\n  let migratedData: unknown;\n  let newVersion: string;\n  let transfers: TransferRecord;\n  try {\n    const result = migrateBlockData({ version: storage.__dataVersion, data: storage.__data });\n    migratedData = result.data;\n    newVersion = result.version;\n    transfers = result.transfers;\n  } catch (error) {\n    return {\n      success: false,\n      error: error instanceof Error ? error.message : String(error),\n      failedAt: \"block\",\n    };\n  }\n\n  // Step 2: Migrate plugins\n  const oldPlugins = storage.__plugins ?? {};\n  const oldRegistry = storage.__pluginRegistry ?? {};\n  const newPlugins: Record<PluginHandle, VersionedData<unknown>> = {};\n\n  for (const [key, pluginName] of Object.entries(newPluginRegistry)) {\n    const handle = key as PluginHandle;\n    const existingEntry = oldPlugins[handle];\n    const existingName = oldRegistry[handle];\n\n    try {\n      if (existingEntry && existingName === pluginName) {\n        // Plugin exists with same type - migrate its data\n        const migrated = migratePluginData(handle, {\n          version: existingEntry.__dataVersion,\n          data: existingEntry.__data,\n        });\n        if (migrated) {\n          newPlugins[handle] = { __dataVersion: migrated.version, __data: migrated.data };\n        }\n        // If undefined returned, plugin is intentionally removed\n      } else if (existingEntry) {\n        // Plugin type changed — pass old data with DATA_MODEL_LEGACY_VERSION.\n        // If the new plugin has upgradeLegacy(), it migrates the old data.\n        // If not, defaultRecover throws DataUnrecoverableError → fall back to init.\n        let recovered = false;\n        try {\n          const migrated = migratePluginData(handle, {\n            version: DATA_MODEL_LEGACY_VERSION,\n            data: existingEntry.__data,\n          });\n          if (migrated) {\n            newPlugins[handle] = { __dataVersion: migrated.version, __data: migrated.data };\n            recovered = true;\n          }\n        } catch (recoverError) {\n          if (!isDataUnrecoverableError(recoverError)) throw recoverError;\n        }\n        if (!recovered) {\n          const transfer = transfers[handle];\n          const initial = createPluginData(handle, transfer);\n          newPlugins[handle] = { __dataVersion: initial.version, __data: initial.data };\n        }\n      } else {\n        // New plugin - create with initial data, passing transfer if available\n        const transfer = transfers[handle];\n        const initial = createPluginData(handle, transfer);\n        newPlugins[handle] = { __dataVersion: initial.version, __data: initial.data };\n      }\n    } catch (error) {\n      return {\n        success: false,\n        error: error instanceof Error ? error.message : String(error),\n        failedAt: handle,\n      };\n    }\n  }\n\n  // Step 3: Build final storage atomically\n  const migratedStorage: BlockStorage = {\n    [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,\n    __dataVersion: newVersion,\n    __data: migratedData,\n    __pluginRegistry: newPluginRegistry,\n    __plugins: newPlugins,\n  };\n\n  return {\n    success: true,\n    storage: migratedStorage,\n  };\n}\n\n/**\n * Gets plugin-specific data from block storage.\n * Accepts raw storage (any format) and normalizes internally.\n *\n * When called with a typed PluginHandle<F>, the return type is automatically\n * inferred from the factory's phantom `__types.data` field.\n *\n * @param rawStorage - Raw block storage (may be legacy format or BlockStorage)\n * @param handle - The plugin handle (branded plugin instance id)\n * @returns The plugin data, typed via factory inference\n * @throws If plugin is not found in storage\n */\nexport function getPluginData<F extends PluginFactoryLike>(\n  rawStorage: unknown,\n  handle: PluginHandle<F>,\n): InferFactoryData<F> {\n  const storage = normalizeBlockStorage(rawStorage);\n  const pluginEntry = storage.__plugins?.[handle];\n  if (!pluginEntry) throw new Error(`Plugin '${handle}' not found in block storage`);\n  return pluginEntry.__data as InferFactoryData<F>;\n}\n"],"mappings":"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"}

package/dist/block_storage_callbacks.cjs

@@ -1,4 +1,3 @@
-require("./_virtual/_rolldown/runtime.cjs");
 const require_block_storage = require("./block_storage.cjs");
 let _milaboratories_pl_model_common = require("@milaboratories/pl-model-common");
 //#region src/block_storage_callbacks.ts
@@ -178,6 +177,7 @@ function derivePrerunArgsFromStorage(storageJson, argsFunction, prerunArgsFuncti
 	}
 }
 //#endregion
+exports.BLOCK_STORAGE_KEY = require_block_storage.BLOCK_STORAGE_KEY;
 exports.applyStorageUpdate = applyStorageUpdate;
 exports.createInitialStorage = createInitialStorage;
 exports.deriveArgsFromStorage = deriveArgsFromStorage;

package/dist/block_storage_callbacks.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"block_storage_callbacks.cjs","names":["createBlockStorage","isBlockStorage","normalizeBlockStorage","getStorageData","updateStorageData","migrateBlockStorage","BLOCK_STORAGE_KEY"],"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 PluginRegistry,\n  type VersionedData,\n  createBlockStorage,\n  getStorageData,\n  isBlockStorage,\n  migrateBlockStorage,\n  normalizeBlockStorage,\n  updateStorageData,\n} from \"./block_storage\";\nimport type { PluginHandle } from \"./plugin_handle\";\n\nimport { stringifyJson, type StringifiedJson } from \"@milaboratories/pl-model-common\";\nimport type { DataVersioned, TransferRecord } from \"./block_migrations\";\nimport type { StorageDebugView } from \"@milaboratories/pl-model-middle-layer\";\n\n// =============================================================================\n// Hook interfaces for dependency injection\n// =============================================================================\n\n/** Dependencies for storage migration */\nexport interface MigrationHooks {\n  migrateBlockData: (versioned: DataVersioned<unknown>) => DataVersioned<unknown> & {\n    transfers: TransferRecord;\n  };\n  getPluginRegistry: () => PluginRegistry;\n  migratePluginData: (\n    handle: PluginHandle,\n    versioned: DataVersioned<unknown>,\n  ) => DataVersioned<unknown> | undefined;\n  createPluginData: (\n    handle: PluginHandle,\n    transfer?: DataVersioned<unknown>,\n  ) => DataVersioned<unknown>;\n}\n\n/** Dependencies for initial storage creation */\nexport interface InitialStorageHooks {\n  getDefaultBlockData: () => DataVersioned<unknown>;\n  getPluginRegistry: () => PluginRegistry;\n  createPluginData: (handle: PluginHandle) => 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 * @throws If initialDataFn or createPluginData throws\n */\nexport function createInitialStorage(hooks: InitialStorageHooks): StringifiedJson<BlockStorage> {\n  const blockDefault = hooks.getDefaultBlockData();\n  const pluginRegistry = hooks.getPluginRegistry();\n\n  const plugins: Record<PluginHandle, VersionedData<unknown>> = {};\n  for (const handle of Object.keys(pluginRegistry) as PluginHandle[]) {\n    const initial = hooks.createPluginData(handle);\n    plugins[handle] = { __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"],"mappings":"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"}
+{"version":3,"file":"block_storage_callbacks.cjs","names":["createBlockStorage","isBlockStorage","normalizeBlockStorage","getStorageData","updateStorageData","obj","migrateBlockStorage","BLOCK_STORAGE_KEY"],"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 PluginRegistry,\n  type VersionedData,\n  createBlockStorage,\n  getStorageData,\n  isBlockStorage,\n  migrateBlockStorage,\n  normalizeBlockStorage,\n  updateStorageData,\n} from \"./block_storage\";\nimport type { PluginHandle } from \"./plugin_handle\";\n\nimport { stringifyJson, type StringifiedJson } from \"@milaboratories/pl-model-common\";\nimport type { DataVersioned, TransferRecord } from \"./block_migrations\";\nimport type { StorageDebugView } from \"@milaboratories/pl-model-middle-layer\";\n\n// =============================================================================\n// Hook interfaces for dependency injection\n// =============================================================================\n\n/** Dependencies for storage migration */\nexport interface MigrationHooks {\n  migrateBlockData: (versioned: DataVersioned<unknown>) => DataVersioned<unknown> & {\n    transfers: TransferRecord;\n  };\n  getPluginRegistry: () => PluginRegistry;\n  migratePluginData: (\n    handle: PluginHandle,\n    versioned: DataVersioned<unknown>,\n  ) => DataVersioned<unknown> | undefined;\n  createPluginData: (\n    handle: PluginHandle,\n    transfer?: DataVersioned<unknown>,\n  ) => DataVersioned<unknown>;\n}\n\n/** Dependencies for initial storage creation */\nexport interface InitialStorageHooks {\n  getDefaultBlockData: () => DataVersioned<unknown>;\n  getPluginRegistry: () => PluginRegistry;\n  createPluginData: (handle: PluginHandle) => 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 * @throws If initialDataFn or createPluginData throws\n */\nexport function createInitialStorage(hooks: InitialStorageHooks): StringifiedJson<BlockStorage> {\n  const blockDefault = hooks.getDefaultBlockData();\n  const pluginRegistry = hooks.getPluginRegistry();\n\n  const plugins: Record<PluginHandle, VersionedData<unknown>> = {};\n  for (const handle of Object.keys(pluginRegistry) as PluginHandle[]) {\n    const initial = hooks.createPluginData(handle);\n    plugins[handle] = { __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"],"mappings":"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"}

package/dist/block_storage_callbacks.js

@@ -177,6 +177,6 @@ function derivePrerunArgsFromStorage(storageJson, argsFunction, prerunArgsFuncti
 	}
 }
 //#endregion
-export { applyStorageUpdate, createInitialStorage, deriveArgsFromStorage, derivePrerunArgsFromStorage, getStorageDebugView, migrateStorage };
+export { BLOCK_STORAGE_KEY, applyStorageUpdate, createInitialStorage, deriveArgsFromStorage, derivePrerunArgsFromStorage, getStorageDebugView, migrateStorage };
 
 //# sourceMappingURL=block_storage_callbacks.js.map

package/dist/block_storage_callbacks.js.map

@@ -1 +1 @@
-{"version":3,"file":"block_storage_callbacks.js","names":[],"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 PluginRegistry,\n  type VersionedData,\n  createBlockStorage,\n  getStorageData,\n  isBlockStorage,\n  migrateBlockStorage,\n  normalizeBlockStorage,\n  updateStorageData,\n} from \"./block_storage\";\nimport type { PluginHandle } from \"./plugin_handle\";\n\nimport { stringifyJson, type StringifiedJson } from \"@milaboratories/pl-model-common\";\nimport type { DataVersioned, TransferRecord } from \"./block_migrations\";\nimport type { StorageDebugView } from \"@milaboratories/pl-model-middle-layer\";\n\n// =============================================================================\n// Hook interfaces for dependency injection\n// =============================================================================\n\n/** Dependencies for storage migration */\nexport interface MigrationHooks {\n  migrateBlockData: (versioned: DataVersioned<unknown>) => DataVersioned<unknown> & {\n    transfers: TransferRecord;\n  };\n  getPluginRegistry: () => PluginRegistry;\n  migratePluginData: (\n    handle: PluginHandle,\n    versioned: DataVersioned<unknown>,\n  ) => DataVersioned<unknown> | undefined;\n  createPluginData: (\n    handle: PluginHandle,\n    transfer?: DataVersioned<unknown>,\n  ) => DataVersioned<unknown>;\n}\n\n/** Dependencies for initial storage creation */\nexport interface InitialStorageHooks {\n  getDefaultBlockData: () => DataVersioned<unknown>;\n  getPluginRegistry: () => PluginRegistry;\n  createPluginData: (handle: PluginHandle) => 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 * @throws If initialDataFn or createPluginData throws\n */\nexport function createInitialStorage(hooks: InitialStorageHooks): StringifiedJson<BlockStorage> {\n  const blockDefault = hooks.getDefaultBlockData();\n  const pluginRegistry = hooks.getPluginRegistry();\n\n  const plugins: Record<PluginHandle, VersionedData<unknown>> = {};\n  for (const handle of Object.keys(pluginRegistry) as PluginHandle[]) {\n    const initial = hooks.createPluginData(handle);\n    plugins[handle] = { __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"],"mappings":"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"}
+{"version":3,"file":"block_storage_callbacks.js","names":["obj"],"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 PluginRegistry,\n  type VersionedData,\n  createBlockStorage,\n  getStorageData,\n  isBlockStorage,\n  migrateBlockStorage,\n  normalizeBlockStorage,\n  updateStorageData,\n} from \"./block_storage\";\nimport type { PluginHandle } from \"./plugin_handle\";\n\nimport { stringifyJson, type StringifiedJson } from \"@milaboratories/pl-model-common\";\nimport type { DataVersioned, TransferRecord } from \"./block_migrations\";\nimport type { StorageDebugView } from \"@milaboratories/pl-model-middle-layer\";\n\n// =============================================================================\n// Hook interfaces for dependency injection\n// =============================================================================\n\n/** Dependencies for storage migration */\nexport interface MigrationHooks {\n  migrateBlockData: (versioned: DataVersioned<unknown>) => DataVersioned<unknown> & {\n    transfers: TransferRecord;\n  };\n  getPluginRegistry: () => PluginRegistry;\n  migratePluginData: (\n    handle: PluginHandle,\n    versioned: DataVersioned<unknown>,\n  ) => DataVersioned<unknown> | undefined;\n  createPluginData: (\n    handle: PluginHandle,\n    transfer?: DataVersioned<unknown>,\n  ) => DataVersioned<unknown>;\n}\n\n/** Dependencies for initial storage creation */\nexport interface InitialStorageHooks {\n  getDefaultBlockData: () => DataVersioned<unknown>;\n  getPluginRegistry: () => PluginRegistry;\n  createPluginData: (handle: PluginHandle) => 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 * @throws If initialDataFn or createPluginData throws\n */\nexport function createInitialStorage(hooks: InitialStorageHooks): StringifiedJson<BlockStorage> {\n  const blockDefault = hooks.getDefaultBlockData();\n  const pluginRegistry = hooks.getPluginRegistry();\n\n  const plugins: Record<PluginHandle, VersionedData<unknown>> = {};\n  for (const handle of Object.keys(pluginRegistry) as PluginHandle[]) {\n    const initial = hooks.createPluginData(handle);\n    plugins[handle] = { __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"],"mappings":"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"}

package/dist/block_storage_facade.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"block_storage_facade.cjs","names":["createRenderLambda"],"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"],"mappings":";;;;;;AA8DA,MAAa,+BAA+B;;;;;;;;;;AAe5C,MAAa,8BAA8B;CACzC,oBAAoB;CACpB,kBAAkB;CAClB,gBAAgB;CAChB,YAAY;CACZ,kBAAkB;CAClB,gBAAgB;CACjB;;;;;AAMD,SAAS,oBACP,WAC2C;AAC3C,QAAO,OAAO,YACZ,OAAO,OAAO,UAAU,CAAC,KAAK,WAAW,CAAC,QAAQA,iBAAAA,mBAAmB,EAAE,QAAQ,CAAC,CAAC,CAAC,CACnF;;;;;;AAOH,MAAa,4BAA4B,oBAAoB,4BAA4B;;AA4FzF,SAAgB,wBAAwB,WAAqC;AAC3E,MAAK,MAAM,OAAO,OAAO,OAAO,4BAA4B,CAC1D,kBAAA,oBAAoB,KAAK,UAAU,KAAgC"}
+{"version":3,"file":"block_storage_facade.cjs","names":["createRenderLambda"],"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"],"mappings":";;;;;;AA8DA,MAAa,+BAA+B;;;;;;;;;;AAe5C,MAAa,8BAA8B;CACzC,oBAAoB;CACpB,kBAAkB;CAClB,gBAAgB;CAChB,YAAY;CACZ,kBAAkB;CAClB,gBAAgB;AAClB;;;;;AAMA,SAAS,oBACP,WAC2C;CAC3C,OAAO,OAAO,YACZ,OAAO,OAAO,SAAS,CAAC,CAAC,KAAK,WAAW,CAAC,QAAQA,iBAAAA,mBAAmB,EAAE,OAAO,CAAC,CAAC,CAAC,CACnF;AACF;;;;;AAMA,MAAa,4BAA4B,oBAAoB,2BAA2B;;AA4FxF,SAAgB,wBAAwB,WAAqC;CAC3E,KAAK,MAAM,OAAO,OAAO,OAAO,2BAA2B,GACzD,iBAAA,oBAAoB,KAAK,UAAU,IAA+B;AAEtE"}