gui/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is forge.lthn.ai/core/gui — a display/windowing module for the Core web3 desktop framework. It provides window management, dialogs, system tray, clipboard, notifications, theming, layouts, and real-time WebSocket events. Built on Wails v3 (Go backend) with an Angular 20 custom element frontend.

Build & Development Commands

Go backend

go build ./...              # Build all packages
go test ./...               # Run all tests
go test ./pkg/display/...   # Run display package tests
go test -race ./...         # Run tests with race detection
go test -cover ./...        # Run tests with coverage
go test -run TestNew ./pkg/display/  # Run a single test

Angular frontend (pkg/display/ui/)

cd pkg/display/ui
npm install                 # Install dependencies
npm run build               # Production build
npm run watch               # Dev watch mode
npm run start               # Dev server (localhost:4200)
npm test                    # Unit tests (Karma/Jasmine)

Architecture

Service-based design with Core DI

The display Service registers with forge.lthn.ai/core/go's service container via Register(c *core.Core). It embeds core.ServiceRuntime[Options] for lifecycle management and access to sibling services.

Interface abstraction for testability

All Wails application APIs are abstracted behind interfaces in interfaces.go (App, WindowManager, MenuManager, DialogManager, etc.). The wailsApp adapter wraps the real Wails app. Tests inject a mockApp instead — see mocks_test.go and the newServiceWithMockApp(t) helper.

Package structure (pkg/)

Package	Responsibility
display	Orchestrator service — bridges sub-service IPC to WebSocket events, menu/tray setup, config persistence
window	Window lifecycle, Manager, StateManager (position persistence), LayoutManager (named arrangements), tiling/snapping
menu	Application menu construction via platform abstraction
systray	System tray icon, tooltip, menu via platform abstraction
dialog	File open/save, message, confirm, and prompt dialogs
clipboard	Clipboard read/write/clear
notification	System notifications with permission management
screen	Screen/monitor queries (list, primary, at-point, work areas)
environment	Theme detection (dark/light) and OS environment info
keybinding	Global keyboard shortcut registration
contextmenu	Named context menu registration and lifecycle
browser	Open URLs and files in the default browser
dock	macOS dock icon visibility and badge
lifecycle	Application lifecycle events (start, terminate, suspend, resume)
webview	Webview automation (eval, click, type, screenshot, DOM queries)
mcp	MCP tool subsystem — exposes all services as Model Context Protocol tools

Patterns used throughout

• Platform abstraction: Each sub-service defines a Platform interface and PlatformWindow/PlatformTray/etc. types; tests inject mocks
• Functional options: WindowOption functions (WithName(), WithTitle(), WithSize(), etc.) configure window.Window descriptors
• IPC message bus: Sub-services communicate via core.QUERY, core.PERFORM, and core.ACTION — display orchestrates and bridges to WebSocket events
• Event broadcasting: WSEventManager uses gorilla/websocket with a buffered channel (eventBuffer) and per-client subscription filtering (supports "*" wildcard)
• Error handling: All errors use coreerr.E(op, msg, err) from forge.lthn.ai/core/go-log (aliased as coreerr), never fmt.Errorf
• File I/O: Use forge.lthn.ai/core/go-io (coreio.Local) for filesystem operations, never os.ReadFile/os.WriteFile

Testing

• Framework: testify (assert + require)
• Each sub-package has its own *_test.go with mock platform implementations
• pkg/window: NewManagerWithDir / NewStateManagerWithDir / NewLayoutManagerWithDir accept custom config dirs for isolated tests
• pkg/display: newTestCore(t) creates a real core.Core instance for integration-style tests
• Sub-services use mock_platform.go or mock_test.go for platform mocks

CI/CD

Forgejo Actions (.forgejo/workflows/):

• test.yml: Runs go test with race detection and coverage on push to main/dev and PRs to main
• security-scan.yml: Security scanning on push to main/dev/feat/* and PRs to main

Both use reusable workflows from core/go-devops.

Dependencies

• forge.lthn.ai/core/go — Core framework with service container and DI
• forge.lthn.ai/core/go-log — Structured errors (coreerr.E())
• forge.lthn.ai/core/go-io — Filesystem abstraction (coreio.Local)
• forge.lthn.ai/core/config — Configuration file management
• github.com/wailsapp/wails/v3 — Desktop app framework (alpha.74)
• github.com/gorilla/websocket — WebSocket for real-time events
• github.com/stretchr/testify — Test assertions
• github.com/modelcontextprotocol/go-sdk — MCP tool registration

Repository migration note

Import paths were recently migrated from github.com/Snider/Core to forge.lthn.ai/core/*. The cmd/ directories visible in git status are deleted artifacts from this migration and prior app scaffolds.