Track scene object creator attribution

Author: dprada

docs/content/developer/changes_notes.md

@@ -35,3 +35,4 @@ This page tracks major architectural and documentation milestones.
 - 2026-07-14: The ElasNetMT add-on was renamed to **ElastNetMT**. The Python package is now `elastnetmt`, the MolSysViewer bridge module is `molsysviewer_elastnetmt`, and `KNOWN_ADDON_MODULES` discovers the new name only. Environments with the old package installed must reinstall it; the previous module name is no longer discovered.
 - 2026-07-15: Breaking scene-manager consistency fix: `info(tag)` now returns a `dict` for one tag across regions, shapes, annotations, measurements, and layers; shapes and measurements previously returned a one-element list. A missing tag raises `ValueError` in all five managers; regions and layers previously leaked `KeyError`. Calling `info()` without a tag continues to return a list.
 - 2026-07-15: Layer summaries no longer expose `kind`: a layer can contain objects from several scene domains, so reporting the last attached member's kind was misleading. The internal `Layer.kind` protocol/state field remains unchanged.
+- 2026-07-15: Scene-object creator attribution added. Add-ons can wrap public scene construction in `with view.attributed_to("elastnetmt"):`; layers, regions, shapes, annotations, measurements, and sections created inside expose an immutable `owner` property. The optional owner is shown in Studio summaries and survives state-v2 export/import. It is informational only and never restricts rename, movement, visibility, or deletion. Older v2 documents without `owner` restore objects as user-created (`owner=None`).

docs/content/developer/public_api.md

@@ -55,6 +55,10 @@ edits on an existing viewer are provided by the MolSysMT addon namespace:
 
 `MolSysView` is also explicitly growing an inspection-oriented object API beyond the minimal viewer shell. Public user-facing methods now include:
 
+- `attributed_to(owner)`
+  - context manager for add-ons creating scene objects through the public API
+  - objects created inside expose the immutable informational property `owner`
+  - attribution does not grant ownership rights or prevent user operations
 - `load(..., mode="add" | "replace" | "append_structures" | "auto", ...)`
   - current default is `mode="add"`
   - first load initializes `whole` without creating an automatic region

molsysviewer/annotations.py

