@crouton-kit/crouter 0.3.14 → 0.3.16

package/dist/types.d.ts

@@ -53,6 +53,28 @@ export interface AutoUpdateConfig {
     content: AutoUpdateMode;
     interval_hours: number;
 }
+/** One canvas-nav action binding: a `crtr` argv string (templated with
+ *  {id|self|name|manager|subtree}) plus optional confirm gate + menu label.
+ *  `run` of the sentinel `__graph__` toggles the in-pi GRAPH modal instead of
+ *  shelling a command. */
+export interface CanvasBind {
+    run: string;
+    confirm?: boolean;
+    desc?: string;
+}
+/** Canvas-nav config (`canvasNav` in config.json). `prefixBinds` are consumed
+ *  at the tmux alt+c menu layer; `graphBinds` are consumed in-process by the
+ *  canvas-nav pi extension while in GRAPH. Built-in GRAPH keys
+ *  (j/k/h/l/g/G/enter/m/e/x/esc) are reserved — `graphBinds` is strictly
+ *  additive. */
+export interface CanvasNavConfig {
+    /** Fallback pi shortcut for GRAPH toggle when NOT in tmux. Default 'alt+g'. */
+    prefixKey?: string;
+    /** chord key (after alt+c) → action; tmux-menu layer. */
+    prefixBinds: Record<string, CanvasBind>;
+    /** extra raw key in GRAPH → action; pi-extension layer (additive only). */
+    graphBinds: Record<string, CanvasBind>;
+}
 export interface ScopeConfig {
     schema_version: number;
     marketplaces: Record<string, ConfigMarketplaceEntry>;
@@ -60,6 +82,7 @@ export interface ScopeConfig {
     skills: Record<string, ConfigSkillEntry>;
     auto_update: AutoUpdateConfig;
     max_panes_per_window: number;
+    canvasNav: CanvasNavConfig;
 }
 export interface ScopeState {
     marketplaces: Record<string, {
@@ -141,5 +164,10 @@ export declare const AGENTS_DIR = "agents";
 export declare const SCOPE_SKILL_PLUGIN = "_";
 export declare const DEFAULT_MAX_PANES_PER_WINDOW = 3;
 export declare function defaultScopeConfig(): ScopeConfig;
+/** Built-in canvas-nav binds so an absent config still gives the intended UX.
+ *  prefixBinds: g→GRAPH toggle (sentinel), m→focus manager, e→expand to tmux.
+ *  1..9 (focus report N) are generated by the menu layer, not literal entries.
+ *  graphBinds: empty — built-in GRAPH keys are reserved, custom keys add on. */
+export declare function defaultCanvasNavConfig(): CanvasNavConfig;
 export declare function skillConfigKey(plugin: string, name: string): string;
 export declare function defaultScopeState(): ScopeState;

package/dist/types.js

@@ -36,6 +36,22 @@ export function defaultScopeConfig() {
         skills: {},
         auto_update: { crtr: 'notify', content: 'notify', interval_hours: 24 },
         max_panes_per_window: DEFAULT_MAX_PANES_PER_WINDOW,
+        canvasNav: defaultCanvasNavConfig(),
+    };
+}
+/** Built-in canvas-nav binds so an absent config still gives the intended UX.
+ *  prefixBinds: g→GRAPH toggle (sentinel), m→focus manager, e→expand to tmux.
+ *  1..9 (focus report N) are generated by the menu layer, not literal entries.
+ *  graphBinds: empty — built-in GRAPH keys are reserved, custom keys add on. */
+export function defaultCanvasNavConfig() {
+    return {
+        prefixKey: 'alt+g',
+        prefixBinds: {
+            g: { run: '__graph__', desc: 'graph view' },
+            m: { run: 'node focus {manager}', desc: 'focus manager' },
+            e: { run: 'canvas tmux-spread {self}', desc: 'expand to tmux' },
+        },
+        graphBinds: {},
     };
 }
 export function skillConfigKey(plugin, name) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.3.14",
+  "version": "0.3.16",
   "description": "crtr — fast access to skills, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
@@ -36,7 +36,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@crouton-kit/humanloop": "^0.3.14",
+    "@crouton-kit/humanloop": "^0.3.15",
     "commander": "^13.0.0"
   },
   "devDependencies": {

package/dist/core/runtime/presence.d.ts

@@ -1,38 +0,0 @@
-import type { NodeMeta } from '../canvas/index.js';
-/** Persist `nodeId` as the currently focused node. Best-effort; never throws. */
-export declare function setFocus(nodeId: string): void;
-/** Read the currently focused node id, or null if the pointer is absent or
- *  empty (no active focus). Best-effort; never throws. */
-export declare function getFocus(): string | null;
-/** True when the node's tmux window is alive.  A falsy tmux_session/window
- *  always returns false so callers don't need to null-guard. */
-export declare function nodeLive(meta: NodeMeta): boolean;
-/** Bring a node's tmux window to the foreground and record it as focused.
- *
- * Strategy:
- *   - If the node has no live window (`nodeLive` is false), still write the
- *     focus pointer — the caller (e.g. revive logic) uses `focused:false` to
- *     know it needs to open a window first.
- *   - Otherwise call `switchClient` (lands us in the right session) then
- *     `selectWindow` (picks the right window within it).  Both calls are
- *     best-effort; the focus pointer is always written regardless.
- *
- * Returns:
- *   focused — whether the tmux focus actually succeeded.
- *   session — the tmux session name if one was attempted, null otherwise. */
-export declare function focusNode(nodeId: string): {
-    focused: boolean;
-    session: string | null;
-};
-/** Focus a node IN PLACE: bring its pane into the caller's current pane slot
- *  (swap-pane) instead of navigating the client to the node's own window. This
- *  is the default for `crtr node focus` and the nav-chrome spine jump — the
- *  agent appears where you are.
- *
- *  Falls back to window focus when there is no caller pane (not inside tmux) or
- *  the target pane can't be resolved. `inPlace` reports which path ran. */
-export declare function focusNodeInPlace(nodeId: string, callerPane?: string, callerNodeId?: string): {
-    focused: boolean;
-    session: string | null;
-    inPlace: boolean;
-};

package/dist/core/runtime/presence.js

@@ -1,154 +0,0 @@
-// presence.ts — focus pointer + per-node liveness helpers.
-//
-// The focus pointer (`<crtrHome>/focus.ptr`) is a plain-text file holding the
-// node id that currently "has focus" — meaning the user's terminal is showing
-// that node's tmux window. It is written on every explicit `focusNode()` call
-// and read by the dashboard / status-line to highlight the active node.
-//
-// This is intentionally a simple file-based pointer rather than a database
-// column: focus is transient UI state, not durable business data. A crash
-// leaves a stale pointer that the next focusNode() clobbers — harmless.
-//
-// focusNode() does two things:
-//   1. Ensures the user's terminal lands on the right tmux window by calling
-//      switchClient (cross-session) then selectWindow (in-session). Both are
-//      best-effort; we set the pointer regardless so the dashboard stays in sync.
-//   2. Persists the node id to focus.ptr so any process can quickly read "what
-//      is the user looking at?".
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
-import { join } from 'node:path';
-import { crtrHome, getNode, updateNode } from '../canvas/index.js';
-import { selectWindow, switchClient, windowAlive, currentTmux, paneOfWindow, swapPaneInPlace, windowOfPane } from './tmux.js';
-// ---------------------------------------------------------------------------
-// Focus pointer
-// ---------------------------------------------------------------------------
-/** Absolute path to the focus pointer file. */
-function focusPtrPath() {
-    return join(crtrHome(), 'focus.ptr');
-}
-/** Persist `nodeId` as the currently focused node. Best-effort; never throws. */
-export function setFocus(nodeId) {
-    try {
-        const p = focusPtrPath();
-        mkdirSync(dirname(p), { recursive: true });
-        writeFileSync(p, nodeId, 'utf8');
-    }
-    catch {
-        /* focus pointer is best-effort; never surface */
-    }
-}
-/** Read the currently focused node id, or null if the pointer is absent or
- *  empty (no active focus). Best-effort; never throws. */
-export function getFocus() {
-    try {
-        const raw = readFileSync(focusPtrPath(), 'utf8').trim();
-        return raw !== '' ? raw : null;
-    }
-    catch {
-        return null;
-    }
-}
-// ---------------------------------------------------------------------------
-// Liveness
-// ---------------------------------------------------------------------------
-/** True when the node's tmux window is alive.  A falsy tmux_session/window
- *  always returns false so callers don't need to null-guard. */
-export function nodeLive(meta) {
-    return windowAlive(meta.tmux_session, meta.window);
-}
-// ---------------------------------------------------------------------------
-// Focus
-// ---------------------------------------------------------------------------
-/** Bring a node's tmux window to the foreground and record it as focused.
- *
- * Strategy:
- *   - If the node has no live window (`nodeLive` is false), still write the
- *     focus pointer — the caller (e.g. revive logic) uses `focused:false` to
- *     know it needs to open a window first.
- *   - Otherwise call `switchClient` (lands us in the right session) then
- *     `selectWindow` (picks the right window within it).  Both calls are
- *     best-effort; the focus pointer is always written regardless.
- *
- * Returns:
- *   focused — whether the tmux focus actually succeeded.
- *   session — the tmux session name if one was attempted, null otherwise. */
-export function focusNode(nodeId) {
-    const meta = getNode(nodeId);
-    // Always write the pointer so the dashboard reflects intent even when focus
-    // fails (e.g. we're not currently inside tmux).
-    setFocus(nodeId);
-    if (meta === null || !nodeLive(meta)) {
-        // Node not found or window is gone — caller may need to revive.
-        return { focused: false, session: meta?.tmux_session ?? null };
-    }
-    // Both fields are non-null thanks to nodeLive() returning true.
-    const session = meta.tmux_session;
-    const window = meta.window;
-    // Cross-session hop first, then window selection within the session.
-    // switchClient may be a no-op when already in the same session but is
-    // always safe to call — tmux handles it gracefully.
-    const clientOk = switchClient(session);
-    const windowOk = selectWindow(session, window);
-    return { focused: clientOk && windowOk, session };
-}
-/** Focus a node IN PLACE: bring its pane into the caller's current pane slot
- *  (swap-pane) instead of navigating the client to the node's own window. This
- *  is the default for `crtr node focus` and the nav-chrome spine jump — the
- *  agent appears where you are.
- *
- *  Falls back to window focus when there is no caller pane (not inside tmux) or
- *  the target pane can't be resolved. `inPlace` reports which path ran. */
-export function focusNodeInPlace(nodeId, callerPane, callerNodeId) {
-    const meta = getNode(nodeId);
-    // Always write the pointer so the dashboard reflects intent even on failure.
-    setFocus(nodeId);
-    if (meta === null || !nodeLive(meta)) {
-        return { focused: false, session: meta?.tmux_session ?? null, inPlace: false };
-    }
-    const session = meta.tmux_session;
-    const window = meta.window;
-    const pane = callerPane ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane;
-    // No caller pane (not in tmux) — best we can do is bring the window forefront.
-    if (pane === undefined || pane === '') {
-        const ok = switchClient(session) && selectWindow(session, window);
-        return { focused: ok, session, inPlace: false };
-    }
-    const targetPane = paneOfWindow(session, window);
-    if (targetPane === null) {
-        const ok = switchClient(session) && selectWindow(session, window);
-        return { focused: ok, session, inPlace: false };
-    }
-    if (targetPane === pane)
-        return { focused: true, session, inPlace: true }; // already here
-    // The window the caller's pane currently sits in — the slot the target's pane
-    // is about to be swapped INTO.
-    const callerWindow = windowOfPane(pane);
-    const ok = swapPaneInPlace(targetPane, pane);
-    // Keep the canvas window mapping in sync with the physical swap. swap-pane
-    // exchanges the two PANES between their windows (pane ids are stable, windows
-    // are slots): after the swap the target's pane occupies the caller's window
-    // and the caller's pane occupies the target's old window. Without this update
-    // meta.window goes stale, and a later paneOfWindow(session, meta.window)
-    // resolves the WRONG pane — the bug that made focusing back to a manager a
-    // no-op (it kept resolving the pane already in view) and made a focused node's
-    // exit collapse the visible window instead of its background one.
-    if (ok && callerWindow !== null && callerWindow !== window) {
-        try {
-            updateNode(nodeId, { window: callerWindow });
-        }
-        catch { /* best-effort */ }
-        // The caller is the node running this focus (its pi process owns callerPane).
-        // Its pane moved to the target's old window, so re-point its window there.
-        // Prefer an explicit id (the `node cycle` tmux binding runs outside any pi,
-        // so CRTR_NODE_ID is unset there) and fall back to the env for `node focus`.
-        const cnid = callerNodeId ?? process.env['CRTR_NODE_ID'];
-        if (cnid !== undefined && cnid.trim() !== '' && cnid !== nodeId) {
-            try {
-                updateNode(cnid, { window });
-            }
-            catch { /* best-effort */ }
-        }
-    }
-    return { focused: ok, session, inPlace: true };
-}