@phren/cli 0.1.48 → 0.1.50

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.
@@ -0,0 +1,51 @@
1
+ /**
2
+ * Speech bubbles on the graph canvas.
3
+ *
4
+ * Two uses, one primitive. Press space on a node and its whole text opens in
5
+ * a bubble beside it, wrapped wide enough to actually read, because the side
6
+ * pane is a column and a long finding does not fit in a column. In watch
7
+ * mode, a recall that just landed gets a small bubble at its node for a few
8
+ * seconds, so what phren is remembering shows where it lives rather than only
9
+ * in a feed. Pure geometry and strings; the view draws the result.
10
+ */
11
+ export type BubbleSide = "left" | "right" | "above" | "below";
12
+ export interface BubblePlacement {
13
+ col: number;
14
+ row: number;
15
+ width: number;
16
+ height: number;
17
+ /** Which side of the anchor the bubble sits on. */
18
+ side: BubbleSide;
19
+ /** For left/right: the bubble row level with the anchor, where the tail attaches. */
20
+ tailRow: number;
21
+ /** For above/below: the bubble column level with the anchor. */
22
+ tailCol: number;
23
+ }
24
+ /** How long a recall's bubble stays at its node before the feed alone carries it. */
25
+ export declare const LIVE_BUBBLE_MS = 6000;
26
+ /** Cells the border and inner padding add around the text. */
27
+ export declare const BUBBLE_CHROME_COLS = 4;
28
+ export declare const BUBBLE_CHROME_ROWS = 2;
29
+ /**
30
+ * Where to put a bubble of the given text size next to an anchor cell. Prefers
31
+ * beside the anchor on the side with room, then above or below it, and never
32
+ * covers the anchor itself: a bubble that hides the node it is about has
33
+ * failed at its one job. Returns null when it could never fit, so the caller
34
+ * shrinks the text.
35
+ */
36
+ export declare function placeBubble(anchor: {
37
+ col: number;
38
+ row: number;
39
+ }, cols: number, rows: number, innerWidth: number, innerHeight: number): BubblePlacement | null;
40
+ export interface BubbleStyle {
41
+ title?: string;
42
+ footer?: string;
43
+ /** Applied to the border and chrome; the text carries its own styling. */
44
+ frame?: (s: string) => string;
45
+ }
46
+ /**
47
+ * The bubble's rows, each exactly `innerWidth + 4` cells wide. Beside the
48
+ * anchor, the tail is a `┤` / `├` on the border row level with it; above or
49
+ * below, a `┬` / `┴` on the cap, on the anchor's column.
50
+ */
51
+ export declare function bubbleRows(lines: string[], innerWidth: number, placement: Pick<BubblePlacement, "side" | "tailRow" | "tailCol" | "row" | "col">, style?: BubbleStyle): string[];
@@ -0,0 +1,98 @@
1
+ /**
2
+ * Speech bubbles on the graph canvas.
3
+ *
4
+ * Two uses, one primitive. Press space on a node and its whole text opens in
5
+ * a bubble beside it, wrapped wide enough to actually read, because the side
6
+ * pane is a column and a long finding does not fit in a column. In watch
7
+ * mode, a recall that just landed gets a small bubble at its node for a few
8
+ * seconds, so what phren is remembering shows where it lives rather than only
9
+ * in a feed. Pure geometry and strings; the view draws the result.
10
+ */
11
+ import { displayWidth, padToWidth } from "../render.js";
12
+ /** How long a recall's bubble stays at its node before the feed alone carries it. */
13
+ export const LIVE_BUBBLE_MS = 6000;
14
+ /** Cells the border and inner padding add around the text. */
15
+ export const BUBBLE_CHROME_COLS = 4;
16
+ export const BUBBLE_CHROME_ROWS = 2;
17
+ /**
18
+ * Where to put a bubble of the given text size next to an anchor cell. Prefers
19
+ * beside the anchor on the side with room, then above or below it, and never
20
+ * covers the anchor itself: a bubble that hides the node it is about has
21
+ * failed at its one job. Returns null when it could never fit, so the caller
22
+ * shrinks the text.
23
+ */
24
+ export function placeBubble(anchor, cols, rows, innerWidth, innerHeight) {
25
+ const width = innerWidth + BUBBLE_CHROME_COLS;
26
+ const height = innerHeight + BUBBLE_CHROME_ROWS;
27
+ if (width > cols || height > rows)
28
+ return null;
29
+ const gap = 2;
30
+ const clampRow = (r) => Math.max(0, Math.min(rows - height, r));
31
+ const clampCol = (c) => Math.max(0, Math.min(cols - width, c));
32
+ const beside = (side) => {
33
+ const col = side === "right" ? anchor.col + 1 + gap : anchor.col - gap - width;
34
+ const row = clampRow(anchor.row - Math.floor(height / 2));
35
+ const tailRow = Math.max(row + 1, Math.min(row + height - 2, anchor.row));
36
+ return { col, row, width, height, side, tailRow, tailCol: side === "right" ? col : col + width - 1 };
37
+ };
38
+ if (cols - (anchor.col + 1 + gap) >= width)
39
+ return beside("right");
40
+ if (anchor.col - gap >= width)
41
+ return beside("left");
42
+ // No room beside it: go above or below, whichever has the space, and slide
43
+ // sideways within the canvas while keeping the tail on the anchor's column.
44
+ const stacked = (side) => {
45
+ const row = side === "below" ? anchor.row + 1 + 1 : anchor.row - 1 - height;
46
+ const col = clampCol(anchor.col - Math.floor(width / 2));
47
+ const tailCol = Math.max(col + 1, Math.min(col + width - 2, anchor.col));
48
+ return { col, row, width, height, side, tailRow: side === "below" ? row : row + height - 1, tailCol };
49
+ };
50
+ if (rows - (anchor.row + 2) >= height)
51
+ return stacked("below");
52
+ if (anchor.row - 1 >= height)
53
+ return stacked("above");
54
+ return null;
55
+ }
56
+ /**
57
+ * The bubble's rows, each exactly `innerWidth + 4` cells wide. Beside the
58
+ * anchor, the tail is a `┤` / `├` on the border row level with it; above or
59
+ * below, a `┬` / `┴` on the cap, on the anchor's column.
60
+ */
61
+ export function bubbleRows(lines, innerWidth, placement, style = {}) {
62
+ const frame = style.frame ?? ((s) => s);
63
+ const cap = (label, left, right, tail) => {
64
+ const span = innerWidth + 2;
65
+ let bar;
66
+ let styledLabel = "";
67
+ if (!label || displayWidth(label) > innerWidth - 1) {
68
+ bar = Array.from({ length: span }, () => "─");
69
+ }
70
+ else {
71
+ // "─ label ─…": the label is spliced in after one bar cell.
72
+ bar = Array.from({ length: span }, () => "─");
73
+ styledLabel = label;
74
+ }
75
+ if (tail !== null) {
76
+ const at = placement.tailCol - placement.col - 1;
77
+ if (at >= 0 && at < span)
78
+ bar[at] = tail;
79
+ }
80
+ if (!styledLabel)
81
+ return frame(`${left}${bar.join("")}${right}`);
82
+ const labelWidth = displayWidth(styledLabel);
83
+ // Keep the tail if it falls outside the label's span; the label wins otherwise.
84
+ const head = bar.slice(0, 1).join("");
85
+ const tailPart = bar.slice(1 + 1 + labelWidth + 1).join("");
86
+ return `${frame(`${left}${head} `)}${styledLabel}${frame(` ${tailPart}${right}`)}`;
87
+ };
88
+ const out = [cap(style.title, "╭", "╮", placement.side === "below" ? "┴" : null)];
89
+ lines.forEach((line, i) => {
90
+ const rowIndex = placement.row + 1 + i;
91
+ const tail = rowIndex === placement.tailRow;
92
+ const left = frame(tail && placement.side === "right" ? "┤" : "│");
93
+ const right = frame(tail && placement.side === "left" ? "├" : "│");
94
+ out.push(`${left} ${padToWidth(line, innerWidth)} ${right}`);
95
+ });
96
+ out.push(cap(style.footer, "╰", "╯", placement.side === "above" ? "┬" : null));
97
+ return out;
98
+ }
@@ -58,6 +58,13 @@ export declare class BrailleCanvas {
58
58
  * of cells written (0 when the text starts off-canvas).
59
59
  */
60
60
  putText(col: number, row: number, text: string, sgr?: string): number;
61
+ /**
62
+ * Overlay a line that already carries ANSI styling, one cell per visible
63
+ * character. Each cell records the full attribute state in force at that
64
+ * point (everything since the last reset), so the renderer can switch
65
+ * styles cell by cell without leaking bold or colour into the neighbours.
66
+ */
67
+ putStyled(col: number, row: number, styled: string): number;
61
68
  /** Every cell in a rectangle is overlaid with a space, hiding dots underneath (pane backdrop). */
62
69
  clearRect(col: number, row: number, width: number, height: number): void;
63
70
  render(): string[];
@@ -205,6 +205,61 @@ export class BrailleCanvas {
205
205
  }
206
206
  return written;
207
207
  }
