@phren/cli 0.1.46 → 0.1.48

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,67 @@
1
+ /**
2
+ * Drawing for the shell's modal editor.
3
+ *
4
+ * The frame is painted whole on every key, so there is no real terminal cursor
5
+ * to move: the character under the cursor is drawn inverted instead.
6
+ */
7
+ import { displayWidth, lineViewport, padToWidth, style, truncateLine } from "./render.js";
8
+ const GUTTER = 5;
9
+ function modeBadge(state) {
10
+ switch (state.mode) {
11
+ case "insert": return style.boldGreen(" INSERT ");
12
+ case "command": return style.boldYellow(" COMMAND ");
13
+ default: return style.boldCyan(" NORMAL ");
14
+ }
15
+ }
16
+ /** The line with the cursor drawn on it, as inverse video. */
17
+ function withCursor(text, col, active) {
18
+ if (!active)
19
+ return text;
20
+ const chars = [...text];
21
+ const at = Math.min(col, chars.length);
22
+ const before = chars.slice(0, at).join("");
23
+ const under = chars[at] ?? " ";
24
+ const after = chars.slice(at + 1).join("");
25
+ return `${before}${style.invert(under)}${after}`;
26
+ }
27
+ export function renderEditor(state, width, height) {
28
+ const out = [];
29
+ const bodyHeight = Math.max(1, height - 2);
30
+ // Header: what is open, which mode, and whether it is unsaved.
31
+ const dirty = state.dirty ? style.boldYellow(" ●") : "";
32
+ const header = ` ${style.bold(state.label)}${dirty} ${modeBadge(state)}`;
33
+ out.push(padToWidth(truncateLine(header, width), width));
34
+ // Body, scrolled to keep the cursor in view.
35
+ const numbered = state.lines.map((text, i) => {
36
+ const active = i === state.cursor.line;
37
+ const gutter = active
38
+ ? style.boldCyan(String(i + 1).padStart(GUTTER - 1) + " ")
39
+ : style.dim(String(i + 1).padStart(GUTTER - 1) + " ");
40
+ const shown = withCursor(text, state.cursor.col, active && state.mode !== "command");
41
+ return `${gutter}${shown}`;
42
+ });
43
+ const vp = lineViewport(numbered, state.cursor.line, state.cursor.line, bodyHeight, 0);
44
+ for (const line of vp.lines)
45
+ out.push(padToWidth(truncateLine(line, width), width));
46
+ while (out.length < height - 1)
47
+ out.push(padToWidth("", width));
48
+ // Status: the command being typed wins, then a message, then position.
49
+ const position = `${state.cursor.line + 1},${state.cursor.col + 1}`;
50
+ let status;
51
+ if (state.mode === "command") {
52
+ status = ` ${style.boldCyan(state.command)}${style.cyan("█")}`;
53
+ }
54
+ else if (state.message) {
55
+ status = ` ${style.yellow(state.message)}`;
56
+ }
57
+ else {
58
+ const hint = state.mode === "insert"
59
+ ? style.dim("esc normal mode")
60
+ : style.dim(":w write · :q quit · i insert · / search");
61
+ status = ` ${hint}`;
62
+ }
63
+ const right = style.dim(position);
64
+ const pad = Math.max(1, width - displayWidth(status) - displayWidth(right) - 2);
65
+ out.push(padToWidth(truncateLine(`${status}${" ".repeat(pad)}${right}`, width), width));
66
+ return out.slice(0, height);
67
+ }
@@ -107,10 +107,16 @@ export async function startShell(phrenPath, profile, startup = {}) {
107
107
  await new Promise((resolve) => { rl.on("close", () => { shell.close(); resolve(); }); });
108
108
  return;
109
109
  }
