Initial commit

.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

.gitignore

@@ -0,0 +1,7 @@
+bin/
+frontend/dist/
+frontend/node_modules/
+.idea/
+.vscode/
+*.log
+

.task/checksum/build-frontend--DEV--RUNNER-npm-

@@ -0,0 +1 @@
+d098e6fd836c808a8a51f1d4f66e26d9

.task/checksum/windows-common-generate-bindings

@@ -0,0 +1 @@
+595353d17d943f79f25c683007ba302c

.task/checksum/windows-common-generate-icons

@@ -0,0 +1 @@
+a78891e5df81dd5285725ac05c28aadc

.task/checksum/windows-common-install-frontend-deps-npm

@@ -0,0 +1 @@
+2a6c359f91e7e7c95aa4b1f4064d40c

README.md

@@ -0,0 +1,2 @@
+# opic
+

Taskfile.yml

@@ -0,0 +1,61 @@
+version: '3'
+
+vars:
+  APP_NAME: "opic-flow"
+  BIN_DIR: "bin"
+  PACKAGE_MANAGER: '{{.PACKAGE_MANAGER | default "npm"}}'
+  VITE_PORT: '{{.WAILS_VITE_PORT | default 9245}}'
+
+includes:
+  common: ./build/Taskfile.yml
+  windows: ./build/windows/Taskfile.yml
+  darwin: ./build/darwin/Taskfile.yml
+  linux: ./build/linux/Taskfile.yml
+  ios: ./build/ios/Taskfile.yml
+  android: ./build/android/Taskfile.yml
+
+tasks:
+  build:
+    summary: Builds the application
+    cmds:
+      - task: "{{OS}}:build"
+
+  package:
+    summary: Packages a production build of the application
+    cmds:
+      - task: "{{OS}}:package"
+
+  run:
+    summary: Runs the application
+    cmds:
+      - task: "{{OS}}:run"
+
+  dev:
+    summary: Runs the application in development mode
+    cmds:
+      - wails3 dev -config ./build/config.yml -port {{.VITE_PORT}}
+
+  setup:docker:
+    summary: Builds Docker image for cross-compilation (~800MB download)
+    cmds:
+      - task: common:setup:docker
+
+  build:server:
+    summary: Builds the application in server mode (no GUI, HTTP server only)
+    cmds:
+      - task: common:build:server
+
+  run:server:
+    summary: Runs the application in server mode
+    cmds:
+      - task: common:run:server
+
+  build:docker:
+    summary: Builds a Docker image for server mode deployment
+    cmds:
+      - task: common:build:docker
+
+  run:docker:
+    summary: Builds and runs the Docker image
+    cmds:
+      - task: common:run:docker

build/Taskfile.yml

@@ -0,0 +1,366 @@
+version: '3'
+
+tasks:
+  go:mod:tidy:
+    summary: Runs `go mod tidy`
+    internal: true
+    # Universal/multi-arch builds invoke this concurrently from parallel deps;
+    # two `go mod tidy` processes racing on go.mod can corrupt it (#4637).
+    run: once
+    cmds:
+      - go mod tidy
+
+  install:frontend:deps:
+    summary: Install frontend dependencies
+    run: once
+    cmds:
+      - task: install:frontend:deps:{{.PACKAGE_MANAGER}}
+
+  install:frontend:deps:npm:
+    dir: frontend
+    sources:
+      - package.json
+      - package-lock.json
+    generates:
+      - node_modules
+    preconditions:
+      - sh: npm version
+        msg: "Looks like npm isn't installed. Npm is part of the Node installer: https://nodejs.org/en/download/"
+    cmds:
+      - npm install
+
+  install:frontend:deps:bun:
+    dir: frontend
+    sources:
+      - package.json
+      - bun.lock
+      - bun.lockb
+    generates:
+      - node_modules
+    preconditions:
+      - sh: bun --version
+        msg: "bun not found"
+    cmds:
+      - bun install
+
+  install:frontend:deps:pnpm:
+    dir: frontend
+    sources:
+      - package.json
+      - pnpm-lock.yaml
+    generates:
+      - node_modules
+    preconditions:
+      - sh: pnpm --version
+        msg: "pnpm not found"
+    cmds:
+      - pnpm install
+
+  install:frontend:deps:yarn:
+    dir: frontend
+    sources:
+      - package.json
+      - yarn.lock
+    status:
+      - test -d node_modules || test -f .pnp.cjs
+    preconditions:
+      - sh: yarn --version
+        msg: "yarn not found"
+    cmds:
+      - yarn install
+
+  build:frontend:
+    label: build:frontend (DEV={{.DEV}} RUNNER={{.PACKAGE_MANAGER}})
+    summary: Build the frontend project
+    # darwin:build:universal runs its per-arch builds as parallel deps, each of
+    # which depends on this task. Without run:once the two executions race:
+    # one regenerates frontend/bindings (-clean deletes it first) while the
+    # other's bundler is reading it, failing intermittently with
+    # 'Could not resolve "./bindings/<pkg>"' (#4637).
+    run: once
+    dir: frontend
+    sources:
+      - "**/*"
+      - exclude: node_modules/**/*
+    generates:
+      - dist/**/*
+    deps:
+      - task: install:frontend:deps
+      - task: generate:bindings
+        vars:
+          BUILD_FLAGS:
+            ref: .BUILD_FLAGS
+          OBFUSCATED:
+            ref: .OBFUSCATED
+    cmds:
+      - task: frontend:run
+        vars:
+          SCRIPT: '{{if eq .DEV "true"}}build:dev{{else}}build{{end}}'
+    env:
+      PRODUCTION: '{{if eq .DEV "true"}}false{{else}}true{{end}}'
+
+  frontend:run:
+    summary: Run a frontend script with selected runner
+    cmds:
+      - task: frontend:run:{{.PACKAGE_MANAGER}}
+        vars:
+          SCRIPT: "{{.SCRIPT}}"
+    vars:
+      SCRIPT: "{{.SCRIPT}}"
+
+  frontend:run:npm:
+    dir: frontend
+    cmds:
+      - npm run {{.SCRIPT}} -q
+    vars:
+      SCRIPT: "{{.SCRIPT}}"
+
+  frontend:run:yarn:
+    dir: frontend
+    cmds:
+      - yarn {{.SCRIPT}}
+    vars:
+      SCRIPT: "{{.SCRIPT}}"
+
+  frontend:run:pnpm:
+    dir: frontend
+    cmds:
+      - pnpm run {{.SCRIPT}}
+    vars:
+      SCRIPT: "{{.SCRIPT}}"
+
+  frontend:run:bun:
+    dir: frontend
+    cmds:
+      - bun run {{.SCRIPT}}
+    vars:
+      SCRIPT: "{{.SCRIPT}}"
+
+  frontend:vendor:puppertino:
+    summary: Fetches Puppertino CSS into frontend/public for consistent mobile styling
+    sources:
+      - frontend/public/puppertino/puppertino.css
+    generates:
+      - frontend/public/puppertino/puppertino.css
+    cmds:
+      - |
+        set -euo pipefail
+        mkdir -p frontend/public/puppertino
+        # If bundled Puppertino exists, prefer it. Otherwise, try to fetch, but don't fail build on error.
+        if [ ! -f frontend/public/puppertino/puppertino.css ]; then
+          echo "No bundled Puppertino found. Attempting to fetch from GitHub..."
+          if curl -fsSL https://raw.githubusercontent.com/codedgar/Puppertino/main/dist/css/full.css -o frontend/public/puppertino/puppertino.css; then
+            curl -fsSL https://raw.githubusercontent.com/codedgar/Puppertino/main/LICENSE -o frontend/public/puppertino/LICENSE || true
+            echo "Puppertino CSS downloaded to frontend/public/puppertino/puppertino.css"
+          else
+            echo "Warning: Could not fetch Puppertino CSS. Proceeding without download since template may bundle it."
+          fi
+        else
+          echo "Using bundled Puppertino at frontend/public/puppertino/puppertino.css"
+        fi
+        # Ensure index.html includes Puppertino CSS and button classes
+        INDEX_HTML=frontend/index.html
+        if [ -f "$INDEX_HTML" ]; then
+          if ! grep -q 'href="/puppertino/puppertino.css"' "$INDEX_HTML"; then
+            # Insert Puppertino link tag after style.css link
+            awk '
+              /href="\/style.css"\/?/ && !x { print; print "    <link rel=\"stylesheet\" href=\"/puppertino/puppertino.css\"/>"; x=1; next }1
+            ' "$INDEX_HTML" > "$INDEX_HTML.tmp" && mv "$INDEX_HTML.tmp" "$INDEX_HTML"
+          fi
+          # Replace default .btn with Puppertino primary button classes if present
+          sed -E -i'' 's/class=\"btn\"/class=\"p-btn p-prim-col\"/g' "$INDEX_HTML" || true
+        fi
+
+
+
+  generate:bindings:
+    summary: Generates bindings for the frontend
+    run: once
+    deps:
+      - task: go:mod:tidy
+    sources:
+      - "**/*.[jt]s"
+      - exclude: frontend/**/*
+      - frontend/bindings/**/*  # Rerun when switching between dev/production mode causes changes in output
+      - "**/*.go"
+      - go.mod
+      - go.sum
+    generates:
+      - frontend/bindings/**/*
+    cmds:
+      - wails3 generate bindings -f '{{.BUILD_FLAGS}}' -clean=true{{if eq .OBFUSCATED "true"}} -obfuscated{{end}} -ts -i
+
+  generate:icons:
+    summary: Generates Windows `.ico` and Mac `.icns` from an image; on macOS, `-iconcomposerinput appicon.icon -macassetdir darwin` also produces `Assets.car` from a `.icon` file (skipped on other platforms).
+    run: once
+    dir: build
+    sources:
+      - "appicon.png"
+      - "appicon.icon"
+    generates:
+      - "darwin/icons.icns"
+      - "windows/icon.ico"
+    cmds:
+      - wails3 generate icons -input appicon.png -macfilename darwin/icons.icns -windowsfilename windows/icon.ico -iconcomposerinput appicon.icon -macassetdir darwin
+
+  dev:frontend:
+    summary: Runs the frontend in development mode
+    deps:
+      - task: install:frontend:deps
+    cmds:
+      - task: frontend:dev:{{.PACKAGE_MANAGER}}
+
+  frontend:dev:npm:
+    dir: frontend
+    cmds:
+      - npm run dev -- --port {{.VITE_PORT}} --strictPort
+
+  frontend:dev:yarn:
+    dir: frontend
+    cmds:
+      - yarn dev --port {{.VITE_PORT}} --strictPort
+
+  frontend:dev:pnpm:
+    dir: frontend
+    cmds:
+      - pnpm dev --port {{.VITE_PORT}} --strictPort
+
+  frontend:dev:bun:
+    dir: frontend
+    cmds:
+      - bun run dev --port {{.VITE_PORT}} --strictPort
+
+  update:build-assets:
+    summary: Updates the build assets
+    dir: build
+    cmds:
+      - wails3 update build-assets -name "{{.APP_NAME}}" -binaryname "{{.APP_NAME}}" -config config.yml -dir .
+
+  build:server:
+    summary: Builds the application in server mode (no GUI, HTTP server only)
+    desc: |
+      Builds the application with the server build tag enabled.
+      Server mode runs as a pure HTTP server without native GUI dependencies.
+      Usage: task build:server
+    deps:
+      - task: build:frontend
+        vars:
+          BUILD_FLAGS:
+            ref: .BUILD_FLAGS
+    cmds:
+      - go build -tags server {{.BUILD_FLAGS}} -o {{.BIN_DIR}}/{{.APP_NAME}}-server{{exeExt}}
+    vars:
+      BUILD_FLAGS: "{{.BUILD_FLAGS}}"
+
+  run:server:
+    summary: Builds and runs the application in server mode
+    deps:
+      - task: build:server
+    cmds:
+      - ./{{.BIN_DIR}}/{{.APP_NAME}}-server{{exeExt}}
+
+  build:docker:
+    summary: Builds a Docker image for server mode deployment
+    desc: |
+      Creates a minimal Docker image containing the server mode binary.
+      The image is based on distroless for security and small size.
+      Usage: task build:docker [TAG=myapp:latest]
+    cmds:
+      - docker build -t {{.TAG | default (printf "%s:latest" .APP_NAME)}} -f build/docker/Dockerfile.server .
+    vars:
+      TAG: "{{.TAG}}"
+    preconditions:
+      - sh: docker info > /dev/null 2>&1
+        msg: "Docker is required. Please install Docker first."
+      - sh: test -f build/docker/Dockerfile.server
+        msg: "Dockerfile.server not found. Run 'wails3 update build-assets' to generate it."
+
+  run:docker:
+    summary: Builds and runs the Docker image
+    desc: |
+      Builds the Docker image and runs it, exposing port 8080.
+      Usage: task run:docker [TAG=myapp:latest] [PORT=8080]
+      Note: The internal container port is always 8080. The PORT variable
+      only changes the host port mapping. Ensure your app uses port 8080
+      or modify the Dockerfile to match your ServerOptions.Port setting.
+    deps:
+      - task: build:docker
+        vars:
+          TAG:
+            ref: .TAG
+    cmds:
+      - docker run --rm -p {{.PORT | default "8080"}}:8080 {{.TAG | default (printf "%s:latest" .APP_NAME)}}
+    vars:
+      TAG: "{{.TAG}}"
+      PORT: "{{.PORT}}"
+
+  setup:docker:
+    summary: Builds Docker image for cross-compilation (~800MB download)
+    desc: |
+      Builds the Docker image needed for cross-compiling to any platform.
+      Run this once to enable cross-platform builds from any OS.
+    cmds:
+      - docker build -t wails-cross -f build/docker/Dockerfile.cross build/docker/
+    preconditions:
+      - sh: docker info > /dev/null 2>&1
+        msg: "Docker is required. Please install Docker first."
+
+  ios:device:list:
+    summary: Lists connected iOS devices (UDIDs)
+    cmds:
+      - xcrun xcdevice list
+
+  ios:run:device:
+    summary: Build, install, and launch on a physical iPhone using Apple tools (xcodebuild/devicectl)
+    vars:
+      PROJECT: '{{.PROJECT}}'   # e.g., build/ios/xcode/<YourProject>.xcodeproj
+      SCHEME: '{{.SCHEME}}'     # e.g., ios.dev
+      CONFIG: '{{.CONFIG | default "Debug"}}'
+      DERIVED: '{{.DERIVED | default "build/ios/DerivedData"}}'
+      UDID: '{{.UDID}}'         # from `task ios:device:list`
+      BUNDLE_ID: '{{.BUNDLE_ID}}' # e.g., com.yourco.wails.ios.dev
+      TEAM_ID: '{{.TEAM_ID}}'   # optional, if your project is not already set up for signing
+    preconditions:
+      - sh: xcrun -f xcodebuild
+        msg: "xcodebuild not found. Please install Xcode."
+      - sh: xcrun -f devicectl
+        msg: "devicectl not found. Please update to Xcode 15+ (which includes devicectl)."
+      - sh: test -n '{{.PROJECT}}'
+        msg: "Set PROJECT to your .xcodeproj path (e.g., PROJECT=build/ios/xcode/App.xcodeproj)."
+      - sh: test -n '{{.SCHEME}}'
+        msg: "Set SCHEME to your app scheme (e.g., SCHEME=ios.dev)."
+      - sh: test -n '{{.UDID}}'
+        msg: "Set UDID to your device UDID (see: task ios:device:list)."
+      - sh: test -n '{{.BUNDLE_ID}}'
+        msg: "Set BUNDLE_ID to your app's bundle identifier (e.g., com.yourco.wails.ios.dev)."
+    cmds:
+      - |
+        set -euo pipefail
+        echo "Building for device: UDID={{.UDID}} SCHEME={{.SCHEME}} PROJECT={{.PROJECT}}"
+        XCB_ARGS=(
+          -project "{{.PROJECT}}"
+          -scheme "{{.SCHEME}}"
+          -configuration "{{.CONFIG}}"
+          -destination "id={{.UDID}}"
+          -derivedDataPath "{{.DERIVED}}"
+          -allowProvisioningUpdates
+          -allowProvisioningDeviceRegistration
+        )
+        # Optionally inject signing identifiers if provided
+        if [ -n '{{.TEAM_ID}}' ]; then XCB_ARGS+=(DEVELOPMENT_TEAM={{.TEAM_ID}}); fi
+        if [ -n '{{.BUNDLE_ID}}' ]; then XCB_ARGS+=(PRODUCT_BUNDLE_IDENTIFIER={{.BUNDLE_ID}}); fi
+        xcodebuild "${XCB_ARGS[@]}" build | xcpretty || true
+        # If xcpretty isn't installed, run without it
+        if [ "${PIPESTATUS[0]}" -ne 0 ]; then
+          xcodebuild "${XCB_ARGS[@]}" build
+        fi
+        # Find built .app
+        APP_PATH=$(find "{{.DERIVED}}/Build/Products" -type d -name "*.app" -maxdepth 3 | head -n 1)
+        if [ -z "$APP_PATH" ]; then
+          echo "Could not locate built .app under {{.DERIVED}}/Build/Products" >&2
+          exit 1
+        fi
+        echo "Installing: $APP_PATH"
+        xcrun devicectl device install app --device "{{.UDID}}" "$APP_PATH"
+        echo "Launching: {{.BUNDLE_ID}}"
+        xcrun devicectl device process launch --device "{{.UDID}}" --stderr console --stdout console "{{.BUNDLE_ID}}"

build/android/Taskfile.yml

@@ -0,0 +1,290 @@
+version: '3'
+
+includes:
+  common: ../Taskfile.yml
+
+vars:
+  APP_ID: '{{.APP_ID | default "com.wails.app"}}'
+  MIN_SDK: '21'
+  TARGET_SDK: '34'
+  # The emulator runs the host architecture; physical devices are arm64
+  HOST_ARCH:
+    sh: '[ "$(uname -m)" = "x86_64" ] && echo "amd64" || echo "arm64"'
+  # System-image ABI for the host, used in the "create an AVD" hint below.
+  ANDROID_ABI:
+    sh: '[ "$(uname -m)" = "arm64" ] && echo "arm64-v8a" || echo "x86_64"'
+  # SDK location: $ANDROID_HOME / $ANDROID_SDK_ROOT, else the per-OS default
+  # (macOS: ~/Library/Android/sdk, Linux/other: ~/Android/Sdk)
+  SDK_ROOT:
+    sh: 'echo "${ANDROID_HOME:-${ANDROID_SDK_ROOT:-$([ -d "$HOME/Library/Android/sdk" ] && echo "$HOME/Library/Android/sdk" || echo "$HOME/Android/Sdk")}}"'
+  ADB:
+    sh: 'command -v adb || echo "${ANDROID_HOME:-${ANDROID_SDK_ROOT:-$([ -d "$HOME/Library/Android/sdk" ] && echo "$HOME/Library/Android/sdk" || echo "$HOME/Android/Sdk")}}/platform-tools/adb"'
+  EMULATOR:
+    sh: 'command -v emulator || echo "${ANDROID_HOME:-${ANDROID_SDK_ROOT:-$([ -d "$HOME/Library/Android/sdk" ] && echo "$HOME/Library/Android/sdk" || echo "$HOME/Android/Sdk")}}/emulator/emulator"'
+
+tasks:
+  install:deps:
+    summary: Check and install Android development dependencies
+    cmds:
+      - go run build/android/scripts/deps/install_deps.go
+    env:
+      TASK_FORCE_YES: '{{if .YES}}true{{else}}false{{end}}'
+    prompt: This will check and install Android development dependencies. Continue?
+
+  build:
+    summary: Creates a debug build of the application for Android
+    deps:
+      - task: common:go:mod:tidy
+      - task: generate:android:overlay
+      - task: common:build:frontend
+        vars:
+          BUILD_FLAGS:
+            ref: .BUILD_FLAGS
+          PRODUCTION:
+            ref: .PRODUCTION
+    cmds:
+      - echo "Building Android app {{.APP_NAME}}..."
+      - task: compile:go:shared
+        vars:
+          ARCH: '{{.ARCH | default .HOST_ARCH}}'
+    vars:
+      BUILD_FLAGS: '{{if eq .PRODUCTION "true"}}-tags production,android -trimpath -buildvcs=false -ldflags="-w -s"{{else}}-tags android,debug -buildvcs=false -gcflags=all="-l"{{end}}'
+    env:
+      PRODUCTION: '{{.PRODUCTION | default "false"}}'
+
+  compile:go:shared:
+    summary: Compile Go code to shared library (.so)
+    cmds:
+      - |
+        # Locate the NDK: $ANDROID_NDK_HOME, or the newest installed NDK
+        NDK_ROOT="$ANDROID_NDK_HOME"
+        if [ -z "$NDK_ROOT" ]; then
+          SDK_ROOT="{{.SDK_ROOT}}"
+          NDK_ROOT=$(ls -d "$SDK_ROOT"/ndk/* 2>/dev/null | sort -V | tail -1)
+        fi
+        if [ -z "$NDK_ROOT" ] || [ ! -d "$NDK_ROOT" ]; then
+          echo "Error: Android NDK not found"
+          echo "Install one with: sdkmanager 'ndk;26.3.11579264' (or set ANDROID_NDK_HOME)"
+          exit 1
+        fi
+
+        # Determine toolchain based on host OS
+        case "$(uname -s)" in
+          Darwin) HOST_TAG="darwin-x86_64" ;;
+          Linux)  HOST_TAG="linux-x86_64" ;;
+          *)      echo "Unsupported host OS"; exit 1 ;;
+        esac
+
+        TOOLCHAIN="$NDK_ROOT/toolchains/llvm/prebuilt/$HOST_TAG"
+
+        # Set compiler based on architecture
+        case "{{.ARCH}}" in
+          arm64)
+            export CC="$TOOLCHAIN/bin/aarch64-linux-android{{.MIN_SDK}}-clang"
+            export CXX="$TOOLCHAIN/bin/aarch64-linux-android{{.MIN_SDK}}-clang++"
+            export GOARCH=arm64
+            JNI_DIR="arm64-v8a"
+            ;;
+          amd64|x86_64)
+            export CC="$TOOLCHAIN/bin/x86_64-linux-android{{.MIN_SDK}}-clang"
+            export CXX="$TOOLCHAIN/bin/x86_64-linux-android{{.MIN_SDK}}-clang++"
+            export GOARCH=amd64
+            JNI_DIR="x86_64"
+            ;;
+          *)
+            echo "Unsupported architecture: {{.ARCH}}"
+            exit 1
+            ;;
+        esac
+
+        export CGO_ENABLED=1
+        export GOOS=android
+
+        mkdir -p {{.BIN_DIR}}
+        mkdir -p build/android/app/src/main/jniLibs/$JNI_DIR
+
+        go build -buildmode=c-shared -overlay build/android/overlay.json {{.BUILD_FLAGS}} \
+          -o build/android/app/src/main/jniLibs/$JNI_DIR/libwails.so
+    vars:
+      BUILD_FLAGS: '{{if eq .PRODUCTION "true"}}-tags production,android -trimpath -buildvcs=false -ldflags="-w -s"{{else}}-tags android,debug -buildvcs=false -gcflags=all="-l"{{end}}'
+
+  compile:go:all-archs:
+    summary: Compile Go code for all Android architectures (fat APK)
+    cmds:
+      - task: compile:go:shared
+        vars:
+          ARCH: arm64
+      - task: compile:go:shared
+        vars:
+          ARCH: amd64
+
+  package:
+    summary: Packages a production build of the application into a signed release APK
+    deps:
+      - task: build
+        vars:
+          PRODUCTION: "true"
+          ARCH: '{{.ARCH | default .HOST_ARCH}}'
+    cmds:
+      - task: assemble:apk:release
+
+  package:fat:
+    summary: Packages a production build for all architectures (fat APK)
+    deps:
+      - task: build
+        vars:
+          PRODUCTION: "true"
+          ARCH: arm64
+    cmds:
+      - task: compile:go:shared
+        vars:
+          ARCH: amd64
+          PRODUCTION: "true"
+      - task: assemble:apk:release
+
+  assemble:apk:
+    summary: Assembles a debug APK using Gradle
+    preconditions:
+      - sh: 'command -v java >/dev/null || [ -n "$JAVA_HOME" ]'
+        msg: "Java not found. Install a JDK (e.g. brew install openjdk@21) and/or set JAVA_HOME"
+    cmds:
+      - |
+        cd build/android
+        # The exec bit is lost when gradlew is extracted from the embedded
+        # build assets, so restore it before invoking the wrapper.
+        chmod +x ./gradlew
+        ./gradlew assembleDebug
+        cp app/build/outputs/apk/debug/app-debug.apk "../../{{.BIN_DIR}}/{{.APP_NAME}}.apk"
+        echo "APK created: {{.BIN_DIR}}/{{.APP_NAME}}.apk"
+
+  assemble:apk:release:
+    summary: Assembles a release APK using Gradle (signed with the debug keystore unless ANDROID_KEYSTORE_FILE is set)
+    preconditions:
+      - sh: 'command -v java >/dev/null || [ -n "$JAVA_HOME" ]'
+        msg: "Java not found. Install a JDK (e.g. brew install openjdk@21) and/or set JAVA_HOME"
+    cmds:
+      - |
+        cd build/android
+        # The exec bit is lost when gradlew is extracted from the embedded
+        # build assets, so restore it before invoking the wrapper.
+        chmod +x ./gradlew
+        ./gradlew assembleRelease
+        cp app/build/outputs/apk/release/app-release.apk "../../{{.BIN_DIR}}/{{.APP_NAME}}.apk"
+        echo "Release APK created: {{.BIN_DIR}}/{{.APP_NAME}}.apk"
+
+  generate:android:overlay:
+    internal: true
+    summary: Generate Go build overlay that registers the Android main
+    sources:
+      - build/config.yml
+    generates:
+      - build/android/overlay.json
+      - build/android/gen/main_android.gen.go
+    cmds:
+      - wails3 android overlay:gen -out build/android/overlay.json -config build/config.yml
+
+  generate:android:bindings:
+    internal: true
+    summary: Generates bindings for Android
+    sources:
+      - "**/*.go"
+      - go.mod
+      - go.sum
+    generates:
+      - frontend/bindings/**/*
+    cmds:
+      # Bindings are generated from the Go AST; CGO is disabled so the NDK
+      # is not required for this step
+      - wails3 generate bindings -f '-tags android' -clean=true
+    env:
+      GOOS: android
+      CGO_ENABLED: 0
+
+  ensure-emulator:
+    internal: true
+    summary: Ensure Android Emulator is running
+    silent: true
+    cmds:
+      - |
+        # Check if an emulator is already running
+        if "{{.ADB}}" devices | grep -q "emulator"; then
+          echo "Emulator already running"
+          exit 0
+        fi
+
+        # Get first available AVD
+        AVD_NAME=$("{{.EMULATOR}}" -list-avds | tail -1)
+        if [ -z "$AVD_NAME" ]; then
+          echo "No Android Virtual Devices found. Create one with:"
+          echo "  avdmanager create avd --name wails --package 'system-images;android-34;google_apis;{{.ANDROID_ABI}}' --device pixel_7"
+          exit 1
+        fi
+
+        echo "Starting emulator: $AVD_NAME"
+        # Start the emulator daemonized so it outlives this task step. go-task's
+        # shell tracks background jobs by PID and reaps them when the command's
+        # interpreter finishes (which nohup/setsid alone don't prevent — the kill
+        # is direct), so a bare `emulator &` is gone before the later
+        # install/launch steps run. Launch it from a short-lived child shell that
+        # backgrounds the emulator and exits immediately: the emulator is then
+        # reparented to init/launchd and go-task's shell has no handle to reap it.
+        nohup sh -c "'{{.EMULATOR}}' -avd '$AVD_NAME' -no-snapshot-load </dev/null >/dev/null 2>&1 &" >/dev/null 2>&1
+
+        # Wait for emulator to boot (max 120 seconds)
+        echo "Waiting for emulator to boot..."
+        "{{.ADB}}" wait-for-device
+
+        for i in $(seq 1 120); do
+          BOOT_COMPLETED=$("{{.ADB}}" shell getprop sys.boot_completed 2>/dev/null | tr -d '\r')
+          if [ "$BOOT_COMPLETED" = "1" ]; then
+            echo "Emulator booted successfully"
+            exit 0
+          fi
+          sleep 1
+        done
+
+        echo "Emulator boot timeout"
+        exit 1
+    preconditions:
+      - sh: '[ -x "{{.ADB}}" ] || command -v adb'
+        msg: "adb not found. Install the Android SDK platform-tools (or set ANDROID_HOME)"
+      - sh: '[ -x "{{.EMULATOR}}" ] || command -v emulator'
+        msg: "emulator not found. Install the Android SDK emulator package (or set ANDROID_HOME)"
+
+  deploy-emulator:
+    summary: Deploy the packaged release APK to the Android Emulator
+    deps: [package]
+    cmds:
+      - task: ensure-emulator
+      - '"{{.ADB}}" uninstall {{.APP_ID}} 2>/dev/null || true'
+      - '"{{.ADB}}" install "{{.BIN_DIR}}/{{.APP_NAME}}.apk"'
+      - '"{{.ADB}}" shell am start -n {{.APP_ID}}/com.wails.app.MainActivity'
+
+  run:
+    summary: Build, install and launch a debug build in the Android Emulator
+    deps:
+      - task: ensure-emulator
+      - task: build
+    cmds:
+      - task: assemble:apk
+      - '"{{.ADB}}" uninstall {{.APP_ID}} 2>/dev/null || true'
+      - '"{{.ADB}}" install "{{.BIN_DIR}}/{{.APP_NAME}}.apk"'
+      - '"{{.ADB}}" shell am start -n {{.APP_ID}}/com.wails.app.MainActivity'
+
+  logs:
+    summary: Stream Android logcat filtered to this app
+    cmds:
+      - '"{{.ADB}}" logcat -v time | grep -E "(Wails|{{.APP_NAME}})" || true'
+
+  logs:all:
+    summary: Stream all Android logcat (verbose)
+    cmds:
+      - '"{{.ADB}}" logcat -v time'
+
+  clean:
+    summary: Clean build artifacts
+    cmds:
+      - rm -rf {{.BIN_DIR}}
+      - rm -rf build/android/app/build
+      - rm -rf build/android/app/src/main/jniLibs/*/libwails.so
+      - rm -rf build/android/.gradle

build/android/app/build.gradle

@@ -0,0 +1,83 @@
+plugins {
+    id 'com.android.application'
+}
+
+android {
+    namespace 'com.wails.app'
+    compileSdk 34
+
+    buildFeatures {
+        buildConfig = true
+    }
+
+    defaultConfig {
+        applicationId "com.wails.app"
+        minSdk 21
+        targetSdk 34
+        versionCode 1
+        versionName "1.0"
+
+        // Configure supported ABIs
+        ndk {
+            abiFilters 'arm64-v8a', 'x86_64'
+        }
+    }
+
+    def keystoreFile = System.getenv("ANDROID_KEYSTORE_FILE")
+    def hasKeystore = keystoreFile != null && !keystoreFile.trim().isEmpty()
+
+    signingConfigs {
+        // A real keystore can be provided via environment variables; without
+        // one, release builds are signed with the debug keystore so they can
+        // be installed for testing (not suitable for Play Store uploads).
+        release {
+            if (hasKeystore) {
+                storeFile file(keystoreFile)
+                storePassword System.getenv("ANDROID_KEYSTORE_PASSWORD")
+                keyAlias System.getenv("ANDROID_KEY_ALIAS")
+                keyPassword System.getenv("ANDROID_KEY_PASSWORD")
+            }
+        }
+    }
+
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+            signingConfig hasKeystore ? signingConfigs.release : signingConfigs.debug
+        }
+        debug {
+            debuggable true
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_11
+        targetCompatibility JavaVersion.VERSION_11
+    }
+
+    // Source sets configuration
+    sourceSets {
+        main {
+            // JNI libraries are in jniLibs folder
+            jniLibs.srcDirs = ['src/main/jniLibs']
+            // Assets for the WebView
+            assets.srcDirs = ['src/main/assets']
+        }
+    }
+
+    // Packaging options
+    packagingOptions {
+        // Don't strip Go symbols in debug builds
+        doNotStrip '*/arm64-v8a/libwails.so'
+        doNotStrip '*/x86_64/libwails.so'
+    }
+}
+
+dependencies {
+    implementation 'androidx.appcompat:appcompat:1.6.1'
+    implementation 'androidx.webkit:webkit:1.9.0'
+    implementation 'com.google.android.material:material:1.11.0'
+    implementation 'androidx.biometric:biometric:1.1.0'
+    implementation 'androidx.security:security-crypto:1.1.0-alpha06'
+}

build/android/app/proguard-rules.pro

@@ -0,0 +1,12 @@
+# Add project specific ProGuard rules here.
+# You can control the set of applied configuration files using the
+# proguardFiles setting in build.gradle.
+
+# Keep native methods
+-keepclasseswithmembernames class * {
+    native <methods>;
+}
+
+# Keep Wails bridge classes
+-keep class com.wails.app.WailsBridge { *; }
+-keep class com.wails.app.WailsJSBridge { *; }

build/android/app/src/main/AndroidManifest.xml

@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools">
+
+    <!-- Internet permission for WebView -->
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.VIBRATE" />
+    <!-- Observe network connectivity / type for android:NetworkChanged events -->
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+    <uses-permission android:name="android.permission.USE_BIOMETRIC" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+    <uses-permission android:name="android.permission.CAMERA" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
+
+    <queries>
+        <intent>
+            <action android:name="android.media.action.IMAGE_CAPTURE" />
+        </intent>
+        <intent>
+            <action android:name="android.media.action.VIDEO_CAPTURE" />
+        </intent>
+    </queries>
+
+    <application
+        android:allowBackup="true"
+        android:icon="@mipmap/ic_launcher"
+        android:label="@string/app_name"
+        android:roundIcon="@mipmap/ic_launcher_round"
+        android:supportsRtl="true"
+        android:theme="@style/Theme.WailsApp"
+        tools:targetApi="31">
+
+        <activity
+            android:name=".MainActivity"
+            android:exported="true"
+            android:configChanges="orientation|screenSize|keyboardHidden|uiMode"
+            android:windowSoftInputMode="adjustResize">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+
+        <provider
+            android:name="androidx.core.content.FileProvider"
+            android:authorities="${applicationId}.fileprovider"
+            android:exported="false"
+            android:grantUriPermissions="true">
+            <meta-data
+                android:name="android.support.FILE_PROVIDER_PATHS"
+                android:resource="@xml/file_paths" />
+        </provider>
+
+        <service
+            android:name=".WailsForegroundService"
+            android:exported="false"
+            android:foregroundServiceType="dataSync" />
+    </application>
+
+</manifest>

build/android/app/src/main/java/com/wails/app/MainActivity.java