@@ -148,6 +148,7 @@ def summarize(record: dict[str, Any]) -> dict[str, Any]:
             return {
                 "kind": "label" if record.get("op") == "add_label" else "annotation",
                 "tag": record_tag,
+                "owner": None if layer is None else layer.owner,
                 "layer_tag": None if layer is None else getattr(layer, "layer_tag", record_tag),
                 "text": options.get("text"),
                 "style": dict(options.get("style") or {}),

molsysviewer/js/src/managers/handlers/state-handlers.ts

@@ -74,6 +74,7 @@ interface RegionEntry {
 
 export interface RegionSummary {
     tag: string;
+    owner?: string;
     atom_indices: number[];
     atom_count: number;
     selection?: string;
@@ -1042,6 +1043,7 @@ export class StateHandlers {
             .filter(item => typeof item?.tag === "string")
             .map(item => ({
                 tag: item.tag,
+                owner: typeof item.owner === "string" ? item.owner : undefined,
                 atom_indices: Array.isArray(item.atom_indices)
                     ? item.atom_indices.filter((value): value is number => typeof value === "number")
                     : [],

molsysviewer/js/src/managers/viewer-controller.ts

@@ -2173,6 +2173,7 @@ export class MolSysViewerController {
                         .filter((item: any) => typeof item?.tag === "string" && (item.provenance === "auto" || item.provenance === "user"))
                         .map((item: any) => ({
                             tag: item.tag,
+                            owner: typeof item.owner === "string" ? item.owner : undefined,
                             provenance: item.provenance,
                             hidden: !!item.hidden,
                         }));
@@ -2184,6 +2185,7 @@ export class MolSysViewerController {
                     this.annotationSummaries = records.filter((item: any) => typeof item?.tag === "string").map((item: any) => ({
                         kind: typeof item.kind === "string" ? item.kind : "annotation",
                         tag: item.tag,
+                        owner: typeof item.owner === "string" ? item.owner : undefined,
                         layerTag: typeof item.layer_tag === "string" ? item.layer_tag : undefined,
                         text: typeof item.text === "string" ? item.text : item.tag,
                         style: item.style && typeof item.style === "object" ? {
@@ -2215,6 +2217,7 @@ export class MolSysViewerController {
                     this.measurementSummaries = records.filter((item: any) => typeof item?.tag === "string").map((item: any) => ({
                         kind: ["distance", "angle", "dihedral"].includes(item.kind) ? item.kind : "measurement",
                         tag: item.tag,
+                        owner: typeof item.owner === "string" ? item.owner : undefined,
                         layerTag: typeof item.layer_tag === "string" ? item.layer_tag : undefined,
                         picks: typeof item.n_picks === "number" ? item.n_picks : 0,
                         hidden: !!item.hidden,
@@ -2259,6 +2262,7 @@ export class MolSysViewerController {
                         op: typeof item.op === "string" ? item.op : "",
                         kind: typeof item.kind === "string" ? item.kind : "shape",
                         tag: item.tag,
+                        owner: typeof item.owner === "string" ? item.owner : undefined,
                         layerTag: typeof item.layer_tag === "string" ? item.layer_tag : undefined,
                         title: typeof item.title === "string" ? item.title : item.tag,
                         subtitle: typeof item.subtitle === "string" ? item.subtitle : undefined,
@@ -2829,20 +2833,23 @@ export class MolSysViewerController {
             ...this.annotationSummaries.map((item) => ({
                 kind: "annotation" as const,
                 tag: item.tag,
+                owner: item.owner,
                 title: item.text,
                 layerTag: item.layerTag,
                 hidden: item.hidden,
             })),
             ...this.measurementSummaries.map((item) => ({
                 kind: "measurement" as const,
                 tag: item.tag,
+                owner: item.owner,
                 title: `${item.kind[0].toUpperCase()}${item.kind.slice(1)}`,
                 layerTag: item.layerTag,
                 hidden: item.hidden,
             })),
             ...this.shapeSummaries.map((item) => ({
                 kind: "shape" as const,
                 tag: item.tag,
+                owner: item.owner,
                 title: item.title,
                 layerTag: item.layerTag,
                 hidden: item.hidden,

molsysviewer/js/src/messages/viewer-messages.ts

@@ -474,6 +474,7 @@ export type SetRegionSummariesMessage = {
     op: "set_region_summaries";
     regions?: Array<{
         tag: string;
+        owner?: string | null;
         atom_indices?: number[];
         atom_count?: number;
         selection?: string;
@@ -496,6 +497,7 @@ export type SetLayerSummariesMessage = {
     op: "set_layer_summaries";
     layers?: Array<{
         tag: string;
+        owner?: string | null;
         provenance: "auto" | "user";
         hidden?: boolean;
     }>;
@@ -521,6 +523,7 @@ export type SetAnnotationSummariesMessage = {
     annotations?: Array<{
         kind?: string;
         tag: string;
+        owner?: string | null;
         layer_tag?: string | null;
         text?: string | null;
         style?: LabelStyle | null;
@@ -540,6 +543,7 @@ export type SetMeasurementSummariesMessage = {
     measurements?: Array<{
         kind?: string;
         tag: string;
+        owner?: string | null;
         layer_tag?: string | null;
         n_picks?: number;
         atom_indices?: number[];
@@ -575,6 +579,7 @@ export type SetShapeSummariesMessage = {
         op?: string;
         kind?: string;
         tag: string;
+        owner?: string | null;
         layer_tag?: string | null;
         title?: string;
         subtitle?: string | null;

molsysviewer/js/src/ui/group-panel.ts

@@ -85,6 +85,7 @@ export type OnAnnotationContext = (target: ContextMenuTarget, pageX: number, pag
 export type SavedSelectionSummary = { tag: string; atom_count: number; element_level?: string };
 export type RegionSummary = {
     tag: string;
+    owner?: string;
     atom_count: number;
     hidden: boolean;
     layer?: string | null;

molsysviewer/js/src/ui/panels/annotations-panel.ts

@@ -13,6 +13,7 @@ export type AnnotationLabelStyle = {
 export type AnnotationSummary = {
     kind: string;
     tag: string;
+    owner?: string;
     layerTag?: string;
     text: string;
     hidden: boolean;
@@ -223,8 +224,8 @@ export class AnnotationsPanel extends BasePanel {
 
         const identity = document.createElement("div");
         identity.textContent = item.broken
-            ? `${item.tag} · anchor broken`
-            : `${item.tag} · ${item.nAtoms} atom${item.nAtoms === 1 ? "" : "s"}${item.layerTag && item.layerTag !== item.tag ? ` · layer: ${item.layerTag}` : ""}`;
+            ? `${item.tag} · anchor broken${item.owner ? ` · from ${item.owner}` : ""}`
+            : `${item.tag} · ${item.nAtoms} atom${item.nAtoms === 1 ? "" : "s"}${item.layerTag && item.layerTag !== item.tag ? ` · layer: ${item.layerTag}` : ""}${item.owner ? ` · from ${item.owner}` : ""}`;
         identity.setAttribute("data-molsysviewer-annotation-identity", item.tag);
         Object.assign(identity.style, { fontSize: "10px", color: "rgba(244,244,245,0.58)" });
         row.appendChild(identity);

molsysviewer/js/src/ui/panels/layers-panel.ts

@@ -5,13 +5,15 @@ import { makeButton, makeSectionHeader, makeSettingsCard } from "./ui-helpers";
 
 export type LayerSummary = {
     tag: string;
+    owner?: string;
     provenance: "auto" | "user";
     hidden: boolean;
 };
 
 export type LayerObjectSummary = {
     kind: "annotation" | "measurement" | "shape";
     tag: string;
+    owner?: string;
     title: string;
     layerTag?: string;
     hidden?: boolean;
@@ -21,6 +23,7 @@ type MemberKind = "region" | LayerObjectSummary["kind"];
 type LayerMember = {
     kind: MemberKind;
     tag: string;
+    owner?: string;
     title: string;
     layerTag?: string | null;
     hidden: boolean;
@@ -91,6 +94,7 @@ export class LayersPanel extends BasePanel {
             ...this.regions.map(region => ({
                 kind: "region" as const,
                 tag: region.tag,
+                owner: region.owner,
                 title: region.tag,
                 layerTag: region.layer,
                 hidden: region.hidden,
@@ -99,6 +103,7 @@ export class LayersPanel extends BasePanel {
             ...this.objects.map(object => ({
                 kind: object.kind,
                 tag: object.tag,
+                owner: object.owner,
                 title: object.title,
                 layerTag: object.layerTag,
                 hidden: !!object.hidden,
@@ -145,7 +150,7 @@ export class LayersPanel extends BasePanel {
         card.setAttribute("data-molsysviewer-layer-card", layer.tag);
 
         const summary = document.createElement("div");
-        summary.textContent = `${layer.members.length} member${layer.members.length === 1 ? "" : "s"}`;
+        summary.textContent = `${layer.members.length} member${layer.members.length === 1 ? "" : "s"}${layer.owner ? ` · from ${layer.owner}` : ""}`;
         Object.assign(summary.style, { fontSize: "10px", color: "rgba(244,244,245,0.56)" });
         card.appendChild(summary);
 
@@ -239,7 +244,7 @@ export class LayersPanel extends BasePanel {
             background: "rgba(255,255,255,0.04)", border: "1px solid rgba(255,255,255,0.05)",
         });
         const label = document.createElement("div");
-        label.textContent = `${member.title} · ${member.kind}${member.atomCount === undefined ? "" : ` · ${member.atomCount} atoms`}`;
+        label.textContent = `${member.title} · ${member.kind}${member.atomCount === undefined ? "" : ` · ${member.atomCount} atoms`}${member.owner ? ` · from ${member.owner}` : ""}`;
         Object.assign(label.style, { minWidth: "0", fontSize: "11px", color: member.hidden ? "rgba(244,244,245,0.42)" : "#f4f4f5" });
         const remove = makeButton("Remove", () => this.ctx.onAction("remove_member_from_layer", {
             layer: layerTag,

molsysviewer/js/src/ui/panels/measures-panel.ts

@@ -6,6 +6,7 @@ import { makeButton, makeSectionHeader } from "./ui-helpers";
 export type MeasurementSummary = {
     kind: "distance" | "angle" | "dihedral" | "measurement";
     tag: string;
+    owner?: string;
     layerTag?: string;
     picks: number;
     hidden: boolean;
@@ -202,7 +203,7 @@ export class MeasuresPanel extends BasePanel {
         row.appendChild(head);
 
         const identity = document.createElement("div");
-        identity.textContent = `${item.kind} · ${item.tag}${item.layerTag && item.layerTag !== item.tag ? ` · layer: ${item.layerTag}` : ""}`;
+        identity.textContent = `${item.kind} · ${item.tag}${item.layerTag && item.layerTag !== item.tag ? ` · layer: ${item.layerTag}` : ""}${item.owner ? ` · from ${item.owner}` : ""}`;
         Object.assign(identity.style, { fontSize: "10px", color: "rgba(244,244,245,0.58)" });
         row.appendChild(identity);
         const endpoints = document.createElement("div");