@platforma-sdk/model 1.57.0 → 1.58.0

package/src/block_storage.ts

@@ -11,6 +11,7 @@
 
 import type { Branded } from "@milaboratories/pl-model-common";
 import type { DataMigrationResult, DataVersioned } from "./block_migrations";
+import type { PluginHandle, PluginFactoryLike, InferFactoryData } from "./plugin_handle";
 
 // =============================================================================
 // Core Types
@@ -50,7 +51,7 @@ export type PluginName = Branded<string, "PluginName">;
  * Plugin registry - maps pluginId (unique within a block) to pluginName (globally unique plugin type).
  * Using a Record highlights that pluginIds must be unique within a block.
  */
-export type PluginRegistry = Record<string, PluginName>;
+export type PluginRegistry = Record<PluginHandle, PluginName>;
 
 /**
  * Versioned data - used for both block data and plugin data
@@ -75,8 +76,8 @@ export type BlockStorage<TState = unknown> = {
   readonly [BLOCK_STORAGE_KEY]: BlockStorageSchemaVersion;
   /** Registry of plugins: pluginId -> pluginName */
   __pluginRegistry?: PluginRegistry;
-  /** Plugin-specific data, keyed by pluginId */
-  __plugins?: Record<string, VersionedData<unknown>>;
+  /** Plugin-specific data, keyed by plugin handle */
+  __plugins?: Record<PluginHandle, VersionedData<unknown>>;
 } & VersionedData<TState>;
 
 /**
@@ -176,7 +177,7 @@ export function deriveDataFromStorage<TData = unknown>(rawStorage: unknown): TDa
 /** Payload for storage mutation operations. SDK defines specific operations. */
 export type MutateStoragePayload<T = unknown> =
   | { operation: "update-block-data"; value: T }
-  | { operation: "update-plugin-data"; pluginId: string; value: unknown };
+  | { operation: "update-plugin-data"; pluginId: PluginHandle; value: unknown };
 
 /**
  * Updates the data in BlockStorage (immutable)
@@ -261,13 +262,13 @@ export interface MigrateBlockStorageConfig {
   migrateBlockData: (versioned: DataVersioned<unknown>) => DataMigrationResult<unknown>;
   /** Migrate each plugin's data. Return undefined to remove the plugin. */
   migratePluginData: (
-    pluginId: string,
+    handle: PluginHandle,
     versioned: DataVersioned<unknown>,
   ) => DataMigrationResult<unknown> | undefined;
   /** The new plugin registry after migration (pluginId -> pluginName) */
   newPluginRegistry: PluginRegistry;
   /** Factory to create initial data for new plugins */
-  createPluginData: (pluginId: string) => DataVersioned<unknown>;
+  createPluginData: (handle: PluginHandle) => DataVersioned<unknown>;
 }
 
 /**
@@ -334,33 +335,34 @@ export function migrateBlockStorage(
   // Step 2: Migrate plugins
   const oldPlugins = storage.__plugins ?? {};
   const oldRegistry = storage.__pluginRegistry ?? {};
-  const newPlugins: Record<string, VersionedData<unknown>> = {};
+  const newPlugins: Record<PluginHandle, VersionedData<unknown>> = {};
 
-  for (const [pluginId, pluginName] of Object.entries(newPluginRegistry)) {
-    const existingEntry = oldPlugins[pluginId];
-    const existingName = oldRegistry[pluginId];
+  for (const [key, pluginName] of Object.entries(newPluginRegistry)) {
+    const handle = key as PluginHandle;
+    const existingEntry = oldPlugins[handle];
+    const existingName = oldRegistry[handle];
 
     try {
       if (existingEntry && existingName === pluginName) {
         // Plugin exists with same type - migrate its data
-        const migrated = migratePluginData(pluginId, {
+        const migrated = migratePluginData(handle, {
           version: existingEntry.__dataVersion,
           data: existingEntry.__data,
         });
         if (migrated) {
-          newPlugins[pluginId] = { __dataVersion: migrated.version, __data: migrated.data };
+          newPlugins[handle] = { __dataVersion: migrated.version, __data: migrated.data };
         }
         // If undefined returned, plugin is intentionally removed
       } else {
         // New plugin or type changed - create with initial data
-        const initial = createPluginData(pluginId);
-        newPlugins[pluginId] = { __dataVersion: initial.version, __data: initial.data };
+        const initial = createPluginData(handle);
+        newPlugins[handle] = { __dataVersion: initial.version, __data: initial.data };
       }
     } catch (error) {
       return {
         success: false,
         error: error instanceof Error ? error.message : String(error),
-        failedAt: pluginId,
+        failedAt: handle,
       };
     }
   }
@@ -384,14 +386,20 @@ export function migrateBlockStorage(
  * Gets plugin-specific data from block storage.
  * Accepts raw storage (any format) and normalizes internally.
  *
+ * When called with a typed PluginHandle<F>, the return type is automatically
+ * inferred from the factory's phantom `__types.data` field.
+ *
  * @param rawStorage - Raw block storage (may be legacy format or BlockStorage)
- * @param pluginId - The plugin instance id
- * @returns The plugin data
- * @throws If pluginId is not found in storage
+ * @param handle - The plugin handle (branded plugin instance id)
+ * @returns The plugin data, typed via factory inference
+ * @throws If plugin is not found in storage
  */
