persian-clock-widget 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shayan Bamyar (® Shayan Bamyar)
+
+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-LINUX.md

@@ -0,0 +1,128 @@
+<div dir="rtl">
+
+# 🐧 راهنمای نصب و اجرا در لینوکس — ویجت ساعت تهران، تقویم شمسی و آلارم
+
+**طراحی و توسعه:** شایان بامیار (`® Shayan Bamyar`)
+
+این راهنما نحوه نصب، اجرا، فعال‌سازی اجرای خودکار (Startup) و حذف برنامه **Persian Clock & Calendar** را روی تمام توزیع‌های لینوکس توضیح می‌دهد.
+
+---
+
+## 📦 روش ۱: نصب روی اوبونتو، دبیان، مینت و Pop!_OS (فایل `.deb`) — پیشنهادی
+
+فایل **[`release/linux/persian-clock-widget_1.0.0_all.deb`](release/linux/persian-clock-widget_1.0.0_all.deb)** را دانلود کنید و با **دابل‌کلیک** یا از طریق ترمینال نصب کنید:
+
+```bash
+sudo apt update
+sudo apt install ./persian-clock-widget_1.0.0_all.deb
+```
+
+**کارهایی که این بسته خودکار انجام می‌دهد:**
+- نصب پیش‌نیاز `python3-tk` (در صورت نبودن)
+- نصب برنامه در `/opt/persian-clock-widget`
+- نصب فونت‌های فارسی (`Vazir`, `B Yekan+`, `Iranian Sans`) و به‌روزرسانی `fc-cache`
+- ساخت آیکون و میانبر در منوی برنامه‌ها (**Applications Menu**) با نام `Persian Clock & Calendar`
+- ایجاد دستور ترمینال `persian-clock-widget`
+
+**اجرا پس از نصب:**
+- از منوی برنامه‌های سیستم روی **Persian Clock & Calendar** کلیک کنید، یا در ترمینال بزنید:
+```bash
+persian-clock-widget
+```
+
+---
+
+## 🚀 روش ۲: نصب‌کننده تک‌فایلی روی تمام توزیع‌های لینوکس (`.sh`)
+
+مناسب برای **Ubuntu, Debian, Arch, Manjaro, Fedora, openSUSE** و هر توزیع دیگر؛ فقط فایل **[`release/linux/PersianClockWidget-Linux-Installer.sh`](release/linux/PersianClockWidget-Linux-Installer.sh)** را اجرا کنید:
+
+```bash
+bash PersianClockWidget-Linux-Installer.sh
+```
+
+**کارهایی که نصب‌کننده انجام می‌دهد:**
+1. بررسی وجود `python3` و `tkinter`
+2. استخراج برنامه در `~/.local/share/persian-clock-widget`
+3. نصب فونت‌های فارسی در `~/.local/share/fonts/PersianClockWidget`
+4. ساخت میانبر منوی برنامه‌ها و فعال‌سازی اجرای خودکار با شروع لینوکس (`~/.config/autostart/persian-clock-widget.desktop`)
+5. اجرای فوری ویجت
+
+---
+
+## 📁 روش ۳: اجرای پرتابل بدون نصب (از سورس یا آرشیو `tar.gz`)
+
+اگر فایل **[`release/linux/PersianClockWidget-linux-portable.tar.gz`](release/linux/PersianClockWidget-linux-portable.tar.gz)** را دارید:
+
+```bash
+tar -xzf PersianClockWidget-linux-portable.tar.gz
+cd persian-clock-widget
+./scripts/run_linux.sh
+```
+
+### پیش‌نیازها (در صورت اجرای مستقیم از سورس):
+- **Ubuntu / Debian / Mint:**
+  ```bash
+  sudo apt install python3 python3-tk mpv
+  ```
+- **Fedora:**
+  ```bash
+  sudo dnf install python3 python3-tkinter mpv
+  ```
+- **Arch / Manjaro:**
+  ```bash
+  sudo pacman -S python tk mpv
+  ```
+> **نکته صوتی:** برای پخش صدای MP3 آلارم‌ها در لینوکس، کافی است یکی از پخش‌کننده‌های سبک `mpv`، `ffmpeg` (`ffplay`)، `mpg123` یا `vlc` (`cvlc`) روی سیستم نصب باشد.
+
+---
+
+## 🔨 ساخت فایل اجرایی تک‌فایلی بومی لینوکس (اختیاری)
+
+اگر می‌خواهید یک فایل اجرایی باینری تک‌فایلی (`ELF`) مخصوص سیستم خود بسازید:
+
+```bash
+./scripts/build_linux.sh
+```
+خروجی در مسیر `release/PersianClockWidget-linux` و `release/PersianClockWidget-linux.tar.gz` ساخته می‌شود.
+
+---
+
+## ⚙️ اجرای خودکار با بالا آمدن لینوکس (`Startup`)
+
+برای فعال یا غیرفعال کردن اجرای خودکار برنامه هنگام روشن شدن سیستم:
+1. روی آیکون **`⚙` (تنظیمات)** در ویجت کلیک کنید و تیک **«🚀 اجرا خودکار ویجت هم‌زمان با بالا آمدن لینوکس (Startup)»** را بزنید؛ **یا**
+2. روی ویجت **راست‌کلیک** کرده و گزینه **«🚀 اجرا خودکار با شروع لینوکس»** را بزنید.
+
+> فایل تنظیمات اتواستارت در مسیر `~/.config/autostart/persian-clock-widget.desktop` ساخته می‌شود.
+
+---
+
+## 📂 مسیر ذخیره تنظیمات، آلارم‌ها و مناسبت‌های شخصی
+
+- در نصب سیستمی (`.deb`) یا اجرای باینری، اطلاعات کاربر (تنظیمات، آلارم‌ها و تولدهای ثبت‌شده) بدون نیاز به دسترسی `root` در مسیر زیر ذخیره می‌شوند:
+  ```text
+  ~/.local/share/PersianClockWidget/data/
+  ├── config.json
+  ├── alarms.json
+  └── custom_occasions.json
+  ```
+- در اجرای پرتابل از پوشه پروژه، داده‌ها در پوشه `data/` کنار برنامه ذخیره می‌شوند.
+
+---
+
+## 🗑 حذف برنامه (`Uninstall`)
+
+- **اگر با `.deb` نصب کرده‌اید:**
+  ```bash
+  sudo apt remove persian-clock-widget
+  ```
+- **اگر با `.sh` نصب کرده‌اید:**
+  ```bash
+  rm -rf ~/.local/share/persian-clock-widget \
+         ~/.local/bin/persian-clock-widget \
+         ~/.local/share/applications/persian-clock-widget.desktop \
+         ~/.config/autostart/persian-clock-widget.desktop \
+         ~/.local/share/fonts/PersianClockWidget
+  ```
+
+</div>