@@ -0,0 +1,806 @@
+package com.wails.app;
+
+import android.annotation.SuppressLint;
+import android.content.BroadcastReceiver;
+import android.content.Context;
+import android.content.Intent;
+import android.content.IntentFilter;
+import android.content.res.Configuration;
+import android.database.Cursor;
+import android.net.ConnectivityManager;
+import android.net.Network;
+import android.net.NetworkCapabilities;
+import android.net.Uri;
+import android.os.BatteryManager;
+import android.os.Build;
+import android.os.Bundle;
+import android.os.PowerManager;
+import android.content.pm.PackageManager;
+import android.graphics.Bitmap;
+import android.graphics.BitmapFactory;
+import android.provider.MediaStore;
+import android.provider.OpenableColumns;
+import android.util.Base64;
+import android.util.Log;
+import android.webkit.WebResourceRequest;
+import android.webkit.WebResourceResponse;
+import android.webkit.WebSettings;
+import android.webkit.WebView;
+import android.webkit.WebViewClient;
+
+import androidx.annotation.Nullable;
+import androidx.appcompat.app.AppCompatActivity;
+import androidx.core.content.FileProvider;
+import androidx.webkit.WebViewAssetLoader;
+
+import org.json.JSONObject;
+
+import java.io.File;
+import java.io.FileOutputStream;
+import java.io.ByteArrayOutputStream;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * MainActivity hosts the WebView and manages the Wails application lifecycle.
+ * It uses WebViewAssetLoader to serve assets from the Go library without
+ * requiring a network server.
+ */
+public class MainActivity extends AppCompatActivity {
+    private static final String TAG = "WailsActivity";
+    private static final boolean DEBUG = BuildConfig.DEBUG;
+    private static final String WAILS_SCHEME = "https";
+    private static final String WAILS_HOST = "wails.localhost";
+    private static final int FILE_PICKER_REQUEST = 7001;
+
+    private WebView webView;
+    private WailsBridge bridge;
+    // Battery: system-event receivers are registered only while the activity is
+    // in the foreground (onStart) and torn down in onStop, so background battery/
+    // network/screen broadcasts don't wake the app.
+    private boolean systemReceiversRegistered = false;
+    private WebViewAssetLoader assetLoader;
+
+    // The Go-side dialog ID of the in-flight file picker (-1 when idle)
+    private int pendingFilePickerCallbackID = -1;
+    private static final int PHOTO_CAPTURE_REQUEST = 7002;
+    private static final int VIDEO_CAPTURE_REQUEST = 7003;
+    private static final int CAMERA_PERMISSION_REQUEST = 7010;
+    private File pendingCaptureFile;
+    private boolean pendingCaptureIsVideo;
+
+    // System-event sources (battery/power, screen lock, network). Registered in
+    // onCreate, torn down in onDestroy. Each forwards a "system:*" event to JS
+    // via the bridge.
+    private BroadcastReceiver batteryReceiver;
+    private BroadcastReceiver screenReceiver;
+    private BroadcastReceiver powerSaveReceiver;
+    private ConnectivityManager connectivityManager;
+    private ConnectivityManager.NetworkCallback networkCallback;
+
+    @Override
+    protected void onCreate(Bundle savedInstanceState) {
+        super.onCreate(savedInstanceState);
+        setContentView(R.layout.activity_main);
+
+        // Initialize the native Go library
+        bridge = new WailsBridge(this);
+        bridge.initialize();
+
+        // Set up WebView
+        setupWebView();
+
+        // Load the application
+        loadApplication();
+    }
+
+    @SuppressLint("SetJavaScriptEnabled")
+    private void setupWebView() {
+        webView = findViewById(R.id.webview);
+        bridge.setWebView(webView);
+
+        // Configure WebView settings
+        WebSettings settings = webView.getSettings();
+        settings.setJavaScriptEnabled(true);
+        settings.setDomStorageEnabled(true);
+        settings.setDatabaseEnabled(true);
+        settings.setAllowFileAccess(false);
+        settings.setAllowContentAccess(false);
+        settings.setMediaPlaybackRequiresUserGesture(false);
+        settings.setMixedContentMode(WebSettings.MIXED_CONTENT_NEVER_ALLOW);
+
+        // Enable debugging in debug builds
+        if (DEBUG) {
+            WebView.setWebContentsDebuggingEnabled(true);
+        }
+
+        // Set up asset loader for serving local assets
+        assetLoader = new WebViewAssetLoader.Builder()
+                .setDomain(WAILS_HOST)
+                .addPathHandler("/", new WailsPathHandler(bridge))
+                .build();
+
+        // Set up WebView client to intercept requests
+        webView.setWebViewClient(new WebViewClient() {
+            @Nullable
+            @Override
+            public WebResourceResponse shouldInterceptRequest(WebView view, WebResourceRequest request) {
+                // Handle wails.localhost requests
+                if (request.getUrl().getHost() != null &&
+                        request.getUrl().getHost().equals(WAILS_HOST)) {
+
+                    // For wails API calls (runtime, capabilities, etc.) pass the
+                    // full URL including the query string, because
+                    // WebViewAssetLoader.PathHandler strips query params
+                    String path = request.getUrl().getPath();
+                    if (path != null && path.startsWith("/wails/")) {
+                        String fullPath = path;
+                        String query = request.getUrl().getQuery();
+                        if (query != null && !query.isEmpty()) {
+                            fullPath = path + "?" + query;
+                        }
+                        if (DEBUG) Log.d(TAG, "Wails API call: " + fullPath);
+
+                        byte[] data = bridge.serveAsset(fullPath, request.getMethod(), "{}");
+                        if (data != null && data.length > 0) {
+                            java.io.InputStream inputStream = new java.io.ByteArrayInputStream(data);
+                            java.util.Map<String, String> headers = new java.util.HashMap<>();
+                            headers.put("Access-Control-Allow-Origin", "*");
+                            headers.put("Cache-Control", "no-cache");
+                            headers.put("Content-Type", "application/json");
+
+                            return new WebResourceResponse(
+                                "application/json",
+                                "UTF-8",
+                                200,
+                                "OK",
+                                headers,
+                                inputStream
+                            );
+                        }
+                        // Return error response if data is null
+                        return new WebResourceResponse(
+                            "application/json",
+                            "UTF-8",
+                            500,
+                            "Internal Error",
+                            new java.util.HashMap<>(),
+                            new java.io.ByteArrayInputStream("{}".getBytes())
+                        );
+                    }
+
+                    // Stream captured photos/videos from the cache with HTTP Range
+                    // support so <video> can seek/stream a clip of any length.
+                    if (path != null && path.startsWith("/__capture__/")) {
+                        return serveCaptureFile(path.substring("/__capture__/".length()), request);
+                    }
+
+                    // For regular assets, use the asset loader
+                    return assetLoader.shouldInterceptRequest(request.getUrl());
+                }
+
+                return super.shouldInterceptRequest(view, request);
+            }
+
+            @Override
+            public void onPageFinished(WebView view, String url) {
+                super.onPageFinished(view, url);
+                if (DEBUG) Log.d(TAG, "Page loaded: " + url);
+                bridge.onPageFinished(url);
+                // Now that JS listeners are mounted, push a snapshot of the
+                // current battery / network / theme so the UI starts populated.
+                emitSystemSnapshot();
+            }
+        });
+
+        // Add JavaScript interface for Go communication
+        webView.addJavascriptInterface(new WailsJSBridge(bridge, webView), "wails");
+    }
+
+    private void loadApplication() {
+        String url = WAILS_SCHEME + "://" + WAILS_HOST + "/";
+        if (DEBUG) Log.d(TAG, "Loading URL: " + url);
+        webView.loadUrl(url);
+    }
+
+    /**
+     * Launch the system camera to capture a photo (video=false) or a video
+     * (video=true). The capture is written to a FileProvider URI in the cache and
+     * the result is delivered to JS as a "common:capture" event.
+     */
+    public void launchCameraCapture(boolean video) {
+        if (checkSelfPermission("android.permission.CAMERA") != PackageManager.PERMISSION_GRANTED) {
+            requestPermissions(new String[]{"android.permission.CAMERA"}, CAMERA_PERMISSION_REQUEST);
+            bridge.emitEvent("common:capture",
+                    "{\"error\":\"camera permission requested \u2014 tap again once granted\"}");
+            return;
+        }
+        try {
+            File dir = new File(getCacheDir(), "captures");
+            if (!dir.exists()) dir.mkdirs();
+            pendingCaptureFile = new File(dir, "capture_" + System.currentTimeMillis() + (video ? ".mp4" : ".jpg"));
+            pendingCaptureIsVideo = video;
+            Uri uri = FileProvider.getUriForFile(this, getPackageName() + ".fileprovider", pendingCaptureFile);
+            Intent intent = new Intent(video ? MediaStore.ACTION_VIDEO_CAPTURE : MediaStore.ACTION_IMAGE_CAPTURE);
+            intent.putExtra(MediaStore.EXTRA_OUTPUT, uri);
+            intent.addFlags(Intent.FLAG_GRANT_WRITE_URI_PERMISSION);
+            // Don't pre-check with resolveActivity(): Android 11+ package visibility
+            // hides other apps' intents unless declared in <queries>, so it can
+            // return null even when a camera app exists. Just launch and handle a miss.
+            startActivityForResult(intent, video ? VIDEO_CAPTURE_REQUEST : PHOTO_CAPTURE_REQUEST);
+        } catch (android.content.ActivityNotFoundException e) {
+            bridge.emitEvent("common:capture", "{\"error\":\"no camera app available\"}");
+        } catch (Exception e) {
+            Log.e(TAG, "launchCameraCapture failed", e);
+            bridge.emitEvent("common:capture", "{\"error\":\"capture failed\"}");
+        }
+    }
+
+    private void handleCaptureResult(int resultCode, @Nullable Intent data) {
+        File file = pendingCaptureFile;
+        final boolean video = pendingCaptureIsVideo;
+        pendingCaptureFile = null;
+        if (resultCode != RESULT_OK) {
+            bridge.emitEvent("common:capture", "{\"cancelled\":true}");
+            return;
+        }
+        // Some camera apps (commonly for video) ignore EXTRA_OUTPUT and instead
+        // return a content URI in the result data; copy that into our cache.
+        if ((file == null || !file.exists() || file.length() == 0)
+                && data != null && data.getData() != null) {
+            String copied = copyUriToCache(data.getData());
+            if (copied != null) file = new File(copied);
+        }
+        final File f = file;
+        if (f == null || !f.exists() || f.length() == 0) {
+            bridge.emitEvent("common:capture", "{\"cancelled\":true}");
+            return;
+        }
+        new Thread(() -> {
+            try {
+                JSONObject o = new JSONObject();
+                o.put("type", video ? "video" : "photo");
+                o.put("path", f.getAbsolutePath());
+                o.put("size", f.length());
+                if (!video) {
+                    String thumb = makePhotoThumbnail(f);
+                    if (thumb != null) o.put("thumb", thumb);
+                }
+                // Stream URL works for both: <video>/<img> load it from the cache
+                // via shouldInterceptRequest (Range-enabled), no size limit.
+                o.put("streamUrl", captureStreamUrl(f));
+                bridge.emitEvent("common:capture", o.toString());
+            } catch (Exception e) {
+                Log.e(TAG, "handleCaptureResult failed", e);
+                bridge.emitEvent("common:capture", "{\"error\":\"result processing failed\"}");
+            }
+        }).start();
+    }
+
+    /** Downscale a captured photo into a base64 JPEG data URL for display in the webview. */
+    @Nullable
+    private String makePhotoThumbnail(File file) {
+        try {
+            BitmapFactory.Options bounds = new BitmapFactory.Options();
+            bounds.inJustDecodeBounds = true;
+            BitmapFactory.decodeFile(file.getAbsolutePath(), bounds);
+            int sample = 1;
+            while (Math.max(bounds.outWidth, bounds.outHeight) / sample > 640) sample *= 2;
+            BitmapFactory.Options opts = new BitmapFactory.Options();
+            opts.inSampleSize = sample;
+            Bitmap bmp = BitmapFactory.decodeFile(file.getAbsolutePath(), opts);
+            if (bmp == null) return null;
+            ByteArrayOutputStream baos = new ByteArrayOutputStream();
+            bmp.compress(Bitmap.CompressFormat.JPEG, 70, baos);
+            bmp.recycle();
+            return "data:image/jpeg;base64," + Base64.encodeToString(baos.toByteArray(), Base64.NO_WRAP);
+        } catch (Exception e) {
+            return null;
+        }
+    }
+
+    /**
+     * Build a same-origin URL the webview can stream a capture from. Served by
+     * serveCaptureFile (via shouldInterceptRequest); the path is relative to the
+     * cache dir so both camera files (captures/) and copied content URIs
+     * (wails-picker/) resolve.
+     */
+    private String captureStreamUrl(File file) {
+        String base = getCacheDir().getAbsolutePath() + File.separator;
+        String abs = file.getAbsolutePath();
+        String rel = abs.startsWith(base) ? abs.substring(base.length()) : file.getName();
+        return "/__capture__/" + Uri.encode(rel, "/");
+    }
+
+    /**
+     * Serve a captured file (under the app cache) to the webview with HTTP Range
+     * support, so &lt;video&gt; can stream and seek a clip of any length without
+     * inlining it as a data URL.
+     */
+    private WebResourceResponse serveCaptureFile(String relPath, WebResourceRequest request) {
+        try {
+            File cache = getCacheDir();
+            File file = new File(cache, Uri.decode(relPath));
+            // Path-traversal guard: only ever serve files under the cache dir.
+            if (!file.getCanonicalPath().startsWith(cache.getCanonicalPath() + File.separator)
+                    || !file.exists() || !file.isFile()) {
+                return new WebResourceResponse("text/plain", "UTF-8", 404, "Not Found",
+                        new java.util.HashMap<>(), new java.io.ByteArrayInputStream(new byte[0]));
+            }
+            String name = file.getName().toLowerCase();
+            String mime = name.endsWith(".mp4") ? "video/mp4"
+                    : name.endsWith(".mov") ? "video/quicktime"
+                    : name.endsWith(".jpg") || name.endsWith(".jpeg") ? "image/jpeg"
+                    : name.endsWith(".png") ? "image/png" : "application/octet-stream";
+            long length = file.length();
+            java.util.Map<String, String> reqHeaders = request.getRequestHeaders();
+            String range = reqHeaders != null ? reqHeaders.get("Range") : null;
+            if (range == null && reqHeaders != null) range = reqHeaders.get("range");
+
+            java.util.Map<String, String> headers = new java.util.HashMap<>();
+            headers.put("Accept-Ranges", "bytes");
+            headers.put("Cache-Control", "no-store");
+
+            if (range != null && range.startsWith("bytes=")) {
+                long start = 0, end = length - 1;
+                String spec = range.substring(6).trim();
+                int dash = spec.indexOf('-');
+                if (dash >= 0) {
+                    try {
+                        if (dash > 0) start = Long.parseLong(spec.substring(0, dash).trim());
+                        String e = spec.substring(dash + 1).trim();
+                        if (!e.isEmpty()) end = Long.parseLong(e);
+                    } catch (NumberFormatException ignored) { }
+                }
+                if (start < 0) start = 0;
+                if (end >= length) end = length - 1;
+                if (start > end) { start = 0; end = length - 1; }
+                long count = end - start + 1;
+                java.io.InputStream in = new java.io.FileInputStream(file);
+                long toSkip = start;
+                while (toSkip > 0) {
+                    long s = in.skip(toSkip);
+                    if (s <= 0) break;
+                    toSkip -= s;
+                }
+                headers.put("Content-Range", "bytes " + start + "-" + end + "/" + length);
+                headers.put("Content-Length", String.valueOf(count));
+                return new WebResourceResponse(mime, null, 206, "Partial Content",
+                        headers, new LimitedInputStream(in, count));
+            }
+            headers.put("Content-Length", String.valueOf(length));
+            return new WebResourceResponse(mime, null, 200, "OK", headers,
+                    new java.io.FileInputStream(file));
+        } catch (Exception e) {
+            Log.e(TAG, "serveCaptureFile failed", e);
+            return new WebResourceResponse("text/plain", "UTF-8", 500, "Error",
+                    new java.util.HashMap<>(), new java.io.ByteArrayInputStream(new byte[0]));
+        }
+    }
+
+    /** Wraps a stream to yield at most a fixed number of bytes (for Range responses). */
+    private static final class LimitedInputStream extends java.io.FilterInputStream {
+        private long remaining;
+        LimitedInputStream(java.io.InputStream in, long limit) {
+            super(in);
+            this.remaining = limit;
+        }
+        @Override public int read() throws java.io.IOException {
+            if (remaining <= 0) return -1;
+            int b = super.read();
+            if (b >= 0) remaining--;
+            return b;
+        }
+        @Override public int read(byte[] b, int off, int len) throws java.io.IOException {
+            if (remaining <= 0) return -1;
+            int n = super.read(b, off, (int) Math.min(len, remaining));
+            if (n > 0) remaining -= n;
+            return n;
+        }
+    }
+
+    /**
+     * Launch the system document picker. Results are copied into the app's
+     * cache directory so Go receives real filesystem paths. Called by
+     * WailsBridge on the main thread.
+     */
+    public void launchFilePicker(int callbackID, boolean multiple) {
+        synchronized (this) {
+            if (pendingFilePickerCallbackID != -1) {
+                // Only one picker can be in flight
+                bridge.filePickerDone(callbackID);
+                return;
+            }
+            pendingFilePickerCallbackID = callbackID;
+        }
+
+        Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT);
+        intent.addCategory(Intent.CATEGORY_OPENABLE);
+        intent.setType("*/*");
+        intent.putExtra(Intent.EXTRA_ALLOW_MULTIPLE, multiple);
+        try {
+            startActivityForResult(intent, FILE_PICKER_REQUEST);
+        } catch (Exception e) {
+            Log.e(TAG, "Failed to launch file picker", e);
+            pendingFilePickerCallbackID = -1;
+            bridge.filePickerDone(callbackID);
+        }
+    }
+
+    @Override
+    protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
+        super.onActivityResult(requestCode, resultCode, data);
+        if (requestCode == PHOTO_CAPTURE_REQUEST || requestCode == VIDEO_CAPTURE_REQUEST) {
+            handleCaptureResult(resultCode, data);
+            return;
+        }
+        if (requestCode != FILE_PICKER_REQUEST) {
+            return;
+        }
+        final int callbackID = pendingFilePickerCallbackID;
+        pendingFilePickerCallbackID = -1;
+        if (callbackID == -1) {
+            return;
+        }
+
+        final List<Uri> uris = new ArrayList<>();
+        if (resultCode == RESULT_OK && data != null) {
+            if (data.getClipData() != null) {
+                for (int i = 0; i < data.getClipData().getItemCount(); i++) {
+                    uris.add(data.getClipData().getItemAt(i).getUri());
+                }
+            } else if (data.getData() != null) {
+                uris.add(data.getData());
+            }
+        }
+
+        // Copy the documents off the main thread, then notify Go
+        new Thread(() -> {
+            for (Uri uri : uris) {
+                String path = copyUriToCache(uri);
+                if (path != null) {
+                    bridge.filePickerResult(callbackID, path);
+                }
+            }
+            bridge.filePickerDone(callbackID);
+        }).start();
+    }
+
+    /**
+     * Copy a content URI into the app cache and return its filesystem path.
+     */
+    @Nullable
+    private String copyUriToCache(Uri uri) {
+        String name = "document";
+        try (Cursor cursor = getContentResolver().query(uri, null, null, null, null)) {
+            if (cursor != null && cursor.moveToFirst()) {
+                int idx = cursor.getColumnIndex(OpenableColumns.DISPLAY_NAME);
+                if (idx >= 0 && cursor.getString(idx) != null) {
+                    name = new File(cursor.getString(idx)).getName();
+                }
+            }
+        } catch (Exception ignored) {
+        }
+
+        try {
+            File dir = new File(getCacheDir(), "wails-picker/" + System.nanoTime());
+            if (!dir.mkdirs()) {
+                return null;
+            }
+            File out = new File(dir, name);
+            try (InputStream in = getContentResolver().openInputStream(uri);
+                 OutputStream os = new FileOutputStream(out)) {
+                if (in == null) {
+                    return null;
+                }
+                byte[] buf = new byte[64 * 1024];
+                int n;
+                while ((n = in.read(buf)) > 0) {
+                    os.write(buf, 0, n);
+                }
+            }
+            return out.getAbsolutePath();
+        } catch (Exception e) {
+            Log.e(TAG, "Failed to copy picked document", e);
+            return null;
+        }
+    }
+
+    /**
+     * Execute JavaScript in the WebView from the Go side
+     */
+    public void executeJavaScript(final String js) {
+        runOnUiThread(() -> {
+            if (webView != null) {
+                webView.evaluateJavascript(js, null);
+            }
+        });
+    }
+
+    // ---- System events ---------------------------------------------------
+    // Battery/power, screen lock and network connectivity are surfaced to JS as
+    // "system:*" events. The OS broadcasts used here (ACTION_BATTERY_CHANGED,
+    // SCREEN_OFF, USER_PRESENT, POWER_SAVE_MODE_CHANGED) are protected system
+    // broadcasts, so dynamic registration needs no RECEIVER_* export flag.
+
+    private void registerSystemEventReceivers() {
+        // Battery + charging state (sticky broadcast: the current value is
+        // delivered to the receiver immediately on registration).
+        batteryReceiver = new BroadcastReceiver() {
+            @Override public void onReceive(Context context, Intent intent) {
+                emitBattery(intent);
+            }
+        };
+        registerReceiver(batteryReceiver, new IntentFilter(Intent.ACTION_BATTERY_CHANGED));
+
+        // Low-power (battery saver) mode toggles → re-emit battery with the flag.
+        powerSaveReceiver = new BroadcastReceiver() {
+            @Override public void onReceive(Context context, Intent intent) {
+                emitBattery(registerSticky(Intent.ACTION_BATTERY_CHANGED));
+            }
+        };
+        registerReceiver(powerSaveReceiver,
+                new IntentFilter(PowerManager.ACTION_POWER_SAVE_MODE_CHANGED));
+
+        // Screen lock / unlock. SCREEN_OFF ≈ locked; USER_PRESENT = unlocked.
+        screenReceiver = new BroadcastReceiver() {
+            @Override public void onReceive(Context context, Intent intent) {
+                String action = intent.getAction();
+                if (Intent.ACTION_SCREEN_OFF.equals(action)) {
+                    emitLock(true);
+                } else if (Intent.ACTION_USER_PRESENT.equals(action)) {
+                    emitLock(false);
+                }
+            }
+        };
+        IntentFilter screenFilter = new IntentFilter();
+        screenFilter.addAction(Intent.ACTION_SCREEN_OFF);
+        screenFilter.addAction(Intent.ACTION_USER_PRESENT);
+        registerReceiver(screenReceiver, screenFilter);
+
+        // Network connectivity / transport type / cellular signal strength.
+        connectivityManager = (ConnectivityManager) getSystemService(Context.CONNECTIVITY_SERVICE);
+        if (connectivityManager != null) {
+            networkCallback = new ConnectivityManager.NetworkCallback() {
+                @Override public void onAvailable(Network network) { emitNetwork(network); }
+                @Override public void onLost(Network network) { emitNetworkDisconnected(); }
+                @Override public void onCapabilitiesChanged(Network network, NetworkCapabilities caps) {
+                    emitNetwork(network);
+                }
+            };
+            try {
+                connectivityManager.registerDefaultNetworkCallback(networkCallback);
+            } catch (Exception e) {
+                Log.e(TAG, "registerDefaultNetworkCallback failed", e);
+            }
+        }
+    }
+
+    private void unregisterSystemEventReceivers() {
+        safeUnregister(batteryReceiver);
+        batteryReceiver = null;
+        safeUnregister(powerSaveReceiver);
+        powerSaveReceiver = null;
+        safeUnregister(screenReceiver);
+        screenReceiver = null;
+        if (connectivityManager != null && networkCallback != null) {
+            try {
+                connectivityManager.unregisterNetworkCallback(networkCallback);
+            } catch (Exception ignored) {
+            }
+            networkCallback = null;
+        }
+    }
+
+    private void safeUnregister(BroadcastReceiver r) {
+        if (r != null) {
+            try {
+                unregisterReceiver(r);
+            } catch (Exception ignored) {
+            }
+        }
+    }
+
+    /** Read the current sticky value for an action without a standing receiver. */
+    @Nullable
+    private Intent registerSticky(String action) {
+        return registerReceiver(null, new IntentFilter(action));
+    }
+
+    /** Push current battery / network / theme so a freshly-loaded UI is populated. */
+    private void emitSystemSnapshot() {
+        emitBattery(registerSticky(Intent.ACTION_BATTERY_CHANGED));
+        if (connectivityManager != null) {
+            Network active = connectivityManager.getActiveNetwork();
+            if (active != null) {
+                emitNetwork(active);
+            } else {
+                emitNetworkDisconnected();
+            }
+        }
+        emitTheme();
+    }
+
+    private void emitBattery(@Nullable Intent batteryStatus) {
+        try {
+            float level = -1f;
+            String state = "unknown";
+            if (batteryStatus != null) {
+                int lvl = batteryStatus.getIntExtra(BatteryManager.EXTRA_LEVEL, -1);
+                int scale = batteryStatus.getIntExtra(BatteryManager.EXTRA_SCALE, -1);
+                if (lvl >= 0 && scale > 0) {
+                    level = lvl / (float) scale;
+                }
+                switch (batteryStatus.getIntExtra(BatteryManager.EXTRA_STATUS, -1)) {
+                    case BatteryManager.BATTERY_STATUS_CHARGING: state = "charging"; break;
+                    case BatteryManager.BATTERY_STATUS_FULL: state = "full"; break;
+                    case BatteryManager.BATTERY_STATUS_DISCHARGING:
+                    case BatteryManager.BATTERY_STATUS_NOT_CHARGING: state = "unplugged"; break;
+                    default: state = "unknown"; break;
+                }
+            }
+            boolean lowPower = false;
+            PowerManager pm = (PowerManager) getSystemService(Context.POWER_SERVICE);
+            if (pm != null) {
+                lowPower = pm.isPowerSaveMode();
+            }
+            JSONObject o = new JSONObject();
+            o.put("level", (double) level);
+            o.put("state", state);
+            o.put("lowPowerMode", lowPower);
+            if (bridge != null) bridge.emitSystemEvent("android:BatteryChanged", o.toString());
+        } catch (Exception e) {
+            Log.e(TAG, "emitBattery failed", e);
+        }
+    }
+
+    private void emitNetwork(@Nullable Network network) {
+        try {
+            boolean connected = false;
+            String type = "none";
+            boolean metered = false;
+            Integer signal = null;
+            if (connectivityManager != null && network != null) {
+                NetworkCapabilities caps = connectivityManager.getNetworkCapabilities(network);
+                if (caps != null) {
+                    connected = caps.hasCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET);
+                    if (caps.hasTransport(NetworkCapabilities.TRANSPORT_WIFI)) {
+                        type = "wifi";
+                    } else if (caps.hasTransport(NetworkCapabilities.TRANSPORT_CELLULAR)) {
+                        type = "cellular";
+                    } else if (caps.hasTransport(NetworkCapabilities.TRANSPORT_ETHERNET)) {
+                        type = "wired";
+                    } else {
+                        type = "other";
+                    }
+                    metered = !caps.hasCapability(NetworkCapabilities.NET_CAPABILITY_NOT_METERED);
+                    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+                        int s = caps.getSignalStrength();
+                        if (s != Integer.MIN_VALUE) {
+                            signal = s; // dBm; closer to 0 is a stronger signal
+                        }
+                    }
+                }
+            }
+            JSONObject o = new JSONObject();
+            o.put("connected", connected);
+            o.put("type", type);
+            o.put("metered", metered);
+            if (signal != null) {
+                o.put("signal", (int) signal);
+            }
+            if (bridge != null) bridge.emitSystemEvent("android:NetworkChanged", o.toString());
+        } catch (Exception e) {
+            Log.e(TAG, "emitNetwork failed", e);
+        }
+    }
+
+    private void emitNetworkDisconnected() {
+        try {
+            JSONObject o = new JSONObject();
+            o.put("connected", false);
+            o.put("type", "none");
+            o.put("metered", false);
+            if (bridge != null) bridge.emitSystemEvent("android:NetworkChanged", o.toString());
+        } catch (Exception ignored) {
+        }
+    }
+
+    private void emitLock(boolean locked) {
+        // Lock/unlock are signals (no payload); name carries the state.
+        if (bridge != null) {
+            bridge.emitSystemEvent(locked ? "android:ScreenLocked" : "android:ScreenUnlocked", "{}");
+        }
+    }
+
+    private void emitTheme() {
+        try {
+            int mode = getResources().getConfiguration().uiMode & Configuration.UI_MODE_NIGHT_MASK;
+            JSONObject o = new JSONObject();
+            // "isDarkMode" matches the context key the desktop platforms use.
+            o.put("isDarkMode", mode == Configuration.UI_MODE_NIGHT_YES);
+            if (bridge != null) bridge.emitSystemEvent("android:ThemeChanged", o.toString());
+        } catch (Exception ignored) {
+        }
+    }
+
+    @Override
+    public void onConfigurationChanged(Configuration newConfig) {
+        super.onConfigurationChanged(newConfig);
+        // Fires for light/dark switches because the manifest lists uiMode in
+        // android:configChanges (otherwise the activity would be recreated).
+        emitTheme();
+    }
+
+    @Override
+    protected void onStart() {
+        super.onStart();
+        // Battery: only monitor system events while the app is visible.
+        if (!systemReceiversRegistered) {
+            registerSystemEventReceivers();
+            systemReceiversRegistered = true;
+        }
+        if (bridge != null) {
+            bridge.onStart();
+        }
+    }
+
+    @Override
+    protected void onResume() {
+        super.onResume();
+        if (bridge != null) {
+            bridge.onResume();
+        }
+    }
+
+    @Override
+    protected void onPause() {
+        super.onPause();
+        if (bridge != null) {
+            bridge.onPause();
+        }
+    }
+
+    @Override
+    protected void onStop() {
+        super.onStop();
+        if (systemReceiversRegistered) {
+            unregisterSystemEventReceivers();
+            systemReceiversRegistered = false;
+        }
+        if (bridge != null) {
+            bridge.onStop();
+        }
+    }
+
+    @Override
+    public void onLowMemory() {
+        super.onLowMemory();
+        if (bridge != null) {
+            bridge.onLowMemory();
+        }
+    }
+
+    @Override
+    protected void onDestroy() {
+        super.onDestroy();
+        unregisterSystemEventReceivers();
+        if (bridge != null) {
+            bridge.shutdown();
+        }
+        if (webView != null) {
+            webView.destroy();
+        }
+    }
+
+    @Override
+    public void onBackPressed() {
+        if (webView != null && webView.canGoBack()) {
+            webView.goBack();
+        } else {
+            super.onBackPressed();
+        }
+    }
+}

build/android/app/src/main/java/com/wails/app/WailsForegroundService.java

@@ -0,0 +1,74 @@
+package com.wails.app;
+
+import android.app.Notification;
+import android.app.NotificationChannel;
+import android.app.NotificationManager;
+import android.app.PendingIntent;
+import android.content.Intent;
+import android.content.pm.ServiceInfo;
+import android.os.Build;
+import android.os.IBinder;
+
+import androidx.annotation.Nullable;
+import androidx.core.app.NotificationCompat;
+
+/**
+ * A minimal started foreground service. It does no work of its own — its purpose
+ * is to keep the app's process alive (with the required ongoing notification) so
+ * the developer's Go goroutines keep running while the app is backgrounded,
+ * which Android would otherwise be free to kill. Start it from
+ * {@link WailsBridge#startForegroundService(String)} and stop it with
+ * {@link WailsBridge#stopForegroundService()}.
+ */
+public class WailsForegroundService extends android.app.Service {
+    public static final String ACTION_START = "com.wails.app.FGS_START";
+    private static final String CHANNEL_ID = "wails_foreground";
+    private static final int NOTIFICATION_ID = 0x57A1; // "WAI"
+
+    @Override
+    public int onStartCommand(Intent intent, int flags, int startId) {
+        String title = "Wails";
+        String text = "Running in the background";
+        if (intent != null) {
+            if (intent.getStringExtra("title") != null) title = intent.getStringExtra("title");
+            if (intent.getStringExtra("text") != null) text = intent.getStringExtra("text");
+        }
+
+        NotificationManager nm = (NotificationManager) getSystemService(NOTIFICATION_SERVICE);
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            NotificationChannel ch = new NotificationChannel(
+                    CHANNEL_ID, "Background work", NotificationManager.IMPORTANCE_LOW);
+            nm.createNotificationChannel(ch);
+        }
+
+        PendingIntent contentIntent = null;
+        Intent launch = getPackageManager().getLaunchIntentForPackage(getPackageName());
+        if (launch != null) {
+            int piFlags = Build.VERSION.SDK_INT >= Build.VERSION_CODES.M
+                    ? PendingIntent.FLAG_IMMUTABLE : 0;
+            contentIntent = PendingIntent.getActivity(this, 0, launch, piFlags);
+        }
+
+        Notification n = new NotificationCompat.Builder(this, CHANNEL_ID)
+                .setSmallIcon(android.R.drawable.ic_popup_sync)
+                .setContentTitle(title)
+                .setContentText(text)
+                .setOngoing(true)
+                .setContentIntent(contentIntent)
+                .build();
+
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+            startForeground(NOTIFICATION_ID, n, ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC);
+        } else {
+            startForeground(NOTIFICATION_ID, n);
+        }
+        // Restart if the OS kills us while still wanted.
+        return START_STICKY;
+    }
+
+    @Nullable
+    @Override
+    public IBinder onBind(Intent intent) {
+        return null;
+    }
+}

build/android/app/src/main/java/com/wails/app/WailsJSBridge.java

@@ -0,0 +1,151 @@
+package com.wails.app;
+
+import android.util.Log;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import android.webkit.JavascriptInterface;
+import android.webkit.WebView;
+import com.wails.app.BuildConfig;
+
+/**
+ * WailsJSBridge provides the JavaScript interface that allows the web frontend
+ * to communicate with the Go backend. This is exposed to JavaScript as the
+ * `window.wails` object.
+ *
+ * Similar to iOS's WKScriptMessageHandler but using Android's addJavascriptInterface.
+ */
+public class WailsJSBridge {
+    private static final String TAG = "WailsJSBridge";
+    private static final boolean DEBUG = BuildConfig.DEBUG;
+    // Pooled threads avoid unbounded thread creation under high call volume.
+    private static final ExecutorService executor = Executors.newCachedThreadPool();
+
+    private final WailsBridge bridge;
+    private final WebView webView;
+
+    public WailsJSBridge(WailsBridge bridge, WebView webView) {
+        this.bridge = bridge;
+        this.webView = webView;
+    }
+
+    /**
+     * Send a message to Go and return the response synchronously.
+     * Called from JavaScript: wails.invoke(message)
+     *
+     * @param message The message to send (JSON string)
+     * @return The response from Go (JSON string)
+     */
+    @JavascriptInterface
+    public String invoke(String message) {
+        if (DEBUG) Log.d(TAG, "Invoke called: " + message);
+        return bridge.handleMessage(message);
+    }
+
+    /**
+     * Send a message to Go asynchronously.
+     * The response will be sent back via a callback.
+     * Called from JavaScript: wails.invokeAsync(callbackId, message)
+     *
+     * @param callbackId The callback ID to use for the response
+     * @param message The message to send (JSON string)
+     */
+    @JavascriptInterface
+    public void invokeAsync(final String callbackId, final String payload) {
+        if (DEBUG) Log.d(TAG, "InvokeAsync called: " + payload);
+
+        // Handle off the JS thread so we don't block the WebView.
+        executor.execute(() -> {
+            try {
+                String response = bridge.handleRuntimeCall(payload);
+                sendCallback(callbackId, response, null);
+            } catch (Exception e) {
+                Log.e(TAG, "Error in async invoke", e);
+                sendCallback(callbackId, null, e.getMessage());
+            }
+        });
+    }
+
+    /**
+     * Log a message from JavaScript to Android's logcat
+     * Called from JavaScript: wails.log(level, message)
+     *
+     * @param level The log level (debug, info, warn, error)
+     * @param message The message to log
+     */
+    @JavascriptInterface
+    public void log(String level, String message) {
+        switch (level.toLowerCase()) {
+            case "debug":
+                Log.d(TAG + "/JS", message);
+                break;
+            case "info":
+                Log.i(TAG + "/JS", message);
+                break;
+            case "warn":
+                Log.w(TAG + "/JS", message);
+                break;
+            case "error":
+                Log.e(TAG + "/JS", message);
+                break;
+            default:
+                Log.v(TAG + "/JS", message);
+                break;
+        }
+    }
+
+    /**
+     * Get the platform name
+     * Called from JavaScript: wails.platform()
+     *
+     * @return "android"
+     */
+    @JavascriptInterface
+    public String platform() {
+        return "android";
+    }
+
+    /**
+     * Check if we're running in debug mode
+     * Called from JavaScript: wails.isDebug()
+     *
+     * @return true if debug build, false otherwise
+     */
+    @JavascriptInterface
+    public boolean isDebug() {
+        return BuildConfig.DEBUG;
+    }
+
+    /**
+     * Send a callback response to JavaScript
+     */
+    private void sendCallback(String callbackId, String result, String error) {
+        final String js;
+        if (error != null) {
+            js = String.format(
+                    "window._wailsAndroidCallback && window._wailsAndroidCallback('%s', null, '%s');",
+                    escapeJsString(callbackId),
+                    escapeJsString(error)
+            );
+        } else {
+            js = String.format(
+                    "window._wailsAndroidCallback && window._wailsAndroidCallback('%s', '%s', null);",
+                    escapeJsString(callbackId),
+                    escapeJsString(result != null ? result : "")
+            );
+        }
+
+        webView.post(() -> webView.evaluateJavascript(js, null));
+    }
+
+    private String escapeJsString(String str) {
+        if (str == null) return "";
+        return str.replace("\\", "\\\\")
+                .replace("'", "\\'")
+                .replace("\n", "\\n")
+                .replace("\r", "\\r")
+                // JS line terminators (U+2028/U+2029) must be escaped too; built via
+                // (char) casts so the Java lexer does not reinterpret them as newlines.
+                .replace(String.valueOf((char) 0x2028), "\\u2028")
+                .replace(String.valueOf((char) 0x2029), "\\u2029");
+    }
+}