-export function getPluginData<TData = unknown>(rawStorage: unknown, pluginId: string): TData {
+export function getPluginData<F extends PluginFactoryLike>(
+  rawStorage: unknown,
+  handle: PluginHandle<F>,
+): InferFactoryData<F> {
   const storage = normalizeBlockStorage(rawStorage);
-  const pluginEntry = storage.__plugins?.[pluginId];
-  if (!pluginEntry) throw new Error(`Plugin '${pluginId}' not found in block storage`);
-  return pluginEntry.__data as TData;
+  const pluginEntry = storage.__plugins?.[handle];
+  if (!pluginEntry) throw new Error(`Plugin '${handle}' not found in block storage`);
+  return pluginEntry.__data as InferFactoryData<F>;
 }

package/src/block_storage_callbacks.ts

@@ -24,6 +24,7 @@ import {
   normalizeBlockStorage,
   updateStorageData,
 } from "./block_storage";
+import type { PluginHandle } from "./plugin_handle";
 
 import { stringifyJson, type StringifiedJson } from "@milaboratories/pl-model-common";
 import type { DataMigrationResult, DataVersioned } from "./block_migrations";
@@ -37,17 +38,17 @@ export interface MigrationHooks {
   migrateBlockData: (versioned: DataVersioned<unknown>) => DataMigrationResult<unknown>;
   getPluginRegistry: () => PluginRegistry;
   migratePluginData: (
-    pluginId: string,
+    handle: PluginHandle,
     versioned: DataVersioned<unknown>,
   ) => DataMigrationResult<unknown> | undefined;
-  createPluginData: (pluginId: string) => DataVersioned<unknown>;
+  createPluginData: (handle: PluginHandle) => DataVersioned<unknown>;
 }
 
 /** Dependencies for initial storage creation */
 export interface InitialStorageHooks {
   getDefaultBlockData: () => DataVersioned<unknown>;
   getPluginRegistry: () => PluginRegistry;
-  createPluginData: (pluginId: string) => DataVersioned<unknown>;
+  createPluginData: (handle: PluginHandle) => DataVersioned<unknown>;
 }
 
 /**
@@ -233,10 +234,10 @@ export function createInitialStorage(hooks: InitialStorageHooks): StringifiedJso
   const blockDefault = hooks.getDefaultBlockData();
   const pluginRegistry = hooks.getPluginRegistry();
 
-  const plugins: Record<string, VersionedData<unknown>> = {};
-  for (const pluginId of Object.keys(pluginRegistry)) {
-    const initial = hooks.createPluginData(pluginId);
-    plugins[pluginId] = { __dataVersion: initial.version, __data: initial.data };
+  const plugins: Record<PluginHandle, VersionedData<unknown>> = {};
+  for (const handle of Object.keys(pluginRegistry) as PluginHandle[]) {
+    const initial = hooks.createPluginData(handle);
+    plugins[handle] = { __dataVersion: initial.version, __data: initial.data };
   }
 
   const storage: BlockStorage = {

package/src/components/PFrameForGraphs.ts

@@ -1,55 +1,9 @@
-import type {
-  AxisId,
-  AxisSpecNormalized,
-  CanonicalizedJson,
-  PColumn,
-  PColumnSpec,
-  PFrameHandle,
-  PObjectId,
-} from "@milaboratories/pl-model-common";
-import {
-  Annotation,
-  canonicalizeJson,
-  getAxisId,
-  getColumnIdAndSpec,
-  LinkerMap,
-  matchAxisId,
-  readAnnotation,
-  readAnnotationJson,
-  stringifyJson,
-} from "@milaboratories/pl-model-common";
+import type { PColumn, PColumnSpec, PFrameHandle } from "@milaboratories/pl-model-common";
+import { Annotation, readAnnotationJson } from "@milaboratories/pl-model-common";
 import type { PColumnDataUniversal, RenderCtxBase } from "../render";
 import { getAllRelatedColumns, getRelatedColumns } from "../pframe_utils/columns";
-
-/** Create id for column copy with added keys in axes domains */
-const colId = (id: PObjectId, domains: (Record<string, string> | undefined)[]) => {
-  let wid = id.toString();
-  domains?.forEach((domain) => {
-    if (domain) {
-      for (const [k, v] of Object.entries(domain)) {
-        wid += k;
-        wid += v;
-      }
-    }
-  });
-  return wid;
-};
-
-/** All combinations with 1 key from each list */
-function getKeysCombinations(idsLists: AxisId[][]) {
-  if (!idsLists.length) {
-    return [];
-  }
-  let result: AxisId[][] = [[]];
-  idsLists.forEach((list) => {
-    const nextResult: AxisId[][] = [];
-    list.forEach((key) => {
-      nextResult.push(...result.map((resultItem) => [...resultItem, key]));
-    });
-    result = nextResult;
-  });
-  return result;
-}
+export type { AxesVault } from "../pframe_utils/axes";
+export { enrichCompatible, getAvailableWithLinkersAxes } from "../pframe_utils/axes";
 
 export function isHiddenFromGraphColumn(column: PColumnSpec): boolean {
   return !!readAnnotationJson(column, Annotation.HideDataFromGraphs);
@@ -59,123 +13,6 @@ export function isHiddenFromUIColumn(column: PColumnSpec): boolean {
   return !!readAnnotationJson(column, Annotation.HideDataFromUi);
 }
 
-export type AxesVault = Map<CanonicalizedJson<AxisId>, AxisSpecNormalized>;
-
-export function getAvailableWithLinkersAxes(
-  linkerColumns: PColumn<PColumnDataUniversal>[],
-  blockAxes: AxesVault,
-): AxesVault {
-  const linkerMap = LinkerMap.fromColumns(linkerColumns.map(getColumnIdAndSpec));
-  const availableAxes = linkerMap.getReachableByLinkersAxesFromAxesNormalized(
-    [...blockAxes.values()],
-    (linkerKeyId, sourceAxisId) => matchAxisId(sourceAxisId, linkerKeyId),
-  );
-
-  return new Map(
-    availableAxes.map((axisSpec) => {
-      const id = getAxisId(axisSpec);
-      return [canonicalizeJson(id), axisSpec];
-    }),
-  );
-}
-/** Add columns with fully compatible axes created from partial compatible ones */
-export function enrichCompatible<T extends Omit<PColumn<PColumnDataUniversal>, "data">>(
-  blockAxes: AxesVault,
-  columns: T[],
-): T[] {
-  return columns.flatMap((column) => getAdditionalColumnsForColumn(blockAxes, column));
-}
-
-function getAdditionalColumnsForColumn<T extends Omit<PColumn<PColumnDataUniversal>, "data">>(
-  blockAxes: AxesVault,
-  column: T,
-): T[] {
-  const columnAxesIds = column.spec.axesSpec.map(getAxisId);
-
-  if (columnAxesIds.every((id) => blockAxes.has(canonicalizeJson(id)))) {
-    return [column]; // the column is compatible with its own domains without modifications
-  }
-
-  // options with different possible domains for every axis of secondary column
-  const secondaryIdsOptions = columnAxesIds.map((id) => {
-    const result = [];
-    for (const [_, mainId] of blockAxes) {
-      if (matchAxisId(mainId, id) && !matchAxisId(id, mainId)) {
-        result.push(mainId);
-      }
-    }
-    return result;
-  });
-  // all possible combinations of axes with added domains
-  const secondaryIdsVariants = getKeysCombinations(secondaryIdsOptions);
-
-  // sets of added to column domain fields
-  const allAddedDomainValues = new Set<string>();
-  const addedNotToAllVariantsDomainValues = new Set<string>();
-  const addedByVariantsDomainValues = secondaryIdsVariants.map((idsList) => {
-    const addedSet = new Set<string>();
-    idsList.map((axisId, idx) => {
-      const d1 = column.spec.axesSpec[idx].domain;
-      const d2 = axisId.domain;
-      Object.entries(d2 ?? {}).forEach(([key, value]) => {
-        if (d1?.[key] === undefined) {
-          const item = JSON.stringify([key, value]);
-          addedSet.add(item);
-          allAddedDomainValues.add(item);
-        }
-      });
-      return {
-        ...axisId,
-        annotations: column.spec.axesSpec[idx].annotations,
-      };
-    });
-    return addedSet;
-  });
-  [...allAddedDomainValues].forEach((addedPart) => {
-    if (addedByVariantsDomainValues.some((s) => !s.has(addedPart))) {
-      addedNotToAllVariantsDomainValues.add(addedPart);
-    }
-  });
-
-  const additionalColumns = secondaryIdsVariants.map((idsList, idx) => {
-    const id = colId(
-      column.id,
-      idsList.map((id) => id.domain),
-    );
-
-    const label = readAnnotation(column.spec, Annotation.Label) ?? "";
-    const labelDomainPart = [...addedByVariantsDomainValues[idx]]
-      .filter((str) => addedNotToAllVariantsDomainValues.has(str))
-      .sort()
-      .map((v) => JSON.parse(v)?.[1]) // use in labels only domain values, but sort them by key to save the same order in all column variants
-      .join(" / ");
-
-    const annotations: Annotation = {
-      ...column.spec.annotations,
-      [Annotation.Graph.IsVirtual]: stringifyJson(true),
-    };
-    if (label || labelDomainPart) {
-      annotations[Annotation.Label] =
-        label && labelDomainPart ? label + " / " + labelDomainPart : label + labelDomainPart;
-    }
-
-    return {
-      ...column,
-      id: id as PObjectId,
-      spec: {
-        ...column.spec,
-        axesSpec: idsList.map((axisId, idx) => ({
-          ...axisId,
-          annotations: column.spec.axesSpec[idx].annotations,
-        })),
-        annotations,
-      },
-    };
-  });
-
-  return [column, ...additionalColumns];
-}
-
 /**
  The aim of createPFrameForGraphs: to create pframe with block’s columns and all compatible columns from result pool
  (including linker columns and all label columns).

package/src/components/PlDataTable/index.ts

@@ -21,4 +21,9 @@ export {
   createPlDataTableStateV2,
 } from "./state-migration";
 
-export { isColumnHidden, isColumnOptional, createPlDataTableV2 } from "./table";
+export {
+  isColumnHidden,
+  isColumnOptional,
+  createPlDataTableV2,
+  createPlDataTableSheet,
+} from "./table";

package/src/components/PlDataTable/table.ts

@@ -39,6 +39,7 @@ import type { PlDataTableStateV2 } from "./state-migration";
 import type { PlDataTableSheet } from "./v5";
 import { getAllLabelColumns, getMatchingLabelColumns } from "./labels";
 import { collectFilterSpecColumns } from "../../filters/traverse";
+import { isEmpty } from "es-toolkit/compat";
 
 /** Convert a PTableColumnId to a SpecQueryExpression reference. */
 function columnIdToExpr(col: PTableColumnId): SpecQueryExpression {
@@ -198,10 +199,8 @@ export function createPlDataTableV2<A, U>(
     );
 
   // -- Sorting validation --
-  const sorting: PTableSorting[] = uniqueBy(
-    [...tableStateNormalized.pTableParams.sorting, ...(ops?.sorting ?? [])],
-    (s) => canonicalizeJson<PTableColumnId>(s.column),
-  );
+  const userSorting = tableStateNormalized.pTableParams.sorting;
+  const sorting = (isEmpty(userSorting) ? ops?.sorting : userSorting) ?? [];
   const firstInvalidSortingColumn = sorting.find(
     (s) => !isValidColumnId(canonicalizeJson<PTableColumnId>(s.column)),
   );

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from "./block_state_patch";
 export * from "./block_state_util";
+export * from "./plugin_handle";
 export * from "./block_storage";
 export * from "./block_storage_facade";
 export * from "./block_model_legacy";
@@ -14,7 +15,7 @@ export {
   makeDataVersioned,
 } from "./block_migrations";
 export type { LegacyV1State } from "./block_migrations";
-export { PluginModel } from "./plugin_model";
+export * from "./plugin_model";
 export * from "./bconfig";
 export * from "./components";
 export * from "./config";

package/src/pframe_utils/axes.ts

@@ -0,0 +1,175 @@
+/**
+ * Axes utilities for PFrame graph operations.
+ *
+ * Extracted from PFrameForGraphs to break circular dependency
+ * between PFrameForGraphs and columns modules.
+ *
+ * @module pframe_utils/axes
+ */
+
+import type {
+  AxisId,
+  AxisSpecNormalized,
+  CanonicalizedJson,
+  PColumn,
+  PObjectId,
+} from "@milaboratories/pl-model-common";
+import {
+  Annotation,
+  canonicalizeJson,
+  getAxisId,
+  getColumnIdAndSpec,
+  LinkerMap,
+  matchAxisId,
+  readAnnotation,
+  stringifyJson,
+} from "@milaboratories/pl-model-common";
+import type { PColumnDataUniversal } from "../render";
+
+export type AxesVault = Map<CanonicalizedJson<AxisId>, AxisSpecNormalized>;
+
+/** Create id for column copy with added keys in axes domains */
+const colId = (id: PObjectId, domains: (Record<string, string> | undefined)[]) => {
+  let wid = id.toString();
+  domains?.forEach((domain) => {
+    if (domain) {
+      for (const [k, v] of Object.entries(domain)) {
+        wid += k;
+        wid += v;
+      }
+    }
+  });
+  return wid;
+};
+
+/** All combinations with 1 key from each list */
+function getKeysCombinations(idsLists: AxisId[][]) {
+  if (!idsLists.length) {
+    return [];
+  }
+  let result: AxisId[][] = [[]];
+  idsLists.forEach((list) => {
+    const nextResult: AxisId[][] = [];
+    list.forEach((key) => {
+      nextResult.push(...result.map((resultItem) => [...resultItem, key]));
+    });
+    result = nextResult;
+  });
+  return result;
+}
+
+export function getAvailableWithLinkersAxes(
+  linkerColumns: PColumn<PColumnDataUniversal>[],
+  blockAxes: AxesVault,
+): AxesVault {
+  const linkerMap = LinkerMap.fromColumns(linkerColumns.map(getColumnIdAndSpec));
+  const availableAxes = linkerMap.getReachableByLinkersAxesFromAxesNormalized(
+    [...blockAxes.values()],
+    (linkerKeyId, sourceAxisId) => matchAxisId(sourceAxisId, linkerKeyId),
+  );
+
+  return new Map(
+    availableAxes.map((axisSpec) => {
+      const id = getAxisId(axisSpec);
+      return [canonicalizeJson(id), axisSpec];
+    }),
+  );
+}
+
+/** Add columns with fully compatible axes created from partial compatible ones */
+export function enrichCompatible<T extends Omit<PColumn<PColumnDataUniversal>, "data">>(
+  blockAxes: AxesVault,
+  columns: T[],
+): T[] {
+  return columns.flatMap((column) => getAdditionalColumnsForColumn(blockAxes, column));
+}
+
+function getAdditionalColumnsForColumn<T extends Omit<PColumn<PColumnDataUniversal>, "data">>(
+  blockAxes: AxesVault,
+  column: T,
+): T[] {
+  const columnAxesIds = column.spec.axesSpec.map(getAxisId);
+
+  if (columnAxesIds.every((id) => blockAxes.has(canonicalizeJson(id)))) {
+    return [column]; // the column is compatible with its own domains without modifications
+  }
+
+  // options with different possible domains for every axis of secondary column
+  const secondaryIdsOptions = columnAxesIds.map((id) => {
+    const result = [];
+    for (const [_, mainId] of blockAxes) {
+      if (matchAxisId(mainId, id) && !matchAxisId(id, mainId)) {
+        result.push(mainId);
+      }
+    }
+    return result;
+  });
+  // all possible combinations of axes with added domains
+  const secondaryIdsVariants = getKeysCombinations(secondaryIdsOptions);
+
+  // sets of added to column domain fields
+  const allAddedDomainValues = new Set<string>();
+  const addedNotToAllVariantsDomainValues = new Set<string>();
+  const addedByVariantsDomainValues = secondaryIdsVariants.map((idsList) => {
+    const addedSet = new Set<string>();
+    idsList.map((axisId, idx) => {
+      const d1 = column.spec.axesSpec[idx].domain;
+      const d2 = axisId.domain;
+      Object.entries(d2 ?? {}).forEach(([key, value]) => {
+        if (d1?.[key] === undefined) {
+          const item = JSON.stringify([key, value]);
+          addedSet.add(item);
+          allAddedDomainValues.add(item);
+        }
+      });
+      return {
+        ...axisId,
+        annotations: column.spec.axesSpec[idx].annotations,
+      };
+    });
+    return addedSet;
+  });
+  [...allAddedDomainValues].forEach((addedPart) => {
+    if (addedByVariantsDomainValues.some((s) => !s.has(addedPart))) {
+      addedNotToAllVariantsDomainValues.add(addedPart);
+    }
+  });
+
+  const additionalColumns = secondaryIdsVariants.map((idsList, idx) => {
+    const id = colId(
+      column.id,
+      idsList.map((id) => id.domain),
+    );
+
+    const label = readAnnotation(column.spec, Annotation.Label) ?? "";
+    const labelDomainPart = [...addedByVariantsDomainValues[idx]]
+      .filter((str) => addedNotToAllVariantsDomainValues.has(str))
+      .sort()
+      .map((v) => JSON.parse(v)?.[1]) // use in labels only domain values, but sort them by key to save the same order in all column variants
+      .join(" / ");
+
+    const annotations: Annotation = {
+      ...column.spec.annotations,
+      [Annotation.Graph.IsVirtual]: stringifyJson(true),
+    };
+    if (label || labelDomainPart) {
+      annotations[Annotation.Label] =
+        label && labelDomainPart ? label + " / " + labelDomainPart : label + labelDomainPart;
+    }
+
+    return {
+      ...column,
+      id: id as PObjectId,
+      spec: {
+        ...column.spec,
+        axesSpec: idsList.map((axisId, idx) => ({
+          ...axisId,
+          annotations: column.spec.axesSpec[idx].annotations,
+        })),
+        annotations,
+      },
+    };
+  });
+
+  return [column, ...additionalColumns];
+}

package/src/pframe_utils/columns.ts

@@ -7,8 +7,8 @@ import {
   matchAxisId,
   isLabelColumn,
 } from "@milaboratories/pl-model-common";
-import type { AxesVault } from "../components";
-import { enrichCompatible, getAvailableWithLinkersAxes } from "../components";
+import type { AxesVault } from "./axes";
+import { enrichCompatible, getAvailableWithLinkersAxes } from "./axes";
 import type { RenderCtxBase, PColumnDataUniversal } from "../render";
 import { PColumnCollection } from "../render";
 

package/src/platforma.ts

@@ -10,6 +10,7 @@ import type {
 import type { SdkInfo } from "./version";
 import type { BlockStatePatch } from "./block_state_patch";
 import type { PluginInstance } from "./block_model";
+import type { PluginHandle, PluginFactoryLike } from "./plugin_handle";
 
 /** Defines all methods to interact with the platform environment from within a block UI. @deprecated */
 export interface PlatformaV1<
@@ -85,6 +86,7 @@ export type BlockModelInfo = {
       withStatus: boolean;
     }
   >;
+  pluginIds: PluginHandle[];
 };
 
 export type PlatformaApiVersion = Platforma["apiVersion"];
@@ -124,14 +126,27 @@ export type InferBlockStatePatch<Pl extends Platforma> = BlockStatePatch<
 
 /** 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;
+  Pl extends PlatformaV3<unknown, unknown, BlockOutputsBase, `/${string}`, 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>
+  Pl extends PlatformaV3<unknown, unknown, BlockOutputsBase, `/${string}`, infer P>
     ? PluginId extends keyof P
       ? P[PluginId] extends PluginInstance<infer D, any, any>
         ? D
         : never
       : never
     : never;
+
+/**
+ * Map each plugin instance to a type-safe opaque handle branded with normalized phantom.
+ * Uses the same brand structure as InferPluginHandle — only data/params/outputs, no config —
+ * because PluginInstance doesn't carry Config (it's lost after factory.create()).
+ */
+export type InferPluginHandles<T extends Record<string, unknown>> = {
+  readonly [K in keyof T]: T[K] extends PluginInstance<infer Data, infer Params, infer Outputs>
+    ? PluginHandle<PluginFactoryLike<Data, Params, Outputs>>
+    : never;
+};