feat: Machine-Hosted PWA — Direct Mode without MeticAI backend

[hessius]

Machine-Hosted PWA

Run MeticAI's web UI directly on the Meticulous machine without the MeticAI Docker container. The PWA intercepts all API calls and translates them to native Meticulous /api/v1/ endpoints.

What's included

• Global fetch interceptor (main.tsx) with ~30 endpoint translations
• Direct Socket.IO telemetry — real-time shot data mapped to MeticAI's format
• Profile catalogue from machine's native profiles
• Shot history translated from machine format
• Run profiles with stop → load → start flow (no purge)
• Preheat & schedule support via client-side timers
• Build scripts for machine deployment (build:machine, install-meticai.sh)
• CI workflow for automated PWA builds

Limitations (by design)

• No AI features (no Gemini API key on machine)
• No profile generation or analysis
• No cross-device sync
• History limited to machine's local storage

Related

• Issue feat: Machine-Hosted MeticAI PWA — Implementation Plan #309
• Milestone 2.4

[Copilot]

Pull request overview

Adds a “machine-hosted PWA” deployment path where MeticAI’s web UI can run as static files served by the Meticulous machine (no MeticAI Docker backend), introducing direct-mode adapters for machine comms + browser-based persistence and AI.

Changes:

• Introduces direct/proxy mode detection, feature flags, and a MachineService abstraction with a DirectAdapter using the machine’s native REST + Socket.IO APIs.
• Adds browser-side persistence (IndexedDB via idb) and ports/introduces AI prompt + validation utilities for direct/PWA operation.
• Adds install/validate/update/uninstall scripts and CI workflows to build and ship a machine PWA tarball.

Reviewed changes

