🖨️ Ink Flow — Printer Maintenance Tracker

Version 3.1.0 | Windows, macOS, and Linux

Versioning policy: every commit increments the patch number in package.json. Run npm run bump (or npm version patch --no-git-tag-version) before committing — that way the in-app About panel always identifies exactly which code state is running. Tags (vX.Y.Z pushed to GitHub) are reserved for installer releases.

CI: Windows + macOS + Linux builds run on every push via AppVeyor. Tag pushes auto-publish installers to the GitHub Releases page.

What's new in v3.1

• Auto-updater — the running app now checks GitHub Releases on startup, downloads new versions in the background, and applies them on next quit. No more manual download/install.
• Real-time print detection — Windows now uses a .NET EventLogWatcher subscription instead of 5-minute polling. Prints are detected within a second of the spooler finishing.
• First-run wizard — new installs walk through Detect printers → Background tick → Print log enable in three guided steps.
• Single-instance enforcement — clicking the app multiple times re-focuses the existing window instead of spawning duplicates.
• Color test page — auto-maintenance now prints a CMYK + composite + gradient pattern that exercises every ink channel, replacing the black-only text page.
• Settings redesigned — four-tab layout (General / Automation / Detection / Backup), each tab fits without scrolling.
• Customizable tick interval — hourly to weekly options.
• Tick summary on launch — banner shows what the background did while you were away.
• Statistics: Background Activity — verify the tick is doing real work (tick runs / auto-prints / offline skips / failures).
• macOS Full Disk Access deep-link — Enable button opens the right System Settings pane directly.
• MIT licensed — proper LICENSE file, anyone can fork.

Ink Flow is a cross-platform desktop app that helps prevent liquid ink printer nozzle clogging by tracking printer usage, sending automatic maintenance prints, detecting external print jobs, and alerting you when printers sit idle too long — even when the app itself is closed.

Why? Liquid ink printers (inkjet, EcoTank, SuperTank, etc.) can clog their nozzles if left unused for extended periods. Ink Flow ensures every printer gets used regularly — automatically.

What's new in v3.0

• Cross-platform. Builds for Windows, macOS, and Linux. CUPS adapter covers Mac + Linux with the same printer logic.
• Background maintenance tick. A headless helper registered with the OS scheduler (Task Scheduler / LaunchAgent / systemd --user timer) fires every 6 hours so overdue printers get a maintenance page even when the GUI is closed.
• Real offline detection. TCP probes the printer's print port (9100) for network printers instead of trusting the spooler's cached status. No more "ready" when the printer has been off for an hour.
• Diagnostics panel. Every tick, every print, every failure is logged. The new in-app Diagnostics view shows what Ink Flow has been doing while you weren't watching.
• One-click fix for "doesn't detect my prints". On Windows the PrintService/Operational event log is disabled by default — Ink Flow now detects that and offers a one-click enable (UAC prompt).
• Per-printer opt-out and maintenance window. Exclude specific printers from automation; restrict auto-prints to a time-of-day range.

---

✨ Features

Core Printer Management

• Add, edit, and delete printers with custom names, models, ink types, idle thresholds, and warning periods
• Auto-detect system printers — scans Windows for installed printers via WMI and lets you add them instantly
• Online/offline status — real-time printer connectivity checks with visual indicators
• Manual logging — quickly record "Printed" or "Cleaned" actions per printer

Smart Monitoring

• Idle countdown timer — each printer card shows a progress bar counting down to the maintenance deadline
• Overdue severity levels — Low Risk, Moderate Risk, High Risk, and Critical Risk based on how long a printer has been idle
• Automatic print job detection — monitors the Windows Print Service event log (Event ID 307) every 5 minutes and auto-logs detected print jobs
• Print job deduplication — won't double-count events within a ±2 minute window

Automatic Maintenance

• Auto maintenance printing — when enabled, automatically sends a test page to overdue/urgent printers using notepad.exe /p (antivirus-safe, no shell commands)
• Offline-aware — skips auto-printing for offline printers and notifies you instead
• Configurable per-printer — set custom max idle days and warning thresholds for each printer

Notifications & Alerts

• Hourly status checks — automatically scans all printers and triggers alerts for those needing attention
• Standalone alert popup — always-on-top, frameless window that appears over all apps even when the main window is hidden
• In-app alert modal — color-coded, severity-sorted alerts with dismiss confirmation
• Taskbar flashing — grabs your attention when printers need maintenance
• Escalating severity — alerts escalate from Warning → Urgent → Overdue → Severe → Critical based on idle duration

Advanced History

• Full event timeline — all maintenance events grouped by date with relative timestamps ("2h ago", "Yesterday")
• Multi-filter system — filter by event type (prints/cleans), date range (today, 7d, 30d, 90d, all), specific printer, or search text
• Source detection — each event is tagged as Manual, Auto-detected, Auto-maintenance, or Test print
• Summary statistics — total events, print count, clean count, and auto-detected count
• Delete events — remove individual events with double-click confirmation
• Export CSV — copy filtered history to clipboard as CSV with one click

Statistics Dashboard

• 30-day activity chart — stacked bar chart showing daily prints and cleans with hover tooltips
• Per-printer breakdown — sorted by total activity with visual progress bars
• Summary cards — total printers tracked and total events logged

Settings & Preferences

• Start with Windows — auto-launch minimized to system tray on login
• Auto maintenance print toggle — enable/disable automatic test printing
• Dark / Light theme — full theme support across all UI components
• Backup & Restore — export and import all printer data as JSON files

System Tray

• Minimize to tray — closing the window hides to tray instead of quitting
• Tray context menu — Show Ink Flow / Quit
• Double-click to show — quickly access the app from the tray
• Hidden startup — starts minimized to tray when launched at Windows boot

