pmptr 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jatin Krmalik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,189 @@
+# <img src="assets/icon.svg" height="40" align="center" /> pmptr
+
+[![Release](https://img.shields.io/github/v/release/jatinkrmalik/pmptr?include_prereleases)](https://github.com/jatinkrmalik/pmptr/releases)
+[![Build](https://github.com/jatinkrmalik/pmptr/actions/workflows/build.yml/badge.svg)](https://github.com/jatinkrmalik/pmptr/actions/workflows/build.yml)
+[![Release Pipeline](https://github.com/jatinkrmalik/pmptr/actions/workflows/release.yml/badge.svg)](https://github.com/jatinkrmalik/pmptr/actions/workflows/release.yml)
+[![Nightly](https://github.com/jatinkrmalik/pmptr/actions/workflows/nightly.yml/badge.svg)](https://github.com/jatinkrmalik/pmptr/actions/workflows/nightly.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macos%20%7C%20windows-blue)](https://github.com/jatinkrmalik/pmptr)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-339933)](https://nodejs.org)
+[![Electron](https://img.shields.io/badge/electron-31-47848F)](https://www.electronjs.org)
+
+> **Beta** — pmptr is in active beta. Expect occasional bugs and breaking changes.
+> Please [report issues](https://github.com/jatinkrmalik/pmptr/issues) you encounter.
+
+A minimal virtual teleprompter that lives as a transparent, always-on-top,
+click-through overlay over whatever you do on your screen.
+
+## Download
+
+Grab the latest build from the [Releases page](https://github.com/jatinkrmalik/pmptr/releases).
+
+| Platform | Format |
+|----------|--------|
+| macOS    | `.dmg` |
+| Windows  | `.exe` (NSIS installer) |
+| Linux    | `.AppImage` or `.deb` |
+
+Not code-signed — your OS may warn on first launch. That's expected during beta.
+
+## Install from npm
+
+If you have [Node.js](https://nodejs.org) installed, you can install `pmptr` globally and run it from your terminal:
+
+```bash
+npm install -g pmptr
+pmptr
+```
+
+Requires Node.js **20** or later.
+
+## Run from source
+
+```bash
+git clone https://github.com/jatinkrmalik/pmptr.git
+cd pmptr
+npm install
+npm start
+```
+
+Then click **Open floating prompter** in the control window.
+
+## Features
+
+- **Control window** — paste your script, tune speed, size, colors, opacity, mirror,
+  window dimensions, and more.
+- **Floating prompter window** — transparent, frameless, always on top, with
+  a true OS-level click-through "lock" so you can keep working with your mouse
+  on whatever is underneath.
+- Settings persist to disk in your Electron user-data folder.
+- Live updates: edits in the control window apply to the prompter instantly.
+
+## Shortcuts (in the floating window)
+
+| Key       | Action                                  |
+| --------- | --------------------------------------- |
+| `Space`   | Play / pause                            |
+| `R`       | Reset scroll to the top                 |
+| `↑` / `↓` | Speed ± 5 px/s                          |
+| `L`       | Toggle click-through (lock / unlock)   |
+| `Esc`     | Close the prompter                      |
+
+You can also use the small HUD in the bottom-right of the floating window
+(mouse over it to reveal it).
+
+## Architecture
+
+```mermaid
+graph TB
+    subgraph "Electron Main Process"
+        M[main.js]
+        SETTINGS[(settings.json)]
+    end
+
+    subgraph "Control Window"
+        CH[control.html]
+        CJ[control.js]
+    end
+
+    subgraph "Prompter Window"
+        PH[prompter.html]
+        PJ[prompter.js]
+    end
+
+    M -->|spawns| CH
+    M -->|spawns| PH
+    M <-->|save/load| SETTINGS
+    CJ -->|IPC: settings changed| M
+    M -->|IPC: settings| PH
+    PH -->|IPC: state| M
+    M -->|IPC: state| CJ
+```
+
+The app runs in two Electron `BrowserWindow` instances that communicate
+through IPC handlers in the main process. The control window is where you
+paste your script and adjust settings; the prompter window is the
+transparent, always-on-top overlay that scrolls the text. Settings are
+persisted to `settings.json` in the Electron user-data directory.
+
+## How the click-through works
+
+The prompter is a separate `BrowserWindow` with `transparent: true`, `frame: false`,
+and `alwaysOnTop: true`. When you toggle "click-through" (the lock), the main
+process calls `win.setIgnoreMouseEvents(true, { forward: true })` — clicks
+and wheel events fall straight through to whatever app is behind, while the
+window stays visible and keeps scrolling. The HUD itself is hidden while
+locked, so nothing on the prompter intercepts your pointer.
+
+## Tweaking transparency
+
+The window background is a CSS `rgba()` color set on `.frame`. Move the
+**Background opacity** slider to 0 for fully see-through, or use
+**Background dim** to keep it readable on bright content underneath. The text
+itself stays opaque.
+
+## Project layout
+
+```
+src/
+├── main/
+│   ├── main.js               Electron main: creates both windows, handles IPC,
+│   │                         click-through, always-on-top, position presets.
+│   └── preload.js            contextBridge for the control window.
+├── control/
+│   ├── control.html          The control panel UI.
+│   ├── control.js            Control panel logic.
+│   └── control.css           Control panel styles.
+└── prompter/
+    ├── prompter.html         The floating teleprompter overlay.
+    ├── prompter.js           Prompter logic (scroll, shortcuts, HUD).
+    ├── prompter.css          Prompter styles.
+    └── prompter-preload.js   contextBridge for the prompter window.
+
+assets/
+└── icon.svg                  Application icon.
+
+.github/workflows/
+── build.yml                 CI build for Linux, macOS, Windows.
+├── release.yml               Tag-triggered release pipeline.
+├── nightly.yml               Daily scheduled builds.
+└── pr-build.yml              Comment-triggered PR artifact builds.
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run the app
+npm start
+
+# Lint code
+npm run lint
+
+# Run tests (currently just lint)
+npm test
+
+# Build for distribution
+npm run build
+```
+
+## Known limitations
+
+- Wayland compositors vary in their support for `setIgnoreMouseEvents` and
+  `setAlwaysOnTop` (the underlying APIs Electron uses). X11 (Xorg) and recent
+  KDE / GNOME Wayland work fine; some lighter Wayland compositors may ignore
+  these hints. If click-through or always-on-top does not work, the prompter
+  is still useful — just drag it to a corner.
+- On macOS you may need to grant Accessibility / Screen Recording permissions
+  to the app for click-through to behave predictably across all apps.
+- The app is not code-signed. Your OS may warn on first launch.
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

package/assets/icon.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" fill="none">
+  <!-- Dark background -->
+  <rect width="512" height="512" rx="64" fill="#0f1115"/>
+  <!-- Screen -->
+  <rect x="96" y="144" width="320" height="224" rx="16" stroke="#ffffff" stroke-width="12"/>
+  <!-- Text lines -->
+  <path d="M144 208h224M144 256h224M144 304h224" stroke="#ffffff" stroke-width="8" stroke-linecap="round"/>
+  <!-- Play arrow -->
+  <path d="M336 344l-40 24v-48z" fill="#ffd84d"/>
+</svg>

package/bin/pmptr.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+const { spawn } = require('child_process');
+const path = require('path');
+const electron = require('electron');
+
+const appPath = path.join(__dirname, '..');
+const child = spawn(electron, [appPath], { stdio: 'inherit' });
+
+child.on('close', (code) => {
+  process.exit(code ?? 0);
+});

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "pmptr",
+  "version": "0.1.0",
+  "description": "A minimal virtual teleprompter that lives as a transparent, always-on-top, click-through overlay.",
+  "main": "src/main/main.js",
+  "bin": {
+    "pmptr": "bin/pmptr.js"
+  },
+  "files": [
+    "bin/**/*",
+    "src/**/*",
+    "assets/**/*"
+  ],
+  "author": {
+    "name": "Jatin Malik",
+    "email": "jatinkrmalik@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jatinkrmalik/pmptr.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jatinkrmalik/pmptr/issues"
+  },
+  "homepage": "https://github.com/jatinkrmalik/pmptr",
+  "scripts": {
+    "start": "electron .",
+    "lint": "eslint src/",
+    "test": "npm run lint",
+    "build": "electron-builder"
+  },
+  "build": {
+    "appId": "com.pmptr.app",
+    "productName": "pmptr",
+    "directories": {
+      "output": "dist"
+    },
+    "files": [
+      "bin/**/*",
+      "src/**/*",
+      "assets/**/*",
+      "package.json"
+    ],
+    "mac": {
+      "target": "dmg",
+      "icon": "assets/icon.png"
+    },
+    "win": {
+      "target": "nsis",
+      "icon": "assets/icon.png"
+    },
+    "linux": {
+      "target": [
+        "AppImage",
+        "deb"
+      ],
+      "icon": "assets/icon.png",
+      "category": "Utility"
+    }
+  },
+  "dependencies": {
+    "electron": "^31.0.0"
+  },
+  "devDependencies": {
+    "electron-builder": "^24.13.3",
+    "eslint": "^8.57.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "license": "MIT"
+}

package/src/control/control.css

@@ -0,0 +1,317 @@
+:root {
+  --bg: #0f1115;
+  --bg-2: #15181f;
+  --bg-3: #1c2029;
+  --fg: #e7eaf0;
+  --muted: #8a93a6;
+  --line: #262b36;
+  --accent: #7aa2ff;
+  --accent-2: #ffd84d;
+  --danger: #ff6b6b;
+  --ok: #6bd58a;
+  --radius: 10px;
+  --radius-sm: 6px;
+  --shadow: 0 1px 0 rgba(255, 255, 255, 0.03) inset, 0 6px 20px rgba(0, 0, 0, 0.35);
+  color-scheme: dark;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  margin: 0;
+  padding: 0;
+  background: var(--bg);
+  color: var(--fg);
+  font: 14px/1.45 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
+    "Helvetica Neue", Arial, sans-serif;
+  min-height: 100vh;
+  -webkit-font-smoothing: antialiased;
+}
+
+.topbar {
+  display: flex;
+  align-items: baseline;
+  gap: 12px;
+  padding: 14px 20px 6px;
+  border-bottom: 1px solid var(--line);
+}
+.brand {
+  font-weight: 700;
+  letter-spacing: 0.5px;
+}
+.sub {
+  color: var(--muted);
+  font-size: 12px;
+}
+
+.layout {
+  padding: 16px 20px 28px;
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+  max-width: 720px;
+  margin: 0 auto;
+}
+
+.card {
+  background: var(--bg-2);
+  border: 1px solid var(--line);
+  border-radius: var(--radius);
+  padding: 14px 16px 16px;
+  box-shadow: var(--shadow);
+}
+.card h2 {
+  margin: 0 0 10px;
+  font-size: 12px;
+  text-transform: uppercase;
+  letter-spacing: 1.2px;
+  color: var(--muted);
+  font-weight: 600;
+}
+.card-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 8px;
+}
+.card-head h2 {
+  margin: 0;
+}
+
+textarea#script {
+  width: 100%;
+  min-height: 180px;
+  max-height: 50vh;
+  resize: vertical;
+  background: var(--bg-3);
+  color: var(--fg);
+  border: 1px solid var(--line);
+  border-radius: var(--radius-sm);
+  padding: 10px 12px;
+  font: 14px/1.5 ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+  outline: none;
+}
+textarea#script:focus {
+  border-color: var(--accent);
+}
+
+.hint {
+  font-size: 12px;
+  color: var(--muted);
+  margin-top: 6px;
+}
+
+.grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 12px 16px;
+}
+@media (max-width: 560px) {
+  .grid {
+    grid-template-columns: 1fr;
+  }
+}
+
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  min-width: 0;
+}
+.field.wide {
+  grid-column: 1 / -1;
+}
+.field .lbl {
+  display: flex;
+  align-items: baseline;
+  gap: 6px;
+  font-size: 12px;
+  color: var(--muted);
+}
+.field output {
+  color: var(--fg);
+  font-variant-numeric: tabular-nums;
+  font-weight: 600;
+  margin-left: auto;
+}
+.field .unit {
+  color: var(--muted);
+  font-weight: 400;
+}
+
+input[type="range"] {
+  -webkit-appearance: none;
+  appearance: none;
+  width: 100%;
+  height: 18px;
+  background: transparent;
+  margin: 0;
+}
+input[type="range"]::-webkit-slider-runnable-track {
+  height: 4px;
+  background: var(--bg-3);
+  border-radius: 999px;
+}
+input[type="range"]::-moz-range-track {
+  height: 4px;
+  background: var(--bg-3);
+  border-radius: 999px;
+}
+input[type="range"]::-webkit-slider-thumb {
+  -webkit-appearance: none;
+  appearance: none;
+  width: 14px;
+  height: 14px;
+  margin-top: -5px;
+  border-radius: 50%;
+  background: var(--accent);
+  border: 0;
+  cursor: pointer;
+  box-shadow: 0 0 0 3px rgba(122, 162, 255, 0.15);
+}
+input[type="range"]::-moz-range-thumb {
+  width: 14px;
+  height: 14px;
+  border-radius: 50%;
+  background: var(--accent);
+  border: 0;
+  cursor: pointer;
+}
+
+input[type="color"] {
+  width: 100%;
+  height: 30px;
+  background: var(--bg-3);
+  border: 1px solid var(--line);
+  border-radius: var(--radius-sm);
+  padding: 2px;
+  cursor: pointer;
+}
+
+select {
+  width: 100%;
+  height: 30px;
+  background: var(--bg-3);
+  color: var(--fg);
+  border: 1px solid var(--line);
+  border-radius: var(--radius-sm);
+  padding: 0 8px;
+  outline: none;
+}
+
+.row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 14px;
+  align-items: center;
+  margin-top: 12px;
+}
+.row.tight {
+  gap: 8px;
+  margin-top: 10px;
+}
+
+.check {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 13px;
+  color: var(--fg);
+  user-select: none;
+  cursor: pointer;
+}
+.check input {
+  margin: 0;
+  accent-color: var(--accent);
+}
+
+button {
+  appearance: none;
+  border: 1px solid var(--line);
+  background: var(--bg-3);
+  color: var(--fg);
+  padding: 8px 14px;
+  border-radius: var(--radius-sm);
+  cursor: pointer;
+  font: inherit;
+  transition: background 80ms ease, border-color 80ms ease, transform 80ms ease;
+}
+button:hover {
+  background: #232834;
+}
+button:active {
+  transform: translateY(1px);
+}
+button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+button.primary {
+  background: var(--accent);
+  color: #0b0d12;
+  border-color: transparent;
+  font-weight: 600;
+}
+button.primary:hover {
+  background: #95b5ff;
+}
+button.ghost {
+  background: transparent;
+}
+
+.actions {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  flex-wrap: wrap;
+}
+.actions .state {
+  margin-left: auto;
+  color: var(--muted);
+  font-size: 12px;
+  font-variant-numeric: tabular-nums;
+}
+.actions .state.ok {
+  color: var(--ok);
+}
+.actions .state.warn {
+  color: var(--accent-2);
+}
+
+details.hint-card summary {
+  cursor: pointer;
+  color: var(--muted);
+  font-size: 13px;
+  list-style: none;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+details.hint-card summary::before {
+  content: "▸";
+  display: inline-block;
+  transition: transform 120ms ease;
+  color: var(--muted);
+}
+details.hint-card[open] summary::before {
+  transform: rotate(90deg);
+}
+details.hint-card ul {
+  margin: 10px 0 0;
+  padding-left: 20px;
+  color: var(--fg);
+}
+details.hint-card li {
+  margin: 4px 0;
+}
+kbd {
+  background: var(--bg-3);
+  border: 1px solid var(--line);
+  border-bottom-width: 2px;
+  border-radius: 4px;
+  padding: 0 5px;
+  font: 11px/1.6 ui-monospace, "SF Mono", Menlo, monospace;
+}