build/android/app/src/main/java/com/wails/app/WailsPathHandler.java

@@ -0,0 +1,68 @@
+package com.wails.app;
+
+import android.net.Uri;
+import android.util.Log;
+import android.webkit.WebResourceResponse;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+import androidx.webkit.WebViewAssetLoader;
+
+import java.io.ByteArrayInputStream;
+import java.io.InputStream;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * WailsPathHandler implements WebViewAssetLoader.PathHandler to serve assets
+ * from the Go asset server. This allows the WebView to load assets without
+ * using a network server, similar to iOS's WKURLSchemeHandler.
+ */
+public class WailsPathHandler implements WebViewAssetLoader.PathHandler {
+    private static final String TAG = "WailsPathHandler";
+    private static final boolean DEBUG = BuildConfig.DEBUG;
+
+    private final WailsBridge bridge;
+
+    public WailsPathHandler(WailsBridge bridge) {
+        this.bridge = bridge;
+    }
+
+    @Nullable
+    @Override
+    public WebResourceResponse handle(@NonNull String path) {
+        if (DEBUG) Log.d(TAG, "Handling path: " + path);
+
+        // Normalize path
+        if (path.isEmpty() || path.equals("/")) {
+            path = "/index.html";
+        }
+
+        // Get asset from Go
+        byte[] data = bridge.serveAsset(path, "GET", "{}");
+
+        if (data == null || data.length == 0) {
+            Log.w(TAG, "Asset not found: " + path);
+            return null; // Return null to let WebView handle 404
+        }
+
+        // Determine MIME type
+        String mimeType = bridge.getAssetMimeType(path);
+        if (DEBUG) Log.d(TAG, "Serving " + path + " with type " + mimeType + " (" + data.length + " bytes)");
+
+        // Create response
+        InputStream inputStream = new ByteArrayInputStream(data);
+        Map<String, String> headers = new HashMap<>();
+        headers.put("Access-Control-Allow-Origin", "*");
+        headers.put("Cache-Control", "no-cache");
+
+        return new WebResourceResponse(
+                mimeType,
+                "UTF-8",
+                200,
+                "OK",
+                headers,
+                inputStream
+        );
+    }
+}

build/android/app/src/main/res/layout/activity_main.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="utf-8"?>
+<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:id="@+id/main_container"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent">
+
+    <WebView
+        android:id="@+id/webview"
+        android:layout_width="match_parent"
+        android:layout_height="match_parent" />
+
+</FrameLayout>

build/android/app/src/main/res/values/colors.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <color name="wails_blue">#3574D4</color>
+    <color name="wails_blue_dark">#2C5FB8</color>
+    <color name="wails_background">#1B2636</color>
+    <color name="white">#FFFFFFFF</color>
+    <color name="black">#FF000000</color>
+</resources>

build/android/app/src/main/res/values/strings.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <string name="app_name">Wails App</string>
+</resources>

build/android/app/src/main/res/values/themes.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <style name="Theme.WailsApp" parent="Theme.MaterialComponents.DayNight.NoActionBar">
+        <!-- Primary brand color. -->
+        <item name="colorPrimary">@color/wails_blue</item>
+        <item name="colorPrimaryVariant">@color/wails_blue_dark</item>
+        <item name="colorOnPrimary">@android:color/white</item>
+        <!-- Status bar color. -->
+        <item name="android:statusBarColor">@color/wails_background</item>
+        <item name="android:navigationBarColor">@color/wails_background</item>
+        <!-- Window background -->
+        <item name="android:windowBackground">@color/wails_background</item>
+    </style>
+</resources>

build/android/app/src/main/res/xml/file_paths.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="utf-8"?>
+<paths>
+    <!-- Camera captures are written here and shared with the camera app via the
+         FileProvider. -->
+    <cache-path name="captures" path="captures/" />
+</paths>

build/android/build.gradle

@@ -0,0 +1,4 @@
+// Top-level build file where you can add configuration options common to all sub-projects/modules.
+plugins {
+    id 'com.android.application' version '8.7.3' apply false
+}

build/android/gradle.properties

@@ -0,0 +1,26 @@
+# Project-wide Gradle settings.
+# IDE (e.g. Android Studio) users:
+# Gradle settings configured through the IDE *will override*
+# any settings specified in this file.
+
+# For more details on how to configure your build environment visit
+# http://www.gradle.org/docs/current/userguide/build_environment.html
+
+# Specifies the JVM arguments used for the daemon process.
+# The setting is particularly useful for tweaking memory settings.
+org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
+
+# When configured, Gradle will run in incubating parallel mode.
+# This option should only be used with decoupled projects. For more details, visit
+# https://developer.android.com/build/optimize-your-build#parallel
+# org.gradle.parallel=true
+
+# AndroidX package structure to make it clearer which packages are bundled with the
+# Android operating system, and which are packaged with your app's APK
+# https://developer.android.com/topic/libraries/support-library/androidx-rn
+android.useAndroidX=true
+
+# Enables namespacing of each library's R class so that its R class includes only the
+# resources declared in the library itself and none from the library's dependencies,
+# thereby reducing the size of the R class for that library
+android.nonTransitiveRClass=true

build/android/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,7 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-9.2.1-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists

build/android/gradlew

@@ -0,0 +1,248 @@
+#!/bin/sh
+
+#
+# Copyright © 2015 the original authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+
+##############################################################################
+#
+#   Gradle start up script for POSIX generated by Gradle.
+#
+#   Important for running:
+#
+#   (1) You need a POSIX-compliant shell to run this script. If your /bin/sh is
+#       noncompliant, but you have some other compliant shell such as ksh or
+#       bash, then to run this script, type that shell name before the whole
+#       command line, like:
+#
+#           ksh Gradle
+#
+#       Busybox and similar reduced shells will NOT work, because this script
+#       requires all of these POSIX shell features:
+#         * functions;
+#         * expansions «$var», «${var}», «${var:-default}», «${var+SET}»,
+#           «${var#prefix}», «${var%suffix}», and «$( cmd )»;
+#         * compound commands having a testable exit status, especially «case»;
+#         * various built-in commands including «command», «set», and «ulimit».
+#
+#   Important for patching:
+#
+#   (2) This script targets any POSIX shell, so it avoids extensions provided
+#       by Bash, Ksh, etc; in particular arrays are avoided.
+#
+#       The "traditional" practice of packing multiple parameters into a
+#       space-separated string is a well documented source of bugs and security
+#       problems, so this is (mostly) avoided, by progressively accumulating
+#       options in "$@", and eventually passing that to Java.
+#
+#       Where the inherited environment variables (DEFAULT_JVM_OPTS, JAVA_OPTS,
+#       and GRADLE_OPTS) rely on word-splitting, this is performed explicitly;
+#       see the in-line comments for details.
+#
+#       There are tweaks for specific operating systems such as AIX, CygWin,
+#       Darwin, MinGW, and NonStop.
+#
+#   (3) This script is generated from the Groovy template
+#       https://github.com/gradle/gradle/blob/HEAD/platforms/jvm/plugins-application/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
+#       within the Gradle project.
+#
+#       You can find Gradle at https://github.com/gradle/gradle/.
+#
+##############################################################################
+
+# Attempt to set APP_HOME
+
+# Resolve links: $0 may be a link
+app_path=$0
+
+# Need this for daisy-chained symlinks.
+while
+    APP_HOME=${app_path%"${app_path##*/}"}  # leaves a trailing /; empty if no leading path
+    [ -h "$app_path" ]
+do
+    ls=$( ls -ld "$app_path" )
+    link=${ls#*' -> '}
+    case $link in             #(
+      /*)   app_path=$link ;; #(
+      *)    app_path=$APP_HOME$link ;;
+    esac
+done
+
+# This is normally unused
+# shellcheck disable=SC2034
+APP_BASE_NAME=${0##*/}
+# Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036)
+APP_HOME=$( cd -P "${APP_HOME:-./}" > /dev/null && printf '%s\n' "$PWD" ) || exit
+
+# Use the maximum available, or set MAX_FD != -1 to use that value.
+MAX_FD=maximum
+
+warn () {
+    echo "$*"
+} >&2
+
+die () {
+    echo
+    echo "$*"
+    echo
+    exit 1
+} >&2
+
+# OS specific support (must be 'true' or 'false').
+cygwin=false
+msys=false
+darwin=false
+nonstop=false
+case "$( uname )" in                #(
+  CYGWIN* )         cygwin=true  ;; #(
+  Darwin* )         darwin=true  ;; #(
+  MSYS* | MINGW* )  msys=true    ;; #(
+  NONSTOP* )        nonstop=true ;;
+esac
+
+
+
+# Determine the Java command to use to start the JVM.
+if [ -n "$JAVA_HOME" ] ; then
+    if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
+        # IBM's JDK on AIX uses strange locations for the executables
+        JAVACMD=$JAVA_HOME/jre/sh/java
+    else
+        JAVACMD=$JAVA_HOME/bin/java
+    fi
+    if [ ! -x "$JAVACMD" ] ; then
+        die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+    fi
+else
+    JAVACMD=java
+    if ! command -v java >/dev/null 2>&1
+    then
+        die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+    fi
+fi
+
+# Increase the maximum file descriptors if we can.
+if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then
+    case $MAX_FD in #(
+      max*)
+        # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC2039,SC3045
+        MAX_FD=$( ulimit -H -n ) ||
+            warn "Could not query maximum file descriptor limit"
+    esac
+    case $MAX_FD in  #(
+      '' | soft) :;; #(
+      *)
+        # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC2039,SC3045
+        ulimit -n "$MAX_FD" ||
+            warn "Could not set maximum file descriptor limit to $MAX_FD"
+    esac
+fi
+
+# Collect all arguments for the java command, stacking in reverse order:
+#   * args from the command line
+#   * the main class name
+#   * -classpath
+#   * -D...appname settings
+#   * --module-path (only if needed)
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, and GRADLE_OPTS environment variables.
+
+# For Cygwin or MSYS, switch paths to Windows format before running java
+if "$cygwin" || "$msys" ; then
+    APP_HOME=$( cygpath --path --mixed "$APP_HOME" )
+
+    JAVACMD=$( cygpath --unix "$JAVACMD" )
+
+    # Now convert the arguments - kludge to limit ourselves to /bin/sh
+    for arg do
+        if
+            case $arg in                                #(
+              -*)   false ;;                            # don't mess with options #(
+              /?*)  t=${arg#/} t=/${t%%/*}              # looks like a POSIX filepath
+                    [ -e "$t" ] ;;                      #(
+              *)    false ;;
+            esac
+        then
+            arg=$( cygpath --path --ignore --mixed "$arg" )
+        fi
+        # Roll the args list around exactly as many times as the number of
+        # args, so each arg winds up back in the position where it started, but
+        # possibly modified.
+        #
+        # NB: a `for` loop captures its iteration list before it begins, so
+        # changing the positional parameters here affects neither the number of
+        # iterations, nor the values presented in `arg`.
+        shift                   # remove old arg
+        set -- "$@" "$arg"      # push replacement arg
+    done
+fi
+
+
+# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
+
+# Collect all arguments for the java command:
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments,
+#     and any embedded shellness will be escaped.
+#   * For example: A user cannot expect ${Hostname} to be expanded, as it is an environment variable and will be
+#     treated as '${Hostname}' itself on the command line.
+
+set -- \
+        "-Dorg.gradle.appname=$APP_BASE_NAME" \
+        -jar "$APP_HOME/gradle/wrapper/gradle-wrapper.jar" \
+        "$@"
+
+# Stop when "xargs" is not available.
+if ! command -v xargs >/dev/null 2>&1
+then
+    die "xargs is not available"
+fi
+
+# Use "xargs" to parse quoted args.
+#
+# With -n1 it outputs one arg per line, with the quotes and backslashes removed.
+#
+# In Bash we could simply go:
+#
+#   readarray ARGS < <( xargs -n1 <<<"$var" ) &&
+#   set -- "${ARGS[@]}" "$@"
+#
+# but POSIX shell has neither arrays nor command substitution, so instead we
+# post-process each arg (as a line of input to sed) to backslash-escape any
+# character that might be a shell metacharacter, then use eval to reverse
+# that process (while maintaining the separation between arguments), and wrap
+# the whole thing up as a single "set" statement.
+#
+# This will of course break if any of these variables contains a newline or
+# an unmatched quote.
+#
+
+eval "set -- $(
+        printf '%s\n' "$DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS" |
+        xargs -n1 |
+        sed ' s~[^-[:alnum:]+,./:=@_]~\\&~g; ' |
+        tr '\n' ' '
+    )" '"$@"'
+
+exec "$JAVACMD" "$@"

build/android/gradlew.bat

@@ -0,0 +1,93 @@
+@rem
+@rem Copyright 2015 the original author or authors.
+@rem
+@rem Licensed under the Apache License, Version 2.0 (the "License");
+@rem you may not use this file except in compliance with the License.
+@rem You may obtain a copy of the License at
+@rem
+@rem      https://www.apache.org/licenses/LICENSE-2.0
+@rem
+@rem Unless required by applicable law or agreed to in writing, software
+@rem distributed under the License is distributed on an "AS IS" BASIS,
+@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+@rem See the License for the specific language governing permissions and
+@rem limitations under the License.
+@rem
+@rem SPDX-License-Identifier: Apache-2.0
+@rem
+
+@if "%DEBUG%"=="" @echo off
+@rem ##########################################################################
+@rem
+@rem  Gradle startup script for Windows
+@rem
+@rem ##########################################################################
+
+@rem Set local scope for the variables with windows NT shell
+if "%OS%"=="Windows_NT" setlocal
+
+set DIRNAME=%~dp0
+if "%DIRNAME%"=="" set DIRNAME=.
+@rem This is normally unused
+set APP_BASE_NAME=%~n0
+set APP_HOME=%DIRNAME%
+
+@rem Resolve any "." and ".." in APP_HOME to make it shorter.
+for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi
+
+@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+set DEFAULT_JVM_OPTS="-Xmx64m" "-Xms64m"
+
+@rem Find java.exe
+if defined JAVA_HOME goto findJavaFromJavaHome
+
+set JAVA_EXE=java.exe
+%JAVA_EXE% -version >NUL 2>&1
+if %ERRORLEVEL% equ 0 goto execute
+
+echo. 1>&2
+echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
+
+goto fail
+
+:findJavaFromJavaHome
+set JAVA_HOME=%JAVA_HOME:"=%
+set JAVA_EXE=%JAVA_HOME%/bin/java.exe
+
+if exist "%JAVA_EXE%" goto execute
+
+echo. 1>&2
+echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
+
+goto fail
+
+:execute
+@rem Setup the command line
+
+
+
+@rem Execute Gradle
+"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -jar "%APP_HOME%\gradle\wrapper\gradle-wrapper.jar" %*
+
+:end
+@rem End local scope for the variables with windows NT shell
+if %ERRORLEVEL% equ 0 goto mainEnd
+
+:fail
+rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
+rem the _cmd.exe /c_ return code!
+set EXIT_CODE=%ERRORLEVEL%
+if %EXIT_CODE% equ 0 set EXIT_CODE=1
+if not ""=="%GRADLE_EXIT_CONSOLE%" exit %EXIT_CODE%
+exit /b %EXIT_CODE%
+
+:mainEnd
+if "%OS%"=="Windows_NT" endlocal
+
+:omega

build/android/main_android.go

@@ -0,0 +1,11 @@
+//go:build android
+
+package main
+
+import "github.com/wailsapp/wails/v3/pkg/application"
+
+func init() {
+	// Register main function to be called when the Android app initializes
+	// This is necessary because in c-shared build mode, main() is not automatically called
+	application.RegisterAndroidMain(main)
+}

build/android/scripts/deps/install_deps.go

@@ -0,0 +1,151 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+)
+
+func main() {
+	fmt.Println("Checking Android development dependencies...")
+	fmt.Println()
+
+	errors := []string{}
+
+	// Check Go
+	if !checkCommand("go", "version") {
+		errors = append(errors, "Go is not installed. Install from https://go.dev/dl/")
+	} else {
+		fmt.Println("✓ Go is installed")
+	}
+
+	// Check ANDROID_HOME
+	androidHome := os.Getenv("ANDROID_HOME")
+	if androidHome == "" {
+		androidHome = os.Getenv("ANDROID_SDK_ROOT")
+	}
+	if androidHome == "" {
+		// Try common default locations
+		home, _ := os.UserHomeDir()
+		possiblePaths := []string{
+			filepath.Join(home, "Android", "Sdk"),
+			filepath.Join(home, "Library", "Android", "sdk"),
+			"/usr/local/share/android-sdk",
+		}
+		for _, p := range possiblePaths {
+			if _, err := os.Stat(p); err == nil {
+				androidHome = p
+				break
+			}
+		}
+	}
+
+	if androidHome == "" {
+		errors = append(errors, "ANDROID_HOME not set. Install Android Studio and set ANDROID_HOME environment variable")
+	} else {
+		fmt.Printf("✓ ANDROID_HOME: %s\n", androidHome)
+	}
+
+	// Check adb
+	if !checkCommand("adb", "version") {
+		if androidHome != "" {
+			platformTools := filepath.Join(androidHome, "platform-tools")
+			errors = append(errors, fmt.Sprintf("adb not found. Add %s to PATH", platformTools))
+		} else {
+			errors = append(errors, "adb not found. Install Android SDK Platform-Tools")
+		}
+	} else {
+		fmt.Println("✓ adb is installed")
+	}
+
+	// Check emulator
+	if !checkCommand("emulator", "-list-avds") {
+		if androidHome != "" {
+			emulatorPath := filepath.Join(androidHome, "emulator")
+			errors = append(errors, fmt.Sprintf("emulator not found. Add %s to PATH", emulatorPath))
+		} else {
+			errors = append(errors, "emulator not found. Install Android Emulator via SDK Manager")
+		}
+	} else {
+		fmt.Println("✓ Android Emulator is installed")
+	}
+
+	// Check NDK
+	ndkHome := os.Getenv("ANDROID_NDK_HOME")
+	if ndkHome == "" && androidHome != "" {
+		// Look for NDK in default location
+		ndkDir := filepath.Join(androidHome, "ndk")
+		if entries, err := os.ReadDir(ndkDir); err == nil {
+			for _, entry := range entries {
+				if entry.IsDir() {
+					ndkHome = filepath.Join(ndkDir, entry.Name())
+					break
+				}
+			}
+		}
+	}
+
+	if ndkHome == "" {
+		errors = append(errors, "Android NDK not found. Install NDK via Android Studio > SDK Manager > SDK Tools > NDK (Side by side)")
+	} else {
+		fmt.Printf("✓ Android NDK: %s\n", ndkHome)
+	}
+
+	// Check Java
+	if !checkCommand("java", "-version") {
+		errors = append(errors, "Java not found. Install JDK 11+ (OpenJDK recommended)")
+	} else {
+		fmt.Println("✓ Java is installed")
+	}
+
+	// Check for AVD (Android Virtual Device)
+	if checkCommand("emulator", "-list-avds") {
+		cmd := exec.Command("emulator", "-list-avds")
+		output, err := cmd.Output()
+		if err == nil && len(strings.TrimSpace(string(output))) > 0 {
+			avds := strings.Split(strings.TrimSpace(string(output)), "\n")
+			fmt.Printf("✓ Found %d Android Virtual Device(s)\n", len(avds))
+		} else {
+			fmt.Println("⚠ No Android Virtual Devices found. Create one via Android Studio > Tools > Device Manager")
+		}
+	}
+
+	fmt.Println()
+
+	if len(errors) > 0 {
+		fmt.Println("❌ Missing dependencies:")
+		for _, err := range errors {
+			fmt.Printf("   - %s\n", err)
+		}
+		fmt.Println()
+		fmt.Println("Setup instructions:")
+		fmt.Println("1. Install Android Studio: https://developer.android.com/studio")
+		fmt.Println("2. Open SDK Manager and install:")
+		fmt.Println("   - Android SDK Platform (API 34)")
+		fmt.Println("   - Android SDK Build-Tools")
+		fmt.Println("   - Android SDK Platform-Tools")
+		fmt.Println("   - Android Emulator")
+		fmt.Println("   - NDK (Side by side)")
+		fmt.Println("3. Set environment variables:")
+		if runtime.GOOS == "darwin" {
+			fmt.Println("   export ANDROID_HOME=$HOME/Library/Android/sdk")
+		} else {
+			fmt.Println("   export ANDROID_HOME=$HOME/Android/Sdk")
+		}
+		fmt.Println("   export PATH=$PATH:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator")
+		fmt.Println("4. Create an AVD via Android Studio > Tools > Device Manager")
+		os.Exit(1)
+	}
+
+	fmt.Println("✓ All Android development dependencies are installed!")
+}
+
+func checkCommand(name string, args ...string) bool {
+	cmd := exec.Command(name, args...)
+	cmd.Stdout = nil
+	cmd.Stderr = nil
+	return cmd.Run() == nil
+}

build/android/settings.gradle