---

🛠️ Tech Stack

Technology	Version	Purpose
Electron	33.2.0	Desktop framework, native OS integration
React	18.3	UI components
TypeScript	5.7	Type-safe code across main and renderer
Vite	6.0	Fast renderer bundling
Tailwind CSS	3.4	Utility-first styling with dark mode

---

📁 Project Structure

Ink Flow/
├── package.json
├── tsconfig.json
├── vite.config.ts
├── tailwind.config.js
├── postcss.config.js
├── assets/
│   └── icon.png
├── src/
│   ├── main/                          # Electron main process
│   │   ├── main.ts                    # App entry, window & tray creation
│   │   ├── store.ts                   # JSON data persistence (atomic writes)
│   │   ├── ipc-handlers.ts            # IPC API bridge (22+ channels)
│   │   ├── preload.ts                 # Context-isolated renderer API
│   │   ├── printer-detect.ts          # Windows WMI printer detection
│   │   ├── notifications.ts           # Hourly status checker & alert dispatcher
│   │   ├── auto-print.ts              # Safe test printing via notepad.exe
│   │   ├── print-monitor.ts           # Windows Event Log print job scanner
│   │   ├── autostart.ts               # Windows startup shortcut management
│   │   ├── alert-window.ts            # Standalone always-on-top alert popup
│   │   ├── tray.ts                    # System tray icon & context menu
│   │   └── window-ref.ts              # Shared window reference module
│   └── renderer/                      # React frontend
│       ├── index.tsx                   # React mount point
│       ├── App.tsx                     # Root component & state management
│       ├── index.html                  # HTML template
│       ├── globals.css                 # Base Tailwind styles
│       ├── ThemeContext.tsx             # Dark/light theme provider
│       ├── types/
│       │   └── index.ts                # TypeScript interfaces & Window API types
│       ├── hooks/
│       │   └── useEscapeKey.ts         # Reusable Escape key hook for modals
│       └── components/
│           ├── Layout.tsx              # Main UI shell with navigation
│           ├── Dashboard.tsx           # Printer grid with action buttons
│           ├── PrinterCard.tsx         # Individual printer status card
│           ├── AddPrinterModal.tsx     # Create new printer form
│           ├── EditPrinterModal.tsx    # Edit printer settings
│           ├── DetectPrintersModal.tsx  # Auto-detect system printers
│           ├── HistoryPanel.tsx        # Advanced event history viewer
│           ├── SettingsPanel.tsx       # App settings & backup
│           ├── StatisticsPanel.tsx     # Activity charts & stats

│           └── AlertModal.tsx          # In-app alert display
└── dist/                              # Compiled output
    ├── main/                          # Compiled Electron main process
    └── renderer/                      # Bundled React app

---

🚀 Getting Started

Prerequisites

• Node.js 18+ with npm
• Windows 10/11 (required for printer detection, event log monitoring, and startup integration)

Installation

# Clone or navigate to the project
cd "Ink Flow"

# Install dependencies
npm install

# Run in development mode
npm run dev

Available Scripts

Command	Description
npm run dev	Start dev server (Vite + Electron with hot reload)
npm run build	Compile TypeScript + bundle renderer with Vite
npm start	Launch the built app with Electron
npm run package	Build + generate Windows NSIS installer

---

📦 Building for Distribution

# Build and create Windows installer
npm run package

This generates an NSIS installer in the release/ directory. The installer allows users to choose their installation directory.

---

🔧 How It Works

Data Storage

All printer and event data is stored in a single JSON file at:

%APPDATA%/ink-flow/inkflow-data.json

• Atomic writes — uses temp file + rename to prevent corruption
• Auto-migration — automatically adds missing fields when loading older data formats
• ID management — recalculates ID counters on load to prevent collisions

Print Job Detection

The app queries the Windows Print Service Operational event log using PowerShell:

Get-WinEvent -LogName "Microsoft-Windows-PrintService/Operational"
  -FilterXPath "*[System[EventID=307]]" -MaxEvents 50

This detects Document Printed events and matches them against your tracked printers by name.

Safe Test Printing

Instead of using shell commands (which trigger antivirus false positives), the app:

1. Writes a text file to a temp directory using fs.writeFileSync()
2. Launches notepad.exe /p tempfile.txt using Node.js execFile() (no shell)
3. Cleans up the temp file after printing

Notification Flow

Every 60 minutes:
  → Check all printer statuses
  → Build alert list (warning/urgent/overdue/severe/critical)
  → Show standalone alert popup (always-on-top)
  → Send alerts to renderer (in-app modal)
  → Flash taskbar + restore window
  → Run auto-maintenance prints (if enabled)

---

🎨 Themes

Ink Flow supports Dark and Light themes. Toggle from the top navigation bar. The theme preference is persisted across sessions.

---

⌨️ Keyboard Shortcuts

Key	Action
Escape	Close any open modal or panel

---

🔒 Security

• Context isolation enabled on all windows (main + alert popup)
• Sandbox enabled on popup windows
• No nodeIntegration in any renderer process
• No shell execution — all system commands use execFile() with explicit paths
• Atomic file writes — prevents data corruption on crashes
• HTML escaping — all dynamic content in alert popups is escaped (including single quotes)
• Input validation — imported data is validated for correct structure before loading

---

📋 Requirements

• Operating System: Windows 10 or Windows 11
• Windows Print Spooler service must be running (default on all Windows with printers)
• PowerShell (pre-installed on all modern Windows)
• No additional Windows services or drivers required

---

📄 License

MIT — see LICENSE. You can use, fork, modify, and redistribute this code freely; the only requirement is to keep the copyright + license notice intact.

---

Built with ❤️ for printer maintenance peace of mind.