@yuneta/gobj-ui 7.23.196 → 7.25.0

package/README.md

@@ -2084,7 +2084,37 @@ The logic is pure and tested apart from the view: `schema_model.js` (the three
 lists regrouped — grouping follows the **fkey**, not a split of the qualified
 id on `.`, which works right up to the first name that carries one),
 `schema_validate.js`, `schema_descs.js`, `schema_to_c.js`, `schema_import.js`,
-`schema_flags.js`, `schema_write_options.js`. Since 6.1.0.
+`schema_flags.js`, `schema_write_options.js`, `schema_to_diagram.js`. Since 6.1.0.
+
+**The export is the whole `treedb_schema_<db>.c`.** `schema_to_c()` writes the
+graph of the schema as a comment — one box per topic, `*` required, `=`
+inherited, `(2)` pkey2, `(t)` tkey, the hook markers `{}` `[]` `()` and the
+fkey markers `(↖)` `[↖]` `{↖}`, and a line from each hook's row to the row of
+the fkey it fills — and then the literal, and that is all such a file holds:
+an edit made in the editor goes back into the source by replacing the file
+whole. The graph is `schema_to_diagram()`, derived and never drawn by hand;
+`json_to_c()` writes the same file from the literal's own JSON (the yunetas
+script `scripts/schema_diagram.mjs` uses it to keep the files in the repo
+equal to what an export would give). `with_diagram: false` gives the literal
+alone. Since 7.23.197.
+
+```c
+/*
+    Generated from the literal below by schema_to_diagram() (gobj-ui).
+    ...
+                    users
+            ┌───────────────────────────┐
+            │* id                       │
+            │  name (2)                 │
+            │           departments [↖] │ ──────┘
+            └───────────────────────────┘
+*/
+
+static char treedb_schema_sample[]= "\
+{                                                                   \n\
+    'id': 'treedb_sample',                                          \n\
+    ...
+```
 
 **A drag can be undone.** Reordering a column is a WRITE — `order` is a field —
 so the drop lands in the store the moment you let go. The toolbar grows an

package/dist/gobj-ui.cjs.js

@@ -70457,6 +70457,230 @@ function topic_descs(treedb) {
 	}
 	return descs;
 }
