Shelf and platform capabilities¶
Implemented
Shelf capability fields are served by Go and read by the frontend.
Device operations are exposed through PlatformCapabilities, accessed with
getPlatformCapabilities() beside getBookshelfProvider().
The frontend reads and writes shelf data through BookshelfProvider. The
host supplies file pickers, native readers, file exports and shelf management
through a separate platform object.
This design splits those methods by who knows the answer:
- What a shelf can do is known by the engine that opened it. The server reports it as fields on each shelf, the same on every client.
- What the device can do is known by the host the frontend runs in (Wails, Capacitor, the wasm page, a browser). The host provides it as a separate platform interface, never over the HTTP API.
Since pCloud moved into Go and the TypeScript reader was removed, every client reads every shelf through the same Go API. The capability split leaves the provider with one job: reading and writing a shelf.
Where each optional method goes¶
The implemented migration from the optional methods formerly on BookshelfProvider, in
frontend/src/providers/bookshelfProvider.ts:
| Method | Implemented by | Goes to |
|---|---|---|
getSourceAsset (now required) |
server, mobile, pCloud | Required on the shelf interface |
getSourceAssetsBundle (now required) |
server, mobile, pCloud | Required on the shelf interface |
supportsShelfRefresh |
server, mobile, pCloud | Shelf capability rescan |
refreshShelf |
server, mobile, pCloud | Shelf interface, gated by rescan |
supportsCharCountListing |
mobile, pCloud | Shelf capability char_count |
getShelfFetchedAt |
mobile, pCloud | Shelf field offline.snapshot_at |
downloadBook, removeDownload, getDownloadState, listDownloadedBookEntries |
mobile | Shelf interface, backed by the Go API, gated by download |
getPersistedShelfID |
mobile | Offline wrapper for remote-server entries (see below) |
supportsServerMode (removed) |
— | Every backend now has a Go server to answer /api/mode |
filtersNsfwOnDevice, localNsfwMarks |
mobile, pCloud | Still used by EmbeddedPCloudReader for the device preference and offline filtering |
coversMustBeFetchedAsBlob |
mobile | Platform boolean, retained on Android: direct WebView image requests bypass CapacitorHttp and can be blocked as mixed content |
getStorageEstimate |
mobile | Platform interface |
openLocalBookFiles, importBookFromLocalPath |
desktop | Platform interface |
openDesktopFolder, openDesktopBookFolder, openDesktopShelfFolder, openDesktopShelfDirectory |
desktop | Platform interface, renamed without Desktop |
openDesktopReader |
desktop | Platform interface |
saveBookContentToFile |
desktop, mobile | Platform interface |
previewDesktopShelfID, addDesktopShelf, getDesktopShelfDetails, modifyDesktopShelf, removeDesktopShelf |
desktop | Platform interface as previewShelfID, addShelf, getShelfDetails, modifyShelf, removeShelf |
(new) openExternalUrl |
— | Platform interface: opens the system browser for pCloud authorization |
No method is left unassigned. "Mobile" here is MobileBookshelfProvider, the
wrapper that adds offline downloads to remote PlainShelf server connections.
Embedded pCloud/WebDAV entries use Go downloads directly; local shelves are not wrapped.
Shelf capabilities¶
GET /api/shelves returns kind, capabilities and offline alongside id,
name and read_only:
[
{
"id": "living_room",
"name": "Living room",
"read_only": true,
"kind": "virtual",
"capabilities": {
"rescan": true,
"download": true,
"fingerprint": false,
"char_count": false
},
"offline": {
"snapshot_at": "2026-10-16T09:12:44Z"
}
}
]
| Field | Meaning |
|---|---|
kind |
local or virtual, as defined in Two kinds of shelf. |
capabilities.rescan |
The shelf can be rescanned on request (POST /api/shelves/{id}/scans). |
capabilities.download |
Books can be downloaded to the device's offline layer. The engine reports true for a virtual shelf and false for a local one, which is already local. A client that keeps its own offline copy overrides it (see the remote-server connection). |
capabilities.fingerprint |
Fingerprints and similar-book pairs are available. False on a virtual shelf: computing them reads every source, a request per book. |
capabilities.char_count |
Listings carry character counts, so sorting and filtering by length work. False on a virtual shelf, whose listing comes from the exported book cache and carries none. |
offline.snapshot_at |
When the shelf listing was last fetched from the source. Present only on a virtual shelf that has a snapshot; the UI shows it as "last updated" when the source is unreachable. |
capabilities is an object rather than a flat set of can_* booleans so that a
capability can grow detail later without a new top-level key, and so that a
client can treat an unknown member as absent. Every field is added: an older
client ignores members it does not know, and read_only keeps its meaning.
The server fills these from the opened shelf. read_only is still the one
answer to "may I show write controls", and kind never stands in for it: a
local shelf can be read-only too.
Who reads them¶
| Former caller | Implemented behavior |
|---|---|
composables/useShelfRefresh.ts asks supportsShelfRefresh and getShelfFetchedAt |
reads capabilities.rescan and offline.snapshot_at |
features/library/pages/LibraryPage.vue, features/maintenance/pages/SimilarContentPage.vue and utils/bookFilters/registry.ts ask supportsCharCountListing |
read capabilities.char_count |
features/maintenance/pages/SimilarContentPage.vue calls getFingerprintStatus and handles an empty answer |
checks capabilities.fingerprint first |
features/mobile/pages/DownloadsPage.vue and the book actions use the mobile download methods |
check capabilities.download, then call the shelf interface |
composables/useServerMode.ts asks /api/mode directly |
Already implemented; pCloud entries query the embedded server |
/api/mode reports the whole installation's read_only, not the selected
shelf's. The embedded server can be writable while its pCloud shelf stays
read-only: useWriteAccess also requires a provider with a write surface, which
the mobile pCloud reader does not have. Its API transport rejects writes too.
The mode query does not wait for the pCloud shelf to open.
The fields live in server/contract/shelves, beside ShelfInfo
(server/handle_shelf.go). The source configuration itself is never part of the
response, as the source design requires.
The platform interface¶
The interface is implemented in frontend/src/providers/platformCapabilities.ts.
Wails supplies its host operations in providers/wailsBookshelfProvider.ts;
Capacitor supplies its object in shells/mobile/platform.ts. Web and the wasm
app use the browser implementation. The wasm toolbar continues to manage its
own engine outside the shared app; it does not expose shelves to that app.
interface PlatformCapabilities {
// Shelf management: present only where the host can manage shelves.
shelves?: {
previewShelfID(name: string): Promise<ShelfIDPreview>;
addShelf(params: AddShelfParams): Promise<void>;
checkShelfSource(params: ShelfSourceParams): Promise<ShelfSourceCheck>;
listShelfDetails?(): Promise<ShelfDetails[]>; // Includes failed virtual entries.
retryShelf?(shelfID: string): Promise<void>;
getShelfDetails(shelfID: string): Promise<ShelfDetails>;
modifyShelf(params: ModifyShelfParams): Promise<void>;
removeShelf(shelfID: string): Promise<void>;
};
// Files and folders on the device.
openLocalBookFiles?(): Promise<string[] | null>;
importBookFromLocalPath?(localPath: string, folderPath: string): Promise<ImportBookResult | null>;
openFolder?(folderPath: string): Promise<void>;
openBookFolder?(bookId: string): Promise<void>;
openShelfFolder?(shelfID: string): Promise<void>;
chooseShelfDirectory?(): Promise<string | null>;
saveBookContentToFile?(bookId: string, suggestedName: string): Promise<string | void>;
// Other apps and the system.
openReader?(bookId: string, section?: number): Promise<void>;
openExternalUrl?(url: string): Promise<void>;
getStorageEstimate?(): Promise<StorageEstimateResult>;
// Rendering workarounds.
coversMustBeFetchedAsBlob?: boolean;
}
The host builds this object during bootstrap (lazily for desktop), and the frontend
reads it through getPlatformCapabilities(), beside getBookshelfProvider(). A missing member means the
platform cannot do it, which is the same rule the optional methods follow today,
in one place instead of spread over the provider.
| Host | shelves |
Files and folders | openExternalUrl |
|---|---|---|---|
| Server (browser) | absent: shelves come only from the YAML file | absent | browser window.open |
| Desktop (Wails) | Wails bindings | Wails bindings | Wails Browser.OpenURL |
| Android (Capacitor) | absent from the shared desktop management form; the mobile entry editor uses its existing Go plugin | Documents export, storage estimate, blob covers | Capacitor Browser (browser preview uses window.open) |
| wasm demo | absent in the shared app; the host toolbar manages the engine | absent | window.open |
None of this goes over the HTTP API. Shelf management stays a host
capability, as Who holds the shelf list
requires: server.App's handler has no shelf-management route, so "can this
client manage shelves" is answered by whether shelves is present, never by a
server field.
Reaching the Wails bindings¶
Every frontend call into Go goes through frontend/src/api/wailsBindings.ts;
nothing else imports @wailsio/runtime. Both apps run on Wails v3, and the
module calls Call.ByName("main.<App>.<Method>") from @wailsio/runtime,
which it loads with a dynamic import so the web and mobile bundles never
contain it; main.ts loads it before anything else boots,
because v3 reports the page ready (WindowRuntimeReady) only once the runtime
runs.
The page learns which Wails app it runs in from
a marker the Go side injects into index.html: window.__PLAINSHELF_DESKTOP__
from desktop/assets.go, window.__PLAINSHELF_READER__ from
reader/readerapi/spa.go. isWailsRuntime() is true for either marker or for
?desktop-shell-preview=1. Both apps also answer an in-app route such as
/books with that page, so a reload keeps the route; neither adds a Wails
script tag, since the runtime comes from the bundle. A call made inside the
right app whose method Go does not bind rejects with an error naming
App.Method, since the method list is only known to Go, so a binding lost in a
migration fails loudly instead of disabling the feature. The mobile stack may
not import this module or src/api/desktop.ts; check-boundaries enforces it,
and also that @wailsio/runtime is only ever imported dynamically from here.
The remote-server connection stays a wrapper¶
The Android app can still connect to another PlainShelf server's full API, as
it does today. That connection is client-side state, not a shelf source (see
Compatibility), and its offline downloads
remain the job of MobileBookshelfProvider wrapping a ServerBookshelfProvider.
In the Android shell (frontend/src/shells/mobile/index.ts), only remote-server
entries use MobileBookshelfProvider. Embedded pCloud and WebDAV entries use
EmbeddedPCloudReader directly: Go owns their offline content and snapshots.
Local shelves use ServerBookshelfProvider without a wrapper.
The capability migration keeps downloads available on a wrapped
remote connection, whatever the remote server reports. A remote server reports
download: false for its local shelves, and an older server reports nothing,
so the mobile shell overrides download to true for its wrapped entries. The
layer that owns the offline copy answers download: the
engine for shelves it opens, the wrapper for a remote connection.
getPersistedShelfID belongs to the remote-server wrapper.
Virtual shelves now cover reading another PlainShelf through its WebDAV export. Retiring the full-API remote-server connection and its wrapper remains a separate decision.
What stays the same¶
WailsBookshelfProviderkeeps extendingServerBookshelfProvider: the desktop is already the target shape. Its desktop-only methods have moved to the platform object; the shelf methods do not change.read_onlyonGET /api/shelveskeeps its meaning and its place.- An older client against a newer server ignores
kind,capabilitiesandoffline. A newer client against an older server sees them missing and falls back to today's behaviour:rescantrue, the rest true, anddownloadas the remote-server wrapper reports it (true) or false where nothing wraps the shelf.
How the rest of the system follows¶
- pCloud in Go. A pCloud shelf reports
kind: virtual,download: trueandoffline.snapshot_at, so the UI that reads them needs no pCloud branch.PCloudBookshelfProvideris no longer constructed for pCloud, and the screens listed in Who reads them read the new fields. - Removing the TS pCloud reader. Done.
EmbeddedPCloudReaderreads through Go and still answersfiltersNsfwOnDeviceandlocalNsfwMarksfor the device preference and offline filtering. A follow-up removedsupportsServerModeand routed pCloud's/api/modequery to the embedded server. - Required illustration methods. Done.
getSourceAssetandgetSourceAssetsBundleare required onBookshelfReader, so a backend that omits either fails the type check.MobileBookshelfProviderforwards a bundle request to its remote while online and rejects it offline, since the cache stores figures one by one; the reader's per-image path still reads them. - Offline download. Done in Go:
capabilities.download,offline.snapshot_atand the download API exist. Android's embedded virtual entries now use Go downloads directly; only remote-server entries use the wrapper. - Desktop and Android hosts. LAN sharing and Android
local shelves are implemented through host bindings. Exposing shelf
management through
PlatformCapabilities.shelves, with the generic names above, is implemented for Wails. Android keeps its mobile entry editor and Go plugin outside the desktop management form.coversMustBeFetchedAsBlobis retained as a platform boolean for all Android shelves, including local ones.
Reading shell metadata¶
listServerShelves() preserves validated kind, capabilities and
offline.snapshot_at fields. The mobile shell enriches its device-local entry
with the engine response, retaining the device's entry ID and display name.
Embedded virtual entries route /api/shelves to Go as well as their shelf
routes. A disconnected wrapped entry still advertises its working downloads.
The selected shelf's capabilities are reactive, so switching shelves updates
refresh, character-count and fingerprint controls without rebuilding a provider.
Missing rescan, char_count or fingerprint members default to true.
Missing download defaults to false unless the offline wrapper overrides it.
Invalid snapshot dates are ignored. This keeps older servers compatible while
honoring explicit false values from newer servers.