pytron-kit 0.3.12__py3-none-macosx_11_0_universal2.whl

pytron/installer/Installation.nsi

@@ -0,0 +1,236 @@
+; Pytron NSIS Installer Script (polished)
+; - Expects BUILD_DIR to be defined when invoking makensis
+; - Uses assets found in the same directory as this script
+
+!include "MUI2.nsh"
+!include "LogicLib.nsh"
+!include "WinMessages.nsh"
+
+; ---------------------
+; ---------------------
+; Configurable values
+; ---------------------
+!ifndef NAME
+  !define NAME "Pytron"
+!endif
+!ifndef VERSION
+  !define VERSION "1.0"
+!endif
+!ifndef COMPANY
+  !define COMPANY "Pytron User"
+!endif
+!ifndef DESCRIPTION
+  !define DESCRIPTION "${NAME} Installer"
+!endif
+!ifndef COPYRIGHT
+  !define COPYRIGHT "Copyright © 2025 ${COMPANY}"
+!endif
+!ifndef BUILD_DIR
+  !error "BUILD_DIR must be defined"
+!endif
+!ifndef MAIN_EXE_NAME
+  !define MAIN_EXE_NAME "Pytron.exe"
+!endif
+!ifndef OUT_DIR
+  !define OUT_DIR "$EXEDIR"
+!endif
+
+Name "${NAME}"
+OutFile "${OUT_DIR}\${NAME}_Installer_${VERSION}.exe"
+InstallDir "$PROGRAMFILES\\${NAME}"
+InstallDirRegKey HKLM "Software\${NAME}" "Install_Dir"
+; Explicitly set the installer icon if defined
+!ifdef MUI_ICON
+  Icon "${MUI_ICON}"
+!endif
+!ifdef MUI_UNICON
+  UninstallIcon "${MUI_UNICON}"
+!endif
+RequestExecutionLevel admin
+
+; Version Info for the Installer EXE
+VIProductVersion "${VERSION}.0.0"
+VIAddVersionKey "ProductName" "${NAME}"
+VIAddVersionKey "CompanyName" "${COMPANY}"
+VIAddVersionKey "LegalCopyright" "${COPYRIGHT}"
+VIAddVersionKey "FileDescription" "${DESCRIPTION}"
+VIAddVersionKey "FileVersion" "${VERSION}"
+VIAddVersionKey "ProductVersion" "${VERSION}"
+
+; Use ZLIB compression for better AV compatibility (LZMA often flagged)
+SetCompressor /SOLID zlib
+; SetCompressorDictSize 32 ; Not applicable for zlib usually, or default is fine
+
+; Welcome/Finish Page Image (Left side)
+!define MUI_WELCOMEFINISHPAGE_BITMAP "sidebar.bmp"
+!define MUI_UNWELCOMEFINISHPAGE_BITMAP "sidebar.bmp"
+
+; Finish Page options
+!define MUI_FINISHPAGE_RUN "$INSTDIR\${MAIN_EXE_NAME}"
+!define MUI_FINISHPAGE_RUN_TEXT "Run ${NAME}"
+!define MUI_FINISHPAGE_LINK "Built with Pytron"
+!define MUI_FINISHPAGE_LINK_LOCATION "https://github.com/Ghua8088/pytron"
+
+; ---------------------
+; Detect Existing Install
+; ---------------------
+Var IS_UPDATE
+
+Function .onInit
+    ReadRegStr $R0 HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\${NAME}" "UninstallString"
+    ${If} $R0 != ""
+        StrCpy $IS_UPDATE "1"
+        ReadRegStr $INSTDIR HKLM "Software\${NAME}" "Install_Dir"
+        
+        ; Check if the application is running
+        check_running:
+        ClearErrors
+        FileOpen $0 "$INSTDIR\${MAIN_EXE_NAME}" "a"
+        FileClose $0
+        IfErrors 0 not_running
+
+        MessageBox MB_RETRYCANCEL|MB_ICONEXCLAMATION "${NAME} is still running. Please close it before updating." IDRETRY check_running
+        Quit
+    ${Else}
+        StrCpy $IS_UPDATE "0"
+    ${EndIf}
+    not_running:
+FunctionEnd
+
+; ---------------------
+; Pages
+; ---------------------
+!define MUI_PAGE_CUSTOMFUNCTION_SHOW WelcomeShow
+!insertmacro MUI_PAGE_WELCOME
+
+Function WelcomeShow
+    ${If} $IS_UPDATE == "1"
+        ; MUI2 Welcome/Finish pages are special child dialogs (#32770)
+        FindWindow $1 "#32770" "" $HWNDPARENT
+        ; 1000 is the title control, 1001 is the text control
+        GetDlgItem $0 $1 1000
+        SendMessage $0 ${WM_SETTEXT} 0 "STR:Welcome to the ${NAME} Update/Repair Wizard"
+        GetDlgItem $0 $1 1001
+        SendMessage $0 ${WM_SETTEXT} 0 "STR:This wizard will guide you through updating or fixing your existing installation of ${NAME}.$\r$\n$\r$\nClick Next to continue."
+    ${EndIf}
+FunctionEnd
+
+; !insertmacro MUI_PAGE_LICENSE "${BUILD_DIR}\\LICENSE.txt" ; Uncomment if you have a license
+!insertmacro MUI_PAGE_DIRECTORY
+!insertmacro MUI_PAGE_INSTFILES
+
+!define MUI_PAGE_CUSTOMFUNCTION_SHOW FinishShow
+!insertmacro MUI_PAGE_FINISH
+
+Function FinishShow
+    ${If} $IS_UPDATE == "1"
+        FindWindow $1 "#32770" "" $HWNDPARENT
+        GetDlgItem $0 $1 1000
+        SendMessage $0 ${WM_SETTEXT} 0 "STR:Update/Repair Complete"
+    ${EndIf}
+FunctionEnd
+
+!insertmacro MUI_UNPAGE_WELCOME
+; Custom uninstaller page for data deletion
+Var DeleteAppDataCheckbox
+Var DELETE_APPA_DATA
+UninstPage custom un.ConfirmDataPage un.ConfirmDataPageLeave
+!insertmacro MUI_UNPAGE_CONFIRM
+!insertmacro MUI_UNPAGE_INSTFILES
+!insertmacro MUI_UNPAGE_FINISH
+
+!include "nsDialogs.nsh"
+
+Function un.ConfirmDataPage
+    nsDialogs::Create 1018
+    Pop $0
+    ${If} $0 == error
+        Abort
+    ${EndIf}
+
+    ${NSD_CreateLabel} 0 0 100% 24u "Uninstall ${NAME}"
+    ${NSD_CreateLabel} 0 30u 100% 24u "Do you want to delete your application data (settings, cache, etc)?$\r$\nThis cannot be undone."
+    
+    ${NSD_CreateCheckbox} 0 60u 100% 10u "Delete application data ($LOCALAPPDATA\${NAME})"
+    Pop $DeleteAppDataCheckbox
+    
+    nsDialogs::Show
+FunctionEnd
+
+Function un.ConfirmDataPageLeave
+    ${NSD_GetState} $DeleteAppDataCheckbox $0
+    StrCpy $DELETE_APPA_DATA $0
+FunctionEnd
+
+!insertmacro MUI_LANGUAGE "English"
+ 
+; ---------------------
+; Uninstaller Initialization
+; ---------------------
+Function un.onInit
+    ; Check if the application is running by trying to open the EXE for writing
+    un.check_running:
+    ClearErrors
+    FileOpen $0 "$INSTDIR\${MAIN_EXE_NAME}" "a"
+    FileClose $0
+    IfErrors 0 un.not_running
+
+    MessageBox MB_RETRYCANCEL|MB_ICONEXCLAMATION "${NAME} is still running. Please close it before uninstalling." IDRETRY un.check_running
+    Quit
+
+    un.not_running:
+FunctionEnd
+
+; ---------------------
+; Installation section
+; ---------------------
+Section "Install"
+    ; Ensure the install directory exists and copy all built files
+    SetOutPath "$INSTDIR"
+    SetOverwrite on
+    File /r "${BUILD_DIR}\*.*"
+
+    ; Write useful uninstall registry entries
+    WriteRegStr HKLM "Software\${NAME}" "Install_Dir" "$INSTDIR"
+    WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\${NAME}" "DisplayName" "${NAME}"
+    WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\${NAME}" "DisplayVersion" "${VERSION}"
+    WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\${NAME}" "Publisher" "${COMPANY}"
+    WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\${NAME}" "InstallLocation" "$INSTDIR"
+    WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\${NAME}" "UninstallString" "$INSTDIR\\uninstall.exe"
+    WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\${NAME}" "DisplayIcon" "$INSTDIR\${MAIN_EXE_NAME}"
+
+    WriteUninstaller "$INSTDIR\\uninstall.exe"
+
+    ; Shortcuts
+    CreateDirectory "$SMPROGRAMS\${NAME}"
+    CreateShortCut "$SMPROGRAMS\${NAME}\${NAME}.lnk" "$INSTDIR\${MAIN_EXE_NAME}" "" "$INSTDIR\${MAIN_EXE_NAME}" 0
+    CreateShortCut "$DESKTOP\${NAME}.lnk" "$INSTDIR\${MAIN_EXE_NAME}" "" "$INSTDIR\${MAIN_EXE_NAME}" 0
+SectionEnd
+
+; ---------------------
+; Uninstaller
+; ---------------------
+Section "Uninstall"
+    ; Avoid locking the installation directory
+    SetOutPath "$TEMP"
+
+    ; Remove shortcuts first
+    Delete "$DESKTOP\${NAME}.lnk"
+    Delete "$SMPROGRAMS\${NAME}\${NAME}.lnk"
+    RMDir "$SMPROGRAMS\${NAME}"
+
+    ; Remove files and install directory
+    RMDir /r "$INSTDIR"
+
+    ; Delete AppData if requested
+    ${If} $DELETE_APPA_DATA == "1"
+        DetailPrint "Deleting application data..."
+        RMDir /r "$LOCALAPPDATA\${NAME}"
+    ${EndIf}
+
+    ; Clean up registry
+    DeleteRegKey HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\${NAME}"
+    DeleteRegKey HKLM "Software\\${NAME}"
+SectionEnd
+
+; EOF

pytron/llms.md

@@ -0,0 +1,98 @@
+# Pytron AI Guide
+
+This guide is intended for AI agents (LLMs) to understand how to interact with, develop, and extend the Pytron framework.
+
+## 🚀 Overview
+
+Pytron is an Electron-like framework for Python that allows developers to build desktop applications using Python for the backend and modern Web technologies (React, Vue, Vite, etc.) for the frontend.
+
+### Core Architecture
+- **Pytron Kit (`pytron`)**: The Python backend that manages application windows, handles IPC, and synchronizes state.
+- **Pytron Client (`pytron-client`)**: A JavaScript/TypeScript library that provides an RPC bridge and state synchronization in the frontend.
+- **Pytron UI (`pytron-ui`)**: A React-based UI component library designed for building native-feeling desktop applications.
+
+---
+
+## 🛠 Backend Development (Python)
+
+### 1. The `App` Instance
+The entry point of any Pytron application is the `App` class.
+```python
+from pytron import App
+app = App()
+```
+
+### 2. Exposing Functions
+Functions can be exposed to the frontend using the `@app.expose` decorator.
+```python
+@app.expose
+def greet(name: str):
+    return f"Hello, {name}!"
+```
+*Note: Pytron automatically generates TypeScript definitions for these functions.*
+
+### 3. Reactive State
+Pytron maintains a reactive state shared between Python and the frontend via `app.state`.
+```python
+app.state.user = {"name": "Alice", "role": "admin"}
+```
+Any change to `app.state` is automatically synchronized to the frontend.
+
+---
+
+## 🌐 Frontend Development (JS/TS)
+
+### 1. Calling Python Functions
+Use the `pytron` client (usually a proxy) to call exposed Python functions.
+```javascript
+import pytron from 'pytron-client';
+
+const result = await pytron.greet("Agent");
+```
+
+### 2. Consuming State
+Listen for state updates to react to backend changes.
+```javascript
+pytron.on('pytron:state-update', (change) => {
+    console.log("State updated:", change);
+});
+```
+
+---
+
+## 📁 Project Structure & Key Files
+
+- `pytron/application.py`: Main `App` class and window orchestration.
+- `pytron/webview.py`: Integration with system WebView (Edge WebView2, WebKit, etc.).
+- `pytron/state.py`: Reactive state implementation.
+- `pytron/cli.py`: Command line interface for project management.
+- `pyproject.toml`: Package configuration and dependencies.
+
+---
+
+## ⌨️ CLI Commands
+
+- `pytron init`: Initialize a new project from templates.
+- `pytron run`: Start the application in development mode with hot-reloading.
+- `pytron build`: Package the app into a standalone executable.
+
+---
+
+## 💡 Best Practices for LLMs
+1. **Always use `@app.expose`** for functions you want the UI to call.
+2. **Prefer `app.state`** for data synchronization rather than frequent RPC calls if the data needs to be reactive.
+3. **Check `application.py`** for window management settings (width, height, title, frameless mode).
+4. **Use Type Hints** in Python functions; they are used to generate accurate TypeScript definitions.
+
+---
+
+## 📱 Android Development
+
+Pytron supports building and deploying applications to Android devices.
+
+### Commands
+- `pytron android init`: Initialize Android project.
+- `pytron android sync`: Sync python code and frontend to Android project. **Automatically re-compiles C-extensions using NDK.**
+- `pytron android run`: Install and run the app on connected device.
+- `pytron android logcat`: View device logs.
+

pytron/manifests/README.md

@@ -0,0 +1,29 @@
+# Windows UTF-8 Manifest (process opt-in)
+
+This folder contains a process manifest that opts an application into Windows' "UTF-8 for worldwide language support" (the UTF-8 code page) for the C runtime.
+
+- File: `windows-utf8.manifest`
+
+Usage (PyInstaller .spec):
+
+Add the manifest to the `EXE()` call in your `.spec` file, for example:
+
+```python
+exe = EXE(
+    pyz,
+    ...,
+    manifest='pytron/manifests/windows-utf8.manifest',
+    ...
+)
+```
+
+Notes:
+- The manifest adds the `<UseUnicodeUTF8>true</UseUnicodeUTF8>` setting for the process. This asks the Microsoft C runtime to treat the ANSI code page as UTF-8 for narrow-character (`char`/`printf`/`fopen`-style) APIs.
+- Behavior depends on OS and CRT version. Test your application on target Windows versions.
+- If you embed the manifest with other tools (e.g. `mt.exe`, `rcedit`, or build systems), pass the manifest as the application's resource/manifest.
+
+If you want, I can also update `pytron` packaging helpers to automatically include this manifest when building Windows executables.
+
+Note on Installer Compression:
+
+- The Windows installer script (`pytron/installer/Installation.nsi`) has been updated to prefer ZLIB compression by default for better compatibility with some antivirus products. If you customize the NSIS script, be aware of the `SetCompressor` directive: newer builds may use `SetCompressor /SOLID zlib` instead of `SetCompressor lzma`.

pytron/manifests/windows-utf8.manifest

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1">
+  <assemblyIdentity type="win32" name="Pytron.App" version="1.0.0.0" processorArchitecture="*"/>
+
+  <compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
+    <application>
+      <supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}"/> <supportedOS Id="{1f676c76-80e1-4239-95bb-83d0f6d0da78}"/> <supportedOS Id="{4a2f28e3-53b9-4441-ba9c-d69d4a4a6e38}"/> </application>
+  </compatibility>
+
+  <dependency>
+    <dependentAssembly>
+      <assemblyIdentity
+        type="win32"
+        name="Microsoft.Windows.Common-Controls"
+        version="6.0.0.0"
+        processorArchitecture="*"
+        publicKeyToken="6595b64144ccf1df"
+        language="*"
+      />
+    </dependentAssembly>
+  </dependency>
+
+  <trustInfo xmlns="urn:schemas-microsoft-com:asm.v3">
+    <security>
+      <requestedPrivileges>
+        <requestedExecutionLevel level="asInvoker" uiAccess="false"/>
+      </requestedPrivileges>
+    </security>
+  </trustInfo>
+
+  <application xmlns="urn:schemas-microsoft-com:asm.v3">
+    <windowsSettings>
+      <activeCodePage xmlns="http://schemas.microsoft.com/SMI/2019/WindowsSettings">UTF-8</activeCodePage>
+      
+      <dpiAware xmlns="http://schemas.microsoft.com/SMI/2005/WindowsSettings">true</dpiAware>
+      <dpiAwareness xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">PerMonitorV2</dpiAwareness>
+
+      <longPathAware xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">true</longPathAware>
+
+      <heapType xmlns="http://schemas.microsoft.com/SMI/2020/WindowsSettings">SegmentHeap</heapType>
+    </windowsSettings>
+  </application>
+
+</assembly>

