geeknative 0.0.0-stage → 0.1.0

package/template/apps/ios/App.xcodeproj/xcshareddata/xcschemes/App.xcscheme

@@ -0,0 +1,89 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Scheme
+   LastUpgradeVersion = "2630"
+   version = "1.7">
+   <BuildAction
+      parallelizeBuildables = "YES"
+      buildImplicitDependencies = "YES">
+      <BuildActionEntries>
+         <BuildActionEntry
+            buildForTesting = "YES"
+            buildForRunning = "YES"
+            buildForProfiling = "YES"
+            buildForArchiving = "YES"
+            buildForAnalyzing = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "A1B2C3D4E5F6000000000020"
+               BuildableName = "App.app"
+               BlueprintName = "App"
+               ReferencedContainer = "container:App.xcodeproj">
+            </BuildableReference>
+         </BuildActionEntry>
+      </BuildActionEntries>
+   </BuildAction>
+   <TestAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      shouldUseLaunchSchemeArgsEnv = "YES">
+      <Testables>
+         <TestableReference
+            skipped = "NO"
+            parallelizable = "YES">
+            <BuildableReference
+               BuildableIdentifier = "primary"
+               BlueprintIdentifier = "A1B2C3D4E5F6000000000030"
+               BuildableName = "AppTests.xctest"
+               BlueprintName = "AppTests"
+               ReferencedContainer = "container:App.xcodeproj">
+            </BuildableReference>
+         </TestableReference>
+      </Testables>
+   </TestAction>
+   <LaunchAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      launchStyle = "0"
+      useCustomWorkingDirectory = "NO"
+      ignoresPersistentStateOnLaunch = "NO"
+      debugDocumentVersioning = "YES"
+      debugServiceExtension = "internal"
+      allowLocationSimulation = "YES">
+      <BuildableProductRunnable
+         runnableDebuggingMode = "0">
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "A1B2C3D4E5F6000000000020"
+            BuildableName = "App.app"
+            BlueprintName = "App"
+            ReferencedContainer = "container:App.xcodeproj">
+         </BuildableReference>
+      </BuildableProductRunnable>
+   </LaunchAction>
+   <ProfileAction
+      buildConfiguration = "Release"
+      shouldUseLaunchSchemeArgsEnv = "YES"
+      savedToolIdentifier = ""
+      useCustomWorkingDirectory = "NO"
+      debugDocumentVersioning = "YES">
+      <BuildableProductRunnable
+         runnableDebuggingMode = "0">
+         <BuildableReference
+            BuildableIdentifier = "primary"
+            BlueprintIdentifier = "A1B2C3D4E5F6000000000020"
+            BuildableName = "App.app"
+            BlueprintName = "App"
+            ReferencedContainer = "container:App.xcodeproj">
+         </BuildableReference>
+      </BuildableProductRunnable>
+   </ProfileAction>
+   <AnalyzeAction
+      buildConfiguration = "Debug">
+   </AnalyzeAction>
+   <ArchiveAction
+      buildConfiguration = "Release"
+      revealArchiveInOrganizer = "YES">
+   </ArchiveAction>
+</Scheme>

package/template/apps/ios/AppTests/SettingsTests.swift

