@yuneta/gobj-ui 7.23.141 → 7.23.142

package/README.md

@@ -1294,8 +1294,8 @@ a level or two, with a count on every cut.
   parent shows it or it is a shown root — the **union**, so a device that hangs
   from its place AND its controller is drawn once, under whichever opened
   first, and folding one of the two leaves it where the other shows it.
-- **`expand_depth`** (default `2`) is how much opens on load: the roots and
-  their children. **`fold_page_size`** (default `24`) is how many children of
+- **`expand_depth`** (default `1` since `7.23.142`, `2` before) is how much
+  opens on load until the reader steps: the roots alone. **`fold_page_size`** (default `24`) is how many children of
   one hook are shown at a time; the rest is a **`+N` chip** at the end of the
   page that opens the next one. Both are attrs of `C_YUI_TREEDB_GRAPH`,
   forwarded to the engine — and since `7.23.93` so are the seven the engine
@@ -1596,18 +1596,31 @@ them:
 | control | what it does |
 |---|---|
 | the chip body | **show / hide** the topic. A hidden topic leaves the MODEL, not just the drawing: no card, no pill counts it, no edge reaches it, and whatever hung from it alone has no parent any more. The name is struck through and the count is the total. |
-| `★` / `☆` | the **main topic**: the trunk the tree hangs from. Filled on the main one (a mark, not a button — the main topic cannot be hidden, because hiding the trunk turns everything into roots, which is the pile); hollow on the others, where it moves the star. |
+| `★` / `☆` | the **main topic**: the trunk the tree hangs from, always a **hierarchical** topic (hooked to itself); the hollow star appears only on the other hierarchical topics, and only when there are two or more (`7.23.142`). Filled on the main one (a mark, not a button — the main topic cannot be hidden, because hiding the trunk turns everything into roots, which is the pile); hollow on the others, where it moves the star. |
 | `+N` | the topic's **loose records**: the ones that should hang from the main tree and do not (a device with no place). Counted here, shown only on request. |
 | `⌖` | **highlight** the topic — the focus, with `reveal: "all"`. |
 
-The **main topic is deduced** when none is chosen: the topic whose hooks reach
-the most OTHER topics, a self-referent hook breaking a tie (a tree of places
-over a flat list of groups). On the yunovatios central that is `places` (it
-reaches places, devices, users and controllers); `device_types` reaches one.
-An `extended` topic (hooks, no fkeys) never wins: the engine draws no edge
-from one, so its records hang nothing. A treedb where no topic reaches
-another has no trunk, and every topic is a tree of its own — the behaviour
-before this existed.
+**Only a HIERARCHICAL topic can be the main one** (since `7.23.142`): a topic
+hooked to ITSELF — places inside places, groups inside groups, roles inside
+roles (`fold_is_hierarchical()`). A topic that only reaches OTHER topics is a
+list with children, and the old rule (*the topic whose hooks reach the most
+others*) drew the agent's treedb from `yunos` instead of `realms`. In order:
+
+1. the reader's pick (the star), if it is hierarchical — a saved pick the rule
+   refuses is ignored;
+2. the topic the schema **marks**, `main_topic: true` on the topic, sent in the
+   desc by SDK 7.19+ (`tranger2_topic_desc()`); the schema allows one, and only
+   on a topic hooked to itself;
+3. the hierarchical topic that reaches the most other topics, schema order
+   breaking a tie.
+
+In every treedb of the SDK and the apps there is exactly one hierarchical
+topic (`places`, `device_groups`, `systems`, `roles`, `realms`), so the mark
+only has something to decide once a schema grows a second one. A treedb with
+no topic hooked to itself has no trunk, and every topic is a tree of its own.
+
+(Not the engine's card tier: a topic with hooks AND fkeys is an `entity` card
+— it was called `hierarchical` until `7.23.142` — and that only sizes a card.)
 
 What the main topic governs, in `treedb_fold_model.js`:
 

package/dist/gobj-ui.cjs.js

@@ -27675,7 +27675,9 @@ function fold_build_model(descs, records, opts) {
 	opts = (0, _yuneta_gobj_js.is_object)(opts) ? opts : {};
 	let hidden = new Set((0, _yuneta_gobj_js.is_array)(opts.hidden_topics) ? opts.hidden_topics : []);
 	let loose_shown = new Set((0, _yuneta_gobj_js.is_array)(opts.loose_topics) ? opts.loose_topics : []);
-	let main_topic = opts.main_topic || fold_main_topic(descs);
+	let main_topic = opts.main_topic || "";
+	if (main_topic && !fold_is_hierarchical(descs, main_topic)) main_topic = "";
+	if (!main_topic) main_topic = fold_main_topic(descs);
 	if (main_topic && (!descs[main_topic] || hidden.has(main_topic))) main_topic = "";
 	let linked = fold_linked_topics(descs, main_topic);
 	let totals = {};
@@ -27796,28 +27798,49 @@ function count_levels(model) {
 	model.levels = deepest;
 }
 /************************************************************
-*  The topic the schema hangs the others from: the one whose hooks
-*  reach the most OTHER topics, a self-referent hook breaking a tie
-*  (a tree of places over a flat list of groups), schema order
-*  breaking the rest. "" when no topic reaches another -- a treedb of
-*  unrelated lists has no trunk, and every topic is a tree of its own.
+*  A HIERARCHICAL topic: one hooked to ITSELF -- places inside
+*  places, groups inside groups, roles inside roles. It is the
+*  only kind of topic a tree can hang from: a topic that only
+*  reaches OTHER topics is a list with children, and making it
+*  the trunk drew the agent's treedb from `yunos` instead of
+*  `realms`.
+*
+*  (Not the engine's `entity` tier, which is any topic with
+*  hooks AND fkeys: that one sizes a card and says nothing about
+*  where a tree starts.)
+************************************************************/
+function fold_is_hierarchical(descs, topic_name) {
+	if (!(0, _yuneta_gobj_js.is_object)(descs) || !descs[topic_name]) return false;
+	return hook_targets(descs, topic_name).has(topic_name);
+}
+/************************************************************
+*  The topic the tree hangs from. Only a HIERARCHICAL topic can
+*  be it, and in this order:
+*
+*      the one the schema MARKS (`main_topic: true` on the topic,
+*      sent by the backend in its desc since SDK 7.19; the first
+*      one in schema order if a schema marks two);
+*      else the one whose hooks reach the most OTHER topics,
+*      schema order breaking a tie.
+*
+*  "" when no topic is hooked to itself: there is no trunk, and
+*  every topic is a tree of its own. (A pick by the reader comes
+*  first of all, and is fold_build_model's business.)
 ************************************************************/
 function fold_main_topic(descs) {
 	descs = (0, _yuneta_gobj_js.is_object)(descs) ? descs : {};
+	let candidates = Object.keys(descs).filter((topic_name) => {
+		return topic_name.substring(0, 2) !== "__" && fold_is_hierarchical(descs, topic_name);
+	});
+	for (let topic_name of candidates) if (descs[topic_name].main_topic === true) return topic_name;
 	let best = "";
-	let best_score = 0;
-	let best_self = false;
-	for (let topic_name of Object.keys(descs)) {
-		if (topic_name.substring(0, 2) === "__") continue;
+	let best_score = -1;
+	for (let topic_name of candidates) {
 		let reach = hook_targets(descs, topic_name);
-		let self = reach.has(topic_name);
 		reach.delete(topic_name);
-		let score = reach.size;
-		if (score === 0) continue;
-		if (score > best_score || score === best_score && self && !best_self) {
+		if (reach.size > best_score) {
 			best = topic_name;
-			best_score = score;
-			best_self = self;
+			best_score = reach.size;
 		}
 	}
 	return best;
@@ -55303,13 +55326,13 @@ var NODE_MODES$1 = [
 	"shape"
 ];
 var PILL_SIZE = {
-	hierarchical: [200, 30],
+	entity: [200, 30],
 	extended: [180, 28],
 	child: [160, 26]
 };
 var PORT_R_PILL = 6;
 var SHAPE_SIZE = {
-	hierarchical: 32,
+	entity: 32,
 	extended: 28,
 	child: 22
 };
@@ -55397,7 +55420,7 @@ var attrs_table$4 = [
 	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.data_type_t.DTP_LIST, "layout_names", _yuneta_gobj_js.sdata_flag_t.SDF_RD, JSON.stringify(Object.keys(_layouts)), "Available layout names (read-only, for parent to query)"),
 	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.data_type_t.DTP_STRING, "hook_port_position", 0, "bottom", "Hook port position"),
 	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.data_type_t.DTP_STRING, "fkey_port_position", 0, "top", "Fkey port position"),
-	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.data_type_t.DTP_INTEGER, "expand_depth", 0, 2, "Levels open when a treedb loads, until the reader steps (`fold_level`): 1 = the roots alone, 2 = the roots and their children. Every open hook shows its first page"),
+	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.data_type_t.DTP_INTEGER, "expand_depth", 0, 1, "Levels open when a treedb loads, until the reader steps (`fold_level`): 1 = the roots alone (the default), 2 = the roots and their children. Every open hook shows its first page"),
 	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.data_type_t.DTP_INTEGER, "fold_level", 0, 0, "The level of the MAIN tree the toolbar's stepper stands on: 1 = its roots, N = N-1 levels under them; 0 = `expand_depth`. The host persists it and sends EV_SET_FOLD_LEVEL; it is published back in EV_LEGEND_STATE (`fold`) with the levels the tree has"),
 	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.data_type_t.DTP_INTEGER, "fold_page_size", 0, 24, "Children of one hook shown per page; the `+N` chip after the page opens the next one"),
 	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.data_type_t.DTP_LIST, "hidden_topics", 0, "[]", "Topics left out of the tree: no card, no pill counts them, no edge reaches them"),
