instbyte 1.9.4 → 1.11.0

package/README.md

@@ -21,11 +21,13 @@
 npx instbyte
 ```
 
-**Instbyte** is a high-speed, real-time, short-lived LAN sharing utility built for teams and developers who need to move snippets, links, files, and structured notes across devices instantly — without cloud accounts, logins, or external services.
+You're three feet from your teammate. *A quick share* still leaves your building before it reaches them.
 
-It operates entirely on your local network, acting as a lightweight "digital dead-drop" for frictionless collaboration.
+Your chat app is for conversation. Your cloud storage is for files. Your email is for async.
 
-Instbyte can also be fully white-labelled — the difference between ***a tool you use*** and ***a tool you own***.
+None of them are for *right now, on this network, gone tomorrow.*
+
+That's what **Instbyte** is for.
 
 ---
 
@@ -102,147 +104,19 @@ For teams who want auth, custom retention, or branding — create `instbyte.conf
 
 Then run `npx instbyte` in the same directory. The config is picked up automatically.
 
-### Keeping It Running
-For persistent team use, run it as a background process:
-
-```bash
-# using pm2
-npm install -g pm2
-pm2 start "npx instbyte" --name instbyte
-pm2 save
-```
-
-Or use any process manager you already have — systemd, screen, tmux.
+For persistent deployment options including pm2, systemd, and Docker, see the [Deployment Guide](docs/deployment.md).
 
 ---
 
 ## Docker
 
-The fastest way to run Instbyte with Docker:
-```bash
-docker compose up -d
-```
-
-Or with plain Docker:
-```bash
-docker run -d \
-  -p 3000:3000 \
-  -v $(pwd)/instbyte-data:/data \
-  -e INSTBYTE_DATA=/data \
-  -e INSTBYTE_UPLOADS=/data/uploads \
-  --name instbyte \
-  mohitgauniyal/instbyte
-```
-
-Data persists in `./instbyte-data` on your host. The same folder used by `npx instbyte` — so switching between the two preserves all your data.
-
-### With a config file
-
-Mount your config file into the container:
-```yaml
-services:
-  instbyte:
-    image: mohitgauniyal/instbyte
-    ports:
-      - "3000:3000"
-    volumes:
-      - ./instbyte-data:/data
-      - ./instbyte.config.json:/app/instbyte.config.json
-    environment:
-      - INSTBYTE_DATA=/data
-      - INSTBYTE_UPLOADS=/data/uploads
-    restart: unless-stopped
-```
-
-### Changing the port
-
-Edit the host port in `docker-compose.yml`:
-```yaml
-ports:
-  - "8080:3000"  # now runs on port 8080
-```
-
-> **Note:** File uploads may not work correctly on Windows Docker Desktop due to network limitations. For Windows, use `npx instbyte` directly or deploy on a Linux server.
+For Docker setup, persistent data, and config file mounting, see [Deployment Guide](docs/deployment.md).
 
 ---
 
 ## Reverse Proxy
 
-For teams who want to access Instbyte over HTTPS or from outside their local network, running it behind a reverse proxy is the standard approach.
-
-> **Important:** Instbyte uses WebSockets for real-time sync. Your proxy must be configured to forward WebSocket connections — otherwise the app will load but live updates will stop working.
-
-### Nginx
-```nginx
-server {
-    listen 80;
-    server_name instbyte.yourdomain.com;
-
-    # Redirect HTTP to HTTPS
-    return 301 https://$host$request_uri;
-}
-
-server {
-    listen 443 ssl;
-    server_name instbyte.yourdomain.com;
-
-    ssl_certificate     /etc/letsencrypt/live/instbyte.yourdomain.com/fullchain.pem;
-    ssl_certificate_key /etc/letsencrypt/live/instbyte.yourdomain.com/privkey.pem;
-
-    # Increase max upload size to match Instbyte's limit
-    client_max_body_size 2G;
-
-    location / {
-        proxy_pass http://localhost:3000;
-        proxy_http_version 1.1;
-
-        # Required for WebSocket support
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection "upgrade";
-
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-
-        # Prevent proxy timeouts on large uploads
-        proxy_read_timeout 300s;
-        proxy_send_timeout 300s;
-    }
-}
-```
-
-Get a free SSL certificate with Certbot:
-```bash
-certbot --nginx -d instbyte.yourdomain.com
-```
-
-### Caddy
-
-Caddy automatically handles HTTPS certificates — no Certbot needed.
-```caddy
-instbyte.yourdomain.com {
-    reverse_proxy localhost:3000
-}
-```
-
-Caddy handles WebSocket forwarding and HTTPS automatically. That's all you need.
-
-### With Docker
-
-If running Instbyte via Docker, proxy to the mapped host port:
-```nginx
-proxy_pass http://localhost:3000;
-```
-
-Or use Docker's internal network — replace `localhost` with the container name:
-```nginx
-proxy_pass http://instbyte:3000;
-```
-
-### Keeping it LAN-only
-
-If you don't want external access but still want HTTPS on your local network, tools like [Tailscale](https://tailscale.com) or [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) are good options that require no open ports.
+For Nginx, Caddy, and HTTPS setup, see [Deployment Guide](docs/deployment.md).
 
 ---
 