@@ -0,0 +1,54 @@
+import Foundation
+import Testing
+import UIKit
+@testable import App
+
+@Suite("Settings")
+struct SettingsTests {
+    /// An empty UserDefaults suite, so tests don't share state.
+    private func freshDefaults() -> UserDefaults {
+        let name = "SettingsTests.\(UUID().uuidString)"
+        let defaults = UserDefaults(suiteName: name)!
+        defaults.removePersistentDomain(forName: name)
+        return defaults
+    }
+
+    @Test("AC-settings-1: appearance defaults to System")
+    func defaultsToSystem() {
+        #expect(UserDefaultsSettingsRepository(defaults: freshDefaults()).appearance == .system)
+
+        let defaults = freshDefaults()
+        defaults.set("sepia", forKey: Appearance.storageKey)
+        #expect(UserDefaultsSettingsRepository(defaults: defaults).appearance == .system)
+    }
+
+    @Test("AC-settings-2: choosing an appearance applies it to the whole app immediately")
+    func appliesImmediately() {
+        let repository = InMemorySettingsRepository()
+        let viewModel = SettingsViewModel(repository: repository)
+
+        viewModel.selectAppearance(.dark)
+
+        // RootView applies the repository's appearance to every window as it changes.
+        #expect(repository.appearance == .dark)
+        #expect(viewModel.appearance == .dark)
+        #expect(Appearance.dark.interfaceStyle == .dark)
+        #expect(Appearance.system.interfaceStyle == .unspecified)
+    }
+
+    @Test("AC-settings-3: the chosen appearance survives a restart")
+    func survivesRestart() {
+        let defaults = freshDefaults()
+        UserDefaultsSettingsRepository(defaults: defaults).setAppearance(.light)
+
+        #expect(UserDefaultsSettingsRepository(defaults: defaults).appearance == .light)
+        #expect(defaults.string(forKey: "settings.appearance") == "light")
+    }
+
+    @Test("AC-settings-4: shows the app version and build number")
+    func showsVersion() {
+        let text = SettingsViewModel(repository: InMemorySettingsRepository()).versionText
+        #expect(text.contains(AppIdentity.version))
+        #expect(text.contains(String(AppIdentity.build)))
+    }
+}

package/template/apps/ios/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/template/apps/ios/Config/App.xcconfig

@@ -0,0 +1,23 @@
+// The app target. Its name, bundle ID and version come from contracts/app.json (via Identity.xcconfig).
+#include "Identity.xcconfig"
+
+PRODUCT_NAME = App
+PRODUCT_BUNDLE_IDENTIFIER = $(APP_BUNDLE_ID)
+MARKETING_VERSION = $(APP_VERSION)
+CURRENT_PROJECT_VERSION = $(APP_BUILD)
+
+GENERATE_INFOPLIST_FILE = YES
+INFOPLIST_KEY_CFBundleDisplayName = $(APP_DISPLAY_NAME)
+INFOPLIST_KEY_UIApplicationSceneManifest_Generation = YES
+INFOPLIST_KEY_UIApplicationSupportsIndirectInputEvents = YES
+INFOPLIST_KEY_UILaunchScreen_Generation = YES
+INFOPLIST_KEY_UISupportedInterfaceOrientations_iPhone = UIInterfaceOrientationPortrait UIInterfaceOrientationLandscapeLeft UIInterfaceOrientationLandscapeRight
+INFOPLIST_KEY_UISupportedInterfaceOrientations_iPad = UIInterfaceOrientationPortrait UIInterfaceOrientationPortraitUpsideDown UIInterfaceOrientationLandscapeLeft UIInterfaceOrientationLandscapeRight
+
+ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon
+ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor
+ENABLE_PREVIEWS = YES
+LD_RUNPATH_SEARCH_PATHS = $(inherited) @executable_path/Frameworks
+
+// To run on a device, set your Apple Developer team ID.
+DEVELOPMENT_TEAM =

package/template/apps/ios/Config/AppTests.xcconfig

@@ -0,0 +1,10 @@
+// The unit test target, hosted in the app.
+#include "Identity.xcconfig"
+
+PRODUCT_NAME = AppTests
+PRODUCT_BUNDLE_IDENTIFIER = $(APP_BUNDLE_ID).tests
+MARKETING_VERSION = $(APP_VERSION)
+CURRENT_PROJECT_VERSION = $(APP_BUILD)
+GENERATE_INFOPLIST_FILE = YES
+TEST_HOST = $(BUILT_PRODUCTS_DIR)/App.app/$(BUNDLE_EXECUTABLE_FOLDER_PATH)/App
+BUNDLE_LOADER = $(TEST_HOST)

package/template/apps/ios/Config/Base.xcconfig

