@nextclaw/companion 0.1.1-beta.0 → 0.1.1-beta.2

package/{src/launcher/index.ts → electron/launcher.ts}

@@ -5,12 +5,12 @@ import { resolve } from "node:path";
 
 const loadModule = createRequire(__filename);
 const electronBinary = loadModule("electron") as string;
-const appRoot = resolve(__dirname, "..", "..", "..");
+const mainEntryPath = resolve(__dirname, "main.js");
 const env = { ...process.env };
 
 delete env.ELECTRON_RUN_AS_NODE;
 
-const child = spawn(electronBinary, [appRoot, ...process.argv.slice(2)], {
+const child = spawn(electronBinary, [mainEntryPath, ...process.argv.slice(2)], {
   stdio: "inherit",
   env
 });

package/{src → electron}/main.ts

@@ -1,3 +1,4 @@
+import type { CompanionAppOptions } from "./types/companion-shell.types.js";
 import { CompanionApplicationService } from "./services/companion-application.service.js";
 
 function resolveBaseUrl(argv: string[]): string {
@@ -13,11 +14,11 @@ function resolveBaseUrl(argv: string[]): string {
 }
 
 async function main(): Promise<void> {
-  const application = new CompanionApplicationService({
+  const options: CompanionAppOptions = {
     baseUrl: resolveBaseUrl(process.argv.slice(1)),
     runtimeStatePath: process.env.NEXTCLAW_COMPANION_RUNTIME_STATE_PATH?.trim() || undefined
-  });
-  await application.run();
+  };
+  await new CompanionApplicationService(options).run();
 }
 
 void main();

package/electron/preload.ts

@@ -0,0 +1,7 @@
+import { contextBridge, ipcRenderer } from "electron";
+
+contextBridge.exposeInMainWorld("nextclawCompanion", {
+  open: () => ipcRenderer.invoke("companion:open"),
+  quit: () => ipcRenderer.invoke("companion:quit"),
+  getBootstrap: () => ipcRenderer.invoke("companion:get-bootstrap")
+});

package/{src → electron}/services/companion-application.service.ts

@@ -1,29 +1,29 @@
 import { app } from "electron";
 import { resolve } from "node:path";
-import type { CompanionAppOptions } from "../types/companion.types.js";
-import { CompanionRuntimeStateStore } from "../stores/companion-runtime-state.store.js";
-import { CompanionWindowPositionStore } from "../stores/companion-window-position.store.js";
-import { CompanionRuntimeClientService } from "./companion-runtime-client.service.js";
+
+import type { CompanionAppOptions } from "../types/companion-shell.types.js";
+import { CompanionRuntimeStatePersistenceService } from "./companion-runtime-state-persistence.service.js";
 import { CompanionTrayService } from "./companion-tray.service.js";
+import { CompanionWindowPositionPersistenceService } from "./companion-window-position-persistence.service.js";
 import { CompanionWindowService } from "./companion-window.service.js";
 
 export class CompanionApplicationService {
-  private readonly runtimeClient: CompanionRuntimeClientService;
-  private readonly runtimeStateStore: CompanionRuntimeStateStore | null;
+  private readonly runtimeStatePersistenceService: CompanionRuntimeStatePersistenceService | null;
   private readonly windowService: CompanionWindowService;
   private readonly trayService: CompanionTrayService;
   private quitting = false;
 
   constructor(private readonly options: CompanionAppOptions) {
-    const preloadPath = resolve(__dirname, "..", "preload", "index.js");
-    this.runtimeClient = new CompanionRuntimeClientService(options.baseUrl);
-    this.runtimeStateStore = options.runtimeStatePath
-      ? new CompanionRuntimeStateStore(options.runtimeStatePath)
+    this.runtimeStatePersistenceService = options.runtimeStatePath
+      ? new CompanionRuntimeStatePersistenceService(options.runtimeStatePath)
       : null;
-    this.windowService = new CompanionWindowService(
-      preloadPath,
-      CompanionWindowPositionStore.fromUserData(app.getPath("userData"))
-    );
+    this.windowService = new CompanionWindowService({
+      preloadPath: resolve(__dirname, "..", "preload.js"),
+      rendererEntryPath: resolve(__dirname, "..", "..", "ui", "index.html"),
+      positionPersistenceService: CompanionWindowPositionPersistenceService.fromUserData(app.getPath("userData")),
+      baseUrl: options.baseUrl,
+      onQuit: () => this.quit()
+    });
     this.trayService = new CompanionTrayService(
       options.baseUrl,
       () => this.windowService.toggleVisibility(),
@@ -43,17 +43,16 @@ export class CompanionApplicationService {
     app.on("window-all-closed", () => undefined);
     app.on("before-quit", () => {
       this.quitting = true;
-      this.runtimeClient.stop();
       this.trayService.destroy();
       this.windowService.destroy();
-      this.runtimeStateStore?.clear();
+      this.runtimeStatePersistenceService?.clear();
     });
     app.on("activate", () => {
       this.windowService.show();
     });
 
     await app.whenReady();
-    this.runtimeStateStore?.write({
+    this.runtimeStatePersistenceService?.write({
       pid: process.pid,
       startedAt: new Date().toISOString(),
       baseUrl: this.options.baseUrl
@@ -61,9 +60,6 @@ export class CompanionApplicationService {
     await this.windowService.create();
     this.windowService.show();
     this.trayService.create();
-    await this.runtimeClient.start((view) => {
-      this.windowService.updateView(view);
-    });
   };
 
   readonly quit = (): void => {

package/{src/stores/companion-runtime-state.store.ts → electron/services/companion-runtime-state-persistence.service.ts}

@@ -7,7 +7,7 @@ type CompanionRuntimeState = {
   baseUrl: string;
 };
 
-export class CompanionRuntimeStateStore {
+export class CompanionRuntimeStatePersistenceService {
   constructor(private readonly filePath: string) {}
 
   readonly write = (state: CompanionRuntimeState): void => {

package/{src/stores/companion-window-position.store.ts → electron/services/companion-window-position-persistence.service.ts}

@@ -6,7 +6,7 @@ type WindowBounds = {
   y?: number;
 };
 
-export class CompanionWindowPositionStore {
+export class CompanionWindowPositionPersistenceService {
   constructor(private readonly filePath: string) {}
 
   readonly read = (): WindowBounds | null => {
@@ -25,7 +25,7 @@ export class CompanionWindowPositionStore {
     writeFileSync(this.filePath, JSON.stringify(bounds, null, 2));
   };
 
-  static readonly fromUserData = (userDataPath: string): CompanionWindowPositionStore => {
-    return new CompanionWindowPositionStore(resolve(userDataPath, "companion-window.json"));
+  static readonly fromUserData = (userDataPath: string): CompanionWindowPositionPersistenceService => {
+    return new CompanionWindowPositionPersistenceService(resolve(userDataPath, "companion-window.json"));
   };
 }

package/{src → electron}/services/companion-window.service.ts

@@ -1,23 +1,25 @@
-import { app, BrowserWindow, ipcMain, shell } from "electron";
-import type { CompanionAvatarView } from "../types/companion.types.js";
-import type { CompanionWindowPositionStore } from "../stores/companion-window-position.store.js";
-import { renderCompanionHtml } from "../utils/companion-renderer-html.utils.js";
+import { BrowserWindow, ipcMain, shell } from "electron";
+
+import type { CompanionShellBootstrap } from "../types/companion-shell.types.js";
+import type { CompanionWindowPositionPersistenceService } from "./companion-window-position-persistence.service.js";
 
 export class CompanionWindowService {
   private window: BrowserWindow | null = null;
-  private currentView: CompanionAvatarView | null = null;
 
-  constructor(
-    private readonly preloadPath: string,
-    private readonly positionStore: CompanionWindowPositionStore
-  ) {}
+  constructor(private readonly options: {
+    preloadPath: string;
+    rendererEntryPath: string;
+    positionPersistenceService: CompanionWindowPositionPersistenceService;
+    baseUrl: string;
+    onQuit: () => void;
+  }) {}
 
   readonly create = async (): Promise<void> => {
     if (this.window) {
       return;
     }
 
-    const bounds = this.positionStore.read();
+    const bounds = this.options.positionPersistenceService.read();
     this.window = new BrowserWindow({
       width: 112,
       height: 132,
@@ -31,7 +33,7 @@ export class CompanionWindowService {
       skipTaskbar: true,
       hasShadow: false,
       webPreferences: {
-        preload: this.preloadPath,
+        preload: this.options.preloadPath,
         contextIsolation: true,
         nodeIntegration: false
       }
@@ -52,26 +54,22 @@ export class CompanionWindowService {
 
     ipcMain.removeHandler("companion:open");
     ipcMain.handle("companion:open", async () => {
-      const openUrl = this.currentView?.openUrl;
-      if (openUrl) {
-        await shell.openExternal(openUrl);
-      }
+      await shell.openExternal(this.options.baseUrl);
       return null;
     });
     ipcMain.removeHandler("companion:quit");
     ipcMain.handle("companion:quit", async () => {
-      app.quit();
+      this.options.onQuit();
       return null;
     });
-
-    ipcMain.removeAllListeners("companion:ready");
-    ipcMain.on("companion:ready", () => {
-      if (this.currentView) {
-        this.window?.webContents.send("companion:view", this.currentView);
-      }
+    ipcMain.removeHandler("companion:get-bootstrap");
+    ipcMain.handle("companion:get-bootstrap", async (): Promise<CompanionShellBootstrap> => {
+      return {
+        baseUrl: this.options.baseUrl
+      };
     });
 
-    await this.window.loadURL(`data:text/html;charset=utf-8,${encodeURIComponent(renderCompanionHtml())}`);
+    await this.window.loadFile(this.options.rendererEntryPath);
   };
 
   readonly show = (): void => {
@@ -89,15 +87,10 @@ export class CompanionWindowService {
     this.window.showInactive();
   };
 
-  readonly updateView = (view: CompanionAvatarView): void => {
-    this.currentView = view;
-    this.window?.webContents.send("companion:view", view);
-  };
-
   readonly destroy = (): void => {
     ipcMain.removeHandler("companion:open");
     ipcMain.removeHandler("companion:quit");
-    ipcMain.removeAllListeners("companion:ready");
+    ipcMain.removeHandler("companion:get-bootstrap");
     this.window?.destroy();
     this.window = null;
   };
@@ -107,7 +100,7 @@ export class CompanionWindowService {
     if (!bounds) {
       return;
     }
-    this.positionStore.write({
+    this.options.positionPersistenceService.write({
       x: bounds.x,
       y: bounds.y
     });

package/electron/types/companion-shell.types.ts

@@ -0,0 +1,8 @@
+export type CompanionAppOptions = {
+  baseUrl: string;
+  runtimeStatePath?: string;
+};
+
+export type CompanionShellBootstrap = {
+  baseUrl: string;
+};

package/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>NextClaw Companion</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/app/main.tsx"></script>
+  </body>
+</html>

package/module-structure.config.json

@@ -0,0 +1,25 @@
+{
+  "contractKind": "legacy",
+  "organizationModel": "legacy-apps-companion-workspace-root",
+  "rootPolicy": "contract-only",
+  "enforcement": "error",
+  "allowedRootDirectories": [
+    "electron",
+    "scripts",
+    "src"
+  ],
+  "requiredRootDirectories": [
+    "electron",
+    "src"
+  ],
+  "allowedRootFiles": [
+    "CHANGELOG.md",
+    "index.html",
+    "module-structure.config.json",
+    "package.json",
+    "postcss.config.mjs",
+    "tailwind.config.mjs",
+    "tsconfig.json",
+    "vite.config.mts"
+  ]
+}

package/package.json

@@ -1,31 +1,43 @@
 {
   "name": "@nextclaw/companion",
-  "version": "0.1.1-beta.0",
+  "version": "0.1.1-beta.2",
   "private": false,
   "description": "Standalone Electron companion shell for active NextClaw agents.",
   "author": "NextClaw Team",
   "homepage": "https://github.com/Peiiii/nextclaw",
-  "main": "dist/src/main.js",
+  "main": "dist/electron/main.js",
   "bin": {
-    "nextclaw-companion": "dist/src/launcher/index.js"
+    "nextclaw-companion": "dist/electron/launcher.js"
   },
   "license": "MIT",
   "dependencies": {
     "electron": "^32.2.1",
-    "@nextclaw/client-sdk": "0.1.1-beta.0"
+    "lucide-react": "^0.462.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "zustand": "^5.0.2",
+    "@nextclaw/client-sdk": "0.1.1-beta.2"
   },
   "devDependencies": {
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^6.0.1",
+    "autoprefixer": "^10.4.20",
     "@types/node": "^20.17.6",
+    "postcss": "^8.4.49",
+    "tailwindcss": "^3.4.15",
     "typescript": "^5.6.3",
+    "vite": "^8.0.3",
     "vitest": "^4.1.2"
   },
   "scripts": {
-    "dev": "pnpm build:main && node dist/src/launcher/index.js",
-    "build": "pnpm build:main",
+    "dev": "pnpm build && node dist/electron/launcher.js",
+    "build": "pnpm build:main && pnpm build:renderer",
     "build:main": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json --outDir dist --noEmit false",
-    "lint": "eslint \"src/**/*.ts\"",
+    "build:renderer": "vite build --config vite.config.mts",
+    "lint": "eslint \"electron/**/*.ts\" \"src/**/*.{ts,tsx}\" vite.config.mts",
     "tsc": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run src/companion-session-view.service.test.ts",
-    "smoke": "pnpm build:main && node scripts/smoke.mjs"
+    "test": "vitest run src/managers/companion-runtime.manager.test.ts",
+    "smoke": "pnpm build && node scripts/smoke.mjs"
   }
 }

package/postcss.config.mjs

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {}
+  }
+};

package/scripts/smoke.mjs

@@ -2,9 +2,10 @@ import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 
 const requiredFiles = [
-  resolve("dist/src/main.js"),
-  resolve("dist/src/launcher/index.js"),
-  resolve("dist/src/preload/index.js")
+  resolve("dist/electron/main.js"),
+  resolve("dist/electron/launcher.js"),
+  resolve("dist/electron/preload.js"),
+  resolve("dist/ui/index.html")
 ];
 
 const missingFiles = requiredFiles.filter((filePath) => !existsSync(filePath));

package/src/app/app.tsx

@@ -0,0 +1,17 @@
+import { useEffect } from "react";
+
+import { CompanionShellContainer } from "./components/companion-shell.container.js";
+import { usePresenter } from "./providers/companion-presenter.provider.js";
+
+export function App() {
+  const presenter = usePresenter();
+
+  useEffect(() => {
+    void presenter.bootstrap();
+    return () => {
+      presenter.shutdown();
+    };
+  }, [presenter]);
+
+  return <CompanionShellContainer />;
+}

package/src/app/components/companion-shell.container.tsx

@@ -0,0 +1,67 @@
+import { ExternalLink, X } from "lucide-react";
+
+import { useCompanionRuntimeStore } from "../../stores/companion-runtime.store.js";
+import { useCompanionShellStore } from "../../stores/companion-shell.store.js";
+import { usePresenter } from "../providers/companion-presenter.provider.js";
+
+export function CompanionShellContainer() {
+  const presenter = usePresenter();
+  const view = useCompanionRuntimeStore((state) => state.snapshot.currentView);
+  const connectionState = useCompanionRuntimeStore((state) => state.snapshot.connectionState);
+  const bootstrapped = useCompanionShellStore((state) => state.snapshot.bootstrapped);
+
+  const statusColorClass = connectionState === "running"
+    ? "bg-success"
+    : connectionState === "offline"
+      ? "bg-danger"
+      : "bg-slate-300";
+
+  return (
+    <div className="h-screen w-screen overflow-hidden bg-transparent">
+      <div className="grid h-full place-items-center">
+        <div className="grid w-[112px] justify-items-center gap-2">
+          <div className="drag-region relative grid h-24 w-24 place-items-center overflow-hidden rounded-[28px] border border-white/70 bg-white/90 shadow-companion backdrop-blur-xl">
+            <div className="no-drag absolute right-1.5 top-1.5 z-20 flex gap-1">
+              <button
+                type="button"
+                aria-label="Open NextClaw"
+                onClick={() => void presenter.companionShellManager.open()}
+                className="grid h-5 w-5 place-items-center rounded-full bg-slate-900/10 text-slate-700 transition hover:bg-slate-900/15"
+              >
+                <ExternalLink className="h-3 w-3" />
+              </button>
+              <button
+                type="button"
+                aria-label="Quit Companion"
+                onClick={() => void presenter.companionShellManager.quit()}
+                className="grid h-5 w-5 place-items-center rounded-full bg-slate-900/10 text-slate-700 transition hover:bg-slate-900/15"
+              >
+                <X className="h-3 w-3" />
+              </button>
+            </div>
+            {view.avatarUrl ? (
+              <img src={view.avatarUrl} alt="" className="h-full w-full object-cover" />
+            ) : (
+              <span className="grid h-full w-full place-items-center bg-gradient-to-b from-white to-slate-200 text-[28px] font-bold text-slate-800">
+                {(view.title || "NC").slice(0, 2).toUpperCase()}
+              </span>
+            )}
+            <span className={`absolute bottom-2 right-2 h-3.5 w-3.5 rounded-full border-2 border-white ${statusColorClass}`} />
+          </div>
+          <button
+            type="button"
+            onClick={() => void presenter.companionShellManager.open()}
+            className="no-drag w-full rounded-xl px-1 text-center"
+          >
+            <div className="truncate text-[12px] font-semibold leading-4 text-slate-900">
+              {bootstrapped ? view.title : "NextClaw"}
+            </div>
+            <div className="truncate pt-0.5 text-[11px] leading-4 text-slate-500">
+              {bootstrapped ? view.subtitle : "Connecting"}
+            </div>
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/app/index.css

@@ -0,0 +1,37 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  * {
+    box-sizing: border-box;
+  }
+
+  html,
+  body,
+  #root {
+    margin: 0;
+    width: 100%;
+    height: 100%;
+    overflow: hidden;
+    background: transparent;
+    color: rgb(15 23 42);
+    font-family: "SF Pro Display", "Inter", "Helvetica Neue", sans-serif;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+  }
+
+  button {
+    font: inherit;
+  }
+}
+
+@layer utilities {
+  .drag-region {
+    -webkit-app-region: drag;
+  }
+
+  .no-drag {
+    -webkit-app-region: no-drag;
+  }
+}

package/src/app/main.tsx

@@ -0,0 +1,15 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+
+import { App } from "./app.js";
+import { CompanionPresenterProvider } from "./providers/companion-presenter.provider.js";
+import { companionPresenter } from "../presenters/companion.presenter.js";
+import "./index.css";
+
+createRoot(document.getElementById("root") as HTMLElement).render(
+  <StrictMode>
+    <CompanionPresenterProvider presenter={companionPresenter}>
+      <App />
+    </CompanionPresenterProvider>
+  </StrictMode>
+);

package/src/app/providers/companion-presenter.provider.tsx

@@ -0,0 +1,27 @@
+import { createContext, useContext, type ReactNode } from "react";
+
+import type { CompanionPresenter } from "../../presenters/companion.presenter.js";
+
+const CompanionPresenterContext = createContext<CompanionPresenter | null>(null);
+
+export function CompanionPresenterProvider({
+  presenter,
+  children
+}: {
+  presenter: CompanionPresenter;
+  children: ReactNode;
+}) {
+  return (
+    <CompanionPresenterContext.Provider value={presenter}>
+      {children}
+    </CompanionPresenterContext.Provider>
+  );
+}
+
+export function usePresenter(): CompanionPresenter {
+  const presenter = useContext(CompanionPresenterContext);
+  if (!presenter) {
+    throw new Error("usePresenter must be used inside CompanionPresenterProvider");
+  }
+  return presenter;
+}

package/src/managers/companion-runtime.manager.test.ts

@@ -0,0 +1,56 @@
+import { beforeEach, describe, expect, it } from "vitest";
+
+import { useCompanionRuntimeStore } from "../stores/companion-runtime.store.js";
+import { CompanionRuntimeManager } from "./companion-runtime.manager.js";
+
+describe("CompanionRuntimeManager", () => {
+  beforeEach(() => {
+    useCompanionRuntimeStore.getState().reset();
+  });
+
+  it("prefers the most recently updated running session", () => {
+    const manager = new CompanionRuntimeManager();
+    const baseUrl = "http://127.0.0.1:55667";
+
+    (manager as unknown as { baseUrl: string | null }).baseUrl = baseUrl;
+
+    const snapshot = manager.syncRuntimeSnapshot({
+      agents: [{ id: "writer", displayName: "Writer" }],
+      sessions: [
+        { sessionId: "older", agentId: "writer", messageCount: 1, updatedAt: "2026-05-05T00:00:00.000Z", status: "running" },
+        { sessionId: "newer", agentId: "writer", messageCount: 2, updatedAt: "2026-05-06T00:00:00.000Z", status: "running" }
+      ]
+    });
+
+    expect(snapshot.currentView.sessionId).toBe("newer");
+    expect(snapshot.currentView.title).toBe("Writer");
+    expect(snapshot.connectionState).toBe("running");
+  });
+
+  it("falls back to an idle shell view when no running session exists", () => {
+    const manager = new CompanionRuntimeManager();
+    const baseUrl = "http://127.0.0.1:55667";
+
+    (manager as unknown as { baseUrl: string | null }).baseUrl = baseUrl;
+
+    const snapshot = manager.syncRuntimeSnapshot({
+      agents: [],
+      sessions: []
+    });
+
+    expect(snapshot.currentView.state).toBe("idle");
+    expect(snapshot.currentView.subtitle).toBe("No active agent");
+    expect(snapshot.connectionState).toBe("idle");
+  });
+
+  it("produces an offline snapshot with a readable reason", () => {
+    const manager = new CompanionRuntimeManager();
+    (manager as unknown as { baseUrl: string | null }).baseUrl = "http://127.0.0.1:55667";
+
+    const snapshot = manager.applyOfflineState({ summary: "Cannot reach runtime" });
+
+    expect(snapshot.connectionState).toBe("offline");
+    expect(snapshot.currentView.state).toBe("offline");
+    expect(snapshot.currentView.subtitle).toBe("Cannot reach runtime");
+  });
+});