diff --git a/package.json b/package.json
index 78025ab..fca2bc6 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
{
"name": "@simoncatbot/rocclaw",
- "version": "0.1.0",
- "description": "Focused operator studio for OpenClaw - Web dashboard for AI agent management",
+ "version": "0.9.0-alpha.0",
+ "description": "⚠️ ALPHA PREVIEW — Focused operator studio for OpenClaw AI agents. This is early software — expect rough edges.",
"main": "server/index.js",
"bin": {
"rocclaw": "./server/index.js"
@@ -19,7 +19,9 @@
"agent",
"dashboard",
"chat",
- "nextjs"
+ "nextjs",
+ "alpha",
+ "operator-studio"
],
"author": "SimonCatBot",
"license": "MIT",
diff --git a/tests/e2e/agent-avatar-settings.spec.ts b/tests/e2e/agent-avatar-settings.spec.ts
new file mode 100644
index 0000000..2696ca5
--- /dev/null
+++ b/tests/e2e/agent-avatar-settings.spec.ts
@@ -0,0 +1,110 @@
+import { expect, test } from "@playwright/test";
+import { stubRocclawRoute } from "./helpers/rocclawRoute";
+import { stubRuntimeRoutes } from "./helpers/runtimeRoute";
+
+const FLEET_WITH_TWO_AGENTS = {
+ seeds: [
+ { agentId: "agent-1", name: "Alice", sessionKey: "agent:agent-1:main" },
+ { agentId: "agent-2", name: "Bob", sessionKey: "agent:agent-2:main" },
+ ],
+ sessionCreatedAgentIds: [],
+ sessionSettingsSyncedAgentIds: [],
+ summaryPatches: [],
+ suggestedSelectedAgentId: "agent-1",
+ configSnapshot: null,
+};
+
+test.beforeEach(async ({ page }) => {
+ await stubRocclawRoute(page, {
+ version: 1,
+ gateway: null,
+ focused: {},
+ avatars: {},
+ });
+ await stubRuntimeRoutes(page, {
+ summary: { status: "connected" },
+ fleetResult: FLEET_WITH_TWO_AGENTS,
+ });
+});
+
+test("fleet row click applies selected CSS class to clicked agent", async ({ page }) => {
+ await page.goto("/");
+
+ await expect(page.getByTestId("fleet-agent-row-agent-1")).toBeVisible();
+ await expect(page.getByTestId("fleet-agent-row-agent-2")).toBeVisible();
+
+ // Agent-2 starts unselected
+ const agent2 = page.getByTestId("fleet-agent-row-agent-2");
+ await expect(agent2).not.toHaveClass(/ui-card-selected/);
+
+ // Click selects agent-2
+ await agent2.click();
+ await expect(agent2).toHaveClass(/ui-card-selected/);
+
+ // Agent-1 is no longer selected
+ const agent1 = page.getByTestId("fleet-agent-row-agent-1");
+ await expect(agent1).not.toHaveClass(/ui-card-selected/);
+});
+
+test("fleet row click triggers PUT request with focused selectedAgentId", async ({ page }) => {
+ await page.goto("/");
+
+ await expect(page.getByTestId("fleet-agent-row-agent-1")).toBeVisible();
+
+ // Capture the focused PUT request
+ const focusedPut = page.waitForRequest((req) => {
+ if (!req.url().includes("/api/rocclaw") || req.method() !== "PUT") return false;
+ try {
+ const payload = JSON.parse(req.postData() ?? "{}");
+ return (
+ payload.focused &&
+ Object.values(payload.focused).some(
+ (entry: unknown) =>
+ typeof entry === "object" &&
+ entry !== null &&
+ "selectedAgentId" in entry &&
+ (entry as { selectedAgentId: string }).selectedAgentId === "agent-2"
+ )
+ );
+ } catch {
+ return false;
+ }
+ });
+
+ await page.getByTestId("fleet-agent-row-agent-2").click();
+ const request = await focusedPut;
+
+ const payload = JSON.parse(request.postData() ?? "{}");
+ const focusedEntry = Object.values(payload.focused ?? {})[0] as {
+ selectedAgentId: string;
+ } | null;
+ expect(focusedEntry?.selectedAgentId).toBe("agent-2");
+});
+
+test("avatar shuffle triggers PUT request with avatar data", async ({ page }) => {
+ await page.goto("/");
+
+ await expect(page.getByTestId("fleet-agent-row-agent-1")).toBeVisible();
+ await page.getByTestId("fleet-agent-row-agent-1").click();
+
+ // Wait for the inspect panel's AvatarSelector to render — look for shuffle button
+ await expect(page.getByRole("button", { name: /shuffle/i })).toBeVisible({ timeout: 10000 });
+
+ // Capture avatar PUT triggered by shuffle
+ const avatarPut = page.waitForRequest((req) => {
+ if (!req.url().includes("/api/rocclaw") || req.method() !== "PUT") return false;
+ try {
+ const payload = JSON.parse(req.postData() ?? "{}");
+ return "avatars" in payload || "avatarSources" in payload;
+ } catch {
+ return false;
+ }
+ });
+
+ await page.getByRole("button", { name: /shuffle/i }).click();
+
+ const request = await avatarPut;
+ expect(request).toBeDefined();
+ const payload = JSON.parse(request.postData() ?? "{}");
+ expect(payload.avatars ?? payload.avatarSources).toBeDefined();
+});
diff --git a/tests/e2e/avatar-toggle.spec.ts b/tests/e2e/avatar-toggle.spec.ts
new file mode 100644
index 0000000..0dd3d69
--- /dev/null
+++ b/tests/e2e/avatar-toggle.spec.ts
@@ -0,0 +1,130 @@
+import { expect, test } from "@playwright/test";
+import { stubRocclawRoute } from "./helpers/rocclawRoute";
+import { stubRuntimeRoutes } from "./helpers/runtimeRoute";
+
+const FLEET_WITH_TWO_AGENTS = {
+ seeds: [
+ { agentId: "agent-1", name: "Alice", sessionKey: "agent:agent-1:main" },
+ { agentId: "agent-2", name: "Bob", sessionKey: "agent:agent-2:main" },
+ ],
+ sessionCreatedAgentIds: [],
+ sessionSettingsSyncedAgentIds: [],
+ summaryPatches: [],
+ suggestedSelectedAgentId: "agent-1",
+ configSnapshot: null,
+};
+
+test.beforeEach(async ({ page }) => {
+ await stubRocclawRoute(page, {
+ version: 1,
+ gateway: null,
+ focused: {},
+ avatars: {},
+ });
+ await stubRuntimeRoutes(page, {
+ summary: { status: "connected" },
+ fleetResult: FLEET_WITH_TWO_AGENTS,
+ });
+});
+
+test("footer avatar toggle opens dropdown with all three mode options", async ({ page }) => {
+ await page.goto("/");
+
+ // Wait for fleet to hydrate
+ await expect(page.getByTestId("fleet-agent-row-agent-1")).toBeVisible();
+
+ // Footer is rendered
+ const footer = page.locator("footer");
+ await expect(footer).toBeVisible();
+
+ // Footer avatar toggle button is present
+ const avatarToggle = page.getByRole("button", { name: /avatar mode: auto/i });
+ await expect(avatarToggle).toBeVisible();
+
+ // Open the dropdown
+ await avatarToggle.click();
+
+ // Dropdown items appear with descriptive accessible names
+ // Each mode button's accessible name is "{label} {description}"
+ await expect(page.getByRole("button", { name: /auto procedural/i })).toBeVisible();
+ await expect(page.getByRole("button", { name: /default profile/i })).toBeVisible();
+ await expect(page.getByRole("button", { name: /custom custom/i })).toBeVisible();
+});
+
+test("selecting default mode closes dropdown and updates toggle title", async ({ page }) => {
+ await page.goto("/");
+ await expect(page.getByTestId("fleet-agent-row-agent-1")).toBeVisible();
+
+ // Open dropdown
+ await page.getByRole("button", { name: /avatar mode: auto/i }).click();
+
+ // Select Default mode
+ await page.getByRole("button", { name: /default profile/i }).click();
+
+ // Dropdown is closed
+ await expect(page.getByRole("button", { name: /auto procedural/i })).not.toBeVisible();
+
+ // Toggle reflects the new mode — re-query to avoid stale locator
+ await expect(
+ page.getByRole("button", { name: /avatar mode: default/i })
+ ).toHaveAttribute("title", "Avatar mode: Default");
+});
+
+test("selecting custom mode persists across page reload", async ({ page }) => {
+ await page.goto("/");
+ await expect(page.getByTestId("fleet-agent-row-agent-1")).toBeVisible();
+
+ // Select Custom
+ await page.getByRole("button", { name: /avatar mode: auto/i }).click();
+ await page.getByRole("button", { name: /custom custom/i }).click();
+
+ // Reload — mode is restored from localStorage
+ await page.reload();
+ await expect(page.getByTestId("fleet-agent-row-agent-1")).toBeVisible();
+ await expect(
+ page.getByRole("button", { name: /avatar mode: custom/i })
+ ).toHaveAttribute("title", "Avatar mode: Custom");
+});
+
+test("footer avatar toggle is present even when fleet is empty", async ({ page }) => {
+ // Override stubs with empty fleet before navigating
+ await stubRuntimeRoutes(page, {
+ summary: { status: "connected" },
+ fleetResult: {
+ seeds: [],
+ sessionCreatedAgentIds: [],
+ sessionSettingsSyncedAgentIds: [],
+ summaryPatches: [],
+ suggestedSelectedAgentId: null,
+ configSnapshot: null,
+ },
+ });
+
+ await page.goto("/");
+
+ // Footer is rendered
+ const footer = page.locator("footer");
+ await expect(footer).toBeVisible();
+
+ // Avatar toggle is still present even when fleet is empty
+ const avatarToggle = page.getByRole("button", { name: /avatar mode/i });
+ await expect(avatarToggle).toBeVisible();
+ await expect(avatarToggle).toHaveAttribute("title", "Avatar mode: Auto");
+});
+
+test("agent row selection is reflected via CSS class change", async ({ page }) => {
+ await page.goto("/");
+ await expect(page.getByTestId("fleet-agent-row-agent-1")).toBeVisible();
+
+ // Agent-2 starts unselected
+ const agent2 = page.getByTestId("fleet-agent-row-agent-2");
+ await expect(agent2).not.toHaveClass(/ui-card-selected/);
+
+ // Click selects agent-2
+ await agent2.click();
+ await expect(agent2).toHaveClass(/ui-card-selected/);
+
+ // Agent-1 is no longer selected
+ const agent1 = page.getByTestId("fleet-agent-row-agent-1");
+ await expect(agent1).not.toHaveClass(/ui-card-selected/);
+});
diff --git a/tests/unit/agentAvatar.test.ts b/tests/unit/agentAvatar.test.ts
new file mode 100644
index 0000000..f5f6071
--- /dev/null
+++ b/tests/unit/agentAvatar.test.ts
@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+
+import { deriveDefaultIndex, buildDefaultAvatarUrl } from "@/features/agents/components/AgentAvatar";
+
+describe("deriveDefaultIndex", () => {
+ it("returns a number within [0, 11] for any seed", () => {
+ for (let i = 0; i < 100; i++) {
+ const index = deriveDefaultIndex(`agent-${i}`, 0);
+ expect(index).toBeGreaterThanOrEqual(0);
+ expect(index).toBeLessThan(12);
+ }
+ });
+
+ it("produces different indices for different seeds", () => {
+ const results = new Set
+ 