+//#endregion
+//#region src/schema_to_diagram.js
+/***********************************************************************
+*          schema_to_diagram.js
+*
+*      The graph of a treedb schema, drawn as text.
+*
+*      It is the comment that heads every `treedb_schema_<db>.c`: one
+*      box per topic, in the order the schema declares them, a row per
+*      column, and every hook -> fkey link drawn as a line from the
+*      hook's row (`◀`) to the fkey's row. It is DERIVED from the
+*      schema, never drawn by hand, so the file that holds the literal
+*      can be replaced whole with an export and its picture is never
+*      behind it.
+*
+*      Each link runs down its own LANE to the right of the boxes, the
+*      shorter links nearer to them, so no search is needed to lay it
+*      out: the only ambiguity left is where a line crosses a lane that
+*      is in use, and that is drawn as a junction.
+*
+*      The input is the schema as its literal holds it (what
+*      schema_to_json() answers, or the parsed literal itself):
+*          {id, schema_version, topics: [{id, pkey2s, tkey, main_topic,
+*                                         cols: {name: {type, flag, hook}}}]}
+*
+*          Copyright (c) 2026, ArtGins.
+*          All Rights Reserved.
+***********************************************************************/
+var INDENT = 8;
+var MIN_INNER = 27;
+var LANE_GAP = 4;
+var LEGEND = [
+	"{}  dict hook   (N unique children)",
+	"[]  list hook   (n not-unique children)",
+	"()  string hook (1 unique child)",
+	"(↖) 1 fkey      (1 parent)",
+	"[↖] n fkeys     (n parents)",
+	"{↖} N fkeys     (N parents)",
+	"",
+	"(2) pkey2 - secondary key",
+	"(t) tkey  - time key",
+	"*   field required",
+	"=   field inherited"
+];
+var L = 1;
+var R = 2;
+var U = 4;
+var D = 8;
+var GLYPH = {
+	[3]: "─",
+	[L]: "─",
+	[R]: "─",
+	[12]: "│",
+	[U]: "│",
+	[D]: "│",
+	[10]: "┌",
+	[9]: "┐",
+	[6]: "└",
+	[5]: "┘",
+	[11]: "┬",
+	[7]: "┴",
+	[14]: "├",
+	[13]: "┤",
+	[15]: "┼"
+};
+/***************************************************************
+*  A value that may be one string or a list of them, as a list.
+***************************************************************/
+function as_list(value) {
+	if (typeof value === "string") return value ? [value] : [];
+	if (Array.isArray(value)) {
+		let list = [];
+		for (let v of value) list.push(...as_list(v));
+		return list;
+	}
+	if (value && typeof value === "object") {
+		let list = [];
+		for (let v of Object.values(value)) list.push(...as_list(v));
+		return list;
+	}
+	return [];
+}
+/***************************************************************
+*  The columns of a topic as [name, desc] in declared order: a
+*  dict in the literals, a list of {id} in some stores.
+***************************************************************/
+function topic_cols(topic) {
+	let cols = topic.cols || {};
+	if (Array.isArray(cols)) return cols.map((c) => [c.id, c]);
+	return Object.entries(cols);
+}
+/***************************************************************
+*  What a link column looks like at its end of the line.
+***************************************************************/
+function hook_marker(type) {
+	if (type === "dict" || type === "object") return "{}";
+	if (type === "array" || type === "list") return "[]";
+	return "()";
+}
+function fkey_marker(type) {
+	if (type === "dict" || type === "object") return "{↖}";
+	if (type === "array" || type === "list") return "[↖]";
+	return "(↖)";
+}
+/***************************************************************
+*  One row of a box: the text inside it, and whether it is a
+*  link column (written against the right edge, where its line
+*  leaves the box).
+***************************************************************/
+function col_row(topic, name, desc, pkey2s) {
+	let flags = as_list(desc.flag);
+	if (flags.indexOf("hook") >= 0) return {
+		text: `${name} ${hook_marker(desc.type)}`,
+		link: true
+	};
+	if (flags.indexOf("fkey") >= 0) return {
+		text: `${name} ${fkey_marker(desc.type)}`,
+		link: true
+	};
+	let text = `${flags.indexOf("required") >= 0 ? "*" : flags.indexOf("inherit") >= 0 ? "=" : " "} ${name}`;
+	if (pkey2s.indexOf(name) >= 0) text += " (2)";
+	if (topic.tkey && topic.tkey === name) text += " (t)";
+	return {
+		text,
+		link: false
+	};
+}
+/***************************************************************
+*  schema_to_diagram(schema) -> the text, one string with a
+*  newline per line and no trailing spaces.
+***************************************************************/
+function schema_to_diagram(schema) {
+	if (!schema || !Array.isArray(schema.topics)) return "";
+	let boxes = [];
+	let inner = MIN_INNER;
+	for (let topic of schema.topics) {
+		let pkey2s = as_list(topic.pkey2s);
+		let rows = topic_cols(topic).map(([name, desc]) => Object.assign({ name }, col_row(topic, name, desc || {}, pkey2s)));
+		for (let row of rows) inner = Math.max(inner, row.text.length + 2);
+		let title = topic.id + (topic.main_topic ? "  (main_topic)" : "");
+		inner = Math.max(inner, title.length);
+		boxes.push({
+			topic,
+			title,
+			rows
+		});
+	}
+	let lines = [];
+	let where = {};
+	let edge = INDENT + inner + 1;
+	lines.push(`${schema.id || ""}  (schema_version ${schema.schema_version || "?"})`);
+	lines.push("");
+	for (let l of LEGEND) lines.push(l);
+	lines.push("");
+	lines.push("");
+	for (let box of boxes) {
+		let pad = Math.max(0, Math.floor((inner + 2 - box.title.length) / 2));
+		lines.push(" ".repeat(INDENT + pad) + box.title);
+		lines.push(" ".repeat(INDENT) + "┌" + "─".repeat(inner) + "┐");
+		for (let row of box.rows) {
+			let text = row.link ? row.text.padStart(inner - 1) + " " : row.text.padEnd(inner);
+			where[`${box.topic.id}\`${row.name}`] = lines.length;
+			lines.push(" ".repeat(INDENT) + "│" + text + "│");
+		}
+		lines.push(" ".repeat(INDENT) + "└" + "─".repeat(inner) + "┘");
+		lines.push("");
+	}
+	let links = [];
+	for (let topic of schema.topics) for (let [name, desc] of topic_cols(topic)) {
+		desc = desc || {};
+		if (as_list(desc.flag).indexOf("hook") < 0) continue;
+		let hook = desc.hook;
+		if (!hook || typeof hook !== "object" || Array.isArray(hook)) continue;
+		for (let [child_topic, fkey_col] of Object.entries(hook)) {
+			let from = where[`${topic.id}\`${name}`];
+			let to = where[`${child_topic}\`${fkey_col}`];
+			if (from === void 0 || to === void 0) continue;
+			links.push({
+				from,
+				to,
+				top: Math.min(from, to),
+				bottom: Math.max(from, to)
+			});
+		}
+	}
+	links.sort((a, b) => a.bottom - a.top - (b.bottom - b.top) || a.top - b.top);
+	let lanes = [];
+	for (let link of links) {
+		let k = 0;
+		for (;; k++) if ((lanes[k] || []).every((o) => link.bottom < o.top || o.bottom < link.top)) break;
+		lanes[k] = (lanes[k] || []).concat([link]);
+		link.x = edge + LANE_GAP + LANE_GAP * k;
+	}
+	let bits = {};
+	let fixed = {};
+	let join = (y, x, b) => {
+		let key = `${y},${x}`;
+		bits[key] = (bits[key] || 0) | b;
+	};
+	let hline = (y, x1, x2) => {
+		for (let x = x1; x <= x2; x++) join(y, x, (x > x1 ? L : 0) | (x < x2 ? R : 0));
+	};
+	let vline = (x, y1, y2) => {
+		for (let y = y1; y <= y2; y++) join(y, x, (y > y1 ? U : 0) | (y < y2 ? D : 0));
+	};
+	for (let link of links) {
+		hline(link.from, edge + 2, link.x);
+		hline(link.to, edge + 2, link.x);
+		vline(link.x, link.top, link.bottom);
+		fixed[`${link.from},${edge + 2}`] = "◀";
+	}
+	let out = lines.map((line, y) => {
+		let chars = Array.from(line);
+		for (let key of Object.keys(bits)) {
+			let [ky, kx] = key.split(",").map(Number);
+			if (ky !== y) continue;
+			while (chars.length <= kx) chars.push(" ");
+			chars[kx] = fixed[key] || GLYPH[bits[key]] || " ";
+		}
+		return chars.join("").replace(/\s+$/, "");
+	});
+	while (out.length && out[out.length - 1] === "") out.pop();
+	return out.join("\n");
+}
 var TOPIC_KEY_ORDER = [
 	"id",
 	"pkey",
@@ -70661,14 +70885,22 @@ function c_pair(lines, key, value, indent, trailing) {
 /***************************************************************
 *  schema_to_c(treedb, options) -> the C source text
 *
-*      options {var_name, pad}
-*          var_name  the array's name; defaults to
-*                    `treedb_schema_<treedb id without its prefix>`
-*          pad       column of the `\n\` continuation
+*      options {var_name, pad, with_diagram}
+*          var_name      the array's name; defaults to
+*                        `treedb_schema_<treedb id without its prefix>`
+*          pad           column of the `\n\` continuation
+*          with_diagram  the graph as a comment above the array
+*                        (default true)
 ***************************************************************/
 function schema_to_c(treedb, options) {
+	return json_to_c(schema_to_json(treedb), options);
+}
+/***************************************************************
+*  json_to_c(json, options) -> the C source text, from the schema
+*  as its literal holds it. Same options as schema_to_c().
+***************************************************************/
+function json_to_c(json, options) {
 	let opts = options || {};
-	let json = schema_to_json(treedb);
 	if (!json) return "";
 	let name = opts.var_name;
 	if (!name) {
@@ -70687,7 +70919,24 @@ function schema_to_c(treedb, options) {
 	let body = lines.map((line) => {
 		return `${line}${line.length < pad ? " ".repeat(pad - line.length) : " "}\\n\\`;
 	});
-	return `static char ${name}[]= "\\\n${body.join("\n")}\n";\n`;
+	let literal = `static char ${name}[]= "\\\n${body.join("\n")}\n";\n`;
+	if (opts.with_diagram === false) return literal;
+	return c_diagram_comment(schema_to_diagram(json)) + "\n" + literal;
+}
+/***************************************************************
+*  The diagram as the comment that heads the file.
+***************************************************************/
+function c_diagram_comment(diagram) {
+	let lines = [
+		"/*",
+		"    Generated from the literal below by schema_to_diagram() (gobj-ui).",
+		"    This file holds this comment and the literal, nothing else: replace",
+		"    it whole with an export of the schema editor.",
+		""
+	];
+	for (let line of diagram.split("\n")) lines.push(line ? "    " + line : "");
+	lines.push("*/");
+	return lines.join("\n") + "\n";
 }
 //#endregion
 //#region src/schema_import.js

package/dist/gobj-ui.es.js

@@ -70452,6 +70452,230 @@ function topic_descs(treedb) {
 	}
 	return descs;
 }
+//#endregion
+//#region src/schema_to_diagram.js
+/***********************************************************************
+*          schema_to_diagram.js
+*
+*      The graph of a treedb schema, drawn as text.
+*
+*      It is the comment that heads every `treedb_schema_<db>.c`: one
+*      box per topic, in the order the schema declares them, a row per
+*      column, and every hook -> fkey link drawn as a line from the
+*      hook's row (`◀`) to the fkey's row. It is DERIVED from the
+*      schema, never drawn by hand, so the file that holds the literal
+*      can be replaced whole with an export and its picture is never
+*      behind it.
+*
+*      Each link runs down its own LANE to the right of the boxes, the
+*      shorter links nearer to them, so no search is needed to lay it
+*      out: the only ambiguity left is where a line crosses a lane that
+*      is in use, and that is drawn as a junction.
+*
+*      The input is the schema as its literal holds it (what
+*      schema_to_json() answers, or the parsed literal itself):
+*          {id, schema_version, topics: [{id, pkey2s, tkey, main_topic,
+*                                         cols: {name: {type, flag, hook}}}]}
+*
+*          Copyright (c) 2026, ArtGins.
+*          All Rights Reserved.
+***********************************************************************/
+var INDENT = 8;
+var MIN_INNER = 27;
+var LANE_GAP = 4;
+var LEGEND = [
+	"{}  dict hook   (N unique children)",
+	"[]  list hook   (n not-unique children)",
+	"()  string hook (1 unique child)",
+	"(↖) 1 fkey      (1 parent)",
+	"[↖] n fkeys     (n parents)",
+	"{↖} N fkeys     (N parents)",
+	"",
+	"(2) pkey2 - secondary key",
+	"(t) tkey  - time key",
+	"*   field required",
+	"=   field inherited"
+];
+var L = 1;
+var R = 2;
+var U = 4;
+var D = 8;
+var GLYPH = {
+	[3]: "─",
+	[L]: "─",
+	[R]: "─",
+	[12]: "│",
+	[U]: "│",
+	[D]: "│",
+	[10]: "┌",
+	[9]: "┐",
+	[6]: "└",
+	[5]: "┘",
+	[11]: "┬",
+	[7]: "┴",
+	[14]: "├",
+	[13]: "┤",
+	[15]: "┼"
+};
+/***************************************************************
+*  A value that may be one string or a list of them, as a list.
+***************************************************************/
+function as_list(value) {
+	if (typeof value === "string") return value ? [value] : [];
+	if (Array.isArray(value)) {
+		let list = [];
+		for (let v of value) list.push(...as_list(v));
+		return list;
+	}
+	if (value && typeof value === "object") {
+		let list = [];
+		for (let v of Object.values(value)) list.push(...as_list(v));
+		return list;
+	}
+	return [];
+}
+/***************************************************************
+*  The columns of a topic as [name, desc] in declared order: a
+*  dict in the literals, a list of {id} in some stores.
+***************************************************************/
+function topic_cols(topic) {
+	let cols = topic.cols || {};
+	if (Array.isArray(cols)) return cols.map((c) => [c.id, c]);
+	return Object.entries(cols);
+}
+/***************************************************************
+*  What a link column looks like at its end of the line.
+***************************************************************/
+function hook_marker(type) {
+	if (type === "dict" || type === "object") return "{}";
+	if (type === "array" || type === "list") return "[]";
+	return "()";
+}
+function fkey_marker(type) {
+	if (type === "dict" || type === "object") return "{↖}";
+	if (type === "array" || type === "list") return "[↖]";
+	return "(↖)";
+}
+/***************************************************************
+*  One row of a box: the text inside it, and whether it is a
+*  link column (written against the right edge, where its line
+*  leaves the box).
+***************************************************************/
+function col_row(topic, name, desc, pkey2s) {
+	let flags = as_list(desc.flag);
+	if (flags.indexOf("hook") >= 0) return {
+		text: `${name} ${hook_marker(desc.type)}`,
+		link: true
+	};
+	if (flags.indexOf("fkey") >= 0) return {
+		text: `${name} ${fkey_marker(desc.type)}`,
+		link: true
+	};
+	let text = `${flags.indexOf("required") >= 0 ? "*" : flags.indexOf("inherit") >= 0 ? "=" : " "} ${name}`;
+	if (pkey2s.indexOf(name) >= 0) text += " (2)";
+	if (topic.tkey && topic.tkey === name) text += " (t)";
+	return {
+		text,
+		link: false
+	};
+}
+/***************************************************************
+*  schema_to_diagram(schema) -> the text, one string with a
+*  newline per line and no trailing spaces.
+***************************************************************/
+function schema_to_diagram(schema) {
+	if (!schema || !Array.isArray(schema.topics)) return "";
+	let boxes = [];
+	let inner = MIN_INNER;
+	for (let topic of schema.topics) {
+		let pkey2s = as_list(topic.pkey2s);
+		let rows = topic_cols(topic).map(([name, desc]) => Object.assign({ name }, col_row(topic, name, desc || {}, pkey2s)));
+		for (let row of rows) inner = Math.max(inner, row.text.length + 2);
+		let title = topic.id + (topic.main_topic ? "  (main_topic)" : "");
+		inner = Math.max(inner, title.length);
+		boxes.push({
+			topic,
+			title,
+			rows
+		});
+	}
+	let lines = [];
+	let where = {};
+	let edge = INDENT + inner + 1;
+	lines.push(`${schema.id || ""}  (schema_version ${schema.schema_version || "?"})`);
+	lines.push("");
+	for (let l of LEGEND) lines.push(l);
+	lines.push("");
+	lines.push("");
+	for (let box of boxes) {
+		let pad = Math.max(0, Math.floor((inner + 2 - box.title.length) / 2));
+		lines.push(" ".repeat(INDENT + pad) + box.title);
+		lines.push(" ".repeat(INDENT) + "┌" + "─".repeat(inner) + "┐");
+		for (let row of box.rows) {
+			let text = row.link ? row.text.padStart(inner - 1) + " " : row.text.padEnd(inner);
+			where[`${box.topic.id}\`${row.name}`] = lines.length;
+			lines.push(" ".repeat(INDENT) + "│" + text + "│");
+		}
+		lines.push(" ".repeat(INDENT) + "└" + "─".repeat(inner) + "┘");
+		lines.push("");
+	}
+	let links = [];
+	for (let topic of schema.topics) for (let [name, desc] of topic_cols(topic)) {
+		desc = desc || {};
+		if (as_list(desc.flag).indexOf("hook") < 0) continue;
+		let hook = desc.hook;
+		if (!hook || typeof hook !== "object" || Array.isArray(hook)) continue;
+		for (let [child_topic, fkey_col] of Object.entries(hook)) {
+			let from = where[`${topic.id}\`${name}`];
+			let to = where[`${child_topic}\`${fkey_col}`];
+			if (from === void 0 || to === void 0) continue;
+			links.push({
+				from,
+				to,
+				top: Math.min(from, to),
+				bottom: Math.max(from, to)
+			});
+		}
+	}
+	links.sort((a, b) => a.bottom - a.top - (b.bottom - b.top) || a.top - b.top);
+	let lanes = [];
+	for (let link of links) {
+		let k = 0;
+		for (;; k++) if ((lanes[k] || []).every((o) => link.bottom < o.top || o.bottom < link.top)) break;
+		lanes[k] = (lanes[k] || []).concat([link]);
+		link.x = edge + LANE_GAP + LANE_GAP * k;
+	}
+	let bits = {};
+	let fixed = {};
+	let join = (y, x, b) => {
+		let key = `${y},${x}`;
+		bits[key] = (bits[key] || 0) | b;
+	};
+	let hline = (y, x1, x2) => {
+		for (let x = x1; x <= x2; x++) join(y, x, (x > x1 ? L : 0) | (x < x2 ? R : 0));
+	};
+	let vline = (x, y1, y2) => {
+		for (let y = y1; y <= y2; y++) join(y, x, (y > y1 ? U : 0) | (y < y2 ? D : 0));
+	};
+	for (let link of links) {
+		hline(link.from, edge + 2, link.x);
+		hline(link.to, edge + 2, link.x);
+		vline(link.x, link.top, link.bottom);
+		fixed[`${link.from},${edge + 2}`] = "◀";
+	}
+	let out = lines.map((line, y) => {
+		let chars = Array.from(line);
+		for (let key of Object.keys(bits)) {
+			let [ky, kx] = key.split(",").map(Number);
+			if (ky !== y) continue;
+			while (chars.length <= kx) chars.push(" ");
+			chars[kx] = fixed[key] || GLYPH[bits[key]] || " ";
+		}
+		return chars.join("").replace(/\s+$/, "");
+	});
+	while (out.length && out[out.length - 1] === "") out.pop();
+	return out.join("\n");
+}
 var TOPIC_KEY_ORDER = [
 	"id",
 	"pkey",
@@ -70656,14 +70880,22 @@ function c_pair(lines, key, value, indent, trailing) {
 /***************************************************************
 *  schema_to_c(treedb, options) -> the C source text
 *
-*      options {var_name, pad}
-*          var_name  the array's name; defaults to
-*                    `treedb_schema_<treedb id without its prefix>`
-*          pad       column of the `\n\` continuation
+*      options {var_name, pad, with_diagram}
+*          var_name      the array's name; defaults to
+*                        `treedb_schema_<treedb id without its prefix>`
+*          pad           column of the `\n\` continuation
+*          with_diagram  the graph as a comment above the array
+*                        (default true)
 ***************************************************************/
 function schema_to_c(treedb, options) {
+	return json_to_c(schema_to_json(treedb), options);
+}
+/***************************************************************
+*  json_to_c(json, options) -> the C source text, from the schema
+*  as its literal holds it. Same options as schema_to_c().
+***************************************************************/
+function json_to_c(json, options) {
 	let opts = options || {};
-	let json = schema_to_json(treedb);
 	if (!json) return "";
 	let name = opts.var_name;
 	if (!name) {
@@ -70682,7 +70914,24 @@ function schema_to_c(treedb, options) {
 	let body = lines.map((line) => {
 		return `${line}${line.length < pad ? " ".repeat(pad - line.length) : " "}\\n\\`;
 	});
-	return `static char ${name}[]= "\\\n${body.join("\n")}\n";\n`;
+	let literal = `static char ${name}[]= "\\\n${body.join("\n")}\n";\n`;
+	if (opts.with_diagram === false) return literal;
+	return c_diagram_comment(schema_to_diagram(json)) + "\n" + literal;
+}
+/***************************************************************
+*  The diagram as the comment that heads the file.
+***************************************************************/
+function c_diagram_comment(diagram) {
+	let lines = [
+		"/*",
+		"    Generated from the literal below by schema_to_diagram() (gobj-ui).",
+		"    This file holds this comment and the literal, nothing else: replace",
+		"    it whole with an export of the schema editor.",
+		""
+	];
+	for (let line of diagram.split("\n")) lines.push(line ? "    " + line : "");
+	lines.push("*/");
+	return lines.join("\n") + "\n";
 }
 //#endregion
 //#region src/schema_import.js

package/package.json

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

package/src/schema_to_c.js

@@ -19,13 +19,19 @@
  *      Two outputs, because they answer different questions:
  *        schema_to_json() — the schema as a value: to diff, to keep, to
  *                           feed back in.
- *        schema_to_c()    — the same value as the literal: single
- *                           quotes, `\n\` continuations, padded, ready
- *                           to paste.
+ *        schema_to_c()    — the same value as the WHOLE file
+ *                           `treedb_schema_<db>.c`: the graph of the
+ *                           schema as a comment (schema_to_diagram()),
+ *                           then the literal — single quotes, `\n\`
+ *                           continuations, padded. The file holds that
+ *                           and nothing else, so an export replaces it
+ *                           whole. json_to_c() does the same from the
+ *                           literal's own JSON.
  *
  *          Copyright (c) 2026, ArtGins.
  *          All Rights Reserved.
  ***********************************************************************/
+import { schema_to_diagram } from "./schema_to_diagram.js";
 import {
     col_flags,
     col_hook,
@@ -326,15 +332,25 @@ function c_pair(lines, key, value, indent, trailing)
 /***************************************************************
  *  schema_to_c(treedb, options) -> the C source text
  *
- *      options {var_name, pad}
- *          var_name  the array's name; defaults to
- *                    `treedb_schema_<treedb id without its prefix>`
- *          pad       column of the `\n\` continuation
+ *      options {var_name, pad, with_diagram}
+ *          var_name      the array's name; defaults to
+ *                        `treedb_schema_<treedb id without its prefix>`
+ *          pad           column of the `\n\` continuation
+ *          with_diagram  the graph as a comment above the array
+ *                        (default true)
  ***************************************************************/
 function schema_to_c(treedb, options)
+{
+    return json_to_c(schema_to_json(treedb), options);
+}
+
+/***************************************************************
+ *  json_to_c(json, options) -> the C source text, from the schema
+ *  as its literal holds it. Same options as schema_to_c().
+ ***************************************************************/
+function json_to_c(json, options)
 {
     let opts = options || {};
-    let json = schema_to_json(treedb);
 
     if(!json) {
         return "";
@@ -368,7 +384,30 @@ function schema_to_c(treedb, options)
         return `${line}${padding}\\n\\`;
     });
 
-    return `static char ${name}[]= "\\\n${body.join("\n")}\n";\n`;
+    let literal = `static char ${name}[]= "\\\n${body.join("\n")}\n";\n`;
+    if(opts.with_diagram === false) {
+        return literal;
+    }
+    return c_diagram_comment(schema_to_diagram(json)) + "\n" + literal;
+}
+
+/***************************************************************
+ *  The diagram as the comment that heads the file.
+ ***************************************************************/
+function c_diagram_comment(diagram)
+{
+    let lines = [
+        "/*",
+        "    Generated from the literal below by schema_to_diagram() (gobj-ui).",
+        "    This file holds this comment and the literal, nothing else: replace",
+        "    it whole with an export of the schema editor.",
+        "",
+    ];
+    for(let line of diagram.split("\n")) {
+        lines.push(line ? "    " + line : "");
+    }
+    lines.push("*/");
+    return lines.join("\n") + "\n";
 }
 
 
@@ -378,4 +417,5 @@ export {
     COL_KEY_ORDER,
     schema_to_json,
     schema_to_c,
+    json_to_c,
 };

package/src/schema_to_c.test.js

@@ -12,7 +12,8 @@
  ***********************************************************************/
 import { describe, test, expect } from "vitest";
 import { build_schema_model } from "./schema_model.js";
-import { schema_to_json, schema_to_c } from "./schema_to_c.js";
+import { schema_to_json, schema_to_c, json_to_c } from "./schema_to_c.js";
+import { schema_to_diagram } from "./schema_to_diagram.js";
 
 
 /***************************************************************
@@ -134,7 +135,24 @@ describe("schema_to_json", () => {
 });
 
 describe("schema_to_c — the round trip", () => {
-    const source = schema_to_c(TREEDB);
+    const file = schema_to_c(TREEDB);
+    const source = file.slice(file.indexOf("static char"));
+
+    test("the file is the diagram as a comment, then the literal, nothing else", () => {
+        expect(file.startsWith("/*\n")).toBe(true);
+        const close = file.indexOf("\n*/\n");
+        expect(close).toBeGreaterThan(0);
+        expect(file.slice(close + 4)).toBe("\n" + source);
+        expect(file).toContain(schema_to_diagram(schema_to_json(TREEDB)).split("\n")[0]);
+    });
+
+    test("without the diagram it is the literal alone", () => {
+        expect(schema_to_c(TREEDB, {with_diagram: false})).toBe(source);
+    });
+
+    test("json_to_c() writes the same file from the literal's JSON", () => {
+        expect(json_to_c(schema_to_json(TREEDB))).toBe(file);
+    });
 
     test("it is a C array declaration with the conventional name", () => {
         expect(source.startsWith("static char treedb_schema_sample[]= \"\\\n")).toBe(true);
@@ -153,7 +171,7 @@ describe("schema_to_c — the round trip", () => {
     });
 
     test("the caller can name the array and set the continuation column", () => {
-        const custom = schema_to_c(TREEDB, {var_name: "my_schema", pad: 40});
+        const custom = schema_to_c(TREEDB, {var_name: "my_schema", pad: 40, with_diagram: false});
         expect(custom.startsWith("static char my_schema[]=")).toBe(true);
         expect(load_like_the_yuno(custom)).toEqual(schema_to_json(TREEDB));
     });

package/src/schema_to_diagram.js

@@ -0,0 +1,301 @@
+/***********************************************************************
+ *          schema_to_diagram.js
+ *
+ *      The graph of a treedb schema, drawn as text.
+ *
+ *      It is the comment that heads every `treedb_schema_<db>.c`: one
+ *      box per topic, in the order the schema declares them, a row per
+ *      column, and every hook -> fkey link drawn as a line from the
+ *      hook's row (`◀`) to the fkey's row. It is DERIVED from the
+ *      schema, never drawn by hand, so the file that holds the literal
+ *      can be replaced whole with an export and its picture is never
+ *      behind it.
+ *
+ *      Each link runs down its own LANE to the right of the boxes, the
+ *      shorter links nearer to them, so no search is needed to lay it
+ *      out: the only ambiguity left is where a line crosses a lane that
+ *      is in use, and that is drawn as a junction.
+ *
+ *      The input is the schema as its literal holds it (what
+ *      schema_to_json() answers, or the parsed literal itself):
+ *          {id, schema_version, topics: [{id, pkey2s, tkey, main_topic,
+ *                                         cols: {name: {type, flag, hook}}}]}
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+
+
+/*  Where the boxes start, and their narrowest inside: the widths of
+ *  the diagrams drawn by hand before this, so a generated one reads
+ *  like them.  */
+const INDENT = 8;
+const MIN_INNER = 27;
+
+/*  From a box's right edge to its first lane, and between lanes.  */
+const LANE_GAP = 4;
+
+const LEGEND = [
+    "{}  dict hook   (N unique children)",
+    "[]  list hook   (n not-unique children)",
+    "()  string hook (1 unique child)",
+    "(↖) 1 fkey      (1 parent)",
+    "[↖] n fkeys     (n parents)",
+    "{↖} N fkeys     (N parents)",
+    "",
+    "(2) pkey2 - secondary key",
+    "(t) tkey  - time key",
+    "*   field required",
+    "=   field inherited",
+];
+
+/*  A cell of a line is a set of the directions it joins; the glyph is
+ *  what those directions draw.  */
+const L = 1, R = 2, U = 4, D = 8;
+const GLYPH = {
+    [L|R]: "─", [L]: "─", [R]: "─",
+    [U|D]: "│", [U]: "│", [D]: "│",
+    [R|D]: "┌", [L|D]: "┐", [R|U]: "└", [L|U]: "┘",
+    [L|R|D]: "┬", [L|R|U]: "┴", [U|D|R]: "├", [U|D|L]: "┤",
+    [L|R|U|D]: "┼",
+};
+
+
+/***************************************************************
+ *  A value that may be one string or a list of them, as a list.
+ ***************************************************************/
+function as_list(value)
+{
+    if(typeof value === "string") {
+        return value ? [value] : [];
+    }
+    if(Array.isArray(value)) {
+        let list = [];
+        for(let v of value) {
+            list.push(...as_list(v));
+        }
+        return list;
+    }
+    if(value && typeof value === "object") {
+        let list = [];
+        for(let v of Object.values(value)) {
+            list.push(...as_list(v));
+        }
+        return list;
+    }
+    return [];
+}
+
+/***************************************************************
+ *  The columns of a topic as [name, desc] in declared order: a
+ *  dict in the literals, a list of {id} in some stores.
+ ***************************************************************/
+function topic_cols(topic)
+{
+    let cols = topic.cols || {};
+    if(Array.isArray(cols)) {
+        return cols.map((c) => [c.id, c]);
+    }
+    return Object.entries(cols);
+}
+
+/***************************************************************
+ *  What a link column looks like at its end of the line.
+ ***************************************************************/
+function hook_marker(type)
+{
+    if(type === "dict" || type === "object") {
+        return "{}";
+    }
+    if(type === "array" || type === "list") {
+        return "[]";
+    }
+    return "()";
+}
+
+function fkey_marker(type)
+{
+    if(type === "dict" || type === "object") {
+        return "{↖}";
+    }
+    if(type === "array" || type === "list") {
+        return "[↖]";
+    }
+    return "(↖)";
+}
+
+/***************************************************************
+ *  One row of a box: the text inside it, and whether it is a
+ *  link column (written against the right edge, where its line
+ *  leaves the box).
+ ***************************************************************/
+function col_row(topic, name, desc, pkey2s)
+{
+    let flags = as_list(desc.flag);
+    if(flags.indexOf("hook") >= 0) {
+        return {text: `${name} ${hook_marker(desc.type)}`, link: true};
+    }
+    if(flags.indexOf("fkey") >= 0) {
+        return {text: `${name} ${fkey_marker(desc.type)}`, link: true};
+    }
+    let mark = flags.indexOf("required") >= 0 ? "*" :
+               flags.indexOf("inherit") >= 0 ? "=" : " ";
+    let text = `${mark} ${name}`;
+    if(pkey2s.indexOf(name) >= 0) {
+        text += " (2)";
+    }
+    if(topic.tkey && topic.tkey === name) {
+        text += " (t)";
+    }
+    return {text: text, link: false};
+}
+
+/***************************************************************
+ *  schema_to_diagram(schema) -> the text, one string with a
+ *  newline per line and no trailing spaces.
+ ***************************************************************/
+function schema_to_diagram(schema)
+{
+    if(!schema || !Array.isArray(schema.topics)) {
+        return "";
+    }
+
+    /*
+     *  The boxes, and where each column landed
+     */
+    let boxes = [];
+    let inner = MIN_INNER;
+    for(let topic of schema.topics) {
+        let pkey2s = as_list(topic.pkey2s);
+        let rows = topic_cols(topic).map(([name, desc]) =>
+            Object.assign({name: name}, col_row(topic, name, desc || {}, pkey2s))
+        );
+        for(let row of rows) {
+            inner = Math.max(inner, row.text.length + 2);
+        }
+        let title = topic.id + (topic.main_topic ? "  (main_topic)" : "");
+        inner = Math.max(inner, title.length);
+        boxes.push({topic: topic, title: title, rows: rows});
+    }
+
+    let lines = [];
+    let where = {};     /*  "topic`col" -> line index  */
+    let edge = INDENT + inner + 1;
+
+    lines.push(`${schema.id || ""}  (schema_version ${schema.schema_version || "?"})`);
+    lines.push("");
+    for(let l of LEGEND) {
+        lines.push(l);
+    }
+    lines.push("");
+    lines.push("");
+
+    for(let box of boxes) {
+        let pad = Math.max(0, Math.floor((inner + 2 - box.title.length) / 2));
+        lines.push(" ".repeat(INDENT + pad) + box.title);
+        lines.push(" ".repeat(INDENT) + "┌" + "─".repeat(inner) + "┐");
+        for(let row of box.rows) {
+            let text = row.link ?
+                row.text.padStart(inner - 1) + " " :
+                row.text.padEnd(inner);
+            where[`${box.topic.id}\`${row.name}`] = lines.length;
+            lines.push(" ".repeat(INDENT) + "│" + text + "│");
+        }
+        lines.push(" ".repeat(INDENT) + "└" + "─".repeat(inner) + "┘");
+        lines.push("");
+    }
+
+    /*
+     *  The links: from a hook's row to the row of the fkey it fills
+     */
+    let links = [];
+    for(let topic of schema.topics) {
+        for(let [name, desc] of topic_cols(topic)) {
+            desc = desc || {};
+            if(as_list(desc.flag).indexOf("hook") < 0) {
+                continue;
+            }
+            let hook = desc.hook;
+            if(!hook || typeof hook !== "object" || Array.isArray(hook)) {
+                continue;
+            }
+            for(let [child_topic, fkey_col] of Object.entries(hook)) {
+                let from = where[`${topic.id}\`${name}`];
+                let to = where[`${child_topic}\`${fkey_col}`];
+                if(from === undefined || to === undefined) {
+                    continue;
+                }
+                links.push({from: from, to: to,
+                            top: Math.min(from, to), bottom: Math.max(from, to)});
+            }
+        }
+    }
+
+    /*  Shorter links nearer the boxes: a lane holds links whose rows
+     *  do not overlap.  */
+    links.sort((a, b) => (a.bottom - a.top) - (b.bottom - b.top) || a.top - b.top);
+    let lanes = [];
+    for(let link of links) {
+        let k = 0;
+        for(;; k++) {
+            let used = lanes[k] || [];
+            let free = used.every((o) => link.bottom < o.top || o.bottom < link.top);
+            if(free) {
+                break;
+            }
+        }
+        lanes[k] = (lanes[k] || []).concat([link]);
+        link.x = edge + LANE_GAP + LANE_GAP * k;
+    }
+
+    /*
+     *  Draw them on a grid of direction bits, then as glyphs
+     */
+    let bits = {};
+    let fixed = {};
+    let join = (y, x, b) => {
+        let key = `${y},${x}`;
+        bits[key] = (bits[key] || 0) | b;
+    };
+    let hline = (y, x1, x2) => {
+        for(let x = x1; x <= x2; x++) {
+            join(y, x, (x > x1 ? L : 0) | (x < x2 ? R : 0));
+        }
+    };
+    let vline = (x, y1, y2) => {
+        for(let y = y1; y <= y2; y++) {
+            join(y, x, (y > y1 ? U : 0) | (y < y2 ? D : 0));
+        }
+    };
+    for(let link of links) {
+        hline(link.from, edge + 2, link.x);
+        hline(link.to, edge + 2, link.x);
+        vline(link.x, link.top, link.bottom);
+        fixed[`${link.from},${edge + 2}`] = "◀";
+    }
+
+    let out = lines.map((line, y) => {
+        let chars = Array.from(line);
+        for(let key of Object.keys(bits)) {
+            let [ky, kx] = key.split(",").map(Number);
+            if(ky !== y) {
+                continue;
+            }
+            while(chars.length <= kx) {
+                chars.push(" ");
+            }
+            chars[kx] = fixed[key] || GLYPH[bits[key]] || " ";
+        }
+        return chars.join("").replace(/\s+$/, "");
+    });
+
+    while(out.length && out[out.length - 1] === "") {
+        out.pop();
+    }
+    return out.join("\n");
+}
+
+
+export {
+    schema_to_diagram,
+};

package/src/schema_to_diagram.test.js

@@ -0,0 +1,107 @@
+/***********************************************************************
+ *          schema_to_diagram.test.js
+ *
+ *      The graph of a schema as text, pinned on a small schema that has
+ *      every case: a self-referent hook, a hook to another topic, one
+ *      hook filling two topics, a pkey2, a tkey, required and inherited
+ *      fields, and the main topic.
+ ***********************************************************************/
+import { describe, test, expect } from "vitest";
+import { schema_to_diagram } from "./schema_to_diagram.js";
+
+
+const SCHEMA = {
+    id: "treedb_sample",
+    schema_version: "4",
+    topics: [
+        {
+            id: "departments",
+            pkey: "id",
+            main_topic: true,
+            cols: {
+                id:             {type: "string", flag: ["persistent", "required"]},
+                departments:    {type: "dict", flag: ["hook"], hook: {departments: "department_id"}},
+                department_id:  {type: "string", flag: ["fkey"]},
+                users:          {type: "dict", flag: ["hook"], hook: {users: "departments"}},
+                managers:       {type: "list", flag: ["hook"],
+                                 hook: {users: "manager", departments: "manager"}},
+                manager:        {type: "array", flag: ["fkey"]},
+            }
+        },
+        {
+            id: "users",
+            pkey: "id",
+            pkey2s: "name",
+            tkey: "tm",
+            cols: {
+                id:             {type: "string", flag: "required"},
+                name:           {type: "string", flag: ["persistent"]},
+                enabled:        {type: "boolean", flag: ["persistent", "inherit"]},
+                tm:             {type: "integer", flag: ["time"]},
+                departments:    {type: "array", flag: ["fkey"]},
+                manager:        {type: "array", flag: ["fkey"]},
+            }
+        },
+    ]
+};
+
+const EXPECTED = `treedb_sample  (schema_version 4)
+
+{}  dict hook   (N unique children)
+[]  list hook   (n not-unique children)
+()  string hook (1 unique child)
+(↖) 1 fkey      (1 parent)
+[↖] n fkeys     (n parents)
+{↖} N fkeys     (N parents)
+
+(2) pkey2 - secondary key
+(t) tkey  - time key
+*   field required
+=   field inherited
+
+
+          departments  (main_topic)
+        ┌───────────────────────────┐
+        │* id                       │
+        │            departments {} │ ◀─┐
+        │         department_id (↖) │ ──┘
+        │                  users {} │ ◀─────┐
+        │               managers [] │ ◀─┬───┼───┐
+        │               manager [↖] │ ──┘   │   │
+        └───────────────────────────┘       │   │
+                                            │   │
+                    users                   │   │
+        ┌───────────────────────────┐       │   │
+        │* id                       │       │   │
+        │  name (2)                 │       │   │
+        │= enabled                  │       │   │
+        │  tm (t)                   │       │   │
+        │           departments [↖] │ ──────┘   │
+        │               manager [↖] │ ──────────┘
+        └───────────────────────────┘`;
+
+
+describe("schema_to_diagram", () => {
+    const diagram = schema_to_diagram(SCHEMA);
+
+    test("the whole picture", () => {
+        expect(diagram).toBe(EXPECTED);
+    });
+
+    test("no line ends in a space", () => {
+        for(const line of diagram.split("\n")) {
+            expect(line).toBe(line.trimEnd());
+        }
+    });
+
+    test("a link to a column that does not exist is not drawn", () => {
+        const broken = JSON.parse(JSON.stringify(SCHEMA));
+        broken.topics[0].cols.users.hook = {users: "nowhere"};
+        expect(schema_to_diagram(broken)).not.toContain("◀─────┐");
+    });
+
+    test("nothing to draw is an empty string, not a throw", () => {
+        expect(schema_to_diagram(null)).toBe("");
+        expect(schema_to_diagram({id: "x"})).toBe("");
+    });
+});