@@ -0,0 +1,25 @@
+// Settings shared by every target and configuration.
+// Edit build settings here, not in the Xcode project file.
+
+SDKROOT = iphoneos
+IPHONEOS_DEPLOYMENT_TARGET = 17.0
+TARGETED_DEVICE_FAMILY = 1,2
+
+SWIFT_VERSION = 6.0
+SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor
+SWIFT_APPROACHABLE_CONCURRENCY = YES
+SWIFT_UPCOMING_FEATURE_MEMBER_IMPORT_VISIBILITY = YES
+
+// contracts/strings is the source of copy; don't let Xcode extract strings into the generated catalog.
+SWIFT_EMIT_LOC_STRINGS = NO
+LOCALIZATION_PREFERS_STRING_CATALOGS = YES
+
+ASSETCATALOG_COMPILER_GENERATE_SWIFT_ASSET_SYMBOL_EXTENSIONS = YES
+ENABLE_USER_SCRIPT_SANDBOXING = YES
+ENABLE_STRICT_OBJC_MSGSEND = YES
+CLANG_ENABLE_MODULES = YES
+CLANG_ENABLE_OBJC_ARC = YES
+GCC_C_LANGUAGE_STANDARD = gnu17
+ALWAYS_SEARCH_USER_PATHS = NO
+CODE_SIGN_STYLE = Automatic
+COPY_PHASE_STRIP = NO

package/template/apps/ios/Config/Debug.xcconfig

@@ -0,0 +1,9 @@
+#include "Base.xcconfig"
+
+DEBUG_INFORMATION_FORMAT = dwarf
+ENABLE_TESTABILITY = YES
+GCC_OPTIMIZATION_LEVEL = 0
+GCC_PREPROCESSOR_DEFINITIONS = DEBUG=1 $(inherited)
+ONLY_ACTIVE_ARCH = YES
+SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEBUG $(inherited)
+SWIFT_OPTIMIZATION_LEVEL = -Onone

package/template/apps/ios/Config/Identity.xcconfig

@@ -0,0 +1,5 @@
+// GENERATED by geeknative from contracts/app.json. Do not edit: change the contract, then run `make gen`.
+APP_DISPLAY_NAME = GeekNative
+APP_BUNDLE_ID = com.example.geeknative
+APP_VERSION = 1.0.0
+APP_BUILD = 1

package/template/apps/ios/Config/Release.xcconfig

@@ -0,0 +1,6 @@
+#include "Base.xcconfig"
+
+DEBUG_INFORMATION_FORMAT = dwarf-with-dsym
+ENABLE_NS_ASSERTIONS = NO
+SWIFT_COMPILATION_MODE = wholemodule
+VALIDATE_PRODUCT = YES

package/template/apps/web/AGENTS.md

