@yuneta/gobj-ui 3.0.0 → 4.0.0

package/src/c_yui_treedb_graph.js

@@ -57,6 +57,11 @@ import {
     trace_json,
     json_object_update_missing,
     gobj_start,
+    gobj_stop,
+    gobj_is_running,
+    gobj_current_state,
+    is_gobj,
+    gobj_is_destroying,
     log_info,
     trace_msg,
     refresh_language,
@@ -80,8 +85,8 @@ import {
     set_submit_state,
     set_active_state,
 } from "./lib_graph.js";
-import {yui_shell_show_error} from "./shell_modals.js";
-import {yui_shell_of} from "./c_yui_shell.js";
+import {yui_shell_show_error, yui_shell_show_modal, yui_shell_popup_layer} from "./shell_modals.js";
+import {yui_shell_of, yui_shell_set_sub_routes} from "./c_yui_shell.js";
 
 import {t} from "i18next";
 
@@ -110,6 +115,8 @@ SDATA(data_type_t.DTP_POINTER,  "gobj_remote_yuno", 0,  null,   "Remote Yuno to
 SDATA(data_type_t.DTP_STRING,   "treedb_name",      0,  null,   "Remote service treedb name"),
 SDATA(data_type_t.DTP_DICT,     "descs",            0,  null,   "Descriptions of topics obtained"),
 SDATA(data_type_t.DTP_BOOLEAN,  "system",           0,  false,  "Manage system topics (true) or user topics (false)"),
+SDATA(data_type_t.DTP_STRING,   "back_route",       0,  "",     "Optional hash route for a '← topics' button back to the topics grid (host-supplied; empty = no button)"),
+SDATA(data_type_t.DTP_STRING,   "base_route",       0,  "",     "This view's base route (host-supplied); used to declare its per-topic focus sub-routes to the site map (ROUTING.md contributor)."),
 SDATA(data_type_t.DTP_DICT,     "records",          0,  "{}",   "Data of topics"),
 SDATA(data_type_t.DTP_LIST,     "topics",           0,  "[]",   "List of topic objects"),
 
@@ -141,11 +148,15 @@ let PRIVATE_DATA = {
     gobj_nodes_tree:    null,
     gobj_treedb_tables: null,
     hook_data_viewer:   null,
+    json_gobj:          null,   /*  C_YUI_JSON viewer of the raw tranger (or null)  */
+    json_win:           null,   /*  C_YUI_WINDOW hosting it, desktop (or null)  */
+    json_modal:         null,   /*  shell modal hosting it, mobile (or null)  */
     with_treedb_tables: false,
     canvas_id:          null,
     operation_mode:     null,
     layout:             null,
     _topics_subscribed: {},
+    _links_subscribed:  false,  /*  EV_TREEDB_NODE_LINKED/UNLINKED (treedb-wide)  */
 
     is_pinhold_window:  false, // inherited of v6, todo review
 };
@@ -182,15 +193,6 @@ function mt_create(gobj)
         log_error(`${gobj_name(gobj)} -> treedb_name not configured`);
     }
 
-    /*  Optional legacy integration: EV_RESIZE from C_YUI_MAIN
-     *  (old shell).  Under the new C_YUI_SHELL there is no
-     *  __yui_main__ — look it up SILENTLY (no verbose) so its
-     *  absence is not logged as an error every mount. */
-    let __yui_main__ = gobj_find_service("__yui_main__");
-    if(__yui_main__) {
-        gobj_subscribe_event(__yui_main__, "EV_RESIZE", {}, gobj);
-    }
-
     /*
      *  set canvas_id, before build_ui()
      */
@@ -284,6 +286,11 @@ function mt_start(gobj)
  ***************************************************************/
 function mt_stop(gobj)
 {
+    let shell = yui_shell_of(gobj);
+    if(shell) {
+        yui_shell_set_sub_routes(shell, gobj_read_str_attr(gobj, "base_route"), null);
+    }
+    close_json_viewer(gobj);
     gobj_stop_children(gobj);
 }
 
@@ -318,12 +325,17 @@ function build_ui(gobj)
     let padding = gobj_read_attr(gobj, "padding");
     let $toolbar = make_toolbar(gobj);
 
+    /*  The back link is pinned in the row, BEFORE the toolbar, so the
+     *  toolbar's horizontal scroll never carries it off-screen. */
+    let $back = make_back_to_topics(gobj);
+    let row_items = $back ? [$back, $toolbar] : [$toolbar];
+
     let $container = createElement2(
         // Don't use is-flex, don't work well with is-hidden
         ['div', {class: 'C_YUI_TREEDB_GRAPH', style: `height:100%; display:flex; flex-direction:column;`}, [
-            ['div', {class: 'is-flex-grow-0 is-flex is-align-items-center toolbar_yui_treedb_graph'}, $toolbar],
-            ['div', {class: `is-flex-grow-1 ${padding}`, style: 'height:100%; min-height:0; overflow:hidden;'}, [
-                ['div', {id: priv.canvas_id, class: `graph-container`, style: 'height:100%; min-height:0;border: 1px solid var(--bulma-border-weak);border-radius:0.2rem;'}, [
+            ['div', {class: 'GRAPH_TOOLBAR_ROW is-flex-grow-0 is-flex is-align-items-center'}, row_items],
+            ['div', {class: `GRAPH_BODY is-flex-grow-1 ${padding}`, style: 'height:100%; min-height:0; overflow:hidden;'}, [
+                ['div', {id: priv.canvas_id, class: `GRAPH_CANVAS graph-container`, style: 'height:100%; min-height:0;border: 1px solid var(--bulma-border-weak);border-radius:0.2rem;'}, [
                 ]]
             ]]
         ]]
@@ -331,9 +343,49 @@ function build_ui(gobj)
 
     gobj_write_attr(gobj, "$container", $container);
     refresh_language($container, t);
+    refresh_raw_json_button(gobj);  /*  disabled until the backend session is up  */
     return $container;
 }
 
+/************************************************************
+ *  The "Raw JSON" viewer issues a remote print-tranger, so it only makes
+ *  sense with a live backend session — the remote (C_IEVENT_CLI) is in
+ *  ST_SESSION exactly while connected. Enable the button only then; native
+ *  `disabled` dims it (Bulma) and blocks its click.
+ ************************************************************/
+function is_connected(gobj)
+{
+    let remote = gobj_read_pointer_attr(gobj, "gobj_remote_yuno");
+    return !!remote && gobj_current_state(remote) === "ST_SESSION";
+}
+
+function refresh_raw_json_button(gobj, connected)
+{
+    let $container = gobj_read_attr(gobj, "$container");
+    if(!$container) {
+        return;
+    }
+    if(typeof connected !== "boolean") {
+        connected = is_connected(gobj);
+    }
+    let $raw = $container.querySelector(".TREEDB_JSON_BTN");
+    if($raw) {
+        $raw.disabled = !connected;
+    }
+}
+
+/************************************************************
+ *  The host (C_TREEDB_VIEW) forwards the backend transport edges here so the
+ *  "Raw JSON" button disables the moment the session drops and re-enables on
+ *  reconnect. The library view must not subscribe to the C_IEVENT_CLI itself
+ *  (that forwards the subscription upstream and breaks the session).
+ ************************************************************/
+function ac_transport_state(gobj, event, kw, src)
+{
+    refresh_raw_json_button(gobj, !!(kw && kw.connected));
+    return 0;
+}
+
 /************************************************************
  *   Show a non-blocking inline error banner at the top of the view
  *   (used when the treedb schema `descs` cannot load). Reuses a single
@@ -345,10 +397,10 @@ function show_load_error(gobj, message)
     if(!$container) {
         return;
     }
-    let $err = $container.querySelector(".treedb-load-error");
+    let $err = $container.querySelector(".GRAPH_LOAD_ERROR");
     if(!$err) {
         $err = createElement2(
-            ["div", {class: "notification is-danger is-light m-3 treedb-load-error"}, []]
+            ["div", {class: "GRAPH_LOAD_ERROR notification is-danger is-light m-3"}, []]
         );
         $container.insertBefore($err, $container.firstChild);
     }
@@ -389,9 +441,9 @@ function make_toolbar(gobj)
      *  via populate_nodes_tree_options()
      */
     let left_items = [
-        ['span', {class: 'is-hidden-mobile', style: 'padding-right:5px;', i18n: 'layout'}, 'layout'],
+        ['span', {class: 'GRAPH_LAYOUT_LABEL is-hidden-mobile', style: 'padding-right:5px;', i18n: 'layout'}, 'layout'],
         ['div', {class: 'select'}, [
-            ['select', {class: 'graph_layout'}]
+            ['select', {class: 'GRAPH_LAYOUT_SELECT'}]
         ], {
             change: (evt) => {
                 evt.stopPropagation();
@@ -399,9 +451,9 @@ function make_toolbar(gobj)
             }
         }],
 
-        ['span', {class: 'is-hidden-mobile', style: 'padding-left:10px; padding-right:5px;', i18n: 'operation mode'}, 'operation mode'],
+        ['span', {class: 'GRAPH_MODE_LABEL is-hidden-mobile', style: 'padding-left:10px; padding-right:5px;', i18n: 'operation mode'}, 'operation mode'],
         ['div', {class: 'select'}, [
-            ['select', {class: 'graph_operation_mode'}, mode_options]
+            ['select', {class: 'GRAPH_MODE_SELECT'}, mode_options]
         ], {
             change: (evt) => {
                 evt.stopPropagation();
@@ -409,7 +461,7 @@ function make_toolbar(gobj)
             }
         }],
 
-        ['button', {class: 'button EV_REFRESH_TREEDB'}, [
+        ['button', {class: 'GRAPH_REFRESH button'}, [
             ['i', {class: 'yi-arrows-rotate'}],
             ['span', {class: 'is-hidden-mobile', style: 'padding-left:5px;', i18n: 'refresh'}, 'refresh']
         ], {
@@ -418,6 +470,21 @@ function make_toolbar(gobj)
                 gobj_send_event(gobj, "EV_REFRESH_TREEDB", {evt}, gobj);
             }
         }],
+
+        /*  Inspect the treedb's raw tranger json in the lazy tree viewer
+         *  (print-tranger on the C_NODE service). A treedb can be huge, so
+         *  the viewer drills in on demand — see open_json_viewer.  */
+        ['button', {class: 'button ml-2 TREEDB_JSON_BTN',
+                    title: t('raw json'), 'aria-label': t('raw json'),
+                    'data-i18n-title': 'raw json', 'data-i18n-aria-label': 'raw json'}, [
+            ['i', {class: 'yi-eye'}],
+            ['span', {class: 'is-hidden-mobile', style: 'padding-left:5px;', i18n: 'raw json'}, 'raw json']
+        ], {
+            click: (evt) => {
+                evt.stopPropagation();
+                gobj_send_event(gobj, "EV_OPEN_JSON", {}, gobj);
+            }
+        }],
     ];
 
     /*
@@ -434,7 +501,7 @@ function make_toolbar(gobj)
     const $toolbar_header = yui_toolbar({}, [
         ['div', {class: 'yui-horizontal-toolbar-section left'}, left_items],
         ['div', {class: 'yui-horizontal-toolbar-section center'}, center_items],
-        ['div', {class: 'yui-horizontal-toolbar-section right mode_buttons'}, right_items]
+        ['div', {class: 'GRAPH_MODE_BUTTONS yui-horizontal-toolbar-section right'}, right_items]
     ]);
 
     refresh_language($toolbar_header, t);
@@ -442,6 +509,242 @@ function make_toolbar(gobj)
     return $toolbar_header;
 }
 
+/************************************************************
+ *  "← topics": a real hash link back to the topics grid (host-supplied
+ *  `back_route`), shown only when set. Lets a graph reached from a topic
+ *  card's graph icon return to the cards landing — symmetric with the
+ *  topics view's own back button. Absent (e.g. wattyzer) ⇒ no button.
+ *
+ *  It is deliberately NOT a toolbar item: yui_toolbar() lays its items in
+ *  a horizontally SCROLLING container, and this is the only control here
+ *  that leaves the view instead of acting on the graph — a way out cannot
+ *  depend on where the toolbar happens to be scrolled. It sits pinned
+ *  ahead of the toolbar, on the same row (see build_ui), like the topics
+ *  view's back button, whose plain non-scrolling strip never moves.
+ ************************************************************/
+function make_back_to_topics(gobj)
+{
+    let back_route = gobj_read_attr(gobj, "back_route") || "";
+    if(!back_route) {
+        return null;
+    }
+
+    let $back = createElement2(
+        ['a', {class: 'GRAPH_BACK_TOPICS button ml-1 mr-1 is-flex-shrink-0',
+               href: back_route,
+               title: t('topics'), 'aria-label': t('topics'),
+               'data-i18n-title': 'topics', 'data-i18n-aria-label': 'topics'}, [
+            ['span', {class: 'icon'}, [['i', {class: 'yi-arrow-left'}]]],
+            ['span', {class: 'is-hidden-mobile', style: 'padding-left:5px;',
+                      i18n: 'topics'}, 'topics']
+        ]]
+    );
+    refresh_language($back, t);
+
+    return $back;
+}
+
+/************************************************************
+ *  True on a phone-width viewport (Bulma's mobile breakpoint).
+ ************************************************************/
+function is_mobile()
+{
+    return typeof window !== "undefined" && window.innerWidth <= 768;
+}
+
+/************************************************************
+ *  Raw-tranger JSON viewer: a C_YUI_JSON driving its own DOM, hosted in a
+ *  moveable C_YUI_WINDOW on desktop / an adaptive modal sheet on mobile. It
+ *  is a helper of THIS view (CHILD model: it publishes EV_EXPAND_PATH back
+ *  to us), single at a time.
+ *
+ *  A treedb's tranger can be enormous, so the first fetch is collapsed
+ *  (print-tranger with lists/dicts limits) and the viewer drills in on
+ *  demand: EV_EXPAND_PATH -> print-tranger path=<path> -> EV_SUBTREE_LOADED.
+ *
+ *  print-tranger must exist on the backend C_NODE service (SDK >= the
+ *  release that added it); against an older backend the command answers
+ *  "command not found" and the viewer shows that error.
+ ************************************************************/
+function open_json_viewer(gobj)
+{
+    let priv = gobj.priv;
+    if(priv.json_win || priv.json_modal) {
+        return;     /*  already open  */
+    }
+    if(gclass_find_by_name("C_YUI_JSON") === null) {
+        log_error(`${gobj_short_name(gobj)}: C_YUI_JSON not registered by the app`);
+        yui_shell_show_error(yui_shell_of(gobj), "raw json viewer unavailable", {t: t});
+        return;
+    }
+
+    let mobile = is_mobile();
+    let shell = yui_shell_of(gobj);
+
+    let jv = gobj_create_service(
+        `treedb-json-${clean_name(gobj_name(gobj))}`,
+        "C_YUI_JSON",
+        {
+            /*  No `title`: the host titles it — the window's title bar on
+             *  desktop, the dialog's header on mobile. The viewer's own
+             *  title would land INSIDE that host, doubling it.  */
+            subscriber: gobj        /*  publishes EV_EXPAND_PATH to us  */
+        },
+        gobj
+    );
+    if(!jv) {
+        log_error(`${gobj_short_name(gobj)}: cannot create the JSON viewer`);
+        return;
+    }
+    priv.json_gobj = jv;
+    gobj_start(jv);
+    let $box = gobj_read_pointer_attr(jv, "$container");
+
+    if(mobile) {
+        if(!shell) {
+            log_error(`${gobj_short_name(gobj)}: no shell, cannot open the JSON sheet`);
+            close_json_viewer(gobj);
+            return;
+        }
+        priv.json_modal = yui_shell_show_modal(shell, $box, {
+            dialog:        true,
+            logical_class: "TREEDB_JSON_SHEET",
+            title_prefix: priv.treedb_name,
+            title:         "raw json",
+            t:             t,
+            on_close: () => {
+                if(gobj_is_destroying(gobj)) {
+                    return;
+                }
+                gobj_send_event(gobj, "EV_JSON_CLOSED", {}, gobj);
+            }
+        });
+    } else {
+        let $win_parent = (shell && yui_shell_popup_layer(shell)) ||
+            (typeof document !== "undefined" && document.getElementById("top-layer")) ||
+            null;
+
+        priv.json_win = gobj_create_service(
+            `treedb-jsonwin-${clean_name(gobj_name(gobj))}`,
+            "C_YUI_WINDOW",
+            {
+                $parent:    $win_parent,
+                subscriber: null,
+                modal:      false,
+                showMax:    true,
+                showFooter: false,
+                resizable:  true,
+                center:     true,
+                auto_save_size_and_position: true,
+                width:      640,
+                height:     620,
+                logical_class: "TREEDB_JSON_WINDOW",
+                title_prefix: priv.treedb_name,
+                title:      "raw json",
+                icon:       "yi-eye",
+                body:       $box,
+                manager:    null,
+                on_close: () => {
+                    if(gobj_is_destroying(gobj)) {
+                        return;
+                    }
+                    gobj_send_event(gobj, "EV_JSON_CLOSED", {}, gobj);
+                }
+            },
+            gobj
+        );
+        if(!priv.json_win) {
+            log_error(`${gobj_short_name(gobj)}: cannot create the JSON window`);
+            close_json_viewer(gobj);
+            return;
+        }
+        gobj_start(priv.json_win);
+    }
+
+    request_print_tranger(gobj, "");    /*  first fetch: whole tranger, collapsed  */
+}
+
+/************************************************************
+ *  Close the JSON viewer (user dismiss / teardown). Destroys the viewer
+ *  gobj and whichever presenter is up, then clears the refs.
+ ************************************************************/
+function close_json_viewer(gobj)
+{
+    let priv = gobj.priv;
+    let jv = priv.json_gobj;
+    let win = priv.json_win;
+    let modal = priv.json_modal;
+
+    priv.json_gobj = null;
+    priv.json_win = null;
+    priv.json_modal = null;
+
+    if(win && is_gobj(win)) {
+        try {
+            /*  STOP, then destroy — same rule as the viewer below: the
+             *  window was STARTED on open, and gobj_destroy() raises the
+             *  `destroying` flag before it can stop a running gobj, so
+             *  destroying it straight logs two errors and skips mt_stop.
+             *  The ✕ path already stopped it (close_window) — guard. */
+            if(gobj_is_running(win)) {
+                gobj_stop(win);
+            }
+            gobj_destroy(win);
+        } catch(e) {
+            log_warning(`${gobj_short_name(gobj)}: already gone: ${e}`);
+        }
+    }
+    if(modal && typeof modal.close === "function") {
+        try {
+            modal.close();
+        } catch(e) {
+            log_warning(`${gobj_short_name(gobj)}: already gone: ${e}`);
+        }
+    }
+    if(jv && is_gobj(jv)) {
+        try {
+            /*  STOP, then destroy — the viewer was STARTED in open_json_viewer.
+             *  gobj_destroy() raises the `destroying` flag before it can stop a
+             *  running gobj, so destroying it straight logs "Destroying a
+             *  RUNNING gobj" + "gobj NULL or DESTROYED" and skips its mt_stop. */
+            gobj_stop(jv);
+            gobj_destroy(jv);
+        } catch(e) {
+            log_warning(`${gobj_short_name(gobj)}: already gone: ${e}`);
+        }
+    }
+}
+
+/************************************************************
+ *  Fetch the treedb's raw tranger (or one subtree when `path` is set) as
+ *  bounded, drillable JSON. Collapsed at 100 so a huge tranger stays a
+ *  small payload of `__collapsed__` stubs the viewer expands on demand.
+ ************************************************************/
+function request_print_tranger(gobj, path)
+{
+    let priv = gobj.priv;
+    if(!priv.gobj_remote_yuno) {
+        log_error(`${gobj_short_name(gobj)}: No gobj_remote_yuno defined`);
+        let jv = priv.json_gobj;
+        if(path && jv && is_gobj(jv) && !gobj_is_destroying(jv)) {
+            gobj_send_event(jv, "EV_SUBTREE_ERROR",
+                {path: path, error: t("no session")}, gobj);
+        }
+        return;
+    }
+    let ret = gobj_command(priv.gobj_remote_yuno, "print-tranger",
+        {
+            service:     priv.treedb_name,
+            expanded:    1,
+            lists_limit: 100,
+            dicts_limit: 100,
+            path:        path || ""
+        }, gobj);
+    if(ret) {
+        log_error(ret);
+    }
+}
+
 /************************************************************
  *  Populate layout dropdown from child's available layouts
  ************************************************************/
@@ -451,7 +754,7 @@ function populate_nodes_tree_options(gobj)
     let $container = priv.$container;
 
     let layout_names = gobj_read_attr(priv.gobj_nodes_tree, "layout_names");
-    let $layout_select = $container.querySelector('.graph_layout');
+    let $layout_select = $container.querySelector('.GRAPH_LAYOUT_SELECT');
     if($layout_select && layout_names) {
         for(let name of layout_names) {
             let option = document.createElement('option');
@@ -467,7 +770,7 @@ function populate_nodes_tree_options(gobj)
     }
 
     // Restore persisted operation_mode selection
-    let $operation_mode_select = $container.querySelector('.graph_operation_mode');
+    let $operation_mode_select = $container.querySelector('.GRAPH_MODE_SELECT');
     $operation_mode_select.value = priv.operation_mode;
 }
 
@@ -507,6 +810,48 @@ function treedb_nodes(gobj, treedb_name, topic_name, options)
     }
 }
 
+/************************************************************
+ *  Command to remote service: re-read ONE node (by id).
+ *
+ *  Used to resync a node whose links changed: the answer is fed to the
+ *  nodes-tree as EV_NODE_UPDATED, whose fkey diff (old vs new refs) is what
+ *  draws or clears the edge. Reusing that path keeps the tree the single
+ *  owner of the edge model — the alternative (deriving the edge here from
+ *  the event's parent/child ids) would duplicate it.
+ ************************************************************/
+function treedb_get_node(gobj, treedb_name, topic_name, node_id)
+{
+    let priv = gobj.priv;
+
+    if(!priv.gobj_remote_yuno) {
+        log_error(`${gobj_short_name(gobj)}: No gobj_remote_yuno defined`);
+        return;
+    }
+
+    let kw = {
+        service: treedb_name,
+        treedb_name: treedb_name,
+        topic_name: topic_name,
+        node_id: node_id,
+        options: {
+            list_dict: true     /*  same shape as the initial `nodes` load  */
+        }
+    };
+
+    kw.__md_command__ = { // Data to be returned
+        topic_name: topic_name,
+    };
+
+    let ret = gobj_command(priv.gobj_remote_yuno,
+        "node",
+        kw,
+        gobj
+    );
+    if(ret) {
+        log_error(ret);
+    }
+}
+
 /************************************************************
  *  Command to remote service
  ************************************************************/
@@ -754,6 +1099,36 @@ function process_treedb_descs(gobj, descs)
         //create_combo(gobj, desc);
         get_nodes(gobj, topic_name);
     }
+
+    /*  Declare per-topic focus sub-routes to the site map (ROUTING.md). */
+    register_sub_routes(gobj);
+}
+
+/************************************************************
+ *  Declare this graph's per-topic focus sub-routes to the site map.
+ *  Route-agnostic except for the host-supplied `base_route`. Cleared
+ *  on stop.
+ ************************************************************/
+function register_sub_routes(gobj)
+{
+    let shell = yui_shell_of(gobj);
+    let base = gobj_read_str_attr(gobj, "base_route");
+    if(!shell || !base) {
+        return;
+    }
+    let descs = gobj_read_attr(gobj, "descs");
+    let system = gobj_read_bool_attr(gobj, "system");
+    let nodes = [];
+    if(descs) {
+        for(const topic of Object.keys(descs)) {
+            if(!system && topic.substring(0, 2) === "__") {
+                continue;
+            }
+            nodes.push({route: base + "/" + topic, label: topic,
+                        icon: "yi-hexagon-nodes", gclass: GCLASS_NAME});
+        }
+    }
+    yui_shell_set_sub_routes(shell, base, nodes);
 }
 
 /************************************************************
@@ -779,6 +1154,43 @@ function get_nodes(gobj, topic_name)
     );
 }
 
+/************************************************************
+ *  EV_TREEDB_NODE_LINKED / EV_TREEDB_NODE_UNLINKED are TREEDB-wide, not
+ *  per-topic: their kw is the RELATIONSHIP
+ *  ({hook_name, parent_topic_name, child_topic_name, parent_id, child_id,
+ *  treedb_name}), with no `topic_name` — so they are subscribed ONCE, and
+ *  filtered by treedb_name alone (a {topic_name} filter would match nothing).
+ *
+ *  NOTE: the backend only publishes them when its C_NODE service is
+ *  configured with `with_link_events` (SDF_RD, default FALSE). Without it,
+ *  a link/unlink is announced the backward-compatible way — an
+ *  EV_TREEDB_NODE_UPDATED of the PARENT — which cannot move an edge here:
+ *  an edge IS a fkey of the CHILD (link-saves-child), and the parent's fkeys
+ *  did not change. That is why an open Graph kept showing stale edges when
+ *  another operator linked two nodes.
+ ************************************************************/
+function subscribe_treedb_links(gobj)
+{
+    let priv = gobj.priv;
+    if(priv._links_subscribed) {
+        return;
+    }
+    priv._links_subscribed = true;
+
+    for(let event of ["EV_TREEDB_NODE_LINKED", "EV_TREEDB_NODE_UNLINKED"]) {
+        gobj_subscribe_event(priv.gobj_remote_yuno,
+            event,
+            {
+                __service__: priv.treedb_name,
+                __filter__: {
+                    "treedb_name": priv.treedb_name
+                }
+            },
+            gobj
+        );
+    }
+}
+
 /************************************************************
  *
  ************************************************************/
@@ -788,6 +1200,8 @@ function subscribe_treedb(gobj, topic_name)
     const gobj_remote_yuno = priv.gobj_remote_yuno;
     const treedb_name = priv.treedb_name;
 
+    subscribe_treedb_links(gobj);
+
     /*
      *  Avoid repetitions of subscribings
      */
@@ -881,6 +1295,34 @@ function unsubscribe_treedb(gobj, topic_name)
         },
         gobj
     );