Copilot reviewed 64 out of 66 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
scripts/machine/validate-meticai.sh	Installation validation utility for machine-hosted PWA
scripts/machine/update-meticai.sh	Delegates updates to installer script
scripts/machine/uninstall-meticai.sh	Removes PWA install + backups from machine
scripts/install-direct.sh	Installer for deploying static PWA to machine + patching Tornado route
apps/web/vite.config.ts	Adds direct/proxy build mode behavior (base path, chunking)
apps/web/src/vite-end.d.ts	Types for import.meta.env direct/proxy vars
apps/web/src/views/StartView.tsx	Adds direct-mode behavior (skip backend author fetch, profile catalogue entry)
apps/web/src/services/storage/useStorageMigration.ts	Initializes IndexedDB only in direct mode
apps/web/src/services/storage/index.ts	Storage barrel exports
apps/web/src/services/storage/AppDatabase.ts	IndexedDB schema + helpers (settings, cache, sessions, images)
apps/web/src/services/storage/AppDatabase.test.ts	Unit tests for IndexedDB layer
apps/web/src/services/machine/index.ts	Exports expanded machine service types + adapters
apps/web/src/services/machine/MeticAIAdapter.ts	Refactors proxy adapter to satisfy expanded MachineService interface
apps/web/src/services/machine/MachineServiceContext.tsx	Provider selects DirectAdapter vs proxy and connects in direct mode
apps/web/src/services/machine/MachineService.ts	Expands MachineService to include profiles/telemetry/history/settings
apps/web/src/services/machine/DirectAdapter.ts	Direct machine adapter using @meticulous-home/espresso-api + Socket.IO
apps/web/src/services/ai/prompts/prompts.test.ts	Tests for prompt builders
apps/web/src/services/ai/prompts/index.ts	TypeScript prompt builder implementations
apps/web/src/services/ai/profilePromptFull.ts	Full profile prompt + validate/retry loop shared by browser AI
apps/web/src/services/ai/index.ts	AI services barrel exports
apps/web/src/services/ai/ProxyAIService.ts	Backend-delegating AI service implementation
apps/web/src/services/ai/BrowserAIService.ts	Browser Gemini SDK AI service implementation
apps/web/src/services/ai/AIServiceProvider.tsx	React context/provider for AI service injection
apps/web/src/services/ai/AIService.ts	AI service interface + request/response types
apps/web/src/lib/staticProfileDescription.ts	Non-AI profile description generator (server parity)
apps/web/src/lib/profileValidator.ts	Browser-side OEPF validation (server parity)
apps/web/src/lib/network-url.ts	Skips backend network IP discovery in direct mode
apps/web/src/lib/machineMode.ts	Detects direct vs proxy mode and default machine URL
apps/web/src/lib/machineMode.test.ts	Tests for mode detection + default URL
apps/web/src/lib/featureFlags.ts	Feature gating between proxy/direct deployments
apps/web/src/lib/featureFlags.test.ts	Tests for feature flag behavior/caching
apps/web/src/lib/directModeAI.ts	Client-side Gemini REST integration (direct mode)
apps/web/src/lib/config.ts	Direct-mode config defaults + BASE_URL-aware config fetch
apps/web/src/lib/config.test.ts	Adjusts config tests for mode/env setup
apps/web/src/index.css	iOS PWA safe-area padding adjustments
apps/web/src/i18n/config.ts	BASE_URL-aware locale loading path
apps/web/src/hooks/useMachineTelemetry.ts	Unified telemetry hook (proxy WS vs direct Socket.IO)
apps/web/src/hooks/useMachineService.ts	Re-export hook from service context
apps/web/src/components/SettingsView.tsx	Direct-mode localStorage settings + feature-gated sections
apps/web/src/components/RunShotView.tsx	Feature-gates scheduling UI and adjusts navigation behavior
apps/web/src/components/ProfileCatalogueView.tsx	Adds direct-mode UI affordances (click-to-view, short descriptions, image URLs)
apps/web/src/components/ProfileBreakdown.tsx	Hardens handling of missing keys / dynamics formats
apps/web/src/components/PourOverView.tsx	Null-safe recipe preference reads
apps/web/src/components/MeticAILogo.tsx	BASE_URL-aware logo asset paths
apps/web/src/components/LiveShotView.tsx	Disables image-proxy usage in direct mode
apps/web/src/components/ControlCenterExpanded.tsx	Disables image-proxy usage in direct mode
apps/web/src/components/ControlCenter.tsx	Disables image-proxy usage in direct mode
apps/web/src/components/BetaBanner.tsx	Skips backend beta status fetch in direct mode
apps/web/src/App.tsx	Switches to unified telemetry, adds storage migration, direct-mode routing
apps/web/public/manifest.json	Makes manifest start/scope + icon paths relative for subpath hosting
apps/web/public/locales/en/translation.json	Adds new keys for “done” and profile catalogue messages
apps/web/public/locales/sv/translation.json	Adds new keys for “done” and profile catalogue messages
apps/web/public/locales/de/translation.json	Adds new keys for “done” and profile catalogue messages
apps/web/public/locales/es/translation.json	Adds new keys for “done” and profile catalogue messages
apps/web/public/locales/fr/translation.json	Adds new keys for “done” and profile catalogue messages
apps/web/public/locales/it/translation.json	Adds new keys for “done” and profile catalogue messages
apps/web/package.json	Adds direct/proxy build scripts, direct-mode tests, new deps (genai, espresso-api, idb, etc.)
apps/web/index.html	Updates manifest comment (but still references manifest)
apps/web/.gitignore	Ignores generated meticai-web.tar.gz
MACHINE_PWA.md	Documentation for installing/running machine-hosted PWA
.github/workflows/tests.yml	Adds direct-mode test run in CI
.github/workflows/build-machine-pwa.yml	New workflow to build and upload machine PWA artifact
.github/workflows/auto-release.yml	Attaches machine PWA tarball to GitHub releases
.github/skills/testing.md	Fixes Docker compose command formatting

[Copilot]

Pull request overview

Copilot reviewed 67 out of 69 changed files in this pull request and generated 9 comments.

[Copilot]

generateImage() throws generic Error instances with user-facing English messages (“No image generated”, “No image data in response”). Elsewhere this service uses typed AIServiceError codes so the UI can translate. For consistency (and i18n), throw AIServiceError with a specific code here as well, or map these cases to an existing code.

[hessius]

✅ Resolved in c8cc045. Added IMAGE_GENERATION_FAILED and IMAGE_NO_DATA to AIErrorCode type union. Both throw new Error() calls replaced with throw new AIServiceError() — consistent with the typed error pattern used throughout the service.

[Copilot]

Direct-mode settings read/write uses string literals for localStorage keys ('meticai-gemini-key', 'meticai-author-name'). This duplicates the new STORAGE_KEYS single-source-of-truth and risks future key drift. Import STORAGE_KEYS and use STORAGE_KEYS.GEMINI_API_KEY / STORAGE_KEYS.AUTHOR_NAME instead.

[hessius]

