@platforma-sdk/model 1.54.10 → 1.55.0

package/src/filters/distill.ts

@@ -1,6 +1,11 @@
 import { DistributiveKeys, UnionToTuples } from "@milaboratories/helpers";
-import { type FilterSpec, type FilterSpecLeaf } from "@milaboratories/pl-model-common";
+import {
+  RootFilterSpec,
+  type FilterSpec,
+  type FilterSpecLeaf,
+} from "@milaboratories/pl-model-common";
 import { traverseFilterSpec } from "./traverse";
+import { InferFilterSpecLeaf } from "@milaboratories/pl-model-common";
 
 /** All possible field names that can appear in any FilterSpecLeaf variant. */
 type FilterSpecLeafKey = DistributiveKeys<FilterSpecLeaf<string>>;
@@ -41,23 +46,26 @@ function distillLeaf(node: Record<string, unknown>): FilterSpecLeaf<string> {
  * Strips non-FilterSpec metadata (whitelist approach) and removes
  * unfilled leaves (type is undefined or any required field is undefined).
  */
-export function distillFilterSpec<T extends FilterSpecLeaf<unknown>>(
-  filter: null | undefined | FilterSpec<T, unknown, unknown>,
-): null | FilterSpec<T> {
+export function distillFilterSpec<
+  FS extends FilterSpec<FilterSpecLeaf<unknown>, unknown, unknown>,
+  R extends FS extends RootFilterSpec<FilterSpecLeaf<unknown>, unknown, unknown>
+    ? RootFilterSpec<InferFilterSpecLeaf<FS>>
+    : FilterSpec<InferFilterSpecLeaf<FS>>,
+>(filter: null | undefined | FS): null | R {
   if (filter == null) return null;
-  return traverseFilterSpec(filter, {
+  return traverseFilterSpec<FS, null | R>(filter, {
     leaf: (leaf) => {
       if (!isFilledLeaf(leaf as Record<string, unknown>)) return null;
-      return distillLeaf(leaf as Record<string, unknown>) as FilterSpec<T>;
+      return distillLeaf(leaf as Record<string, unknown>) as R;
     },
     and: (results) => {
-      const filtered = results.filter((f): f is FilterSpec<T> => f !== null);
-      return filtered.length === 0 ? null : { type: "and", filters: filtered };
+      const filtered = results.filter((f): f is NonNullable<typeof f> => f !== null);
+      return filtered.length === 0 ? null : ({ type: "and", filters: filtered } as R);
     },
     or: (results) => {
-      const filtered = results.filter((f): f is FilterSpec<T> => f !== null);
-      return filtered.length === 0 ? null : { type: "or", filters: filtered };
+      const filtered = results.filter((f): f is NonNullable<typeof f> => f !== null);
+      return filtered.length === 0 ? null : ({ type: "or", filters: filtered } as R);
     },
-    not: (result) => (result === null ? null : { type: "not", filter: result }),
+    not: (result) => (result === null ? null : ({ type: "not", filter: result } as R)),
   });
 }

package/src/filters/traverse.ts

@@ -1,4 +1,24 @@
-import type { FilterSpecLeaf, FilterSpecNode } from "@milaboratories/pl-model-common";
+import type {
+  FilterSpec,
+  FilterSpecLeaf,
+  FilterSpecNode,
+  InferFilterSpecLeafColumn,
+} from "@milaboratories/pl-model-common";
+import type {
+  InferFilterSpecCommonLeaf,
+  InferFilterSpecLeaf,
+} from "@milaboratories/pl-model-common";
+
+export type FilterSpecVisitor<LeafArg, R> = {
+  /** Handle a leaf filter node. */
+  leaf: (leaf: LeafArg) => R;
+  /** Handle an AND node after children have been traversed. */
+  and: (results: R[]) => R;
+  /** Handle an OR node after children have been traversed. */
+  or: (results: R[]) => R;
+  /** Handle a NOT node after the inner filter has been traversed. */
+  not: (result: R) => R;
+};
 
 /**
  * Recursively traverses a FilterSpec tree bottom-up, applying visitor callbacks.
@@ -11,50 +31,50 @@ import type { FilterSpecLeaf, FilterSpecNode } from "@milaboratories/pl-model-co
  * 2. Apply the corresponding visitor callback with already-traversed children
  * 3. For leaf nodes, call `leaf` directly
  */
-export function traverseFilterSpec<Leaf extends FilterSpecLeaf<unknown>, CommonNode, CommonLeaf, R>(
-  filter: FilterSpecNode<Leaf, CommonNode, CommonLeaf>,
-  visitor: {
-    /** Handle a leaf filter node. */
-    leaf: (leaf: CommonLeaf & Leaf) => R;
-    /** Handle an AND node after children have been traversed. */
-    and: (results: R[]) => R;
-    /** Handle an OR node after children have been traversed. */
-    or: (results: R[]) => R;
-    /** Handle a NOT node after the inner filter has been traversed. */
-    not: (result: R) => R;
-  },
+export function traverseFilterSpec<
+  F extends FilterSpec<FilterSpecLeaf<unknown>, unknown, unknown>,
+  R,
+>(
+  filter: F,
+  visitor: FilterSpecVisitor<InferFilterSpecCommonLeaf<F> & InferFilterSpecLeaf<F>, R>,
+): R {
+  return traverseFilterSpecImpl(filter, visitor as FilterSpecVisitor<unknown, R>);
+}
+/** Internal implementation with simple generics for clean recursion. */
+function traverseFilterSpecImpl<R>(
+  filter: FilterSpecNode<FilterSpecLeaf<unknown>, unknown, unknown>,
+  visitor: FilterSpecVisitor<unknown, R>,
 ): R {
   switch (filter.type) {
     case "and":
       return visitor.and(
         filter.filters
           .filter((f) => f.type !== undefined)
-          .map((f) => traverseFilterSpec(f, visitor)),
+          .map((f) => traverseFilterSpecImpl(f, visitor)),
       );
     case "or":
       return visitor.or(
         filter.filters
           .filter((f) => f.type !== undefined)
-          .map((f) => traverseFilterSpec(f, visitor)),
+          .map((f) => traverseFilterSpecImpl(f, visitor)),
       );
     case "not":
-      return visitor.not(traverseFilterSpec(filter.filter, visitor));
+      return visitor.not(traverseFilterSpecImpl(filter.filter, visitor));
     default:
-      return visitor.leaf(filter as CommonLeaf & Leaf);
+      return visitor.leaf(filter);
   }
 }
 
 /** Collects all column references (`column` and `rhs` fields) from filter leaves. */
 export function collectFilterSpecColumns<
-  Leaf extends FilterSpecLeaf<unknown>,
-  CommonNode,
-  CommonLeaf,
->(filter: FilterSpecNode<Leaf, CommonNode, CommonLeaf>): string[] {
+  F extends FilterSpec<FilterSpecLeaf<unknown>, unknown, unknown>,
+  R extends InferFilterSpecLeafColumn<F> = InferFilterSpecLeafColumn<F>,
+>(filter: F): R[] {
   return traverseFilterSpec(filter, {
     leaf: (leaf) => {
-      const cols: string[] = [];
-      if ("column" in leaf && leaf.column !== undefined) cols.push(leaf.column as string);
-      if ("rhs" in leaf && leaf.rhs !== undefined) cols.push(leaf.rhs as string);
+      const cols: R[] = [];
+      if ("column" in leaf && leaf.column !== undefined) cols.push(leaf.column as R);
+      if ("rhs" in leaf && leaf.rhs !== undefined) cols.push(leaf.rhs as R);
       return cols;
     },
     and: (results) => results.flat(),

package/src/index.ts

@@ -1,17 +1,21 @@
 export * from "./block_state_patch";
 export * from "./block_state_util";
 export * from "./block_storage";
-export * from "./builder";
+export * from "./block_storage_facade";
+export * from "./block_model_legacy";
 export { BlockModelV3 } from "./block_model";
+export type { PluginInstance, ParamsInput } from "./block_model";
 export {
   DataModel,
   DataModelBuilder,
   DataUnrecoverableError,
   isDataUnrecoverableError,
-  defineDataVersions,
   defaultRecover,
   makeDataVersioned,
 } from "./block_migrations";
+export type { LegacyV1State } from "./block_migrations";
+export { PluginModel } from "./plugin_model";
+export type { PluginRenderCtx } from "./plugin_model";
 export * from "./bconfig";
 export * from "./components";
 export * from "./config";
@@ -19,7 +23,7 @@ export * from "./pframe";
 export * from "./platforma";
 export * from "./ref_util";
 export * from "./render";
-export * from "./sdk_info";
+export * from "./version";
 export * from "./raw_globals";
 export * from "./block_api_v1";
 export * from "./block_api_v2";

package/src/platforma.ts

@@ -7,8 +7,9 @@ import type {
   DriverKit,
   OutputWithStatus,
 } from "@milaboratories/pl-model-common";
-import type { SdkInfo } from "./sdk_info";
+import type { SdkInfo } from "./version";
 import type { BlockStatePatch } from "./block_state_patch";
+import type { PluginInstance } from "./block_model";
 
 /** Defines all methods to interact with the platform environment from within a block UI. @deprecated */
 export interface PlatformaV1<
@@ -43,18 +44,21 @@ export interface PlatformaV2<
 }
 
 export interface PlatformaV3<
+  Data = unknown,
   Args = unknown,
   Outputs extends Record<string, OutputWithStatus<unknown>> = Record<
     string,
     OutputWithStatus<unknown>
   >,
-  Data = unknown,
   Href extends `/${string}` = `/${string}`,
+  Plugins extends Record<string, unknown> = Record<string, unknown>,
 >
-  extends BlockApiV3<Args, Outputs, Data, Href>, DriverKit {
+  extends BlockApiV3<Data, Args, Outputs, Href>, DriverKit {
   /** Information about SDK version current platforma environment was compiled with. */
   readonly sdkInfo: SdkInfo;
   readonly apiVersion: 3;
+  /** @internal Type brand for plugin type inference. Not used at runtime. */
+  readonly __pluginsBrand?: Plugins;
 }
 
 export type Platforma<
@@ -63,12 +67,12 @@ export type Platforma<
     string,
     OutputWithStatus<unknown>
   >,
-  UiState = unknown,
+  UiStateOrData = unknown,
   Href extends `/${string}` = `/${string}`,
 > =
-  | PlatformaV1<Args, Outputs, UiState, Href>
-  | PlatformaV2<Args, Outputs, UiState, Href>
-  | PlatformaV3<Args, Outputs, UiState, Href>;
+  | PlatformaV1<Args, Outputs, UiStateOrData, Href>
+  | PlatformaV2<Args, Outputs, UiStateOrData, Href>
+  | PlatformaV3<UiStateOrData, Args, Outputs, Href>;
 
 export type PlatformaExtended<Pl extends Platforma = Platforma> = Pl & {
   blockModelInfo: BlockModelInfo;
@@ -106,6 +110,7 @@ export type InferHrefType<Pl extends Platforma> =
 export type PlatformaFactory = (config: { sdkVersion: string }) => Platforma;
 
 export type InferBlockState<Pl extends Platforma> = BlockStateV3<
+  InferDataType<Pl>,
   InferOutputsType<Pl>,
   InferHrefType<Pl>
 >;
@@ -116,3 +121,17 @@ export type InferBlockStatePatch<Pl extends Platforma> = BlockStatePatch<
   InferUiState<Pl>,
   InferHrefType<Pl>
 >;
+
+/** Extract plugin IDs as a string literal union from a Platforma type. */
+export type InferPluginNames<Pl> =
+  Pl extends PlatformaV3<any, any, any, any, infer P> ? string & keyof P : never;
+
+/** Extract the Data type for a specific plugin by its ID. */
+export type InferPluginData<Pl, PluginId extends string> =
+  Pl extends PlatformaV3<any, any, any, any, infer P>
+    ? PluginId extends keyof P
+      ? P[PluginId] extends PluginInstance<infer D, any, any>
+        ? D
+        : never
+      : never
+    : never;

package/src/plugin_model.test.ts

@@ -0,0 +1,168 @@
+import { describe, expect, it } from "vitest";
+import { PluginModel } from "./plugin_model";
+import type { PluginRenderCtx } from "./plugin_model";
+import { DataModelBuilder } from "./block_migrations";
+import { DATA_MODEL_DEFAULT_VERSION, type PluginName } from "./block_storage";
+import type { ResultPool } from "./render";
+
+// =============================================================================
+// Test Fixtures
+// =============================================================================
+
+type Data = { count: number; label: string };
+
+const dataModelChain = new DataModelBuilder().from<Data>(DATA_MODEL_DEFAULT_VERSION);
+
+// Mock ResultPool for testing
+const mockResultPool = {} as ResultPool;
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe("PluginModel", () => {
+  it("creates PluginModel with required fields", () => {
+    const factory = PluginModel.define<Data>({
+      name: "testPlugin" as PluginName,
+      data: () => dataModelChain.init(() => ({ count: 0, label: "" })),
+    }).build();
+
+    const plugin = factory.create();
+    expect(plugin.name).toBe("testPlugin");
+    expect(plugin.outputs).toEqual({});
+  });
+
+  it("creates PluginModel when calling create() with config", () => {
+    type Config = { initialCount: number };
+
+    const factory = PluginModel.define<Data, undefined, Config>({
+      name: "factoryPlugin" as PluginName,
+      data: (cfg) => dataModelChain.init(() => ({ count: cfg.initialCount, label: "initialized" })),
+    }).build();
+
+    const plugin = factory.create({ initialCount: 100 });
+    expect(plugin.name).toBe("factoryPlugin");
+    expect(plugin.dataModel.initialData()).toEqual({ count: 100, label: "initialized" });
+  });
+
+  it("adds single output", () => {
+    const factory = PluginModel.define<Data, { multiplier: number }>({
+      name: "singleOutput" as PluginName,
+      data: () => dataModelChain.init(() => ({ count: 0, label: "" })),
+    })
+      .output("doubled", (ctx) => ctx.data.count * ctx.params.multiplier)
+      .build();
+
+    const plugin = factory.create();
+    expect(Object.keys(plugin.outputs)).toEqual(["doubled"]);
+  });
+
+  it("accumulates multiple outputs", () => {
+    const factory = PluginModel.define<Data, { prefix: string }>({
+      name: "multiOutput" as PluginName,
+      data: () => dataModelChain.init(() => ({ count: 0, label: "" })),
+    })
+      .output("formattedCount", (ctx) => `${ctx.params.prefix}${ctx.data.count}`)
+      .output("upperLabel", (ctx) => ctx.data.label.toUpperCase())
+      .output("isReady", (ctx) => ctx.data.count > 0)
+      .build();
+
+    const plugin = factory.create();
+    expect(Object.keys(plugin.outputs).sort()).toEqual(["formattedCount", "isReady", "upperLabel"]);
+  });
+
+  it("executes output functions with correct context", () => {
+    const factory = PluginModel.define<Data, { factor: number }>({
+      name: "contextTest" as PluginName,
+      data: () => dataModelChain.init(() => ({ count: 0, label: "" })),
+    })
+      .output("computed", (ctx) => ctx.data.count * ctx.params.factor)
+      .build();
+
+    const plugin = factory.create();
+
+    const ctx: PluginRenderCtx<Data, { factor: number }> = {
+      data: { count: 5, label: "" },
+      params: { factor: 3 },
+      resultPool: mockResultPool,
+    };
+
+    const result = plugin.outputs.computed(ctx);
+    expect(result).toBe(15);
+  });
+
+  it("allows outputs to access resultPool", () => {
+    const factory = PluginModel.define<Data>({
+      name: "resultPoolTest" as PluginName,
+      data: () => dataModelChain.init(() => ({ count: 0, label: "" })),
+    })
+      .output("hasResultPool", (ctx) => ctx.resultPool !== undefined)
+      .build();
+
+    const plugin = factory.create();
+
+    const ctx: PluginRenderCtx<Data> = {
+      data: { count: 0, label: "" },
+      params: undefined,
+      resultPool: mockResultPool,
+    };
+
+    expect(plugin.outputs.hasResultPool(ctx)).toBe(true);
+  });
+
+  it("returns valid PluginModel from factory.create()", () => {
+    const factory = PluginModel.define<Data, { items: string[] }, { option: boolean }>({
+      name: "completePlugin" as PluginName,
+      data: () => dataModelChain.init(() => ({ count: -1, label: "" })),
+    })
+      .output("currentItem", (ctx) => ctx.params.items[ctx.data.count])
+      .output("hasSelection", (ctx) => ctx.data.count >= 0)
+      .build();
+
+    const plugin = factory.create({ option: true });
+    expect(plugin.name).toBe("completePlugin");
+    expect(Object.keys(plugin.outputs).sort()).toEqual(["currentItem", "hasSelection"]);
+  });
+
+  it("allows creating plugin without outputs", () => {
+    const factory = PluginModel.define<Data>({
+      name: "noOutputs" as PluginName,
+      data: () => dataModelChain.init(() => ({ count: 0, label: "" })),
+    }).build();
+
+    const plugin = factory.create();
+    expect(plugin.outputs).toEqual({});
+  });
+
+  it("passes config to data model factory for initialization", () => {
+    type Config = { defaultCount: number; defaultLabel: string };
+
+    const factory = PluginModel.define<Data, undefined, Config>({
+      name: "configInitPlugin" as PluginName,
+      data: (cfg) =>
+        dataModelChain.init(() => ({ count: cfg.defaultCount, label: cfg.defaultLabel })),
+    }).build();
+
+    const plugin = factory.create({ defaultCount: 10, defaultLabel: "default" });
+    expect(plugin.dataModel.initialData()).toEqual({ count: 10, label: "default" });
+  });
+
+  it("does not modify original builder when chaining", () => {
+    const basePlugin = PluginModel.define<Data>({
+      name: "immutableTest" as PluginName,
+      data: () => dataModelChain.init(() => ({ count: 0, label: "" })),
+    });
+
+    const pluginWithOutput1 = basePlugin.output("first", (ctx) => ctx.data.count);
+    const pluginWithOutput2 = basePlugin.output("second", (ctx) => ctx.data.count * 2);
+
+    const factory1 = pluginWithOutput1.build();
+    const factory2 = pluginWithOutput2.build();
+
+    const plugin1 = factory1.create(undefined);
+    const plugin2 = factory2.create(undefined);
+
+    expect(Object.keys(plugin1.outputs)).toEqual(["first"]);
+    expect(Object.keys(plugin2.outputs)).toEqual(["second"]);
+  });
+});

package/src/plugin_model.ts

@@ -0,0 +1,242 @@
+/**
+ * PluginModel - Builder for creating plugin types with data model and outputs.
+ *
+ * Plugins are UI components with their own model logic and persistent state.
+ * Block developers register plugin instances via BlockModelV3.plugin() method.
+ *
+ * @module plugin_model
+ */
+
+import type { DataModel } from "./block_migrations";
+import type { PluginName } from "./block_storage";
+import type { ResultPool } from "./render";
+
+/** Symbol for internal builder creation method */
+const FROM_BUILDER = Symbol("fromBuilder");
+
+// =============================================================================
+// Plugin Render Context
+// =============================================================================
+
+/**
+ * Context passed to plugin output functions.
+ * Provides access to plugin's persistent data, params derived from block context,
+ * and the result pool for accessing workflow outputs.
+ */
+export interface PluginRenderCtx<Data, Params = undefined> {
+  /** Plugin's persistent data */
+  readonly data: Data;
+  /** Params derived from block's RenderCtx */
+  readonly params: Params;
+  /** Result pool for accessing workflow outputs */
+  readonly resultPool: ResultPool;
+}
+
+// =============================================================================
+// Plugin Type
+// =============================================================================
+
+/**
+ * Configured plugin instance returned by PluginModelFactory.create().
+ * Contains the plugin's name, data model, and output definitions.
+ */
+export class PluginModel<Data = unknown, Params = undefined, Outputs = {}> {
+  /** Globally unique plugin name */
+  readonly name: PluginName;
+  /** Data model instance for this plugin */
+  readonly dataModel: DataModel<Data>;
+  /** Output definitions - functions that compute outputs from plugin context */
+  readonly outputs: { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] };
+
+  private constructor(input: {
+    name: PluginName;
+    dataModel: DataModel<Data>;
+    outputs: { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] };
+  }) {
+    this.name = input.name;
+    this.dataModel = input.dataModel;
+    this.outputs = input.outputs;
+  }
+
+  /**
+   * Internal method for creating PluginModel from factory.
+   * Uses Symbol key to prevent external access.
+   * @internal
+   */
+  static [FROM_BUILDER]<D, P, O>(input: {
+    name: PluginName;
+    dataModel: DataModel<D>;
+    outputs: { [K in keyof O]: (ctx: PluginRenderCtx<D, P>) => O[K] };
+  }): PluginModel<D, P, O> {
+    return new this<D, P, O>(input);
+  }
+
+  /**
+   * Creates a new PluginModelBuilder for building plugin definitions.
+   *
+   * @param options.name - Globally unique plugin name
+   * @param options.data - Factory function that creates the data model from config
+   * @returns PluginModelBuilder for chaining output definitions
+   *
+   * @example
+   * const dataModelChain = new DataModelBuilder().from<MyData>(DATA_MODEL_DEFAULT_VERSION);
+   *
+   * const myPlugin = PluginModel.define<MyData, MyParams, MyConfig>({
+   *   name: 'myPlugin' as PluginName,
+   *   data: (cfg) => dataModelChain.init(() => ({ value: cfg.defaultValue })),
+   * })
+   *   .output('computed', (ctx) => ctx.data.value * ctx.params.multiplier)
+   *   .build();
+   */
+  static define<Data, Params = undefined, Config = undefined>(options: {
+    name: PluginName;
+    data: (config?: Config) => DataModel<Data>;
+  }): PluginModelBuilder<Data, Params, Config> {
+    return PluginModelBuilder[FROM_BUILDER]<Data, Params, Config>(options);
+  }
+}
+
+/**
+ * Plugin factory returned by PluginModelBuilder.build().
+ * Call create() with config to get a configured PluginModel instance.
+ */
+class PluginModelFactory<Data, Params, Config, Outputs> {
+  private readonly name: PluginName;
+  private readonly data: (config?: Config) => DataModel<Data>;
+  private readonly outputs: {
+    [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K];
+  };
+
+  constructor(input: {
+    name: PluginName;
+    data: (config?: Config) => DataModel<Data>;
+    outputs: { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] };
+  }) {
+    this.name = input.name;
+    this.data = input.data;
+    this.outputs = input.outputs;
+  }
+
+  /** Create a configured PluginModel instance */
+  create(config?: Config): PluginModel<Data, Params, Outputs> {
+    return PluginModel[FROM_BUILDER]<Data, Params, Outputs>({
+      name: this.name,
+      dataModel: this.data(config),
+      outputs: this.outputs,
+    });
+  }
+}
+
+// =============================================================================
+// Plugin Model Builder
+// =============================================================================
+
+/**
+ * Builder for creating PluginType with type-safe output definitions.
+ *
+ * Use `PluginModel.define()` to create a builder instance.
+ *
+ * @typeParam Data - Plugin's persistent data type
+ * @typeParam Params - Params derived from block's RenderCtx (optional)
+ * @typeParam Config - Static configuration passed to plugin factory (optional)
+ * @typeParam Outputs - Accumulated output types
+ *
+ * @example
+ * const dataModelChain = new DataModelBuilder().from<TableData>(DATA_MODEL_DEFAULT_VERSION);
+ *
+ * const dataTable = PluginModel.define<TableData, TableParams, TableConfig>({
+ *     name: 'dataTable' as PluginName,
+ *     data: (cfg) => {
+ *       return dataModelChain.init(() => ({ state: createInitialState(cfg.ops) }));
+ *     },
+ *   })
+ *   .output('model', (ctx) => createTableModel(ctx))
+ *   .build();
+ */
+class PluginModelBuilder<
+  Data,
+  Params = undefined,
+  Config = undefined,
+  Outputs extends Record<string, unknown> = {},
+> {
+  private readonly name: PluginName;
+  private readonly data: (config?: Config) => DataModel<Data>;
+  private readonly outputs: {
+    [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K];
+  };
+
+  private constructor(input: {
+    name: PluginName;
+    data: (config?: Config) => DataModel<Data>;
+    outputs?: { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] };
+  }) {
+    this.name = input.name;
+    this.data = input.data;
+    this.outputs =
+      input.outputs ??
+      ({} as { [K in keyof Outputs]: (ctx: PluginRenderCtx<Data, Params>) => Outputs[K] });
+  }
+
+  /**
+   * Internal method for creating PluginModelBuilder.
+   * Uses Symbol key to prevent external access.
+   * @internal
+   */
+  static [FROM_BUILDER]<D, P, C, O extends Record<string, unknown> = {}>(input: {
+    name: PluginName;
+    data: (config?: C) => DataModel<D>;
+    outputs?: { [K in keyof O]: (ctx: PluginRenderCtx<D, P>) => O[K] };
+  }): PluginModelBuilder<D, P, C, O> {
+    return new this<D, P, C, O>(input);
+  }
+
+  /**
+   * Adds an output to the plugin.
+   *
+   * @param key - Output name
+   * @param fn - Function that computes the output value from plugin context
+   * @returns PluginModel with the new output added
+   *
+   * @example
+   * .output('model', (ctx) => createModel(ctx.params.columns, ctx.data.state))
+   * .output('isReady', (ctx) => ctx.params.columns !== undefined)
+   */
+  output<const Key extends string, T>(
+    key: Key,
+    fn: (ctx: PluginRenderCtx<Data, Params>) => T,
+  ): PluginModelBuilder<Data, Params, Config, Outputs & { [K in Key]: T }> {
+    return new PluginModelBuilder<Data, Params, Config, Outputs & { [K in Key]: T }>({
+      name: this.name,
+      data: this.data,
+      outputs: {
+        ...this.outputs,
+        [key]: fn,
+      } as {
+        [K in keyof (Outputs & { [P in Key]: T })]: (
+          ctx: PluginRenderCtx<Data, Params>,
+        ) => (Outputs & { [P in Key]: T })[K];
+      },
+    });
+  }
+
+  /**
+   * Finalizes the plugin definition and returns a ConfigurablePluginModel.
+   *
+   * @returns Callable plugin factory that accepts config and returns PluginModel
+   *
+   * @example
+   * const myPlugin = new PluginModelBuilder('myPlugin', () => dataModel)
+   *   .output('value', (ctx) => ctx.data.value)
+   *   .build();
+   *
+   * // Later, call create() with config to get a configured instance:
+   * const configured = myPlugin.create({ defaultValue: 'test' });
+   */
+  build(): PluginModelFactory<Data, Params, Config, Outputs> {
+    return new PluginModelFactory<Data, Params, Config, Outputs>({
+      name: this.name,
+      data: this.data,
+      outputs: this.outputs,
+    });
+  }
+}