@phren/cli 0.1.42 → 0.1.45

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.
Files changed (97) hide show
  1. package/dist/capabilities/cli.js +1 -1
  2. package/dist/capabilities/mcp.js +1 -1
  3. package/dist/capabilities/vscode.js +3 -3
  4. package/dist/capabilities/web-ui.js +29 -29
  5. package/dist/cli/actions.d.ts +1 -1
  6. package/dist/cli/actions.js +7 -2
  7. package/dist/cli/config-proactivity.d.ts +6 -6
  8. package/dist/cli/hooks-output.js +15 -6
  9. package/dist/cli/hooks.d.ts +1 -1
  10. package/dist/cli/hooks.js +16 -5
  11. package/dist/cli/session-stop.d.ts +1 -1
  12. package/dist/cli/session-tool-hook.d.ts +1 -1
  13. package/dist/cli-registry.js +1 -1
  14. package/dist/data/access.js +2 -1
  15. package/dist/generated/memory-ui-graph.browser.js +481 -318
  16. package/dist/governance/locks.js +6 -0
  17. package/dist/governance/scores.d.ts +9 -1
  18. package/dist/governance/scores.js +12 -1
  19. package/dist/graph-core/index.d.ts +2 -0
  20. package/dist/graph-core/index.js +2 -0
  21. package/dist/graph-core/model.d.ts +84 -0
  22. package/dist/graph-core/model.js +355 -0
  23. package/dist/graph-core/types.d.ts +110 -0
  24. package/dist/graph-core/types.js +43 -0
  25. package/dist/index.js +4 -1
  26. package/dist/init/init-uninstall.d.ts +1 -0
  27. package/dist/init/init-uninstall.js +13 -3
  28. package/dist/init/setup.js +11 -4
  29. package/dist/link/context.js +2 -1
  30. package/dist/link/link.js +3 -2
  31. package/dist/link/skills.js +2 -1
  32. package/dist/memory-ui-graph.runtime.js +481 -318
  33. package/dist/phren-core.d.ts +16 -0
  34. package/dist/phren-core.js +21 -0
  35. package/dist/phren-paths.js +8 -4
  36. package/dist/profile-store.d.ts +2 -0
  37. package/dist/profile-store.js +16 -19
  38. package/dist/project-config.js +2 -1
  39. package/dist/shared/fragment-graph.js +7 -2
  40. package/dist/shared/index.js +1 -1
  41. package/dist/shared/retrieval.d.ts +38 -0
  42. package/dist/shared/retrieval.js +62 -4
  43. package/dist/shell/entry.d.ts +10 -2
  44. package/dist/shell/entry.js +128 -97
  45. package/dist/shell/graph/canvas.d.ts +64 -0
  46. package/dist/shell/graph/canvas.js +256 -0
  47. package/dist/shell/graph/controller.d.ts +164 -0
  48. package/dist/shell/graph/controller.js +645 -0
  49. package/dist/shell/graph/glyphs.d.ts +12 -0
  50. package/dist/shell/graph/glyphs.js +31 -0
  51. package/dist/shell/graph/graph-view.d.ts +12 -0
  52. package/dist/shell/graph/graph-view.js +408 -0
  53. package/dist/shell/graph/layout.d.ts +68 -0
  54. package/dist/shell/graph/layout.js +267 -0
  55. package/dist/shell/input.d.ts +4 -1
  56. package/dist/shell/input.js +28 -5
  57. package/dist/shell/intro.d.ts +37 -0
  58. package/dist/shell/intro.js +82 -0
  59. package/dist/shell/keys.d.ts +36 -0
  60. package/dist/shell/keys.js +107 -0
  61. package/dist/shell/logo-fx.d.ts +35 -0
  62. package/dist/shell/logo-fx.js +128 -0
  63. package/dist/shell/render.d.ts +34 -1
  64. package/dist/shell/render.js +220 -66
  65. package/dist/shell/shell.d.ts +13 -1
  66. package/dist/shell/shell.js +61 -10
  67. package/dist/shell/startup.d.ts +37 -0
  68. package/dist/shell/startup.js +105 -0
  69. package/dist/shell/state-store.d.ts +1 -1
  70. package/dist/shell/state-store.js +1 -1
  71. package/dist/shell/types.js +1 -0
  72. package/dist/shell/view.d.ts +3 -0
  73. package/dist/shell/view.js +26 -4
  74. package/dist/store-registry.d.ts +13 -0
  75. package/dist/store-registry.js +109 -37
  76. package/dist/test-global-setup.d.ts +1 -0
  77. package/dist/test-global-setup.js +22 -0
  78. package/dist/tool-registry.js +1 -0
  79. package/dist/tools/memory.js +12 -5
  80. package/dist/tools/ops.js +1 -1
  81. package/dist/ui/data.d.ts +15 -7
  82. package/dist/ui/data.js +102 -3
  83. package/dist/utils-fts.js +2 -1
  84. package/dist/utils-helpers.d.ts +1 -0
  85. package/dist/utils-helpers.js +6 -0
  86. package/dist/utils.d.ts +1 -1
  87. package/dist/utils.js +1 -1
  88. package/package.json +38 -7
  89. package/starter/global/skills/phren-consolidate/SKILL.md +152 -0
  90. package/starter/global/skills/phren-discover/SKILL.md +175 -0
  91. package/starter/global/skills/phren-init/SKILL.md +216 -0
  92. package/starter/global/skills/phren-profiles/SKILL.md +121 -0
  93. package/starter/global/skills/phren-sync/SKILL.md +261 -0
  94. package/dist/init-uninstall.d.ts +0 -3
  95. package/dist/init-uninstall.js +0 -514
  96. package/dist/init-walkthrough.d.ts +0 -55
  97. package/dist/init-walkthrough.js +0 -524