@@ -55489,7 +55512,7 @@ var PRIVATE_DATA$4 = {
 	_layout_asked: "",
 	_nodes_total: 0,
 	_nodes_placed: 0,
-	expand_depth: 2,
+	expand_depth: 1,
 	fold_level: 0,
 	fold_page_size: 24,
 	hidden_topics: null,
@@ -56213,7 +56236,12 @@ function configure_behaviour(gobj) {
 	graph_write_behaviors(gobj, behaviors);
 }
 /************************************************************
-*  Count hooks and fkeys in topic desc, classify node type
+*  Count hooks and fkeys in topic desc, classify node type:
+*  `child` (no hooks), `extended` (hooks, no fkeys), `entity`
+*  (both). It sizes the card and nothing else. It used to be
+*  called `hierarchical`, and that word means something else now:
+*  a topic hooked to ITSELF, the only kind a tree can hang from
+*  (treedb_fold_model).
 ************************************************************/
 function calculate_hooks_fkeys_counter(desc) {
 	let cols = desc.cols;
@@ -56230,7 +56258,7 @@ function calculate_hooks_fkeys_counter(desc) {
 	}
 	if (desc.hooks_counter === 0) desc.node_treedb_type = "child";
 	else if (desc.fkeys_counter === 0) desc.node_treedb_type = "extended";
-	else desc.node_treedb_type = "hierarchical";
+	else desc.node_treedb_type = "entity";
 }
 /************************************************************
 *  Build ports for a topic desc
@@ -56603,7 +56631,7 @@ function dress_ports(gobj, style, ports, geometry, topic_defaults, r_default, fi
 ************************************************************/
 function pill_shape_of(gobj, desc, record, geometry) {
 	let priv = gobj.priv;
-	let size = PILL_SIZE[desc.node_treedb_type] || PILL_SIZE.hierarchical;
+	let size = PILL_SIZE[desc.node_treedb_type] || PILL_SIZE.entity;
 	let ports = build_ports(gobj, desc);
 	let paint = node_paint_of(gobj, desc, geometry);
 	let style = {
@@ -56652,7 +56680,7 @@ function figure_shape_of(gobj, desc, record, geometry, flags) {
 	let dark = priv.theme === "dark";
 	let f = flags || {};
 	let tier = desc.node_treedb_type;
-	let side = SHAPE_SIZE[tier] || SHAPE_SIZE.hierarchical;
+	let side = SHAPE_SIZE[tier] || SHAPE_SIZE.entity;
 	let labels = (0, _yuneta_gobj_js.gobj_read_bool_attr)(gobj, "node_labels");
 	let figure = node_figure_of(gobj, desc, geometry || {});
 	let paint = node_paint_of(gobj, desc, geometry);
@@ -59718,7 +59746,7 @@ function show_node_detail_popover(gobj, node_id) {
 	clamp_popover_position(gobj, popover);
 }
 /************************************************************
-*  Re-render every HTML (hierarchical) node so its card adopts
+*  Re-render every HTML (entity) node so its card adopts
 *  the given theme: entity cards and leaf chips (baked innerHTML,
 *  not re-themed by setTheme()) are regenerated; structural
 *  junction diamonds get their neutral fill/stroke re-themed.
@@ -59837,7 +59865,7 @@ function refresh_minimap(gobj) {
 }
 /************************************************************
 *  The innerHTML of ONE node, in the given theme and highlight state.
-*  The three treedb tiers (hierarchical / extended / child) each have
+*  The three treedb tiers (entity / extended / child) each have
 *  their own card, and both the theme refresh and the highlight need the
 *  same three-way choice — it lived inline in the theme refresh and is
 *  shared now. Returns null for a node that carries no desc.
@@ -59854,7 +59882,7 @@ function node_innerHTML_of(nd, theme, highlight, selected, anchored, pills_html)
 	switch (desc.node_treedb_type) {
 		case "child": return build_chip_innerHTML(fill, theme, record.icon, label, record.id, highlight, selected, anchored);
 		case "extended": return build_node_innerHTML(fill, theme, record.icon, label, desc.topic_name, true, record.id, highlight, selected, anchored, pills_html);
-		case "hierarchical": return build_node_innerHTML(fill, theme, record.icon, label, desc.topic_name, false, record.id, highlight, selected, anchored, pills_html);
+		case "entity": return build_node_innerHTML(fill, theme, record.icon, label, desc.topic_name, false, record.id, highlight, selected, anchored, pills_html);
 	}
 	return null;
 }
@@ -60051,7 +60079,7 @@ function build_chip_innerHTML(color, theme, icon, label, key, highlight, selecte
 `;
 }
 /************************************************************
-*  Build innerHTML for hierarchical (HTML) nodes.
+*  Build innerHTML for entity (HTML) nodes.
 *
 *  Card style modelled on the documentation schema graphs
 *  (docs gen_treedb_graphs.py): rounded card, soft tint of the
@@ -61369,12 +61397,13 @@ function publish_legend_state(gobj, visible) {
 			loose: loose.length,
 			loose_shown: model.loose_shown.has(topic_name),
 			hidden: model.hidden.has(topic_name),
-			linked: model.linked.has(topic_name)
+			linked: model.linked.has(topic_name),
+			hierarchical: fold_is_hierarchical(priv.descs, topic_name)
 		});
 	}
 	(0, _yuneta_gobj_js.gobj_publish_event)(gobj, "EV_LEGEND_STATE", {
 		main_topic: model.main_topic,
-		main_chosen: !!(0, _yuneta_gobj_js.gobj_read_str_attr)(gobj, "main_topic"),
+		main_chosen: !!model.main_topic && (0, _yuneta_gobj_js.gobj_read_str_attr)(gobj, "main_topic") === model.main_topic,
 		topics,
 		fold: {
 			topic: model.main_topic,
@@ -62950,7 +62979,7 @@ var attrs_table$3 = [
 	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.data_type_t.DTP_POINTER, "subscriber", 0, null, "Subscriber of output events"),
 	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.data_type_t.DTP_LIST, "operation_modes", 0, "[\"reading\", \"operation\", \"writing\", \"edition\"]", "Available **permission** or behaviour modes. These operation modes are required to be accomplish by the graph handler (G6 child). TODO permissions must match treedb permissions."),
 	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.data_type_t.DTP_BOOLEAN, "with_treedb_tables", 0, false, "Include treedb tables"),
-	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.data_type_t.DTP_INTEGER, "expand_depth", 0, 2, "Levels of the treedb open when it loads: 1 = the roots alone, 2 = the roots and their children. Forwarded to the G6 child"),
+	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.data_type_t.DTP_INTEGER, "expand_depth", 0, 1, "Levels of the treedb open when it loads, until the reader steps (`fold_level`): 1 = the roots alone (the default), 2 = the roots and their children. Forwarded to the G6 child"),
 	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.data_type_t.DTP_INTEGER, "fold_page_size", 0, 24, "Children of one hook shown per page in the graph; a `+N` chip opens the next page. Forwarded to the G6 child"),
 	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.data_type_t.DTP_INTEGER, "minimap_min_nodes", 0, 30, "Show the minimap from this many nodes on (0 = never). Forwarded to the G6 child"),
 	(0, _yuneta_gobj_js.SDATA)(_yuneta_gobj_js.data_type_t.DTP_BOOLEAN, "with_gridline", 0, true, "Draw the grid under the graph. Forwarded to the G6 child"),
@@ -64601,6 +64630,7 @@ function refresh_legend(gobj) {
 	let topics = state.topics.slice().sort((a, b) => {
 		return String(a.topic).localeCompare(String(b.topic));
 	});
+	let hierarchical_count = topics.filter((e) => e.hierarchical && !e.hidden).length;
 	for (let entry of topics) {
 		let topic_name = entry.topic;
 		let is_main = topic_name === state.main_topic;
@@ -64695,7 +64725,7 @@ function refresh_legend(gobj) {
 				"★"
 			]]
 		]);
-		else if (!hidden) extras.push([
+		else if (!hidden && entry.hierarchical && hierarchical_count > 1) extras.push([
 			"button",
 			{
 				class: "GRAPH_LEGEND_STAR button",
@@ -66044,7 +66074,7 @@ function sort_by_order(list) {
 *              schema_version, c_schema_version, system_schema_version,
 *              topics: [{
 *                  id, name, order, record,
-*                  pkey, topic_version, system_topic,
+*                  pkey, topic_version, system_topic, main_topic,
 *                  cols: [{id, name, order, record}]
 *              }]
 *          }],
@@ -66093,6 +66123,7 @@ function build_schema_model(records) {
 			tkey: record.tkey || "",
 			topic_version: record.topic_version,
 			system_topic: !!record.system_topic,
+			main_topic: !!record.main_topic,
 			cols: []
 		};
 		by_topic_id[entry.id] = entry;
@@ -66389,6 +66420,12 @@ function validate_schema(treedb, options) {
 			if (is_fkey && FKEY_TYPES.indexOf(type) < 0) add("error", "fkey has a bad type", topic.name, col.name, type);
 		}
 	}
+	let marked = treedb.topics.filter((topic) => topic.main_topic);
+	if (marked.length > 1) add("error", "more than one main topic", marked[1].name, "", marked.map((topic) => topic.name).join(", "));
+	for (let topic of marked) if (!topic.cols.some((col) => {
+		let hook = col_hook(col.record);
+		return col_flags(col.record).indexOf("hook") >= 0 && !!hook && Object.prototype.hasOwnProperty.call(hook, topic.name);
+	})) add("error", "main topic not hooked to itself", topic.name, "", "");
 	let hooked = {};
 	for (let topic of treedb.topics) for (let col of topic.cols) {
 		let hook = col_hook(col.record);
@@ -66580,7 +66617,8 @@ var TOPIC_KEY_ORDER = [
 	"system_flag",
 	"tkey",
 	"topic_version",
-	"system_topic"
+	"system_topic",
+	"main_topic"
 ];
 var COL_KEY_ORDER = [
 	"header",
@@ -66838,7 +66876,8 @@ var TOPIC_FIELDS = [
 	"system_flag",
 	"tkey",
 	"topic_version",
-	"system_topic"
+	"system_topic",
+	"main_topic"
 ];
 var COL_FIELDS = [
 	"header",
@@ -68455,6 +68494,20 @@ function render_topics(gobj, $body) {
 							{},
 							""
 						],
+						topic.main_topic ? [
+							"span",
+							{
+								class: "SCHEMA_TOPIC_MAIN ml-2",
+								style: "color:#d4a017;",
+								title: (0, i18next.t)("main topic"),
+								"data-i18n-title": "main topic"
+							},
+							"★"
+						] : [
+							"span",
+							{},
+							""
+						],
 						ambiguous ? [
 							"div",
 							{ class: "SCHEMA_TOPIC_ID is-size-7 yui-text-quiet" },
@@ -69449,6 +69502,26 @@ function open_topic_form(gobj, treedb, topic) {
 					]]
 				]]
 			],
+			[
+				"div",
+				{ class: "SCHEMA_TOPIC_FORM_MAIN field mb-3" },
+				[[
+					"label",
+					{ class: "checkbox" },
+					[["input", el_attrs({
+						type: "checkbox",
+						"data-name": "main_topic",
+						checked: record.main_topic ? "checked" : void 0
+					})], [
+						"span",
+						{
+							class: "ml-1",
+							i18n: "main topic"
+						},
+						(0, i18next.t)("main topic")
+					]]
+				]]
+			],
 			[
 				"div",
 				{
@@ -70241,6 +70314,7 @@ function topic_record(gobj, treedb, topic, values) {
 	record.tkey = values.tkey || "";
 	record.topic_version = values.topic_version === "" ? 1 : Number(values.topic_version);
 	record.system_topic = !!values.system_topic;
+	record.main_topic = !!values.main_topic;
 	return record;
 }
 /***************************

package/dist/gobj-ui.es.js

@@ -27670,7 +27670,9 @@ function fold_build_model(descs, records, opts) {
 	opts = is_object(opts) ? opts : {};
 	let hidden = new Set(is_array(opts.hidden_topics) ? opts.hidden_topics : []);
 	let loose_shown = new Set(is_array(opts.loose_topics) ? opts.loose_topics : []);
-	let main_topic = opts.main_topic || fold_main_topic(descs);
+	let main_topic = opts.main_topic || "";
+	if (main_topic && !fold_is_hierarchical(descs, main_topic)) main_topic = "";
+	if (!main_topic) main_topic = fold_main_topic(descs);
 	if (main_topic && (!descs[main_topic] || hidden.has(main_topic))) main_topic = "";
 	let linked = fold_linked_topics(descs, main_topic);
 	let totals = {};
@@ -27791,28 +27793,49 @@ function count_levels(model) {
 	model.levels = deepest;
 }
 /************************************************************
-*  The topic the schema hangs the others from: the one whose hooks
-*  reach the most OTHER topics, a self-referent hook breaking a tie
-*  (a tree of places over a flat list of groups), schema order
-*  breaking the rest. "" when no topic reaches another -- a treedb of
-*  unrelated lists has no trunk, and every topic is a tree of its own.
+*  A HIERARCHICAL topic: one hooked to ITSELF -- places inside
+*  places, groups inside groups, roles inside roles. It is the
+*  only kind of topic a tree can hang from: a topic that only
+*  reaches OTHER topics is a list with children, and making it
+*  the trunk drew the agent's treedb from `yunos` instead of
+*  `realms`.
+*
+*  (Not the engine's `entity` tier, which is any topic with
+*  hooks AND fkeys: that one sizes a card and says nothing about
+*  where a tree starts.)
+************************************************************/
+function fold_is_hierarchical(descs, topic_name) {
+	if (!is_object(descs) || !descs[topic_name]) return false;
+	return hook_targets(descs, topic_name).has(topic_name);
+}
+/************************************************************
+*  The topic the tree hangs from. Only a HIERARCHICAL topic can
+*  be it, and in this order:
+*
+*      the one the schema MARKS (`main_topic: true` on the topic,
+*      sent by the backend in its desc since SDK 7.19; the first
+*      one in schema order if a schema marks two);
+*      else the one whose hooks reach the most OTHER topics,
+*      schema order breaking a tie.
+*
+*  "" when no topic is hooked to itself: there is no trunk, and
+*  every topic is a tree of its own. (A pick by the reader comes
+*  first of all, and is fold_build_model's business.)
 ************************************************************/
 function fold_main_topic(descs) {
 	descs = is_object(descs) ? descs : {};
+	let candidates = Object.keys(descs).filter((topic_name) => {
+		return topic_name.substring(0, 2) !== "__" && fold_is_hierarchical(descs, topic_name);
+	});
+	for (let topic_name of candidates) if (descs[topic_name].main_topic === true) return topic_name;
 	let best = "";
-	let best_score = 0;
-	let best_self = false;
-	for (let topic_name of Object.keys(descs)) {
-		if (topic_name.substring(0, 2) === "__") continue;
+	let best_score = -1;
+	for (let topic_name of candidates) {
 		let reach = hook_targets(descs, topic_name);
-		let self = reach.has(topic_name);
 		reach.delete(topic_name);
-		let score = reach.size;
-		if (score === 0) continue;
-		if (score > best_score || score === best_score && self && !best_self) {
+		if (reach.size > best_score) {
 			best = topic_name;
-			best_score = score;
-			best_self = self;
+			best_score = reach.size;
 		}
 	}
 	return best;
@@ -55298,13 +55321,13 @@ var NODE_MODES$1 = [
 	"shape"
 ];
 var PILL_SIZE = {
-	hierarchical: [200, 30],
+	entity: [200, 30],
 	extended: [180, 28],
 	child: [160, 26]
 };
 var PORT_R_PILL = 6;
 var SHAPE_SIZE = {
-	hierarchical: 32,
+	entity: 32,
 	extended: 28,
 	child: 22
 };
@@ -55392,7 +55415,7 @@ var attrs_table$4 = [
 	SDATA(data_type_t.DTP_LIST, "layout_names", sdata_flag_t.SDF_RD, JSON.stringify(Object.keys(_layouts)), "Available layout names (read-only, for parent to query)"),
 	SDATA(data_type_t.DTP_STRING, "hook_port_position", 0, "bottom", "Hook port position"),
 	SDATA(data_type_t.DTP_STRING, "fkey_port_position", 0, "top", "Fkey port position"),
-	SDATA(data_type_t.DTP_INTEGER, "expand_depth", 0, 2, "Levels open when a treedb loads, until the reader steps (`fold_level`): 1 = the roots alone, 2 = the roots and their children. Every open hook shows its first page"),
+	SDATA(data_type_t.DTP_INTEGER, "expand_depth", 0, 1, "Levels open when a treedb loads, until the reader steps (`fold_level`): 1 = the roots alone (the default), 2 = the roots and their children. Every open hook shows its first page"),
 	SDATA(data_type_t.DTP_INTEGER, "fold_level", 0, 0, "The level of the MAIN tree the toolbar's stepper stands on: 1 = its roots, N = N-1 levels under them; 0 = `expand_depth`. The host persists it and sends EV_SET_FOLD_LEVEL; it is published back in EV_LEGEND_STATE (`fold`) with the levels the tree has"),
 	SDATA(data_type_t.DTP_INTEGER, "fold_page_size", 0, 24, "Children of one hook shown per page; the `+N` chip after the page opens the next one"),
 	SDATA(data_type_t.DTP_LIST, "hidden_topics", 0, "[]", "Topics left out of the tree: no card, no pill counts them, no edge reaches them"),
@@ -55484,7 +55507,7 @@ var PRIVATE_DATA$4 = {
 	_layout_asked: "",
 	_nodes_total: 0,
 	_nodes_placed: 0,
-	expand_depth: 2,
+	expand_depth: 1,
 	fold_level: 0,
 	fold_page_size: 24,
 	hidden_topics: null,
@@ -56208,7 +56231,12 @@ function configure_behaviour(gobj) {
 	graph_write_behaviors(gobj, behaviors);
 }
 /************************************************************
-*  Count hooks and fkeys in topic desc, classify node type
+*  Count hooks and fkeys in topic desc, classify node type:
+*  `child` (no hooks), `extended` (hooks, no fkeys), `entity`
+*  (both). It sizes the card and nothing else. It used to be
+*  called `hierarchical`, and that word means something else now:
+*  a topic hooked to ITSELF, the only kind a tree can hang from
+*  (treedb_fold_model).
 ************************************************************/
 function calculate_hooks_fkeys_counter(desc) {
 	let cols = desc.cols;
@@ -56225,7 +56253,7 @@ function calculate_hooks_fkeys_counter(desc) {
 	}
 	if (desc.hooks_counter === 0) desc.node_treedb_type = "child";
 	else if (desc.fkeys_counter === 0) desc.node_treedb_type = "extended";
-	else desc.node_treedb_type = "hierarchical";
+	else desc.node_treedb_type = "entity";
 }
 /************************************************************
 *  Build ports for a topic desc
@@ -56598,7 +56626,7 @@ function dress_ports(gobj, style, ports, geometry, topic_defaults, r_default, fi
 ************************************************************/
 function pill_shape_of(gobj, desc, record, geometry) {
 	let priv = gobj.priv;
-	let size = PILL_SIZE[desc.node_treedb_type] || PILL_SIZE.hierarchical;
+	let size = PILL_SIZE[desc.node_treedb_type] || PILL_SIZE.entity;
 	let ports = build_ports(gobj, desc);
 	let paint = node_paint_of(gobj, desc, geometry);
 	let style = {
@@ -56647,7 +56675,7 @@ function figure_shape_of(gobj, desc, record, geometry, flags) {
 	let dark = priv.theme === "dark";
 	let f = flags || {};
 	let tier = desc.node_treedb_type;
-	let side = SHAPE_SIZE[tier] || SHAPE_SIZE.hierarchical;
+	let side = SHAPE_SIZE[tier] || SHAPE_SIZE.entity;
 	let labels = gobj_read_bool_attr(gobj, "node_labels");
 	let figure = node_figure_of(gobj, desc, geometry || {});
 	let paint = node_paint_of(gobj, desc, geometry);
@@ -59713,7 +59741,7 @@ function show_node_detail_popover(gobj, node_id) {
 	clamp_popover_position(gobj, popover);
 }
 /************************************************************
-*  Re-render every HTML (hierarchical) node so its card adopts
+*  Re-render every HTML (entity) node so its card adopts
 *  the given theme: entity cards and leaf chips (baked innerHTML,
 *  not re-themed by setTheme()) are regenerated; structural
 *  junction diamonds get their neutral fill/stroke re-themed.
@@ -59832,7 +59860,7 @@ function refresh_minimap(gobj) {
 }
 /************************************************************
 *  The innerHTML of ONE node, in the given theme and highlight state.
-*  The three treedb tiers (hierarchical / extended / child) each have
+*  The three treedb tiers (entity / extended / child) each have
 *  their own card, and both the theme refresh and the highlight need the
 *  same three-way choice — it lived inline in the theme refresh and is
 *  shared now. Returns null for a node that carries no desc.
@@ -59849,7 +59877,7 @@ function node_innerHTML_of(nd, theme, highlight, selected, anchored, pills_html)
 	switch (desc.node_treedb_type) {
 		case "child": return build_chip_innerHTML(fill, theme, record.icon, label, record.id, highlight, selected, anchored);
 		case "extended": return build_node_innerHTML(fill, theme, record.icon, label, desc.topic_name, true, record.id, highlight, selected, anchored, pills_html);
-		case "hierarchical": return build_node_innerHTML(fill, theme, record.icon, label, desc.topic_name, false, record.id, highlight, selected, anchored, pills_html);
+		case "entity": return build_node_innerHTML(fill, theme, record.icon, label, desc.topic_name, false, record.id, highlight, selected, anchored, pills_html);
 	}
 	return null;
 }
@@ -60046,7 +60074,7 @@ function build_chip_innerHTML(color, theme, icon, label, key, highlight, selecte
 `;
 }
 /************************************************************
-*  Build innerHTML for hierarchical (HTML) nodes.
+*  Build innerHTML for entity (HTML) nodes.
 *
 *  Card style modelled on the documentation schema graphs
 *  (docs gen_treedb_graphs.py): rounded card, soft tint of the
@@ -61364,12 +61392,13 @@ function publish_legend_state(gobj, visible) {
 			loose: loose.length,
 			loose_shown: model.loose_shown.has(topic_name),
 			hidden: model.hidden.has(topic_name),
-			linked: model.linked.has(topic_name)
+			linked: model.linked.has(topic_name),
+			hierarchical: fold_is_hierarchical(priv.descs, topic_name)
 		});
 	}
 	gobj_publish_event(gobj, "EV_LEGEND_STATE", {
 		main_topic: model.main_topic,
-		main_chosen: !!gobj_read_str_attr(gobj, "main_topic"),
+		main_chosen: !!model.main_topic && gobj_read_str_attr(gobj, "main_topic") === model.main_topic,
 		topics,
 		fold: {
 			topic: model.main_topic,
@@ -62945,7 +62974,7 @@ var attrs_table$3 = [
 	SDATA(data_type_t.DTP_POINTER, "subscriber", 0, null, "Subscriber of output events"),
 	SDATA(data_type_t.DTP_LIST, "operation_modes", 0, "[\"reading\", \"operation\", \"writing\", \"edition\"]", "Available **permission** or behaviour modes. These operation modes are required to be accomplish by the graph handler (G6 child). TODO permissions must match treedb permissions."),
 	SDATA(data_type_t.DTP_BOOLEAN, "with_treedb_tables", 0, false, "Include treedb tables"),
-	SDATA(data_type_t.DTP_INTEGER, "expand_depth", 0, 2, "Levels of the treedb open when it loads: 1 = the roots alone, 2 = the roots and their children. Forwarded to the G6 child"),
+	SDATA(data_type_t.DTP_INTEGER, "expand_depth", 0, 1, "Levels of the treedb open when it loads, until the reader steps (`fold_level`): 1 = the roots alone (the default), 2 = the roots and their children. Forwarded to the G6 child"),
 	SDATA(data_type_t.DTP_INTEGER, "fold_page_size", 0, 24, "Children of one hook shown per page in the graph; a `+N` chip opens the next page. Forwarded to the G6 child"),
 	SDATA(data_type_t.DTP_INTEGER, "minimap_min_nodes", 0, 30, "Show the minimap from this many nodes on (0 = never). Forwarded to the G6 child"),
 	SDATA(data_type_t.DTP_BOOLEAN, "with_gridline", 0, true, "Draw the grid under the graph. Forwarded to the G6 child"),
@@ -64596,6 +64625,7 @@ function refresh_legend(gobj) {
 	let topics = state.topics.slice().sort((a, b) => {
 		return String(a.topic).localeCompare(String(b.topic));
 	});
+	let hierarchical_count = topics.filter((e) => e.hierarchical && !e.hidden).length;
 	for (let entry of topics) {
 		let topic_name = entry.topic;
 		let is_main = topic_name === state.main_topic;
@@ -64690,7 +64720,7 @@ function refresh_legend(gobj) {
 				"★"
 			]]
 		]);
-		else if (!hidden) extras.push([
+		else if (!hidden && entry.hierarchical && hierarchical_count > 1) extras.push([
 			"button",
 			{
 				class: "GRAPH_LEGEND_STAR button",
@@ -66039,7 +66069,7 @@ function sort_by_order(list) {
 *              schema_version, c_schema_version, system_schema_version,
 *              topics: [{
 *                  id, name, order, record,
-*                  pkey, topic_version, system_topic,
+*                  pkey, topic_version, system_topic, main_topic,
 *                  cols: [{id, name, order, record}]
 *              }]
 *          }],
@@ -66088,6 +66118,7 @@ function build_schema_model(records) {
 			tkey: record.tkey || "",
 			topic_version: record.topic_version,
 			system_topic: !!record.system_topic,
+			main_topic: !!record.main_topic,
 			cols: []
 		};
 		by_topic_id[entry.id] = entry;
@@ -66384,6 +66415,12 @@ function validate_schema(treedb, options) {
 			if (is_fkey && FKEY_TYPES.indexOf(type) < 0) add("error", "fkey has a bad type", topic.name, col.name, type);
 		}
 	}
+	let marked = treedb.topics.filter((topic) => topic.main_topic);
+	if (marked.length > 1) add("error", "more than one main topic", marked[1].name, "", marked.map((topic) => topic.name).join(", "));
+	for (let topic of marked) if (!topic.cols.some((col) => {
+		let hook = col_hook(col.record);
+		return col_flags(col.record).indexOf("hook") >= 0 && !!hook && Object.prototype.hasOwnProperty.call(hook, topic.name);
+	})) add("error", "main topic not hooked to itself", topic.name, "", "");
 	let hooked = {};
 	for (let topic of treedb.topics) for (let col of topic.cols) {
 		let hook = col_hook(col.record);
@@ -66575,7 +66612,8 @@ var TOPIC_KEY_ORDER = [
 	"system_flag",
 	"tkey",
 	"topic_version",
-	"system_topic"
+	"system_topic",
+	"main_topic"
 ];
 var COL_KEY_ORDER = [
 	"header",
@@ -66833,7 +66871,8 @@ var TOPIC_FIELDS = [
 	"system_flag",
 	"tkey",
 	"topic_version",
-	"system_topic"
+	"system_topic",
+	"main_topic"
 ];
 var COL_FIELDS = [
 	"header",
@@ -68450,6 +68489,20 @@ function render_topics(gobj, $body) {
 							{},
 							""
 						],
+						topic.main_topic ? [
+							"span",
+							{
+								class: "SCHEMA_TOPIC_MAIN ml-2",
+								style: "color:#d4a017;",
+								title: t("main topic"),
+								"data-i18n-title": "main topic"
+							},
+							"★"
+						] : [
+							"span",
+							{},
+							""
+						],
 						ambiguous ? [
 							"div",
 							{ class: "SCHEMA_TOPIC_ID is-size-7 yui-text-quiet" },
@@ -69444,6 +69497,26 @@ function open_topic_form(gobj, treedb, topic) {
 					]]
 				]]
 			],
+			[
+				"div",
+				{ class: "SCHEMA_TOPIC_FORM_MAIN field mb-3" },
+				[[
+					"label",
+					{ class: "checkbox" },
+					[["input", el_attrs({
+						type: "checkbox",
+						"data-name": "main_topic",
+						checked: record.main_topic ? "checked" : void 0
+					})], [
+						"span",
+						{
+							class: "ml-1",
+							i18n: "main topic"
+						},
+						t("main topic")
+					]]
+				]]
+			],
 			[
 				"div",
 				{
@@ -70236,6 +70309,7 @@ function topic_record(gobj, treedb, topic, values) {
 	record.tkey = values.tkey || "";
 	record.topic_version = values.topic_version === "" ? 1 : Number(values.topic_version);
 	record.system_topic = !!values.system_topic;
+	record.main_topic = !!values.main_topic;
 	return record;
 }
 /***************************

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yuneta/gobj-ui",
-  "version": "7.23.141",
+  "version": "7.23.142",
   "type": "module",
   "main": "dist/gobj-ui.cjs.js",
   "module": "dist/gobj-ui.es.js",

package/src/c_g6_nodes_tree.js

@@ -122,6 +122,7 @@ import {
     fold_open_levels,
     fold_close_levels,
     fold_level_clamp,
+    fold_is_hierarchical,
     fold_toggle,
     fold_show_more,
     fold_reveal,
@@ -301,14 +302,14 @@ const PORT_LINE_WIDTH = 2;
 const NODE_MODES = ['expanded', 'compact', 'shape'];
 
 const PILL_SIZE = {
-    hierarchical: [200, 30],
+    entity:       [200, 30],
     extended:     [180, 28],
     child:        [160, 26],
 };
 const PORT_R_PILL = 6;
 
 const SHAPE_SIZE = {
-    hierarchical: 32,
+    entity:       32,
     extended:     28,
     child:        22,
 };
@@ -436,7 +437,7 @@ SDATA(data_type_t.DTP_STRING,   "hook_port_position",   0,  "bottom",   "Hook po
 SDATA(data_type_t.DTP_STRING,   "fkey_port_position",   0,  "top",      "Fkey port position"),
 
 /*---------------- Folding ----------------*/
-SDATA(data_type_t.DTP_INTEGER,  "expand_depth",         0,  2,      "Levels open when a treedb loads, until the reader steps (`fold_level`): 1 = the roots alone, 2 = the roots and their children. Every open hook shows its first page"),
+SDATA(data_type_t.DTP_INTEGER,  "expand_depth",         0,  1,      "Levels open when a treedb loads, until the reader steps (`fold_level`): 1 = the roots alone (the default), 2 = the roots and their children. Every open hook shows its first page"),
 SDATA(data_type_t.DTP_INTEGER,  "fold_level",           0,  0,      "The level of the MAIN tree the toolbar's stepper stands on: 1 = its roots, N = N-1 levels under them; 0 = `expand_depth`. The host persists it and sends EV_SET_FOLD_LEVEL; it is published back in EV_LEGEND_STATE (`fold`) with the levels the tree has"),
 SDATA(data_type_t.DTP_INTEGER,  "fold_page_size",       0,  24,     "Children of one hook shown per page; the `+N` chip after the page opens the next one"),
 SDATA(data_type_t.DTP_LIST,     "hidden_topics",        0,  "[]",   "Topics left out of the tree: no card, no pill counts them, no edge reaches them"),
@@ -545,7 +546,7 @@ let PRIVATE_DATA = {
     _nodes_placed:      0,          // ...of which carry a saved position
 
     /*---------------- folding ----------------*/
-    expand_depth:       2,
+    expand_depth:       1,
     fold_level:         0,
     fold_page_size:     24,
     hidden_topics:      null,
@@ -1859,7 +1860,12 @@ function configure_behaviour(gobj)
 }
 
 /************************************************************
- *  Count hooks and fkeys in topic desc, classify node type
+ *  Count hooks and fkeys in topic desc, classify node type:
+ *  `child` (no hooks), `extended` (hooks, no fkeys), `entity`
+ *  (both). It sizes the card and nothing else. It used to be
+ *  called `hierarchical`, and that word means something else now:
+ *  a topic hooked to ITSELF, the only kind a tree can hang from
+ *  (treedb_fold_model).
  ************************************************************/
 function calculate_hooks_fkeys_counter(desc)
 {
@@ -1885,7 +1891,7 @@ function calculate_hooks_fkeys_counter(desc)
     } else if(desc.fkeys_counter === 0) {
         desc.node_treedb_type = 'extended';
     } else {
-        desc.node_treedb_type = 'hierarchical';
+        desc.node_treedb_type = 'entity';
     }
 }
 
@@ -2306,7 +2312,7 @@ function card_shape_of(gobj, desc, record, geometry, pills_html)
             desc.topic_name, true, record.id, false, false, false, pills_html
         );
     } else {
-        // Hierarchical entity (ROOT / container): largest tier.
+        // Entity, hooks and fkeys (ROOT / container): largest tier.
         style.innerHTML = build_node_innerHTML(
             paint.fill, priv.theme, record.icon, label,
             desc.topic_name, false, record.id, false, false, false, pills_html
@@ -2409,7 +2415,7 @@ function pill_shape_of(gobj, desc, record, geometry)
 {
     let priv = gobj.priv;
     let tier = desc.node_treedb_type;
-    let size = PILL_SIZE[tier] || PILL_SIZE.hierarchical;
+    let size = PILL_SIZE[tier] || PILL_SIZE.entity;
     let ports = build_ports(gobj, desc);
     let paint = node_paint_of(gobj, desc, geometry);
 
@@ -2472,7 +2478,7 @@ function figure_shape_of(gobj, desc, record, geometry, flags)
     let dark = (priv.theme === "dark");
     let f = flags || {};
     let tier = desc.node_treedb_type;
-    let side = SHAPE_SIZE[tier] || SHAPE_SIZE.hierarchical;
+    let side = SHAPE_SIZE[tier] || SHAPE_SIZE.entity;
     let labels = gobj_read_bool_attr(gobj, "node_labels");
     let figure = node_figure_of(gobj, desc, geometry || {});
     let paint = node_paint_of(gobj, desc, geometry);
@@ -7042,7 +7048,7 @@ function show_node_detail_popover(gobj, node_id)
 }
 
 /************************************************************
- *  Re-render every HTML (hierarchical) node so its card adopts
+ *  Re-render every HTML (entity) node so its card adopts
  *  the given theme: entity cards and leaf chips (baked innerHTML,
  *  not re-themed by setTheme()) are regenerated; structural
  *  junction diamonds get their neutral fill/stroke re-themed.
@@ -7258,7 +7264,7 @@ function refresh_minimap(gobj)
 
 /************************************************************
  *  The innerHTML of ONE node, in the given theme and highlight state.
- *  The three treedb tiers (hierarchical / extended / child) each have
+ *  The three treedb tiers (entity / extended / child) each have
  *  their own card, and both the theme refresh and the highlight need the
  *  same three-way choice — it lived inline in the theme refresh and is
  *  shared now. Returns null for a node that carries no desc.
@@ -7295,7 +7301,7 @@ function node_innerHTML_of(nd, theme, highlight, selected, anchored, pills_html)
                 desc.topic_name, true, record.id, highlight, selected, anchored,
                 pills_html
             );
-        case 'hierarchical':
+        case 'entity':
             return build_node_innerHTML(
                 fill, theme, record.icon, label,
                 desc.topic_name, false, record.id, highlight, selected, anchored,
@@ -7569,7 +7575,7 @@ function build_chip_innerHTML(color, theme, icon, label, key, highlight, selecte
 }
 
 /************************************************************
- *  Build innerHTML for hierarchical (HTML) nodes.
+ *  Build innerHTML for entity (HTML) nodes.
  *
  *  Card style modelled on the documentation schema graphs
  *  (docs gen_treedb_graphs.py): rounded card, soft tint of the
@@ -9538,12 +9544,16 @@ function publish_legend_state(gobj, visible)
             loose_shown: model.loose_shown.has(topic_name),
             hidden: model.hidden.has(topic_name),
             linked: model.linked.has(topic_name),
+            hierarchical: fold_is_hierarchical(priv.descs, topic_name),
         });
     }
 
     gobj_publish_event(gobj, "EV_LEGEND_STATE", {
         main_topic: model.main_topic,
-        main_chosen: !!gobj_read_str_attr(gobj, "main_topic"),
+        /*  CHOSEN only when the reader's pick is the one in force: a
+         *  pick the rule refuses (not hierarchical) is ignored.  */
+        main_chosen: !!model.main_topic &&
+                     gobj_read_str_attr(gobj, "main_topic") === model.main_topic,
         topics: topics,
         /*  The toolbar's stepper: the tree it walks, where it stands,
          *  and how deep it goes. `levels` 0 = nothing to step through.  */

package/src/c_yui_schema_editor.js

@@ -1061,6 +1061,13 @@ function render_topics(gobj, $body)
                     ? ["span", {class: "SCHEMA_TOPIC_SYSTEM tag ml-2",
                                 i18n: "system"}, t("system")]
                     : ["span", {}, ""],
+                /*  The schema's mark of the topic the tree hangs from: the
+                 *  same gold star the treedb graph's legend wears.  */
+                topic.main_topic
+                    ? ["span", {class: "SCHEMA_TOPIC_MAIN ml-2",
+                                style: "color:#d4a017;",
+                                title: t("main topic"), "data-i18n-title": "main topic"}, "★"]
+                    : ["span", {}, ""],
                 ambiguous
                     ? ["div", {class: "SCHEMA_TOPIC_ID is-size-7 yui-text-quiet"},
                         [["code", {}, `${topic.id}`]]]
@@ -1898,6 +1905,14 @@ function open_topic_form(gobj, treedb, topic)
                     ["span", {class: "ml-1", i18n: "system topic"}, t("system topic")]
                 ]]
             ]],
+            /*  A LABEL that wraps its control names it: no aria-label.  */
+            ["div", {class: "SCHEMA_TOPIC_FORM_MAIN field mb-3"}, [
+                ["label", {class: "checkbox"}, [
+                    ["input", el_attrs({type: "checkbox", "data-name": "main_topic",
+                               checked: record.main_topic ? "checked" : undefined})],
+                    ["span", {class: "ml-1", i18n: "main topic"}, t("main topic")]
+                ]]
+            ]],
             ["div", {class: "SCHEMA_TOPIC_FORM_ACTIONS is-flex mt-4",
                      style: "gap:.5rem; justify-content:flex-end;"}, [
                 ["button", {class: "SCHEMA_TOPIC_FORM_CANCEL button", type: "button"},
@@ -2501,6 +2516,7 @@ function topic_record(gobj, treedb, topic, values)
     record.tkey = values.tkey || "";
     record.topic_version = values.topic_version === "" ? 1 : Number(values.topic_version);
     record.system_topic = !!values.system_topic;
+    record.main_topic = !!values.main_topic;
 
     return record;
 }

package/src/c_yui_treedb_graph.js

@@ -111,7 +111,7 @@ SDATA(data_type_t.DTP_LIST,     "operation_modes",  0,
 '["reading", "operation", "writing", "edition"]',
 "Available **permission** or behaviour modes. These operation modes are required to be accomplish by the graph handler (G6 child). TODO permissions must match treedb permissions."),
 SDATA(data_type_t.DTP_BOOLEAN,  "with_treedb_tables",0, false,  "Include treedb tables"),
-SDATA(data_type_t.DTP_INTEGER,  "expand_depth",     0,  2,      "Levels of the treedb open when it loads: 1 = the roots alone, 2 = the roots and their children. Forwarded to the G6 child"),
+SDATA(data_type_t.DTP_INTEGER,  "expand_depth",     0,  1,      "Levels of the treedb open when it loads, until the reader steps (`fold_level`): 1 = the roots alone (the default), 2 = the roots and their children. Forwarded to the G6 child"),
 SDATA(data_type_t.DTP_INTEGER,  "fold_page_size",   0,  24,     "Children of one hook shown per page in the graph; a `+N` chip opens the next page. Forwarded to the G6 child"),
 
 /*---------------- Forwarded to the G6 child (its own defaults) ----------------*/
@@ -2699,6 +2699,11 @@ function refresh_legend(gobj)
         return String(a.topic).localeCompare(String(b.topic));
     });
 
+    /*  Only a topic hooked to ITSELF can be the main one, so only those
+     *  offer the star -- and only when there is more than one to pick
+     *  from: with a single hierarchical topic the choice is made.  */
+    let hierarchical_count = topics.filter((e) => e.hierarchical && !e.hidden).length;
+
     for(let entry of topics) {
         let topic_name = entry.topic;
         let is_main = (topic_name === state.main_topic);
@@ -2813,7 +2818,7 @@ function refresh_legend(gobj)
                                   style: 'padding:0 .5rem; cursor:default;',
                                   title: t('main topic'), 'data-i18n-title': 'main topic'},
                          [['span', {style: LEGEND_STAR_MAIN_STYLE}, '★']]]);
-        } else if(!hidden) {
+        } else if(!hidden && entry.hierarchical && hierarchical_count > 1) {
             extras.push(['button', {class: 'GRAPH_LEGEND_STAR button',
                                     type: 'button', style: 'padding:0 .5rem;',
                                     title: t('main topic'), 'data-i18n-title': 'main topic',

package/src/schema_import.js

@@ -38,7 +38,8 @@ import {
  *  the fkey, `order`) is composed, and `_geometry` belongs to whoever
  *  laid the graph out — an import must not move their boxes.  */
 const TOPIC_FIELDS = [
-    "pkey", "pkey2s", "system_flag", "tkey", "topic_version", "system_topic"
+    "pkey", "pkey2s", "system_flag", "tkey", "topic_version", "system_topic",
+    "main_topic"
 ];
 
 /*  Same for a `cols` record.  */

package/src/schema_model.js

@@ -183,7 +183,7 @@ function sort_by_order(list)
  *              schema_version, c_schema_version, system_schema_version,
  *              topics: [{
  *                  id, name, order, record,
- *                  pkey, topic_version, system_topic,
+ *                  pkey, topic_version, system_topic, main_topic,
  *                  cols: [{id, name, order, record}]
  *              }]
  *          }],
@@ -239,6 +239,7 @@ function build_schema_model(records)
             tkey:          record.tkey || "",
             topic_version: record.topic_version,
             system_topic:  !!record.system_topic,
+            main_topic:    !!record.main_topic,
             cols:          []
         };
         by_topic_id[entry.id] = entry;

package/src/schema_to_c.js

@@ -47,7 +47,7 @@ const DEFAULT_PAD = 68;
  *  and every export diffs against the last one.  */
 const TOPIC_KEY_ORDER = [
     "id", "pkey", "pkey2s", "system_flag", "tkey",
-    "topic_version", "system_topic"
+    "topic_version", "system_topic", "main_topic"
 ];
 
 /*  Same for a column, in the order the .c literals write it.  */

package/src/schema_validate.js

@@ -189,6 +189,26 @@ function validate_schema(treedb, options)
         }
     }
 
+    /*  The topic the tree hangs from (`main_topic`): ONE per treedb, and
+     *  only a topic hooked to itself. treedb_open_db logs either mistake
+     *  and ignores the mark, so the restart succeeds and the graph goes
+     *  on deducing -- better said here, before it.  */
+    let marked = treedb.topics.filter((topic) => topic.main_topic);
+    if(marked.length > 1) {
+        add("error", "more than one main topic", marked[1].name, "",
+            marked.map((topic) => topic.name).join(", "));
+    }
+    for(let topic of marked) {
+        let hooks_itself = topic.cols.some((col) => {
+            let hook = col_hook(col.record);
+            return col_flags(col.record).indexOf("hook") >= 0 &&
+                   !!hook && Object.prototype.hasOwnProperty.call(hook, topic.name);
+        });
+        if(!hooks_itself) {
+            add("error", "main topic not hooked to itself", topic.name, "", "");
+        }
+    }
+
     /*  How many hooks name each fkey column. Both answers are a
      *  finding: NONE and the parent side of the link was renamed or
      *  deleted, so the references are written by nobody; TWO and the

package/src/schema_validate.test.js

@@ -94,6 +94,50 @@ describe("the topic will not open", () => {
     });
 });
 
+describe("the main topic mark", () => {
+    /*  departments hooked to itself: the one topic the mark can go on  */
+    const self_hook = {
+        id: "db.departments.departments", value: "departments", order: 3,
+        type: "dict", flag: ["hook"], hook: {departments: "departments"},
+        topics: ["topics^db.departments^cols"]
+    };
+
+    test("on a topic hooked to itself, says nothing", () => {
+        const t = schema({extra_col: self_hook});
+        t.topics[0].main_topic = true;
+        const c = codes(validate_schema(t));
+        expect(c).not.toContain("main topic not hooked to itself");
+        expect(c).not.toContain("more than one main topic");
+    });
+
+    test("on a topic that is not hooked to itself", () => {
+        const t = schema();
+        t.topics[1].main_topic = true;
+        const f = validate_schema(t);
+        expect(codes(f)).toContain("main topic not hooked to itself");
+        expect(has_errors(f)).toBe(true);
+    });
+
+    test("on two topics", () => {
+        const t = schema({extra_col: self_hook});
+        t.topics[0].main_topic = true;
+        t.topics[1].main_topic = true;
+        const f = validate_schema(t);
+        expect(codes(f)).toContain("more than one main topic");
+        expect(f.find((x) => x.code === "more than one main topic").detail)
+            .toBe("departments, users");
+    });
+
+    test("the model reads the mark from the record", () => {
+        const model = build_schema_model({
+            treedbs: [{id: "db"}],
+            topics:  [{id: "db.a", value: "a", main_topic: true, treedbs: ["treedbs^db^topics"]}],
+            cols:    [],
+        });
+        expect(model.treedbs[0].topics[0].main_topic).toBe(true);
+    });
+});
+
 describe("the link does nothing, and the write succeeded", () => {
     test("a hook with no mapping", () => {
         expect(codes(validate_schema(schema({hook: null})))).toContain("hook has no mapping");

package/src/treedb_fold_model.js

@@ -152,7 +152,13 @@ export function fold_build_model(descs, records, opts)
 
     let hidden = new Set(is_array(opts.hidden_topics)? opts.hidden_topics : []);
     let loose_shown = new Set(is_array(opts.loose_topics)? opts.loose_topics : []);
-    let main_topic = opts.main_topic || fold_main_topic(descs);
+    let main_topic = opts.main_topic || "";
+    if(main_topic && !fold_is_hierarchical(descs, main_topic)) {
+        main_topic = "";    /*  a pick the rule does not allow (see fold_main_topic): deduce  */
+    }
+    if(!main_topic) {
+        main_topic = fold_main_topic(descs);
+    }
     if(main_topic && (!descs[main_topic] || hidden.has(main_topic))) {
         main_topic = "";    /*  a main topic that is not drawn governs nothing  */
     }
@@ -355,34 +361,60 @@ function count_levels(model)
 }
 
 /************************************************************
- *  The topic the schema hangs the others from: the one whose hooks
- *  reach the most OTHER topics, a self-referent hook breaking a tie
- *  (a tree of places over a flat list of groups), schema order
- *  breaking the rest. "" when no topic reaches another -- a treedb of
- *  unrelated lists has no trunk, and every topic is a tree of its own.
+ *  A HIERARCHICAL topic: one hooked to ITSELF -- places inside
+ *  places, groups inside groups, roles inside roles. It is the
+ *  only kind of topic a tree can hang from: a topic that only
+ *  reaches OTHER topics is a list with children, and making it
+ *  the trunk drew the agent's treedb from `yunos` instead of
+ *  `realms`.
+ *
+ *  (Not the engine's `entity` tier, which is any topic with
+ *  hooks AND fkeys: that one sizes a card and says nothing about
+ *  where a tree starts.)
+ ************************************************************/
+export function fold_is_hierarchical(descs, topic_name)
+{
+    if(!is_object(descs) || !descs[topic_name]) {
+        return false;
+    }
+    return hook_targets(descs, topic_name).has(topic_name);
+}
+
+/************************************************************
+ *  The topic the tree hangs from. Only a HIERARCHICAL topic can
+ *  be it, and in this order:
+ *
+ *      the one the schema MARKS (`main_topic: true` on the topic,
+ *      sent by the backend in its desc since SDK 7.19; the first
+ *      one in schema order if a schema marks two);
+ *      else the one whose hooks reach the most OTHER topics,
+ *      schema order breaking a tie.
+ *
+ *  "" when no topic is hooked to itself: there is no trunk, and
+ *  every topic is a tree of its own. (A pick by the reader comes
+ *  first of all, and is fold_build_model's business.)
  ************************************************************/
 export function fold_main_topic(descs)
 {
     descs = is_object(descs)? descs : {};
-    let best = "";
-    let best_score = 0;
-    let best_self = false;
+    let candidates = Object.keys(descs).filter((topic_name) => {
+        return topic_name.substring(0, 2) !== "__" && fold_is_hierarchical(descs, topic_name);
+    });
 
-    for(let topic_name of Object.keys(descs)) {
-        if(topic_name.substring(0, 2) === "__") {
-            continue;
+    for(let topic_name of candidates) {
+        if(descs[topic_name].main_topic === true) {
+            return topic_name;
         }
+    }
+
+    let best = "";
+    let best_score = -1;
+    for(let topic_name of candidates) {
         let reach = hook_targets(descs, topic_name);
-        let self = reach.has(topic_name);
         reach.delete(topic_name);
-        let score = reach.size;
-        if(score === 0) {
-            continue;
-        }
-        if(score > best_score || (score === best_score && self && !best_self)) {
+        if(reach.size > best_score) {
             best = topic_name;
-            best_score = score;
-            best_self = self;
+            best_score = reach.size;
         }
     }
     return best;

package/src/treedb_fold_model.test.js

@@ -31,11 +31,12 @@ import {
     fold_open_levels,
     fold_close_levels,
     fold_expand_to_level,
+    fold_is_hierarchical,
 } from "./treedb_fold_model.js";
 
 const places_desc = {
     topic_name: "places",
-    node_treedb_type: "hierarchical",
+    node_treedb_type: "entity",
     cols: [
         {id: "id", flag: []},
         {id: "place", flag: ["fkey"], fkey: {places: "places"}},
@@ -56,13 +57,20 @@ const devices_desc = {
 };
 const controllers_desc = {
     topic_name: "controllers",
-    node_treedb_type: "hierarchical",
+    node_treedb_type: "entity",
     cols: [
         {id: "id", flag: []},
         {id: "place", flag: ["fkey"], fkey: {places: "controllers"}},
         {id: "devices", flag: ["hook"], hook: {devices: "controller"}},
     ],
 };
+/*  controllers inside controllers: a second HIERARCHICAL topic  */
+const controllers_self = Object.assign({}, controllers_desc, {
+    cols: controllers_desc.cols.concat([
+        {id: "controllers", flag: ["hook"], hook: {controllers: "parent"}},
+        {id: "parent", flag: ["fkey"], fkey: {controllers: "controllers"}},
+    ]),
+});
 const groups_desc = {
     topic_name: "device_groups",
     node_treedb_type: "extended",
@@ -189,10 +197,33 @@ describe("main topic, hidden topics, loose records", () => {
         expect(m.linked.has("device_groups")).toBe(false);
     });
 
+    test("only a topic hooked to ITSELF can be the main one", () => {
+        expect(fold_is_hierarchical(descs, "places")).toBe(true);
+        expect(fold_is_hierarchical(descs, "controllers")).toBe(false);
+        expect(fold_is_hierarchical(descs, "device_groups")).toBe(false);
+        /*  c reaches x and nothing reaches itself: no trunk at all  */
+        let c = {topic_name: "c", cols: [{id: "id", flag: []},
+                 {id: "xs", flag: ["hook"], hook: {x: "c"}}]};
+        let x = {topic_name: "x", cols: [{id: "id", flag: []}, {id: "c", flag: ["fkey"]}]};
+        expect(fold_main_topic({c: c, x: x})).toBe("");
+        /*  a tree of places alone, reaching no other topic, is still a trunk  */
+        expect(fold_main_topic({places: places_desc})).toBe("places");
+    });
+
+    test("the schema's mark wins over the deduction, among hierarchical topics", () => {
+        let d = Object.assign({}, descs, {controllers: controllers_self});
+        expect(fold_main_topic(d)).toBe("places");  /*  places reaches more  */
+        let marked = Object.assign({}, d, {controllers: Object.assign({}, controllers_self, {main_topic: true})});
+        expect(fold_main_topic(marked)).toBe("controllers");
+        /*  a mark on a topic that is not hierarchical is not a trunk  */
+        let wrong = Object.assign({}, descs, {devices: Object.assign({}, devices_desc, {main_topic: true})});
+        expect(fold_main_topic(wrong)).toBe("places");
+    });
+
     test("a self-referent hook breaks a tie", () => {
         let a = {topic_name: "a", node_treedb_type: "extended",
                  cols: [{id: "id", flag: []}, {id: "xs", flag: ["hook"], hook: {x: "a"}}]};
-        let b = {topic_name: "b", node_treedb_type: "hierarchical",
+        let b = {topic_name: "b", node_treedb_type: "entity",
                  cols: [{id: "id", flag: []}, {id: "xs", flag: ["hook"], hook: {x: "b"}},
                         {id: "bs", flag: ["hook"], hook: {b: "parent"}},
                         {id: "parent", flag: ["fkey"], fkey: {b: "bs"}}]};
@@ -201,12 +232,16 @@ describe("main topic, hidden topics, loose records", () => {
         expect(fold_main_topic({x: x})).toBe("");
     });
 
-    test("an explicit main topic wins over the deduced one", () => {
-        let m = fold_build_model(descs, make_records(3), {main_topic: "controllers"});
+    test("the reader's pick wins -- if it is a hierarchical topic", () => {
+        let d = Object.assign({}, descs, {controllers: controllers_self});
+        let m = fold_build_model(d, make_records(3), {main_topic: "controllers"});
         expect(m.main_topic).toBe("controllers");
         expect([...m.linked].sort()).toEqual(["controllers", "devices"]);
         /*  places is not linked to controllers, so its roots are roots  */
         expect(m.groups.get(fold_root_group_key("places"))).toEqual([K("places", "es")]);
+        /*  a pick the rule refuses is ignored, and the trunk is deduced  */
+        let m2 = fold_build_model(descs, make_records(3), {main_topic: "controllers"});
+        expect(m2.main_topic).toBe("places");
     });
 
     test("a device with no place is LOOSE: counted, not a root, unless asked for", () => {