+
+    /*  The treedb-wide LINKED/UNLINKED subscription rides the per-topic
+     *  ones: when the last topic goes, it goes too — otherwise it outlives
+     *  every view of the treedb and keeps pushing events nobody will use
+     *  (the handler's _topics_subscribed guards make them no-ops, but the
+     *  traffic still crosses the wire).  */
+    let any_left = false;
+    for(let k in priv._topics_subscribed) {
+        if(priv._topics_subscribed[k]) {
+            any_left = true;
+            break;
+        }
+    }
+    if(!any_left && priv._links_subscribed) {
+        priv._links_subscribed = false;
+        for(let ev of ["EV_TREEDB_NODE_LINKED", "EV_TREEDB_NODE_UNLINKED"]) {
+            gobj_unsubscribe_event(gobj_remote_yuno,
+                ev,
+                {
+                    __service__: treedb_name,
+                    __filter__: {
+                        "treedb_name": treedb_name
+                    }
+                },
+                gobj
+            );
+        }
+    }
 }
 
 /********************************************
@@ -935,6 +1377,36 @@ function ac_mt_command_answer(gobj, event, kw, src)
     let command = kw_get_str(gobj, __command__, "command", "", kw_flag_t.KW_REQUIRED);
     let kw_command = kw_get_dict(gobj, __command__, "kw", {}, kw_flag_t.KW_REQUIRED);
 
+    /*
+     *  print-tranger feeds the raw-JSON viewer, correlated by the echoed
+     *  `path`: empty = first whole-tranger fetch (EV_SET_JSON), a set path =
+     *  a lazy drill (EV_SUBTREE_LOADED). Handled before the generic error
+     *  path so a failed drill marks its own branch, not the whole view.
+     */
+    if(command === "print-tranger") {
+        let jv = priv.json_gobj;
+        if(!jv || !is_gobj(jv) || gobj_is_destroying(jv)) {
+            return 0;   /*  viewer closed before its answer landed: benign  */
+        }
+        let path = kw_get_str(gobj, kw_command, "path", "", 0);
+        if(result < 0) {
+            if(path) {
+                gobj_send_event(jv, "EV_SUBTREE_ERROR",
+                    {path: path, error: comment || "print-tranger failed"}, gobj);
+            } else {
+                yui_shell_show_error(yui_shell_of(gobj),
+                    comment || "print-tranger failed", {t: t});
+            }
+            return 0;
+        }
+        if(path) {
+            gobj_send_event(jv, "EV_SUBTREE_LOADED", {path: path, json: data}, gobj);
+        } else {
+            gobj_send_event(jv, "EV_SET_JSON", {json: data}, gobj);
+        }
+        return 0;
+    }
+
     if(result < 0) {
         if(command === "descs") {
             /*  The schema couldn't load (not a treedb, no authz for it, backend
@@ -973,6 +1445,24 @@ function ac_mt_command_answer(gobj, event, kw, src)
             }
             break;
 
+        case "node":
+            if(result >= 0) {
+                /*
+                 *  A node we re-read because its links changed. Feed it as an
+                 *  UPDATE: the tree diffs its fkey refs against the ones it
+                 *  holds and draws / clears exactly the edges that moved.
+                 */
+                gobj_send_event(priv.gobj_nodes_tree,
+                    "EV_NODE_UPDATED",
+                    {
+                        topic_name: kw_get_str(gobj, kw_command, "topic_name", "", 0),
+                        node: data
+                    },
+                    gobj
+                );
+            }
+            break;
+
         case "create-node":
         case "update-node":
         case "delete-node":
@@ -1049,6 +1539,51 @@ function ac_treedb_node_updated(gobj, event, kw, src)
     return 0;
 }
 
