spk-gui - GTK3 front-end for the SliTaz spk toolset
================================================================================

spk-gui is the graphical companion of spk-tui. Like the TUI it contains
NO package logic: everything it shows comes from the spk-* tools' --raw
(TSV) output, and every change goes through spk-add, spk-rm or spk-up,
whose --raw milestone stream is followed live in a bar at the bottom of
the window while browsing goes on (and, from Settings, through
spk-rm --autoremove --raw, and spk-mirror and spk --block/--unblock/
clean, whose plain output is shown the same way).

	$ make gui              # needs gtk+3-dev, gcc, pkg-config
	$ make install-gui      # /usr/bin/spk-gui + data/spk-gui.desktop
	$ spk-gui [search]      # starts on Browse with the search box
	                        # prefilled (an exact package name opens its
	                        # details page); without it, on Discover

Run as root (the .desktop uses `tazbox su spk-gui`) to install, remove
and upgrade. As a plain user the window is read-only: browse, search,
read details, and a "Relaunch as administrator" button re-execs the
program through tazbox su.


Layout
-------------------------------------------------------------------------------

A navigation at the left picks a page; a click (or Enter) on a row or a
card opens the details page of that package, Back returns to the page
as it was left (scroll and cursor untouched).

Discover, the first page and the one shown at start-up, shows the
featured applications as cards, then the application groups as tiles
and a last tile, Browse all, on one rhythm of 3 equal columns:

	+-------------+-------------------------------------------------+
	| Discover    | Featured                                        |
	| Browse      | +-------------+ +-------------+ +-------------+ |
	| Installed   | |[F] Firefox..| |[S] Sylpheed | |[G] GNU Imag.| |
	| Updates (3) | |    Official.| |    Simple,..| |    Gnu Imag.| |
	| History     | |    [Install]| |             | |    [Install]| |
	| ----------- | +-------------+ +-------------+ +-------------+ |
	| Settings    | [Inkscape     ] [VLC          ] [Audacity     ] |
	|             | [Geany IDE    ] [ePDFView     ] [Transmission ] |
	|             | Categories                                      |
	|             | [Internet     ] [Multimedia   ] [Graphics     ] |
	|             | [Office       ] [Games        ] [Development  ] |
	|             | [Accessories  ] [System       ] [Browse all   ] |
	+-------------+-------------------------------------------------+

The featured cards, the tiles (8 groups + Browse all) and the cards of
a group (below) share the same 3 columns (discover.c COLUMNS):
homogeneous flow boxes with exactly 3 children per line and the same
spacing and padding, so cards and tiles have the same width and line
up column by column; they stretch with the window instead of
re-wrapping. The front shows 9 featured cards at most, three rows
(FEATURED_MAX: the first 9 names of featured.list the catalogue
knows); fewer stay in the first columns. At the default size
(1180x820) the last row of tiles needs a short scroll (about 40 px
with the information bar of a plain user). A card's
minimum width does not depend on its texts (the name asks for 9
characters: room for "Installed" and an ellipsized package name), so
no view makes the window wider; Discover is narrower than the rest of
the window's minimum (about 840 px).

Browse all (icon lxtaz-cat-all, else applications-other; second line
"All packages") shows the Browse page as if chosen in the navigation (the browse callback of discover.h): the navigation row
follows and the list gets the keyboard. It is hidden with the groups.