@@ -0,0 +1,63 @@
+<!-- geeknative:begin (managed by geeknative: replaced on upgrade. Add your own rules under "Project rules" at the end.) -->
+# Web app (React + TanStack Start)
+
+Read the root AGENTS.md first. This file covers how the web app is built.
+
+## Stack
+
+- React 19 and TanStack Start (server rendering), with TanStack Router file routes and TanStack Query.
+- Tailwind CSS v4 with the generated design tokens, and Lucide icons.
+- TypeScript (strict), Vite, Vitest.
+- Supports Safari 16.4+, Chrome 111+ and Firefox 128+ (Tailwind v4's minimum).
+
+## Layout
+
+```
+apps/web/src/
+  router.tsx              Creates the router with { queryClient, container } as context
+  routes/                 One thin file per URL: head, loader, then render a feature's screen
+    __root.tsx            HTML shell, site header, AppearanceEffect
+  core/                   AppContainer, AppearanceEffect
+    designsystem/         Shared components (AppCard, ...)
+  features/<name>/        <Name>Screen.tsx, use<Name>ViewModel.ts, <Name>Repository.ts, implementations, tests
+  generated/              From contracts/ by `make gen`. Never edit.
+  styles.css              Tailwind entry; imports generated/tokens.css
+  routeTree.gen.ts        Generated by TanStack Router. Never edit.
+```
+
+## Patterns
+
+Same names and responsibilities as the iOS and Android apps.
+
+| Concept | Web |
+|---|---|
+| Screen | `NotesScreen` in features/notes/, rendered by routes/notes.tsx |
+| State and actions | `useNotesViewModel()`: reads data with TanStack Query, returns state and actions |
+| Data | `NotesRepository` interface, plus implementations such as `LocalStorageNotesRepository` |
+| Dependencies | `AppContainer`, in router context: `useRouteContext({ from: '__root__' }).container` |
+| Navigation | A file in routes/ per screen; link with `<Link to="/notes">` |
+| Copy | `strings.notesEmptyTitle` (generated) |
+| Colors, spacing, radii, type | Tailwind token classes: `bg-primary`, `p-md`, `rounded-lg`, `text-title` |
+| Icons | `<AppIcons.settings className="size-6" />` (generated) |
+| Test IDs | `data-testid="notes.addButton"` |
+
+Follow features/settings as the reference implementation.
+
+## Rules
+
+- Never hardcode user-facing text, colors or spacing. Add them to contracts/ and run `make gen`. Use token classes (`bg-surface`, `p-lg`), not arbitrary values (`bg-[#fff]`, `p-[13px]`).
+- Server functions and API routes are only for web-only concerns (rendering, cookies, SEO). Logic the mobile apps need too goes through repositories, so a future backend can serve all three apps.
+- Code that uses browser APIs (localStorage, window) must also run safely during server rendering.
+- Use semantic HTML, give icon-only links and buttons an `aria-label` from strings, and keep focus visible.
+- For complex primitives (dialogs, menus, popovers), use shadcn/ui: the tokens already map onto its CSS variables.
+- Name tests after acceptance criteria: `test('AC-notes-2: ...')`.
+
+## Commands
+
+- `make check-web`: type-check, unit tests and a production build. Full log: .geeknative/logs/web.log.
+- `make run-web`: dev server at http://localhost:3000.
+<!-- geeknative:end -->
+
+## Project rules
+
+<!-- Your web-specific rules. They override the defaults above, and geeknative upgrades never touch them. -->

package/template/apps/web/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/template/apps/web/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "web",
+  "private": true,
+  "type": "module",
+  "imports": {
+    "#/*": "./src/*"
+  },
+  "scripts": {
+    "dev": "vite dev --port 3000",
+    "build": "vite build",
+    "preview": "vite preview",
+    "routes": "tsr generate",
+    "typecheck": "tsr generate && tsc --noEmit",
+    "test": "vitest run",
+    "check": "npm run typecheck && npm run test && npm run build"
+  },
+  "dependencies": {
+    "@tailwindcss/vite": "4.3.3",
+    "@tanstack/react-query": "5.104.1",
+    "@tanstack/react-router": "1.170.42",
+    "@tanstack/react-router-ssr-query": "1.167.3",
+    "@tanstack/react-start": "1.168.61",
+    "lucide-react": "1.55.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "tailwindcss": "4.3.3"
+  },
+  "devDependencies": {
+    "@tanstack/router-cli": "1.167.41",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^6.0.1",
+    "typescript": "^6.0.2",
+    "vite": "^8.0.0",
+    "vitest": "^5.0.3"
+  }
+}

package/template/apps/web/public/favicon.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <rect width="64" height="64" rx="14" fill="#4F46E5"/>
+  <circle cx="19" cy="32" r="5.5" fill="#fff"/>
+  <circle cx="32" cy="32" r="5.5" fill="#fff"/>
+  <circle cx="45" cy="32" r="5.5" fill="#fff"/>
+</svg>

package/template/apps/web/src/core/AppContainer.ts

@@ -0,0 +1,18 @@
+import { LocalStorageSettingsRepository } from '#/features/settings/LocalStorageSettingsRepository'
+import type { SettingsRepository } from '#/features/settings/SettingsRepository'
+
+/**
+ * The app's dependencies, created once per router and shared through router context.
+ * Swap an implementation here (for example, a backend-backed repository) without touching screens.
+ */
+export interface AppContainer {
+  settingsRepository: SettingsRepository
+}
+
+export function createAppContainer(): AppContainer {
+  // During server rendering there's no localStorage, so the repository falls back to defaults.
+  const storage = typeof window === 'undefined' ? undefined : window.localStorage
+  return {
+    settingsRepository: new LocalStorageSettingsRepository(storage),
+  }
+}

