151 lines
5.2 KiB
Markdown
151 lines
5.2 KiB
Markdown
# Protocol Bicorder - Web App
|
|
|
|
A Svelte Progressive Web App (PWA) for carrying out protocol diagnostics as defined in `../bicorder.json`.
|
|
|
|
## Features
|
|
|
|
- **Single-page diagnostic tool** with ASCII-styled interface
|
|
- **Touch-friendly controls** optimized for mobile devices
|
|
- **Shortform toggle** - switch between full (23 gradients) and short (10 gradients) versions
|
|
- **Tooltips** on all gradient terms (long-press on mobile, hover on desktop)
|
|
- **Editable metadata** fields with auto-generated timestamps
|
|
- **Auto-calculated analysis** section (hardness/softness, polarized/centrist)
|
|
- **Citation support** for each gradient value
|
|
- **Local storage** - your progress is automatically saved
|
|
- **Export to JSON** - download your completed diagnostic
|
|
- **Share functionality** - use Web Share API on supported devices
|
|
- **Public upload** - submit readings directly to the public repository
|
|
- **Full PWA** - installable, works offline
|
|
- **Privacy-focused** - no telemetry, no external fonts, works completely offline
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Start development server (http://localhost:5173)
|
|
npm run dev
|
|
|
|
# Build for production
|
|
npm run build
|
|
|
|
# Preview production build (http://localhost:4173)
|
|
npm run preview
|
|
```
|
|
|
|
**Important:** The app must be served via HTTP/HTTPS (not opened directly as `file://`). Modern browsers block ES modules and service workers from the file protocol for security reasons. Always use `npm run preview` or deploy to a web server to test the built app.
|
|
|
|
## Build Process
|
|
|
|
The app reads `../bicorder.json` at build time and constructs the interface based on its structure. To update the diagnostic:
|
|
|
|
1. Edit `../bicorder.json`
|
|
2. Run `npm run update` (or `npm run build`)
|
|
3. The app will automatically reflect the new structure
|
|
|
|
Alternatively, run `./update-diagnostic.sh` for a friendlier update experience.
|
|
|
|
## Deployment
|
|
|
|
The built app is in the `dist/` folder. You can deploy it to any static hosting service:
|
|
|
|
- **GitHub Pages**: Push the dist folder
|
|
- **Netlify**: Connect your repo and set build command to `npm run build`
|
|
- **Vercel**: Same as Netlify
|
|
- **Static server**: Copy the dist folder contents to your web server
|
|
|
|
### Quick local server options
|
|
|
|
If you don't have Node.js available, you can serve the `dist/` folder with:
|
|
|
|
```bash
|
|
# Use the provided script (tries Python/PHP automatically)
|
|
./serve-local.sh
|
|
|
|
# Or manually:
|
|
# Python 3
|
|
python3 -m http.server 8000 --directory dist
|
|
|
|
# PHP
|
|
php -S localhost:8000 -t dist
|
|
|
|
# Any other static file server
|
|
```
|
|
|
|
Then open http://localhost:8000 in your browser.
|
|
|
|
## Usage
|
|
|
|
### Filling out the diagnostic
|
|
|
|
1. Fill in the metadata fields (Protocol, Analyst, Standpoint)
|
|
2. **Toggle shortform mode** (optional) to show only the 10 core gradients
|
|
3. For each gradient, tap/click the numbered buttons (1-9) to set values
|
|
- 1 = strongly toward the left term
|
|
- 5 = balanced/neutral
|
|
- 9 = strongly toward the right term
|
|
4. Optionally add citations for each gradient value
|
|
5. The Analysis section is automatically calculated based on your inputs
|
|
|
|
### Exporting and sharing results
|
|
|
|
- **Export JSON**: Downloads the diagnostic as a JSON file
|
|
- **Share**: Uses your device's share functionality (mobile)
|
|
- **Upload**: Submit your readings to the public repository
|
|
|
|
### Public upload
|
|
|
|
When you click **Upload**, your readings will be:
|
|
- Posted to the public repository: [protocol-bicorder-data](https://git.medlab.host/ntnsndr/protocol-bicorder-data)
|
|
- Licensed to the public domain (CC0)
|
|
- Committed with your analyst name and protocol name
|
|
- Stored in the `readings/` directory with a timestamp
|
|
|
|
All uploaded readings are public and available for research and analysis. By uploading, you consent to releasing your diagnostic under a public domain license.
|
|
|
|
## Browser Support
|
|
|
|
- Modern browsers (Chrome, Firefox, Safari, Edge)
|
|
- Mobile browsers (iOS Safari, Android Chrome)
|
|
- PWA installation supported on Android, iOS 16.4+, and desktop browsers
|
|
|
|
## Customization
|
|
|
|
### Styling
|
|
|
|
The app uses CSS custom properties for theming. Edit `src/app.css` to change colors:
|
|
|
|
```css
|
|
--bg-color: #000000; /* Background */
|
|
--fg-color: #00ff00; /* Foreground/text */
|
|
--border-color: #00ff00; /* Borders */
|
|
--hover-color: #00cc00; /* Hover states */
|
|
```
|
|
|
|
### Icons
|
|
|
|
Replace `public/icon.svg` with your own icon. For better PWA support, also generate PNG versions:
|
|
|
|
```bash
|
|
# Example using ImageMagick (if available)
|
|
convert -background none -resize 192x192 public/icon.svg public/icon-192.png
|
|
convert -background none -resize 512x512 public/icon.svg public/icon-512.png
|
|
```
|
|
|
|
Then update `vite.config.ts` to reference the PNG icons in the manifest.
|
|
|
|
## Architecture
|
|
|
|
- **Framework**: Svelte 4 with TypeScript
|
|
- **Build tool**: Vite 5
|
|
- **PWA**: vite-plugin-pwa with Workbox
|
|
- **State management**: Svelte stores + localStorage
|
|
- **Data source**: bicorder.json (build-time integration)
|
|
|
|
## Authorship and licensing
|
|
|
|
Initiated by [Nathan Schneider](https://nathanschneider.info) and available for use under the [Hippocratic License](https://firstdonoharm.dev/) (do no harm!). Several AI assistants, local and remote, were utilized in developing this tool.
|
|
|
|
[](https://firstdonoharm.dev/version/3/0/core.html)
|