====== Clip Studio Assets on Linux (Bottles) — clipstudio:// Scheme Handler ======

This documents a working setup to open **Clip Studio Assets** links (``clipstudio://...``) on Linux when Clip Studio is installed inside **Bottles (Flatpak)**.

When you click the **Download** button on assets.clip-studio.com, the browser launches a ``clipstudio://assets.clip-studio.com/materialdownload/...`` URL. This handler forwards the URL into the Bottle so Clip Studio downloads the asset.

----

===== Requirements =====
  * Linux desktop with xdg/gio
  * Bottles (Flatpak): ``com.usebottles.bottles``
  * A Bottle named: **Clip Studio**
  * Clip Studio installed in that bottle
  * Programs visible in the bottle (example output):
    * ``CLIPStudio``
    * ``CLIPStudioPaint``

----

===== Quick Diagnostics =====

Check your current default handler:

<code bash>
xdg-mime query default x-scheme-handler/clipstudio
gio mime x-scheme-handler/clipstudio
</code>

Test a manual open:

<code bash>
gio open "clipstudio://test"
</code>

List Bottles programs:

<code bash>
flatpak run --command=bottles-cli com.usebottles.bottles programs -b "Clip Studio"
</code>

----

===== Handler Overview =====
We install:
  * ``/usr/bin/clipstudio-handler`` (desktop entry target)
  * ``/usr/bin/clipstudio-worker`` (does the Bottles/Wine forwarding)
  * ``/usr/share/applications/clipstudio-handler.desktop`` (registers ``x-scheme-handler/clipstudio``)

The handler **debounces** rapid clicks and avoids spawning endless Bottles sessions.

----

===== Packaging as a .deb =====

If you already have working files installed under ``/usr/local``:
  * ``/usr/local/bin/clipstudio-handler``
  * ``/usr/local/bin/clipstudio-worker``
  * ``/usr/local/share/applications/clipstudio-handler.desktop``

You can build a Debian package that installs them to proper system locations under ``/usr``.

==== Build Script ====

<code bash>
nano ~/build-clipstudio-handler-deb.sh
chmod +x ~/build-clipstudio-handler-deb.sh
~/build-clipstudio-handler-deb.sh
</code>

(See the build script in the project notes; it copies from /usr/local into a staging tree and runs dpkg-deb.)

==== Install / Remove ====

<code bash>
sudo dpkg -i ~/clipstudio-scheme-handler_1.0.0_all.deb

sudo dpkg -r clipstudio-scheme-handler
</code>

After install/remove, refresh desktop DB if needed:

<code bash>
sudo update-desktop-database /usr/share/applications
</code>

----

===== Troubleshooting =====

==== Handler registered but gio open does nothing ====
Refresh desktop database:

<code bash>
sudo update-desktop-database /usr/share/applications
gio mime x-scheme-handler/clipstudio
</code>

==== Bottles gets stuck / ghost bwrap processes ====
Find and kill stuck runs:

<code bash>
pgrep -fa 'bwrap --args .*bottles-cli' || echo "clean"
# kill specific PIDs shown:
kill <PID1> <PID2>
kill -9 <PID1> <PID2> 2>/dev/null || true
</code>

==== Clip Studio opens but second click doesn’t ====
This usually indicates the handler is spawning multiple instances or the worker lock is held too long.
Verify logs:

<code bash>
tail -n 200 ~/.cache/clipstudio/handler.log
tail -n 200 ~/.cache/clipstudio/worker.script.log
</code>

----

===== Notes =====
  * ``clipstudio://`` URLs contain short-lived login tokens. Avoid pasting them publicly.
  * The handler should prefer forwarding the URL into the already-running Clip Studio session.
</text>