+/********************************************
+ *  Remote subscription response: two nodes were LINKED or UNLINKED
+ *  (by us, or by another operator on the same treedb).
+ *
+ *  The kw is the relationship, not a node:
+ *      {hook_name, parent_topic_name, child_topic_name,
+ *       parent_id, child_id, treedb_name}
+ *
+ *  An edge IS a fkey of the CHILD (link-saves-child), so the child is what
+ *  must be resynced — re-read it, and its EV_NODE_UPDATED diff moves the
+ *  edge. The PARENT is re-read too: its hook (the children list it shows,
+ *  and what the hook-data viewer reads) changed in memory even though it was
+ *  never saved.
+ *
+ *  Only topics already loaded in the graph are re-read: a link to a topic
+ *  the user never opened has no node here to update.
+ ********************************************/
+function ac_treedb_node_linked(gobj, event, kw, src)
+{
+    let priv = gobj.priv;
+    let treedb_name = kw_get_str(gobj, kw, "treedb_name", "", 0);
+    let parent_topic_name = kw_get_str(gobj, kw, "parent_topic_name", "", 0);
+    let child_topic_name = kw_get_str(gobj, kw, "child_topic_name", "", 0);
+    let parent_id = kw_get_str(gobj, kw, "parent_id", "", 0);
+    let child_id = kw_get_str(gobj, kw, "child_id", "", 0);
+
+    if(treedb_name !== priv.treedb_name) {
+        log_error("It's not my treedb_name: " + treedb_name);
+        return 0;
+    }
+    if(!child_id || !parent_id) {
+        log_error(`${gobj_short_name(gobj)}: ${event} without parent_id/child_id`);
+        return -1;
+    }
+
+    if(priv._topics_subscribed[child_topic_name]) {
+        treedb_get_node(gobj, treedb_name, child_topic_name, child_id);
+    }
+    if(priv._topics_subscribed[parent_topic_name]) {
+        treedb_get_node(gobj, treedb_name, parent_topic_name, parent_id);
+    }
+
+    return 0;
+}
+
 /********************************************
  *  Remote subscription response
  ********************************************/