A card: a coloured letter tile (lettertile.c), the application's Name
(one line, ellipsized), the package's short description (two lines at
most, ellipsized), "Installed" when it is, always at the bottom left
(all the cards have the same height). The Name is the one
of the package's .desktop files equal to the package name (ignoring
case), else the shortest one that starts with it or that it starts
with, else the first: "Sylpheed", not "Sylpheed Compose". A featured
package without .desktop (a meta package) shows its name with a
capital: "Firefox". When two cards shown have the same Name (epdfview
and epdfview-cups) both add their package name, small, at the bottom
right. A group tile opens the grid of all the cards of its group (sorted by
name) inside the page; Back (header button, Alt+Left, mouse back) returns to the front,
and a package opened from the grid returns to the grid. Activating
Discover in the navigation while on it returns to the front too. The
header subtitle is empty on the front, "N applications" in a group. A
search typed on Discover is shown by Browse (application names are not
searched). With no application list at all (an spk-ls without --apps,
lists never fetched with them) a centred message says to refresh the
package lists, with a Refresh button as root. Once a refresh has
succeeded in the session and there is still none, it says instead that
the mirror does not provide one yet and points to Browse, without
button (refreshing again would bring the same). Without featured names
only that section is hidden, without applications only the groups.
The Installed page offers "Applications | All packages" (All by
default; hidden while there is no application list).

	+---------------------------------------------------------------+
	| [search...........]   SliTaz Packages        (refresh) (=)    |
	|                       N packages shown                        |
	| info bar: browsing only ...       [Relaunch as administrator] |
	+-------------+-------------------------------------------------+
	| Discover    | [All categories v]    Show technical packages o |
	| Browse      |  +       Package      Version    Description    |
	| Installed   |       v  acl          2.3.1      Commands ...   |
	| Updates (3) | [x] +    gimp         ...        GNU Image ...  |
	| History     | [ ]      ...                                    |
	+-------------+-------------------------------------------------+
	| 2 to install . 1 to remove                [Clear] [Apply...]  |
	+---------------------------------------------------------------+
	| (o) Upgrading the system . cairo (42s) [= 5 of 11 ] [Show log]|
	+---------------------------------------------------------------+

The cart (root only): the first column of a list marks packages for
later, what a tick means depends on the page: install on Browse (rows
not installed), remove on Installed, upgrade on Updates (not the held-
back rows). A coloured glyph (+ install, - remove, ^ upgrade) and a
light tint of the row show a mark; any mark can be unticked anywhere.
Removal is never marked from Browse. The details page has the same
choice under its button ("Mark to install"...). The cart bar counts all
marks, those hidden by a filter too; Apply runs them as one operation,
Clear forgets them. It is hidden while empty and during a run.

Apply first opens the review, which is the confirmation: one row per
mark under Remove, Upgrade and Install, the order of the run. The
tools' dry-run (spk-add/spk-rm --trame, as the user, in a thread) fills
in what each install brings along and each removal takes with it, and
the sizes; Apply never waits for it. A removal spk-rm would refuse (an
essential package in the set) is shown as such and unmarked. Unticking
a row unmarks it. One line per row: what an install brings along (or
a removal takes) is named when it fits, else counted ("+ 5 packages"),
the names in the tooltip. Upgrades of a selection go through `spk-up --raw
--upgrade names` when `spk-up --help` lists that option (asked once at
start-up), else through spk-add --forced as before.

The activity bar at the bottom is shown only during an operation and
after it, with its result (green, orange or red) and the log, until
it is closed or the next one starts; "Last operation" in the menu
brings it back. One operation at a time: meanwhile the action buttons
and the menu entries that start one are greyed out. After a failure the
log ends with what the tool wrote to /var/log/spk/raw-*.log during the
run (dim rows, last 16 KiB, colours stripped): the reason behind
"failed (see log)".

While the log is shown, a thin grip above the bar (a short line,
vertical resize cursor) pulls it up to read more of a long run (System
check, upgrade) and back down; a double click switches between the
default height (170 px, also the smallest) and all the pages can give.
The pages keep 215 px at least (the whole navigation): window.c hands
them to activity_set_room. The height lasts the session (Hide/Show
log, Last operation, the next run), never saved. A smaller window
takes it back from the log first, a larger one gives it back up to
the height chosen; the log keeps following its end meanwhile. Bar
hidden or log collapsed: no grip, the window as before.

