Per-instance trace label for sequence-properties

.changeset/sequence-properties-trace-label-and-meta.md

@@ -0,0 +1,14 @@
+---
+'@platforma-open/milaboratories.sequence-properties.workflow': minor
+'@platforma-open/milaboratories.sequence-properties.model': minor
+'@platforma-open/milaboratories.sequence-properties.ui': minor
+'@platforma-open/milaboratories.sequence-properties': minor
+'@platforma-open/milaboratories.sequence-properties.test': patch
+---
+
+Per-instance trace label, broader plot pickers, locked-in test coverage.
+
+- **Trace label is per-instance.** The workflow's `pl7.app/trace.label` resolves to `customBlockLabel || defaultBlockLabel || "Sequence Properties"` (centralised in `model/src/label.ts`). Two sequence-properties blocks on the same dataset show distinguishable entries in Lead Selection and other downstream pickers once the user customises the `PlBlockPage` subtitle. Same pattern as clonotype-clustering and titeseq-analysis PR #13.
+- **Scatter and Histogram metadata pickers accept own-block columns.** Filter, Grouping/Color, Highlight, Size, Tab, Tooltip, Label, and Additional-curves now treat every column in the property pframe as a candidate — own scalars and upstream metadata alike. Users can color the Property Relationships scatter by Aromaticity while plotting Charge vs Hydrophobicity. X/Y axis defaults unchanged.
+- **Migration backfill.** A new `Ver_2026_05_18` step fills the new label fields onto projects tagged at the deployed `Ver_2026_05_05`, preserving any interim-deployed value via `?? ""`. Without the split, already-V2 projects would skip the migration and the workflow would receive `args.customBlockLabel === undefined`.
+- **Test coverage.** Model vitest locks the resolution chain (6 cases) and the migration backfill (4 cases). A subprocess-based Python byte-compare test guards Python output determinism. `build.yaml` enables `test: true` so block-level tests exercise on every PR.

.github/workflows/build.yaml

@@ -32,7 +32,7 @@ jobs:
       build-script-name: 'build'
       pnpm-recursive-build: false
 
-      test: false
+      test: true
       test-script-name: 'test'
       pnpm-recursive-tests: false
       team-id: 'ciplopen'

block/package.json

@@ -47,5 +47,5 @@
   "devDependencies": {
     "@platforma-sdk/block-tools": "catalog:"
   },
-  "packageManager": "pnpm@9.12.0"
+  "packageManager": "pnpm@9.15.0"
 }

model/package.json

@@ -17,7 +17,9 @@
     "fmt": "ts-builder format",
     "watch": "ts-builder build --target block-model --watch",
     "build": "ts-builder build --target block-model && block-tools build-model",