@@ -0,0 +1,128 @@
1
+ /**
2
+ * Text effects for the phren wordmark on the shell splash.
3
+ *
4
+ * Inspired by TerminalTextEffects: the block-letter logo is revealed with a
5
+ * "decrypt" scramble that settles cell by cell into the real glyphs, and the
6
+ * finished wordmark carries a slow light-beam shimmer while the splash holds.
7
+ *
8
+ * Two rules keep the letters intact:
9
+ * - scramble glyphs come only from the same box-drawing / block family the
10
+ * logo already uses, so every cell stays one column wide;
11
+ * - every frame is a pure function of (progress, cell) with hash-based
12
+ * jitter, so the reveal is deterministic and the final frame equals the
13
+ * plain gradient logo exactly.
14
+ *
15
+ * This module is imported by render.ts and must not import from it.
16
+ */
17
+ const RESET = "\x1b[0m";
18
+ // Block-letter logo for the splash.
19
+ export const PHREN_LOGO = [
20
+ "██████╗ ██╗ ██╗██████╗ ███████╗███╗ ██╗",
21
+ "██╔══██╗██║ ██║██╔══██╗██╔════╝████╗ ██║",
22
+ "██████╔╝███████║██████╔╝█████╗ ██╔██╗ ██║",
23
+ "██╔═══╝ ██╔══██║██╔══██╗██╔══╝ ██║╚██╗██║",
24
+ "██║ ██║ ██║██║ ██║███████╗██║ ╚████║",
25
+ "╚═╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚══════╝╚═╝ ╚═══╝",
26
+ ];
27
+ // Neural gradient palette: purple → blue → cyan (256-color ANSI)
28
+ export const PHREN_GRADIENT = [
29
+ "\x1b[38;5;93m", // vivid purple
30
+ "\x1b[38;5;99m", // purple-blue
31
+ "\x1b[38;5;105m", // blue-purple
32
+ "\x1b[38;5;111m", // sky blue
33
+ "\x1b[38;5;75m", // dodger blue
34
+ "\x1b[38;5;81m", // cyan-blue
35
+ "\x1b[38;5;87m", // bright cyan
36
+ ];
37
+ /** Glyphs the scramble may show: the logo's own alphabet plus shade blocks. All one cell wide. */
38
+ const SCRAMBLE_POOL = [..."░▒▓█▀▄╗╔╝╚║═╬╪╫┼"];
39
+ /** Dim greys the unsettled cells cycle through. */
40
+ const SCRAMBLE_COLORS = ["\x1b[38;5;238m", "\x1b[38;5;240m", "\x1b[38;5;243m", "\x1b[38;5;245m"];
41
+ const FLASH = "\x1b[38;5;231m";
42
+ const SHIMMER = ["\x1b[38;5;123m", "\x1b[38;5;159m", "\x1b[38;5;195m", "\x1b[38;5;159m", "\x1b[38;5;123m"];
43
+ /** Frames in the reveal and the delay between them. ~1s total. */
44
+ export const LOGO_REVEAL_FRAMES = 22;
45
+ export const LOGO_REVEAL_FRAME_MS = 45;
46
+ export const LOGO_SHIMMER_FRAME_MS = 110;
47
+ function hash(a, b, c) {
48
+ let h = 2166136261;
49
+ for (const v of [a, b, c]) {
50
+ h ^= v + 0x9e3779b9;
51
+ h = Math.imul(h, 16777619);
52
+ }
53
+ return (h >>> 0) / 4294967296;
54
+ }
55
+ /**
56
+ * Split a logo line into cells with the same colour assignment `gradient()`
57
+ * in render.ts uses (bucket by position among non-space characters).
58
+ */
59
+ function cells(line) {
60
+ const chars = [...line];
61
+ const nonSpace = chars.filter((ch) => !/\s/.test(ch)).length;
62
+ let vi = 0;
63
+ return chars.map((ch) => {
64
+ if (/\s/.test(ch))
65
+ return { ch, colorIdx: -1, along: 0 };
66
+ const colorIdx = Math.min(Math.floor((vi * PHREN_GRADIENT.length) / nonSpace), PHREN_GRADIENT.length - 1);
67
+ const along = nonSpace > 1 ? vi / (nonSpace - 1) : 0;
68
+ vi++;
69
+ return { ch, colorIdx, along };
70
+ });
71
+ }
72
+ const LOGO_CELLS = PHREN_LOGO.map(cells);
73
+ function paint(row, color) {
74
+ let out = "";
75
+ let current = "";
76
+ row.forEach((cell, col) => {
77
+ if (cell.colorIdx < 0) {
78
+ out += cell.ch;
79
+ return;
80
+ }
81
+ const { ch, sgr } = color(cell, col);
82
+ if (sgr !== current) {
83
+ out += sgr;
84
+ current = sgr;
85
+ }
86
+ out += ch;
87
+ });
88
+ return out + RESET;
89
+ }
90
+ /** The finished wordmark: identical colours to `gradient(line)` in render.ts. */
91
+ export function logoPlain() {
92
+ return LOGO_CELLS.map((row) => paint(row, (cell) => ({ ch: cell.ch, sgr: PHREN_GRADIENT[cell.colorIdx] })));
93
+ }
94
+ /**
95
+ * Decrypt reveal at `progress` in [0, 1]. Cells settle left to right with
96
+ * per-cell jitter; a settling cell flashes white for a moment; unsettled
97
+ * cells churn through scramble glyphs. At progress >= 1 this is `logoPlain()`.
98
+ */
99
+ export function logoRevealFrame(progress) {
100
+ const p = Math.max(0, Math.min(1, progress));
101
+ const tick = Math.floor(p * 40);
102
+ return LOGO_CELLS.map((row, r) => paint(row, (cell, c) => {
103
+ const settleAt = cell.along * 0.72 + hash(r, c, 1) * 0.24;
104
+ if (p >= 1 || p >= settleAt + 0.07)
105
+ return { ch: cell.ch, sgr: PHREN_GRADIENT[cell.colorIdx] };
106
+ if (p >= settleAt)
107
+ return { ch: cell.ch, sgr: FLASH };
108
+ const glyph = SCRAMBLE_POOL[Math.floor(hash(r, c, tick) * SCRAMBLE_POOL.length)];
109
+ const shade = SCRAMBLE_COLORS[Math.floor(hash(c, r, tick + 7) * SCRAMBLE_COLORS.length)];
110
+ return { ch: glyph, sgr: shade };
111
+ }));
112
+ }
113
+ /**
114
+ * A soft beam of light sweeping across the finished wordmark. `tick` is any
115
+ * increasing integer; the sweep loops with a pause between passes.
116
+ */
117
+ export function logoShimmerFrame(tick) {
118
+ const width = Math.max(...PHREN_LOGO.map((line) => [...line].length));
119
+ const period = width + 26;
120
+ const x = ((tick * 2) % period) - 8;
121
+ return LOGO_CELLS.map((row, r) => paint(row, (cell, c) => {
122
+ // The beam leans like a slash: each row is offset one column.
123
+ const d = c + r - x;
124
+ if (d >= -2 && d <= 2)
125
+ return { ch: cell.ch, sgr: SHIMMER[d + 2] };
126
+ return { ch: cell.ch, sgr: PHREN_GRADIENT[cell.colorIdx] };
127
+ }));
128
+ }
@@ -29,6 +29,8 @@ export declare const style: {
29
29
  export declare function badge(label: string, colorFn: (s: string) => string): string;
30
30
  export declare function separator(width?: number): string;
31
31
  export declare function stripAnsi(s: string): string;
32
+ /** Terminal cells occupied by `s`, ignoring any ANSI escape codes it contains. */
33
+ export declare function displayWidth(s: string): number;
32
34
  export declare function padToWidth(s: string, width: number): string;
33
35
  export declare function truncateLine(s: string, cols: number): string;
34
36
  export declare function renderWidth(columns?: number): number;
@@ -46,5 +48,36 @@ export declare function lineViewport(allLines: string[], cursorFirstLine: number
46
48
  export declare function shellHelpText(): string;
47
49
  export declare function clearScreen(): void;
48
50
  export declare function clearToEnd(): void;
49
- export declare function shellStartupFrames(version: string): string[];
51
+ /** Switch to the alternate screen buffer and put the terminal in TUI mode. */
52
+ export declare function enterFullscreen(): void;
53
+ /** Undo enterFullscreen(). Safe to call more than once. */
54
+ export declare function exitFullscreen(): void;
55
+ /**
56
+ * Write one frame as a single synchronized write.
57
+ *
58
+ * The old path issued three separate writes (home, body, erase-to-end) with the
59
+ * cursor visible, which let a concurrent repaint interleave between them and
60
+ * dragged the caret across the screen on every keystroke.
61
+ */
62
+ export declare function paintFrame(frame: string): void;
63
+ /**
64
+ * Lay out one splash frame from the character art the caller supplies (a live
65
+ * animation frame, or the static art).
66
+ *
67
+ * Every branch is chosen so the result fits the terminal it is about to be
68
+ * painted into: the wide layout needs room for art + gap + logo, the stacked
69
+ * one drops the logo rather than clipping it, and a terminal too short for the
70
+ * character drops the character rather than pushing the tagline off the bottom.
71
+ * A frame taller than the screen would scroll the alternate buffer, and once it
72
+ * scrolls every later cursor-home repaint lands on shifted rows, stacking the
73
+ * frames on top of each other.
74
+ */
75
+ export declare function composeStartupFrame(artLines: string[], version: string, hint?: string, logo?: string[], tagline?: string): string[];
76
+ /**
77
+ * Clamp a frame to the terminal before painting: truncate each line to the
78
+ * render width, erase whatever the previous frame left to the right of it, and
79
+ * drop rows past the bottom so the frame can never scroll the screen.
80
+ */
81
+ export declare function fitFrame(lines: string[]): string;
82
+ export declare function shellStartupFrames(version: string, tagline?: string): string[];
50
83
  export {};
@@ -37,22 +37,103 @@ export function separator(width = 50) {
37
37
  export function stripAnsi(s) {
38
38
  return s.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "");
39
39
  }
40
+ // ── Display width ────────────────────────────────────────────────────────────
41
+ // String length counts UTF-16 code units, which is not what a terminal draws:
42
+ // combining marks occupy no cell, and East Asian Wide / emoji-presentation
43
+ // characters occupy two. Measuring with .length under-counts those, so a line
44
+ // built to "fit" overflows, the terminal autowraps it, and every row below
45
+ // shifts — which corrupts the whole in-place redraw. Ambiguous-width characters
46
+ // are counted as one cell, matching the default in Windows Terminal and most
47
+ // Unix terminals.
48
+ const ZERO_WIDTH = /^\p{M}$/u;
49
+ // East Asian Wide/Fullwidth blocks plus the BMP characters with
50
+ // Emoji_Presentation=Yes (which terminals draw double-wide).
51
+ const WIDE_RANGES = [
52
+ [0x1100, 0x115f], [0x231a, 0x231b], [0x23e9, 0x23ec], [0x23f0, 0x23f0],
53
+ [0x23f3, 0x23f3], [0x25fd, 0x25fe], [0x2614, 0x2615], [0x2648, 0x2653],
54
+ [0x267f, 0x267f], [0x2693, 0x2693], [0x26a1, 0x26a1], [0x26aa, 0x26ab],
55
+ [0x26bd, 0x26be], [0x26c4, 0x26c5], [0x26ce, 0x26ce], [0x26d4, 0x26d4],
56
+ [0x26ea, 0x26ea], [0x26f2, 0x26f3], [0x26f5, 0x26f5], [0x26fa, 0x26fa],
57
+ [0x26fd, 0x26fd], [0x2705, 0x2705], [0x270a, 0x270b], [0x2728, 0x2728],
58
+ [0x274c, 0x274c], [0x274e, 0x274e], [0x2753, 0x2755], [0x2757, 0x2757],
59
+ [0x2795, 0x2797], [0x27b0, 0x27b0], [0x27bf, 0x27bf], [0x2b1b, 0x2b1c],
60
+ [0x2b50, 0x2b50], [0x2b55, 0x2b55], [0x2e80, 0x303e], [0x3041, 0x33ff],
61
+ [0x3400, 0x4dbf], [0x4e00, 0x9fff], [0xa000, 0xa4cf], [0xa960, 0xa97f],
62
+ [0xac00, 0xd7a3], [0xf900, 0xfaff], [0xfe10, 0xfe19], [0xfe30, 0xfe6f],
63
+ [0xff00, 0xff60], [0xffe0, 0xffe6], [0x1f004, 0x1f004], [0x1f0cf, 0x1f0cf],
64
+ [0x1f18e, 0x1f18e], [0x1f191, 0x1f19a], [0x1f300, 0x1f64f],
65
+ [0x1f680, 0x1f6ff], [0x1f7e0, 0x1f7eb], [0x1f900, 0x1f9ff],
66
+ [0x1fa70, 0x1faff], [0x20000, 0x3fffd],
67
+ ];
68
+ function isWideCodePoint(cp) {
69
+ let lo = 0, hi = WIDE_RANGES.length - 1;
70
+ while (lo <= hi) {
71
+ const mid = (lo + hi) >> 1;
72
+ const range = WIDE_RANGES[mid];
73
+ if (cp < range[0])
74
+ hi = mid - 1;
75
+ else if (cp > range[1])
76
+ lo = mid + 1;
77
+ else
78
+ return true;
79
+ }
80
+ return false;
81
+ }
82
+ /** Terminal cells occupied by `s`, ignoring any ANSI escape codes it contains. */
83
+ export function displayWidth(s) {
84
+ const plain = stripAnsi(s);
85
+ let width = 0;
86
+ for (let i = 0; i < plain.length;) {
87
+ const cp = plain.codePointAt(i);
88
+ const size = cp > 0xffff ? 2 : 1;
89
+ i += size;
90
+ // Zero-width joiner, bidi/format controls and byte-order mark draw nothing.
91
+ if (cp === 0x200d || (cp >= 0x200b && cp <= 0x200f) || cp === 0xfeff)
92
+ continue;
93
+ // Variation selectors: VS16 promotes the previous character to emoji width.
94
+ if (cp >= 0xfe00 && cp <= 0xfe0f) {
95
+ if (cp === 0xfe0f)
96
+ width += 1;
97
+ continue;
98
+ }
99
+ if (cp >= 0xe0100 && cp <= 0xe01ef)
100
+ continue;
101
+ if (ZERO_WIDTH.test(String.fromCodePoint(cp)))
102
+ continue;
103
+ width += isWideCodePoint(cp) ? 2 : 1;
104
+ }
105
+ return width;
106
+ }
40
107
  function visibleWidth(s) {
41
- return stripAnsi(s).length;
108
+ return displayWidth(s);
109
+ }
110
+ /** Longest prefix of `plain` (unstyled) that fits in `cols` cells. */
111
+ function sliceToWidth(plain, cols) {
112
+ let width = 0;
113
+ for (let i = 0; i < plain.length;) {
114
+ const cp = plain.codePointAt(i);
115
+ const size = cp > 0xffff ? 2 : 1;
116
+ const next = displayWidth(String.fromCodePoint(cp));
117
+ if (width + next > cols)
118
+ return plain.slice(0, i);
119
+ width += next;
120
+ i += size;
121
+ }
122
+ return plain;
42
123
  }
43
124
  export function padToWidth(s, width) {
44
125
  if (width <= 0)
45
126
  return "";
46
127
  if (width === 1)
47
128
  return truncateLine(s, width);
48
- const visible = stripAnsi(s);
49
- if (visible.length > width)
50
- return visible.slice(0, width - 1) + "…";
51
- return s + " ".repeat(width - visible.length);
129
+ const visible = displayWidth(s);
130
+ if (visible > width)
131
+ return sliceToWidth(stripAnsi(s), width - 1) + "…";
132
+ return s + " ".repeat(width - visible);
52
133
  }
53
134
  // ANSI handling: `s` may contain ANSI escape codes (styled text from the style.*
54
- // helpers). We measure visible width via stripAnsi, then if truncation is needed we
55
- // slice the *plain* text (discarding ANSI codes) to avoid cutting mid-escape. A
135
+ // helpers). We measure visible width via displayWidth, then if truncation is needed
136
+ // we slice the *plain* text (discarding ANSI codes) to avoid cutting mid-escape. A
56
137
  // trailing reset is appended to guard against any residual SGR state from earlier
57
138
  // output on the same terminal line.
58
139
  export function truncateLine(s, cols) {
@@ -60,10 +141,9 @@ export function truncateLine(s, cols) {
60
141
  return "";
61
142
  if (cols === 1)
62
143
  return "…" + "\x1b[0m";
63
- const visible = stripAnsi(s);
64
- if (visible.length <= cols)
144
+ if (displayWidth(s) <= cols)
65
145
  return s;
66
- return visible.slice(0, cols - 1) + "…" + "\x1b[0m";
146
+ return sliceToWidth(stripAnsi(s), cols - 1) + "…" + "\x1b[0m";
67
147
  }
68
148
  // Reserve one column to avoid terminal autowrap when a line exactly fills the width.
69
149
  // Many terminals wrap on the last visible column, which corrupts full-screen redraws.
@@ -110,16 +190,8 @@ export function wrapSegments(segments, cols, opts = {}) {
110
190
  return lines.slice(0, maxLines).join("\n");
111
191
  }
112
192
  // ── Phren theme ────────────────────────────────────────────────────────────
113
- // Neural gradient palette: purple → blue → cyan (256-color ANSI)
114
- const PHREN_GRADIENT = [
115
- "\x1b[38;5;93m", // vivid purple
116
- "\x1b[38;5;99m", // purple-blue
117
- "\x1b[38;5;105m", // blue-purple
118
- "\x1b[38;5;111m", // sky blue
119
- "\x1b[38;5;75m", // dodger blue
120
- "\x1b[38;5;81m", // cyan-blue
121
- "\x1b[38;5;87m", // bright cyan
122
- ];
193
+ // The wordmark and its gradient live with the splash text effects.
194
+ import { PHREN_GRADIENT, PHREN_LOGO } from "./logo-fx.js";
123
195
  // Apply gradient coloring across non-whitespace characters
124
196
  export function gradient(text, colors = PHREN_GRADIENT) {
125
197
  const plain = stripAnsi(text);
@@ -141,15 +213,6 @@ export function gradient(text, colors = PHREN_GRADIENT) {
141
213
  }
142
214
  return result + RESET;
143
215
  }
144
- // Block-letter logo for startup animation
145
- const PHREN_LOGO = [
146
- "██████╗ ██╗ ██╗██████╗ ███████╗███╗ ██╗",
147
- "██╔══██╗██║ ██║██╔══██╗██╔════╝████╗ ██║",
148
- "██████╔╝███████║██████╔╝█████╗ ██╔██╗ ██║",
149
- "██╔═══╝ ██╔══██║██╔══██╗██╔══╝ ██║╚██╗██║",
150
- "██║ ██║ ██║██║ ██║███████╗██║ ╚████║",
151
- "╚═╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚══════╝╚═╝ ╚═══╝",
152
- ];
153
216
  import { PHREN_ART as PHREN_STARTUP_ART } from "../phren-art.js";
154
217
  // ── Line-based viewport: edge-triggered scroll (stable, no jumpiness) ─────────
155
218
  export function lineViewport(allLines, cursorFirstLine, cursorLastLine, height, prevStart) {
@@ -219,50 +282,141 @@ export function clearToEnd() {
219
282
  process.stdout.write("\x1b[J");
220
283
  }
221
284
  }
222
- export function shellStartupFrames(version) {
223
- const cols = process.stdout.columns || 80;
224
- const tagline = style.dim("local memory for working agents");
225
- const versionBadge = badge(`v${version}`, style.boldBlue);
226
- if (cols >= 72) {
227
- // Side-by-side: phren character on left, logo text on right
228
- const phrenLines = PHREN_STARTUP_ART;
229
- const logoLines = PHREN_LOGO.map(line => gradient(line));
230
- const infoLine = `${gradient("◆")} ${style.bold("phren")} ${versionBadge} ${tagline}`;
231
- // Logo is 6 lines, pad to align vertically with character center
232
- const rightSide = [
233
- "", "", ...logoLines, "", infoLine,
234
- ];
235
- // Merge side by side: character left (26 cols), logo right
236
- const charWidth = 26;
237
- const maxLines = Math.max(phrenLines.length, rightSide.length);
238
- const merged = [""];
239
- for (let i = 0; i < maxLines; i++) {
240
- const left = (i < phrenLines.length ? phrenLines[i] : "").padEnd(charWidth);
241
- const right = i < rightSide.length ? rightSide[i] : "";
242
- merged.push(left + right);
285
+ // Begin/End Synchronized Update (DEC private mode 2026). Terminals that support
286
+ // it buffer everything between the two and present the frame in one go, so a
287
+ // multi-kilobyte repaint never shows half-drawn. Terminals that don't support it
288
+ // ignore unknown private modes, so this is safe to send unconditionally.
289
+ const SYNC_BEGIN = "\x1b[?2026h";
290
+ const SYNC_END = "\x1b[?2026l";
291
+ const HIDE_CURSOR = "\x1b[?25l";
292
+ const SHOW_CURSOR = "\x1b[?25h";
293
+ // Autowrap off. The views already truncate to renderWidth(), but a single
294
+ // mismeasured line would otherwise wrap, push every row below it down, and
295
+ // scroll the frame out from under the cursor-home redraw — corrupting every
296
+ // subsequent frame. With autowrap off an over-long line is merely clipped.
297
+ const WRAP_OFF = "\x1b[?7l";
298
+ const WRAP_ON = "\x1b[?7h";
299
+ const ALT_SCREEN_ON = "\x1b[?1049h";
300
+ const ALT_SCREEN_OFF = "\x1b[?1049l";
301
+ /** Switch to the alternate screen buffer and put the terminal in TUI mode. */
302
+ export function enterFullscreen() {
303
+ if (!process.stdout.isTTY)
304
+ return;
305
+ process.stdout.write(ALT_SCREEN_ON);
306
+ process.stdout.write(HIDE_CURSOR);
307
+ process.stdout.write(WRAP_OFF);
308
+ }
309
+ /** Undo enterFullscreen(). Safe to call more than once. */
310
+ export function exitFullscreen() {
311
+ if (!process.stdout.isTTY)
312
+ return;
313
+ process.stdout.write(WRAP_ON);
314
+ process.stdout.write(SHOW_CURSOR);
315
+ process.stdout.write(ALT_SCREEN_OFF);
316
+ }
317
+ /**
318
+ * Write one frame as a single synchronized write.
319
+ *
320
+ * The old path issued three separate writes (home, body, erase-to-end) with the
321
+ * cursor visible, which let a concurrent repaint interleave between them and
322
+ * dragged the caret across the screen on every keystroke.
323
+ */
324
+ export function paintFrame(frame) {
325
+ // A frame with more lines than the terminal has rows scrolls the alternate
326
+ // buffer, and once it scrolls every later cursor-home repaint lands on
327
+ // shifted rows and the frames stack on top of each other. Clip the overflow
328
+ // (including a trailing newline on the last row) rather than scroll.
329
+ const rows = Math.max(1, process.stdout.rows || 24);
330
+ const lines = frame.split("\n");
331
+ const body = lines.length > rows ? lines.slice(0, rows).join("\n") : frame;
332
+ process.stdout.write(SYNC_BEGIN + "\x1b[H" + body + "\x1b[J" + SYNC_END);
333
+ }
334
+ // The character art is a fixed-size pixel grid; the gap keeps the logo off it.
335
+ const ART_WIDTH = 24;
336
+ const ART_GAP = 2;
337
+ const LOGO_WIDTH = Math.max(...PHREN_LOGO.map(displayWidth));
338
+ /**
339
+ * The wordmark line, split onto two rows when the terminal is too narrow to
340
+ * carry the tagline alongside the version badge.
341
+ */
342
+ function startupInfoLines(version, available, taglineText = "local memory for working agents") {
343
+ const tagline = style.dim(taglineText);
344
+ const head = `${gradient("◆")} ${style.bold("phren")} ${badge(`v${version}`, style.boldBlue)}`;
345
+ const single = `${head} ${tagline}`;
346
+ return displayWidth(single) <= available ? [single] : [head, tagline];
347
+ }
348
+ /**
349
+ * Lay out one splash frame from the character art the caller supplies (a live
350
+ * animation frame, or the static art).
351
+ *
352
+ * Every branch is chosen so the result fits the terminal it is about to be
353
+ * painted into: the wide layout needs room for art + gap + logo, the stacked
354
+ * one drops the logo rather than clipping it, and a terminal too short for the
355
+ * character drops the character rather than pushing the tagline off the bottom.
356
+ * A frame taller than the screen would scroll the alternate buffer, and once it
357
+ * scrolls every later cursor-home repaint lands on shifted rows, stacking the
358
+ * frames on top of each other.
359
+ */
360
+ export function composeStartupFrame(artLines, version, hint, logo, tagline) {
361
+ const cols = renderWidth();
362
+ const rows = process.stdout.rows || 24;
363
+ // A text-effect frame of the wordmark may be supplied; otherwise the plain gradient.
364
+ const logoLines = logo ?? PHREN_LOGO.map(line => gradient(line));
365
+ const hintLines = hint ? ["", ` ${hint}`] : [];
366
+ // One blank line above, one below, plus the hint block.
367
+ const budget = rows - 2 - hintLines.length;
368
+ const stackedInfo = startupInfoLines(version, cols - 2, tagline).map(line => ` ${line}`);
369
+ const sideBySide = () => {
370
+ // Logo is 6 lines; the leading blanks centre it against the character.
371
+ const rightSide = ["", "", ...logoLines, "", ...startupInfoLines(version, cols - ART_WIDTH - ART_GAP, tagline)];
372
+ const lines = [];
373
+ for (let i = 0; i < Math.max(artLines.length, rightSide.length); i++) {
374
+ // padToWidth measures display cells; String.padEnd counts the art's ANSI
375
+ // bytes as width and pads nothing at all.
376
+ const left = padToWidth(i < artLines.length ? artLines[i] : "", ART_WIDTH + ART_GAP);
377
+ lines.push(left + (i < rightSide.length ? rightSide[i] : ""));
243
378
  }
244
- merged.push("");
245
- return [
246
- // Frame 1: Logo with character side by side immediately
247
- merged.join("\n"),
248
- ];
249
- }
250
- if (cols >= 56) {
251
- // Medium terminal: stacked but compact
252
- const logo = PHREN_LOGO.map(line => " " + gradient(line));
253
- const sep = gradient("━".repeat(Math.min(52, cols)));
254
- return [
255
- ["", ...logo, ` ${sep}`, ` ${gradient("◆")} ${style.bold("phren")} ${versionBadge} ${tagline}`, ""].join("\n"),
256
- ];
379
+ return lines;
380
+ };
381
+ // Widest layout the terminal can carry, then progressively less of it: art
382
+ // beside the logo, art alone, logo alone, and finally just the wordmark.
383
+ const candidates = [];
384
+ if (cols >= ART_WIDTH + ART_GAP + LOGO_WIDTH)
385
+ candidates.push(sideBySide());
386
+ candidates.push([...artLines, "", ...stackedInfo]);
387
+ if (cols >= LOGO_WIDTH + 2)
388
+ candidates.push([...logoLines.map(line => ` ${line}`), "", ...stackedInfo]);
389
+ candidates.push(stackedInfo);
390
+ const body = candidates.find(lines => lines.length <= budget) ?? stackedInfo;
391
+ return ["", ...body, ...hintLines, ""];
392
+ }
393
+ /**
394
+ * Clamp a frame to the terminal before painting: truncate each line to the
395
+ * render width, erase whatever the previous frame left to the right of it, and
396
+ * drop rows past the bottom so the frame can never scroll the screen.
397
+ */
398
+ export function fitFrame(lines) {
399
+ const cols = renderWidth();
400
+ const rows = Math.max(1, process.stdout.rows || 24);
401
+ return lines
402
+ .slice(0, rows)
403
+ .map(line => truncateLine(line, cols) + "\x1b[K")
404
+ .join("\n");
405
+ }
406
+ export function shellStartupFrames(version, tagline) {
407
+ const cols = process.stdout.columns || 80;
408
+ if (cols >= 44) {
409
+ return [fitFrame(composeStartupFrame(PHREN_STARTUP_ART, version, undefined, undefined, tagline))];
257
410
  }
258
411
  // Narrow terminal: progressive text reveal with gradient
259
412
  const stages = ["p", "phr", "phren"];
260
413
  const spinners = ["◜", "◠", "◝"];
261
- return stages.map((stage, i) => [
414
+ const infoLines = startupInfoLines(version, renderWidth() - 2, tagline).map(line => ` ${line}`);
415
+ return stages.map((stage, i) => fitFrame([
262
416
  "",
263
417
  ` ${gradient(stage)} ${style.dim(spinners[i])}`,
264
418
  "",
265
- ` ${versionBadge} ${tagline}`,
419
+ ...infoLines,
266
420
  "",
267
- ].join("\n"));
421
+ ]));
268
422
  }
@@ -1,5 +1,7 @@
1
1
  import { type ShellView, type ShellDeps, type DoctorResultLike } from "./types.js";
2
2
  export type { ShellView, ShellDeps } from "./types.js";
3
+ import type { ShellStartup } from "./startup.js";
4
+ import { GraphController } from "./graph/controller.js";
3
5
  export declare class PhrenShell {
4
6
  readonly phrenPath: string;
5
7
  readonly profile: string;
@@ -22,12 +24,21 @@ export declare class PhrenShell {
22
24
  private viewScrollMap;
23
25
  private healthLineCount;
24
26
  private _subsectionsCache;
27
+ private _graph?;
28
+ private repaintHandler;
25
29
  get mode(): "navigate" | "input";
26
30
  get inputBuffer(): string;
27
31
  get filter(): string | undefined;
28
- constructor(phrenPath: string, profile: string, deps?: ShellDeps);
32
+ constructor(phrenPath: string, profile: string, deps?: ShellDeps, startup?: ShellStartup);
29
33
  close(): void;
30
34
  setMessage(msg: string): void;
35
+ /**
36
+ * Let the host (entry.ts) hand over a way to repaint on the shell's own
37
+ * initiative — the graph view uses it to animate its layout settling and
38
+ * to show a build that finished while nothing was typed.
39
+ */
40
+ setRepaintHandler(handler: (() => void) | null): void;
41
+ graph(): GraphController;
31
42
  confirmThen(label: string, action: () => void): void;
32
43
  setView(view: ShellView): void;
33
44
  setFilter(value: string): void;
@@ -59,3 +70,4 @@ export declare class PhrenShell {
59
70
  completeInput(line: string): string[];
60
71
  }
61
72
  export { startShell } from "./entry.js";
73
+ export type { ShellStartup } from "./startup.js";