First commit for bicorder-app

2025-11-25 13:20:21 -05:00
parent 3a55d3dbb9
commit b541f6049e
24 changed files with 8883 additions and 0 deletions
--- a/bicorder-app/README.md
+++ b/bicorder-app/README.md
@@ -0,0 +1,150 @@
+# 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.
+
+[![Hippocratic License HL3-CORE](https://img.shields.io/static/v1?label=Hippocratic%20License&message=HL3-CORE&labelColor=5e2751&color=bc8c3d)](https://firstdonoharm.dev/version/3/0/core.html)