package/README.md

@@ -1,3 +1,264 @@
-# Temporary Holding Version
+<div dir="rtl" align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img src="assets/icons/app_icon.png" alt="Persian Clock & Calendar Widget Icon" width="128" height="128" />
+
+# ویجت حرفه‌ای ساعت تهران، تقویم شمسی و سیستم یادآور ویندوز
+### **Persian Clock, Jalali Calendar & Smart Alarm Desktop Widget**
+
+[![Platform](https://img.shields.io/badge/Platform-Windows%2010%20%7C%2011-0078D6?style=for-the-badge&logo=windows&logoColor=white)](#)
+[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)](#)
+[![Offline](https://img.shields.io/badge/Mode-100%25%20Offline-10B981?style=for-the-badge)](#)
+[![License](https://img.shields.io/badge/License-MIT-F59E0B?style=for-the-badge)](LICENSE)
+[![Author](https://img.shields.io/badge/Author-%C2%AE%20Shayan%20Bamyar-38BDF8?style=for-the-badge)](#)
+
+**یک ویجت دسکتاپ فوق‌سبک، مینیمال، کاملاً آفلاین و قابل شخصی‌سازی برای ویندوز**  
+شامل ساعت دقیق به وقت تهران، تاریخ هجری شمسی، مناسبت‌ها و تعطیلات رسمی، تقویم ماهانه بازشونده، سیستم آلارم با ۶ صدای MP3 داخلی (پیش‌فرض: `heeeeyyyyy.mp3`) و زنگوله متحرک، و ابزار کپی زمان مخصوص برنامه‌نویسان.
+
+---
+
+</div>
+
+<div dir="rtl">
+
+## 📌 فهرست مطالب
+- [معرفی و ویژگی‌های کلیدی](#-معرفی-و-ویژگیهای-کلیدی)
+- [ساختار پوشه‌ها و معماری پروژه](#-ساختار-پوشهها-و-معماری-پروژه)
+- [نحوه دانلود و اجرای سریع (بدون نیاز به پایتون)](#-نحوه-دانلود-و-اجرای-سریع-بدون-نیاز-به-پایتون)
+- [راهنمای کامل امکانات و نحوه کارکرد](#-راهنمای-کامل-امکانات-و-نحوه-کارکرد)
+  - [۱. دکمه قفل هوشمند (🔒/🔓) و عبوردهی کلیک (Click-Through)](#۱-دکمه-قفل-هوشمند--و-عبوردهی-کلیک-click-through)
+  - [۲. کنترل لایه نمایش (Z-Index)](#۲-کنترل-لایه-نمایش-z-index)
+  - [۳. تقویم ماهانه بازشونده (Extend) و مناسبت‌ها](#۳-تقویم-ماهانه-بازشونده-extend-و-مناسبتها)
+  - [۴. سیستم رویداد، یادآور و آلارم (⏰) با زنگوله متحرک و صداهای MP3](#۴-سیستم-رویداد-یادآور-و-آلارم--با-زنگوله-متحرک-و-صداهای-mp3)
+  - [۵. ابزار کپی زمان برای برنامه‌نویسان (📋)](#۵-ابزار-کپی-زمان-برای-برنامهنویسان-)
+  - [۶. پنجره تنظیمات ظاهری، رنگ، سایز و فونت (⚙)](#۶-پنجره-تنظیمات-ظاهری-رنگ-سایز-و-فونت-)
+- [اجرا از طریق سورس کد پایتون](#-اجرا-از-طریق-سورس-کد-پایتون)
+- [نحوه ساخت مجدد فایل اجرایی (`.exe`)](#-نحوه-ساخت-مجدد-فایل-اجرایی-exe)
+- [طراح و توسعه‌دهنده (حق ناشر)](#-طراح-و-توسعهدهنده-حق-ناشر)
+
+---
+
+## ✨ معرفی و ویژگی‌های کلیدی
+
+| ویژگی | توضیحات |
+| :--- | :--- |
+| 🕒 **ساعت دقیق تهران (`UTC+03:30`)** | محاسبه مستقل از منطقه زمانی ویندوز؛ نمایش همیشه دقیق ساعت رسمی ایران |
+| 📅 **تقویم شمسی و قمری ۱۰۰٪ آفلاین** | دیتابیس کامل مناسبت‌های ملی، باستانی و مذهبی ایران و تشخیص روزهای تعطیل رسمی بدون نیاز به اینترنت |
+| 🖋 **خط دور مشکی (`Black Outline`) و ابعاد پویا** | رسم حاشیه مشکی دور تمام اعداد و نوشته‌ها برای خوانایی کامل روی هر والپیپر + محاسبه خودکار ابعاد برای جلوگیری از بریده شدن متون در فونت‌های بسیار کوچک یا بزرگ |
+| 🔒 **قفل هوشمند و عبوردهی کلیک (`Click-Through`)** | قرارگیری دکمه قفل در بالا-چپ داخل ویجت؛ در حالت قفل، کلیک ماوس در ناحیه مشترک مستقیماً روی اپلیکیشن زیرین کار می‌کند و **فقط خود دکمه قفل** قابل کلیک است |
+| ⏰ **سیستم آلارم و یادآور حرفه‌ای + تقویم چندانتخابی** | انتخاب روزها به شکل **تقویم گرافیکی چندانتخابی (Multi-Select)**، هر روز یا روزهای خاص هفته، با ۶ صدای MP3 داخلی (پیش‌فرض `heeeeyyyyy.mp3`)، زنگوله متحرک مرکز صفحه و **حذف خودکار آلارم‌های منقضی‌شده** |
+| 📋 **ابزار کپی ۱۰ فرمت زمان API + تولیدکننده GUID** | کپی سریع **۱۰ فرمت پرکاربرد تاریخ و ساعت برای پر کردن APIها** (تاریخ و ساعت با هم، تاریخ جدا، ساعت جدا، تایم‌استمپ) + **تولید و کپی فوری `GUID / UUID v4`** |
+| 🔤 **فونت پیش‌فرض وزیر (`Vazir`) + فونت‌های باندل‌شده** | تنظیم پیش‌فرض روی فونت **وزیر (`Vazir`)** به همراه فونت‌های **بی‌یکان پلاس (`B Yekan+`)** و **ایرانیان سنس (`A Iranian Sans`)** در داخل فایل `.exe` بدون نیاز به نصب فونت در ویندوز |
+| ✨ **افکت Hover و راهنمای شناور (Tooltip)** | تغییر رنگ زیبا و نمایش توضیحات شناور هنگام نگه داشتن ماوس روی تمام آیکون‌های ویجت و تقویم |
+| ⭐ **جایگزینی کامل ساعت و تاریخ ویندوز در تسک‌بار (با یک تیک)** | پوشاندن ۱۰۰٪ مات ساعت و تاریخ پیش‌فرض انگلیسی ویندوز با ساعت دقیق تهران و تاریخ شمسی در گوشه تسک‌بار؛ با کلیک چپ تقویم بالای ساعت باز می‌شود، با راست‌کلیک تنظیمات در دسترس است و ماوس روی آن Hover و Tooltip دارد + امکان مخفی کردن ویجت دسکتاپ و نمایش اختصاصی در تسک‌بار |
+| 👻 **اجرا در پس‌زمینه (فقط در Hidden Icons)** | بدون اشغال هیچ فضایی در نوار وظیفه (`Taskbar`) یا `Alt+Tab`؛ حضور تمیز در بخش `System Tray` کنار ساعت ویندوز با قابلیت اجرا در `Startup` |
+
+---
+
+## 📂 ساختار پوشه‌ها و معماری پروژه
+
+پروژه با ساختار ماژولار و استاندارد زیر سازماندهی شده است و فایل اجرایی مستقل در پوشه مجزای `release/` قرار دارد:
+
+```text
+persian-clock-widget/
+├── assets/                        # منابع گرافیکی، فونت‌ها و فایل‌های صوتی باندل‌شده
+│   ├── fonts/                     # فونت‌های فارسی داخلی (بدون نیاز به نصب در ویندوز)
+│   │   ├── BYekan+ Bold.ttf
+│   │   ├── Iranian Sans.ttf
+│   │   └── Vazir-Medium.ttf
+│   ├── icons/                     # آیکون‌های اختصاصی برنامه و System Tray
+│   │   ├── app_icon.ico
+│   │   └── app_icon.png
+│   └── sounds/                    # فایل‌های صوتی MP3 آلارم (پیش‌فرض: heeeeyyyyy.mp3)
+│       ├── heeeeyyyyy.mp3         # ⭐ صدای پیش‌فرض آلارم
+│       ├── alarm.mp3
+│       ├── axel.mp3
+│       ├── liilililililililii.mp3
+│       ├── morning_glory.mp3
+│       └── peter_axel_f.mp3
+├── data/                          # محل ذخیره تنظیمات کاربر، آلارم‌ها و مناسبت‌های شخصی
+│   ├── alarms.json                # لیست رویدادها و آلارم‌های ثبت‌شده توسط کاربر
+│   ├── config.json                # تنظیمات ظاهری، مکان، رنگ‌ها و فونت
+│   └── custom_occasions.json      # فایل افزودن مناسبت‌های شخصی آفلاین
+├── release/                       # 📦 خروجی‌های نهایی ویندوز و لینوکس
+│   ├── windows/                   # نسخه مستقل ویندوز (Portable EXE & ZIP)
+│   │   ├── PersianClockWidget.exe
+│   │   └── PersianClockWidget.zip
+│   └── linux/                     # بسته‌های نصبی و پرتابل لینوکس
+│       ├── persian-clock-widget_1.0.0_all.deb
+│       ├── PersianClockWidget-Linux-Installer.sh
+│       ├── PersianClockWidget-linux-portable.tar.gz
+│       └── INSTALL-LINUX.txt      # نوت دستورات سریع نصب در لینوکس
+├── scripts/                       # اسکریپت ساخت فایل اجرایی
+│   └── build_exe.bat              # اسکریپت کامپایل خودکار به فایل exe در پوشه release/
+├── src/                           # کدهای منبع اصلی برنامه (Source Code)
+│   ├── __init__.py
+│   ├── alarm_manager.py           # مدیریت آلارم‌ها، پخش صدا و پاپ‌آپ زنگوله متحرک
+│   ├── calendar_data.py           # مبدل تقویم شمسی/قمری/میلادی و دیتابیس مناسبت‌ها
+│   ├── icon_generator.py          # تولیدکننده آیکون برداری ساعت و تقویم فارسی
+│   ├── widget.py                  # رابط گرافیکی اصلی ویجت، تقویم ماهانه و پنجره تنظیمات
+│   ├── taskbar_clock.py           # ساعت روی تسک‌بار و آیکون برنامه در تسک‌بار
+│   └── win_utils.py               # توابع Win32 API (Z-Index، Click-Through، فونت، صدا و Tray)
+├── .gitignore
+├── LICENSE                        # مجوز انتشار MIT (® Shayan Bamyar)
+├── main.py                        # نقطه ورود اصلی برنامه (Main Entry Point)
+├── requirements.txt               # وابستگی‌های پایتون برای توسعه
+└── README.md                      # مستندات کامل پروژه
+```
+
+---
+
+## 🚀 نحوه دانلود و اجرای سریع (بدون نیاز به پایتون)
+
+اگر نمی‌خواهید پایتون یا هیچ پیش‌نیازی روی سیستم نصب کنید:
+1. وارد پوشه **[`release/windows/`](release/windows/)** شوید.
+2. فایل **[`PersianClockWidget.exe`](release/windows/PersianClockWidget.exe)** را اجرا کنید (می‌توانید این تک‌فایل را به هر کامپیوتر دیگری هم منتقل کنید؛ تمام فونت‌ها، آیکون‌ها و صداهای آلارم در داخل خود فایل `.exe` قرار دارند).
+3. ویجت در گوشه بالا-راست مانیتور ظاهر می‌شود و آیکون آن در بخش **Hidden Icons (کنار ساعت ویندوز)** قرار می‌گیرد.
+
+---
+
+## 📖 راهنمای کامل امکانات و نحوه کارکرد
+
+### ۱. دکمه قفل هوشمند (`🔒` / `🔓`)، حذف فضای خالی و چسبیدن به لبه مانیتور
+در گوشه **بالا-سمت چپ در داخل ویجت** یک دکمه کوچک قفل قرار دارد:
+- **حالت باز (`🔓` آبی)**:
+  - می‌توانید ویجت را با کشیدن ماوس (**Drag & Drop**) در هر نقطه‌ای از مانیتور قرار دهید (مختصات به صورت خودکار ذخیره می‌شود).
+  - نوار دکمه‌های `◂ تقویم`، `📋`، `GUID`، `⏰`، `⚙` و `🗕` (مینیمایز) در کنار دکمه قفل نمایش داده می‌شوند و قابل کلیک هستند.
+- **حالت قفل و فیکس هوشمند (`🔒` طلایی)**:
+  - با کلیک روی `🔓`، تقویم باز خودکار بسته می‌شود و نوار دکمه‌ها مخفی می‌گردد.
+  - **حذف کامل فضای خالی و حداقل اندازه (Ultra-Minimal)**: ابعاد ویجت دقیقاً به اندازه متن ساعت و تاریخ کوچک شده و نوشته فوتر (`® Shayan Bamyar`) در حالت قفل محو می‌شود تا کمترین فضای ممکن را از صفحه اشغال کند.
+  - **چسبیدن خودکار به لبه صفحه (Smart Edge Docking)**: اگر ویجت در نیمه راست صفحه باشد کاملاً به **لبه راست مانیتور** می‌چسبد و اگر در نیمه چپ باشد به **لبه چپ مانیتور** متصل می‌شود.
+  - پنجره ویجت با ویژگی سیستمی `WS_EX_TRANSPARENT | WS_EX_LAYERED` ویندوز کاملاً **Click-Through (عبوردهنده کلیک)** می‌شود؛ یعنی کلیک در ناحیه مشترک مستقیماً روی اپلیکیشن زیرین کار می‌کند و هیچ جای ویجت به‌جز **خود دکمه کوچک قفل (`🔒`)** کلیک را جذب نمی‌کند.
+  - هر زمان که دوباره روی دکمه `🔒` کلیک کنید، ویجت از حالت قفل خارج شده و نوار ابزار در دسترس قرار می‌گیرد.
+
+### ۱.۱. قابلیت مینیمایز (مخفی کردن از صفحه؛ فقط در تسک‌بار و Hidden Icons)
+- با کلیک روی دکمه **`🗕`** (یا از منوی راست‌کلیک)، پنجره ویجت از روی صفحه دسکتاپ محو شده و **فقط در تسک‌بار و بخش Hidden Icons (کنار ساعت ویندوز)** قرار می‌گیرد.
+- با یک کلیک روی آیکون برنامه در تسک‌بار یا آیکون Tray، ویجت بلافاصله به مکان قبلی خود بازمی‌گردد.
+
+### ۲. کنترل لایه نمایش (`Z-Index`)
+از طریق پنجره تنظیمات (`⚙`) یا منوی راست‌کلیک می‌توانید نحوه قرارگیری ویجت نسبت به سایر پنجره‌ها را تعیین کنید:
+- **همیشه روی تمام برنامه‌ها (`Topmost` - پیش‌فرض)**: حتی اگر برنامه جدیدی باز شود، ویجت روی آن باقی می‌ماند.
+- **چسبیده به والپیپر دسکتاپ (`Desktop`)**: ویجت مانند گجت‌های کلاسیک ویندوز روی تصویر زمینه دسکتاپ و در پشت پنجره‌های باز قرار می‌گیرد.
+
+### ۳. تقویم ماهانه بازشونده (`Extend`) و مناسبت‌ها
+- با کلیک روی دکمه **`◂ تقویم`** (یا دابل‌کلیک روی ویجت)، پنل کامل تقویم ماهانه در کنار ویجت باز می‌شود.
+- با دکمه‌های `‹` و `›` می‌توانید ماه‌های سال را ورق بزنید و با دکمه **`امروز`** به تاریخ جاری برگردید.
+- روزهای تعطیل رسمی و جمعه‌ها با **رنگ قرمز مرجانی** و روزهای دارای مناسبت یا یادآور شخصی با **نقطه رنگی (`•`)** در زیر عدد روز مشخص می‌شوند.
+- با **کلیک روی هر روز از ماه**، مناسبت‌های شمسی و قمری و آلارم‌های ثبت‌شده آن روز در پایین تقویم نمایش داده می‌شوند.
+- اگر روزی هیچ مناسبتی نداشته باشد، هیچ عبارت اضافه‌ای (مانند «بدون مناسبت») نوشته نمی‌شود و فضای ویجت به شکل مینیمال جمع می‌شود.
+- **🎂 ثبت مناسبت‌های شخصی و تولد دوستان + آلارم خودکار ۱ روز قبل**:
+  - با کلیک روی دکمه **`🎂 + مناسبت / تولد`** در پایین تقویم (یا از منوی راست‌کلیک)، می‌توانید روز تولد دوستان، سالگردها یا تعطیلات شخصی را برای هر روز و ماه شمسی روی تقویم ثبت کنید.
+  - با فعال ماندن تیک **«ثبت خودکار آلارم یادآور ۱ روز قبل (تکرار سالانه)»**، برنامه به‌صورت خودکار هر سال یک روز قبل از تاریخ تولد/مناسبت (حتی اگر روز اول ماه باشد، در روز آخر ماه قبل) در ساعت دلخواه شما آلارم می‌گذارد تا هرگز تولدی را فراموش نکنید.
+
+### ۴. سیستم رویداد، یادآور و آلارم (`⏰`) با تقویم چندانتخابی و حذف خودکار
+با کلیک روی دکمه **`⏰`** در بالای ویجت (یا دکمه **`⏰ + ثبت آلارم / رویداد`** در پایین تقویم ماهانه)، پنجره مدیریت آلارم‌ها باز می‌شود:
+- **تعیین متن و ساعت**: می‌توانید عنوان/متن دلخواه و ساعت و دقیقه دقیق (به وقت تهران) را وارد کنید.
+- **۳ حالت زمان‌بندی و تکرار**:
+  1. **انتخاب از روی تقویم (تک‌روز یا چند روز خاص - Multi-Select)**: یک تقویم شمسی گرافیکی و تعاملی باز می‌شود که می‌توانید با کلیک روی روزهای مختلف (حتی در ماه‌های مختلف)، **یک یا چند روز خاص** را هم‌زمان انتخاب یا از انتخاب خارج کنید.
+  2. **هر روز (`Daily`)**: تکرار روزانه در ساعت مشخص‌شده.
+  3. **روزهای خاص هفته (`Weekly`)**: انتخاب یک یا چند روز از هفته (مثلاً **هر دوشنبه** و **هر چهارشنبه**).
+- **انتخاب صدای آلارم MP3 و تست زنده**:
+  - شامل ۶ صدای آلارم داخلی (`heeeeyyyyy.mp3` به عنوان پیش‌فرض، `alarm.mp3`، `axel.mp3`، `liilililililililii.mp3`، `morning_glory.mp3` و `peter_axel_f.mp3`).
+  - با دکمه **`▶ تست صدا`** می‌توانید صدای انتخابی را قبل از ذخیره گوش دهید و با دکمه **`🔔 پیش‌نمایش زنگوله + صدا`** کل هشدار را شبیه‌سازی کنید.
+- **پاپ‌آپ مرکز مانیتور در زمان سررسید و حذف خودکار پس از انقضا**:
+  - در لحظه رسیدن زمان آلارم، یک پنجره دارک در **مرکز مانیتور** باز می‌شود که یک **زنگوله طلایی متحرک در حال تکان خوردن و زنگ زدن** به همراه ساعت و متن اختصاصی شما را نمایش می‌دهد و صدای انتخابی را پخش می‌کند.
+  - دارای دکمه **`✓ متوجه شدم (قطع آلارم)`** و دکمه **`💤 ۵ دقیقه دیگر (Snooze)`**.
+  - **پاک‌سازی هوشمند**: وقتی زمان یک آلارم تاریخ‌محور بگذرد و به تاخیر (`Snooze`) نیفتد، آن تاریخ (یا کل آلارم در صورت تمام شدن تمام روزهای انتخاب‌شده) **به‌طور خودکار از لیست پاک می‌شود** تا لیست آلارم‌ها همیشه تمیز بماند.
+- **مدیریت کامل لیست**: امکان **ویرایش (`✏️`)**، **حذف (`🗑`)** و **فعال/غیرفعال‌سازی** هر یک از آلارم‌ها.
+
+### ۵. ابزار کپی زمان برای برنامه‌نویسان (`📋`) + تولیدکننده `GUID`
+برنامه‌نویسان می‌توانند با کلیک روی آیکون **`📋`** (که با فاصله استاندارد از ویجت باز می‌شود تا روی ساعت را نپوشاند)، **۱۰ فرمت پرکاربرد تاریخ و ساعت برای پر کردن APIها** و همچنین **`GUID (UUID v4)`** را در لحظه کپی کنند:
+- **بخش ۱: تاریخ و ساعت با هم (`Date & Time - API / ISO / DB`)**:
+  1. `ISO-8601 UTC (ms)`: فرمت استاندارد جهانی با میلی‌ثانیه (`2026-11-11T06:15:12.340Z`)
+  2. `ISO-8601 Tehran (ms)`: فرمت استاندارد تهران با آفست (`2026-11-11T09:45:12.340+03:30`)
+  3. `SQL / API DateTime`: فرمت دیتابیس و کوئری با میلی‌ثانیه (`2026-11-11 09:45:12.340`)
+  4. `Jalali DateTime (ms)`: تاریخ و ساعت شمسی کامل با میلی‌ثانیه (`1405/08/20 09:45:12.340`)
+- **بخش ۲: فقط تاریخ جدا (`Date Only`)**:
+  5. `Date Only (Gregorian)`: فقط تاریخ میلادی (`2026-11-11`)
+  6. `Date Only (Jalali)`: فقط تاریخ شمسی (`1405/08/20`)
+- **بخش ۳: فقط ساعت جدا (`Time Only`)**:
+  7. `Time Only + ms (Tehran)`: فقط ساعت دقیق به همراه میلی‌ثانیه (`09:45:12.340`)
+  8. `Time Only (HH:MM:SS)`: فقط ساعت استاندارد بدون میلی‌ثانیه (`09:45:12`)
+- **بخش ۴: تایم‌استمپ عددی (`Epoch / Unix Timestamp`)**:
+  9. `Unix Timestamp (ms)`: زمان یونیکس بر حسب میلی‌ثانیه (`1794377712340`)
+  10. `Unix Timestamp (sec)`: زمان یونیکس بر حسب ثانیه (`1794377712`)
+- **بخش ۵: رندر و کپی `GUID / UUID v4`**:
+  - `🎲 Render & Copy GUID (v4)`: تولید و کپی GUID استاندارد حروف کوچک (`xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`)
+  - `🎲 Render GUID (UPPERCASE)`: تولید و کپی GUID با حروف بزرگ
+  - `🎲 Render GUID (No Hyphens)`: تولید و کپی GUID ۳۲ کاراکتری بدون خط تیره
+  - `🎲 Copy Empty GUID`: کپی GUID صفر (`00000000-0000-0000-0000-000000000000`)
+- **کپی یکجای `JSON`**: گزینه `📦 Copy All as JSON Object` برای کپی تمام مقادیر بالا در یک آبجکت JSON.
+
+### ۶. پنجره تنظیمات ظاهری، رنگ، سایز و فونت (`⚙`)
+با کلیک روی دکمه **`⚙`** (یا از منوی راست‌کلیک در System Tray)، پنجره تنظیمات باز می‌شود و تغییرات را **به صورت زنده (Live Preview)** اعمال می‌کند:
+- **با پس‌زمینه یا بدون پس‌زمینه**: امکان حذف کامل کادر کارت (نمایش فقط نوشته‌ها با خط دور مشکی روی تصویر زمینه) یا تنظیم درصد شفافیت (`Opacity` از ۲۵٪ تا ۱۰۰٪).
+- **انتخاب رنگ مجزا برای تمام بخش‌ها**: انتخابگر رنگ (`Color Picker`) برای **رنگ ساعت**، **رنگ تاریخ شمسی**، **رنگ مناسبت‌ها**، **رنگ روزهای تعطیل**، **رنگ کارت پس‌زمینه** و **رنگ دکمه‌ها**.
+- **تنظیم اندازه کلی ویجت و فونت‌ها**:
+  - اسلایدر **بزرگ‌نمایی کلی ویجت** (`70%` تا `170%`).
+  - انتخاب **نوع فونت متون و ساعت** (شامل فونت‌های فارسی باندل‌شده `Vazir`، `B Yekan+` و `A Iranian Sans` + فونت‌های سیستم).
+  - تنظیم جداگانه **سایز فونت ساعت**، **سایز فونت تاریخ** و **سایز فونت مناسبت**.
+- **نمایش و جایگزینی در تسک‌بار ویندوز** (قابل فعال‌سازی با یک تیک؛ پیش‌فرض خاموش):
+  - **⭐ جایگزینی کامل ساعت و تاریخ ویندوز در تسک‌بار (`Replace Windows Clock`)**:
+    - **با یک تیک**، پنجره ساعت و تاریخ شمسی مستقیماً **به داخل نوار تسک‌بار ویندوز (`Shell_TrayWnd`) متصل (`SetParent`)** می‌شود تا کاملاً جزئی از تسک‌بار باشد (نه پنجره شناور روی برنامه‌های تمام‌صفحه).
+    - **تشخیص خودکار رنگ تسک‌بار (`Auto Theme & Pixel Sample`)**: رنگ پس‌زمینه تسک‌بار ویندوز ۱۰/۱۱ (تم تیره یا روشن) را به‌طور خودکار تشخیص داده و با آن یکدست می‌شود؛ در ویندوز ۱۰ ساعت کلاسیک `TrayClockWClass` را مخفی می‌کند و در ویندوز ۱۱ گزینه مستقیم **حذف ساعت و تاریخ انگلیسی از تسک‌بار (`HideSystrayDateTimeValueName`)** نیز در تنظیمات تعبیه شده است.
+    - در دو خط منظم و زیبا: خط بالا ساعت دقیق تهران با خط دور مشکی (`Outlined`) و خط پایین تاریخ شمسی استاندارد (همراه با رنگ تفکیک‌شده روزهای تعطیل) را نمایش می‌دهد.
+    - **کلیک چپ**: باز و بسته کردن تقویم ماهانه شمسی دقیقاً بالای ساعت گوشه تسک‌بار (مشابه کلیک روی ساعت ویندوز).
+    - **کلیک راست**: دسترسی فوری به منوی کامل برنامه و تنظیمات.
+    - **افکت Hover و Tooltip شناور**: با نگه داشتن ماوس، پس‌زمینه هایلایت شده و تولتیپ شناور شامل نام روز، تاریخ کامل و مناسبت روز بالای ساعت نمایش داده می‌شود.
+    - **جابه‌جایی دستی (Drag)**: با کلیک و کشیدن ماوس به چپ یا راست، موقعیت قرارگیری روی ساعت ویندوز تنظیم شده و فاصله به صورت خودکار در `config.json` ذخیره می‌شود.
+    - **👁️ مخفی کردن ویجت دسکتاپ (اختیاری)**: اگر مایل باشید هیچ ویجت شناوری روی دسکتاپ نباشد و تنها ساعت تسک‌بار نمایش داده شود، با تیک زدن گزینه *«مخفی کردن ویجت دسکتاپ هنگام فعال بودن جایگزینی»*، ویجت شناور مخفی شده و تقویم مستقیماً از روی ساعت تسک‌بار باز و بسته می‌شود.
+    - **دکمه‌های بازنشانی و انتخاب رنگ**: دکمه بازنشانی موقعیت به گوشه مانیتور و انتخابگر رنگ پس‌زمینه برای هماهنگی با هر رنگ و پوسته‌ای از ویندوز.
+  - **🕒 ساعت و تاریخ شمسی شناور روی تسک‌بار (حالت شفاف)**: ساعت تهران و تاریخ شمسی را با پس‌زمینه شفاف در کنار ساعت ویندوز نمایش می‌دهد.
+  - **📌 آیکون برنامه در تسک‌بار**: یک دکمه مجزا در تسک‌بار اضافه می‌کند که با کلیک، تقویم ماهانه باز و بسته می‌شود.
+
+---
+
+## 💻 اجرا از طریق سورس کد پایتون
+
+اگر مایل به اجرای مستقیم از روی سورس کد یا توسعه پروژه هستید:
+
+```powershell
+# ۱. نصب پیش‌نیازها
+pip install -r requirements.txt
+
+# ۲. اجرای برنامه (با کنسول یا بدون کنسول)
+pythonw main.py
+```
+
+---
+
+## 🛠 نحوه ساخت مجدد فایل اجرایی (`.exe` و خروجی لینوکس)
+
+### ویندوز:
+برای کامپایل مجدد پروژه و ساخت فایل تک‌فایلی `PersianClockWidget.exe` در پوشه `release/` (به همراه تعبیه خودکار فونت‌ها، آیکون و صداهای MP3)، کافی است اسکریپت زیر را اجرا کنید:
+
+```bat
+scripts\build_exe.bat
+```
+پس از اتمام، فایل اجرایی مستقل در مسیر `release\PersianClockWidget.exe` آماده خواهد بود.
+
+### لینوکس (`Linux`):
+> 🐧 **راهنمای کامل و اختصاصی نصب و اجرا در لینوکس:** [README-LINUX.md](README-LINUX.md)
+
+دو فایل نصبی آماده برای لینوکس در پوشه `release/linux/` قرار دارد:
+1. **فایل نصبی دبیان / اوبونتو (`.deb`)**: [persian-clock-widget_1.0.0_all.deb](release/linux/persian-clock-widget_1.0.0_all.deb)
+   ```bash
+   sudo apt install ./persian-clock-widget_1.0.0_all.deb
+   ```
+   *(پیش‌نیاز `python3-tk`، فونت‌های وزیر، آیکون و میانبر منوی برنامه‌ها را خودکار نصب می‌کند).*
+2. **نصب‌کننده تک‌فایلی تمام توزیع‌ها (`.sh`)**: [PersianClockWidget-Linux-Installer.sh](release/linux/PersianClockWidget-Linux-Installer.sh)
+   ```bash
+   bash PersianClockWidget-Linux-Installer.sh
+   ```
+   *(فایل‌ها، فونت‌ها، میانبر منوی برنامه‌ها و اجرای خودکار با شروع لینوکس را نصب و بلافاصله اجرا می‌کند).*
+3. **نوت دستورات سریع نصب**: [INSTALL-LINUX.txt](release/linux/INSTALL-LINUX.txt)
+
+گزینه **«اجرا خودکار با شروع ویندوز / لینوکس (Startup)»** هم در پنجره تنظیمات (`⚙`) و هم در منوی راست‌کلیک در دسترس است.
+
+---
+
+## 👨‍💻 طراح و توسعه‌دهنده (حق ناشر)
+
+طراحی، معماری و توسعه توسط **شایان بامیار (`® Shayan Bamyar`)** انجام شده است.  
+منتشر شده تحت مجوز [MIT License](LICENSE).
+
+</div>

package/bin/persian-clock.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawn, spawnSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
+const rootDir = path.resolve(__dirname, "..");
+const winExe = path.join(rootDir, "release", "windows", "PersianClockWidget.exe");
+const mainPy = path.join(rootDir, "main.py");
+
+function launchDetached(cmd, args, cwd) {
+  const child = spawn(cmd, args, {
+    cwd,
+    detached: true,
+    stdio: "ignore",
+    windowsHide: false,
+  });
+  child.unref();
+}
+
+if (process.platform === "win32" && fs.existsSync(winExe)) {
+  console.log("Launching Persian Clock & Calendar Widget (Windows)...");
+  launchDetached(winExe, [], rootDir);
+  process.exit(0);
+}
+
+const pyCandidates = process.platform === "win32" ? ["python", "python3", "py"] : ["python3", "python"];
+let pyBin = null;
+
+for (const candidate of pyCandidates) {
+  const res = spawnSync(candidate, ["--version"], { stdio: "ignore" });
+  if (res.status === 0) {
+    pyBin = candidate;
+    break;
+  }
+}
+
+if (!pyBin) {
+  console.error("Error: Python 3 is required on this platform.");
+  if (process.platform === "linux") {
+    console.error("Install it with: sudo apt install python3 python3-tk");
+  }
+  process.exit(1);
+}
+
+const tkCheck = spawnSync(pyBin, ["-c", "import tkinter"], { stdio: "ignore" });
+if (tkCheck.status !== 0) {
+  console.error("Error: python3-tk (Tkinter) is not installed.");
+  if (process.platform === "linux") {
+    console.error("  Ubuntu/Debian: sudo apt update && sudo apt install -y python3-tk");
+    console.error("  Fedora:        sudo dnf install -y python3-tkinter");
+    console.error("  Arch/Manjaro:  sudo pacman -S tk");
+  }
+  process.exit(1);
+}
+
+console.log("Launching Persian Clock & Calendar Widget...");
+launchDetached(pyBin, [mainPy], rootDir);
+process.exit(0);

package/main.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+نقطه ورود اصلی برنامه (Main Entry Point)
+ویجت ساعت تهران، تقویم شمسی، مناسبت‌ها و سیستم یادآور ویندوز
+طراحی و توسعه: شایان بامیار (® Shayan Bamyar)
+"""
+
+import os
+import sys
+
+# افزودن پوشه ریشه پروژه به مسیر جستجوی ماژول‌ها
+ROOT_DIR = os.path.dirname(os.path.abspath(__file__))
+if ROOT_DIR not in sys.path:
+    sys.path.insert(0, ROOT_DIR)
+
+from src.widget import PersianClockWidget
+
+
+def main():
+    app = PersianClockWidget()
+    app.run()
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "persian-clock-widget",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Tehran Clock, Jalali Calendar, Personal Birthdays & Alarms Desktop Widget for Windows and Linux",
+  "bin": {
+    "persian-clock-widget": "bin/persian-clock.js",
+    "persian-clock": "bin/persian-clock.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "assets/",
+    "main.py",
+    "requirements.txt",
+    "README.md",
+    "README-LINUX.md",
+    "LICENSE",
+    "release/windows/PersianClockWidget.exe"
+  ],
+  "keywords": [
+    "persian",
+    "clock",
+    "jalali",
+    "shamsi",
+    "calendar",
+    "widget",
+    "tehran",
+    "alarm",
+    "windows",
+    "linux"
+  ],
+  "author": "Shayan Bamyar",
+  "license": "MIT",
+  "os": [
+    "win32",
+    "linux"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}

package/requirements.txt

@@ -0,0 +1,3 @@
+pywin32>=306
+Pillow>=10.0.0
+pyinstaller>=6.0.0

package/src/__init__.py

@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""
+پکیج اصلی ویجت ساعت تهران، تقویم شمسی و سیستم یادآور ویندوز
+طراحی و توسعه: شایان بامیار (® Shayan Bamyar)
+"""
+
+__version__ = "2.0.0"
+__author__ = "Shayan Bamyar"