Phase 7e: rename the whole's wire protocol from *_global to *_whole

The Python API and the panels say "whole"; the wire protocol still said
"global". Shipping 1.0 with that contradiction is not acceptable, and with no
external users there is no back-compat to keep.

set_global_representation -> set_whole_representation, show_global -> show_whole,
hide_global -> hide_whole, and the target: "global" payload -> "whole" (the
"all" target is unchanged). The TS message types (SetWholeRepresentationMessage,
ShowWholeMessage, HideWholeMessage) and handlers (setWholeRepresentation,
showWhole, hideWhole) follow. Internal names that are not wire protocol --
globalReprs, currentGlobalRepresentationRefs, the { tag: "global" } Mol* state
tags -- are left as they are.

Verified end to end in real Mol*: set_whole_representation renders the whole,
hide_whole/show_whole toggle it, with no console errors. Python and JS suites
green; tsc unchanged.

This closes Phase 7. Deferred to Phase 12 (Whole subpanel GUI): the whole's
PanelAction family and the whole summary payload -- GUI infrastructure with no
consumer until the subpanel exists.

Author: dprada

devguide/pending_proposals/scene_master_plan.md

@@ -690,7 +690,7 @@ none were reported by a failing test.
 | 4 | Contract B/O: colour + order | L | ☑ | 2026-07-11 | *(this commit)* | **Passed.** Done in two slices (4a colour/decorator, 4b order→render + region-vs-region ownership). Decorator, layers, precedence, region-vs-region masking + R-O1 all mutation-verified in real Mol\*. `order` serialisation deferred to P6. |
 | 5 | Contract R: recipes | L | ☑ | 2026-07-11 | *(this commit)* | **Passed.** provenance/uid/mode/frame_dependent, uid-referenced recipes, operand-deletion freeze, read-only atom_indices, and rebuild re-evaluation (not remap) all mutation-verified. `mode` is a validating setter, not a `new_region` arg. Dynamic evaluation → P10, serialisation → P6. |
 | 6 | Contract C: state v2 | M | ☑ | 2026-07-11 | *(this commit)* | **Passed.** Implemented by Claude (author == auditor; flagged). Round-trip overlap winner, order high-water mark, topological restore, transient filter, whole restore all mutation-verified. No v1 reader. Layer-membership is a format-only field (behaviour → P9). |
-| 7 | API completeness & symmetry | L | ☐ | — | — | — |
+| 7 | API completeness & symmetry | L | ☑ | 2026-07-11 | `cb7a26dd`+ | **Passed.** Done in five slices 7a–7e (variadic booleans + count + complement-of-many; visible/set_color_scheme/manager parity; read-only state; view.regions.add; protocol rename *_global→*_whole verified in real Mol\*). Implemented by Claude. **Deferred to P12:** the whole PanelAction family and whole summary (GUI infrastructure, no consumer until the Whole subpanel). |
 | 8 | Contract H: command history | L | ☐ | — | — | — |
 | 9 | Layer membership | M | ☐ | — | — | — |
 | 10 | Dynamic-region evaluation | L | ☐ | — | — | — |

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