package/template/apps/web/src/core/AppearanceEffect.tsx

@@ -0,0 +1,31 @@
+import { useEffect } from 'react'
+import { APPEARANCE_STORAGE_KEY, isDark } from '#/features/settings/Appearance'
+import { useAppearance } from '#/features/settings/useSettingsViewModel'
+
+/**
+ * Runs in <head> before the first paint: applies the stored appearance (unknown or missing
+ * values count as "system"), so the page never flashes the wrong theme.
+ */
+export const appearanceScript = `(() => {
+  try {
+    const stored = localStorage.getItem(${JSON.stringify(APPEARANCE_STORAGE_KEY)})
+    const dark = stored === 'dark' || (stored !== 'light' && matchMedia('(prefers-color-scheme: dark)').matches)
+    document.documentElement.classList.toggle('dark', dark)
+  } catch {}
+})()`
+
+/** Keeps the "dark" class on <html> in step with the chosen appearance and the system setting. */
+export function AppearanceEffect() {
+  const { data: appearance } = useAppearance()
+
+  useEffect(() => {
+    if (!appearance) return
+    const media = window.matchMedia('(prefers-color-scheme: dark)')
+    const apply = () => document.documentElement.classList.toggle('dark', isDark(appearance, media.matches))
+    apply()
+    media.addEventListener('change', apply)
+    return () => media.removeEventListener('change', apply)
+  }, [appearance])
+
+  return null
+}

package/template/apps/web/src/core/designsystem/AppCard.tsx

@@ -0,0 +1,6 @@
+import type { ReactNode } from 'react'
+
+/** A card for grouped content on a screen (DESIGN.md: Card). */
+export function AppCard({ children, className = '' }: { children: ReactNode; className?: string }) {
+  return <section className={`rounded-lg bg-surface p-lg text-on-surface ${className}`}>{children}</section>
+}

package/template/apps/web/src/features/home/HomeScreen.tsx

@@ -0,0 +1,15 @@
+import { AppCard } from '#/core/designsystem/AppCard'
+import { AppIdentity } from '#/generated/app'
+import { strings } from '#/generated/strings'
+
+export function HomeScreen() {
+  return (
+    <div className="flex flex-col gap-xl">
+      <h1 className="text-display">{AppIdentity.name}</h1>
+      <AppCard>
+        <h2 className="text-title">{strings.homeWelcomeTitle}</h2>
+        <p className="mt-sm text-body text-on-surface-variant">{strings.homeWelcomeBody}</p>
+      </AppCard>
+    </div>
+  )
+}

package/template/apps/web/src/features/home/home.test.tsx

@@ -0,0 +1,22 @@
+import { renderToString } from 'react-dom/server'
+import { describe, expect, test } from 'vitest'
+import { AppIdentity } from '#/generated/app'
+import { strings } from '#/generated/strings'
+import { HomeScreen } from './HomeScreen'
+
+/** How React escapes text in server-rendered HTML. */
+const escapeHtml = (text: string) =>
+  text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#x27;')
+
+describe('Home', () => {
+  const html = renderToString(<HomeScreen />)
+
+  test('AC-home-1: shows the app name as its title', () => {
+    expect(html).toContain(`>${escapeHtml(AppIdentity.name)}</h1>`)
+  })
+
+  test("AC-home-2: shows the welcome card's title and text", () => {
+    expect(html).toContain(escapeHtml(strings.homeWelcomeTitle))
+    expect(html).toContain(escapeHtml(strings.homeWelcomeBody))
+  })
+})

package/template/apps/web/src/features/settings/Appearance.ts