@@ -1090,6 +1625,50 @@ function ac_refresh_treedb(gobj, event, kw, src)
     return 0;
 }
 
+/********************************************
+ *  Open the raw-tranger JSON viewer.
+ ********************************************/
+function ac_open_json(gobj, event, kw, src)
+{
+    open_json_viewer(gobj);
+    return 0;
+}
+
+/********************************************
+ *  The viewer asked to load a collapsed subtree: re-issue print-tranger
+ *  for that path. The answer returns through ac_mt_command_answer and is
+ *  fed back as EV_SUBTREE_LOADED / EV_SUBTREE_ERROR.
+ ********************************************/
+function ac_json_expand_path(gobj, event, kw, src)
+{
+    request_print_tranger(gobj, (kw && kw.path) || "");
+    return 0;
+}
+
+/********************************************
+ *  The JSON viewer was dismissed (X / dock / Escape / back), or torn down
+ *  by close_json_viewer(): release the viewer and clear the refs.
+ ********************************************/
+function ac_json_closed(gobj, event, kw, src)
+{
+    let priv = gobj.priv;
+    let jv = priv.json_gobj;
+    priv.json_gobj = null;
+    priv.json_win = null;
+    priv.json_modal = null;
+    if(jv && is_gobj(jv)) {
+        try {
+            /*  STOP before destroy — the viewer was STARTED in open_json_viewer
+             *  (see close_json_viewer for the full rationale). */
+            gobj_stop(jv);
+            gobj_destroy(jv);
+        } catch(e) {
+            log_warning(`${gobj_short_name(gobj)}: already gone: ${e}`);
+        }
+    }
+    return 0;
+}
+
 /********************************************
  *  Event from G6_nodes_tree
  *  kw: {
@@ -1399,7 +1978,7 @@ function ac_set_layout(gobj, event, kw, src)
     gobj_write_str_attr(gobj, "layout", layout);
     gobj_save_persistent_attrs(gobj, "layout");
 
-    let $layout_select = priv.$container.querySelector('.graph_layout');
+    let $layout_select = priv.$container.querySelector('.GRAPH_LAYOUT_SELECT');
     $layout_select.value = priv.layout;
 
     gobj_send_event(
@@ -1425,7 +2004,7 @@ function ac_set_operation_mode(gobj, event, kw, src)
     gobj_write_str_attr(gobj, "operation_mode", operation_mode);
     gobj_save_persistent_attrs(gobj, "operation_mode");
 
-    let $operation_mode_select = priv.$container.querySelector('.graph_operation_mode');
+    let $operation_mode_select = priv.$container.querySelector('.GRAPH_MODE_SELECT');
     $operation_mode_select.value = priv.operation_mode;
 
     gobj_send_event(
@@ -1448,6 +2027,26 @@ function ac_set_operation_mode(gobj, event, kw, src)
     return 0;
 }
 
+/************************************************************
+ *  Focus the graph on a topic (a topic card's graph icon, or a
+ *  `.../graphs/db/<sel>/<topic>` deep link): forward it to the G6
+ *  tree, which centres + highlights that topic's nodes (deferring
+ *  until its data is loaded).
+ ************************************************************/
+function ac_set_focus_topic(gobj, event, kw, src)
+{
+    let priv = gobj.priv;
+    if(priv.gobj_nodes_tree) {
+        gobj_send_event(
+            priv.gobj_nodes_tree,
+            "EV_FOCUS_TOPIC",
+            {topic: kw && kw.topic},
+            gobj
+        );
+    }
+    return 0;
+}
+
 /************************************************************
  *  Parent (routing) inform us that we go showing
  *
@@ -1473,15 +2072,6 @@ function ac_hide(gobj, event, kw, src)
     return gobj_send_event(priv.gobj_nodes_tree, event, kw, gobj);
 }
 
-/************************************************************
- *  we are subscribed to EV_RESIZE from __yui_main__
- ************************************************************/
-function ac_resize(gobj, event, kw, src)
-{
-    let priv = gobj.priv;
-    return gobj_send_event(priv.gobj_nodes_tree, event, kw, gobj);
-}
-
 
 
 
