Enhanced Bookmarks / Bookmark Tool
=================================

A local, self-hosted bookmark and launcher tool for organizing websites, local HTML tools, and optional run-command application shortcuts.

This app runs locally on your computer using PowerShell 7 and opens in a browser app window. Your bookmarks are stored in a local data.json file in the same folder as the app.


WHAT IS INCLUDED
----------------

Required app files:

- BookMarkTool.ps1
- BookMarkTool-html.ps1
- BookMarkTool.css
- BookMarkTool-app.js
- BookMarkTool-render.js
- BookMarkTool-dnd.js
- BookMarkTool-settings.js
- BookMarkTool-compat.ps1
- BookMarkTool-Manual.ps1
- data.json

The included data.json is a clean starter file with no personal bookmarks, no saved application launchers, no logs, and no backups.


REQUIREMENTS
------------

Required:

- PowerShell 7 or newer, available as the `pwsh` command
- A modern browser such as Brave, Chrome, Chromium, Microsoft Edge, or your system default browser

Recommended:

- Brave, Chrome, or Edge for app-window launch mode
- Linux users using Flatpak Brave should launch with `-LaunchMode brave`


QUICK START
-----------

1. Extract the zip file to a folder you can write to.
2. Open a terminal or PowerShell window in that folder.
3. Run:

   pwsh -NoProfile -File ./BookMarkTool.ps1

4. The app will start a local server and open a local browser window.
5. Default local address:

   http://127.0.0.1:8788/

To stop the app, use the app's shutdown option or close the PowerShell/terminal window running the server.


LINUX SETUP
-----------

1. Install PowerShell 7 if it is not already installed.

   Check whether PowerShell is available:

   pwsh --version

2. Extract the app zip to a folder, for example:

   ~/Applications/EnhancedBookmarks

3. Open a terminal in the extracted folder:

   cd ~/Applications/EnhancedBookmarks

4. Start the app:

   pwsh -NoProfile -File ./BookMarkTool.ps1

5. Optional: choose a browser launch mode:

   pwsh -NoProfile -File ./BookMarkTool.ps1 -LaunchMode brave
   pwsh -NoProfile -File ./BookMarkTool.ps1 -LaunchMode chrome
   pwsh -NoProfile -File ./BookMarkTool.ps1 -LaunchMode edge
   pwsh -NoProfile -File ./BookMarkTool.ps1 -LaunchMode default
   pwsh -NoProfile -File ./BookMarkTool.ps1 -LaunchMode none

Notes for Linux users:

- `-LaunchMode brave` supports Brave and Flatpak Brave when available.
- Local HTML files are opened directly in a browser app window instead of using xdg-open.
- App-window size and position persistence is designed for Linux/X11 browser app windows.
- Window switching for application launchers may depend on available desktop/window tools and may vary by desktop environment.


WINDOWS SETUP
-------------

1. Install PowerShell 7 if needed.

   Check in PowerShell or Windows Terminal:

   pwsh --version

2. Extract the app zip to a folder, for example:

   C:\Users\YourName\Documents\EnhancedBookmarks

3. Open PowerShell 7 in the extracted folder.

4. Start the app:

   pwsh -NoProfile -File .\BookMarkTool.ps1

5. Optional: choose a browser launch mode:

   pwsh -NoProfile -File .\BookMarkTool.ps1 -LaunchMode brave
   pwsh -NoProfile -File .\BookMarkTool.ps1 -LaunchMode chrome
   pwsh -NoProfile -File .\BookMarkTool.ps1 -LaunchMode edge
   pwsh -NoProfile -File .\BookMarkTool.ps1 -LaunchMode default
   pwsh -NoProfile -File .\BookMarkTool.ps1 -LaunchMode none

Example Windows run command for an application launcher:

   pwsh -NoProfile -File "C:\Users\YourName\Documents\Tools\ExampleTool.ps1"