@@ -0,0 +1,29 @@
+import { strings } from '#/generated/strings'
+
+/** The appearance setting. Stored as these exact values on every platform. */
+export const appearances = ['system', 'light', 'dark'] as const
+export type Appearance = (typeof appearances)[number]
+
+/** Storage key, shared with the iOS and Android apps. */
+export const APPEARANCE_STORAGE_KEY = 'settings.appearance'
+
+/** Missing or unknown stored values count as "system". */
+export function parseAppearance(value: string | null | undefined): Appearance {
+  return appearances.find((appearance) => appearance === value) ?? 'system'
+}
+
+/** Whether to render dark, given the chosen appearance and the system setting. */
+export function isDark(appearance: Appearance, systemIsDark: boolean) {
+  return appearance === 'dark' || (appearance === 'system' && systemIsDark)
+}
+
+export function appearanceLabel(appearance: Appearance) {
+  switch (appearance) {
+    case 'system':
+      return strings.settingsAppearanceSystem
+    case 'light':
+      return strings.settingsAppearanceLight
+    case 'dark':
+      return strings.settingsAppearanceDark
+  }
+}

package/template/apps/web/src/features/settings/LocalStorageSettingsRepository.ts

@@ -0,0 +1,21 @@
+import { APPEARANCE_STORAGE_KEY, parseAppearance, type Appearance } from './Appearance'
+import type { SettingsRepository } from './SettingsRepository'
+
+type KeyValueStorage = Pick<Storage, 'getItem' | 'setItem'>
+
+/** Keeps settings in the browser's localStorage. Without storage (during server rendering) it returns defaults. */
+export class LocalStorageSettingsRepository implements SettingsRepository {
+  private readonly storage: KeyValueStorage | undefined
+
+  constructor(storage: KeyValueStorage | undefined) {
+    this.storage = storage
+  }
+
+  async getAppearance(): Promise<Appearance> {
+    return parseAppearance(this.storage?.getItem(APPEARANCE_STORAGE_KEY))
+  }
+
+  async setAppearance(appearance: Appearance): Promise<void> {
+    this.storage?.setItem(APPEARANCE_STORAGE_KEY, appearance)
+  }
+}

package/template/apps/web/src/features/settings/SettingsRepository.ts

@@ -0,0 +1,7 @@
+import type { Appearance } from './Appearance'
+
+/** Stores the user's preferences. Screens use whichever implementation AppContainer provides. */
+export interface SettingsRepository {
+  getAppearance(): Promise<Appearance>
+  setAppearance(appearance: Appearance): Promise<void>
+}

package/template/apps/web/src/features/settings/SettingsScreen.tsx

@@ -0,0 +1,44 @@
+import { AppCard } from '#/core/designsystem/AppCard'
+import { strings } from '#/generated/strings'
+import { useSettingsViewModel } from './useSettingsViewModel'
+
+export function SettingsScreen() {
+  const viewModel = useSettingsViewModel()
+
+  return (
+    <div className="flex flex-col gap-xl">
+      <h1 className="text-display">{strings.settingsTitle}</h1>
+
+      <AppCard>
+        <fieldset data-testid="settings.appearance">
+          <legend className="text-label text-on-surface-variant">{strings.settingsAppearanceTitle}</legend>
+          <div className="mt-md flex flex-col gap-xs">
+            {viewModel.appearanceOptions.map((option) => (
+              <label
+                key={option.id}
+                className="flex cursor-pointer items-center gap-md rounded-md p-sm hover:bg-surface-variant"
+              >
+                <input
+                  type="radio"
+                  name="appearance"
+                  value={option.id}
+                  checked={viewModel.appearance === option.id}
+                  onChange={() => void viewModel.selectAppearance(option.id)}
+                  className="size-4 accent-primary"
+                />
+                <span className="text-body">{option.label}</span>
+              </label>
+            ))}
+          </div>
+        </fieldset>
+      </AppCard>
+
+      <AppCard>
+        <h2 className="text-label text-on-surface-variant">{strings.settingsAboutTitle}</h2>
+        <p data-testid="settings.version" className="mt-sm text-body">
+          {viewModel.versionText}
+        </p>
+      </AppCard>
+    </div>
+  )
+}

package/template/apps/web/src/features/settings/settings.test.ts

