2026-05-13 18:55:14 +00:00
20 changed files with 2090 additions and 12 deletions
@@ -0,0 +1,30 @@
+# pnpm / node
+node_modules/
+.pnpm-store/
+
+# Vite / SvelteKit
+.svelte-kit/
+build/
+dist/
+
+# Generated WASM bundles
+*.wasm
+
+# Wails desktop wrapper (Phase 31+)
+desktop/build/
+desktop/frontend/dist/
+
+# Capacitor mobile wrappers (Phase 32+)
+mobile/ios/
+mobile/android/
+mobile/dist/
+mobile/node_modules/
+
+# Playwright artifacts (Phase 2+)
+test-results/
+playwright-report/
+playwright/.cache/
+
+# Editor / OS noise
+.DS_Store
+*.log
@@ -0,0 +1,19 @@
+.PHONY: help web wasm gomobile desktop-mac desktop-win desktop-linux ios android all
+
+.DEFAULT_GOAL := help
+
+help:
+	@echo "ui targets (placeholders, implemented in later phases of ui/PLAN.md):"
+	@echo "  web            Vite production build (Phase 5+)"
+	@echo "  wasm           TinyGo build of ui/core to core.wasm (Phase 5)"
+	@echo "  gomobile       gomobile bind for iOS .framework + Android .aar (Phase 32+)"
+	@echo "  desktop-mac    Wails build for darwin/{arm64,amd64} (Phase 31)"
+	@echo "  desktop-win    Wails build for windows/amd64 (Phase 31)"
+	@echo "  desktop-linux  Wails build for linux/amd64 (Phase 31)"
+	@echo "  ios            Capacitor sync + xcodebuild + archive (Phase 32+)"
+	@echo "  android        Capacitor sync + gradle assembleRelease (Phase 32+)"
+	@echo "  all            every target above"
+
+web wasm gomobile desktop-mac desktop-win desktop-linux ios android all:
+	@echo "TODO: implement '$@' (placeholder, see ui/PLAN.md)"
+	@exit 1
@@ -241,12 +241,12 @@ live in per-phase topic docs under `ui/docs/`.

 ---

-## Phase 1. Workspace Skeleton
+## ~~Phase 1. Workspace Skeleton~~

-Status: pending.
+Status: done.

-Goal: bring up the `ui/` workspace with a runnable empty Svelte+Vite
-frontend and architectural anchors.
+Goal: bring up the `ui/` workspace with a runnable empty
+SvelteKit + Vite frontend and architectural anchors.

 Artifacts:

@@ -254,10 +254,19 @@ Artifacts:
 - `ui/Makefile` with placeholder targets for every build type (`web`,
  `wasm`, `gomobile`, `desktop-{mac,win,linux}`, `ios`, `android`,
  `all`)
- `ui/frontend/` Svelte 5 + Vite + TypeScript project scaffolded with
-  `pnpm create vite`
- `ui/frontend/src/routes/` minimal landing page rendering the app
-  version string in the page footer
+- `ui/pnpm-workspace.yaml` declaring the single-package pnpm workspace
+- `ui/frontend/` Svelte 5 + SvelteKit + Vite + TypeScript project
+  (the SvelteKit scaffold provides `+layout.svelte`, `+page.svelte`,
+  `static/`, and the file-system router used by later phases)
+- `ui/frontend/src/routes/+page.svelte` minimal landing page
+  rendering the app version string in the page footer; the version
+  is read at build time by Vite `define` from
+  `ui/frontend/package.json`
+- `ui/frontend/{vitest.config.ts, tests/}` minimum Vitest harness
+  needed to run the smoke test below (`vitest`, `jsdom`,
+  `@testing-library/svelte`); the rest of the test toolchain
+  (Playwright, `@testing-library/jest-dom`, CI workflows) lands in
+  Phase 2
 - `ui/.gitignore` covering `node_modules`, `dist`, `*.wasm`, build
  outputs for Wails and Capacitor, Playwright artefacts
 - `ui/docs/` empty directory ready for per-phase topic docs