pytron/menu.py

@@ -0,0 +1,128 @@
+import ctypes
+from typing import List, Optional, Callable
+
+
+class Menu:
+    """
+    Abstraction for a native system menu.
+    """
+
+    def __init__(self, title: str = ""):
+        self.title = title
+        self.items: List["MenuItem"] = []
+        self._hmenu = None
+
+    def add_item(
+        self, label: str, callback: Optional[Callable] = None, shortcut: str = ""
+    ):
+        item = MenuItem(label, callback, shortcut)
+        self.items.append(item)
+        return item
+
+    def add_submenu(self, title: str):
+        submenu = Menu(title)
+        item = MenuItem(title, submenu=submenu)
+        self.items.append(item)
+        return submenu
+
+    def add_separator(self):
+        item = MenuItem("", is_separator=True)
+        self.items.append(item)
+        return item
+
+
+class MenuItem:
+    def __init__(
+        self,
+        label: str,
+        callback: Optional[Callable] = None,
+        shortcut: str = "",
+        submenu: Optional[Menu] = None,
+        is_separator: bool = False,
+    ):
+        self.label = label
+        self.callback = callback
+        self.shortcut = shortcut
+        self.submenu = submenu
+        self.is_separator = is_separator
+        self.enabled = True
+        self.checked = False
+        self.id = None  # Assigned by the platform when starting
+
+
+class MenuBar:
+    """
+    A collection of Menus that forms the application's top menu bar.
+    """
+
+    def __init__(self):
+        self.menus: List[Menu] = []
+        self._id_counter = 1000
+        self._callbacks = {}
+
+    def add_menu(self, menu: Menu):
+        self.menus.append(menu)
+        return menu
+
+    def build_for_windows(self, hwnd):
+        """Creates and attaches a Win32 menu to the given HWND."""
+        user32 = ctypes.windll.user32
+        from .platforms.windows_ops.constants import (
+            MF_STRING,
+            MF_POPUP,
+            MF_SEPARATOR,
+            MF_GRAYED,
+            MF_CHECKED,
+        )
+
+        h_menubar = user32.CreateMenu()
+
+        def _build_recursive(menu_obj, is_top=False):
+            if is_top:
+                h_menu = h_menubar
+            else:
+                h_menu = user32.CreatePopupMenu() if not is_top else h_menubar
+
+            for item in menu_obj.items:
+                flags = 0
+                if item.is_separator:
+                    user32.AppendMenuW(h_menu, MF_SEPARATOR, 0, None)
+                    continue
+
+                if item.submenu:
+                    h_sub = _build_recursive(item.submenu)
+                    user32.AppendMenuW(h_menu, MF_STRING | MF_POPUP, h_sub, item.label)
+                else:
+                    self._id_counter += 1
+                    item.id = self._id_counter
+                    if item.callback:
+                        self._callbacks[item.id] = item.callback
+
+                    if not item.enabled:
+                        flags |= MF_GRAYED
+                    if item.checked:
+                        flags |= MF_CHECKED
+
+                    label = item.label
+                    if item.shortcut:
+                        label += f"\t{item.shortcut}"
+
+                    user32.AppendMenuW(h_menu, flags | MF_STRING, item.id, label)
+
+            return h_menu
+
+        for top_menu in self.menus:
+            h_sub = _build_recursive(top_menu)
+            user32.AppendMenuW(h_menubar, MF_STRING | MF_POPUP, h_sub, top_menu.title)
+
+        user32.SetMenu(hwnd, h_menubar)
+        return h_menubar
+
+    def handle_command(self, cmd_id):
+        """Dispatches a menu command to the appropriate callback."""
+        if cmd_id in self._callbacks:
+            import threading
+
+            threading.Thread(target=self._callbacks[cmd_id], daemon=True).start()
+            return True
+        return False