@@ -0,0 +1,45 @@
+import { QueryClient } from '@tanstack/react-query'
+import { describe, expect, test } from 'vitest'
+import { AppIdentity } from '#/generated/app'
+import { isDark, parseAppearance } from './Appearance'
+import { LocalStorageSettingsRepository } from './LocalStorageSettingsRepository'
+import { appearanceQuery, selectAppearance, versionText } from './useSettingsViewModel'
+
+function memoryStorage() {
+  const values = new Map<string, string>()
+  return {
+    getItem: (key: string) => values.get(key) ?? null,
+    setItem: (key: string, value: string) => void values.set(key, value),
+  }
+}
+
+describe('Settings', () => {
+  test('AC-settings-1: appearance defaults to System', async () => {
+    const repository = new LocalStorageSettingsRepository(memoryStorage())
+    expect(await repository.getAppearance()).toBe('system')
+    expect(parseAppearance('sepia')).toBe('system')
+  })
+
+  test('AC-settings-2: choosing an appearance applies it to the whole app immediately', async () => {
+    const queryClient = new QueryClient()
+    const repository = new LocalStorageSettingsRepository(memoryStorage())
+    const saving = selectAppearance(queryClient, repository, 'dark')
+    // The shared query changes before saving finishes, so every screen updates at once.
+    expect(queryClient.getQueryData(appearanceQuery(repository).queryKey)).toBe('dark')
+    await saving
+    expect(isDark('dark', false)).toBe(true)
+    expect(isDark('system', true)).toBe(true)
+    expect(isDark('light', true)).toBe(false)
+  })
+
+  test('AC-settings-3: the chosen appearance survives a restart', async () => {
+    const storage = memoryStorage()
+    await new LocalStorageSettingsRepository(storage).setAppearance('light')
+    expect(await new LocalStorageSettingsRepository(storage).getAppearance()).toBe('light')
+  })
+
+  test('AC-settings-4: shows the app version and build number', () => {
+    expect(versionText()).toContain(AppIdentity.version)
+    expect(versionText()).toContain(String(AppIdentity.build))
+  })
+})

package/template/apps/web/src/features/settings/useSettingsViewModel.ts

@@ -0,0 +1,42 @@
+import { queryOptions, useQuery, useQueryClient, type QueryClient } from '@tanstack/react-query'
+import { useRouteContext } from '@tanstack/react-router'
+import { AppIdentity } from '#/generated/app'
+import { strings } from '#/generated/strings'
+import { appearanceLabel, appearances, type Appearance } from './Appearance'
+import type { SettingsRepository } from './SettingsRepository'
+
+export const appearanceQuery = (repository: SettingsRepository) =>
+  queryOptions({
+    queryKey: ['settings', 'appearance'] as const,
+    queryFn: () => repository.getAppearance(),
+    staleTime: Infinity,
+  })
+
+/** Applies the appearance everywhere at once (through the shared query), then saves it. */
+export async function selectAppearance(queryClient: QueryClient, repository: SettingsRepository, appearance: Appearance) {
+  queryClient.setQueryData(appearanceQuery(repository).queryKey, appearance)
+  await repository.setAppearance(appearance)
+}
+
+export const versionText = () =>
+  strings.settingsAboutVersion({ version: AppIdentity.version, build: AppIdentity.build })
+
+/** The current appearance. Used by the Settings screen and by AppearanceEffect. */
+export function useAppearance() {
+  const { container } = useRouteContext({ from: '__root__' })
+  return useQuery(appearanceQuery(container.settingsRepository))
+}
+
+/** State and actions for the Settings screen. */
+export function useSettingsViewModel() {
+  const { container } = useRouteContext({ from: '__root__' })
+  const queryClient = useQueryClient()
+  const { data: appearance = 'system' } = useAppearance()
+
+  return {
+    appearance,
+    appearanceOptions: appearances.map((id) => ({ id, label: appearanceLabel(id) })),
+    selectAppearance: (next: Appearance) => selectAppearance(queryClient, container.settingsRepository, next),
+    versionText: versionText(),
+  }
+}

package/template/apps/web/src/generated/app.ts

@@ -0,0 +1,9 @@
+// GENERATED by geeknative from contracts/app.json. Do not edit: change the contract, then run `make gen`.
+
+/** The app's name, identifier and version, shared with the iOS and Android apps. */
+export const AppIdentity = {
+  name: "GeekNative",
+  id: "com.example.geeknative",
+  version: "1.0.0",
+  build: 1,
+} as const