The details page, in the same frame (Back shown in the header bar):

	+-------------+-------------------------------------------------+
	| Discover    | acl                                 [ Remove ]  |
	| Browse      | 2.3.1 . System tools [Installed]  [ ] Mark for..|
	| Installed   | short description                Block upgrades |
	| Updates (3) | ----------------------------------------------- |
	| History     | long description                                |
	| ----------- |  Web site  http://...                           |
	| Settings    |      Size  44K to download, 148K on disk        |
	|             |   Depends  attr                                 |
	|             | > Installed files                               |
	|             | History                                         |
	|             | 2026-11-19 22:19  (^) Upgraded                  |
	|             | 2026-10-02 10:05  (+) Installed                 |
	+-------------+-------------------------------------------------+

The History section, last of the page, shows the last 10 lines of
`spk history PKG --raw`, newest first: date and time (dim), the
action's icon, the action. Hidden while there is none (or the tool
cannot tell). It is read in a thread at each details_show, a reload
too; an answer for a package no longer shown is dropped (a counter of
details_show calls).

An installed package in the blocked list gets a "Blocked" badge (for
anyone); as root a flat "Block upgrades" / "Unblock upgrades" button
under the mark runs `spk PKG --block` / `--unblock`. A blocked package
with an update is a held-back row of the Updates page (spk-up --check
status "blocked"): after a block or unblock the update check is redone.

History, after Updates, is the operations journal (`spk activity --raw
--lines=N`), newest first, for anyone:

	+-------------+-------------------------------------------------+
	| ...         |     Date              Action     Package        |
	| Updates     | (-) 2026-11-19 22:19  Removed    alsaplayer-lang|
	| History     | (^) 2026-11-19 22:19  Upgraded   alsaplayer-lang|
	| ----------- | (+) 2026-11-19 22:19  Installed  alsaplayer-lang|
	| Settings    | ...                                             |
	|             | Showing the last 200 operations.     [Show all] |
	+-------------+-------------------------------------------------+

The icon tells the action at a glance (list-add, software-update-
available, list-remove, changes-prevent/allow for Blocked/Unblocked;
none for a word the GUI does not know, shown as the tool wrote it);
the known words are translated, the tool's output stays English. The
first read asks for the last 200 lines (HISTORY_FIRST); while that
many came back a bar under the list offers Show all (`--lines=0`, the
whole journal, ~2000 rows in a fixed-height GtkTreeView stay fast).
A double click or Enter on a row opens the package's details; a
package neither installed nor on the mirror any more opens nothing
(open_details ignores a name the catalogue does not know). The journal
is read in a thread when the page is shown and it is stale: at
start-up, and after every load (any operation, a refresh). A load
ending while the page is shown re-reads it at once. Empty journal:
"No operation recorded yet."; the tool failing or too old (no
activity command): a note that it needs a newer spk. A search typed
there is shown by Browse.