-    "check": "ts-builder check --target block-model"
+    "check": "ts-builder check --target block-model",
+    "test": "vitest --run --passWithNoTests",
+    "test:watch": "vitest"
   },
   "dependencies": {
     "@milaboratories/graph-maker": "catalog:",
@@ -27,7 +29,8 @@
   "devDependencies": {
     "@milaboratories/ts-builder": "catalog:",
     "@milaboratories/ts-configs": "catalog:",
-    "@platforma-sdk/block-tools": "catalog:"
+    "@platforma-sdk/block-tools": "catalog:",
+    "vitest": "catalog:"
   },
   "peerDependencies": {
     "@types/node": "*",

model/src/dataModel.test.ts

@@ -0,0 +1,63 @@
+// Tests drive the migration callbacks directly because @platforma-sdk/model's
+// DataModelBuilder exposes no introspection / external-apply API. The builder
+// wiring in dataModel.ts (the two `.migrate(...)` calls) is only exercised
+// when a real block loads — these unit tests would still pass if someone
+// deleted a `.migrate(...)` line while keeping the named callback exported.
+
+import { describe, expect, it } from "vitest";
+import type { BlockData, BlockDataV1, BlockDataV2 } from "./types";
+import { migrateV1toV2, migrateV2toV2_1 } from "./dataModel";
+
+const tableState = {
+  pTableParams: {
+    defaultFilters: null,
+    filters: null,
+    hiddenColIds: null,
+    sorting: [],
+    sourceId: null,
+  },
+  stateCache: [],
+  version: 6,
+} as BlockDataV2["tableState"];
+
+const v2Graph: Pick<BlockDataV2, "graphStateScatter" | "graphStateHistogram"> = {
+  graphStateScatter: { currentTab: null, template: "dots", title: "Property Relationships" },
+  graphStateHistogram: {
+    currentTab: null,
+    layersSettings: { bins: { fillColor: "#99e099" } },
+    template: "bins",
+    title: "Property Distribution",
+  },
+};
+
+describe("blockDataModel Ver_2026_05_18 backfill", () => {
+  it("backfills both label fields to '' on a bare V2 payload", () => {
+    const v2: BlockDataV2 = { tableState, ...v2Graph };
+    const upgraded: BlockData = migrateV2toV2_1(v2);
+    expect(upgraded.customBlockLabel).toBe("");
+    expect(upgraded.defaultBlockLabel).toBe("");
+  });
+
+  it("preserves an interim-deployed customBlockLabel", () => {
+    const v2: BlockDataV2 = { tableState, ...v2Graph, customBlockLabel: "X" };
+    const upgraded: BlockData = migrateV2toV2_1(v2);
+    expect(upgraded.customBlockLabel).toBe("X");
+    expect(upgraded.defaultBlockLabel).toBe("");
+  });
+
+  it("preserves an interim-deployed defaultBlockLabel", () => {
+    const v2: BlockDataV2 = { tableState, ...v2Graph, defaultBlockLabel: "Y" };
+    const upgraded: BlockData = migrateV2toV2_1(v2);
+    expect(upgraded.defaultBlockLabel).toBe("Y");
+    expect(upgraded.customBlockLabel).toBe("");
+  });
+
+  it("runs the full V1 → V2 → V2.1 chain on legacy data", () => {
+    const v1: BlockDataV1 = { tableState, defaultBlockLabel: "Old" };
+    const upgraded: BlockData = migrateV2toV2_1(migrateV1toV2(v1));
+    expect(upgraded.defaultBlockLabel).toBe("Old");
+    expect(upgraded.customBlockLabel).toBe("");
+    expect(upgraded.graphStateScatter).toBeDefined();
+    expect(upgraded.graphStateHistogram).toBeDefined();
+  });
+});

model/src/dataModel.ts

@@ -1,6 +1,6 @@
 import type { GraphMakerState } from "@milaboratories/graph-maker";
 import { createPlDataTableStateV2, DataModelBuilder } from "@platforma-sdk/model";
-import type { BlockData, BlockDataV1 } from "./types";
+import type { BlockData, BlockDataV1, BlockDataV2 } from "./types";
 
 const DEFAULT_SCATTER_STATE: GraphMakerState = {
   title: "Property Relationships",
@@ -17,15 +17,33 @@ const DEFAULT_HISTOGRAM_STATE: GraphMakerState = {
   },
 };
 
+export const migrateV1toV2 = (v1: BlockDataV1): BlockDataV2 => ({
+  ...v1,
+  graphStateScatter: { ...DEFAULT_SCATTER_STATE },
+  graphStateHistogram: { ...DEFAULT_HISTOGRAM_STATE },
+});
+
+export const migrateV2toV2_1 = (v2: BlockDataV2): BlockData => ({
+  ...v2,
+  defaultBlockLabel: v2.defaultBlockLabel ?? "",
+  customBlockLabel: v2.customBlockLabel ?? "",
+});
+
 export const blockDataModel = new DataModelBuilder()
   .from<BlockDataV1>("Ver_2026_04_28")
-  .migrate<BlockData>("Ver_2026_05_05", (v1) => ({
-    ...v1,
-    graphStateScatter: { ...DEFAULT_SCATTER_STATE },
-    graphStateHistogram: { ...DEFAULT_HISTOGRAM_STATE },
-  }))
+  // Already-deployed step. Future field additions must go into a new step
+  // below — editing this body has no effect on projects already tagged
+  // Ver_2026_05_05 (DataModelBuilder skips matching-version migrations).
+  .migrate<BlockDataV2>("Ver_2026_05_05", migrateV1toV2)
+  // Backfills label fields onto V2-tagged projects. `?? ""` preserves any
+  // interim-deployed value; missing fields default to "". The args
+  // projection (resolveTraceLabel in label.ts) requires both fields to be
+  // strings, never undefined.
+  .migrate<BlockData>("Ver_2026_05_18", migrateV2toV2_1)
   .init(() => ({
     tableState: createPlDataTableStateV2(),
+    defaultBlockLabel: "",
+    customBlockLabel: "",
     graphStateScatter: { ...DEFAULT_SCATTER_STATE },
     graphStateHistogram: { ...DEFAULT_HISTOGRAM_STATE },
   }));

model/src/index.ts

@@ -6,6 +6,7 @@ import {
   createPlDataTableV2,
 } from "@platforma-sdk/model";
 import { blockDataModel } from "./dataModel";
+import { resolveSubtitle, resolveTraceLabel } from "./label";
 import type { BlockArgs, WorkflowInfo } from "./types";
 
 export type * from "@milaboratories/helpers";
@@ -41,6 +42,7 @@ export const platforma = BlockModelV3.create(blockDataModel)
     }
     return {
       inputAnchor: data.inputAnchor,
+      traceLabel: resolveTraceLabel(data),
     };
   })
   .output("inputOptions", (ctx) => ctx.resultPool.getOptions(inputAnchorSpecs))
@@ -107,7 +109,7 @@ export const platforma = BlockModelV3.create(blockDataModel)
     return pCols.map((c) => ({ columnId: c.id, spec: c.spec }) satisfies PColumnIdAndSpec);
   })
   .title(() => "Sequence Properties")
