verstak
/
verstak-docs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
verstak-docs/docs/superpowers/plans/2026-07-12-alpha-shell-ux.md

8.4 KiB
Raw Blame History

Alpha Shell UX Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox syntax for tracking.

Goal: Make the Desktop overview scoped and actionable, hide diagnostic plugin IDs by default, and remove alpha UI strings that expose implementation noise.

Architecture: The shell consumes stable workspace IDs and plugin capabilities rather than hard-coded namespaces. Overview builds deterministic case-scoped projections; debug display is a presentation preference plus a session-only command-line override.

Tech Stack: Svelte, Wails app settings, Go tests, Playwright E2E, existing i18n catalogs.

Global Constraints

  • Default UI labels are Russian and use Дела, Входящие, Активности, Журнал.
  • A normal tab never shows a plugin ID.
  • Settings Debug Show plugin IDs defaults false; Desktop --debug enables it only for that run.
  • Overview never leaks an unscoped event into every case.
  • Todo entries are included only if todo.workspace capability is loaded.
  • No action opens or creates a Дело implicitly.

Task 1: Add effective debug display setting and human plugin tab labels

Files:

  • Modify: /home/mirivlad/git/verstak2/verstak-desktop/main.go
  • Modify: /home/mirivlad/git/verstak2/verstak-desktop/internal/core/appsettings/manager.go
  • Modify: /home/mirivlad/git/verstak2/verstak-desktop/internal/core/appsettings/manager_test.go
  • Modify: /home/mirivlad/git/verstak2/verstak-desktop/internal/api/app.go
  • Modify: /home/mirivlad/git/verstak2/verstak-desktop/internal/api/app_test.go
  • Modify: /home/mirivlad/git/verstak2/verstak-desktop/frontend/src/lib/shell/WorkspaceHost.svelte
  • Modify: /home/mirivlad/git/verstak2/verstak-desktop/frontend/src/lib/plugin-manager/PluginManager.svelte
  • Modify: /home/mirivlad/git/verstak2/verstak-desktop/frontend/src/lib/i18n/catalogs/en.js
  • Modify: /home/mirivlad/git/verstak2/verstak-desktop/frontend/src/lib/i18n/catalogs/ru.js
  • Modify: /home/mirivlad/git/verstak2/verstak-desktop/frontend/e2e/plugin-api-bridge.spec.js

Interfaces:

  • Persisted app setting showPluginIds bool defaults false.

  • GetAppSettings returns effectiveShowPluginIds and UpdateAppSettings accepts showPluginIds.

  • Runtime --debug sets effectiveShowPluginIds true without persisting it.

  • Step 1: Write failing app-setting and E2E tests

Add a Go test proving the setting preserves theme and language, plus a browser test proving normal mode has no raw ID and debug mode has one:

await expect(page.locator('[role="tab"]').filter({ hasText: 'verstak.' })).toHaveCount(0);
await mockAppSettings({ showPluginIds: true });
await expect(page.locator('[role="tab"]').filter({ hasText: 'verstak.default-editor' })).toHaveCount(1);
  • Step 2: Run red

Run:

cd /home/mirivlad/git/verstak2/verstak-desktop
GOCACHE=/tmp/verstak-go-cache go test ./internal/core/appsettings ./internal/api -run 'Test.*PluginIds' -count=1
cd frontend && npm run test:e2e -- plugin-api-bridge.spec.js

Expected: FAIL because no display preference exists.

  • Step 3: Implement presentation-only debug state

Parse --debug before Wails startup and keep it in App runtime state. Merge it with the persisted bool when returning effective settings. Render the localized manifest title normally; append the plugin ID only when effectiveShowPluginIds is true. Add the Debug settings checkbox and localized explanatory copy.

  • Step 4: Run green and commit

Run:

GOCACHE=/tmp/verstak-go-cache go test ./internal/core/appsettings ./internal/api -count=1
cd frontend && npm run test:e2e -- plugin-api-bridge.spec.js
git add main.go internal/core/appsettings internal/api frontend/src frontend/e2e/plugin-api-bridge.spec.js
git commit -m "feat: hide plugin IDs outside debug mode"

Expected: normal and debug labels are both verified.

Task 2: Implement deterministic case-scoped Overview