@@ -0,0 +1,18 @@
+pluginManagement {
+    repositories {
+        google()
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+
+dependencyResolutionManagement {
+    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+rootProject.name = "WailsApp"
+include ':app'

build/appicon.icon/Assets/wails_icon_vector.svg

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg width="100%" height="100%" viewBox="0 0 583 533" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;">
+    <g transform="matrix(1,0,0,1,-246,-251)">
+        <g id="Ebene1">
+            <path d="M246,251L265,784L401,784L506,450L507,450L505,784L641,784L829,251L682,251L596,567L595,567L596,251L478,251L378,568L391,251L246,251Z"/>
+        </g>
+    </g>
+</svg>

build/appicon.icon/icon.json

@@ -0,0 +1,51 @@
+{
+  "fill" : {
+    "automatic-gradient" : "extended-gray:1.00000,1.00000"
+  },
+  "groups" : [
+    {
+      "layers" : [
+        {
+          "fill-specializations" : [
+            {
+              "appearance" : "dark",
+              "value" : {
+                "solid" : "srgb:0.92143,0.92145,0.92144,1.00000"
+              }
+            },
+            {
+              "appearance" : "tinted",
+              "value" : {
+                "solid" : "srgb:0.83742,0.83744,0.83743,1.00000"
+              }
+            }
+          ],
+          "image-name" : "wails_icon_vector.svg",
+          "name" : "wails_icon_vector",
+          "position" : {
+            "scale" : 1.5,
+            "translation-in-points" : [
+              0.0,
+              0.0
+            ]
+          }
+        }
+      ],
+      "shadow" : {
+        "kind" : "neutral",
+        "opacity" : 0.5
+      },
+      "specular" : true,
+      "translucency" : {
+        "enabled" : true,
+        "value" : 0.5
+      }
+    }
+  ],
+  "supported-platforms" : {
+    "circles" : [
+      "watchOS"
+    ],
+    "squares" : "shared"
+  }
+}

build/config.yml

@@ -0,0 +1,79 @@
+# This file contains the configuration for this project.
+# When you update `info` or `fileAssociations`, run `wails3 task common:update:build-assets` to update the assets.
+# Note that this will overwrite any changes you have made to the assets.
+version: '3'
+
+# This information is used to generate the build assets.
+info:
+  companyName: "OPIc Flow"
+  productName: "OPIc Flow"
+  productIdentifier: "app.opicflow.desktop"
+  description: "AI voice practice and feedback for the OPIc speaking test"
+  copyright: "(c) 2026, OPIc Flow"
+  comments: "Wails 3 + Vue TypeScript desktop application"
+  version: "0.1.0"
+  # cfBundleIconName: "appicon" # The macOS icon name in Assets.car icon bundles (optional)
+  #                               # Should match the name of your .icon file without the extension
+  #                               # If not set and Assets.car exists, defaults to "appicon"
+
+# iOS build configuration (uncomment to customise iOS project generation)
+# Note: Keys under `ios` OVERRIDE values under `info` when set.
+# ios:
+#   # The iOS bundle identifier used in the generated Xcode project (CFBundleIdentifier)
+#   bundleID: "com.mycompany.myproduct"
+#   # The display name shown under the app icon (CFBundleDisplayName/CFBundleName)
+#   displayName: "My Product"
+#   # The app version to embed in Info.plist (CFBundleShortVersionString/CFBundleVersion)
+#   version: "0.0.1"
+#   # The company/organisation name for templates and project settings
+#   company: "My Company"
+#   # Additional comments to embed in Info.plist metadata
+#   comments: "Some Product Comments"
+
+# Dev mode configuration
+dev_mode:
+  root_path: .
+  log_level: warn
+  debounce: 1000
+  ignore:
+    dir:
+      - .git
+      - node_modules
+      - frontend
+      - bin
+    file:
+      - .DS_Store
+      - .gitignore
+      - .gitkeep
+      - "*_test.go"
+    watched_extension:
+      - "*.go"
+      - "*.js" # Watch for changes to JS/TS files included using the //wails:include directive.
+      - "*.ts" # The frontend directory will be excluded entirely by the setting above.
+    git_ignore: true
+  executes:
+    - cmd: wails3 build DEV=true
+      type: blocking
+    - cmd: wails3 task common:dev:frontend
+      type: background
+    - cmd: wails3 task run
+      type: primary
+
+# File Associations
+# More information at: https://v3.wails.io/noit/done/yet
+fileAssociations:
+#  - ext: wails
+#    name: Wails
+#    description: Wails Application File
+#    iconName: wailsFileIcon
+#    role: Editor
+#  - ext: jpg
+#    name: JPEG
+#    description: Image File
+#    iconName: jpegFileIcon
+#    role: Editor
+#    mimeType: image/jpeg  # (optional)
+
+# Other data
+other:
+  - name: My Other Data

build/darwin/Info.dev.plist

@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+	<dict>
+		<key>CFBundleExecutable</key>
+		<string>opic-flow</string>
+		<key>CFBundleGetInfoString</key>
+		<string>Wails 3 + Vue TypeScript desktop application</string>
+		<key>CFBundleIconFile</key>
+		<string>icons</string>
+		<key>CFBundleIconName</key>
+		<string>appicon</string>
+		<key>CFBundleIdentifier</key>
+		<string>app.opicflow.desktop</string>
+		<key>CFBundleName</key>
+		<string>OPIc Flow</string>
+		<key>CFBundlePackageType</key>
+		<string>APPL</string>
+		<key>CFBundleShortVersionString</key>
+		<string>0.1.0</string>
+		<key>CFBundleVersion</key>
+		<string>0.1.0</string>
+		<key>LSMinimumSystemVersion</key>
+		<string>12.0.0</string>
+		<key>NSAppTransportSecurity</key>
+		<dict>
+			<key>NSAllowsLocalNetworking</key>
+			<true/>
+		</dict>
+		<key>NSHighResolutionCapable</key>
+		<string>true</string>
+		<key>NSHumanReadableCopyright</key>
+		<string>(c) 2026, OPIc Flow</string>
+	</dict>
+</plist>

build/darwin/Info.plist

@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+	<dict>
+		<key>CFBundleExecutable</key>
+		<string>opic-flow</string>
+		<key>CFBundleGetInfoString</key>
+		<string>Wails 3 + Vue TypeScript desktop application</string>
+		<key>CFBundleIconFile</key>
+		<string>icons</string>
+		<key>CFBundleIconName</key>
+		<string>appicon</string>
+		<key>CFBundleIdentifier</key>
+		<string>app.opicflow.desktop</string>
+		<key>CFBundleName</key>
+		<string>OPIc Flow</string>
+		<key>CFBundlePackageType</key>
+		<string>APPL</string>
+		<key>CFBundleShortVersionString</key>
+		<string>0.1.0</string>
+		<key>CFBundleVersion</key>
+		<string>0.1.0</string>
+		<key>LSMinimumSystemVersion</key>
+		<string>12.0.0</string>
+		<key>NSHighResolutionCapable</key>
+		<string>true</string>
+		<key>NSHumanReadableCopyright</key>
+		<string>(c) 2026, OPIc Flow</string>
+	</dict>
+</plist>

build/darwin/Taskfile.yml

@@ -0,0 +1,193 @@
+version: '3'
+
+includes:
+  common: ../Taskfile.yml
+
+vars:
+  # Docker image for cross-compilation (used when building on non-macOS)
+  CROSS_IMAGE: wails-cross
+
+tasks:
+  build:
+    summary: Builds the application
+    cmds:
+      - task: '{{if eq OS "darwin"}}build:native{{else}}build:docker{{end}}'
+        vars:
+          ARCH: '{{.ARCH}}'
+          DEV: '{{.DEV}}'
+          OUTPUT: '{{.OUTPUT}}'
+          EXTRA_TAGS: '{{.EXTRA_TAGS}}'
+          OBFUSCATED: '{{.OBFUSCATED}}'
+          GARBLE_ARGS: '{{.GARBLE_ARGS}}'
+    vars:
+      DEFAULT_OUTPUT: '{{.BIN_DIR}}/{{.APP_NAME}}'
+      OUTPUT: '{{ .OUTPUT | default .DEFAULT_OUTPUT }}'
+
+  build:native:
+    summary: Builds the application natively on macOS
+    internal: true
+    deps:
+      - task: common:go:mod:tidy
+      - task: common:build:frontend
+        vars:
+          BUILD_FLAGS:
+            ref: .BUILD_FLAGS
+          OBFUSCATED:
+            ref: .OBFUSCATED
+          DEV:
+            ref: .DEV
+      - task: common:generate:icons
+    preconditions:
+      - sh: '{{if eq .OBFUSCATED "true"}}command -v garble >/dev/null 2>&1{{else}}true{{end}}'
+        msg: "garble is required for obfuscated builds. Install it with: go install mvdan.cc/garble@v0.16.0 (requires Go 1.24+). See https://github.com/burrowers/garble/releases for version/toolchain compatibility."
+    cmds:
+      - '{{if eq .OBFUSCATED "true"}}garble {{.GARBLE_ARGS}} build{{else}}go build{{end}} {{.BUILD_FLAGS}} -o "{{.OUTPUT}}"'
+    vars:
+      BUILD_FLAGS: '{{if eq .DEV "true"}}{{if or .EXTRA_TAGS (eq .OBFUSCATED "true")}}-tags {{if eq .OBFUSCATED "true"}}wails_obfuscated{{if .EXTRA_TAGS}},{{end}}{{end}}{{.EXTRA_TAGS}} {{end}}-buildvcs=false -gcflags=all="-l"{{else}}-tags production{{if eq .OBFUSCATED "true"}},wails_obfuscated{{end}}{{if .EXTRA_TAGS}},{{.EXTRA_TAGS}}{{end}} -trimpath -buildvcs=false -ldflags="-w -s"{{end}}'
+      DEFAULT_OUTPUT: '{{.BIN_DIR}}/{{.APP_NAME}}'
+      OUTPUT: '{{ .OUTPUT | default .DEFAULT_OUTPUT }}'
+    env:
+      GOOS: darwin
+      CGO_ENABLED: 1
+      GOARCH: '{{.ARCH | default ARCH}}'
+      CGO_CFLAGS: "-mmacosx-version-min=12.0"
+      CGO_LDFLAGS: "-mmacosx-version-min=12.0"
+      MACOSX_DEPLOYMENT_TARGET: "12.0"
+
+  build:docker:
+    summary: Cross-compiles for macOS using Docker (for Linux/Windows hosts)
+    internal: true
+    deps:
+      - task: common:build:frontend
+        vars:
+          OBFUSCATED:
+            ref: .OBFUSCATED
+      - task: common:generate:icons
+    preconditions:
+      - sh: docker info > /dev/null 2>&1
+        msg: "Docker is required for cross-compilation. Please install Docker."
+      - sh: docker image inspect {{.CROSS_IMAGE}} > /dev/null 2>&1
+        msg: |
+          Docker image '{{.CROSS_IMAGE}}' not found.
+          Build it first: wails3 task setup:docker
+    cmds:
+      - docker run --rm -v "{{.ROOT_DIR}}:/app" {{.DOCKER_MOUNTS}} -e APP_NAME="{{.APP_NAME}}" {{if .EXTRA_TAGS}}-e EXTRA_TAGS="{{.EXTRA_TAGS}}"{{end}} {{if eq .OBFUSCATED "true"}}-e OBFUSCATED=true{{end}} {{if .GARBLE_ARGS}}-e GARBLE_ARGS="{{.GARBLE_ARGS}}"{{end}} {{.CROSS_IMAGE}} darwin {{.DOCKER_ARCH}}
+      - cmd: docker run --rm -v "{{.ROOT_DIR}}:/app" alpine chown -R $(id -u):$(id -g) /app/bin
+        platforms: [linux, darwin]
+      - mkdir -p {{.BIN_DIR}}
+      - mv "bin/{{.APP_NAME}}-darwin-{{.DOCKER_ARCH}}" "{{.OUTPUT}}"
+    vars:
+      DOCKER_ARCH: '{{if eq .ARCH "arm64"}}arm64{{else if eq .ARCH "amd64"}}amd64{{else}}arm64{{end}}'
+      DEFAULT_OUTPUT: '{{.BIN_DIR}}/{{.APP_NAME}}'
+      OUTPUT: '{{ .OUTPUT | default .DEFAULT_OUTPUT }}'
+      # Generate Docker volume mounts: Go module cache + go.mod replace directives
+      # Uses wails3 tool docker-mounts for cross-platform compatibility (Windows/Linux/macOS)
+      DOCKER_MOUNTS:
+        sh: 'wails3 tool docker-mounts'
+
+  build:universal:
+    summary: Builds darwin universal binary (arm64 + amd64)
+    deps:
+      - task: build
+        vars:
+          ARCH: amd64
+          OUTPUT: "{{.BIN_DIR}}/{{.APP_NAME}}-amd64"
+      - task: build
+        vars:
+          ARCH: arm64
+          OUTPUT: "{{.BIN_DIR}}/{{.APP_NAME}}-arm64"
+    cmds:
+      - task: '{{if eq OS "darwin"}}build:universal:lipo:native{{else}}build:universal:lipo:go{{end}}'
+
+  build:universal:lipo:native:
+    summary: Creates universal binary using native lipo (macOS)
+    internal: true
+    cmds:
+      - lipo -create -output "{{.BIN_DIR}}/{{.APP_NAME}}" "{{.BIN_DIR}}/{{.APP_NAME}}-amd64" "{{.BIN_DIR}}/{{.APP_NAME}}-arm64"
+      - rm "{{.BIN_DIR}}/{{.APP_NAME}}-amd64" "{{.BIN_DIR}}/{{.APP_NAME}}-arm64"
+
+  build:universal:lipo:go:
+    summary: Creates universal binary using wails3 tool lipo (Linux/Windows)
+    internal: true
+    cmds:
+      - wails3 tool lipo -output "{{.BIN_DIR}}/{{.APP_NAME}}" -input "{{.BIN_DIR}}/{{.APP_NAME}}-amd64" -input "{{.BIN_DIR}}/{{.APP_NAME}}-arm64"
+      - rm -f "{{.BIN_DIR}}/{{.APP_NAME}}-amd64" "{{.BIN_DIR}}/{{.APP_NAME}}-arm64"
+
+  package:
+    summary: Packages the application into a `.app` bundle
+    deps:
+      - task: build
+    cmds:
+      - task: create:app:bundle
+
+  package:universal:
+    summary: Packages darwin universal binary (arm64 + amd64)
+    deps:
+      - task: build:universal
+    cmds:
+      - task: create:app:bundle
+
+
+  create:app:bundle:
+    summary: Creates an `.app` bundle
+    cmds:
+      - mkdir -p "{{.BIN_DIR}}/{{.APP_NAME}}.app/Contents/MacOS"
+      - mkdir -p "{{.BIN_DIR}}/{{.APP_NAME}}.app/Contents/Resources"
+      - cp build/darwin/icons.icns "{{.BIN_DIR}}/{{.APP_NAME}}.app/Contents/Resources"
+      - |
+        if [ -f build/darwin/Assets.car ]; then
+          cp build/darwin/Assets.car "{{.BIN_DIR}}/{{.APP_NAME}}.app/Contents/Resources"
+        fi
+      - cp "{{.BIN_DIR}}/{{.APP_NAME}}" "{{.BIN_DIR}}/{{.APP_NAME}}.app/Contents/MacOS"
+      - cp build/darwin/Info.plist "{{.BIN_DIR}}/{{.APP_NAME}}.app/Contents"
+      - task: '{{if eq OS "darwin"}}codesign:adhoc{{else}}codesign:skip{{end}}'
+
+  codesign:adhoc:
+    summary: Ad-hoc signs the app bundle (macOS only)
+    internal: true
+    cmds:
+      - codesign --force --deep --sign - "{{.BIN_DIR}}/{{.APP_NAME}}.app"
+
+  codesign:skip:
+    summary: Skips codesigning when cross-compiling
+    internal: true
+    cmds:
+      - 'echo "Skipping codesign (not available on {{OS}}). Sign the .app on macOS before distribution."'
+
+  run:
+    cmds:
+      - mkdir -p "{{.BIN_DIR}}/{{.APP_NAME}}.dev.app/Contents/MacOS"
+      - mkdir -p "{{.BIN_DIR}}/{{.APP_NAME}}.dev.app/Contents/Resources"
+      - cp build/darwin/icons.icns "{{.BIN_DIR}}/{{.APP_NAME}}.dev.app/Contents/Resources"
+      - |
+        if [ -f build/darwin/Assets.car ]; then
+          cp build/darwin/Assets.car "{{.BIN_DIR}}/{{.APP_NAME}}.dev.app/Contents/Resources"
+        fi
+      - cp "{{.BIN_DIR}}/{{.APP_NAME}}" "{{.BIN_DIR}}/{{.APP_NAME}}.dev.app/Contents/MacOS"
+      - cp "build/darwin/Info.dev.plist" "{{.BIN_DIR}}/{{.APP_NAME}}.dev.app/Contents/Info.plist"
+      - codesign --force --deep --sign - "{{.BIN_DIR}}/{{.APP_NAME}}.dev.app"
+      - '"{{.BIN_DIR}}/{{.APP_NAME}}.dev.app/Contents/MacOS/{{.APP_NAME}}"'
+
+  sign:
+    summary: Signs the application bundle with Developer ID
+    desc: |
+      Signs the .app bundle for distribution.
+      Uses signing identity from `wails3 setup` (stored in ~/.config/wails/defaults.yaml).
+      Override with: task darwin:sign -- --identity "Developer ID Application: ..."
+    deps:
+      - task: package
+    cmds:
+      - wails3 tool sign --input "{{.BIN_DIR}}/{{.APP_NAME}}.app" {{.CLI_ARGS}}
+
+  sign:notarize:
+    summary: Signs and notarizes the application bundle
+    desc: |
+      Signs the .app bundle and submits it for notarization.
+      Uses signing identity and keychain profile from `wails3 setup`.
+
+      First-time setup:
+        wails3 setup
+    deps:
+      - task: package
+    cmds:
+      - wails3 tool sign --input "{{.BIN_DIR}}/{{.APP_NAME}}.app" --notarize {{.CLI_ARGS}}

build/docker/Dockerfile.cross

@@ -0,0 +1,220 @@
+# Cross-compile Wails v3 apps to any platform
+#
+# Darwin: Zig + macOS SDK
+# Linux: Native GCC when host matches target, Zig for cross-arch
+# Windows: Zig + bundled mingw
+#
+# Usage:
+#   docker build -t wails-cross -f Dockerfile.cross .
+#   docker run --rm -v $(pwd):/app wails-cross darwin arm64
+#   docker run --rm -v $(pwd):/app wails-cross darwin amd64
+#   docker run --rm -v $(pwd):/app wails-cross linux amd64
+#   docker run --rm -v $(pwd):/app wails-cross linux arm64
+#   docker run --rm -v $(pwd):/app wails-cross windows amd64
+#   docker run --rm -v $(pwd):/app wails-cross windows arm64
+
+FROM golang:1.26-bookworm
+
+ARG TARGETARCH
+ARG GARBLE_VERSION=v0.16.0
+
+# Install base tools, GCC, and GTK/WebKit dev packages
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl xz-utils python3 nodejs npm pkg-config gcc libc6-dev \
+    libgtk-3-dev libwebkit2gtk-4.1-dev \
+    libgtk-4-dev libwebkitgtk-6.0-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN go install mvdan.cc/garble@${GARBLE_VERSION}
+
+# Install Zig - automatically selects correct binary for host architecture.
+# The SHA-256 is fetched from Zig's official download manifest and verified
+# before extraction to protect against MITM or corrupted downloads.
+ARG ZIG_VERSION=0.14.0
+RUN ZIG_ARCH=$(case "${TARGETARCH}" in arm64) echo "aarch64" ;; *) echo "x86_64" ;; esac) && \
+    ZIG_FILE="zig-linux-${ZIG_ARCH}-${ZIG_VERSION}.tar.xz" && \
+    curl -fSL "https://ziglang.org/download/${ZIG_VERSION}/${ZIG_FILE}" -o "/tmp/${ZIG_FILE}" && \
+    EXPECTED=$(curl -fsSL "https://ziglang.org/download/index.json" | \
+        python3 -c "import json,sys; d=json.load(sys.stdin); print(d[sys.argv[1]][sys.argv[2]+'-linux']['shasum'])" \
+        "${ZIG_VERSION}" "${ZIG_ARCH}") && \
+    echo "${EXPECTED}  /tmp/${ZIG_FILE}" | sha256sum -c - && \
+    tar -xJ -f "/tmp/${ZIG_FILE}" -C /opt && \
+    rm "/tmp/${ZIG_FILE}" && \
+    ln -s /opt/zig-linux-${ZIG_ARCH}-${ZIG_VERSION}/zig /usr/local/bin/zig
+
+# Download macOS SDK (required for darwin targets)
+ARG MACOS_SDK_VERSION=14.5
+RUN curl -L "https://github.com/joseluisq/macosx-sdks/releases/download/${MACOS_SDK_VERSION}/MacOSX${MACOS_SDK_VERSION}.sdk.tar.xz" \
+    | tar -xJ -C /opt \
+    && mv /opt/MacOSX${MACOS_SDK_VERSION}.sdk /opt/macos-sdk
+
+ENV MACOS_SDK_PATH=/opt/macos-sdk
+
+# Create Zig CC wrappers for cross-compilation targets
+# Darwin and Windows use Zig; Linux uses native GCC (run with --platform for cross-arch)
+
+# Darwin arm64
+COPY <<'ZIGWRAP' /usr/local/bin/zcc-darwin-arm64
+#!/bin/sh
+ARGS=""
+SKIP_NEXT=0
+for arg in "$@"; do
+    if [ $SKIP_NEXT -eq 1 ]; then
+        SKIP_NEXT=0
+        continue
+    fi
+    case "$arg" in
+        -target) SKIP_NEXT=1 ;;
+        -mmacosx-version-min=*) ;;
+        *) ARGS="$ARGS $arg" ;;
+    esac
+done
+exec zig cc -fno-sanitize=all -target aarch64-macos-none -isysroot /opt/macos-sdk -I/opt/macos-sdk/usr/include -L/opt/macos-sdk/usr/lib -F/opt/macos-sdk/System/Library/Frameworks -w $ARGS
+ZIGWRAP
+RUN chmod +x /usr/local/bin/zcc-darwin-arm64
+
+# Darwin amd64
+COPY <<'ZIGWRAP' /usr/local/bin/zcc-darwin-amd64
+#!/bin/sh
+ARGS=""
+SKIP_NEXT=0
+for arg in "$@"; do
+    if [ $SKIP_NEXT -eq 1 ]; then
+        SKIP_NEXT=0
+        continue
+    fi
+    case "$arg" in
+        -target) SKIP_NEXT=1 ;;
+        -mmacosx-version-min=*) ;;
+        *) ARGS="$ARGS $arg" ;;
+    esac
+done
+exec zig cc -fno-sanitize=all -target x86_64-macos-none -isysroot /opt/macos-sdk -I/opt/macos-sdk/usr/include -L/opt/macos-sdk/usr/lib -F/opt/macos-sdk/System/Library/Frameworks -w $ARGS
+ZIGWRAP
+RUN chmod +x /usr/local/bin/zcc-darwin-amd64
+
+# Windows amd64 - uses Zig's bundled mingw
+COPY <<'ZIGWRAP' /usr/local/bin/zcc-windows-amd64
+#!/bin/sh
+ARGS=""
+SKIP_NEXT=0
+for arg in "$@"; do
+    if [ $SKIP_NEXT -eq 1 ]; then
+        SKIP_NEXT=0
+        continue
+    fi
+    case "$arg" in
+        -target) SKIP_NEXT=1 ;;
+        -Wl,*) ;;
+        *) ARGS="$ARGS $arg" ;;
+    esac
+done
+exec zig cc -target x86_64-windows-gnu $ARGS
+ZIGWRAP
+RUN chmod +x /usr/local/bin/zcc-windows-amd64
+
+# Windows arm64 - uses Zig's bundled mingw
+COPY <<'ZIGWRAP' /usr/local/bin/zcc-windows-arm64
+#!/bin/sh
+ARGS=""
+SKIP_NEXT=0
+for arg in "$@"; do
+    if [ $SKIP_NEXT -eq 1 ]; then
+        SKIP_NEXT=0
+        continue
+    fi
+    case "$arg" in
+        -target) SKIP_NEXT=1 ;;
+        -Wl,*) ;;
+        *) ARGS="$ARGS $arg" ;;
+    esac
+done
+exec zig cc -target aarch64-windows-gnu $ARGS
+ZIGWRAP
+RUN chmod +x /usr/local/bin/zcc-windows-arm64
+
+# Build script
+COPY <<'SCRIPT' /usr/local/bin/build.sh
+#!/bin/sh
+set -e
+
+OS=${1:-darwin}
+ARCH=${2:-arm64}
+
+case "${OS}-${ARCH}" in
+    darwin-arm64|darwin-aarch64)
+        export CC=zcc-darwin-arm64
+        export GOARCH=arm64
+        export GOOS=darwin
+        ;;
+    darwin-amd64|darwin-x86_64)
+        export CC=zcc-darwin-amd64
+        export GOARCH=amd64
+        export GOOS=darwin
+        ;;
+    linux-arm64|linux-aarch64)
+        export CC=gcc
+        export GOARCH=arm64
+        export GOOS=linux
+        ;;
+    linux-amd64|linux-x86_64)
+        export CC=gcc
+        export GOARCH=amd64
+        export GOOS=linux
+        ;;
+    windows-arm64|windows-aarch64)
+        export CC=zcc-windows-arm64
+        export GOARCH=arm64
+        export GOOS=windows
+        ;;
+    windows-amd64|windows-x86_64)
+        export CC=zcc-windows-amd64
+        export GOARCH=amd64
+        export GOOS=windows
+        ;;
+    *)
+        echo "Usage: <os> <arch>"
+        echo "  os: darwin, linux, windows"
+        echo "  arch: amd64, arm64"
+        exit 1
+        ;;
+esac
+
+export CGO_ENABLED=1
+export CGO_CFLAGS="-w"
+
+# Build frontend if exists and not already built (host may have built it)
+if [ -d "frontend" ] && [ -f "frontend/package.json" ] && [ ! -d "frontend/dist" ]; then
+    (cd frontend && npm install --silent && npm run build --silent)
+fi
+
+# Build
+APP=${APP_NAME:-$(basename $(pwd))}
+mkdir -p bin
+
+EXT=""
+LDFLAGS="-s -w"
+if [ "$GOOS" = "windows" ]; then
+    EXT=".exe"
+    LDFLAGS="-s -w -H windowsgui"
+fi
+
+TAGS="production"
+if [ -n "$EXTRA_TAGS" ]; then
+    TAGS="${TAGS},${EXTRA_TAGS}"
+fi
+
+COMPILER="go build"
+if [ "$OBFUSCATED" = "true" ]; then
+    COMPILER="garble ${GARBLE_ARGS} build"
+    TAGS="${TAGS},wails_obfuscated"
+fi
+
+${COMPILER} -tags "$TAGS" -trimpath -buildvcs=false -ldflags="$LDFLAGS" -o bin/${APP}-${GOOS}-${GOARCH}${EXT} .
+echo "Built: bin/${APP}-${GOOS}-${GOARCH}${EXT}"
+SCRIPT
+RUN chmod +x /usr/local/bin/build.sh
+
+WORKDIR /app
+ENTRYPOINT ["/usr/local/bin/build.sh"]
+CMD ["darwin", "arm64"]

build/docker/Dockerfile.server

@@ -0,0 +1,41 @@
+# Wails Server Mode Dockerfile
+# Multi-stage build for minimal image size
+
+# Build stage
+FROM golang:alpine AS builder
+
+WORKDIR /app
+
+# Install build dependencies
+RUN apk add --no-cache git
+
+# Copy source code
+COPY . .
+
+# Remove local replace directive if present (for production builds)
+RUN sed -i '/^replace/d' go.mod || true
+
+# Download dependencies
+RUN go mod tidy
+
+# Build the server binary
+RUN go build -tags server -ldflags="-s -w" -o server .
+
+# Runtime stage - minimal image
+FROM gcr.io/distroless/static-debian12
+
+# Copy the binary
+COPY --from=builder /app/server /server
+
+# Copy frontend assets
+COPY --from=builder /app/frontend/dist /frontend/dist
+
+# Expose the default port
+EXPOSE 8080
+
+# Bind to all interfaces (required for Docker)
+# Can be overridden at runtime with -e WAILS_SERVER_HOST=...
+ENV WAILS_SERVER_HOST=0.0.0.0
+
+# Run the server
+ENTRYPOINT ["/server"]

build/ios/Assets.xcassets

@@ -0,0 +1,116 @@
+{
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  },
+  "images" : [
+    {
+      "filename" : "icon-20@2x.png",
+      "idiom" : "iphone",
+      "scale" : "2x",
+      "size" : "20x20"
+    },
+    {
+      "filename" : "icon-20@3x.png",
+      "idiom" : "iphone",
+      "scale" : "3x",
+      "size" : "20x20"
+    },
+    {
+      "filename" : "icon-29@2x.png",
+      "idiom" : "iphone",
+      "scale" : "2x",
+      "size" : "29x29"
+    },
+    {
+      "filename" : "icon-29@3x.png",
+      "idiom" : "iphone",
+      "scale" : "3x",
+      "size" : "29x29"
+    },
+    {
+      "filename" : "icon-40@2x.png",
+      "idiom" : "iphone",
+      "scale" : "2x",
+      "size" : "40x40"
+    },
+    {
+      "filename" : "icon-40@3x.png",
+      "idiom" : "iphone",
+      "scale" : "3x",
+      "size" : "40x40"
+    },
+    {
+      "filename" : "icon-60@2x.png",
+      "idiom" : "iphone",
+      "scale" : "2x",
+      "size" : "60x60"
+    },
+    {
+      "filename" : "icon-60@3x.png",
+      "idiom" : "iphone",
+      "scale" : "3x",
+      "size" : "60x60"
+    },
+    {
+      "filename" : "icon-20.png",
+      "idiom" : "ipad",
+      "scale" : "1x",
+      "size" : "20x20"
+    },
+    {
+      "filename" : "icon-20@2x.png",
+      "idiom" : "ipad",
+      "scale" : "2x",
+      "size" : "20x20"
+    },
+    {
+      "filename" : "icon-29.png",
+      "idiom" : "ipad",
+      "scale" : "1x",
+      "size" : "29x29"
+    },
+    {
+      "filename" : "icon-29@2x.png",
+      "idiom" : "ipad",
+      "scale" : "2x",
+      "size" : "29x29"
+    },
+    {
+      "filename" : "icon-40.png",
+      "idiom" : "ipad",
+      "scale" : "1x",
+      "size" : "40x40"
+    },
+    {
+      "filename" : "icon-40@2x.png",
+      "idiom" : "ipad",
+      "scale" : "2x",
+      "size" : "40x40"
+    },
+    {
+      "filename" : "icon-76.png",
+      "idiom" : "ipad",
+      "scale" : "1x",
+      "size" : "76x76"
+    },
+    {
+      "filename" : "icon-76@2x.png",
+      "idiom" : "ipad",
+      "scale" : "2x",
+      "size" : "76x76"
+    },
+    {
+      "filename" : "icon-83.5@2x.png",
+      "idiom" : "ipad",
+      "scale" : "2x",
+      "size" : "83.5x83.5"
+    },
+    {
+      "filename" : "icon-1024.png",
+      "idiom" : "ios-marketing",
+      "scale" : "1x",
+      "size" : "1024x1024"
+    }
+  ]
+}

build/ios/Info.dev.plist

@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+	<dict>
+		<key>CFBundleDisplayName</key>
+		<string>OPIc Flow (Dev)</string>
+		<key>CFBundleExecutable</key>
+		<string>opic-flow</string>
+		<key>CFBundleGetInfoString</key>
+		<string>Wails 3 + Vue TypeScript desktop application</string>
+		<key>CFBundleIdentifier</key>
+		<string>app.opicflow.desktop.dev</string>
+		<key>CFBundleName</key>
+		<string>OPIc Flow (Dev)</string>
+		<key>CFBundlePackageType</key>
+		<string>APPL</string>
+		<key>CFBundleShortVersionString</key>
+		<string>0.1.0-dev</string>
+		<key>CFBundleVersion</key>
+		<string>0.1.0</string>
+		<key>LSRequiresIPhoneOS</key>
+		<true/>
+		<key>MinimumOSVersion</key>
+		<string>15.0</string>
+		<key>NSAppTransportSecurity</key>
+		<dict>
+			<key>NSAllowsArbitraryLoads</key>
+			<true/>
+			<key>NSAllowsLocalNetworking</key>
+			<true/>
+		</dict>
+		<key>NSHumanReadableCopyright</key>
+		<string>(c) 2026, OPIc Flow</string>
+		<key>UILaunchStoryboardName</key>
+		<string>LaunchScreen</string>
+		<key>UIRequiredDeviceCapabilities</key>
+		<array>
+			<string>arm64</string>
+		</array>
+		<key>UISupportedInterfaceOrientations</key>
+		<array>
+			<string>UIInterfaceOrientationPortrait</string>
+			<string>UIInterfaceOrientationLandscapeLeft</string>
+			<string>UIInterfaceOrientationLandscapeRight</string>
+		</array>
+		<key>UISupportedInterfaceOrientations~ipad</key>
+		<array>
+			<string>UIInterfaceOrientationPortrait</string>
+			<string>UIInterfaceOrientationPortraitUpsideDown</string>
+			<string>UIInterfaceOrientationLandscapeLeft</string>
+			<string>UIInterfaceOrientationLandscapeRight</string>
+		</array>
+		<key>WailsDevelopmentMode</key>
+		<true/>
+	</dict>
+</plist>

build/ios/Info.plist

@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+	<dict>
+		<key>CFBundleDisplayName</key>
+		<string>OPIc Flow</string>
+		<key>CFBundleExecutable</key>
+		<string>opic-flow</string>
+		<key>CFBundleGetInfoString</key>
+		<string>Wails 3 + Vue TypeScript desktop application</string>
+		<key>CFBundleIdentifier</key>
+		<string>app.opicflow.desktop</string>
+		<key>CFBundleName</key>
+		<string>OPIc Flow</string>
+		<key>CFBundlePackageType</key>
+		<string>APPL</string>
+		<key>CFBundleShortVersionString</key>
+		<string>0.1.0</string>
+		<key>CFBundleVersion</key>
+		<string>0.1.0</string>
+		<key>LSRequiresIPhoneOS</key>
+		<true/>
+		<key>MinimumOSVersion</key>
+		<string>15.0</string>
+		<key>NSAppTransportSecurity</key>
+		<dict>
+			<key>NSAllowsArbitraryLoads</key>
+			<false/>
+			<key>NSAllowsLocalNetworking</key>
+			<true/>
+		</dict>
+		<key>NSHumanReadableCopyright</key>
+		<string>(c) 2026, OPIc Flow</string>
+		<key>UILaunchStoryboardName</key>
+		<string>LaunchScreen</string>
+		<key>UIRequiredDeviceCapabilities</key>
+		<array>
+			<string>arm64</string>
+		</array>
+		<key>UISupportedInterfaceOrientations</key>
+		<array>
+			<string>UIInterfaceOrientationPortrait</string>
+			<string>UIInterfaceOrientationLandscapeLeft</string>
+			<string>UIInterfaceOrientationLandscapeRight</string>
+		</array>
+		<key>UISupportedInterfaceOrientations~ipad</key>
+		<array>
+			<string>UIInterfaceOrientationPortrait</string>
+			<string>UIInterfaceOrientationPortraitUpsideDown</string>
+			<string>UIInterfaceOrientationLandscapeLeft</string>
+			<string>UIInterfaceOrientationLandscapeRight</string>
+		</array>
+	</dict>
+</plist>

build/ios/LaunchScreen.storyboard

@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<document type="com.apple.InterfaceBuilder3.CocoaTouch.Storyboard.XIB" version="3.0" toolsVersion="21701" targetRuntime="iOS.CocoaTouch" propertyAccessControl="none" useAutolayout="YES" launchScreen="YES" useTraitCollections="YES" useSafeAreas="YES" colorMatched="YES" initialViewController="01J-lp-oVM">
+    <device id="retina6_12" orientation="portrait" appearance="light"/>
+    <dependencies>
+        <deployment identifier="iOS"/>
+        <plugIn identifier="com.apple.InterfaceBuilder.IBCocoaTouchPlugin" version="21678"/>
+        <capability name="Safe area layout guides" minToolsVersion="9.0"/>
+        <capability name="documents saved in the Xcode 8 format" minToolsVersion="8.0"/>
+    </dependencies>
+    <scenes>
+        <!--View Controller-->
+        <scene sceneID="EHf-IW-A2E">
+            <objects>
+                <viewController id="01J-lp-oVM" sceneMemberID="viewController">
+                    <view key="view" contentMode="scaleToFill" id="Ze5-6b-2t3">
+                        <rect key="frame" x="0.0" y="0.0" width="393" height="852"/>
+                        <autoresizingMask key="autoresizingMask" widthSizable="YES" heightSizable="YES"/>
+                        <subviews>
+                            <label opaque="NO" clipsSubviews="YES" userInteractionEnabled="NO" contentMode="left" horizontalHuggingPriority="251" verticalHuggingPriority="251" text="OPIc Flow" textAlignment="center" lineBreakMode="middleTruncation" baselineAdjustment="alignBaselines" minimumFontSize="18" translatesAutoresizingMaskIntoConstraints="NO" id="GJd-Yh-RWb">
+                                <rect key="frame" x="0.0" y="397" width="393" height="43"/>
+                                <fontDescription key="fontDescription" type="boldSystem" pointSize="36"/>
+                                <nil key="textColor"/>
+                                <nil key="highlightedColor"/>
+                            </label>
+                            
+                            <label opaque="NO" clipsSubviews="YES" userInteractionEnabled="NO" contentMode="left" horizontalHuggingPriority="251" verticalHuggingPriority="251" text="AI voice practice and feedback for the OPIc speaking test" textAlignment="center" lineBreakMode="tailTruncation" baselineAdjustment="alignBaselines" minimumFontSize="9" translatesAutoresizingMaskIntoConstraints="NO" id="MN2-I3-ftu">
+                                <rect key="frame" x="0.0" y="448" width="393" height="21"/>
+                                <fontDescription key="fontDescription" type="system" pointSize="17"/>
+                                <nil key="textColor"/>
+                                <nil key="highlightedColor"/>
+                            </label>
+                            
+                        </subviews>
+                        <viewLayoutGuide key="safeArea" id="Bcu-3y-fUS"/>
+                        <color key="backgroundColor" white="1" alpha="1" colorSpace="custom" customColorSpace="genericGamma22GrayColorSpace"/>
+                        <constraints>
+                            <constraint firstItem="Bcu-3y-fUS" firstAttribute="centerX" secondItem="GJd-Yh-RWb" secondAttribute="centerX" id="Q3B-4B-g5h"/>
+                            <constraint firstItem="GJd-Yh-RWb" firstAttribute="centerY" secondItem="Ze5-6b-2t3" secondAttribute="bottom" multiplier="1/2" constant="-20" id="moa-c2-u7t"/>
+                            <constraint firstItem="GJd-Yh-RWb" firstAttribute="leading" secondItem="Bcu-3y-fUS" secondAttribute="leading" symbolic="YES" id="x7j-FC-K8j"/>
+                            
+                            <constraint firstItem="MN2-I3-ftu" firstAttribute="top" secondItem="GJd-Yh-RWb" secondAttribute="bottom" constant="8" symbolic="YES" id="cPy-rs-vsC"/>
+                            <constraint firstItem="MN2-I3-ftu" firstAttribute="centerX" secondItem="Bcu-3y-fUS" secondAttribute="centerX" id="OQL-iM-xY6"/>
+                            <constraint firstItem="MN2-I3-ftu" firstAttribute="leading" secondItem="Bcu-3y-fUS" secondAttribute="leading" symbolic="YES" id="Dti-5h-tvW"/>
+                            
+                        </constraints>
+                    </view>
+                </viewController>
+                <placeholder placeholderIdentifier="IBFirstResponder" id="iYj-Kq-Ea1" userLabel="First Responder" sceneMemberID="firstResponder"/>
+            </objects>
+            <point key="canvasLocation" x="53" y="375"/>
+        </scene>
+    </scenes>
+</document>

build/ios/Taskfile.yml