✅ Resolved in c8cc045. Imported STORAGE_KEYS from @/lib/constants and replaced all hard-coded 'meticai-gemini-key' / 'meticai-author-name' string literals in the loadSettings path with STORAGE_KEYS.GEMINI_API_KEY / STORAGE_KEYS.AUTHOR_NAME.

[Copilot]

Direct-mode handleSave() persists to localStorage using hard-coded keys ('meticai-gemini-key', 'meticai-author-name'). To avoid mismatches with other direct-mode code, use the shared STORAGE_KEYS constants here too.

[hessius]

✅ Resolved in c8cc045. Same fix applied to handleSave() — all localStorage.setItem() calls now use STORAGE_KEYS constants.

[Copilot]

The provider’s connect/disconnect effect is gated on value.name === 'DirectAdapter', which is a brittle string check (and won’t run for custom direct implementations). Since MachineService always defines connect()/disconnect() and MeticAIAdapter.connect() is a safe no-op, consider connecting based on getMachineMode() (or just always calling connect()/disconnect() in the effect) instead of relying on the name string.

[hessius]

✅ Resolved in c8cc045. Removed the value.name === 'DirectAdapter' guard. The effect now always calls connect()/disconnect() — MeticAIAdapter.connect() is a documented safe no-op (async () => {}), so this works correctly for both adapters and any future implementations.

[Copilot]

connect() calls setupSocketListeners() every time, and setupSocketListeners() only ever adds socket.on(...) handlers (no off() / guard). If the provider remounts or connect() is called again (e.g. React StrictMode double-invokes effects in dev), handlers can accumulate and callbacks will fire multiple times. Add an idempotency guard (e.g. listenersAttached ref) and/or remove listeners in disconnect() via socket.off(...).

[hessius]

✅ Resolved in c8cc045. Added socket.removeAllListeners() at the top of setupSocketListeners() before registering handlers. This prevents listener accumulation on reconnect or React StrictMode double-invocation.

[Copilot]

update-meticai.sh delegates to "${SCRIPT_DIR}/install-meticai.sh", but that script is not present under scripts/machine/ (or elsewhere in scripts/). As written, the updater will always fail with “No such file or directory”. Point it at the actual installer (scripts/install-direct.sh) or add the missing install-meticai.sh to the repo and ensure paths match.

[hessius]

✅ Resolved in c8cc045. install-meticai.sh does not exist in scripts/machine/. Updated the reference to ${SCRIPT_DIR}/../install-direct.sh which is the actual installer script (236 lines, handles backup/download/extract).

[Copilot]

The onProgress events emit hard-coded English message strings (e.g. “Preparing prompt...”), and LoadingView renders progress.message directly. This makes the UI non-localizable in direct mode. Consider emitting a stable message key/code (or just phase + params) from the service and translating via t() in the UI layer.

[hessius]

✅ Resolved in c8cc045. BrowserAIService now emits i18n keys (e.g. generation.progress.preparingPrompt) instead of English strings. LoadingView translates via t(progress.message, { defaultValue: progress.message }) — i18n keys get translated, while server SSE messages (English) fall through as-is. Added all 5 progress keys to all 6 locales.

Note: In the current direct mode flow, onProgress is not wired up (the fetch interceptor doesn't pass it), so this is forward-looking. The keys are ready for when progress is plumbed through.

[Copilot]

In direct mode this fetches /api/v1/profile/get/${profileId} from the current origin to derive final_weight. That works for machine-hosted PWA, but the adapter is also intended for Capacitor/other direct deployments where the machine base URL may be different. Prefer using machine.getProfile(profileId) (which is already baseUrl-aware) and add a simple cancellation guard so an in-flight request can’t setState after unmount.

[hessius]

✅ Resolved in c8cc045. Replaced the raw fetch('/api/v1/profile/get/${profileId}') with machine.getProfile(profileId) — the machine service is already available in the hook via useMachineService(). This works correctly across all deployment modes (machine PWA uses DirectAdapter → espresso-api, Capacitor will use the same adapter with a configurable base URL).

[Copilot]

The interface header comment says the proxy implementation is ProxyAdapter, but the actual proxy implementation in this PR is MeticAIAdapter (and there’s no ProxyAdapter module). Update the comment to match the real implementation name to avoid confusion for future contributors.

[hessius]

✅ Resolved in c8cc045. Updated the JSDoc header comment: ProxyAdapter → MeticAIAdapter to match the actual implementation name.