Files:

  • Modify: /home/mirivlad/git/verstak2/verstak-desktop/frontend/src/lib/shell/TodaySurface.svelte
  • Modify: /home/mirivlad/git/verstak2/verstak-desktop/frontend/src/lib/shell/WorkspaceHost.svelte
  • Modify: /home/mirivlad/git/verstak2/verstak-desktop/frontend/src/lib/i18n/catalogs/en.js
  • Modify: /home/mirivlad/git/verstak2/verstak-desktop/frontend/src/lib/i18n/catalogs/ru.js
  • Modify: /home/mirivlad/git/verstak2/verstak-desktop/frontend/e2e/ux-today.spec.js
  • Modify: /home/mirivlad/git/verstak2/verstak-desktop/frontend/e2e/ux-p0.spec.js
  • Modify: /home/mirivlad/git/verstak2/verstak-desktop/frontend/src/lib/test/wails-mock.js

Interfaces:

  • Every overview row has workspaceId and lastMeaningfulAt.

  • Needs attention maximum is five; Continue work maximum is four; Recent changes maximum is eight.

  • Hidden recommendation state is keyed by entity ID and invalidated by later meaningful change.

  • Step 1: Write failing scope and ranking tests

Add fixture events for two workspace IDs plus an unscoped event:

await seedOverview({
  selectedWorkspaceId: 'client-a',
  events: [
    { activityId: 'a', workspaceId: 'client-a', type: 'note.saved', occurredAt: now },
    { activityId: 'b', workspaceId: 'client-b', type: 'file.changed', occurredAt: now },
    { activityId: 'global', type: 'workspace.selected', occurredAt: now }
  ]
});
await expect(page.getByText(/client-b/i)).toHaveCount(0);
await expect(page.locator('[data-overview-section="continue"] [data-overview-item]')).toHaveCount(4);

Also assert no selection shows only the select/create prompt and up to five unassigned active Inbox captures.

  • Step 2: Run red

Run:

cd /home/mirivlad/git/verstak2/verstak-desktop/frontend
npm run test:e2e -- ux-today.spec.js ux-p0.spec.js

Expected: FAIL because rowsFor currently accepts untagged events for every workspace.

  • Step 3: Implement exact overview projections

Replace path-only filtering with workspaceId equality. Build:

  1. Needs attention: ready Journal candidates, active unprocessed captures, then urgent Todo rows only if todo.workspace capability exists; take five.
  2. Continue work: distinct entities updated in 14 days; sort by lastMeaningfulAt descending and the documented type tie-break; take four.
  3. Recent changes: note save/create, file create/rename or last change per file, saved link, and Journal create in seven days; take eight.

Persist Hide recommendation without changing underlying data. Use localized empty states and remove English technical strings.

  • Step 4: Run green and commit

Run:

npm run test:e2e -- ux-today.spec.js ux-p0.spec.js
git add src/lib/shell/TodaySurface.svelte src/lib/shell/WorkspaceHost.svelte src/lib/i18n frontend/e2e/ux-today.spec.js frontend/e2e/ux-p0.spec.js src/lib/test/wails-mock.js
git commit -m "feat: make overview case-scoped and actionable"

Expected: limits, scope, empty state, and recommendation hide tests pass.

Task 3: Verify alpha UX as a user sees it

Files:

  • Modify: /home/mirivlad/git/verstak2/verstak-desktop/frontend/e2e/ux-followup.spec.js
  • Modify: /home/mirivlad/git/verstak2/verstak-desktop/scripts/check-gui.sh

Interfaces:

  • E2E fixture uses effectiveShowPluginIds false by default.

  • GUI checker accepts a --debug-labels case.

  • Step 1: Write the final failing alpha scenarios

Add a scenario that creates a capture, assigns it, archives it globally, opens the assigned case, and verifies the capture is still present. Add a session candidate path to Journal and assert normal tab labels are human-readable.

await archiveGlobalCapture('capture-1');
await openWorkspace('client-a');
await expect(page.getByTestId('browser-capture-capture-1')).toBeVisible();
await expect(page.getByRole('tab', { name: /verstak\./i })).toHaveCount(0);
  • Step 2: Run red

Run:

npm run test:e2e -- ux-followup.spec.js

Expected: FAIL until the prior plans are integrated.

  • Step 3: Add deterministic GUI smoke commands

Extend check-gui.sh to start an isolated test vault, run normal and --debug screens, and save screenshots under frontend/e2e-results. The script must not read or mutate the user's normal vault.

  • Step 4: Run green and commit

Run:

npm run test:e2e -- ux-followup.spec.js
GOCACHE=/tmp/verstak-go-cache ./scripts/check-gui.sh
git add frontend/e2e/ux-followup.spec.js scripts/check-gui.sh
git commit -m "test: cover first alpha UX smoke flow"

Expected: E2E and isolated GUI smoke pass.