@@ -305,6 +179,8 @@ The difference between *a tool you use* and *a tool you own.*
 
 **Presence awareness** — see how many people are currently connected in real time.
 
+**Live broadcast** — share your screen in real time with everyone on the network. Viewers join instantly from their browser, no plugins or installs needed. Built on WebRTC for smooth, low-latency video. Includes mic audio, viewer mute/unmute, raise hand, and screen capture to channel.
+
 **Read receipts** — see how many devices have viewed each shared item. Updates live as teammates open the page.
 
 **Item management** — add optional titles to label any item for future reference. Edit text items inline without deleting and re-pasting. Pinned items are protected from both manual deletion and auto-cleanup.
@@ -315,8 +191,19 @@ The difference between *a tool you use* and *a tool you own.*
 
 ---
 
+## Broadcasting
+
+One person shares their screen — everyone else on the network watches live in their browser. No plugins, no accounts, no external services. Built on WebRTC.
+
+Viewers can save the current frame to a channel, raise a hand to notify the broadcaster, and toggle audio from the panel.
+
+For HTTPS setup and advanced network configuration, see the [Deployment Guide](docs/deployment.md#broadcasting).
+
+---
+
 ## Keyboard Shortcuts
 
+```
 | Key | Action |
 |---|---|
 | `/` | Focus search |
@@ -346,40 +233,13 @@ node server/server.js
 - Home lab file sharing without setting up NAS or cloud sync
 - Piping build logs or stack traces from CI or terminal directly into a shared channel
 - Sharing sensitive credentials or config files over LAN without leaving a cloud trail
+- Live screen sharing during standups, design reviews, or debugging sessions — no Zoom link needed
 
 ---
 
 ## Terminal Usage
 
-Since Instbyte exposes a simple HTTP API, you can push content directly from your terminal using `curl` — no browser needed.
-
-**Send a log file:**
-```bash
-curl -X POST http://192.168.x.x:3000/text \
-  -H "Content-Type: application/json" \
-  -d "{\"content\": \"$(cat error.log)\", \"channel\": \"general\", \"uploader\": \"terminal\"}"
-```
-
-**Pipe command output directly:**
-```bash
-npm run build 2>&1 | curl -X POST http://192.168.x.x:3000/text \
-  -H "Content-Type: application/json" \
-  --data-binary @-  \
-  -H "X-Channel: general" \
-  -H "X-Uploader: CI"
-```
-
-**Upload a file from the terminal:**
-```bash
-curl -X POST http://192.168.x.x:3000/upload \
-  -F "file=@./build.log" \
-  -F "channel=general" \
-  -F "uploader=terminal"
-```
-
-Replace `192.168.x.x:3000` with the URL shown when Instbyte starts. If auth is enabled, add `-b "instbyte_auth=your-token"` to each request.
-
-Useful for piping stack traces, build logs, or environment dumps straight into a channel your whole team can see instantly.
+Push content from your terminal using curl — no browser needed. See [Terminal Usage Guide](docs/terminal-usage.md).
 
 ---
 
@@ -393,7 +253,7 @@ Instbyte follows [Semantic Versioning](https://semver.org). See [Releases](https
 
 Instbyte is intentionally lightweight and LAN-first. If you want to extend it — CLI tools, themes, integrations — open an issue or submit a pull request.
 
-The codebase has a full test suite (184 tests across unit and integration). Run `npm test` before submitting anything. Issues tagged **good first issue** are a good starting point.
+The codebase has a full test suite (195 tests across unit and integration). Run `npm test` before submitting anything. Issues tagged **good first issue** are a good starting point.
 
 ---
 

package/bin/instbyte.js

@@ -11,18 +11,27 @@ const fs = require("fs");
 // When run via npx or global install, we want data to live
 // in the user's current working directory, not inside the
 // npm cache or global node_modules.
+//
+// When run via Docker, INSTBYTE_DATA and INSTBYTE_UPLOADS may
+// already be set via environment variables — respect those and
+// don't override them.
 
-const dataDir = path.join(process.cwd(), "instbyte-data");
-const uploadsDir = path.join(dataDir, "uploads");
+if (!process.env.INSTBYTE_DATA) {
+    process.env.INSTBYTE_DATA = path.join(process.cwd(), "instbyte-data");
+}
+
+if (!process.env.INSTBYTE_UPLOADS) {
+    process.env.INSTBYTE_UPLOADS = path.join(process.env.INSTBYTE_DATA, "uploads");
+}
+
+const dataDir = process.env.INSTBYTE_DATA;
+const uploadsDir = process.env.INSTBYTE_UPLOADS;
 
 if (!fs.existsSync(dataDir)) fs.mkdirSync(dataDir, { recursive: true });
 if (!fs.existsSync(uploadsDir)) fs.mkdirSync(uploadsDir, { recursive: true });
 
-// Pass locations to the rest of the app via env vars
-process.env.INSTBYTE_DATA = dataDir;
-process.env.INSTBYTE_UPLOADS = uploadsDir;
-
 // ========================
 // BOOT
 // ========================
+process.env.INSTBYTE_BOOT = '1';
 require("../server/server.js");

package/client/css/app.css

@@ -1079,6 +1079,264 @@ input[type=text]:focus {
     transition: background 1.5s ease, border-color 1.5s ease;
 }
 
+/* ============================================================
+   BROADCAST
+   ============================================================ */
+
+/* Bar — sits below header, visible to all when live */
+.broadcast-bar {
+    background: #111827;
+    color: #fff;
+    padding: 8px 20px;
+    position: sticky;
+    top: 0;
+    z-index: 100;
+    border-bottom: 1px solid #1f2937;
+}
+
+.broadcast-bar-inner {
+    max-width: 900px;
+    margin: 0 auto;
+    display: flex;
+    align-items: center;
+    gap: 10px;
+}
+
+.broadcast-pulse {
+    display: inline-block;
+    width: 8px;
+    height: 8px;
+    background: #ef4444;
+    border-radius: 50%;
+    flex-shrink: 0;
+    animation: broadcastPulse 1.5s ease-in-out infinite;
+}
+
+@keyframes broadcastPulse {
+
+    0%,
+    100% {
+        opacity: 1;
+        transform: scale(1);
+    }
+
+    50% {
+        opacity: 0.4;
+        transform: scale(0.85);
+    }
+}
+
+#broadcastLabel {
+    font-size: 13px;
+    font-weight: 500;
+    flex: 1;
+}
+
+.broadcast-viewers {
+    font-size: 12px;
+    color: #9ca3af;
+}
+
+.broadcast-bar-actions {
+    display: flex;
+    gap: 8px;
+}
+
+.broadcast-join-btn {
+    background: #2563eb;
+    color: #fff;
+    border: none;
+    border-radius: 6px;
+    padding: 5px 14px;
+    font-size: 13px;
+    cursor: pointer;
+}
+
+.broadcast-join-btn:hover {
+    background: #1d4ed8;
+}
+
+.broadcast-end-btn {
+    background: #ef4444;
+    color: #fff;
+    border: none;
+    border-radius: 6px;
+    padding: 5px 14px;
+    font-size: 13px;
+    cursor: pointer;
+}
+
+.broadcast-end-btn:hover {
+    background: #dc2626;
+}
+
+/* Start button in composer */
+.broadcast-start-btn {
+    background: #374151;
+    color: #fff;
+    border: none;
+    border-radius: 6px;
+    padding: 10px 14px;
+    font-size: 13px;
+    cursor: pointer;
+    white-space: nowrap;
+}
+
+.broadcast-start-btn:hover {
+    background: #4b5563;
+}
+
+.broadcast-start-btn.is-live {
+    background: #ef4444;
+}
+
+.broadcast-start-btn.is-live:hover {
+    background: #dc2626;
+}
+
+/* ─── VIEWER PANEL ─────────────────────────────────────────── */
+
+.viewer-panel {
+    position: fixed;
+    top: 60px;
+    right: 20px;
+    width: 480px;
+    max-width: calc(100vw - 40px);
+    background: #fff;
+    border: 1px solid #e5e7eb;
+    border-radius: 12px;
+    box-shadow: 0 8px 32px rgba(0, 0, 0, 0.15);
+    z-index: 500;
+    display: flex;
+    flex-direction: column;
+    overflow: auto;
+    resize: both;
+    min-width: 280px;
+    min-height: 200px;
+}
+
+.viewer-panel-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 10px 14px;
+    background: #f9fafb;
+    border-bottom: 1px solid #e5e7eb;
+    flex-shrink: 0;
+    cursor: grab;
+    user-select: none;
+}
+
+.viewer-panel-header:active {
+    cursor: grabbing;
+}
+
+.viewer-minimize-btn {
+    background: #f3f4f6;
+    border: 1px solid #e5e7eb;
+    border-radius: 6px;
+    padding: 4px 10px;
+    font-size: 12px;
+    cursor: pointer;
+    color: #374151;
+}
+
+.viewer-minimize-btn:hover {
+    background: #fef9c3;
+    border-color: #fde68a;
+    color: #92400e;
+}
+
+.viewer-panel.minimized .viewer-frame,
+.viewer-panel.minimized .viewer-panel-actions .viewer-capture-btn,
+.viewer-panel.minimized .viewer-panel-actions .viewer-raise-btn,
+.viewer-panel.minimized .viewer-panel-actions .viewer-close-btn {
+    display: none;
+}
+
+.viewer-panel.minimized {
+    min-height: unset;
+    resize: none;
+}
+
+#viewerLabel {
+    font-size: 13px;
+    font-weight: 600;
+    color: #111827;
+}
+
+.viewer-panel-actions {
+    display: flex;
+    gap: 6px;
+}
+
+.viewer-capture-btn,
+.viewer-raise-btn,
+.viewer-close-btn {
+    background: #f3f4f6;
+    border: 1px solid #e5e7eb;
+    border-radius: 6px;
+    padding: 4px 10px;
+    font-size: 12px;
+    cursor: pointer;
+    color: #374151;
+}
+
+.viewer-capture-btn:hover {
+    background: #dbeafe;
+    border-color: #bfdbfe;
+    color: #1d4ed8;
+}
+
+.viewer-raise-btn:hover {
+    background: #fef9c3;
+    border-color: #fde68a;
+    color: #92400e;
+}
+
+.viewer-close-btn:hover {
+    background: #fee2e2;
+    border-color: #fecaca;
+    color: #b91c1c;
+}
+
+.viewer-frame {
+    width: 100%;
+    display: block;
+    background: #0f1117;
+    min-height: 180px;
+    object-fit: contain;
+}
+
+/* ─── RAISE HAND TOAST ─────────────────────────────────────── */
+
+.raise-hand-toast {
+    position: fixed;
+    bottom: 80px;
+    left: 50%;
+    transform: translateX(-50%);
+    background: #111827;
+    color: #fff;
+    padding: 8px 16px;
+    border-radius: 20px;
+    font-size: 13px;
+    z-index: 9999;
+    pointer-events: none;
+    animation: raiseHandIn 0.2s ease;
+}
+
+@keyframes raiseHandIn {
+    from {
+        opacity: 0;
+        transform: translateX(-50%) translateY(8px);
+    }
+
+    to {
+        opacity: 1;
+        transform: translateX(-50%) translateY(0);
+    }
+}
+
 /* ============================================================
    MOBILE
    ============================================================ */
@@ -1322,6 +1580,36 @@ input[type=text]:focus {
             transform: translateY(0);
         }
     }
+
+    .broadcast-bar {
+        padding: 8px 12px;
+    }
+
+    .broadcast-bar-inner {
+        gap: 8px;
+    }
+
+    #broadcastLabel {
+        font-size: 12px;
+    }
+
+    .broadcast-start-btn {
+        display: none;
+    }
+
+    .viewer-panel {
+        position: fixed;
+        top: auto;
+        bottom: 0;
+        left: 0;
+        right: 0;
+        width: 100%;
+        max-width: 100%;
+        border-radius: 16px 16px 0 0;
+        resize: none;
+        max-height: 85vh;
+    }
+
 }
 
 
@@ -1728,6 +2016,45 @@ input[type=text]:focus {
             background: #1a1d27 !important;
             color: #e5e7eb !important;
         }
+
+        .broadcast-bar {
+            background: #0f1117;
+            border-bottom-color: #1f2937;
+        }
+
+        .broadcast-start-btn {
+            background: #1f2937;
+        }
+
+        .broadcast-start-btn:hover {
+            background: #374151;
+        }
+
+        .viewer-panel {
+            background: #1e2433;
+            border-color: #2d3748;
+        }
+
+        .viewer-panel-header {
+            background: #161b27;
+            border-bottom-color: #2d3748;
+        }
+
+        #viewerLabel {
+            color: #f9fafb;
+        }
+
+        .viewer-capture-btn,
+        .viewer-raise-btn,
+        .viewer-close-btn {
+            background: #2d3748;
+            border-color: #374151;
+            color: #d1d5db;
+        }
+
+        .raise-hand-toast {
+            background: #1f2937;
+        }
     }
 }
 
@@ -2126,4 +2453,43 @@ input[type=text]:focus {
         background: #1a1d27 !important;
         color: #e5e7eb !important;
     }
+
+    .broadcast-bar {
+        background: #0f1117;
+        border-bottom-color: #1f2937;
+    }
+
+    .broadcast-start-btn {
+        background: #1f2937;
+    }
+
+    .broadcast-start-btn:hover {
+        background: #374151;
+    }
+
+    .viewer-panel {
+        background: #1e2433;
+        border-color: #2d3748;
+    }
+
+    .viewer-panel-header {
+        background: #161b27;
+        border-bottom-color: #2d3748;
+    }
+
+    #viewerLabel {
+        color: #f9fafb;
+    }
+
+    .viewer-capture-btn,
+    .viewer-raise-btn,
+    .viewer-close-btn {
+        background: #2d3748;
+        border-color: #374151;
+        color: #d1d5db;
+    }
+
+    .raise-hand-toast {
+        background: #1f2937;
+    }
 }

package/client/index.html

@@ -37,6 +37,34 @@
     </div>
   </header>
 
+  <div id="broadcastBar" class="broadcast-bar" style="display:none">
+    <div class="broadcast-bar-inner">
+      <span class="broadcast-pulse"></span>
+      <span id="broadcastLabel">Someone is broadcasting</span>
+      <span id="broadcastViewers" class="broadcast-viewers"></span>
+      <div class="broadcast-bar-actions">
+        <button id="broadcastJoinBtn" class="broadcast-join-btn" onclick="joinBroadcast()">Join</button>
+        <button id="broadcastEndBtn" class="broadcast-end-btn" onclick="stopBroadcast()" style="display:none">End
+          broadcast</button>
+      </div>
+    </div>
+  </div>
+
+  <div id="viewerPanel" class="viewer-panel" style="display:none">
+    <div class="viewer-panel-header">
+      <span id="viewerLabel">Broadcast</span>
+      <div class="viewer-panel-actions">
+        <button onclick="captureToChannel()" class="viewer-capture-btn" title="Save frame to channel">📸
+          Capture</button>
+        <button onclick="raiseHand()" class="viewer-raise-btn" title="Raise hand">✋</button>
+        <button onclick="toggleAudio()" class="viewer-audio-btn" id="audioToggleBtn" title="Unmute audio">🔇</button>
+        <button onclick="toggleMinimize()" class="viewer-minimize-btn" title="Minimize">─</button>
+        <button onclick="leaveBroadcast()" class="viewer-close-btn" title="Leave broadcast">✕</button>
+      </div>
+    </div>
+    <video id="viewerFrame" class="viewer-frame" autoplay playsinline muted></video>
+  </div>
+
   <div class="container">
     <div class="channel-bar">
       <div class="channels" id="channels"></div>
@@ -49,6 +77,9 @@
       <button onclick="sendText()">Send</button>
       <input type="file" id="fileInput" hidden multiple>
       <button onclick="fileInput.click()">Upload</button>
+      <button id="startBroadcastBtn" onclick="startBroadcast()" class="broadcast-start-btn"
+        title="Start broadcasting your screen">📡 Broadcast</button>
+
     </div>
     <div class="drop" id="drop">Drag files anywhere to upload</div>
     <div id="uploadStatus"