208
+ /**
209
+ * Overlay a line that already carries ANSI styling, one cell per visible
210
+ * character. Each cell records the full attribute state in force at that
211
+ * point (everything since the last reset), so the renderer can switch
212
+ * styles cell by cell without leaking bold or colour into the neighbours.
213
+ */
214
+ putStyled(col, row, styled) {
215
+ if (row < 0 || row >= this.rows)
216
+ return 0;
217
+ let c = col;
218
+ let written = 0;
219
+ let state = "";
220
+ let i = 0;
221
+ while (i < styled.length) {
222
+ if (styled[i] === "\x1b") {
223
+ const end = styled.indexOf("m", i);
224
+ if (end === -1)
225
+ break;
226
+ const seq = styled.slice(i, end + 1);
227
+ state = seq === "\x1b[0m" || seq === "\x1b[m" ? "" : state + seq;
228
+ i = end + 1;
229
+ continue;
230
+ }
231
+ const cp = styled.codePointAt(i) ?? 32;
232
+ const raw = String.fromCodePoint(cp);
233
+ i += raw.length;
234
+ if (c >= this.cols)
235
+ break;
236
+ if (c >= 0) {
237
+ const width = displayWidth(raw);
238
+ if (width === 0)
239
+ continue;
240
+ if (width === 2) {
241
+ // A wide glyph owns two cells: the glyph in the first, an empty
242
+ // marker in the second so nothing else draws there and the row
243
+ // still adds up to the right width. At the edge it becomes a dot.
244
+ if (c + 1 >= this.cols) {
245
+ this.overlay[this.cell(c, row)] = { ch: "·", sgr: state };
246
+ written++;
247
+ c++;
248
+ continue;
249
+ }
250
+ this.overlay[this.cell(c, row)] = { ch: raw, sgr: state };
251
+ this.overlay[this.cell(c + 1, row)] = { ch: "", sgr: state };
252
+ written += 2;
253
+ c += 2;
254
+ continue;
255
+ }
256
+ this.overlay[this.cell(c, row)] = { ch: raw, sgr: state };
257
+ written++;
258
+ }
259
+ c++;
260
+ }
261
+ return written;
262
+ }
208
263
  /** Every cell in a rectangle is overlaid with a space, hiding dots underneath (pane backdrop). */
