@phren/cli 0.1.47 → 0.1.49

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.
@@ -32,6 +32,12 @@ export declare class GraphAgents {
32
32
  constructor(phrenPath: string, profile: string, opts?: GraphAgentsOptions);
33
33
  get running(): boolean;
34
34
  private polledOnce;
35
+ /**
36
+ * Is there anything to show, without turning the overlay on? Used to offer
37
+ * the feature when agents are actually running, rather than leaving it as a
38
+ * key nobody presses.
39
+ */
40
+ hasSomethingToShow(): boolean;
35
41
  start(onUpdate: () => void): void;
36
42
  stop(): void;
37
43
  toggle(): boolean;
@@ -58,6 +58,19 @@ export class GraphAgents {
58
58
  return this.timer !== null || this.polledOnce;
59
59
  }
60
60
  polledOnce = false;
61
+ /**
62
+ * Is there anything to show, without turning the overlay on? Used to offer
63
+ * the feature when agents are actually running, rather than leaving it as a
64
+ * key nobody presses.
65
+ */
66
+ hasSomethingToShow() {
67
+ try {
68
+ return this.collectFn().length > 0;
69
+ }
70
+ catch {
71
+ return false;
72
+ }
73
+ }
61
74
  start(onUpdate) {
62
75
  if (!this.enabled || this.timer)
63
76
  return;
@@ -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,8 +10,9 @@
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
+ import { GraphMascot } from "./mascot.js";
15
16
  /** Nodes drawn at once. Terminals have far fewer pixels than a browser tab. */
16
17
  export declare const TUI_NODE_LIMIT = 350;
17
18
  export type GraphStatus = "idle" | "loading" | "ready" | "empty" | "error";
@@ -87,7 +88,6 @@ export declare class GraphController {
87
88
  private timer;
88
89
  private cameraTarget;
89
90
  /** Re-frame once the intro settle finishes so the whole map is in view. */
90
- private fitOnSettle;
91
91
  /** Set by pan/zoom; until then a resize re-fits the whole map. */
92
92
  private userMoved;
93
93
  private readonly builder;
@@ -97,6 +97,10 @@ export declare class GraphController {
97
97
  readonly watch: GraphWatch;
98
98
  /** Coding agents running on this machine, joined onto their projects. */
99
99
  readonly agents: GraphAgents;
100
+ /** phren himself, who walks to whatever the store just touched. */
101
+ readonly mascot: GraphMascot;
102
+ /** Space opens the selected node's full text in a bubble on the canvas. */
103
+ reader: boolean;
100
104
  watchEnabled: boolean;
101
105
  /**
102
106
  * Wall-clock ms of the last navigation keypress. While the user is driving,
@@ -109,6 +113,22 @@ export declare class GraphController {
109
113
  stopWatch(): void;
110
114
  /** Idempotent; the poller only runs while the Graph view is open. */
111
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;
125
+ /**
126
+ * Offer the overlay once per session when agents are actually running but it
127
+ * is switched off. Shipping a feature off by default and never mentioning it
128
+ * is the same as not shipping it.
129
+ */
130
+ agentHint(): string | null;
131
+ private offeredAgents;
112
132
  toggleAgents(): boolean;
113
133
  toggleWatch(): boolean;
114
134
  /** True while the user is actively driving, so the camera is left alone. */
@@ -16,6 +16,8 @@ import { style } from "../render.js";
16
16
  import { ForceSim, bounds } from "./layout.js";
17
17
  import { GraphWatch } from "./watch.js";
18
18
  import { GraphAgents } from "./agents.js";
19
+ import { GraphMascot } from "./mascot.js";
20
+ import { LIVE_BUBBLE_MS } from "./bubble.js";
19
21
  /** Nodes drawn at once. Terminals have far fewer pixels than a browser tab. */
20
22
  export const TUI_NODE_LIMIT = 350;
21
23
  const ALL_TYPES = { project: true, finding: true, task: true, entity: true, reference: true };
@@ -85,7 +87,6 @@ export class GraphController {
85
87
  timer = null;
86
88
  cameraTarget = null;
87
89
  /** Re-frame once the intro settle finishes so the whole map is in view. */
88
- fitOnSettle = false;
89
90
  /** Set by pan/zoom; until then a resize re-fits the whole map. */
90
91
  userMoved = false;
91
92
  builder;
@@ -95,6 +96,10 @@ export class GraphController {
95
96
  watch;
96
97
  /** Coding agents running on this machine, joined onto their projects. */
97
98
  agents;
99
+ /** phren himself, who walks to whatever the store just touched. */
100
+ mascot = new GraphMascot();
101
+ /** Space opens the selected node's full text in a bubble on the canvas. */
102
+ reader = false;
98
103
  watchEnabled;
99
104
  /**
100
105
  * Wall-clock ms of the last navigation keypress. While the user is driving,
@@ -128,6 +133,37 @@ export class GraphController {
128
133
  return;
129
134
  this.agents.start(() => this.repaintHook?.());
130
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
+ }
155
+ /**
156
+ * Offer the overlay once per session when agents are actually running but it
157
+ * is switched off. Shipping a feature off by default and never mentioning it
158
+ * is the same as not shipping it.
159
+ */
160
+ agentHint() {
161
+ if (this.offeredAgents || this.agents.enabled || this.status !== "ready")
162
+ return null;
163
+ this.offeredAgents = true;
164
+ return this.agents.hasSomethingToShow() ? "agents are running on this machine" : null;
165
+ }
166
+ offeredAgents = false;
131
167
  toggleAgents() {
132
168
  if (this.agents.enabled) {
133
169
  this.agents.toggle();
@@ -159,6 +195,7 @@ export class GraphController {
159
195
  const nodeId = items[i].nodeId;
160
196
  if (!nodeId || !this.model.nodeById.has(nodeId))
161
197
  continue;
198
+ this.mascot.walkTo(nodeId, this.positions);
162
199
  if (!this.userDriving) {
163
200
  this.selectedId = nodeId;
164
201
  this.flyTo(nodeId);
@@ -280,20 +317,21 @@ export class GraphController {
280
317
  this.sim = new ForceSim(nodes, links, undefined, this.viewport.width / Math.max(1, this.viewport.height));
281
318
  if (warm && this.lastPositions.size)
282
319
  this.sim.warmStart(this.lastPositions);
283
- const fresh = !warm || !this.lastPositions.size;
284
- if (this.repaintHook) {
285
- this.sim.tick(warm ? 12 : 40);
286
- if (fresh) {
287
- this.fitAll();
288
- this.fitOnSettle = true;
289
- }
320
+ this.mascot.reset();
321
+ // Settle before anyone sees it. Animating the relaxation instead — ticking
322
+ // a few steps, framing the half-settled positions, then letting the rest
323
+ // play out under a fixed camera — read as the whole cluster bouncing for a
324
+ // second every time a project came into focus. A layout change is a cut,
325
+ // not a motion; the camera flights are the only thing meant to move. It
326
+ // is cheap enough not to notice: under 10ms for a couple of hundred nodes,
327
+ // and the focused subset that [ ] shows is far smaller than that.
328
+ this.sim.settle();
329
+ if (!warm || !this.lastPositions.size)
330
+ this.fitAll();
331
+ // One frame through the loop repaints, then it stops itself unless the
332
+ // mascot, a flight or watch mode has something to show.
333
+ if (this.repaintHook)
290
334
  this.startAnimation();
291
- }
292
- else {
293
- this.sim.settle();
294
- if (fresh)
295
- this.fitAll();
296
- }
297
335
  }
298
336
  /**
299
337
  * The view reports its canvas size (in dots) before projecting. The first
@@ -304,11 +342,8 @@ export class GraphController {
304
342
  if (width === this.viewport.width && height === this.viewport.height)
305
343
  return;
306
344
  this.viewport = { width: Math.max(2, width), height: Math.max(4, height) };
307
- if (!this.userMoved) {
308
- const keepFlag = this.fitOnSettle;
345
+ if (!this.userMoved)
309
346
  this.fitAll();
310
- this.fitOnSettle = keepFlag;
311
- }
312
347
  else if (this.selectedId)
313
348
  this.keepInView(this.selectedId);
314
349
  }
@@ -325,7 +360,6 @@ export class GraphController {
325
360
  fitAll() {
326
361
  const box = bounds(this.positions.values());
327
362
  this.cameraTarget = null;
328
- this.fitOnSettle = false;
329
363
  this.userMoved = false;
330
364
  if (!box) {
331
365
  this.camera = { cx: 0, cy: 0, scaleX: 2, scaleY: 2 };
@@ -414,13 +448,19 @@ export class GraphController {
414
448
  }
415
449
  animationFrame() {
416
450
  let busy = this.watch.hot;
451
+ if (this.liveRecall())
452
+ busy = true;
453
+ if (this.mascot.step())
454
+ busy = true;
455
+ if (this.mascot.arrivalGlow() > 0)
456
+ busy = true;
457
+ if (this.mascot.maybeWander(this.visible.nodes.map((node) => node.id), this.positions))
458
+ busy = true;
459
+ // Only a graph too large to settle within the tick budget gets here; it
460
+ // finishes relaxing quietly under whatever camera it was given.
417
461
  if (this.sim && !this.sim.settled) {
418
462
  this.sim.tick(3);
419
463
  busy = true;
420
- if (this.sim.settled && this.fitOnSettle && !this.cameraTarget) {
421
- this.fitAll();
422
- this.fitOnSettle = false;
423
- }
424
464
  }
425
465
  if (this.cameraTarget) {
426
466
  const t = this.cameraTarget;
@@ -460,8 +500,11 @@ export class GraphController {
460
500
  return nodes.sort((a, b) => nodeRank(b, this.filters, this.model.scores) - nodeRank(a, this.filters, this.model.scores));
461
501
  }
462
502
  select(nodeId, opts = {}) {
503
+ if (nodeId !== this.selectedId)
504
+ this.reader = false;
463
505
  this.selectedId = nodeId;
464
506
  if (nodeId) {
507
+ this.mascot.walkTo(nodeId, this.positions);
465
508
  if (opts.fly)
466
509
  this.flyTo(nodeId);
467
510
  else
@@ -747,7 +790,21 @@ export class GraphController {
747
790
  host.setMessage(` ${style.dim("open the 3D viewer in a browser:")} ${style.boldCyan("phren web-ui")}`);
748
791
  return true;
749
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
+ }
750
802
  if (key === "\x1b") {
803
+ if (this.reader) {
804
+ this.reader = false;
805
+ host.setMessage("");
806
+ return true;
807
+ }
751
808
  if (this.agents.current) {
752
809
  this.agents.clearHighlight();
753
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[];
@@ -11,8 +11,17 @@ import { nodeRank } from "../../graph-core/model.js";
11
11
  import { displayWidth, padToWidth, style } from "../render.js";
12
12
  import { BrailleCanvas, blendHex, hexToSgr } from "./canvas.js";
13
13
  import { graphGlyphs } from "./glyphs.js";
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";
14
16
  import { formatAge } from "./watch.js";
15
- 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
+ }
16
25
  const WIDE_BREAKPOINT = 100;
17
26
  /** Ceiling for the narrow-terminal detail strip; it only takes what it fills. */
18
27
  const NARROW_STRIP_MAX = 6;
@@ -106,13 +115,14 @@ export function renderGraphView(controller, width, height) {
106
115
  // Build the strip first so it takes only the rows it fills; every row it
107
116
  // gives back goes to the graph, which is the part worth the space.
108
117
  const strip = !wide && selected ? renderStrip(controller, selected, width, NARROW_STRIP_MAX) : [];
109
- const canvasCols = wide ? width - PANE_WIDTH - 1 : width;
118
+ const paneWidth = paneWidthFor(width);
119
+ const canvasCols = wide ? width - paneWidth - 1 : width;
110
120
  const canvasRows = Math.max(4, height - strip.length);
111
121
  const canvasLines = drawCanvas(controller, canvasCols, canvasRows, selected);
112
122
  if (wide) {
113
- const pane = renderPane(controller, selected, PANE_WIDTH, canvasRows);
123
+ const pane = renderPane(controller, selected, paneWidth, canvasRows);
114
124
  const divider = style.dim("│");
115
- return canvasLines.map((line, i) => `${line}${divider}${padToWidth(pane[i] ?? "", PANE_WIDTH)}`);
125
+ return canvasLines.map((line, i) => `${line}${divider}${padToWidth(pane[i] ?? "", paneWidth)}`);
116
126
  }
117
127
  return [...canvasLines, ...strip.map((line) => padToWidth(line, width))];
118
128
  }
@@ -147,6 +157,8 @@ function drawCanvas(controller, cols, rows, selected) {
147
157
  placed.push({ node, x: d.x, y: d.y });
148
158
  }
149
159
  const isLit = (id) => !searching || matches.has(id);
160
+ // How connected the selection is, so a hub's highlight stays readable.
161
+ const selectedDegree = selected ? (controller.model.visibleAdjacency.get(selected.id)?.size ?? 0) : 0;
150
162
  // Edges first so node dots win the cell colour.
151
163
  for (const link of controller.visible.links) {
152
164
  const a = projected.get(link.source);
@@ -154,7 +166,7 @@ function drawCanvas(controller, cols, rows, selected) {
154
166
  if (!a || !b)
155
167
  continue;
156
168
  const touchesSelected = selected !== null && (link.source === selected.id || link.target === selected.id);
157
- const color = edgeColor(controller, link, touchesSelected, isLit(link.source) && isLit(link.target));
169
+ const color = edgeColor(controller, link, touchesSelected, isLit(link.source) && isLit(link.target), selectedDegree);
158
170
  canvas.line(a.x, a.y, b.x, b.y, color, { z: touchesSelected ? 2 : 0, dotted: link.kind === "contradicts" });
159
171
  }
160
172
  const watching = controller.watchEnabled && controller.watch.running;
@@ -191,6 +203,12 @@ function drawCanvas(controller, cols, rows, selected) {
191
203
  controller.neighborsOf(selected.id).slice(0, 9).forEach((node, i) => neighborIndex.set(node.id, i + 1));
192
204
  const currentHit = searching ? controller.search.results[controller.search.index]?.id : undefined;
193
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);
194
212
  const ranked = placed.slice().sort((a, b) => labelPriority(controller, b.node, selected, neighborIndex) - labelPriority(controller, a.node, selected, neighborIndex));
195
213
  const onCanvas = ({ x, y }) => {
196
214
  const col = Math.floor(x / 2);
@@ -294,15 +312,104 @@ function drawCanvas(controller, cols, rows, selected) {
294
312
  canvas.putText(col, row, mark, marker);
295
313
  }
296
314
  }
315
+ // phren, wherever he currently is. Drawn after everything else so he is
316
+ // never lost in the dot field — he is the thing you are meant to follow.
317
+ const mascotPos = controller.mascot.pos;
318
+ if (mascotPos) {
319
+ const d = controller.project(mascotPos);
320
+ const col = Math.floor(d.x / 2);
321
+ const row = Math.floor(d.y / 4);
322
+ if (col >= 0 && col < cols && row >= 0 && row < rows) {
323
+ const glow = controller.mascot.arrivalGlow();
324
+ // A cyan halo on arrival, fading out, so a landing reads at a glance.
325
+ if (glow > 0) {
326
+ for (let a = 0; a < 12; a++) {
327
+ const t = (a / 12) * Math.PI * 2;
328
+ canvas.setDot(d.x + Math.cos(t) * 5, d.y + Math.sin(t) * 4.5, blendHex(MASCOT_SPARK, BG_COLOR, 1 - glow), 5);
329
+ }
330
+ }
331
+ // He perches *beside* what he is visiting, never on top of it — sitting
332
+ // on the node would hide the very marker you are meant to be looking at.
333
+ const perch = [[col - 1, row], [col + 1, row], [col, row - 1], [col - 1, row - 1]]
334
+ .find(([c, r]) => canvas.isFree(c, r, 1)) ?? [col - 1, row];
335
+ if (glow > 0)
336
+ canvas.putText(perch[0], perch[1] - 1, "✦", sgr(blendHex(MASCOT_SPARK, BG_COLOR, 1 - glow), "\x1b[1m"));
337
+ canvas.putText(perch[0], perch[1], "◕", sgr(MASCOT_COLOR, "\x1b[1m"));
338
+ }
339
+ }
340
+ for (const b of bubbles)
341
+ paintBubble(canvas, b);
297
342
  if (controller.refreshing) {
298
343
  const badge = " ⟳ refreshing ";
299
344
  canvas.putText(cols - displayWidth(badge), 0, badge, sgr(ACCENT_CYAN, "\x1b[2m"));
300
345
  }
301
346
  return canvas.render();
302
347
  }
303
- function edgeColor(controller, link, touchesSelected, lit) {
304
- if (touchesSelected)
305
- return ACCENT_AMBER;
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
+ }
412
+ function edgeColor(controller, link, touchesSelected, lit, degree = 0) {
306
413
  let base;
307
414
  if (link.kind === "fragment")
308
415
  base = blendHex(ACCENT_CYAN, BG_COLOR, 0.45);
@@ -315,7 +422,11 @@ function edgeColor(controller, link, touchesSelected, lit) {
315
422
  const node = controller.model.nodeById.get(leaf);
316
423
  base = blendHex(node?.baseColor ?? KIND_COLORS.other, BG_COLOR, 0.55);
317
424
  }
318
- return lit ? base : blendHex(base, BG_COLOR, 0.6);
425
+ const shown = lit ? base : blendHex(base, BG_COLOR, 0.6);
426
+ if (!touchesSelected)
427
+ return shown;
428
+ const lift = degree > 24 ? 0.22 : degree > 8 ? 0.34 : 0.5;
429
+ return blendHex(shown, ACCENT_AMBER, lift);
319
430
  }
320
431
  /** How much of the store a project holds; decides which get named when space is short. */
321
432
  function projectWeight(node) {
@@ -364,8 +475,13 @@ function renderPane(controller, selected, width, height) {
364
475
  if (selected) {
365
476
  const detail = controller.detail(selected.id);
366
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()}`) : ""}`);
367
- 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)
368
482
  push(line);
483
+ if (wrapped.length && wrapped[wrapped.length - 1].endsWith("…") && !text.endsWith("…"))
484
+ push(`${style.boldCyan("␣")} ${style.dim("read all of it")}`);
369
485
  push();
370
486
  if (selected.kind !== "project" && selected.project)
371
487
  row("project", style.cyan(selected.project));
@@ -0,0 +1,45 @@
1
+ /**
2
+ * phren, on the graph.
3
+ *
4
+ * The web viewer has had him for a while (browser/graph/mascot.ts): small and
5
+ * calm, perching next to whatever you select, and walking to a memory the
6
+ * moment a lookup lands on it. This is the same behaviour in the terminal —
7
+ * when watch mode says something was read or written, he goes there, so what
8
+ * you are watching has a face rather than being an abstract pulse.
9
+ *
10
+ * Pure movement only: no drawing, no timers. The host steps him each frame.
11
+ */
12
+ import type { Point } from "./layout.js";
13
+ /** Mascot purple, matching the sprite the web viewer and the splash use. */
14
+ export declare const MASCOT_COLOR = "#9c8ff8";
15
+ /** The cyan he sparkles with on arrival, matching the live-pulse accent. */
16
+ export declare const MASCOT_SPARK = "#28d3f2";
17
+ export declare class GraphMascot {
18
+ /** Where he is, in world coordinates. Null until he first has somewhere to be. */
19
+ pos: Point | null;
20
+ /** The node he is heading for, or sitting at. */
21
+ targetNodeId: string | null;
22
+ private target;
23
+ private arrivedAt;
24
+ private lastEventAt;
25
+ private readonly now;
26
+ constructor(now?: () => number);
27
+ get moving(): boolean;
28
+ /**
29
+ * Send him to a node. `deliberate` marks the visits worth sparkling over —
30
+ * a lookup landing — as opposed to idle wandering.
31
+ */
32
+ walkTo(nodeId: string, positions: Map<string, Point>, deliberate?: boolean): void;
33
+ /** Advance one frame. Returns true while he still has somewhere to be. */
34
+ step(): boolean;
35
+ /**
36
+ * After a long enough quiet spell, drift to another node so the graph does
37
+ * not look frozen. Deterministic given the same inputs, so a test can drive
38
+ * it: the destination is chosen by stepping through the candidates.
39
+ */
40
+ maybeWander(candidates: string[], positions: Map<string, Point>): boolean;
41
+ /** 1 just after arriving, easing to 0 — the sparkle over his head. */
42
+ arrivalGlow(): number;
43
+ /** Forget where he was, so a rebuilt graph does not strand him mid-air. */
44
+ reset(): void;
45
+ }
@@ -0,0 +1,105 @@
1
+ /**
2
+ * phren, on the graph.
3
+ *
4
+ * The web viewer has had him for a while (browser/graph/mascot.ts): small and
5
+ * calm, perching next to whatever you select, and walking to a memory the
6
+ * moment a lookup lands on it. This is the same behaviour in the terminal —
7
+ * when watch mode says something was read or written, he goes there, so what
8
+ * you are watching has a face rather than being an abstract pulse.
9
+ *
10
+ * Pure movement only: no drawing, no timers. The host steps him each frame.
11
+ */
12
+ /** Mascot purple, matching the sprite the web viewer and the splash use. */
13
+ export const MASCOT_COLOR = "#9c8ff8";
14
+ /** The cyan he sparkles with on arrival, matching the live-pulse accent. */
15
+ export const MASCOT_SPARK = "#28d3f2";
16
+ /** How long the arrival sparkle lasts. */
17
+ const ARRIVAL_MS = 1400;
18
+ /** Quiet time before he wanders off on his own. */
19
+ const IDLE_AFTER_MS = 12_000;
20
+ /** Fraction of the remaining distance covered per frame. */
21
+ const EASE = 0.16;
22
+ /** Close enough to count as arrived, in world units. */
23
+ const ARRIVED = 0.6;
24
+ export class GraphMascot {
25
+ /** Where he is, in world coordinates. Null until he first has somewhere to be. */
26
+ pos = null;
27
+ /** The node he is heading for, or sitting at. */
28
+ targetNodeId = null;
29
+ target = null;
30
+ arrivedAt = 0;
31
+ lastEventAt = 0;
32
+ now;
33
+ constructor(now = Date.now) {
34
+ this.now = now;
35
+ this.lastEventAt = now();
36
+ }
37
+ get moving() {
38
+ return this.target !== null;
39
+ }
40
+ /**
41
+ * Send him to a node. `deliberate` marks the visits worth sparkling over —
42
+ * a lookup landing — as opposed to idle wandering.
43
+ */
44
+ walkTo(nodeId, positions, deliberate = true) {
45
+ const to = positions.get(nodeId);
46
+ if (!to)
47
+ return;
48
+ this.targetNodeId = nodeId;
49
+ this.target = { ...to };
50
+ // First appearance: no long walk in from nowhere, just arrive.
51
+ if (!this.pos)
52
+ this.pos = { ...to };
53
+ if (deliberate)
54
+ this.lastEventAt = this.now();
55
+ }
56
+ /** Advance one frame. Returns true while he still has somewhere to be. */
57
+ step() {
58
+ if (!this.pos || !this.target)
59
+ return false;
60
+ const dx = this.target.x - this.pos.x;
61
+ const dy = this.target.y - this.pos.y;
62
+ if (Math.hypot(dx, dy) < ARRIVED) {
63
+ this.pos = { ...this.target };
64
+ this.target = null;
65
+ this.arrivedAt = this.now();
66
+ return false;
67
+ }
68
+ this.pos = { x: this.pos.x + dx * EASE, y: this.pos.y + dy * EASE };
69
+ return true;
70
+ }
71
+ /**
72
+ * After a long enough quiet spell, drift to another node so the graph does
73
+ * not look frozen. Deterministic given the same inputs, so a test can drive
74
+ * it: the destination is chosen by stepping through the candidates.
75
+ */
76
+ maybeWander(candidates, positions) {
77
+ if (this.moving || !candidates.length)
78
+ return false;
79
+ if (this.now() - this.lastEventAt < IDLE_AFTER_MS)
80
+ return false;
81
+ const here = candidates.indexOf(this.targetNodeId ?? "");
82
+ const next = candidates[(here + 1 + candidates.length) % candidates.length];
83
+ if (!next || next === this.targetNodeId)
84
+ return false;
85
+ this.walkTo(next, positions, false);
86
+ this.lastEventAt = this.now();
87
+ return true;
88
+ }
89
+ /** 1 just after arriving, easing to 0 — the sparkle over his head. */
90
+ arrivalGlow() {
91
+ if (!this.arrivedAt)
92
+ return 0;
93
+ const age = this.now() - this.arrivedAt;
94
+ if (age >= ARRIVAL_MS)
95
+ return 0;
96
+ return 1 - age / ARRIVAL_MS;
97
+ }
98
+ /** Forget where he was, so a rebuilt graph does not strand him mid-air. */
99
+ reset() {
100
+ this.pos = null;
101
+ this.target = null;
102
+ this.targetNodeId = null;
103
+ this.arrivedAt = 0;
104
+ }
105
+ }
@@ -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
@@ -733,6 +733,9 @@ export async function renderShell(ctx, navMode, inputCtx, inputBuf, showHelp, he
733
733
  }
734
734
  const controller = ctx.graph();
735
735
  await controller.ensureData();
736
+ const offer = controller.agentHint();
737
+ if (offer)
738
+ message = ` ${style.boldCyan("▲")} ${style.dim(`${offer} — press`)} ${style.boldCyan("a")} ${style.dim("to see them")}`;
736
739
  contentLines = renderGraphView(controller, renderWidth(), height);
737
740
  break;
738
741
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@phren/cli",
3
- "version": "0.1.47",
3
+ "version": "0.1.49",
4
4
  "description": "Knowledge layer for AI agents — CLI, MCP server, and data layer",
5
5
  "type": "module",
6
6
  "bin": {