feat(stubs): rebuild Wails v3 stub bridge from clean dev — 15 files, 479 exports

Rebuilt from scratch on current dev (post-fleet AX passes).

Stub files:
- application.go (expanded App with 12 managers, WebviewWindow satisfies Window)
- application_options.go (Options, Mac/Win/Linux/iOS/Android, Server, TLS, Assets)
- browser_manager.go, browser_window.go (~47 no-op methods)
- clipboard.go, context_menu.go, dialog.go (full dialog builder API)
- environment.go, events.go (EventManager with On/Off/Emit/Reset)
- keybinding.go, menuitem.go (42 Role constants)
- screen.go (Rect/Point/Size geometry), services.go (generic Service[T])
- webview_window_options.go (full platform types)
- window.go (Window interface ~50 methods)

Wails v3 submodule at internal/wails3/ pinned to alpha 74.
All 16 gui packages build and test clean.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -38,38 +38,43 @@ The display `Service` registers with `forge.lthn.ai/core/go`'s service container
 
 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.
 
-### Key files in pkg/display/
+### Package structure (pkg/)
 
-| File | Responsibility |
-|------|---------------|
-| `display.go` | Service struct, lifecycle (`Startup`), window CRUD, screen queries, tiling/snapping/layout, workflow presets |
-| `window.go` | `WindowOption` functional options pattern, `Window` type alias for `application.WebviewWindowOptions` |
-| `window_state.go` | `WindowStateManager` — persists window position/size across restarts |
-| `layout.go` | `LayoutManager` — save/restore named window arrangements |
-| `events.go` | `WSEventManager` — WebSocket pub/sub for window/theme/screen events |
-| `interfaces.go` | Abstract interfaces + Wails adapter implementations |
-| `actions.go` | `ActionOpenWindow` IPC message type |
-| `menu.go` | Application menu construction |
-| `tray.go` | System tray setup |
-| `dialog.go` | File/directory dialogs |
-| `clipboard.go` | Clipboard read/write |
-| `notification.go` | System notifications |
-| `theme.go` | Dark/light mode detection |
-| `mocks_test.go` | Mock implementations of all interfaces for testing |
+| 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
 
-- **Functional options**: `WindowOption` functions (`WindowName()`, `WindowTitle()`, `WindowWidth()`, etc.) configure `application.WebviewWindowOptions`
-- **Type alias**: `Window = application.WebviewWindowOptions` — direct alias, not a wrapper
+- **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)
-- **Window lookup by name**: Most Service methods iterate `s.app.Window().GetAll()` and type-assert to `*application.WebviewWindow`, then match by `Name()`
+- **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)
-- Pattern: `newServiceWithMockApp(t)` creates a `Service` with mock Wails app — no real window system needed
-- `newTestCore(t)` creates a real `core.Core` instance for integration-style tests
-- Some tests use `defer func() { recover() }()` to handle nil panics from mock methods that return nil pointers (e.g., `Dialog().Info()`)
+- 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
 
@@ -82,9 +87,13 @@ 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
 

docs/RFC-CORE-008-AGENT-EXPERIENCE.md

@@ -0,0 +1,440 @@
+# RFC-025: Agent Experience (AX) Design Principles
+
+- **Status:** Draft
+- **Authors:** Snider, Cladius
+- **Date:** 2026-03-19
+- **Applies to:** All Core ecosystem packages (CoreGO, CorePHP, CoreTS, core-agent)
+
+## Abstract
+
+Agent Experience (AX) is a design paradigm for software systems where the primary code consumer is an AI agent, not a human developer. AX sits alongside User Experience (UX) and Developer Experience (DX) as the third era of interface design.
+
+This RFC establishes AX as a formal design principle for the Core ecosystem and defines the conventions that follow from it.
+
+## Motivation
+
+As of early 2026, AI agents write, review, and maintain the majority of code in the Core ecosystem. The original author has not manually edited code (outside of Core struct design) since October 2025. Code is processed semantically — agents reason about intent, not characters.
+
+Design patterns inherited from the human-developer era optimise for the wrong consumer:
+
+- **Short names** save keystrokes but increase semantic ambiguity
+- **Functional option chains** are fluent for humans but opaque for agents tracing configuration
+- **Error-at-every-call-site** produces 50% boilerplate that obscures intent
+- **Generic type parameters** force agents to carry type context that the runtime already has
+- **Panic-hiding conventions** (`Must*`) create implicit control flow that agents must special-case
+
+AX acknowledges this shift and provides principles for designing code, APIs, file structures, and conventions that serve AI agents as first-class consumers.
+
+## The Three Eras
+
+| Era | Primary Consumer | Optimises For | Key Metric |
+|-----|-----------------|---------------|------------|
+| UX | End users | Discoverability, forgiveness, visual clarity | Task completion time |
+| DX | Developers | Typing speed, IDE support, convention familiarity | Time to first commit |
+| AX | AI agents | Predictability, composability, semantic navigation | Correct-on-first-pass rate |
+
+AX does not replace UX or DX. End users still need good UX. Developers still need good DX. But when the primary code author and maintainer is an AI agent, the codebase should be designed for that consumer first.
+
+## Principles
+
+### 1. Predictable Names Over Short Names
+
+Names are tokens that agents pattern-match across languages and contexts. Abbreviations introduce mapping overhead.
+
+```
+Config    not  Cfg
+Service   not  Srv
+Embed     not  Emb
+Error     not  Err (as a subsystem name; err for local variables is fine)
+Options   not  Opts
+```
+
+**Rule:** If a name would require a comment to explain, it is too short.
+
+**Exception:** Industry-standard abbreviations that are universally understood (`HTTP`, `URL`, `ID`, `IPC`, `I18n`) are acceptable. The test: would an agent trained on any mainstream language recognise it without context?
+
+### 2. Comments as Usage Examples
+
+The function signature tells WHAT. The comment shows HOW with real values.
+
+```go
+// Detect the project type from files present
+setup.Detect("/path/to/project")
+
+// Set up a workspace with auto-detected template
+setup.Run(setup.Options{Path: ".", Template: "auto"})
+
+// Scaffold a PHP module workspace
+setup.Run(setup.Options{Path: "./my-module", Template: "php"})
+```
+
+**Rule:** If a comment restates what the type signature already says, delete it. If a comment shows a concrete usage with realistic values, keep it.
+
+**Rationale:** Agents learn from examples more effectively than from descriptions. A comment like "Run executes the setup process" adds zero information. A comment like `setup.Run(setup.Options{Path: ".", Template: "auto"})` teaches an agent exactly how to call the function.
+
+### 3. Path Is Documentation
+
+File and directory paths should be self-describing. An agent navigating the filesystem should understand what it is looking at without reading a README.
+
+```
+flow/deploy/to/homelab.yaml    — deploy TO the homelab
+flow/deploy/from/github.yaml   — deploy FROM GitHub
+flow/code/review.yaml           — code review flow
+template/file/go/struct.go.tmpl — Go struct file template
+template/dir/workspace/php/     — PHP workspace scaffold
+```
+
+**Rule:** If an agent needs to read a file to understand what a directory contains, the directory naming has failed.
+
+**Corollary:** The unified path convention (folder structure = HTTP route = CLI command = test path) is AX-native. One path, every surface.
+
+### 4. Templates Over Freeform
+
+When an agent generates code from a template, the output is constrained to known-good shapes. When an agent writes freeform, the output varies.
+
+```go
+// Template-driven — consistent output
+lib.RenderFile("php/action", data)
+lib.ExtractDir("php", targetDir, data)
+
+// Freeform — variance in output
+"write a PHP action class that..."
+```
+
+**Rule:** For any code pattern that recurs, provide a template. Templates are guardrails for agents.
+
+**Scope:** Templates apply to file generation, workspace scaffolding, config generation, and commit messages. They do NOT apply to novel logic — agents should write business logic freeform with the domain knowledge available.
+
+### 5. Declarative Over Imperative
+
+Agents reason better about declarations of intent than sequences of operations.
+
+```yaml
+# Declarative — agent sees what should happen
+steps:
+  - name: build
+    flow: tools/docker-build
+    with:
+      context: "{{ .app_dir }}"
+      image_name: "{{ .image_name }}"
+
+  - name: deploy
+    flow: deploy/with/docker
+    with:
+      host: "{{ .host }}"
+```
+
+```go
+// Imperative — agent must trace execution
+cmd := exec.Command("docker", "build", "--platform", "linux/amd64", "-t", imageName, ".")
+cmd.Dir = appDir
+if err := cmd.Run(); err != nil {
+    return fmt.Errorf("docker build: %w", err)
+}
+```
+
+**Rule:** Orchestration, configuration, and pipeline logic should be declarative (YAML/JSON). Implementation logic should be imperative (Go/PHP/TS). The boundary is: if an agent needs to compose or modify the logic, make it declarative.
+
+### 6. Universal Types (Core Primitives)
+
+Every component in the ecosystem accepts and returns the same primitive types. An agent processing any level of the tree sees identical shapes.
+
+```go
+// Universal contract
+setup.Run(core.Options{Path: ".", Template: "auto"})
+brain.New(core.Options{Name: "openbrain"})
+deploy.Run(core.Options{Flow: "deploy/to/homelab"})
+
+// Fractal — Core itself is a Service
+core.New(core.Options{
+    Services: []core.Service{
+        process.New(core.Options{Name: "process"}),
+        brain.New(core.Options{Name: "brain"}),
+    },
+})
+```
+
+**Core primitive types:**
+
+| Type | Purpose |
+|------|---------|
+| `core.Options` | Input configuration (what you want) |
+| `core.Config` | Runtime settings (what is active) |
+| `core.Data` | Embedded or stored content |
+| `core.Service` | A managed component with lifecycle |
+| `core.Result[T]` | Return value with OK/fail state |
+
+**What this replaces:**
+
+| Go Convention | Core AX | Why |
+|--------------|---------|-----|
+| `func With*(v) Option` | `core.Options{Field: v}` | Struct literal is parseable; option chain requires tracing |
+| `func Must*(v) T` | `core.Result[T]` | No hidden panics; errors flow through Core |
+| `func *For[T](c) T` | `c.Service("name")` | String lookup is greppable; generics require type context |
+| `val, err :=` everywhere | Single return via `core.Result` | Intent not obscured by error handling |
+| `_ = err` | Never needed | Core handles all errors internally |
+
+### 7. Directory as Semantics
+
+The directory structure tells an agent the intent before it reads a word. Top-level directories are semantic categories, not organisational bins.
+
+```
+plans/
+├── code/       # Pure primitives — read for WHAT exists
+├── project/    # Products — read for WHAT we're building and WHY
+└── rfc/        # Contracts — read for constraints and rules
+```
+
+**Rule:** An agent should know what kind of document it's reading from the path alone. `code/core/go/io/RFC.md` = a lib primitive spec. `project/ofm/RFC.md` = a product spec that cross-references code/. `rfc/snider/borg/RFC-BORG-006-SMSG-FORMAT.md` = an immutable contract for the Borg SMSG protocol.
+
+**Corollary:** The three-way split (code/project/rfc) extends principle 3 (Path Is Documentation) from files to entire subtrees. The path IS the metadata.
+
+### 8. Lib Never Imports Consumer
+
+Dependency flows one direction. Libraries define primitives. Consumers compose from them. A new feature in a consumer can never break a library.
+
+```
+code/core/go/*     → lib tier (stable foundation)
+code/core/agent/   → consumer tier (composes from go/*)
+code/core/cli/     → consumer tier (composes from go/*)
+code/core/gui/     → consumer tier (composes from go/*)
+```
+
+**Rule:** If package A is in `go/` and package B is in the consumer tier, B may import A but A must never import B. The repo naming convention enforces this: `go-{name}` = lib, bare `{name}` = consumer.
+
+**Why this matters for agents:** When an agent is dispatched to implement a feature in `core/agent`, it can freely import from `go-io`, `go-scm`, `go-process`. But if an agent is dispatched to `go-io`, it knows its changes are foundational — every consumer depends on it, so the contract must not break.
+
+### 9. Issues Are N+(rounds) Deep
+
+Problems in code and specs are layered. Surface issues mask deeper issues. Fixing the surface reveals the next layer. This is not a failure mode — it is the discovery process.
+
+```
+Pass 1: Find 16 issues (surface — naming, imports, obvious errors)
+Pass 2: Find 11 issues (structural — contradictions, missing types)
+Pass 3: Find 5 issues (architectural — signature mismatches, registration gaps)
+Pass 4: Find 4 issues (contract — cross-spec API mismatches)
+Pass 5: Find 2 issues (mechanical — path format, nil safety)
+Pass N: Findings are trivial → spec/code is complete
+```
+
+**Rule:** Iteration is required, not a failure. Each pass sees what the previous pass could not, because the context changed. An agent dispatched with the same task on the same repo will find different things each time — this is correct behaviour.
+
+**Corollary:** The cheapest model should do the most passes (surface work). The frontier model should arrive last, when only deep issues remain. Tiered iteration: grunt model grinds → mid model pre-warms → frontier model polishes.
+
+**Anti-pattern:** One-shot generation expecting valid output. No model, no human, produces correct-on-first-pass for non-trivial work. Expecting it wastes the first pass on surface issues that a cheaper pass would have caught.
+
+### 10. CLI Tests as Artifact Validation
+
+Unit tests verify the code. CLI tests verify the binary. The directory structure IS the command structure — path maps to command, Taskfile runs the test.
+
+```
+tests/cli/
+├── core/
+│   └── lint/
+│       ├── Taskfile.yaml          ← test `core-lint` (root)
+│       ├── run/
+│       │   ├── Taskfile.yaml      ← test `core-lint run`
+│       │   └── fixtures/
+│       ├── go/
+│       │   ├── Taskfile.yaml      ← test `core-lint go`
+│       │   └── fixtures/
+│       └── security/
+│           ├── Taskfile.yaml      ← test `core-lint security`
+│           └── fixtures/
+```
+
+**Rule:** Every CLI command has a matching `tests/cli/{path}/Taskfile.yaml`. The Taskfile runs the compiled binary against fixtures with known inputs and validates the output. If the CLI test passes, the underlying actions work — because CLI commands call actions, MCP tools call actions, API endpoints call actions. Test the CLI, trust the rest.
+
+**Pattern:**
+
+```yaml
+# tests/cli/core/lint/go/Taskfile.yaml
+version: '3'
+tasks:
+  test:
+    cmds:
+      - core-lint go --output json fixtures/ > /tmp/result.json
+      - jq -e '.findings | length > 0' /tmp/result.json
+      - jq -e '.summary.passed == false' /tmp/result.json
+```
+
+**Why this matters for agents:** An agent can validate its own work by running `task test` in the matching `tests/cli/` directory. No test framework, no mocking, no setup — just the binary, fixtures, and `jq` assertions. The agent builds the binary, runs the test, sees the result. If it fails, the agent can read the fixture, read the output, and fix the code.
+
+**Corollary:** Fixtures are planted bugs. Each fixture file has a known issue that the linter must find. If the linter doesn't find it, the test fails. Fixtures are the spec for what the tool must detect — they ARE the test cases, not descriptions of test cases.
+
+## Applying AX to Existing Patterns
+
+### File Structure
+
+```
+# AX-native: path describes content
+core/agent/
+├── go/                    # Go source
+├── php/                   # PHP source
+├── ui/                    # Frontend source
+├── claude/                # Claude Code plugin
+└── codex/                 # Codex plugin
+
+# Not AX: generic names requiring README
+src/
+├── lib/
+├── utils/
+└── helpers/
+```
+
+### Error Handling
+
+```go
+// AX-native: errors are infrastructure, not application logic
+svc := c.Service("brain")
+cfg := c.Config().Get("database.host")
+// Errors logged by Core. Code reads like a spec.
+
+// Not AX: errors dominate the code
+svc, err := c.ServiceFor[brain.Service]()
+if err != nil {
+    return fmt.Errorf("get brain service: %w", err)
+}
+cfg, err := c.Config().Get("database.host")
+if err != nil {
+    _ = err // silenced because "it'll be fine"
+}
+```
+
+### API Design
+
+```go
+// AX-native: one shape, every surface
+core.New(core.Options{
+    Name: "my-app",
+    Services: []core.Service{...},
+    Config: core.Config{...},
+})
+
+// Not AX: multiple patterns for the same thing
+core.New(
+    core.WithName("my-app"),
+    core.WithService(factory1),
+    core.WithService(factory2),
+    core.WithConfig(cfg),
+)
+```
+
+## The Plans Convention — AX Development Lifecycle
+
+The `plans/` directory structure encodes a development methodology designed for how generative AI actually works: iterative refinement across structured phases, not one-shot generation.
+
+### The Three-Way Split
+
+```
+plans/
+├── project/    # 1. WHAT and WHY — start here
+├── rfc/        # 2. CONSTRAINTS — immutable contracts
+└── code/       # 3. HOW — implementation specs
+```
+
+Each directory is a phase. Work flows from project → rfc → code. Each transition forces a refinement pass — you cannot write a code spec without discovering gaps in the project spec, and you cannot write an RFC without discovering assumptions in both.
+
+**Three places for data that can't be written simultaneously = three guaranteed iterations of "actually, this needs changing."** Refinement is baked into the structure, not bolted on as a review step.
+
+### Phase 1: Project (Vision)
+
+Start with `project/`. No code exists yet. Define:
+- What the product IS and who it serves
+- What existing primitives it consumes (cross-ref to `code/`)
+- What constraints it operates under (cross-ref to `rfc/`)
+
+This is where creativity lives. Map features to building blocks. Connect systems. The project spec is integrative — it references everything else.
+
+### Phase 2: RFC (Contracts)
+
+Extract the immutable rules into `rfc/`. These are constraints that don't change with implementation:
+- Wire formats, protocols, hash algorithms
+- Security properties that must hold
+- Compatibility guarantees
+
+RFCs are numbered per component (`RFC-BORG-006-SMSG-FORMAT.md`) and never modified after acceptance. If the contract changes, write a new RFC.
+
+### Phase 3: Code (Implementation Specs)
+
+Define the implementation in `code/`. Each component gets an RFC.md that an agent can implement from:
+- Struct definitions (the DTOs — see principle 6)
+- Method signatures and behaviour
+- Error conditions and edge cases
+- Cross-references to other code/ specs
+
+The code spec IS the product. Write the spec → dispatch to an agent → review output → iterate.
+
+### Pre-Launch: Alignment Protocol
+
+Before dispatching for implementation, verify spec-model alignment:
+
+```
+1. REVIEW — The implementation model (Codex/Jules) reads the spec
+   and reports missing elements. This surfaces the delta between
+   the model's training and the spec's assumptions.
+
+   "I need X, Y, Z to implement this" is the model saying
+   "I hear you but I'm missing context" — without asking.
+
+2. ADJUST — Update the spec to close the gaps. Add examples,
+   clarify ambiguities, provide the context the model needs.
+   This is shared alignment, not compromise.
+
+3. VERIFY — A different model (or sub-agent) reviews the adjusted
+   spec without the planner's bias. Fresh eyes on the contract.
+   "Does this make sense to someone who wasn't in the room?"
+
+4. READY — When the review findings are trivial or deployment-
+   related (not architectural), the spec is ready to dispatch.
+```
+
+### Implementation: Iterative Dispatch
+
+Same prompt, multiple runs. Each pass sees deeper because the context evolved:
+
+```
+Round 1: Build features (the obvious gaps)
+Round 2: Write tests (verify what was built)
+Round 3: Harden security (what can go wrong?)
+Round 4: Next RFC section (what's still missing?)
+Round N: Findings are trivial → implementation is complete
+```
+
+Re-running is not failure. It is the process. Each pass changes the codebase, which changes what the next pass can see. The iteration IS the refinement.
+
+### Post-Implementation: Auto-Documentation
+
+The QA/verify chain produces artefacts that feed forward:
+- Test results document the contract (what works, what doesn't)
+- Coverage reports surface untested paths
+- Diff summaries prep the changelog for the next release
+- Doc site updates from the spec (the spec IS the documentation)
+
+The output of one cycle is the input to the next. The plans repo stays current because the specs drive the code, not the other way round.
+
+## Compatibility
+
+AX conventions are valid, idiomatic Go/PHP/TS. They do not require language extensions, code generation, or non-standard tooling. An AX-designed codebase compiles, tests, and deploys with standard toolchains.
+
+The conventions diverge from community patterns (functional options, Must/For, etc.) but do not violate language specifications. This is a style choice, not a fork.
+
+## Adoption
+
+AX applies to all new code in the Core ecosystem. Existing code migrates incrementally as it is touched — no big-bang rewrite.
+
+Priority order:
+1. **Public APIs** (package-level functions, struct constructors)
+2. **File structure** (path naming, template locations)
+3. **Internal fields** (struct field names, local variables)
+
+## References
+
+- dAppServer unified path convention (2024)
+- CoreGO DTO pattern refactor (2026-03-18)
+- Core primitives design (2026-03-19)
+- Go Proverbs, Rob Pike (2015) — AX provides an updated lens
+
+## Changelog
+
+- 2026-03-19: Initial draft

docs/ref/wails-v3/go.mod

@@ -0,0 +1,3 @@
+module github.com/wailsapp/wails/v3
+
+go 1.26.0

docs/ref/wails-v3/src/application/assets/index.html

@@ -0,0 +1,9 @@
+<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>Wails Assets Placeholder</title>
+</head>
+<body>
+</body>
+</html>

go.mod

@@ -5,73 +5,37 @@ go 1.26.0
 require (
 	forge.lthn.ai/core/config v0.1.8
 	forge.lthn.ai/core/go v0.3.3
+	forge.lthn.ai/core/go-io v0.1.7
+	forge.lthn.ai/core/go-log v0.0.4
 	forge.lthn.ai/core/go-webview v0.1.7
 	github.com/gorilla/websocket v1.5.3
-	github.com/leaanthony/u v1.1.1
 	github.com/modelcontextprotocol/go-sdk v1.4.1
-	github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c
 	github.com/stretchr/testify v1.11.1
 	github.com/wailsapp/wails/v3 v3.0.0-alpha.74
 )
 
+replace github.com/wailsapp/wails/v3 => ./stubs/wails
+
 require (
-	dario.cat/mergo v1.0.2 // indirect
-	forge.lthn.ai/core/go-io v0.1.7 // indirect
-	forge.lthn.ai/core/go-log v0.0.4 // indirect
-	github.com/Microsoft/go-winio v0.6.2 // indirect
-	github.com/ProtonMail/go-crypto v1.4.0 // indirect
-	github.com/adrg/xdg v0.5.3 // indirect
-	github.com/bep/debounce v1.2.1 // indirect
-	github.com/cloudflare/circl v1.6.3 // indirect
-	github.com/coder/websocket v1.8.14 // indirect
-	github.com/cyphar/filepath-securejoin v0.6.1 // indirect
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
-	github.com/ebitengine/purego v0.10.0 // indirect
-	github.com/emirpasic/gods v1.18.1 // indirect
 	github.com/fsnotify/fsnotify v1.9.0 // indirect
-	github.com/go-git/gcfg v1.5.1-0.20230307220236-3a3c6141e376 // indirect
-	github.com/go-git/go-billy/v5 v5.8.0 // indirect
-	github.com/go-git/go-git/v5 v5.17.0 // indirect
-	github.com/go-ole/go-ole v1.3.0 // indirect
 	github.com/go-viper/mapstructure/v2 v2.5.0 // indirect
-	github.com/godbus/dbus/v5 v5.2.2 // indirect
 	github.com/golang-jwt/jwt/v5 v5.3.1 // indirect
-	github.com/golang/groupcache v0.0.0-20241129210726-2c02b8208cf8 // indirect
 	github.com/google/jsonschema-go v0.4.2 // indirect
-	github.com/google/uuid v1.6.0 // indirect
-	github.com/jbenet/go-context v0.0.0-20150711004518-d14ea06fba99 // indirect
-	github.com/jchv/go-winloader v0.0.0-20250406163304-c1995be93bd1 // indirect
-	github.com/kevinburke/ssh_config v1.6.0 // indirect
-	github.com/klauspost/cpuid/v2 v2.3.0 // indirect
-	github.com/leaanthony/go-ansi-parser v1.6.1 // indirect
-	github.com/lmittmann/tint v1.1.3 // indirect
-	github.com/mattn/go-colorable v0.1.14 // indirect
-	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
-	github.com/pjbgf/sha1cd v0.5.0 // indirect
 	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
-	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/sagikazarmark/locafero v0.12.0 // indirect
-	github.com/samber/lo v1.53.0 // indirect
 	github.com/segmentio/asm v1.2.1 // indirect
 	github.com/segmentio/encoding v0.5.4 // indirect
-	github.com/sergi/go-diff v1.4.0 // indirect
-	github.com/skeema/knownhosts v1.3.2 // indirect
 	github.com/spf13/afero v1.15.0 // indirect
 	github.com/spf13/cast v1.10.0 // indirect
 	github.com/spf13/pflag v1.0.10 // indirect
 	github.com/spf13/viper v1.21.0 // indirect
 	github.com/subosito/gotenv v1.6.0 // indirect
-	github.com/wailsapp/go-webview2 v1.0.23 // indirect
-	github.com/xanzy/ssh-agent v0.3.3 // indirect
 	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
-	golang.org/x/crypto v0.49.0 // indirect
-	golang.org/x/exp v0.0.0-20260312153236-7ab1446f8b90 // indirect
-	golang.org/x/net v0.52.0 // indirect
 	golang.org/x/oauth2 v0.36.0 // indirect
 	golang.org/x/sys v0.42.0 // indirect
 	golang.org/x/text v0.35.0 // indirect
-	gopkg.in/warnings.v0 v0.1.2 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -1,5 +1,3 @@
-dario.cat/mergo v1.0.2 h1:85+piFYR1tMbRrLcDwR18y4UKJ3aH1Tbzi24VRW1TK8=
-dario.cat/mergo v1.0.2/go.mod h1:E/hbnu0NxMFBjpMIE34DRGLWqDy0g5FuKDhCb31ngxA=
 forge.lthn.ai/core/config v0.1.8 h1:xP2hys7T94QGVF/OTh84/Zr5Dm/dL/0vzjht8zi+LOg=
 forge.lthn.ai/core/config v0.1.8/go.mod h1:8epZrkwoCt+5ayrqdinOUU/+w6UoxOyv9ZrdgVOgYfQ=
 forge.lthn.ai/core/go v0.3.3 h1:kYYZ2nRYy0/Be3cyuLJspRjLqTMxpckVyhb/7Sw2gd0=
@@ -10,130 +8,40 @@ forge.lthn.ai/core/go-log v0.0.4 h1:KTuCEPgFmuM8KJfnyQ8vPOU1Jg654W74h8IJvfQMfv0=
 forge.lthn.ai/core/go-log v0.0.4/go.mod h1:r14MXKOD3LF/sI8XUJQhRk/SZHBE7jAFVuCfgkXoZPw=
 forge.lthn.ai/core/go-webview v0.1.7 h1:9+aEHeAvNcPX8Zwr+UGu0/T+menRm5T1YOmqZ9dawDc=
 forge.lthn.ai/core/go-webview v0.1.7/go.mod h1:5n1tECD1wBV/uFZRY9ZjfPFO5TYZrlaR3mQFwvO2nek=
-github.com/Microsoft/go-winio v0.5.2/go.mod h1:WpS1mjBmmwHBEWmogvA2mj8546UReBk4v8QkMxJ6pZY=
-github.com/Microsoft/go-winio v0.6.2 h1:F2VQgta7ecxGYO8k3ZZz3RS8fVIXVxONVUPlNERoyfY=
-github.com/Microsoft/go-winio v0.6.2/go.mod h1:yd8OoFMLzJbo9gZq8j5qaps8bJ9aShtEA8Ipt1oGCvU=
-github.com/ProtonMail/go-crypto v1.4.0 h1:Zq/pbM3F5DFgJiMouxEdSVY44MVoQNEKp5d5QxIQceQ=
-github.com/ProtonMail/go-crypto v1.4.0/go.mod h1:e1OaTyu5SYVrO9gKOEhTc+5UcXtTUa+P3uLudwcgPqo=
-github.com/adrg/xdg v0.5.3 h1:xRnxJXne7+oWDatRhR1JLnvuccuIeCoBu2rtuLqQB78=
-github.com/adrg/xdg v0.5.3/go.mod h1:nlTsY+NNiCBGCK2tpm09vRqfVzrc2fLmXGpBLF0zlTQ=
-github.com/anmitsu/go-shlex v0.0.0-20200514113438-38f4b401e2be h1:9AeTilPcZAjCFIImctFaOjnTIavg87rW78vTPkQqLI8=
-github.com/anmitsu/go-shlex v0.0.0-20200514113438-38f4b401e2be/go.mod h1:ySMOLuWl6zY27l47sB3qLNK6tF2fkHG55UZxx8oIVo4=
-github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5 h1:0CwZNZbxp69SHPdPJAN/hZIm0C4OItdklCFmMRWYpio=
-github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5/go.mod h1:wHh0iHkYZB8zMSxRWpUBQtwG5a7fFgvEO+odwuTv2gs=
-github.com/bep/debounce v1.2.1 h1:v67fRdBA9UQu2NhLFXrSg0Brw7CexQekrBwDMM8bzeY=
-github.com/bep/debounce v1.2.1/go.mod h1:H8yggRPQKLUhUoqrJC1bO2xNya7vanpDl7xR3ISbCJ0=
-github.com/cloudflare/circl v1.6.3 h1:9GPOhQGF9MCYUeXyMYlqTR6a5gTrgR/fBLXvUgtVcg8=
-github.com/cloudflare/circl v1.6.3/go.mod h1:2eXP6Qfat4O/Yhh8BznvKnJ+uzEoTQ6jVKJRn81BiS4=
-github.com/coder/websocket v1.8.14 h1:9L0p0iKiNOibykf283eHkKUHHrpG7f65OE3BhhO7v9g=
-github.com/coder/websocket v1.8.14/go.mod h1:NX3SzP+inril6yawo5CQXx8+fk145lPDC6pumgx0mVg=
-github.com/cyphar/filepath-securejoin v0.6.1 h1:5CeZ1jPXEiYt3+Z6zqprSAgSWiggmpVyciv8syjIpVE=
-github.com/cyphar/filepath-securejoin v0.6.1/go.mod h1:A8hd4EnAeyujCJRrICiOWqjS1AX0a9kM5XL+NwKoYSc=
-github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
 github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/ebitengine/purego v0.10.0 h1:QIw4xfpWT6GWTzaW5XEKy3HXoqrJGx1ijYHzTF0/ISU=
-github.com/ebitengine/purego v0.10.0/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ=
-github.com/elazarl/goproxy v1.7.2 h1:Y2o6urb7Eule09PjlhQRGNsqRfPmYI3KKQLFpCAV3+o=
-github.com/elazarl/goproxy v1.7.2/go.mod h1:82vkLNir0ALaW14Rc399OTTjyNREgmdL2cVoIbS6XaE=
-github.com/emirpasic/gods v1.18.1 h1:FXtiHYKDGKCW2KzwZKx0iC0PQmdlorYgdFG9jPXJ1Bc=
-github.com/emirpasic/gods v1.18.1/go.mod h1:8tpGGwCnJ5H4r6BWwaV6OrWmMoPhUl5jm/FMNAnJvWQ=
 github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8=
 github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0=
 github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S9k=
 github.com/fsnotify/fsnotify v1.9.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
-github.com/gliderlabs/ssh v0.3.8 h1:a4YXD1V7xMF9g5nTkdfnja3Sxy1PVDCj1Zg4Wb8vY6c=
-github.com/gliderlabs/ssh v0.3.8/go.mod h1:xYoytBv1sV0aL3CavoDuJIQNURXkkfPA/wxQ1pL1fAU=
-github.com/go-git/gcfg v1.5.1-0.20230307220236-3a3c6141e376 h1:+zs/tPmkDkHx3U66DAb0lQFJrpS6731Oaa12ikc+DiI=
-github.com/go-git/gcfg v1.5.1-0.20230307220236-3a3c6141e376/go.mod h1:an3vInlBmSxCcxctByoQdvwPiA7DTK7jaaFDBTtu0ic=
-github.com/go-git/go-billy/v5 v5.8.0 h1:I8hjc3LbBlXTtVuFNJuwYuMiHvQJDq1AT6u4DwDzZG0=
-github.com/go-git/go-billy/v5 v5.8.0/go.mod h1:RpvI/rw4Vr5QA+Z60c6d6LXH0rYJo0uD5SqfmrrheCY=
-github.com/go-git/go-git-fixtures/v4 v4.3.2-0.20231010084843-55a94097c399 h1:eMje31YglSBqCdIqdhKBW8lokaMrL3uTkpGYlE2OOT4=
-github.com/go-git/go-git-fixtures/v4 v4.3.2-0.20231010084843-55a94097c399/go.mod h1:1OCfN199q1Jm3HZlxleg+Dw/mwps2Wbk9frAWm+4FII=
-github.com/go-git/go-git/v5 v5.17.0 h1:AbyI4xf+7DsjINHMu35quAh4wJygKBKBuXVjV/pxesM=
-github.com/go-git/go-git/v5 v5.17.0/go.mod h1:f82C4YiLx+Lhi8eHxltLeGC5uBTXSFa6PC5WW9o4SjI=
-github.com/go-json-experiment/json v0.0.0-20251027170946-4849db3c2f7e h1:Lf/gRkoycfOBPa42vU2bbgPurFong6zXeFtPoxholzU=
-github.com/go-json-experiment/json v0.0.0-20251027170946-4849db3c2f7e/go.mod h1:uNVvRXArCGbZ508SxYYTC5v1JWoz2voff5pm25jU1Ok=
-github.com/go-ole/go-ole v1.3.0 h1:Dt6ye7+vXGIKZ7Xtk4s6/xVdGDQynvom7xCFEdWr6uE=
-github.com/go-ole/go-ole v1.3.0/go.mod h1:5LS6F96DhAwUc7C+1HLexzMXY1xGRSryjyPPKW6zv78=
 github.com/go-viper/mapstructure/v2 v2.5.0 h1:vM5IJoUAy3d7zRSVtIwQgBj7BiWtMPfmPEgAXnvj1Ro=
 github.com/go-viper/mapstructure/v2 v2.5.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
-github.com/godbus/dbus/v5 v5.2.2 h1:TUR3TgtSVDmjiXOgAAyaZbYmIeP3DPkld3jgKGV8mXQ=
-github.com/godbus/dbus/v5 v5.2.2/go.mod h1:3AAv2+hPq5rdnr5txxxRwiGjPXamgoIHgz9FPBfOp3c=
 github.com/golang-jwt/jwt/v5 v5.3.1 h1:kYf81DTWFe7t+1VvL7eS+jKFVWaUnK9cB1qbwn63YCY=
 github.com/golang-jwt/jwt/v5 v5.3.1/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
-github.com/golang/groupcache v0.0.0-20241129210726-2c02b8208cf8 h1:f+oWsMOmNPc8JmEHVZIycC7hBoQxHH9pNKQORJNozsQ=
-github.com/golang/groupcache v0.0.0-20241129210726-2c02b8208cf8/go.mod h1:wcDNUvekVysuuOpQKo3191zZyTpiI6se1N1ULghS0sw=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/jsonschema-go v0.4.2 h1:tmrUohrwoLZZS/P3x7ex0WAVknEkBZM46iALbcqoRA8=
 github.com/google/jsonschema-go v0.4.2/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=
-github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
-github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
 github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
-github.com/jbenet/go-context v0.0.0-20150711004518-d14ea06fba99 h1:BQSFePA1RWJOlocH6Fxy8MmwDt+yVQYULKfN0RoTN8A=
-github.com/jbenet/go-context v0.0.0-20150711004518-d14ea06fba99/go.mod h1:1lJo3i6rXxKeerYnT8Nvf0QmHCRC1n8sfWVwXF2Frvo=
-github.com/jchv/go-winloader v0.0.0-20250406163304-c1995be93bd1 h1:njuLRcjAuMKr7kI3D85AXWkw6/+v9PwtV6M6o11sWHQ=
-github.com/jchv/go-winloader v0.0.0-20250406163304-c1995be93bd1/go.mod h1:alcuEEnZsY1WQsagKhZDsoPCRoOijYqhZvPwLG0kzVs=
-github.com/kevinburke/ssh_config v1.6.0 h1:J1FBfmuVosPHf5GRdltRLhPJtJpTlMdKTBjRgTaQBFY=
-github.com/kevinburke/ssh_config v1.6.0/go.mod h1:q2RIzfka+BXARoNexmF9gkxEX7DmvbW9P4hIVx2Kg4M=
-github.com/klauspost/cpuid/v2 v2.3.0 h1:S4CRMLnYUhGeDFDqkGriYKdfoFlDnMtqTiI/sFzhA9Y=
-github.com/klauspost/cpuid/v2 v2.3.0/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
-github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
 github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
-github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
-github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
-github.com/leaanthony/go-ansi-parser v1.6.1 h1:xd8bzARK3dErqkPFtoF9F3/HgN8UQk0ed1YDKpEz01A=
-github.com/leaanthony/go-ansi-parser v1.6.1/go.mod h1:+vva/2y4alzVmmIEpk9QDhA7vLC5zKDTRwfZGOp3IWU=
-github.com/leaanthony/u v1.1.1 h1:TUFjwDGlNX+WuwVEzDqQwC2lOv0P4uhTQw7CMFdiK7M=
-github.com/leaanthony/u v1.1.1/go.mod h1:9+o6hejoRljvZ3BzdYlVL0JYCwtnAsVuN9pVTQcaRfI=
-github.com/lmittmann/tint v1.1.3 h1:Hv4EaHWXQr+GTFnOU4VKf8UvAtZgn0VuKT+G0wFlO3I=
-github.com/lmittmann/tint v1.1.3/go.mod h1:HIS3gSy7qNwGCj+5oRjAutErFBl4BzdQP6cJZ0NfMwE=
-github.com/matryer/is v1.4.0/go.mod h1:8I/i5uYgLzgsgEloJE1U6xx5HkBQpAZvepWuujKwMRU=
-github.com/matryer/is v1.4.1 h1:55ehd8zaGABKLXQUe2awZ99BD/PTc2ls+KV/dXphgEQ=
-github.com/matryer/is v1.4.1/go.mod h1:8I/i5uYgLzgsgEloJE1U6xx5HkBQpAZvepWuujKwMRU=
-github.com/mattn/go-colorable v0.1.14 h1:9A9LHSqF/7dyVVX6g0U9cwm9pG3kP9gSzcuIPHPsaIE=
-github.com/mattn/go-colorable v0.1.14/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
-github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
-github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
 github.com/modelcontextprotocol/go-sdk v1.4.1 h1:M4x9GyIPj+HoIlHNGpK2hq5o3BFhC+78PkEaldQRphc=
 github.com/modelcontextprotocol/go-sdk v1.4.1/go.mod h1:Bo/mS87hPQqHSRkMv4dQq1XCu6zv4INdXnFZabkNU6s=
-github.com/onsi/gomega v1.34.1 h1:EUMJIKUjM8sKjYbtxQI9A4z2o+rruxnzNvpknOXie6k=
-github.com/onsi/gomega v1.34.1/go.mod h1:kU1QgUvBDLXBJq618Xvm2LUX6rSAfRaFRTcdOeDLwwY=
 github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
 github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
-github.com/pjbgf/sha1cd v0.5.0 h1:a+UkboSi1znleCDUNT3M5YxjOnN1fz2FhN48FlwCxs0=
-github.com/pjbgf/sha1cd v0.5.0/go.mod h1:lhpGlyHLpQZoxMv8HcgXvZEhcGs0PG/vsZnEJ7H0iCM=
-github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c h1:+mdjkGKdHQG3305AYmdv1U2eRNDiU2ErMBj1gwrq8eQ=
-github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c/go.mod h1:7rwL4CYBLnjLxUqIJNnCWiEdr3bn6IUYi15bNlnbCCU=
-github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
-github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
-github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
-github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
-github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
 github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
 github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
 github.com/sagikazarmark/locafero v0.12.0 h1:/NQhBAkUb4+fH1jivKHWusDYFjMOOKU88eegjfxfHb4=
 github.com/sagikazarmark/locafero v0.12.0/go.mod h1:sZh36u/YSZ918v0Io+U9ogLYQJ9tLLBmM4eneO6WwsI=
-github.com/samber/lo v1.53.0 h1:t975lj2py4kJPQ6haz1QMgtId2gtmfktACxIXArw3HM=
-github.com/samber/lo v1.53.0/go.mod h1:4+MXEGsJzbKGaUEQFKBq2xtfuznW9oz/WrgyzMzRoM0=
 github.com/segmentio/asm v1.2.1 h1:DTNbBqs57ioxAD4PrArqftgypG4/qNpXoJx8TVXxPR0=
 github.com/segmentio/asm v1.2.1/go.mod h1:BqMnlJP91P8d+4ibuonYZw9mfnzI9HfxselHZr5aAcs=
 github.com/segmentio/encoding v0.5.4 h1:OW1VRern8Nw6ITAtwSZ7Idrl3MXCFwXHPgqESYfvNt0=
 github.com/segmentio/encoding v0.5.4/go.mod h1:HS1ZKa3kSN32ZHVZ7ZLPLXWvOVIiZtyJnO1gPH1sKt0=
-github.com/sergi/go-diff v1.4.0 h1:n/SP9D5ad1fORl+llWyN+D6qoUETXNZARKjyY2/KVCw=
-github.com/sergi/go-diff v1.4.0/go.mod h1:A0bzQcvG0E7Rwjx0REVgAGH58e96+X0MeOfepqsbeW4=
-github.com/sirupsen/logrus v1.7.0/go.mod h1:yWOB1SBYBC5VeMP7gHvWumXLIWorT60ONWic61uBYv0=
-github.com/skeema/knownhosts v1.3.2 h1:EDL9mgf4NzwMXCTfaxSD/o/a5fxDw/xL9nkU28JjdBg=
-github.com/skeema/knownhosts v1.3.2/go.mod h1:bEg3iQAuw+jyiw+484wwFJoKSLwcfd7fqRy+N0QTiow=
 github.com/spf13/afero v1.15.0 h1:b/YBCLWAJdFWJTN9cLhiXXcD7mzKn9Dm86dNnfyQw1I=
 github.com/spf13/afero v1.15.0/go.mod h1:NC2ByUVxtQs4b3sIUphxK0NioZnmxgyCrfzeuq8lxMg=
 github.com/spf13/cast v1.10.0 h1:h2x0u2shc1QuLHfxi+cTJvs30+ZAHOGRic8uyGTDWxY=
@@ -142,60 +50,24 @@ github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
 github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/spf13/viper v1.21.0 h1:x5S+0EU27Lbphp4UKm1C+1oQO+rKx36vfCoaVebLFSU=
 github.com/spf13/viper v1.21.0/go.mod h1:P0lhsswPGWD/1lZJ9ny3fYnVqxiegrlNrEmgLjbTCAY=
-github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
-github.com/stretchr/testify v1.2.2/go.mod h1:a8OnRcib4nhh0OaRAV+Yts87kKdq0PP7pXfy6kDkUVs=
-github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/subosito/gotenv v1.6.0 h1:9NlTDc1FTs4qu0DDq7AEtTPNw6SVm7uBMsUCUjABIf8=
 github.com/subosito/gotenv v1.6.0/go.mod h1:Dk4QP5c2W3ibzajGcXpNraDfq2IrhjMIvMSWPKKo0FU=
-github.com/wailsapp/go-webview2 v1.0.23 h1:jmv8qhz1lHibCc79bMM/a/FqOnnzOGEisLav+a0b9P0=
-github.com/wailsapp/go-webview2 v1.0.23/go.mod h1:qJmWAmAmaniuKGZPWwne+uor3AHMB5PFhqiK0Bbj8kc=
-github.com/wailsapp/wails/v3 v3.0.0-alpha.74 h1:wRm1EiDQtxDisXk46NtpiBH90STwfKp36NrTDwOEdxw=
-github.com/wailsapp/wails/v3 v3.0.0-alpha.74/go.mod h1:4saK4A4K9970X+X7RkMwP2lyGbLogcUz54wVeq4C/V8=
-github.com/xanzy/ssh-agent v0.3.3 h1:+/15pJfg/RsTxqYcX6fHqOXZwwMP+2VyYWJeWM2qQFM=
-github.com/xanzy/ssh-agent v0.3.3/go.mod h1:6dzNDKs0J9rVPHPhaGCukekBHKqfl+L3KghI1Bc68Uw=
 github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zIM+UJPGz4=
 github.com/yosida95/uritemplate/v3 v3.0.2/go.mod h1:ILOh0sOhIJR3+L/8afwt/kE++YT040gmv5BQTMR2HP4=
 go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
-golang.org/x/crypto v0.0.0-20220622213112-05595931fe9d/go.mod h1:IxCIyHEi3zRg3s0A5j5BB6A9Jmi73HwBIUl50j+osU4=
-golang.org/x/crypto v0.49.0 h1:+Ng2ULVvLHnJ/ZFEq4KdcDd/cfjrrjjNSXNzxg0Y4U4=
-golang.org/x/crypto v0.49.0/go.mod h1:ErX4dUh2UM+CFYiXZRTcMpEcN8b/1gxEuv3nODoYtCA=
-golang.org/x/exp v0.0.0-20260312153236-7ab1446f8b90 h1:jiDhWWeC7jfWqR9c/uplMOqJ0sbNlNWv0UkzE0vX1MA=
-golang.org/x/exp v0.0.0-20260312153236-7ab1446f8b90/go.mod h1:xE1HEv6b+1SCZ5/uscMRjUBKtIxworgEcEi+/n9NQDQ=
-golang.org/x/net v0.0.0-20211112202133-69e39bad7dc2/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=
-golang.org/x/net v0.52.0 h1:He/TN1l0e4mmR3QqHMT2Xab3Aj3L9qjbhRm78/6jrW0=
-golang.org/x/net v0.52.0/go.mod h1:R1MAz7uMZxVMualyPXb+VaqGSa3LIaUqk0eEt3w36Sw=
 golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs=
 golang.org/x/oauth2 v0.36.0/go.mod h1:YDBUJMTkDnJS+A4BP4eZBjCqtokkg1hODuPjwiGPO7Q=
-golang.org/x/sys v0.0.0-20191026070338-33540a1f6037/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
-golang.org/x/sys v0.0.0-20200810151505-1b9f1253b3ed/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
-golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
-golang.org/x/sys v0.0.0-20210124154548-22da62e12c0c/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
-golang.org/x/sys v0.0.0-20210423082822-04245dca01da/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
-golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.1.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
 golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
-golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
-golang.org/x/term v0.41.0 h1:QCgPso/Q3RTJx2Th4bDLqML4W6iJiaXFq2/ftQF13YU=
-golang.org/x/term v0.41.0/go.mod h1:3pfBgksrReYfZ5lvYM0kSO0LIkAl4Yl2bXOkKP7Ec2A=
-golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.35.0 h1:JOVx6vVDFokkpaq1AEptVzLTpDe9KGpj5tR4/X+ybL8=
 golang.org/x/text v0.35.0/go.mod h1:khi/HExzZJ2pGnjenulevKNX1W67CUy0AsXcNubPGCA=
-golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
 golang.org/x/tools v0.43.0 h1:12BdW9CeB3Z+J/I/wj34VMl8X+fEXBxVR90JeMX5E7s=
 golang.org/x/tools v0.43.0/go.mod h1:uHkMso649BX2cZK6+RpuIPXS3ho2hZo4FVwfoy1vIk0=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
-gopkg.in/warnings.v0 v0.1.2 h1:wFXVbFY8DY5/xOe1ECiWdKCzZlxgshcYVNkBHstARME=
-gopkg.in/warnings.v0 v0.1.2/go.mod h1:jksf8JmL6Qr/oQM2OXTHunEvvTAsrWBLb6OOjuVWRNI=
-gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
-gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

internal/wails3

@@ -0,0 +1 @@
+Subproject commit bb4fbf95744fafe5acf84e143a419bfffc2159e6

pkg/browser/register.go

@@ -1,10 +1,9 @@
-// pkg/browser/register.go
 package browser
 
 import "forge.lthn.ai/core/go/pkg/core"
 
-// Register creates a factory closure that captures the Platform adapter.
-// The returned function has the signature WithService requires: func(*Core) (any, error).
+// Register(p) binds the browser service to a Core instance.
+// core.WithService(browser.Register(wailsBrowser))
 func Register(p Platform) func(*core.Core) (any, error) {
 	return func(c *core.Core) (any, error) {
 		return &Service{

pkg/browser/service.go

@@ -1,4 +1,3 @@
-// pkg/browser/service.go
 package browser
 
 import (
@@ -7,29 +6,22 @@ import (
 	"forge.lthn.ai/core/go/pkg/core"
 )
 
-// Options holds configuration for the browser service.
 type Options struct{}
 
-// Service is a core.Service that delegates browser/file-open operations
-// to the platform. It is stateless — no queries, no actions.
 type Service struct {
 	*core.ServiceRuntime[Options]
 	platform Platform
 }
 
-// OnStartup registers IPC handlers.
 func (s *Service) OnStartup(ctx context.Context) error {
 	s.Core().RegisterTask(s.handleTask)
 	return nil
 }
 
-// HandleIPCEvents is auto-discovered and registered by core.WithService.
 func (s *Service) HandleIPCEvents(c *core.Core, msg core.Message) error {
 	return nil
 }
 
-// --- Task Handlers ---
-
 func (s *Service) handleTask(c *core.Core, t core.Task) (any, bool, error) {
 	switch t := t.(type) {
 	case TaskOpenURL:

pkg/clipboard/service.go

@@ -7,16 +7,15 @@ import (
 	"forge.lthn.ai/core/go/pkg/core"
 )
 
-// Options holds configuration for the clipboard service.
 type Options struct{}
 
-// Service is a core.Service managing clipboard operations via IPC.
 type Service struct {
 	*core.ServiceRuntime[Options]
 	platform Platform
 }
 
-// Register creates a factory closure that captures the Platform adapter.
+// Register(p) binds the clipboard service to a Core instance.
+// c.WithService(clipboard.Register(wailsClipboard))
 func Register(p Platform) func(*core.Core) (any, error) {
 	return func(c *core.Core) (any, error) {
 		return &Service{
@@ -26,14 +25,12 @@ func Register(p Platform) func(*core.Core) (any, error) {
 	}
 }
 
-// OnStartup registers IPC handlers.
 func (s *Service) OnStartup(ctx context.Context) error {
 	s.Core().RegisterQuery(s.handleQuery)
 	s.Core().RegisterTask(s.handleTask)
 	return nil
 }
 
-// HandleIPCEvents is auto-discovered by core.WithService.
 func (s *Service) HandleIPCEvents(c *core.Core, msg core.Message) error {
 	return nil
 }

pkg/contextmenu/messages.go

@@ -1,15 +1,10 @@
-// pkg/contextmenu/messages.go
 package contextmenu
 
 import "errors"
 
-// ErrMenuNotFound is returned when attempting to remove or get a menu
-// that does not exist in the registry.
-var ErrMenuNotFound = errors.New("contextmenu: menu not found")
+var ErrorMenuNotFound = errors.New("contextmenu: menu not found")
 
-// --- Queries ---
-
-// QueryGet returns a single context menu by name. Result: *ContextMenuDef (nil if not found)
+// QueryGet returns a named context menu definition. Result: *ContextMenuDef (nil if not found)
 type QueryGet struct {
 	Name string `json:"name"`
 }
@@ -17,26 +12,18 @@ type QueryGet struct {
 // QueryList returns all registered context menus. Result: map[string]ContextMenuDef
 type QueryList struct{}
 
-// --- Tasks ---
-
-// TaskAdd registers a context menu. Result: nil
-// If a menu with the same name already exists it is replaced (remove + re-add).
+// TaskAdd registers a named context menu. Replaces if already exists.
 type TaskAdd struct {
 	Name string         `json:"name"`
 	Menu ContextMenuDef `json:"menu"`
 }
 
-// TaskRemove unregisters a context menu. Result: nil
-// Returns ErrMenuNotFound if the menu does not exist.
+// TaskRemove unregisters a context menu by name. Error: ErrorMenuNotFound if missing.
 type TaskRemove struct {
 	Name string `json:"name"`
 }
 
-// --- Actions ---
-
 // ActionItemClicked is broadcast when a context menu item is clicked.
-// The Data field is populated from the CSS --custom-contextmenu-data property
-// on the element that triggered the context menu.
 type ActionItemClicked struct {
 	MenuName string `json:"menuName"`
 	ActionID string `json:"actionId"`

pkg/contextmenu/register.go

@@ -1,16 +1,15 @@
-// pkg/contextmenu/register.go
 package contextmenu
 
 import "forge.lthn.ai/core/go/pkg/core"
 
-// Register creates a factory closure that captures the Platform adapter.
-// The returned function has the signature WithService requires: func(*Core) (any, error).
+// Register(p) binds the context menu service to a Core instance.
+// core.WithService(contextmenu.Register(wailsContextMenu))
 func Register(p Platform) func(*core.Core) (any, error) {
 	return func(c *core.Core) (any, error) {
 		return &Service{
-			ServiceRuntime: core.NewServiceRuntime[Options](c, Options{}),
-			platform:       p,
-			menus:          make(map[string]ContextMenuDef),
+			ServiceRuntime:  core.NewServiceRuntime[Options](c, Options{}),
+			platform:        p,
+			registeredMenus: make(map[string]ContextMenuDef),
 		}, nil
 	}
 }

pkg/contextmenu/service.go

@@ -3,31 +3,25 @@ package contextmenu
 
 import (
 	"context"
-	"fmt"
 
+	coreerr "forge.lthn.ai/core/go-log"
 	"forge.lthn.ai/core/go/pkg/core"
 )
 
-// Options holds configuration for the context menu service.
 type Options struct{}
 
-// Service is a core.Service managing context menus via IPC.
-// It maintains an in-memory registry of menus (map[string]ContextMenuDef)
-// and delegates platform-level registration to the Platform interface.
 type Service struct {
 	*core.ServiceRuntime[Options]
-	platform Platform
-	menus    map[string]ContextMenuDef
+	platform        Platform
+	registeredMenus map[string]ContextMenuDef
 }
 
-// OnStartup registers IPC handlers.
 func (s *Service) OnStartup(ctx context.Context) error {
 	s.Core().RegisterQuery(s.handleQuery)
 	s.Core().RegisterTask(s.handleTask)
 	return nil
 }
 
-// HandleIPCEvents is auto-discovered and registered by core.WithService.
 func (s *Service) HandleIPCEvents(c *core.Core, msg core.Message) error {
 	return nil
 }
@@ -45,19 +39,17 @@ func (s *Service) handleQuery(c *core.Core, q core.Query) (any, bool, error) {
 	}
 }
 
-// queryGet returns a single menu definition by name, or nil if not found.
 func (s *Service) queryGet(q QueryGet) *ContextMenuDef {
-	menu, ok := s.menus[q.Name]
+	menu, ok := s.registeredMenus[q.Name]
 	if !ok {
 		return nil
 	}
 	return &menu
 }
 
-// queryList returns a copy of all registered menus.
 func (s *Service) queryList() map[string]ContextMenuDef {
-	result := make(map[string]ContextMenuDef, len(s.menus))
-	for k, v := range s.menus {
+	result := make(map[string]ContextMenuDef, len(s.registeredMenus))
+	for k, v := range s.registeredMenus {
 		result[k] = v
 	}
 	return result
@@ -78,9 +70,9 @@ func (s *Service) handleTask(c *core.Core, t core.Task) (any, bool, error) {
 
 func (s *Service) taskAdd(t TaskAdd) error {
 	// If menu already exists, remove it first (replace semantics)
-	if _, exists := s.menus[t.Name]; exists {
+	if _, exists := s.registeredMenus[t.Name]; exists {
 		_ = s.platform.Remove(t.Name)
-		delete(s.menus, t.Name)
+		delete(s.registeredMenus, t.Name)
 	}
 
 	// Register on platform with a callback that broadcasts ActionItemClicked
@@ -92,23 +84,23 @@ func (s *Service) taskAdd(t TaskAdd) error {
 		})
 	})
 	if err != nil {
-		return fmt.Errorf("contextmenu: platform add failed: %w", err)
+		return coreerr.E("contextmenu.taskAdd", "platform add failed", err)
 	}
 
-	s.menus[t.Name] = t.Menu
+	s.registeredMenus[t.Name] = t.Menu
 	return nil
 }
 
 func (s *Service) taskRemove(t TaskRemove) error {
-	if _, exists := s.menus[t.Name]; !exists {
-		return ErrMenuNotFound
+	if _, exists := s.registeredMenus[t.Name]; !exists {
+		return ErrorMenuNotFound
 	}
 
 	err := s.platform.Remove(t.Name)
 	if err != nil {
-		return fmt.Errorf("contextmenu: platform remove failed: %w", err)
+		return coreerr.E("contextmenu.taskRemove", "platform remove failed", err)
 	}
 
-	delete(s.menus, t.Name)
+	delete(s.registeredMenus, t.Name)
 	return nil
 }

pkg/contextmenu/service_test.go

@@ -171,7 +171,7 @@ func TestTaskRemove_Bad_NotFound(t *testing.T) {
 
 	_, handled, err := c.PERFORM(TaskRemove{Name: "nonexistent"})
 	assert.True(t, handled)
-	assert.ErrorIs(t, err, ErrMenuNotFound)
+	assert.ErrorIs(t, err, ErrorMenuNotFound)
 }
 
 func TestQueryGet_Good(t *testing.T) {

pkg/dialog/messages.go

@@ -1,14 +1,9 @@
-// pkg/dialog/messages.go
 package dialog
 
-// TaskOpenFile shows an open file dialog. Result: []string (paths)
-type TaskOpenFile struct{ Opts OpenFileOptions }
+type TaskOpenFile struct{ Options OpenFileOptions }
 
-// TaskSaveFile shows a save file dialog. Result: string (path)
-type TaskSaveFile struct{ Opts SaveFileOptions }
+type TaskSaveFile struct{ Options SaveFileOptions }
 
-// TaskOpenDirectory shows a directory picker. Result: string (path)
-type TaskOpenDirectory struct{ Opts OpenDirectoryOptions }
+type TaskOpenDirectory struct{ Options OpenDirectoryOptions }
 
-// TaskMessageDialog shows a message dialog. Result: string (button clicked)
-type TaskMessageDialog struct{ Opts MessageDialogOptions }
+type TaskMessageDialog struct{ Options MessageDialogOptions }

pkg/dialog/platform.go

@@ -3,10 +3,10 @@ package dialog
 
 // Platform abstracts the native dialog backend.
 type Platform interface {
-	OpenFile(opts OpenFileOptions) ([]string, error)
-	SaveFile(opts SaveFileOptions) (string, error)
-	OpenDirectory(opts OpenDirectoryOptions) (string, error)
-	MessageDialog(opts MessageDialogOptions) (string, error)
+	OpenFile(options OpenFileOptions) ([]string, error)
+	SaveFile(options SaveFileOptions) (string, error)
+	OpenDirectory(options OpenDirectoryOptions) (string, error)
+	MessageDialog(options MessageDialogOptions) (string, error)
 }
 
 // DialogType represents the type of message dialog.

pkg/dialog/service.go

@@ -7,16 +7,13 @@ import (
 	"forge.lthn.ai/core/go/pkg/core"
 )
 
-// Options holds configuration for the dialog service.
 type Options struct{}
 
-// Service is a core.Service managing native dialogs via IPC.
 type Service struct {
 	*core.ServiceRuntime[Options]
 	platform Platform
 }
 
-// Register creates a factory closure that captures the Platform adapter.
 func Register(p Platform) func(*core.Core) (any, error) {
 	return func(c *core.Core) (any, error) {
 		return &Service{
@@ -26,13 +23,11 @@ func Register(p Platform) func(*core.Core) (any, error) {
 	}
 }
 
-// OnStartup registers IPC handlers.
 func (s *Service) OnStartup(ctx context.Context) error {
 	s.Core().RegisterTask(s.handleTask)
 	return nil
 }
 
-// HandleIPCEvents is auto-discovered by core.WithService.
 func (s *Service) HandleIPCEvents(c *core.Core, msg core.Message) error {
 	return nil
 }
@@ -40,16 +35,16 @@ func (s *Service) HandleIPCEvents(c *core.Core, msg core.Message) error {
 func (s *Service) handleTask(c *core.Core, t core.Task) (any, bool, error) {
 	switch t := t.(type) {
 	case TaskOpenFile:
-		paths, err := s.platform.OpenFile(t.Opts)
+		paths, err := s.platform.OpenFile(t.Options)
 		return paths, true, err
 	case TaskSaveFile:
-		path, err := s.platform.SaveFile(t.Opts)
+		path, err := s.platform.SaveFile(t.Options)
 		return path, true, err
 	case TaskOpenDirectory:
-		path, err := s.platform.OpenDirectory(t.Opts)
+		path, err := s.platform.OpenDirectory(t.Options)
 		return path, true, err
 	case TaskMessageDialog:
-		button, err := s.platform.MessageDialog(t.Opts)
+		button, err := s.platform.MessageDialog(t.Options)
 		return button, true, err
 	default:
 		return nil, false, nil

pkg/dialog/service_test.go

@@ -11,18 +11,18 @@ import (
 )
 
 type mockPlatform struct {
-	openFilePaths  []string
-	saveFilePath   string
-	openDirPath    string
-	messageButton  string
-	openFileErr    error
-	saveFileErr    error
-	openDirErr     error
-	messageErr     error
-	lastOpenOpts   OpenFileOptions
-	lastSaveOpts   SaveFileOptions
-	lastDirOpts    OpenDirectoryOptions
-	lastMsgOpts    MessageDialogOptions
+	openFilePaths []string
+	saveFilePath  string
+	openDirPath   string
+	messageButton string
+	openFileErr   error
+	saveFileErr   error
+	openDirErr    error
+	messageErr    error
+	lastOpenOpts  OpenFileOptions
+	lastSaveOpts  SaveFileOptions
+	lastDirOpts   OpenDirectoryOptions
+	lastMsgOpts   MessageDialogOptions
 }
 
 func (m *mockPlatform) OpenFile(opts OpenFileOptions) ([]string, error) {
@@ -70,7 +70,7 @@ func TestTaskOpenFile_Good(t *testing.T) {
 	mock.openFilePaths = []string{"/a.txt", "/b.txt"}
 
 	result, handled, err := c.PERFORM(TaskOpenFile{
-		Opts: OpenFileOptions{Title: "Pick", AllowMultiple: true},
+		Options: OpenFileOptions{Title: "Pick", AllowMultiple: true},
 	})
 	require.NoError(t, err)
 	assert.True(t, handled)
@@ -83,7 +83,7 @@ func TestTaskOpenFile_Good(t *testing.T) {
 func TestTaskSaveFile_Good(t *testing.T) {
 	_, c := newTestService(t)
 	result, handled, err := c.PERFORM(TaskSaveFile{
-		Opts: SaveFileOptions{Filename: "out.txt"},
+		Options: SaveFileOptions{Filename: "out.txt"},
 	})
 	require.NoError(t, err)
 	assert.True(t, handled)
@@ -93,7 +93,7 @@ func TestTaskSaveFile_Good(t *testing.T) {
 func TestTaskOpenDirectory_Good(t *testing.T) {
 	_, c := newTestService(t)
 	result, handled, err := c.PERFORM(TaskOpenDirectory{
-		Opts: OpenDirectoryOptions{Title: "Pick Dir"},
+		Options: OpenDirectoryOptions{Title: "Pick Dir"},
 	})
 	require.NoError(t, err)
 	assert.True(t, handled)
@@ -105,7 +105,7 @@ func TestTaskMessageDialog_Good(t *testing.T) {
 	mock.messageButton = "Yes"
 
 	result, handled, err := c.PERFORM(TaskMessageDialog{
-		Opts: MessageDialogOptions{
+		Options: MessageDialogOptions{
 			Type: DialogQuestion, Title: "Confirm",
 			Message: "Sure?", Buttons: []string{"Yes", "No"},
 		},

pkg/display/display.go

@@ -2,14 +2,14 @@ package display
 
 import (
 	"context"
-	"fmt"
+	"encoding/json"
 	"os"
 	"path/filepath"
 	"runtime"
 
 	"forge.lthn.ai/core/config"
+	coreerr "forge.lthn.ai/core/go-log"
 	"forge.lthn.ai/core/go/pkg/core"
-	"encoding/json"
 
 	"forge.lthn.ai/core/gui/pkg/browser"
 	"forge.lthn.ai/core/gui/pkg/contextmenu"
@@ -27,27 +27,25 @@ import (
 	"github.com/wailsapp/wails/v3/pkg/application"
 )
 
-// Options holds configuration for the display service.
 type Options struct{}
 
 // WindowInfo is an alias for window.WindowInfo (backward compatibility).
 type WindowInfo = window.WindowInfo
 
-// Service manages windowing, dialogs, and other visual elements.
-// It orchestrates sub-services (window, systray, menu) via IPC and bridges
-// IPC actions to WebSocket events for TypeScript apps.
+// Service orchestrates window, systray, and menu sub-services via IPC.
+// Bridges IPC actions to WebSocket events for TypeScript apps.
 type Service struct {
 	*core.ServiceRuntime[Options]
 	wailsApp   *application.App
 	app        App
-	config     Options
 	configData map[string]map[string]any
-	cfg        *config.Config // config instance for file persistence
-	events *WSEventManager
+	configFile *config.Config // config instance for file persistence
+	events     *WSEventManager
 }
 
-// New is the constructor for the display service.
-func New() (*Service, error) {
+// NewService returns a display Service with empty config sections.
+// svc, _ := display.NewService(); _, _ = svc.CreateWindow(display.CreateWindowOptions{Name: "settings", URL: "/settings", Width: 800, Height: 600})
+func NewService() (*Service, error) {
 	return &Service{
 		configData: map[string]map[string]any{
 			"window":  {},
@@ -57,11 +55,17 @@ func New() (*Service, error) {
 	}, nil
 }
 
-// Register creates a factory closure that captures the Wails app.
-// Pass nil for testing without a Wails runtime.
+// Deprecated: use NewService().
+func New() (*Service, error) {
+	return NewService()
+}
+
+// Register binds the display service to a Core instance.
+// core.WithService(display.Register(app))      // production (Wails app)
+// core.WithService(display.Register(nil))      // tests (no Wails runtime)
 func Register(wailsApp *application.App) func(*core.Core) (any, error) {
 	return func(c *core.Core) (any, error) {
-		s, err := New()
+		s, err := NewService()
 		if err != nil {
 			return nil, err
 		}
@@ -71,9 +75,8 @@ func Register(wailsApp *application.App) func(*core.Core) (any, error) {
 	}
 }
 
-// OnStartup loads config and registers IPC handlers synchronously.
-// CRITICAL: config handlers MUST be registered before returning —
-// sub-services depend on them during their own OnStartup.
+// OnStartup loads config and registers handlers before sub-services start.
+// Config handlers are registered first — sub-services query them during their own OnStartup.
 func (s *Service) OnStartup(ctx context.Context) error {
 	s.loadConfig()
 
@@ -90,8 +93,7 @@ func (s *Service) OnStartup(ctx context.Context) error {
 	return nil
 }
 
-// HandleIPCEvents is auto-discovered and registered by core.WithService.
-// It bridges sub-service IPC actions to WebSocket events for TS apps.
+// HandleIPCEvents bridges IPC actions from sub-services to WebSocket events for TS apps.
 func (s *Service) HandleIPCEvents(c *core.Core, msg core.Message) error {
 	switch m := msg.(type) {
 	case core.ActionServiceStartup:
@@ -116,7 +118,7 @@ func (s *Service) HandleIPCEvents(c *core.Core, msg core.Message) error {
 	case window.ActionWindowResized:
 		if s.events != nil {
 			s.events.Emit(Event{Type: EventWindowResize, Window: m.Name,
-				Data: map[string]any{"w": m.W, "h": m.H}})
+				Data: map[string]any{"w": m.Width, "h": m.Height}})
 		}
 	case window.ActionWindowFocused:
 		if s.events != nil {
@@ -241,7 +243,7 @@ type WSMessage struct {
 func wsRequire(data map[string]any, key string) (string, error) {
 	v, _ := data[key].(string)
 	if v == "" {
-		return "", fmt.Errorf("ws: missing required field %q", key)
+		return "", coreerr.E("display.wsRequire", "missing required field \""+key+"\"", nil)
 	}
 	return v, nil
 }
@@ -487,10 +489,10 @@ func (s *Service) handleTrayAction(actionID string) {
 		result, handled, _ := s.Core().QUERY(environment.QueryInfo{})
 		if handled {
 			info := result.(environment.EnvironmentInfo)
-			details := fmt.Sprintf("OS: %s\nArch: %s\nPlatform: %s %s",
-				info.OS, info.Arch, info.Platform.Name, info.Platform.Version)
+			details := "OS: " + info.OS + "\nArch: " + info.Arch + "\nPlatform: " +
+				info.Platform.Name + " " + info.Platform.Version
 			_, _, _ = s.Core().PERFORM(dialog.TaskMessageDialog{
-				Opts: dialog.MessageDialogOptions{
+				Options: dialog.MessageDialogOptions{
 					Type: dialog.DialogInfo, Title: "Environment",
 					Message: details, Buttons: []string{"OK"},
 				},
@@ -512,23 +514,23 @@ func guiConfigPath() string {
 }
 
 func (s *Service) loadConfig() {
-	if s.cfg != nil {
+	if s.configFile != nil {
 		return // Already loaded (e.g., via loadConfigFrom in tests)
 	}
 	s.loadConfigFrom(guiConfigPath())
 }
 
 func (s *Service) loadConfigFrom(path string) {
-	cfg, err := config.New(config.WithPath(path))
+	configFile, err := config.New(config.WithPath(path))
 	if err != nil {
 		// Non-critical — continue with empty configData
 		return
 	}
-	s.cfg = cfg
+	s.configFile = configFile
 
 	for _, section := range []string{"window", "systray", "menu"} {
 		var data map[string]any
-		if err := cfg.Get(section, &data); err == nil && data != nil {
+		if err := configFile.Get(section, &data); err == nil && data != nil {
 			s.configData[section] = data
 		}
 	}
@@ -550,16 +552,16 @@ func (s *Service) handleConfigQuery(c *core.Core, q core.Query) (any, bool, erro
 func (s *Service) handleConfigTask(c *core.Core, t core.Task) (any, bool, error) {
 	switch t := t.(type) {
 	case window.TaskSaveConfig:
-		s.configData["window"] = t.Value
-		s.persistSection("window", t.Value)
+		s.configData["window"] = t.Config
+		s.persistSection("window", t.Config)
 		return nil, true, nil
 	case systray.TaskSaveConfig:
-		s.configData["systray"] = t.Value
-		s.persistSection("systray", t.Value)
+		s.configData["systray"] = t.Config
+		s.persistSection("systray", t.Config)
 		return nil, true, nil
 	case menu.TaskSaveConfig:
-		s.configData["menu"] = t.Value
-		s.persistSection("menu", t.Value)
+		s.configData["menu"] = t.Config
+		s.persistSection("menu", t.Config)
 		return nil, true, nil
 	default:
 		return nil, false, nil
@@ -567,11 +569,11 @@ func (s *Service) handleConfigTask(c *core.Core, t core.Task) (any, bool, error)
 }
 
 func (s *Service) persistSection(key string, value map[string]any) {
-	if s.cfg == nil {
+	if s.configFile == nil {
 		return
 	}
-	_ = s.cfg.Set(key, value)
-	_ = s.cfg.Commit()
+	_ = s.configFile.Set(key, value)
+	_ = s.configFile.Commit()
 }
 
 // --- Service accessors ---
@@ -587,9 +589,13 @@ func (s *Service) windowService() *window.Service {
 
 // --- Window Management (delegates via IPC) ---
 
-// OpenWindow creates a new window via IPC.
-func (s *Service) OpenWindow(opts ...window.WindowOption) error {
-	_, _, err := s.Core().PERFORM(window.TaskOpenWindow{Opts: opts})
+// Deprecated: use CreateWindow(display.CreateWindowOptions{Name: "settings", URL: "/settings", Width: 800, Height: 600}).
+func (s *Service) OpenWindow(options ...window.WindowOption) error {
+	spec, err := window.ApplyOptions(options...)
+	if err != nil {
+		return err
+	}
+	_, _, err = s.Core().PERFORM(window.TaskOpenWindow{Window: spec})
 	return err
 }
 
@@ -600,7 +606,7 @@ func (s *Service) GetWindowInfo(name string) (*window.WindowInfo, error) {
 		return nil, err
 	}
 	if !handled {
-		return nil, fmt.Errorf("window service not available")
+		return nil, coreerr.E("display.GetWindowInfo", "window service not available", nil)
 	}
 	info, _ := result.(*window.WindowInfo)
 	return info, nil
@@ -624,7 +630,7 @@ func (s *Service) SetWindowPosition(name string, x, y int) error {
 
 // SetWindowSize resizes a window via IPC.
 func (s *Service) SetWindowSize(name string, width, height int) error {
-	_, _, err := s.Core().PERFORM(window.TaskSetSize{Name: name, W: width, H: height})
+	_, _, err := s.Core().PERFORM(window.TaskSetSize{Name: name, Width: width, Height: height})
 	return err
 }
 
@@ -633,7 +639,7 @@ func (s *Service) SetWindowBounds(name string, x, y, width, height int) error {
 	if _, _, err := s.Core().PERFORM(window.TaskSetPosition{Name: name, X: x, Y: y}); err != nil {
 		return err
 	}
-	_, _, err := s.Core().PERFORM(window.TaskSetSize{Name: name, W: width, H: height})
+	_, _, err := s.Core().PERFORM(window.TaskSetSize{Name: name, Width: width, Height: height})
 	return err
 }
 
@@ -662,97 +668,41 @@ func (s *Service) CloseWindow(name string) error {
 }
 
 // RestoreWindow restores a maximized/minimized window.
-// Uses direct Manager access (no IPC task for restore yet).
 func (s *Service) RestoreWindow(name string) error {
-	ws := s.windowService()
-	if ws == nil {
-		return fmt.Errorf("window service not available")
-	}
-	pw, ok := ws.Manager().Get(name)
-	if !ok {
-		return fmt.Errorf("window not found: %s", name)
-	}
-	pw.Restore()
-	return nil
+	_, _, err := s.Core().PERFORM(window.TaskRestore{Name: name})
+	return err
 }
 
 // SetWindowVisibility shows or hides a window.
-// Uses direct Manager access (no IPC task for visibility yet).
 func (s *Service) SetWindowVisibility(name string, visible bool) error {
-	ws := s.windowService()
-	if ws == nil {
-		return fmt.Errorf("window service not available")
-	}
-	pw, ok := ws.Manager().Get(name)
-	if !ok {
-		return fmt.Errorf("window not found: %s", name)
-	}
-	pw.SetVisibility(visible)
-	return nil
+	_, _, err := s.Core().PERFORM(window.TaskSetVisibility{Name: name, Visible: visible})
+	return err
 }
 
 // SetWindowAlwaysOnTop sets whether a window stays on top.
-// Uses direct Manager access (no IPC task for always-on-top yet).
 func (s *Service) SetWindowAlwaysOnTop(name string, alwaysOnTop bool) error {
-	ws := s.windowService()
-	if ws == nil {
-		return fmt.Errorf("window service not available")
-	}
-	pw, ok := ws.Manager().Get(name)
-	if !ok {
-		return fmt.Errorf("window not found: %s", name)
-	}
-	pw.SetAlwaysOnTop(alwaysOnTop)
-	return nil
+	_, _, err := s.Core().PERFORM(window.TaskSetAlwaysOnTop{Name: name, AlwaysOnTop: alwaysOnTop})
+	return err
 }
 
 // SetWindowTitle changes a window's title.
-// Uses direct Manager access (no IPC task for title yet).
 func (s *Service) SetWindowTitle(name string, title string) error {
-	ws := s.windowService()
-	if ws == nil {
-		return fmt.Errorf("window service not available")
-	}
-	pw, ok := ws.Manager().Get(name)
-	if !ok {
-		return fmt.Errorf("window not found: %s", name)
-	}
-	pw.SetTitle(title)
-	return nil
+	_, _, err := s.Core().PERFORM(window.TaskSetTitle{Name: name, Title: title})
+	return err
 }
 
 // SetWindowFullscreen sets a window to fullscreen mode.
-// Uses direct Manager access (no IPC task for fullscreen yet).
 func (s *Service) SetWindowFullscreen(name string, fullscreen bool) error {
-	ws := s.windowService()
-	if ws == nil {
-		return fmt.Errorf("window service not available")
-	}
-	pw, ok := ws.Manager().Get(name)
-	if !ok {
-		return fmt.Errorf("window not found: %s", name)
-	}
-	if fullscreen {
-		pw.Fullscreen()
-	} else {
-		pw.UnFullscreen()
-	}
-	return nil
+	_, _, err := s.Core().PERFORM(window.TaskFullscreen{Name: name, Fullscreen: fullscreen})
+	return err
 }
 
 // SetWindowBackgroundColour sets the background colour of a window.
-// Uses direct Manager access (no IPC task for background colour yet).
 func (s *Service) SetWindowBackgroundColour(name string, r, g, b, a uint8) error {
-	ws := s.windowService()
-	if ws == nil {
-		return fmt.Errorf("window service not available")
-	}
-	pw, ok := ws.Manager().Get(name)
-	if !ok {
-		return fmt.Errorf("window not found: %s", name)
-	}
-	pw.SetBackgroundColour(r, g, b, a)
-	return nil
+	_, _, err := s.Core().PERFORM(window.TaskSetBackgroundColour{
+		Name: name, Red: r, Green: g, Blue: b, Alpha: a,
+	})
+	return err
 }
 
 // GetFocusedWindow returns the name of the currently focused window.
@@ -773,7 +723,7 @@ func (s *Service) GetWindowTitle(name string) (string, error) {
 		return "", err
 	}
 	if info == nil {
-		return "", fmt.Errorf("window not found: %s", name)
+		return "", coreerr.E("display.GetWindowTitle", "window not found: "+name, nil)
 	}
 	return info.Title, nil
 }
@@ -802,7 +752,8 @@ func (s *Service) GetSavedWindowStates() map[string]window.WindowState {
 	return result
 }
 
-// CreateWindowOptions contains options for creating a new window.
+// CreateWindowOptions specifies the initial state for a new named window.
+// svc.CreateWindow(display.CreateWindowOptions{Name: "settings", URL: "/settings", Width: 800, Height: 600})
 type CreateWindowOptions struct {
 	Name   string `json:"name"`
 	Title  string `json:"title,omitempty"`
@@ -813,18 +764,19 @@ type CreateWindowOptions struct {
 	Height int    `json:"height,omitempty"`
 }
 
-// CreateWindow creates a new window with the specified options.
-func (s *Service) CreateWindow(opts CreateWindowOptions) (*window.WindowInfo, error) {
-	if opts.Name == "" {
-		return nil, fmt.Errorf("window name is required")
+func (s *Service) CreateWindow(options CreateWindowOptions) (*window.WindowInfo, error) {
+	if options.Name == "" {
+		return nil, coreerr.E("display.CreateWindow", "window name is required", nil)
 	}
 	result, _, err := s.Core().PERFORM(window.TaskOpenWindow{
-		Opts: []window.WindowOption{
-			window.WithName(opts.Name),
-			window.WithTitle(opts.Title),
-			window.WithURL(opts.URL),
-			window.WithSize(opts.Width, opts.Height),
-			window.WithPosition(opts.X, opts.Y),
+		Window: &window.Window{
+			Name:   options.Name,
+			Title:  options.Title,
+			URL:    options.URL,
+			Width:  options.Width,
+			Height: options.Height,
+			X:      options.X,
+			Y:      options.Y,
 		},
 	})
 	if err != nil {
@@ -838,113 +790,68 @@ func (s *Service) CreateWindow(opts CreateWindowOptions) (*window.WindowInfo, er
 
 // SaveLayout saves the current window arrangement as a named layout.
 func (s *Service) SaveLayout(name string) error {
-	ws := s.windowService()
-	if ws == nil {
-		return fmt.Errorf("window service not available")
-	}
-	states := make(map[string]window.WindowState)
-	for _, n := range ws.Manager().List() {
-		if pw, ok := ws.Manager().Get(n); ok {
-			x, y := pw.Position()
-			w, h := pw.Size()
-			states[n] = window.WindowState{X: x, Y: y, Width: w, Height: h, Maximized: pw.IsMaximised()}
-		}
-	}
-	return ws.Manager().Layout().SaveLayout(name, states)
+	_, _, err := s.Core().PERFORM(window.TaskSaveLayout{Name: name})
+	return err
 }
 
 // RestoreLayout applies a saved layout.
 func (s *Service) RestoreLayout(name string) error {
-	ws := s.windowService()
-	if ws == nil {
-		return fmt.Errorf("window service not available")
-	}
-	layout, ok := ws.Manager().Layout().GetLayout(name)
-	if !ok {
-		return fmt.Errorf("layout not found: %s", name)
-	}
-	for wName, state := range layout.Windows {
-		if pw, ok := ws.Manager().Get(wName); ok {
-			pw.SetPosition(state.X, state.Y)
-			pw.SetSize(state.Width, state.Height)
-			if state.Maximized {
-				pw.Maximise()
-			} else {
-				pw.Restore()
-			}
-		}
-	}
-	return nil
+	_, _, err := s.Core().PERFORM(window.TaskRestoreLayout{Name: name})
+	return err
 }
 
 // ListLayouts returns all saved layout names with metadata.
 func (s *Service) ListLayouts() []window.LayoutInfo {
-	ws := s.windowService()
-	if ws == nil {
+	result, handled, _ := s.Core().QUERY(window.QueryLayoutList{})
+	if !handled {
 		return nil
 	}
-	return ws.Manager().Layout().ListLayouts()
+	layouts, _ := result.([]window.LayoutInfo)
+	return layouts
 }
 
 // DeleteLayout removes a saved layout by name.
 func (s *Service) DeleteLayout(name string) error {
-	ws := s.windowService()
-	if ws == nil {
-		return fmt.Errorf("window service not available")
-	}
-	ws.Manager().Layout().DeleteLayout(name)
-	return nil
+	_, _, err := s.Core().PERFORM(window.TaskDeleteLayout{Name: name})
+	return err
 }
 
 // GetLayout returns a specific layout by name.
 func (s *Service) GetLayout(name string) *window.Layout {
-	ws := s.windowService()
-	if ws == nil {
+	result, handled, _ := s.Core().QUERY(window.QueryLayoutGet{Name: name})
+	if !handled {
 		return nil
 	}
-	layout, ok := ws.Manager().Layout().GetLayout(name)
-	if !ok {
-		return nil
-	}
-	return &layout
+	layout, _ := result.(*window.Layout)
+	return layout
 }
 
 // --- Tiling/snapping delegation ---
 
 // TileWindows arranges windows in a tiled layout.
 func (s *Service) TileWindows(mode window.TileMode, windowNames []string) error {
-	ws := s.windowService()
-	if ws == nil {
-		return fmt.Errorf("window service not available")
-	}
-	return ws.Manager().TileWindows(mode, windowNames, 1920, 1080) // TODO: use actual screen size
+	_, _, err := s.Core().PERFORM(window.TaskTileWindows{Mode: mode.String(), Windows: windowNames})
+	return err
 }
 
 // SnapWindow snaps a window to a screen edge or corner.
 func (s *Service) SnapWindow(name string, position window.SnapPosition) error {
-	ws := s.windowService()
-	if ws == nil {
-		return fmt.Errorf("window service not available")
-	}
-	return ws.Manager().SnapWindow(name, position, 1920, 1080) // TODO: use actual screen size
+	_, _, err := s.Core().PERFORM(window.TaskSnapWindow{Name: name, Position: position.String()})
+	return err
 }
 
 // StackWindows arranges windows in a cascade pattern.
 func (s *Service) StackWindows(windowNames []string, offsetX, offsetY int) error {
-	ws := s.windowService()
-	if ws == nil {
-		return fmt.Errorf("window service not available")
-	}
-	return ws.Manager().StackWindows(windowNames, offsetX, offsetY)
+	_, _, err := s.Core().PERFORM(window.TaskStackWindows{Windows: windowNames, OffsetX: offsetX, OffsetY: offsetY})
+	return err
 }
 
 // ApplyWorkflowLayout applies a predefined layout for a specific workflow.
 func (s *Service) ApplyWorkflowLayout(workflow window.WorkflowLayout) error {
-	ws := s.windowService()
-	if ws == nil {
-		return fmt.Errorf("window service not available")
-	}
-	return ws.Manager().ApplyWorkflow(workflow, ws.Manager().List(), 1920, 1080)
+	_, _, err := s.Core().PERFORM(window.TaskApplyWorkflow{
+		Workflow: workflow.String(),
+	})
+	return err
 }
 
 // GetEventManager returns the event manager for WebSocket event subscriptions.
@@ -993,11 +900,12 @@ func ptr[T any](v T) *T { return &v }
 
 func (s *Service) handleNewWorkspace() {
 	_, _, _ = s.Core().PERFORM(window.TaskOpenWindow{
-		Opts: []window.WindowOption{
-			window.WithName("workspace-new"),
-			window.WithTitle("New Workspace"),
-			window.WithURL("/workspace/new"),
-			window.WithSize(500, 400),
+		Window: &window.Window{
+			Name:   "workspace-new",
+			Title:  "New Workspace",
+			URL:    "/workspace/new",
+			Width:  500,
+			Height: 400,
 		},
 	})
 }
@@ -1016,18 +924,19 @@ func (s *Service) handleListWorkspaces() {
 
 func (s *Service) handleNewFile() {
 	_, _, _ = s.Core().PERFORM(window.TaskOpenWindow{
-		Opts: []window.WindowOption{
-			window.WithName("editor"),
-			window.WithTitle("New File - Editor"),
-			window.WithURL("/#/developer/editor?new=true"),
-			window.WithSize(1200, 800),
+		Window: &window.Window{
+			Name:   "editor",
+			Title:  "New File - Editor",
+			URL:    "/#/developer/editor?new=true",
+			Width:  1200,
+			Height: 800,
 		},
 	})
 }
 
 func (s *Service) handleOpenFile() {
 	result, handled, err := s.Core().PERFORM(dialog.TaskOpenFile{
-		Opts: dialog.OpenFileOptions{
+		Options: dialog.OpenFileOptions{
 			Title:         "Open File",
 			AllowMultiple: false,
 		},
@@ -1040,11 +949,12 @@ func (s *Service) handleOpenFile() {
 		return
 	}
 	_, _, _ = s.Core().PERFORM(window.TaskOpenWindow{
-		Opts: []window.WindowOption{
-			window.WithName("editor"),
-			window.WithTitle(paths[0] + " - Editor"),
-			window.WithURL("/#/developer/editor?file=" + paths[0]),
-			window.WithSize(1200, 800),
+		Window: &window.Window{
+			Name:   "editor",
+			Title:  paths[0] + " - Editor",
+			URL:    "/#/developer/editor?file=" + paths[0],
+			Width:  1200,
+			Height: 800,
 		},
 	})
 }
@@ -1052,21 +962,23 @@ func (s *Service) handleOpenFile() {
 func (s *Service) handleSaveFile() { _ = s.Core().ACTION(ActionIDECommand{Command: "save"}) }
 func (s *Service) handleOpenEditor() {
 	_, _, _ = s.Core().PERFORM(window.TaskOpenWindow{
-		Opts: []window.WindowOption{
-			window.WithName("editor"),
-			window.WithTitle("Editor"),
-			window.WithURL("/#/developer/editor"),
-			window.WithSize(1200, 800),
+		Window: &window.Window{
+			Name:   "editor",
+			Title:  "Editor",
+			URL:    "/#/developer/editor",
+			Width:  1200,
+			Height: 800,
 		},
 	})
 }
 func (s *Service) handleOpenTerminal() {
 	_, _, _ = s.Core().PERFORM(window.TaskOpenWindow{
-		Opts: []window.WindowOption{
-			window.WithName("terminal"),
-			window.WithTitle("Terminal"),
-			window.WithURL("/#/developer/terminal"),
-			window.WithSize(800, 500),
+		Window: &window.Window{
+			Name:   "terminal",
+			Title:  "Terminal",
+			URL:    "/#/developer/terminal",
+			Width:  800,
+			Height: 500,
 		},
 	})
 }

pkg/display/display_test.go

@@ -44,25 +44,29 @@ func newTestConclave(t *testing.T) *core.Core {
 	return c
 }
 
-// --- Tests ---
-
-func TestNew(t *testing.T) {
-	t.Run("creates service successfully", func(t *testing.T) {
-		service, err := New()
-		assert.NoError(t, err)
-		assert.NotNil(t, service, "New() should return a non-nil service instance")
-	})
-
-	t.Run("returns independent instances", func(t *testing.T) {
-		service1, err1 := New()
-		service2, err2 := New()
-		assert.NoError(t, err1)
-		assert.NoError(t, err2)
-		assert.NotSame(t, service1, service2, "New() should return different instances")
-	})
+func requireCreateWindow(t *testing.T, svc *Service, options CreateWindowOptions) {
+	t.Helper()
+	_, err := svc.CreateWindow(options)
+	require.NoError(t, err)
 }
 
-func TestRegisterClosure_Good(t *testing.T) {
+// --- Tests ---
+
+func TestNewService_Good(t *testing.T) {
+	service, err := NewService()
+	assert.NoError(t, err)
+	assert.NotNil(t, service)
+}
+
+func TestNewService_Good_IndependentInstances(t *testing.T) {
+	service1, err1 := NewService()
+	service2, err2 := NewService()
+	assert.NoError(t, err1)
+	assert.NoError(t, err2)
+	assert.NotSame(t, service1, service2)
+}
+
+func TestRegister_Good(t *testing.T) {
 	factory := Register(nil) // nil wailsApp for testing
 	assert.NotNil(t, factory)
 
@@ -104,7 +108,7 @@ func TestConfigTask_Good(t *testing.T) {
 	_, c := newTestDisplayService(t)
 
 	newCfg := map[string]any{"default_width": 800}
-	_, handled, err := c.PERFORM(window.TaskSaveConfig{Value: newCfg})
+	_, handled, err := c.PERFORM(window.TaskSaveConfig{Config: newCfg})
 	require.NoError(t, err)
 	assert.True(t, handled)
 
@@ -121,7 +125,7 @@ func TestServiceConclave_Good(t *testing.T) {
 
 	// Open a window via IPC
 	result, handled, err := c.PERFORM(window.TaskOpenWindow{
-		Opts: []window.WindowOption{window.WithName("main")},
+		Window: &window.Window{Name: "main"},
 	})
 	require.NoError(t, err)
 	assert.True(t, handled)
@@ -163,7 +167,7 @@ func TestServiceConclave_Bad(t *testing.T) {
 
 // --- IPC delegation tests (full conclave) ---
 
-func TestOpenWindow_Good(t *testing.T) {
+func TestOpenWindow_Compatibility_Good(t *testing.T) {
 	c := newTestConclave(t)
 	svc := core.MustServiceFor[*Service](c, "display")
 
@@ -176,17 +180,16 @@ func TestOpenWindow_Good(t *testing.T) {
 		assert.GreaterOrEqual(t, len(infos), 1)
 	})
 
-	t.Run("creates window with custom options", func(t *testing.T) {
-		err := svc.OpenWindow(
-			window.WithName("custom-window"),
-			window.WithTitle("Custom Title"),
-			window.WithSize(640, 480),
-			window.WithURL("/custom"),
-		)
-		assert.NoError(t, err)
+	t.Run("creates window with declarative options", func(t *testing.T) {
+		info, err := svc.CreateWindow(CreateWindowOptions{
+			Name:   "custom-window",
+			Title:  "Custom Title",
+			URL:    "/custom",
+			Width:  640,
+			Height: 480,
+		})
+		require.NoError(t, err)
 
-		result, _, _ := c.QUERY(window.QueryWindowByName{Name: "custom-window"})
-		info := result.(*window.WindowInfo)
 		assert.Equal(t, "custom-window", info.Name)
 	})
 }
@@ -195,10 +198,7 @@ func TestGetWindowInfo_Good(t *testing.T) {
 	c := newTestConclave(t)
 	svc := core.MustServiceFor[*Service](c, "display")
 
-	_ = svc.OpenWindow(
-		window.WithName("test-win"),
-		window.WithSize(800, 600),
-	)
+	requireCreateWindow(t, svc, CreateWindowOptions{Name: "test-win", Width: 800, Height: 600})
 
 	// Modify position via IPC
 	_, _, _ = c.PERFORM(window.TaskSetPosition{Name: "test-win", X: 100, Y: 200})
@@ -226,8 +226,8 @@ func TestListWindowInfos_Good(t *testing.T) {
 	c := newTestConclave(t)
 	svc := core.MustServiceFor[*Service](c, "display")
 
-	_ = svc.OpenWindow(window.WithName("win-1"))
-	_ = svc.OpenWindow(window.WithName("win-2"))
+	requireCreateWindow(t, svc, CreateWindowOptions{Name: "win-1"})
+	requireCreateWindow(t, svc, CreateWindowOptions{Name: "win-2"})
 
 	infos := svc.ListWindowInfos()
 	assert.Len(t, infos, 2)
@@ -236,7 +236,7 @@ func TestListWindowInfos_Good(t *testing.T) {
 func TestSetWindowPosition_Good(t *testing.T) {
 	c := newTestConclave(t)
 	svc := core.MustServiceFor[*Service](c, "display")
-	_ = svc.OpenWindow(window.WithName("pos-win"))
+	requireCreateWindow(t, svc, CreateWindowOptions{Name: "pos-win"})
 
 	err := svc.SetWindowPosition("pos-win", 300, 400)
 	assert.NoError(t, err)
@@ -257,7 +257,7 @@ func TestSetWindowPosition_Bad(t *testing.T) {
 func TestSetWindowSize_Good(t *testing.T) {
 	c := newTestConclave(t)
 	svc := core.MustServiceFor[*Service](c, "display")
-	_ = svc.OpenWindow(window.WithName("size-win"))
+	requireCreateWindow(t, svc, CreateWindowOptions{Name: "size-win"})
 
 	err := svc.SetWindowSize("size-win", 1024, 768)
 	assert.NoError(t, err)
@@ -270,7 +270,7 @@ func TestSetWindowSize_Good(t *testing.T) {
 func TestMaximizeWindow_Good(t *testing.T) {
 	c := newTestConclave(t)
 	svc := core.MustServiceFor[*Service](c, "display")
-	_ = svc.OpenWindow(window.WithName("max-win"))
+	requireCreateWindow(t, svc, CreateWindowOptions{Name: "max-win"})
 
 	err := svc.MaximizeWindow("max-win")
 	assert.NoError(t, err)
@@ -282,7 +282,7 @@ func TestMaximizeWindow_Good(t *testing.T) {
 func TestRestoreWindow_Good(t *testing.T) {
 	c := newTestConclave(t)
 	svc := core.MustServiceFor[*Service](c, "display")
-	_ = svc.OpenWindow(window.WithName("restore-win"))
+	requireCreateWindow(t, svc, CreateWindowOptions{Name: "restore-win"})
 	_ = svc.MaximizeWindow("restore-win")
 
 	err := svc.RestoreWindow("restore-win")
@@ -295,7 +295,7 @@ func TestRestoreWindow_Good(t *testing.T) {
 func TestFocusWindow_Good(t *testing.T) {
 	c := newTestConclave(t)
 	svc := core.MustServiceFor[*Service](c, "display")
-	_ = svc.OpenWindow(window.WithName("focus-win"))
+	requireCreateWindow(t, svc, CreateWindowOptions{Name: "focus-win"})
 
 	err := svc.FocusWindow("focus-win")
 	assert.NoError(t, err)
@@ -307,7 +307,7 @@ func TestFocusWindow_Good(t *testing.T) {
 func TestCloseWindow_Good(t *testing.T) {
 	c := newTestConclave(t)
 	svc := core.MustServiceFor[*Service](c, "display")
-	_ = svc.OpenWindow(window.WithName("close-win"))
+	requireCreateWindow(t, svc, CreateWindowOptions{Name: "close-win"})
 
 	err := svc.CloseWindow("close-win")
 	assert.NoError(t, err)
@@ -320,7 +320,7 @@ func TestCloseWindow_Good(t *testing.T) {
 func TestSetWindowVisibility_Good(t *testing.T) {
 	c := newTestConclave(t)
 	svc := core.MustServiceFor[*Service](c, "display")
-	_ = svc.OpenWindow(window.WithName("vis-win"))
+	requireCreateWindow(t, svc, CreateWindowOptions{Name: "vis-win"})
 
 	err := svc.SetWindowVisibility("vis-win", false)
 	assert.NoError(t, err)
@@ -332,7 +332,7 @@ func TestSetWindowVisibility_Good(t *testing.T) {
 func TestSetWindowAlwaysOnTop_Good(t *testing.T) {
 	c := newTestConclave(t)
 	svc := core.MustServiceFor[*Service](c, "display")
-	_ = svc.OpenWindow(window.WithName("ontop-win"))
+	requireCreateWindow(t, svc, CreateWindowOptions{Name: "ontop-win"})
 
 	err := svc.SetWindowAlwaysOnTop("ontop-win", true)
 	assert.NoError(t, err)
@@ -341,7 +341,7 @@ func TestSetWindowAlwaysOnTop_Good(t *testing.T) {
 func TestSetWindowTitle_Good(t *testing.T) {
 	c := newTestConclave(t)
 	svc := core.MustServiceFor[*Service](c, "display")
-	_ = svc.OpenWindow(window.WithName("title-win"))
+	requireCreateWindow(t, svc, CreateWindowOptions{Name: "title-win"})
 
 	err := svc.SetWindowTitle("title-win", "New Title")
 	assert.NoError(t, err)
@@ -350,18 +350,18 @@ func TestSetWindowTitle_Good(t *testing.T) {
 func TestGetFocusedWindow_Good(t *testing.T) {
 	c := newTestConclave(t)
 	svc := core.MustServiceFor[*Service](c, "display")
-	_ = svc.OpenWindow(window.WithName("win-a"))
-	_ = svc.OpenWindow(window.WithName("win-b"))
+	requireCreateWindow(t, svc, CreateWindowOptions{Name: "win-a"})
+	requireCreateWindow(t, svc, CreateWindowOptions{Name: "win-b"})
 	_ = svc.FocusWindow("win-b")
 
 	focused := svc.GetFocusedWindow()
 	assert.Equal(t, "win-b", focused)
 }
 
-func TestGetFocusedWindow_NoneSelected(t *testing.T) {
+func TestGetFocusedWindow_Good_NoneSelected(t *testing.T) {
 	c := newTestConclave(t)
 	svc := core.MustServiceFor[*Service](c, "display")
-	_ = svc.OpenWindow(window.WithName("win-a"))
+	requireCreateWindow(t, svc, CreateWindowOptions{Name: "win-a"})
 
 	focused := svc.GetFocusedWindow()
 	assert.Equal(t, "", focused)
@@ -413,7 +413,7 @@ func TestHandleIPCEvents_WindowOpened_Good(t *testing.T) {
 	// Open a window — this should trigger ActionWindowOpened
 	// which HandleIPCEvents should convert to a WS event
 	result, handled, err := c.PERFORM(window.TaskOpenWindow{
-		Opts: []window.WindowOption{window.WithName("test")},
+		Window: &window.Window{Name: "test"},
 	})
 	require.NoError(t, err)
 	assert.True(t, handled)
@@ -456,7 +456,7 @@ menu:
   show_dev_tools: false
 `), 0o644))
 
-	s, _ := New()
+	s, _ := NewService()
 	s.loadConfigFrom(cfgPath)
 
 	// Verify configData was populated from file
@@ -466,7 +466,7 @@ menu:
 }
 
 func TestLoadConfig_Bad_MissingFile(t *testing.T) {
-	s, _ := New()
+	s, _ := NewService()
 	s.loadConfigFrom(filepath.Join(t.TempDir(), "nonexistent.yaml"))
 
 	// Should not panic, configData stays at empty defaults
@@ -479,7 +479,7 @@ func TestHandleConfigTask_Persists_Good(t *testing.T) {
 	dir := t.TempDir()
 	cfgPath := filepath.Join(dir, "config.yaml")
 
-	s, _ := New()
+	s, _ := NewService()
 	s.loadConfigFrom(cfgPath) // Creates empty config (file doesn't exist yet)
 
 	// Simulate a TaskSaveConfig through the handler
@@ -493,7 +493,7 @@ func TestHandleConfigTask_Persists_Good(t *testing.T) {
 	c.ServiceStartup(context.Background(), nil)
 
 	_, handled, err := c.PERFORM(window.TaskSaveConfig{
-		Value: map[string]any{"default_width": 1920},
+		Config: map[string]any{"default_width": 1920},
 	})
 	require.NoError(t, err)
 	assert.True(t, handled)

pkg/display/events.go

@@ -2,8 +2,8 @@ package display
 
 import (
 	"encoding/json"
-	"fmt"
 	"net/http"
+	"strconv"
 	"sync"
 	"time"
 
@@ -15,12 +15,12 @@ import (
 type EventType string
 
 const (
-	EventWindowFocus  EventType = "window.focus"
-	EventWindowBlur   EventType = "window.blur"
-	EventWindowMove   EventType = "window.move"
-	EventWindowResize EventType = "window.resize"
-	EventWindowClose  EventType = "window.close"
-	EventWindowCreate EventType = "window.create"
+	EventWindowFocus         EventType = "window.focus"
+	EventWindowBlur          EventType = "window.blur"
+	EventWindowMove          EventType = "window.move"
+	EventWindowResize        EventType = "window.resize"
+	EventWindowClose         EventType = "window.close"
+	EventWindowCreate        EventType = "window.create"
 	EventThemeChange         EventType = "theme.change"
 	EventScreenChange        EventType = "screen.change"
 	EventNotificationClick   EventType = "notification.click"
@@ -202,7 +202,7 @@ func (em *WSEventManager) subscribe(conn *websocket.Conn, id string, eventTypes
 	if id == "" {
 		em.mu.Lock()
 		em.nextSubID++
-		id = fmt.Sprintf("sub-%d", em.nextSubID)
+		id = "sub-" + strconv.Itoa(em.nextSubID)
 		em.mu.Unlock()
 	}
 

pkg/dock/register.go

@@ -1,10 +1,9 @@
-// pkg/dock/register.go
 package dock
 
 import "forge.lthn.ai/core/go/pkg/core"
 
-// Register creates a factory closure that captures the Platform adapter.
-// The returned function has the signature WithService requires: func(*Core) (any, error).
+// Register(p) binds the dock service to a Core instance.
+// core.WithService(dock.Register(wailsDock))
 func Register(p Platform) func(*core.Core) (any, error) {
 	return func(c *core.Core) (any, error) {
 		return &Service{

pkg/dock/service.go

@@ -1,4 +1,3 @@
-// pkg/dock/service.go
 package dock
 
 import (
@@ -7,30 +6,23 @@ import (
 	"forge.lthn.ai/core/go/pkg/core"
 )
 
-// Options holds configuration for the dock service.
 type Options struct{}
 
-// Service is a core.Service managing dock/taskbar operations via IPC.
-// It embeds ServiceRuntime for Core access and delegates to Platform.
 type Service struct {
 	*core.ServiceRuntime[Options]
 	platform Platform
 }
 
-// OnStartup registers IPC handlers.
 func (s *Service) OnStartup(ctx context.Context) error {
 	s.Core().RegisterQuery(s.handleQuery)
 	s.Core().RegisterTask(s.handleTask)
 	return nil
 }
 
-// HandleIPCEvents is auto-discovered and registered by core.WithService.
 func (s *Service) HandleIPCEvents(c *core.Core, msg core.Message) error {
 	return nil
 }
 
-// --- Query Handlers ---
-
 func (s *Service) handleQuery(c *core.Core, q core.Query) (any, bool, error) {
 	switch q.(type) {
 	case QueryVisible:
@@ -40,8 +32,6 @@ func (s *Service) handleQuery(c *core.Core, q core.Query) (any, bool, error) {
 	}
 }
 
-// --- Task Handlers ---
-
 func (s *Service) handleTask(c *core.Core, t core.Task) (any, bool, error) {
 	switch t := t.(type) {
 	case TaskShowIcon:

pkg/environment/service.go

@@ -7,17 +7,16 @@ import (
 	"forge.lthn.ai/core/go/pkg/core"
 )
 
-// Options holds configuration for the environment service.
 type Options struct{}
 
-// Service is a core.Service providing environment queries and theme change events via IPC.
 type Service struct {
 	*core.ServiceRuntime[Options]
 	platform    Platform
-	cancelTheme func() // cancel function for theme change listener
+	cancelTheme func() // returned by Platform.OnThemeChange — called on shutdown
 }
 
-// Register creates a factory closure that captures the Platform adapter.
+// Register(p) binds the environment service to a Core instance.
+// core.WithService(environment.Register(wailsEnvironment))
 func Register(p Platform) func(*core.Core) (any, error) {
 	return func(c *core.Core) (any, error) {
 		return &Service{
@@ -27,7 +26,6 @@ func Register(p Platform) func(*core.Core) (any, error) {
 	}
 }
 
-// OnStartup registers IPC handlers and the theme change listener.
 func (s *Service) OnStartup(ctx context.Context) error {
 	s.Core().RegisterQuery(s.handleQuery)
 	s.Core().RegisterTask(s.handleTask)
@@ -39,7 +37,6 @@ func (s *Service) OnStartup(ctx context.Context) error {
 	return nil
 }
 
-// OnShutdown cancels the theme change listener.
 func (s *Service) OnShutdown(ctx context.Context) error {
 	if s.cancelTheme != nil {
 		s.cancelTheme()
@@ -47,7 +44,6 @@ func (s *Service) OnShutdown(ctx context.Context) error {
 	return nil
 }
 
-// HandleIPCEvents is auto-discovered by core.WithService.
 func (s *Service) HandleIPCEvents(c *core.Core, msg core.Message) error {
 	return nil
 }

pkg/keybinding/messages.go

@@ -1,40 +1,30 @@
-// pkg/keybinding/messages.go
 package keybinding
 
 import "errors"
 
-// ErrAlreadyRegistered is returned when attempting to add a binding
-// that already exists. Callers must TaskRemove first to rebind.
-var ErrAlreadyRegistered = errors.New("keybinding: accelerator already registered")
+var ErrorAlreadyRegistered = errors.New("keybinding: accelerator already registered")
 
-// BindingInfo describes a registered keyboard shortcut.
+// BindingInfo describes a registered global key binding.
 type BindingInfo struct {
 	Accelerator string `json:"accelerator"`
 	Description string `json:"description"`
 }
 
-// --- Queries ---
-
-// QueryList returns all registered bindings. Result: []BindingInfo
+// QueryList returns all registered key bindings. Result: []BindingInfo
 type QueryList struct{}
 
-// --- Tasks ---
-
-// TaskAdd registers a new keyboard shortcut. Result: nil
-// Returns ErrAlreadyRegistered if the accelerator is already bound.
+// TaskAdd registers a global key binding. Error: ErrorAlreadyRegistered if accelerator taken.
 type TaskAdd struct {
 	Accelerator string `json:"accelerator"`
 	Description string `json:"description"`
 }
 
-// TaskRemove unregisters a keyboard shortcut. Result: nil
+// TaskRemove unregisters a global key binding by accelerator.
 type TaskRemove struct {
 	Accelerator string `json:"accelerator"`
 }
 
-// --- Actions ---
-
-// ActionTriggered is broadcast when a registered shortcut is activated.
+// ActionTriggered is broadcast when a registered key binding fires.
 type ActionTriggered struct {
 	Accelerator string `json:"accelerator"`
 }

pkg/keybinding/register.go

@@ -1,16 +1,15 @@
-// pkg/keybinding/register.go
 package keybinding
 
 import "forge.lthn.ai/core/go/pkg/core"
 
-// Register creates a factory closure that captures the Platform adapter.
-// The returned function has the signature WithService requires: func(*Core) (any, error).
+// Register(p) binds the keybinding service to a Core instance.
+// core.WithService(keybinding.Register(wailsKeybinding))
 func Register(p Platform) func(*core.Core) (any, error) {
 	return func(c *core.Core) (any, error) {
 		return &Service{
-			ServiceRuntime: core.NewServiceRuntime[Options](c, Options{}),
-			platform:       p,
-			bindings:       make(map[string]BindingInfo),
+			ServiceRuntime:     core.NewServiceRuntime[Options](c, Options{}),
+			platform:           p,
+			registeredBindings: make(map[string]BindingInfo),
 		}, nil
 	}
 }

pkg/keybinding/service.go

@@ -3,31 +3,25 @@ package keybinding
 
 import (
 	"context"
-	"fmt"
 
+	coreerr "forge.lthn.ai/core/go-log"
 	"forge.lthn.ai/core/go/pkg/core"
 )
 
-// Options holds configuration for the keybinding service.
 type Options struct{}
 
-// Service is a core.Service managing keyboard shortcuts via IPC.
-// It maintains an in-memory registry of bindings and delegates
-// platform-level registration to the Platform interface.
 type Service struct {
 	*core.ServiceRuntime[Options]
-	platform Platform
-	bindings map[string]BindingInfo
+	platform           Platform
+	registeredBindings map[string]BindingInfo
 }
 
-// OnStartup registers IPC handlers.
 func (s *Service) OnStartup(ctx context.Context) error {
 	s.Core().RegisterQuery(s.handleQuery)
 	s.Core().RegisterTask(s.handleTask)
 	return nil
 }
 
-// HandleIPCEvents is auto-discovered and registered by core.WithService.
 func (s *Service) HandleIPCEvents(c *core.Core, msg core.Message) error {
 	return nil
 }
@@ -43,10 +37,9 @@ func (s *Service) handleQuery(c *core.Core, q core.Query) (any, bool, error) {
 	}
 }
 
-// queryList reads from the in-memory registry (not platform.GetAll()).
 func (s *Service) queryList() []BindingInfo {
-	result := make([]BindingInfo, 0, len(s.bindings))
-	for _, info := range s.bindings {
+	result := make([]BindingInfo, 0, len(s.registeredBindings))
+	for _, info := range s.registeredBindings {
 		result = append(result, info)
 	}
 	return result
@@ -66,8 +59,8 @@ func (s *Service) handleTask(c *core.Core, t core.Task) (any, bool, error) {
 }
 
 func (s *Service) taskAdd(t TaskAdd) error {
-	if _, exists := s.bindings[t.Accelerator]; exists {
-		return ErrAlreadyRegistered
+	if _, exists := s.registeredBindings[t.Accelerator]; exists {
+		return ErrorAlreadyRegistered
 	}
 
 	// Register on platform with a callback that broadcasts ActionTriggered
@@ -75,10 +68,10 @@ func (s *Service) taskAdd(t TaskAdd) error {
 		_ = s.Core().ACTION(ActionTriggered{Accelerator: t.Accelerator})
 	})
 	if err != nil {
-		return fmt.Errorf("keybinding: platform add failed: %w", err)
+		return coreerr.E("keybinding.taskAdd", "platform add failed", err)
 	}
 
-	s.bindings[t.Accelerator] = BindingInfo{
+	s.registeredBindings[t.Accelerator] = BindingInfo{
 		Accelerator: t.Accelerator,
 		Description: t.Description,
 	}
@@ -86,15 +79,15 @@ func (s *Service) taskAdd(t TaskAdd) error {
 }
 
 func (s *Service) taskRemove(t TaskRemove) error {
-	if _, exists := s.bindings[t.Accelerator]; !exists {
-		return fmt.Errorf("keybinding: not registered: %s", t.Accelerator)
+	if _, exists := s.registeredBindings[t.Accelerator]; !exists {
+		return coreerr.E("keybinding.taskRemove", "not registered: "+t.Accelerator, nil)
 	}
 
 	err := s.platform.Remove(t.Accelerator)
 	if err != nil {
-		return fmt.Errorf("keybinding: platform remove failed: %w", err)
+		return coreerr.E("keybinding.taskRemove", "platform remove failed", err)
 	}
 
-	delete(s.bindings, t.Accelerator)
+	delete(s.registeredBindings, t.Accelerator)
 	return nil
 }

pkg/keybinding/service_test.go

@@ -99,7 +99,7 @@ func TestTaskAdd_Bad_Duplicate(t *testing.T) {
 	// Second add with same accelerator should fail
 	_, handled, err := c.PERFORM(TaskAdd{Accelerator: "Ctrl+S", Description: "Save Again"})
 	assert.True(t, handled)
-	assert.ErrorIs(t, err, ErrAlreadyRegistered)
+	assert.ErrorIs(t, err, ErrorAlreadyRegistered)
 }
 
 func TestTaskRemove_Good(t *testing.T) {

pkg/lifecycle/register.go

@@ -1,10 +1,9 @@
-// pkg/lifecycle/register.go
 package lifecycle
 
 import "forge.lthn.ai/core/go/pkg/core"
 
-// Register creates a factory closure that captures the Platform adapter.
-// The returned function has the signature WithService requires: func(*Core) (any, error).
+// Register(p) binds the lifecycle service to a Core instance.
+// core.WithService(lifecycle.Register(wailsLifecycle))
 func Register(p Platform) func(*core.Core) (any, error) {
 	return func(c *core.Core) (any, error) {
 		return &Service{

pkg/lifecycle/service.go

@@ -1,4 +1,3 @@
-// pkg/lifecycle/service.go
 package lifecycle
 
 import (
@@ -7,22 +6,15 @@ import (
 	"forge.lthn.ai/core/go/pkg/core"
 )
 
-// Options holds configuration for the lifecycle service.
 type Options struct{}
 
-// Service is a core.Service that registers platform lifecycle callbacks
-// and broadcasts corresponding IPC Actions. It implements both Startable
-// and Stoppable: OnStartup registers all callbacks, OnShutdown cancels them.
 type Service struct {
 	*core.ServiceRuntime[Options]
 	platform Platform
 	cancels  []func()
 }
 
-// OnStartup registers a platform callback for each EventType and for file-open.
-// Each callback broadcasts the corresponding Action via s.Core().ACTION().
 func (s *Service) OnStartup(ctx context.Context) error {
-	// Register fire-and-forget event callbacks
 	eventActions := map[EventType]func(){
 		EventApplicationStarted: func() { _ = s.Core().ACTION(ActionApplicationStarted{}) },
 		EventWillTerminate:      func() { _ = s.Core().ACTION(ActionWillTerminate{}) },
@@ -38,7 +30,6 @@ func (s *Service) OnStartup(ctx context.Context) error {
 		s.cancels = append(s.cancels, cancel)
 	}
 
-	// Register file-open callback (carries data)
 	cancel := s.platform.OnOpenedWithFile(func(path string) {
 		_ = s.Core().ACTION(ActionOpenedWithFile{Path: path})
 	})
@@ -47,7 +38,6 @@ func (s *Service) OnStartup(ctx context.Context) error {
 	return nil
 }
 
-// OnShutdown cancels all registered platform callbacks.
 func (s *Service) OnShutdown(ctx context.Context) error {
 	for _, cancel := range s.cancels {
 		cancel()
@@ -56,8 +46,6 @@ func (s *Service) OnShutdown(ctx context.Context) error {
 	return nil
 }
 
-// HandleIPCEvents is auto-discovered and registered by core.WithService.
-// Lifecycle events are all outbound (platform -> IPC) so there is nothing to handle here.
 func (s *Service) HandleIPCEvents(c *core.Core, msg core.Message) error {
 	return nil
 }

pkg/mcp/mcp_test.go

@@ -14,13 +14,13 @@ import (
 
 func TestSubsystem_Good_Name(t *testing.T) {
 	c, _ := core.New(core.WithServiceLock())
-	sub := New(c)
+	sub := NewSubsystem(c)
 	assert.Equal(t, "display", sub.Name())
 }
 
 func TestSubsystem_Good_RegisterTools(t *testing.T) {
 	c, _ := core.New(core.WithServiceLock())
-	sub := New(c)
+	sub := NewSubsystem(c)
 	// RegisterTools should not panic with a real mcp.Server
 	server := mcp.NewServer(&mcp.Implementation{Name: "test", Version: "0.1.0"}, nil)
 	assert.NotPanics(t, func() { sub.RegisterTools(server) })
@@ -34,7 +34,7 @@ type mockClipPlatform struct {
 }
 
 func (m *mockClipPlatform) Text() (string, bool)  { return m.text, m.ok }
-func (m *mockClipPlatform) SetText(t string) bool  { m.text = t; m.ok = t != ""; return true }
+func (m *mockClipPlatform) SetText(t string) bool { m.text = t; m.ok = t != ""; return true }
 
 func TestMCP_Good_ClipboardRoundTrip(t *testing.T) {
 	c, err := core.New(

pkg/mcp/subsystem.go

@@ -6,21 +6,24 @@ import (
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
-// Subsystem implements the MCP Subsystem interface via structural typing.
-// It registers GUI tools that translate MCP tool calls to IPC messages.
+// Subsystem translates MCP tool calls to Core IPC messages for GUI operations.
 type Subsystem struct {
 	core *core.Core
 }
 
-// New creates a display MCP subsystem backed by the given Core instance.
-func New(c *core.Core) *Subsystem {
+// NewSubsystem creates the display MCP bridge for a Core instance.
+// sub := mcp.NewSubsystem(c); sub.RegisterTools(server)
+func NewSubsystem(c *core.Core) *Subsystem {
 	return &Subsystem{core: c}
 }
 
-// Name returns the subsystem identifier.
+// Deprecated: use NewSubsystem(c).
+func New(c *core.Core) *Subsystem {
+	return NewSubsystem(c)
+}
+
 func (s *Subsystem) Name() string { return "display" }
 
-// RegisterTools registers all GUI tools with the MCP server.
 func (s *Subsystem) RegisterTools(server *mcp.Server) {
 	s.registerWebviewTools(server)
 	s.registerWindowTools(server)

pkg/mcp/tools_clipboard.go

@@ -3,8 +3,8 @@ package mcp
 
 import (
 	"context"
-	"fmt"
 
+	coreerr "forge.lthn.ai/core/go-log"
 	"forge.lthn.ai/core/gui/pkg/clipboard"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
@@ -23,7 +23,7 @@ func (s *Subsystem) clipboardRead(_ context.Context, _ *mcp.CallToolRequest, _ C
 	}
 	content, ok := result.(clipboard.ClipboardContent)
 	if !ok {
-		return nil, ClipboardReadOutput{}, fmt.Errorf("unexpected result type from clipboard read query")
+		return nil, ClipboardReadOutput{}, coreerr.E("mcp.clipboardRead", "unexpected result type", nil)
 	}
 	return nil, ClipboardReadOutput{Content: content.Text}, nil
 }
@@ -44,7 +44,7 @@ func (s *Subsystem) clipboardWrite(_ context.Context, _ *mcp.CallToolRequest, in
 	}
 	success, ok := result.(bool)
 	if !ok {
-		return nil, ClipboardWriteOutput{}, fmt.Errorf("unexpected result type from clipboard write task")
+		return nil, ClipboardWriteOutput{}, coreerr.E("mcp.clipboardWrite", "unexpected result type", nil)
 	}
 	return nil, ClipboardWriteOutput{Success: success}, nil
 }
@@ -63,7 +63,7 @@ func (s *Subsystem) clipboardHas(_ context.Context, _ *mcp.CallToolRequest, _ Cl
 	}
 	content, ok := result.(clipboard.ClipboardContent)
 	if !ok {
-		return nil, ClipboardHasOutput{}, fmt.Errorf("unexpected result type from clipboard has query")
+		return nil, ClipboardHasOutput{}, coreerr.E("mcp.clipboardHas", "unexpected result type", nil)
 	}
 	return nil, ClipboardHasOutput{HasContent: content.HasContent}, nil
 }
@@ -82,7 +82,7 @@ func (s *Subsystem) clipboardClear(_ context.Context, _ *mcp.CallToolRequest, _
 	}
 	success, ok := result.(bool)
 	if !ok {
-		return nil, ClipboardClearOutput{}, fmt.Errorf("unexpected result type from clipboard clear task")
+		return nil, ClipboardClearOutput{}, coreerr.E("mcp.clipboardClear", "unexpected result type", nil)
 	}
 	return nil, ClipboardClearOutput{Success: success}, nil
 }

pkg/mcp/tools_contextmenu.go

@@ -4,8 +4,8 @@ package mcp
 import (
 	"context"
 	"encoding/json"
-	"fmt"
 
+	coreerr "forge.lthn.ai/core/go-log"
 	"forge.lthn.ai/core/gui/pkg/contextmenu"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
@@ -27,11 +27,11 @@ func (s *Subsystem) contextMenuAdd(_ context.Context, _ *mcp.CallToolRequest, in
 	// Convert map[string]any to ContextMenuDef via JSON round-trip
 	menuJSON, err := json.Marshal(input.Menu)
 	if err != nil {
-		return nil, ContextMenuAddOutput{}, fmt.Errorf("failed to marshal menu definition: %w", err)
+		return nil, ContextMenuAddOutput{}, coreerr.E("mcp.contextMenuAdd", "failed to marshal menu definition", err)
 	}
 	var menuDef contextmenu.ContextMenuDef
 	if err := json.Unmarshal(menuJSON, &menuDef); err != nil {
-		return nil, ContextMenuAddOutput{}, fmt.Errorf("failed to unmarshal menu definition: %w", err)
+		return nil, ContextMenuAddOutput{}, coreerr.E("mcp.contextMenuAdd", "failed to unmarshal menu definition", err)
 	}
 	_, _, err = s.core.PERFORM(contextmenu.TaskAdd{Name: input.Name, Menu: menuDef})
 	if err != nil {
@@ -73,7 +73,7 @@ func (s *Subsystem) contextMenuGet(_ context.Context, _ *mcp.CallToolRequest, in
 	}
 	menu, ok := result.(*contextmenu.ContextMenuDef)
 	if !ok {
-		return nil, ContextMenuGetOutput{}, fmt.Errorf("unexpected result type from context menu get query")
+		return nil, ContextMenuGetOutput{}, coreerr.E("mcp.contextMenuGet", "unexpected result type", nil)
 	}
 	if menu == nil {
 		return nil, ContextMenuGetOutput{}, nil
@@ -81,11 +81,11 @@ func (s *Subsystem) contextMenuGet(_ context.Context, _ *mcp.CallToolRequest, in
 	// Convert to map[string]any via JSON round-trip to avoid cyclic type in schema
 	menuJSON, err := json.Marshal(menu)
 	if err != nil {
-		return nil, ContextMenuGetOutput{}, fmt.Errorf("failed to marshal context menu: %w", err)
+		return nil, ContextMenuGetOutput{}, coreerr.E("mcp.contextMenuGet", "failed to marshal context menu", err)
 	}
 	var menuMap map[string]any
 	if err := json.Unmarshal(menuJSON, &menuMap); err != nil {
-		return nil, ContextMenuGetOutput{}, fmt.Errorf("failed to unmarshal context menu: %w", err)
+		return nil, ContextMenuGetOutput{}, coreerr.E("mcp.contextMenuGet", "failed to unmarshal context menu", err)
 	}
 	return nil, ContextMenuGetOutput{Menu: menuMap}, nil
 }
@@ -104,16 +104,16 @@ func (s *Subsystem) contextMenuList(_ context.Context, _ *mcp.CallToolRequest, _
 	}
 	menus, ok := result.(map[string]contextmenu.ContextMenuDef)
 	if !ok {
-		return nil, ContextMenuListOutput{}, fmt.Errorf("unexpected result type from context menu list query")
+		return nil, ContextMenuListOutput{}, coreerr.E("mcp.contextMenuList", "unexpected result type", nil)
 	}
 	// Convert to map[string]any via JSON round-trip to avoid cyclic type in schema
 	menusJSON, err := json.Marshal(menus)
 	if err != nil {
-		return nil, ContextMenuListOutput{}, fmt.Errorf("failed to marshal context menus: %w", err)
+		return nil, ContextMenuListOutput{}, coreerr.E("mcp.contextMenuList", "failed to marshal context menus", err)
 	}
 	var menusMap map[string]any
 	if err := json.Unmarshal(menusJSON, &menusMap); err != nil {
-		return nil, ContextMenuListOutput{}, fmt.Errorf("failed to unmarshal context menus: %w", err)
+		return nil, ContextMenuListOutput{}, coreerr.E("mcp.contextMenuList", "failed to unmarshal context menus", err)
 	}
 	return nil, ContextMenuListOutput{Menus: menusMap}, nil
 }

pkg/mcp/tools_dialog.go

@@ -3,8 +3,8 @@ package mcp
 
 import (
 	"context"
-	"fmt"
 
+	coreerr "forge.lthn.ai/core/go-log"
 	"forge.lthn.ai/core/gui/pkg/dialog"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
@@ -22,7 +22,7 @@ type DialogOpenFileOutput struct {
 }
 
 func (s *Subsystem) dialogOpenFile(_ context.Context, _ *mcp.CallToolRequest, input DialogOpenFileInput) (*mcp.CallToolResult, DialogOpenFileOutput, error) {
-	result, _, err := s.core.PERFORM(dialog.TaskOpenFile{Opts: dialog.OpenFileOptions{
+	result, _, err := s.core.PERFORM(dialog.TaskOpenFile{Options: dialog.OpenFileOptions{
 		Title:         input.Title,
 		Directory:     input.Directory,
 		Filters:       input.Filters,
@@ -33,7 +33,7 @@ func (s *Subsystem) dialogOpenFile(_ context.Context, _ *mcp.CallToolRequest, in
 	}
 	paths, ok := result.([]string)
 	if !ok {
-		return nil, DialogOpenFileOutput{}, fmt.Errorf("unexpected result type from open file dialog")
+		return nil, DialogOpenFileOutput{}, coreerr.E("mcp.dialogOpenFile", "unexpected result type", nil)
 	}
 	return nil, DialogOpenFileOutput{Paths: paths}, nil
 }
@@ -51,7 +51,7 @@ type DialogSaveFileOutput struct {
 }
 
 func (s *Subsystem) dialogSaveFile(_ context.Context, _ *mcp.CallToolRequest, input DialogSaveFileInput) (*mcp.CallToolResult, DialogSaveFileOutput, error) {
-	result, _, err := s.core.PERFORM(dialog.TaskSaveFile{Opts: dialog.SaveFileOptions{
+	result, _, err := s.core.PERFORM(dialog.TaskSaveFile{Options: dialog.SaveFileOptions{
 		Title:     input.Title,
 		Directory: input.Directory,
 		Filename:  input.Filename,
@@ -62,7 +62,7 @@ func (s *Subsystem) dialogSaveFile(_ context.Context, _ *mcp.CallToolRequest, in
 	}
 	path, ok := result.(string)
 	if !ok {
-		return nil, DialogSaveFileOutput{}, fmt.Errorf("unexpected result type from save file dialog")
+		return nil, DialogSaveFileOutput{}, coreerr.E("mcp.dialogSaveFile", "unexpected result type", nil)
 	}
 	return nil, DialogSaveFileOutput{Path: path}, nil
 }
@@ -78,7 +78,7 @@ type DialogOpenDirectoryOutput struct {
 }
 
 func (s *Subsystem) dialogOpenDirectory(_ context.Context, _ *mcp.CallToolRequest, input DialogOpenDirectoryInput) (*mcp.CallToolResult, DialogOpenDirectoryOutput, error) {
-	result, _, err := s.core.PERFORM(dialog.TaskOpenDirectory{Opts: dialog.OpenDirectoryOptions{
+	result, _, err := s.core.PERFORM(dialog.TaskOpenDirectory{Options: dialog.OpenDirectoryOptions{
 		Title:     input.Title,
 		Directory: input.Directory,
 	}})
@@ -87,7 +87,7 @@ func (s *Subsystem) dialogOpenDirectory(_ context.Context, _ *mcp.CallToolReques
 	}
 	path, ok := result.(string)
 	if !ok {
-		return nil, DialogOpenDirectoryOutput{}, fmt.Errorf("unexpected result type from open directory dialog")
+		return nil, DialogOpenDirectoryOutput{}, coreerr.E("mcp.dialogOpenDirectory", "unexpected result type", nil)
 	}
 	return nil, DialogOpenDirectoryOutput{Path: path}, nil
 }
@@ -104,7 +104,7 @@ type DialogConfirmOutput struct {
 }
 
 func (s *Subsystem) dialogConfirm(_ context.Context, _ *mcp.CallToolRequest, input DialogConfirmInput) (*mcp.CallToolResult, DialogConfirmOutput, error) {
-	result, _, err := s.core.PERFORM(dialog.TaskMessageDialog{Opts: dialog.MessageDialogOptions{
+	result, _, err := s.core.PERFORM(dialog.TaskMessageDialog{Options: dialog.MessageDialogOptions{
 		Type:    dialog.DialogQuestion,
 		Title:   input.Title,
 		Message: input.Message,
@@ -115,7 +115,7 @@ func (s *Subsystem) dialogConfirm(_ context.Context, _ *mcp.CallToolRequest, inp
 	}
 	button, ok := result.(string)
 	if !ok {
-		return nil, DialogConfirmOutput{}, fmt.Errorf("unexpected result type from confirm dialog")
+		return nil, DialogConfirmOutput{}, coreerr.E("mcp.dialogConfirm", "unexpected result type", nil)
 	}
 	return nil, DialogConfirmOutput{Button: button}, nil
 }
@@ -131,7 +131,7 @@ type DialogPromptOutput struct {
 }
 
 func (s *Subsystem) dialogPrompt(_ context.Context, _ *mcp.CallToolRequest, input DialogPromptInput) (*mcp.CallToolResult, DialogPromptOutput, error) {
-	result, _, err := s.core.PERFORM(dialog.TaskMessageDialog{Opts: dialog.MessageDialogOptions{
+	result, _, err := s.core.PERFORM(dialog.TaskMessageDialog{Options: dialog.MessageDialogOptions{
 		Type:    dialog.DialogInfo,
 		Title:   input.Title,
 		Message: input.Message,
@@ -142,7 +142,7 @@ func (s *Subsystem) dialogPrompt(_ context.Context, _ *mcp.CallToolRequest, inpu
 	}
 	button, ok := result.(string)
 	if !ok {
-		return nil, DialogPromptOutput{}, fmt.Errorf("unexpected result type from prompt dialog")
+		return nil, DialogPromptOutput{}, coreerr.E("mcp.dialogPrompt", "unexpected result type", nil)
 	}
 	return nil, DialogPromptOutput{Button: button}, nil
 }

pkg/mcp/tools_environment.go

@@ -3,8 +3,8 @@ package mcp
 
 import (
 	"context"
-	"fmt"
 
+	coreerr "forge.lthn.ai/core/go-log"
 	"forge.lthn.ai/core/gui/pkg/environment"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
@@ -23,7 +23,7 @@ func (s *Subsystem) themeGet(_ context.Context, _ *mcp.CallToolRequest, _ ThemeG
 	}
 	theme, ok := result.(environment.ThemeInfo)
 	if !ok {
-		return nil, ThemeGetOutput{}, fmt.Errorf("unexpected result type from theme query")
+		return nil, ThemeGetOutput{}, coreerr.E("mcp.themeGet", "unexpected result type", nil)
 	}
 	return nil, ThemeGetOutput{Theme: theme}, nil
 }
@@ -42,7 +42,7 @@ func (s *Subsystem) themeSystem(_ context.Context, _ *mcp.CallToolRequest, _ The
 	}
 	info, ok := result.(environment.EnvironmentInfo)
 	if !ok {
-		return nil, ThemeSystemOutput{}, fmt.Errorf("unexpected result type from environment info query")
+		return nil, ThemeSystemOutput{}, coreerr.E("mcp.themeSystem", "unexpected result type", nil)
 	}
 	return nil, ThemeSystemOutput{Info: info}, nil
 }

pkg/mcp/tools_layout.go

@@ -3,8 +3,8 @@ package mcp
 
 import (
 	"context"
-	"fmt"
 
+	coreerr "forge.lthn.ai/core/go-log"
 	"forge.lthn.ai/core/gui/pkg/window"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
@@ -57,7 +57,7 @@ func (s *Subsystem) layoutList(_ context.Context, _ *mcp.CallToolRequest, _ Layo
 	}
 	layouts, ok := result.([]window.LayoutInfo)
 	if !ok {
-		return nil, LayoutListOutput{}, fmt.Errorf("unexpected result type from layout list query")
+		return nil, LayoutListOutput{}, coreerr.E("mcp.layoutList", "unexpected result type", nil)
 	}
 	return nil, LayoutListOutput{Layouts: layouts}, nil
 }
@@ -95,7 +95,7 @@ func (s *Subsystem) layoutGet(_ context.Context, _ *mcp.CallToolRequest, input L
 	}
 	layout, ok := result.(*window.Layout)
 	if !ok {
-		return nil, LayoutGetOutput{}, fmt.Errorf("unexpected result type from layout get query")
+		return nil, LayoutGetOutput{}, coreerr.E("mcp.layoutGet", "unexpected result type", nil)
 	}
 	return nil, LayoutGetOutput{Layout: layout}, nil
 }
@@ -136,6 +136,43 @@ func (s *Subsystem) layoutSnap(_ context.Context, _ *mcp.CallToolRequest, input
 	return nil, LayoutSnapOutput{Success: true}, nil
 }
 
+// --- layout_stack ---
+
+type LayoutStackInput struct {
+	Windows []string `json:"windows,omitempty"`
+	OffsetX int      `json:"offsetX"`
+	OffsetY int      `json:"offsetY"`
+}
+type LayoutStackOutput struct {
+	Success bool `json:"success"`
+}
+
+func (s *Subsystem) layoutStack(_ context.Context, _ *mcp.CallToolRequest, input LayoutStackInput) (*mcp.CallToolResult, LayoutStackOutput, error) {
+	_, _, err := s.core.PERFORM(window.TaskStackWindows{Windows: input.Windows, OffsetX: input.OffsetX, OffsetY: input.OffsetY})
+	if err != nil {
+		return nil, LayoutStackOutput{}, err
+	}
+	return nil, LayoutStackOutput{Success: true}, nil
+}
+
+// --- layout_workflow ---
+
+type LayoutWorkflowInput struct {
+	Workflow string   `json:"workflow"`
+	Windows  []string `json:"windows,omitempty"`
+}
+type LayoutWorkflowOutput struct {
+	Success bool `json:"success"`
+}
+
+func (s *Subsystem) layoutWorkflow(_ context.Context, _ *mcp.CallToolRequest, input LayoutWorkflowInput) (*mcp.CallToolResult, LayoutWorkflowOutput, error) {
+	_, _, err := s.core.PERFORM(window.TaskApplyWorkflow{Workflow: input.Workflow, Windows: input.Windows})
+	if err != nil {
+		return nil, LayoutWorkflowOutput{}, err
+	}
+	return nil, LayoutWorkflowOutput{Success: true}, nil
+}
+
 // --- Registration ---
 
 func (s *Subsystem) registerLayoutTools(server *mcp.Server) {
@@ -146,4 +183,6 @@ func (s *Subsystem) registerLayoutTools(server *mcp.Server) {
 	mcp.AddTool(server, &mcp.Tool{Name: "layout_get", Description: "Get a specific layout by name"}, s.layoutGet)
 	mcp.AddTool(server, &mcp.Tool{Name: "layout_tile", Description: "Tile windows in a grid arrangement"}, s.layoutTile)
 	mcp.AddTool(server, &mcp.Tool{Name: "layout_snap", Description: "Snap a window to a screen edge or corner"}, s.layoutSnap)
+	mcp.AddTool(server, &mcp.Tool{Name: "layout_stack", Description: "Stack windows in a cascade pattern"}, s.layoutStack)
+	mcp.AddTool(server, &mcp.Tool{Name: "layout_workflow", Description: "Apply a preset workflow layout"}, s.layoutWorkflow)
 }

pkg/mcp/tools_notification.go

@@ -3,8 +3,8 @@ package mcp
 
 import (
 	"context"
-	"fmt"
 
+	coreerr "forge.lthn.ai/core/go-log"
 	"forge.lthn.ai/core/gui/pkg/notification"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
@@ -21,7 +21,7 @@ type NotificationShowOutput struct {
 }
 
 func (s *Subsystem) notificationShow(_ context.Context, _ *mcp.CallToolRequest, input NotificationShowInput) (*mcp.CallToolResult, NotificationShowOutput, error) {
-	_, _, err := s.core.PERFORM(notification.TaskSend{Opts: notification.NotificationOptions{
+	_, _, err := s.core.PERFORM(notification.TaskSend{Options: notification.NotificationOptions{
 		Title:    input.Title,
 		Message:  input.Message,
 		Subtitle: input.Subtitle,
@@ -46,7 +46,7 @@ func (s *Subsystem) notificationPermissionRequest(_ context.Context, _ *mcp.Call
 	}
 	granted, ok := result.(bool)
 	if !ok {
-		return nil, NotificationPermissionRequestOutput{}, fmt.Errorf("unexpected result type from notification permission request")
+		return nil, NotificationPermissionRequestOutput{}, coreerr.E("mcp.notificationPermissionRequest", "unexpected result type", nil)
 	}
 	return nil, NotificationPermissionRequestOutput{Granted: granted}, nil
 }
@@ -65,7 +65,7 @@ func (s *Subsystem) notificationPermissionCheck(_ context.Context, _ *mcp.CallTo
 	}
 	status, ok := result.(notification.PermissionStatus)
 	if !ok {
-		return nil, NotificationPermissionCheckOutput{}, fmt.Errorf("unexpected result type from notification permission check")
+		return nil, NotificationPermissionCheckOutput{}, coreerr.E("mcp.notificationPermissionCheck", "unexpected result type", nil)
 	}
 	return nil, NotificationPermissionCheckOutput{Granted: status.Granted}, nil
 }

pkg/mcp/tools_screen.go

@@ -3,9 +3,10 @@ package mcp
 
 import (
 	"context"
-	"fmt"
 
+	coreerr "forge.lthn.ai/core/go-log"
 	"forge.lthn.ai/core/gui/pkg/screen"
+	"forge.lthn.ai/core/gui/pkg/window"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
@@ -23,7 +24,7 @@ func (s *Subsystem) screenList(_ context.Context, _ *mcp.CallToolRequest, _ Scre
 	}
 	screens, ok := result.([]screen.Screen)
 	if !ok {
-		return nil, ScreenListOutput{}, fmt.Errorf("unexpected result type from screen list query")
+		return nil, ScreenListOutput{}, coreerr.E("mcp.screenList", "unexpected result type", nil)
 	}
 	return nil, ScreenListOutput{Screens: screens}, nil
 }
@@ -44,7 +45,7 @@ func (s *Subsystem) screenGet(_ context.Context, _ *mcp.CallToolRequest, input S
 	}
 	scr, ok := result.(*screen.Screen)
 	if !ok {
-		return nil, ScreenGetOutput{}, fmt.Errorf("unexpected result type from screen get query")
+		return nil, ScreenGetOutput{}, coreerr.E("mcp.screenGet", "unexpected result type", nil)
 	}
 	return nil, ScreenGetOutput{Screen: scr}, nil
 }
@@ -63,7 +64,7 @@ func (s *Subsystem) screenPrimary(_ context.Context, _ *mcp.CallToolRequest, _ S
 	}
 	scr, ok := result.(*screen.Screen)
 	if !ok {
-		return nil, ScreenPrimaryOutput{}, fmt.Errorf("unexpected result type from screen primary query")
+		return nil, ScreenPrimaryOutput{}, coreerr.E("mcp.screenPrimary", "unexpected result type", nil)
 	}
 	return nil, ScreenPrimaryOutput{Screen: scr}, nil
 }
@@ -85,7 +86,7 @@ func (s *Subsystem) screenAtPoint(_ context.Context, _ *mcp.CallToolRequest, inp
 	}
 	scr, ok := result.(*screen.Screen)
 	if !ok {
-		return nil, ScreenAtPointOutput{}, fmt.Errorf("unexpected result type from screen at point query")
+		return nil, ScreenAtPointOutput{}, coreerr.E("mcp.screenAtPoint", "unexpected result type", nil)
 	}
 	return nil, ScreenAtPointOutput{Screen: scr}, nil
 }
@@ -104,11 +105,39 @@ func (s *Subsystem) screenWorkAreas(_ context.Context, _ *mcp.CallToolRequest, _
 	}
 	areas, ok := result.([]screen.Rect)
 	if !ok {
-		return nil, ScreenWorkAreasOutput{}, fmt.Errorf("unexpected result type from screen work areas query")
+		return nil, ScreenWorkAreasOutput{}, coreerr.E("mcp.screenWorkAreas", "unexpected result type", nil)
 	}
 	return nil, ScreenWorkAreasOutput{WorkAreas: areas}, nil
 }
 
+// --- screen_for_window ---
+
+type ScreenForWindowInput struct {
+	Name string `json:"name"`
+}
+type ScreenForWindowOutput struct {
+	Screen *screen.Screen `json:"screen"`
+}
+
+func (s *Subsystem) screenForWindow(_ context.Context, _ *mcp.CallToolRequest, input ScreenForWindowInput) (*mcp.CallToolResult, ScreenForWindowOutput, error) {
+	result, _, err := s.core.QUERY(window.QueryWindowByName{Name: input.Name})
+	if err != nil {
+		return nil, ScreenForWindowOutput{}, err
+	}
+	info, _ := result.(*window.WindowInfo)
+	if info == nil {
+		return nil, ScreenForWindowOutput{}, nil
+	}
+	centerX := info.X + info.Width/2
+	centerY := info.Y + info.Height/2
+	screenResult, _, err := s.core.QUERY(screen.QueryAtPoint{X: centerX, Y: centerY})
+	if err != nil {
+		return nil, ScreenForWindowOutput{}, err
+	}
+	scr, _ := screenResult.(*screen.Screen)
+	return nil, ScreenForWindowOutput{Screen: scr}, nil
+}
+
 // --- Registration ---
 
 func (s *Subsystem) registerScreenTools(server *mcp.Server) {
@@ -117,4 +146,5 @@ func (s *Subsystem) registerScreenTools(server *mcp.Server) {
 	mcp.AddTool(server, &mcp.Tool{Name: "screen_primary", Description: "Get the primary screen"}, s.screenPrimary)
 	mcp.AddTool(server, &mcp.Tool{Name: "screen_at_point", Description: "Get the screen at a specific point"}, s.screenAtPoint)
 	mcp.AddTool(server, &mcp.Tool{Name: "screen_work_areas", Description: "Get work areas for all screens"}, s.screenWorkAreas)
+	mcp.AddTool(server, &mcp.Tool{Name: "screen_for_window", Description: "Get the screen containing a window"}, s.screenForWindow)
 }

pkg/mcp/tools_tray.go

@@ -3,8 +3,8 @@ package mcp
 
 import (
 	"context"
-	"fmt"
 
+	coreerr "forge.lthn.ai/core/go-log"
 	"forge.lthn.ai/core/gui/pkg/systray"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
@@ -70,7 +70,7 @@ func (s *Subsystem) trayInfo(_ context.Context, _ *mcp.CallToolRequest, _ TrayIn
 	}
 	config, ok := result.(map[string]any)
 	if !ok {
-		return nil, TrayInfoOutput{}, fmt.Errorf("unexpected result type from tray config query")
+		return nil, TrayInfoOutput{}, coreerr.E("mcp.trayInfo", "unexpected result type", nil)
 	}
 	return nil, TrayInfoOutput{Config: config}, nil
 }

pkg/mcp/tools_webview.go

@@ -3,8 +3,8 @@ package mcp
 
 import (
 	"context"
-	"fmt"
 
+	coreerr "forge.lthn.ai/core/go-log"
 	"forge.lthn.ai/core/gui/pkg/webview"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
@@ -105,7 +105,7 @@ func (s *Subsystem) webviewScreenshot(_ context.Context, _ *mcp.CallToolRequest,
 	}
 	sr, ok := result.(webview.ScreenshotResult)
 	if !ok {
-		return nil, WebviewScreenshotOutput{}, fmt.Errorf("unexpected result type from webview screenshot")
+		return nil, WebviewScreenshotOutput{}, coreerr.E("mcp.webviewScreenshot", "unexpected result type", nil)
 	}
 	return nil, WebviewScreenshotOutput{Base64: sr.Base64, MimeType: sr.MimeType}, nil
 }
@@ -248,7 +248,7 @@ func (s *Subsystem) webviewConsole(_ context.Context, _ *mcp.CallToolRequest, in
 	}
 	msgs, ok := result.([]webview.ConsoleMessage)
 	if !ok {
-		return nil, WebviewConsoleOutput{}, fmt.Errorf("unexpected result type from webview console query")
+		return nil, WebviewConsoleOutput{}, coreerr.E("mcp.webviewConsole", "unexpected result type", nil)
 	}
 	return nil, WebviewConsoleOutput{Messages: msgs}, nil
 }
@@ -289,7 +289,7 @@ func (s *Subsystem) webviewQuery(_ context.Context, _ *mcp.CallToolRequest, inpu
 	}
 	el, ok := result.(*webview.ElementInfo)
 	if !ok {
-		return nil, WebviewQueryOutput{}, fmt.Errorf("unexpected result type from webview query")
+		return nil, WebviewQueryOutput{}, coreerr.E("mcp.webviewQuery", "unexpected result type", nil)
 	}
 	return nil, WebviewQueryOutput{Element: el}, nil
 }
@@ -312,7 +312,7 @@ func (s *Subsystem) webviewQueryAll(_ context.Context, _ *mcp.CallToolRequest, i
 	}
 	els, ok := result.([]*webview.ElementInfo)
 	if !ok {
-		return nil, WebviewQueryAllOutput{}, fmt.Errorf("unexpected result type from webview query all")
+		return nil, WebviewQueryAllOutput{}, coreerr.E("mcp.webviewQueryAll", "unexpected result type", nil)
 	}
 	return nil, WebviewQueryAllOutput{Elements: els}, nil
 }
@@ -335,7 +335,7 @@ func (s *Subsystem) webviewDOMTree(_ context.Context, _ *mcp.CallToolRequest, in
 	}
 	html, ok := result.(string)
 	if !ok {
-		return nil, WebviewDOMTreeOutput{}, fmt.Errorf("unexpected result type from webview DOM tree query")
+		return nil, WebviewDOMTreeOutput{}, coreerr.E("mcp.webviewDOMTree", "unexpected result type", nil)
 	}
 	return nil, WebviewDOMTreeOutput{HTML: html}, nil
 }
@@ -357,7 +357,7 @@ func (s *Subsystem) webviewURL(_ context.Context, _ *mcp.CallToolRequest, input
 	}
 	url, ok := result.(string)
 	if !ok {
-		return nil, WebviewURLOutput{}, fmt.Errorf("unexpected result type from webview URL query")
+		return nil, WebviewURLOutput{}, coreerr.E("mcp.webviewURL", "unexpected result type", nil)
 	}
 	return nil, WebviewURLOutput{URL: url}, nil
 }
@@ -379,7 +379,7 @@ func (s *Subsystem) webviewTitle(_ context.Context, _ *mcp.CallToolRequest, inpu
 	}
 	title, ok := result.(string)
 	if !ok {
-		return nil, WebviewTitleOutput{}, fmt.Errorf("unexpected result type from webview title query")
+		return nil, WebviewTitleOutput{}, coreerr.E("mcp.webviewTitle", "unexpected result type", nil)
 	}
 	return nil, WebviewTitleOutput{Title: title}, nil
 }

pkg/mcp/tools_window.go

@@ -3,8 +3,8 @@ package mcp
 
 import (
 	"context"
-	"fmt"
 
+	coreerr "forge.lthn.ai/core/go-log"
 	"forge.lthn.ai/core/gui/pkg/window"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
@@ -23,7 +23,7 @@ func (s *Subsystem) windowList(_ context.Context, _ *mcp.CallToolRequest, _ Wind
 	}
 	windows, ok := result.([]window.WindowInfo)
 	if !ok {
-		return nil, WindowListOutput{}, fmt.Errorf("unexpected result type from window list query")
+		return nil, WindowListOutput{}, coreerr.E("mcp.windowList", "unexpected result type", nil)
 	}
 	return nil, WindowListOutput{Windows: windows}, nil
 }
@@ -44,7 +44,7 @@ func (s *Subsystem) windowGet(_ context.Context, _ *mcp.CallToolRequest, input W
 	}
 	info, ok := result.(*window.WindowInfo)
 	if !ok {
-		return nil, WindowGetOutput{}, fmt.Errorf("unexpected result type from window get query")
+		return nil, WindowGetOutput{}, coreerr.E("mcp.windowGet", "unexpected result type", nil)
 	}
 	return nil, WindowGetOutput{Window: info}, nil
 }
@@ -63,7 +63,7 @@ func (s *Subsystem) windowFocused(_ context.Context, _ *mcp.CallToolRequest, _ W
 	}
 	windows, ok := result.([]window.WindowInfo)
 	if !ok {
-		return nil, WindowFocusedOutput{}, fmt.Errorf("unexpected result type from window list query")
+		return nil, WindowFocusedOutput{}, coreerr.E("mcp.windowFocused", "unexpected result type", nil)
 	}
 	for _, w := range windows {
 		if w.Focused {
@@ -89,28 +89,23 @@ type WindowCreateOutput struct {
 }
 
 func (s *Subsystem) windowCreate(_ context.Context, _ *mcp.CallToolRequest, input WindowCreateInput) (*mcp.CallToolResult, WindowCreateOutput, error) {
-	opts := []window.WindowOption{
-		window.WithName(input.Name),
-	}
-	if input.Title != "" {
-		opts = append(opts, window.WithTitle(input.Title))
-	}
-	if input.URL != "" {
-		opts = append(opts, window.WithURL(input.URL))
-	}
-	if input.Width > 0 || input.Height > 0 {
-		opts = append(opts, window.WithSize(input.Width, input.Height))
-	}
-	if input.X != 0 || input.Y != 0 {
-		opts = append(opts, window.WithPosition(input.X, input.Y))
-	}
-	result, _, err := s.core.PERFORM(window.TaskOpenWindow{Opts: opts})
+	result, _, err := s.core.PERFORM(window.TaskOpenWindow{
+		Window: &window.Window{
+			Name:   input.Name,
+			Title:  input.Title,
+			URL:    input.URL,
+			Width:  input.Width,
+			Height: input.Height,
+			X:      input.X,
+			Y:      input.Y,
+		},
+	})
 	if err != nil {
 		return nil, WindowCreateOutput{}, err
 	}
 	info, ok := result.(window.WindowInfo)
 	if !ok {
-		return nil, WindowCreateOutput{}, fmt.Errorf("unexpected result type from window create task")
+		return nil, WindowCreateOutput{}, coreerr.E("mcp.windowCreate", "unexpected result type", nil)
 	}
 	return nil, WindowCreateOutput{Window: info}, nil
 }
@@ -163,7 +158,7 @@ type WindowSizeOutput struct {
 }
 
 func (s *Subsystem) windowSize(_ context.Context, _ *mcp.CallToolRequest, input WindowSizeInput) (*mcp.CallToolResult, WindowSizeOutput, error) {
-	_, _, err := s.core.PERFORM(window.TaskSetSize{Name: input.Name, W: input.Width, H: input.Height})
+	_, _, err := s.core.PERFORM(window.TaskSetSize{Name: input.Name, Width: input.Width, Height: input.Height})
 	if err != nil {
 		return nil, WindowSizeOutput{}, err
 	}
@@ -188,7 +183,7 @@ func (s *Subsystem) windowBounds(_ context.Context, _ *mcp.CallToolRequest, inpu
 	if err != nil {
 		return nil, WindowBoundsOutput{}, err
 	}
-	_, _, err = s.core.PERFORM(window.TaskSetSize{Name: input.Name, W: input.Width, H: input.Height})
+	_, _, err = s.core.PERFORM(window.TaskSetSize{Name: input.Name, Width: input.Width, Height: input.Height})
 	if err != nil {
 		return nil, WindowBoundsOutput{}, err
 	}
@@ -281,6 +276,27 @@ func (s *Subsystem) windowTitle(_ context.Context, _ *mcp.CallToolRequest, input
 	return nil, WindowTitleOutput{Success: true}, nil
 }
 
+// --- window_title_get ---
+
+type WindowTitleGetInput struct {
+	Name string `json:"name"`
+}
+type WindowTitleGetOutput struct {
+	Title string `json:"title"`
+}
+
+func (s *Subsystem) windowTitleGet(_ context.Context, _ *mcp.CallToolRequest, input WindowTitleGetInput) (*mcp.CallToolResult, WindowTitleGetOutput, error) {
+	result, _, err := s.core.QUERY(window.QueryWindowByName{Name: input.Name})
+	if err != nil {
+		return nil, WindowTitleGetOutput{}, err
+	}
+	info, _ := result.(*window.WindowInfo)
+	if info == nil {
+		return nil, WindowTitleGetOutput{}, nil
+	}
+	return nil, WindowTitleGetOutput{Title: info.Title}, nil
+}
+
 // --- window_visibility ---
 
 type WindowVisibilityInput struct {
@@ -299,6 +315,47 @@ func (s *Subsystem) windowVisibility(_ context.Context, _ *mcp.CallToolRequest,
 	return nil, WindowVisibilityOutput{Success: true}, nil
 }
 
+// --- window_always_on_top ---
+
+type WindowAlwaysOnTopInput struct {
+	Name        string `json:"name"`
+	AlwaysOnTop bool   `json:"alwaysOnTop"`
+}
+type WindowAlwaysOnTopOutput struct {
+	Success bool `json:"success"`
+}
+
+func (s *Subsystem) windowAlwaysOnTop(_ context.Context, _ *mcp.CallToolRequest, input WindowAlwaysOnTopInput) (*mcp.CallToolResult, WindowAlwaysOnTopOutput, error) {
+	_, _, err := s.core.PERFORM(window.TaskSetAlwaysOnTop{Name: input.Name, AlwaysOnTop: input.AlwaysOnTop})
+	if err != nil {
+		return nil, WindowAlwaysOnTopOutput{}, err
+	}
+	return nil, WindowAlwaysOnTopOutput{Success: true}, nil
+}
+
+// --- window_background_colour ---
+
+type WindowBackgroundColourInput struct {
+	Name  string `json:"name"`
+	Red   uint8  `json:"red"`
+	Green uint8  `json:"green"`
+	Blue  uint8  `json:"blue"`
+	Alpha uint8  `json:"alpha"`
+}
+type WindowBackgroundColourOutput struct {
+	Success bool `json:"success"`
+}
+
+func (s *Subsystem) windowBackgroundColour(_ context.Context, _ *mcp.CallToolRequest, input WindowBackgroundColourInput) (*mcp.CallToolResult, WindowBackgroundColourOutput, error) {
+	_, _, err := s.core.PERFORM(window.TaskSetBackgroundColour{
+		Name: input.Name, Red: input.Red, Green: input.Green, Blue: input.Blue, Alpha: input.Alpha,
+	})
+	if err != nil {
+		return nil, WindowBackgroundColourOutput{}, err
+	}
+	return nil, WindowBackgroundColourOutput{Success: true}, nil
+}
+
 // --- window_fullscreen ---
 
 type WindowFullscreenInput struct {
@@ -333,6 +390,9 @@ func (s *Subsystem) registerWindowTools(server *mcp.Server) {
 	mcp.AddTool(server, &mcp.Tool{Name: "window_restore", Description: "Restore a maximised or minimised window"}, s.windowRestore)
 	mcp.AddTool(server, &mcp.Tool{Name: "window_focus", Description: "Bring a window to the front"}, s.windowFocus)
 	mcp.AddTool(server, &mcp.Tool{Name: "window_title", Description: "Set the title of a window"}, s.windowTitle)
+	mcp.AddTool(server, &mcp.Tool{Name: "window_title_get", Description: "Get the title of a window"}, s.windowTitleGet)
 	mcp.AddTool(server, &mcp.Tool{Name: "window_visibility", Description: "Show or hide a window"}, s.windowVisibility)
+	mcp.AddTool(server, &mcp.Tool{Name: "window_always_on_top", Description: "Pin a window above others"}, s.windowAlwaysOnTop)
+	mcp.AddTool(server, &mcp.Tool{Name: "window_background_colour", Description: "Set a window background colour"}, s.windowBackgroundColour)
 	mcp.AddTool(server, &mcp.Tool{Name: "window_fullscreen", Description: "Set a window to fullscreen mode"}, s.windowFullscreen)
 }

pkg/menu/menu.go

@@ -20,11 +20,13 @@ type Manager struct {
 }
 
 // NewManager creates a menu Manager.
+// menu.NewManager(menu.NewWailsPlatform(app)).SetApplicationMenu([]menu.MenuItem{{Label: "File"}})
 func NewManager(platform Platform) *Manager {
 	return &Manager{platform: platform}
 }
 
 // Build constructs a PlatformMenu from a tree of MenuItems.
+// menu.NewManager(menu.NewWailsPlatform(app)).Build([]menu.MenuItem{{Label: "File"}})
 func (m *Manager) Build(items []MenuItem) PlatformMenu {
 	menu := m.platform.NewMenu()
 	m.buildItems(menu, items)
@@ -60,6 +62,7 @@ func (m *Manager) buildItems(menu PlatformMenu, items []MenuItem) {
 }
 
 // SetApplicationMenu builds and sets the application menu.
+// menu.NewManager(menu.NewWailsPlatform(app)).SetApplicationMenu([]menu.MenuItem{{Label: "File"}})
 func (m *Manager) SetApplicationMenu(items []MenuItem) {
 	menu := m.Build(items)
 	m.platform.SetApplicationMenu(menu)

pkg/menu/messages.go

@@ -1,16 +1,9 @@
 package menu
 
-// QueryConfig requests this service's config section from the display orchestrator.
-// Result: map[string]any
 type QueryConfig struct{}
 
-// QueryGetAppMenu returns the current app menu item descriptors.
-// Result: []MenuItem
 type QueryGetAppMenu struct{}
 
-// TaskSetAppMenu sets the application menu. OnClick closures work because
-// core/go IPC is in-process (no serialisation boundary).
 type TaskSetAppMenu struct{ Items []MenuItem }
 
-// TaskSaveConfig persists this service's config section via the display orchestrator.
-type TaskSaveConfig struct{ Value map[string]any }
+type TaskSaveConfig struct{ Config map[string]any }

pkg/menu/register.go

@@ -2,7 +2,8 @@ package menu
 
 import "forge.lthn.ai/core/go/pkg/core"
 
-// Register creates a factory closure that captures the Platform adapter.
+// Register(p) binds the menu service to a Core instance.
+// core.WithService(menu.Register(wailsMenu))
 func Register(p Platform) func(*core.Core) (any, error) {
 	return func(c *core.Core) (any, error) {
 		return &Service{

pkg/menu/service.go

@@ -6,24 +6,21 @@ import (
 	"forge.lthn.ai/core/go/pkg/core"
 )
 
-// Options holds configuration for the menu service.
 type Options struct{}
 
-// Service is a core.Service managing application menus via IPC.
 type Service struct {
 	*core.ServiceRuntime[Options]
 	manager      *Manager
 	platform     Platform
-	items        []MenuItem // last-set menu items for QueryGetAppMenu
+	menuItems    []MenuItem
 	showDevTools bool
 }
 
-// OnStartup queries config and registers IPC handlers.
 func (s *Service) OnStartup(ctx context.Context) error {
-	cfg, handled, _ := s.Core().QUERY(QueryConfig{})
+	configValue, handled, _ := s.Core().QUERY(QueryConfig{})
 	if handled {
-		if mCfg, ok := cfg.(map[string]any); ok {
-			s.applyConfig(mCfg)
+		if menuConfig, ok := configValue.(map[string]any); ok {
+			s.applyConfig(menuConfig)
 		}
 	}
 	s.Core().RegisterQuery(s.handleQuery)
@@ -31,20 +28,18 @@ func (s *Service) OnStartup(ctx context.Context) error {
 	return nil
 }
 
-func (s *Service) applyConfig(cfg map[string]any) {
-	if v, ok := cfg["show_dev_tools"]; ok {
+func (s *Service) applyConfig(configData map[string]any) {
+	if v, ok := configData["show_dev_tools"]; ok {
 		if show, ok := v.(bool); ok {
 			s.showDevTools = show
 		}
 	}
 }
 
-// ShowDevTools returns whether developer tools menu items should be shown.
 func (s *Service) ShowDevTools() bool {
 	return s.showDevTools
 }
 
-// HandleIPCEvents is auto-discovered and registered by core.WithService.
 func (s *Service) HandleIPCEvents(c *core.Core, msg core.Message) error {
 	return nil
 }
@@ -52,7 +47,7 @@ func (s *Service) HandleIPCEvents(c *core.Core, msg core.Message) error {
 func (s *Service) handleQuery(c *core.Core, q core.Query) (any, bool, error) {
 	switch q.(type) {
 	case QueryGetAppMenu:
-		return s.items, true, nil
+		return s.menuItems, true, nil
 	default:
 		return nil, false, nil
 	}
@@ -61,7 +56,7 @@ func (s *Service) handleQuery(c *core.Core, q core.Query) (any, bool, error) {
 func (s *Service) handleTask(c *core.Core, t core.Task) (any, bool, error) {
 	switch t := t.(type) {
 	case TaskSetAppMenu:
-		s.items = t.Items
+		s.menuItems = t.Items
 		s.manager.SetApplicationMenu(t.Items)
 		return nil, true, nil
 	default:
@@ -69,7 +64,6 @@ func (s *Service) handleTask(c *core.Core, t core.Task) (any, bool, error) {
 	}
 }
 
-// Manager returns the underlying menu Manager.
 func (s *Service) Manager() *Manager {
 	return s.manager
 }

pkg/notification/messages.go

@@ -1,14 +1,13 @@
-// pkg/notification/messages.go
 package notification
 
-// QueryPermission checks notification authorisation. Result: PermissionStatus
+// QueryPermission returns current notification permission status. Result: PermissionStatus
 type QueryPermission struct{}
 
-// TaskSend sends a notification. Falls back to dialog if platform fails.
-type TaskSend struct{ Opts NotificationOptions }
+// TaskSend sends a native notification, falling back to dialog on failure.
+type TaskSend struct{ Options NotificationOptions }
 
-// TaskRequestPermission requests notification authorisation. Result: bool (granted)
+// TaskRequestPermission requests notification permission from the OS. Result: bool (granted)
 type TaskRequestPermission struct{}
 
-// ActionNotificationClicked is broadcast when a notification is clicked (future).
+// ActionNotificationClicked is broadcast when the user clicks a notification.
 type ActionNotificationClicked struct{ ID string }

pkg/notification/platform.go

@@ -3,7 +3,7 @@ package notification
 
 // Platform abstracts the native notification backend.
 type Platform interface {
-	Send(opts NotificationOptions) error
+	Send(options NotificationOptions) error
 	RequestPermission() (bool, error)
 	CheckPermission() (bool, error)
 }

pkg/notification/service.go

@@ -3,23 +3,20 @@ package notification
 
 import (
 	"context"
-	"fmt"
+	"strconv"
 	"time"
 
 	"forge.lthn.ai/core/go/pkg/core"
 	"forge.lthn.ai/core/gui/pkg/dialog"
 )
 
-// Options holds configuration for the notification service.
 type Options struct{}
 
-// Service is a core.Service managing notifications via IPC.
 type Service struct {
 	*core.ServiceRuntime[Options]
 	platform Platform
 }
 
-// Register creates a factory closure that captures the Platform adapter.
 func Register(p Platform) func(*core.Core) (any, error) {
 	return func(c *core.Core) (any, error) {
 		return &Service{
@@ -29,14 +26,12 @@ func Register(p Platform) func(*core.Core) (any, error) {
 	}
 }
 
-// OnStartup registers IPC handlers.
 func (s *Service) OnStartup(ctx context.Context) error {
 	s.Core().RegisterQuery(s.handleQuery)
 	s.Core().RegisterTask(s.handleTask)
 	return nil
 }
 
-// HandleIPCEvents is auto-discovered by core.WithService.
 func (s *Service) HandleIPCEvents(c *core.Core, msg core.Message) error {
 	return nil
 }
@@ -54,7 +49,7 @@ func (s *Service) handleQuery(c *core.Core, q core.Query) (any, bool, error) {
 func (s *Service) handleTask(c *core.Core, t core.Task) (any, bool, error) {
 	switch t := t.(type) {
 	case TaskSend:
-		return nil, true, s.send(t.Opts)
+		return nil, true, s.send(t.Options)
 	case TaskRequestPermission:
 		granted, err := s.platform.RequestPermission()
 		return granted, true, err
@@ -64,24 +59,24 @@ func (s *Service) handleTask(c *core.Core, t core.Task) (any, bool, error) {
 }
 
 // send attempts native notification, falls back to dialog via IPC.
-func (s *Service) send(opts NotificationOptions) error {
+func (s *Service) send(options NotificationOptions) error {
 	// Generate ID if not provided
-	if opts.ID == "" {
-		opts.ID = fmt.Sprintf("core-%d", time.Now().UnixNano())
+	if options.ID == "" {
+		options.ID = "core-" + strconv.FormatInt(time.Now().UnixNano(), 10)
 	}
 
-	if err := s.platform.Send(opts); err != nil {
+	if err := s.platform.Send(options); err != nil {
 		// Fallback: show as dialog via IPC
-		return s.fallbackDialog(opts)
+		return s.fallbackDialog(options)
 	}
 	return nil
 }
 
 // fallbackDialog shows a dialog via IPC when native notifications fail.
-func (s *Service) fallbackDialog(opts NotificationOptions) error {
+func (s *Service) fallbackDialog(options NotificationOptions) error {
 	// Map severity to dialog type
 	var dt dialog.DialogType
-	switch opts.Severity {
+	switch options.Severity {
 	case SeverityWarning:
 		dt = dialog.DialogWarning
 	case SeverityError:
@@ -90,15 +85,15 @@ func (s *Service) fallbackDialog(opts NotificationOptions) error {
 		dt = dialog.DialogInfo
 	}
 
-	msg := opts.Message
-	if opts.Subtitle != "" {
-		msg = opts.Subtitle + "\n\n" + msg
+	msg := options.Message
+	if options.Subtitle != "" {
+		msg = options.Subtitle + "\n\n" + msg
 	}
 
 	_, _, err := s.Core().PERFORM(dialog.TaskMessageDialog{
-		Opts: dialog.MessageDialogOptions{
+		Options: dialog.MessageDialogOptions{
 			Type:    dt,
-			Title:   opts.Title,
+			Title:   options.Title,
 			Message: msg,
 			Buttons: []string{"OK"},
 		},

pkg/notification/service_test.go

@@ -66,7 +66,7 @@ func TestRegister_Good(t *testing.T) {
 func TestTaskSend_Good(t *testing.T) {
 	mock, c := newTestService(t)
 	_, handled, err := c.PERFORM(TaskSend{
-		Opts: NotificationOptions{Title: "Test", Message: "Hello"},
+		Options: NotificationOptions{Title: "Test", Message: "Hello"},
 	})
 	require.NoError(t, err)
 	assert.True(t, handled)
@@ -87,7 +87,7 @@ func TestTaskSend_Fallback_Good(t *testing.T) {
 	require.NoError(t, c.ServiceStartup(context.Background(), nil))
 
 	_, handled, err := c.PERFORM(TaskSend{
-		Opts: NotificationOptions{Title: "Warn", Message: "Oops", Severity: SeverityWarning},
+		Options: NotificationOptions{Title: "Warn", Message: "Oops", Severity: SeverityWarning},
 	})
 	assert.True(t, handled)
 	assert.NoError(t, err) // fallback succeeds even though platform failed

pkg/screen/service.go

@@ -7,16 +7,15 @@ import (
 	"forge.lthn.ai/core/go/pkg/core"
 )
 
-// Options holds configuration for the screen service.
 type Options struct{}
 
-// Service is a core.Service providing screen/display queries via IPC.
 type Service struct {
 	*core.ServiceRuntime[Options]
 	platform Platform
 }
 
-// Register creates a factory closure that captures the Platform adapter.
+// Register(p) binds the screen service to a Core instance.
+// core.WithService(screen.Register(wailsScreen))
 func Register(p Platform) func(*core.Core) (any, error) {
 	return func(c *core.Core) (any, error) {
 		return &Service{
@@ -26,13 +25,11 @@ func Register(p Platform) func(*core.Core) (any, error) {
 	}
 }
 
-// OnStartup registers IPC handlers.
 func (s *Service) OnStartup(ctx context.Context) error {
 	s.Core().RegisterQuery(s.handleQuery)
 	return nil
 }
 
-// HandleIPCEvents is auto-discovered by core.WithService.
 func (s *Service) HandleIPCEvents(c *core.Core, msg core.Message) error {
 	return nil
 }

pkg/systray/menu.go

@@ -1,31 +1,29 @@
 // pkg/systray/menu.go
 package systray
 
-import "fmt"
+import coreerr "forge.lthn.ai/core/go-log"
 
 // SetMenu sets a dynamic menu on the tray from TrayMenuItem descriptors.
 func (m *Manager) SetMenu(items []TrayMenuItem) error {
 	if m.tray == nil {
-		return fmt.Errorf("tray not initialised")
+		return coreerr.E("systray.SetMenu", "tray not initialised", nil)
 	}
-	menu := m.buildMenu(items)
+	menu := m.platform.NewMenu()
+	m.buildMenu(menu, items)
 	m.tray.SetMenu(menu)
 	return nil
 }
 
 // buildMenu recursively builds a PlatformMenu from TrayMenuItem descriptors.
-func (m *Manager) buildMenu(items []TrayMenuItem) PlatformMenu {
-	menu := m.platform.NewMenu()
+func (m *Manager) buildMenu(menu PlatformMenu, items []TrayMenuItem) {
 	for _, item := range items {
 		if item.Type == "separator" {
 			menu.AddSeparator()
 			continue
 		}
 		if len(item.Submenu) > 0 {
-			sub := m.buildMenu(item.Submenu)
-			mi := menu.Add(item.Label)
-			_ = mi.AddSubmenu()
-			_ = sub // TODO: wire sub into parent via platform
+			sub := menu.AddSubmenu(item.Label)
+			m.buildMenu(sub, item.Submenu)
 			continue
 		}
 		mi := menu.Add(item.Label)
@@ -47,7 +45,6 @@ func (m *Manager) buildMenu(items []TrayMenuItem) PlatformMenu {
 			})
 		}
 	}
-	return menu
 }
 
 // RegisterCallback registers a callback for a menu action ID.

pkg/systray/messages.go

@@ -1,30 +1,17 @@
 package systray
 
-// QueryConfig requests this service's config section from the display orchestrator.
-// Result: map[string]any
 type QueryConfig struct{}
 
-// --- Tasks ---
-
-// TaskSetTrayIcon sets the tray icon.
 type TaskSetTrayIcon struct{ Data []byte }
 
-// TaskSetTrayMenu sets the tray menu items.
 type TaskSetTrayMenu struct{ Items []TrayMenuItem }
 
-// TaskShowPanel shows the tray panel window.
 type TaskShowPanel struct{}
 
-// TaskHidePanel hides the tray panel window.
 type TaskHidePanel struct{}
 
-// TaskSaveConfig persists this service's config section via the display orchestrator.
-type TaskSaveConfig struct{ Value map[string]any }
+type TaskSaveConfig struct{ Config map[string]any }
 
-// --- Actions ---
-
-// ActionTrayClicked is broadcast when the tray icon is clicked.
 type ActionTrayClicked struct{}
 
-// ActionTrayMenuItemClicked is broadcast when a tray menu item is clicked.
 type ActionTrayMenuItemClicked struct{ ActionID string }

pkg/systray/mock_platform.go

@@ -13,14 +13,17 @@ type exportedMockTray struct {
 	tooltip, label     string
 }
 
-func (t *exportedMockTray) SetIcon(data []byte)           { t.icon = data }
-func (t *exportedMockTray) SetTemplateIcon(data []byte)    { t.templateIcon = data }
-func (t *exportedMockTray) SetTooltip(text string)         { t.tooltip = text }
-func (t *exportedMockTray) SetLabel(text string)           { t.label = text }
-func (t *exportedMockTray) SetMenu(menu PlatformMenu)      {}
-func (t *exportedMockTray) AttachWindow(w WindowHandle)     {}
+func (t *exportedMockTray) SetIcon(data []byte)         { t.icon = data }
+func (t *exportedMockTray) SetTemplateIcon(data []byte) { t.templateIcon = data }
+func (t *exportedMockTray) SetTooltip(text string)      { t.tooltip = text }
+func (t *exportedMockTray) SetLabel(text string)        { t.label = text }
+func (t *exportedMockTray) SetMenu(menu PlatformMenu)   {}
+func (t *exportedMockTray) AttachWindow(w WindowHandle) {}
 
-type exportedMockMenu struct{ items []exportedMockMenuItem }
+type exportedMockMenu struct {
+	items []exportedMockMenuItem
+	subs  []*exportedMockMenu
+}
 
 func (m *exportedMockMenu) Add(label string) PlatformMenuItem {
 	mi := &exportedMockMenuItem{label: label}
@@ -28,15 +31,20 @@ func (m *exportedMockMenu) Add(label string) PlatformMenuItem {
 	return mi
 }
 func (m *exportedMockMenu) AddSeparator() {}
+func (m *exportedMockMenu) AddSubmenu(label string) PlatformMenu {
+	m.items = append(m.items, exportedMockMenuItem{label: label})
+	sub := &exportedMockMenu{}
+	m.subs = append(m.subs, sub)
+	return sub
+}
 
 type exportedMockMenuItem struct {
-	label, tooltip string
+	label, tooltip   string
 	checked, enabled bool
 	onClick          func()
 }
 
-func (mi *exportedMockMenuItem) SetTooltip(tip string)         { mi.tooltip = tip }
-func (mi *exportedMockMenuItem) SetChecked(checked bool)        { mi.checked = checked }
-func (mi *exportedMockMenuItem) SetEnabled(enabled bool)        { mi.enabled = enabled }
-func (mi *exportedMockMenuItem) OnClick(fn func())              { mi.onClick = fn }
-func (mi *exportedMockMenuItem) AddSubmenu() PlatformMenu       { return &exportedMockMenu{} }
+func (mi *exportedMockMenuItem) SetTooltip(tip string)   { mi.tooltip = tip }
+func (mi *exportedMockMenuItem) SetChecked(checked bool) { mi.checked = checked }
+func (mi *exportedMockMenuItem) SetEnabled(enabled bool) { mi.enabled = enabled }
+func (mi *exportedMockMenuItem) OnClick(fn func())       { mi.onClick = fn }

pkg/systray/mock_test.go

@@ -22,6 +22,7 @@ func (p *mockPlatform) NewMenu() PlatformMenu {
 
 type mockTrayMenu struct {
 	items []string
+	subs  []*mockTrayMenu
 }
 
 func (m *mockTrayMenu) Add(label string) PlatformMenuItem {
@@ -29,14 +30,19 @@ func (m *mockTrayMenu) Add(label string) PlatformMenuItem {
 	return &mockTrayMenuItem{}
 }
 func (m *mockTrayMenu) AddSeparator() { m.items = append(m.items, "---") }
+func (m *mockTrayMenu) AddSubmenu(label string) PlatformMenu {
+	m.items = append(m.items, label)
+	sub := &mockTrayMenu{}
+	m.subs = append(m.subs, sub)
+	return sub
+}
 
 type mockTrayMenuItem struct{}
 
 func (mi *mockTrayMenuItem) SetTooltip(text string)  {}
-func (mi *mockTrayMenuItem) SetChecked(checked bool)  {}
-func (mi *mockTrayMenuItem) SetEnabled(enabled bool)  {}
-func (mi *mockTrayMenuItem) OnClick(fn func())        {}
-func (mi *mockTrayMenuItem) AddSubmenu() PlatformMenu { return &mockTrayMenu{} }
+func (mi *mockTrayMenuItem) SetChecked(checked bool) {}
+func (mi *mockTrayMenuItem) SetEnabled(enabled bool) {}
+func (mi *mockTrayMenuItem) OnClick(fn func())       {}
 
 type mockTray struct {
 	icon, templateIcon []byte
@@ -45,9 +51,9 @@ type mockTray struct {
 	attachedWindow     WindowHandle
 }
 
-func (t *mockTray) SetIcon(data []byte)        { t.icon = data }
+func (t *mockTray) SetIcon(data []byte)         { t.icon = data }
 func (t *mockTray) SetTemplateIcon(data []byte) { t.templateIcon = data }
 func (t *mockTray) SetTooltip(text string)      { t.tooltip = text }
 func (t *mockTray) SetLabel(text string)        { t.label = text }
 func (t *mockTray) SetMenu(menu PlatformMenu)   { t.menu = menu }
-func (t *mockTray) AttachWindow(w WindowHandle)  { t.attachedWindow = w }
+func (t *mockTray) AttachWindow(w WindowHandle) { t.attachedWindow = w }

pkg/systray/platform.go

@@ -21,6 +21,7 @@ type PlatformTray interface {
 type PlatformMenu interface {
 	Add(label string) PlatformMenuItem
 	AddSeparator()
+	AddSubmenu(label string) PlatformMenu
 }
 
 // PlatformMenuItem is a single item in a tray menu.
@@ -29,7 +30,6 @@ type PlatformMenuItem interface {
 	SetChecked(checked bool)
 	SetEnabled(enabled bool)
 	OnClick(fn func())
-	AddSubmenu() PlatformMenu
 }
 
 // WindowHandle is a cross-package interface for window operations.

pkg/systray/register.go

@@ -2,7 +2,8 @@ package systray
 
 import "forge.lthn.ai/core/go/pkg/core"
 
-// Register creates a factory closure that captures the Platform adapter.
+// Register(p) binds the systray service to a Core instance.
+// core.WithService(systray.Register(wailsSystray))
 func Register(p Platform) func(*core.Core) (any, error) {
 	return func(c *core.Core) (any, error) {
 		return &Service{

pkg/systray/service.go

@@ -6,10 +6,8 @@ import (
 	"forge.lthn.ai/core/go/pkg/core"
 )
 
-// Options holds configuration for the systray service.
 type Options struct{}
 
-// Service is a core.Service managing the system tray via IPC.
 type Service struct {
 	*core.ServiceRuntime[Options]
 	manager  *Manager
@@ -17,33 +15,31 @@ type Service struct {
 	iconPath string
 }
 
-// OnStartup queries config and registers IPC handlers.
 func (s *Service) OnStartup(ctx context.Context) error {
-	cfg, handled, _ := s.Core().QUERY(QueryConfig{})
+	configValue, handled, _ := s.Core().QUERY(QueryConfig{})
 	if handled {
-		if tCfg, ok := cfg.(map[string]any); ok {
-			s.applyConfig(tCfg)
+		if trayConfig, ok := configValue.(map[string]any); ok {
+			s.applyConfig(trayConfig)
 		}
 	}
 	s.Core().RegisterTask(s.handleTask)
 	return nil
 }
 
-func (s *Service) applyConfig(cfg map[string]any) {
-	tooltip, _ := cfg["tooltip"].(string)
+func (s *Service) applyConfig(configData map[string]any) {
+	tooltip, _ := configData["tooltip"].(string)
 	if tooltip == "" {
 		tooltip = "Core"
 	}
 	_ = s.manager.Setup(tooltip, tooltip)
 
-	if iconPath, ok := cfg["icon"].(string); ok && iconPath != "" {
+	if iconPath, ok := configData["icon"].(string); ok && iconPath != "" {
 		// Icon loading is deferred to when assets are available.
 		// Store the path for later use.
 		s.iconPath = iconPath
 	}
 }
 
-// HandleIPCEvents is auto-discovered and registered by core.WithService.
 func (s *Service) HandleIPCEvents(c *core.Core, msg core.Message) error {
 	return nil
 }
@@ -78,7 +74,6 @@ func (s *Service) taskSetTrayMenu(t TaskSetTrayMenu) error {
 	return s.manager.SetMenu(t.Items)
 }
 
-// Manager returns the underlying systray Manager.
 func (s *Service) Manager() *Manager {
 	return s.manager
 }

pkg/systray/tray.go

@@ -3,8 +3,9 @@ package systray
 
 import (
 	_ "embed"
-	"fmt"
 	"sync"
+
+	coreerr "forge.lthn.ai/core/go-log"
 )
 
 //go:embed assets/apptray.png
@@ -20,6 +21,7 @@ type Manager struct {
 }
 
 // NewManager creates a systray Manager.
+// systray.NewManager(systray.NewWailsPlatform(app)).Setup("Core", "Core")
 func NewManager(platform Platform) *Manager {
 	return &Manager{
 		platform:  platform,
@@ -28,10 +30,11 @@ func NewManager(platform Platform) *Manager {
 }
 
 // Setup creates the system tray with default icon and tooltip.
+// systray.NewManager(systray.NewWailsPlatform(app)).Setup("Core", "Core")
 func (m *Manager) Setup(tooltip, label string) error {
 	m.tray = m.platform.NewTray()
 	if m.tray == nil {
-		return fmt.Errorf("platform returned nil tray")
+		return coreerr.E("systray.Setup", "platform returned nil tray", nil)
 	}
 	m.tray.SetTemplateIcon(defaultIcon)
 	m.tray.SetTooltip(tooltip)
@@ -42,7 +45,7 @@ func (m *Manager) Setup(tooltip, label string) error {
 // SetIcon sets the tray icon.
 func (m *Manager) SetIcon(data []byte) error {
 	if m.tray == nil {
-		return fmt.Errorf("tray not initialised")
+		return coreerr.E("systray.SetIcon", "tray not initialised", nil)
 	}
 	m.tray.SetIcon(data)
 	return nil
@@ -51,7 +54,7 @@ func (m *Manager) SetIcon(data []byte) error {
 // SetTemplateIcon sets the template icon (macOS).
 func (m *Manager) SetTemplateIcon(data []byte) error {
 	if m.tray == nil {
-		return fmt.Errorf("tray not initialised")
+		return coreerr.E("systray.SetTemplateIcon", "tray not initialised", nil)
 	}
 	m.tray.SetTemplateIcon(data)
 	return nil
@@ -60,7 +63,7 @@ func (m *Manager) SetTemplateIcon(data []byte) error {
 // SetTooltip sets the tray tooltip.
 func (m *Manager) SetTooltip(text string) error {
 	if m.tray == nil {
-		return fmt.Errorf("tray not initialised")
+		return coreerr.E("systray.SetTooltip", "tray not initialised", nil)
 	}
 	m.tray.SetTooltip(text)
 	return nil
@@ -69,7 +72,7 @@ func (m *Manager) SetTooltip(text string) error {
 // SetLabel sets the tray label.
 func (m *Manager) SetLabel(text string) error {
 	if m.tray == nil {
-		return fmt.Errorf("tray not initialised")
+		return coreerr.E("systray.SetLabel", "tray not initialised", nil)
 	}
 	m.tray.SetLabel(text)
 	return nil
@@ -78,7 +81,7 @@ func (m *Manager) SetLabel(text string) error {
 // AttachWindow attaches a panel window to the tray.
 func (m *Manager) AttachWindow(w WindowHandle) error {
 	if m.tray == nil {
-		return fmt.Errorf("tray not initialised")
+		return coreerr.E("systray.AttachWindow", "tray not initialised", nil)
 	}
 	m.tray.AttachWindow(w)
 	return nil

pkg/systray/tray_test.go

@@ -84,3 +84,29 @@ func TestManager_GetInfo_Good(t *testing.T) {
 	info = m.GetInfo()
 	assert.True(t, info["active"].(bool))
 }
+
+func TestManager_Build_Submenu_Recursive_Good(t *testing.T) {
+	m, p := newTestManager()
+	require.NoError(t, m.Setup("Core", "Core"))
+
+	items := []TrayMenuItem{
+		{
+			Label: "Parent",
+			Submenu: []TrayMenuItem{
+				{Label: "Child 1"},
+				{Label: "Child 2"},
+			},
+		},
+	}
+
+	require.NoError(t, m.SetMenu(items))
+	require.Len(t, p.menus, 1)
+
+	menu := p.menus[0]
+	require.Len(t, menu.items, 1)
+	assert.Equal(t, "Parent", menu.items[0])
+	require.Len(t, menu.subs, 1)
+	require.Len(t, menu.subs[0].items, 2)
+	assert.Equal(t, "Child 1", menu.subs[0].items[0])
+	assert.Equal(t, "Child 2", menu.subs[0].items[1])
+}

pkg/systray/wails.go

@@ -28,9 +28,9 @@ type wailsTray struct {
 }
 
 func (wt *wailsTray) SetIcon(data []byte)         { wt.tray.SetIcon(data) }
-func (wt *wailsTray) SetTemplateIcon(data []byte)  { wt.tray.SetTemplateIcon(data) }
-func (wt *wailsTray) SetTooltip(text string)       { wt.tray.SetTooltip(text) }
-func (wt *wailsTray) SetLabel(text string)         { wt.tray.SetLabel(text) }
+func (wt *wailsTray) SetTemplateIcon(data []byte) { wt.tray.SetTemplateIcon(data) }
+func (wt *wailsTray) SetTooltip(text string)      { wt.tray.SetTooltip(text) }
+func (wt *wailsTray) SetLabel(text string)        { wt.tray.SetLabel(text) }
 
 func (wt *wailsTray) SetMenu(menu PlatformMenu) {
 	if wm, ok := menu.(*wailsTrayMenu); ok {
@@ -56,18 +56,18 @@ func (m *wailsTrayMenu) AddSeparator() {
 	m.menu.AddSeparator()
 }
 
+func (m *wailsTrayMenu) AddSubmenu(label string) PlatformMenu {
+	return &wailsTrayMenu{menu: m.menu.AddSubmenu(label)}
+}
+
 // wailsTrayMenuItem wraps *application.MenuItem for the PlatformMenuItem interface.
 type wailsTrayMenuItem struct {
 	item *application.MenuItem
 }
 
-func (mi *wailsTrayMenuItem) SetTooltip(text string) { mi.item.SetTooltip(text) }
+func (mi *wailsTrayMenuItem) SetTooltip(text string)  { mi.item.SetTooltip(text) }
 func (mi *wailsTrayMenuItem) SetChecked(checked bool) { mi.item.SetChecked(checked) }
 func (mi *wailsTrayMenuItem) SetEnabled(enabled bool) { mi.item.SetEnabled(enabled) }
 func (mi *wailsTrayMenuItem) OnClick(fn func()) {
 	mi.item.OnClick(func(ctx *application.Context) { fn() })
 }
-func (mi *wailsTrayMenuItem) AddSubmenu() PlatformMenu {
-	// Wails doesn't have a direct AddSubmenu on MenuItem — use Menu.AddSubmenu instead
-	return &wailsTrayMenu{menu: application.NewMenu()}
-}

pkg/webview/service.go

@@ -2,10 +2,10 @@
 package webview
 
 import (
+	"bytes"
 	"context"
 	"encoding/base64"
 	"strconv"
-	"strings"
 	"sync"
 	"time"
 
@@ -37,37 +37,51 @@ type connector interface {
 	Close() error
 }
 
-// Options holds configuration for the webview service.
 type Options struct {
 	DebugURL     string        // Chrome debug endpoint (default: "http://localhost:9222")
 	Timeout      time.Duration // Operation timeout (default: 30s)
 	ConsoleLimit int           // Max console messages per window (default: 1000)
 }
 
-// Service is a core.Service managing webview interactions via IPC.
+func defaultOptions() Options {
+	return Options{
+		DebugURL:     "http://localhost:9222",
+		Timeout:      30 * time.Second,
+		ConsoleLimit: 1000,
+	}
+}
+
+func normalizeOptions(options Options) Options {
+	defaults := defaultOptions()
+	if options.DebugURL == "" {
+		options.DebugURL = defaults.DebugURL
+	}
+	if options.Timeout == 0 {
+		options.Timeout = defaults.Timeout
+	}
+	if options.ConsoleLimit == 0 {
+		options.ConsoleLimit = defaults.ConsoleLimit
+	}
+	return options
+}
+
 type Service struct {
 	*core.ServiceRuntime[Options]
-	opts         Options
+	options      Options
 	connections  map[string]connector
 	mu           sync.RWMutex
 	newConn      func(debugURL, windowName string) (connector, error) // injectable for tests
 	watcherSetup func(conn connector, windowName string)              // called after connection creation
 }
 
-// Register creates a factory closure with the given options.
-func Register(opts ...func(*Options)) func(*core.Core) (any, error) {
-	o := Options{
-		DebugURL:     "http://localhost:9222",
-		Timeout:      30 * time.Second,
-		ConsoleLimit: 1000,
-	}
-	for _, fn := range opts {
-		fn(&o)
-	}
+// RegisterWithOptions binds the webview service to a Core instance using a declarative Options literal.
+// core.WithService(webview.RegisterWithOptions(webview.Options{DebugURL: "http://localhost:9223", Timeout: 30 * time.Second, ConsoleLimit: 1000}))
+func RegisterWithOptions(options Options) func(*core.Core) (any, error) {
+	o := normalizeOptions(options)
 	return func(c *core.Core) (any, error) {
 		svc := &Service{
 			ServiceRuntime: core.NewServiceRuntime[Options](c, o),
-			opts:           o,
+			options:        o,
 			connections:    make(map[string]connector),
 			newConn:        defaultNewConn(o),
 		}
@@ -76,8 +90,19 @@ func Register(opts ...func(*Options)) func(*core.Core) (any, error) {
 	}
 }
 
+// Deprecated: use RegisterWithOptions(webview.Options{DebugURL: "http://localhost:9223", Timeout: 30 * time.Second, ConsoleLimit: 1000}).
+func Register(optionFns ...func(*Options)) func(*core.Core) (any, error) {
+	options := defaultOptions()
+	for _, fn := range optionFns {
+		if fn != nil {
+			fn(&options)
+		}
+	}
+	return RegisterWithOptions(options)
+}
+
 // defaultNewConn creates real go-webview connections.
-func defaultNewConn(opts Options) func(string, string) (connector, error) {
+func defaultNewConn(options Options) func(string, string) (connector, error) {
 	return func(debugURL, windowName string) (connector, error) {
 		// Enumerate targets, match by title/URL containing window name
 		targets, err := gowebview.ListTargets(debugURL)
@@ -86,7 +111,7 @@ func defaultNewConn(opts Options) func(string, string) (connector, error) {
 		}
 		var wsURL string
 		for _, t := range targets {
-			if t.Type == "page" && (strings.Contains(t.Title, windowName) || strings.Contains(t.URL, windowName)) {
+			if t.Type == "page" && (bytes.Contains([]byte(t.Title), []byte(windowName)) || bytes.Contains([]byte(t.URL), []byte(windowName))) {
 				wsURL = t.WebSocketDebuggerURL
 				break
 			}
@@ -105,8 +130,8 @@ func defaultNewConn(opts Options) func(string, string) (connector, error) {
 		}
 		wv, err := gowebview.New(
 			gowebview.WithDebugURL(debugURL),
-			gowebview.WithTimeout(opts.Timeout),
-			gowebview.WithConsoleLimit(opts.ConsoleLimit),
+			gowebview.WithTimeout(options.Timeout),
+			gowebview.WithConsoleLimit(options.ConsoleLimit),
 		)
 		if err != nil {
 			return nil, err
@@ -154,7 +179,6 @@ func (s *Service) defaultWatcherSetup(conn connector, windowName string) {
 	})
 }
 
-// OnStartup registers IPC handlers.
 func (s *Service) OnStartup(_ context.Context) error {
 	s.Core().RegisterQuery(s.handleQuery)
 	s.Core().RegisterTask(s.handleTask)
@@ -201,7 +225,7 @@ func (s *Service) getConn(windowName string) (connector, error) {
 	if conn, ok := s.connections[windowName]; ok {
 		return conn, nil
 	}
-	conn, err := s.newConn(s.opts.DebugURL, windowName)
+	conn, err := s.newConn(s.options.DebugURL, windowName)
 	if err != nil {
 		return nil, err
 	}
@@ -373,17 +397,17 @@ type realConnector struct {
 	wv *gowebview.Webview
 }
 
-func (r *realConnector) Navigate(url string) error              { return r.wv.Navigate(url) }
-func (r *realConnector) Click(sel string) error                 { return r.wv.Click(sel) }
-func (r *realConnector) Type(sel, text string) error            { return r.wv.Type(sel, text) }
-func (r *realConnector) Evaluate(script string) (any, error)    { return r.wv.Evaluate(script) }
-func (r *realConnector) Screenshot() ([]byte, error)            { return r.wv.Screenshot() }
-func (r *realConnector) GetURL() (string, error)                { return r.wv.GetURL() }
-func (r *realConnector) GetTitle() (string, error)              { return r.wv.GetTitle() }
-func (r *realConnector) GetHTML(sel string) (string, error)     { return r.wv.GetHTML(sel) }
-func (r *realConnector) ClearConsole()                          { r.wv.ClearConsole() }
-func (r *realConnector) Close() error                           { return r.wv.Close() }
-func (r *realConnector) SetViewport(w, h int) error             { return r.wv.SetViewport(w, h) }
+func (r *realConnector) Navigate(url string) error               { return r.wv.Navigate(url) }
+func (r *realConnector) Click(sel string) error                  { return r.wv.Click(sel) }
+func (r *realConnector) Type(sel, text string) error             { return r.wv.Type(sel, text) }
+func (r *realConnector) Evaluate(script string) (any, error)     { return r.wv.Evaluate(script) }
+func (r *realConnector) Screenshot() ([]byte, error)             { return r.wv.Screenshot() }
+func (r *realConnector) GetURL() (string, error)                 { return r.wv.GetURL() }
+func (r *realConnector) GetTitle() (string, error)               { return r.wv.GetTitle() }
+func (r *realConnector) GetHTML(sel string) (string, error)      { return r.wv.GetHTML(sel) }
+func (r *realConnector) ClearConsole()                           { r.wv.ClearConsole() }
+func (r *realConnector) Close() error                            { return r.wv.Close() }
+func (r *realConnector) SetViewport(w, h int) error              { return r.wv.SetViewport(w, h) }
 func (r *realConnector) UploadFile(sel string, p []string) error { return r.wv.UploadFile(sel, p) }
 
 func (r *realConnector) Hover(sel string) error {

pkg/webview/service_test.go

@@ -37,21 +37,41 @@ type mockConnector struct {
 	consoleClearCalled bool
 }
 
-func (m *mockConnector) Navigate(url string) error        { m.lastNavURL = url; return nil }
-func (m *mockConnector) Click(sel string) error           { m.lastClickSel = sel; return nil }
-func (m *mockConnector) Type(sel, text string) error      { m.lastTypeSel = sel; m.lastTypeText = text; return nil }
-func (m *mockConnector) Hover(sel string) error           { m.lastHoverSel = sel; return nil }
-func (m *mockConnector) Select(sel, val string) error     { m.lastSelectSel = sel; m.lastSelectVal = val; return nil }
-func (m *mockConnector) Check(sel string, c bool) error   { m.lastCheckSel = sel; m.lastCheckVal = c; return nil }
-func (m *mockConnector) Evaluate(s string) (any, error)   { return m.evalResult, nil }
-func (m *mockConnector) Screenshot() ([]byte, error)      { return m.screenshot, nil }
-func (m *mockConnector) GetURL() (string, error)          { return m.url, nil }
-func (m *mockConnector) GetTitle() (string, error)        { return m.title, nil }
+func (m *mockConnector) Navigate(url string) error { m.lastNavURL = url; return nil }
+func (m *mockConnector) Click(sel string) error    { m.lastClickSel = sel; return nil }
+func (m *mockConnector) Type(sel, text string) error {
+	m.lastTypeSel = sel
+	m.lastTypeText = text
+	return nil
+}
+func (m *mockConnector) Hover(sel string) error { m.lastHoverSel = sel; return nil }
+func (m *mockConnector) Select(sel, val string) error {
+	m.lastSelectSel = sel
+	m.lastSelectVal = val
+	return nil
+}
+func (m *mockConnector) Check(sel string, c bool) error {
+	m.lastCheckSel = sel
+	m.lastCheckVal = c
+	return nil
+}
+func (m *mockConnector) Evaluate(s string) (any, error)     { return m.evalResult, nil }
+func (m *mockConnector) Screenshot() ([]byte, error)        { return m.screenshot, nil }
+func (m *mockConnector) GetURL() (string, error)            { return m.url, nil }
+func (m *mockConnector) GetTitle() (string, error)          { return m.title, nil }
 func (m *mockConnector) GetHTML(sel string) (string, error) { return m.html, nil }
-func (m *mockConnector) ClearConsole()                    { m.consoleClearCalled = true }
-func (m *mockConnector) Close() error                     { m.closed = true; return nil }
-func (m *mockConnector) SetViewport(w, h int) error       { m.lastViewportW = w; m.lastViewportH = h; return nil }
-func (m *mockConnector) UploadFile(sel string, p []string) error { m.lastUploadSel = sel; m.lastUploadPaths = p; return nil }
+func (m *mockConnector) ClearConsole()                      { m.consoleClearCalled = true }
+func (m *mockConnector) Close() error                       { m.closed = true; return nil }
+func (m *mockConnector) SetViewport(w, h int) error {
+	m.lastViewportW = w
+	m.lastViewportH = h
+	return nil
+}
+func (m *mockConnector) UploadFile(sel string, p []string) error {
+	m.lastUploadSel = sel
+	m.lastUploadPaths = p
+	return nil
+}
 
 func (m *mockConnector) QuerySelector(sel string) (*ElementInfo, error) {
 	if len(m.elements) > 0 {
@@ -68,7 +88,7 @@ func (m *mockConnector) GetConsole() []ConsoleMessage { return m.console }
 
 func newTestService(t *testing.T, mock *mockConnector) (*Service, *core.Core) {
 	t.Helper()
-	factory := Register()
+	factory := RegisterWithOptions(Options{})
 	c, err := core.New(core.WithService(factory), core.WithServiceLock())
 	require.NoError(t, err)
 	require.NoError(t, c.ServiceStartup(context.Background(), nil))
@@ -78,7 +98,7 @@ func newTestService(t *testing.T, mock *mockConnector) (*Service, *core.Core) {
 	return svc, c
 }
 
-func TestRegister_Good(t *testing.T) {
+func TestRegisterWithOptions_Good(t *testing.T) {
 	svc, _ := newTestService(t, &mockConnector{})
 	assert.NotNil(t, svc)
 }

pkg/window/layout.go

@@ -3,11 +3,13 @@ package window
 
 import (
 	"encoding/json"
-	"fmt"
 	"os"
 	"path/filepath"
 	"sync"
 	"time"
+
+	coreio "forge.lthn.ai/core/go-io"
+	coreerr "forge.lthn.ai/core/go-log"
 )
 
 // Layout is a named window arrangement.
@@ -65,13 +67,13 @@ func (lm *LayoutManager) load() {
 	if lm.configDir == "" {
 		return
 	}
-	data, err := os.ReadFile(lm.filePath())
+	content, err := coreio.Local.Read(lm.filePath())
 	if err != nil {
 		return
 	}
 	lm.mu.Lock()
 	defer lm.mu.Unlock()
-	_ = json.Unmarshal(data, &lm.layouts)
+	_ = json.Unmarshal([]byte(content), &lm.layouts)
 }
 
 func (lm *LayoutManager) save() {
@@ -84,14 +86,14 @@ func (lm *LayoutManager) save() {
 	if err != nil {
 		return
 	}
-	_ = os.MkdirAll(lm.configDir, 0o755)
-	_ = os.WriteFile(lm.filePath(), data, 0o644)
+	_ = coreio.Local.EnsureDir(lm.configDir)
+	_ = coreio.Local.Write(lm.filePath(), string(data))
 }
 
 // SaveLayout creates or updates a named layout.
 func (lm *LayoutManager) SaveLayout(name string, windowStates map[string]WindowState) error {
 	if name == "" {
-		return fmt.Errorf("layout name cannot be empty")
+		return coreerr.E("window.LayoutManager.SaveLayout", "layout name cannot be empty", nil)
 	}
 	now := time.Now().UnixMilli()
 	lm.mu.Lock()

pkg/window/messages.go

@@ -1,6 +1,5 @@
 package window
 
-// WindowInfo contains information about a window.
 type WindowInfo struct {
 	Name      string `json:"name"`
 	Title     string `json:"title"`
@@ -12,103 +11,96 @@ type WindowInfo struct {
 	Focused   bool   `json:"focused"`
 }
 
-// --- Queries (read-only) ---
-
-// QueryWindowList returns all tracked windows. Result: []WindowInfo
 type QueryWindowList struct{}
 
-// QueryWindowByName returns a single window by name. Result: *WindowInfo (nil if not found)
 type QueryWindowByName struct{ Name string }
 
-// QueryConfig requests this service's config section from the display orchestrator.
-// Result: map[string]any
 type QueryConfig struct{}
 
-// --- Tasks (side-effects) ---
+// TaskOpenWindow opens a concrete Window descriptor.
+// window.TaskOpenWindow{Window: &window.Window{Name: "settings", URL: "/", Width: 800, Height: 600}}
+type TaskOpenWindow struct{ Window *Window }
 
-// TaskOpenWindow creates a new window. Result: WindowInfo
-type TaskOpenWindow struct{ Opts []WindowOption }
-
-// TaskCloseWindow closes a window. Handler persists state BEFORE emitting ActionWindowClosed.
 type TaskCloseWindow struct{ Name string }
 
-// TaskSetPosition moves a window.
 type TaskSetPosition struct {
 	Name string
 	X, Y int
 }
 
-// TaskSetSize resizes a window.
 type TaskSetSize struct {
-	Name string
-	W, H int
+	Name          string
+	Width, Height int
 }
 
-// TaskMaximise maximises a window.
 type TaskMaximise struct{ Name string }
 
-// TaskMinimise minimises a window.
 type TaskMinimise struct{ Name string }
 
-// TaskFocus brings a window to the front.
 type TaskFocus struct{ Name string }
 
-// TaskRestore restores a maximised or minimised window to its normal state.
 type TaskRestore struct{ Name string }
 
-// TaskSetTitle changes a window's title.
 type TaskSetTitle struct {
 	Name  string
 	Title string
 }
 
-// TaskSetVisibility shows or hides a window.
+type TaskSetAlwaysOnTop struct {
+	Name        string
+	AlwaysOnTop bool
+}
+
+type TaskSetBackgroundColour struct {
+	Name  string
+	Red   uint8
+	Green uint8
+	Blue  uint8
+	Alpha uint8
+}
+
 type TaskSetVisibility struct {
 	Name    string
 	Visible bool
 }
 
-// TaskFullscreen enters or exits fullscreen mode.
 type TaskFullscreen struct {
 	Name       string
 	Fullscreen bool
 }
 
-// --- Layout Queries ---
-
-// QueryLayoutList returns summaries of all saved layouts. Result: []LayoutInfo
 type QueryLayoutList struct{}
 
-// QueryLayoutGet returns a layout by name. Result: *Layout (nil if not found)
 type QueryLayoutGet struct{ Name string }
 
-// --- Layout Tasks ---
-
-// TaskSaveLayout saves the current window arrangement as a named layout. Result: bool
 type TaskSaveLayout struct{ Name string }
 
-// TaskRestoreLayout restores a saved layout by name.
 type TaskRestoreLayout struct{ Name string }
 
-// TaskDeleteLayout removes a saved layout by name.
 type TaskDeleteLayout struct{ Name string }
 
-// TaskTileWindows arranges windows in a tiling mode.
 type TaskTileWindows struct {
 	Mode    string   // "left-right", "grid", "left-half", "right-half", etc.
 	Windows []string // window names; empty = all
 }
 
-// TaskSnapWindow snaps a window to a screen edge/corner.
+type TaskStackWindows struct {
+	Windows []string // window names; empty = all
+	OffsetX int
+	OffsetY int
+}
+
 type TaskSnapWindow struct {
 	Name     string // window name
 	Position string // "left", "right", "top", "bottom", "top-left", "top-right", "bottom-left", "bottom-right", "center"
 }
 
-// TaskSaveConfig persists this service's config section via the display orchestrator.
-type TaskSaveConfig struct{ Value map[string]any }
+type TaskApplyWorkflow struct {
+	Workflow string
+	Windows  []string // window names; empty = all
+}
 
-// --- Actions (broadcasts) ---
+type TaskSaveConfig struct{ Config map[string]any }
 
 type ActionWindowOpened struct{ Name string }
 type ActionWindowClosed struct{ Name string }
@@ -119,15 +111,15 @@ type ActionWindowMoved struct {
 }
 
 type ActionWindowResized struct {
-	Name string
-	W, H int
+	Name          string
+	Width, Height int
 }
 
 type ActionWindowFocused struct{ Name string }
 type ActionWindowBlurred struct{ Name string }
 
 type ActionFilesDropped struct {
-	Name     string   `json:"name"`     // window name
+	Name     string   `json:"name"` // window name
 	Paths    []string `json:"paths"`
 	TargetID string   `json:"targetId,omitempty"`
 }

pkg/window/mock_platform.go

@@ -10,11 +10,11 @@ func NewMockPlatform() *MockPlatform {
 	return &MockPlatform{}
 }
 
-func (m *MockPlatform) CreateWindow(opts PlatformWindowOptions) PlatformWindow {
+func (m *MockPlatform) CreateWindow(options PlatformWindowOptions) PlatformWindow {
 	w := &MockWindow{
-		name: opts.Name, title: opts.Title, url: opts.URL,
-		width: opts.Width, height: opts.Height,
-		x: opts.X, y: opts.Y,
+		name: options.Name, title: options.Title, url: options.URL,
+		width: options.Width, height: options.Height,
+		x: options.X, y: options.Y,
 	}
 	m.Windows = append(m.Windows, w)
 	return w
@@ -33,33 +33,36 @@ type MockWindow struct {
 	width, height, x, y  int
 	maximised, focused   bool
 	visible, alwaysOnTop bool
+	backgroundColour     [4]uint8
 	closed               bool
 	eventHandlers        []func(WindowEvent)
 	fileDropHandlers     []func(paths []string, targetID string)
 }
 
-func (w *MockWindow) Name() string                            { return w.name }
-func (w *MockWindow) Title() string                           { return w.title }
-func (w *MockWindow) Position() (int, int)                    { return w.x, w.y }
-func (w *MockWindow) Size() (int, int)                        { return w.width, w.height }
-func (w *MockWindow) IsMaximised() bool                       { return w.maximised }
-func (w *MockWindow) IsFocused() bool                         { return w.focused }
-func (w *MockWindow) SetTitle(title string)                   { w.title = title }
-func (w *MockWindow) SetPosition(x, y int)                    { w.x = x; w.y = y }
-func (w *MockWindow) SetSize(width, height int)               { w.width = width; w.height = height }
-func (w *MockWindow) SetBackgroundColour(r, g, b, a uint8)    {}
-func (w *MockWindow) SetVisibility(visible bool)              { w.visible = visible }
-func (w *MockWindow) SetAlwaysOnTop(alwaysOnTop bool)         { w.alwaysOnTop = alwaysOnTop }
-func (w *MockWindow) Maximise()                               { w.maximised = true }
-func (w *MockWindow) Restore()                                { w.maximised = false }
-func (w *MockWindow) Minimise()                               {}
-func (w *MockWindow) Focus()                                  { w.focused = true }
-func (w *MockWindow) Close()                                  { w.closed = true }
-func (w *MockWindow) Show()                                   { w.visible = true }
-func (w *MockWindow) Hide()                                   { w.visible = false }
-func (w *MockWindow) Fullscreen()                             {}
-func (w *MockWindow) UnFullscreen()                           {}
-func (w *MockWindow) OnWindowEvent(handler func(WindowEvent)) { w.eventHandlers = append(w.eventHandlers, handler) }
+func (w *MockWindow) Name() string                         { return w.name }
+func (w *MockWindow) Title() string                        { return w.title }
+func (w *MockWindow) Position() (int, int)                 { return w.x, w.y }
+func (w *MockWindow) Size() (int, int)                     { return w.width, w.height }
+func (w *MockWindow) IsMaximised() bool                    { return w.maximised }
+func (w *MockWindow) IsFocused() bool                      { return w.focused }
+func (w *MockWindow) SetTitle(title string)                { w.title = title }
+func (w *MockWindow) SetPosition(x, y int)                 { w.x = x; w.y = y }
+func (w *MockWindow) SetSize(width, height int)            { w.width = width; w.height = height }
+func (w *MockWindow) SetBackgroundColour(r, g, b, a uint8) { w.backgroundColour = [4]uint8{r, g, b, a} }
+func (w *MockWindow) SetVisibility(visible bool)           { w.visible = visible }
+func (w *MockWindow) SetAlwaysOnTop(alwaysOnTop bool)      { w.alwaysOnTop = alwaysOnTop }
+func (w *MockWindow) Maximise()                            { w.maximised = true }
+func (w *MockWindow) Restore()                             { w.maximised = false }
+func (w *MockWindow) Minimise()                            {}
+func (w *MockWindow) Focus()                               { w.focused = true }
+func (w *MockWindow) Close()                               { w.closed = true }
+func (w *MockWindow) Show()                                { w.visible = true }
+func (w *MockWindow) Hide()                                { w.visible = false }
+func (w *MockWindow) Fullscreen()                          {}
+func (w *MockWindow) UnFullscreen()                        {}
+func (w *MockWindow) OnWindowEvent(handler func(WindowEvent)) {
+	w.eventHandlers = append(w.eventHandlers, handler)
+}
 func (w *MockWindow) OnFileDrop(handler func(paths []string, targetID string)) {
 	w.fileDropHandlers = append(w.fileDropHandlers, handler)
 }

pkg/window/mock_test.go

@@ -1,4 +1,3 @@
-// pkg/window/mock_test.go
 package window
 
 type mockPlatform struct {
@@ -9,11 +8,11 @@ func newMockPlatform() *mockPlatform {
 	return &mockPlatform{}
 }
 
-func (m *mockPlatform) CreateWindow(opts PlatformWindowOptions) PlatformWindow {
+func (m *mockPlatform) CreateWindow(options PlatformWindowOptions) PlatformWindow {
 	w := &mockWindow{
-		name: opts.Name, title: opts.Title, url: opts.URL,
-		width: opts.Width, height: opts.Height,
-		x: opts.X, y: opts.Y,
+		name: options.Name, title: options.Title, url: options.URL,
+		width: options.Width, height: options.Height,
+		x: options.X, y: options.Y,
 	}
 	m.windows = append(m.windows, w)
 	return w
@@ -32,33 +31,38 @@ type mockWindow struct {
 	width, height, x, y  int
 	maximised, focused   bool
 	visible, alwaysOnTop bool
+	backgroundColour     [4]uint8
 	closed               bool
+	minimised            bool
+	fullscreened         bool
 	eventHandlers        []func(WindowEvent)
 	fileDropHandlers     []func(paths []string, targetID string)
 }
 
-func (w *mockWindow) Name() string                            { return w.name }
-func (w *mockWindow) Title() string                           { return w.title }
-func (w *mockWindow) Position() (int, int)                    { return w.x, w.y }
-func (w *mockWindow) Size() (int, int)                        { return w.width, w.height }
-func (w *mockWindow) IsMaximised() bool                       { return w.maximised }
-func (w *mockWindow) IsFocused() bool                         { return w.focused }
-func (w *mockWindow) SetTitle(title string)                   { w.title = title }
-func (w *mockWindow) SetPosition(x, y int)                    { w.x = x; w.y = y }
-func (w *mockWindow) SetSize(width, height int)               { w.width = width; w.height = height }
-func (w *mockWindow) SetBackgroundColour(r, g, b, a uint8)    {}
-func (w *mockWindow) SetVisibility(visible bool)              { w.visible = visible }
-func (w *mockWindow) SetAlwaysOnTop(alwaysOnTop bool)         { w.alwaysOnTop = alwaysOnTop }
-func (w *mockWindow) Maximise()                               { w.maximised = true }
-func (w *mockWindow) Restore()                                { w.maximised = false }
-func (w *mockWindow) Minimise()                               {}
-func (w *mockWindow) Focus()                                  { w.focused = true }
-func (w *mockWindow) Close()                                  { w.closed = true }
-func (w *mockWindow) Show()                                   { w.visible = true }
-func (w *mockWindow) Hide()                                   { w.visible = false }
-func (w *mockWindow) Fullscreen()                             {}
-func (w *mockWindow) UnFullscreen()                           {}
-func (w *mockWindow) OnWindowEvent(handler func(WindowEvent)) { w.eventHandlers = append(w.eventHandlers, handler) }
+func (w *mockWindow) Name() string                         { return w.name }
+func (w *mockWindow) Title() string                        { return w.title }
+func (w *mockWindow) Position() (int, int)                 { return w.x, w.y }
+func (w *mockWindow) Size() (int, int)                     { return w.width, w.height }
+func (w *mockWindow) IsMaximised() bool                    { return w.maximised }
+func (w *mockWindow) IsFocused() bool                      { return w.focused }
+func (w *mockWindow) SetTitle(title string)                { w.title = title }
+func (w *mockWindow) SetPosition(x, y int)                 { w.x = x; w.y = y }
+func (w *mockWindow) SetSize(width, height int)            { w.width = width; w.height = height }
+func (w *mockWindow) SetBackgroundColour(r, g, b, a uint8) { w.backgroundColour = [4]uint8{r, g, b, a} }
+func (w *mockWindow) SetVisibility(visible bool)           { w.visible = visible }
+func (w *mockWindow) SetAlwaysOnTop(alwaysOnTop bool)      { w.alwaysOnTop = alwaysOnTop }
+func (w *mockWindow) Maximise()                            { w.maximised = true }
+func (w *mockWindow) Restore()                             { w.maximised = false }
+func (w *mockWindow) Minimise()                            { w.minimised = true }
+func (w *mockWindow) Focus()                               { w.focused = true }
+func (w *mockWindow) Close()                               { w.closed = true }
+func (w *mockWindow) Show()                                { w.visible = true }
+func (w *mockWindow) Hide()                                { w.visible = false }
+func (w *mockWindow) Fullscreen()                          { w.fullscreened = true }
+func (w *mockWindow) UnFullscreen()                        { w.fullscreened = false }
+func (w *mockWindow) OnWindowEvent(handler func(WindowEvent)) {
+	w.eventHandlers = append(w.eventHandlers, handler)
+}
 func (w *mockWindow) OnFileDrop(handler func(paths []string, targetID string)) {
 	w.fileDropHandlers = append(w.fileDropHandlers, handler)
 }

pkg/window/options.go

@@ -1,23 +1,25 @@
 // pkg/window/options.go
 package window
 
-// WindowOption is a functional option applied to a Window descriptor.
+// WindowOption is the compatibility layer for option-chain callers.
+// Prefer a Window literal with Manager.CreateWindow.
 type WindowOption func(*Window) error
 
-// ApplyOptions creates a Window and applies all options in order.
-func ApplyOptions(opts ...WindowOption) (*Window, error) {
+// Deprecated: use Manager.CreateWindow(Window{Name: "settings", URL: "/", Width: 800, Height: 600}).
+func ApplyOptions(options ...WindowOption) (*Window, error) {
 	w := &Window{}
-	for _, opt := range opts {
-		if opt == nil {
+	for _, option := range options {
+		if option == nil {
 			continue
 		}
-		if err := opt(w); err != nil {
+		if err := option(w); err != nil {
 			return nil, err
 		}
 	}
 	return w, nil
 }
 
+// Compatibility helpers for callers still using option chains.
 func WithName(name string) WindowOption {
 	return func(w *Window) error { w.Name = name; return nil }
 }

pkg/window/persistence_test.go

@@ -0,0 +1,334 @@
+// pkg/window/persistence_test.go
+package window
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// --- StateManager Persistence Tests ---
+
+func TestStateManager_SetAndGet_Good(t *testing.T) {
+	sm := NewStateManagerWithDir(t.TempDir())
+	state := WindowState{
+		X: 150, Y: 250, Width: 1024, Height: 768,
+		Maximized: true, Screen: "primary", URL: "/app",
+	}
+	sm.SetState("editor", state)
+
+	got, ok := sm.GetState("editor")
+	require.True(t, ok)
+	assert.Equal(t, 150, got.X)
+	assert.Equal(t, 250, got.Y)
+	assert.Equal(t, 1024, got.Width)
+	assert.Equal(t, 768, got.Height)
+	assert.True(t, got.Maximized)
+	assert.Equal(t, "primary", got.Screen)
+	assert.Equal(t, "/app", got.URL)
+	assert.NotZero(t, got.UpdatedAt, "UpdatedAt should be set by SetState")
+}
+
+func TestStateManager_UpdatePosition_Good(t *testing.T) {
+	sm := NewStateManagerWithDir(t.TempDir())
+	sm.SetState("win", WindowState{X: 0, Y: 0, Width: 800, Height: 600})
+
+	sm.UpdatePosition("win", 300, 400)
+
+	got, ok := sm.GetState("win")
+	require.True(t, ok)
+	assert.Equal(t, 300, got.X)
+	assert.Equal(t, 400, got.Y)
+	// Width/Height should remain unchanged
+	assert.Equal(t, 800, got.Width)
+	assert.Equal(t, 600, got.Height)
+}
+
+func TestStateManager_UpdateSize_Good(t *testing.T) {
+	sm := NewStateManagerWithDir(t.TempDir())
+	sm.SetState("win", WindowState{X: 100, Y: 200, Width: 800, Height: 600})
+
+	sm.UpdateSize("win", 1920, 1080)
+
+	got, ok := sm.GetState("win")
+	require.True(t, ok)
+	assert.Equal(t, 1920, got.Width)
+	assert.Equal(t, 1080, got.Height)
+	// Position should remain unchanged
+	assert.Equal(t, 100, got.X)
+	assert.Equal(t, 200, got.Y)
+}
+
+func TestStateManager_UpdateMaximized_Good(t *testing.T) {
+	sm := NewStateManagerWithDir(t.TempDir())
+	sm.SetState("win", WindowState{Width: 800, Height: 600, Maximized: false})
+
+	sm.UpdateMaximized("win", true)
+
+	got, ok := sm.GetState("win")
+	require.True(t, ok)
+	assert.True(t, got.Maximized)
+
+	sm.UpdateMaximized("win", false)
+
+	got, ok = sm.GetState("win")
+	require.True(t, ok)
+	assert.False(t, got.Maximized)
+}
+
+func TestStateManager_CaptureState_Good(t *testing.T) {
+	sm := NewStateManagerWithDir(t.TempDir())
+	pw := &mockWindow{
+		name: "captured", x: 75, y: 125,
+		width: 1440, height: 900, maximised: true,
+	}
+
+	sm.CaptureState(pw)
+
+	got, ok := sm.GetState("captured")
+	require.True(t, ok)
+	assert.Equal(t, 75, got.X)
+	assert.Equal(t, 125, got.Y)
+	assert.Equal(t, 1440, got.Width)
+	assert.Equal(t, 900, got.Height)
+	assert.True(t, got.Maximized)
+	assert.NotZero(t, got.UpdatedAt)
+}
+
+func TestStateManager_ApplyState_Good(t *testing.T) {
+	sm := NewStateManagerWithDir(t.TempDir())
+	sm.SetState("target", WindowState{X: 55, Y: 65, Width: 700, Height: 500})
+
+	w := &Window{Name: "target", Width: 1280, Height: 800, X: 0, Y: 0}
+	sm.ApplyState(w)
+
+	assert.Equal(t, 55, w.X)
+	assert.Equal(t, 65, w.Y)
+	assert.Equal(t, 700, w.Width)
+	assert.Equal(t, 500, w.Height)
+}
+
+func TestStateManager_ApplyState_Good_NoState(t *testing.T) {
+	sm := NewStateManagerWithDir(t.TempDir())
+
+	w := &Window{Name: "untouched", Width: 1280, Height: 800, X: 10, Y: 20}
+	sm.ApplyState(w)
+
+	// Window should remain unchanged when no state is saved
+	assert.Equal(t, 10, w.X)
+	assert.Equal(t, 20, w.Y)
+	assert.Equal(t, 1280, w.Width)
+	assert.Equal(t, 800, w.Height)
+}
+
+func TestStateManager_ListStates_Good(t *testing.T) {
+	sm := NewStateManagerWithDir(t.TempDir())
+	sm.SetState("alpha", WindowState{Width: 100})
+	sm.SetState("beta", WindowState{Width: 200})
+	sm.SetState("gamma", WindowState{Width: 300})
+
+	names := sm.ListStates()
+	assert.Len(t, names, 3)
+	assert.Contains(t, names, "alpha")
+	assert.Contains(t, names, "beta")
+	assert.Contains(t, names, "gamma")
+}
+
+func TestStateManager_Clear_Good(t *testing.T) {
+	sm := NewStateManagerWithDir(t.TempDir())
+	sm.SetState("a", WindowState{Width: 100})
+	sm.SetState("b", WindowState{Width: 200})
+	sm.SetState("c", WindowState{Width: 300})
+
+	sm.Clear()
+
+	names := sm.ListStates()
+	assert.Empty(t, names)
+
+	_, ok := sm.GetState("a")
+	assert.False(t, ok)
+}
+
+func TestStateManager_Persistence_Good(t *testing.T) {
+	dir := t.TempDir()
+
+	// First manager: write state and force sync to disk
+	sm1 := NewStateManagerWithDir(dir)
+	sm1.SetState("persist-win", WindowState{
+		X: 42, Y: 84, Width: 500, Height: 300,
+		Maximized: true, Screen: "secondary", URL: "/settings",
+	})
+	sm1.ForceSync()
+
+	// Second manager: load from the same directory
+	sm2 := NewStateManagerWithDir(dir)
+
+	got, ok := sm2.GetState("persist-win")
+	require.True(t, ok)
+	assert.Equal(t, 42, got.X)
+	assert.Equal(t, 84, got.Y)
+	assert.Equal(t, 500, got.Width)
+	assert.Equal(t, 300, got.Height)
+	assert.True(t, got.Maximized)
+	assert.Equal(t, "secondary", got.Screen)
+	assert.Equal(t, "/settings", got.URL)
+	assert.NotZero(t, got.UpdatedAt)
+}
+
+func TestStateManager_SetPath_Good(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "custom", "window-state.json")
+
+	sm := NewStateManagerWithDir(dir)
+	sm.SetPath(path)
+	sm.SetState("custom", WindowState{Width: 640, Height: 480})
+	sm.ForceSync()
+
+	content, err := os.ReadFile(path)
+	require.NoError(t, err)
+	assert.Contains(t, string(content), "custom")
+}
+
+// --- LayoutManager Persistence Tests ---
+
+func TestLayoutManager_SaveAndGet_Good(t *testing.T) {
+	lm := NewLayoutManagerWithDir(t.TempDir())
+	windows := map[string]WindowState{
+		"editor":   {X: 0, Y: 0, Width: 960, Height: 1080},
+		"terminal": {X: 960, Y: 0, Width: 960, Height: 540},
+		"browser":  {X: 960, Y: 540, Width: 960, Height: 540},
+	}
+
+	err := lm.SaveLayout("coding", windows)
+	require.NoError(t, err)
+
+	layout, ok := lm.GetLayout("coding")
+	require.True(t, ok)
+	assert.Equal(t, "coding", layout.Name)
+	assert.Len(t, layout.Windows, 3)
+	assert.Equal(t, 960, layout.Windows["editor"].Width)
+	assert.Equal(t, 1080, layout.Windows["editor"].Height)
+	assert.Equal(t, 960, layout.Windows["terminal"].X)
+	assert.NotZero(t, layout.CreatedAt)
+	assert.NotZero(t, layout.UpdatedAt)
+	assert.Equal(t, layout.CreatedAt, layout.UpdatedAt, "CreatedAt and UpdatedAt should match on first save")
+}
+
+func TestLayoutManager_SaveLayout_EmptyName_Bad(t *testing.T) {
+	lm := NewLayoutManagerWithDir(t.TempDir())
+	err := lm.SaveLayout("", map[string]WindowState{
+		"win": {Width: 800},
+	})
+	assert.Error(t, err)
+}
+
+func TestLayoutManager_SaveLayout_Update_Good(t *testing.T) {
+	lm := NewLayoutManagerWithDir(t.TempDir())
+
+	// First save
+	err := lm.SaveLayout("evolving", map[string]WindowState{
+		"win1": {Width: 800, Height: 600},
+	})
+	require.NoError(t, err)
+
+	first, ok := lm.GetLayout("evolving")
+	require.True(t, ok)
+	originalCreatedAt := first.CreatedAt
+	originalUpdatedAt := first.UpdatedAt
+
+	// Small delay to ensure UpdatedAt differs
+	time.Sleep(2 * time.Millisecond)
+
+	// Second save with same name but different windows
+	err = lm.SaveLayout("evolving", map[string]WindowState{
+		"win1": {Width: 1024, Height: 768},
+		"win2": {Width: 640, Height: 480},
+	})
+	require.NoError(t, err)
+
+	updated, ok := lm.GetLayout("evolving")
+	require.True(t, ok)
+
+	// CreatedAt should be preserved from the original save
+	assert.Equal(t, originalCreatedAt, updated.CreatedAt, "CreatedAt should be preserved on update")
+	// UpdatedAt should be newer
+	assert.GreaterOrEqual(t, updated.UpdatedAt, originalUpdatedAt, "UpdatedAt should advance on update")
+	// Windows should reflect the second save
+	assert.Len(t, updated.Windows, 2)
+	assert.Equal(t, 1024, updated.Windows["win1"].Width)
+}
+
+func TestLayoutManager_ListLayouts_Good(t *testing.T) {
+	lm := NewLayoutManagerWithDir(t.TempDir())
+	require.NoError(t, lm.SaveLayout("coding", map[string]WindowState{
+		"editor": {Width: 960}, "terminal": {Width: 960},
+	}))
+	require.NoError(t, lm.SaveLayout("presenting", map[string]WindowState{
+		"slides": {Width: 1920},
+	}))
+	require.NoError(t, lm.SaveLayout("debugging", map[string]WindowState{
+		"code": {Width: 640}, "debugger": {Width: 640}, "console": {Width: 640},
+	}))
+
+	infos := lm.ListLayouts()
+	assert.Len(t, infos, 3)
+
+	// Build a lookup map for assertions regardless of order
+	byName := make(map[string]LayoutInfo)
+	for _, info := range infos {
+		byName[info.Name] = info
+	}
+
+	assert.Equal(t, 2, byName["coding"].WindowCount)
+	assert.Equal(t, 1, byName["presenting"].WindowCount)
+	assert.Equal(t, 3, byName["debugging"].WindowCount)
+}
+
+func TestLayoutManager_DeleteLayout_Good(t *testing.T) {
+	lm := NewLayoutManagerWithDir(t.TempDir())
+	require.NoError(t, lm.SaveLayout("temporary", map[string]WindowState{
+		"win": {Width: 800},
+	}))
+
+	// Verify it exists
+	_, ok := lm.GetLayout("temporary")
+	require.True(t, ok)
+
+	lm.DeleteLayout("temporary")
+
+	// Verify it is gone
+	_, ok = lm.GetLayout("temporary")
+	assert.False(t, ok)
+
+	// Verify list is empty
+	assert.Empty(t, lm.ListLayouts())
+}
+
+func TestLayoutManager_Persistence_Good(t *testing.T) {
+	dir := t.TempDir()
+
+	// First manager: save layout to disk
+	lm1 := NewLayoutManagerWithDir(dir)
+	err := lm1.SaveLayout("persisted", map[string]WindowState{
+		"main":    {X: 0, Y: 0, Width: 1280, Height: 800},
+		"sidebar": {X: 1280, Y: 0, Width: 640, Height: 800},
+	})
+	require.NoError(t, err)
+
+	// Second manager: load from the same directory
+	lm2 := NewLayoutManagerWithDir(dir)
+
+	layout, ok := lm2.GetLayout("persisted")
+	require.True(t, ok)
+	assert.Equal(t, "persisted", layout.Name)
+	assert.Len(t, layout.Windows, 2)
+	assert.Equal(t, 1280, layout.Windows["main"].Width)
+	assert.Equal(t, 800, layout.Windows["main"].Height)
+	assert.Equal(t, 640, layout.Windows["sidebar"].Width)
+	assert.NotZero(t, layout.CreatedAt)
+	assert.NotZero(t, layout.UpdatedAt)
+}

pkg/window/platform.go

@@ -3,25 +3,25 @@ package window
 
 // Platform abstracts the windowing backend (Wails v3).
 type Platform interface {
-	CreateWindow(opts PlatformWindowOptions) PlatformWindow
+	CreateWindow(options PlatformWindowOptions) PlatformWindow
 	GetWindows() []PlatformWindow
 }
 
 // PlatformWindowOptions are the backend-specific options passed to CreateWindow.
 type PlatformWindowOptions struct {
-	Name                  string
-	Title                 string
-	URL                   string
-	Width, Height         int
-	X, Y                  int
-	MinWidth, MinHeight   int
-	MaxWidth, MaxHeight   int
-	Frameless             bool
-	Hidden                bool
-	AlwaysOnTop           bool
-	BackgroundColour      [4]uint8 // RGBA
-	DisableResize         bool
-	EnableFileDrop        bool
+	Name                string
+	Title               string
+	URL                 string
+	Width, Height       int
+	X, Y                int
+	MinWidth, MinHeight int
+	MaxWidth, MaxHeight int
+	Frameless           bool
+	Hidden              bool
+	AlwaysOnTop         bool
+	BackgroundColour    [4]uint8 // RGBA
+	DisableResize       bool
+	EnableFileDrop      bool
 }
 
 // PlatformWindow is a live window handle from the backend.

pkg/window/register.go

@@ -2,8 +2,8 @@ package window
 
 import "forge.lthn.ai/core/go/pkg/core"
 
-// Register creates a factory closure that captures the Platform adapter.
-// The returned function has the signature WithService requires: func(*Core) (any, error).
+// Register(p) binds the window service to a Core instance.
+// core.WithService(window.Register(window.NewWailsPlatform(app)))
 func Register(p Platform) func(*core.Core) (any, error) {
 	return func(c *core.Core) (any, error) {
 		return &Service{

pkg/window/service.go

@@ -2,66 +2,57 @@ package window
 
 import (
 	"context"
-	"fmt"
 
+	coreerr "forge.lthn.ai/core/go-log"
 	"forge.lthn.ai/core/go/pkg/core"
+	"forge.lthn.ai/core/gui/pkg/screen"
 )
 
-// Options holds configuration for the window service.
 type Options struct{}
 
-// Service is a core.Service managing window lifecycle via IPC.
-// It embeds ServiceRuntime for Core access and composes Manager for platform operations.
 type Service struct {
 	*core.ServiceRuntime[Options]
 	manager  *Manager
 	platform Platform
 }
 
-// OnStartup queries config from the display orchestrator and registers IPC handlers.
 func (s *Service) OnStartup(ctx context.Context) error {
 	// Query config — display registers its handler before us (registration order guarantee).
 	// If display is not registered, handled=false and we skip config.
-	cfg, handled, _ := s.Core().QUERY(QueryConfig{})
+	configValue, handled, _ := s.Core().QUERY(QueryConfig{})
 	if handled {
-		if wCfg, ok := cfg.(map[string]any); ok {
-			s.applyConfig(wCfg)
+		if windowConfig, ok := configValue.(map[string]any); ok {
+			s.applyConfig(windowConfig)
 		}
 	}
 
-	// Register QUERY and TASK handlers manually.
-	// ACTION handler (HandleIPCEvents) is auto-registered by WithService —
-	// do NOT call RegisterAction here or actions will double-fire.
 	s.Core().RegisterQuery(s.handleQuery)
 	s.Core().RegisterTask(s.handleTask)
 	return nil
 }
 
-func (s *Service) applyConfig(cfg map[string]any) {
-	if w, ok := cfg["default_width"]; ok {
-		if _, ok := w.(int); ok {
-			// TODO: s.manager.SetDefaultWidth(width) — add when Manager API is extended
+func (s *Service) applyConfig(configData map[string]any) {
+	if width, ok := configData["default_width"]; ok {
+		if width, ok := width.(int); ok {
+			s.manager.SetDefaultWidth(width)
 		}
 	}
-	if h, ok := cfg["default_height"]; ok {
-		if _, ok := h.(int); ok {
-			// TODO: s.manager.SetDefaultHeight(height) — add when Manager API is extended
+	if height, ok := configData["default_height"]; ok {
+		if height, ok := height.(int); ok {
+			s.manager.SetDefaultHeight(height)
 		}
 	}
-	if sf, ok := cfg["state_file"]; ok {
-		if _, ok := sf.(string); ok {
-			// TODO: s.manager.State().SetPath(stateFile) — add when StateManager API is extended
+	if stateFile, ok := configData["state_file"]; ok {
+		if stateFile, ok := stateFile.(string); ok {
+			s.manager.State().SetPath(stateFile)
 		}
 	}
 }
 
-// HandleIPCEvents is auto-discovered and registered by core.WithService.
 func (s *Service) HandleIPCEvents(c *core.Core, msg core.Message) error {
 	return nil
 }
 
-// --- Query Handlers ---
-
 func (s *Service) handleQuery(c *core.Core, q core.Query) (any, bool, error) {
 	switch q := q.(type) {
 	case QueryWindowList:
@@ -123,7 +114,7 @@ func (s *Service) handleTask(c *core.Core, t core.Task) (any, bool, error) {
 	case TaskSetPosition:
 		return nil, true, s.taskSetPosition(t.Name, t.X, t.Y)
 	case TaskSetSize:
-		return nil, true, s.taskSetSize(t.Name, t.W, t.H)
+		return nil, true, s.taskSetSize(t.Name, t.Width, t.Height)
 	case TaskMaximise:
 		return nil, true, s.taskMaximise(t.Name)
 	case TaskMinimise:
@@ -134,6 +125,10 @@ func (s *Service) handleTask(c *core.Core, t core.Task) (any, bool, error) {
 		return nil, true, s.taskRestore(t.Name)
 	case TaskSetTitle:
 		return nil, true, s.taskSetTitle(t.Name, t.Title)
+	case TaskSetAlwaysOnTop:
+		return nil, true, s.taskSetAlwaysOnTop(t.Name, t.AlwaysOnTop)
+	case TaskSetBackgroundColour:
+		return nil, true, s.taskSetBackgroundColour(t.Name, t.Red, t.Green, t.Blue, t.Alpha)
 	case TaskSetVisibility:
 		return nil, true, s.taskSetVisibility(t.Name, t.Visible)
 	case TaskFullscreen:
@@ -147,15 +142,55 @@ func (s *Service) handleTask(c *core.Core, t core.Task) (any, bool, error) {
 		return nil, true, nil
 	case TaskTileWindows:
 		return nil, true, s.taskTileWindows(t.Mode, t.Windows)
+	case TaskStackWindows:
+		return nil, true, s.taskStackWindows(t.Windows, t.OffsetX, t.OffsetY)
 	case TaskSnapWindow:
 		return nil, true, s.taskSnapWindow(t.Name, t.Position)
+	case TaskApplyWorkflow:
+		return nil, true, s.taskApplyWorkflow(t.Workflow, t.Windows)
 	default:
 		return nil, false, nil
 	}
 }
 
+func (s *Service) primaryScreenArea() (int, int, int, int) {
+	const fallbackX = 0
+	const fallbackY = 0
+	const fallbackWidth = 1920
+	const fallbackHeight = 1080
+
+	result, handled, err := s.Core().QUERY(screen.QueryPrimary{})
+	if err != nil || !handled {
+		return fallbackX, fallbackY, fallbackWidth, fallbackHeight
+	}
+
+	primary, ok := result.(*screen.Screen)
+	if !ok || primary == nil {
+		return fallbackX, fallbackY, fallbackWidth, fallbackHeight
+	}
+
+	x := primary.WorkArea.X
+	y := primary.WorkArea.Y
+	width := primary.WorkArea.Width
+	height := primary.WorkArea.Height
+	if width <= 0 || height <= 0 {
+		x = primary.Bounds.X
+		y = primary.Bounds.Y
+		width = primary.Bounds.Width
+		height = primary.Bounds.Height
+	}
+	if width <= 0 || height <= 0 {
+		return fallbackX, fallbackY, fallbackWidth, fallbackHeight
+	}
+
+	return x, y, width, height
+}
+
 func (s *Service) taskOpenWindow(t TaskOpenWindow) (any, bool, error) {
-	pw, err := s.manager.Open(t.Opts...)
+	if t.Window == nil {
+		return nil, true, coreerr.E("window.taskOpenWindow", "window descriptor is required", nil)
+	}
+	pw, err := s.manager.CreateWindow(*t.Window)
 	if err != nil {
 		return nil, true, err
 	}
@@ -189,7 +224,7 @@ func (s *Service) trackWindow(pw PlatformWindow) {
 			if data := e.Data; data != nil {
 				w, _ := data["w"].(int)
 				h, _ := data["h"].(int)
-				_ = s.Core().ACTION(ActionWindowResized{Name: e.Name, W: w, H: h})
+				_ = s.Core().ACTION(ActionWindowResized{Name: e.Name, Width: w, Height: h})
 			}
 		case "close":
 			_ = s.Core().ACTION(ActionWindowClosed{Name: e.Name})
@@ -207,7 +242,7 @@ func (s *Service) trackWindow(pw PlatformWindow) {
 func (s *Service) taskCloseWindow(name string) error {
 	pw, ok := s.manager.Get(name)
 	if !ok {
-		return fmt.Errorf("window not found: %s", name)
+		return coreerr.E("window.taskClose", "window not found: "+name, nil)
 	}
 	// Persist state BEFORE closing (spec requirement)
 	s.manager.State().CaptureState(pw)
@@ -220,27 +255,27 @@ func (s *Service) taskCloseWindow(name string) error {
 func (s *Service) taskSetPosition(name string, x, y int) error {
 	pw, ok := s.manager.Get(name)
 	if !ok {
-		return fmt.Errorf("window not found: %s", name)
+		return coreerr.E("window.taskSetPosition", "window not found: "+name, nil)
 	}
 	pw.SetPosition(x, y)
 	s.manager.State().UpdatePosition(name, x, y)
 	return nil
 }
 
-func (s *Service) taskSetSize(name string, w, h int) error {
+func (s *Service) taskSetSize(name string, width, height int) error {
 	pw, ok := s.manager.Get(name)
 	if !ok {
-		return fmt.Errorf("window not found: %s", name)
+		return coreerr.E("window.taskSetSize", "window not found: "+name, nil)
 	}
-	pw.SetSize(w, h)
-	s.manager.State().UpdateSize(name, w, h)
+	pw.SetSize(width, height)
+	s.manager.State().UpdateSize(name, width, height)
 	return nil
 }
 
 func (s *Service) taskMaximise(name string) error {
 	pw, ok := s.manager.Get(name)
 	if !ok {
-		return fmt.Errorf("window not found: %s", name)
+		return coreerr.E("window.taskMaximise", "window not found: "+name, nil)
 	}
 	pw.Maximise()
 	s.manager.State().UpdateMaximized(name, true)
@@ -250,7 +285,7 @@ func (s *Service) taskMaximise(name string) error {
 func (s *Service) taskMinimise(name string) error {
 	pw, ok := s.manager.Get(name)
 	if !ok {
-		return fmt.Errorf("window not found: %s", name)
+		return coreerr.E("window.taskMinimise", "window not found: "+name, nil)
 	}
 	pw.Minimise()
 	return nil
@@ -259,7 +294,7 @@ func (s *Service) taskMinimise(name string) error {
 func (s *Service) taskFocus(name string) error {
 	pw, ok := s.manager.Get(name)
 	if !ok {
-		return fmt.Errorf("window not found: %s", name)
+		return coreerr.E("window.taskFocus", "window not found: "+name, nil)
 	}
 	pw.Focus()
 	return nil
@@ -268,7 +303,7 @@ func (s *Service) taskFocus(name string) error {
 func (s *Service) taskRestore(name string) error {
 	pw, ok := s.manager.Get(name)
 	if !ok {
-		return fmt.Errorf("window not found: %s", name)
+		return coreerr.E("window.taskRestore", "window not found: "+name, nil)
 	}
 	pw.Restore()
 	s.manager.State().UpdateMaximized(name, false)
@@ -278,16 +313,34 @@ func (s *Service) taskRestore(name string) error {
 func (s *Service) taskSetTitle(name, title string) error {
 	pw, ok := s.manager.Get(name)
 	if !ok {
-		return fmt.Errorf("window not found: %s", name)
+		return coreerr.E("window.taskSetTitle", "window not found: "+name, nil)
 	}
 	pw.SetTitle(title)
 	return nil
 }
 
+func (s *Service) taskSetAlwaysOnTop(name string, alwaysOnTop bool) error {
+	pw, ok := s.manager.Get(name)
+	if !ok {
+		return coreerr.E("window.taskSetAlwaysOnTop", "window not found: "+name, nil)
+	}
+	pw.SetAlwaysOnTop(alwaysOnTop)
+	return nil
+}
+
+func (s *Service) taskSetBackgroundColour(name string, red, green, blue, alpha uint8) error {
+	pw, ok := s.manager.Get(name)
+	if !ok {
+		return coreerr.E("window.taskSetBackgroundColour", "window not found: "+name, nil)
+	}
+	pw.SetBackgroundColour(red, green, blue, alpha)
+	return nil
+}
+
 func (s *Service) taskSetVisibility(name string, visible bool) error {
 	pw, ok := s.manager.Get(name)
 	if !ok {
-		return fmt.Errorf("window not found: %s", name)
+		return coreerr.E("window.taskSetVisibility", "window not found: "+name, nil)
 	}
 	pw.SetVisibility(visible)
 	return nil
@@ -296,7 +349,7 @@ func (s *Service) taskSetVisibility(name string, visible bool) error {
 func (s *Service) taskFullscreen(name string, fullscreen bool) error {
 	pw, ok := s.manager.Get(name)
 	if !ok {
-		return fmt.Errorf("window not found: %s", name)
+		return coreerr.E("window.taskFullscreen", "window not found: "+name, nil)
 	}
 	if fullscreen {
 		pw.Fullscreen()
@@ -321,7 +374,7 @@ func (s *Service) taskSaveLayout(name string) error {
 func (s *Service) taskRestoreLayout(name string) error {
 	layout, ok := s.manager.Layout().GetLayout(name)
 	if !ok {
-		return fmt.Errorf("layout not found: %s", name)
+		return coreerr.E("window.taskRestoreLayout", "layout not found: "+name, nil)
 	}
 	for winName, state := range layout.Windows {
 		pw, found := s.manager.Get(winName)
@@ -332,7 +385,10 @@ func (s *Service) taskRestoreLayout(name string) error {
 		pw.SetSize(state.Width, state.Height)
 		if state.Maximized {
 			pw.Maximise()
+		} else {
+			pw.Restore()
 		}
+		s.manager.State().CaptureState(pw)
 	}
 	return nil
 }
@@ -348,13 +404,21 @@ var tileModeMap = map[string]TileMode{
 func (s *Service) taskTileWindows(mode string, names []string) error {
 	tm, ok := tileModeMap[mode]
 	if !ok {
-		return fmt.Errorf("unknown tile mode: %s", mode)
+		return coreerr.E("window.taskTileWindows", "unknown tile mode: "+mode, nil)
 	}
 	if len(names) == 0 {
 		names = s.manager.List()
 	}
-	// Default screen size — callers can query screen_primary for actual values.
-	return s.manager.TileWindows(tm, names, 1920, 1080)
+	originX, originY, screenWidth, screenHeight := s.primaryScreenArea()
+	return s.manager.TileWindows(tm, names, screenWidth, screenHeight, originX, originY)
+}
+
+func (s *Service) taskStackWindows(names []string, offsetX, offsetY int) error {
+	if len(names) == 0 {
+		names = s.manager.List()
+	}
+	originX, originY, _, _ := s.primaryScreenArea()
+	return s.manager.StackWindows(names, offsetX, offsetY, originX, originY)
 }
 
 var snapPosMap = map[string]SnapPosition{
@@ -368,9 +432,29 @@ var snapPosMap = map[string]SnapPosition{
 func (s *Service) taskSnapWindow(name, position string) error {
 	pos, ok := snapPosMap[position]
 	if !ok {
-		return fmt.Errorf("unknown snap position: %s", position)
+		return coreerr.E("window.taskSnapWindow", "unknown snap position: "+position, nil)
 	}
-	return s.manager.SnapWindow(name, pos, 1920, 1080)
+	originX, originY, screenWidth, screenHeight := s.primaryScreenArea()
+	return s.manager.SnapWindow(name, pos, screenWidth, screenHeight, originX, originY)
+}
+
+var workflowLayoutMap = map[string]WorkflowLayout{
+	"coding":       WorkflowCoding,
+	"debugging":    WorkflowDebugging,
+	"presenting":   WorkflowPresenting,
+	"side-by-side": WorkflowSideBySide,
+}
+
+func (s *Service) taskApplyWorkflow(workflow string, names []string) error {
+	layout, ok := workflowLayoutMap[workflow]
+	if !ok {
+		return coreerr.E("window.taskApplyWorkflow", "unknown workflow layout: "+workflow, nil)
+	}
+	if len(names) == 0 {
+		names = s.manager.List()
+	}
+	originX, originY, screenWidth, screenHeight := s.primaryScreenArea()
+	return s.manager.ApplyWorkflow(layout, names, screenWidth, screenHeight, originX, originY)
 }
 
 // Manager returns the underlying window Manager for direct access.

pkg/window/service_screen_test.go

@@ -0,0 +1,129 @@
+package window
+
+import (
+	"context"
+	"testing"
+
+	"forge.lthn.ai/core/go/pkg/core"
+	"forge.lthn.ai/core/gui/pkg/screen"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+type mockScreenPlatform struct {
+	screens []screen.Screen
+}
+
+func (m *mockScreenPlatform) GetAll() []screen.Screen { return m.screens }
+
+func (m *mockScreenPlatform) GetPrimary() *screen.Screen {
+	for i := range m.screens {
+		if m.screens[i].IsPrimary {
+			return &m.screens[i]
+		}
+	}
+	return nil
+}
+
+func newTestWindowServiceWithScreen(t *testing.T, screens []screen.Screen) (*Service, *core.Core) {
+	t.Helper()
+
+	c, err := core.New(
+		core.WithService(screen.Register(&mockScreenPlatform{screens: screens})),
+		core.WithService(Register(newMockPlatform())),
+		core.WithServiceLock(),
+	)
+	require.NoError(t, err)
+	require.NoError(t, c.ServiceStartup(context.Background(), nil))
+
+	svc := core.MustServiceFor[*Service](c, "window")
+	return svc, c
+}
+
+func TestTaskTileWindows_Good_UsesPrimaryScreenSize(t *testing.T) {
+	_, c := newTestWindowServiceWithScreen(t, []screen.Screen{
+		{
+			ID: "1", Name: "Primary", IsPrimary: true,
+			Bounds:   screen.Rect{X: 0, Y: 0, Width: 2000, Height: 1000},
+			WorkArea: screen.Rect{X: 0, Y: 0, Width: 2000, Height: 1000},
+		},
+	})
+
+	_ = requireOpenWindow(t, c, Window{Name: "left", Width: 400, Height: 400})
+	_ = requireOpenWindow(t, c, Window{Name: "right", Width: 400, Height: 400})
+
+	_, handled, err := c.PERFORM(TaskTileWindows{Mode: "left-right", Windows: []string{"left", "right"}})
+	require.NoError(t, err)
+	assert.True(t, handled)
+
+	result, _, err := c.QUERY(QueryWindowByName{Name: "left"})
+	require.NoError(t, err)
+	left := result.(*WindowInfo)
+	assert.Equal(t, 0, left.X)
+	assert.Equal(t, 1000, left.Width)
+	assert.Equal(t, 1000, left.Height)
+
+	result, _, err = c.QUERY(QueryWindowByName{Name: "right"})
+	require.NoError(t, err)
+	right := result.(*WindowInfo)
+	assert.Equal(t, 1000, right.X)
+	assert.Equal(t, 1000, right.Width)
+	assert.Equal(t, 1000, right.Height)
+}
+
+func TestTaskSnapWindow_Good_UsesPrimaryScreenSize(t *testing.T) {
+	_, c := newTestWindowServiceWithScreen(t, []screen.Screen{
+		{
+			ID: "1", Name: "Primary", IsPrimary: true,
+			Bounds:   screen.Rect{X: 0, Y: 0, Width: 2000, Height: 1000},
+			WorkArea: screen.Rect{X: 0, Y: 0, Width: 2000, Height: 1000},
+		},
+	})
+
+	_ = requireOpenWindow(t, c, Window{Name: "snap", Width: 400, Height: 300})
+
+	_, handled, err := c.PERFORM(TaskSnapWindow{Name: "snap", Position: "left"})
+	require.NoError(t, err)
+	assert.True(t, handled)
+
+	result, _, err := c.QUERY(QueryWindowByName{Name: "snap"})
+	require.NoError(t, err)
+	info := result.(*WindowInfo)
+	assert.Equal(t, 0, info.X)
+	assert.Equal(t, 0, info.Y)
+	assert.Equal(t, 1000, info.Width)
+	assert.Equal(t, 1000, info.Height)
+}
+
+func TestTaskTileWindows_Good_UsesPrimaryWorkAreaOrigin(t *testing.T) {
+	_, c := newTestWindowServiceWithScreen(t, []screen.Screen{
+		{
+			ID: "1", Name: "Primary", IsPrimary: true,
+			Bounds:   screen.Rect{X: 0, Y: 0, Width: 2000, Height: 1000},
+			WorkArea: screen.Rect{X: 100, Y: 50, Width: 2000, Height: 1000},
+		},
+	})
+
+	_ = requireOpenWindow(t, c, Window{Name: "left", Width: 400, Height: 400})
+	_ = requireOpenWindow(t, c, Window{Name: "right", Width: 400, Height: 400})
+
+	_, handled, err := c.PERFORM(TaskTileWindows{Mode: "left-right", Windows: []string{"left", "right"}})
+	require.NoError(t, err)
+	assert.True(t, handled)
+
+	result, _, err := c.QUERY(QueryWindowByName{Name: "left"})
+	require.NoError(t, err)
+	left := result.(*WindowInfo)
+	assert.Equal(t, 100, left.X)
+	assert.Equal(t, 50, left.Y)
+	assert.Equal(t, 1000, left.Width)
+	assert.Equal(t, 1000, left.Height)
+
+	result, _, err = c.QUERY(QueryWindowByName{Name: "right"})
+	require.NoError(t, err)
+	right := result.(*WindowInfo)
+	assert.Equal(t, 1100, right.X)
+	assert.Equal(t, 50, right.Y)
+	assert.Equal(t, 1000, right.Width)
+	assert.Equal(t, 1000, right.Height)
+}

pkg/window/service_test.go

@@ -22,6 +22,14 @@ func newTestWindowService(t *testing.T) (*Service, *core.Core) {
 	return svc, c
 }
 
+func requireOpenWindow(t *testing.T, c *core.Core, window Window) WindowInfo {
+	t.Helper()
+	result, handled, err := c.PERFORM(TaskOpenWindow{Window: &window})
+	require.NoError(t, err)
+	require.True(t, handled)
+	return result.(WindowInfo)
+}
+
 func TestRegister_Good(t *testing.T) {
 	svc, _ := newTestWindowService(t)
 	assert.NotNil(t, svc)
@@ -31,7 +39,7 @@ func TestRegister_Good(t *testing.T) {
 func TestTaskOpenWindow_Good(t *testing.T) {
 	_, c := newTestWindowService(t)
 	result, handled, err := c.PERFORM(TaskOpenWindow{
-		Opts: []WindowOption{WithName("test"), WithURL("/")},
+		Window: &Window{Name: "test", URL: "/"},
 	})
 	require.NoError(t, err)
 	assert.True(t, handled)
@@ -39,6 +47,14 @@ func TestTaskOpenWindow_Good(t *testing.T) {
 	assert.Equal(t, "test", info.Name)
 }
 
+func TestTaskOpenWindow_Bad_MissingWindow(t *testing.T) {
+	_, c := newTestWindowService(t)
+	result, handled, err := c.PERFORM(TaskOpenWindow{})
+	assert.True(t, handled)
+	assert.Error(t, err)
+	assert.Nil(t, result)
+}
+
 func TestTaskOpenWindow_Bad(t *testing.T) {
 	// No window service registered — PERFORM returns handled=false
 	c, err := core.New(core.WithServiceLock())
@@ -49,8 +65,8 @@ func TestTaskOpenWindow_Bad(t *testing.T) {
 
 func TestQueryWindowList_Good(t *testing.T) {
 	_, c := newTestWindowService(t)
-	_, _, _ = c.PERFORM(TaskOpenWindow{Opts: []WindowOption{WithName("a")}})
-	_, _, _ = c.PERFORM(TaskOpenWindow{Opts: []WindowOption{WithName("b")}})
+	_ = requireOpenWindow(t, c, Window{Name: "a"})
+	_ = requireOpenWindow(t, c, Window{Name: "b"})
 
 	result, handled, err := c.QUERY(QueryWindowList{})
 	require.NoError(t, err)
@@ -61,7 +77,7 @@ func TestQueryWindowList_Good(t *testing.T) {
 
 func TestQueryWindowByName_Good(t *testing.T) {
 	_, c := newTestWindowService(t)
-	_, _, _ = c.PERFORM(TaskOpenWindow{Opts: []WindowOption{WithName("test")}})
+	_ = requireOpenWindow(t, c, Window{Name: "test"})
 
 	result, handled, err := c.QUERY(QueryWindowByName{Name: "test"})
 	require.NoError(t, err)
@@ -80,7 +96,7 @@ func TestQueryWindowByName_Bad(t *testing.T) {
 
 func TestTaskCloseWindow_Good(t *testing.T) {
 	_, c := newTestWindowService(t)
-	_, _, _ = c.PERFORM(TaskOpenWindow{Opts: []WindowOption{WithName("test")}})
+	_ = requireOpenWindow(t, c, Window{Name: "test"})
 
 	_, handled, err := c.PERFORM(TaskCloseWindow{Name: "test"})
 	require.NoError(t, err)
@@ -100,7 +116,7 @@ func TestTaskCloseWindow_Bad(t *testing.T) {
 
 func TestTaskSetPosition_Good(t *testing.T) {
 	_, c := newTestWindowService(t)
-	_, _, _ = c.PERFORM(TaskOpenWindow{Opts: []WindowOption{WithName("test")}})
+	_ = requireOpenWindow(t, c, Window{Name: "test"})
 
 	_, handled, err := c.PERFORM(TaskSetPosition{Name: "test", X: 100, Y: 200})
 	require.NoError(t, err)
@@ -114,9 +130,9 @@ func TestTaskSetPosition_Good(t *testing.T) {
 
 func TestTaskSetSize_Good(t *testing.T) {
 	_, c := newTestWindowService(t)
-	_, _, _ = c.PERFORM(TaskOpenWindow{Opts: []WindowOption{WithName("test")}})
+	_ = requireOpenWindow(t, c, Window{Name: "test"})
 
-	_, handled, err := c.PERFORM(TaskSetSize{Name: "test", W: 800, H: 600})
+	_, handled, err := c.PERFORM(TaskSetSize{Name: "test", Width: 800, Height: 600})
 	require.NoError(t, err)
 	assert.True(t, handled)
 
@@ -128,7 +144,7 @@ func TestTaskSetSize_Good(t *testing.T) {
 
 func TestTaskMaximise_Good(t *testing.T) {
 	_, c := newTestWindowService(t)
-	_, _, _ = c.PERFORM(TaskOpenWindow{Opts: []WindowOption{WithName("test")}})
+	_ = requireOpenWindow(t, c, Window{Name: "test"})
 
 	_, handled, err := c.PERFORM(TaskMaximise{Name: "test"})
 	require.NoError(t, err)
@@ -143,10 +159,7 @@ func TestFileDrop_Good(t *testing.T) {
 	_, c := newTestWindowService(t)
 
 	// Open a window
-	result, _, _ := c.PERFORM(TaskOpenWindow{
-		Opts: []WindowOption{WithName("drop-test")},
-	})
-	info := result.(WindowInfo)
+	info := requireOpenWindow(t, c, Window{Name: "drop-test"})
 	assert.Equal(t, "drop-test", info.Name)
 
 	// Capture broadcast actions
@@ -174,3 +187,338 @@ func TestFileDrop_Good(t *testing.T) {
 	assert.Equal(t, "upload-zone", dropped.TargetID)
 	mu.Unlock()
 }
+
+// --- TaskMinimise ---
+
+func TestTaskMinimise_Good(t *testing.T) {
+	svc, c := newTestWindowService(t)
+	_ = requireOpenWindow(t, c, Window{Name: "test"})
+
+	_, handled, err := c.PERFORM(TaskMinimise{Name: "test"})
+	require.NoError(t, err)
+	assert.True(t, handled)
+
+	pw, ok := svc.Manager().Get("test")
+	require.True(t, ok)
+	mw := pw.(*mockWindow)
+	assert.True(t, mw.minimised)
+}
+
+func TestTaskMinimise_Bad(t *testing.T) {
+	_, c := newTestWindowService(t)
+	_, handled, err := c.PERFORM(TaskMinimise{Name: "nonexistent"})
+	assert.True(t, handled)
+	assert.Error(t, err)
+}
+
+// --- TaskFocus ---
+
+func TestTaskFocus_Good(t *testing.T) {
+	svc, c := newTestWindowService(t)
+	_ = requireOpenWindow(t, c, Window{Name: "test"})
+
+	_, handled, err := c.PERFORM(TaskFocus{Name: "test"})
+	require.NoError(t, err)
+	assert.True(t, handled)
+
+	pw, ok := svc.Manager().Get("test")
+	require.True(t, ok)
+	mw := pw.(*mockWindow)
+	assert.True(t, mw.focused)
+}
+
+func TestTaskFocus_Bad(t *testing.T) {
+	_, c := newTestWindowService(t)
+	_, handled, err := c.PERFORM(TaskFocus{Name: "nonexistent"})
+	assert.True(t, handled)
+	assert.Error(t, err)
+}
+
+// --- TaskRestore ---
+
+func TestTaskRestore_Good(t *testing.T) {
+	svc, c := newTestWindowService(t)
+	_ = requireOpenWindow(t, c, Window{Name: "test"})
+
+	// First maximise, then restore
+	_, _, _ = c.PERFORM(TaskMaximise{Name: "test"})
+
+	_, handled, err := c.PERFORM(TaskRestore{Name: "test"})
+	require.NoError(t, err)
+	assert.True(t, handled)
+
+	pw, ok := svc.Manager().Get("test")
+	require.True(t, ok)
+	mw := pw.(*mockWindow)
+	assert.False(t, mw.maximised)
+
+	// Verify state was updated
+	state, ok := svc.Manager().State().GetState("test")
+	assert.True(t, ok)
+	assert.False(t, state.Maximized)
+}
+
+func TestTaskRestore_Bad(t *testing.T) {
+	_, c := newTestWindowService(t)
+	_, handled, err := c.PERFORM(TaskRestore{Name: "nonexistent"})
+	assert.True(t, handled)
+	assert.Error(t, err)
+}
+
+// --- TaskSetTitle ---
+
+func TestTaskSetTitle_Good(t *testing.T) {
+	svc, c := newTestWindowService(t)
+	_ = requireOpenWindow(t, c, Window{Name: "test"})
+
+	_, handled, err := c.PERFORM(TaskSetTitle{Name: "test", Title: "New Title"})
+	require.NoError(t, err)
+	assert.True(t, handled)
+
+	pw, ok := svc.Manager().Get("test")
+	require.True(t, ok)
+	assert.Equal(t, "New Title", pw.Title())
+}
+
+func TestTaskSetTitle_Bad(t *testing.T) {
+	_, c := newTestWindowService(t)
+	_, handled, err := c.PERFORM(TaskSetTitle{Name: "nonexistent", Title: "Nope"})
+	assert.True(t, handled)
+	assert.Error(t, err)
+}
+
+// --- TaskSetAlwaysOnTop ---
+
+func TestTaskSetAlwaysOnTop_Good(t *testing.T) {
+	svc, c := newTestWindowService(t)
+	_ = requireOpenWindow(t, c, Window{Name: "test"})
+
+	_, handled, err := c.PERFORM(TaskSetAlwaysOnTop{Name: "test", AlwaysOnTop: true})
+	require.NoError(t, err)
+	assert.True(t, handled)
+
+	pw, ok := svc.Manager().Get("test")
+	require.True(t, ok)
+	mw := pw.(*mockWindow)
+	assert.True(t, mw.alwaysOnTop)
+}
+
+func TestTaskSetAlwaysOnTop_Bad(t *testing.T) {
+	_, c := newTestWindowService(t)
+	_, handled, err := c.PERFORM(TaskSetAlwaysOnTop{Name: "nonexistent", AlwaysOnTop: true})
+	assert.True(t, handled)
+	assert.Error(t, err)
+}
+
+// --- TaskSetBackgroundColour ---
+
+func TestTaskSetBackgroundColour_Good(t *testing.T) {
+	svc, c := newTestWindowService(t)
+	_ = requireOpenWindow(t, c, Window{Name: "test"})
+
+	_, handled, err := c.PERFORM(TaskSetBackgroundColour{
+		Name: "test", Red: 10, Green: 20, Blue: 30, Alpha: 40,
+	})
+	require.NoError(t, err)
+	assert.True(t, handled)
+
+	pw, ok := svc.Manager().Get("test")
+	require.True(t, ok)
+	mw := pw.(*mockWindow)
+	assert.Equal(t, [4]uint8{10, 20, 30, 40}, mw.backgroundColour)
+}
+
+func TestTaskSetBackgroundColour_Bad(t *testing.T) {
+	_, c := newTestWindowService(t)
+	_, handled, err := c.PERFORM(TaskSetBackgroundColour{Name: "nonexistent", Red: 1, Green: 2, Blue: 3, Alpha: 4})
+	assert.True(t, handled)
+	assert.Error(t, err)
+}
+
+// --- TaskSetVisibility ---
+
+func TestTaskSetVisibility_Good(t *testing.T) {
+	svc, c := newTestWindowService(t)
+	_ = requireOpenWindow(t, c, Window{Name: "test"})
+
+	_, handled, err := c.PERFORM(TaskSetVisibility{Name: "test", Visible: true})
+	require.NoError(t, err)
+	assert.True(t, handled)
+
+	pw, ok := svc.Manager().Get("test")
+	require.True(t, ok)
+	mw := pw.(*mockWindow)
+	assert.True(t, mw.visible)
+
+	// Now hide it
+	_, handled, err = c.PERFORM(TaskSetVisibility{Name: "test", Visible: false})
+	require.NoError(t, err)
+	assert.True(t, handled)
+	assert.False(t, mw.visible)
+}
+
+func TestTaskSetVisibility_Bad(t *testing.T) {
+	_, c := newTestWindowService(t)
+	_, handled, err := c.PERFORM(TaskSetVisibility{Name: "nonexistent", Visible: true})
+	assert.True(t, handled)
+	assert.Error(t, err)
+}
+
+// --- TaskFullscreen ---
+
+func TestTaskFullscreen_Good(t *testing.T) {
+	svc, c := newTestWindowService(t)
+	_ = requireOpenWindow(t, c, Window{Name: "test"})
+
+	// Enter fullscreen
+	_, handled, err := c.PERFORM(TaskFullscreen{Name: "test", Fullscreen: true})
+	require.NoError(t, err)
+	assert.True(t, handled)
+
+	pw, ok := svc.Manager().Get("test")
+	require.True(t, ok)
+	mw := pw.(*mockWindow)
+	assert.True(t, mw.fullscreened)
+
+	// Exit fullscreen
+	_, handled, err = c.PERFORM(TaskFullscreen{Name: "test", Fullscreen: false})
+	require.NoError(t, err)
+	assert.True(t, handled)
+	assert.False(t, mw.fullscreened)
+}
+
+func TestTaskFullscreen_Bad(t *testing.T) {
+	_, c := newTestWindowService(t)
+	_, handled, err := c.PERFORM(TaskFullscreen{Name: "nonexistent", Fullscreen: true})
+	assert.True(t, handled)
+	assert.Error(t, err)
+}
+
+// --- TaskSaveLayout ---
+
+func TestTaskSaveLayout_Good(t *testing.T) {
+	svc, c := newTestWindowService(t)
+	_ = requireOpenWindow(t, c, Window{Name: "editor", Width: 960, Height: 1080, X: 0, Y: 0})
+	_ = requireOpenWindow(t, c, Window{Name: "terminal", Width: 960, Height: 1080, X: 960, Y: 0})
+
+	_, handled, err := c.PERFORM(TaskSaveLayout{Name: "coding"})
+	require.NoError(t, err)
+	assert.True(t, handled)
+
+	// Verify layout was saved with correct window states
+	layout, ok := svc.Manager().Layout().GetLayout("coding")
+	assert.True(t, ok)
+	assert.Equal(t, "coding", layout.Name)
+	assert.Len(t, layout.Windows, 2)
+
+	editorState, ok := layout.Windows["editor"]
+	assert.True(t, ok)
+	assert.Equal(t, 0, editorState.X)
+	assert.Equal(t, 960, editorState.Width)
+
+	termState, ok := layout.Windows["terminal"]
+	assert.True(t, ok)
+	assert.Equal(t, 960, termState.X)
+	assert.Equal(t, 960, termState.Width)
+}
+
+func TestTaskSaveLayout_Bad(t *testing.T) {
+	_, c := newTestWindowService(t)
+	// Saving an empty layout with empty name returns an error from LayoutManager
+	_, handled, err := c.PERFORM(TaskSaveLayout{Name: ""})
+	assert.True(t, handled)
+	assert.Error(t, err)
+}
+
+// --- TaskRestoreLayout ---
+
+func TestTaskRestoreLayout_Good(t *testing.T) {
+	svc, c := newTestWindowService(t)
+	// Open windows
+	_ = requireOpenWindow(t, c, Window{Name: "editor", Width: 800, Height: 600, X: 0, Y: 0})
+	_ = requireOpenWindow(t, c, Window{Name: "terminal", Width: 800, Height: 600, X: 0, Y: 0})
+
+	// Save a layout with specific positions
+	_, _, _ = c.PERFORM(TaskSaveLayout{Name: "coding"})
+
+	// Move the windows to different positions
+	_, _, _ = c.PERFORM(TaskSetPosition{Name: "editor", X: 500, Y: 500})
+	_, _, _ = c.PERFORM(TaskSetPosition{Name: "terminal", X: 600, Y: 600})
+
+	// Restore the layout
+	_, handled, err := c.PERFORM(TaskRestoreLayout{Name: "coding"})
+	require.NoError(t, err)
+	assert.True(t, handled)
+
+	// Verify windows were moved back to saved positions
+	pw, ok := svc.Manager().Get("editor")
+	require.True(t, ok)
+	x, y := pw.Position()
+	assert.Equal(t, 0, x)
+	assert.Equal(t, 0, y)
+
+	pw2, ok := svc.Manager().Get("terminal")
+	require.True(t, ok)
+	x2, y2 := pw2.Position()
+	assert.Equal(t, 0, x2)
+	assert.Equal(t, 0, y2)
+
+	editorState, ok := svc.Manager().State().GetState("editor")
+	require.True(t, ok)
+	assert.Equal(t, 0, editorState.X)
+	assert.Equal(t, 0, editorState.Y)
+
+	terminalState, ok := svc.Manager().State().GetState("terminal")
+	require.True(t, ok)
+	assert.Equal(t, 0, terminalState.X)
+	assert.Equal(t, 0, terminalState.Y)
+}
+
+func TestTaskRestoreLayout_Bad(t *testing.T) {
+	_, c := newTestWindowService(t)
+	_, handled, err := c.PERFORM(TaskRestoreLayout{Name: "nonexistent"})
+	assert.True(t, handled)
+	assert.Error(t, err)
+}
+
+// --- TaskStackWindows ---
+
+func TestTaskStackWindows_Good(t *testing.T) {
+	svc, c := newTestWindowService(t)
+	_ = requireOpenWindow(t, c, Window{Name: "s1", Width: 800, Height: 600})
+	_ = requireOpenWindow(t, c, Window{Name: "s2", Width: 800, Height: 600})
+
+	_, handled, err := c.PERFORM(TaskStackWindows{Windows: []string{"s1", "s2"}, OffsetX: 25, OffsetY: 35})
+	require.NoError(t, err)
+	assert.True(t, handled)
+
+	pw, ok := svc.Manager().Get("s2")
+	require.True(t, ok)
+	x, y := pw.Position()
+	assert.Equal(t, 25, x)
+	assert.Equal(t, 35, y)
+}
+
+// --- TaskApplyWorkflow ---
+
+func TestTaskApplyWorkflow_Good(t *testing.T) {
+	svc, c := newTestWindowService(t)
+	_ = requireOpenWindow(t, c, Window{Name: "editor", Width: 800, Height: 600})
+	_ = requireOpenWindow(t, c, Window{Name: "terminal", Width: 800, Height: 600})
+
+	_, handled, err := c.PERFORM(TaskApplyWorkflow{Workflow: "side-by-side"})
+	require.NoError(t, err)
+	assert.True(t, handled)
+
+	editor, ok := svc.Manager().Get("editor")
+	require.True(t, ok)
+	x, y := editor.Position()
+	assert.Equal(t, 0, x)
+	assert.Equal(t, 0, y)
+
+	terminal, ok := svc.Manager().Get("terminal")
+	require.True(t, ok)
+	x, y = terminal.Position()
+	assert.Equal(t, 960, x)
+	assert.Equal(t, 0, y)
+}

pkg/window/state.go

@@ -7,6 +7,8 @@ import (
 	"path/filepath"
 	"sync"
 	"time"
+
+	coreio "forge.lthn.ai/core/go-io"
 )
 
 // WindowState holds the persisted position/size of a window.
@@ -25,6 +27,7 @@ type WindowState struct {
 // StateManager persists window positions to ~/.config/Core/window_state.json.
 type StateManager struct {
 	configDir string
+	statePath string
 	states    map[string]WindowState
 	mu        sync.RWMutex
 	saveTimer *time.Timer
@@ -55,24 +58,49 @@ func NewStateManagerWithDir(configDir string) *StateManager {
 }
 
 func (sm *StateManager) filePath() string {
+	if sm.statePath != "" {
+		return sm.statePath
+	}
 	return filepath.Join(sm.configDir, "window_state.json")
 }
 
-func (sm *StateManager) load() {
-	if sm.configDir == "" {
+func (sm *StateManager) dataDir() string {
+	if sm.statePath != "" {
+		return filepath.Dir(sm.statePath)
+	}
+	return sm.configDir
+}
+
+func (sm *StateManager) SetPath(path string) {
+	if path == "" {
 		return
 	}
-	data, err := os.ReadFile(sm.filePath())
+	sm.mu.Lock()
+	if sm.saveTimer != nil {
+		sm.saveTimer.Stop()
+		sm.saveTimer = nil
+	}
+	sm.statePath = path
+	sm.states = make(map[string]WindowState)
+	sm.mu.Unlock()
+	sm.load()
+}
+
+func (sm *StateManager) load() {
+	if sm.configDir == "" && sm.statePath == "" {
+		return
+	}
+	content, err := coreio.Local.Read(sm.filePath())
 	if err != nil {
 		return
 	}
 	sm.mu.Lock()
 	defer sm.mu.Unlock()
-	_ = json.Unmarshal(data, &sm.states)
+	_ = json.Unmarshal([]byte(content), &sm.states)
 }
 
 func (sm *StateManager) save() {
-	if sm.configDir == "" {
+	if sm.configDir == "" && sm.statePath == "" {
 		return
 	}
 	sm.mu.RLock()
@@ -81,8 +109,10 @@ func (sm *StateManager) save() {
 	if err != nil {
 		return
 	}
-	_ = os.MkdirAll(sm.configDir, 0o755)
-	_ = os.WriteFile(sm.filePath(), data, 0o644)
+	if dir := sm.dataDir(); dir != "" {
+		_ = coreio.Local.EnsureDir(dir)
+	}
+	_ = coreio.Local.Write(sm.filePath(), string(data))
 }
 
 func (sm *StateManager) scheduleSave() {

pkg/window/tiling.go

@@ -1,7 +1,7 @@
 // pkg/window/tiling.go
 package window
 
-import "fmt"
+import coreerr "forge.lthn.ai/core/go-log"
 
 // TileMode defines how windows are arranged.
 type TileMode int
@@ -44,6 +44,16 @@ const (
 	SnapCenter
 )
 
+var snapPositionNames = map[SnapPosition]string{
+	SnapLeft: "left", SnapRight: "right",
+	SnapTop: "top", SnapBottom: "bottom",
+	SnapTopLeft: "top-left", SnapTopRight: "top-right",
+	SnapBottomLeft: "bottom-left", SnapBottomRight: "bottom-right",
+	SnapCenter: "center",
+}
+
+func (p SnapPosition) String() string { return snapPositionNames[p] }
+
 // WorkflowLayout is a predefined arrangement for common tasks.
 type WorkflowLayout int
 
@@ -61,18 +71,36 @@ var workflowNames = map[WorkflowLayout]string{
 
 func (w WorkflowLayout) String() string { return workflowNames[w] }
 
+func layoutOrigin(origin []int) (int, int) {
+	if len(origin) == 0 {
+		return 0, 0
+	}
+	if len(origin) == 1 {
+		return origin[0], 0
+	}
+	return origin[0], origin[1]
+}
+
+func (m *Manager) captureState(pw PlatformWindow) {
+	if m.state == nil || pw == nil {
+		return
+	}
+	m.state.CaptureState(pw)
+}
+
 // TileWindows arranges the named windows in the given mode across the screen area.
-func (m *Manager) TileWindows(mode TileMode, names []string, screenW, screenH int) error {
+func (m *Manager) TileWindows(mode TileMode, names []string, screenW, screenH int, origin ...int) error {
+	originX, originY := layoutOrigin(origin)
 	windows := make([]PlatformWindow, 0, len(names))
 	for _, name := range names {
 		pw, ok := m.Get(name)
 		if !ok {
-			return fmt.Errorf("window %q not found", name)
+			return coreerr.E("window.Manager.TileWindows", "window not found: "+name, nil)
 		}
 		windows = append(windows, pw)
 	}
 	if len(windows) == 0 {
-		return fmt.Errorf("no windows to tile")
+		return coreerr.E("window.Manager.TileWindows", "no windows to tile", nil)
 	}
 
 	halfW, halfH := screenW/2, screenH/2
@@ -81,8 +109,9 @@ func (m *Manager) TileWindows(mode TileMode, names []string, screenW, screenH in
 	case TileModeLeftRight:
 		w := screenW / len(windows)
 		for i, pw := range windows {
-			pw.SetPosition(i*w, 0)
+			pw.SetPosition(originX+i*w, originY)
 			pw.SetSize(w, screenH)
+			m.captureState(pw)
 		}
 	case TileModeGrid:
 		cols := 2
@@ -95,110 +124,124 @@ func (m *Manager) TileWindows(mode TileMode, names []string, screenW, screenH in
 			col := i % cols
 			rows := (len(windows) + cols - 1) / cols
 			cellH := screenH / rows
-			pw.SetPosition(col*cellW, row*cellH)
+			pw.SetPosition(originX+col*cellW, originY+row*cellH)
 			pw.SetSize(cellW, cellH)
+			m.captureState(pw)
 		}
 	case TileModeLeftHalf:
 		for _, pw := range windows {
-			pw.SetPosition(0, 0)
+			pw.SetPosition(originX, originY)
 			pw.SetSize(halfW, screenH)
+			m.captureState(pw)
 		}
 	case TileModeRightHalf:
 		for _, pw := range windows {
-			pw.SetPosition(halfW, 0)
+			pw.SetPosition(originX+halfW, originY)
 			pw.SetSize(halfW, screenH)
+			m.captureState(pw)
 		}
 	case TileModeTopHalf:
 		for _, pw := range windows {
-			pw.SetPosition(0, 0)
+			pw.SetPosition(originX, originY)
 			pw.SetSize(screenW, halfH)
+			m.captureState(pw)
 		}
 	case TileModeBottomHalf:
 		for _, pw := range windows {
-			pw.SetPosition(0, halfH)
+			pw.SetPosition(originX, originY+halfH)
 			pw.SetSize(screenW, halfH)
+			m.captureState(pw)
 		}
 	case TileModeTopLeft:
 		for _, pw := range windows {
-			pw.SetPosition(0, 0)
+			pw.SetPosition(originX, originY)
 			pw.SetSize(halfW, halfH)
+			m.captureState(pw)
 		}
 	case TileModeTopRight:
 		for _, pw := range windows {
-			pw.SetPosition(halfW, 0)
+			pw.SetPosition(originX+halfW, originY)
 			pw.SetSize(halfW, halfH)
+			m.captureState(pw)
 		}
 	case TileModeBottomLeft:
 		for _, pw := range windows {
-			pw.SetPosition(0, halfH)
+			pw.SetPosition(originX, originY+halfH)
 			pw.SetSize(halfW, halfH)
+			m.captureState(pw)
 		}
 	case TileModeBottomRight:
 		for _, pw := range windows {
-			pw.SetPosition(halfW, halfH)
+			pw.SetPosition(originX+halfW, originY+halfH)
 			pw.SetSize(halfW, halfH)
+			m.captureState(pw)
 		}
 	}
 	return nil
 }
 
 // SnapWindow snaps a window to a screen edge/corner/centre.
-func (m *Manager) SnapWindow(name string, pos SnapPosition, screenW, screenH int) error {
+func (m *Manager) SnapWindow(name string, pos SnapPosition, screenW, screenH int, origin ...int) error {
+	originX, originY := layoutOrigin(origin)
 	pw, ok := m.Get(name)
 	if !ok {
-		return fmt.Errorf("window %q not found", name)
+		return coreerr.E("window.Manager.SnapWindow", "window not found: "+name, nil)
 	}
 
 	halfW, halfH := screenW/2, screenH/2
 
 	switch pos {
 	case SnapLeft:
-		pw.SetPosition(0, 0)
+		pw.SetPosition(originX, originY)
 		pw.SetSize(halfW, screenH)
 	case SnapRight:
-		pw.SetPosition(halfW, 0)
+		pw.SetPosition(originX+halfW, originY)
 		pw.SetSize(halfW, screenH)
 	case SnapTop:
-		pw.SetPosition(0, 0)
+		pw.SetPosition(originX, originY)
 		pw.SetSize(screenW, halfH)
 	case SnapBottom:
-		pw.SetPosition(0, halfH)
+		pw.SetPosition(originX, originY+halfH)
 		pw.SetSize(screenW, halfH)
 	case SnapTopLeft:
-		pw.SetPosition(0, 0)
+		pw.SetPosition(originX, originY)
 		pw.SetSize(halfW, halfH)
 	case SnapTopRight:
-		pw.SetPosition(halfW, 0)
+		pw.SetPosition(originX+halfW, originY)
 		pw.SetSize(halfW, halfH)
 	case SnapBottomLeft:
-		pw.SetPosition(0, halfH)
+		pw.SetPosition(originX, originY+halfH)
 		pw.SetSize(halfW, halfH)
 	case SnapBottomRight:
-		pw.SetPosition(halfW, halfH)
+		pw.SetPosition(originX+halfW, originY+halfH)
 		pw.SetSize(halfW, halfH)
 	case SnapCenter:
 		cw, ch := pw.Size()
-		pw.SetPosition((screenW-cw)/2, (screenH-ch)/2)
+		pw.SetPosition(originX+(screenW-cw)/2, originY+(screenH-ch)/2)
 	}
+	m.captureState(pw)
 	return nil
 }
 
 // StackWindows cascades windows with an offset.
-func (m *Manager) StackWindows(names []string, offsetX, offsetY int) error {
+func (m *Manager) StackWindows(names []string, offsetX, offsetY int, origin ...int) error {
+	originX, originY := layoutOrigin(origin)
 	for i, name := range names {
 		pw, ok := m.Get(name)
 		if !ok {
-			return fmt.Errorf("window %q not found", name)
+			return coreerr.E("window.Manager.StackWindows", "window not found: "+name, nil)
 		}
-		pw.SetPosition(i*offsetX, i*offsetY)
+		pw.SetPosition(originX+i*offsetX, originY+i*offsetY)
+		m.captureState(pw)
 	}
 	return nil
 }
 
 // ApplyWorkflow arranges windows in a predefined workflow layout.
-func (m *Manager) ApplyWorkflow(workflow WorkflowLayout, names []string, screenW, screenH int) error {
+func (m *Manager) ApplyWorkflow(workflow WorkflowLayout, names []string, screenW, screenH int, origin ...int) error {
+	originX, originY := layoutOrigin(origin)
 	if len(names) == 0 {
-		return fmt.Errorf("no windows for workflow")
+		return coreerr.E("window.Manager.ApplyWorkflow", "no windows for workflow", nil)
 	}
 
 	switch workflow {
@@ -206,36 +249,41 @@ func (m *Manager) ApplyWorkflow(workflow WorkflowLayout, names []string, screenW
 		// 70/30 split — main editor + terminal
 		mainW := screenW * 70 / 100
 		if pw, ok := m.Get(names[0]); ok {
-			pw.SetPosition(0, 0)
+			pw.SetPosition(originX, originY)
 			pw.SetSize(mainW, screenH)
+			m.captureState(pw)
 		}
 		if len(names) > 1 {
 			if pw, ok := m.Get(names[1]); ok {
-				pw.SetPosition(mainW, 0)
+				pw.SetPosition(originX+mainW, originY)
 				pw.SetSize(screenW-mainW, screenH)
+				m.captureState(pw)
 			}
 		}
 	case WorkflowDebugging:
 		// 60/40 split
 		mainW := screenW * 60 / 100
 		if pw, ok := m.Get(names[0]); ok {
-			pw.SetPosition(0, 0)
+			pw.SetPosition(originX, originY)
 			pw.SetSize(mainW, screenH)
+			m.captureState(pw)
 		}
 		if len(names) > 1 {
 			if pw, ok := m.Get(names[1]); ok {
-				pw.SetPosition(mainW, 0)
+				pw.SetPosition(originX+mainW, originY)
 				pw.SetSize(screenW-mainW, screenH)
+				m.captureState(pw)
 			}
 		}
 	case WorkflowPresenting:
 		// Maximise first window
 		if pw, ok := m.Get(names[0]); ok {
-			pw.SetPosition(0, 0)
+			pw.SetPosition(originX, originY)
 			pw.SetSize(screenW, screenH)
+			m.captureState(pw)
 		}
 	case WorkflowSideBySide:
-		return m.TileWindows(TileModeLeftRight, names, screenW, screenH)
+		return m.TileWindows(TileModeLeftRight, names, screenW, screenH, originX, originY)
 	}
 	return nil
 }

pkg/window/wails.go

@@ -16,28 +16,28 @@ func NewWailsPlatform(app *application.App) *WailsPlatform {
 	return &WailsPlatform{app: app}
 }
 
-func (wp *WailsPlatform) CreateWindow(opts PlatformWindowOptions) PlatformWindow {
+func (wp *WailsPlatform) CreateWindow(options PlatformWindowOptions) PlatformWindow {
 	wOpts := application.WebviewWindowOptions{
-		Name:              opts.Name,
-		Title:             opts.Title,
-		URL:               opts.URL,
-		Width:             opts.Width,
-		Height:            opts.Height,
-		X:                 opts.X,
-		Y:                 opts.Y,
-		MinWidth:          opts.MinWidth,
-		MinHeight:         opts.MinHeight,
-		MaxWidth:          opts.MaxWidth,
-		MaxHeight:         opts.MaxHeight,
-		Frameless:         opts.Frameless,
-		Hidden:            opts.Hidden,
-		AlwaysOnTop:       opts.AlwaysOnTop,
-		DisableResize:  opts.DisableResize,
-		EnableFileDrop: opts.EnableFileDrop,
-		BackgroundColour:  application.NewRGBA(opts.BackgroundColour[0], opts.BackgroundColour[1], opts.BackgroundColour[2], opts.BackgroundColour[3]),
+		Name:             options.Name,
+		Title:            options.Title,
+		URL:              options.URL,
+		Width:            options.Width,
+		Height:           options.Height,
+		X:                options.X,
+		Y:                options.Y,
+		MinWidth:         options.MinWidth,
+		MinHeight:        options.MinHeight,
+		MaxWidth:         options.MaxWidth,
+		MaxHeight:        options.MaxHeight,
+		Frameless:        options.Frameless,
+		Hidden:           options.Hidden,
+		AlwaysOnTop:      options.AlwaysOnTop,
+		DisableResize:    options.DisableResize,
+		EnableFileDrop:   options.EnableFileDrop,
+		BackgroundColour: application.NewRGBA(options.BackgroundColour[0], options.BackgroundColour[1], options.BackgroundColour[2], options.BackgroundColour[3]),
 	}
 	w := wp.app.Window.NewWithOptions(wOpts)
-	return &wailsWindow{w: w, title: opts.Title}
+	return &wailsWindow{w: w, title: options.Title}
 }
 
 func (wp *WailsPlatform) GetWindows() []PlatformWindow {
@@ -58,14 +58,14 @@ type wailsWindow struct {
 	title string
 }
 
-func (ww *wailsWindow) Name() string             { return ww.w.Name() }
-func (ww *wailsWindow) Title() string            { return ww.title }
-func (ww *wailsWindow) Position() (int, int)     { return ww.w.Position() }
-func (ww *wailsWindow) Size() (int, int)         { return ww.w.Size() }
-func (ww *wailsWindow) IsMaximised() bool        { return ww.w.IsMaximised() }
-func (ww *wailsWindow) IsFocused() bool          { return ww.w.IsFocused() }
-func (ww *wailsWindow) SetTitle(title string)    { ww.title = title; ww.w.SetTitle(title) }
-func (ww *wailsWindow) SetPosition(x, y int)     { ww.w.SetPosition(x, y) }
+func (ww *wailsWindow) Name() string              { return ww.w.Name() }
+func (ww *wailsWindow) Title() string             { return ww.title }
+func (ww *wailsWindow) Position() (int, int)      { return ww.w.Position() }
+func (ww *wailsWindow) Size() (int, int)          { return ww.w.Size() }
+func (ww *wailsWindow) IsMaximised() bool         { return ww.w.IsMaximised() }
+func (ww *wailsWindow) IsFocused() bool           { return ww.w.IsFocused() }
+func (ww *wailsWindow) SetTitle(title string)     { ww.title = title; ww.w.SetTitle(title) }
+func (ww *wailsWindow) SetPosition(x, y int)      { ww.w.SetPosition(x, y) }
 func (ww *wailsWindow) SetSize(width, height int) { ww.w.SetSize(width, height) }
 func (ww *wailsWindow) SetBackgroundColour(r, g, b, a uint8) {
 	ww.w.SetBackgroundColour(application.NewRGBA(r, g, b, a))
@@ -140,4 +140,3 @@ var _ PlatformWindow = (*wailsWindow)(nil)
 
 // Ensure WailsPlatform satisfies Platform at compile time.
 var _ Platform = (*WailsPlatform)(nil)
-

pkg/window/window.go

@@ -2,25 +2,26 @@
 package window
 
 import (
-	"fmt"
 	"sync"
+
+	coreerr "forge.lthn.ai/core/go-log"
 )
 
 // Window is CoreGUI's own window descriptor — NOT a Wails type alias.
 type Window struct {
-	Name              string
-	Title             string
-	URL               string
-	Width, Height     int
-	X, Y              int
+	Name                string
+	Title               string
+	URL                 string
+	Width, Height       int
+	X, Y                int
 	MinWidth, MinHeight int
 	MaxWidth, MaxHeight int
-	Frameless         bool
-	Hidden            bool
-	AlwaysOnTop       bool
-	BackgroundColour  [4]uint8
-	DisableResize     bool
-	EnableFileDrop    bool
+	Frameless           bool
+	Hidden              bool
+	AlwaysOnTop         bool
+	BackgroundColour    [4]uint8
+	DisableResize       bool
+	EnableFileDrop      bool
 }
 
 // ToPlatformOptions converts a Window to PlatformWindowOptions for the backend.
@@ -38,14 +39,17 @@ func (w *Window) ToPlatformOptions() PlatformWindowOptions {
 
 // Manager manages window lifecycle through a Platform backend.
 type Manager struct {
-	platform Platform
-	state    *StateManager
-	layout   *LayoutManager
-	windows  map[string]PlatformWindow
-	mu       sync.RWMutex
+	platform      Platform
+	state         *StateManager
+	layout        *LayoutManager
+	windows       map[string]PlatformWindow
+	defaultWidth  int
+	defaultHeight int
+	mu            sync.RWMutex
 }
 
 // NewManager creates a window Manager with the given platform backend.
+// window.NewManager(window.NewWailsPlatform(app))
 func NewManager(platform Platform) *Manager {
 	return &Manager{
 		platform: platform,
@@ -56,7 +60,7 @@ func NewManager(platform Platform) *Manager {
 }
 
 // NewManagerWithDir creates a window Manager with a custom config directory for state/layout persistence.
-// Useful for testing or when the default config directory is not appropriate.
+// window.NewManagerWithDir(window.NewMockPlatform(), t.TempDir())
 func NewManagerWithDir(platform Platform, configDir string) *Manager {
 	return &Manager{
 		platform: platform,
@@ -66,43 +70,82 @@ func NewManagerWithDir(platform Platform, configDir string) *Manager {
 	}
 }
 
-// Open creates a window using functional options, applies saved state, and tracks it.
-func (m *Manager) Open(opts ...WindowOption) (PlatformWindow, error) {
-	w, err := ApplyOptions(opts...)
-	if err != nil {
-		return nil, fmt.Errorf("window.Manager.Open: %w", err)
+func (m *Manager) SetDefaultWidth(width int) {
+	if width > 0 {
+		m.defaultWidth = width
 	}
-	return m.Create(w)
 }
 
-// Create creates a window from a Window descriptor.
+func (m *Manager) SetDefaultHeight(height int) {
+	if height > 0 {
+		m.defaultHeight = height
+	}
+}
+
+// Deprecated: use CreateWindow(Window{Name: "settings", URL: "/settings", Width: 800, Height: 600}).
+func (m *Manager) Open(options ...WindowOption) (PlatformWindow, error) {
+	w, err := ApplyOptions(options...)
+	if err != nil {
+		return nil, coreerr.E("window.Manager.Open", "failed to apply options", err)
+	}
+	return m.CreateWindow(*w)
+}
+
+// CreateWindow creates a window from a Window descriptor.
+// window.NewManager(window.NewWailsPlatform(app)).CreateWindow(window.Window{Name: "settings", URL: "/settings", Width: 800, Height: 600})
+func (m *Manager) CreateWindow(spec Window) (PlatformWindow, error) {
+	_, pw, err := m.createWindow(spec)
+	return pw, err
+}
+
+// Deprecated: use CreateWindow(Window{Name: "settings", URL: "/settings", Width: 800, Height: 600}).
 func (m *Manager) Create(w *Window) (PlatformWindow, error) {
-	if w.Name == "" {
-		w.Name = "main"
+	if w == nil {
+		return nil, coreerr.E("window.Manager.Create", "window descriptor is required", nil)
 	}
-	if w.Title == "" {
-		w.Title = "Core"
+	spec, pw, err := m.createWindow(*w)
+	if err != nil {
+		return nil, err
 	}
-	if w.Width == 0 {
-		w.Width = 1280
+	*w = spec
+	return pw, nil
+}
+
+func (m *Manager) createWindow(spec Window) (Window, PlatformWindow, error) {
+	if spec.Name == "" {
+		spec.Name = "main"
 	}
-	if w.Height == 0 {
-		w.Height = 800
+	if spec.Title == "" {
+		spec.Title = "Core"
 	}
-	if w.URL == "" {
-		w.URL = "/"
+	if spec.Width == 0 {
+		if m.defaultWidth > 0 {
+			spec.Width = m.defaultWidth
+		} else {
+			spec.Width = 1280
+		}
+	}
+	if spec.Height == 0 {
+		if m.defaultHeight > 0 {
+			spec.Height = m.defaultHeight
+		} else {
+			spec.Height = 800
+		}
+	}
+	if spec.URL == "" {
+		spec.URL = "/"
 	}
 
-	// Apply saved state if available
-	m.state.ApplyState(w)
+	// Apply saved state if available.
+	m.state.ApplyState(&spec)
 
-	pw := m.platform.CreateWindow(w.ToPlatformOptions())
+	pw := m.platform.CreateWindow(spec.ToPlatformOptions())
 
 	m.mu.Lock()
-	m.windows[w.Name] = pw
+	m.windows[spec.Name] = pw
 	m.mu.Unlock()
 
-	return pw, nil
+	return spec, pw, nil
 }
 
 // Get returns a tracked window by name.

pkg/window/window_test.go

@@ -8,7 +8,7 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
-func TestWindowDefaults(t *testing.T) {
+func TestWindowDefaults_Good(t *testing.T) {
 	w := &Window{}
 	assert.Equal(t, "", w.Name)
 	assert.Equal(t, 0, w.Width)
@@ -91,26 +91,48 @@ func newTestManager() (*Manager, *mockPlatform) {
 	return m, p
 }
 
-func TestManager_Open_Good(t *testing.T) {
-	m, p := newTestManager()
-	pw, err := m.Open(WithName("test"), WithTitle("Test"), WithURL("/test"), WithSize(800, 600))
+func requireCreateWindow(t *testing.T, m *Manager, w Window) PlatformWindow {
+	t.Helper()
+	pw, err := m.CreateWindow(w)
 	require.NoError(t, err)
+	return pw
+}
+
+func TestManager_CreateWindow_Good(t *testing.T) {
+	m, p := newTestManager()
+	pw := requireCreateWindow(t, m, Window{
+		Name:   "test",
+		Title:  "Test",
+		URL:    "/test",
+		Width:  800,
+		Height: 600,
+	})
 	assert.NotNil(t, pw)
 	assert.Equal(t, "test", pw.Name())
 	assert.Len(t, p.windows, 1)
 }
 
-func TestManager_Open_Defaults_Good(t *testing.T) {
+func TestManager_CreateWindow_Defaults_Good(t *testing.T) {
 	m, _ := newTestManager()
-	pw, err := m.Open()
-	require.NoError(t, err)
+	pw := requireCreateWindow(t, m, Window{})
 	assert.Equal(t, "main", pw.Name())
 	w, h := pw.Size()
 	assert.Equal(t, 1280, w)
 	assert.Equal(t, 800, h)
 }
 
-func TestManager_Open_Bad(t *testing.T) {
+func TestManager_CreateWindow_CustomDefaults_Good(t *testing.T) {
+	m, _ := newTestManager()
+	m.SetDefaultWidth(1440)
+	m.SetDefaultHeight(900)
+
+	pw := requireCreateWindow(t, m, Window{})
+	w, h := pw.Size()
+	assert.Equal(t, 1440, w)
+	assert.Equal(t, 900, h)
+}
+
+func TestManager_Open_Compatibility_Bad(t *testing.T) {
 	m, _ := newTestManager()
 	_, err := m.Open(func(w *Window) error { return assert.AnError })
 	assert.Error(t, err)
@@ -118,7 +140,7 @@ func TestManager_Open_Bad(t *testing.T) {
 
 func TestManager_Get_Good(t *testing.T) {
 	m, _ := newTestManager()
-	_, _ = m.Open(WithName("findme"))
+	_ = requireCreateWindow(t, m, Window{Name: "findme"})
 	pw, ok := m.Get("findme")
 	assert.True(t, ok)
 	assert.Equal(t, "findme", pw.Name())
@@ -132,8 +154,8 @@ func TestManager_Get_Bad(t *testing.T) {
 
 func TestManager_List_Good(t *testing.T) {
 	m, _ := newTestManager()
-	_, _ = m.Open(WithName("a"))
-	_, _ = m.Open(WithName("b"))
+	_ = requireCreateWindow(t, m, Window{Name: "a"})
+	_ = requireCreateWindow(t, m, Window{Name: "b"})
 	names := m.List()
 	assert.Len(t, names, 2)
 	assert.Contains(t, names, "a")
@@ -142,137 +164,12 @@ func TestManager_List_Good(t *testing.T) {
 
 func TestManager_Remove_Good(t *testing.T) {
 	m, _ := newTestManager()
-	_, _ = m.Open(WithName("temp"))
+	_ = requireCreateWindow(t, m, Window{Name: "temp"})
 	m.Remove("temp")
 	_, ok := m.Get("temp")
 	assert.False(t, ok)
 }
 
-// --- StateManager Tests ---
-
-// newTestStateManager creates a clean StateManager with a temp dir for testing.
-func newTestStateManager(t *testing.T) *StateManager {
-	return &StateManager{
-		configDir: t.TempDir(),
-		states:    make(map[string]WindowState),
-	}
-}
-
-func TestStateManager_SetGet_Good(t *testing.T) {
-	sm := newTestStateManager(t)
-	state := WindowState{X: 100, Y: 200, Width: 800, Height: 600, Maximized: false}
-	sm.SetState("main", state)
-	got, ok := sm.GetState("main")
-	assert.True(t, ok)
-	assert.Equal(t, 100, got.X)
-	assert.Equal(t, 800, got.Width)
-}
-
-func TestStateManager_SetGet_Bad(t *testing.T) {
-	sm := newTestStateManager(t)
-	_, ok := sm.GetState("nonexistent")
-	assert.False(t, ok)
-}
-
-func TestStateManager_CaptureState_Good(t *testing.T) {
-	sm := newTestStateManager(t)
-	w := &mockWindow{name: "cap", x: 50, y: 60, width: 1024, height: 768, maximised: true}
-	sm.CaptureState(w)
-	got, ok := sm.GetState("cap")
-	assert.True(t, ok)
-	assert.Equal(t, 50, got.X)
-	assert.Equal(t, 1024, got.Width)
-	assert.True(t, got.Maximized)
-}
-
-func TestStateManager_ApplyState_Good(t *testing.T) {
-	sm := newTestStateManager(t)
-	sm.SetState("win", WindowState{X: 10, Y: 20, Width: 640, Height: 480})
-	w := &Window{Name: "win", Width: 1280, Height: 800}
-	sm.ApplyState(w)
-	assert.Equal(t, 10, w.X)
-	assert.Equal(t, 20, w.Y)
-	assert.Equal(t, 640, w.Width)
-	assert.Equal(t, 480, w.Height)
-}
-
-func TestStateManager_ListStates_Good(t *testing.T) {
-	sm := newTestStateManager(t)
-	sm.SetState("a", WindowState{Width: 100})
-	sm.SetState("b", WindowState{Width: 200})
-	names := sm.ListStates()
-	assert.Len(t, names, 2)
-}
-
-func TestStateManager_Clear_Good(t *testing.T) {
-	sm := newTestStateManager(t)
-	sm.SetState("a", WindowState{Width: 100})
-	sm.Clear()
-	names := sm.ListStates()
-	assert.Empty(t, names)
-}
-
-func TestStateManager_Persistence_Good(t *testing.T) {
-	dir := t.TempDir()
-	sm1 := &StateManager{configDir: dir, states: make(map[string]WindowState)}
-	sm1.SetState("persist", WindowState{X: 42, Y: 84, Width: 500, Height: 300})
-	sm1.ForceSync()
-
-	sm2 := &StateManager{configDir: dir, states: make(map[string]WindowState)}
-	sm2.load()
-	got, ok := sm2.GetState("persist")
-	assert.True(t, ok)
-	assert.Equal(t, 42, got.X)
-	assert.Equal(t, 500, got.Width)
-}
-
-// --- LayoutManager Tests ---
-
-// newTestLayoutManager creates a clean LayoutManager with a temp dir for testing.
-func newTestLayoutManager(t *testing.T) *LayoutManager {
-	return &LayoutManager{
-		configDir: t.TempDir(),
-		layouts:   make(map[string]Layout),
-	}
-}
-
-func TestLayoutManager_SaveGet_Good(t *testing.T) {
-	lm := newTestLayoutManager(t)
-	states := map[string]WindowState{
-		"editor":   {X: 0, Y: 0, Width: 960, Height: 1080},
-		"terminal": {X: 960, Y: 0, Width: 960, Height: 1080},
-	}
-	err := lm.SaveLayout("coding", states)
-	require.NoError(t, err)
-
-	layout, ok := lm.GetLayout("coding")
-	assert.True(t, ok)
-	assert.Equal(t, "coding", layout.Name)
-	assert.Len(t, layout.Windows, 2)
-}
-
-func TestLayoutManager_GetLayout_Bad(t *testing.T) {
-	lm := newTestLayoutManager(t)
-	_, ok := lm.GetLayout("nonexistent")
-	assert.False(t, ok)
-}
-
-func TestLayoutManager_ListLayouts_Good(t *testing.T) {
-	lm := newTestLayoutManager(t)
-	_ = lm.SaveLayout("a", map[string]WindowState{})
-	_ = lm.SaveLayout("b", map[string]WindowState{})
-	layouts := lm.ListLayouts()
-	assert.Len(t, layouts, 2)
-}
-
-func TestLayoutManager_DeleteLayout_Good(t *testing.T) {
-	lm := newTestLayoutManager(t)
-	_ = lm.SaveLayout("temp", map[string]WindowState{})
-	lm.DeleteLayout("temp")
-	_, ok := lm.GetLayout("temp")
-	assert.False(t, ok)
-}
-
 // --- Tiling Tests ---
 
 func TestTileMode_String_Good(t *testing.T) {
@@ -282,8 +179,8 @@ func TestTileMode_String_Good(t *testing.T) {
 
 func TestManager_TileWindows_Good(t *testing.T) {
 	m, _ := newTestManager()
-	_, _ = m.Open(WithName("a"), WithSize(800, 600))
-	_, _ = m.Open(WithName("b"), WithSize(800, 600))
+	_ = requireCreateWindow(t, m, Window{Name: "a", Width: 800, Height: 600})
+	_ = requireCreateWindow(t, m, Window{Name: "b", Width: 800, Height: 600})
 	err := m.TileWindows(TileModeLeftRight, []string{"a", "b"}, 1920, 1080)
 	require.NoError(t, err)
 	a, _ := m.Get("a")
@@ -302,7 +199,7 @@ func TestManager_TileWindows_Bad(t *testing.T) {
 
 func TestManager_SnapWindow_Good(t *testing.T) {
 	m, _ := newTestManager()
-	_, _ = m.Open(WithName("snap"), WithSize(800, 600))
+	_ = requireCreateWindow(t, m, Window{Name: "snap", Width: 800, Height: 600})
 	err := m.SnapWindow("snap", SnapLeft, 1920, 1080)
 	require.NoError(t, err)
 	w, _ := m.Get("snap")
@@ -314,8 +211,8 @@ func TestManager_SnapWindow_Good(t *testing.T) {
 
 func TestManager_StackWindows_Good(t *testing.T) {
 	m, _ := newTestManager()
-	_, _ = m.Open(WithName("s1"), WithSize(800, 600))
-	_, _ = m.Open(WithName("s2"), WithSize(800, 600))
+	_ = requireCreateWindow(t, m, Window{Name: "s1", Width: 800, Height: 600})
+	_ = requireCreateWindow(t, m, Window{Name: "s2", Width: 800, Height: 600})
 	err := m.StackWindows([]string{"s1", "s2"}, 30, 30)
 	require.NoError(t, err)
 	s2, _ := m.Get("s2")
@@ -328,3 +225,185 @@ func TestWorkflowLayout_Good(t *testing.T) {
 	assert.Equal(t, "coding", WorkflowCoding.String())
 	assert.Equal(t, "debugging", WorkflowDebugging.String())
 }
+
+// --- Comprehensive Tiling Tests ---
+
+func TestTileWindows_AllModes_Good(t *testing.T) {
+	const screenW, screenH = 1920, 1080
+	halfW, halfH := screenW/2, screenH/2
+
+	tests := []struct {
+		name       string
+		mode       TileMode
+		wantX      int
+		wantY      int
+		wantWidth  int
+		wantHeight int
+	}{
+		{"LeftHalf", TileModeLeftHalf, 0, 0, halfW, screenH},
+		{"RightHalf", TileModeRightHalf, halfW, 0, halfW, screenH},
+		{"TopHalf", TileModeTopHalf, 0, 0, screenW, halfH},
+		{"BottomHalf", TileModeBottomHalf, 0, halfH, screenW, halfH},
+		{"TopLeft", TileModeTopLeft, 0, 0, halfW, halfH},
+		{"TopRight", TileModeTopRight, halfW, 0, halfW, halfH},
+		{"BottomLeft", TileModeBottomLeft, 0, halfH, halfW, halfH},
+		{"BottomRight", TileModeBottomRight, halfW, halfH, halfW, halfH},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			m, _ := newTestManager()
+			_ = requireCreateWindow(t, m, Window{Name: "win", Width: 800, Height: 600})
+
+			err := m.TileWindows(tc.mode, []string{"win"}, screenW, screenH)
+			require.NoError(t, err)
+
+			pw, ok := m.Get("win")
+			require.True(t, ok)
+
+			x, y := pw.Position()
+			w, h := pw.Size()
+			assert.Equal(t, tc.wantX, x, "x position")
+			assert.Equal(t, tc.wantY, y, "y position")
+			assert.Equal(t, tc.wantWidth, w, "width")
+			assert.Equal(t, tc.wantHeight, h, "height")
+		})
+	}
+}
+
+func TestSnapWindow_AllPositions_Good(t *testing.T) {
+	const screenW, screenH = 1920, 1080
+	halfW, halfH := screenW/2, screenH/2
+
+	tests := []struct {
+		name       string
+		pos        SnapPosition
+		initW      int
+		initH      int
+		wantX      int
+		wantY      int
+		wantWidth  int
+		wantHeight int
+	}{
+		{"Right", SnapRight, 800, 600, halfW, 0, halfW, screenH},
+		{"Top", SnapTop, 800, 600, 0, 0, screenW, halfH},
+		{"Bottom", SnapBottom, 800, 600, 0, halfH, screenW, halfH},
+		{"TopLeft", SnapTopLeft, 800, 600, 0, 0, halfW, halfH},
+		{"TopRight", SnapTopRight, 800, 600, halfW, 0, halfW, halfH},
+		{"BottomLeft", SnapBottomLeft, 800, 600, 0, halfH, halfW, halfH},
+		{"BottomRight", SnapBottomRight, 800, 600, halfW, halfH, halfW, halfH},
+		{"Center", SnapCenter, 800, 600, (screenW - 800) / 2, (screenH - 600) / 2, 800, 600},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			m, _ := newTestManager()
+			_ = requireCreateWindow(t, m, Window{Name: "snap", Width: tc.initW, Height: tc.initH})
+
+			err := m.SnapWindow("snap", tc.pos, screenW, screenH)
+			require.NoError(t, err)
+
+			pw, ok := m.Get("snap")
+			require.True(t, ok)
+
+			x, y := pw.Position()
+			w, h := pw.Size()
+			assert.Equal(t, tc.wantX, x, "x position")
+			assert.Equal(t, tc.wantY, y, "y position")
+			assert.Equal(t, tc.wantWidth, w, "width")
+			assert.Equal(t, tc.wantHeight, h, "height")
+		})
+	}
+}
+
+func TestStackWindows_ThreeWindows_Good(t *testing.T) {
+	m, _ := newTestManager()
+	names := []string{"s1", "s2", "s3"}
+	for _, name := range names {
+		_ = requireCreateWindow(t, m, Window{Name: name, Width: 800, Height: 600})
+	}
+
+	err := m.StackWindows(names, 30, 30)
+	require.NoError(t, err)
+
+	for i, name := range names {
+		pw, ok := m.Get(name)
+		require.True(t, ok, "window %s should exist", name)
+		x, y := pw.Position()
+		assert.Equal(t, i*30, x, "window %s x position", name)
+		assert.Equal(t, i*30, y, "window %s y position", name)
+	}
+}
+
+func TestApplyWorkflow_AllLayouts_Good(t *testing.T) {
+	const screenW, screenH = 1920, 1080
+
+	tests := []struct {
+		name     string
+		workflow WorkflowLayout
+		// Expected positions/sizes for the first two windows.
+		// For WorkflowSideBySide, TileWindows(LeftRight) divides equally.
+		win0X, win0Y, win0W, win0H int
+		win1X, win1Y, win1W, win1H int
+	}{
+		{
+			"Coding",
+			WorkflowCoding,
+			0, 0, 1344, screenH, // 70% of 1920 = 1344
+			1344, 0, screenW - 1344, screenH, // remaining 30%
+		},
+		{
+			"Debugging",
+			WorkflowDebugging,
+			0, 0, 1152, screenH, // 60% of 1920 = 1152
+			1152, 0, screenW - 1152, screenH, // remaining 40%
+		},
+		{
+			"Presenting",
+			WorkflowPresenting,
+			0, 0, screenW, screenH, // maximised
+			0, 0, 800, 600, // second window untouched
+		},
+		{
+			"SideBySide",
+			WorkflowSideBySide,
+			0, 0, 960, screenH, // left half (1920/2)
+			960, 0, 960, screenH, // right half
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			m, _ := newTestManager()
+			_ = requireCreateWindow(t, m, Window{Name: "editor", Width: 800, Height: 600})
+			_ = requireCreateWindow(t, m, Window{Name: "terminal", Width: 800, Height: 600})
+
+			err := m.ApplyWorkflow(tc.workflow, []string{"editor", "terminal"}, screenW, screenH)
+			require.NoError(t, err)
+
+			pw0, ok := m.Get("editor")
+			require.True(t, ok)
+			x0, y0 := pw0.Position()
+			w0, h0 := pw0.Size()
+			assert.Equal(t, tc.win0X, x0, "editor x")
+			assert.Equal(t, tc.win0Y, y0, "editor y")
+			assert.Equal(t, tc.win0W, w0, "editor width")
+			assert.Equal(t, tc.win0H, h0, "editor height")
+
+			pw1, ok := m.Get("terminal")
+			require.True(t, ok)
+			x1, y1 := pw1.Position()
+			w1, h1 := pw1.Size()
+			assert.Equal(t, tc.win1X, x1, "terminal x")
+			assert.Equal(t, tc.win1Y, y1, "terminal y")
+			assert.Equal(t, tc.win1W, w1, "terminal width")
+			assert.Equal(t, tc.win1H, h1, "terminal height")
+		})
+	}
+}
+
+func TestApplyWorkflow_Empty_Bad(t *testing.T) {
+	m, _ := newTestManager()
+	err := m.ApplyWorkflow(WorkflowCoding, []string{}, 1920, 1080)
+	assert.Error(t, err)
+}

stubs/wails/go.mod

@@ -0,0 +1,3 @@
+module github.com/wailsapp/wails/v3
+
+go 1.26.0

stubs/wails/pkg/application/application.go

@@ -0,0 +1,778 @@
+package application
+
+import (
+	"sync"
+	"unsafe"
+
+	"github.com/wailsapp/wails/v3/pkg/events"
+)
+
+// Context mirrors the callback context type exposed by Wails.
+//
+//	item.OnClick(func(ctx *Context) { openPrefs() })
+type Context struct {
+	clickedMenuItem *MenuItem
+	contextMenuData *ContextMenuData
+	checked         bool
+}
+
+func newContext() *Context { return &Context{} }
+
+func (ctx *Context) withClickedMenuItem(item *MenuItem) *Context {
+	ctx.clickedMenuItem = item
+	return ctx
+}
+
+func (ctx *Context) withContextMenuData(data *ContextMenuData) *Context {
+	ctx.contextMenuData = data
+	return ctx
+}
+
+func (ctx *Context) withChecked(checked bool) *Context {
+	ctx.checked = checked
+	return ctx
+}
+
+// Logger is a minimal logger surface used by the GUI packages.
+type Logger struct{}
+
+func (l Logger) Info(message string, args ...any) {}
+
+// RGBA stores a colour with alpha.
+//
+//	colour := NewRGBA(255, 128, 0, 255) // opaque orange
+type RGBA struct {
+	Red, Green, Blue, Alpha uint8
+}
+
+// NewRGBA constructs an RGBA value.
+//
+//	colour := NewRGBA(255, 128, 0, 255) // opaque orange
+func NewRGBA(red, green, blue, alpha uint8) RGBA {
+	return RGBA{Red: red, Green: green, Blue: blue, Alpha: alpha}
+}
+
+// Menu is a menu tree used by the GUI wrappers.
+//
+//	menu := NewMenu()
+//	menu.Add("Save").SetAccelerator("CmdOrCtrl+S").OnClick(func(ctx *Context) { save() })
+type Menu struct {
+	label string
+	Items []*MenuItem
+}
+
+// NewMenu creates a new, empty Menu.
+//
+//	menu := NewMenu()
+func NewMenu() *Menu { return &Menu{} }
+
+// Add appends a new text item with the given label.
+func (m *Menu) Add(label string) *MenuItem {
+	item := NewMenuItem(label)
+	item.disabled = false
+	m.Items = append(m.Items, item)
+	return item
+}
+
+// AddSeparator appends a separator item.
+func (m *Menu) AddSeparator() {
+	m.Items = append(m.Items, NewMenuItemSeparator())
+}
+
+// AddSubmenu appends a submenu item and returns the child Menu.
+func (m *Menu) AddSubmenu(label string) *Menu {
+	item := NewSubMenuItem(label)
+	m.Items = append(m.Items, item)
+	return item.submenu
+}
+
+// AddRole appends a platform-role item.
+func (m *Menu) AddRole(role Role) {
+	m.Items = append(m.Items, NewRole(role))
+}
+
+// AppendItem appends an already-constructed MenuItem.
+func (m *Menu) AppendItem(item *MenuItem) {
+	m.Items = append(m.Items, item)
+}
+
+// Clone returns a deep copy of the menu tree.
+func (m *Menu) Clone() *Menu {
+	cloned := &Menu{label: m.label}
+	for _, item := range m.Items {
+		cloned.Items = append(cloned.Items, item.Clone())
+	}
+	return cloned
+}
+
+// Destroy frees all items in the menu.
+func (m *Menu) Destroy() {
+	for _, item := range m.Items {
+		item.Destroy()
+	}
+	m.Items = nil
+}
+
+func (m *Menu) setContextData(data *ContextMenuData) {
+	for _, item := range m.Items {
+		item.contextMenuData = data
+		if item.submenu != nil {
+			item.submenu.setContextData(data)
+		}
+	}
+}
+
+// MenuManager owns the application menu.
+//
+//	app.Menu.SetApplicationMenu(menu)
+type MenuManager struct {
+	applicationMenu *Menu
+}
+
+func (m *MenuManager) SetApplicationMenu(menu *Menu) { m.applicationMenu = menu }
+
+// SystemTray represents a tray instance.
+type SystemTray struct {
+	icon           []byte
+	templateIcon   []byte
+	tooltip        string
+	label          string
+	menu           *Menu
+	attachedWindow Window
+}
+
+func (t *SystemTray) SetIcon(data []byte)         { t.icon = append([]byte(nil), data...) }
+func (t *SystemTray) SetTemplateIcon(data []byte) { t.templateIcon = append([]byte(nil), data...) }
+func (t *SystemTray) SetTooltip(text string)      { t.tooltip = text }
+func (t *SystemTray) SetLabel(text string)        { t.label = text }
+func (t *SystemTray) SetMenu(menu *Menu)          { t.menu = menu }
+
+// AttachWindow associates a window with the tray icon (shown on click).
+func (t *SystemTray) AttachWindow(w Window) { t.attachedWindow = w }
+
+// SystemTrayManager creates tray instances.
+type SystemTrayManager struct{}
+
+func (m *SystemTrayManager) New() *SystemTray { return &SystemTray{} }
+
+// WindowEventContext carries drag-and-drop details for a window event.
+type WindowEventContext struct {
+	droppedFiles []string
+	dropDetails  *DropTargetDetails
+}
+
+func (c *WindowEventContext) DroppedFiles() []string {
+	return append([]string(nil), c.droppedFiles...)
+}
+
+func (c *WindowEventContext) DropTargetDetails() *DropTargetDetails {
+	if c.dropDetails == nil {
+		return nil
+	}
+	details := *c.dropDetails
+	return &details
+}
+
+// DropTargetDetails mirrors the fields consumed by the GUI wrappers.
+type DropTargetDetails struct {
+	ElementID string
+}
+
+// WindowEvent mirrors the event object passed to window callbacks.
+type WindowEvent struct {
+	ctx *WindowEventContext
+}
+
+func (e *WindowEvent) Context() *WindowEventContext {
+	if e.ctx == nil {
+		e.ctx = &WindowEventContext{}
+	}
+	return e.ctx
+}
+
+// WebviewWindow is a lightweight, in-memory window implementation
+// that satisfies the Window interface.
+type WebviewWindow struct {
+	mu                sync.RWMutex
+	opts              WebviewWindowOptions
+	windowID          uint
+	title             string
+	posX, posY        int
+	sizeW, sizeH      int
+	maximised         bool
+	focused           bool
+	visible           bool
+	alwaysOnTop       bool
+	isFullscreen      bool
+	closed            bool
+	zoom              float64
+	resizable         bool
+	ignoreMouseEvents bool
+	enabled           bool
+	eventHandlers     map[events.WindowEventType][]func(*WindowEvent)
+}
+
+var globalWindowID uint
+var globalWindowIDMu sync.Mutex
+
+func nextWindowID() uint {
+	globalWindowIDMu.Lock()
+	defer globalWindowIDMu.Unlock()
+	globalWindowID++
+	return globalWindowID
+}
+
+func newWebviewWindow(options WebviewWindowOptions) *WebviewWindow {
+	return &WebviewWindow{
+		opts:          options,
+		windowID:      nextWindowID(),
+		title:         options.Title,
+		posX:          options.X,
+		posY:          options.Y,
+		sizeW:         options.Width,
+		sizeH:         options.Height,
+		visible:       !options.Hidden,
+		alwaysOnTop:   options.AlwaysOnTop,
+		zoom:          options.Zoom,
+		resizable:     !options.DisableResize,
+		enabled:       true,
+		eventHandlers: make(map[events.WindowEventType][]func(*WindowEvent)),
+	}
+}
+
+// ID returns the unique numeric identifier for the window.
+func (w *WebviewWindow) ID() uint { return w.windowID }
+
+// Name returns the window name set in WebviewWindowOptions.
+func (w *WebviewWindow) Name() string { return w.opts.Name }
+
+// Show makes the window visible and returns it for chaining.
+func (w *WebviewWindow) Show() Window {
+	w.mu.Lock()
+	w.visible = true
+	w.mu.Unlock()
+	return w
+}
+
+// Hide makes the window invisible and returns it for chaining.
+func (w *WebviewWindow) Hide() Window {
+	w.mu.Lock()
+	w.visible = false
+	w.mu.Unlock()
+	return w
+}
+
+// IsVisible reports whether the window is currently visible.
+func (w *WebviewWindow) IsVisible() bool {
+	w.mu.RLock()
+	defer w.mu.RUnlock()
+	return w.visible
+}
+
+// Close marks the window as closed.
+func (w *WebviewWindow) Close() {
+	w.mu.Lock()
+	w.closed = true
+	w.mu.Unlock()
+}
+
+// Focus marks the window as focused.
+func (w *WebviewWindow) Focus() {
+	w.mu.Lock()
+	w.focused = true
+	w.mu.Unlock()
+}
+
+// Run is a no-op in the stub (the real implementation enters the run loop).
+func (w *WebviewWindow) Run() {}
+
+// Center is a no-op in the stub.
+func (w *WebviewWindow) Center() {}
+
+// Position returns the current x/y position.
+func (w *WebviewWindow) Position() (int, int) {
+	w.mu.RLock()
+	defer w.mu.RUnlock()
+	return w.posX, w.posY
+}
+
+// RelativePosition returns the position relative to the screen.
+func (w *WebviewWindow) RelativePosition() (int, int) {
+	w.mu.RLock()
+	defer w.mu.RUnlock()
+	return w.posX, w.posY
+}
+
+// Size returns the current width and height.
+func (w *WebviewWindow) Size() (int, int) {
+	w.mu.RLock()
+	defer w.mu.RUnlock()
+	return w.sizeW, w.sizeH
+}
+
+// Width returns the current window width.
+func (w *WebviewWindow) Width() int {
+	w.mu.RLock()
+	defer w.mu.RUnlock()
+	return w.sizeW
+}
+
+// Height returns the current window height.
+func (w *WebviewWindow) Height() int {
+	w.mu.RLock()
+	defer w.mu.RUnlock()
+	return w.sizeH
+}
+
+// Bounds returns the window's position and size as a Rect.
+func (w *WebviewWindow) Bounds() Rect {
+	w.mu.RLock()
+	defer w.mu.RUnlock()
+	return Rect{X: w.posX, Y: w.posY, Width: w.sizeW, Height: w.sizeH}
+}
+
+// SetPosition sets the top-left corner position.
+func (w *WebviewWindow) SetPosition(x, y int) {
+	w.mu.Lock()
+	w.posX, w.posY = x, y
+	w.mu.Unlock()
+}
+
+// SetRelativePosition sets position relative to the screen and returns the window.
+func (w *WebviewWindow) SetRelativePosition(x, y int) Window {
+	w.SetPosition(x, y)
+	return w
+}
+
+// SetSize sets the window dimensions and returns the window.
+func (w *WebviewWindow) SetSize(width, height int) Window {
+	w.mu.Lock()
+	w.sizeW, w.sizeH = width, height
+	w.mu.Unlock()
+	return w
+}
+
+// SetBounds sets position and size in one call.
+func (w *WebviewWindow) SetBounds(bounds Rect) {
+	w.mu.Lock()
+	w.posX, w.posY = bounds.X, bounds.Y
+	w.sizeW, w.sizeH = bounds.Width, bounds.Height
+	w.mu.Unlock()
+}
+
+// SetMaxSize is a no-op in the stub.
+func (w *WebviewWindow) SetMaxSize(maxWidth, maxHeight int) Window { return w }
+
+// SetMinSize is a no-op in the stub.
+func (w *WebviewWindow) SetMinSize(minWidth, minHeight int) Window { return w }
+
+// EnableSizeConstraints is a no-op in the stub.
+func (w *WebviewWindow) EnableSizeConstraints() {}
+
+// DisableSizeConstraints is a no-op in the stub.
+func (w *WebviewWindow) DisableSizeConstraints() {}
+
+// Resizable reports whether the user can resize the window.
+func (w *WebviewWindow) Resizable() bool {
+	w.mu.RLock()
+	defer w.mu.RUnlock()
+	return w.resizable
+}
+
+// SetResizable enables or disables user resizing and returns the window.
+func (w *WebviewWindow) SetResizable(b bool) Window {
+	w.mu.Lock()
+	w.resizable = b
+	w.mu.Unlock()
+	return w
+}
+
+// Maximise maximises the window and returns it.
+func (w *WebviewWindow) Maximise() Window {
+	w.mu.Lock()
+	w.maximised = true
+	w.mu.Unlock()
+	return w
+}
+
+// UnMaximise restores from maximised state.
+func (w *WebviewWindow) UnMaximise() {
+	w.mu.Lock()
+	w.maximised = false
+	w.mu.Unlock()
+}
+
+// ToggleMaximise toggles between maximised and normal.
+func (w *WebviewWindow) ToggleMaximise() {
+	w.mu.Lock()
+	w.maximised = !w.maximised
+	w.mu.Unlock()
+}
+
+// IsMaximised reports whether the window is maximised.
+func (w *WebviewWindow) IsMaximised() bool {
+	w.mu.RLock()
+	defer w.mu.RUnlock()
+	return w.maximised
+}
+
+// Minimise minimises the window and returns it.
+func (w *WebviewWindow) Minimise() Window {
+	w.mu.Lock()
+	w.visible = false
+	w.mu.Unlock()
+	return w
+}
+
+// UnMinimise restores from minimised state.
+func (w *WebviewWindow) UnMinimise() {
+	w.mu.Lock()
+	w.visible = true
+	w.mu.Unlock()
+}
+
+// IsMinimised always returns false in the stub.
+func (w *WebviewWindow) IsMinimised() bool { return false }
+
+// Fullscreen enters fullscreen and returns the window.
+func (w *WebviewWindow) Fullscreen() Window {
+	w.mu.Lock()
+	w.isFullscreen = true
+	w.mu.Unlock()
+	return w
+}
+
+// UnFullscreen exits fullscreen.
+func (w *WebviewWindow) UnFullscreen() {
+	w.mu.Lock()
+	w.isFullscreen = false
+	w.mu.Unlock()
+}
+
+// ToggleFullscreen toggles between fullscreen and normal.
+func (w *WebviewWindow) ToggleFullscreen() {
+	w.mu.Lock()
+	w.isFullscreen = !w.isFullscreen
+	w.mu.Unlock()
+}
+
+// IsFullscreen reports whether the window is in fullscreen mode.
+func (w *WebviewWindow) IsFullscreen() bool {
+	w.mu.RLock()
+	defer w.mu.RUnlock()
+	return w.isFullscreen
+}
+
+// Restore exits both fullscreen and maximised states.
+func (w *WebviewWindow) Restore() {
+	w.mu.Lock()
+	w.maximised = false
+	w.isFullscreen = false
+	w.mu.Unlock()
+}
+
+// SnapAssist is a no-op in the stub.
+func (w *WebviewWindow) SnapAssist() {}
+
+// SetTitle updates the window title and returns the window.
+func (w *WebviewWindow) SetTitle(title string) Window {
+	w.mu.Lock()
+	w.title = title
+	w.mu.Unlock()
+	return w
+}
+
+// SetURL is a no-op in the stub.
+func (w *WebviewWindow) SetURL(s string) Window { return w }
+
+// SetHTML is a no-op in the stub.
+func (w *WebviewWindow) SetHTML(html string) Window { return w }
+
+// SetMinimiseButtonState is a no-op in the stub.
+func (w *WebviewWindow) SetMinimiseButtonState(state ButtonState) Window { return w }
+
+// SetMaximiseButtonState is a no-op in the stub.
+func (w *WebviewWindow) SetMaximiseButtonState(state ButtonState) Window { return w }
+
+// SetCloseButtonState is a no-op in the stub.
+func (w *WebviewWindow) SetCloseButtonState(state ButtonState) Window { return w }
+
+// SetMenu is a no-op in the stub.
+func (w *WebviewWindow) SetMenu(menu *Menu) {}
+
+// ShowMenuBar is a no-op in the stub.
+func (w *WebviewWindow) ShowMenuBar() {}
+
+// HideMenuBar is a no-op in the stub.
+func (w *WebviewWindow) HideMenuBar() {}
+
+// ToggleMenuBar is a no-op in the stub.
+func (w *WebviewWindow) ToggleMenuBar() {}
+
+// SetBackgroundColour is a no-op in the stub.
+func (w *WebviewWindow) SetBackgroundColour(colour RGBA) Window { return w }
+
+// SetAlwaysOnTop sets the always-on-top flag and returns the window.
+func (w *WebviewWindow) SetAlwaysOnTop(b bool) Window {
+	w.mu.Lock()
+	w.alwaysOnTop = b
+	w.mu.Unlock()
+	return w
+}
+
+// SetFrameless is a no-op in the stub.
+func (w *WebviewWindow) SetFrameless(frameless bool) Window { return w }
+
+// ToggleFrameless is a no-op in the stub.
+func (w *WebviewWindow) ToggleFrameless() {}
+
+// SetIgnoreMouseEvents sets the mouse-event passthrough flag and returns the window.
+func (w *WebviewWindow) SetIgnoreMouseEvents(ignore bool) Window {
+	w.mu.Lock()
+	w.ignoreMouseEvents = ignore
+	w.mu.Unlock()
+	return w
+}
+
+// IsIgnoreMouseEvents reports whether mouse events are being ignored.
+func (w *WebviewWindow) IsIgnoreMouseEvents() bool {
+	w.mu.RLock()
+	defer w.mu.RUnlock()
+	return w.ignoreMouseEvents
+}
+
+// SetContentProtection is a no-op in the stub.
+func (w *WebviewWindow) SetContentProtection(protection bool) Window { return w }
+
+// GetZoom returns the current zoom magnification.
+func (w *WebviewWindow) GetZoom() float64 {
+	w.mu.RLock()
+	defer w.mu.RUnlock()
+	return w.zoom
+}
+
+// SetZoom sets the zoom magnification and returns the window.
+func (w *WebviewWindow) SetZoom(magnification float64) Window {
+	w.mu.Lock()
+	w.zoom = magnification
+	w.mu.Unlock()
+	return w
+}
+
+// Zoom is a no-op in the stub.
+func (w *WebviewWindow) Zoom() {}
+
+// ZoomIn is a no-op in the stub.
+func (w *WebviewWindow) ZoomIn() {}
+
+// ZoomOut is a no-op in the stub.
+func (w *WebviewWindow) ZoomOut() {}
+
+// ZoomReset resets zoom to 1.0 and returns the window.
+func (w *WebviewWindow) ZoomReset() Window {
+	w.mu.Lock()
+	w.zoom = 1.0
+	w.mu.Unlock()
+	return w
+}
+
+// GetBorderSizes returns zero insets in the stub.
+func (w *WebviewWindow) GetBorderSizes() *LRTB { return &LRTB{} }
+
+// GetScreen returns nil in the stub.
+func (w *WebviewWindow) GetScreen() (*Screen, error) { return nil, nil }
+
+// ExecJS is a no-op in the stub.
+func (w *WebviewWindow) ExecJS(js string) {}
+
+// EmitEvent always returns false in the stub.
+func (w *WebviewWindow) EmitEvent(name string, data ...any) bool { return false }
+
+// DispatchWailsEvent is a no-op in the stub.
+func (w *WebviewWindow) DispatchWailsEvent(event *CustomEvent) {}
+
+// OnWindowEvent registers an event callback and returns an unsubscribe function.
+func (w *WebviewWindow) OnWindowEvent(eventType events.WindowEventType, callback func(event *WindowEvent)) func() {
+	w.mu.Lock()
+	w.eventHandlers[eventType] = append(w.eventHandlers[eventType], callback)
+	w.mu.Unlock()
+	return func() {}
+}
+
+// RegisterHook is an alias for OnWindowEvent.
+func (w *WebviewWindow) RegisterHook(eventType events.WindowEventType, callback func(event *WindowEvent)) func() {
+	return w.OnWindowEvent(eventType, callback)
+}
+
+// handleDragAndDropMessage is a no-op in the stub.
+func (w *WebviewWindow) handleDragAndDropMessage(filenames []string, dropTarget *DropTargetDetails) {}
+
+// InitiateFrontendDropProcessing is a no-op in the stub.
+func (w *WebviewWindow) InitiateFrontendDropProcessing(filenames []string, x int, y int) {}
+
+// HandleMessage is a no-op in the stub.
+func (w *WebviewWindow) HandleMessage(message string) {}
+
+// HandleWindowEvent is a no-op in the stub.
+func (w *WebviewWindow) HandleWindowEvent(id uint) {}
+
+// HandleKeyEvent is a no-op in the stub.
+func (w *WebviewWindow) HandleKeyEvent(acceleratorString string) {}
+
+// OpenContextMenu is a no-op in the stub.
+func (w *WebviewWindow) OpenContextMenu(data *ContextMenuData) {}
+
+// AttachModal is a no-op in the stub.
+func (w *WebviewWindow) AttachModal(modalWindow Window) {}
+
+// OpenDevTools is a no-op in the stub.
+func (w *WebviewWindow) OpenDevTools() {}
+
+// Print always returns nil in the stub.
+func (w *WebviewWindow) Print() error { return nil }
+
+// Flash is a no-op in the stub.
+func (w *WebviewWindow) Flash(enabled bool) {}
+
+// IsFocused reports whether the window has focus.
+func (w *WebviewWindow) IsFocused() bool {
+	w.mu.RLock()
+	defer w.mu.RUnlock()
+	return w.focused
+}
+
+// NativeWindow returns nil in the stub.
+func (w *WebviewWindow) NativeWindow() unsafe.Pointer { return nil }
+
+// SetEnabled sets the window's enabled state.
+func (w *WebviewWindow) SetEnabled(enabled bool) {
+	w.mu.Lock()
+	w.enabled = enabled
+	w.mu.Unlock()
+}
+
+// Reload is a no-op in the stub.
+func (w *WebviewWindow) Reload() {}
+
+// ForceReload is a no-op in the stub.
+func (w *WebviewWindow) ForceReload() {}
+
+// Info is a no-op in the stub.
+func (w *WebviewWindow) Info(message string, args ...any) {}
+
+// Error is a no-op in the stub.
+func (w *WebviewWindow) Error(message string, args ...any) {}
+
+// shouldUnconditionallyClose always returns false in the stub.
+func (w *WebviewWindow) shouldUnconditionallyClose() bool { return false }
+
+// Internal editing stubs — satisfy the Window interface.
+func (w *WebviewWindow) cut()       {}
+func (w *WebviewWindow) copy()      {}
+func (w *WebviewWindow) paste()     {}
+func (w *WebviewWindow) undo()      {}
+func (w *WebviewWindow) redo()      {}
+func (w *WebviewWindow) delete()    {}
+func (w *WebviewWindow) selectAll() {}
+
+// Title returns the current window title.
+func (w *WebviewWindow) Title() string {
+	w.mu.RLock()
+	defer w.mu.RUnlock()
+	return w.title
+}
+
+// WindowManager manages in-memory windows.
+//
+//	win := app.Window.NewWithOptions(application.WebviewWindowOptions{Title: "Main"})
+type WindowManager struct {
+	mu      sync.RWMutex
+	windows map[uint]*WebviewWindow
+}
+
+func (wm *WindowManager) init() {
+	if wm.windows == nil {
+		wm.windows = make(map[uint]*WebviewWindow)
+	}
+}
+
+// NewWithOptions creates and registers a new window.
+func (wm *WindowManager) NewWithOptions(options WebviewWindowOptions) *WebviewWindow {
+	window := newWebviewWindow(options)
+	wm.mu.Lock()
+	wm.init()
+	wm.windows[window.windowID] = window
+	wm.mu.Unlock()
+	return window
+}
+
+// New creates a window with default options.
+func (wm *WindowManager) New() *WebviewWindow {
+	return wm.NewWithOptions(WebviewWindowOptions{})
+}
+
+// GetAll returns all managed windows as the Window interface slice.
+func (wm *WindowManager) GetAll() []Window {
+	wm.mu.RLock()
+	defer wm.mu.RUnlock()
+	out := make([]Window, 0, len(wm.windows))
+	for _, window := range wm.windows {
+		out = append(out, window)
+	}
+	return out
+}
+
+// GetByName finds a window by name, returning it and whether it was found.
+func (wm *WindowManager) GetByName(name string) (Window, bool) {
+	wm.mu.RLock()
+	defer wm.mu.RUnlock()
+	for _, window := range wm.windows {
+		if window.opts.Name == name {
+			return window, true
+		}
+	}
+	return nil, false
+}
+
+// GetByID finds a window by its numeric ID.
+func (wm *WindowManager) GetByID(id uint) (Window, bool) {
+	wm.mu.RLock()
+	defer wm.mu.RUnlock()
+	window, exists := wm.windows[id]
+	return window, exists
+}
+
+// Remove unregisters a window by ID.
+func (wm *WindowManager) Remove(windowID uint) {
+	wm.mu.Lock()
+	wm.init()
+	delete(wm.windows, windowID)
+	wm.mu.Unlock()
+}
+
+// App is the top-level application object used by the GUI packages.
+//
+//	app := &application.App{}
+//	win := app.Window.NewWithOptions(application.WebviewWindowOptions{Title: "Main"})
+type App struct {
+	Logger      Logger
+	Window      WindowManager
+	Menu        MenuManager
+	SystemTray  SystemTrayManager
+	Dialog      DialogManager
+	Event       EventManager
+	Browser     BrowserManager
+	Clipboard   ClipboardManager
+	ContextMenu ContextMenuManager
+	Environment EnvironmentManager
+	Screen      ScreenManager
+	KeyBinding  KeyBindingManager
+}
+
+// Quit is a no-op in the stub.
+func (a *App) Quit() {}
+
+// NewMenu creates a new empty Menu.
+func (a *App) NewMenu() *Menu {
+	return NewMenu()
+}

stubs/wails/pkg/application/application_options.go

@@ -0,0 +1,348 @@
+package application
+
+import (
+	"net/http"
+	"time"
+)
+
+// Options is the top-level application configuration passed to New().
+// app := application.New(application.Options{Name: "MyApp", Services: []Service{...}})
+type Options struct {
+	// Name is displayed in the default about box.
+	Name string
+
+	// Description is displayed in the default about box.
+	Description string
+
+	// Icon is the application icon shown in the about box.
+	Icon []byte
+
+	// Mac contains macOS-specific options.
+	Mac MacOptions
+
+	// Windows contains Windows-specific options.
+	Windows WindowsOptions
+
+	// Linux contains Linux-specific options.
+	Linux LinuxOptions
+
+	// IOS contains iOS-specific options.
+	IOS IOSOptions
+
+	// Android contains Android-specific options.
+	Android AndroidOptions
+
+	// Services lists bound Go services exposed to the frontend.
+	Services []Service
+
+	// MarshalError serialises service method errors to JSON.
+	// Return nil to fall back to the default error handler.
+	MarshalError func(error) []byte
+
+	// BindAliases maps alias IDs to bound method IDs.
+	// Example: map[uint32]uint32{1: 1411160069}
+	BindAliases map[uint32]uint32
+
+	// Assets configures the embedded asset server.
+	Assets AssetOptions
+
+	// Flags are key/value pairs available to the frontend at startup.
+	Flags map[string]any
+
+	// PanicHandler is called when an unhandled panic occurs.
+	PanicHandler func(*PanicDetails)
+
+	// DisableDefaultSignalHandler prevents Wails from handling OS signals.
+	DisableDefaultSignalHandler bool
+
+	// KeyBindings maps accelerator strings to window callbacks.
+	// Example: map[string]func(Window){"Ctrl+Q": func(w Window) { w.Close() }}
+	KeyBindings map[string]func(window Window)
+
+	// OnShutdown is called before the application terminates.
+	OnShutdown func()
+
+	// PostShutdown is called after shutdown, just before process exit.
+	PostShutdown func()
+
+	// ShouldQuit is called when the user attempts to quit.
+	// Return false to prevent the application from quitting.
+	ShouldQuit func() bool
+
+	// RawMessageHandler handles raw messages from the frontend.
+	RawMessageHandler func(window Window, message string, originInfo *OriginInfo)
+
+	// WarningHandler is called when a non-fatal warning occurs.
+	WarningHandler func(string)
+
+	// ErrorHandler is called when a non-fatal error occurs.
+	ErrorHandler func(err error)
+
+	// FileAssociations lists file extensions associated with this application.
+	// Each extension must include the leading dot, e.g. ".txt".
+	FileAssociations []string
+
+	// SingleInstance configures single-instance enforcement.
+	SingleInstance *SingleInstanceOptions
+
+	// Server configures the headless HTTP server (enabled via the "server" build tag).
+	Server ServerOptions
+}
+
+// ServerOptions configures the headless HTTP server started in server mode.
+// opts.Server = application.ServerOptions{Host: "0.0.0.0", Port: 8080}
+type ServerOptions struct {
+	// Host is the bind address. Defaults to "localhost".
+	Host string
+
+	// Port is the TCP port. Defaults to 8080.
+	Port int
+
+	// ReadTimeout is the maximum duration for reading a complete request.
+	ReadTimeout time.Duration
+
+	// WriteTimeout is the maximum duration before timing out a response write.
+	WriteTimeout time.Duration
+
+	// IdleTimeout is the maximum duration to wait for the next request.
+	IdleTimeout time.Duration
+
+	// ShutdownTimeout is the maximum duration to wait for active connections on shutdown.
+	ShutdownTimeout time.Duration
+
+	// TLS configures HTTPS. If nil, plain HTTP is used.
+	TLS *TLSOptions
+}
+
+// TLSOptions configures HTTPS for the headless server.
+// opts.Server.TLS = &application.TLSOptions{CertFile: "cert.pem", KeyFile: "key.pem"}
+type TLSOptions struct {
+	// CertFile is the path to the TLS certificate file.
+	CertFile string
+
+	// KeyFile is the path to the TLS private key file.
+	KeyFile string
+}
+
+// AssetOptions configures the embedded asset server.
+// opts.Assets = application.AssetOptions{Handler: http.FileServer(http.FS(assets))}
+type AssetOptions struct {
+	// Handler serves all content to the WebView.
+	Handler http.Handler
+
+	// Middleware injects into the asset server request chain before Wails internals.
+	Middleware Middleware
+
+	// DisableLogging suppresses per-request asset server log output.
+	DisableLogging bool
+}
+
+// Middleware is an HTTP middleware function for the asset server.
+// type Middleware func(next http.Handler) http.Handler
+type Middleware func(next http.Handler) http.Handler
+
+// ChainMiddleware composes multiple Middleware values into a single Middleware.
+// chain := application.ChainMiddleware(authMiddleware, loggingMiddleware)
+func ChainMiddleware(middleware ...Middleware) Middleware {
+	return func(handler http.Handler) http.Handler {
+		for index := len(middleware) - 1; index >= 0; index-- {
+			handler = middleware[index](handler)
+		}
+		return handler
+	}
+}
+
+// PanicDetails carries information about an unhandled panic.
+// opts.PanicHandler = func(d *application.PanicDetails) { log(d.StackTrace) }
+type PanicDetails struct {
+	StackTrace     string
+	Error          error
+	FullStackTrace string
+}
+
+// OriginInfo carries frame-origin metadata for raw message handling.
+// opts.RawMessageHandler = func(w Window, msg string, o *application.OriginInfo) { ... }
+type OriginInfo struct {
+	Origin      string
+	TopOrigin   string
+	IsMainFrame bool
+}
+
+// SingleInstanceOptions configures single-instance enforcement.
+// opts.SingleInstance = &application.SingleInstanceOptions{UniqueID: "com.example.myapp"}
+type SingleInstanceOptions struct {
+	// UniqueID identifies the application instance, e.g. "com.example.myapp".
+	UniqueID string
+
+	// OnSecondInstanceLaunch is called when a second instance attempts to start.
+	OnSecondInstanceLaunch func(data SecondInstanceData)
+
+	// AdditionalData passes custom data from the second instance to the first.
+	AdditionalData map[string]string
+}
+
+// SecondInstanceData describes a second-instance launch event.
+type SecondInstanceData struct {
+	Args           []string          `json:"args"`
+	WorkingDir     string            `json:"workingDir"`
+	AdditionalData map[string]string `json:"additionalData,omitempty"`
+}
+
+// ActivationPolicy controls when a macOS application activates.
+// opts.Mac.ActivationPolicy = application.ActivationPolicyAccessory
+type ActivationPolicy int
+
+const (
+	// ActivationPolicyRegular is used for applications with a main window.
+	ActivationPolicyRegular ActivationPolicy = iota
+	// ActivationPolicyAccessory is used for menu-bar or background applications.
+	ActivationPolicyAccessory
+	// ActivationPolicyProhibited prevents the application from activating.
+	ActivationPolicyProhibited
+)
+
+// MacOptions contains macOS-specific application options.
+// opts.Mac = application.MacOptions{ActivationPolicy: application.ActivationPolicyRegular}
+type MacOptions struct {
+	// ActivationPolicy controls how and when the application becomes active.
+	ActivationPolicy ActivationPolicy
+
+	// ApplicationShouldTerminateAfterLastWindowClosed quits the app when
+	// the last window closes, matching standard macOS behaviour.
+	ApplicationShouldTerminateAfterLastWindowClosed bool
+}
+
+// WindowsOptions contains Windows-specific application options.
+// opts.Windows = application.WindowsOptions{WndClass: "MyAppWindow"}
+type WindowsOptions struct {
+	// WndClass is the Windows window class name. Defaults to "WailsWebviewWindow".
+	WndClass string
+
+	// WndProcInterceptor intercepts all Win32 messages in the main message loop.
+	WndProcInterceptor func(hwnd uintptr, msg uint32, wParam, lParam uintptr) (returnCode uintptr, shouldReturn bool)
+
+	// DisableQuitOnLastWindowClosed prevents auto-quit when the last window closes.
+	DisableQuitOnLastWindowClosed bool
+
+	// WebviewUserDataPath sets the WebView2 user-data directory.
+	// Defaults to %APPDATA%\[BinaryName.exe].
+	WebviewUserDataPath string
+
+	// WebviewBrowserPath sets the directory containing WebView2 executables.
+	// Defaults to the system-installed WebView2.
+	WebviewBrowserPath string
+
+	// EnabledFeatures lists WebView2 feature flags to enable.
+	EnabledFeatures []string
+
+	// DisabledFeatures lists WebView2 feature flags to disable.
+	DisabledFeatures []string
+
+	// AdditionalBrowserArgs are extra Chromium command-line arguments.
+	// Each argument must include the "--" prefix, e.g. "--remote-debugging-port=9222".
+	AdditionalBrowserArgs []string
+}
+
+// LinuxOptions contains Linux-specific application options.
+// opts.Linux = application.LinuxOptions{ProgramName: "myapp"}
+type LinuxOptions struct {
+	// DisableQuitOnLastWindowClosed prevents auto-quit when the last window closes.
+	DisableQuitOnLastWindowClosed bool
+
+	// ProgramName is passed to g_set_prgname() for window grouping in GTK.
+	ProgramName string
+}
+
+// IOSOptions contains iOS-specific application options.
+// opts.IOS = application.IOSOptions{EnableInlineMediaPlayback: true}
+type IOSOptions struct {
+	// DisableInputAccessoryView hides the Next/Previous/Done toolbar above the keyboard.
+	DisableInputAccessoryView bool
+
+	// DisableScroll disables WebView scrolling.
+	DisableScroll bool
+
+	// DisableBounce disables the iOS overscroll bounce effect.
+	DisableBounce bool
+
+	// DisableScrollIndicators hides scroll indicator bars.
+	DisableScrollIndicators bool
+
+	// EnableBackForwardNavigationGestures enables swipe navigation gestures.
+	EnableBackForwardNavigationGestures bool
+
+	// DisableLinkPreview disables long-press link preview (peek and pop).
+	DisableLinkPreview bool
+
+	// EnableInlineMediaPlayback allows video to play inline rather than full-screen.
+	EnableInlineMediaPlayback bool
+
+	// EnableAutoplayWithoutUserAction allows media to autoplay without a user gesture.
+	EnableAutoplayWithoutUserAction bool
+
+	// DisableInspectable disables the Safari remote web inspector.
+	DisableInspectable bool
+
+	// UserAgent overrides the WKWebView user agent string.
+	UserAgent string
+
+	// ApplicationNameForUserAgent appends a name to the user agent. Defaults to "wails.io".
+	ApplicationNameForUserAgent string
+
+	// AppBackgroundColourSet enables BackgroundColour for the main iOS window.
+	AppBackgroundColourSet bool
+
+	// BackgroundColour is applied to the iOS app window before any WebView is created.
+	BackgroundColour RGBA
+
+	// EnableNativeTabs enables a native UITabBar at the bottom of the screen.
+	EnableNativeTabs bool
+
+	// NativeTabsItems configures the labels and SF Symbol icons for the native UITabBar.
+	NativeTabsItems []NativeTabItem
+}
+
+// NativeTabItem describes a single tab in the iOS native UITabBar.
+// item := application.NativeTabItem{Title: "Home", SystemImage: application.NativeTabIconHouse}
+type NativeTabItem struct {
+	Title       string        `json:"Title"`
+	SystemImage NativeTabIcon `json:"SystemImage"`
+}
+
+// NativeTabIcon is an SF Symbols name used for a UITabBar icon.
+// tab := application.NativeTabItem{SystemImage: application.NativeTabIconGear}
+type NativeTabIcon string
+
+const (
+	NativeTabIconNone    NativeTabIcon = ""
+	NativeTabIconHouse   NativeTabIcon = "house"
+	NativeTabIconGear    NativeTabIcon = "gear"
+	NativeTabIconStar    NativeTabIcon = "star"
+	NativeTabIconPerson  NativeTabIcon = "person"
+	NativeTabIconBell    NativeTabIcon = "bell"
+	NativeTabIconMagnify NativeTabIcon = "magnifyingglass"
+	NativeTabIconList    NativeTabIcon = "list.bullet"
+	NativeTabIconFolder  NativeTabIcon = "folder"
+)
+
+// AndroidOptions contains Android-specific application options.
+// opts.Android = application.AndroidOptions{EnableZoom: true}
+type AndroidOptions struct {
+	// DisableScroll disables WebView scrolling.
+	DisableScroll bool
+
+	// DisableOverscroll disables the overscroll bounce effect.
+	DisableOverscroll bool
+
+	// EnableZoom enables pinch-to-zoom in the WebView.
+	EnableZoom bool
+
+	// UserAgent overrides the WebView user agent string.
+	UserAgent string
+
+	// BackgroundColour sets the WebView background colour.
+	BackgroundColour RGBA
+
+	// DisableHardwareAcceleration disables GPU acceleration for the WebView.
+	DisableHardwareAcceleration bool
+}

stubs/wails/pkg/application/browser_manager.go

@@ -0,0 +1,21 @@
+package application
+
+// BrowserManager handles opening URLs and files in the system browser.
+//
+//	manager.OpenURL("https://lthn.io")
+//	manager.OpenFile("/home/user/document.pdf")
+type BrowserManager struct{}
+
+// OpenURL opens the given URL in the default browser.
+//
+//	err := manager.OpenURL("https://lthn.io")
+func (bm *BrowserManager) OpenURL(url string) error {
+	return nil
+}
+
+// OpenFile opens the given file path in the default browser or file handler.
+//
+//	err := manager.OpenFile("/home/user/report.html")
+func (bm *BrowserManager) OpenFile(path string) error {
+	return nil
+}

stubs/wails/pkg/application/browser_window.go

@@ -0,0 +1,230 @@
+package application
+
+import (
+	"sync"
+	"unsafe"
+
+	"github.com/wailsapp/wails/v3/pkg/events"
+)
+
+// ButtonState represents the visual state of a window control button.
+//
+//	window.SetMinimiseButtonState(ButtonHidden)
+type ButtonState int
+
+const (
+	ButtonEnabled  ButtonState = 0
+	ButtonDisabled ButtonState = 1
+	ButtonHidden   ButtonState = 2
+)
+
+// LRTB holds left/right/top/bottom border sizes in pixels.
+//
+//	sizes := window.GetBorderSizes()
+type LRTB struct {
+	Left   int
+	Right  int
+	Top    int
+	Bottom int
+}
+
+// ContextMenuData carries context-menu position and metadata from the frontend.
+//
+//	window.OpenContextMenu(&ContextMenuData{Id: "file-menu"})
+type ContextMenuData struct {
+	Id   string `json:"id"`
+	X    int    `json:"x"`
+	Y    int    `json:"y"`
+	Data string `json:"data"`
+}
+
+func (c *ContextMenuData) clone() *ContextMenuData {
+	if c == nil {
+		return nil
+	}
+	copy := *c
+	return &copy
+}
+
+// CustomEvent carries a named event with arbitrary data from the frontend.
+//
+//	window.DispatchWailsEvent(&CustomEvent{Name: "ready", Data: nil})
+type CustomEvent struct {
+	Name      string `json:"name"`
+	Data      any    `json:"data"`
+	Sender    string `json:"sender,omitempty"`
+	cancelled bool
+}
+
+// Cancel prevents the event from reaching further listeners.
+func (e *CustomEvent) Cancel() { e.cancelled = true }
+
+// IsCancelled reports whether Cancel has been called.
+func (e *CustomEvent) IsCancelled() bool { return e.cancelled }
+
+// BrowserWindow represents a browser client connection in server mode.
+// It satisfies the Window interface so browser clients are treated
+// uniformly with native windows throughout the codebase.
+//
+//	bw := NewBrowserWindow(1, "nano-abc123")
+//	bw.Focus() // no-op in browser mode
+type BrowserWindow struct {
+	mu       sync.RWMutex
+	id       uint
+	name     string
+	clientID string
+}
+
+// NewBrowserWindow constructs a BrowserWindow with the given numeric ID and client nano-ID.
+//
+//	bw := NewBrowserWindow(1, "nano-abc123")
+func NewBrowserWindow(id uint, clientID string) *BrowserWindow {
+	return &BrowserWindow{
+		id:       id,
+		name:     "browser-window",
+		clientID: clientID,
+	}
+}
+
+// ID returns the numeric window identifier.
+func (b *BrowserWindow) ID() uint { return b.id }
+
+// Name returns the window name.
+func (b *BrowserWindow) Name() string {
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+	return b.name
+}
+
+// ClientID returns the runtime nano-ID for this client.
+func (b *BrowserWindow) ClientID() string {
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+	return b.clientID
+}
+
+// No-op windowing methods — browser windows have no native chrome.
+
+func (b *BrowserWindow) Center()                  {}
+func (b *BrowserWindow) Close()                   {}
+func (b *BrowserWindow) DisableSizeConstraints()  {}
+func (b *BrowserWindow) EnableSizeConstraints()   {}
+func (b *BrowserWindow) ExecJS(_ string)          {}
+func (b *BrowserWindow) Focus()                   {}
+func (b *BrowserWindow) ForceReload()             {}
+func (b *BrowserWindow) HideMenuBar()             {}
+func (b *BrowserWindow) OpenDevTools()            {}
+func (b *BrowserWindow) Reload()                  {}
+func (b *BrowserWindow) Restore()                 {}
+func (b *BrowserWindow) Run()                     {}
+func (b *BrowserWindow) SetPosition(_ int, _ int) {}
+func (b *BrowserWindow) ShowMenuBar()             {}
+func (b *BrowserWindow) SnapAssist()              {}
+func (b *BrowserWindow) ToggleFrameless()         {}
+func (b *BrowserWindow) ToggleFullscreen()        {}
+func (b *BrowserWindow) ToggleMaximise()          {}
+func (b *BrowserWindow) ToggleMenuBar()           {}
+func (b *BrowserWindow) UnFullscreen()            {}
+func (b *BrowserWindow) UnMaximise()              {}
+func (b *BrowserWindow) UnMinimise()              {}
+func (b *BrowserWindow) SetEnabled(_ bool)        {}
+func (b *BrowserWindow) Flash(_ bool)             {}
+func (b *BrowserWindow) SetMenu(_ *Menu)          {}
+func (b *BrowserWindow) SetBounds(_ Rect)         {}
+func (b *BrowserWindow) Zoom()                    {}
+func (b *BrowserWindow) ZoomIn()                  {}
+func (b *BrowserWindow) ZoomOut()                 {}
+func (b *BrowserWindow) OpenContextMenu(_ *ContextMenuData) {}
+func (b *BrowserWindow) HandleMessage(_ string)             {}
+func (b *BrowserWindow) HandleWindowEvent(_ uint)           {}
+func (b *BrowserWindow) HandleKeyEvent(_ string)            {}
+func (b *BrowserWindow) AttachModal(_ Window)               {}
+
+// Internal editing stubs.
+func (b *BrowserWindow) cut()       {}
+func (b *BrowserWindow) copy()      {}
+func (b *BrowserWindow) paste()     {}
+func (b *BrowserWindow) undo()      {}
+func (b *BrowserWindow) redo()      {}
+func (b *BrowserWindow) delete()    {}
+func (b *BrowserWindow) selectAll() {}
+
+// shouldUnconditionallyClose always returns false for browser windows.
+func (b *BrowserWindow) shouldUnconditionallyClose() bool { return false }
+
+// Methods returning Window for chaining — always no-op for browser windows.
+
+func (b *BrowserWindow) Fullscreen() Window                           { return b }
+func (b *BrowserWindow) Hide() Window                                 { return b }
+func (b *BrowserWindow) Maximise() Window                             { return b }
+func (b *BrowserWindow) Minimise() Window                             { return b }
+func (b *BrowserWindow) Show() Window                                 { return b }
+func (b *BrowserWindow) SetAlwaysOnTop(_ bool) Window                 { return b }
+func (b *BrowserWindow) SetBackgroundColour(_ RGBA) Window            { return b }
+func (b *BrowserWindow) SetFrameless(_ bool) Window                   { return b }
+func (b *BrowserWindow) SetHTML(_ string) Window                      { return b }
+func (b *BrowserWindow) SetMinimiseButtonState(_ ButtonState) Window  { return b }
+func (b *BrowserWindow) SetMaximiseButtonState(_ ButtonState) Window  { return b }
+func (b *BrowserWindow) SetCloseButtonState(_ ButtonState) Window     { return b }
+func (b *BrowserWindow) SetMaxSize(_ int, _ int) Window               { return b }
+func (b *BrowserWindow) SetMinSize(_ int, _ int) Window               { return b }
+func (b *BrowserWindow) SetRelativePosition(_ int, _ int) Window      { return b }
+func (b *BrowserWindow) SetResizable(_ bool) Window                   { return b }
+func (b *BrowserWindow) SetIgnoreMouseEvents(_ bool) Window           { return b }
+func (b *BrowserWindow) SetSize(_ int, _ int) Window                  { return b }
+func (b *BrowserWindow) SetTitle(_ string) Window                     { return b }
+func (b *BrowserWindow) SetURL(_ string) Window                       { return b }
+func (b *BrowserWindow) SetZoom(_ float64) Window                     { return b }
+func (b *BrowserWindow) SetContentProtection(_ bool) Window           { return b }
+func (b *BrowserWindow) ZoomReset() Window                            { return b }
+
+// Methods returning simple zero values.
+
+func (b *BrowserWindow) GetBorderSizes() *LRTB               { return nil }
+func (b *BrowserWindow) GetScreen() (*Screen, error)         { return nil, nil }
+func (b *BrowserWindow) GetZoom() float64                    { return 1.0 }
+func (b *BrowserWindow) Height() int                         { return 0 }
+func (b *BrowserWindow) Width() int                          { return 0 }
+func (b *BrowserWindow) IsFocused() bool                     { return false }
+func (b *BrowserWindow) IsFullscreen() bool                  { return false }
+func (b *BrowserWindow) IsIgnoreMouseEvents() bool           { return false }
+func (b *BrowserWindow) IsMaximised() bool                   { return false }
+func (b *BrowserWindow) IsMinimised() bool                   { return false }
+func (b *BrowserWindow) IsVisible() bool                     { return true }
+func (b *BrowserWindow) Resizable() bool                     { return false }
+func (b *BrowserWindow) Position() (int, int)                { return 0, 0 }
+func (b *BrowserWindow) RelativePosition() (int, int)        { return 0, 0 }
+func (b *BrowserWindow) Size() (int, int)                    { return 0, 0 }
+func (b *BrowserWindow) Bounds() Rect                        { return Rect{} }
+func (b *BrowserWindow) NativeWindow() unsafe.Pointer        { return nil }
+func (b *BrowserWindow) Print() error                        { return nil }
+
+// DispatchWailsEvent is a no-op for browser windows; events are broadcast via WebSocket.
+func (b *BrowserWindow) DispatchWailsEvent(_ *CustomEvent) {}
+
+// EmitEvent broadcasts a named event; always returns false in the stub.
+func (b *BrowserWindow) EmitEvent(_ string, _ ...any) bool { return false }
+
+// Error logs an error message (no-op in the stub).
+func (b *BrowserWindow) Error(_ string, _ ...any) {}
+
+// Info logs an info message (no-op in the stub).
+func (b *BrowserWindow) Info(_ string, _ ...any) {}
+
+// OnWindowEvent registers a callback for a window event type; returns an unsubscribe func.
+//
+//	unsubscribe := bw.OnWindowEvent(events.Common.WindowClosing, fn)
+func (b *BrowserWindow) OnWindowEvent(_ events.WindowEventType, _ func(*WindowEvent)) func() {
+	return func() {}
+}
+
+// RegisterHook registers a lifecycle hook; returns an unsubscribe func.
+func (b *BrowserWindow) RegisterHook(_ events.WindowEventType, _ func(*WindowEvent)) func() {
+	return func() {}
+}
+
+// handleDragAndDropMessage is a no-op for browser windows.
+func (b *BrowserWindow) handleDragAndDropMessage(_ []string, _ *DropTargetDetails) {}
+
+// InitiateFrontendDropProcessing is a no-op for browser windows.
+func (b *BrowserWindow) InitiateFrontendDropProcessing(_ []string, _ int, _ int) {}

stubs/wails/pkg/application/clipboard.go

@@ -0,0 +1,65 @@
+package application
+
+import "sync"
+
+// Clipboard provides direct read/write access to the system clipboard.
+//
+//	ok := clipboard.SetText("hello")
+//	text, ok := clipboard.Text()
+type Clipboard struct {
+	mu   sync.RWMutex
+	text string
+}
+
+// SetText writes the given text to the clipboard and returns true on success.
+//
+//	ok := clipboard.SetText("copied text")
+func (c *Clipboard) SetText(text string) bool {
+	c.mu.Lock()
+	c.text = text
+	c.mu.Unlock()
+	return true
+}
+
+// Text reads the current clipboard text. Returns the text and true on success.
+//
+//	text, ok := clipboard.Text()
+func (c *Clipboard) Text() (string, bool) {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+	return c.text, true
+}
+
+// ClipboardManager is the application-level clipboard surface.
+// Lazily initialises the underlying Clipboard on first use.
+//
+//	manager.SetText("hello")
+//	text, ok := manager.Text()
+type ClipboardManager struct {
+	mu        sync.Mutex
+	clipboard *Clipboard
+}
+
+// SetText writes text to the clipboard and returns true on success.
+//
+//	ok := manager.SetText("hello")
+func (cm *ClipboardManager) SetText(text string) bool {
+	return cm.instance().SetText(text)
+}
+
+// Text reads the current clipboard text. Returns the text and true on success.
+//
+//	text, ok := manager.Text()
+func (cm *ClipboardManager) Text() (string, bool) {
+	return cm.instance().Text()
+}
+
+// instance returns the Clipboard, creating it if it does not yet exist.
+func (cm *ClipboardManager) instance() *Clipboard {
+	cm.mu.Lock()
+	defer cm.mu.Unlock()
+	if cm.clipboard == nil {
+		cm.clipboard = &Clipboard{}
+	}
+	return cm.clipboard
+}

stubs/wails/pkg/application/context_menu.go

@@ -0,0 +1,73 @@
+package application
+
+import "sync"
+
+// ContextMenu is a named Menu used as a right-click context menu.
+//
+//	cm := manager.New()
+//	cm.Add("Cut").OnClick(func(*Context) { ... })
+type ContextMenu struct {
+	*Menu
+	name string
+}
+
+// ContextMenuManager manages named context menus for the application.
+//
+//	manager.Add("fileList", cm)
+//	menu, ok := manager.Get("fileList")
+type ContextMenuManager struct {
+	mu    sync.RWMutex
+	menus map[string]*ContextMenu
+}
+
+// New creates an empty, unnamed ContextMenu ready for population.
+//
+//	cm := manager.New()
+//	cm.Add("Open")
+func (cmm *ContextMenuManager) New() *ContextMenu {
+	return &ContextMenu{Menu: NewMenu()}
+}
+
+// Add registers a ContextMenu under the given name, replacing any existing entry.
+//
+//	manager.Add("fileList", cm)
+func (cmm *ContextMenuManager) Add(name string, menu *ContextMenu) {
+	cmm.mu.Lock()
+	defer cmm.mu.Unlock()
+	if cmm.menus == nil {
+		cmm.menus = make(map[string]*ContextMenu)
+	}
+	cmm.menus[name] = menu
+}
+
+// Remove unregisters the context menu with the given name.
+//
+//	manager.Remove("fileList")
+func (cmm *ContextMenuManager) Remove(name string) {
+	cmm.mu.Lock()
+	defer cmm.mu.Unlock()
+	delete(cmm.menus, name)
+}
+
+// Get retrieves a registered context menu by name.
+//
+//	menu, ok := manager.Get("fileList")
+func (cmm *ContextMenuManager) Get(name string) (*ContextMenu, bool) {
+	cmm.mu.RLock()
+	defer cmm.mu.RUnlock()
+	menu, exists := cmm.menus[name]
+	return menu, exists
+}
+
+// GetAll returns all registered context menus as a slice.
+//
+//	for _, cm := range manager.GetAll() { ... }
+func (cmm *ContextMenuManager) GetAll() []*ContextMenu {
+	cmm.mu.RLock()
+	defer cmm.mu.RUnlock()
+	result := make([]*ContextMenu, 0, len(cmm.menus))
+	for _, menu := range cmm.menus {
+		result = append(result, menu)
+	}
+	return result
+}

stubs/wails/pkg/application/dialog.go

@@ -0,0 +1,481 @@
+package application
+
+// DialogType identifies the visual style of a message dialog.
+type DialogType int
+
+const (
+	InfoDialogType     DialogType = iota
+	QuestionDialogType DialogType = iota
+	WarningDialogType  DialogType = iota
+	ErrorDialogType    DialogType = iota
+)
+
+// FileFilter describes a file type filter for open/save dialogs.
+//
+//	filter := FileFilter{DisplayName: "Images (*.png;*.jpg)", Pattern: "*.png;*.jpg"}
+type FileFilter struct {
+	DisplayName string
+	Pattern     string
+}
+
+// Button is a labelled action in a MessageDialog.
+//
+//	btn := dialog.AddButton("OK")
+//	btn.SetAsDefault().OnClick(func() { ... })
+type Button struct {
+	Label     string
+	IsCancel  bool
+	IsDefault bool
+	Callback  func()
+}
+
+// OnClick registers a click handler on the button and returns itself for chaining.
+//
+//	btn.OnClick(func() { saveFile() })
+func (b *Button) OnClick(callback func()) *Button {
+	b.Callback = callback
+	return b
+}
+
+// SetAsDefault marks this button as the default (Enter key) action.
+func (b *Button) SetAsDefault() *Button {
+	b.IsDefault = true
+	return b
+}
+
+// SetAsCancel marks this button as the cancel (Escape key) action.
+func (b *Button) SetAsCancel() *Button {
+	b.IsCancel = true
+	return b
+}
+
+// MessageDialogOptions holds configuration for a MessageDialog.
+type MessageDialogOptions struct {
+	DialogType DialogType
+	Title      string
+	Message    string
+	Buttons    []*Button
+	Icon       []byte
+}
+
+// MessageDialog is an in-memory message dialog (info / question / warning / error).
+//
+//	dialog.Info().SetTitle("Done").SetMessage("File saved.").Show()
+type MessageDialog struct {
+	MessageDialogOptions
+}
+
+// SetTitle sets the dialog window title.
+//
+//	dialog.SetTitle("Confirm Delete")
+func (d *MessageDialog) SetTitle(title string) *MessageDialog {
+	d.Title = title
+	return d
+}
+
+// SetMessage sets the body text shown in the dialog.
+//
+//	dialog.SetMessage("Are you sure?")
+func (d *MessageDialog) SetMessage(message string) *MessageDialog {
+	d.Message = message
+	return d
+}
+
+// SetIcon sets the icon bytes shown in the dialog.
+func (d *MessageDialog) SetIcon(icon []byte) *MessageDialog {
+	d.Icon = icon
+	return d
+}
+
+// AddButton appends a labelled button and returns it for further configuration.
+//
+//	btn := dialog.AddButton("Yes")
+func (d *MessageDialog) AddButton(label string) *Button {
+	btn := &Button{Label: label}
+	d.Buttons = append(d.Buttons, btn)
+	return btn
+}
+
+// AddButtons replaces the button list in bulk.
+func (d *MessageDialog) AddButtons(buttons []*Button) *MessageDialog {
+	d.Buttons = buttons
+	return d
+}
+
+// SetDefaultButton marks the given button as the default action.
+func (d *MessageDialog) SetDefaultButton(button *Button) *MessageDialog {
+	for _, b := range d.Buttons {
+		b.IsDefault = false
+	}
+	button.IsDefault = true
+	return d
+}
+
+// SetCancelButton marks the given button as the cancel action.
+func (d *MessageDialog) SetCancelButton(button *Button) *MessageDialog {
+	for _, b := range d.Buttons {
+		b.IsCancel = false
+	}
+	button.IsCancel = true
+	return d
+}
+
+// AttachToWindow associates the dialog with a parent window (no-op in the stub).
+func (d *MessageDialog) AttachToWindow(window *WebviewWindow) *MessageDialog {
+	return d
+}
+
+// Show presents the dialog. No-op in the stub.
+func (d *MessageDialog) Show() {}
+
+func newMessageDialog(dialogType DialogType) *MessageDialog {
+	return &MessageDialog{
+		MessageDialogOptions: MessageDialogOptions{DialogType: dialogType},
+	}
+}
+
+// OpenFileDialogOptions configures an OpenFileDialogStruct.
+type OpenFileDialogOptions struct {
+	CanChooseDirectories            bool
+	CanChooseFiles                  bool
+	CanCreateDirectories            bool
+	ShowHiddenFiles                 bool
+	ResolvesAliases                 bool
+	AllowsMultipleSelection         bool
+	HideExtension                   bool
+	CanSelectHiddenExtension        bool
+	TreatsFilePackagesAsDirectories bool
+	AllowsOtherFileTypes            bool
+	Filters                         []FileFilter
+	Title                           string
+	Message                         string
+	ButtonText                      string
+	Directory                       string
+}
+
+// OpenFileDialogStruct is a builder for file-open dialogs.
+//
+//	path, err := manager.OpenFile().SetTitle("Pick a file").PromptForSingleSelection()
+type OpenFileDialogStruct struct {
+	canChooseDirectories            bool
+	canChooseFiles                  bool
+	canCreateDirectories            bool
+	showHiddenFiles                 bool
+	resolvesAliases                 bool
+	allowsMultipleSelection         bool
+	hideExtension                   bool
+	canSelectHiddenExtension        bool
+	treatsFilePackagesAsDirectories bool
+	allowsOtherFileTypes            bool
+	filters                         []FileFilter
+	title                           string
+	message                         string
+	buttonText                      string
+	directory                       string
+}
+
+func newOpenFileDialog() *OpenFileDialogStruct {
+	return &OpenFileDialogStruct{
+		canChooseFiles:       true,
+		canCreateDirectories: true,
+	}
+}
+
+// SetOptions applies all fields from OpenFileDialogOptions to the dialog.
+func (d *OpenFileDialogStruct) SetOptions(options *OpenFileDialogOptions) {
+	d.title = options.Title
+	d.message = options.Message
+	d.buttonText = options.ButtonText
+	d.directory = options.Directory
+	d.canChooseDirectories = options.CanChooseDirectories
+	d.canChooseFiles = options.CanChooseFiles
+	d.canCreateDirectories = options.CanCreateDirectories
+	d.showHiddenFiles = options.ShowHiddenFiles
+	d.resolvesAliases = options.ResolvesAliases
+	d.allowsMultipleSelection = options.AllowsMultipleSelection
+	d.hideExtension = options.HideExtension
+	d.canSelectHiddenExtension = options.CanSelectHiddenExtension
+	d.treatsFilePackagesAsDirectories = options.TreatsFilePackagesAsDirectories
+	d.allowsOtherFileTypes = options.AllowsOtherFileTypes
+	d.filters = options.Filters
+}
+
+func (d *OpenFileDialogStruct) SetTitle(title string) *OpenFileDialogStruct {
+	d.title = title
+	return d
+}
+
+func (d *OpenFileDialogStruct) SetMessage(message string) *OpenFileDialogStruct {
+	d.message = message
+	return d
+}
+
+func (d *OpenFileDialogStruct) SetButtonText(text string) *OpenFileDialogStruct {
+	d.buttonText = text
+	return d
+}
+
+func (d *OpenFileDialogStruct) SetDirectory(directory string) *OpenFileDialogStruct {
+	d.directory = directory
+	return d
+}
+
+func (d *OpenFileDialogStruct) CanChooseFiles(canChooseFiles bool) *OpenFileDialogStruct {
+	d.canChooseFiles = canChooseFiles
+	return d
+}
+
+func (d *OpenFileDialogStruct) CanChooseDirectories(canChooseDirectories bool) *OpenFileDialogStruct {
+	d.canChooseDirectories = canChooseDirectories
+	return d
+}
+
+func (d *OpenFileDialogStruct) CanCreateDirectories(canCreateDirectories bool) *OpenFileDialogStruct {
+	d.canCreateDirectories = canCreateDirectories
+	return d
+}
+
+func (d *OpenFileDialogStruct) ShowHiddenFiles(showHiddenFiles bool) *OpenFileDialogStruct {
+	d.showHiddenFiles = showHiddenFiles
+	return d
+}
+
+func (d *OpenFileDialogStruct) HideExtension(hideExtension bool) *OpenFileDialogStruct {
+	d.hideExtension = hideExtension
+	return d
+}
+
+func (d *OpenFileDialogStruct) CanSelectHiddenExtension(canSelectHiddenExtension bool) *OpenFileDialogStruct {
+	d.canSelectHiddenExtension = canSelectHiddenExtension
+	return d
+}
+
+func (d *OpenFileDialogStruct) ResolvesAliases(resolvesAliases bool) *OpenFileDialogStruct {
+	d.resolvesAliases = resolvesAliases
+	return d
+}
+
+func (d *OpenFileDialogStruct) AllowsOtherFileTypes(allowsOtherFileTypes bool) *OpenFileDialogStruct {
+	d.allowsOtherFileTypes = allowsOtherFileTypes
+	return d
+}
+
+func (d *OpenFileDialogStruct) TreatsFilePackagesAsDirectories(treats bool) *OpenFileDialogStruct {
+	d.treatsFilePackagesAsDirectories = treats
+	return d
+}
+
+// AddFilter appends a file type filter to the dialog.
+//
+//	dialog.AddFilter("Images", "*.png;*.jpg")
+func (d *OpenFileDialogStruct) AddFilter(displayName, pattern string) *OpenFileDialogStruct {
+	d.filters = append(d.filters, FileFilter{DisplayName: displayName, Pattern: pattern})
+	return d
+}
+
+func (d *OpenFileDialogStruct) AttachToWindow(window *WebviewWindow) *OpenFileDialogStruct {
+	return d
+}
+
+// PromptForSingleSelection shows the dialog and returns the chosen path.
+// Always returns ("", nil) in the stub.
+//
+//	path, err := dialog.PromptForSingleSelection()
+func (d *OpenFileDialogStruct) PromptForSingleSelection() (string, error) {
+	return "", nil
+}
+
+// PromptForMultipleSelection shows the dialog and returns all chosen paths.
+// Always returns (nil, nil) in the stub.
+//
+//	paths, err := dialog.PromptForMultipleSelection()
+func (d *OpenFileDialogStruct) PromptForMultipleSelection() ([]string, error) {
+	return nil, nil
+}
+
+// SaveFileDialogOptions configures a SaveFileDialogStruct.
+type SaveFileDialogOptions struct {
+	CanCreateDirectories            bool
+	ShowHiddenFiles                 bool
+	CanSelectHiddenExtension        bool
+	AllowOtherFileTypes             bool
+	HideExtension                   bool
+	TreatsFilePackagesAsDirectories bool
+	Title                           string
+	Message                         string
+	Directory                       string
+	Filename                        string
+	ButtonText                      string
+	Filters                         []FileFilter
+}
+
+// SaveFileDialogStruct is a builder for file-save dialogs.
+//
+//	path, err := manager.SaveFile().SetTitle("Save As").PromptForSingleSelection()
+type SaveFileDialogStruct struct {
+	canCreateDirectories            bool
+	showHiddenFiles                 bool
+	canSelectHiddenExtension        bool
+	allowOtherFileTypes             bool
+	hideExtension                   bool
+	treatsFilePackagesAsDirectories bool
+	title                           string
+	message                         string
+	directory                       string
+	filename                        string
+	buttonText                      string
+	filters                         []FileFilter
+}
+
+func newSaveFileDialog() *SaveFileDialogStruct {
+	return &SaveFileDialogStruct{canCreateDirectories: true}
+}
+
+// SetOptions applies all fields from SaveFileDialogOptions to the dialog.
+func (d *SaveFileDialogStruct) SetOptions(options *SaveFileDialogOptions) {
+	d.title = options.Title
+	d.canCreateDirectories = options.CanCreateDirectories
+	d.showHiddenFiles = options.ShowHiddenFiles
+	d.canSelectHiddenExtension = options.CanSelectHiddenExtension
+	d.allowOtherFileTypes = options.AllowOtherFileTypes
+	d.hideExtension = options.HideExtension
+	d.treatsFilePackagesAsDirectories = options.TreatsFilePackagesAsDirectories
+	d.message = options.Message
+	d.directory = options.Directory
+	d.filename = options.Filename
+	d.buttonText = options.ButtonText
+	d.filters = options.Filters
+}
+
+func (d *SaveFileDialogStruct) SetTitle(title string) *SaveFileDialogStruct {
+	d.title = title
+	return d
+}
+
+func (d *SaveFileDialogStruct) SetMessage(message string) *SaveFileDialogStruct {
+	d.message = message
+	return d
+}
+
+func (d *SaveFileDialogStruct) SetDirectory(directory string) *SaveFileDialogStruct {
+	d.directory = directory
+	return d
+}
+
+func (d *SaveFileDialogStruct) SetFilename(filename string) *SaveFileDialogStruct {
+	d.filename = filename
+	return d
+}
+
+func (d *SaveFileDialogStruct) SetButtonText(text string) *SaveFileDialogStruct {
+	d.buttonText = text
+	return d
+}
+
+func (d *SaveFileDialogStruct) CanCreateDirectories(canCreateDirectories bool) *SaveFileDialogStruct {
+	d.canCreateDirectories = canCreateDirectories
+	return d
+}
+
+func (d *SaveFileDialogStruct) ShowHiddenFiles(showHiddenFiles bool) *SaveFileDialogStruct {
+	d.showHiddenFiles = showHiddenFiles
+	return d
+}
+
+func (d *SaveFileDialogStruct) CanSelectHiddenExtension(canSelectHiddenExtension bool) *SaveFileDialogStruct {
+	d.canSelectHiddenExtension = canSelectHiddenExtension
+	return d
+}
+
+func (d *SaveFileDialogStruct) AllowsOtherFileTypes(allowOtherFileTypes bool) *SaveFileDialogStruct {
+	d.allowOtherFileTypes = allowOtherFileTypes
+	return d
+}
+
+func (d *SaveFileDialogStruct) HideExtension(hideExtension bool) *SaveFileDialogStruct {
+	d.hideExtension = hideExtension
+	return d
+}
+
+func (d *SaveFileDialogStruct) TreatsFilePackagesAsDirectories(treats bool) *SaveFileDialogStruct {
+	d.treatsFilePackagesAsDirectories = treats
+	return d
+}
+
+// AddFilter appends a file type filter to the dialog.
+//
+//	dialog.AddFilter("Text files", "*.txt")
+func (d *SaveFileDialogStruct) AddFilter(displayName, pattern string) *SaveFileDialogStruct {
+	d.filters = append(d.filters, FileFilter{DisplayName: displayName, Pattern: pattern})
+	return d
+}
+
+func (d *SaveFileDialogStruct) AttachToWindow(window *WebviewWindow) *SaveFileDialogStruct {
+	return d
+}
+
+// PromptForSingleSelection shows the save dialog and returns the chosen path.
+// Always returns ("", nil) in the stub.
+//
+//	path, err := dialog.PromptForSingleSelection()
+func (d *SaveFileDialogStruct) PromptForSingleSelection() (string, error) {
+	return "", nil
+}
+
+// DialogManager exposes factory methods for all dialog types.
+//
+//	manager.Info().SetMessage("Saved!").Show()
+//	path, _ := manager.OpenFile().PromptForSingleSelection()
+type DialogManager struct{}
+
+// OpenFile creates a file-open dialog builder.
+func (dm *DialogManager) OpenFile() *OpenFileDialogStruct {
+	return newOpenFileDialog()
+}
+
+// OpenFileWithOptions creates a file-open dialog builder pre-populated from options.
+func (dm *DialogManager) OpenFileWithOptions(options *OpenFileDialogOptions) *OpenFileDialogStruct {
+	result := newOpenFileDialog()
+	result.SetOptions(options)
+	return result
+}
+
+// SaveFile creates a file-save dialog builder.
+func (dm *DialogManager) SaveFile() *SaveFileDialogStruct {
+	return newSaveFileDialog()
+}
+
+// SaveFileWithOptions creates a file-save dialog builder pre-populated from options.
+func (dm *DialogManager) SaveFileWithOptions(options *SaveFileDialogOptions) *SaveFileDialogStruct {
+	result := newSaveFileDialog()
+	result.SetOptions(options)
+	return result
+}
+
+// Info creates an information message dialog.
+//
+//	manager.Info().SetMessage("Done").Show()
+func (dm *DialogManager) Info() *MessageDialog {
+	return newMessageDialog(InfoDialogType)
+}
+
+// Question creates a question message dialog.
+//
+//	manager.Question().SetMessage("Continue?").Show()
+func (dm *DialogManager) Question() *MessageDialog {
+	return newMessageDialog(QuestionDialogType)
+}
+
+// Warning creates a warning message dialog.
+//
+//	manager.Warning().SetMessage("Low disk space").Show()
+func (dm *DialogManager) Warning() *MessageDialog {
+	return newMessageDialog(WarningDialogType)
+}
+
+// Error creates an error message dialog.
+//
+//	manager.Error().SetMessage("Write failed").Show()
+func (dm *DialogManager) Error() *MessageDialog {
+	return newMessageDialog(ErrorDialogType)
+}

stubs/wails/pkg/application/environment.go

@@ -0,0 +1,63 @@
+package application
+
+// EnvironmentInfo holds runtime information about the host OS and build.
+//
+//	info := manager.Info()
+//	fmt.Println(info.OS, info.Arch)
+type EnvironmentInfo struct {
+	OS           string
+	Arch         string
+	Debug        bool
+	PlatformInfo map[string]any
+}
+
+// EnvironmentManager provides queries about the host OS environment.
+//
+//	if manager.IsDarkMode() { applyDarkTheme() }
+//	accent := manager.GetAccentColor()
+type EnvironmentManager struct {
+	darkMode    bool
+	accentColor string
+}
+
+// IsDarkMode returns true when the OS is using a dark colour scheme.
+//
+//	if manager.IsDarkMode() { applyDarkTheme() }
+func (em *EnvironmentManager) IsDarkMode() bool {
+	return em.darkMode
+}
+
+// GetAccentColor returns the OS accent colour as an rgb() string.
+//
+//	colour := manager.GetAccentColor() // e.g. "rgb(0,122,255)"
+func (em *EnvironmentManager) GetAccentColor() string {
+	if em.accentColor == "" {
+		return "rgb(0,122,255)"
+	}
+	return em.accentColor
+}
+
+// Info returns a snapshot of OS and build environment information.
+//
+//	info := manager.Info()
+func (em *EnvironmentManager) Info() EnvironmentInfo {
+	return EnvironmentInfo{
+		PlatformInfo: make(map[string]any),
+	}
+}
+
+// OpenFileManager opens the file manager at the given path, optionally selecting the file.
+// No-op in the stub.
+//
+//	err := manager.OpenFileManager("/home/user/docs", false)
+func (em *EnvironmentManager) OpenFileManager(path string, selectFile bool) error {
+	return nil
+}
+
+// HasFocusFollowsMouse reports whether the Linux desktop is configured for
+// focus-follows-mouse. Always returns false in the stub.
+//
+//	if manager.HasFocusFollowsMouse() { adjustMouseBehaviour() }
+func (em *EnvironmentManager) HasFocusFollowsMouse() bool {
+	return false
+}

stubs/wails/pkg/application/events.go

@@ -0,0 +1,297 @@
+package application
+
+import (
+	"sync"
+	"sync/atomic"
+
+	"github.com/wailsapp/wails/v3/pkg/events"
+)
+
+// ApplicationEventContext carries structured data for an ApplicationEvent.
+//
+//	files := event.Context().OpenedFiles()
+//	dark := event.Context().IsDarkMode()
+type ApplicationEventContext struct {
+	data map[string]any
+}
+
+// OpenedFiles returns the list of files provided via the event context, or nil.
+//
+//	for _, path := range event.Context().OpenedFiles() { open(path) }
+func (c *ApplicationEventContext) OpenedFiles() []string {
+	if c.data == nil {
+		return nil
+	}
+	files, ok := c.data["openedFiles"]
+	if !ok {
+		return nil
+	}
+	result, ok := files.([]string)
+	if !ok {
+		return nil
+	}
+	return result
+}
+
+// IsDarkMode returns true when the event context reports dark mode active.
+//
+//	if event.Context().IsDarkMode() { applyDark() }
+func (c *ApplicationEventContext) IsDarkMode() bool {
+	return c.getBool("isDarkMode")
+}
+
+// HasVisibleWindows returns true when the event context reports at least one visible window.
+//
+//	if event.Context().HasVisibleWindows() { ... }
+func (c *ApplicationEventContext) HasVisibleWindows() bool {
+	return c.getBool("hasVisibleWindows")
+}
+
+// Filename returns the filename value from the event context, or "".
+//
+//	path := event.Context().Filename()
+func (c *ApplicationEventContext) Filename() string {
+	if c.data == nil {
+		return ""
+	}
+	v, ok := c.data["filename"]
+	if !ok {
+		return ""
+	}
+	result, ok := v.(string)
+	if !ok {
+		return ""
+	}
+	return result
+}
+
+// URL returns the URL value from the event context, or "".
+//
+//	url := event.Context().URL()
+func (c *ApplicationEventContext) URL() string {
+	if c.data == nil {
+		return ""
+	}
+	v, ok := c.data["url"]
+	if !ok {
+		return ""
+	}
+	result, ok := v.(string)
+	if !ok {
+		return ""
+	}
+	return result
+}
+
+func (c *ApplicationEventContext) getBool(key string) bool {
+	if c.data == nil {
+		return false
+	}
+	v, ok := c.data[key]
+	if !ok {
+		return false
+	}
+	result, ok := v.(bool)
+	if !ok {
+		return false
+	}
+	return result
+}
+
+// ApplicationEvent is the event object delivered to OnApplicationEvent listeners.
+//
+//	em.OnApplicationEvent(events.Common.ThemeChanged, func(e *application.ApplicationEvent) {
+//	    dark := e.Context().IsDarkMode()
+//	})
+type ApplicationEvent struct {
+	Id        uint
+	ctx       *ApplicationEventContext
+	cancelled atomic.Bool
+}
+
+// Context returns the ApplicationEventContext attached to the event.
+func (e *ApplicationEvent) Context() *ApplicationEventContext {
+	if e.ctx == nil {
+		e.ctx = &ApplicationEventContext{data: make(map[string]any)}
+	}
+	return e.ctx
+}
+
+// Cancel marks the event as cancelled, preventing further listener dispatch.
+func (e *ApplicationEvent) Cancel() {
+	e.cancelled.Store(true)
+}
+
+// IsCancelled reports whether the event has been cancelled.
+func (e *ApplicationEvent) IsCancelled() bool {
+	return e.cancelled.Load()
+}
+
+// customEventListener is an internal listener registration.
+type customEventListener struct {
+	callback func(*CustomEvent)
+	counter  int // -1 = unlimited
+}
+
+// applicationEventListener is an internal listener registration.
+type applicationEventListener struct {
+	callback func(*ApplicationEvent)
+}
+
+// EventManager manages custom and application-level event subscriptions.
+//
+//	em.Emit("build:done", result)
+//	cancel := em.On("build:done", func(e *application.CustomEvent) { ... })
+//	em.OnApplicationEvent(events.Common.ThemeChanged, func(e *application.ApplicationEvent) { ... })
+type EventManager struct {
+	mu sync.RWMutex
+
+	customListeners      map[string][]*customEventListener
+	applicationListeners map[uint][]*applicationEventListener
+}
+
+func (em *EventManager) ensureCustomListeners() {
+	if em.customListeners == nil {
+		em.customListeners = make(map[string][]*customEventListener)
+	}
+}
+
+func (em *EventManager) ensureApplicationListeners() {
+	if em.applicationListeners == nil {
+		em.applicationListeners = make(map[uint][]*applicationEventListener)
+	}
+}
+
+// Emit emits a custom event by name with optional data arguments.
+// Returns true if the event was cancelled by a listener.
+//
+//	cancelled := em.Emit("build:done", buildResult)
+func (em *EventManager) Emit(name string, data ...any) bool {
+	event := &CustomEvent{Name: name}
+	if len(data) == 1 {
+		event.Data = data[0]
+	} else if len(data) > 1 {
+		event.Data = data
+	}
+	return em.EmitEvent(event)
+}
+
+// EmitEvent emits a pre-constructed CustomEvent.
+// Returns true if the event was cancelled by a listener.
+//
+//	cancelled := em.EmitEvent(&application.CustomEvent{Name: "ping"})
+func (em *EventManager) EmitEvent(event *CustomEvent) bool {
+	em.mu.RLock()
+	listeners := append([]*customEventListener(nil), em.customListeners[event.Name]...)
+	em.mu.RUnlock()
+
+	toRemove := []int{}
+	for index, listener := range listeners {
+		if event.IsCancelled() {
+			break
+		}
+		listener.callback(event)
+		if listener.counter > 0 {
+			listener.counter--
+			if listener.counter == 0 {
+				toRemove = append(toRemove, index)
+			}
+		}
+	}
+
+	if len(toRemove) > 0 {
+		em.mu.Lock()
+		remaining := em.customListeners[event.Name]
+		for _, index := range toRemove {
+			if index < len(remaining) {
+				remaining = append(remaining[:index], remaining[index+1:]...)
+			}
+		}
+		em.customListeners[event.Name] = remaining
+		em.mu.Unlock()
+	}
+
+	return event.IsCancelled()
+}
+
+// On registers a persistent listener for the named custom event.
+// Returns a cancel function that deregisters the listener.
+//
+//	cancel := em.On("build:done", func(e *application.CustomEvent) { ... })
+//	defer cancel()
+func (em *EventManager) On(name string, callback func(event *CustomEvent)) func() {
+	em.mu.Lock()
+	em.ensureCustomListeners()
+	listener := &customEventListener{callback: callback, counter: -1}
+	em.customListeners[name] = append(em.customListeners[name], listener)
+	em.mu.Unlock()
+
+	return func() {
+		em.mu.Lock()
+		defer em.mu.Unlock()
+		slice := em.customListeners[name]
+		for i, l := range slice {
+			if l == listener {
+				em.customListeners[name] = append(slice[:i], slice[i+1:]...)
+				return
+			}
+		}
+	}
+}
+
+// Off removes all listeners for the named custom event.
+//
+//	em.Off("build:done")
+func (em *EventManager) Off(name string) {
+	em.mu.Lock()
+	delete(em.customListeners, name)
+	em.mu.Unlock()
+}
+
+// OnMultiple registers a listener that fires at most counter times, then auto-deregisters.
+//
+//	em.OnMultiple("ping", func(e *application.CustomEvent) { ... }, 3)
+func (em *EventManager) OnMultiple(name string, callback func(event *CustomEvent), counter int) {
+	em.mu.Lock()
+	em.ensureCustomListeners()
+	em.customListeners[name] = append(em.customListeners[name], &customEventListener{
+		callback: callback,
+		counter:  counter,
+	})
+	em.mu.Unlock()
+}
+
+// Reset removes all custom event listeners.
+//
+//	em.Reset()
+func (em *EventManager) Reset() {
+	em.mu.Lock()
+	em.customListeners = make(map[string][]*customEventListener)
+	em.mu.Unlock()
+}
+
+// OnApplicationEvent registers a listener for a platform application event.
+// Returns a cancel function that deregisters the listener.
+//
+//	cancel := em.OnApplicationEvent(events.Common.ThemeChanged, func(e *application.ApplicationEvent) { ... })
+//	defer cancel()
+func (em *EventManager) OnApplicationEvent(eventType events.ApplicationEventType, callback func(event *ApplicationEvent)) func() {
+	eventID := uint(eventType)
+	em.mu.Lock()
+	em.ensureApplicationListeners()
+	listener := &applicationEventListener{callback: callback}
+	em.applicationListeners[eventID] = append(em.applicationListeners[eventID], listener)
+	em.mu.Unlock()
+
+	return func() {
+		em.mu.Lock()
+		defer em.mu.Unlock()
+		slice := em.applicationListeners[eventID]
+		for i, l := range slice {
+			if l == listener {
+				em.applicationListeners[eventID] = append(slice[:i], slice[i+1:]...)
+				return
+			}
+		}
+	}
+}

stubs/wails/pkg/application/keybinding.go

@@ -0,0 +1,69 @@
+package application
+
+import "sync"
+
+// KeyBinding pairs an accelerator string with its callback.
+// binding := &KeyBinding{Accelerator: "Ctrl+K", Callback: fn}
+type KeyBinding struct {
+	Accelerator string
+	Callback    func(window Window)
+}
+
+// KeyBindingManager holds all registered global key bindings in memory.
+// manager.Add("Ctrl+K", fn) — manager.Remove("Ctrl+K") — manager.GetAll()
+type KeyBindingManager struct {
+	mu       sync.RWMutex
+	bindings map[string]func(window Window)
+}
+
+// NewKeyBindingManager constructs an empty KeyBindingManager.
+// manager := NewKeyBindingManager()
+func NewKeyBindingManager() *KeyBindingManager {
+	return &KeyBindingManager{
+		bindings: make(map[string]func(window Window)),
+	}
+}
+
+// Add registers a callback for the given accelerator string.
+// manager.Add("Ctrl+Shift+P", func(w Window) { w.Focus() })
+func (m *KeyBindingManager) Add(accelerator string, callback func(window Window)) {
+	m.mu.Lock()
+	m.bindings[accelerator] = callback
+	m.mu.Unlock()
+}
+
+// Remove deletes the binding for the given accelerator.
+// manager.Remove("Ctrl+Shift+P")
+func (m *KeyBindingManager) Remove(accelerator string) {
+	m.mu.Lock()
+	delete(m.bindings, accelerator)
+	m.mu.Unlock()
+}
+
+// Process fires the callback for accelerator if registered, returning true when handled.
+// handled := manager.Process("Ctrl+K", window)
+func (m *KeyBindingManager) Process(accelerator string, window Window) bool {
+	m.mu.RLock()
+	callback, exists := m.bindings[accelerator]
+	m.mu.RUnlock()
+	if exists && callback != nil {
+		callback(window)
+		return true
+	}
+	return false
+}
+
+// GetAll returns a snapshot of all registered bindings.
+// for _, b := range manager.GetAll() { fmt.Println(b.Accelerator) }
+func (m *KeyBindingManager) GetAll() []*KeyBinding {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	result := make([]*KeyBinding, 0, len(m.bindings))
+	for accelerator, callback := range m.bindings {
+		result = append(result, &KeyBinding{
+			Accelerator: accelerator,
+			Callback:    callback,
+		})
+	}
+	return result
+}

stubs/wails/pkg/application/menuitem.go

@@ -0,0 +1,379 @@
+package application
+
+import "sync/atomic"
+
+// Role identifies a platform-defined menu role.
+//
+//	item := NewRole(Quit)   // produces the platform quit item
+type Role uint
+
+const (
+	NoRole       Role = iota
+	AppMenu      Role = iota
+	EditMenu      Role = iota
+	ViewMenu      Role = iota
+	WindowMenu    Role = iota
+	ServicesMenu  Role = iota
+	HelpMenu      Role = iota
+	SpeechMenu    Role = iota
+	FileMenu      Role = iota
+
+	Hide               Role = iota
+	HideOthers         Role = iota
+	ShowAll            Role = iota
+	BringAllToFront    Role = iota
+	UnHide             Role = iota
+	About              Role = iota
+	Undo               Role = iota
+	Redo               Role = iota
+	Cut                Role = iota
+	Copy               Role = iota
+	Paste              Role = iota
+	PasteAndMatchStyle Role = iota
+	SelectAll          Role = iota
+	Delete             Role = iota
+	Quit               Role = iota
+	CloseWindow        Role = iota
+	Reload             Role = iota
+	ForceReload        Role = iota
+	OpenDevTools       Role = iota
+	ResetZoom          Role = iota
+	ZoomIn             Role = iota
+	ZoomOut            Role = iota
+	ToggleFullscreen   Role = iota
+	Minimise           Role = iota
+	Zoom               Role = iota
+	FullScreen         Role = iota
+	NewFile            Role = iota
+	Open               Role = iota
+	Save               Role = iota
+	SaveAs             Role = iota
+	StartSpeaking      Role = iota
+	StopSpeaking       Role = iota
+	Revert             Role = iota
+	Print              Role = iota
+	PageLayout         Role = iota
+	Find               Role = iota
+	FindAndReplace     Role = iota
+	FindNext           Role = iota
+	FindPrevious       Role = iota
+	Front              Role = iota
+	Help               Role = iota
+)
+
+// menuItemType classifies what kind of item a MenuItem is.
+type menuItemType int
+
+const (
+	menuItemTypeText      menuItemType = iota
+	menuItemTypeSeparator menuItemType = iota
+	menuItemTypeCheckbox  menuItemType = iota
+	menuItemTypeRadio     menuItemType = iota
+	menuItemTypeSubmenu   menuItemType = iota
+)
+
+var globalMenuItemID uintptr
+
+// MenuItem is a node in a menu tree.
+//
+//	item := NewMenuItem("Preferences").
+//	    SetAccelerator("CmdOrCtrl+,").
+//	    OnClick(func(ctx *Context) { openPrefs() })
+type MenuItem struct {
+	id              uint
+	label           string
+	tooltip         string
+	disabled        bool
+	checked         bool
+	hidden          bool
+	bitmap          []byte
+	submenu         *Menu
+	callback        func(*Context)
+	itemType        menuItemType
+	acceleratorStr  string
+	role            Role
+	contextMenuData *ContextMenuData
+
+	radioGroupMembers []*MenuItem
+}
+
+func nextMenuItemID() uint {
+	return uint(atomic.AddUintptr(&globalMenuItemID, 1))
+}
+
+// NewMenuItem creates a standard clickable menu item with the given label.
+//
+//	item := NewMenuItem("Save").OnClick(func(ctx *Context) { save() })
+func NewMenuItem(label string) *MenuItem {
+	return &MenuItem{
+		id:       nextMenuItemID(),
+		label:    label,
+		itemType: menuItemTypeText,
+		disabled: false,
+	}
+}
+
+// NewMenuItemSeparator creates a horizontal separator.
+//
+//	menu.AppendItem(NewMenuItemSeparator())
+func NewMenuItemSeparator() *MenuItem {
+	return &MenuItem{
+		id:       nextMenuItemID(),
+		itemType: menuItemTypeSeparator,
+	}
+}
+
+// NewMenuItemCheckbox creates a checkable menu item.
+//
+//	item := NewMenuItemCheckbox("Show Toolbar", true)
+func NewMenuItemCheckbox(label string, checked bool) *MenuItem {
+	return &MenuItem{
+		id:       nextMenuItemID(),
+		label:    label,
+		checked:  checked,
+		itemType: menuItemTypeCheckbox,
+	}
+}
+
+// NewMenuItemRadio creates a radio-group menu item.
+//
+//	light := NewMenuItemRadio("Light Theme", true)
+func NewMenuItemRadio(label string, checked bool) *MenuItem {
+	return &MenuItem{
+		id:       nextMenuItemID(),
+		label:    label,
+		checked:  checked,
+		itemType: menuItemTypeRadio,
+	}
+}
+
+// NewSubMenuItem creates an item that reveals a child menu on hover.
+//
+//	sub := NewSubMenuItem("Recent Files")
+//	sub.GetSubmenu().Add("report.pdf")
+func NewSubMenuItem(label string) *MenuItem {
+	return &MenuItem{
+		id:       nextMenuItemID(),
+		label:    label,
+		itemType: menuItemTypeSubmenu,
+		submenu:  &Menu{label: label},
+	}
+}
+
+// NewRole creates a platform-managed menu item for the given role.
+//
+//	menu.AppendItem(NewRole(Quit))
+func NewRole(role Role) *MenuItem {
+	item := &MenuItem{
+		id:       nextMenuItemID(),
+		label:    roleLabel(role),
+		itemType: menuItemTypeText,
+		role:     role,
+	}
+	return item
+}
+
+func roleLabel(role Role) string {
+	switch role {
+	case AppMenu:
+		return "Application"
+	case EditMenu:
+		return "Edit"
+	case ViewMenu:
+		return "View"
+	case WindowMenu:
+		return "Window"
+	case ServicesMenu:
+		return "Services"
+	case HelpMenu:
+		return "Help"
+	case SpeechMenu:
+		return "Speech"
+	case FileMenu:
+		return "File"
+	case Hide:
+		return "Hide"
+	case HideOthers:
+		return "Hide Others"
+	case ShowAll:
+		return "Show All"
+	case BringAllToFront:
+		return "Bring All to Front"
+	case UnHide:
+		return "Unhide"
+	case About:
+		return "About"
+	case Undo:
+		return "Undo"
+	case Redo:
+		return "Redo"
+	case Cut:
+		return "Cut"
+	case Copy:
+		return "Copy"
+	case Paste:
+		return "Paste"
+	case PasteAndMatchStyle:
+		return "Paste and Match Style"
+	case SelectAll:
+		return "Select All"
+	case Delete:
+		return "Delete"
+	case Quit:
+		return "Quit"
+	case CloseWindow:
+		return "Close Window"
+	case Reload:
+		return "Reload"
+	case ForceReload:
+		return "Force Reload"
+	case OpenDevTools:
+		return "Open Dev Tools"
+	case ResetZoom:
+		return "Reset Zoom"
+	case ZoomIn:
+		return "Zoom In"
+	case ZoomOut:
+		return "Zoom Out"
+	case ToggleFullscreen:
+		return "Toggle Fullscreen"
+	case Minimise:
+		return "Minimise"
+	case Zoom:
+		return "Zoom"
+	case FullScreen:
+		return "Fullscreen"
+	case NewFile:
+		return "New"
+	case Open:
+		return "Open"
+	case Save:
+		return "Save"
+	case SaveAs:
+		return "Save As"
+	case StartSpeaking:
+		return "Start Speaking"
+	case StopSpeaking:
+		return "Stop Speaking"
+	case Revert:
+		return "Revert"
+	case Print:
+		return "Print"
+	case PageLayout:
+		return "Page Layout"
+	case Find:
+		return "Find"
+	case FindAndReplace:
+		return "Find and Replace"
+	case FindNext:
+		return "Find Next"
+	case FindPrevious:
+		return "Find Previous"
+	case Front:
+		return "Bring All to Front"
+	case Help:
+		return "Help"
+	default:
+		return ""
+	}
+}
+
+// Fluent setters — all return *MenuItem for chaining.
+
+// SetLabel updates the visible label.
+func (m *MenuItem) SetLabel(s string) *MenuItem { m.label = s; return m }
+
+// SetAccelerator sets the keyboard shortcut string (e.g. "CmdOrCtrl+S").
+func (m *MenuItem) SetAccelerator(shortcut string) *MenuItem {
+	m.acceleratorStr = shortcut
+	return m
+}
+
+// GetAccelerator returns the raw accelerator string.
+func (m *MenuItem) GetAccelerator() string { return m.acceleratorStr }
+
+// RemoveAccelerator clears the keyboard shortcut.
+func (m *MenuItem) RemoveAccelerator() { m.acceleratorStr = "" }
+
+// SetTooltip sets the hover tooltip.
+func (m *MenuItem) SetTooltip(s string) *MenuItem { m.tooltip = s; return m }
+
+// SetRole assigns a platform role to the item.
+func (m *MenuItem) SetRole(role Role) *MenuItem { m.role = role; return m }
+
+// SetEnabled enables or disables the item.
+func (m *MenuItem) SetEnabled(enabled bool) *MenuItem { m.disabled = !enabled; return m }
+
+// SetBitmap sets a raw-bytes icon for the item (Windows).
+func (m *MenuItem) SetBitmap(bitmap []byte) *MenuItem {
+	m.bitmap = append([]byte(nil), bitmap...)
+	return m
+}
+
+// SetChecked sets the checked state for checkbox/radio items.
+func (m *MenuItem) SetChecked(checked bool) *MenuItem { m.checked = checked; return m }
+
+// SetHidden hides or shows the item without removing it.
+func (m *MenuItem) SetHidden(hidden bool) *MenuItem { m.hidden = hidden; return m }
+
+// OnClick registers the callback invoked when the item is activated.
+func (m *MenuItem) OnClick(f func(*Context)) *MenuItem { m.callback = f; return m }
+
+// Getters
+
+// Label returns the item's display label.
+func (m *MenuItem) Label() string { return m.label }
+
+// Tooltip returns the hover tooltip.
+func (m *MenuItem) Tooltip() string { return m.tooltip }
+
+// Enabled reports whether the item is interactive.
+func (m *MenuItem) Enabled() bool { return !m.disabled }
+
+// Checked reports whether the item is checked.
+func (m *MenuItem) Checked() bool { return m.checked }
+
+// Hidden reports whether the item is hidden.
+func (m *MenuItem) Hidden() bool { return m.hidden }
+
+// IsSeparator reports whether this is a separator item.
+func (m *MenuItem) IsSeparator() bool { return m.itemType == menuItemTypeSeparator }
+
+// IsSubmenu reports whether this item contains a child menu.
+func (m *MenuItem) IsSubmenu() bool { return m.itemType == menuItemTypeSubmenu }
+
+// IsCheckbox reports whether this is a checkbox item.
+func (m *MenuItem) IsCheckbox() bool { return m.itemType == menuItemTypeCheckbox }
+
+// IsRadio reports whether this is a radio item.
+func (m *MenuItem) IsRadio() bool { return m.itemType == menuItemTypeRadio }
+
+// GetSubmenu returns the submenu, or nil if this is not a submenu item.
+func (m *MenuItem) GetSubmenu() *Menu { return m.submenu }
+
+// Clone returns a shallow copy of the MenuItem.
+func (m *MenuItem) Clone() *MenuItem {
+	cloned := *m
+	if m.submenu != nil {
+		cloned.submenu = m.submenu.Clone()
+	}
+	if m.bitmap != nil {
+		cloned.bitmap = append([]byte(nil), m.bitmap...)
+	}
+	if m.contextMenuData != nil {
+		cloned.contextMenuData = m.contextMenuData.clone()
+	}
+	cloned.radioGroupMembers = nil
+	return &cloned
+}
+
+// Destroy frees resources held by the item and its submenu.
+func (m *MenuItem) Destroy() {
+	if m.submenu != nil {
+		m.submenu.Destroy()
+		m.submenu = nil
+	}
+	m.callback = nil
+	m.radioGroupMembers = nil
+	m.contextMenuData = nil
+}

stubs/wails/pkg/application/screen.go

@@ -0,0 +1,202 @@
+package application
+
+import (
+	"math"
+	"sync"
+)
+
+// Rect describes an axis-aligned rectangle.
+// r := Rect{X: 0, Y: 0, Width: 1920, Height: 1080}
+type Rect struct {
+	X      int
+	Y      int
+	Width  int
+	Height int
+}
+
+// Point is a 2D integer coordinate.
+// p := Point{X: 100, Y: 200}
+type Point struct {
+	X int
+	Y int
+}
+
+// Size holds a width/height pair.
+// s := Size{Width: 1920, Height: 1080}
+type Size struct {
+	Width  int
+	Height int
+}
+
+// Origin returns the top-left corner of the rect as a Point.
+// origin := r.Origin()
+func (r Rect) Origin() Point { return Point{X: r.X, Y: r.Y} }
+
+// Corner returns the exclusive bottom-right corner of the rect.
+// corner := r.Corner()
+func (r Rect) Corner() Point { return Point{X: r.X + r.Width, Y: r.Y + r.Height} }
+
+// InsideCorner returns the last pixel inside the rect.
+// inside := r.InsideCorner()
+func (r Rect) InsideCorner() Point { return Point{X: r.X + r.Width - 1, Y: r.Y + r.Height - 1} }
+
+// RectSize returns the size of the rect.
+// s := r.RectSize()
+func (r Rect) RectSize() Size { return Size{Width: r.Width, Height: r.Height} }
+
+// IsEmpty reports whether the rect has no area.
+// if r.IsEmpty() { return }
+func (r Rect) IsEmpty() bool { return r.Width <= 0 || r.Height <= 0 }
+
+// Contains reports whether the point lies inside the rect.
+// if r.Contains(Point{X: 100, Y: 200}) { ... }
+func (r Rect) Contains(point Point) bool {
+	return point.X >= r.X && point.X < r.X+r.Width &&
+		point.Y >= r.Y && point.Y < r.Y+r.Height
+}
+
+// Intersect returns the overlapping rectangle of r and other.
+// overlap := r.Intersect(otherRect)
+func (r Rect) Intersect(other Rect) Rect {
+	if r.IsEmpty() || other.IsEmpty() {
+		return Rect{}
+	}
+	maxLeft := max(r.X, other.X)
+	maxTop := max(r.Y, other.Y)
+	minRight := min(r.X+r.Width, other.X+other.Width)
+	minBottom := min(r.Y+r.Height, other.Y+other.Height)
+	if minRight > maxLeft && minBottom > maxTop {
+		return Rect{X: maxLeft, Y: maxTop, Width: minRight - maxLeft, Height: minBottom - maxTop}
+	}
+	return Rect{}
+}
+
+// Screen describes a physical display.
+// primary := manager.GetPrimary()
+type Screen struct {
+	ID               string
+	Name             string
+	ScaleFactor      float32
+	X                int
+	Y                int
+	Size             Size
+	Bounds           Rect
+	PhysicalBounds   Rect
+	WorkArea         Rect
+	PhysicalWorkArea Rect
+	IsPrimary        bool
+	Rotation         float32
+}
+
+// Origin returns the logical origin of the screen.
+// origin := screen.Origin()
+func (s Screen) Origin() Point { return Point{X: s.X, Y: s.Y} }
+
+// scale converts a value between physical and DIP coordinates for this screen.
+func (s Screen) scale(value int, toDIP bool) int {
+	if toDIP {
+		return int(math.Ceil(float64(value) / float64(s.ScaleFactor)))
+	}
+	return int(math.Floor(float64(value) * float64(s.ScaleFactor)))
+}
+
+// ScreenManager holds the list of known screens in memory.
+// screens := manager.GetAll()
+type ScreenManager struct {
+	mu            sync.RWMutex
+	screens       []*Screen
+	primaryScreen *Screen
+}
+
+// NewScreenManager constructs an empty ScreenManager.
+// manager := NewScreenManager()
+func NewScreenManager() *ScreenManager {
+	return &ScreenManager{}
+}
+
+// SetScreens replaces the tracked screen list; the first screen with IsPrimary == true becomes primary.
+// manager.SetScreens([]*Screen{primary, secondary})
+func (m *ScreenManager) SetScreens(screens []*Screen) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.screens = screens
+	m.primaryScreen = nil
+	for _, screen := range screens {
+		if screen.IsPrimary {
+			m.primaryScreen = screen
+			break
+		}
+	}
+}
+
+// GetAll returns all tracked screens.
+// for _, s := range manager.GetAll() { fmt.Println(s.Name) }
+func (m *ScreenManager) GetAll() []*Screen {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	result := make([]*Screen, len(m.screens))
+	copy(result, m.screens)
+	return result
+}
+
+// GetPrimary returns the primary screen, or nil if none is set.
+// primary := manager.GetPrimary()
+func (m *ScreenManager) GetPrimary() *Screen {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	return m.primaryScreen
+}
+
+// GetCurrent returns the screen nearest to the given DIP point.
+// current := manager.GetCurrent(Point{X: 500, Y: 300})
+func (m *ScreenManager) GetCurrent(dipPoint Point) *Screen {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	for _, screen := range m.screens {
+		if screen.Bounds.Contains(dipPoint) {
+			return screen
+		}
+	}
+	return m.primaryScreen
+}
+
+// DipToPhysicalPoint converts a DIP point to physical pixels using the nearest screen.
+// physical := manager.DipToPhysicalPoint(Point{X: 100, Y: 200})
+func (m *ScreenManager) DipToPhysicalPoint(dipPoint Point) Point {
+	screen := m.GetCurrent(dipPoint)
+	if screen == nil {
+		return dipPoint
+	}
+	relativeX := dipPoint.X - screen.Bounds.X
+	relativeY := dipPoint.Y - screen.Bounds.Y
+	return Point{
+		X: screen.PhysicalBounds.X + screen.scale(relativeX, false),
+		Y: screen.PhysicalBounds.Y + screen.scale(relativeY, false),
+	}
+}
+
+// PhysicalToDipPoint converts physical pixel coordinates to DIP using the nearest screen.
+// dip := manager.PhysicalToDipPoint(Point{X: 200, Y: 400})
+func (m *ScreenManager) PhysicalToDipPoint(physicalPoint Point) Point {
+	m.mu.RLock()
+	var nearest *Screen
+	for _, screen := range m.screens {
+		if screen.PhysicalBounds.Contains(physicalPoint) {
+			nearest = screen
+			break
+		}
+	}
+	if nearest == nil {
+		nearest = m.primaryScreen
+	}
+	m.mu.RUnlock()
+	if nearest == nil {
+		return physicalPoint
+	}
+	relativeX := physicalPoint.X - nearest.PhysicalBounds.X
+	relativeY := physicalPoint.Y - nearest.PhysicalBounds.Y
+	return Point{
+		X: nearest.Bounds.X + nearest.scale(relativeX, true),
+		Y: nearest.Bounds.Y + nearest.scale(relativeY, true),
+	}
+}

stubs/wails/pkg/application/services.go

@@ -0,0 +1,76 @@
+package application
+
+import "context"
+
+// Service wraps a bound type instance for registration with the application.
+// svc := NewService(&MyService{})
+type Service struct {
+	instance any
+	options  ServiceOptions
+}
+
+// ServiceOptions provides optional configuration for a Service.
+// opts := ServiceOptions{Name: "my-service", Route: "/api/my"}
+type ServiceOptions struct {
+	// Name overrides the service name used in logging and debugging.
+	// Defaults to the value from ServiceName interface, or the type name.
+	Name string
+
+	// Route mounts the service on the internal asset server at this path
+	// when the instance implements http.Handler.
+	Route string
+
+	// MarshalError serialises errors returned by service methods to JSON.
+	// Return nil to fall back to the globally configured error handler.
+	MarshalError func(error) []byte
+}
+
+// DefaultServiceOptions is the default service options used by NewService.
+var DefaultServiceOptions = ServiceOptions{}
+
+// NewService wraps instance as a Service.
+// svc := NewService(&Calculator{})
+func NewService[T any](instance *T) Service {
+	return Service{instance: instance, options: DefaultServiceOptions}
+}
+
+// NewServiceWithOptions wraps instance as a Service with explicit options.
+// svc := NewServiceWithOptions(&Calculator{}, ServiceOptions{Name: "calculator"})
+func NewServiceWithOptions[T any](instance *T, options ServiceOptions) Service {
+	service := NewService(instance)
+	service.options = options
+	return service
+}
+
+// Instance returns the underlying pointer passed to NewService.
+// raw := svc.Instance().(*Calculator)
+func (s Service) Instance() any {
+	return s.instance
+}
+
+// Options returns the ServiceOptions for this service.
+// opts := svc.Options()
+func (s Service) Options() ServiceOptions {
+	return s.options
+}
+
+// ServiceName is an optional interface that service instances may implement
+// to provide a human-readable name for logging and debugging.
+// func (s *MyService) ServiceName() string { return "my-service" }
+type ServiceName interface {
+	ServiceName() string
+}
+
+// ServiceStartup is an optional interface for services that need initialisation.
+// Called in registration order during application startup.
+// func (s *MyService) ServiceStartup(ctx context.Context, opts ServiceOptions) error { ... }
+type ServiceStartup interface {
+	ServiceStartup(ctx context.Context, options ServiceOptions) error
+}
+
+// ServiceShutdown is an optional interface for services that need cleanup.
+// Called in reverse registration order during application shutdown.
+// func (s *MyService) ServiceShutdown() error { ... }
+type ServiceShutdown interface {
+	ServiceShutdown() error
+}

stubs/wails/pkg/application/webview_window_options.go

@@ -0,0 +1,471 @@
+package application
+
+import "github.com/wailsapp/wails/v3/pkg/events"
+
+// WindowState represents the starting visual state of a window.
+type WindowState int
+
+const (
+	WindowStateNormal     WindowState = iota
+	WindowStateMinimised  WindowState = iota
+	WindowStateMaximised  WindowState = iota
+	WindowStateFullscreen WindowState = iota
+)
+
+// WindowStartPosition determines how the initial X/Y coordinates are interpreted.
+type WindowStartPosition int
+
+const (
+	// WindowCentered places the window in the centre of the screen on first show.
+	WindowCentered WindowStartPosition = 0
+	// WindowXY places the window at the explicit X/Y coordinates.
+	WindowXY WindowStartPosition = 1
+)
+
+// BackgroundType controls window transparency.
+type BackgroundType int
+
+const (
+	BackgroundTypeSolid       BackgroundType = iota
+	BackgroundTypeTransparent BackgroundType = iota
+	BackgroundTypeTranslucent BackgroundType = iota
+)
+
+// WebviewWindowOptions holds all configuration for a webview window.
+//
+//	opts := WebviewWindowOptions{
+//	    Name:   "main",
+//	    Title:  "My App",
+//	    Width:  1280,
+//	    Height: 800,
+//	    Mac:    MacWindow{TitleBar: MacTitleBarHiddenInset},
+//	}
+type WebviewWindowOptions struct {
+	// Name is a unique identifier for the window.
+	Name string
+	// Title is shown in the title bar.
+	Title string
+	// Width is the initial width in logical pixels.
+	Width int
+	// Height is the initial height in logical pixels.
+	Height int
+	// AlwaysOnTop makes the window float above others.
+	AlwaysOnTop bool
+	// URL is the URL to load on creation.
+	URL string
+	// HTML is inline HTML to load (alternative to URL).
+	HTML string
+	// JS is inline JavaScript to inject.
+	JS string
+	// CSS is inline CSS to inject.
+	CSS string
+	// DisableResize prevents the user from resizing the window.
+	DisableResize bool
+	// Frameless removes the OS window frame.
+	Frameless bool
+	// MinWidth is the minimum allowed width.
+	MinWidth int
+	// MinHeight is the minimum allowed height.
+	MinHeight int
+	// MaxWidth is the maximum allowed width (0 = unlimited).
+	MaxWidth int
+	// MaxHeight is the maximum allowed height (0 = unlimited).
+	MaxHeight int
+	// StartState sets the visual state when first shown.
+	StartState WindowState
+	// BackgroundType controls transparency.
+	BackgroundType BackgroundType
+	// BackgroundColour is the solid background fill colour.
+	BackgroundColour RGBA
+	// InitialPosition controls how X/Y are interpreted.
+	InitialPosition WindowStartPosition
+	// X is the initial horizontal position.
+	X int
+	// Y is the initial vertical position.
+	Y int
+	// Hidden creates the window without showing it.
+	Hidden bool
+	// Zoom sets the initial zoom magnification (0 = default = 1.0).
+	Zoom float64
+	// ZoomControlEnabled allows the user to change zoom.
+	ZoomControlEnabled bool
+	// EnableFileDrop enables drag-and-drop of files onto the window.
+	EnableFileDrop bool
+	// OpenInspectorOnStartup opens the web inspector when first shown.
+	OpenInspectorOnStartup bool
+	// DevToolsEnabled exposes the developer tools (default true in debug builds).
+	DevToolsEnabled bool
+	// DefaultContextMenuDisabled disables the built-in right-click menu.
+	DefaultContextMenuDisabled bool
+	// KeyBindings is a map of accelerator strings to window callbacks.
+	KeyBindings map[string]func(window Window)
+	// IgnoreMouseEvents passes all mouse events through (Windows + macOS only).
+	IgnoreMouseEvents bool
+	// ContentProtectionEnabled prevents screen capture (Windows + macOS only).
+	ContentProtectionEnabled bool
+	// HideOnFocusLost hides the window when it loses focus.
+	HideOnFocusLost bool
+	// HideOnEscape hides the window when Escape is pressed.
+	HideOnEscape bool
+	// UseApplicationMenu uses the application-level menu for this window.
+	UseApplicationMenu bool
+	// MinimiseButtonState controls the minimise button state.
+	MinimiseButtonState ButtonState
+	// MaximiseButtonState controls the maximise/zoom button state.
+	MaximiseButtonState ButtonState
+	// CloseButtonState controls the close button state.
+	CloseButtonState ButtonState
+	// Mac contains macOS-specific window options.
+	Mac MacWindow
+	// Windows contains Windows-specific window options.
+	Windows WindowsWindow
+	// Linux contains Linux-specific window options.
+	Linux LinuxWindow
+}
+
+// -------------------------
+// macOS-specific types
+// -------------------------
+
+// MacBackdrop is the backdrop material for a macOS window.
+type MacBackdrop int
+
+const (
+	// MacBackdropNormal uses an opaque background.
+	MacBackdropNormal MacBackdrop = iota
+	// MacBackdropTransparent shows the desktop behind the window.
+	MacBackdropTransparent MacBackdrop = iota
+	// MacBackdropTranslucent applies a frosted-glass vibrancy effect.
+	MacBackdropTranslucent MacBackdrop = iota
+	// MacBackdropLiquidGlass uses the Apple Liquid Glass effect (macOS 15+).
+	MacBackdropLiquidGlass MacBackdrop = iota
+)
+
+// MacToolbarStyle controls toolbar layout relative to the title bar.
+type MacToolbarStyle int
+
+const (
+	MacToolbarStyleAutomatic      MacToolbarStyle = iota
+	MacToolbarStyleExpanded       MacToolbarStyle = iota
+	MacToolbarStylePreference     MacToolbarStyle = iota
+	MacToolbarStyleUnified        MacToolbarStyle = iota
+	MacToolbarStyleUnifiedCompact MacToolbarStyle = iota
+)
+
+// MacLiquidGlassStyle defines the tint of the Liquid Glass effect.
+type MacLiquidGlassStyle int
+
+const (
+	LiquidGlassStyleAutomatic MacLiquidGlassStyle = iota
+	LiquidGlassStyleLight     MacLiquidGlassStyle = iota
+	LiquidGlassStyleDark      MacLiquidGlassStyle = iota
+	LiquidGlassStyleVibrant   MacLiquidGlassStyle = iota
+)
+
+// NSVisualEffectMaterial maps to the NSVisualEffectMaterial macOS enum.
+type NSVisualEffectMaterial int
+
+const (
+	NSVisualEffectMaterialAppearanceBased       NSVisualEffectMaterial = 0
+	NSVisualEffectMaterialLight                 NSVisualEffectMaterial = 1
+	NSVisualEffectMaterialDark                  NSVisualEffectMaterial = 2
+	NSVisualEffectMaterialTitlebar              NSVisualEffectMaterial = 3
+	NSVisualEffectMaterialSelection             NSVisualEffectMaterial = 4
+	NSVisualEffectMaterialMenu                  NSVisualEffectMaterial = 5
+	NSVisualEffectMaterialPopover               NSVisualEffectMaterial = 6
+	NSVisualEffectMaterialSidebar               NSVisualEffectMaterial = 7
+	NSVisualEffectMaterialHeaderView            NSVisualEffectMaterial = 10
+	NSVisualEffectMaterialSheet                 NSVisualEffectMaterial = 11
+	NSVisualEffectMaterialWindowBackground      NSVisualEffectMaterial = 12
+	NSVisualEffectMaterialHUDWindow             NSVisualEffectMaterial = 13
+	NSVisualEffectMaterialFullScreenUI          NSVisualEffectMaterial = 15
+	NSVisualEffectMaterialToolTip               NSVisualEffectMaterial = 17
+	NSVisualEffectMaterialContentBackground     NSVisualEffectMaterial = 18
+	NSVisualEffectMaterialUnderWindowBackground NSVisualEffectMaterial = 21
+	NSVisualEffectMaterialUnderPageBackground   NSVisualEffectMaterial = 22
+	NSVisualEffectMaterialAuto                  NSVisualEffectMaterial = -1
+)
+
+// MacLiquidGlass configures the Liquid Glass compositor effect.
+type MacLiquidGlass struct {
+	Style        MacLiquidGlassStyle
+	Material     NSVisualEffectMaterial
+	CornerRadius float64
+	TintColor    *RGBA
+	GroupID      string
+	GroupSpacing float64
+}
+
+// MacAppearanceType is the NSAppearance name string for a macOS window.
+type MacAppearanceType string
+
+const (
+	DefaultAppearance                                    MacAppearanceType = ""
+	NSAppearanceNameAqua                                 MacAppearanceType = "NSAppearanceNameAqua"
+	NSAppearanceNameDarkAqua                             MacAppearanceType = "NSAppearanceNameDarkAqua"
+	NSAppearanceNameVibrantLight                         MacAppearanceType = "NSAppearanceNameVibrantLight"
+	NSAppearanceNameAccessibilityHighContrastAqua        MacAppearanceType = "NSAppearanceNameAccessibilityHighContrastAqua"
+	NSAppearanceNameAccessibilityHighContrastDarkAqua    MacAppearanceType = "NSAppearanceNameAccessibilityHighContrastDarkAqua"
+	NSAppearanceNameAccessibilityHighContrastVibrantLight MacAppearanceType = "NSAppearanceNameAccessibilityHighContrastVibrantLight"
+	NSAppearanceNameAccessibilityHighContrastVibrantDark  MacAppearanceType = "NSAppearanceNameAccessibilityHighContrastVibrantDark"
+)
+
+// MacWindowLevel controls Z-ordering relative to other windows.
+type MacWindowLevel string
+
+const (
+	MacWindowLevelNormal      MacWindowLevel = "normal"
+	MacWindowLevelFloating    MacWindowLevel = "floating"
+	MacWindowLevelTornOffMenu MacWindowLevel = "tornOffMenu"
+	MacWindowLevelModalPanel  MacWindowLevel = "modalPanel"
+	MacWindowLevelMainMenu    MacWindowLevel = "mainMenu"
+	MacWindowLevelStatus      MacWindowLevel = "status"
+	MacWindowLevelPopUpMenu   MacWindowLevel = "popUpMenu"
+	MacWindowLevelScreenSaver MacWindowLevel = "screenSaver"
+)
+
+// MacWindowCollectionBehavior is a bitmask controlling Spaces and fullscreen behaviour.
+type MacWindowCollectionBehavior int
+
+const (
+	MacWindowCollectionBehaviorDefault                   MacWindowCollectionBehavior = 0
+	MacWindowCollectionBehaviorCanJoinAllSpaces          MacWindowCollectionBehavior = 1 << 0
+	MacWindowCollectionBehaviorMoveToActiveSpace         MacWindowCollectionBehavior = 1 << 1
+	MacWindowCollectionBehaviorManaged                   MacWindowCollectionBehavior = 1 << 2
+	MacWindowCollectionBehaviorTransient                 MacWindowCollectionBehavior = 1 << 3
+	MacWindowCollectionBehaviorStationary                MacWindowCollectionBehavior = 1 << 4
+	MacWindowCollectionBehaviorParticipatesInCycle       MacWindowCollectionBehavior = 1 << 5
+	MacWindowCollectionBehaviorIgnoresCycle              MacWindowCollectionBehavior = 1 << 6
+	MacWindowCollectionBehaviorFullScreenPrimary         MacWindowCollectionBehavior = 1 << 7
+	MacWindowCollectionBehaviorFullScreenAuxiliary       MacWindowCollectionBehavior = 1 << 8
+	MacWindowCollectionBehaviorFullScreenNone            MacWindowCollectionBehavior = 1 << 9
+	MacWindowCollectionBehaviorFullScreenAllowsTiling    MacWindowCollectionBehavior = 1 << 11
+	MacWindowCollectionBehaviorFullScreenDisallowsTiling MacWindowCollectionBehavior = 1 << 12
+)
+
+// MacWebviewPreferences holds WKWebView preference flags for macOS.
+// Use integer tristate: 0 = unset, 1 = true, 2 = false.
+type MacWebviewPreferences struct {
+	TabFocusesLinks                     int
+	TextInteractionEnabled              int
+	FullscreenEnabled                   int
+	AllowsBackForwardNavigationGestures int
+}
+
+// MacTitleBar configures the macOS title bar appearance.
+type MacTitleBar struct {
+	// AppearsTransparent removes the title bar background.
+	AppearsTransparent bool
+	// Hide removes the title bar entirely.
+	Hide bool
+	// HideTitle hides only the text title.
+	HideTitle bool
+	// FullSizeContent extends window content into the title bar area.
+	FullSizeContent bool
+	// UseToolbar replaces the title bar with an NSToolbar.
+	UseToolbar bool
+	// HideToolbarSeparator removes the line between toolbar and content.
+	HideToolbarSeparator bool
+	// ShowToolbarWhenFullscreen keeps the toolbar visible in fullscreen.
+	ShowToolbarWhenFullscreen bool
+	// ToolbarStyle selects the toolbar layout style.
+	ToolbarStyle MacToolbarStyle
+}
+
+// MacWindow contains macOS-specific window options.
+type MacWindow struct {
+	Backdrop                        MacBackdrop
+	DisableShadow                   bool
+	TitleBar                        MacTitleBar
+	Appearance                      MacAppearanceType
+	InvisibleTitleBarHeight         int
+	EventMapping                    map[events.WindowEventType]events.WindowEventType
+	EnableFraudulentWebsiteWarnings bool
+	WebviewPreferences              MacWebviewPreferences
+	WindowLevel                     MacWindowLevel
+	CollectionBehavior              MacWindowCollectionBehavior
+	LiquidGlass                     MacLiquidGlass
+}
+
+// Pre-built MacTitleBar configurations — use directly in MacWindow.TitleBar.
+
+// MacTitleBarDefault produces the standard macOS title bar.
+//
+//	Mac: MacWindow{TitleBar: MacTitleBarDefault}
+var MacTitleBarDefault = MacTitleBar{}
+
+// MacTitleBarHidden hides the title text while keeping the traffic-light buttons.
+//
+//	Mac: MacWindow{TitleBar: MacTitleBarHidden}
+var MacTitleBarHidden = MacTitleBar{
+	AppearsTransparent: true,
+	HideTitle:          true,
+	FullSizeContent:    true,
+}
+
+// MacTitleBarHiddenInset keeps traffic lights slightly inset from the window edge.
+//
+//	Mac: MacWindow{TitleBar: MacTitleBarHiddenInset}
+var MacTitleBarHiddenInset = MacTitleBar{
+	AppearsTransparent:   true,
+	HideTitle:            true,
+	FullSizeContent:      true,
+	UseToolbar:           true,
+	HideToolbarSeparator: true,
+}
+
+// MacTitleBarHiddenInsetUnified uses the unified toolbar style for a more compact look.
+//
+//	Mac: MacWindow{TitleBar: MacTitleBarHiddenInsetUnified}
+var MacTitleBarHiddenInsetUnified = MacTitleBar{
+	AppearsTransparent:   true,
+	HideTitle:            true,
+	FullSizeContent:      true,
+	UseToolbar:           true,
+	HideToolbarSeparator: true,
+	ToolbarStyle:         MacToolbarStyleUnified,
+}
+
+// -------------------------
+// Windows-specific types
+// -------------------------
+
+// BackdropType selects the Windows 11 compositor effect.
+type BackdropType int32
+
+const (
+	Auto    BackdropType = 0
+	None    BackdropType = 1
+	Mica    BackdropType = 2
+	Acrylic BackdropType = 3
+	Tabbed  BackdropType = 4
+)
+
+// Theme selects dark or light mode on Windows.
+type Theme int
+
+const (
+	SystemDefault Theme = 0
+	Dark          Theme = 1
+	Light         Theme = 2
+)
+
+// WindowTheme holds custom title-bar colours for a Windows window.
+type WindowTheme struct {
+	BorderColour    *uint32
+	TitleBarColour  *uint32
+	TitleTextColour *uint32
+}
+
+// TextTheme holds foreground/background colour pair for menu text.
+type TextTheme struct {
+	Text       *uint32
+	Background *uint32
+}
+
+// MenuBarTheme holds per-state text themes for the Windows menu bar.
+type MenuBarTheme struct {
+	Default  *TextTheme
+	Hover    *TextTheme
+	Selected *TextTheme
+}
+
+// ThemeSettings holds custom colours for dark/light mode on Windows.
+// Colours use 0x00BBGGRR encoding.
+type ThemeSettings struct {
+	DarkModeActive    *WindowTheme
+	DarkModeInactive  *WindowTheme
+	LightModeActive   *WindowTheme
+	LightModeInactive *WindowTheme
+	DarkModeMenuBar   *MenuBarTheme
+	LightModeMenuBar  *MenuBarTheme
+}
+
+// CoreWebView2PermissionKind identifies a WebView2 permission category.
+type CoreWebView2PermissionKind uint32
+
+const (
+	CoreWebView2PermissionKindUnknownPermission CoreWebView2PermissionKind = iota
+	CoreWebView2PermissionKindMicrophone
+	CoreWebView2PermissionKindCamera
+	CoreWebView2PermissionKindGeolocation
+	CoreWebView2PermissionKindNotifications
+	CoreWebView2PermissionKindOtherSensors
+	CoreWebView2PermissionKindClipboardRead
+)
+
+// CoreWebView2PermissionState sets whether a permission is granted.
+type CoreWebView2PermissionState uint32
+
+const (
+	CoreWebView2PermissionStateDefault CoreWebView2PermissionState = iota
+	CoreWebView2PermissionStateAllow
+	CoreWebView2PermissionStateDeny
+)
+
+// WindowsWindow contains Windows-specific window options.
+type WindowsWindow struct {
+	BackdropType                      BackdropType
+	DisableIcon                       bool
+	Theme                             Theme
+	CustomTheme                       ThemeSettings
+	DisableFramelessWindowDecorations bool
+	WindowMask                        []byte
+	WindowMaskDraggable               bool
+	ResizeDebounceMS                  uint16
+	WindowDidMoveDebounceMS           uint16
+	EventMapping                      map[events.WindowEventType]events.WindowEventType
+	HiddenOnTaskbar                   bool
+	EnableSwipeGestures               bool
+	Menu                              *Menu
+	Permissions                       map[CoreWebView2PermissionKind]CoreWebView2PermissionState
+	ExStyle                           int
+	GeneralAutofillEnabled            bool
+	PasswordAutosaveEnabled           bool
+}
+
+// -------------------------
+// Linux-specific types
+// -------------------------
+
+// WebviewGpuPolicy controls GPU acceleration for the Linux webview.
+type WebviewGpuPolicy int
+
+const (
+	WebviewGpuPolicyAlways   WebviewGpuPolicy = iota
+	WebviewGpuPolicyOnDemand WebviewGpuPolicy = iota
+	WebviewGpuPolicyNever    WebviewGpuPolicy = iota
+)
+
+// LinuxMenuStyle selects how the application menu is rendered on Linux.
+type LinuxMenuStyle int
+
+const (
+	LinuxMenuStyleMenuBar     LinuxMenuStyle = iota
+	LinuxMenuStylePrimaryMenu LinuxMenuStyle = iota
+)
+
+// LinuxWindow contains Linux-specific window options.
+type LinuxWindow struct {
+	Icon                    []byte
+	WindowIsTranslucent     bool
+	WebviewGpuPolicy        WebviewGpuPolicy
+	WindowDidMoveDebounceMS uint16
+	Menu                    *Menu
+	MenuStyle               LinuxMenuStyle
+}
+
+// NewRGB constructs an RGBA value with full opacity from RGB components.
+//
+//	colour := NewRGB(255, 128, 0)
+func NewRGB(red, green, blue uint8) RGBA {
+	return RGBA{Red: red, Green: green, Blue: blue, Alpha: 255}
+}
+
+// NewRGBPtr encodes RGB as a packed uint32 pointer (0x00BBGGRR) for ThemeSettings.
+//
+//	theme.BorderColour = NewRGBPtr(255, 0, 0)
+func NewRGBPtr(red, green, blue uint8) *uint32 {
+	result := uint32(red) | uint32(green)<<8 | uint32(blue)<<16
+	return &result
+}

stubs/wails/pkg/application/window.go

@@ -0,0 +1,160 @@
+package application
+
+import (
+	"unsafe"
+
+	"github.com/wailsapp/wails/v3/pkg/events"
+)
+
+// Window is the interface satisfied by all window types in the application.
+// Fluent mutating methods return Window so callers can chain calls:
+//
+//	app.Window.NewWithOptions(opts).SetTitle("Main").Show()
+type Window interface {
+	// Identity
+	ID() uint
+	Name() string
+
+	// Visibility
+	Show() Window
+	Hide() Window
+	IsVisible() bool
+
+	// Lifecycle
+	Close()
+	Focus()
+	Run()
+
+	// Geometry
+	Center()
+	Position() (x int, y int)
+	RelativePosition() (x int, y int)
+	Size() (width int, height int)
+	Width() int
+	Height() int
+	Bounds() Rect
+	SetPosition(x, y int)
+	SetRelativePosition(x, y int) Window
+	SetSize(width, height int) Window
+	SetBounds(bounds Rect)
+	SetMaxSize(maxWidth, maxHeight int) Window
+	SetMinSize(minWidth, minHeight int) Window
+	EnableSizeConstraints()
+	DisableSizeConstraints()
+	Resizable() bool
+	SetResizable(b bool) Window
+
+	// State
+	Maximise() Window
+	UnMaximise()
+	ToggleMaximise()
+	IsMaximised() bool
+	Minimise() Window
+	UnMinimise()
+	IsMinimised() bool
+	Fullscreen() Window
+	UnFullscreen()
+	ToggleFullscreen()
+	IsFullscreen() bool
+	Restore()
+	SnapAssist()
+
+	// Title and content
+	SetTitle(title string) Window
+	SetURL(s string) Window
+	SetHTML(html string) Window
+
+	// Titlebar buttons (macOS / Windows)
+	SetMinimiseButtonState(state ButtonState) Window
+	SetMaximiseButtonState(state ButtonState) Window
+	SetCloseButtonState(state ButtonState) Window
+
+	// Menu bar
+	SetMenu(menu *Menu)
+	ShowMenuBar()
+	HideMenuBar()
+	ToggleMenuBar()
+
+	// Appearance
+	SetBackgroundColour(colour RGBA) Window
+	SetAlwaysOnTop(b bool) Window
+	SetFrameless(frameless bool) Window
+	ToggleFrameless()
+	SetIgnoreMouseEvents(ignore bool) Window
+	IsIgnoreMouseEvents() bool
+	SetContentProtection(protection bool) Window
+
+	// Zoom
+	GetZoom() float64
+	SetZoom(magnification float64) Window
+	Zoom()
+	ZoomIn()
+	ZoomOut()
+	ZoomReset() Window
+
+	// Border sizes (Windows)
+	GetBorderSizes() *LRTB
+
+	// Screen
+	GetScreen() (*Screen, error)
+
+	// JavaScript / events
+	ExecJS(js string)
+	EmitEvent(name string, data ...any) bool
+	DispatchWailsEvent(event *CustomEvent)
+	OnWindowEvent(eventType events.WindowEventType, callback func(event *WindowEvent)) func()
+	RegisterHook(eventType events.WindowEventType, callback func(event *WindowEvent)) func()
+
+	// Drag-and-drop (internal message bus)
+	handleDragAndDropMessage(filenames []string, dropTarget *DropTargetDetails)
+	InitiateFrontendDropProcessing(filenames []string, x int, y int)
+
+	// Message handling (internal)
+	HandleMessage(message string)
+	HandleWindowEvent(id uint)
+	HandleKeyEvent(acceleratorString string)
+
+	// Context menu
+	OpenContextMenu(data *ContextMenuData)
+
+	// Modal
+	AttachModal(modalWindow Window)
+
+	// DevTools
+	OpenDevTools()
+
+	// Print
+	Print() error
+
+	// Flash (Windows taskbar flash)
+	Flash(enabled bool)
+
+	// Focus tracking
+	IsFocused() bool
+
+	// Native handle (platform-specific, use with care)
+	NativeWindow() unsafe.Pointer
+
+	// Enabled state
+	SetEnabled(enabled bool)
+
+	// Reload
+	Reload()
+	ForceReload()
+
+	// Logging (routed to the application logger)
+	Info(message string, args ...any)
+	Error(message string, args ...any)
+
+	// Internal hooks
+	shouldUnconditionallyClose() bool
+
+	// Editing operations (routed to focused element)
+	cut()
+	copy()
+	paste()
+	undo()
+	redo()
+	delete()
+	selectAll()
+}

stubs/wails/pkg/events/events.go

@@ -0,0 +1,44 @@
+package events
+
+// ApplicationEventType identifies a platform-level application event.
+// Matches the type used by the real Wails v3 package.
+//
+//	em.OnApplicationEvent(events.Common.ThemeChanged, handler)
+type ApplicationEventType uint
+
+// WindowEventType identifies a window event emitted by the application layer.
+type WindowEventType int
+
+const (
+	WindowFocus WindowEventType = iota
+	WindowLostFocus
+	WindowDidMove
+	WindowDidResize
+	WindowClosing
+	WindowFilesDropped
+)
+
+// Common matches the event namespace used by the real Wails package.
+var Common = struct {
+	ApplicationOpenedWithFile  ApplicationEventType
+	ApplicationStarted         ApplicationEventType
+	ApplicationLaunchedWithUrl ApplicationEventType
+	ThemeChanged               ApplicationEventType
+	WindowFocus                WindowEventType
+	WindowLostFocus            WindowEventType
+	WindowDidMove              WindowEventType
+	WindowDidResize            WindowEventType
+	WindowClosing              WindowEventType
+	WindowFilesDropped         WindowEventType
+}{
+	ApplicationOpenedWithFile:  1024,
+	ApplicationStarted:         1025,
+	ApplicationLaunchedWithUrl: 1026,
+	ThemeChanged:               1027,
+	WindowFocus:                WindowFocus,
+	WindowLostFocus:            WindowLostFocus,
+	WindowDidMove:              WindowDidMove,
+	WindowDidResize:            WindowDidResize,
+	WindowClosing:              WindowClosing,
+	WindowFilesDropped:         WindowFilesDropped,
+}