keyvoid 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is inspired by Keep a Changelog and follows Semantic Versioning.
+
+## [1.0.0] - 2026-03-30
+
+### Added
+
+- Initial npm-ready CLI release of KeyVoid
+- Cross-platform keyboard suppression via native helpers
+- Seven interactive terminal modes (`clean`, `zen`, `arcade`, `hacker`, `cat`, `prank`, `toddler`)
+- Mouse-driven unlock flow with emergency failsafe (`ESC + SPACE`)
+- Updated publish metadata and maintainer verification scripts

package/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing to KeyVoid
+
+Thanks for taking the time to contribute.
+
+## Development Setup
+
+```bash
+git clone https://github.com/chirayuoli/keyvoid.git
+cd keyvoid
+npm install
+```
+
+## Branch and Commit Flow
+
+1. Create a feature branch from `main`
+2. Keep commits focused and descriptive
+3. Run `npm run verify` before opening a PR
+4. Open a PR with a short problem statement and test notes
+
+## Code Guidelines
+
+- Keep behavior cross-platform (`darwin`, `linux`, `win32`)
+- Preserve safety guarantees (mouse unlock + failsafe)
+- Avoid adding dependencies unless there is a strong reason
+- Match existing code style and naming conventions
+
+## Pull Request Checklist
+
+- [ ] Change is scoped and documented
+- [ ] README is updated when CLI behavior changes
+- [ ] `npm run verify` passes locally
+- [ ] No unrelated refactors are mixed in
+
+## Reporting Issues
+
+When opening an issue, include:
+
+- OS and terminal app/version
+- Node version
+- Command used (`keyvoid --mode`)
+- Expected behavior vs actual behavior
+- Any relevant logs/screenshots

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KeyVoid contributors
+
+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,233 @@
+# KeyVoid
+
+<p align="center">
+  <strong>Global keyboard lock in your terminal with safe mouse-first unlock.</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/chirayuoli/keyvoid/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-22c55e"></a>
+  <a href="https://nodejs.org/"><img alt="Node" src="https://img.shields.io/badge/node-%3E%3D18-0ea5e9"></a>
+  <a href="https://www.npmjs.com/package/keyvoid"><img alt="NPM" src="https://img.shields.io/npm/v/keyvoid"></a>
+  <a href="https://www.npmjs.com/package/keyvoid"><img alt="Downloads" src="https://img.shields.io/npm/dm/keyvoid"></a>
+</p>
+
+KeyVoid is a cross-platform CLI that intercepts keyboard input at the OS level and displays an interactive full-screen terminal UI. It is built for focus sessions, safe keyboard lock while away from desk, toddler/cat-proof moments, and lightweight prank demos.
+
+## Table of Contents
+
+- [What You Get](#what-you-get)
+- [System Requirements](#system-requirements)
+- [Install](#install)
+- [First Run Checklist](#first-run-checklist)
+- [Usage](#usage)
+- [Modes](#modes)
+- [Safety and Unlock Paths](#safety-and-unlock-paths)
+- [Troubleshooting](#troubleshooting)
+- [Developer Setup](#developer-setup)
+- [NPM Publishing (Maintainer)](#npm-publishing-maintainer)
+- [Project Structure](#project-structure)
+- [Security Notes](#security-notes)
+- [License](#license)
+
+## What You Get
+
+- Global keyboard suppression (not just app-local key capture)
+- Mouse-first unlock control with visible UI feedback
+- Emergency failsafe combo (`ESC + SPACE`) and `Ctrl+C` fallback
+- Seven built-in visual modes (`clean`, `zen`, `arcade`, `hacker`, `cat`, `prank`, `toddler`)
+- Works through npm (`npx`, local install, or global install)
+
+## System Requirements
+
+| Requirement | Minimum |
+|---|---|
+| Node.js | `>= 18` |
+| Terminal | Interactive TTY (not piped/non-interactive) |
+| OS | macOS, Linux, or Windows |
+
+Platform-specific notes:
+
+| OS | Status | Required Setup |
+|---|---|---|
+| macOS | Supported | Accessibility permission for your terminal app |
+| Linux | Supported | X11 session + `xinput` installed |
+| Windows | Supported | PowerShell available (default on modern Windows) |
+
+## Install
+
+```bash
+# run instantly (no install)
+npx keyvoid
+
+# OR install globally once
+npm install -g keyvoid
+keyvoid
+```
+
+## First Run Checklist
+
+### macOS
+
+1. Open `System Settings`
+2. Go to `Privacy & Security -> Accessibility`
+3. Add your terminal app (`Terminal`, `iTerm2`, etc.)
+4. Toggle permission to ON
+
+### Linux
+
+Install `xinput`:
+
+```bash
+# Ubuntu / Debian
+sudo apt install xinput
+
+# Fedora
+sudo dnf install xinput
+
+# Arch
+sudo pacman -S xorg-xinput
+```
+
+Note: KeyVoid is intended for X11 environments. Wayland setups may not provide equivalent behavior.
+
+### Windows
+
+No additional permission prompts are typically required.
+
+## Usage
+
+```bash
+# interactive mode picker
+keyvoid
+
+# direct mode launch
+keyvoid --clean
+keyvoid --zen
+keyvoid --arcade
+keyvoid --hacker
+keyvoid --cat
+keyvoid --prank
+keyvoid --toddler
+```
+
+CLI utilities:
+
+```bash
+keyvoid --help
+keyvoid --version
+```
+
+## Modes
+
+| Flag | Theme | Description |
+|---|---|---|
+| `--clean` | Minimal UI | High-contrast dashboard with animated blocked-key counter |
+| `--zen` | Calm focus | Breathing-style motion and low-stimulus visuals |
+| `--arcade` | Retro 8-bit | Shooter-inspired animation reacting to key mashing |
+| `--hacker` | Matrix style | Green terminal aesthetic with lock-screen vibes |
+| `--cat` | ASCII cat defense | Reactive cat states and streak-based animation |
+| `--prank` | Fake updater | Convincing fake update view with secret unlock gesture |
+| `--toddler` | Color chaos | Giant emoji bursts and fast-changing vibrant colors |
+
+## Safety and Unlock Paths
+
+KeyVoid is intentionally designed with redundant exits:
+
+1. Click the on-screen **UNVOID** button using your mouse
+2. Hold `ESC + SPACE` for about 5 seconds (failsafe)
+3. Use `Ctrl+C` as emergency terminal fallback
+
+On exit, KeyVoid attempts to restore keyboard hook state before terminating.
+
+## Troubleshooting
+
+### "It says permissions are missing on macOS"
+
+- Re-check Accessibility permission for your exact terminal app
+- Fully close and re-open terminal after granting permission
+- Run `keyvoid` again
+
+### "Linux launch fails or keyboard is not blocked"
+
+- Confirm you are in an X11 session
+- Confirm `xinput` exists: `xinput --version`
+- Retry from a local terminal session (not remote shell)
+
+### "I launched with --cat but got another mode"
+
+- Ensure you are on the latest commit/release
+- Verify command spelling: `keyvoid --cat`
+- Check version: `keyvoid --version`
+
+### "Command not found: keyvoid"
+
+- If installed globally, check npm global bin is on `PATH`
+- Or run via `npx keyvoid`
+
+## Developer Setup
+
+```bash
+git clone https://github.com/chirayuoli/keyvoid.git
+cd keyvoid
+npm install
+npm run verify
+```
+
+Useful scripts:
+
+- `npm run smoke` -> checks CLI help/version
+- `npm run pack:preview` -> previews publish tarball contents
+- `npm run verify` -> runs smoke + pack preview
+
+## NPM Publishing (Maintainer)
+
+```bash
+# 1) login
+npm login
+npm whoami
+
+# 2) verify package before release
+npm run verify
+
+# 3) dry-run package contents
+npm pack --dry-run
+
+# 4) publish
+npm publish --access public
+```
+
+Recommended release flow:
+
+1. Bump version (`npm version patch|minor|major`)
+2. Update `CHANGELOG.md`
+3. Tag and push (`git push origin main --tags`)
+4. Publish to npm
+
+## Project Structure
+
+```text
+keyvoid/
+├── bin/keyvoid.js                     # CLI entry point
+├── src/app.js                         # Application orchestrator
+├── src/engine/permissions.js          # OS/platform checks
+├── src/engine/suppressor/             # Native keyboard suppression layer
+├── src/ui/renderer.js                 # Full-screen ANSI renderer
+├── src/ui/mouse.js                    # Mouse region tracking and clicks
+├── src/ui/skins/                      # Visual modes
+├── src/scripts/postinstall.js         # macOS helper dependency bootstrap
+├── CONTRIBUTING.md
+├── CHANGELOG.md
+└── LICENSE
+```
+
+## Contributing
+
+Please see `CONTRIBUTING.md` for workflow and PR expectations.
+
+## Security Notes
+
+KeyVoid intercepts keyboard input by design. Use only on systems and sessions you control. Avoid running in privileged production shells or remote sessions where recovery may be difficult.
+
+## License
+
+MIT - see `LICENSE`.

package/bin/keyvoid.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+
+// ─── KeyVoid CLI Entry Point ─────────────────────────────────────────
+// Cross-platform keyboard locker with beautiful terminal UI.
+// Usage: npx keyvoid [--clean|--toddler|--cat|--prank]
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { createRequire } from 'module';
+import { KeyVoidApp } from '../src/app.js';
+
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
+
+const program = new Command();
+
+program
+  .name('keyvoid')
+  .description('🔒 Cross-platform keyboard locker with stunning terminal UI')
+  .version(version)
+  .option('--clean', 'Minimalist mode with keystroke counter')
+  .option('--toddler', 'Fun emoji mode for kids — flashes colors and emojis')
+  .option('--cat', 'Cat defense mode — ASCII cat guards your keyboard')
+  .option('--prank', 'Fake update screen — looks like Windows is updating')
+  .option('--hacker', 'Matrix digital rain with fake system errors')
+  .option('--arcade', 'Retro 8-bit alien shooter mini-game')
+  .option('--zen', 'Calm breathing ripples for focus')
+  .action(async (options) => {
+    // Determine selected skin
+    let skin = null;
+    if (options.clean) skin = 'clean';
+    if (options.toddler) skin = 'toddler';
+    if (options.cat) skin = 'cat';
+    if (options.prank) skin = 'prank';
+    if (options.hacker) skin = 'hacker';
+    if (options.arcade) skin = 'arcade';
+    if (options.zen) skin = 'zen';
+
+    // Interactive prompt if no explicit option is passed
+    if (!skin) {
+      if (!process.stdout.isTTY) {
+        skin = 'clean'; // Fallback for non-interactive shells
+      } else {
+        const { select } = await import('@inquirer/prompts');
+        try {
+          skin = await select({
+            message: 'Choose a KeyVoid mode to launch:',
+            choices: [
+              {
+                name: chalk.cyanBright('1. Clean Mode'),
+                value: 'clean',
+                description: 'Dark minimalist interface with a colorful giant keystroke counter.'
+              },
+              {
+                name: chalk.magenta('2. Zen Mode'),
+                value: 'zen',
+                description: 'Soothing colors and breathing ripples for deep focus.'
+              },
+              {
+                name: chalk.redBright('3. Arcade Mode'),
+                value: 'arcade',
+                description: 'Mashing keys shoots lasers at 8-bit aliens.'
+              },
+              {
+                name: chalk.greenBright('4. Hacker Mode'),
+                value: 'hacker',
+                description: 'Matrix green digital rain and intense system lock errors.'
+              },
+              {
+                name: chalk.magentaBright('5. Cat Defense'),
+                value: 'cat',
+                description: 'An ASCII cat animates and gets angry when you try to type.'
+              },
+              {
+                name: chalk.blueBright('6. Prank Mode'),
+                value: 'prank',
+                description: 'A fake Windows Update screen. Perfect for coffee breaks! (triple click on top right to exit)'
+              },
+              {
+                name: chalk.yellow('7. Toddler Mode'),
+                value: 'toddler',
+                description: 'Bright random background colors and giant emojis on every key press.'
+              }
+            ]
+          });
+        } catch (err) {
+          if (err.name === 'ExitPromptError') {
+            process.exit(0);
+          } else {
+            console.error('Prompt error:', err);
+            process.exit(1);
+          }
+        }
+      }
+    }
+
+    // Ensure proper terminal
+    if (!process.stdout.isTTY) {
+      console.error(chalk.red('Error: KeyVoid requires an interactive terminal (TTY).'));
+      process.exit(1);
+    }
+
+    // Check terminal size
+    const cols = process.stdout.columns || 80;
+    const rows = process.stdout.rows || 24;
+    if (cols < 50 || rows < 15) {
+      console.error(chalk.yellow('Warning: Terminal is very small. For the best experience, resize to at least 80×24.'));
+    }
+
+    // Launch the app
+    const app = new KeyVoidApp({ skin });
+
+    try {
+      await app.start();
+    } catch (err) {
+      console.error(chalk.red('Failed to start KeyVoid:'), err.message);
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "keyvoid",
+  "version": "1.0.0",
+  "description": "Cross-platform keyboard lock CLI with immersive terminal themes and mouse-only unlock",
+  "type": "module",
+  "homepage": "https://github.com/chirayuoli/keyvoid#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chirayuoli/keyvoid.git"
+  },
+  "bugs": {
+    "url": "https://github.com/chirayuoli/keyvoid/issues"
+  },
+  "bin": {
+    "keyvoid": "./bin/keyvoid.js"
+  },
+  "main": "src/app.js",
+  "preferGlobal": true,
+  "publishConfig": {
+    "access": "public"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "scripts": {
+    "start": "node bin/keyvoid.js",
+    "clean": "node bin/keyvoid.js --clean",
+    "zen": "node bin/keyvoid.js --zen",
+    "arcade": "node bin/keyvoid.js --arcade",
+    "hacker": "node bin/keyvoid.js --hacker",
+    "toddler": "node bin/keyvoid.js --toddler",
+    "cat": "node bin/keyvoid.js --cat",
+    "prank": "node bin/keyvoid.js --prank",
+    "postinstall": "node src/scripts/postinstall.js",
+    "smoke": "node bin/keyvoid.js --version && node bin/keyvoid.js --help",
+    "pack:preview": "npm pack --dry-run",
+    "verify": "npm run smoke && npm run pack:preview"
+  },
+  "keywords": [
+    "keyboard",
+    "lock",
+    "locker",
+    "blocker",
+    "system-hook",
+    "terminal",
+    "cli",
+    "security",
+    "toddler",
+    "cat",
+    "prank",
+    "npx"
+  ],
+  "author": "KeyVoid Contributors",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md"
+  ],
+  "dependencies": {
+    "@inquirer/prompts": "^8.3.2",
+    "ansi-escapes": "^7.0.0",
+    "chalk": "^5.4.1",
+    "cli-cursor": "^5.0.0",
+    "commander": "^13.1.0",
+    "figlet": "^1.8.0",
+    "gradient-string": "^3.0.0"
+  }
+}