209
264
  clearRect(col, row, width, height) {
210
265
  for (let r = row; r < row + height; r++) {
@@ -10,7 +10,7 @@
10
10
  import type { GraphFilters, GraphModel, VisibleData } from "../../graph-core/model.js";
11
11
  import type { GraphPayload, NodeDetail, NodeKind, RuntimeNode } from "../../graph-core/types.js";
12
12
  import { type Point } from "./layout.js";
13
- import { GraphWatch } from "./watch.js";
13
+ import { GraphWatch, type ActivityItem } from "./watch.js";
14
14
  import { GraphAgents } from "./agents.js";
15
15
  import { GraphMascot } from "./mascot.js";
16
16
  /** Nodes drawn at once. Terminals have far fewer pixels than a browser tab. */
@@ -99,6 +99,8 @@ export declare class GraphController {
99
99
  readonly agents: GraphAgents;
100
100
  /** phren himself, who walks to whatever the store just touched. */
101
101
  readonly mascot: GraphMascot;
102
+ /** Space opens the selected node's full text in a bubble on the canvas. */
103
+ reader: boolean;
102
104
  watchEnabled: boolean;
103
105
  /**
104
106
  * Wall-clock ms of the last navigation keypress. While the user is driving,
@@ -111,6 +113,15 @@ export declare class GraphController {
111
113
  stopWatch(): void;
112
114
  /** Idempotent; the poller only runs while the Graph view is open. */
113
115
  startAgents(): void;
116
+ /**
117
+ * The recall that just landed, while it is still fresh enough to show at its
118
+ * node. Watch mode's feed lists everything; this is the one worth pointing at.
119
+ */
120
+ liveRecall(now?: number): {
121
+ nodeId: string;
122
+ item: ActivityItem;
123
+ age: number;
124
+ } | null;
114
125
  /**
115
126
  * Offer the overlay once per session when agents are actually running but it
116
127
  * is switched off. Shipping a feature off by default and never mentioning it
@@ -17,6 +17,7 @@ import { ForceSim, bounds } from "./layout.js";
17
17
  import { GraphWatch } from "./watch.js";
18
18
  import { GraphAgents } from "./agents.js";
19
19
  import { GraphMascot } from "./mascot.js";
20
+ import { LIVE_BUBBLE_MS } from "./bubble.js";
20
21
  /** Nodes drawn at once. Terminals have far fewer pixels than a browser tab. */
21
22
  export const TUI_NODE_LIMIT = 350;
22
23
  const ALL_TYPES = { project: true, finding: true, task: true, entity: true, reference: true };
@@ -97,6 +98,8 @@ export class GraphController {
97
98
  agents;
98
99
  /** phren himself, who walks to whatever the store just touched. */
99
100
  mascot = new GraphMascot();
101
+ /** Space opens the selected node's full text in a bubble on the canvas. */
102
+ reader = false;
100
103
  watchEnabled;
101
104
  /**
102
105
  * Wall-clock ms of the last navigation keypress. While the user is driving,
@@ -130,6 +133,25 @@ export class GraphController {
130
133
  return;
131
134
  this.agents.start(() => this.repaintHook?.());
132
135
  }
136
+ /**
137
+ * The recall that just landed, while it is still fresh enough to show at its
138
+ * node. Watch mode's feed lists everything; this is the one worth pointing at.
139
+ */
140
+ liveRecall(now = Date.now()) {
141
+ if (!this.watchEnabled || !this.watch.running)
142
+ return null;
143
+ for (const item of this.watch.activity) {
144
+ if (item.historical || !item.nodeId)
145
+ continue;
146
+ const age = now - item.seenAt;
147
+ if (age > LIVE_BUBBLE_MS)
148
+ return null;
149
+ if (!this.positions.has(item.nodeId))
150
+ return null;
151
+ return { nodeId: item.nodeId, item, age };
152
+ }
153
+ return null;
154
+ }
133
155
  /**
134
156
  * Offer the overlay once per session when agents are actually running but it
135
157
  * is switched off. Shipping a feature off by default and never mentioning it
@@ -426,6 +448,8 @@ export class GraphController {
426
448
  }
427
449
  animationFrame() {
428
450
  let busy = this.watch.hot;
451
+ if (this.liveRecall())
452
+ busy = true;
429
453
  if (this.mascot.step())
430
454
  busy = true;
431
455
  if (this.mascot.arrivalGlow() > 0)
@@ -476,6 +500,8 @@ export class GraphController {
476
500
  return nodes.sort((a, b) => nodeRank(b, this.filters, this.model.scores) - nodeRank(a, this.filters, this.model.scores));
477
501
  }
478
502
  select(nodeId, opts = {}) {
503
+ if (nodeId !== this.selectedId)
504
+ this.reader = false;
479
505
  this.selectedId = nodeId;
480
506
  if (nodeId) {
481
507
  this.mascot.walkTo(nodeId, this.positions);
@@ -764,7 +790,21 @@ export class GraphController {
764
790
  host.setMessage(` ${style.dim("open the 3D viewer in a browser:")} ${style.boldCyan("phren web-ui")}`);
765
791
  return true;
766
792
  }
793
+ if (key === " ") {
794
+ if (!this.selectedId) {
795
+ host.setMessage(` ${style.dim("select a node first — ↵ or 1-9")}`);
796
+ return true;
797
+ }
798
+ this.reader = !this.reader;
799
+ host.setMessage(this.reader ? ` ${style.dim("reading —")} ${style.boldCyan("␣")} ${style.dim("or")} ${style.boldCyan("esc")} ${style.dim("to close")}` : "");
800
+ return true;
801
+ }
767
802
  if (key === "\x1b") {
803
+ if (this.reader) {
804
+ this.reader = false;
805
+ host.setMessage("");
806
+ return true;
807
+ }
768
808
  if (this.agents.current) {
769
809
  this.agents.clearHighlight();
770
810
  host.setMessage(` ${style.dim("agent released")}`);
@@ -7,6 +7,12 @@
7
7
  * amber, search dims everything that does not match.
8
8
  */
9
9
  import type { GraphController } from "./controller.js";
10
+ /**
11
+ * The pane takes a share of a wide terminal rather than a fixed 34 columns:
12
+ * a finding wraps into far fewer lines at 50 cells than at 32, which is the
13
+ * difference between reading it and reading the first third of it.
14
+ */
15
+ export declare function paneWidthFor(width: number): number;
10
16
  /** Word-wrap plain text to `width` cells, at most `maxLines` lines, ellipsised. */
11
17
  export declare function wrapText(text: string, width: number, maxLines: number): string[];
12
18
  export declare function renderGraphView(controller: GraphController, width: number, height: number): string[];
@@ -12,8 +12,16 @@ import { displayWidth, padToWidth, style } from "../render.js";
12
12
  import { BrailleCanvas, blendHex, hexToSgr } from "./canvas.js";
13
13
  import { graphGlyphs } from "./glyphs.js";
14
14
  import { MASCOT_COLOR, MASCOT_SPARK } from "./mascot.js";
15
+ import { BUBBLE_CHROME_COLS, BUBBLE_CHROME_ROWS, LIVE_BUBBLE_MS, bubbleRows, placeBubble } from "./bubble.js";
15
16
  import { formatAge } from "./watch.js";
16
- const PANE_WIDTH = 34;
17
+ /**
18
+ * The pane takes a share of a wide terminal rather than a fixed 34 columns:
19
+ * a finding wraps into far fewer lines at 50 cells than at 32, which is the
20
+ * difference between reading it and reading the first third of it.
21
+ */
22
+ export function paneWidthFor(width) {
23
+ return Math.max(34, Math.min(58, Math.round(width * 0.36)));
24
+ }
17
25
  const WIDE_BREAKPOINT = 100;
18
26
  /** Ceiling for the narrow-terminal detail strip; it only takes what it fills. */
19
27
  const NARROW_STRIP_MAX = 6;
@@ -107,13 +115,14 @@ export function renderGraphView(controller, width, height) {
107
115
  // Build the strip first so it takes only the rows it fills; every row it
108
116
  // gives back goes to the graph, which is the part worth the space.
109
117
  const strip = !wide && selected ? renderStrip(controller, selected, width, NARROW_STRIP_MAX) : [];
110
- const canvasCols = wide ? width - PANE_WIDTH - 1 : width;
118
+ const paneWidth = paneWidthFor(width);
119
+ const canvasCols = wide ? width - paneWidth - 1 : width;
111
120
  const canvasRows = Math.max(4, height - strip.length);
112
121
  const canvasLines = drawCanvas(controller, canvasCols, canvasRows, selected);
113
122
  if (wide) {
114
- const pane = renderPane(controller, selected, PANE_WIDTH, canvasRows);
123
+ const pane = renderPane(controller, selected, paneWidth, canvasRows);
115
124
  const divider = style.dim("│");
116
- return canvasLines.map((line, i) => `${line}${divider}${padToWidth(pane[i] ?? "", PANE_WIDTH)}`);
125
+ return canvasLines.map((line, i) => `${line}${divider}${padToWidth(pane[i] ?? "", paneWidth)}`);
117
126
  }
118
127
  return [...canvasLines, ...strip.map((line) => padToWidth(line, width))];
119
128
  }
@@ -194,6 +203,12 @@ function drawCanvas(controller, cols, rows, selected) {
194
203
  controller.neighborsOf(selected.id).slice(0, 9).forEach((node, i) => neighborIndex.set(node.id, i + 1));
195
204
  const currentHit = searching ? controller.search.results[controller.search.index]?.id : undefined;
196
205
  const zoomedIn = Math.min(controller.camera.scaleX, controller.camera.scaleY) >= 5;
206
+ // Bubbles go down before labels so the labels flow around them; drawn after,
207
+ // a bubble clipped whatever label happened to be under it. They are painted
208
+ // once more at the very end, because node markers do not check for them.
209
+ const bubbles = planBubbles(controller, cols, rows, selected);
210
+ for (const b of bubbles)
211
+ paintBubble(canvas, b);
197
212
  const ranked = placed.slice().sort((a, b) => labelPriority(controller, b.node, selected, neighborIndex) - labelPriority(controller, a.node, selected, neighborIndex));
198
213
  const onCanvas = ({ x, y }) => {
199
214
  const col = Math.floor(x / 2);
@@ -322,18 +337,78 @@ function drawCanvas(controller, cols, rows, selected) {
322
337
  canvas.putText(perch[0], perch[1], "◕", sgr(MASCOT_COLOR, "\x1b[1m"));
323
338
  }
324
339
  }
340
+ for (const b of bubbles)
341
+ paintBubble(canvas, b);
325
342
  if (controller.refreshing) {
326
343
  const badge = " ⟳ refreshing ";
327
344
  canvas.putText(cols - displayWidth(badge), 0, badge, sgr(ACCENT_CYAN, "\x1b[2m"));
328
345
  }
329
346
  return canvas.render();
330
347
  }
331
- /**
332
- * Edges keep their own colour when the selection touches them, lifted toward
333
- * amber rather than replaced by it. Painting every attached edge solid amber
334
- * turned a selected project into a solid yellow fan — the more a node connected,
335
- * the less the highlight told you — so a hub is lifted least.
336
- */
348
+ function planBubbles(controller, cols, rows, selected) {
349
+ if (controller.reader && selected) {
350
+ const p = controller.positions.get(selected.id);
351
+ if (!p)
352
+ return [];
353
+ const text = selected.fullLabel || selected.label;
354
+ const anchor = toCell(controller.project(p));
355
+ const maxInner = Math.min(64, cols - BUBBLE_CHROME_COLS - 2);
356
+ const maxRows = rows - BUBBLE_CHROME_ROWS - 1;
357
+ if (maxInner < 12 || maxRows < 2)
358
+ return [];
359
+ const inner = Math.min(maxInner, Math.max(24, displayWidth(text)));
360
+ let lines = wrapText(text, inner, maxRows);
361
+ const meta = [selected.project, selected.topicLabel || selected.topicSlug, selected.date, selected.priority].filter(Boolean).join(" · ");
362
+ if (meta && lines.length < maxRows)
363
+ lines = [...lines, "", style.dim(sliceWidth(meta, inner))];
364
+ const width = Math.max(inner, ...lines.map((l) => displayWidth(l)));
365
+ const placement = placeBubble(anchor, cols, rows, width, lines.length);
366
+ if (!placement)
367
+ return [];
368
+ const color = selected.kind === "project" ? KIND_COLORS.project : selected.baseColor;
369
+ const title = `${colored(color, KIND_GLYPH[selected.kind])} ${style.bold(KIND_LABEL[selected.kind])}`;
370
+ return [{ placement, rows: bubbleRows(lines, width, placement, { title, footer: `${style.boldCyan("␣")} ${style.dim("close")}`, frame: (s) => colored(color, s) }), anchor, color }];
371
+ }
372
+ const live = controller.liveRecall();
373
+ if (!live)
374
+ return [];
375
+ const p = controller.positions.get(live.nodeId);
376
+ if (!p)
377
+ return [];
378
+ const text = live.item.event.snippet || live.item.event.filename || "";
379
+ if (!text)
380
+ return [];
381
+ const anchor = toCell(controller.project(p));
382
+ const inner = Math.min(40, cols - BUBBLE_CHROME_COLS - 2);
383
+ if (inner < 12 || rows < 6)
384
+ return [];
385
+ const fade = live.age / LIVE_BUBBLE_MS;
386
+ const ink = blendHex("#e2e8f0", BG_COLOR, fade * 0.6);
387
+ const edge = blendHex(ACCENT_CYAN, BG_COLOR, fade * 0.7);
388
+ const lines = wrapText(text, inner, 3).map((l) => colored(ink, l));
389
+ const width = Math.max(...lines.map((l) => displayWidth(l)), 12);
390
+ const placement = placeBubble(anchor, cols, rows, width, lines.length);
391
+ if (!placement)
392
+ return [];
393
+ const source = live.item.event.source || "lookup";
394
+ const title = `${colored(edge, "◉")} ${colored(SOURCE_COLOR[source] ?? "#7f8db3", source)} ${style.dim("·")} ${style.cyan(sliceWidth(live.item.event.project, Math.max(4, width - source.length - 6)))}`;
395
+ return [{ placement, rows: bubbleRows(lines, width, placement, { title, frame: (s) => colored(edge, s) }), anchor, color: edge }];
396
+ }
397
+ function toCell(d) {
398
+ return { col: Math.floor(d.x / 2), row: Math.floor(d.y / 4) };
399
+ }
400
+ /** Clear the dots under the bubble, draw its rows, and run a thread to the anchor. */
401
+ function paintBubble(canvas, { placement, rows, anchor, color }) {
402
+ canvas.clearRect(placement.col, placement.row, placement.width, placement.height);
403
+ rows.forEach((line, i) => canvas.putStyled(placement.col, placement.row + i, line));
404
+ // A dotted thread from the node to the tail, so the bubble is visibly *about* that node.
405
+ const from = { x: anchor.col * 2 + 1, y: anchor.row * 4 + 2 };
406
+ const to = placement.side === "right" ? { x: placement.col * 2, y: placement.tailRow * 4 + 2 }
407
+ : placement.side === "left" ? { x: (placement.col + placement.width) * 2 - 1, y: placement.tailRow * 4 + 2 }
408
+ : placement.side === "below" ? { x: placement.tailCol * 2 + 1, y: placement.row * 4 }
409
+ : { x: placement.tailCol * 2 + 1, y: (placement.row + placement.height) * 4 - 1 };
410
+ canvas.line(from.x, from.y, to.x, to.y, color, { z: 3, dotted: true });
411
+ }
337
412
  function edgeColor(controller, link, touchesSelected, lit, degree = 0) {
338
413
  let base;
339
414
  if (link.kind === "fragment")
@@ -400,8 +475,13 @@ function renderPane(controller, selected, width, height) {
400
475
  if (selected) {
401
476
  const detail = controller.detail(selected.id);
402
477
  push(`${colored(selected.kind === "project" ? KIND_COLORS.project : selected.baseColor, KIND_GLYPH[selected.kind])} ${style.bold(KIND_LABEL[selected.kind])}${selected.kind === "task" && selected.section ? style.dim(` ${selected.section.toLowerCase()}`) : ""}`);
403
- for (const line of wrapText(selected.fullLabel || selected.label, inner, watching ? 7 : 4))
478
+ const text = selected.fullLabel || selected.label;
479
+ const textBudget = Math.max(4, Math.floor(height * (watching ? 0.3 : 0.4)));
480
+ const wrapped = wrapText(text, inner, textBudget);
481
+ for (const line of wrapped)
404
482
  push(line);
483
+ if (wrapped.length && wrapped[wrapped.length - 1].endsWith("…") && !text.endsWith("…"))
484
+ push(`${style.boldCyan("␣")} ${style.dim("read all of it")}`);
405
485
  push();
406
486
  if (selected.kind !== "project" && selected.project)
407
487
  row("project", style.cyan(selected.project));
@@ -96,14 +96,27 @@ export function seedPositions(nodes, links, aspect = DEFAULT_ASPECT) {
96
96
  continue;
97
97
  leavesPer.set(owner, (leavesPer.get(owner) ?? 0) + 1);
98
98
  }
99
- const spread = Math.max(...projects.map((p) => clusterRadius(leavesPer.get(p.id) ?? 0)), IDEAL_DISTANCE);
100
- const packed = (projects.length * spread * 2.3) / (2 * Math.PI);
101
- const ring = Math.max(IDEAL_DISTANCE * 2.2, packed);
99
+ // Each project gets a slice of the ring proportional to its cluster, not an
100
+ // equal share. Equal slices gave a one-finding project the same forty
101
+ // degrees as a fifty-finding one, so small and new projects sat alone in
102
+ // empty space at full ring distance while the heavy clusters merged into a
103
+ // blob — "most of it in the middle, a few way out", and the camera fitted
104
+ // to the few. Small clusters also sit a little inside the ring, so their
105
+ // outer edge lines up with their neighbours' rather than their centre.
106
+ const radii = projects.map((p) => clusterRadius(leavesPer.get(p.id) ?? 0));
107
+ const spread = Math.max(...radii, IDEAL_DISTANCE);
108
+ const slices = radii.map((r) => r * 2.3);
109
+ const circumference = slices.reduce((sum, w) => sum + w, 0);
110
+ const ring = Math.max(IDEAL_DISTANCE * 2.2, circumference / (2 * Math.PI));
111
+ // Projects sit at the start of their slice, so equal clusters land exactly
112
+ // where the equal-slice ring put them (two projects side by side, not
113
+ // stacked, which is the worst case on a wide screen).
114
+ let offset = 0;
102
115
  projects.forEach((project, i) => {
103
- // Start a quarter turn in so two projects sit side by side rather than
104
- // stacked, which is the worst case on a wide screen.
105
- const angle = (i / Math.max(1, projects.length)) * Math.PI * 2;
106
- positions.set(project.id, { x: Math.cos(angle) * ring * ratio, y: Math.sin(angle) * ring });
116
+ const angle = (offset / Math.max(circumference, 1)) * Math.PI * 2;
117
+ offset += slices[i];
118
+ const radius = Math.max(IDEAL_DISTANCE * 1.6, ring - (spread - radii[i]) * 0.7);
119
+ positions.set(project.id, { x: Math.cos(angle) * radius * ratio, y: Math.sin(angle) * radius });
107
120
  });
108
121
  if (projects.length === 1)
109
122
  positions.set(projects[0].id, { x: 0, y: 0 });
@@ -276,7 +289,10 @@ export class ForceSim {
276
289
  if (this.isProject[i]) {
277
290
  // Hold the project on its ring. The error is measured in
278
291
  // aspect-corrected space so the restoring force preserves the wide
279
- // ellipse rather than pulling the layout back into a circle.
292
+ // ellipse rather than pulling the layout back into a circle. A soft
293
+ // spring on purpose: pinning the radius outright left the clusters no
294
+ // room to breathe once the node cap made them larger than the seeded
295
+ // ring allowed for, and a forty-project store folded into a fan.
280
296
  const nx = xs[i] / this.aspect;
281
297
  const ny = ys[i];
282
298
  const radius = Math.hypot(nx, ny);
@@ -250,7 +250,7 @@ export function shellHelpText() {
250
250
  ` ${style.bold("Tasks")} ${k("a")} ${d("add task")} ${k("d")} ${d("toggle active/queue")} ${k("↵")} ${d("mark complete")}`,
251
251
  ` ${style.bold("Findings")} ${k("a")} ${d("tell phren")} ${k("d")} ${d("delete selected")}`,
252
252
  ` ${style.bold("Review Queue")} ${k("↵")} ${d("inspect selected item")} ${d("(read-only)")}`,
253
- ` ${style.bold("Graph")} ${k("↑↓←→")} ${d("walk")} ${k("1-9")} ${d("neighbour")} ${k("↵")} ${d("select / focus")} ${k("w")} ${d("watch")}`,
253
+ ` ${style.bold("Graph")} ${k("↑↓←→")} ${d("walk")} ${k("1-9")} ${d("neighbour")} ${k("↵")} ${d("select / focus")} ${k("␣")} ${d("read in a bubble")} ${k("w")} ${d("watch")}`,
254
254
  ` ${" ".repeat(13)}${k("/")} ${d("search")} ${k("n N")} ${d("next / prev hit")} ${k("f")} ${d("filter")} ${k("[ ]")} ${d("project")}`,
255
255
  ` ${" ".repeat(13)}${k("+ -")} ${d("zoom")} ${k("0")} ${d("fit")} ${k("r")} ${d("re-lay out")} ${k("⇧↑↓←→")} ${d("pan")} ${k("o")} ${d("3D viewer")}`,
256
256
  ` ${style.bold("Skills")} ${k("e")} ${d("edit in $EDITOR")} ${k("E")} ${d("edit here")} ${k("t")} ${d("toggle enabled")} ${k("d")} ${d("remove")}`,
@@ -90,7 +90,7 @@ function renderBottomBar(state, navMode, inputCtx, inputBuf) {
90
90
  Skills: [`${k("↑↓")} ${d("move")}`, `${k("e")} ${d("edit")}`, `${k("t")} ${d("toggle")}`],
91
91
  Hooks: [`${k("↑↓")} ${d("move")}`, `${k("a")} ${d("enable")}`],
92
92
  Health: [`${k("↑↓")} ${d("scroll")}`],
93
- Graph: [`${k("↑↓←→")} ${d("walk")}`, `${k("↵")} ${d("select")}`, `${k("w")} ${d("watch")}`, `${k("a")} ${d("agents")}`],
93
+ Graph: [`${k("↑↓←→")} ${d("walk")}`, `${k("↵")} ${d("select")}`, `${k("␣")} ${d("read")}`, `${k("w")} ${d("watch")}`, `${k("a")} ${d("agents")}`],
94
94
  };
95
95
  const search = state.view === "Graph" ? `${k("/")} ${d("search")}` : `${k("/")} ${d("filter")}`;
96
96
  // `? keys` and `q quit` are the two you cannot afford to lose, so a narrow
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@phren/cli",
3
- "version": "0.1.48",
3
+ "version": "0.1.50",
4
4
  "description": "Knowledge layer for AI agents — CLI, MCP server, and data layer",
5
5
  "type": "module",
6
6
  "bin": {