glassbrain 0.2.0-alpha.1 → 0.2.0-alpha.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -22,24 +22,30 @@ lets you read one at a glance, and when the agent learns something, shows you ex
22
22
  ```json
23
23
  {
24
24
  "nodes": [
25
- { "id": "src", "label": "src", "kind": "folder" },
26
- { "id": "src/auth", "label": "auth", "kind": "folder", "parent": "src" },
25
+ { "id": "src", "label": "src", "kind": "folder", "parent": null },
26
+ { "id": "src/auth", "label": "auth", "kind": "folder", "parent": "src", "order": 1 },
27
27
  { "id": "src/auth/login.ts", "label": "login.ts", "kind": "file", "parent": "src/auth" },
28
- { "id": "src/db.ts", "label": "db.ts", "kind": "file", "parent": "src" }
28
+ { "id": "src/db.ts", "label": "db.ts", "kind": "file", "parent": "src", "order": 2 }
29
29
  ],
30
30
  "edges": [{ "source": "src/auth/login.ts", "target": "src/db.ts", "kind": "uses" }]
31
31
  }
32
32
  ```
33
33
 
34
- `parent` says what sits inside what; that is the whole structure. Everything else is an edge.
34
+ `parent` is required on every node (null for the one root) and says what sits inside what: that is
35
+ the whole structure. `order`, optional, turns the children of one node into a numbered list — the
36
+ layout reads it clockwise, and a numbered root *is* the 2.5D layer view. There is no layer field.
35
37
  A [JSON Schema](https://github.com/voidixyn/glassbrain/blob/main/schema/graph.schema.json) describes every field, and the CLI answers in a form an
36
- agent can act on:
38
+ agent can act on — every finding carries its repair:
37
39
 
38
40
  ```text
39
41
  $ npx glassbrain validate kg
40
- warn 2-filled/ Dangling edge: points to missing node src/session
42
+ error dangling-edge graph.json edge src/auth/login.ts → src/session points at the missing node src/session
43
+ an edge can only join nodes that exist. Add the node, or repoint the edge:
44
+ - { "source": "src/auth/login.ts", "target": "src/session" }
45
+ + { "source": "src/auth/login.ts", "target": "EXISTING_ID" }
41
46
 
42
- kg: 2 versions, 3 nodes, 1 edge — 0 errors, 1 warning
47
+ kg: 1 node, 1 edge — 1 error · 0 warnings · 0 infos
48
+ structure: 1 root · depth 2 · 1/1 parented · isomorphism 1.00
43
49
 
44
50
  $ npx glassbrain diff kg/1-skeleton kg/2-filled
45
51
  1-skeleton → 2-filled
@@ -82,7 +88,7 @@ That makes change the main event:
82
88
 
83
89
  Search ranks by how well a node matches, the detail panel renders the node's markdown, labels
84
90
  make room for each other instead of piling up, and [dark mode is computed](https://github.com/voidixyn/glassbrain/blob/main/docs/guide.md#color-hue-is-configured-everything-else-is-computed)
85
- from the light palette. Graphs with layers can be stood up in 2.5D:
91
+ from the light palette. A root whose children carry `order` opens as floors in 2.5D:
86
92
 
87
93
  ![Protocols, building blocks and products of the agent ecosystem, stacked in 2.5D](https://raw.githubusercontent.com/voidixyn/glassbrain/main/docs/media/layers.png)
88
94
 
package/dist/adapters.js CHANGED
@@ -29,7 +29,7 @@ var clean = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !==
29
29
  // adapters/graphify.ts
30
30
  var STRUCT = /* @__PURE__ */ new Set(["contains", "method"]);
31
31
  var NOTE = "rationale_for";
32
- var looksLike = (d) => isObj(d) && Array.isArray(d.nodes) && Array.isArray(d.links ?? d.edges) && (d.nodes.length === 0 || d.nodes.some((n) => isObj(n) && ("file_type" in n || "source_file" in n))) && !("layers" in d && "project" in d);
32
+ var looksLike = (d) => isObj(d) && Array.isArray(d.nodes) && Array.isArray(d.links ?? d.edges) && (Array.isArray(d.links) || d.nodes.some((n) => isObj(n) && "file_type" in n)) && !("layers" in d && "project" in d);
33
33
  var base = (p) => p.split("/").pop() ?? p;
34
34
  function convertGraphify(d, name) {
35
35
  const raw = d.nodes.filter(isObj);
@@ -106,6 +106,7 @@ function parsePhysical(origin, text) {
106
106
  label: String(n.label ?? n.name ?? n.id),
107
107
  kind: typeof n.kind === "string" ? n.kind : void 0,
108
108
  parent: ref(n.parent),
109
+ order: typeof n.order === "number" && Number.isFinite(n.order) ? n.order : void 0,
109
110
  layer: typeof n.layer === "string" ? n.layer : void 0,
110
111
  // Marks carried by the data itself (e.g. a placeholder "with no content yet"). They are data, not derived: when the profile's
111
112
  // `placeholderFlags` recognizes one, it is drawn as skeleton.
@@ -126,7 +127,8 @@ function parsePhysical(origin, text) {
126
127
  function toPhysical(model) {
127
128
  const clean = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== void 0 && v !== ""));
128
129
  return {
129
- nodes: model.nodes.map((n) => clean({ ...n.data, id: n.id, label: n.label, kind: n.kind, parent: n.parent, layer: n.layer })),
130
+ // `layer` is derived, never written: a file that gains it would freeze a view decision into the data.
131
+ nodes: model.nodes.map((n) => clean({ ...n.data, id: n.id, label: n.label, kind: n.kind, parent: n.parent, order: n.order })),
130
132
  edges: model.edges.map((e) => clean({ ...e.data, source: e.source, target: e.target, kind: e.kind, label: e.label, weight: e.weight }))
131
133
  };
132
134
  }
@@ -586,6 +588,7 @@ function buildElements(model, profile, opts = {}) {
586
588
  kind: n.kind ?? "",
587
589
  layer,
588
590
  origin: n.origin ?? null,
591
+ order: n.order ?? null,
589
592
  share: shareOf(n.id),
590
593
  leaves: leavesOf(n.id),
591
594
  detail: n.data ?? null,
@@ -50,6 +50,7 @@ var EN = {
50
50
  addNode: "Add node\u2026",
51
51
  addEdge: "Add edge\u2026",
52
52
  relayout: "Re-layout",
53
+ restructure: "Restructure",
53
54
  edit: "Edit",
54
55
  editNode: "Edit node",
55
56
  newNode: "New node",
@@ -52,17 +52,17 @@ import {
52
52
  unionSides,
53
53
  untheme,
54
54
  validateModel
55
- } from "./chunk-VCM766BZ.js";
55
+ } from "./chunk-7R6PO7AE.js";
56
56
  import {
57
57
  DetailPanel,
58
58
  I,
59
59
  Icon,
60
60
  StringsContext,
61
61
  useStrings
62
- } from "./chunk-37BAJC3L.js";
62
+ } from "./chunk-ZHPUQDOJ.js";
63
63
  import {
64
64
  EN
65
- } from "./chunk-EJURBBFC.js";
65
+ } from "./chunk-F3DN7SLR.js";
66
66
  import {
67
67
  inlinePool
68
68
  } from "./chunk-YGRPNAXE.js";
@@ -911,6 +911,159 @@ function resolveOverlaps(boxes, o = {}) {
911
911
  }
912
912
  }
913
913
 
914
+ // src/layout/order.ts
915
+ function readOrder(elements) {
916
+ const parentOf = /* @__PURE__ */ new Map();
917
+ const kids = /* @__PURE__ */ new Map();
918
+ const nodeIds = /* @__PURE__ */ new Set();
919
+ for (const el of elements) {
920
+ const id = el.data.id;
921
+ if (!id || el.data.source) continue;
922
+ nodeIds.add(id);
923
+ const parent = el.data.parent;
924
+ if (!parent) continue;
925
+ parentOf.set(id, parent);
926
+ const raw = el.data.order;
927
+ const order = typeof raw === "number" && Number.isFinite(raw) ? raw : null;
928
+ const arr = kids.get(parent);
929
+ arr ? arr.push({ id, order }) : kids.set(parent, [{ id, order }]);
930
+ }
931
+ const orderedKids = /* @__PURE__ */ new Map();
932
+ let any = false;
933
+ for (const [parent, list] of kids) {
934
+ if (list.length < 2 || list.some((k) => k.order === null)) continue;
935
+ const sorted = [...list].sort((a, b) => a.order - b.order).map((k) => k.id);
936
+ const seen = /* @__PURE__ */ new Set();
937
+ let unique = true;
938
+ for (const k of list) {
939
+ if (seen.has(k.order)) {
940
+ unique = false;
941
+ break;
942
+ }
943
+ seen.add(k.order);
944
+ }
945
+ if (!unique) continue;
946
+ orderedKids.set(parent, sorted);
947
+ any = true;
948
+ }
949
+ return any ? { parentOf, orderedKids, nodeIds, any } : null;
950
+ }
951
+ function hash01(id) {
952
+ let h = 2166136261;
953
+ for (let i = 0; i < id.length; i++) {
954
+ h ^= id.charCodeAt(i);
955
+ h = Math.imul(h, 16777619);
956
+ }
957
+ return (h >>> 0) % 1e5 / 1e5;
958
+ }
959
+ var TAU = Math.PI * 2;
960
+ var RING = 320;
961
+ function orderSeed(elements, info) {
962
+ const children = /* @__PURE__ */ new Map();
963
+ for (const [id, parent] of info.parentOf) {
964
+ const arr = children.get(parent);
965
+ arr ? arr.push(id) : children.set(parent, [id]);
966
+ }
967
+ const roots = [...info.nodeIds].filter((id) => !info.parentOf.has(id));
968
+ const weight = /* @__PURE__ */ new Map();
969
+ const weigh = (id, seen = /* @__PURE__ */ new Set()) => {
970
+ const hit = weight.get(id);
971
+ if (hit != null) return hit;
972
+ if (seen.has(id)) return 1;
973
+ seen.add(id);
974
+ let n = 1;
975
+ for (const k of children.get(id) ?? []) n += weigh(k, seen);
976
+ weight.set(id, n);
977
+ return n;
978
+ };
979
+ for (const id of info.nodeIds) weigh(id);
980
+ const out = {};
981
+ const place = (id, cx, cy, from, to, level) => {
982
+ const r = level * RING;
983
+ const mid = (from + to) / 2;
984
+ out[id] = { x: cx + Math.cos(mid) * r, y: cy + Math.sin(mid) * r };
985
+ const kids = children.get(id) ?? [];
986
+ if (!kids.length) return;
987
+ const ordered = info.orderedKids.get(id);
988
+ const list = ordered ?? kids;
989
+ const total = list.reduce((s, k) => s + weigh(k), 0) || 1;
990
+ let at = from;
991
+ for (const k of list) {
992
+ const span = (to - from) * weigh(k) / total;
993
+ const jitter = ordered ? 0 : (hash01(k) - 0.5) * span * 0.6;
994
+ const a = at + jitter;
995
+ place(k, cx, cy, a, a + span, level + 1);
996
+ at += span;
997
+ }
998
+ };
999
+ if (roots.length === 1) place(roots[0], 0, 0, -Math.PI / 2, Math.PI * 1.5, 0);
1000
+ else {
1001
+ roots.forEach((root, i) => {
1002
+ const from = -Math.PI / 2 + TAU * i / roots.length;
1003
+ place(root, 0, 0, from, from + TAU / roots.length, 0);
1004
+ });
1005
+ }
1006
+ return out;
1007
+ }
1008
+ var angle = (p) => Math.atan2(p.y, p.x);
1009
+ function enforceOrder(elements, info, positions) {
1010
+ const children = /* @__PURE__ */ new Map();
1011
+ for (const [id, parent] of info.parentOf) {
1012
+ const arr = children.get(parent);
1013
+ arr ? arr.push(id) : children.set(parent, [id]);
1014
+ }
1015
+ const out = {};
1016
+ for (const [id, p] of Object.entries(positions)) out[id] = { ...p };
1017
+ const weight = /* @__PURE__ */ new Map();
1018
+ const weigh = (id, seen = /* @__PURE__ */ new Set()) => {
1019
+ const hit = weight.get(id);
1020
+ if (hit != null) return hit;
1021
+ if (seen.has(id)) return 1;
1022
+ seen.add(id);
1023
+ let n = 1;
1024
+ for (const k of children.get(id) ?? []) n += weigh(k, seen);
1025
+ weight.set(id, n);
1026
+ return n;
1027
+ };
1028
+ const subtree = (id, acc = []) => {
1029
+ acc.push(id);
1030
+ for (const k of children.get(id) ?? []) subtree(k, acc);
1031
+ return acc;
1032
+ };
1033
+ const rotate = (ids, pivot, delta) => {
1034
+ if (Math.abs(delta) < 1e-6) return;
1035
+ const c = Math.cos(delta), s = Math.sin(delta);
1036
+ for (const id of ids) {
1037
+ const p = out[id];
1038
+ if (!p) continue;
1039
+ const dx = p.x - pivot.x, dy = p.y - pivot.y;
1040
+ out[id] = { x: pivot.x + dx * c - dy * s, y: pivot.y + dx * s + dy * c };
1041
+ }
1042
+ };
1043
+ const settle = (parent) => {
1044
+ const list = info.orderedKids.get(parent);
1045
+ const pivot = out[parent];
1046
+ if (!list || !pivot) return;
1047
+ const present = list.filter((id) => out[id]);
1048
+ if (present.length < 2) return;
1049
+ const total = present.reduce((s, id) => s + weigh(id), 0) || 1;
1050
+ let at = angle({ x: out[present[0]].x - pivot.x, y: out[present[0]].y - pivot.y });
1051
+ for (const id of present) {
1052
+ const p = out[id];
1053
+ const cur = angle({ x: p.x - pivot.x, y: p.y - pivot.y });
1054
+ let delta = at - cur;
1055
+ while (delta > Math.PI) delta -= TAU;
1056
+ while (delta < -Math.PI) delta += TAU;
1057
+ rotate(subtree(id), pivot, delta);
1058
+ at += TAU * weigh(id) / total;
1059
+ }
1060
+ for (const id of present) settle(id);
1061
+ };
1062
+ const roots = [...info.nodeIds].filter((id) => !info.parentOf.has(id));
1063
+ for (const root of roots) settle(root);
1064
+ return out;
1065
+ }
1066
+
914
1067
  // src/layout/engine.ts
915
1068
  var CACHE_PREFIX = "gb:pos:v3:";
916
1069
  var CACHE_KEEP = 16;
@@ -921,7 +1074,7 @@ function shapeHash(elements, salt) {
921
1074
  if (el.data._force === false) continue;
922
1075
  parts.push(`E ${el.data.source}>${el.data.target}`);
923
1076
  } else {
924
- parts.push(`N ${el.data.id}|${el.data.parent ?? ""}|${el.data._struct === false ? "a" : "s"}`);
1077
+ parts.push(`N ${el.data.id}|${el.data.parent ?? ""}|${el.data.order ?? ""}|${el.data._struct === false ? "a" : "s"}`);
925
1078
  }
926
1079
  }
927
1080
  parts.sort();
@@ -1161,14 +1314,17 @@ function computeLayout(req) {
1161
1314
  const owner = req.owner ?? ns;
1162
1315
  const current = inflight.get(owner);
1163
1316
  if (current) current.superseded = true;
1317
+ const order = readOrder(req.elements);
1318
+ const job = order && !req.seed ? { ...req, seed: orderSeed(req.elements, order) } : req;
1164
1319
  const run = { hash, superseded: false, promise: null };
1165
1320
  const runner = mode === "whole" ? runWhole : runDivide;
1166
- run.promise = runner(req, () => run.superseded).then((pos) => {
1321
+ run.promise = runner(job, () => run.superseded).then((pos) => {
1322
+ const settled = order ? enforceOrder(req.elements, order, pos) : pos;
1167
1323
  if (!run.stale) {
1168
- cachePut(hash, pos);
1169
- lastByNs.set(ns, { hash, pos });
1324
+ cachePut(hash, settled);
1325
+ lastByNs.set(ns, { hash, pos: settled });
1170
1326
  }
1171
- return pos;
1327
+ return settled;
1172
1328
  }).finally(() => {
1173
1329
  if (inflight.get(owner) === run) inflight.delete(owner);
1174
1330
  });
@@ -1856,7 +2012,7 @@ function Toolbar(p) {
1856
2012
  /* @__PURE__ */ jsx("span", { children: shortOrigin(view.origins[0]) }),
1857
2013
  /* @__PURE__ */ jsx("button", { "aria-label": t.allOrigins, title: t.allOrigins, onClick: () => setView({ origins: null }), children: /* @__PURE__ */ jsx(Icon, { d: I.x, size: 12 }) })
1858
2014
  ] }),
1859
- (originPick || p.onAdd || p.onRelayout) && /* @__PURE__ */ jsxs(ViewMenu, { foot: t.stats(p.stats.nodes, p.stats.edges), children: [
2015
+ (originPick || p.onAdd || p.onRelayout || p.onRestructure) && /* @__PURE__ */ jsxs(ViewMenu, { foot: t.stats(p.stats.nodes, p.stats.edges), children: [
1860
2016
  originPick && /* @__PURE__ */ jsxs("div", { className: "gb-panel-sec", children: [
1861
2017
  /* @__PURE__ */ jsx("div", { className: "gb-panel-h", children: t.origins }),
1862
2018
  /* @__PURE__ */ jsxs(
@@ -1876,7 +2032,10 @@ function Toolbar(p) {
1876
2032
  /* @__PURE__ */ jsx("button", { className: "gb-menu-item", onClick: () => p.onAdd("node"), disabled: p.busy, children: t.addNode }),
1877
2033
  /* @__PURE__ */ jsx("button", { className: "gb-menu-item", onClick: () => p.onAdd("edge"), disabled: p.busy, children: t.addEdge })
1878
2034
  ] }),
1879
- p.onRelayout && /* @__PURE__ */ jsx("div", { className: "gb-panel-sec gb-menu-list", children: /* @__PURE__ */ jsx("button", { className: "gb-menu-item", onClick: p.onRelayout, disabled: p.busy, children: t.relayout }) })
2035
+ (p.onRelayout || p.onRestructure) && /* @__PURE__ */ jsxs("div", { className: "gb-panel-sec gb-menu-list", children: [
2036
+ p.onRelayout && /* @__PURE__ */ jsx("button", { className: "gb-menu-item", onClick: p.onRelayout, disabled: p.busy, children: t.relayout }),
2037
+ p.onRestructure && /* @__PURE__ */ jsx("button", { className: "gb-menu-item", onClick: p.onRestructure, disabled: p.busy, children: t.restructure })
2038
+ ] })
1880
2039
  ] })
1881
2040
  ] });
1882
2041
  }
@@ -3577,6 +3736,7 @@ function GraphCanvas(props) {
3577
3736
  onEdit,
3578
3737
  renderEditor,
3579
3738
  resolveUrl,
3739
+ onRestructure,
3580
3740
  animate = true,
3581
3741
  matchKey,
3582
3742
  onTransition,
@@ -5518,7 +5678,8 @@ ${lt}`;
5518
5678
  onPick: pick,
5519
5679
  inputRef: searchInputRef,
5520
5680
  onAdd: editable ? startAdd : void 0,
5521
- onRelayout: controls.relayout && !diff ? relayout : void 0
5681
+ onRelayout: controls.relayout && !diff ? relayout : void 0,
5682
+ onRestructure: controls.relayout && !diff ? onRestructure : void 0
5522
5683
  }
5523
5684
  ),
5524
5685
  (note || model.errors.length > 0 || legend && !compact) && /* Bottom left: the host's caption (if any) on top, the legend below. Top left is tools, bottom right is the camera. */
@@ -1,6 +1,6 @@
1
1
  import {
2
2
  EN
3
- } from "./chunk-EJURBBFC.js";
3
+ } from "./chunk-F3DN7SLR.js";
4
4
 
5
5
  // src/react/i18n.ts
6
6
  import { createContext, useContext } from "react";