Settings, apart at the end of the navigation, is read-only as a plain
user (values shown, action buttons greyed out), re-read each time it is
shown and after every load:

	+-------------+-------------------------------------------------+
	| ...         | Mirrors                                         |
	| ----------- | Main mirror      https://mirror.slitaz.org/...  |
	| Settings    | Official mirrors [https://mirror... v] [Use]    |
	|             | Extra mirrors    name  URL  3 packages [Remove] |
	|             | [http://...................]  [Add]             |
	|             | Blocked packages                                |
	|             | held back from upgrades...                      |
	|             | curl  [Unblock]                                 |
	|             | Package cache                                   |
	|             | Directory  /var/cache/tazpkg                    |
	|             | Size       90.1 kB                              |
	|             | [Clean cache...]                                |
	|             | Maintenance                                     |
	|             | Unused packages  7 packages, 3.7 MB [Remove...] |
	|             | [Refresh package lists] [System check] [Last..] |
	+-------------+-------------------------------------------------+

The keys, the add-mirror entry and the Clean cache button share the
left edge of the section titles; the values make a second column. The
Official mirrors row is hidden when there is no list (an empty
/var/lib/tazpkg/mirrors); with an old spk-mirror it stays and says "Not
available". An empty cache (no file; `spk info --raw` gives 0) shows
"Empty" and Clean cache is insensitive.

Unused packages are what `spk-rm --autoremove --dry-run --trame` lists
(plan_unused in plan.c, read with the rest): packages installed as
dependencies (spk-add --asdep) that nothing needs any more. The value
counts them and adds their freed_size_bytes ("7 packages, 3.7 MB",
"None" for an empty list); an spk-rm whose --help does not list
--autoremove leaves it "Not available (needs a newer spk).". Remove...
is live as root, with something to remove, nothing running and the
list not being re-read (the run's own reload would otherwise leave the
old names clickable for a second).

Use runs `spk-mirror OFFICIAL-URL`, Add `spk-mirror URL`, Remove (asked
first) `spk-mirror URL --rm`, Unblock `spk PKG --unblock`, Clean (asked
first) `spk clean`, Remove... of the unused packages (asked first: the
dialog names every package with its size, scrolled past about ten
rows; Cancel is the default) `spk-rm --autoremove --raw`, followed like
any removal (milestones, "N of M" over the names shown, the raw-remove
log after a failure). spk-rm computes the set again itself: the list
shown is the one it would take, as nothing can run in between. The Maintenance buttons are the window actions of
the menu (win.refresh, win.doctor, win.last-run). After a new main or
extra mirror an info bar offers to refresh the lists (not started by
itself: network, and the run's result would be lost under it). A local
depot (a path) is listed without Remove; a blocked package that is not
installed without Unblock (spk --unblock only knows installed ones). An
older spk (no --raw for spk info / spk-mirror --list) leaves those
values "Not available"; spk-ls --blocked --raw is in every spk 3.x.

Keyboard: the list of the page has the keyboard (at start-up, after a
page is chosen, after Back): arrows move, Enter opens the package, Space
marks it (root) and moves down. On Discover the cards and tiles have it
the same way (the one used last, else the first): arrows move, also
from the featured cards down to the groups and back up in the same
column (up lands on the lowest card of the column), Enter opens;
with no application list the Refresh button has it when it can be
pressed, else the navigation (never the search box). Typing anywhere
searches; Down or Enter
in the search box goes to the list, Escape clears the search. In the
navigation the arrows switch pages, Enter, Space or Right enters the
list. Ctrl+F search, F5 refresh lists, Alt+Left back (or the mouse back
button), Ctrl+Q quit.


Modules (one concern per file)
-------------------------------------------------------------------------------

	spk-gui.c   main(): GtkApplication, locale, --version, search arg
	window.c    assembles the header bar, navigation, pages, menu and
	            actions; the only module that knows about all the others
	            and the only one that launches spk-add/rm/up/doctor,
	            spk-mirror and spk --block/--unblock/clean (plan.c runs
	            the dry-runs, settings.c the reads: they change nothing)
	catalog.c   data layer: loads spk-ls --mirror/--raw in a thread
	            (via tui/backend.c), merges into one sorted list,
	            categories, long descriptions, file lists, pending updates;
	            the applications (spk-ls --apps --raw) and the featured
	            names (spk-ls --featured --raw), joined with the list
	category.c  category labels, old slug -> current slug, technical pkgs,
	            freedesktop Categories -> application group (Discover)
	nav.c       left navigation: GtkListBox, one row per page (+ count),
	            a line before the rows added after nav_add_separator
	discover.c  the Discover page: featured cards, group tiles, the grid
	            of a group; a centred message without application list
	lettertile.c coloured letter tile for an application (CSS of
	            style.c), reusable wherever an app needs a picture
	listpage.c  a list page: toolbar (category, Applications | All,
	            technical switch) + pkgview, and a centred message when
	            the list is empty
	uppage.c    the Updates page: installed -> available, download size
	            (column hidden if spk-up gives none), held-back section
	pkgview.c   GtkTreeView + in-memory filter (text/category/technical)
	markcol.c   the mark column of pkgview and uppage: box, glyph, tint,
	            click and Space handling; reads the cart, never writes
	details.c   details page, Install/Remove/Upgrade button, mark box,
	            Block/Unblock button and Blocked badge, History section
	history.c   the History page (spk activity --raw) and the journal
	            reader in a thread, shared with details.c (spk history
	            PKG --raw); action labels and icons
	settings.c  the Settings page: spk info --raw, spk-mirror --list
	            --raw, spk-ls --blocked --raw and plan_unused read in a
	            thread; hands its actions (URL or name) to the window
	cart.c      the cart: name -> pending action, GLib only
	cartbar.c   the cart summary bar: counts, Clear, Apply
	review.c    the review before Apply: rows per action, ticks, totals
	plan.c      what installs and removals would do: the tools' dry-run
	            (--trame) in a thread, sizes from packages.info; the
	            unused packages (spk-rm --autoremove --dry-run --trame,
	            blocking, for Settings' thread)
	openurl.c   web links: http(s) only, as the desktop user, never as root
	run.c       runs one spk tool, parses its --raw stream (no widgets);
	            RUN_PLAIN: human output, the exit status decides
	activity.c  bottom bar following a run: step, progress, log (a grip
	            pulls it up), result
	            (RUN_PLAIN: one log row per output line, colours and
	            ===== rules dropped, the last line says why it failed)
	updates.c   spk-up --check --raw -> list of updates (uplist_t); asks
	            spk-up --help whether it can upgrade named packages
	style.c     small CSS on top of the user's GTK theme

	../tui/backend.c is shared with spk-tui (TSV parsing, pkg_t,
	pkg_load_detail). Do not duplicate it.

Data flow: window -> catalog_load_async -> on_loaded -> discover_fill
(Discover: rebuilt, the front or group shown, its scroll and the card
with the keyboard kept), listpage_fill (Browse, Installed),
uppage_fill (Updates) + nav_set_count -> (root)
updates_check_async -> catalog_set_updates -> listpage_update_upgrades,
uppage_fill + the Updates count in the navigation.
A mutation: details button -> window on_action(name, action) ->
start_run -> activity_run(spk-add --raw pkg) -> run_start; lines and
progress feed the bar -> on_run_done (ok or not) -> catalog_load_async
(full reload) -> refresh_details finds the package again by name ->
updates_check_async. The System check (spk-doctor) only reads: its end
reloads nothing.
Settings: every on_loaded (start-up, refresh, mutation) and every
switch to the page -> settings_reload (a thread; a request during a
load is run after it) -> fill + on_settings_loaded -> the details
page's block state (settings_blocked). A Settings button -> window
on_settings(action, URL or name) -> checks it again (settings_url_ok,
catalog_name_ok + catalog_find), asks for Remove and Clean -> start_run
(RUN_PLAIN) -> mirror set/add: on_mirror_set_done (info bar "refresh")
then on_run_done; mirror remove, block, unblock, autoremove (the
confirmation lists settings_unused): on_run_done (reload + update
check, Settings re-read with it); clean: on_clean_done (Settings
re-read only).
History: every on_loaded -> history_set_stale (+ history_show when
the page is in front); show_page("history") -> history_show -> a
thread runs spk activity --raw --lines=200 (0 after Show all) -> fill.
Details: details_show -> history_read_async(name, 10) -> the section,
if still the same details_show.
Opening a package: row or card activated -> window open_details ->
details page; Back -> go_back to the page it was opened from.
The applications: spk-ls --apps --raw (package, Name, Categories, Icon)
and --featured --raw (one name per line) are read in the catalogue's
worker thread with the rest; a package unknown to the catalogue is
dropped, an application is kept once per package and group
(category_app_group), all with the package's chosen Name. An spk-ls without these options prints its
package list instead: lines that are not 3-4 fields, or not a name,
are ignored, so the lists are simply empty. They are downloaded only
on request: the Refresh run is `spk-up --list --raw --apps` (an spk-up
without --apps skips unknown options); its success calls
discover_set_refreshed (the empty Discover stops offering it).
The cart: a click on a mark -> the page's cart_mark_cb -> window on_mark
(checks the action is valid now) -> cart_set -> on_cart_changed redraws
the marks (no refill), syncs the details box and the cart bar. Apply ->
review_run (plan_async for the rows; an untick is a cart_set) -> prune
again -> activity_run_parts(spk-rm --raw, spk-up --raw --upgrade or
spk-add --raw --forced, spk-add --raw) -> on_run_done as above. Every
load and update check prunes the marks no longer valid: what was done
drops out, what failed stays marked for a retry.


Conventions
-------------------------------------------------------------------------------

* Package names are validated by catalog_name_ok() before being passed
  to any tool run as root (a hostile mirror controls packages.info).
* Mirror URLs are validated by settings_url_ok() (http, https, ftp; a
  host starting with a letter or digit; no ".."; letters, digits and
  - . _ ~ / : % + only): spk-mirror runs as root and word-splits them.
  Never through a shell: argv arrays only.
* Commands use absolute paths (/usr/sbin/spk-add ...) like spk-tui.
  The read-only ones and the Settings tools can be pointed elsewhere at
  build time to try a working copy: -DCATALOG_SPK_LS=, -DPLAN_SPK_ADD=,
  -DPLAN_SPK_RM= (the unused packages of Settings too),
  -DSETTINGS_SPK=, -DSETTINGS_SPK_MIRROR=, -DSETTINGS_SPK_LS=,
  -DWINDOW_SPK=, -DWINDOW_SPK_MIRROR=, -DHISTORY_SPK= (each a C
  string: -DWINDOW_SPK='"/path/to/spk"').
* A running install/remove is never killed, and the window cannot quit
  during it (the tool would die of SIGPIPE on its closed stdout): Quit
  offers "Quit when finished" instead (request_quit in window.c).
* A pkg_t pointer never outlives a catalogue reload, nor an upgrade_t
  one a new update check: keep the name and look the package up again
  (catalog_find, catalog_upgrade).
* What counts as a "technical package" (libraries, -dev, translations)
  is decided in category.c only.
* A page is registered with two lines in window.c: gtk_stack_add_named
  and nav_add (Settings: a nav_add_separator before it). A page that is
  not a list (Settings) gives the keyboard to the navigation, and a
  search typed there is shown by Browse. History has a list but no
  package filter: the keyboard goes to its list (the navigation while
  it is empty), a search is shown by Browse.
* The package names of the application lists go through
  catalog_name_ok() and catalog_find() like any other.
* Strings go through gettext (_ / N_), domain "spk"; `make pot` picks
  them up from gui/*.c.
* Keep modules talking through their small headers and callbacks; no
  global state, no module reaching into another's struct.
* SPK_GUI_DEBUG set (to any value) prints each search and the number
  of rows it leaves on stderr (filter / performance debugging).
* Test without touching the real desktop:
      Xvfb :7 -screen 0 1400x900x24 &
      DISPLAY=:7 ./gui/spk-gui          # or sudo -E env DISPLAY=:7 ...
      DISPLAY=:7 scrot -o shot.png
  As root with the user's DBUS_SESSION_BUS_ADDRESS (sudo -E, su) the bus
  refuses root and GTK 3.22 prints a harmless g_dbus_proxy_new_sync
  CRITICAL; add `-u DBUS_SESSION_BUS_ADDRESS` to env (tazbox su is clean).
  A root view that cannot change the system: `unshare -r ./gui/spk-gui`
  (euid 0 in a user namespace, the real root's files stay read-only:
  the update check fails, the buttons are live). Point the Settings
  tools at copies run with --root=<scratch dir> to try their actions.