@@ -0,0 +1,365 @@
+version: '3'
+
+includes:
+  common: ../Taskfile.yml
+
+# Platform selection:
+#   task ios:package                          -> simulator bundle (ad-hoc signed)
+#   task ios:package IOS_PLATFORM=device CODESIGN_IDENTITY="Apple Development: ..." \
+#        [PROVISIONING_PROFILE=path.mobileprovision]
+#                                             -> device bundle (real signing)
+#   task ios:package:ipa IOS_PLATFORM=device ... -> .ipa for distribution/install
+# For automatically managed signing & provisioning, use `task ios:xcode` and
+# build from the generated Xcode project instead.
+vars:
+  BUNDLE_ID: '{{.BUNDLE_ID | default "com.wails.app"}}'
+  IOS_PLATFORM: '{{.IOS_PLATFORM | default "simulator"}}'
+  MIN_IOS_VERSION: '{{.MIN_IOS_VERSION | default "15.0"}}'
+  IOS_SDK: '{{if eq .IOS_PLATFORM "device"}}iphoneos{{else}}iphonesimulator{{end}}'
+  IOS_TARGET: 'arm64-apple-ios{{.MIN_IOS_VERSION}}{{if ne .IOS_PLATFORM "device"}}-simulator{{end}}'
+  IOS_VERSION_MIN_FLAG: '{{if eq .IOS_PLATFORM "device"}}-miphoneos-version-min={{.MIN_IOS_VERSION}}{{else}}-mios-simulator-version-min={{.MIN_IOS_VERSION}}{{end}}'
+  # "-" is ad-hoc signing: fine for the simulator, rejected by real devices.
+  CODESIGN_IDENTITY: '{{.CODESIGN_IDENTITY | default "-"}}'
+  # Optional path to a .mobileprovision embedded into device bundles
+  PROVISIONING_PROFILE: '{{.PROVISIONING_PROFILE | default ""}}'
+  # Optional entitlements applied at codesign time (generated default below)
+  ENTITLEMENTS_FILE: '{{.ENTITLEMENTS_FILE | default "build/ios/entitlements.plist"}}'
+  # SDK_PATH is computed lazily at task-level to avoid errors on non-macOS systems
+
+tasks:
+  install:deps:
+    summary: Check and install iOS development dependencies
+    cmds:
+      - go run build/ios/scripts/deps/install_deps.go
+    env:
+      TASK_FORCE_YES: '{{if .YES}}true{{else}}false{{end}}'
+    prompt: This will check and install iOS development dependencies. Continue?
+
+  # Note: Bindings generation may show CGO warnings for iOS C imports.
+  # These warnings are harmless and don't affect the generated bindings,
+  # as the generator only needs to parse Go types, not C implementations.
+  build:
+    summary: Creates a build of the application for iOS
+    deps:
+      - task: generate:ios:overlay
+      - task: generate:ios:xcode
+      - task: common:go:mod:tidy
+      - task: common:build:frontend
+        vars:
+          BUILD_FLAGS:
+            ref: .BUILD_FLAGS
+          PRODUCTION:
+            ref: .PRODUCTION
+    cmds:
+      - echo "Building iOS app {{.APP_NAME}} ({{.IOS_PLATFORM}})..."
+      - go build -buildmode=c-archive -overlay build/ios/xcode/overlay.json {{.BUILD_FLAGS}} -o {{.OUTPUT}}.a
+    vars:
+      BUILD_FLAGS: '{{if eq .PRODUCTION "true"}}-tags production,ios -trimpath -buildvcs=false -ldflags="-w -s"{{else}}-tags ios,debug -buildvcs=false -gcflags=all="-l"{{end}}'
+      DEFAULT_OUTPUT: '{{.BIN_DIR}}/{{.APP_NAME}}'
+      OUTPUT: '{{ .OUTPUT | default .DEFAULT_OUTPUT }}'
+      SDK_PATH:
+        sh: xcrun --sdk {{.IOS_SDK}} --show-sdk-path
+    env:
+      GOOS: ios
+      CGO_ENABLED: 1
+      GOARCH: '{{.ARCH | default "arm64"}}'
+      PRODUCTION: '{{.PRODUCTION | default "false"}}'
+      CGO_CFLAGS: '-isysroot {{.SDK_PATH}} -target {{.IOS_TARGET}} {{.IOS_VERSION_MIN_FLAG}}'
+      CGO_LDFLAGS: '-isysroot {{.SDK_PATH}} -target {{.IOS_TARGET}}'
+
+  package:
+    summary: Packages a production build of the application into a `.app` bundle
+    deps:
+      - task: build
+        vars:
+          PRODUCTION: "true"
+    cmds:
+      - task: compile:ios:link
+      - task: create:app:bundle
+
+  package:ipa:
+    summary: Packages a production build into an .ipa (requires IOS_PLATFORM=device and a real CODESIGN_IDENTITY)
+    deps:
+      - task: package
+    cmds:
+      - rm -rf "{{.BIN_DIR}}/Payload" "{{.BIN_DIR}}/{{.APP_NAME}}.ipa"
+      - mkdir -p "{{.BIN_DIR}}/Payload"
+      - cp -R "{{.BIN_DIR}}/{{.APP_NAME}}.app" "{{.BIN_DIR}}/Payload/"
+      - cd "{{.BIN_DIR}}" && zip -qry "{{.APP_NAME}}.ipa" Payload
+      - rm -rf "{{.BIN_DIR}}/Payload"
+      - echo "Created {{.BIN_DIR}}/{{.APP_NAME}}.ipa"
+
+  # Link the Go c-archive with main.m into the final executable.
+  # Used by both the dev `run` flow and `package`.
+  compile:ios:link:
+    internal: true
+    summary: Link the iOS executable from the Go archive and main.m
+    vars:
+      SDK_PATH:
+        sh: xcrun --sdk {{.IOS_SDK}} --show-sdk-path
+    cmds:
+      - |
+        MAIN_M=build/ios/xcode/main/main.m
+        if [ ! -f "$MAIN_M" ]; then
+          MAIN_M=build/ios/main.m
+        fi
+        xcrun -sdk {{.IOS_SDK}} clang \
+          -target {{.IOS_TARGET}} \
+          -isysroot {{.SDK_PATH}} \
+          -framework Foundation -framework UIKit -framework WebKit \
+          -framework Security -framework CoreFoundation \
+          -framework UniformTypeIdentifiers \
+          -framework LocalAuthentication -framework UserNotifications \
+          -framework AVFoundation \
+          -framework CoreLocation -framework CoreMotion -framework SystemConfiguration \
+          -lresolv \
+          -o "{{.BIN_DIR}}/{{.APP_NAME | lower}}" \
+          "$MAIN_M" -Wl,-force_load,"{{.BIN_DIR}}/{{.APP_NAME}}.a"
+
+  create:app:bundle:
+    summary: Creates an iOS `.app` bundle
+    cmds:
+      - rm -rf "{{.BIN_DIR}}/{{.APP_NAME}}.app"
+      - mkdir -p "{{.BIN_DIR}}/{{.APP_NAME}}.app"
+      - cp "{{.BIN_DIR}}/{{.APP_NAME | lower}}" "{{.BIN_DIR}}/{{.APP_NAME}}.app/"
+      - cp build/ios/Info.plist "{{.BIN_DIR}}/{{.APP_NAME}}.app/"
+      - |
+        # Embed the provisioning profile for device builds when provided
+        if [ "{{.IOS_PLATFORM}}" = "device" ] && [ -n "{{.PROVISIONING_PROFILE}}" ]; then
+          cp "{{.PROVISIONING_PROFILE}}" "{{.BIN_DIR}}/{{.APP_NAME}}.app/embedded.mobileprovision"
+        fi
+      - |
+        # Compile asset catalog and embed icons in the app bundle
+        APP_BUNDLE="{{.BIN_DIR}}/{{.APP_NAME}}.app"
+        AC_IN="build/ios/xcode/main/Assets.xcassets"
+        if [ -d "$AC_IN" ]; then
+          TMP_AC=$(mktemp -d)
+          xcrun actool \
+            --compile "$TMP_AC" \
+            --app-icon AppIcon \
+            --platform {{.IOS_SDK}} \
+            --minimum-deployment-target {{.MIN_IOS_VERSION}} \
+            --product-type com.apple.product-type.application \
+            --target-device iphone \
+            --target-device ipad \
+            --output-partial-info-plist "$APP_BUNDLE/assetcatalog_generated_info.plist" \
+            "$AC_IN"
+          if [ -f "$TMP_AC/Assets.car" ]; then
+            cp -f "$TMP_AC/Assets.car" "$APP_BUNDLE/Assets.car"
+          fi
+          rm -rf "$TMP_AC"
+          if [ -f "$APP_BUNDLE/assetcatalog_generated_info.plist" ]; then
+            /usr/libexec/PlistBuddy -c "Merge $APP_BUNDLE/assetcatalog_generated_info.plist" "$APP_BUNDLE/Info.plist" || true
+          fi
+        fi
+      - |
+        # Sign the bundle. Ad-hoc ("-") works on the simulator only; device
+        # builds need a real identity (and usually entitlements + profile).
+        # Entitlements are only applied to device builds - simulator bundles
+        # must not carry them (SpringBoard refuses to launch the app).
+        if [ "{{.IOS_PLATFORM}}" = "device" ] && [ -f "{{.ENTITLEMENTS_FILE}}" ]; then
+          codesign --force --sign "{{.CODESIGN_IDENTITY}}" --entitlements "{{.ENTITLEMENTS_FILE}}" "{{.BIN_DIR}}/{{.APP_NAME}}.app"
+        else
+          codesign --force --sign "{{.CODESIGN_IDENTITY}}" "{{.BIN_DIR}}/{{.APP_NAME}}.app"
+        fi
+
+  deploy-simulator:
+    summary: Deploy to iOS Simulator
+    deps: [package]
+    cmds:
+      - |
+        # Read the real bundle id from the built bundle (it comes from
+        # build/config.yml, not the BUNDLE_ID var, so it varies per project).
+        APP="{{.BIN_DIR}}/{{.APP_NAME}}.app"
+        BUNDLE_ID=$(/usr/libexec/PlistBuddy -c 'Print :CFBundleIdentifier' "$APP/Info.plist")
+        xcrun simctl terminate booted "$BUNDLE_ID" 2>/dev/null || true
+        xcrun simctl uninstall booted "$BUNDLE_ID" 2>/dev/null || true
+        xcrun simctl install booted "$APP"
+        xcrun simctl launch booted "$BUNDLE_ID"
+
+  deploy-device:
+    summary: Install and launch on a connected device (requires IOS_PLATFORM=device build and real signing)
+    cmds:
+      - |
+        DEVICE="{{.DEVICE_ID}}"
+        if [ -z "$DEVICE" ]; then
+          DEVICE=$(xcrun devicectl list devices --hide-headers 2>/dev/null | awk 'NR==1 {print $3}')
+        fi
+        if [ -z "$DEVICE" ]; then
+          echo "No connected device found. Pass DEVICE_ID=<identifier> (see: xcrun devicectl list devices)"
+          exit 1
+        fi
+        xcrun devicectl device install app --device "$DEVICE" "{{.BIN_DIR}}/{{.APP_NAME}}.app"
+        BUNDLE_ID=$(/usr/libexec/PlistBuddy -c 'Print :CFBundleIdentifier' "{{.BIN_DIR}}/{{.APP_NAME}}.app/Info.plist")
+        xcrun devicectl device process launch --device "$DEVICE" "$BUNDLE_ID"
+
+  compile:ios:
+    summary: Compile the iOS executable from Go archive and main.m
+    deps:
+      - task: build
+    cmds:
+      - task: compile:ios:link
+
+  generate:ios:bindings:
+    internal: true
+    summary: Generates bindings for iOS with proper CGO flags
+    sources:
+      - "**/*.go"
+      - go.mod
+      - go.sum
+    generates:
+      - frontend/bindings/**/*
+    vars:
+      SDK_PATH:
+        sh: xcrun --sdk {{.IOS_SDK}} --show-sdk-path
+    cmds:
+      - wails3 generate bindings -f '{{.BUILD_FLAGS}}' -clean=true
+    env:
+      GOOS: ios
+      CGO_ENABLED: 1
+      GOARCH: '{{.ARCH | default "arm64"}}'
+      CGO_CFLAGS: '-isysroot {{.SDK_PATH}} -target {{.IOS_TARGET}} {{.IOS_VERSION_MIN_FLAG}}'
+      CGO_LDFLAGS: '-isysroot {{.SDK_PATH}} -target {{.IOS_TARGET}}'
+
+  ensure-simulator:
+    internal: true
+    summary: Ensure iOS Simulator is running and booted
+    silent: true
+    cmds:
+      - |
+        if ! xcrun simctl list devices booted | grep -q "Booted"; then
+          echo "Starting iOS Simulator..."
+          # Get first available iPhone device
+          DEVICE_ID=$(xcrun simctl list devices available | grep "iPhone" | head -1 | grep -o "[A-F0-9-]\{36\}" || true)
+          if [ -z "$DEVICE_ID" ]; then
+            echo "No iPhone simulator found. Creating one..."
+            RUNTIME=$(xcrun simctl list runtimes | grep iOS | tail -1 | awk '{print $NF}')
+            # Use the newest iPhone device type this Xcode knows about
+            DEVICE_TYPE=$(xcrun simctl list devicetypes | grep -oE "iPhone [0-9][^(]*" | tail -1 | xargs)
+            DEVICE_ID=$(xcrun simctl create "Wails iPhone" "${DEVICE_TYPE:-iPhone 15}" "$RUNTIME")
+          fi
+          # Boot the device
+          echo "Booting device $DEVICE_ID..."
+          xcrun simctl boot "$DEVICE_ID" 2>/dev/null || true
+          # Open Simulator app
+          open -a Simulator
+          # Wait for boot (max 30 seconds)
+          for i in {1..30}; do
+            if xcrun simctl list devices booted | grep -q "Booted"; then
+              echo "Simulator booted successfully"
+              break
+            fi
+            sleep 1
+          done
+          # Final check
+          if ! xcrun simctl list devices booted | grep -q "Booted"; then
+            echo "Failed to boot simulator after 30 seconds"
+            exit 1
+          fi
+        fi
+    preconditions:
+      - sh: command -v xcrun
+        msg: "xcrun not found. Please run 'wails3 task ios:install:deps' to install iOS development dependencies"
+
+  generate:ios:overlay:
+    internal: true
+    summary: Generate Go build overlay and iOS shim
+    sources:
+      - build/config.yml
+    generates:
+      - build/ios/xcode/overlay.json
+      - build/ios/xcode/gen/main_ios.gen.go
+    cmds:
+      - wails3 ios overlay:gen -out build/ios/xcode/overlay.json -config build/config.yml
+
+  generate:ios:xcode:
+    internal: true
+    summary: Generate iOS Xcode project structure and assets
+    sources:
+      - build/config.yml
+      - build/appicon.png
+    generates:
+      - build/ios/xcode/main/main.m
+      - build/ios/xcode/main/Assets.xcassets/**/*
+      - build/ios/xcode/project.pbxproj
+    cmds:
+      - wails3 ios xcode:gen -outdir build/ios/xcode -config build/config.yml
+
+  run:
+    summary: Run the application in iOS Simulator
+    deps:
+      - task: ensure-simulator
+      - task: compile:ios
+    cmds:
+      - rm -rf "{{.BIN_DIR}}/{{.APP_NAME}}.dev.app"
+      - mkdir -p "{{.BIN_DIR}}/{{.APP_NAME}}.dev.app"
+      - cp "{{.BIN_DIR}}/{{.APP_NAME | lower}}" "{{.BIN_DIR}}/{{.APP_NAME}}.dev.app/{{.APP_NAME | lower}}"
+      - cp build/ios/Info.dev.plist "{{.BIN_DIR}}/{{.APP_NAME}}.dev.app/Info.plist"
+      - |
+        # Compile asset catalog and embed icons for dev bundle
+        APP_BUNDLE="{{.BIN_DIR}}/{{.APP_NAME}}.dev.app"
+        AC_IN="build/ios/xcode/main/Assets.xcassets"
+        if [ -d "$AC_IN" ]; then
+          TMP_AC=$(mktemp -d)
+          xcrun actool \
+            --compile "$TMP_AC" \
+            --app-icon AppIcon \
+            --platform iphonesimulator \
+            --minimum-deployment-target {{.MIN_IOS_VERSION}} \
+            --product-type com.apple.product-type.application \
+            --target-device iphone \
+            --target-device ipad \
+            --output-partial-info-plist "$APP_BUNDLE/assetcatalog_generated_info.plist" \
+            "$AC_IN"
+          if [ -f "$TMP_AC/Assets.car" ]; then
+            cp -f "$TMP_AC/Assets.car" "$APP_BUNDLE/Assets.car"
+          fi
+          rm -rf "$TMP_AC"
+          if [ -f "$APP_BUNDLE/assetcatalog_generated_info.plist" ]; then
+            /usr/libexec/PlistBuddy -c "Merge $APP_BUNDLE/assetcatalog_generated_info.plist" "$APP_BUNDLE/Info.plist" || true
+          fi
+        fi
+      - codesign --force --sign - "{{.BIN_DIR}}/{{.APP_NAME}}.dev.app"
+      - |
+        # The dev bundle id comes from build/ios/Info.dev.plist (derived from
+        # build/config.yml), so read it from the built bundle rather than
+        # assuming a com.wails.* prefix.
+        DEV_APP="{{.BIN_DIR}}/{{.APP_NAME}}.dev.app"
+        BUNDLE_ID=$(/usr/libexec/PlistBuddy -c 'Print :CFBundleIdentifier' "$DEV_APP/Info.plist")
+        xcrun simctl terminate booted "$BUNDLE_ID" 2>/dev/null || true
+        xcrun simctl uninstall booted "$BUNDLE_ID" 2>/dev/null || true
+        xcrun simctl install booted "$DEV_APP"
+        xcrun simctl launch booted "$BUNDLE_ID"
+
+  xcode:
+    summary: Open the generated Xcode project for this app
+    cmds:
+      - task: generate:ios:xcode
+      - open build/ios/xcode/main.xcodeproj
+
+  logs:
+    summary: Stream iOS Simulator logs filtered to this app
+    cmds:
+      - |
+        xcrun simctl spawn booted log stream \
+          --level debug \
+          --style compact \
+          --predicate 'senderImagePath CONTAINS[c] "{{.APP_NAME | lower}}.app/" OR composedMessage CONTAINS[c] "{{.APP_NAME | lower}}" OR eventMessage CONTAINS[c] "{{.APP_NAME | lower}}" OR process == "{{.APP_NAME | lower}}" OR category CONTAINS[c] "{{.APP_NAME | lower}}"'
+
+  logs:dev:
+    summary: Stream logs for the dev bundle (used by `task ios:run`)
+    cmds:
+      - |
+        xcrun simctl spawn booted log stream \
+          --level debug \
+          --style compact \
+          --predicate 'senderImagePath CONTAINS[c] ".dev.app/" OR subsystem == "com.wails.{{.APP_NAME | lower}}.dev" OR process == "{{.APP_NAME | lower}}"'
+
+  logs:wide:
+    summary: Wide log stream to help discover the exact process/bundle identifiers
+    cmds:
+      - |
+        xcrun simctl spawn booted log stream \
+          --level debug \
+          --style compact \
+          --predicate 'senderImagePath CONTAINS[c] ".app/"'

build/ios/app_options_default.go

@@ -0,0 +1,10 @@
+//go:build !ios
+
+package main
+
+import "github.com/wailsapp/wails/v3/pkg/application"
+
+// modifyOptionsForIOS is a no-op on non-iOS platforms
+func modifyOptionsForIOS(opts *application.Options) {
+	// No modifications needed for non-iOS platforms
+}

build/ios/app_options_ios.go

@@ -0,0 +1,11 @@
+//go:build ios
+
+package main
+
+import "github.com/wailsapp/wails/v3/pkg/application"
+
+// modifyOptionsForIOS adjusts the application options for iOS
+func modifyOptionsForIOS(opts *application.Options) {
+	// Disable signal handlers on iOS to prevent crashes
+	opts.DisableDefaultSignalHandler = true
+}

build/ios/entitlements.plist

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+	<dict>
+		<key>get-task-allow</key>
+		<true/>
+	</dict>
+</plist>

build/ios/icon.png

@@ -0,0 +1,3 @@
+# iOS Icon Placeholder
+# This file should be replaced with the actual app icon (1024x1024 PNG)
+# The build process will generate all required icon sizes from this base icon

build/ios/main.m

@@ -0,0 +1,22 @@
+//go:build ios
+// Minimal bootstrap: delegate comes from Go archive (WailsAppDelegate)
+#import <UIKit/UIKit.h>
+#include <stdio.h>
+
+int main(int argc, char * argv[]) {
+    @autoreleasepool {
+        // Disable buffering so stdout/stderr from Go log.Printf flush immediately
+        setvbuf(stdout, NULL, _IONBF, 0);
+        setvbuf(stderr, NULL, _IONBF, 0);
+
+        // Call UIApplicationMain IMMEDIATELY and start NOTHING else here. Do not
+        // start the Go runtime yet: starting it concurrently with UIApplicationMain
+        // intermittently corrupts the FrontBoard launch handshake on a physical
+        // device, so the app delegate's didFinishLaunchingWithOptions never fires
+        // (blank cold launch / 0x8BADF00D). Instead, the WailsAppDelegate (provided
+        // by the Go archive) starts the Go runtime itself from
+        // didFinishLaunchingWithOptions — i.e. only AFTER UIKit has delivered the
+        // launch — so the runtime never races the launch handshake.
+        return UIApplicationMain(argc, argv, nil, @"WailsAppDelegate");
+    }
+}

build/ios/main_ios.go

@@ -0,0 +1,23 @@
+//go:build ios
+
+package main
+
+import (
+	"C"
+)
+
+// For iOS builds we export a function the WailsAppDelegate can call.
+// This wrapper keeps the user's main.go unmodified.
+
+// WailsIOSMain runs the user's main() (application.New / app.Run). It is invoked
+// by the WailsAppDelegate from didFinishLaunchingWithOptions — i.e. only AFTER
+// UIKit has launched — on a BACKGROUND thread, so the Go runtime never starts
+// concurrently with UIApplicationMain (that race intermittently corrupts the
+// FrontBoard launch handshake on a physical device → blank cold launch /
+// scene-create watchdog 0x8BADF00D). Keeping all app setup off the OS main
+// thread also leaves UIApplicationMain unobstructed on the main thread.
+//
+//export WailsIOSMain
+func WailsIOSMain() {
+	main()
+}

build/ios/project.pbxproj

@@ -0,0 +1,222 @@
+// !$*UTF8*$!
+{
+	archiveVersion = 1;
+	classes = {};
+	objectVersion = 56;
+	objects = {
+
+/* Begin PBXBuildFile section */
+		C0DEBEEF0000000000000001 /* main.m in Sources */ = {isa = PBXBuildFile; fileRef = C0DEBEEF0000000000000002 /* main.m */; };
+		C0DEBEEF00000000000000F1 /* UIKit.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = C0DEBEEF0000000000000101 /* UIKit.framework */; };
+		C0DEBEEF00000000000000F2 /* Foundation.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = C0DEBEEF0000000000000102 /* Foundation.framework */; };
+		C0DEBEEF00000000000000F3 /* WebKit.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = C0DEBEEF0000000000000103 /* WebKit.framework */; };
+		C0DEBEEF00000000000000F4 /* Security.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = C0DEBEEF0000000000000104 /* Security.framework */; };
+		C0DEBEEF00000000000000F5 /* CoreFoundation.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = C0DEBEEF0000000000000105 /* CoreFoundation.framework */; };
+		C0DEBEEF00000000000000F6 /* libresolv.tbd in Frameworks */ = {isa = PBXBuildFile; fileRef = C0DEBEEF0000000000000106 /* libresolv.tbd */; };
+		C0DEBEEF00000000000000F7 /* OPIc Flow.a in Frameworks */ = {isa = PBXBuildFile; fileRef = C0DEBEEF0000000000000107 /* OPIc Flow.a */; };
+/* End PBXBuildFile section */
+
+/* Begin PBXFileReference section */
+		C0DEBEEF0000000000000002 /* main.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; path = main.m; sourceTree = "<group>"; };
+		C0DEBEEF0000000000000003 /* Info.plist */ = {isa = PBXFileReference; lastKnownFileType = text.plist.xml; path = Info.plist; sourceTree = "<group>"; };
+		C0DEBEEF0000000000000004 /* OPIc Flow.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = "OPIc Flow.app"; sourceTree = BUILT_PRODUCTS_DIR; };
+		C0DEBEEF0000000000000101 /* UIKit.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = UIKit.framework; path = System/Library/Frameworks/UIKit.framework; sourceTree = SDKROOT; };
+		C0DEBEEF0000000000000102 /* Foundation.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = Foundation.framework; path = System/Library/Frameworks/Foundation.framework; sourceTree = SDKROOT; };
+		C0DEBEEF0000000000000103 /* WebKit.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = WebKit.framework; path = System/Library/Frameworks/WebKit.framework; sourceTree = SDKROOT; };
+		C0DEBEEF0000000000000104 /* Security.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = Security.framework; path = System/Library/Frameworks/Security.framework; sourceTree = SDKROOT; };
+		C0DEBEEF0000000000000105 /* CoreFoundation.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = CoreFoundation.framework; path = System/Library/Frameworks/CoreFoundation.framework; sourceTree = SDKROOT; };
+		C0DEBEEF0000000000000106 /* libresolv.tbd */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.text-based-dylib-definition; name = libresolv.tbd; path = usr/lib/libresolv.tbd; sourceTree = SDKROOT; };
+		C0DEBEEF0000000000000107 /* OPIc Flow.a */ = {isa = PBXFileReference; lastKnownFileType = archive.ar; name = "OPIc Flow.a"; path = "../../../bin/OPIc Flow.a"; sourceTree = SOURCE_ROOT; };
+/* End PBXFileReference section */
+
+/* Begin PBXGroup section */
+		C0DEBEEF0000000000000010 = {
+			isa = PBXGroup;
+			children = (
+				C0DEBEEF0000000000000020 /* Products */,
+				C0DEBEEF0000000000000045 /* Frameworks */,
+				C0DEBEEF0000000000000030 /* main */,
+			);
+			sourceTree = "<group>";
+		};
+		C0DEBEEF0000000000000020 /* Products */ = {
+			isa = PBXGroup;
+			children = (
+				C0DEBEEF0000000000000004 /* OPIc Flow.app */,
+			);
+			name = Products;
+			sourceTree = "<group>";
+		};
+		C0DEBEEF0000000000000030 /* main */ = {
+			isa = PBXGroup;
+			children = (
+				C0DEBEEF0000000000000002 /* main.m */,
+				C0DEBEEF0000000000000003 /* Info.plist */,
+			);
+			path = main;
+			sourceTree = SOURCE_ROOT;
+		};
+		C0DEBEEF0000000000000045 /* Frameworks */ = {
+			isa = PBXGroup;
+			children = (
+				C0DEBEEF0000000000000101 /* UIKit.framework */,
+				C0DEBEEF0000000000000102 /* Foundation.framework */,
+				C0DEBEEF0000000000000103 /* WebKit.framework */,
+				C0DEBEEF0000000000000104 /* Security.framework */,
+				C0DEBEEF0000000000000105 /* CoreFoundation.framework */,
+				C0DEBEEF0000000000000106 /* libresolv.tbd */,
+				C0DEBEEF0000000000000107 /* OPIc Flow.a */,
+			);
+			name = Frameworks;
+			sourceTree = "<group>";
+		};
+/* End PBXGroup section */
+
+/* Begin PBXNativeTarget section */
+		C0DEBEEF0000000000000040 /* OPIc Flow */ = {
+			isa = PBXNativeTarget;
+			buildConfigurationList = C0DEBEEF0000000000000070 /* Build configuration list for PBXNativeTarget "OPIc Flow" */;
+			buildPhases = (
+				C0DEBEEF0000000000000055 /* Prebuild: Wails Go Archive */,
+				C0DEBEEF0000000000000050 /* Sources */,
+				C0DEBEEF0000000000000056 /* Frameworks */,
+			);
+			buildRules = (
+			);
+			dependencies = (
+			);
+			name = "OPIc Flow";
+			productName = "OPIc Flow";
+			productReference = C0DEBEEF0000000000000004 /* OPIc Flow.app */;
+			productType = "com.apple.product-type.application";
+		};
+/* End PBXNativeTarget section */
+
+/* Begin PBXProject section */
+		C0DEBEEF0000000000000060 /* Project object */ = {
+			isa = PBXProject;
+			attributes = {
+				LastUpgradeCheck = 1500;
+				ORGANIZATIONNAME = "OPIc Flow";
+				TargetAttributes = {
+					C0DEBEEF0000000000000040 = {
+						CreatedOnToolsVersion = 15.0;
+					};
+				};
+			};
+			buildConfigurationList = C0DEBEEF0000000000000080 /* Build configuration list for PBXProject "main" */;
+			compatibilityVersion = "Xcode 15.0";
+			developmentRegion = en;
+			hasScannedForEncodings = 0;
+			knownRegions = (
+				en,
+			);
+			mainGroup = C0DEBEEF0000000000000010;
+			productRefGroup = C0DEBEEF0000000000000020 /* Products */;
+			projectDirPath = "";
+			projectRoot = "";
+			targets = (
+				C0DEBEEF0000000000000040 /* OPIc Flow */,
+			);
+		};
+/* End PBXProject section */
+
+/* Begin PBXFrameworksBuildPhase section */
+		C0DEBEEF0000000000000056 /* Frameworks */ = {
+			isa = PBXFrameworksBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+				C0DEBEEF00000000000000F7 /* OPIc Flow.a in Frameworks */,
+				C0DEBEEF00000000000000F1 /* UIKit.framework in Frameworks */,
+				C0DEBEEF00000000000000F2 /* Foundation.framework in Frameworks */,
+				C0DEBEEF00000000000000F3 /* WebKit.framework in Frameworks */,
+				C0DEBEEF00000000000000F4 /* Security.framework in Frameworks */,
+				C0DEBEEF00000000000000F5 /* CoreFoundation.framework in Frameworks */,
+				C0DEBEEF00000000000000F6 /* libresolv.tbd in Frameworks */,
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
+/* End PBXFrameworksBuildPhase section */
+
+/* Begin PBXShellScriptBuildPhase section */
+		C0DEBEEF0000000000000055 /* Prebuild: Wails Go Archive */ = {
+			isa = PBXShellScriptBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+			);
+			inputFileListPaths = (
+			);
+			inputPaths = (
+			);
+			name = "Prebuild: Wails Go Archive";
+			outputFileListPaths = (
+			);
+			outputPaths = (
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+			shellPath = /bin/sh;
+			shellScript = "set -e\nAPP_ROOT=\"${PROJECT_DIR}/../../..\"\nPLATFORM=${PLATFORM_NAME:-iphonesimulator}\nSDK_PATH=${SDKROOT:-$(xcrun --sdk ${PLATFORM} --show-sdk-path)}\nif [ ${PLATFORM} = iphonesimulator ]; then GO_TARGET=arm64-apple-ios15.0-simulator; MIN_FLAG=-mios-simulator-version-min=15.0; else GO_TARGET=arm64-apple-ios15.0; MIN_FLAG=-miphoneos-version-min=15.0; fi\nexport GOOS=ios\nexport GOARCH=arm64\nexport CGO_ENABLED=1\nexport CGO_CFLAGS=\"-isysroot ${SDK_PATH} -target ${GO_TARGET} ${MIN_FLAG}\"\nexport CGO_LDFLAGS=\"-isysroot ${SDK_PATH} -target ${GO_TARGET}\"\ncd \"${APP_ROOT}\"\n# Ensure overlay exists\nif [ ! -f build/ios/xcode/overlay.json ]; then\n  wails3 ios overlay:gen -out build/ios/xcode/overlay.json -config build/config.yml || true\nfi\n# Always rebuild the Go c-archive; Go's build cache keeps this fast\n# and avoids stale binaries when .go sources change.\necho \"Building Go c-archive...\"\ngo build -buildmode=c-archive -overlay build/ios/xcode/overlay.json -o \"bin/OPIc Flow.a\"\n";
+		};
+/* End PBXShellScriptBuildPhase section */
+
+/* Begin PBXSourcesBuildPhase section */
+		C0DEBEEF0000000000000050 /* Sources */ = {
+			isa = PBXSourcesBuildPhase;
+			buildActionMask = 2147483647;
+			files = (
+				C0DEBEEF0000000000000001 /* main.m in Sources */,
+			);
+			runOnlyForDeploymentPostprocessing = 0;
+		};
+/* End PBXSourcesBuildPhase section */
+
+/* Begin XCBuildConfiguration section */
+		C0DEBEEF0000000000000090 /* Debug */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				INFOPLIST_FILE = main/Info.plist;
+				IPHONEOS_DEPLOYMENT_TARGET = 15.0;
+				PRODUCT_BUNDLE_IDENTIFIER = "app.opicflow.desktop";
+				PRODUCT_NAME = "OPIc Flow";
+				CODE_SIGNING_ALLOWED = NO;
+				SDKROOT = iphoneos;
+			};
+			name = Debug;
+		};
+		C0DEBEEF00000000000000A0 /* Release */ = {
+			isa = XCBuildConfiguration;
+			buildSettings = {
+				INFOPLIST_FILE = main/Info.plist;
+				IPHONEOS_DEPLOYMENT_TARGET = 15.0;
+				PRODUCT_BUNDLE_IDENTIFIER = "app.opicflow.desktop";
+				PRODUCT_NAME = "OPIc Flow";
+				CODE_SIGNING_ALLOWED = NO;
+				SDKROOT = iphoneos;
+			};
+			name = Release;
+		};
+/* End XCBuildConfiguration section */
+
+/* Begin XCConfigurationList section */
+		C0DEBEEF0000000000000070 /* Build configuration list for PBXNativeTarget "OPIc Flow" */ = {
+			isa = XCConfigurationList;
+			buildConfigurations = (
+				C0DEBEEF0000000000000090 /* Debug */,
+				C0DEBEEF00000000000000A0 /* Release */,
+			);
+			defaultConfigurationIsVisible = 0;
+			defaultConfigurationName = Debug;
+		};
+		C0DEBEEF0000000000000080 /* Build configuration list for PBXProject "main" */ = {
+			isa = XCConfigurationList;
+			buildConfigurations = (
+				C0DEBEEF0000000000000090 /* Debug */,
+				C0DEBEEF00000000000000A0 /* Release */,
+			);
+			defaultConfigurationIsVisible = 0;
+			defaultConfigurationName = Debug;
+		};
+/* End XCConfigurationList section */
+	};
+	rootObject = C0DEBEEF0000000000000060 /* Project object */;
+}

build/ios/scripts/deps/install_deps.go

@@ -0,0 +1,319 @@
+// install_deps.go - iOS development dependency checker
+// This script checks for required iOS development tools.
+// It's designed to be portable across different shells by using Go instead of shell scripts.
+//
+// Usage:
+//   go run install_deps.go                      # Interactive mode
+//   TASK_FORCE_YES=true go run install_deps.go  # Auto-accept prompts
+//   CI=true go run install_deps.go              # CI mode (auto-accept)
+
+package main
+
+import (
+	"bufio"
+	"fmt"
+	"os"
+	"os/exec"
+	"strings"
+)
+
+type Dependency struct {
+	Name       string
+	CheckFunc  func() (bool, string) // Returns (success, details)
+	Required   bool
+	InstallCmd []string
+	InstallMsg string
+	SuccessMsg string
+	FailureMsg string
+}
+
+func main() {
+	fmt.Println("Checking iOS development dependencies...")
+	fmt.Println("=" + strings.Repeat("=", 50))
+	fmt.Println()
+
+	hasErrors := false
+	dependencies := []Dependency{
+		{
+			Name: "Xcode",
+			CheckFunc: func() (bool, string) {
+				// Check if xcodebuild exists
+				if !checkCommand([]string{"xcodebuild", "-version"}) {
+					return false, ""
+				}
+				// Get version info
+				out, err := exec.Command("xcodebuild", "-version").Output()
+				if err != nil {
+					return false, ""
+				}
+				lines := strings.Split(string(out), "\n")
+				if len(lines) > 0 {
+					return true, strings.TrimSpace(lines[0])
+				}
+				return true, ""
+			},
+			Required:   true,
+			InstallMsg: "Please install Xcode from the Mac App Store:\n   https://apps.apple.com/app/xcode/id497799835\n   Xcode is REQUIRED for iOS development (includes iOS SDKs, simulators, and frameworks)",
+			SuccessMsg: "✅ Xcode found",
+			FailureMsg: "❌ Xcode not found (REQUIRED)",
+		},
+		{
+			Name: "Xcode Developer Path",
+			CheckFunc: func() (bool, string) {
+				// Check if xcode-select points to a valid Xcode path
+				out, err := exec.Command("xcode-select", "-p").Output()
+				if err != nil {
+					return false, "xcode-select not configured"
+				}
+				path := strings.TrimSpace(string(out))
+
+				// Check if path exists and is in Xcode.app
+				if _, err := os.Stat(path); err != nil {
+					return false, "Invalid Xcode path"
+				}
+
+				// Verify it's pointing to Xcode.app (not just Command Line Tools)
+				if !strings.Contains(path, "Xcode.app") {
+					return false, fmt.Sprintf("Points to %s (should be Xcode.app)", path)
+				}
+
+				return true, path
+			},
+			Required:   true,
+			InstallCmd: []string{"sudo", "xcode-select", "-s", "/Applications/Xcode.app/Contents/Developer"},
+			InstallMsg: "Xcode developer path needs to be configured",
+			SuccessMsg: "✅ Xcode developer path configured",
+			FailureMsg: "❌ Xcode developer path not configured correctly",
+		},
+		{
+			Name: "iOS SDK",
+			CheckFunc: func() (bool, string) {
+				// Get the iOS Simulator SDK path
+				cmd := exec.Command("xcrun", "--sdk", "iphonesimulator", "--show-sdk-path")
+				output, err := cmd.Output()
+				if err != nil {
+					return false, "Cannot find iOS SDK"
+				}
+				sdkPath := strings.TrimSpace(string(output))
+
+				// Check if the SDK path exists
+				if _, err := os.Stat(sdkPath); err != nil {
+					return false, "iOS SDK path not found"
+				}
+
+				// Check for UIKit framework (essential for iOS development)
+				uikitPath := fmt.Sprintf("%s/System/Library/Frameworks/UIKit.framework", sdkPath)
+				if _, err := os.Stat(uikitPath); err != nil {
+					return false, "UIKit.framework not found"
+				}
+
+				// Get SDK version
+				versionCmd := exec.Command("xcrun", "--sdk", "iphonesimulator", "--show-sdk-version")
+				versionOut, _ := versionCmd.Output()
+				version := strings.TrimSpace(string(versionOut))
+
+				return true, fmt.Sprintf("iOS %s SDK", version)
+			},
+			Required:   true,
+			InstallMsg: "iOS SDK comes with Xcode. Please ensure Xcode is properly installed.",
+			SuccessMsg: "✅ iOS SDK found with UIKit framework",
+			FailureMsg: "❌ iOS SDK not found or incomplete",
+		},
+		{
+			Name: "iOS Simulator Runtime",
+			CheckFunc: func() (bool, string) {
+				if !checkCommand([]string{"xcrun", "simctl", "help"}) {
+					return false, ""
+				}
+				// Check if we can list runtimes
+				out, err := exec.Command("xcrun", "simctl", "list", "runtimes").Output()
+				if err != nil {
+					return false, "Cannot access simulator"
+				}
+				// Count iOS runtimes
+				lines := strings.Split(string(out), "\n")
+				count := 0
+				var versions []string
+				for _, line := range lines {
+					if strings.Contains(line, "iOS") && !strings.Contains(line, "unavailable") {
+						count++
+						// Extract version number
+						if parts := strings.Fields(line); len(parts) > 2 {
+							for _, part := range parts {
+								if strings.HasPrefix(part, "(") && strings.HasSuffix(part, ")") {
+									versions = append(versions, strings.Trim(part, "()"))
+									break
+								}
+							}
+						}
+					}
+				}
+				if count > 0 {
+					return true, fmt.Sprintf("%d runtime(s): %s", count, strings.Join(versions, ", "))
+				}
+				return false, "No iOS runtimes installed"
+			},
+			Required:   true,
+			InstallMsg: "iOS Simulator runtimes come with Xcode. You may need to download them:\n   Xcode → Settings → Platforms → iOS",
+			SuccessMsg: "✅ iOS Simulator runtime available",
+			FailureMsg: "❌ iOS Simulator runtime not available",
+		},
+	}
+
+	// Check each dependency
+	for _, dep := range dependencies {
+		success, details := dep.CheckFunc()
+		if success {
+			msg := dep.SuccessMsg
+			if details != "" {
+				msg = fmt.Sprintf("%s (%s)", dep.SuccessMsg, details)
+			}
+			fmt.Println(msg)
+		} else {
+			fmt.Println(dep.FailureMsg)
+			if details != "" {
+				fmt.Printf("   Details: %s\n", details)
+			}
+			if dep.Required {
+				hasErrors = true
+				if len(dep.InstallCmd) > 0 {
+					fmt.Println()
+					fmt.Println("   " + dep.InstallMsg)
+					fmt.Printf("   Fix command: %s\n", strings.Join(dep.InstallCmd, " "))
+					if promptUser("Do you want to run this command?") {
+						fmt.Println("Running command...")
+						cmd := exec.Command(dep.InstallCmd[0], dep.InstallCmd[1:]...)
+						cmd.Stdout = os.Stdout
+						cmd.Stderr = os.Stderr
+						cmd.Stdin = os.Stdin
+						if err := cmd.Run(); err != nil {
+							fmt.Printf("Command failed: %v\n", err)
+							os.Exit(1)
+						}
+						fmt.Println("✅ Command completed. Please run this check again.")
+					} else {
+						fmt.Printf("   Please run manually: %s\n", strings.Join(dep.InstallCmd, " "))
+					}
+				} else {
+					fmt.Println("   " + dep.InstallMsg)
+				}
+			}
+		}
+	}
+
+	// Check for iPhone simulators
+	fmt.Println()
+	fmt.Println("Checking for iPhone simulator devices...")
+	if !checkCommand([]string{"xcrun", "simctl", "list", "devices"}) {
+		fmt.Println("❌ Cannot check for iPhone simulators")
+		hasErrors = true
+	} else {
+		out, err := exec.Command("xcrun", "simctl", "list", "devices").Output()
+		if err != nil {
+			fmt.Println("❌ Failed to list simulator devices")
+			hasErrors = true
+		} else if !strings.Contains(string(out), "iPhone") {
+			fmt.Println("⚠️  No iPhone simulator devices found")
+			fmt.Println()
+
+			// Get the latest iOS runtime
+			runtimeOut, err := exec.Command("xcrun", "simctl", "list", "runtimes").Output()
+			if err != nil {
+				fmt.Println("   Failed to get iOS runtimes:", err)
+			} else {
+				lines := strings.Split(string(runtimeOut), "\n")
+				var latestRuntime string
+				for _, line := range lines {
+					if strings.Contains(line, "iOS") && !strings.Contains(line, "unavailable") {
+						// Extract runtime identifier
+						parts := strings.Fields(line)
+						if len(parts) > 0 {
+							latestRuntime = parts[len(parts)-1]
+						}
+					}
+				}
+
+				if latestRuntime == "" {
+					fmt.Println("   No iOS runtime found. Please install iOS simulators in Xcode:")
+					fmt.Println("   Xcode → Settings → Platforms → iOS")
+				} else {
+					fmt.Println("   Would you like to create an iPhone 15 Pro simulator?")
+					createCmd := []string{"xcrun", "simctl", "create", "iPhone 15 Pro", "iPhone 15 Pro", latestRuntime}
+					fmt.Printf("   Command: %s\n", strings.Join(createCmd, " "))
+					if promptUser("Create simulator?") {
+						cmd := exec.Command(createCmd[0], createCmd[1:]...)
+						cmd.Stdout = os.Stdout
+						cmd.Stderr = os.Stderr
+						if err := cmd.Run(); err != nil {
+							fmt.Printf("   Failed to create simulator: %v\n", err)
+						} else {
+							fmt.Println("   ✅ iPhone 15 Pro simulator created")
+						}
+					} else {
+						fmt.Println("   Skipping simulator creation")
+						fmt.Printf("   Create manually: %s\n", strings.Join(createCmd, " "))
+					}
+				}
+			}
+		} else {
+			// Count iPhone devices
+			count := 0
+			lines := strings.Split(string(out), "\n")
+			for _, line := range lines {
+				if strings.Contains(line, "iPhone") && !strings.Contains(line, "unavailable") {
+					count++
+				}
+			}
+			fmt.Printf("✅ %d iPhone simulator device(s) available\n", count)
+		}
+	}
+
+	// Final summary
+	fmt.Println()
+	fmt.Println("=" + strings.Repeat("=", 50))
+	if hasErrors {
+		fmt.Println("❌ Some required dependencies are missing or misconfigured.")
+		fmt.Println()
+		fmt.Println("Quick setup guide:")
+		fmt.Println("1. Install Xcode from Mac App Store (if not installed)")
+		fmt.Println("2. Open Xcode once and agree to the license")
+		fmt.Println("3. Install additional components when prompted")
+		fmt.Println("4. Run: sudo xcode-select -s /Applications/Xcode.app/Contents/Developer")
+		fmt.Println("5. Download iOS simulators: Xcode → Settings → Platforms → iOS")
+		fmt.Println("6. Run this check again")
+		os.Exit(1)
+	} else {
+		fmt.Println("✅ All required dependencies are installed!")
+		fmt.Println("   You're ready for iOS development with Wails!")
+	}
+}
+
+func checkCommand(args []string) bool {
+	if len(args) == 0 {
+		return false
+	}
+	cmd := exec.Command(args[0], args[1:]...)
+	cmd.Stdout = nil
+	cmd.Stderr = nil
+	err := cmd.Run()
+	return err == nil
+}
+
+func promptUser(question string) bool {
+	// Check if we're in a non-interactive environment
+	if os.Getenv("CI") != "" || os.Getenv("TASK_FORCE_YES") == "true" {
+		fmt.Printf("%s [y/N]: y (auto-accepted)\n", question)
+		return true
+	}
+
+	reader := bufio.NewReader(os.Stdin)
+	fmt.Printf("%s [y/N]: ", question)
+
+	response, err := reader.ReadString('\n')
+	if err != nil {
+		return false
+	}
+
+	response = strings.ToLower(strings.TrimSpace(response))
+	return response == "y" || response == "yes"
+}

