@pi-unipi/info-screen 0.1.9 → 0.1.11

package/README.md

@@ -0,0 +1,115 @@
+# @pi-unipi/info-screen
+
+Dashboard and module registry for [Unipi](https://github.com/Neuron-Mr-White/unipi). Shows a configurable info overlay on boot with tabbed groups from all registered modules.
+
+## Install
+
+```bash
+pi install npm:@pi-unipi/info-screen
+```
+
+Or as part of the full suite:
+```bash
+pi install npm:unipi
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/unipi:info` | Show info screen dashboard |
+| `/unipi:info-settings` | Configure info display (groups, stats, visibility) |
+
+## Features
+
+- **Module discovery** — listens for `MODULE_READY` events, tracks all registered modules
+- **Tabbed groups** — each module registers info groups with custom data providers
+- **Configurable** — per-group and per-stat visibility via settings
+- **Boot overlay** — shows dashboard on session start (configurable)
+- **Styled dialog chrome** — uses pi-tui theme API for consistent borders, scrollable content, and navigation hints (matching the overlay style used by @pi-unipi/btw)
+- **Core groups** — modules, tools, load time, session info out of the box
+
+## Registering a Group
+
+Other modules register info groups via the global registry:
+
+```typescript
+import { infoRegistry } from "@pi-unipi/info-screen";
+
+infoRegistry.registerGroup({
+  id: "my-module",
+  name: "My Module",
+  icon: "📦",
+  priority: 60,
+  config: {
+    showByDefault: true,
+    stats: [
+      { id: "status", label: "Status", show: true },
+      { id: "count", label: "Count", show: true },
+    ],
+  },
+  dataProvider: async () => ({
+    status: { value: "running" },
+    count: { value: "42", detail: "items processed" },
+  }),
+});
+```
+
+## API
+
+### `infoRegistry`
+
+Singleton registry instance. Also available globally via `globalThis.__unipi_info_registry`.
+
+| Method | Description |
+|--------|-------------|
+| `registerGroup(group)` | Register an info group |
+| `unregisterGroup(id)` | Remove a group |
+| `getGroups()` | Get visible groups (sorted by priority) |
+| `getAllGroups()` | Get all groups (including hidden) |
+| `getGroupData(id)` | Get data for a group (cached) |
+| `updateGroupData(id, data)` | Manually update group data |
+| `getVisibleStats(id)` | Get enabled stats for a group |
+| `invalidateCache(id)` | Invalidate cached data |
+
+### Load Tracking
+
+```typescript
+import { startLoadTracking, recordLoadTime, finishLoadTracking, recordModuleStart } from "@pi-unipi/info-screen";
+
+// Track module load times
+startLoadTracking();
+recordModuleStart("@pi-unipi/memory");
+// ... module loads ...
+recordLoadTime("@pi-unipi/memory", "module", 150);
+finishLoadTracking();
+```
+
+## Settings
+
+Configure in pi `settings.json`:
+
+```json
+{
+  "unipi": {
+    "infoScreen": {
+      "showOnBoot": true,
+      "bootTimeoutMs": 8000,
+      "groups": {
+        "modules": { "show": true },
+        "ralph": { "show": true },
+        "memory": { "show": false }
+      },
+      "groupOrder": ["modules", "ralph", "subagents"]
+    }
+  }
+}
+```
+
+## Dependencies
+
+- `@pi-unipi/core` — shared constants and events
+
+## License
+
+MIT

package/index.ts

@@ -1,20 +1,20 @@
 /**
  * @pi-unipi/info-screen — Extension entry
  *
- * Dashboard and module registry for Unipi.
- * Shows configurable info overlay on boot and via /unipi:info command.
+ * Cache-first reactive dashboard.
+ * Opens immediately with cached data, updates in background.
  *
  * Usage:
  *   /unipi:info          - Show info dashboard
  *   /unipi:info-settings - Configure info display
  */
 
-import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { UNIPI_EVENTS, MODULES, UNIPI_PREFIX, emitEvent, getPackageVersion } from "@pi-unipi/core";
 import { infoRegistry } from "./registry.js";
 import { registerCoreGroups, trackModule, trackTool, setPiApi, registerSkillDir, startLoadTracking, recordLoadTime, finishLoadTracking, recordModuleStart } from "./core-groups.js";
 
-/** Re-export infoRegistry, registerSkillDir, and load tracking for external use */
+/** Re-export for external use */
 export { infoRegistry, registerSkillDir, startLoadTracking, recordLoadTime, finishLoadTracking, recordModuleStart };
 import { getInfoSettings } from "./config.js";
 import { InfoOverlay } from "./tui/info-overlay.js";
@@ -23,71 +23,43 @@ import { SettingsOverlay } from "./settings/settings-tui.js";
 /** Package version */
 const VERSION = getPackageVersion(new URL(".", import.meta.url).pathname);
 
-/** Module ready tracking */
-let moduleReady = false;
-let moduleReadyResolve: (() => void) | null = null;
-const moduleReadyPromise = new Promise<void>((resolve) => {
-  moduleReadyResolve = resolve;
-});
-
-/** Timeout for waiting for modules */
-const MODULE_WAIT_TIMEOUT_MS = 8000;
-
-/**
- * Wait for modules to announce, then return.
- */
-async function waitForModules(): Promise<void> {
-  const settings = getInfoSettings();
-  const timeoutMs = settings.bootTimeoutMs || MODULE_WAIT_TIMEOUT_MS;
-
-  // Wait a bit for modules to announce
-  // We wait for the full timeout to give all modules time to emit MODULE_READY
-  await new Promise<void>((resolve) => setTimeout(resolve, timeoutMs));
-}
-
 export default function (pi: ExtensionAPI) {
-  // Set pi API reference for tools access
   setPiApi(pi);
 
-  // Register core groups on load
+  // Register core groups immediately (synchronous)
   registerCoreGroups();
 
-
-
   // Start load tracking
   startLoadTracking();
 
-  // Listen for module announcements
+  // Listen for module announcements — track and trigger reactive updates
   pi.events.on(UNIPI_EVENTS.MODULE_READY, (event: any) => {
     if (event.name && event.name !== MODULES.INFO_SCREEN) {
-      // Track the module
       trackModule(event.name, event.version || "unknown");
       recordLoadTime(event.name, "module", event.loadTimeMs);
 
-      // Invalidate overview cache so next render shows updated modules
+      // Invalidate overview so next fetch picks up new module list
       infoRegistry.invalidateCache("overview");
 
-      // Track tools from this module
+      // Trigger background refresh of overview — subscribers will re-render
+      infoRegistry.getGroupData("overview");
+
       if (event.tools && Array.isArray(event.tools)) {
         for (const tool of event.tools) {
           trackTool(tool, event.name);
         }
-      }
-
-      // Signal that a module has announced
-      if (!moduleReady) {
-        moduleReady = true;
-        moduleReadyResolve?.();
+        // Refresh tools group too
+        infoRegistry.invalidateCache("tools");
+        infoRegistry.getGroupData("tools");
       }
     }
   });
 
-  // Listen for info group registrations via events
   pi.events.on(UNIPI_EVENTS.INFO_GROUP_REGISTERED, (_event: any) => {
     // Group already registered via globalThis in registerGroup()
   });
 
-  // Also track built-in tools by intercepting tool calls
+  // Track built-in tools
   const trackedBuiltinTools = new Set<string>();
   pi.on("tool_call", async (event, _ctx) => {
     const toolName = event.toolName;
@@ -95,50 +67,56 @@ export default function (pi: ExtensionAPI) {
       trackedBuiltinTools.add(toolName);
       trackTool(toolName, "builtin");
     }
-    return undefined; // Don't block the tool call
+    return undefined;
   });
 
-  // Session lifecycle
+  /**
+   * Show the info overlay immediately.
+   * Cache-first: opens with whatever data is cached (even empty).
+   * Background: each group fetches independently, overlay re-renders reactively.
+   */
+  function showOverlay(ctx: any): void {
+    ctx.ui.custom(
+      (tui: any, theme: any, _keybindings: any, done: () => void) => {
+        const overlay = new InfoOverlay();
+        overlay.setTheme(theme);
+        overlay.onClose = () => {
+          overlay.destroy();
+          done();
+        };
+        overlay.requestRender = () => tui.requestRender();
+        return {
+          render: (w: number) => overlay.render(w),
+          invalidate: () => overlay.invalidate(),
+          handleInput: (data: string) => {
+            overlay.handleInput(data);
+            tui.requestRender();
+          },
+        };
+      },
+      {
+        overlay: true,
+        overlayOptions: {
+          width: "80%",
+          minWidth: 60,
+          anchor: "center",
+          margin: 2,
+        },
+      }
+    );
+  }
+
+  // Session lifecycle — show immediately on boot, no blocking wait
   pi.on("session_start", async (event, ctx) => {
     const settings = getInfoSettings();
 
-    // Show dashboard only on initial startup, not on /new
     if (settings.showOnBoot && event.reason === "startup") {
-      // Wait for other modules to announce
-      await waitForModules();
-
-      // Show the overlay using three-method object pattern
-      ctx.ui.custom(
-        (tui, _theme, _keybindings, done) => {
-          const overlay = new InfoOverlay();
-          overlay.onClose = () => done(undefined);
-          overlay.requestRender = () => tui.requestRender();
-          // Return three-method object as per pi-tui docs
-          return {
-            render: (w: number) => overlay.render(w),
-            invalidate: () => overlay.invalidate(),
-            handleInput: (data: string) => {
-              overlay.handleInput?.(data);
-              tui.requestRender();
-            },
-          };
-        },
-        {
-          overlay: true,
-          overlayOptions: {
-            width: "80%",
-            minWidth: 60,
-            anchor: "center",
-            margin: 2,
-          },
-        }
-      );
+      // Open immediately — cache-first, no waiting
+      showOverlay(ctx);
     }
 
-    // Finish load tracking
     finishLoadTracking();
 
-    // Announce module
     emitEvent(pi, UNIPI_EVENTS.MODULE_READY, {
       name: MODULES.INFO_SCREEN,
       version: VERSION,
@@ -147,43 +125,20 @@ export default function (pi: ExtensionAPI) {
     });
   });
 
-  // Register /unipi:info command
+  // /unipi:info — open immediately
   pi.registerCommand(`${UNIPI_PREFIX}info`, {
     description: "Show info screen dashboard",
     handler: async (_args, ctx) => {
-      ctx.ui.custom(
-        (tui, _theme, _keybindings, done) => {
-          const overlay = new InfoOverlay();
-          overlay.onClose = () => done(undefined);
-          overlay.requestRender = () => tui.requestRender();
-          return {
-            render: (w: number) => overlay.render(w),
-            invalidate: () => overlay.invalidate(),
-            handleInput: (data: string) => {
-              overlay.handleInput?.(data);
-              tui.requestRender();
-            },
-          };
-        },
-        {
-          overlay: true,
-          overlayOptions: {
-            width: "80%",
-            minWidth: 60,
-            anchor: "center",
-            margin: 2,
-          },
-        }
-      );
+      showOverlay(ctx);
     },
   });
 
-  // Register /unipi:info-settings command
+  // /unipi:info-settings
   pi.registerCommand(`${UNIPI_PREFIX}info-settings`, {
     description: "Configure info screen display",
     handler: async (_args, ctx) => {
       ctx.ui.custom(
-        (tui, _theme, _keybindings, done) => {
+        (tui: any, _theme: any, _keybindings: any, done: any) => {
           const overlay = new SettingsOverlay();
           overlay.onClose = () => done(undefined);
           return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/info-screen",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Dashboard and module registry for Unipi — configurable info overlay with tabbed groups",
   "type": "module",
   "license": "MIT",

package/registry.ts

@@ -1,41 +1,16 @@
 /**
  * @pi-unipi/info-screen — Registry
  *
- * Central registry for info groups. Core groups register at startup.
- * External modules call registerGroup() to add their groups.
+ * Central registry for info groups with cache-first reactive model.
+ * Groups load independently; overlay subscribes to per-group updates.
  */
 
 import type { InfoGroup, GroupData } from "./types.js";
-import { getInfoSettings, isGroupEnabled, isStatEnabled } from "./config.js";
+import { getInfoSettings, isStatEnabled } from "./config.js";
+
+/** Callback for reactive updates */
+type GroupUpdateCallback = (groupId: string, data: GroupData) => void;
 
-/**
- * Registry for info-screen groups.
- *
- * Usage:
- * ```ts
- * import { infoRegistry } from "@pi-unipi/info-screen";
- *
- * // Register a group
- * infoRegistry.registerGroup({
- *   id: "memory",
- *   name: "Memory",
- *   icon: "🧠",
- *   priority: 60,
- *   config: {
- *     showByDefault: true,
- *     stats: [
- *       { id: "total", label: "Total", show: true },
- *     ],
- *   },
- *   dataProvider: async () => ({
- *     total: { value: "42" },
- *   }),
- * });
- *
- * // Get all registered groups
- * const groups = infoRegistry.getGroups();
- * ```
- */
 class InfoRegistry {
   /** Registered groups by id */
   private groups = new Map<string, InfoGroup>();
@@ -43,18 +18,29 @@ class InfoRegistry {
   /** Cached data per group */
   private dataCache = new Map<string, GroupData>();
 
+  /** Last successful fetch timestamp per group */
+  private lastUpdated = new Map<string, number>();
+
   /** Cache TTL in ms */
   private cacheTtlMs = 5000;
 
-  /** Last cache update per group */
-  private cacheTimestamps = new Map<string, number>();
+  /** Subscribers per group */
+  private subscribers = new Map<string, Set<GroupUpdateCallback>>();
+
+  /** Global subscribers (any group update) */
+  private globalSubscribers = new Set<GroupUpdateCallback>();
+
+  /** In-flight fetches per group */
+  private inflight = new Map<string, Promise<GroupData>>();
 
   /**
    * Register an info group.
-   * If a group with the same id exists, it's replaced.
+   * Notifies subscribers so overlays can pick up late-arriving groups.
    */
   registerGroup(group: InfoGroup): void {
     this.groups.set(group.id, group);
+    // Notify that a new group appeared (triggers overlay sync)
+    this.notifyGroupRegistered(group.id);
   }
 
   /**
@@ -63,12 +49,12 @@ class InfoRegistry {
   unregisterGroup(groupId: string): void {
     this.groups.delete(groupId);
     this.dataCache.delete(groupId);
-    this.cacheTimestamps.delete(groupId);
+    this.lastUpdated.delete(groupId);
+    this.subscribers.delete(groupId);
   }
 
   /**
    * Get all registered groups, sorted by priority.
-   * Respects config — groups with show: false are excluded.
    */
   getGroups(): InfoGroup[] {
     const settings = getInfoSettings();
@@ -76,10 +62,8 @@ class InfoRegistry {
 
     return allGroups
       .filter((group) => {
-        // Check group-level visibility
         const groupSettings = settings.groups[group.id];
         if (groupSettings && !groupSettings.show) return false;
-        // If no settings, use group's default
         if (!groupSettings && !group.config.showByDefault) return false;
         return true;
       })
@@ -101,8 +85,32 @@ class InfoRegistry {
     return this.groups.get(groupId);
   }
 
+  /**
+   * Synchronous: get cached data for immediate display.
+   * Returns null if never fetched.
+   */
+  getCachedData(groupId: string): GroupData | null {
+    return this.dataCache.get(groupId) ?? null;
+  }
+
+  /**
+   * Synchronous: get last updated timestamp for a group.
+   */
+  getLastUpdated(groupId: string): number {
+    return this.lastUpdated.get(groupId) ?? 0;
+  }
+
+  /**
+   * Synchronous: check if a group is currently fetching.
+   */
+  isFetching(groupId: string): boolean {
+    return this.inflight.has(groupId);
+  }
+
   /**
    * Get data for a group, using cache if fresh.
+   * Returns immediately from cache if fresh, otherwise fetches in background
+   * and notifies subscribers when done.
    */
   async getGroupData(groupId: string): Promise<GroupData> {
     const group = this.groups.get(groupId);
@@ -110,44 +118,114 @@ class InfoRegistry {
 
     // Check cache freshness
     const now = Date.now();
-    const lastUpdate = this.cacheTimestamps.get(groupId) ?? 0;
+    const lastUpdate = this.lastUpdated.get(groupId) ?? 0;
     if (now - lastUpdate < this.cacheTtlMs) {
       const cached = this.dataCache.get(groupId);
       if (cached) return cached;
     }
 
+    // Deduplicate in-flight requests
+    const existing = this.inflight.get(groupId);
+    if (existing) return existing;
+
     // Fetch fresh data
+    const fetchPromise = this.fetchGroupData(groupId, group);
+    this.inflight.set(groupId, fetchPromise);
+
+    try {
+      const data = await fetchPromise;
+      return data;
+    } finally {
+      this.inflight.delete(groupId);
+    }
+  }
+
+  /**
+   * Background fetch: update cache and notify subscribers.
+   * Does not throw — falls back to cached data.
+   */
+  private async fetchGroupData(groupId: string, group: InfoGroup): Promise<GroupData> {
     try {
       const data = await group.dataProvider();
       this.dataCache.set(groupId, data);
-      this.cacheTimestamps.set(groupId, now);
+      this.lastUpdated.set(groupId, Date.now());
+      this.notifySubscribers(groupId, data);
       return data;
-    } catch (error) {
-      // Silently fall back to cached data
+    } catch {
       return this.dataCache.get(groupId) ?? {};
     }
   }
 
   /**
-   * Manually update data for a group (for live updates).
+   * Trigger a background refresh for a group.
+   * Returns cached data immediately if available.
+   */
+  refreshGroup(groupId: string): GroupData | null {
+    const cached = this.dataCache.get(groupId) ?? null;
+    // Fire and forget
+    this.getGroupData(groupId);
+    return cached;
+  }
+
+  /**
+   * Refresh all groups in background.
+   */
+  refreshAll(): void {
+    for (const [id, group] of this.groups) {
+      this.fetchGroupData(id, group);
+    }
+  }
+
+  /**
+   * Subscribe to updates for a specific group.
+   * Returns unsubscribe function.
    */
-  updateGroupData(groupId: string, data: GroupData): void {
-    this.dataCache.set(groupId, data);
-    this.cacheTimestamps.set(groupId, Date.now());
+  subscribe(groupId: string, callback: GroupUpdateCallback): () => void {
+    if (!this.subscribers.has(groupId)) {
+      this.subscribers.set(groupId, new Set());
+    }
+    this.subscribers.get(groupId)!.add(callback);
+
+    return () => {
+      this.subscribers.get(groupId)?.delete(callback);
+    };
+  }
+
+  /**
+   * Subscribe to all group updates.
+   * Returns unsubscribe function.
+   */
+  subscribeAll(callback: GroupUpdateCallback): () => void {
+    this.globalSubscribers.add(callback);
+    return () => {
+      this.globalSubscribers.delete(callback);
+    };
+  }
+
+  private notifySubscribers(groupId: string, data: GroupData): void {
+    // Per-group subscribers
+    const groupSubs = this.subscribers.get(groupId);
+    if (groupSubs) {
+      for (const cb of groupSubs) {
+        try { cb(groupId, data); } catch { /* ignore */ }
+      }
+    }
+
+    // Global subscribers
+    for (const cb of this.globalSubscribers) {
+      try { cb(groupId, data); } catch { /* ignore */ }
+    }
   }
 
   /**
    * Get filtered stats for a group based on config.
-   * Returns stats that are enabled in both group config and settings.
    */
   getVisibleStats(groupId: string): Array<{ id: string; label: string }> {
     const group = this.groups.get(groupId);
     if (!group) return [];
 
     return group.config.stats.filter((stat) => {
-      // Check stat-level visibility from settings
       if (!isStatEnabled(groupId, stat.id)) return false;
-      // Check stat's own default
       return stat.show;
     });
   }
@@ -157,7 +235,7 @@ class InfoRegistry {
    */
   invalidateCache(groupId: string): void {
     this.dataCache.delete(groupId);
-    this.cacheTimestamps.delete(groupId);
+    this.lastUpdated.delete(groupId);
   }
 
   /**
@@ -165,7 +243,18 @@ class InfoRegistry {
    */
   invalidateAllCaches(): void {
     this.dataCache.clear();
-    this.cacheTimestamps.clear();
+    this.lastUpdated.clear();
+  }
+
+  /**
+   * Notify that a new group was registered.
+   * Subscribers can use this to sync group lists.
+   */
+  private notifyGroupRegistered(groupId: string): void {
+    // Fire a dummy update so overlays re-sync their group list
+    for (const cb of this.globalSubscribers) {
+      try { cb(groupId, {} as GroupData); } catch { /* ignore */ }
+    }
   }
 }
 
@@ -173,7 +262,6 @@ class InfoRegistry {
 export const infoRegistry = new InfoRegistry();
 
 // Expose globally so other modules can access without direct imports
-// (pi loads extensions independently, so imports may not resolve)
 const globalObj = globalThis as any;
 if (!globalObj.__unipi_info_registry) {
   globalObj.__unipi_info_registry = infoRegistry;