@@ -287,10 +296,11 @@ depends on, including Tier 1 (per-PR) and Tier 2 (release) targets.

 Artifacts:

- `ui/frontend/package.json` dev-dependencies: `vitest`,
-  `@testing-library/svelte`, `@testing-library/jest-dom`, `jsdom`,
-  `playwright`, `@playwright/test`
- `ui/frontend/vitest.config.ts` configured for Svelte + JSDOM
+- `ui/frontend/package.json` dev-dependencies (added on top of the
+  Phase 1 minimum of `vitest`, `jsdom`, `@testing-library/svelte`):
+  `@testing-library/jest-dom`, `playwright`, `@playwright/test`
+- `ui/frontend/vitest.config.ts` extended for `@testing-library/jest-dom`
+  matchers (the JSDOM environment itself is wired in Phase 1)
 - `ui/frontend/playwright.config.ts` with three projects:
  `chromium-desktop`, `webkit-desktop`, `chromium-mobile-iphone-13`,
  `chromium-mobile-pixel-5`; tracing and screenshots enabled on failure
@@ -0,0 +1,115 @@
+# ui — Galaxy Cross-Platform Client
+
+`ui/` hosts the new cross-platform Galaxy client. A single
+TypeScript + Svelte source tree builds to five targets: web,
+web-mobile, standalone PC (mac/win/linux), iOS, and Android. A
+shared Go module (`ui/core`) carries envelope cryptography, the
+FlatBuffers codec, keypair management, and a thin bridge over
+`pkg/calc/` for UI-side game math; it is compiled to WASM for the
+web targets, gomobile native libraries for mobile, and embedded
+directly in Wails on desktop. All network I/O lives on the
+TypeScript side via ConnectRPC, so the Go module is a pure compute
+boundary on every platform.
+
+The legacy Fyne client under `client/` is reference-only.
+Nothing in `ui/` imports from it.
+
+The full staged implementation plan lives in `PLAN.md`. The
+strategic rationale (why Svelte, why PixiJS, why Go-as-WASM, why
+Wails+Capacitor) lives outside the repo at
+`~/.claude/plans/buzzing-questing-fountain.md`. This README is a
+quick orientation; deeper per-phase design notes earn their place
+under `ui/docs/` as they are introduced.
+
+## Targets
+
+| Target          | Wrapper          | Toolchain               | Phase    |
+| --------------- | ---------------- | ----------------------- | -------- |
+| web             | browser tab      | Vite + WASM             | 5+       |
+| web-mobile      | mobile browser   | Vite + WASM             | 5+       |
+| desktop (mac)   | Wails v2         | Go + Wails CLI          | 31       |
+| desktop (win)   | Wails v2         | Go + Wails CLI          | 31       |
+| desktop (linux) | Wails v2         | Go + Wails CLI          | 31       |
+| iOS             | Capacitor        | gomobile + Xcode        | 32+      |
+| Android         | Capacitor        | gomobile + Gradle       | 32+      |
+
+## Layered architecture
+
+- **TypeScript + Svelte 5 frontend**, shared across all five targets,
+  scaffolded with SvelteKit + Vite.
+- **PixiJS v8** with dual WebGPU/WebGL backend for the world map
+  renderer.
+- **Go module `ui/core/`** as a compute-only library (canonical bytes,
+  Ed25519 sign/verify, FlatBuffers codec, keypair, thin bridge to
+  `pkg/calc/`) compiled to WASM, gomobile, and Wails-embedded native.
+- **TypeScript-side `Core` interface** with three adapters
+  (`WasmCore`, `WailsCore`, `CapacitorCore`) selected at build time.
+- **`GalaxyClient`** on top of `Core` performs all network I/O via
+  ConnectRPC (`@connectrpc/connect-web`) on every platform.
+- **Per-platform storage:** WebCrypto + IndexedDB on web, OS keychain
+  + SQLite on desktop, iOS Keychain / Android Keystore + SQLite on
+  mobile, all behind a single `KeyStore` and `Cache` TypeScript
+  interface.
+- **Mobile-first navigation:** one active view occupies the main area
+  at a time; the sidebar holds a single tool (calculator, inspector,
+  or order) with persistent state on switch.
+
+## Repository layout
+
+Filled in incrementally as phases land. Today only `frontend/` exists.
+
+```text
+ui/
+├── README.md                 this file
+├── PLAN.md                   staged implementation plan
+├── Makefile                  cross-target build placeholders
+├── pnpm-workspace.yaml       pnpm workspace root
+├── .gitignore
+├── docs/                     per-phase topic docs (added per phase)
+├── frontend/                 TS + Svelte source, shared across targets
+├── core/                     Go module ui/core (Phase 3+)
+├── wasm/                     TinyGo entry point for core.wasm (Phase 5)
+├── mobile-bridge/            gomobile bindings (Phase 32+)
+├── desktop/                  Wails project (Phase 31)
+├── mobile/                   Capacitor project (Phase 32+)
+└── web/                      static deploy assets (Phase 30+)
+```
+
+## Build pipeline
+
+Every cross-target build flows through `make` at this level. All
+named targets are placeholders until the named phase lands; running
+`make` with no arguments prints the current placeholder map.
+
+```text
+make web             Vite production build           Phase 5+
+make wasm            TinyGo → core.wasm              Phase 5
+make gomobile        gomobile bind → ios + android   Phase 32+
+make desktop-mac     Wails build for darwin          Phase 31
+make desktop-win     Wails build for windows         Phase 31
+make desktop-linux   Wails build for linux           Phase 31
+make ios             Capacitor + xcodebuild          Phase 32+
+make android         Capacitor + gradle              Phase 32+
+make all             every target above
+```
+
+## Per-phase docs
+
+Topic docs live under `ui/docs/` and are added per phase as they're
+needed (testing tiers, WASM toolchain, navigation shell, renderer
+internals, sync protocol, auth flow, and so on). The staged plan in
+`PLAN.md` names the topic doc each phase produces.
+
+## Cross-references
+
+- [`PLAN.md`](./PLAN.md) — staged implementation plan with goals,
+  artifacts, dependencies, acceptance criteria, and targeted tests
+  per phase.
+- [`../docs/ARCHITECTURE.md`](../docs/ARCHITECTURE.md) — platform
+  architecture and the transport security model (§15) the client
+  envelope contract derives from.
+- [`../docs/FUNCTIONAL.md`](../docs/FUNCTIONAL.md) — per-domain user
+  stories that drive the UI flows.
+- [`../docs/TESTING.md`](../docs/TESTING.md) — project-wide testing
+  layers; UI-specific test tiers (Vitest, Playwright) live in
+  `ui/docs/testing.md` from Phase 2 onward.
@@ -0,0 +1 @@
+engine-strict=true
@@ -0,0 +1,27 @@
+{
+  "name": "galaxy-ui-frontend",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "preview": "vite preview",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@sveltejs/adapter-static": "^3.0.0",
+    "@sveltejs/kit": "^2.59.0",
+    "@sveltejs/vite-plugin-svelte": "^7.0.0",
+    "@testing-library/svelte": "^5.2.0",
+    "@types/node": "^22.0.0",
+    "jsdom": "^25.0.0",
+    "svelte": "^5.0.0",
+    "svelte-check": "^4.0.0",
+    "tslib": "^2.6.0",
+    "typescript": "^5.5.0",
+    "vite": "^8.0.0",
+    "vitest": "^4.0.0"
+  }
+}
@@ -0,0 +1,10 @@
+declare global {
+	// Build-time constant injected by Vite from package.json version.
+	const __APP_VERSION__: string;
+
+	namespace App {
+		// future-phase types added later
+	}
+}
+
+export {};
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<link rel="icon" href="%sveltekit.assets%/favicon.svg" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<title>Galaxy</title>
+		%sveltekit.head%
+	</head>
+	<body data-sveltekit-preload-data="hover">
+		<div style="display: contents">%sveltekit.body%</div>
+	</body>
+</html>
@@ -0,0 +1,3 @@
+// APP_VERSION is the package.json "version" field, inlined at build time
+// by the Vite `define` plugin (see vite.config.ts).
+export const APP_VERSION: string = __APP_VERSION__;
@@ -0,0 +1,5 @@
+<script lang="ts">
+	let { children } = $props();
+</script>
+
+{@render children()}
@@ -0,0 +1,22 @@
+<script lang="ts">
+	import { APP_VERSION } from "$lib/version";
+</script>
+
+<main>
+	<h1>Galaxy</h1>
+	<p>Cross-platform UI client — workspace skeleton.</p>
+</main>
+
+<footer data-testid="app-version">version {APP_VERSION}</footer>
+
+<style>
+	main {
+		padding: 2rem;
+		font-family: system-ui, sans-serif;
+	}
+	footer {
+		padding: 1rem 2rem;
+		opacity: 0.6;
+		font-size: 0.875rem;
+	}
+</style>
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><circle cx="16" cy="16" r="14" fill="#1f2937"/><circle cx="16" cy="16" r="3" fill="#fbbf24"/></svg>
@@ -0,0 +1,15 @@
+import adapter from "@sveltejs/adapter-static";
+import { vitePreprocess } from "@sveltejs/vite-plugin-svelte";
+
+/** @type {import('@sveltejs/kit').Config} */
+export default {
+	preprocess: vitePreprocess(),
+	kit: {
+		adapter: adapter({
+			pages: "build",
+			assets: "build",
+			fallback: "index.html",
+			strict: true,
+		}),
+	},
+};
@@ -0,0 +1,12 @@
+import { render } from "@testing-library/svelte";
+import { describe, expect, it } from "vitest";
+import Page from "../src/routes/+page.svelte";
+
+describe("landing page", () => {
+	it("renders a non-empty version string in the footer", () => {
+		const { getByTestId } = render(Page);
+		const footer = getByTestId("app-version");
+		expect(footer.textContent?.trim()).not.toBe("");
+		expect(footer.textContent).toMatch(/version\s+\S+/);
+	});
+});
@@ -0,0 +1,14 @@
+{
+	"extends": "./.svelte-kit/tsconfig.json",
+	"compilerOptions": {
+		"allowJs": true,
+		"checkJs": true,
+		"esModuleInterop": true,
+		"forceConsistentCasingInFileNames": true,
+		"resolveJsonModule": true,
+		"skipLibCheck": true,
+		"sourceMap": true,
+		"strict": true,
+		"moduleResolution": "bundler"
+	}
+}
@@ -0,0 +1,18 @@
+import { sveltekit } from "@sveltejs/kit/vite";
+import { defineConfig } from "vite";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const pkg = JSON.parse(
+	readFileSync(
+		fileURLToPath(new URL("./package.json", import.meta.url)),
+		"utf8",
+	),
+) as { version: string };
+
+export default defineConfig({
+	plugins: [sveltekit()],
+	define: {
+		__APP_VERSION__: JSON.stringify(pkg.version),
+	},
+});
@@ -0,0 +1,17 @@
+import { defineConfig, mergeConfig } from "vitest/config";
+import viteConfig from "./vite.config";
+
+export default mergeConfig(
+	viteConfig,
+	defineConfig({
+		resolve: {
+			// Force the browser entry of Svelte so `mount` is available in jsdom.
+			conditions: ["browser"],
+		},
+		test: {
+			environment: "jsdom",
+			include: ["tests/**/*.test.ts"],
+			globals: true,
+		},
+	}),
+);
@@ -0,0 +1,4 @@
+packages:
+  - "frontend"
+allowBuilds:
+  esbuild: true
				`@@ -0,0 +1 @@`
				`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><circle cx="16" cy="16" r="14" fill="#1f2937"/><circle cx="16" cy="16" r="3" fill="#fbbf24"/></svg>`