build/linux/Taskfile.yml

@@ -0,0 +1,220 @@
+version: '3'
+
+includes:
+  common: ../Taskfile.yml
+
+vars:
+  # Signing configuration - edit these values for your project
+  # PGP_KEY: "path/to/signing-key.asc"
+  # SIGN_ROLE: "builder"  # Options: origin, maint, archive, builder
+  #
+  # Password is stored securely in system keychain. Run: wails3 setup signing
+
+  # Docker image for cross-compilation (used when building on non-Linux or no CC available)
+  CROSS_IMAGE: wails-cross
+
+tasks:
+  build:
+    summary: Builds the application for Linux
+    cmds:
+      # Linux requires CGO - use Docker when:
+      # 1. Cross-compiling from non-Linux, OR
+      # 2. No C compiler is available, OR
+      # 3. Target architecture differs from host architecture (cross-arch compilation)
+      - task: '{{if and (eq OS "linux") (eq .HAS_CC "true") (eq .TARGET_ARCH ARCH)}}build:native{{else}}build:docker{{end}}'
+        vars:
+          ARCH: '{{.ARCH}}'
+          DEV: '{{.DEV}}'
+          OUTPUT: '{{.OUTPUT}}'
+          EXTRA_TAGS: '{{.EXTRA_TAGS}}'
+          OBFUSCATED: '{{.OBFUSCATED}}'
+          GARBLE_ARGS: '{{.GARBLE_ARGS}}'
+    vars:
+      DEFAULT_OUTPUT: '{{.BIN_DIR}}/{{.APP_NAME}}'
+      OUTPUT: '{{ .OUTPUT | default .DEFAULT_OUTPUT }}'
+      # Determine target architecture (defaults to host ARCH if not specified)
+      TARGET_ARCH: '{{.ARCH | default ARCH}}'
+      # Check if a C compiler is available (gcc or clang) — cross-platform via wails3 tool
+      HAS_CC:
+        sh: 'wails3 tool has "gcc|clang"'
+
+  build:native:
+    summary: Builds the application natively on Linux
+    internal: true
+    deps:
+      - task: common:go:mod:tidy
+      - task: common:build:frontend
+        vars:
+          BUILD_FLAGS:
+            ref: .BUILD_FLAGS
+          OBFUSCATED:
+            ref: .OBFUSCATED
+          DEV:
+            ref: .DEV
+      - task: common:generate:icons
+      - task: generate:dotdesktop
+    preconditions:
+      - sh: '{{if eq .OBFUSCATED "true"}}command -v garble >/dev/null 2>&1{{else}}true{{end}}'
+        msg: "garble is required for obfuscated builds. Install it with: go install mvdan.cc/garble@v0.16.0 (requires Go 1.24+). See https://github.com/burrowers/garble/releases for version/toolchain compatibility."
+    cmds:
+      - '{{if eq .OBFUSCATED "true"}}garble {{.GARBLE_ARGS}} build{{else}}go build{{end}} {{.BUILD_FLAGS}} -o {{.OUTPUT}}'
+    vars:
+      BUILD_FLAGS: '{{if eq .DEV "true"}}{{if or .EXTRA_TAGS (eq .OBFUSCATED "true")}}-tags {{if eq .OBFUSCATED "true"}}wails_obfuscated{{if .EXTRA_TAGS}},{{end}}{{end}}{{.EXTRA_TAGS}} {{end}}-buildvcs=false -gcflags=all="-l"{{else}}-tags production{{if eq .OBFUSCATED "true"}},wails_obfuscated{{end}}{{if .EXTRA_TAGS}},{{.EXTRA_TAGS}}{{end}} -trimpath -buildvcs=false -ldflags="-w -s"{{end}}'
+      DEFAULT_OUTPUT: '{{.BIN_DIR}}/{{.APP_NAME}}'
+      OUTPUT: '{{ .OUTPUT | default .DEFAULT_OUTPUT }}'
+    env:
+      GOOS: linux
+      CGO_ENABLED: 1
+      GOARCH: '{{.ARCH | default ARCH}}'
+
+  build:docker:
+    summary: Builds for Linux using Docker (for non-Linux hosts or when no C compiler available)
+    internal: true
+    deps:
+      - task: common:build:frontend
+        vars:
+          OBFUSCATED:
+            ref: .OBFUSCATED
+      - task: common:generate:icons
+      - task: generate:dotdesktop
+    preconditions:
+      - sh: docker info > /dev/null 2>&1
+        msg: "Docker is required for cross-compilation to Linux. Please install Docker."
+      - sh: docker image inspect {{.CROSS_IMAGE}} > /dev/null 2>&1
+        msg: |
+          Docker image '{{.CROSS_IMAGE}}' not found.
+          Build it first: wails3 task setup:docker
+    cmds:
+      - docker run --rm -v "{{.ROOT_DIR}}:/app" {{.DOCKER_MOUNTS}} -e APP_NAME="{{.APP_NAME}}" {{if .EXTRA_TAGS}}-e EXTRA_TAGS="{{.EXTRA_TAGS}}"{{end}} {{if eq .OBFUSCATED "true"}}-e OBFUSCATED=true{{end}} {{if .GARBLE_ARGS}}-e GARBLE_ARGS="{{.GARBLE_ARGS}}"{{end}} "{{.CROSS_IMAGE}}" linux {{.DOCKER_ARCH}}
+      - cmd: docker run --rm -v "{{.ROOT_DIR}}:/app" alpine chown -R $(id -u):$(id -g) /app/bin
+        platforms: [linux, darwin]
+      - mkdir -p {{.BIN_DIR}}
+      - mv "bin/{{.APP_NAME}}-linux-{{.DOCKER_ARCH}}" "{{.OUTPUT}}"
+    vars:
+      DOCKER_ARCH: '{{.ARCH | default "amd64"}}'
+      DEFAULT_OUTPUT: '{{.BIN_DIR}}/{{.APP_NAME}}'
+      OUTPUT: '{{ .OUTPUT | default .DEFAULT_OUTPUT }}'
+      # Generate Docker volume mounts: Go module cache + go.mod replace directives
+      # Uses wails3 tool docker-mounts for cross-platform compatibility (Windows/Linux/macOS)
+      DOCKER_MOUNTS:
+        sh: 'wails3 tool docker-mounts'
+
+  package:
+    summary: Packages the application for Linux
+    deps:
+      - task: build
+    cmds:
+      - task: create:appimage
+      - task: create:deb
+      - task: create:rpm
+      - task: create:aur
+
+  create:appimage:
+    summary: Creates an AppImage
+    dir: build/linux/appimage
+    deps:
+      - task: build
+      - task: generate:dotdesktop
+    cmds:
+      - cp "{{.APP_BINARY}}" "{{.APP_NAME}}"
+      - cp ../../appicon.png "{{.APP_NAME}}.png"
+      - wails3 generate appimage -binary "{{.APP_NAME}}" -icon {{.ICON}} -desktopfile {{.DESKTOP_FILE}} -outputdir {{.OUTPUT_DIR}} -builddir {{.ROOT_DIR}}/build/linux/appimage/build
+    vars:
+      APP_NAME: '{{.APP_NAME}}'
+      APP_BINARY: '../../../bin/{{.APP_NAME}}'
+      ICON: '{{.APP_NAME}}.png'
+      DESKTOP_FILE: '../{{.APP_NAME}}.desktop'
+      OUTPUT_DIR: '../../../bin'
+
+  create:deb:
+    summary: Creates a deb package
+    deps:
+      - task: build
+    cmds:
+      - task: generate:dotdesktop
+      - task: generate:deb
+
+  create:rpm:
+    summary: Creates a rpm package
+    deps:
+      - task: build
+    cmds:
+      - task: generate:dotdesktop
+      - task: generate:rpm
+
+  create:aur:
+    summary: Creates a arch linux packager package
+    deps:
+      - task: build
+    cmds:
+      - task: generate:dotdesktop
+      - task: generate:aur
+
+  generate:deb:
+    summary: Creates a deb package
+    cmds:
+      - wails3 tool package -name "{{.APP_NAME}}" -format deb -config ./build/linux/nfpm/nfpm.yaml -out {{.ROOT_DIR}}/bin
+
+  generate:rpm:
+    summary: Creates a rpm package
+    cmds:
+      - wails3 tool package -name "{{.APP_NAME}}" -format rpm -config ./build/linux/nfpm/nfpm.yaml -out {{.ROOT_DIR}}/bin
+
+  generate:aur:
+    summary: Creates a arch linux packager package
+    cmds:
+      - wails3 tool package -name "{{.APP_NAME}}" -format archlinux -config ./build/linux/nfpm/nfpm.yaml -out {{.ROOT_DIR}}/bin
+
+  generate:dotdesktop:
+    summary: Generates a `.desktop` file
+    dir: build
+    cmds:
+      - mkdir -p {{.ROOT_DIR}}/build/linux/appimage
+      - wails3 generate .desktop -name "{{.APP_NAME}}" -exec "{{.EXEC}}" -icon "{{.ICON}}" -outputfile "{{.ROOT_DIR}}/build/linux/{{.APP_NAME}}.desktop" -categories "{{.CATEGORIES}}"
+    vars:
+      APP_NAME: '{{.APP_NAME}}'
+      EXEC: '{{.APP_NAME}}'
+      ICON: '{{.APP_NAME}}'
+      CATEGORIES: 'Development;'
+      OUTPUTFILE: '{{.ROOT_DIR}}/build/linux/{{.APP_NAME}}.desktop'
+
+  run:
+    cmds:
+      - '{{.BIN_DIR}}/{{.APP_NAME}}'
+
+  sign:deb:
+    summary: Signs the DEB package
+    desc: |
+      Signs the .deb package with a PGP key.
+      Set PGP_KEY in the vars section to override the key configured globally via
+      `wails3 setup` (~/.config/wails/defaults.yaml).
+      Password is retrieved from system keychain (run: wails3 setup signing)
+    deps:
+      - task: create:deb
+    cmds:
+      # PGP_KEY is optional: if unset, `wails3 tool sign` falls back to the key
+      # configured globally via `wails3 setup`.
+      - wails3 tool sign --input "{{.BIN_DIR}}/{{.APP_NAME}}*.deb" {{if .PGP_KEY}}--pgp-key "{{.PGP_KEY}}"{{end}} {{if .SIGN_ROLE}}--role "{{.SIGN_ROLE}}"{{end}}
+
+  sign:rpm:
+    summary: Signs the RPM package
+    desc: |
+      Signs the .rpm package with a PGP key.
+      Set PGP_KEY in the vars section to override the key configured globally via
+      `wails3 setup` (~/.config/wails/defaults.yaml).
+      Password is retrieved from system keychain (run: wails3 setup signing)
+    deps:
+      - task: create:rpm
+    cmds:
+      - wails3 tool sign --input "{{.BIN_DIR}}/{{.APP_NAME}}*.rpm" {{if .PGP_KEY}}--pgp-key "{{.PGP_KEY}}"{{end}}
+
+  sign:packages:
+    summary: Signs all Linux packages (DEB and RPM)
+    desc: |
+      Signs both .deb and .rpm packages with a PGP key.
+      Set PGP_KEY in the vars section to override the key configured globally via
+      `wails3 setup` (~/.config/wails/defaults.yaml).
+      Password is retrieved from system keychain (run: wails3 setup signing)
+    cmds:
+      - task: sign:deb
+      - task: sign:rpm

build/linux/appimage/build.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Copyright (c) 2018-Present Lea Anthony
+# SPDX-License-Identifier: MIT
+
+# Fail script on any error
+set -euxo pipefail
+
+# Define variables
+APP_DIR="${APP_NAME}.AppDir"
+
+# Create AppDir structure
+mkdir -p "${APP_DIR}/usr/bin"
+cp -r "${APP_BINARY}" "${APP_DIR}/usr/bin/"
+cp "${ICON_PATH}" "${APP_DIR}/"
+cp "${DESKTOP_FILE}" "${APP_DIR}/"
+
+if [[ $(uname -m) == *x86_64* ]]; then
+    # Download linuxdeploy and make it executable
+    wget -q -4 -N https://github.com/linuxdeploy/linuxdeploy/releases/download/continuous/linuxdeploy-x86_64.AppImage
+    chmod +x linuxdeploy-x86_64.AppImage
+
+    # Run linuxdeploy to bundle the application
+    ./linuxdeploy-x86_64.AppImage --appdir "${APP_DIR}" --output appimage
+else
+    # Download linuxdeploy and make it executable (arm64)
+    wget -q -4 -N https://github.com/linuxdeploy/linuxdeploy/releases/download/continuous/linuxdeploy-aarch64.AppImage
+    chmod +x linuxdeploy-aarch64.AppImage
+
+    # Run linuxdeploy to bundle the application (arm64)
+    ./linuxdeploy-aarch64.AppImage --appdir "${APP_DIR}" --output appimage
+fi
+
+# Rename the generated AppImage
+mv "${APP_NAME}*.AppImage" "${APP_NAME}.AppImage"
+

build/linux/desktop

@@ -0,0 +1,13 @@
+[Desktop Entry]
+Version=1.0
+Name=OPIc Flow
+Comment=AI voice practice and feedback for the OPIc speaking test
+# The Exec line includes %u to pass the URL to the application
+Exec=/usr/local/bin/opic-flow %u
+Terminal=false
+Type=Application
+Icon=opic-flow
+Categories=Utility;
+StartupWMClass=opic-flow
+
+ 

build/linux/nfpm/nfpm.yaml

@@ -0,0 +1,80 @@
+# Feel free to remove those if you don't want/need to use them.
+# Make sure to check the documentation at https://nfpm.goreleaser.com
+#
+# The lines below are called `modelines`. See `:help modeline`
+
+name: "opic-flow"
+arch: ${GOARCH}
+platform: "linux"
+version: "0.1.0"
+section: "default"
+priority: "extra"
+maintainer: ${GIT_COMMITTER_NAME} <${GIT_COMMITTER_EMAIL}>
+description: "AI voice practice and feedback for the OPIc speaking test"
+vendor: "OPIc Flow"
+homepage: "https://wails.io"
+license: "MIT"
+release: "1"
+
+contents:
+  - src: "./bin/opic-flow"
+    dst: "/usr/local/bin/opic-flow"
+  - src: "./build/appicon.png"
+    dst: "/usr/share/icons/hicolor/128x128/apps/opic-flow.png"
+  - src: "./build/linux/opic-flow.desktop"
+    dst: "/usr/share/applications/opic-flow.desktop"
+
+# Default dependencies for the GTK4 + WebKitGTK 6.0 stack (Ubuntu 24.04+ / Debian 13+)
+depends:
+  - libgtk-4-1
+  - libwebkitgtk-6.0-4
+
+# Distribution-specific overrides for different package formats
+overrides:
+  # RPM packages for Fedora / RHEL / AlmaLinux / Rocky Linux
+  rpm:
+    depends:
+      - gtk4
+      - webkitgtk6.0
+
+  # Arch Linux packages
+  archlinux:
+    depends:
+      - gtk4
+      - webkitgtk-6.0
+
+# scripts section to ensure desktop database is updated after install
+scripts:
+  postinstall: "./build/linux/nfpm/scripts/postinstall.sh"
+  # You can also add preremove, postremove if needed
+  # preremove: "./build/linux/nfpm/scripts/preremove.sh"
+  # postremove: "./build/linux/nfpm/scripts/postremove.sh"
+
+# If you build your app with -tags gtk3 (legacy WebKit2GTK 4.1 stack — supported through v3.0.x, removed in v3.1),
+# replace the depends/overrides above with these:
+#
+# depends:
+#   - libgtk-3-0
+#   - libwebkit2gtk-4.1-0
+# overrides:
+#   rpm:
+#     depends:
+#       - gtk3
+#       - webkit2gtk4.1
+#   archlinux:
+#     depends:
+#       - gtk3
+#       - webkit2gtk-4.1
+#
+# replaces:
+#   - foobar
+# provides:
+#   - bar
+# recommends:
+#   - whatever
+# suggests:
+#   - something-else
+# conflicts:
+#   - not-foo
+#   - not-bar
+# changelog: "changelog.yaml"

build/linux/nfpm/scripts/postinstall.sh

@@ -0,0 +1,21 @@
+#!/bin/sh
+
+# Update desktop database for .desktop file changes
+# This makes the application appear in application menus and registers its capabilities.
+if command -v update-desktop-database >/dev/null 2>&1; then
+  echo "Updating desktop database..."
+  update-desktop-database -q /usr/share/applications
+else
+  echo "Warning: update-desktop-database command not found. Desktop file may not be immediately recognized." >&2
+fi
+
+# Update MIME database for custom URL schemes (x-scheme-handler)
+# This ensures the system knows how to handle your custom protocols.
+if command -v update-mime-database >/dev/null 2>&1; then
+  echo "Updating MIME database..."
+  update-mime-database -n /usr/share/mime
+else
+  echo "Warning: update-mime-database command not found. Custom URL schemes may not be immediately recognized." >&2
+fi
+
+exit 0

build/linux/nfpm/scripts/postremove.sh

@@ -0,0 +1 @@
+#!/bin/bash

build/linux/nfpm/scripts/preinstall.sh

@@ -0,0 +1 @@
+#!/bin/bash

build/linux/nfpm/scripts/preremove.sh

@@ -0,0 +1 @@
+#!/bin/bash

build/windows/Taskfile.yml

@@ -0,0 +1,195 @@
+version: '3'
+
+includes:
+  common: ../Taskfile.yml
+
+vars:
+  # Signing configuration - edit these values for your project
+  # SIGN_CERTIFICATE: "path/to/certificate.pfx"
+  # SIGN_THUMBPRINT: "certificate-thumbprint"  # Alternative to SIGN_CERTIFICATE
+  # TIMESTAMP_SERVER: "http://timestamp.digicert.com"
+  #
+  # Password is stored securely in system keychain. Run: wails3 setup signing
+
+  # Docker image for cross-compilation with CGO (used when CGO_ENABLED=1 on non-Windows)
+  CROSS_IMAGE: wails-cross
+
+tasks:
+  build:
+    summary: Builds the application for Windows
+    cmds:
+      # Auto-detect CGO: if CGO_ENABLED=1, use Docker; otherwise use native Go cross-compile
+      - task: '{{if and (ne OS "windows") (eq .CGO_ENABLED "1")}}build:docker{{else}}build:native{{end}}'
+        vars:
+          ARCH: '{{.ARCH}}'
+          DEV: '{{.DEV}}'
+          EXTRA_TAGS: '{{.EXTRA_TAGS}}'
+          OBFUSCATED: '{{.OBFUSCATED}}'
+          GARBLE_ARGS: '{{.GARBLE_ARGS}}'
+    vars:
+      # Default to CGO_ENABLED=0 if not explicitly set
+      CGO_ENABLED: '{{.CGO_ENABLED | default "0"}}'
+
+  build:native:
+    summary: Builds the application using native Go cross-compilation
+    internal: true
+    deps:
+      - task: common:go:mod:tidy
+      - task: common:build:frontend
+        vars:
+          BUILD_FLAGS:
+            ref: .BUILD_FLAGS
+          OBFUSCATED:
+            ref: .OBFUSCATED
+          DEV:
+            ref: .DEV
+      - task: common:generate:icons
+    preconditions:
+      - sh: '{{if eq .OBFUSCATED "true"}}command -v garble >/dev/null 2>&1{{else}}true{{end}}'
+        msg: "garble is required for obfuscated builds. Install it with: go install mvdan.cc/garble@v0.16.0 (requires Go 1.24+). See https://github.com/burrowers/garble/releases for version/toolchain compatibility."
+    cmds:
+      - task: generate:syso
+        vars:
+          ARCH: '{{.ARCH}}'
+      - '{{if eq .OBFUSCATED "true"}}garble {{.GARBLE_ARGS}} build{{else}}go build{{end}} {{.BUILD_FLAGS}} -o "{{.BIN_DIR}}/{{.APP_NAME}}.exe"'
+      - cmd: powershell Remove-item *.syso
+        platforms: [windows]
+      - cmd: rm -f *.syso
+        platforms: [linux, darwin]
+    vars:
+      BUILD_FLAGS: '{{if eq .DEV "true"}}{{if or .EXTRA_TAGS (eq .OBFUSCATED "true")}}-tags {{if eq .OBFUSCATED "true"}}wails_obfuscated{{if .EXTRA_TAGS}},{{end}}{{end}}{{.EXTRA_TAGS}} {{end}}-buildvcs=false -gcflags=all="-l"{{else}}-tags production{{if eq .OBFUSCATED "true"}},wails_obfuscated{{end}}{{if .EXTRA_TAGS}},{{.EXTRA_TAGS}}{{end}} -trimpath -buildvcs=false -ldflags="-w -s -H windowsgui"{{end}}'
+    env:
+      GOOS: windows
+      CGO_ENABLED: '{{.CGO_ENABLED | default "0"}}'
+      GOARCH: '{{.ARCH | default ARCH}}'
+
+  build:docker:
+    summary: Cross-compiles for Windows using Docker with Zig (for CGO builds on non-Windows)
+    internal: true
+    deps:
+      - task: common:build:frontend
+        vars:
+          OBFUSCATED:
+            ref: .OBFUSCATED
+      - task: common:generate:icons
+    preconditions:
+      - sh: docker info > /dev/null 2>&1
+        msg: "Docker is required for CGO cross-compilation. Please install Docker."
+      - sh: docker image inspect {{.CROSS_IMAGE}} > /dev/null 2>&1
+        msg: |
+          Docker image '{{.CROSS_IMAGE}}' not found.
+          Build it first: wails3 task setup:docker
+    cmds:
+      - task: generate:syso
+        vars:
+          ARCH: '{{.ARCH}}'
+      - docker run --rm -v "{{.ROOT_DIR}}:/app" {{.DOCKER_MOUNTS}} -e APP_NAME="{{.APP_NAME}}" {{if .EXTRA_TAGS}}-e EXTRA_TAGS="{{.EXTRA_TAGS}}"{{end}} {{if eq .OBFUSCATED "true"}}-e OBFUSCATED=true{{end}} {{if .GARBLE_ARGS}}-e GARBLE_ARGS="{{.GARBLE_ARGS}}"{{end}} {{.CROSS_IMAGE}} windows {{.DOCKER_ARCH}}
+      - cmd: docker run --rm -v "{{.ROOT_DIR}}:/app" alpine chown -R $(id -u):$(id -g) /app/bin
+        platforms: [linux, darwin]
+      - rm -f *.syso
+    vars:
+      DOCKER_ARCH: '{{.ARCH | default "amd64"}}'
+      # Generate Docker volume mounts: Go module cache + go.mod replace directives
+      # Uses wails3 tool docker-mounts for cross-platform compatibility (Windows/Linux/macOS)
+      DOCKER_MOUNTS:
+        sh: 'wails3 tool docker-mounts'
+
+  package:
+    summary: Packages the application
+    cmds:
+      - task: '{{if eq (.FORMAT | default "nsis") "msix"}}create:msix:package{{else}}create:nsis:installer{{end}}'
+        vars:
+          INSTALL_SCOPE: '{{.INSTALL_SCOPE | default "machine"}}'
+    vars:
+      FORMAT: '{{.FORMAT | default "nsis"}}'
+      INSTALL_SCOPE: '{{.INSTALL_SCOPE | default "machine"}}'
+
+  generate:syso:
+    summary: Generates Windows `.syso` file
+    dir: build
+    cmds:
+      - wails3 generate syso -arch {{.ARCH}} -icon windows/icon.ico -manifest windows/wails.exe.manifest -info windows/info.json -out ../wails_windows_{{.ARCH}}.syso
+    vars:
+      ARCH: '{{.ARCH | default ARCH}}'
+
+  create:nsis:installer:
+    summary: Creates an NSIS installer
+    dir: build/windows/nsis
+    deps:
+      - task: build
+    preconditions:
+      - sh: '[ "{{.INSTALL_SCOPE}}" = "user" ] || [ "{{.INSTALL_SCOPE}}" = "machine" ]'
+        msg: "INSTALL_SCOPE must be 'user' or 'machine', got '{{.INSTALL_SCOPE}}'"
+    cmds:
+      # Create the Microsoft WebView2 bootstrapper if it doesn't exist
+      - wails3 generate webview2bootstrapper -dir "{{.ROOT_DIR}}/build/windows/nsis"
+      - |
+        {{if eq OS "windows"}}
+        makensis {{if eq .INSTALL_SCOPE "user"}}-DWAILS_INSTALL_SCOPE=user -DREQUEST_EXECUTION_LEVEL=user {{end}}-DARG_WAILS_{{.ARG_FLAG}}_BINARY="{{.ROOT_DIR}}\{{.BIN_DIR}}\{{.APP_NAME}}.exe" project.nsi
+        {{else}}
+        makensis {{if eq .INSTALL_SCOPE "user"}}-DWAILS_INSTALL_SCOPE=user -DREQUEST_EXECUTION_LEVEL=user {{end}}-DARG_WAILS_{{.ARG_FLAG}}_BINARY="{{.ROOT_DIR}}/{{.BIN_DIR}}/{{.APP_NAME}}.exe" project.nsi
+        {{end}}
+    vars:
+      ARCH: '{{.ARCH | default ARCH}}'
+      ARG_FLAG: '{{if eq .ARCH "amd64"}}AMD64{{else}}ARM64{{end}}'
+      INSTALL_SCOPE: '{{.INSTALL_SCOPE | default "machine"}}'
+
+  create:msix:package:
+    summary: Creates an MSIX package
+    deps:
+      - task: build
+    cmds:
+      - |-
+        wails3 tool msix \
+          --config "{{.ROOT_DIR}}/wails.json" \
+          --name "{{.APP_NAME}}" \
+          --executable "{{.ROOT_DIR}}/{{.BIN_DIR}}/{{.APP_NAME}}.exe" \
+          --arch "{{.ARCH}}" \
+          --out "{{.ROOT_DIR}}/{{.BIN_DIR}}/{{.APP_NAME}}-{{.ARCH}}.msix" \
+          {{if .CERT_PATH}}--cert "{{.CERT_PATH}}"{{end}} \
+          {{if .PUBLISHER}}--publisher "{{.PUBLISHER}}"{{end}} \
+          {{if .USE_MSIX_TOOL}}--use-msix-tool{{else}}--use-makeappx{{end}}
+    vars:
+      ARCH: '{{.ARCH | default ARCH}}'
+      CERT_PATH: '{{.CERT_PATH | default ""}}'
+      PUBLISHER: '{{.PUBLISHER | default ""}}'
+      USE_MSIX_TOOL: '{{.USE_MSIX_TOOL | default "false"}}'
+
+  install:msix:tools:
+    summary: Installs tools required for MSIX packaging
+    cmds:
+      - wails3 tool msix-install-tools
+
+  run:
+    cmds:
+      - '{{.BIN_DIR}}/{{.APP_NAME}}.exe'
+
+  sign:
+    summary: Signs the Windows executable
+    desc: |
+      Signs the .exe with an Authenticode certificate.
+      Set SIGN_CERTIFICATE or SIGN_THUMBPRINT to override the certificate
+      configured globally via `wails3 setup` (~/.config/wails/defaults.yaml).
+      Password is retrieved from system keychain (run: wails3 setup signing)
+    deps:
+      - task: build
+    cmds:
+      # Certificate vars are optional: if unset, `wails3 tool sign` falls back to
+      # the certificate configured globally via `wails3 setup`.
+      - wails3 tool sign --input "{{.BIN_DIR}}/{{.APP_NAME}}.exe" {{if .SIGN_CERTIFICATE}}--certificate "{{.SIGN_CERTIFICATE}}"{{end}} {{if .SIGN_THUMBPRINT}}--thumbprint "{{.SIGN_THUMBPRINT}}"{{end}} {{if .TIMESTAMP_SERVER}}--timestamp "{{.TIMESTAMP_SERVER}}"{{end}}
+
+  sign:installer:
+    summary: Signs the NSIS installer
+    desc: |
+      Creates and signs the NSIS installer.
+      Set SIGN_CERTIFICATE or SIGN_THUMBPRINT to override the certificate
+      configured globally via `wails3 setup` (~/.config/wails/defaults.yaml).
+      Password is retrieved from system keychain (run: wails3 setup signing)
+    deps:
+      - task: create:nsis:installer
+        vars:
+          INSTALL_SCOPE: '{{.INSTALL_SCOPE | default "machine"}}'
+    vars:
+      INSTALL_SCOPE: '{{.INSTALL_SCOPE | default "machine"}}'
+    cmds:
+      - wails3 tool sign --input "build/windows/nsis/{{.APP_NAME}}-installer.exe" {{if .SIGN_CERTIFICATE}}--certificate "{{.SIGN_CERTIFICATE}}"{{end}} {{if .SIGN_THUMBPRINT}}--thumbprint "{{.SIGN_THUMBPRINT}}"{{end}} {{if .TIMESTAMP_SERVER}}--timestamp "{{.TIMESTAMP_SERVER}}"{{end}}

build/windows/info.json

@@ -0,0 +1,15 @@
+{
+	"fixed": {
+		"file_version": "0.1.0"
+	},
+	"info": {
+		"0000": {
+			"ProductVersion": "0.1.0",
+			"CompanyName": "OPIc Flow",
+			"FileDescription": "AI voice practice and feedback for the OPIc speaking test",
+			"LegalCopyright": "(c) 2026, OPIc Flow",
+			"ProductName": "OPIc Flow",
+			"Comments": "Wails 3 + Vue TypeScript desktop application"
+		}
+	}
+}

build/windows/msix/app_manifest.xml

@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Package
+  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
+  xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
+  xmlns:uap3="http://schemas.microsoft.com/appx/manifest/uap/windows10/3"
+  xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"
+  xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10"
+  IgnorableNamespaces="uap3">
+  
+  <Identity 
+    Name="com.example.scaffold"
+    Publisher="CN=My Company"
+    Version="0.1.0.0" 
+    ProcessorArchitecture="x64" />
+  
+  <Properties>
+    <DisplayName>My Product</DisplayName>
+    <PublisherDisplayName>My Company</PublisherDisplayName>
+    <Description>A scaffold application</Description>
+    <Logo>Assets\StoreLogo.png</Logo>
+  </Properties>
+  
+  <Dependencies>
+    <TargetDeviceFamily Name="Windows.Desktop" MinVersion="10.0.17763.0" MaxVersionTested="10.0.19041.0" />
+  </Dependencies>
+  
+  <Resources>
+    <Resource Language="en-us" />
+  </Resources>
+  
+  <Applications>
+    <Application Id="com.example.scaffold" Executable="scaffold.exe" EntryPoint="Windows.FullTrustApplication">
+      <uap:VisualElements
+        DisplayName="My Product"
+        Description="A scaffold application"
+        BackgroundColor="transparent"
+        Square150x150Logo="Assets\Square150x150Logo.png"
+        Square44x44Logo="Assets\Square44x44Logo.png">
+        <uap:DefaultTile Wide310x150Logo="Assets\Wide310x150Logo.png" />
+        <uap:SplashScreen Image="Assets\SplashScreen.png" />
+      </uap:VisualElements>
+      
+      <Extensions>
+        <desktop:Extension Category="windows.fullTrustProcess" Executable="scaffold.exe" />
+        
+        
+      </Extensions>
+    </Application>
+  </Applications>
+  
+  <Capabilities>
+    <rescap:Capability Name="runFullTrust" />
+    
+  </Capabilities>
+</Package>

build/windows/msix/template.xml

@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="utf-8"?>
+<MsixPackagingToolTemplate
+    xmlns="http://schemas.microsoft.com/msix/packaging/msixpackagingtool/template/2022">
+    <Settings
+        AllowTelemetry="false"
+        ApplyACLsToPackageFiles="true"
+        GenerateCommandLineFile="true"
+        AllowPromptForPassword="false">
+    </Settings>
+    <Installer
+        Path="scaffold.exe"
+        Arguments=""
+        InstallLocation="C:\Program Files\My Company\My Product">
+    </Installer>
+    <PackageInformation
+        PackageName="My Product"
+        PackageDisplayName="My Product"
+        PublisherName="CN=My Company"
+        PublisherDisplayName="My Company"
+        Version="0.1.0.0"
+        PackageDescription="A scaffold application">
+        <Capabilities>
+            <Capability Name="runFullTrust" />
+            
+        </Capabilities>
+        <Applications>
+            <Application
+                Id="com.example.scaffold"
+                Description="A scaffold application"
+                DisplayName="My Product"
+                ExecutableName="scaffold.exe"
+                EntryPoint="Windows.FullTrustApplication">
+                
+            </Application>
+        </Applications>
+        <Resources>
+            <Resource Language="en-us" />
+        </Resources>
+        <Dependencies>
+            <TargetDeviceFamily Name="Windows.Desktop" MinVersion="10.0.17763.0" MaxVersionTested="10.0.19041.0" />
+        </Dependencies>
+        <Properties>
+            <Framework>false</Framework>
+            <DisplayName>My Product</DisplayName>
+            <PublisherDisplayName>My Company</PublisherDisplayName>
+            <Description>A scaffold application</Description>
+            <Logo>Assets\AppIcon.png</Logo>
+        </Properties>
+    </PackageInformation>
+    <SaveLocation PackagePath="scaffold.msix" />
+    <PackageIntegrity>
+        <CertificatePath></CertificatePath>
+    </PackageIntegrity>
+</MsixPackagingToolTemplate>