-  .subtitle((ctx) => ctx.data.defaultBlockLabel ?? "")
+  .subtitle((ctx) => resolveSubtitle(ctx.data))
   .sections(() => [
     { type: "link", href: "/", label: "Main" },
     { type: "link", href: "/scatter", label: "Property Relationships" },

model/src/label.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+import type { BlockData } from "./types";
+import { resolveSubtitle, resolveTraceLabel } from "./label";
+
+const base: Omit<BlockData, "customBlockLabel" | "defaultBlockLabel"> = {
+  tableState: {
+    pTableParams: {
+      defaultFilters: null,
+      filters: null,
+      hiddenColIds: null,
+      sorting: [],
+      sourceId: null,
+    },
+    stateCache: [],
+    version: 6,
+  } as BlockData["tableState"],
+  graphStateScatter: {
+    currentTab: null,
+    template: "dots",
+    title: "Property Relationships",
+  } as BlockData["graphStateScatter"],
+  graphStateHistogram: {
+    currentTab: null,
+    layersSettings: { bins: { fillColor: "#99e099" } },
+    template: "bins",
+    title: "Property Distribution",
+  } as BlockData["graphStateHistogram"],
+};
+
+const make = (custom: string, def: string): BlockData => ({
+  ...(base as BlockData),
+  customBlockLabel: custom,
+  defaultBlockLabel: def,
+});
+
+describe("resolveSubtitle", () => {
+  it("uses customBlockLabel when set", () => {
+    expect(resolveSubtitle(make("My label", "Dataset"))).toBe("My label");
+  });
+
+  it("falls back to defaultBlockLabel when customBlockLabel is empty", () => {
+    expect(resolveSubtitle(make("", "Dataset"))).toBe("Dataset");
+  });
+
+  it("returns empty string when both label fields are empty", () => {
+    expect(resolveSubtitle(make("", ""))).toBe("");
+  });
+});
+
+describe("resolveTraceLabel", () => {
+  it("uses customBlockLabel when set", () => {
+    expect(resolveTraceLabel(make("My label", "Dataset"))).toBe("My label");
+  });
+
+  it("falls back to defaultBlockLabel when customBlockLabel is empty", () => {
+    expect(resolveTraceLabel(make("", "Dataset"))).toBe("Dataset");
+  });
+
+  it("falls back to the block-type default when both label fields are empty", () => {
+    expect(resolveTraceLabel(make("", ""))).toBe("Sequence Properties");
+  });
+});

model/src/label.ts

@@ -0,0 +1,17 @@
+import type { BlockData } from "./types";
+
+const STATIC_FALLBACK = "Sequence Properties";
+
+// Subtitle resolution for the PlBlockPage. Empty string is a valid result
+// (the page renders the title alone).
+export function resolveSubtitle(data: BlockData): string {
+  return data.customBlockLabel || data.defaultBlockLabel;
+}
+
+// Trace-label resolution for the workflow's pl7.app/trace.label. Same chain
+// as resolveSubtitle plus a static block-type last-resort, so automated
+// pipelines that run before the UI populates defaultBlockLabel still emit
+// a non-empty label downstream.
+export function resolveTraceLabel(data: BlockData): string {
+  return data.customBlockLabel || data.defaultBlockLabel || STATIC_FALLBACK;
+}

model/src/types.ts

@@ -6,19 +6,31 @@ import type { PlDataTableStateV2, PlRef } from "@platforma-sdk/model";
 export type BlockDataV1 = {
   inputAnchor?: PlRef;
   tableState: PlDataTableStateV2;
-  // UI-only state. Tracks the selected input dataset's label so the block
-  // subtitle can reflect it — populated by the UI watcher in app.ts. Not
-  // projected into BlockArgs because the workflow does not consume it.
+  // Historically optional UI-only state. Required in the current BlockData
+  // shape; consumed by the label helpers in label.ts (resolveSubtitle for
+  // the PlBlockPage subtitle, resolveTraceLabel for the workflow trace).
   defaultBlockLabel?: string;
 };
 
-export type BlockData = BlockDataV1 & {
+// V2 shape — what the deployed Ver_2026_05_05 migration produces. Input to
+// the new Ver_2026_05_18 step that backfills the label fields. Both label
+// fields are optional here so the V2→V2.1 migration can read-or-default any
+// value an interim deployment may have written.
+export type BlockDataV2 = Omit<BlockDataV1, "defaultBlockLabel"> & {
+  defaultBlockLabel?: string;
+  customBlockLabel?: string;
   graphStateScatter: GraphMakerState;
   graphStateHistogram: GraphMakerState;
 };
 
+export type BlockData = Omit<BlockDataV2, "defaultBlockLabel"> & {
+  defaultBlockLabel: string;
+  customBlockLabel: string;
+};
+
 export type BlockArgs = {
   inputAnchor: PlRef;
+  traceLabel: string;
 };
 
 export type WorkflowMode =

model/vitest.config.mts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    watch: false,
+    testTimeout: 5000,
+  },
+});

package.json

@@ -27,5 +27,5 @@
     "oxfmt": "*",
     "oxlint": "*"
   },
-  "packageManager": "pnpm@10.33.2"
+  "packageManager": "pnpm@9.15.0"
 }