@platforma-sdk/model 1.81.1 → 1.82.0

package/dist/block_migrations.d.ts

@@ -1,8 +1,28 @@
+import { BlockKindReference } from "@milaboratories/pl-model-common";
+import { CompiledBlockKind } from "@platforma-sdk/block-kind";
+
 //#region src/block_migrations.d.ts
 type DataVersionKey = string;
 type DataMigrateFn<From, To> = (prev: Readonly<From>) => To;
-type DataCreateFn<T> = () => T;
+/**
+ * Initial-data factory. Object-arg so future inputs (services, resolved refs)
+ * can extend it without a signature break. `Params` carries the block's
+ * kind-declared params type; `never` means the block reads no params yet.
+ */
+type DataCreateFn<T, Params = never> = (args: {
+  params?: Params;
+}) => T;
 type DataRecoverFn<T> = (version: DataVersionKey, data: unknown) => T;
+/**
+ * The compiled block-kind object a block declares — exactly the output of
+ * `defineBlockKind` from `@platforma-sdk/block-kind`, consumed type-only.
+ *
+ * The kind object carries no reference field: the `{name}@{version}` reference
+ * is derived from it internally (via `formatKindRef`) at the point the builder
+ * and `BlockModelV3.create` need it. Aliased here so `DataModelBuilder` /
+ * `create` signatures directly accept `defineBlockKind`'s output.
+ */
+type BlockKind<Params = never> = CompiledBlockKind<Params>;
 /**
  * Minimal interface that .transfer() accepts. PluginInstance implements this.
  * Defined here to avoid circular dependency with plugin_model.ts.
@@ -52,20 +72,35 @@ type LegacyV1State<Args, UiState> = {
   args: Args;
   uiState: UiState;
 };
-/** Internal state passed from builder to DataModel */
-type BuilderState<S> = {
-  versionChain: DataVersionKey[];
-  steps: MigrationStep[];
-  transferSteps: TransferStep[];
-  initialDataFn: () => S;
+/**
+ * The kind a chain belongs to, threaded unchanged from the builder into `DataModel`.
+ *
+ * Named because every constructor in this file carries exactly this pair, and they travel
+ * together by construction: a reference with no parser could not check the params it names,
+ * and a parser with no reference would have nothing to check them against.
+ */
+type KindWiring = {
+  /** Reference to the block kind this data model belongs to, if declared. */kindRef?: BlockKindReference; /** The kind's runtime params check, threaded with {@link KindWiring.kindRef}. */
+  parseInitializationParams?: (value: unknown) => unknown;
+};
+type RecoverState = {
   recoverFn?: (version: DataVersionKey, data: unknown) => unknown;
   /** Index of the first step to run after recovery. Equals the number of steps
    *  present at the time recover() was called. */
   recoverFromIndex?: number;
 };
-type RecoverState = {
-  recoverFn?: (version: DataVersionKey, data: unknown) => unknown;
-  recoverFromIndex?: number;
+/** Internal state passed from builder to DataModel */
+type BuilderState<S> = KindWiring & RecoverState & {
+  versionChain: DataVersionKey[];
+  steps: MigrationStep[];
+  transferSteps: TransferStep[];
+  /**
+   * The params type is erased to `unknown` here: the builder checks the block's
+   * factory against its kind's params, but a caller that supplies params carries them as
+   * data it did not type — parsed file content, today — and cannot state the type. The
+   * kind's own parser is what recovers it.
+   */
+  initialDataFn: DataCreateFn<S, unknown>;
 };
 /**
  * Abstract base for both migration chain types.
@@ -76,11 +111,15 @@ type RecoverState = {
  *
  * @internal
  */
-declare abstract class MigrationChainBase<Current, Transfers extends Record<string, unknown> = {}> {
+declare abstract class MigrationChainBase<Current, Transfers extends Record<string, unknown> = {}, Params = never> {
   protected readonly versionChain: DataVersionKey[];
   protected readonly migrationSteps: MigrationStep[];
   protected readonly transferSteps: TransferStep[];
-  protected constructor(state: {
+  /** Kind reference seeded by the builder, threaded through the chain into init(). */
+  protected readonly kindRef?: BlockKindReference;
+  /** The kind's runtime params check, carried for `init()` to hand to the DataModel. */
+  protected readonly parseInitializationParams?: (value: unknown) => unknown;
+  protected constructor(state: KindWiring & {
     versionChain: DataVersionKey[];
     steps: MigrationStep[];
     transferSteps?: TransferStep[];
@@ -102,7 +141,7 @@ declare abstract class MigrationChainBase<Current, Transfers extends Record<stri
    * @param initialData - Factory function returning the initial state
    * @returns Finalized DataModel instance
    */
-  init(initialData: DataCreateFn<Current>): DataModel<Current, Transfers>;
+  init(initialData: DataCreateFn<Current, Params>): DataModel<Current, Params, Transfers>;
 }
 /**
  * Migration chain after recover() or upgradeLegacy() has been called.
@@ -113,29 +152,27 @@ declare abstract class MigrationChainBase<Current, Transfers extends Record<stri
  * @typeParam Transfers - Accumulated transfer types keyed by plugin ID
  * @internal
  */
-declare class DataModelMigrationChainWithRecover<Current, Transfers extends Record<string, unknown> = {}> extends MigrationChainBase<Current, Transfers> {
+declare class DataModelMigrationChainWithRecover<Current, Transfers extends Record<string, unknown> = {}, Params = never> extends MigrationChainBase<Current, Transfers, Params> {
   private readonly recoverFn?;
   private readonly recoverFromIndex?;
   /** @internal */
-  constructor(state: {
+  constructor(state: KindWiring & RecoverState & {
     versionChain: DataVersionKey[];
     steps: MigrationStep[];
     transferSteps?: TransferStep[];
-    recoverFn?: (version: DataVersionKey, data: unknown) => unknown;
-    recoverFromIndex?: number;
   });
   protected recoverState(): RecoverState;
   /**
    * Add a migration step. Same semantics as on the base chain.
    * recover() and upgradeLegacy() are not available — one has already been called.
    */
-  migrate<Next>(nextVersion: string, fn: DataMigrateFn<Current, Next>): DataModelMigrationChainWithRecover<Next, Transfers>;
+  migrate<Next>(nextVersion: string, fn: DataMigrateFn<Current, Next>): DataModelMigrationChainWithRecover<Next, Transfers, Params>;
   /**
    * Extract data at the current chain position for seeding a new plugin.
    * The extract function's return type must match the plugin's transfer data type.
    * Duplicate plugin IDs are rejected at both type and runtime level.
    */
-  transfer<Id extends string, L>(target: TransferTarget<Id & (Id extends keyof Transfers ? never : string), L>, extract: (data: Current) => L): DataModelMigrationChainWithRecover<Current, Transfers & Record<Id, L>>;
+  transfer<Id extends string, L>(target: TransferTarget<Id & (Id extends keyof Transfers ? never : string), L>, extract: (data: Current) => L): DataModelMigrationChainWithRecover<Current, Transfers & Record<Id, L>, Params>;
 }
 /**
  * Migration chain builder.
@@ -147,13 +184,15 @@ declare class DataModelMigrationChainWithRecover<Current, Transfers extends Reco
  * @typeParam Transfers - Accumulated transfer types keyed by plugin ID
  * @internal
  */
-declare class DataModelMigrationChain<Current, Transfers extends Record<string, unknown> = {}> extends MigrationChainBase<Current, Transfers> {
+declare class DataModelMigrationChain<Current, Transfers extends Record<string, unknown> = {}, Params = never> extends MigrationChainBase<Current, Transfers, Params> {
   /** @internal */
   constructor({
     versionChain,
     steps,
-    transferSteps
-  }: {
+    transferSteps,
+    kindRef,
+    parseInitializationParams
+  }: KindWiring & {
     versionChain: DataVersionKey[];
     steps?: MigrationStep[];
     transferSteps?: TransferStep[];
@@ -169,7 +208,7 @@ declare class DataModelMigrationChain<Current, Transfers extends Record<string,
    * @example
    * .migrate<BlockDataV2>("v2", (v1) => ({ ...v1, labels: [] }))
    */
-  migrate<Next>(nextVersion: string, fn: DataMigrateFn<Current, Next>): DataModelMigrationChain<Next, Transfers>;
+  migrate<Next>(nextVersion: string, fn: DataMigrateFn<Current, Next>): DataModelMigrationChain<Next, Transfers, Params>;
   /**
    * Extract data at the current chain position for seeding a new plugin.
    * The extract function's return type must match the plugin's transfer data type.
@@ -183,7 +222,7 @@ declare class DataModelMigrationChain<Current, Transfers extends Record<string,
    * .transfer(tablePlugin, (v1) => ({ state: v1.tableState }))
    * .migrate<V2>("v2", ({ tableState: _, ...rest }) => rest)
    */
-  transfer<Id extends string, L>(target: TransferTarget<Id & (Id extends keyof Transfers ? never : string), L>, extract: (data: Current) => L): DataModelMigrationChain<Current, Transfers & Record<Id, L>>;
+  transfer<Id extends string, L>(target: TransferTarget<Id & (Id extends keyof Transfers ? never : string), L>, extract: (data: Current) => L): DataModelMigrationChain<Current, Transfers & Record<Id, L>, Params>;
   /**
    * Set a recovery handler for unknown or legacy versions.
    *
@@ -207,7 +246,7 @@ declare class DataModelMigrationChain<Current, Transfers extends Record<string,
    *   .migrate<V3>("v3", (v2) => ({ ...v2, description: "" }))
    *   .init(() => ({ count: 0, label: "", description: "" }));
    */
-  recover(fn: DataRecoverFn<Current>): DataModelMigrationChainWithRecover<Current, Transfers>;
+  recover(fn: DataRecoverFn<Current>): DataModelMigrationChainWithRecover<Current, Transfers, Params>;
 }
 /**
  * Initial migration chain returned by `.from()`.
@@ -218,7 +257,7 @@ declare class DataModelMigrationChain<Current, Transfers extends Record<string,
  * @typeParam Transfers - Accumulated transfer types keyed by plugin ID
  * @internal
  */
-declare class DataModelInitialChain<Current, Transfers extends Record<string, unknown> = {}> extends DataModelMigrationChain<Current, Transfers> {
+declare class DataModelInitialChain<Current, Transfers extends Record<string, unknown> = {}, Params = never> extends DataModelMigrationChain<Current, Transfers, Params> {
   /**
    * Handle legacy V1 model state ({ args, uiState }) when upgrading a block from
    * BlockModel V1 to BlockModelV3.
@@ -253,7 +292,7 @@ declare class DataModelInitialChain<Current, Transfers extends Record<string, un
    *   }))
    *   .init(() => ({ inputFile: '', threshold: 0, selectedTab: 'main' }));
    */
-  upgradeLegacy<Args, UiState = unknown>(fn: (legacy: LegacyV1State<Args, UiState>) => Current): DataModelMigrationChainWithRecover<Current, Transfers>;
+  upgradeLegacy<Args, UiState = unknown>(fn: (legacy: LegacyV1State<Args, UiState>) => Current): DataModelMigrationChainWithRecover<Current, Transfers, Params>;
 }
 /**
  * Builder entry point for creating DataModel with type-safe migrations.
@@ -301,7 +340,20 @@ declare class DataModelInitialChain<Current, Transfers extends Record<string, un
  *   }))
  *   .init(() => ({ inputFile: '', selectedTab: 'main' }));
  */
-declare class DataModelBuilder {
+declare class DataModelBuilder<Params = never> {
+  #private;
+  /**
+   * @param opts.kind - The block kind this data model implements. Its reference
+   *   is captured and baked into the config so the manifest can advertise which
+   *   kind the block satisfies, and its `Params` type flows into `.init()`.
+   *   Optional during the transition window while existing V3 blocks are
+   *   migrated to kind-carrying builders; a kind-less builder simply carries no
+   *   reference and the reconciler can't project it yet. Object form mirrors
+   *   `BlockModelV3.create({ dataModel, kind })`.
+   */
+  constructor(opts?: {
+    kind?: BlockKind<Params>;
+  });
   /**
    * Start the migration chain with the given initial data type and version key.
    *
@@ -309,7 +361,7 @@ declare class DataModelBuilder {
    * @param initialVersion - Version key string (e.g. "v1")
    * @returns Migration chain builder
    */
-  from<T>(initialVersion: string): DataModelInitialChain<T>;
+  from<T>(initialVersion: string): DataModelInitialChain<T, {}, Params>;
 }
 /**
  * DataModel defines the block's data structure, initial values, and migrations.
@@ -330,9 +382,12 @@ declare class DataModelBuilder {
  *   .migrate<V3>("v3", (v2) => ({ ...v2, description: "" }))
  *   .init(() => ({ count: 0, label: "", description: "" }));
  */
-declare class DataModel<State, Transfers extends Record<string, unknown> = {}> {
+declare class DataModel<State, Params = never, Transfers extends Record<string, unknown> = {}> {
   /** @internal Phantom field to anchor the Transfers type parameter. */
   readonly __transfers?: Transfers;
+  /** @internal Phantom field to anchor the Params type parameter (drives the
+   *  compile-time kind cross-check in `BlockModelV3.create`). */
+  readonly __params?: Params;
   /** Latest version key — O(1) access for the common "already current" check. */
   private readonly latestVersion;
   /** Maps each known version key to the index of the first step to run from it. O(1) lookup. */
@@ -342,13 +397,32 @@ declare class DataModel<State, Transfers extends Record<string, unknown> = {}> {
   private readonly initialDataFn;
   private readonly recoverFn;
   private readonly recoverFromIndex;
+  /** Reference to the block kind this data model was built for, if any. */
+  private readonly _kindRef?;
+  /** The kind's runtime params check, if it declares one. */
+  private readonly _parseInitializationParams?;
   private constructor();
   /**
    * Internal method for creating DataModel from builder.
    * Uses Symbol key to prevent external access.
    * @internal
    */
-  static [FROM_BUILDER]<S, T extends Record<string, unknown> = {}>(state: BuilderState<S>): DataModel<S, T>;
+  static [FROM_BUILDER]<S, P = never, T extends Record<string, unknown> = {}>(state: BuilderState<S>): DataModel<S, P, T>;
+  /**
+   * Reference to the block kind this data model was built for, or `undefined`
+   * for a kind-less builder. Used by `BlockModelV3.create` to cross-check that
+   * the kind handed to the builder matches the kind handed to `create`.
+   * @internal
+   */
+  get kindRef(): BlockKindReference | undefined;
+  /**
+   * The kind's runtime params check, or `undefined` if the kind declares none (or
+   * there is no kind). Read by `BlockModelV3.done()` to register the check, and
+   * carried here rather than only on the model because `init` — the one place params
+   * are consumed — lives on this side.
+   * @internal
+   */
+  get templateParamsParser(): ((value: unknown) => unknown) | undefined;
   /**
    * The latest (current) version key in the migration chain.
    */
@@ -362,6 +436,21 @@ declare class DataModel<State, Transfers extends Record<string, unknown> = {}> {
    * Used when creating new blocks or resetting to defaults.
    */
   getDefaultData(): DataVersioned<State>;
+  /**
+   * Get initial data built from params, wrapped with current version.
+   *
+   * The counterpart of {@link getDefaultData} for a block created from a template
+   * entry: the factory receives the entry's params instead of nothing. A factory
+   * that ignores its argument produces the same result as `getDefaultData`, which
+   * is why the two are separate methods rather than one optional argument — the
+   * caller decides which contract it is asking for, and a block that cannot honour
+   * params must not silently look like one that can.
+   *
+   * References inside `params` are already resolved to the target project's
+   * concrete ids by the time they get here; the factory never sees a
+   * template-local one.
+   */
+  getDataFromParams(params: unknown): DataVersioned<State>;
   private recoverFrom;
   /**
    * Migrate versioned data from any version to the latest.
@@ -384,5 +473,5 @@ declare class DataModel<State, Transfers extends Record<string, unknown> = {}> {
   };
 }
 //#endregion
-export { DataCreateFn, DataMigrateFn, DataModel, DataModelBuilder, DataRecoverFn, DataVersionKey, DataVersioned, LegacyV1State, TransferRecord, TransferStep, TransferTarget };
+export { BlockKind, DataCreateFn, DataMigrateFn, DataModel, DataModelBuilder, DataRecoverFn, DataVersionKey, DataVersioned, LegacyV1State, TransferRecord, TransferStep, TransferTarget };
 //# sourceMappingURL=block_migrations.d.ts.map

package/dist/block_migrations.d.ts.map

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

package/dist/block_migrations.js

@@ -1,4 +1,5 @@
 import { DATA_MODEL_LEGACY_VERSION } from "./block_storage.js";
+import { formatKindRef } from "@milaboratories/pl-model-common";
 //#region src/block_migrations.ts
 /** Create a DataVersioned wrapper with correct shape */
 function makeVersionedData(version, data) {
@@ -47,10 +48,16 @@ var MigrationChainBase = class {
 	versionChain;
 	migrationSteps;
 	transferSteps;
+	/** Kind reference seeded by the builder, threaded through the chain into init(). */
+	kindRef;
+	/** The kind's runtime params check, carried for `init()` to hand to the DataModel. */
+	parseInitializationParams;
 	constructor(state) {
 		this.versionChain = state.versionChain;
 		this.migrationSteps = state.steps;
 		this.transferSteps = state.transferSteps ?? [];
+		this.kindRef = state.kindRef;
+		this.parseInitializationParams = state.parseInitializationParams;
 	}
 	/** Appends a migration step and returns the new versionChain and steps arrays. */
 	buildStep(nextVersion, fn) {
@@ -92,6 +99,8 @@ var MigrationChainBase = class {
 			steps: this.migrationSteps,
 			transferSteps: this.transferSteps,
 			initialDataFn: initialData,
+			kindRef: this.kindRef,
+			parseInitializationParams: this.parseInitializationParams,
 			...this.recoverState()
 		});
 	}
@@ -130,6 +139,8 @@ var DataModelMigrationChainWithRecover = class DataModelMigrationChainWithRecove
 			versionChain,
 			steps,
 			transferSteps: this.transferSteps,
+			kindRef: this.kindRef,
+			parseInitializationParams: this.parseInitializationParams,
 			recoverFn: this.recoverFn,
 			recoverFromIndex: this.recoverFromIndex
 		});
@@ -145,6 +156,8 @@ var DataModelMigrationChainWithRecover = class DataModelMigrationChainWithRecove
 			versionChain: this.versionChain,
 			steps: this.migrationSteps,
 			transferSteps,
+			kindRef: this.kindRef,
+			parseInitializationParams: this.parseInitializationParams,
 			recoverFn: this.recoverFn,
 			recoverFromIndex: this.recoverFromIndex
 		});
@@ -162,11 +175,13 @@ var DataModelMigrationChainWithRecover = class DataModelMigrationChainWithRecove
 */
 var DataModelMigrationChain = class DataModelMigrationChain extends MigrationChainBase {
 	/** @internal */
-	constructor({ versionChain, steps = [], transferSteps = [] }) {
+	constructor({ versionChain, steps = [], transferSteps = [], kindRef, parseInitializationParams }) {
 		super({
 			versionChain,
 			steps,
-			transferSteps
+			transferSteps,
+			kindRef,
+			parseInitializationParams
 		});
 	}
 	/**
@@ -185,7 +200,9 @@ var DataModelMigrationChain = class DataModelMigrationChain extends MigrationCha
 		return new DataModelMigrationChain({
 			versionChain,
 			steps,
-			transferSteps: this.transferSteps
+			transferSteps: this.transferSteps,
+			kindRef: this.kindRef,
+			parseInitializationParams: this.parseInitializationParams
 		});
 	}
 	/**
@@ -206,7 +223,9 @@ var DataModelMigrationChain = class DataModelMigrationChain extends MigrationCha
 		return new DataModelMigrationChain({
 			versionChain: this.versionChain,
 			steps: this.migrationSteps,
-			transferSteps
+			transferSteps,
+			kindRef: this.kindRef,
+			parseInitializationParams: this.parseInitializationParams
 		});
 	}
 	/**
@@ -237,6 +256,8 @@ var DataModelMigrationChain = class DataModelMigrationChain extends MigrationCha
 			versionChain: this.versionChain,
 			steps: this.migrationSteps,
 			transferSteps: this.transferSteps,
+			kindRef: this.kindRef,
+			parseInitializationParams: this.parseInitializationParams,
 			recoverFn: fn,
 			recoverFromIndex: this.migrationSteps.length
 		});
@@ -299,6 +320,8 @@ var DataModelInitialChain = class extends DataModelMigrationChain {
 		return new DataModelMigrationChainWithRecover({
 			versionChain: [DATA_MODEL_LEGACY_VERSION, ...this.versionChain],
 			steps: [step, ...this.migrationSteps],
+			kindRef: this.kindRef,
+			parseInitializationParams: this.parseInitializationParams,
 			transferSteps: this.transferSteps.map((t) => ({
 				...t,
 				beforeStepIndex: t.beforeStepIndex + 1
@@ -353,6 +376,21 @@ var DataModelInitialChain = class extends DataModelMigrationChain {
 *   .init(() => ({ inputFile: '', selectedTab: 'main' }));
 */
 var DataModelBuilder = class {
+	#kindRef;
+	#parseInitializationParams;
+	/**
+	* @param opts.kind - The block kind this data model implements. Its reference
+	*   is captured and baked into the config so the manifest can advertise which
+	*   kind the block satisfies, and its `Params` type flows into `.init()`.
+	*   Optional during the transition window while existing V3 blocks are
+	*   migrated to kind-carrying builders; a kind-less builder simply carries no
+	*   reference and the reconciler can't project it yet. Object form mirrors
+	*   `BlockModelV3.create({ dataModel, kind })`.
+	*/
+	constructor(opts) {
+		this.#kindRef = opts?.kind ? formatKindRef(opts.kind) : void 0;
+		this.#parseInitializationParams = opts?.kind?.parseInitializationParams;
+	}
 	/**
 	* Start the migration chain with the given initial data type and version key.
 	*
@@ -361,7 +399,11 @@ var DataModelBuilder = class {
 	* @returns Migration chain builder
 	*/
 	from(initialVersion) {
-		return new DataModelInitialChain({ versionChain: [initialVersion] });
+		return new DataModelInitialChain({
+			versionChain: [initialVersion],
+			kindRef: this.#kindRef,
+			parseInitializationParams: this.#parseInitializationParams
+		});
 	}
 };
 /**
@@ -393,13 +435,19 @@ var DataModel = class DataModel {
 	initialDataFn;
 	recoverFn;
 	recoverFromIndex;
-	constructor({ versionChain, steps, transferSteps = [], initialDataFn, recoverFn = defaultRecover, recoverFromIndex }) {
+	/** Reference to the block kind this data model was built for, if any. */
+	_kindRef;
+	/** The kind's runtime params check, if it declares one. */
+	_parseInitializationParams;
+	constructor({ versionChain, steps, transferSteps = [], initialDataFn, kindRef, parseInitializationParams, recoverFn = defaultRecover, recoverFromIndex }) {
 		if (versionChain.length === 0) throw new Error("DataModel requires at least one version key");
 		this.latestVersion = versionChain[versionChain.length - 1];
 		this.stepsByFromVersion = new Map(versionChain.map((v, i) => [v, i]));
 		this.steps = steps;
 		this.transferSteps = transferSteps;
 		this.initialDataFn = initialDataFn;
+		this._kindRef = kindRef;
+		this._parseInitializationParams = parseInitializationParams;
 		this.recoverFn = recoverFn;
 		this.recoverFromIndex = recoverFromIndex ?? steps.length;
 	}
@@ -412,6 +460,25 @@ var DataModel = class DataModel {
 		return new DataModel(state);
 	}
 	/**
+	* Reference to the block kind this data model was built for, or `undefined`
+	* for a kind-less builder. Used by `BlockModelV3.create` to cross-check that
+	* the kind handed to the builder matches the kind handed to `create`.
+	* @internal
+	*/
+	get kindRef() {
+		return this._kindRef;
+	}
+	/**
+	* The kind's runtime params check, or `undefined` if the kind declares none (or
+	* there is no kind). Read by `BlockModelV3.done()` to register the check, and
+	* carried here rather than only on the model because `init` — the one place params
+	* are consumed — lives on this side.
+	* @internal
+	*/
+	get templateParamsParser() {
+		return this._parseInitializationParams;
+	}
+	/**
 	* The latest (current) version key in the migration chain.
 	*/
 	get version() {
@@ -421,14 +488,31 @@ var DataModel = class DataModel {
 	* Get a fresh copy of the initial data.
 	*/
 	initialData() {
-		return this.initialDataFn();
+		return this.initialDataFn({});
 	}
 	/**
 	* Get initial data wrapped with current version.
 	* Used when creating new blocks or resetting to defaults.
 	*/
 	getDefaultData() {
-		return makeVersionedData(this.latestVersion, this.initialDataFn());
+		return makeVersionedData(this.latestVersion, this.initialDataFn({}));
+	}
+	/**
+	* Get initial data built from params, wrapped with current version.
+	*
+	* The counterpart of {@link getDefaultData} for a block created from a template
+	* entry: the factory receives the entry's params instead of nothing. A factory
+	* that ignores its argument produces the same result as `getDefaultData`, which
+	* is why the two are separate methods rather than one optional argument — the
+	* caller decides which contract it is asking for, and a block that cannot honour
+	* params must not silently look like one that can.
+	*
+	* References inside `params` are already resolved to the target project's
+	* concrete ids by the time they get here; the factory never sees a
+	* template-local one.
+	*/
+	getDataFromParams(params) {
+		return makeVersionedData(this.latestVersion, this.initialDataFn({ params }));
 	}
 	recoverFrom(data, version) {
 		let currentData = this.recoverFn(version, data);