macvscr 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kzf
+
+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,112 @@
+# vscr
+
+A macOS menu-bar tool that creates controllable **virtual displays** — arbitrary resolution, HiDPI (Retina `@2x`), aspect ratio, and iMac presets. Unblocks HiDPI screen-sharing on headless Macs (e.g. a Mac mini with no monitor attached).
+
+## Why
+
+When you screen-share into a headless Mac, macOS locks the session to a 1920×1080 non-HiDPI surface. `vscr` creates a dummy display at any resolution + Retina, which Screen Sharing then renders.
+
+## Resolution model
+
+Everything you type and see is in **logical pixels**; HiDPI (`@2x`) means the physical surface is doubled for crispness.
+
+- `2560×1440 @2x` → logical workspace 2560×1440, physical 5120×2880 (the Retina way macOS itself describes 5K iMacs)
+- `1920×1080` (HiDPI off) → logical = physical = 1920×1080
+
+The tray header shows both, so logical and physical are never confused.
+
+## Install
+
+Zero-install, one line (recommended):
+
+```bash
+npx -y vscr@latest setup
+```
+
+`setup` copies a stable binary to `~/.vscr/vscr`, adds `alias vscr='npx -y vscr@latest'` to your shell rc (if you don't already have a `vscr` command), and registers a login LaunchAgent so the tray app runs at login and restarts on crash. It prints a `source` reminder and how to stop it.
+
+Or install globally:
+
+```bash
+npm install -g vscr
+vscr setup
+```
+
+Requires macOS 13+ on Apple Silicon (arm64).
+
+## Control the service
+
+```bash
+vscr status                # loaded? running? pid?
+vscr stop                  # stop (returns at next login, or `vscr start`)
+vscr start                 # start again
+vscr restart               # restart
+vscr uninstall             # full teardown: LaunchAgent + ~/.vscr + shell alias
+vscr --help                # everything
+```
+
+Stop the app for now without removing the service: click the **display icon in the menu bar → 退出**, or `vscr stop`. A clean quit is **not** restarted; only a crash is.
+
+## Run directly (one-off)
+
+```bash
+vscr                                  # launch the menu-bar app now
+vscr --width 2560 --ratio 16:9 --hidpi
+```
+
+Once running, click the display icon in the menu bar:
+
+- **常见分辨率 ▸** — presets; iMac sizes are folded in with a tail (`2048×1152 @2x · iMac 21.5"` …).
+- **宽度 ▸** / **高度 ▸** / **比例 ▸** — each has quick picks **and a `自定义…`** entry that opens an input dialog.
+- Width, height, and ratio are linked: width is the master axis; set height or ratio and the other adjusts.
+- **HiDPI / Retina @2x** — toggle Retina backing.
+- **退出** — quit the app (clean exit; the service won't relaunch it until next login or `vscr start`).
+
+The header always shows the active logical resolution (`@2x` when Retina) plus the physical size; the active item is checked. Switching rebuilds the display live — no restart.
+
+### CLI flags (all pixel values are logical)
+
+```
+--width <px>            logical width
+--height <px>           logical height (mutually exclusive with --ratio)
+--ratio <16:9|16:10|21:9|32:9|4:3|3:2|5:4|1:1>
+--hidpi / --no-hidpi    Retina @2x on/off (default on)
+--refresh <Hz>          refresh rate (default 60)
+--name <name>           display name prefix
+```
+
+## Notes on the daemon
+
+- A menu-bar app needs your GUI session, so it starts at **login** (LaunchAgent), not boot (a LaunchDaemon has no GUI).
+- The LaunchAgent runs the stable `~/.vscr/vscr` directly — no `npx`/network at login. The `vscr` command (alias) still uses npx so you always get subcommands + the latest version.
+- Logs: `/tmp/vscr.out.log`, `/tmp/vscr.err.log`.
+
+## Headless / Screen Sharing
+
+1. On the headless Mac, run `vscr setup` (or `npx -y vscr@latest setup`) and pick a preset from the menu bar.
+2. From another Mac, connect via Screen Sharing, then in the **View** menu select the dummy.
+3. The remote session renders at the chosen geometry with Retina.
+
+## Verify
+
+```bash
+system_profiler SPDisplaysDataType | grep -i virtual
+# → Virtual Display <physical W>x<physical H>   Resolution: <W> x <H>
+```
+
+## Notes
+
+- The virtual display is owned by the process and is destroyed when `vscr` quits.
+- Uses the macOS private `CGVirtualDisplay*` SPI (in the public CoreGraphics binary). SIP stays on; the app is non-sandboxed.
+- MIT licensed.
+
+## Build from source
+
+This package bundles a prebuilt universal macOS binary. To rebuild from the Swift source:
+
+```bash
+git clone https://github.com/kzf/macos_virtual_screen
+cd macos_virtual_screen
+swift build -c release --arch arm64
+cp .build/release/VirtualScreen npm/binaries/vscr-darwin-arm64
+```

package/bin/vscr.js

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+'use strict';
+
+// vscr CLI — launches the native macOS menu-bar binary and manages a user
+// LaunchAgent (login start + crash restart = the "daemon" mode).
+//
+// `vscr setup` is the standard one-liner (`npx -y vscr@latest setup`):
+//   1. copies the bundled binary to a stable path (~/.vscr/vscr) for the daemon
+//   2. adds `alias vscr='npx -y vscr@latest'` to the shell rc if no vscr command exists
+//   3. registers + starts the LaunchAgent (runs at login, restarts on crash)
+//
+// Why a LaunchAgent (login) not a LaunchDaemon (boot): a menu-bar tray app
+// needs the user's GUI session (WindowServer), which exists only after login.
+
+const { spawn, spawnSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const LABEL = 'npm.vscr';
+const BIN = path.join(__dirname, '..', 'binaries', 'vscr-darwin-arm64');
+const AGENT_DIR = path.join(os.homedir(), 'Library', 'LaunchAgents');
+const PLIST = path.join(AGENT_DIR, `${LABEL}.plist`);
+const STABLE_DIR = path.join(os.homedir(), '.vscr');
+const STABLE_BIN = path.join(STABLE_DIR, 'vscr');
+
+if (process.platform !== 'darwin') {
+  console.error('vscr: macOS only.');
+  process.exit(1);
+}
+if (!fs.existsSync(BIN)) {
+  console.error('vscr: native binary not found at ' + BIN);
+  console.error('      The package looks corrupt — try reinstalling it.');
+  process.exit(1);
+}
+
+const uid = process.getuid();
+const domainTarget = `gui/${uid}`;
+const serviceTarget = `gui/${uid}/${LABEL}`;
+
+// --- helpers ---
+
+function sh(file, args) {
+  return spawnSync(file, args, { stdio: 'inherit' });
+}
+function shOut(file, args) {
+  return spawnSync(file, args, { encoding: 'utf8' });
+}
+function escapeXML(s) {
+  return String(s).replace(/[&<>]/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' }[c]));
+}
+function isLoaded() {
+  return shOut('launchctl', ['print', serviceTarget]).status === 0;
+}
+function servicePid() {
+  if (!isLoaded()) return null;
+  const r = shOut('launchctl', ['print', serviceTarget]);
+  const m = r.stdout && r.stdout.match(/\bpid\s*=\s*(\d+)/);
+  return m ? m[1] : null;
+}
+function hasVscrCommand() {
+  return shOut('sh', ['-c', 'command -v vscr']).status === 0;
+}
+function rcFile() {
+  const shell = process.env.SHELL || '';
+  if (shell.endsWith('bash')) return path.join(os.homedir(), '.bashrc');
+  return path.join(os.homedir(), '.zshrc'); // macOS default + fallback
+}
+// The alias block is wrapped in stable sentinel markers so future changes to
+// the alias command itself never break detection/removal — we match the
+// markers, not the inner command.
+const ALIAS_HEAD = '# +++npm:vscr';
+const ALIAS_TAIL = '# ---npm:vscr';
+const ALIAS_LINE = `alias vscr='npx -y vscr@latest'`;
+const ALIAS_BLOCK = `\n${ALIAS_HEAD}\n# managed by vscr setup — remove with \`vscr uninstall\`\n${ALIAS_LINE}\n${ALIAS_TAIL}\n`;
+const ALIAS_BLOCK_RE = /\n# \+\+\+npm:vscr[\s\S]*?# ---npm:vscr\n?/;
+
+function aliasInRc() {
+  const rc = rcFile();
+  try {
+    return fs.existsSync(rc) && fs.readFileSync(rc, 'utf8').includes(ALIAS_HEAD);
+  } catch (_) {
+    return false;
+  }
+}
+function appendAliasBlock() {
+  const rc = rcFile();
+  try {
+    if (fs.existsSync(rc)) fs.appendFileSync(rc, ALIAS_BLOCK);
+    else fs.writeFileSync(rc, ALIAS_BLOCK);
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+function removeAlias() {
+  const rc = rcFile();
+  if (!fs.existsSync(rc)) return false;
+  try {
+    const content = fs.readFileSync(rc, 'utf8');
+    if (!ALIAS_BLOCK_RE.test(content)) return false;
+    fs.writeFileSync(rc, content.replace(ALIAS_BLOCK_RE, ''));
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+/**
+ * Reconcile the shell alias with reality so it never shadows a real command
+ * and never goes stale:
+ *   - global `vscr` on PATH -> remove any alias (it would shadow the command)
+ *   - no global `vscr`       -> ensure the alias exists
+ * Returns { note, newlyAdded } for setup messaging.
+ */
+function syncAlias() {
+  const rc = rcFile();
+  const present = aliasInRc();
+  if (hasVscrCommand()) {
+    if (present) {
+      removeAlias();
+      return { note: `${rc} (alias removed — global vscr on PATH; alias would shadow it)`, newlyAdded: false };
+    }
+    return { note: 'skipped (global vscr on PATH)', newlyAdded: false };
+  }
+  if (present) return { note: `${rc} (already present)`, newlyAdded: false };
+  const ok = appendAliasBlock();
+  return { note: ok ? `${rc} (added)` : `(could not write ${rc})`, newlyAdded: ok };
+}
+
+function plistXML(daemonBin, args) {
+  const progArgs = [daemonBin, ...args].map(a => `      <string>${escapeXML(a)}</string>`).join('\n');
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${progArgs}
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>ProcessType</key>
+  <string>Interactive</string>
+  <key>StandardOutPath</key>
+  <string>/tmp/vscr.out.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/vscr.err.log</string>
+</dict>
+</plist>
+`;
+}
+
+/** Write the plist (pointing at daemonBin) and bootstrap it. */
+function bootstrapService(daemonBin, args) {
+  fs.mkdirSync(AGENT_DIR, { recursive: true });
+  if (isLoaded()) sh('launchctl', ['bootout', serviceTarget]);
+  fs.writeFileSync(PLIST, plistXML(daemonBin, args));
+  const r = sh('launchctl', ['bootstrap', domainTarget, PLIST]);
+  if (r.status !== 0) {
+    console.error('vscr: failed to bootstrap the LaunchAgent.');
+    process.exit(r.status || 1);
+  }
+}
+
+// --- commands ---
+
+function setup(args) {
+  console.log('vscr: setting up…');
+
+  // 1. stable daemon binary (so login launch needs no network / no npx)
+  fs.mkdirSync(STABLE_DIR, { recursive: true });
+  fs.copyFileSync(BIN, STABLE_BIN);
+  fs.chmodSync(STABLE_BIN, 0o755);
+
+  // 2. shell convenience: smart alias (add if no vscr; remove if global vscr would be shadowed)
+  const { note: aliasNote, newlyAdded: addedAlias } = syncAlias();
+
+  // 3. register + start the LaunchAgent, pointing at the stable binary
+  bootstrapService(STABLE_BIN, args);
+
+  console.log('');
+  console.log('vscr: setup complete.');
+  console.log(`  daemon binary: ${STABLE_BIN}`);
+  console.log(`  LaunchAgent:   ${PLIST}  (runs at login; restarts on crash)`);
+  console.log(`  shell alias:   ${aliasNote}`);
+  if (addedAlias) {
+    console.log('');
+    console.log('  ▸ The `vscr` command won\'t exist in THIS terminal until you reload the shell:');
+    console.log(`      source ${rcFile()}`);
+  }
+  console.log('');
+  console.log('  How to control vscr:');
+  console.log('    • Quit the app now:  click the display icon in the menu bar → 退出');
+  console.log('    • Stop the service:  vscr stop');
+  console.log('    • Full teardown:     vscr uninstall');
+  console.log('    • All options:       vscr --help');
+}
+
+function uninstall() {
+  if (isLoaded()) sh('launchctl', ['bootout', serviceTarget]);
+  if (fs.existsSync(PLIST)) fs.unlinkSync(PLIST);
+  if (fs.existsSync(STABLE_DIR)) fs.rmSync(STABLE_DIR, { recursive: true, force: true });
+  removeAlias();
+  sh('pkill', ['-f', STABLE_BIN]);
+  sh('pkill', ['-f', BIN]);
+  console.log('vscr: uninstalled (LaunchAgent, ~/.vscr, and shell alias removed).');
+}
+
+function start() {
+  if (!fs.existsSync(PLIST)) {
+    console.error('vscr: not installed. Run `vscr setup` first.');
+    process.exit(1);
+  }
+  if (isLoaded()) {
+    sh('launchctl', ['kickstart', '-k', serviceTarget]);
+  } else {
+    sh('launchctl', ['bootstrap', domainTarget, PLIST]);
+  }
+  console.log('vscr: started.');
+}
+
+function stop() {
+  if (isLoaded()) sh('launchctl', ['bootout', serviceTarget]);
+  sh('pkill', ['-f', STABLE_BIN]);
+  sh('pkill', ['-f', BIN]);
+  console.log('vscr: stopped. (Returns at next login, or run `vscr start`.)');
+}
+
+function status() {
+  if (!fs.existsSync(PLIST)) {
+    console.log('vscr: not installed.');
+    return;
+  }
+  if (!isLoaded()) {
+    console.log('vscr: installed (plist present) but not loaded in this session.');
+    return;
+  }
+  const r = shOut('launchctl', ['print', serviceTarget]);
+  const pid = servicePid();
+  const lastM = r.stdout && r.stdout.match(/last exit code = (\d+)/);
+  console.log(`vscr: loaded (${LABEL}).`);
+  console.log(`  ${pid ? `running, pid ${pid}` : 'not currently running'}`);
+  if (lastM) console.log(`  last exit code: ${lastM[1]}`);
+  console.log(`  plist: ${PLIST}`);
+  console.log(`  daemon binary: ${fs.existsSync(STABLE_BIN) ? STABLE_BIN : '(~/.vscr/vscr missing — run vscr setup)'}`);
+}
+
+function runApp(args) {
+  const pid = servicePid();
+  if (pid) {
+    console.log(`vscr: already running as a login service (pid ${pid}). Use the menu-bar icon.`);
+    return;
+  }
+  const wantsHelp = args.some(a => a === '-h' || a === '--help' || a === '--version' || a === '-v');
+  if (wantsHelp) {
+    const r = spawnSync(BIN, args, { stdio: 'inherit' });
+    process.exit(r.status == null ? 1 : r.status);
+  }
+  const child = spawn(BIN, args, { detached: true, stdio: 'ignore' });
+  child.on('error', err => {
+    console.error('vscr: failed to launch:', err.message);
+    process.exit(1);
+  });
+  child.unref();
+  console.log(`vscr: running (pid ${child.pid}). Look for the display icon in the menu bar.`);
+  console.log('      For always-on: `vscr setup`. Manage: `vscr status | start | stop | uninstall`.');
+}
+
+function printHelp() {
+  console.log(`vscr — macOS virtual display tray tool
+
+Standard setup (recommended):
+  npx -y vscr@latest setup [--width N --ratio W:H ...]
+      copies a stable binary, adds a shell alias if needed, and registers +
+      starts a login LaunchAgent (runs at login, restarts on crash).
+
+Manage the service:
+  vscr status        loaded? running? pid?
+  vscr start         start the service
+  vscr stop          stop (returns at next login, or 'vscr start')
+  vscr restart       restart
+  vscr uninstall     remove the LaunchAgent, ~/.vscr, and the shell alias
+
+Run directly (one-off):
+  vscr [resolution flags]            launch the menu-bar app now
+
+A menu-bar app needs your GUI session, so it starts at LOGIN, not boot.
+Resolution flags (all pixels are LOGICAL; @2x = physical × 2):`);
+  const r = spawnSync(BIN, ['--help'], { stdio: 'inherit' });
+  if (r.status) process.exit(r.status);
+}
+
+// --- dispatch ---
+
+const sub = process.argv[2];
+const rest = process.argv.slice(3).map(String);
+
+switch (sub) {
+  case 'setup':
+  case 'install':    setup(rest); break;
+  case 'uninstall':  uninstall(); break;
+  case 'start':      start(); break;
+  case 'stop':       stop(); break;
+  case 'restart':    stop(); setTimeout(start, 700); break;
+  case 'status':     status(); break;
+  case 'help':
+  case '-h':
+  case '--help':     printHelp(); break;
+  case undefined:    runApp([]); break;
+  default:           runApp(process.argv.slice(2)); break;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "macvscr",
+  "version": "0.1.0",
+  "description": "macOS menu-bar tool that creates controllable virtual displays — arbitrary resolution, HiDPI, aspect ratio, and iMac presets. Unblocks HiDPI screen-sharing on headless Macs.",
+  "bin": {
+    "vscr": "bin/vscr.js"
+  },
+  "files": [
+    "bin/",
+    "binaries/",
+    "README.md",
+    "LICENSE"
+  ],
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "arm64"
+  ],
+  "engines": {
+    "node": ">=14"
+  },
+  "preferGlobal": true,
+  "keywords": [
+    "macos",
+    "virtual-display",
+    "dummy-display",
+    "menubar",
+    "tray",
+    "hidpi",
+    "retina",
+    "resolution",
+    "headless",
+    "screen-sharing",
+    "mac-mini",
+    "imac",
+    "cli"
+  ],
+  "license": "MIT",
+  "author": "kzf",
+  "homepage": "https://github.com/kzf/macos_virtual_screen",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kzf/macos_virtual_screen.git",
+    "directory": "npm"
+  }
+}