@@ -1522,7 +2112,12 @@ function create_gclass(gclass_name)
             ["EV_TREEDB_NODE_CREATED",      ac_treedb_node_created,     null],
             ["EV_TREEDB_NODE_UPDATED",      ac_treedb_node_updated,     null],
             ["EV_TREEDB_NODE_DELETED",      ac_treedb_node_deleted,     null],
+            ["EV_TREEDB_NODE_LINKED",       ac_treedb_node_linked,      null],
+            ["EV_TREEDB_NODE_UNLINKED",     ac_treedb_node_linked,      null],
             ["EV_REFRESH_TREEDB",           ac_refresh_treedb,          null],
+            ["EV_OPEN_JSON",                ac_open_json,               null],
+            ["EV_EXPAND_PATH",              ac_json_expand_path,        null],
+            ["EV_JSON_CLOSED",              ac_json_closed,             null],
             ["EV_SHOW_HOOK_DATA",           ac_show_hook_data,          null],
             ["EV_SHOW_TREEDB_TOPIC",        ac_show_treedb_topic,       null],
             ["EV_VERTEX_CLICKED",           ac_vertex_clicked,          null],
@@ -1536,9 +2131,10 @@ function create_gclass(gclass_name)
             ["EV_CLOSE_WINDOW",             ac_close_window,            null],
             ["EV_SET_LAYOUT",               ac_set_layout,              null],
             ["EV_SET_OPERATION_MODE",       ac_set_operation_mode,      null],