110
- process.stdin.setRawMode(true);
111
- process.stdin.resume();
112
- process.stdin.setEncoding("utf8");
113
- enterFullscreen();
110
+ // Taking and releasing the terminal is written once and used twice: at
111
+ // startup and shutdown, and again either side of handing the terminal to an
112
+ // editor. Two copies of this would drift.
113
+ const grabTerminal = () => {
114
+ process.stdin.setRawMode(true);
115
+ process.stdin.resume();
116
+ process.stdin.setEncoding("utf8");
117
+ enterFullscreen();
118
+ };
119
+ grabTerminal();
114
120
  let exiting = false;
115
121
  let cleanedUp = false;
116
122
  // ── Painting ────────────────────────────────────────────────────────────
@@ -268,6 +274,27 @@ export async function startShell(phrenPath, profile, startup = {}) {
268
274
  process.once("SIGINT", onSignal);
269
275
  process.once("SIGTERM", onSignal);
270
276
  process.once("exit", onProcessExit);
277
+ // Hand the terminal to a child process (an editor) and take it back. The
278
+ // shell owns raw mode, the alternate screen and the stdin listener, so all
279
+ // three have to be unwound or the child and the key pump fight over input.
280
+ shell.setSuspendHandler(async (run) => {
281
+ if (exiting)
282
+ return;
283
+ process.stdin.removeListener("data", onData);
284
+ restoreTerminal();
285
+ try {
286
+ await run();
287
+ }
288
+ finally {
289
+ if (!exiting) {
290
+ grabTerminal();
291
+ process.stdin.on("data", onData);
292
+ // Anything typed at the child after it exited is not for us.
293
+ decoder.flush();
294
+ await repaint();
295
+ }
296
+ }
297
+ });
271
298
  try {
272
299
  await playStartupIntro(phrenPath, resolveStartupIntroPlan(phrenPath), waitForIntroKeypress);
273
300
  introKeyWaiter = undefined;
@@ -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;
@@ -12,6 +12,7 @@ import type { GraphPayload, NodeDetail, NodeKind, RuntimeNode } from "../../grap
12
12
  import { type Point } from "./layout.js";
13
13
  import { GraphWatch } 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,8 @@ 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;
100
102
  watchEnabled: boolean;
101
103
  /**
102
104
  * Wall-clock ms of the last navigation keypress. While the user is driving,
@@ -109,6 +111,13 @@ export declare class GraphController {
109
111
  stopWatch(): void;
110
112
  /** Idempotent; the poller only runs while the Graph view is open. */
111
113
  startAgents(): void;
114
+ /**
115
+ * Offer the overlay once per session when agents are actually running but it
116
+ * is switched off. Shipping a feature off by default and never mentioning it
117
+ * is the same as not shipping it.
118
+ */
119
+ agentHint(): string | null;
120
+ private offeredAgents;
112
121
  toggleAgents(): boolean;
113
122
  toggleWatch(): boolean;
114
123
  /** True while the user is actively driving, so the camera is left alone. */
@@ -16,6 +16,7 @@ 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";
19
20
  /** Nodes drawn at once. Terminals have far fewer pixels than a browser tab. */
20
21
  export const TUI_NODE_LIMIT = 350;
21
22
  const ALL_TYPES = { project: true, finding: true, task: true, entity: true, reference: true };
@@ -85,7 +86,6 @@ export class GraphController {
85
86
  timer = null;
86
87
  cameraTarget = null;
87
88
  /** Re-frame once the intro settle finishes so the whole map is in view. */
88
- fitOnSettle = false;
89
89
  /** Set by pan/zoom; until then a resize re-fits the whole map. */
90
90
  userMoved = false;
91
91
  builder;
@@ -95,6 +95,8 @@ export class GraphController {
95
95
  watch;
96
96
  /** Coding agents running on this machine, joined onto their projects. */
97
97
  agents;
98
+ /** phren himself, who walks to whatever the store just touched. */
99
+ mascot = new GraphMascot();
98
100
  watchEnabled;
99
101
  /**
100
102
  * Wall-clock ms of the last navigation keypress. While the user is driving,
@@ -128,6 +130,18 @@ export class GraphController {
128
130
  return;
129
131
  this.agents.start(() => this.repaintHook?.());
130
132
  }
133
+ /**
134
+ * Offer the overlay once per session when agents are actually running but it
135
+ * is switched off. Shipping a feature off by default and never mentioning it
136
+ * is the same as not shipping it.
137
+ */
138
+ agentHint() {
139
+ if (this.offeredAgents || this.agents.enabled || this.status !== "ready")
140
+ return null;
141
+ this.offeredAgents = true;
142
+ return this.agents.hasSomethingToShow() ? "agents are running on this machine" : null;
143
+ }
144
+ offeredAgents = false;
131
145
  toggleAgents() {
132
146
  if (this.agents.enabled) {
133
147
  this.agents.toggle();
@@ -159,6 +173,7 @@ export class GraphController {
159
173
  const nodeId = items[i].nodeId;
160
174
  if (!nodeId || !this.model.nodeById.has(nodeId))
161
175
  continue;
176
+ this.mascot.walkTo(nodeId, this.positions);
162
177
  if (!this.userDriving) {
163
178
  this.selectedId = nodeId;
164
179
  this.flyTo(nodeId);
@@ -280,20 +295,21 @@ export class GraphController {
280
295
  this.sim = new ForceSim(nodes, links, undefined, this.viewport.width / Math.max(1, this.viewport.height));
281
296
  if (warm && this.lastPositions.size)
282
297
  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
- }
298
+ this.mascot.reset();
299
+ // Settle before anyone sees it. Animating the relaxation instead — ticking
300
+ // a few steps, framing the half-settled positions, then letting the rest
301
+ // play out under a fixed camera — read as the whole cluster bouncing for a
302
+ // second every time a project came into focus. A layout change is a cut,
303
+ // not a motion; the camera flights are the only thing meant to move. It
304
+ // is cheap enough not to notice: under 10ms for a couple of hundred nodes,
305
+ // and the focused subset that [ ] shows is far smaller than that.
306
+ this.sim.settle();
307
+ if (!warm || !this.lastPositions.size)
308
+ this.fitAll();
309
+ // One frame through the loop repaints, then it stops itself unless the
310
+ // mascot, a flight or watch mode has something to show.
311
+ if (this.repaintHook)
290
312
  this.startAnimation();
291
- }
292
- else {
293
- this.sim.settle();
294
- if (fresh)
295
- this.fitAll();
296
- }
297
313
  }
298
314
  /**
299
315
  * The view reports its canvas size (in dots) before projecting. The first
@@ -304,11 +320,8 @@ export class GraphController {
304
320
  if (width === this.viewport.width && height === this.viewport.height)
305
321
  return;
306
322
  this.viewport = { width: Math.max(2, width), height: Math.max(4, height) };
307
- if (!this.userMoved) {
308
- const keepFlag = this.fitOnSettle;
323
+ if (!this.userMoved)
309
324
  this.fitAll();
310
- this.fitOnSettle = keepFlag;
311
- }
312
325
  else if (this.selectedId)
313
326
  this.keepInView(this.selectedId);
314
327
  }
@@ -325,7 +338,6 @@ export class GraphController {
325
338
  fitAll() {
326
339
  const box = bounds(this.positions.values());
327
340
  this.cameraTarget = null;
328
- this.fitOnSettle = false;
329
341
  this.userMoved = false;
330
342
  if (!box) {
331
343
  this.camera = { cx: 0, cy: 0, scaleX: 2, scaleY: 2 };
@@ -414,13 +426,17 @@ export class GraphController {
414
426
  }
415
427
  animationFrame() {
416
428
  let busy = this.watch.hot;
429
+ if (this.mascot.step())
430
+ busy = true;
431
+ if (this.mascot.arrivalGlow() > 0)
432
+ busy = true;
433
+ if (this.mascot.maybeWander(this.visible.nodes.map((node) => node.id), this.positions))
434
+ busy = true;
435
+ // Only a graph too large to settle within the tick budget gets here; it
436
+ // finishes relaxing quietly under whatever camera it was given.
417
437
  if (this.sim && !this.sim.settled) {
418
438
  this.sim.tick(3);
419
439
  busy = true;
420
- if (this.sim.settled && this.fitOnSettle && !this.cameraTarget) {
421
- this.fitAll();
422
- this.fitOnSettle = false;
423
- }
424
440
  }
425
441
  if (this.cameraTarget) {
426
442
  const t = this.cameraTarget;
@@ -462,6 +478,7 @@ export class GraphController {
462
478
  select(nodeId, opts = {}) {
463
479
  this.selectedId = nodeId;
464
480
  if (nodeId) {
481
+ this.mascot.walkTo(nodeId, this.positions);
465
482
  if (opts.fly)
466
483
  this.flyTo(nodeId);
467
484
  else
@@ -11,6 +11,7 @@ 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";
14
15
  import { formatAge } from "./watch.js";
15
16
  const PANE_WIDTH = 34;
16
17
  const WIDE_BREAKPOINT = 100;
@@ -147,6 +148,8 @@ function drawCanvas(controller, cols, rows, selected) {
147
148
  placed.push({ node, x: d.x, y: d.y });
148
149
  }
149
150
  const isLit = (id) => !searching || matches.has(id);
151
+ // How connected the selection is, so a hub's highlight stays readable.
152
+ const selectedDegree = selected ? (controller.model.visibleAdjacency.get(selected.id)?.size ?? 0) : 0;
150
153
  // Edges first so node dots win the cell colour.
151
154
  for (const link of controller.visible.links) {
152
155
  const a = projected.get(link.source);
@@ -154,7 +157,7 @@ function drawCanvas(controller, cols, rows, selected) {
154
157
  if (!a || !b)
155
158
  continue;
156
159
  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));
160
+ const color = edgeColor(controller, link, touchesSelected, isLit(link.source) && isLit(link.target), selectedDegree);
158
161
  canvas.line(a.x, a.y, b.x, b.y, color, { z: touchesSelected ? 2 : 0, dotted: link.kind === "contradicts" });
159
162
  }
160
163
  const watching = controller.watchEnabled && controller.watch.running;
@@ -294,15 +297,44 @@ function drawCanvas(controller, cols, rows, selected) {
294
297
  canvas.putText(col, row, mark, marker);
295
298
  }
296
299
  }
300
+ // phren, wherever he currently is. Drawn after everything else so he is
301
+ // never lost in the dot field — he is the thing you are meant to follow.
302
+ const mascotPos = controller.mascot.pos;
303
+ if (mascotPos) {
304
+ const d = controller.project(mascotPos);
305
+ const col = Math.floor(d.x / 2);
306
+ const row = Math.floor(d.y / 4);
307
+ if (col >= 0 && col < cols && row >= 0 && row < rows) {
308
+ const glow = controller.mascot.arrivalGlow();
309
+ // A cyan halo on arrival, fading out, so a landing reads at a glance.
310
+ if (glow > 0) {
311
+ for (let a = 0; a < 12; a++) {
312
+ const t = (a / 12) * Math.PI * 2;
313
+ canvas.setDot(d.x + Math.cos(t) * 5, d.y + Math.sin(t) * 4.5, blendHex(MASCOT_SPARK, BG_COLOR, 1 - glow), 5);
314
+ }
315
+ }
316
+ // He perches *beside* what he is visiting, never on top of it — sitting
317
+ // on the node would hide the very marker you are meant to be looking at.
318
+ const perch = [[col - 1, row], [col + 1, row], [col, row - 1], [col - 1, row - 1]]
319
+ .find(([c, r]) => canvas.isFree(c, r, 1)) ?? [col - 1, row];
320
+ if (glow > 0)
321
+ canvas.putText(perch[0], perch[1] - 1, "✦", sgr(blendHex(MASCOT_SPARK, BG_COLOR, 1 - glow), "\x1b[1m"));
322
+ canvas.putText(perch[0], perch[1], "◕", sgr(MASCOT_COLOR, "\x1b[1m"));
323
+ }
324
+ }
297
325
  if (controller.refreshing) {
298
326
  const badge = " ⟳ refreshing ";
299
327
  canvas.putText(cols - displayWidth(badge), 0, badge, sgr(ACCENT_CYAN, "\x1b[2m"));
300
328
  }
301
329
  return canvas.render();
302
330
  }
303
- function edgeColor(controller, link, touchesSelected, lit) {
304
- if (touchesSelected)
305
- return ACCENT_AMBER;
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
+ */
337
+ function edgeColor(controller, link, touchesSelected, lit, degree = 0) {
306
338
  let base;
307
339
  if (link.kind === "fragment")
308
340
  base = blendHex(ACCENT_CYAN, BG_COLOR, 0.45);
@@ -315,7 +347,11 @@ function edgeColor(controller, link, touchesSelected, lit) {
315
347
  const node = controller.model.nodeById.get(leaf);
316
348
  base = blendHex(node?.baseColor ?? KIND_COLORS.other, BG_COLOR, 0.55);
317
349
  }
318
- return lit ? base : blendHex(base, BG_COLOR, 0.6);
350
+ const shown = lit ? base : blendHex(base, BG_COLOR, 0.6);
351
+ if (!touchesSelected)
352
+ return shown;
353
+ const lift = degree > 24 ? 0.22 : degree > 8 ? 0.34 : 0.5;
354
+ return blendHex(shown, ACCENT_AMBER, lift);
319
355
  }
320
356
  /** How much of the store a project holds; decides which get named when space is short. */
321
357
  function projectWeight(node) {
@@ -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
+ }
@@ -34,6 +34,9 @@ export interface NavigationHost extends PaletteHost {
34
34
  name?: string;
35
35
  text?: string;
36
36
  line?: string;
37
+ path?: string;
38
+ scopeType?: string;
39
+ storePath?: string;
37
40
  }[];
38
41
  startInput(ctx: string, initial: string): void;
39
42
  inputMqId: string;
@@ -42,7 +45,25 @@ export interface NavigationHost extends PaletteHost {
42
45
  setFilter(value: string): void;
43
46
  /** The knowledge-graph view's controller (created on first use). */
44
47
  graph(): GraphController;
48
+ /** Run something with the terminal released; false when the host cannot. */
49
+ suspend(fn: () => Promise<void> | void): Promise<boolean>;
50
+ /** Open a file in the shell's own modal editor. */
51
+ openEditor(filePath: string, label: string, kind: "skill" | "claude", scope?: string): boolean;
45
52
  }
53
+ /**
54
+ * The file `e` and `E` edit for the current view. Skills edit their own
55
+ * markdown; a project edits the CLAUDE.md the store owns and symlinks into the
56
+ * repo, so editing here reaches every linked checkout.
57
+ */
58
+ export declare function editTargetFor(host: NavigationHost, item: {
59
+ name?: string;
60
+ path?: string;
61
+ storePath?: string;
62
+ } | undefined): {
63
+ path: string;
64
+ label: string;
65
+ kind: "skill" | "claude";
66
+ } | null;
46
67
  export declare function executePalette(host: PaletteHost, input: string): Promise<void>;
47
68
  export declare function completeInput(line: string, phrenPath: string, profile: string, state: ShellState): string[];
48
69
  export declare function getListItems(phrenPath: string, profile: string, state: ShellState, healthLineCount: number): {
@@ -50,6 +71,9 @@ export declare function getListItems(phrenPath: string, profile: string, state:
50
71
  name?: string;
51
72
  text?: string;
52
73
  line?: string;
74
+ path?: string;
75
+ scopeType?: string;
76
+ storePath?: string;
53
77
  }[];
54
78
  /**
55
79
  * Handle p/b/l/m/s/k/h shortcut keys that switch the active view.