pytron/pack/assets.py

@@ -0,0 +1,131 @@
+import os
+from pathlib import Path
+from ..console import log
+
+
+def get_smart_assets(
+    script_dir: Path,
+    frontend_dist: Path | None = None,
+    include_patterns: list | None = None,
+    exclude_patterns: list | None = None,
+):
+    """Recursively collect project assets to include with PyInstaller.
+
+    - Skips known unwanted directories (venv, node_modules, .git, build, dist, etc.)
+    - Skips files with Python/source extensions and common dev files
+    - respects include_patterns (overrides defaults) and exclude_patterns
+    - Skips frontend folder since it's handled separately
+    Returns a list of strings in the "abs_path{os.pathsep}rel_path" format
+    expected by PyInstaller's `--add-data`.
+    """
+    import fnmatch
+
+    add_data = []
+    # Default Excludes
+    EXCLUDE_DIRS = {
+        "venv",
+        ".venv",
+        "env",
+        ".env",
+        "node_modules",
+        ".git",
+        ".vscode",
+        ".idea",
+        "build",
+        "dist",
+        "__pycache__",
+        "site",
+        ".pytest_cache",
+        "installer",
+        "frontend",
+    }
+    EXCLUDE_SUFFIXES = {".py", ".pyc", ".pyo", ".spec", ".md", ".map"}
+    EXCLUDE_FILES = {
+        ".gitignore",
+        "package-lock.json",
+        "npm-debug.log",
+        ".DS_Store",
+        "thumbs.db",
+        "settings.json",
+        "pnpm-lock.yaml",
+        "bun.lockb",
+    }
+
+    include_patterns = include_patterns or []
+    exclude_patterns = exclude_patterns or []
+
+    root_path = str(script_dir)
+    for root, dirs, files in os.walk(root_path):
+        # Prune directories we never want to enter
+        # We always exclude invalid dirs unless explicitly included
+        # But for directories, "including" is tricky in os.walk.
+        # We'll stick to default prune for safety, but check user patterns.
+
+        # Filter dirs in-place
+        i = 0
+        while i < len(dirs):
+            d = dirs[i]
+            d_path = os.path.join(root, d)
+            d_rel = os.path.relpath(d_path, root_path)
+
+            # Check user excludes for folders
+            is_user_excluded = False
+            for pat in exclude_patterns:
+                if fnmatch.fnmatch(d, pat) or fnmatch.fnmatch(d_rel, pat):
+                    is_user_excluded = True
+                    break
+
+            if is_user_excluded:
+                del dirs[i]
+                continue
+
+            # Default excludes (only if not explicitly included?)
+            # For simplicity, we enforce default folder excludes unless strictly needed.
+            if d in EXCLUDE_DIRS or d.startswith("."):
+                del dirs[i]
+                continue
+
+            i += 1
+
+        # If this path is part of frontend, skip (we handle frontend separately)
+        if frontend_dist and str(frontend_dist) in root:
+            continue
+
+        for filename in files:
+            file_path = os.path.join(root, filename)
+            rel_path = os.path.relpath(file_path, root_path)
+
+            # 1. User Exclude (Highest Priority)
+            is_user_excluded = False
+            for pat in exclude_patterns:
+                if fnmatch.fnmatch(filename, pat) or fnmatch.fnmatch(rel_path, pat):
+                    is_user_excluded = True
+                    break
+            if is_user_excluded:
+                continue
+
+            # 2. User Include (Overrides defaults)
+            is_user_included = False
+            for pat in include_patterns:
+                if fnmatch.fnmatch(filename, pat) or fnmatch.fnmatch(rel_path, pat):
+                    is_user_included = True
+                    break
+
+            if is_user_included:
+                add_data.append(f"{file_path}{os.pathsep}{rel_path}")
+                log(f"Explicitly included asset: {rel_path}", style="cyan")
+                continue
+
+            # 3. Default Checks
+            if filename in EXCLUDE_FILES:
+                continue
+
+            _, ext = os.path.splitext(filename)
+            if ext.lower() in EXCLUDE_SUFFIXES:
+                continue
+
+            # If passed all checks
+            add_data.append(f"{file_path}{os.pathsep}{rel_path}")
+            log(f"Auto-including asset: {rel_path}", style="dim")
+
+    return add_data