@@ -24,19 +24,19 @@ import {
     DeleteLayerMessage,
     DeleteRegionMessage,
     RenameRegionMessage,
-    HideGlobalMessage,
+    HideWholeMessage,
     HideLayerMessage,
     HideRegionMessage,
     SetAtomColorsMessage,
-    SetGlobalRepresentationMessage,
+    SetWholeRepresentationMessage,
     SetFocusFadeMessage,
     SetLayerTagMessage,
     SetRegionRepresentationMessage,
     SetRegionOrderMessage,
     SetRegionsVisibilityMessage,
     SetRegionSummariesMessage,
     BatchRegionOperationsMessage,
-    ShowGlobalMessage,
+    ShowWholeMessage,
     ShowLayerMessage,
     ShowRegionMessage,
     UpdateVisibilityMessage,
@@ -98,7 +98,7 @@ export class StateHandlers {
     private readonly layerMeta = new Map<string, { kind?: string; meta?: Record<string, unknown> }>();
     private readonly tagIndex = new Map<string, Set<StateTransform.Ref>>();
     private readonly globalReprs = new Set<StateTransform.Ref>();
-    private readonly pendingGlobalOps: Array<{ hide: boolean; target: "global" | "all" }> = [];
+    private readonly pendingGlobalOps: Array<{ hide: boolean; target: "whole" | "all" }> = [];
     private readonly pendingLayerVisibility = new Map<string, boolean>();
     private readonly pendingRegions: CreateRegionMessage[] = [];
     private regionStyleOptions = { representations: [] as string[], presets: [] as string[] };
@@ -1075,7 +1075,7 @@ export class StateHandlers {
         }
     }
 
-    async setGlobalRepresentation(msg: SetGlobalRepresentationMessage) {
+    async setWholeRepresentation(msg: SetWholeRepresentationMessage) {
         const structureRef = this.callbacks.getLoadedStructure()?.structure;
         if (!structureRef) return;
 
@@ -1217,12 +1217,12 @@ export class StateHandlers {
         await this.applyComposedTransparency();
     }
 
-    async showGlobal(msg: ShowGlobalMessage) {
-        await this.handleShowHideGlobal(false, msg.target ?? "global");
+    async showWhole(msg: ShowWholeMessage) {
+        await this.handleShowHideGlobal(false, msg.target ?? "whole");
     }
 
-    async hideGlobal(msg: HideGlobalMessage) {
-        await this.handleShowHideGlobal(true, msg.target ?? "global");
+    async hideWhole(msg: HideWholeMessage) {
+        await this.handleShowHideGlobal(true, msg.target ?? "whole");
     }
 
     async zoom(msg: ZoomMessage) {
@@ -1280,7 +1280,7 @@ export class StateHandlers {
             await this.ensureDefaultGlobalRepresentation();
         }
         if (this.requestedGlobalHidden !== null) {
-            await this.handleShowHideGlobal(this.requestedGlobalHidden, "global");
+            await this.handleShowHideGlobal(this.requestedGlobalHidden, "whole");
         }
     }
 
@@ -1323,8 +1323,8 @@ export class StateHandlers {
         this.tagIndex.delete(tag);
     }
 
-    private async handleShowHideGlobal(hide: boolean, target: "global" | "all" = "global") {
-        if (target === "global") {
+    private async handleShowHideGlobal(hide: boolean, target: "whole" | "all" = "whole") {
+        if (target === "whole") {
             this.requestedGlobalHidden = hide;
         }
         if (!this.callbacks.getStructure()) {
@@ -1343,7 +1343,7 @@ export class StateHandlers {
             if (entry.hidden) hiddenRegionReprRefs.add(ref as any);
         }));
 
-        if (target === "global") {
+        if (target === "whole") {
             this.globalReprs.forEach(ref => {
                 refs.push(ref);
                 baselineRefs.push(ref);
@@ -1396,7 +1396,7 @@ export class StateHandlers {
             if (baselineRefs.length) {
                 baselineRefs.forEach(ref => setSubtreeVisibility(this.plugin.state.data, ref, true));
             } else {
-                this.pendingGlobalOps.push({ hide: true, target: "global" });
+                this.pendingGlobalOps.push({ hide: true, target: "whole" });
             }
         }
     }

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

@@ -77,7 +77,7 @@ const PANEL_REFRESH_BY_OPERATION: Partial<Record<ViewerMessage["op"], readonly P
     set_figure_spec: ["addons"],
     set_user_preset: ["addons"],
     set_canvas_visibility: ["addons"],
-    set_global_representation: ["addons"],
+    set_whole_representation: ["addons"],
     load_molsys_payload: ["addons"],
     load_structure_from_string: ["addons"],
     load_pdb_string: ["addons"],
@@ -2187,9 +2187,9 @@ export class MolSysViewerController {
                     await this.state.clearAtomColors(msg as any);
                     this.groupPanel.render();
                     break;
-                case "set_global_representation": await this.state.setGlobalRepresentation(msg); break;
-                case "show_global": await this.state.showGlobal(msg); break;
-                case "hide_global": await this.state.hideGlobal(msg); break;
+                case "set_whole_representation": await this.state.setWholeRepresentation(msg); break;
+                case "show_whole": await this.state.showWhole(msg); break;
+                case "hide_whole": await this.state.hideWhole(msg); break;
                 case "zoom": await this.state.zoom(msg); break;
                 case "zoom_to_position": await this.scene.zoomToPosition(msg as any); break;
                 case "set_camera_snapshot": await this.setCameraSnapshot((msg as any).snapshot, (msg as any).duration_ms); break;
@@ -2851,7 +2851,7 @@ export class MolSysViewerController {
             return;
         }
 
-        if (op === "set_global_representation") {
+        if (op === "set_whole_representation") {
             const styleTag =
                 typeof (msg as any).user_preset?.name === "string"
                     ? (msg as any).user_preset.name

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

@@ -526,8 +526,8 @@ export type SetLayerTagMessage = {
     new_tag: string;
 };
 
-export type SetGlobalRepresentationMessage = {
-    op: "set_global_representation";
+export type SetWholeRepresentationMessage = {
+    op: "set_whole_representation";
     representation?: string;
     preset?: string;
     user_preset?: any;
@@ -541,14 +541,14 @@ export type SetFigureSpecMessage = {
     figure_variants?: string[];
 };
 
-export type ShowGlobalMessage = {
-    op: "show_global";
-    target?: "global" | "all";
+export type ShowWholeMessage = {
+    op: "show_whole";
+    target?: "whole" | "all";
 };
 
-export type HideGlobalMessage = {
-    op: "hide_global";
-    target?: "global" | "all";
+export type HideWholeMessage = {
+    op: "hide_whole";
+    target?: "whole" | "all";
 };
 
 export type ZoomMessage = {
@@ -810,10 +810,10 @@ export type ViewerMessage =
     HideLayerMessage |
     DeleteLayerMessage |
     SetLayerTagMessage |
-    SetGlobalRepresentationMessage |
+    SetWholeRepresentationMessage |
     SetFigureSpecMessage |
-    ShowGlobalMessage |
-    HideGlobalMessage |
+    ShowWholeMessage |
+    HideWholeMessage |
     ZoomMessage |
     ZoomToPositionMessage |
     SetCameraSnapshotMessage |

molsysviewer/js/tests/e2e/harness.ts

@@ -619,7 +619,7 @@ export async function profileExclusiveOwnership(
     const fullWhole = atomRange(0, atoms);
     const complementWhole = atomRange(ownedAtoms, atoms);
 
-    await profiled.handleMessage({ op: "hide_global", target: "global" });
+    await profiled.handleMessage({ op: "hide_whole", target: "whole" });
     await profiled.handleMessage({ op: "create_region", tag: "__exclusive_owned_region__", atom_indices: owned });
     await profiled.handleMessage({
         op: "set_region_representation",
@@ -821,7 +821,7 @@ export async function probeExclusiveOwnershipPicking(
     if (!structure) throw new Error("Exclusive ownership picking probe requires a loaded structure.");
 
     const owned = atomRange(0, ownedAtoms);
-    await profiled.handleMessage({ op: "hide_global", target: "global" });
+    await profiled.handleMessage({ op: "hide_whole", target: "whole" });
     const explicitWhole = await buildExclusiveWhole(profiled, atomRange(0, atoms), "cartoon");
     const explicitWholeComponent = findComponentByRef(profiled, explicitWhole.componentRef);
     if (!explicitWholeComponent) throw new Error("Exclusive ownership picking probe failed to create explicit whole component.");
@@ -930,7 +930,7 @@ export async function probeGlobalRepresentationOwnershipMask(
         representation: "ball-and-stick",
     });
     await profiled.handleMessage({
-        op: "set_global_representation",
+        op: "set_whole_representation",
         ...options.globalMessage,
     } as any);
 
@@ -975,7 +975,7 @@ export async function probePerAtomColorDecorator(
     if (!structure) throw new Error("Per-atom color decorator probe requires a loaded structure.");
 
     await profiled.handleMessage({
-        op: "set_global_representation",
+        op: "set_whole_representation",
         representation: "ball-and-stick",
         params: { color_scheme: "element_cpk" },
     } as any);

molsysviewer/js/tests/unit/popup-logic.test.ts

@@ -196,7 +196,7 @@ test("bootPopup replays initial sync and enables autohide listeners", async () =
             data: {
                 type: "molsysviewer-initial-sync",
                 data: {
-                    messages: [{ op: "load_molsys_payload" }, { op: "hide_global", target: "global" }],
+                    messages: [{ op: "load_molsys_payload" }, { op: "hide_whole", target: "whole" }],
                     cameraSnapshot: { target: [0, 0, 0] },
                     isSpinActive: true,
                     isSwingActive: true,
@@ -209,7 +209,7 @@ test("bootPopup replays initial sync and enables autohide listeners", async () =
 
         assert.deepStrictEqual(calls.handled, [
             { op: "load_molsys_payload" },
-            { op: "hide_global", target: "global" },
+            { op: "hide_whole", target: "whole" },
         ]);
         assert.deepStrictEqual(calls.camera, [
             { snapshot: { target: [0, 0, 0] }, duration: 0 },
@@ -372,13 +372,13 @@ test("bootPopup dispatches molsysviewer-sync-op to controller (live mirror)", as
         await flushAsync();
 
         env.windowObj.dispatch("message", {
-            data: { type: "molsysviewer-sync-op", data: { op: "show_global", target: "global" } },
+            data: { type: "molsysviewer-sync-op", data: { op: "show_whole", target: "whole" } },
         });
         await flushAsync();
 
         assert.deepStrictEqual(handled, [
             { op: "hide_region", tag: "r1" },
-            { op: "show_global", target: "global" },
+            { op: "show_whole", target: "whole" },
         ]);
     } finally {
         (globalThis as any).window = previousWindow;

molsysviewer/js/tests/unit/state-handler.test.ts

@@ -638,14 +638,14 @@ test("state handler queues global visibility ops when structure is not ready", a
         notify: (_msg: any) => {},
     });
 
-    await handler.hideGlobal({ op: "hide_global" });
+    await handler.hideWhole({ op: "hide_whole" });
     const pendingOpsA = (handler as any).pendingGlobalOps as Array<{ hide: boolean; target: string }>;
     const requestedA = (handler as any).requestedGlobalHidden as boolean | null;
     assert.strictEqual(pendingOpsA.length, 1);
-    assert.deepStrictEqual(pendingOpsA[0], { hide: true, target: "global" });
+    assert.deepStrictEqual(pendingOpsA[0], { hide: true, target: "whole" });
     assert.strictEqual(requestedA, true);
 
-    await handler.showGlobal({ op: "show_global", target: "all" });
+    await handler.showWhole({ op: "show_whole", target: "all" });
     const pendingOpsB = (handler as any).pendingGlobalOps as Array<{ hide: boolean; target: string }>;
     const requestedB = (handler as any).requestedGlobalHidden as boolean | null;
     assert.strictEqual(pendingOpsB.length, 2);
@@ -728,8 +728,8 @@ test("state handler clears orphan default global representations before applying
     };
     (handler as any).handleShowHideGlobal = async () => {};
 
-    await handler.setGlobalRepresentation({
-        op: "set_global_representation",
+    await handler.setWholeRepresentation({
+        op: "set_whole_representation",
         preset: "auto",
         params: {},
     } as any);
@@ -781,8 +781,8 @@ test("state handler replaces prior explicit global representation on subsequent
     };
     (handler as any).handleShowHideGlobal = async () => {};
 
-    await handler.setGlobalRepresentation({ op: "set_global_representation", preset: "auto", params: {} } as any);
-    await handler.setGlobalRepresentation({ op: "set_global_representation", preset: "polymer-cartoon", params: {} } as any);
+    await handler.setWholeRepresentation({ op: "set_whole_representation", preset: "auto", params: {} } as any);
+    await handler.setWholeRepresentation({ op: "set_whole_representation", preset: "polymer-cartoon", params: {} } as any);
 
     assert.deepStrictEqual(removed, ["first-global-repr"]);
     const globalReprs = (handler as any).globalReprs as Set<string>;
@@ -880,8 +880,8 @@ test("state handler maps structural color_scheme to a Mol* color theme for direc
     });
     (handler as any).handleShowHideGlobal = async () => {};
 
-    await handler.setGlobalRepresentation({
-        op: "set_global_representation",
+    await handler.setWholeRepresentation({
+        op: "set_whole_representation",
         representation: "cartoon",
         params: { color_scheme: "secondary_structure_default" },
     } as any);
@@ -948,8 +948,8 @@ test("state handler maps curated structural color and size schemes for direct gl
     });
     (handler as any).handleShowHideGlobal = async () => {};
 
-    await handler.setGlobalRepresentation({
-        op: "set_global_representation",
+    await handler.setWholeRepresentation({
+        op: "set_whole_representation",
         representation: "cartoon",
         params: { color_scheme: "residue_name", size_scheme: "physical" },
     } as any);
@@ -1017,8 +1017,8 @@ test("state handler accepts advanced Mol* color and size themes for direct globa
     });
     (handler as any).handleShowHideGlobal = async () => {};
 
-    await handler.setGlobalRepresentation({
-        op: "set_global_representation",
+    await handler.setWholeRepresentation({
+        op: "set_whole_representation",
         representation: "cartoon",
         params: {
             molstar_color_theme: { name: "residue-name", params: { saturation: 0 } },
@@ -1089,8 +1089,8 @@ test("state handler gives curated structural color and size schemes priority ove
     });
     (handler as any).handleShowHideGlobal = async () => {};
 
-    await handler.setGlobalRepresentation({
-        op: "set_global_representation",
+    await handler.setWholeRepresentation({
+        op: "set_whole_representation",
         representation: "cartoon",
         params: {
             color_scheme: "secondary_structure_default",