build/windows/nsis/project.nsi

@@ -0,0 +1,119 @@
+Unicode true
+
+####
+## Please note: Template replacements don't work in this file. They are provided with default defines like
+## mentioned underneath.
+## If the keyword is not defined, "wails_tools.nsh" will populate them.
+## If they are defined here, "wails_tools.nsh" will not touch them. This allows you to use this project.nsi manually
+## from outside of Wails for debugging and development of the installer.
+## 
+## For development first make a wails nsis build to populate the "wails_tools.nsh":
+## > wails build --target windows/amd64 --nsis
+## Then you can call makensis on this file with specifying the path to your binary:
+## For a AMD64 only installer:
+## > makensis -DARG_WAILS_AMD64_BINARY=..\..\bin\app.exe
+## For a ARM64 only installer:
+## > makensis -DARG_WAILS_ARM64_BINARY=..\..\bin\app.exe
+## For a installer with both architectures:
+## > makensis -DARG_WAILS_AMD64_BINARY=..\..\bin\app-amd64.exe -DARG_WAILS_ARM64_BINARY=..\..\bin\app-arm64.exe
+####
+## The following information is taken from the wails_tools.nsh file, but they can be overwritten here.
+####
+## !define INFO_PROJECTNAME    "my-project" # Default "scaffold"
+## !define INFO_COMPANYNAME    "My Company" # Default "My Company"
+## !define INFO_PRODUCTNAME    "My Product Name" # Default "My Product"
+## !define INFO_PRODUCTVERSION "1.0.0"     # Default "0.1.0"
+## !define INFO_COPYRIGHT      "(c) Now, My Company" # Default "© 2026, My Company"
+###
+## !define PRODUCT_EXECUTABLE  "Application.exe"      # Default "${INFO_PROJECTNAME}.exe"
+## !define UNINST_KEY_NAME     "UninstKeyInRegistry"  # Default "${INFO_COMPANYNAME}${INFO_PRODUCTNAME}"
+####
+## !define REQUEST_EXECUTION_LEVEL "admin"            # Default "admin"  see also https://nsis.sourceforge.io/Docs/Chapter4.html
+## !define WAILS_INSTALL_SCOPE     "user"             # Default "machine" - set to "user" for per-user install ($LOCALAPPDATA) without UAC prompt
+####
+## Include the wails tools
+####
+!include "wails_tools.nsh"
+
+# The version information for this two must consist of 4 parts
+VIProductVersion "${INFO_PRODUCTVERSION}.0"
+VIFileVersion    "${INFO_PRODUCTVERSION}.0"
+
+VIAddVersionKey "CompanyName"     "${INFO_COMPANYNAME}"
+VIAddVersionKey "FileDescription" "${INFO_PRODUCTNAME} Installer"
+VIAddVersionKey "ProductVersion"  "${INFO_PRODUCTVERSION}"
+VIAddVersionKey "FileVersion"     "${INFO_PRODUCTVERSION}"
+VIAddVersionKey "LegalCopyright"  "${INFO_COPYRIGHT}"
+VIAddVersionKey "ProductName"     "${INFO_PRODUCTNAME}"
+
+# Enable HiDPI support. https://nsis.sourceforge.io/Reference/ManifestDPIAware
+ManifestDPIAware true
+
+!include "MUI.nsh"
+
+!define MUI_ICON "..\icon.ico"
+!define MUI_UNICON "..\icon.ico"
+# !define MUI_WELCOMEFINISHPAGE_BITMAP "resources\leftimage.bmp" #Include this to add a bitmap on the left side of the Welcome Page. Must be a size of 164x314
+!define MUI_FINISHPAGE_NOAUTOCLOSE # Wait on the INSTFILES page so the user can take a look into the details of the installation steps
+!define MUI_ABORTWARNING # This will warn the user if they exit from the installer.
+
+!insertmacro MUI_PAGE_WELCOME # Welcome to the installer page.
+# !insertmacro MUI_PAGE_LICENSE "resources\eula.txt" # Adds a EULA page to the installer
+!insertmacro MUI_PAGE_DIRECTORY # In which folder install page.
+!insertmacro MUI_PAGE_INSTFILES # Installing page.
+!insertmacro MUI_PAGE_FINISH # Finished installation page.
+
+!insertmacro MUI_UNPAGE_INSTFILES # Uninstalling page
+
+!insertmacro MUI_LANGUAGE "English" # Set the Language of the installer
+
+## The following two statements can be used to sign the installer and the uninstaller. The path to the binaries are provided in %1
+#!uninstfinalize 'signtool --file "%1"'
+#!finalize 'signtool --file "%1"'
+
+Name "${INFO_PRODUCTNAME}"
+OutFile "..\..\..\bin\${INFO_PROJECTNAME}-${ARCH}-installer.exe" # Name of the installer's file.
+!if "${WAILS_INSTALL_SCOPE}" == "user"
+    InstallDir "$LOCALAPPDATA\Programs\${INFO_PRODUCTNAME}"
+!else
+    InstallDir "$PROGRAMFILES64\${INFO_COMPANYNAME}\${INFO_PRODUCTNAME}"
+!endif
+ShowInstDetails show # This will always show the installation details.
+
+Function .onInit
+   !insertmacro wails.checkArchitecture
+FunctionEnd
+
+Section
+    !insertmacro wails.setShellContext
+
+    !insertmacro wails.webview2runtime
+
+    SetOutPath $INSTDIR
+    
+    !insertmacro wails.files
+
+    CreateShortcut "$SMPROGRAMS\${INFO_PRODUCTNAME}.lnk" "$INSTDIR\${PRODUCT_EXECUTABLE}"
+    CreateShortCut "$DESKTOP\${INFO_PRODUCTNAME}.lnk" "$INSTDIR\${PRODUCT_EXECUTABLE}"
+
+    !insertmacro wails.associateFiles
+    !insertmacro wails.associateCustomProtocols
+    
+    !insertmacro wails.writeUninstaller
+SectionEnd
+
+Section "uninstall" 
+    !insertmacro wails.setShellContext
+
+    RMDir /r "$AppData\${PRODUCT_EXECUTABLE}" # Remove the WebView2 DataPath
+
+    RMDir /r $INSTDIR
+
+    Delete "$SMPROGRAMS\${INFO_PRODUCTNAME}.lnk"
+    Delete "$DESKTOP\${INFO_PRODUCTNAME}.lnk"
+
+    !insertmacro wails.unassociateFiles
+    !insertmacro wails.unassociateCustomProtocols
+
+    !insertmacro wails.deleteUninstaller
+SectionEnd

build/windows/nsis/wails_tools.nsh

@@ -0,0 +1,261 @@
+# DO NOT EDIT - Generated automatically by `wails build`
+
+!include "x64.nsh"
+!include "WinVer.nsh"
+!include "FileFunc.nsh"
+
+!ifndef INFO_PROJECTNAME
+    !define INFO_PROJECTNAME "opic-flow"
+!endif
+!ifndef INFO_COMPANYNAME
+    !define INFO_COMPANYNAME "OPIc Flow"
+!endif
+!ifndef INFO_PRODUCTNAME
+    !define INFO_PRODUCTNAME "OPIc Flow"
+!endif
+!ifndef INFO_PRODUCTVERSION
+    !define INFO_PRODUCTVERSION "0.1.0"
+!endif
+!ifndef INFO_COPYRIGHT
+    !define INFO_COPYRIGHT "(c) 2026, OPIc Flow"
+!endif
+!ifndef PRODUCT_EXECUTABLE
+    !define PRODUCT_EXECUTABLE "${INFO_PROJECTNAME}.exe"
+!endif
+!ifndef UNINST_KEY_NAME
+    !define UNINST_KEY_NAME "${INFO_COMPANYNAME}${INFO_PRODUCTNAME}"
+!endif
+!define UNINST_KEY "Software\Microsoft\Windows\CurrentVersion\Uninstall\${UNINST_KEY_NAME}"
+
+!ifndef WAILS_INSTALL_SCOPE
+    !define WAILS_INSTALL_SCOPE "machine"
+!endif
+
+!ifndef REQUEST_EXECUTION_LEVEL
+    !if "${WAILS_INSTALL_SCOPE}" == "user"
+        !define REQUEST_EXECUTION_LEVEL "user"
+    !else
+        !define REQUEST_EXECUTION_LEVEL "admin"
+    !endif
+!endif
+
+RequestExecutionLevel "${REQUEST_EXECUTION_LEVEL}"
+
+!ifdef ARG_WAILS_AMD64_BINARY
+    !define SUPPORTS_AMD64
+!endif
+
+!ifdef ARG_WAILS_ARM64_BINARY
+    !define SUPPORTS_ARM64
+!endif
+
+!ifdef SUPPORTS_AMD64
+    !ifdef SUPPORTS_ARM64
+        !define ARCH "amd64_arm64"
+    !else
+        !define ARCH "amd64"
+    !endif
+!else
+    !ifdef SUPPORTS_ARM64
+        !define ARCH "arm64"
+    !else
+        !error "Wails: Undefined ARCH, please provide at least one of ARG_WAILS_AMD64_BINARY or ARG_WAILS_ARM64_BINARY"
+    !endif
+!endif
+
+!macro wails.checkArchitecture
+    !ifndef WAILS_WIN10_REQUIRED
+        !define WAILS_WIN10_REQUIRED "This product is only supported on Windows 10 (Server 2016) and later."
+    !endif
+
+    !ifndef WAILS_ARCHITECTURE_NOT_SUPPORTED
+        !define WAILS_ARCHITECTURE_NOT_SUPPORTED "This product can't be installed on the current Windows architecture. Supports: ${ARCH}"
+    !endif
+
+    ${If} ${AtLeastWin10}
+        !ifdef SUPPORTS_AMD64
+            ${if} ${IsNativeAMD64}
+                Goto ok
+            ${EndIf}
+        !endif
+
+        !ifdef SUPPORTS_ARM64
+            ${if} ${IsNativeARM64}
+                Goto ok
+            ${EndIf}
+        !endif
+
+        IfSilent silentArch notSilentArch
+        silentArch:
+            SetErrorLevel 65
+            Abort
+        notSilentArch:
+            MessageBox MB_OK "${WAILS_ARCHITECTURE_NOT_SUPPORTED}"
+            Quit
+    ${else}
+        IfSilent silentWin notSilentWin
+        silentWin:
+            SetErrorLevel 64
+            Abort
+        notSilentWin:
+            MessageBox MB_OK "${WAILS_WIN10_REQUIRED}"
+            Quit
+    ${EndIf}
+
+    ok:
+!macroend
+
+!macro wails.files
+    !ifdef SUPPORTS_AMD64
+        ${if} ${IsNativeAMD64}
+            File "/oname=${PRODUCT_EXECUTABLE}" "${ARG_WAILS_AMD64_BINARY}"
+        ${EndIf}
+    !endif
+
+    !ifdef SUPPORTS_ARM64
+        ${if} ${IsNativeARM64}
+            File "/oname=${PRODUCT_EXECUTABLE}" "${ARG_WAILS_ARM64_BINARY}"
+        ${EndIf}
+    !endif
+!macroend
+
+!macro wails.writeUninstaller
+    WriteUninstaller "$INSTDIR\uninstall.exe"
+
+    SetRegView 64
+    !if "${WAILS_INSTALL_SCOPE}" == "user"
+        WriteRegStr HKCU "${UNINST_KEY}" "Publisher" "${INFO_COMPANYNAME}"
+        WriteRegStr HKCU "${UNINST_KEY}" "DisplayName" "${INFO_PRODUCTNAME}"
+        WriteRegStr HKCU "${UNINST_KEY}" "DisplayVersion" "${INFO_PRODUCTVERSION}"
+        WriteRegStr HKCU "${UNINST_KEY}" "DisplayIcon" "$INSTDIR\${PRODUCT_EXECUTABLE}"
+        WriteRegStr HKCU "${UNINST_KEY}" "UninstallString" "$\"$INSTDIR\uninstall.exe$\""
+        WriteRegStr HKCU "${UNINST_KEY}" "QuietUninstallString" "$\"$INSTDIR\uninstall.exe$\" /S"
+
+        ${GetSize} "$INSTDIR" "/S=0K" $0 $1 $2
+        IntFmt $0 "0x%08X" $0
+        WriteRegDWORD HKCU "${UNINST_KEY}" "EstimatedSize" "$0"
+    !else
+        WriteRegStr HKLM "${UNINST_KEY}" "Publisher" "${INFO_COMPANYNAME}"
+        WriteRegStr HKLM "${UNINST_KEY}" "DisplayName" "${INFO_PRODUCTNAME}"
+        WriteRegStr HKLM "${UNINST_KEY}" "DisplayVersion" "${INFO_PRODUCTVERSION}"
+        WriteRegStr HKLM "${UNINST_KEY}" "DisplayIcon" "$INSTDIR\${PRODUCT_EXECUTABLE}"
+        WriteRegStr HKLM "${UNINST_KEY}" "UninstallString" "$\"$INSTDIR\uninstall.exe$\""
+        WriteRegStr HKLM "${UNINST_KEY}" "QuietUninstallString" "$\"$INSTDIR\uninstall.exe$\" /S"
+
+        ${GetSize} "$INSTDIR" "/S=0K" $0 $1 $2
+        IntFmt $0 "0x%08X" $0
+        WriteRegDWORD HKLM "${UNINST_KEY}" "EstimatedSize" "$0"
+    !endif
+!macroend
+
+!macro wails.deleteUninstaller
+    Delete "$INSTDIR\uninstall.exe"
+
+    SetRegView 64
+    !if "${WAILS_INSTALL_SCOPE}" == "user"
+        DeleteRegKey HKCU "${UNINST_KEY}"
+    !else
+        DeleteRegKey HKLM "${UNINST_KEY}"
+    !endif
+!macroend
+
+!macro wails.setShellContext
+    ${If} ${REQUEST_EXECUTION_LEVEL} == "admin"
+        SetShellVarContext all
+    ${else}
+        SetShellVarContext current
+    ${EndIf}
+!macroend
+
+# Install webview2 by launching the bootstrapper
+# See https://docs.microsoft.com/en-us/microsoft-edge/webview2/concepts/distribution#online-only-deployment
+!macro wails.webview2runtime
+    !ifndef WAILS_INSTALL_WEBVIEW_DETAILPRINT
+        !define WAILS_INSTALL_WEBVIEW_DETAILPRINT "Installing: WebView2 Runtime"
+    !endif
+
+    SetRegView 64
+	# If the admin key exists and is not empty then webview2 is already installed
+	ReadRegStr $0 HKLM "SOFTWARE\WOW6432Node\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}" "pv"
+    ${If} $0 != ""
+        Goto ok
+    ${EndIf}
+
+    ${If} ${REQUEST_EXECUTION_LEVEL} == "user"
+        # If the installer is run in user level, check the user specific key exists and is not empty then webview2 is already installed
+	    ReadRegStr $0 HKCU "Software\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}" "pv"
+        ${If} $0 != ""
+            Goto ok
+        ${EndIf}
+     ${EndIf}
+    
+	SetDetailsPrint both
+    DetailPrint "${WAILS_INSTALL_WEBVIEW_DETAILPRINT}"
+    SetDetailsPrint listonly
+    
+    InitPluginsDir
+    CreateDirectory "$pluginsdir\webview2bootstrapper"
+    SetOutPath "$pluginsdir\webview2bootstrapper"
+    File "MicrosoftEdgeWebview2Setup.exe"
+    ExecWait '"$pluginsdir\webview2bootstrapper\MicrosoftEdgeWebview2Setup.exe" /silent /install'
+    
+    SetDetailsPrint both
+    ok:
+!macroend
+
+# Copy of APP_ASSOCIATE and APP_UNASSOCIATE macros from here https://gist.github.com/nikku/281d0ef126dbc215dd58bfd5b3a5cd5b
+!macro APP_ASSOCIATE EXT FILECLASS DESCRIPTION ICON COMMANDTEXT COMMAND
+  ; Backup the previously associated file class
+  ReadRegStr $R0 SHELL_CONTEXT "Software\Classes\.${EXT}" ""
+  WriteRegStr SHELL_CONTEXT "Software\Classes\.${EXT}" "${FILECLASS}_backup" "$R0"
+
+  WriteRegStr SHELL_CONTEXT "Software\Classes\.${EXT}" "" "${FILECLASS}"
+
+  WriteRegStr SHELL_CONTEXT "Software\Classes\${FILECLASS}" "" `${DESCRIPTION}`
+  WriteRegStr SHELL_CONTEXT "Software\Classes\${FILECLASS}\DefaultIcon" "" `${ICON}`
+  WriteRegStr SHELL_CONTEXT "Software\Classes\${FILECLASS}\shell" "" "open"
+  WriteRegStr SHELL_CONTEXT "Software\Classes\${FILECLASS}\shell\open" "" `${COMMANDTEXT}`
+  WriteRegStr SHELL_CONTEXT "Software\Classes\${FILECLASS}\shell\open\command" "" `${COMMAND}`
+!macroend
+
+!macro APP_UNASSOCIATE EXT FILECLASS
+  ; Backup the previously associated file class
+  ReadRegStr $R0 SHELL_CONTEXT "Software\Classes\.${EXT}" `${FILECLASS}_backup`
+  WriteRegStr SHELL_CONTEXT "Software\Classes\.${EXT}" "" "$R0"
+
+  DeleteRegKey SHELL_CONTEXT `Software\Classes\${FILECLASS}`
+!macroend
+
+!macro wails.associateFiles
+    ; Create file associations
+    
+!macroend
+
+!macro wails.unassociateFiles
+    ; Delete app associations
+    
+!macroend
+
+!macro CUSTOM_PROTOCOL_ASSOCIATE PROTOCOL DESCRIPTION ICON COMMAND
+  DeleteRegKey SHELL_CONTEXT "Software\Classes\${PROTOCOL}"
+  WriteRegStr SHELL_CONTEXT "Software\Classes\${PROTOCOL}" "" "${DESCRIPTION}"
+  WriteRegStr SHELL_CONTEXT "Software\Classes\${PROTOCOL}" "URL Protocol" ""
+  WriteRegStr SHELL_CONTEXT "Software\Classes\${PROTOCOL}\DefaultIcon" "" "${ICON}"
+  WriteRegStr SHELL_CONTEXT "Software\Classes\${PROTOCOL}\shell" "" ""
+  WriteRegStr SHELL_CONTEXT "Software\Classes\${PROTOCOL}\shell\open" "" ""
+  WriteRegStr SHELL_CONTEXT "Software\Classes\${PROTOCOL}\shell\open\command" "" "${COMMAND}"
+!macroend
+
+!macro CUSTOM_PROTOCOL_UNASSOCIATE PROTOCOL
+  DeleteRegKey SHELL_CONTEXT "Software\Classes\${PROTOCOL}"
+!macroend
+
+!macro wails.associateCustomProtocols
+    ; Create custom protocols associations
+    
+!macroend
+
+!macro wails.unassociateCustomProtocols
+    ; Delete app custom protocol associations
+    
+!macroend

build/windows/wails.exe.manifest

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1" xmlns:asmv3="urn:schemas-microsoft-com:asm.v3">
+    <assemblyIdentity type="win32" name="app.opicflow.desktop" version="0.1.0" processorArchitecture="*"/>
+    <dependency>
+        <dependentAssembly>
+            <assemblyIdentity type="win32" name="Microsoft.Windows.Common-Controls" version="6.0.0.0" processorArchitecture="*" publicKeyToken="6595b64144ccf1df" language="*"/>
+        </dependentAssembly>
+    </dependency>
+    <asmv3:application>
+        <asmv3:windowsSettings>
+            <dpiAware xmlns="http://schemas.microsoft.com/SMI/2005/WindowsSettings">true/pm</dpiAware> <!-- fallback for Windows 7 and 8 -->
+            <dpiAwareness xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">permonitorv2,permonitor</dpiAwareness> <!-- falls back to per-monitor if per-monitor v2 is not supported -->
+        </asmv3:windowsSettings>
+    </asmv3:application>
+    <trustInfo xmlns="urn:schemas-microsoft-com:asm.v3">
+        <security>
+            <requestedPrivileges>
+                <requestedExecutionLevel level="asInvoker" uiAccess="false"/>
+            </requestedPrivileges>
+        </security>
+    </trustInfo>
+</assembly>

docs/PLAN.md

@@ -0,0 +1,132 @@
+# OPIc Flow 구현 계획
+
+## 1. 제품 목표
+
+사용자가 난이도와 설문 주제를 선택하면 실제 OPIc 흐름에 가까운 15문항을 음성으로 듣고 영어로 답한다. 각 답변은 즉시 전사·평가되며, 시험 종료 후 전체 평가를 첫 장으로 하고 문항별 점수·키워드·개선점을 포함하는 보고서를 제공한다.
+
+점수와 추정 등급은 공식 OPIc 성적이 아닌 학습용 지표로 명확히 표시한다.
+
+## 2. 시험 구성
+
+1. 자기소개 1문항
+2. 선택 주제 묘사·일상·과거 경험 6문항
+3. 롤플레이 3문항
+4. 돌발 주제 2문항
+5. 비교·의견·미래 예측 3문항
+
+총 15문항이며 난이도에 따라 질문의 추상성, 요구 근거 수, 후속 조건을 조정한다.
+
+## 3. 상태 흐름
+
+`Setup → Device check → Question → Listening → Recording → Transcribing → Evaluating → Next question → Final report`
+
+세션 상태는 Go 백엔드가 권위 있게 관리한다. 프런트엔드는 현재 문항보다 앞선 문항을 임의 제출할 수 없다.
+
+## 4. AI 파이프라인
+
+### 현재 MVP
+
+- 질문 음성: Web Speech Synthesis
+- 사용자 음성: MediaRecorder(WebM/Opus)
+- 전사: `POST /v1/audio/transcriptions`
+- 평가: `POST /v1/responses`, strict JSON Schema
+- 다음 질문: 사전 구성된 OPIc 블루프린트
+
+사전 구성 질문을 사용하면 AI가 시험 범위를 벗어나거나 문항 수를 잘못 생성하는 문제를 막을 수 있다. 답변 내용은 다음 문항을 고를 때 분기 조건으로 사용하도록 확장한다.
+
+### Realtime 2단계
+
+- Wails Go 백엔드가 표준 API 키로 `/v1/realtime/calls`에 SDP를 전달한다.
+- Vue WebView는 `RTCPeerConnection`으로 마이크 트랙과 `oai-events` 데이터 채널을 구성한다.
+- `server_vad` 또는 `semantic_vad`로 발화 종료를 감지한다.
+- `input_audio_transcription` 이벤트로 실시간 자막을 표시한다.
+- 모델 음성 출력은 원격 audio track으로 재생한다.
+- 문항 종료마다 별도의 Responses API 평가를 수행해 점수 JSON을 확정한다.
+
+Realtime 모델이 대화를 자연스럽게 진행하더라도 시험 문항 인덱스와 최대 15문항 제한은 앱 상태 머신이 통제해야 한다.
+
+## 5. 평가 기준
+
+각 문항 100점:
+
+- 과업 수행 25
+- 구체성·내용 전개 20
+- 구성·연결 15
+- 어휘 다양성 15
+- 문법 정확성 15
+- 유창성·답변 길이 10
+
+오디오 기반 고도화 시 말하기 속도, 긴 침묵, filler, 반복, 자기 수정도 별도 feature로 저장한다. transcript만으로 발음 점수를 단정하지 않는다.
+
+## 6. 보고서
+
+첫 장:
+
+- 전체 평균 점수
+- 연습용 추정 등급
+- 핵심 강점 3개
+- 우선 개선 과제 3개
+- 다음 세션 권장 난이도·주제
+
+문항별:
+
+- 질문과 답변 transcript
+- 0–100 점수
+- 핵심 키워드
+- 잘한 점
+- 개선점
+- 개선된 예시 답변(후속 단계)
+
+내보내기:
+
+- 1차: 브라우저 인쇄/PDF
+- 2차: Go PDF 생성 및 세션 JSON/오디오 내보내기
+
+## 7. 인증과 보안
+
+- ChatGPT 웹 로그인/구독은 API 인증으로 재사용하지 않는다.
+- 개인용 MVP: 사용자가 Platform API 키를 입력하며 메모리에만 유지한다.
+- 배포용: 앱에 공용 API 키를 포함하지 않는다. 자체 백엔드에서 사용자 로그인, 사용량 제한, ephemeral Realtime 인증을 처리한다.
+- 장기 로컬 저장이 필요하면 Windows Credential Manager/macOS Keychain/libsecret을 사용한다.
+- 오디오는 기본적으로 평가 후 폐기하고, 사용자가 명시적으로 저장을 선택한 경우에만 로컬 암호화 저장한다.
+
+## 8. 단계별 로드맵
+
+### Phase 1 — 현재
+
+- Wails/Vue 앱 골격
+- 설정·시험·보고서 UI
+- 15문항 상태 머신
+- 녹음, 전사, 구조화 평가
+- 데모 모드
+
+### Phase 2
+
+- Realtime API WebRTC
+- VAD, 실시간 자막, 모델 음성, 끼어들기
+- 답변 특징에 따른 제한된 후속 질문 분기
+- 마이크/스피커 사전 점검
+
+### Phase 3
+
+- SQLite 세션 기록
+- 오디오 파형과 침묵/filler 분석
+- 개선 답변 생성과 쉐도잉
+- PDF/JSON 내보내기
+
+### Phase 4
+
+- 사용자 계정과 서버 측 API 프록시
+- 기기 간 동기화
+- 평가 prompt/eval 데이터셋 및 회귀 테스트
+- 비용·속도·품질 관측 대시보드
+
+## 9. 검증 계획
+
+- 질문 수와 순서 상태 머신 단위 테스트
+- 점수 스키마 0–100 경계 테스트
+- 빈 오디오, 마이크 거부, API 401/429/5xx 오류 테스트
+- 25MB 오디오 업로드 제한 전 사전 차단
+- 세션 완료 전 보고서 접근 차단
+- 난이도별 대표 transcript를 사용한 평가 회귀 테스트
+

frontend/bindings/github.com/wailsapp/wails/v3/internal/eventcreate.ts

@@ -0,0 +1,9 @@
+//@ts-check
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: Unused imports
+import { Create as $Create } from "@wailsio/runtime";
+
+Object.freeze($Create.Events);

frontend/bindings/github.com/wailsapp/wails/v3/internal/eventdata.d.ts

@@ -0,0 +1,2 @@
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT

frontend/bindings/opiccoach/appservice.ts

@@ -0,0 +1,34 @@
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: Unused imports
+import { Call as $Call, CancellablePromise as $CancellablePromise } from "@wailsio/runtime";
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: Unused imports
+import * as $models from "./models.js";
+
+export function Configure(request: $models.ConfigureRequest): $CancellablePromise<$models.AppSettings> {
+    return $Call.ByID(1065098514, request);
+}
+
+export function GetReport(sessionID: string): $CancellablePromise<$models.ExamReport> {
+    return $Call.ByID(704064164, sessionID);
+}
+
+export function GetSettings(): $CancellablePromise<$models.AppSettings> {
+    return $Call.ByID(3018893939);
+}
+
+export function StartSession(config: $models.ExamConfig): $CancellablePromise<$models.StartSessionResponse> {
+    return $Call.ByID(13616470, config);
+}
+
+export function SubmitAnswer(request: $models.SubmitAnswerRequest): $CancellablePromise<$models.SubmitAnswerResponse> {
+    return $Call.ByID(665225252, request);
+}
+
+export function TestConnection(): $CancellablePromise<void> {
+    return $Call.ByID(4037176558);
+}

frontend/bindings/opiccoach/index.ts

@@ -0,0 +1,21 @@
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+import * as AppService from "./appservice.js";
+export {
+    AppService
+};
+
+export type {
+    AnswerEvaluation,
+    AnswerRecord,
+    AppSettings,
+    ConfigureRequest,
+    ExamConfig,
+    ExamReport,
+    OverallReport,
+    Question,
+    StartSessionResponse,
+    SubmitAnswerRequest,
+    SubmitAnswerResponse
+} from "./models.js";

frontend/bindings/opiccoach/models.ts

@@ -0,0 +1,92 @@
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: Unused imports
+import * as time$0 from "../time/models.js";
+
+export interface AnswerEvaluation {
+    "score": number;
+    "keywords": string[] | null;
+    "strengths": string[] | null;
+    "improvements": string[] | null;
+    "feedback": string;
+}
+
+export interface AnswerRecord {
+    "question": Question;
+    "transcript": string;
+    "durationSec": number;
+    "evaluation": AnswerEvaluation;
+    "answeredAt": time$0.Time;
+    "audioPresent": boolean;
+}
+
+export interface AppSettings {
+    "hasApiKey": boolean;
+    "demoMode": boolean;
+    "evaluationModel": string;
+    "transcribeModel": string;
+    "realtimeModel": string;
+}
+
+export interface ConfigureRequest {
+    "apiKey": string;
+    "demoMode": boolean;
+    "evaluationModel": string;
+    "transcribeModel": string;
+    "realtimeModel": string;
+}
+
+export interface ExamConfig {
+    "difficulty": string;
+    "topics": string[] | null;
+    "language": string;
+}
+
+export interface ExamReport {
+    "sessionId": string;
+    "config": ExamConfig;
+    "overall": OverallReport;
+    "answers": AnswerRecord[] | null;
+    "generatedAt": time$0.Time;
+}
+
+export interface OverallReport {
+    "score": number;
+    "estimatedBand": string;
+    "summary": string;
+    "strengths": string[] | null;
+    "priorities": string[] | null;
+}
+
+export interface Question {
+    "index": number;
+    "category": string;
+    "topic": string;
+    "text": string;
+    "intent": string;
+}
+
+export interface StartSessionResponse {
+    "sessionId": string;
+    "question": Question;
+    "totalCount": number;
+}
+
+export interface SubmitAnswerRequest {
+    "sessionId": string;
+    "questionIdx": number;
+    "audioBase64": string;
+    "audioMime": string;
+    "transcript": string;
+    "durationSec": number;
+}
+
+export interface SubmitAnswerResponse {
+    "transcript": string;
+    "evaluation": AnswerEvaluation;
+    "next"?: Question | null;
+    "completed": boolean;
+    "progress": number;
+}

frontend/bindings/time/index.ts

@@ -0,0 +1,6 @@
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+export type {
+    Time
+} from "./models.js";

frontend/bindings/time/models.ts

@@ -0,0 +1,47 @@
+// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
+// This file is automatically generated. DO NOT EDIT
+
+/**
+ * A Time represents an instant in time with nanosecond precision.
+ * 
+ * Programs using times should typically store and pass them as values,
+ * not pointers. That is, time variables and struct fields should be of
+ * type [time.Time], not *time.Time.
+ * 
+ * A Time value can be used by multiple goroutines simultaneously except
+ * that the methods [Time.GobDecode], [Time.UnmarshalBinary], [Time.UnmarshalJSON] and
+ * [Time.UnmarshalText] are not concurrency-safe.
+ * 
+ * Time instants can be compared using the [Time.Before], [Time.After], and [Time.Equal] methods.
+ * The [Time.Sub] method subtracts two instants, producing a [Duration].
+ * The [Time.Add] method adds a Time and a Duration, producing a Time.
+ * 
+ * The zero value of type Time is January 1, year 1, 00:00:00.000000000 UTC.
+ * As this time is unlikely to come up in practice, the [Time.IsZero] method gives
+ * a simple way of detecting a time that has not been initialized explicitly.
+ * 
+ * Each time has an associated [Location]. The methods [Time.Local], [Time.UTC], and Time.In return a
+ * Time with a specific Location. Changing the Location of a Time value with
+ * these methods does not change the actual instant it represents, only the time
+ * zone in which to interpret it.
+ * 
+ * Representations of a Time value saved by the [Time.GobEncode], [Time.MarshalBinary], [Time.AppendBinary],
+ * [Time.MarshalJSON], [Time.MarshalText] and [Time.AppendText] methods store the [Time.Location]'s offset,
+ * but not the location name. They therefore lose information about Daylight Saving Time.
+ * 
+ * In addition to the required “wall clock” reading, a Time may contain an optional
+ * reading of the current process's monotonic clock, to provide additional precision
+ * for comparison or subtraction.
+ * See the “Monotonic Clocks” section in the package documentation for details.
+ * 
+ * Note that the Go == operator compares not just the time instant but also the
+ * Location and the monotonic clock reading. Therefore, Time values should not
+ * be used as map or database keys without first guaranteeing that the
+ * identical Location has been set for all values, which can be achieved
+ * through use of the UTC or Local method, and that the monotonic clock reading
+ * has been stripped by setting t = t.Round(0). In general, prefer t.Equal(u)
+ * to t == u, since t.Equal uses the most accurate comparison available and
+ * correctly handles the case when only one of its arguments has a monotonic
+ * clock reading.
+ */
+export type Time = any;

frontend/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="ko">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#f4f3ee" />
+    <title>OPIc Flow</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+

frontend/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "opic-flow-frontend",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build:dev": "vue-tsc --noEmit && vite build --minify false --mode development",
+    "build": "vue-tsc --noEmit && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@wailsio/runtime": "latest",
+    "vue": "^3.5.17"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^6.0.0",
+    "typescript": "^5.8.3",
+    "vite": "^7.0.0",
+    "vue-tsc": "^2.2.10"
+  }
+}

frontend/src/App.vue