Notes for Windows users:

- Website bookmarks, local files, backups, logs, and most launcher features should work normally.
- Running-window detection and switch-to-window behavior may vary by app and browser window title.
- If Windows blocks script execution, start PowerShell 7 and run the command from the extracted app folder. You may need to review your local PowerShell execution policy.


MACOS SETUP / EXPERIMENTAL
--------------------------

macOS support is experimental and not fully verified.

The core local web app may run with PowerShell 7, but browser app-window launching, local file opening, and switch-to-window behavior may need additional macOS-specific testing.

Basic test:

1. Install PowerShell 7 for macOS.
2. Extract the zip.
3. Open Terminal in the extracted folder.
4. Run:

   pwsh -NoProfile -File ./BookMarkTool.ps1 -LaunchMode default

If the browser does not open automatically, manually open:

   http://127.0.0.1:8788/


LAUNCH OPTIONS
--------------

The app supports these launch modes:

- brave   Opens using Brave when available
- chrome  Opens using Chrome or Chromium when available
- edge    Opens using Microsoft Edge when available
- default Opens using the operating system's default browser
- none    Starts the local server but does not open a browser automatically

Examples:

   pwsh -NoProfile -File ./BookMarkTool.ps1 -LaunchMode brave
   pwsh -NoProfile -File ./BookMarkTool.ps1 -LaunchMode none

Custom port example:

   pwsh -NoProfile -File ./BookMarkTool.ps1 -Port 8790

Then open:

   http://127.0.0.1:8790/


USING LOCAL HTML FILES
----------------------

You can add local HTML tools as bookmarks or application launchers.

Example local file URL:

   file:///home/user/Documents/Tools/Dashboard.html

or on Windows:

   file:///C:/Users/YourName/Documents/Tools/Dashboard.html

Local HTML files are opened directly by the browser in app-window mode, not through the operating system's generic file opener.


USING APPLICATION LAUNCHERS
---------------------------

The Applications popup lets you add run-command shortcuts.

Linux example:

   pwsh -NoProfile -File "/home/user/Documents/Scripts/ExampleTool.ps1"

Windows example:

   pwsh -NoProfile -File "C:\Users\YourName\Documents\Scripts\ExampleTool.ps1"

You can optionally provide a window title match to help the app detect whether the launched application is already running and switch to it.


DATA, BACKUPS, AND LOGS
-----------------------

Your bookmarks and application launchers are stored in:

   data.json

Backups are stored in:

   Backups/

Logs are stored in:

   Logs/

The app includes backup/log retention settings and restore-from-backup options in Settings.

Important: do not replace your personal data.json with a public starter data.json unless you intentionally want to reset your bookmarks.


TROUBLESHOOTING
---------------

PowerShell command not found:

- Install PowerShell 7.
- Confirm `pwsh --version` works in your terminal.

Browser does not open:

- Start the app with:

  pwsh -NoProfile -File ./BookMarkTool.ps1 -LaunchMode none

- Then manually open:

  http://127.0.0.1:8788/

Port already in use:

- Start with a different port:

  pwsh -NoProfile -File ./BookMarkTool.ps1 -Port 8790

Local HTML does not open as expected:

- Use a full file URL beginning with `file:///`.
- Confirm the file path exists.
- Try launching with Brave or Chrome mode instead of default mode.

Application launcher command fails:

- Check quotes around paths with spaces.
- Try running the exact command directly in a terminal first.
- Use full paths when possible.

Settings, Applications, or pop-out windows seem too large/small:

- Adjust Zoom and Field text size in Settings.
- Resize the browser app window; the app remembers supported window sizes/positions.


SAFETY NOTE
-----------

Run-command application launchers execute commands on your own computer. Only add commands that you understand and trust.


PUBLISHING NOTE
---------------

This public package contains a clean starter data.json. If you already use the tool personally, back up your own data.json before testing or replacing files.