+            ["EV_SET_FOCUS_TOPIC",          ac_set_focus_topic,         null],
             ["EV_SHOW",                     ac_show,                    null],
             ["EV_HIDE",                     ac_hide,                    null],
-            ["EV_RESIZE",                   ac_resize,                  null],
+            ["EV_TRANSPORT_STATE",          ac_transport_state,         null],
         ]]
     ];
 
@@ -1550,7 +2146,12 @@ function create_gclass(gclass_name)
         ["EV_TREEDB_NODE_CREATED",      event_flag_t.EVF_PUBLIC_EVENT],
         ["EV_TREEDB_NODE_UPDATED",      event_flag_t.EVF_PUBLIC_EVENT],
         ["EV_TREEDB_NODE_DELETED",      event_flag_t.EVF_PUBLIC_EVENT],
+        ["EV_TREEDB_NODE_LINKED",       event_flag_t.EVF_PUBLIC_EVENT],
+        ["EV_TREEDB_NODE_UNLINKED",     event_flag_t.EVF_PUBLIC_EVENT],
         ["EV_REFRESH_TREEDB",           0],
+        ["EV_OPEN_JSON",                0],
+        ["EV_EXPAND_PATH",              0],
+        ["EV_JSON_CLOSED",              0],
         ["EV_SHOW_HOOK_DATA",           0],
         ["EV_SHOW_TREEDB_TOPIC",        0],
         ["EV_VERTEX_CLICKED",           0],
@@ -1564,11 +2165,12 @@ function create_gclass(gclass_name)
         ["EV_CLOSE_WINDOW",             0],
         ["EV_SET_LAYOUT",               0],
         ["EV_SET_OPERATION_MODE",       0],
+        ["EV_SET_FOCUS_TOPIC",          0],
         ["EV_OPERATION_MODE_CHANGED",
             event_flag_t.EVF_OUTPUT_EVENT | event_flag_t.EVF_NO_WARN_SUBS],
         ["EV_SHOW",                     0],
         ["EV_HIDE",                     0],
-        ["EV_RESIZE",                   0],
+        ["EV_TRANSPORT_STATE",          0],
     ];
 
     /*----------------------------------------*