Redactosaurus Desktop App

Desktop control panel for Redactosaurus. This app runs as an Electron application with a React UI and manages the local native host lifecycle, service state, and browser-extension bridge.

What This App Does

• Provides a desktop dashboard to view and control Redactosaurus protection state.
• Connects to the local native host and reports host status.
• Tracks browser extension connectivity.
• Lets users configure protected/chat domains and mode settings.
• Runs a local extension bridge endpoint for extension-to-desktop communication.
• Supports tray behavior and Windows startup/warmup workflows.

Tech Stack

• Electron (main process + preload)
• React 18 + TypeScript (renderer)
• Vite 5 (bundling/dev server)
• Tailwind CSS 4
• Radix UI primitives
• electron-builder (packaging)

Prerequisites

• Node.js 20+ (recommended)
• npm 10+ (recommended)
• Windows, macOS, or Linux for development

Quick Start

1. Install dependencies:

npm install

2. Start development mode:

npm run dev

3. Build and package the app:

npm run build

The packaged artifacts are written to release/<version>/.

Available Scripts

• npm run dev

  • Starts Vite development mode with Electron integration.
  • Best for local UI and desktop behavior development.

• npm run build

  • Runs TypeScript checks, builds renderer assets, then packages with electron-builder.
  • Outputs app installers/bundles in release/<version>/.

• npm run lint

  • Runs ESLint across TypeScript/TSX files.

• npm run preview

  • Runs Vite preview for renderer output.

Project Layout

electron/
  main.ts           # Electron entry point
  preload.ts        # Secure preload bridge

src/
  components/       # Dashboard and UI components
  hooks/            # Renderer hooks for service, extension, domains, top-bar state
  lib/              # Shared constants and helpers
  main/             # Main-process service modules
    electron/       # Electron-specific controllers (tray, IPC, autostart, bridge)

dist-electron/      # Built Electron output
dist/               # Built renderer output
release/            # Packaged installers/artifacts

Runtime Behavior

• On startup, the app resolves a launch URL in this order:

  1. ELECTRON_START_URL
  2. VITE_DEV_SERVER_URL (development)
  3. bundled dist/index.html (production)

• Runtime config/state files are maintained under local app data (Windows example):

  • Redactosaurus/config.json
  • Redactosaurus/status.json

• Desktop development mode can be influenced with:

  • REDACTOSAURUS_DESKTOP_ENV (development, dev, local, production, prod)

Packaging

Build and packaging are configured in electron-builder.json5.

• App name: Redactosaurus
• Output folder: release/${version}
• Included build folders: dist, dist-electron
• Targets:
  • Windows: NSIS installer (x64)
  • macOS: DMG
  • Linux: AppImage

Development Notes

• Path alias @/ points to src/.
• TypeScript strict mode is enabled.
• Main process code lives in electron/ and src/main/.
• Renderer code lives in src/.

Troubleshooting

• App opens blank page:

  • Ensure npm run dev is running, or confirm dist/index.html exists after build.

• Native host appears disconnected:

  • Check whether the host process is installed/running.
  • Verify local runtime files in the Redactosaurus local app data directory.

• Port binding issues for extension bridge:

  • Ensure no other local process is occupying the configured bridge port.

License

Apache-2.0