@@ -0,0 +1,437 @@
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted, ref } from "vue";
+import { api } from "./api";
+import type { AppSettings, Evaluation, ExamReport, Question } from "./types";
+
+type Screen = "setup" | "exam" | "report";
+
+const difficulties = ["IM1", "IM2", "IM3", "IH", "AL"];
+const topics = ["집", "가족", "직장", "학교", "영화", "음악", "운동", "여행", "카페", "요리", "게임", "쇼핑", "공원"];
+const topicIcons: Record<string, string> = {
+  집: "⌂", 가족: "♧", 직장: "▣", 학교: "◆", 영화: "▶", 음악: "♪", 운동: "●",
+  여행: "✈", 카페: "☕", 요리: "♨", 게임: "✦", 쇼핑: "▤", 공원: "♿"
+};
+const screen = ref<Screen>("setup");
+const selectedDifficulty = ref("IM2");
+const selectedTopics = ref<string[]>(["영화", "여행", "카페"]);
+const settingsOpen = ref(false);
+const settings = ref<AppSettings>({
+  hasApiKey: false,
+  demoMode: true,
+  evaluationModel: "gpt-5-mini",
+  transcribeModel: "gpt-4o-transcribe",
+  realtimeModel: "gpt-realtime"
+});
+const apiKey = ref("");
+const connectionMessage = ref("");
+const busy = ref(false);
+const error = ref("");
+
+const sessionId = ref("");
+const currentQuestion = ref<Question | null>(null);
+const totalCount = ref(15);
+const completedCount = ref(0);
+const transcript = ref("");
+const latestEvaluation = ref<Evaluation | null>(null);
+const report = ref<ExamReport | null>(null);
+const recording = ref(false);
+const elapsed = ref(0);
+let timer: number | undefined;
+let recorder: MediaRecorder | null = null;
+let stream: MediaStream | null = null;
+let chunks: Blob[] = [];
+let englishVoice: SpeechSynthesisVoice | null = null;
+
+const progress = computed(() => Math.round((completedCount.value / totalCount.value) * 100));
+const topicLabel = computed(() => selectedTopics.value.join(" · "));
+
+onMounted(async () => {
+  await loadEnglishVoice();
+  try {
+    settings.value = await api.getSettings();
+  } catch {
+    // The UI can still be previewed in a normal browser without the Wails runtime.
+  }
+});
+
+onBeforeUnmount(() => {
+  stopTracks();
+  if (timer) window.clearInterval(timer);
+});
+
+function toggleTopic(topic: string) {
+  const index = selectedTopics.value.indexOf(topic);
+  if (index >= 0) selectedTopics.value.splice(index, 1);
+  else if (selectedTopics.value.length < 5) selectedTopics.value.push(topic);
+}
+
+async function saveSettings() {
+  busy.value = true;
+  error.value = "";
+  try {
+    settings.value = await api.configure({
+      apiKey: apiKey.value,
+      demoMode: settings.value.demoMode,
+      evaluationModel: settings.value.evaluationModel,
+      transcribeModel: settings.value.transcribeModel,
+      realtimeModel: settings.value.realtimeModel
+    });
+    apiKey.value = "";
+    settingsOpen.value = false;
+  } catch (e) {
+    error.value = readableError(e);
+  } finally {
+    busy.value = false;
+  }
+}
+
+async function testConnection() {
+  connectionMessage.value = "연결 확인 중…";
+  try {
+    if (apiKey.value) {
+      settings.value = await api.configure({
+        apiKey: apiKey.value,
+        demoMode: false,
+        evaluationModel: settings.value.evaluationModel,
+        transcribeModel: settings.value.transcribeModel,
+        realtimeModel: settings.value.realtimeModel
+      });
+    }
+    await api.testConnection();
+    connectionMessage.value = "OpenAI API 연결 성공";
+  } catch (e) {
+    connectionMessage.value = readableError(e);
+  }
+}
+
+async function startExam() {
+  if (!selectedTopics.value.length) {
+    error.value = "주제를 하나 이상 선택하세요.";
+    return;
+  }
+  busy.value = true;
+  error.value = "";
+  try {
+    const result = await api.startSession({
+      difficulty: selectedDifficulty.value,
+      topics: selectedTopics.value,
+      language: "en"
+    });
+    sessionId.value = result.sessionId;
+    currentQuestion.value = result.question;
+    totalCount.value = result.totalCount;
+    completedCount.value = 0;
+    transcript.value = "";
+    latestEvaluation.value = null;
+    screen.value = "exam";
+    window.setTimeout(speakQuestion, 450);
+  } catch (e) {
+    error.value = readableError(e);
+  } finally {
+    busy.value = false;
+  }
+}
+
+async function loadEnglishVoice(): Promise<SpeechSynthesisVoice | null> {
+  if (!("speechSynthesis" in window)) return null;
+
+  let voices = speechSynthesis.getVoices();
+  if (!voices.length) {
+    voices = await new Promise<SpeechSynthesisVoice[]>((resolve) => {
+      const timeout = window.setTimeout(() => resolve(speechSynthesis.getVoices()), 1200);
+      speechSynthesis.addEventListener("voiceschanged", () => {
+        window.clearTimeout(timeout);
+        resolve(speechSynthesis.getVoices());
+      }, { once: true });
+    });
+  }
+
+  const englishVoices = voices.filter((voice) => /^en[-_]/i.test(voice.lang));
+  const preference = [
+    /Microsoft.*Online.*Natural.*English.*United States/i,
+    /Microsoft (Ava|Aria|Jenny|Emma|Andrew|Brian).*Natural/i,
+    /Microsoft (Ava|Aria|Jenny|Emma|Andrew|Brian)/i,
+    /Google US English/i,
+    /Samantha/i,
+    /English.*United States/i
+  ];
+
+  englishVoice =
+    preference
+      .map((pattern) => englishVoices.find((voice) => pattern.test(`${voice.name} ${voice.lang}`)))
+      .find(Boolean) ??
+    englishVoices.find((voice) => /^en-US$/i.test(voice.lang) && voice.localService) ??
+    englishVoices.find((voice) => /^en-US$/i.test(voice.lang)) ??
+    englishVoices[0] ??
+    null;
+
+  return englishVoice;
+}
+
+async function speakQuestion() {
+  if (!currentQuestion.value || !("speechSynthesis" in window)) return;
+  speechSynthesis.cancel();
+
+  const voice = englishVoice ?? await loadEnglishVoice();
+  const naturalEnglish = currentQuestion.value.text
+    .replace(/\s+/g, " ")
+    .replace(/\s+([,.?!])/g, "$1")
+    .trim();
+  const utterance = new SpeechSynthesisUtterance(naturalEnglish);
+  utterance.lang = "en-US";
+  if (voice) utterance.voice = voice;
+  utterance.rate = 0.88;
+  utterance.pitch = 0.98;
+  utterance.volume = 1;
+  speechSynthesis.speak(utterance);
+}
+
+async function toggleRecording() {
+  if (recording.value) {
+    recorder?.stop();
+    return;
+  }
+  error.value = "";
+  try {
+    stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+    const preferred = MediaRecorder.isTypeSupported("audio/webm;codecs=opus")
+      ? "audio/webm;codecs=opus"
+      : "audio/webm";
+    recorder = new MediaRecorder(stream, { mimeType: preferred });
+    chunks = [];
+    recorder.ondataavailable = (event) => {
+      if (event.data.size) chunks.push(event.data);
+    };
+    recorder.onstop = () => {
+      recording.value = false;
+      if (timer) window.clearInterval(timer);
+      stopTracks();
+    };
+    recorder.start(250);
+    elapsed.value = 0;
+    recording.value = true;
+    timer = window.setInterval(() => elapsed.value++, 1000);
+  } catch {
+    error.value = "마이크 권한을 확인하세요. 텍스트 답변으로도 진행할 수 있습니다.";
+  }
+}
+
+function stopTracks() {
+  stream?.getTracks().forEach((track) => track.stop());
+  stream = null;
+}
+
+async function submitAnswer() {
+  if (!currentQuestion.value || busy.value) return;
+  if (recording.value) recorder?.stop();
+  busy.value = true;
+  error.value = "";
+  try {
+    const blob = chunks.length ? new Blob(chunks, { type: recorder?.mimeType || "audio/webm" }) : null;
+    const audioBase64 = blob ? await blobToBase64(blob) : "";
+    const response = await api.submitAnswer({
+      sessionId: sessionId.value,
+      questionIdx: currentQuestion.value.index - 1,
+      audioBase64,
+      audioMime: blob?.type || "",
+      transcript: transcript.value,
+      durationSec: elapsed.value
+    });
+    transcript.value = response.transcript;
+    latestEvaluation.value = response.evaluation;
+    completedCount.value = response.progress;
+    chunks = [];
+    if (response.completed) {
+      report.value = await api.getReport(sessionId.value);
+      screen.value = "report";
+      return;
+    }
+    window.setTimeout(() => {
+      currentQuestion.value = response.next || null;
+      transcript.value = "";
+      latestEvaluation.value = null;
+      elapsed.value = 0;
+      window.setTimeout(speakQuestion, 350);
+    }, 900);
+  } catch (e) {
+    error.value = readableError(e);
+  } finally {
+    busy.value = false;
+  }
+}
+
+function resetExam() {
+  speechSynthesis?.cancel();
+  screen.value = "setup";
+  report.value = null;
+  currentQuestion.value = null;
+  latestEvaluation.value = null;
+  transcript.value = "";
+  completedCount.value = 0;
+}
+
+function printReport() {
+  window.print();
+}
+
+function blobToBase64(blob: Blob): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onloadend = () => resolve(String(reader.result).split(",")[1] || "");
+    reader.onerror = reject;
+    reader.readAsDataURL(blob);
+  });
+}
+
+function readableError(value: unknown) {
+  if (value instanceof Error) return value.message;
+  return String(value).replace(/^.*?: /, "");
+}
+</script>
+
+<template>
+  <div class="app-shell">
+    <header class="topbar">
+      <button class="brand" @click="resetExam">
+        <span class="brand-mark">O</span>
+        <span><strong>OPIc Flow</strong><small>AI SPEAKING LAB</small></span>
+      </button>
+      <div class="top-actions">
+        <span class="connection-pill" :class="{ live: settings.hasApiKey && !settings.demoMode }">
+          <i></i>{{ settings.demoMode ? "DEMO MODE" : "OPENAI CONNECTED" }}
+        </span>
+        <button class="icon-button" aria-label="설정" @click="settingsOpen = true">⚙</button>
+      </div>
+    </header>
+
+    <main v-if="screen === 'setup'" class="setup-layout">
+      <section class="hero">
+        <p class="eyebrow">PERSONAL AI INTERVIEWER</p>
+        <h1>말할수록,<br /><em>정확해지는</em> 영어.</h1>
+        <p class="hero-copy">실제 OPIc 흐름으로 질문을 듣고 답하세요. AI가 매 문항을 분석하고 다음 연습 방향을 제시합니다.</p>
+        <div class="hero-stats">
+          <div><strong>15</strong><span>Questions</span></div>
+          <div><strong>AI</strong><span>Live feedback</span></div>
+          <div><strong>01</strong><span>Final report</span></div>
+        </div>
+      </section>
+
+      <section class="setup-card">
+        <div class="step-heading"><span>01</span><div><h2>목표 난이도</h2><p>현재 목표 등급을 선택하세요.</p></div></div>
+        <div class="difficulty-grid">
+          <button v-for="level in difficulties" :key="level" :class="{ selected: selectedDifficulty === level }" @click="selectedDifficulty = level">
+            <strong>{{ level }}</strong><small>{{ level === "AL" ? "Advanced" : "Intermediate" }}</small>
+          </button>
+        </div>
+
+        <div class="divider"></div>
+        <div class="step-heading"><span>02</span><div><h2>설문 주제</h2><p>자신 있게 말할 수 있는 주제를 최대 5개 고르세요.</p></div><b>{{ selectedTopics.length }}/5</b></div>
+        <div class="topic-grid">
+          <button v-for="topic in topics" :key="topic" :class="{ selected: selectedTopics.includes(topic) }" @click="toggleTopic(topic)">
+            <span>{{ topicIcons[topic] }}</span>{{ topic }}
+          </button>
+        </div>
+
+        <div class="session-summary">
+          <div><small>YOUR SESSION</small><strong>{{ selectedDifficulty }} · {{ topicLabel }}</strong></div>
+          <button class="primary" :disabled="busy" @click="startExam">{{ busy ? "준비 중…" : "연습 시작" }} <span>→</span></button>
+        </div>
+        <p v-if="error" class="error">{{ error }}</p>
+      </section>
+    </main>
+
+    <main v-else-if="screen === 'exam'" class="exam-layout">
+      <aside class="exam-sidebar">
+        <p class="eyebrow">MOCK INTERVIEW</p>
+        <h2>{{ selectedDifficulty }} Session</h2>
+        <div class="progress-ring" :style="{ '--progress': `${progress * 3.6}deg` }"><span><strong>{{ completedCount }}</strong>/ {{ totalCount }}</span></div>
+        <div class="progress-meta"><span>PROGRESS</span><b>{{ progress }}%</b></div>
+        <div class="progress-bar"><i :style="{ width: `${progress}%` }"></i></div>
+        <div class="exam-tip"><small>COACH'S NOTE</small><p>완벽한 문법보다 구체적인 경험과 자연스러운 이야기 흐름에 집중하세요.</p></div>
+      </aside>
+
+      <section class="conversation">
+        <div class="question-meta">
+          <span>QUESTION {{ currentQuestion?.index?.toString().padStart(2, "0") }}</span>
+          <b>{{ currentQuestion?.category }}</b>
+          <span>{{ currentQuestion?.topic }}</span>
+        </div>
+        <div class="question-card">
+          <button class="speaker" @click="speakQuestion">◖))</button>
+          <div><small>INTERVIEWER</small><h1>{{ currentQuestion?.text }}</h1><p>{{ currentQuestion?.intent }}</p></div>
+        </div>
+
+        <div class="answer-area">
+          <div class="record-row">
+            <button class="record-button" :class="{ active: recording }" @click="toggleRecording"><i></i>{{ recording ? "녹음 중지" : "답변 녹음" }}</button>
+            <span class="timer">{{ Math.floor(elapsed / 60).toString().padStart(2, "0") }}:{{ (elapsed % 60).toString().padStart(2, "0") }}</span>
+            <span class="audio-bars" :class="{ active: recording }"><i v-for="n in 18" :key="n"></i></span>
+          </div>
+          <label for="transcript">답변 스크립트 <small>녹음만 제출하면 AI가 자동 전사합니다. 직접 입력하거나 수정할 수도 있습니다.</small></label>
+          <textarea id="transcript" v-model="transcript" placeholder="Start speaking, or type your answer here…"></textarea>
+          <div class="submit-row">
+            <span>{{ transcript.trim().split(/\s+/).filter(Boolean).length }} words</span>
+            <button class="primary" :disabled="busy || (!transcript.trim() && !chunks.length)" @click="submitAnswer">{{ busy ? "AI 분석 중…" : "답변 제출" }} <span>→</span></button>
+          </div>
+        </div>
+
+        <div v-if="latestEvaluation" class="instant-feedback">
+          <div class="score">{{ latestEvaluation.score }}</div>
+          <div><small>INSTANT FEEDBACK</small><p>{{ latestEvaluation.feedback }}</p></div>
+        </div>
+        <p v-if="error" class="error">{{ error }}</p>
+      </section>
+    </main>
+
+    <main v-else-if="report && screen === 'report'" class="report-layout">
+      <section class="report-cover">
+        <p class="eyebrow">SESSION COMPLETE</p>
+        <h1>Speaking<br />Performance<br /><em>Report</em></h1>
+        <p>{{ new Date(report.generatedAt).toLocaleDateString("ko-KR") }} · {{ report.config.difficulty }} · {{ report.config.topics.join(", ") }}</p>
+        <div class="overall-score">
+          <div><strong>{{ report.overall.score }}</strong><span>/ 100</span></div>
+          <aside><small>ESTIMATED BAND</small><b>{{ report.overall.estimatedBand }}</b></aside>
+        </div>
+        <p class="report-summary">{{ report.overall.summary }}</p>
+        <div class="report-actions"><button class="secondary" @click="printReport">보고서 인쇄</button><button class="primary" @click="resetExam">새 연습 시작 →</button></div>
+      </section>
+
+      <section class="report-content">
+        <div class="overview-grid">
+          <article><small>STRENGTHS</small><ul><li v-for="item in report.overall.strengths" :key="item">{{ item }}</li></ul></article>
+          <article class="accent"><small>NEXT PRIORITIES</small><ul><li v-for="item in report.overall.priorities" :key="item">{{ item }}</li></ul></article>
+        </div>
+        <div class="answer-list">
+          <article v-for="answer in report.answers" :key="answer.question.index" class="answer-report">
+            <header><span>Q{{ answer.question.index.toString().padStart(2, "0") }}</span><div><small>{{ answer.question.category }} · {{ answer.question.topic }}</small><h3>{{ answer.question.text }}</h3></div><strong>{{ answer.evaluation.score }}</strong></header>
+            <blockquote>{{ answer.transcript }}</blockquote>
+            <div class="keyword-row"><span v-for="keyword in answer.evaluation.keywords" :key="keyword">{{ keyword }}</span></div>
+            <div class="feedback-grid">
+              <div><small>잘한 점</small><p>{{ answer.evaluation.strengths.join(" ") }}</p></div>
+              <div><small>개선점</small><p>{{ answer.evaluation.improvements.join(" ") }}</p></div>
+            </div>
+          </article>
+        </div>
+      </section>
+    </main>
+
+    <div v-if="settingsOpen" class="modal-backdrop" @click.self="settingsOpen = false">
+      <section class="settings-modal">
+        <button class="modal-close" @click="settingsOpen = false">×</button>
+        <p class="eyebrow">AI CONNECTION</p>
+        <h2>OpenAI 연결 설정</h2>
+        <p class="modal-copy">ChatGPT 웹 로그인은 서드파티 데스크톱 앱의 API 인증으로 사용할 수 없습니다. OpenAI Platform API 키를 사용하세요. 키는 현재 앱 프로세스 메모리에만 보관됩니다.</p>
+        <label>API key<input v-model="apiKey" type="password" placeholder="sk-…" autocomplete="off" /></label>
+        <label class="switch-row"><span><b>데모 모드</b><small>API 비용 없이 전체 흐름을 시험합니다.</small></span><input v-model="settings.demoMode" type="checkbox" /></label>
+        <div class="model-grid">
+          <label>평가 모델<input v-model="settings.evaluationModel" /></label>
+          <label>전사 모델<input v-model="settings.transcribeModel" /></label>
+          <label>Realtime 모델<input v-model="settings.realtimeModel" /></label>
+        </div>
+        <p v-if="connectionMessage" class="connection-message">{{ connectionMessage }}</p>
+        <p v-if="error" class="error">{{ error }}</p>
+        <footer><button class="secondary" @click="testConnection">연결 테스트</button><button class="primary" :disabled="busy" @click="saveSettings">설정 저장</button></footer>
+      </section>
+    </div>
+  </div>
+</template>

frontend/src/api.ts

@@ -0,0 +1,24 @@
+import { AppService } from "../bindings/opiccoach";
+import type { AppSettings, ExamReport, Evaluation, Question } from "./types";
+
+export const api = {
+  getSettings: () => AppService.GetSettings() as Promise<AppSettings>,
+  configure: (settings: Record<string, unknown>) =>
+    AppService.Configure(settings as never) as Promise<AppSettings>,
+  testConnection: () => AppService.TestConnection() as Promise<void>,
+  startSession: (config: Record<string, unknown>) =>
+    AppService.StartSession(config as never) as Promise<{
+      sessionId: string;
+      question: Question;
+      totalCount: number;
+    }>,
+  submitAnswer: (answer: Record<string, unknown>) =>
+    AppService.SubmitAnswer(answer as never) as Promise<{
+      transcript: string;
+      evaluation: Evaluation;
+      next?: Question;
+      completed: boolean;
+      progress: number;
+    }>,
+  getReport: (sessionId: string) => AppService.GetReport(sessionId) as Promise<ExamReport>
+};

frontend/src/main.ts

@@ -0,0 +1,6 @@
+import { createApp } from "vue";
+import App from "./App.vue";
+import "./style.css";
+
+createApp(App).mount("#app");
+

frontend/src/style.css

@@ -0,0 +1,176 @@
+@import url("https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&family=Manrope:wght@400;500;600;700;800&display=swap");
+
+:root {
+  font-family: "DM Sans", "Noto Sans KR", sans-serif;
+  color: #16241d;
+  background: #f3f3ee;
+  font-synthesis: none;
+  --ink: #14251c;
+  --muted: #758078;
+  --line: #dfe2d9;
+  --paper: #fbfbf7;
+  --green: #183f2b;
+  --lime: #c9f36a;
+  --orange: #f06a3c;
+}
+
+* { box-sizing: border-box; }
+body { margin: 0; min-width: 900px; min-height: 100vh; background: #f3f3ee; }
+button, input, textarea { font: inherit; }
+button { color: inherit; }
+.app-shell { min-height: 100vh; }
+.topbar { height: 76px; padding: 0 4.5vw; display: flex; align-items: center; justify-content: space-between; border-bottom: 1px solid var(--line); background: rgba(250,250,246,.9); }
+.brand { display: flex; align-items: center; gap: 12px; border: 0; background: none; cursor: pointer; text-align: left; }
+.brand-mark { width: 38px; height: 38px; display: grid; place-items: center; color: var(--lime); background: var(--green); border-radius: 50% 50% 48% 42%; font: 800 19px Manrope; }
+.brand strong { display: block; font: 800 19px Manrope; letter-spacing: -.6px; }
+.brand small { display: block; margin-top: 2px; font-size: 8px; letter-spacing: 2.1px; color: #8a938d; }
+.top-actions { display: flex; align-items: center; gap: 14px; }
+.connection-pill { display: flex; align-items: center; gap: 8px; padding: 8px 12px; border: 1px solid var(--line); border-radius: 99px; font-size: 9px; font-weight: 700; letter-spacing: 1.2px; }
+.connection-pill i { width: 7px; height: 7px; border-radius: 50%; background: #e7a436; }
+.connection-pill.live i { background: #45a86e; box-shadow: 0 0 0 4px #45a86e22; }
+.icon-button { width: 38px; height: 38px; border: 1px solid var(--line); border-radius: 50%; background: white; cursor: pointer; }
+.setup-layout { display: grid; grid-template-columns: .78fr 1.22fr; min-height: calc(100vh - 76px); }
+.hero { padding: 9vh 5vw; position: relative; overflow: hidden; background: var(--green); color: white; }
+.hero::after { content: ""; position: absolute; width: 430px; height: 430px; left: -130px; bottom: -210px; border: 1px solid #ffffff25; border-radius: 50%; box-shadow: 0 0 0 80px #ffffff08, 0 0 0 160px #ffffff05; }
+.eyebrow { margin: 0 0 28px; color: #92a198; font-size: 10px; font-weight: 700; letter-spacing: 2.5px; }
+.hero .eyebrow { color: var(--lime); }
+.hero h1, .report-cover h1 { margin: 0; font: 500 clamp(45px, 5vw, 78px)/.98 Manrope; letter-spacing: -4px; }
+.hero h1 em, .report-cover h1 em { color: var(--lime); font-style: normal; }
+.hero-copy { max-width: 430px; margin: 34px 0; color: #c6d0ca; font-size: 15px; line-height: 1.8; }
+.hero-stats { position: absolute; left: 5vw; right: 5vw; bottom: 8vh; display: flex; gap: 40px; z-index: 1; }
+.hero-stats div { border-left: 1px solid #ffffff33; padding-left: 15px; }
+.hero-stats strong { display: block; font: 600 25px Manrope; }
+.hero-stats span { color: #90a198; font-size: 9px; text-transform: uppercase; letter-spacing: 1px; }
+.setup-card { padding: 6vh 6vw; background: var(--paper); }
+.step-heading { display: flex; align-items: flex-start; gap: 15px; }
+.step-heading > span { display: grid; place-items: center; width: 31px; height: 31px; border-radius: 50%; background: var(--green); color: white; font-size: 10px; font-weight: 700; }
+.step-heading h2 { margin: 0; font: 700 20px Manrope; }
+.step-heading p { margin: 6px 0 0; color: var(--muted); font-size: 12px; }
+.step-heading b { margin-left: auto; color: var(--orange); font-size: 12px; }
+.difficulty-grid { display: grid; grid-template-columns: repeat(5, 1fr); gap: 8px; margin: 25px 0 0 46px; }
+.difficulty-grid button { padding: 18px 8px; border: 1px solid var(--line); background: white; cursor: pointer; }
+.difficulty-grid strong, .difficulty-grid small { display: block; }
+.difficulty-grid strong { font: 700 16px Manrope; }
+.difficulty-grid small { margin-top: 4px; color: var(--muted); font-size: 8px; }
+.difficulty-grid button.selected { border-color: var(--green); color: white; background: var(--green); box-shadow: inset 0 -3px var(--lime); }
+.difficulty-grid button.selected small { color: #afc0b6; }
+.divider { height: 1px; background: var(--line); margin: 42px 0 34px; }
+.topic-grid { display: grid; grid-template-columns: repeat(5, 1fr); gap: 8px; margin: 24px 0 0 46px; }
+.topic-grid button { display: flex; align-items: center; gap: 8px; min-height: 42px; padding: 8px 10px; border: 1px solid var(--line); border-radius: 3px; background: white; font-size: 11px; cursor: pointer; }
+.topic-grid button span { color: #91a098; font-size: 15px; }
+.topic-grid button.selected { border-color: #b8d771; background: #eff8dc; color: var(--green); font-weight: 700; }
+.topic-grid button.selected span { color: var(--green); }
+.session-summary { margin-top: 42px; padding: 20px 0 0; display: flex; justify-content: space-between; align-items: center; border-top: 1px solid var(--line); }
+.session-summary small { display: block; color: var(--muted); font-size: 8px; letter-spacing: 1.6px; }
+.session-summary strong { display: block; margin-top: 7px; max-width: 350px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; font-size: 13px; }
+.primary, .secondary { min-height: 44px; padding: 0 20px; border-radius: 2px; border: 1px solid var(--green); cursor: pointer; font-size: 11px; font-weight: 700; letter-spacing: .4px; }
+.primary { color: white; background: var(--green); }
+.primary span { margin-left: 18px; color: var(--lime); font-size: 17px; }
+.primary:disabled { opacity: .5; cursor: wait; }
+.secondary { background: transparent; color: var(--green); }
+.error { padding: 10px 14px; color: #a23a24; background: #fff0e9; font-size: 12px; border-left: 3px solid var(--orange); }
+.exam-layout { display: grid; grid-template-columns: 285px 1fr; min-height: calc(100vh - 76px); }
+.exam-sidebar { padding: 52px 36px; color: white; background: var(--green); }
+.exam-sidebar h2 { margin: -14px 0 35px; font: 600 25px Manrope; }
+.progress-ring { --progress: 0deg; width: 150px; height: 150px; margin: 0 auto 30px; display: grid; place-items: center; border-radius: 50%; background: conic-gradient(var(--lime) var(--progress), #ffffff18 0); position: relative; }
+.progress-ring::after { content: ""; position: absolute; inset: 9px; border-radius: 50%; background: var(--green); }
+.progress-ring span { z-index: 1; color: #9aac9f; font-size: 12px; }
+.progress-ring strong { color: white; font: 600 38px Manrope; }
+.progress-meta { display: flex; justify-content: space-between; font-size: 9px; letter-spacing: 1px; color: #9caf9f; }
+.progress-meta b { color: var(--lime); }
+.progress-bar { height: 3px; margin-top: 9px; background: #ffffff20; }
+.progress-bar i { display: block; height: 100%; background: var(--lime); transition: width .4s; }
+.exam-tip { margin-top: 60px; padding: 18px; border: 1px solid #ffffff18; background: #ffffff08; }
+.exam-tip small { color: var(--lime); font-size: 8px; letter-spacing: 1.4px; }
+.exam-tip p { margin: 9px 0 0; color: #b8c6bd; font-size: 11px; line-height: 1.7; }
+.conversation { padding: 5vh 7vw 8vh; background: var(--paper); }
+.question-meta { display: flex; align-items: center; gap: 13px; color: #8a948d; font-size: 9px; letter-spacing: 1.3px; }
+.question-meta b { padding: 6px 9px; color: var(--green); background: #e9f0e9; letter-spacing: 0; }
+.question-card { display: grid; grid-template-columns: 58px 1fr; gap: 22px; margin-top: 30px; padding-bottom: 38px; border-bottom: 1px solid var(--line); }
+.speaker { width: 54px; height: 54px; border-radius: 50%; border: 0; color: var(--green); background: var(--lime); cursor: pointer; font-weight: 800; }
+.question-card small, .instant-feedback small { color: var(--orange); font-size: 8px; font-weight: 700; letter-spacing: 1.7px; }
+.question-card h1 { max-width: 770px; margin: 9px 0 12px; font: 500 clamp(26px, 3vw, 42px)/1.22 Manrope; letter-spacing: -1.8px; }
+.question-card p { color: var(--muted); font-size: 11px; }
+.answer-area { margin-top: 32px; }
+.record-row { display: flex; align-items: center; gap: 18px; }
+.record-button { height: 40px; padding: 0 15px; display: flex; align-items: center; gap: 8px; border: 1px solid #dfd4ce; background: #fff8f4; color: #a7482a; cursor: pointer; font-size: 11px; font-weight: 700; }
+.record-button i { width: 9px; height: 9px; border-radius: 50%; background: var(--orange); }
+.record-button.active i { animation: pulse 1s infinite; }
+.timer { font: 600 13px Manrope; font-variant-numeric: tabular-nums; }
+.audio-bars { height: 26px; flex: 1; display: flex; align-items: center; gap: 3px; overflow: hidden; }
+.audio-bars i { width: 3px; height: 4px; background: #d4d9d2; }
+.audio-bars.active i { background: #7fa18b; animation: wave .7s ease-in-out infinite alternate; }
+.audio-bars i:nth-child(3n) { animation-delay: .2s; }.audio-bars i:nth-child(4n) { animation-delay: .35s; }
+@keyframes wave { to { height: 24px; } } @keyframes pulse { 50% { box-shadow: 0 0 0 6px #f06a3c28; } }
+.answer-area label, .settings-modal label { display: block; margin: 22px 0 9px; font-size: 10px; font-weight: 700; text-transform: uppercase; letter-spacing: 1px; }
+.answer-area label small { margin-left: 8px; color: var(--muted); font-weight: 400; letter-spacing: 0; text-transform: none; }
+textarea { width: 100%; height: 125px; padding: 17px; resize: vertical; border: 1px solid var(--line); outline: none; background: white; line-height: 1.7; }
+textarea:focus, input:focus { border-color: #7e9b88; box-shadow: 0 0 0 3px #7e9b8815; }
+.submit-row { display: flex; justify-content: space-between; align-items: center; margin-top: 12px; }
+.submit-row > span { color: var(--muted); font-size: 10px; }
+.instant-feedback { margin-top: 18px; padding: 15px; display: flex; gap: 15px; align-items: center; background: #edf6d9; border-left: 3px solid #9dc74b; }
+.instant-feedback .score { width: 45px; height: 45px; display: grid; place-items: center; border-radius: 50%; color: white; background: var(--green); font: 700 16px Manrope; }
+.instant-feedback p { margin: 4px 0 0; font-size: 11px; }
+.report-layout { display: grid; grid-template-columns: 38% 62%; min-height: calc(100vh - 76px); }
+.report-cover { position: sticky; top: 0; height: calc(100vh - 76px); padding: 7vh 4vw; color: white; background: var(--green); }
+.report-cover h1 { font-size: clamp(43px, 4.5vw, 68px); }
+.report-cover > p:not(.eyebrow):not(.report-summary) { color: #99aa9f; font-size: 11px; }
+.overall-score { margin-top: 5vh; padding: 24px 0; display: flex; align-items: center; gap: 35px; border-top: 1px solid #ffffff22; border-bottom: 1px solid #ffffff22; }
+.overall-score strong { font: 600 68px Manrope; color: var(--lime); }
+.overall-score span { color: #8ea096; }
+.overall-score aside { padding-left: 30px; border-left: 1px solid #ffffff22; }
+.overall-score small { display: block; color: #8ea096; font-size: 8px; letter-spacing: 1.5px; }
+.overall-score b { display: block; margin-top: 7px; font-size: 16px; }
+.report-summary { color: #b9c6bd; font-size: 12px; line-height: 1.7; }
+.report-actions { display: flex; gap: 10px; margin-top: 25px; }
+.report-cover .secondary { border-color: #ffffff55; color: white; }
+.report-cover .primary { color: var(--green); background: var(--lime); border-color: var(--lime); }
+.report-content { padding: 5vh 5vw; background: var(--paper); }
+.overview-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 12px; }
+.overview-grid article { padding: 25px; border: 1px solid var(--line); background: white; }
+.overview-grid article.accent { background: #eef4dd; }
+.overview-grid small, .answer-report small { color: var(--orange); font-size: 8px; font-weight: 700; letter-spacing: 1.4px; }
+.overview-grid ul { margin: 17px 0 0; padding-left: 18px; font-size: 12px; line-height: 2; }
+.answer-list { margin-top: 32px; }
+.answer-report { padding: 28px 0; border-top: 1px solid var(--line); }
+.answer-report header { display: grid; grid-template-columns: 42px 1fr 55px; gap: 15px; align-items: start; }
+.answer-report header > span { font: 700 15px Manrope; color: #8a948d; }
+.answer-report h3 { margin: 5px 0 0; font: 600 16px/1.45 Manrope; }
+.answer-report header > strong { display: grid; place-items: center; width: 50px; height: 50px; border-radius: 50%; color: white; background: var(--green); }
+blockquote { margin: 18px 0; padding: 16px 18px; color: #526057; background: #f1f2ed; font-size: 11px; line-height: 1.7; border-left: 2px solid #aab5ad; }
+.keyword-row { display: flex; gap: 6px; flex-wrap: wrap; }
+.keyword-row span { padding: 5px 8px; border-radius: 99px; color: #48604f; background: #e5eee7; font-size: 9px; }
+.feedback-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 12px; margin-top: 15px; }
+.feedback-grid div { padding: 14px; border: 1px solid var(--line); }
+.feedback-grid p { margin: 6px 0 0; color: #59665e; font-size: 10px; line-height: 1.6; }
+.modal-backdrop { position: fixed; inset: 0; z-index: 20; display: grid; place-items: center; padding: 30px; background: #102019aa; backdrop-filter: blur(6px); }
+.settings-modal { position: relative; width: min(580px, 90vw); max-height: 90vh; overflow: auto; padding: 38px; background: var(--paper); box-shadow: 0 25px 80px #07140d66; }
+.settings-modal h2 { margin: -15px 0 12px; font: 700 28px Manrope; }
+.modal-copy { color: var(--muted); font-size: 11px; line-height: 1.7; }
+.modal-close { position: absolute; top: 14px; right: 18px; border: 0; background: none; font-size: 25px; cursor: pointer; }
+.settings-modal input:not([type="checkbox"]) { width: 100%; height: 42px; margin-top: 7px; padding: 0 12px; border: 1px solid var(--line); outline: none; background: white; }
+.switch-row { display: flex !important; justify-content: space-between; align-items: center; padding: 14px; background: #eef1ea; }
+.switch-row b, .switch-row small { display: block; }
+.switch-row small { margin-top: 4px; color: var(--muted); font-weight: 400; text-transform: none; letter-spacing: 0; }
+.switch-row input { width: 18px; height: 18px; }
+.model-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 0 12px; }
+.model-grid label:last-child { grid-column: 1 / -1; }
+.settings-modal footer { margin-top: 25px; display: flex; justify-content: flex-end; gap: 8px; }
+.connection-message { padding: 10px; background: #eef4dd; font-size: 11px; }
+
+@media (max-width: 1050px) {
+  .setup-layout { grid-template-columns: .68fr 1.32fr; }
+  .setup-card { padding-left: 4vw; padding-right: 4vw; }
+  .topic-grid { grid-template-columns: repeat(4, 1fr); }
+  .hero h1 { font-size: 52px; }
+}
+
+@media print {
+  .topbar, .report-actions { display: none; }
+  .report-layout { display: block; }
+  .report-cover { position: static; height: auto; color: #14251c; background: white; }
+  .report-cover h1 em, .overall-score strong { color: #14251c; }
+  .report-content { padding: 20px; }
+  .answer-report { break-inside: avoid; }
+}
+

frontend/src/types.ts

@@ -0,0 +1,45 @@
+export interface AppSettings {
+  hasApiKey: boolean;
+  demoMode: boolean;
+  evaluationModel: string;
+  transcribeModel: string;
+  realtimeModel: string;
+}
+
+export interface Question {
+  index: number;
+  category: string;
+  topic: string;
+  text: string;
+  intent: string;
+}
+
+export interface Evaluation {
+  score: number;
+  keywords: string[];
+  strengths: string[];
+  improvements: string[];
+  feedback: string;
+}
+
+export interface AnswerRecord {
+  question: Question;
+  transcript: string;
+  durationSec: number;
+  evaluation: Evaluation;
+}
+
+export interface ExamReport {
+  sessionId: string;
+  config: { difficulty: string; topics: string[]; language: string };
+  overall: {
+    score: number;
+    estimatedBand: string;
+    summary: string;
+    strengths: string[];
+    priorities: string[];
+  };
+  answers: AnswerRecord[];
+  generatedAt: string;
+}
+

frontend/src/vite-env.d.ts

@@ -0,0 +1,2 @@
+/// <reference types="vite/client" />
+

frontend/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts", "src/**/*.d.ts", "src/**/*.vue"]
+}
+