Pairs with Pinakes 0.9.4 (Mobile API 1.12.0). Works with older servers: without pickup_deadline the row shows the return day, as in 1.13.0.
- Last pickup day (#61): a reader's
da_ritirareloan shows "Pick up by " frompickup_deadlineonGET /me/loans, the stored pickup day moved by the server to the next open day of the copy's branch, the same day the staff loan page already showed. A missing or blank value falls back to the return day. - The offline cache keeps the server calendar:
cached_loansstoreseffectiveDueAt,isOverdueandpickupDeadline(Room version 4, additive migrationMIGRATION_3_4, no data loss on update), so a cached loan shows the usable return day and the server's lateness instead of the stored due date.CacheMigrationTestupgrades a real version 3 database without the destructive fallback.
Pairs with Pinakes 0.9.2 (Mobile API 1.11.0). Works with older servers: without staff_attendance_member_pick in /health the button is not shown and the desk behaves as in 1.12.0.
- Find member in the visitor log's desk tab: a reader who forgot the card is found by name, e-mail, card or phone with the loan desk's borrower search (
GET /staff/users, at least two characters) and checked in withuser_idonPOST /staff/attendance/check-ins, under its own Idempotency-Key, with the same result card, tone and inactive-account warning as a scanned card. The rows show card and e-mail only: loan eligibility (a debt block, for example) plays no part at the entrance. The camera stops reading while the search is open.404 member_not_foundhas its own wording; a422keeps the server's text. - Shown only when the server advertises it (
/health.features.staff_attendance_member_pick, Pinakes 0.9.2), and with the visitor log on.
Pairs with Pinakes 0.9.0 and 0.9.1 (Mobile API 1.10.0 as shipped in the stable release). Works with older servers: the new fields are optional and their absence keeps the 1.11.0 behaviour.
- Loans show the usable return day (#58): reader and staff loans read
effective_due_at(the first open day after a due date closed afterwards) andis_overdue(lateness in the library timezone and the copy branch calendar). The date shown, the "late" state and the active/overdue grouping follow them, so a loan due on a closure is not shown late while the library is closed;due_atkeeps the stored date. - Same-day handover after a closure: Library settings → Loans gains the web's Closures calendar section with the
same_day_handover_after_closureswitch and its help (when on, another reader can receive the book on the first open day after a closed due day). It is sent only when changed, and only when the server sends it; Staff can change it, as on the web.
Pairs with Pinakes 0.9.0-rc.2 (Mobile API 1.10.0 for the staff areas, the copy editor's consultation switch and patron_type on the profile; Mobile API 1.9.0 for closed_dates, loanable, reservations_enabled, /me/movements and the new 409 codes; Mobile API 1.9.1 for the /health toggles fines, closures_calendar and circulation_rules). Works with older servers: every field is optional, the three flags default to off, and their absence keeps the 1.10.0 behaviour.
- Feature toggles:
/health.features.fines,closures_calendarandcirculation_rulesare read and stored with the other flags; catalogue mode turns all three off whatever the server sends. - Closures calendar:
closed_datespaints closed days grey (legend "Library closed", only when the library has closures), they cannot be picked as a start, a tap says the library is closed, the pre-selected day skips them, and a proposed return date always lands on an open day (the default return moves forward as the server does; a shortened one sent asend_datemoves back, never past the booked day). Same calendar for the reader and for the staff loan desk. - Consultation only and closed waitlists: with
circulation_ruleson, the book page readsloanableandreservations_enabledfrom the availability payload; the loan button stays visible but disabled, with the reason under it ("Consultation only", or no reservations with this card). A 409not_loanable/reservations_disabledturns the button the same way at once. - Refusal codes:
not_loanable,reservations_disabled,reservation_limit_reached,media_limit_reached,max_loans_reachedandnot_eligiblewithmeta.reasondebt_block/card_expired/user_suspendedhave their own wording for readers and staff; unknown codes keep the server message. Staff borrower pages and the new-loan form name the eligibility reason in the app's words. - Balance and movements (Profile, only with
features.fines): balance, the "loans blocked" banner with the library's threshold, fines still accruing on overdue loans, and the ledger. A 404feature_disabledcloses the page without an error. - Additive, shown when the server sends them:
patron_typeon the profile,consultation_onlyon a staff copy. - Consultation-only copies on their own switch: Pinakes 0.9.0 moved them off the rules matrix (
/health.features.consultation_only). The book page now asks for the reader's rules when eithercirculation_rulesorconsultation_onlyis on, so a consultation-only title shows the disabled button with its reason even with patron-type rules off. A server without the key keeps tying it tocirculation_rules.automatic_finesanddebt_blockneed no client change: the server already leaves the accruing fines out and sendsdebt_block_threshold_cents: nullanddebt_blocked: falsewhen they are off. - A loan approved on a closed day: with the library closed today, an auto-approved request comes back
prenotatowithstart_date(the next open day). The confirmation now says from which day the book can be picked up, instead of "ready for pickup". - Quoted searches offline (Pinakes #501): online, quotes ask the server for the exact spelling. The offline catalogue folds accents and cannot tell spellings apart, so it now drops the quotes and searches the words, as the server reads them (straight and typographic quotes; an inch mark after a digit stays), in the text query and in the author and publisher filters. Before, it looked for the quote characters and found nothing.
- Staff reservations beyond the patron type's limits: with
circulation_ruleson, the staff new-reservation form has the website's switch "Ignore the reservation limits of the patron's type", sent asoverride_limitsonPOST /staff/reservations. Without the switch, or with the rules off, the key is left out. - Consultation-only copies from the copy editor: with
features.consultation_onlyon, the staff copy editor has the switch the book page has;consultation_onlyis sent onPUT /staff/copies/{id}only when it changed. The server refuses it for a copy on loan, awaiting pickup or requested, as the website does. Needs Mobile API 1.10.0 (Pinakes 0.9.0-rc.2), which also sendspatron_typeonGET /mefor the profile row. - Library card barcode: the profile draws the card code (
codice_tessera) as Code128, the printed card's default (Pinakes 0.9.0 library cards), so the desk and the visitor-log kiosk can scan the phone. Only printable ASCII is encoded, as on the printed card. - Staff patron tools (Mobile API 1.10.0, each shown only when its flag and the server's
can_*allow it): the staff patron screen gains a patron section with the photo (take, pick, replace, remove; fetched with the token and kept in memory only), the patron type with the type picker and the "set the expiry from the type" switch, card renewal (Idempotency-Key) and the printable card PDF, and the balance with the debt block leading to the new ledger screen (balance, fines accruing on open loans, paged movements with the operator and the payment receipt PDF, payment, charge and waiver sheets with exact decimal-to-cents parsing and a required Idempotency-Key). The staff return shows the late fine a return today charges, with a waiver switch and its mandatory reason (waive_fine/waive_reason). The front desk gains the visitor log (card scan in CODE 128 or QR, manual entry, branch choice, a result card with a short tone, guests, and a statistics tab with periods, day and hour bars, latest visits, CSV export and, for administrators, retention and purge) and the patron CSV import (upload with separator choice, preview, column mapping with required fields, invitations, the chunk loop of the catalogue import, counters, error report and example file; the jobs left open here or on another device are listed with Resume and Cancel). A 403not_permittedshows the server message and keeps the staff area. - Fixes from a live run against a 0.9.0-rc.2 server: switching a module in Library settings re-reads
/healthat once, so the hub adds or drops the entry without an app restart; the patron type editor's "Empty: …" hint shows what clearing the field gives, not the type's own value; the staff ledger words the balance about the patron; the finished patron import offers the error report only when it has rows; MARC jobs whose list answers late stay in view; a stocktake status poll answered after a close can no longer reopen the session on screen.tools/e2e/live_smoke_090.pydrives every staff area on an emulator against a real server. - No change to the local cache database (Room version 3).
- Staff: library settings (Pinakes 0.9.0, Mobile API 1.10.0, areas
library_settings,circulation_rules,closures_calendar): three screens in the hub's Library section. Library settings has the web's Modules, Loans and Cards tabs: module switches with their help and dependencies (read-only state and no save action whencan_configureis false), every loan setting with its own input (amounts in the server currency, parsed to cents exactly; fields outsideeditable_fieldsshown as values, so Staff never sends the money policy), card layout and texts; a save sends only what changed. Patron types and loan rules lists the types (default, inactive, patrons) with a sheet for every field (empty inherits, the inherited value as hint), default, order and delete, plus the rules matrix (patron type, "all types" included, by material) whose changed cells are saved together. Closures calendar shows the month (by branch) with each closed day's reasons, and edits weekly closed days, closures, yearly switches, the national holiday preset (country, region, year preview), the library's own holidays of every kind, and imports an ICS file. A screen this account may not use (403not_permittedon its first load, or 404feature_disabledfor Staff with the module off) closes with the server's message; a refused action inside a screen shows the message and stays. Only the role gate's 403forbiddendrops the staff role. - Cataloguing (Pinakes 0.9.0, Mobile API 1.10.0): the staff hub's Cataloguing section opens Suppliers (list with search and book counts, create with an Idempotency-Key and the server's field errors under each field, edit as a patch, delete saying how many books lose the link), MARC (import: file from the document picker, flavour, encoding, duplicate mode, supplier and covers from
/staff/marc/options, preview of the first records, then the CSV import's chunk driver with out-of-order recovery, pause, resume and cancel; the unfinished MARC jobs on the server (GET /staff/marc/imports, so also one started on another device or whose id the app lost) are listed above the form with Resume and Cancel; export of the whole catalogue or of chosen books in MARC 21, MARCXML or UNIMARC, and the chosen books' catalogue cards) and Copy cataloguing (catalogues, index, term with an ISBN/ISSN scan, results to select, duplicate mode and covers, idempotent import with links to the new records; the plugin's absence is explained instead of the form). The book form gains a supplier picker and the RDA content, media and carrier selects ("derived" names the server's value) only while the lookups carry them, so the keys stay out with the modules off; the record's screen prints its catalogue card and exports it in MARC. The staff book list has no selection mode, so the multi-book actions live in the MARC screen. A 403not_permittedshows the server message and keeps the staff role. - Staff: stocktake and statistics (Pinakes 0.9.0, Mobile API 1.10.0, areas
stocktakeandstatistics): Stocktake lists the sessions by status with their counters and opens new ones from the server's options (name, note, branch, shelf and its level, genre, media type, shelfmark range) under an Idempotency-Key. A session screen is the scanner: the camera reads copy labels continuously (a label held in view is sent once, reading it again after moving away is sent and recorded as a repeat, as on the web), a typed or keyboard-wedge code works the same, every scan carries the shelf being checked and its own Idempotency-Key, and the answer shows at once in the outcome's web colour with the web's tone (silent unless the ringer is on) and a haptic tick. Counters, the latest scans (by outcome, only mine) and the session status are polled every four seconds while the screen is visible, so several operators see each other's progress; a code list (.txt/.csv) can be uploaded; close asks what to do with the missing copies and says how many there are (mark lost only when the server allows it, also to finish a cut-short marking); a refused mark-lost (403not_permitted) shows the server's message and keeps the role; cancel asks first. The report lists the rows by category and downloads the CSV or the PDF (a too-long PDF says to take the CSV). Offline the screens leave and no code is kept for later. Statistics shows the overview, loans by month, state and material as bars, the most borrowed books (a tap opens the staff book) and the most active readers, then only the sections the server sends (patron types, fines, stocktake), visitors, and the fines report with its period and CSV, amounts in the server's currency. Bodies captured from a 0.9.0 server back 39 unit and Robolectric tests andStocktakeFlowTest.
Pairs with Pinakes 0.8.7 (Mobile API 1.8.2). Works with older servers: every new field is optional and its absence keeps the 1.9.0 behaviour.
- Loan requests stop before a scheduled loan (#53, Pinakes #490): when a scheduled loan or a reservation on every copy begins inside the requested period, the sheet ends the loan the day before, says how long it can be and from when the book is booked, and sends that day as
end_dateofPOST /reservations. A start whose next day is already booked says no loan is possible from it and keeps the request button off. The window also respects the library'smax_loan_duration_days. One predicate decides which days are fully booked, for the calendar and the cap alike. The cap needs a server that readsend_date, which is the one that sendsmax_loan_duration_days: on Pinakes 0.8.6 (Mobile API 1.8.1) the sheet keeps the 1.9.0 behaviour, uncapped and withoutend_date. - No change to the local cache database (Room version 3).
- Verification on this release branch: 446 debug unit tests with none failed or skipped, lint and
assembleDebug; 17 device tests on an Android 15 emulator (LoanRequestSheetUiTest,CalendarLayoutTest,DesiderataStaffFlowTest,DigitalLinkRefreshFlowTest), none failed.
Pairs with Pinakes 0.8.6 (Mobile API 1.8.1). Works with older servers: every new field is optional and its absence keeps the 1.8.0 behaviour.
- Digital files a reader cannot open yet (#50, Pinakes #480): a file the server closes (
url: null,access=login_requiredorloan_required) keeps its card on the book page with a lock and the reason instead of the Read/Play button. Signed links last a day; a tap revalidates the file on the server and opens the renewed address, whatever the phone clock says, bypassing both caches and never falling back to an expired link. A playing audiobook keeps playing when another file of the record is renewed. Servers before 0.8.6 send neither field and every file stays open as before. - Loan request sheet (#46): a plain dialog styled after the web's loan calendar instead of
DatePickerDialog, which cut the month in half; free days are plain numbers, limited and unavailable days keep their tint, the fallback calendar (no availability) lets every future day be chosen and says the server checks the request. - Return date of a loan request (#51, Pinakes #485): with Mobile API 1.8.1 the sheet shows "Start · Return by" from the library's
loan_duration_days; older servers get a hint about the library's standard loan period instead of "about 1 month". - Wanted titles (#49): the row action reads "Receive" (it read as a status, "Received") and asks before adding the copy; after receiving a wanted title or an offer the app opens the record on the new copy's editor, which shows the code the server assigned and lets staff set its status and notes or print its label.
- No change to the local cache database (Room version 3).
- Verification on this release branch: 422 debug unit tests with none failed or skipped, lint and
assembleDebug, locally and in Android CI; 17 device tests on an Android 15 emulator (LoanRequestSheetUiTest,CalendarLayoutTest,DesiderataStaffFlowTest,DigitalLinkRefreshFlowTest), none failed.
Requires Mobile API 1.7.0. Every area is gated on its own /health flag (staff_circulation, staff_copies, staff_series, staff_merges, staff_labels, staff_imports, staff_covers, staff_desiderata, staff_archives) plus the staff role and staff_catalog; a server that answers false or omits a flag keeps the 1.7.0 staff area for that part. The 403 forbidden contract is unchanged: every new call goes through the shared staffCall, which drops the stored role.
- Circulation desk (hidden, never disabled, while the device is offline; an open desk screen closes when the connection drops): counters of the day, loans by bucket (requests, to pick up, scheduled, on loan, overdue, history) with search and multi-select bulk extend/recall, loan detail with the server's actions (approve, reject with reason, confirm/cancel pickup, return with the copy's outcome and a validated penalty, renew, edit user and dates, reminder, receipt PDF read in the app or shared through the FileProvider, receipt by email), new loan and new reservation (borrower search with eligibility, book search or a scanned copy code, per-user availability calendar, hand over now), reservations grouped by title (edit dates, cancel with reason, reactivate), borrower page. Creates carry an
Idempotency-Key(one per submission, kept across the automatic retry after a dropped connection or a 409concurrent_retry, discarded after success oridempotency_conflict). - Copy scanner: the same CameraX + ZXing pipeline reading CODE 128 and CODE 39 inventory labels (and EAN-13); manual code entry always visible; the sheet shows the copy and its open loan, then returns it with an outcome, lends it, or opens the book or the loan.
- Book tools: per-copy list in the book editor (state, notes, delete with the server's refusal reasons, a copy with its own inventory code), book and copy label PDFs and the label settings sheet; series tree with search, details, rename (an existing name asks before merging), merge, delete, parent work, book numbers, removal and multi-select assignment; duplicate merges (suggested author groups or manual pick, publishers, genres); CSV and LibraryThing imports picked with the system document picker and run chunk by chunk from the server's progress (out-of-order recovery, busy retry, resumable after process death, pause/resume/cancel, error lines, past imports with their error CSV); missing covers fetched one book at a time with progress and the rate limit honoured; server-side cover sync and enrichment batches on the long-timeout client behind a confirmation; automatic enrichment switch.
- Plugin content: Desiderata offers by status (accept, reject, receive into the wanted title or a picked record, delete) and wanted titles marked received; Archives units (published or not) created and edited with the plugin's rules checked client-side, publish switch, authorities with roles, cover and document uploads, delete; authority records list and editor.
- Local verification: 377 debug unit tests (new: tolerant 1.7.0 parsing, loan actions, penalty validation, copy codes and export file names, staff areas × flags × connectivity, idempotency keys, series tree and series/label forms, import chunk rules, archive/authority forms and offer actions), zero lint errors (111 warnings, all pre-existing), debug and R8 release builds.
- Device tests: 92 instrumented tests on Android 15 (
staffe2ewithFakePinakes). New flows: return as damaged with penalty, invalid penalty not sent, borrower page, 409 message, new loan with user search and Idempotency-Key, ineligible borrower, return by typed copy code, unknown code, reservation cancel and create, circulation hidden offline and restored, desk screen closing offline, no section without flags; copy edit, refused delete, copy with code, taken code; series number and rename clash merge; suggested author merge; import resume with out-of-order recovery and an upload through the real system document picker; covers loop and enrichment switch; desiderata receive (linked and into a picked record) and closed offer; archive publish keeping every field and create after validation; a retried merge already done; digital upload through the system picker and its absence without the flag; review regressions (bulk recall in batches with Select all, reservation paging, an authority that failed to load cannot be saved, a failed duplicate list with Retry, an import that ended elsewhere is not resumable, exports deleted on sign out); Tier 2 (a typed issue code received, a masthead's issues and a new year, a club created and a member's role changed, a workflow edited, a work created with an expression and a linked book, no Tier 2 rows without their flags). - Live smoke (
tools/e2e/live_smoke.py) gains: loan created by API with an Idempotency-Key and its replay then returned in the app by typing the copy code, a copy with an explicit code from the book editor, a series created in the app, a two-row CSV import followed to completion, a free Desiderata offer received into a picked record, an unpublished archive unit absent from the public list. Each phase 2 step is skipped while its flag is off; cleanup returns loans the run left open and deletes only the books, series, units and offers the run created. Tier 2 steps: an unknown code at the periodicals desk (read-only, the bridge has no deletes), a book club and an FRBR work created in the app (deleted in cleanup). Run on 2026-10-14 against the local server (Mobile API 1.7.0 branch, every staff flag on) on an Android 15 emulator: 19 passed, 0 skipped, 0 failed. - Tier 2 (each behind its own flag:
staff_periodicals,staff_bookclub,staff_frbr,staff_digital_library): periodicals desk (scan or type an arriving issue's barcode, then receive or claim it; mastheads with years, issue states, new years and issues, subscriptions); book club management (create, settings, reading workflow with reorderable states and voting/reading/archived marks, members' role and membership state, adding a borrower, delete); FRBR works (search, create, edit, delete, expressions, link and unlink books); eBook and audiobook upload from the book editor (streamed, long-timeout client). The periodicals bridge has no article routes, so articles stay on the website.
Requires Mobile API 1.6.0 (Pinakes 0.8.5). Every new entry point is gated on the matching /health feature, so an older server keeps showing exactly the 1.6.2 app.
- Staff area (
staff_catalog+ roleadmin/staff, refreshed from login andGET /me; a 403 on any staff call drops the stored role and leaves the screen): Profile → Staff area, and a scan button on the Catalog tab. Books (list with search, edit, delete with the active-circulation refusal), a shared create/edit form for records with or without an ISBN (identifiers validated live, authors/publishers pickers with "add new", genre/subgenre, shelf/level with automatic position, cover from URL / photo / picked image, copies), authors, publishers, genres (tree, find-or-create) and shelves/levels. Edits are true patches: only changed fields are sent. - ISBN scanner: CameraX + ZXing EAN-13 (no Play services), checksum validation, two identical reads before a lookup, 3 s suppression, batch mode with remembered copies, shelf/level and optional auto-confirm, preview / duplicate ("add copies", "open existing") / not-found sheets. Manual ISBN/EAN entry is always visible (emulators, denied permission). CAMERA is requested only there, with rationale and a settings fallback;
camera.anyis optional. - Offline catalogue: Room v2 holds the whole catalogue, kept current by
GET /catalog/sync(delta with a server watermark, forced full resync every 7 days or when the server asks); loans, reservations and wishlist are written through on every fetch. Without a connection, search, book pages, Library and Wishlist answer from the cache with an offline banner. Loan and reservation actions are hidden offline (never shown disabled) and cached availability is shown only as "last known on ". The cache is excluded from backups. - Loans calendar: Profile → Loans in your calendar (
calendar_feed): create the private ICS link, copy it (primary, Google Calendar can only subscribe from its website), open it aswebcal://with an HTTPS fallback, regenerate (old link stops) or turn it off. - Local verification: 283 debug unit tests (new: ISBN/EAN codec, scan debouncer, staff access, staff form and write bodies, sync merge, offline policy, calendar links, tolerant 1.6.0 parsing, Room v2 catalogue/library DAOs), zero lint errors (111 warnings, mostly newer-dependency notices), debug and R8 release builds.
- Device tests (re-runnable):
app/src/androidTest/java/com/pinakes/app/staffe2e/drives the real app (MainActivity, real Hilt graph, ViewModels, Room) againstFakePinakes, a MockWebServer on the device loopback answering JSON fixtures fromapp/src/androidTest/assets/fixtures/and recording every request. Covered: staff entry only for admin/staff withstaff_catalog(hidden for standard users, for the flag off and after a server-side downgrade, header included); scanner manual ISBN → preview → add → counter, duplicate → add copies, not found → manual form with the code, invalid code rejected, camera denied keeps manual entry (the camera prompt is denied through UiAutomator); manual form title required and shelf-without-level both send nothing, edit sends only the changed key (recorded PUT body); offline search banner with cached results and no availability or loan actions, offline detail "last known" wording without loan buttons, Library/Wishlist offline empty state with no raw exception, going offline after an online load hides the loan button and coming back restores it (real airplane mode); calendar create → masked link, copy flagged sensitive, regenerate and turn off both confirm; gender and tax code absent from the profile editor when the library hides them (present when shown) and never asked at registration; author detail with the padded info card and the author's books (author_idsent); loan-calendar month (7 weekday columns, every day cell inside the screen and inside a 320dp column, month navigation) and the birth-date picker within a 360dp screen. Run on a disposable emulator (it replaces the app's stored session and cache):ANDROID_SERIAL=emulator-5554 ./gradlew connectedDebugAndroidTest(one class: add-Pandroid.testInstrumentationRunnerArguments.class=com.pinakes.app.staffe2e.ScannerFlowTest). - Live smoke (real app, real server):
tools/e2e/live-smoke.sh [--install]withPINAKES_E2E_URL(as the device reaches it, e.g.http://10.0.2.2:8081),PINAKES_E2E_EMAIL,PINAKES_E2E_PASSWORD(admin or staff), optionalPINAKES_E2E_HOST_URL,PINAKES_E2E_ISBN(default 9788845292613, must not be catalogued) andANDROID_SERIAL. It clears the app, onboards, signs in, opens the staff hub, scan-adds an ISBN with 2 copies, adds a copy through the duplicate sheet, creates a record without ISBN, sets its shelf/level (skipped when the instance has none) and checks nothing else changed, searches and opens it in airplane mode, creates the calendar link and fetches the feed, and (withPINAKES_E2E_DB_NAME/USER/PASSWORD/SOCKETor_HOST/_PORT) hides gender and tax code in the settings table, checks they vanish from/meand from the profile editor, then restores the previous values; every step is checked through the API. Cleanup removes only what the run created (books, a calendar link that did not exist before, device tokens issued during the run) and clears the app. Texts follow the device language throughi18n/*.json;tools/e2e/ui.pyis the adb/uiautomator driver (python3 tools/e2e/ui.py dump). - Not covered by automation: real camera decoding and photo capture (emulators have no barcode in view).
The app now uses the 2026 web design: Geist / Fraunces, warm neutrals, a server-ready ThemePalette, complete 3D book covers, a searchable home hero with a cover fan, catalog grid/list views, dot status pills, grouped availability/actions and one card per exposed digital asset. Shared tokens apply to all existing account and plugin screens. The five-section bottom navigation is retained. Article lists and details now show server-resolved covers, subtitles, published online resources and access conditions, with a website action for the existing staff management flows. Native collections require the additive Mobile API 1.5.0 server update; existing circulation and authentication routes are retained.
- Debug APK:
pinakes-debug.apk, copied fromapp/build/outputs/apk/debug/app-debug.apk(generated locally and ignored by Git). - Package:
com.pinakes.app, version1.6.2(19), minSdk 26, target/compileSdk 35. - Local verification: 200 debug and 200 release unit tests, 22 instrumented tests on Android 15, zero lint errors (101 warnings), and successful debug + R8 release builds. The 1.6.2 debug APK installs over 1.6.1 with the same signing certificate.
- Verification commands:
assembleDebug,testDebugUnitTest,lintDebug,assembleRelease,assembleDebugAndroidTest; the 22 device tests run througham instrumenton a separate Android 15 AVD, preserving the authenticated demo device. - Unit tests cover the existing contracts and theme contrast/mixing. Compose device tests cover full tall artwork, missing metadata, grid actions, view selection, digital-file cards, narrow search placeholders, circulation actions theme pairings, reachable empty-home actions and query preservation during loading.
- Release builds exercise R8 and resource shrinking. Without release credentials the output is unsigned; no store release is published by this change.
- macOS standalone emulator startup:
tools/run-emulator.shkeeps a power assertion scoped to the emulator PID. A control with the identical debug APK reproduced a 21-second startup timeout at host priority 4; three starts with the assertion completed in 2.3–3.1 seconds. After a VM restart through the launcher, five more cold starts completed in 1.66–1.80 seconds with no ANR events. The original startup ANR also coincided with system/launcher stalls. An older AVD still stalled on a later cold boot, and a snapshot retained a system ANR dialog: the assertion does not repair an unhealthy AVD. No Sentry events are suppressed, and no production-device ANR fix is claimed. - New native sections: Desiderata with verified-account donation proposals and durable retry recovery; Archives with hierarchy, filters, authorities, documents and exports; analytic articles with all bibliographic fields, five citation styles, rich clipboard, shared-author navigation and issue contributions. Home and catalog support author sorting; every digital attachment and publisher is shown. Staff management uses protected website pages. See Uwe parity.
- Headless Android 15 completed the device tests while older GUI AVDs stalled despite the scoped power assertion. GUI and headless emulator processes had different host scheduling priorities; this is development-environment evidence, not a production ANR fix.
ThemePalettedefaults to Classic / Covers. Discovery does not expose theme, CMS home sections, richer catalog facets, CMS-driven home ordering or share data yet; these are documented as future API work in DESIGN.md.
adb install -r pinakes-debug.apkOn first launch the app shows Onboarding: enter your Pinakes instance URL.
- The app calls
GET <url>/api/v1/health, shows the library name/logo and checksapp_access_enabled+ transport. HTTPS is required except for localhost /127.0.0.1/10.0.2.2(emulator → host) /[::1]. - Local dev API:
http://<lan-ip>:8081(Apache on :8081). From the Android emulator usehttp://10.0.2.2:8081. The Pinakes instance must have mobile app access enabled or login is refused. - Then Login (email/password) → bearer token is stored in EncryptedSharedPreferences and sent
as
Authorization: Beareron every authed call.
| Screen | State | Notes |
|---|---|---|
| 1. Onboarding | ✅ | URL → /health discovery card (name, logo, https + app-access status), continue gated on app-access + secure transport |
| 2. Login | ✅ | Email/password, mapped API error messages (invalid creds, app disabled, rate-limited w/ Retry-After, network), "use a different library" |
| 3. Catalog Search | ✅ | Debounced query, filter bottom sheet (available / genre / author / publisher / language) w/ active-count badge, cursor infinite scroll, BookCards w/ covers + availability chips, loading skeletons / empty / error |
| 4. Book Detail | ✅ | Full payload (cover, metadata, copies, shelf, ISBNs), personal-history chips, Reserve/Request loan, Wishlist toggle, ETag/304 reuse via repo |
| 5. My Library | ✅ | Tabs: Active (active+pending) / History / Reservations; cancel pending reservation w/ confirm; pull-to-refresh |
| 6. Wishlist | ✅ | List + remove (optimistic), pull-to-refresh, empty state |
| 7. Profile | ✅ | View, edit (nome/cognome), change password, in-app language switcher (System / it / en / fr / de), devices list w/ per-device sign-out, logout |
| 8. Notifications | ✅ | Feed w/ per-type icons, read/unread styling, pull-to-refresh |
| 9. Contact | ✅ | POST /messages subject+body form, success state |
- Bottom nav: Home / Catalog / Library / Wishlist / Profile. Nested routes: Book Detail, Notifications, Contact and optional collection details.
- Design system: Material 3 light and dark, 2026 theme-derived colours (Classic magenta by default), bundled Geist / Fraunces, warm neutrals, complete book covers, rounded controls and subtle hero washes. Calendar and status colours follow the app theme. The adaptive launcher icon is preserved.
- Architecture: Navigation-Compose + ViewModel/StateFlow + Hilt, Retrofit + OkHttp + kotlinx.serialization, Coil for covers. All loading/empty/error states handled per screen.
The app supports 4 languages — Italian, English, French, German; the PHP server also supports Danish.
It follows the device locale by default and offers an in-app language
switcher in Profile (System default / Italiano / English / Français / Deutsch) via
AppCompatDelegate.setApplicationLocales(...), persisted across restarts (autoStoreLocales).
- Single source of truth = JSON. Translations live in
i18n/{en,it,fr,de}.json(815 keys each, en = default/source). A Gradle task (GenerateI18nResTask) generatesres/values*/strings.xmlfrom those JSONs at build time, so the app uses standard Android string resources but the editable source stays JSON — syncable with the web app'slocale/*.json. - All user-facing strings use
stringResource(...); no hardcoded UI text remains. Server-provided messages (API errors) still pass through verbatim. - Verified live: switching to Deutsch in-app re-localized the entire UI instantly (Profil, bottom nav Suchen/Bibliothek/Merkliste/Profil, all rows), and the choice survived an app restart.
The app built green from day one, but running it on a real emulator against a live instance surfaced two genuine bugs that a build-only check could not have caught:
- Cleartext HTTP was blocked (Android 9+ default). The app could not reach any
http://instance — including a loopback/dev server. Fixed by addingres/xml/network_security_config.xmlwhitelisting cleartext forlocalhost/127.0.0.1/10.0.2.2(mirrors the app's own "HTTPS-except-loopback" onboarding rule) + referencing it in the manifest. Every other host still requires HTTPS. - Blank book titles + wrong availability. The catalog Kotlin models used Italian field names
while the API serializes English snake_case keys (
title,author,cover_url,copies_available,loanable_now, …). kotlinx.serialization left every field empty, so cards showed no title and always read "On loan". Fixed by aligningBookSummary/BookDetail(and the loan / reservation / wishlist / notification item models) to the real API keys, and fixing the availability logic (loanable_now || copies_available > 0). Verified: titles, authors and the green Available / red On loan chips now render correctly.
The optional server-side Book Club plugin is now surfaced in the app. It is
auto-discovered and gated: after login the app probes GET /api/v1/bookclub/health
(public, no token) and only shows the section when the plugin + its mobile module are
active for the instance (a 404 hides it). The flag is cached in an encrypted store and
refreshed alongside /health, so the entry never flickers and a first-run/offline probe
keeps it hidden — same "confirm before showing" rule as public registration.
- Data layer —
BookClubApi(Retrofit) +BookClubRepository, reusing the same base URL and bearer token as the core client; the availability flag lives inFeatureStore(InstanceFeatures.bookClubAvailable) next to the other instance gates. The plugin uses a different envelope ({success, data, error}vs the core{data, meta, error}), handled by a dedicatedbookClubCallthat reuses the core error pipeline (parseErrorBody, status fallbacks,Retry-After) and the sharedApiResult/ErrorCodes. - Screens — a Book Club home (your reading dashboard, your clubs, discover directory,
reached from Profile) and a club detail (reading list with state chips + progress,
polls, meetings). Actions wired end-to-end: join, vote (simple / multi / weighted,
with the ballot pre-seeded from
my_option_ids), RSVP (yes / maybe / no), and reading progress. Guests are read-only. Advanced poll modes and proposing a title deep-link to the web page (per the API contract). - i18n — all new strings added to the 4 locale JSONs (it/en/fr/de), in parity.
- Build —
testDebugUnitTest,assembleDebug,lintDebugandassembleRelease(R8/minify — exercises the keep rules for the new@Serializablemodels) all BUILD SUCCESSFUL.
A full adversarial review against the Book Club plugin + mobile-api PHP sources confirmed the wire contract (paths, regexes, casts, nullability, envelopes, error codes) and fixed every confirmed finding:
- Rejoin parity:
canJoinnow mirrors the server — members with statusleft/suspendedcan re-join (the web shows the join form for them; onlybannedis blocked). - Expired polls: the mobile API never lazy-closes polls (only the web page/cron do), so a
past
closes_atnow renders as Closed instead of a ballot that can only 409poll_closed. - Full meetings: the Going chip disables when
yes_count >= seats(unless already going), mirroring the server's 409no_seatsrule; maybe/no stay enabled. - MySQL DATETIME timestamps: the server emits raw
Y-m-d H:i:sfor reviews, devices and book club dates —DateFormatnow parses wall-clock values, fixing raw strings that previously rendered verbatim on review cards and the device list. - Home "Available now" shelf: restored the server-side
available=truequery (the cached first page is only the offline fallback), so availability beyond the newest 40 titles shows again. - Instance switch hygiene:
forgetInstance()now purges the Room catalog cache + ETag cache (no cross-library leak), and a late availability probe can no longer resurrect the Book Club flag after switching (probe results are guarded by instance URL). - App-access gate: the Book Club section also hides when core
/healthreportsapp_access_enabled=false(the plugin's public health answers 200 regardless). - Startup/login latency: the core health call and the plugin probe now run concurrently.
- Error codes:
ErrorCodesnow matches the server's realapp_access_disabled(the oldapp_disabledconstant matched nothing the server emits). - Partial failures: a dashboard fetch failure on the Book Club home now surfaces a snackbar instead of silently dropping the "Your reading" section.
- Push (UnifiedPush): STUBBED — not wired. The data layer is ready (
/me/push/subscribe,/me/push/prefsinPinakesApi+NotificationsRepository), and/healthexposesvapid_public_key. A UnifiedPush distributor receiver + push-prefs screen were deliberately not added to keep the build minimal and green per the spec's "stub if time-limited" clause. Next step: add theorg.unifiedpush.android:connectordependency, aMessagingReceiver, callsubscribePush()on registration, and build a prefs screen on top ofpushPrefs()/updatePushPrefs(). - Register / forgot-password: API + repository methods exist (
AuthRepository.register/forgotPassword) but no dedicated screens — login is the only auth entry point in this build.
./gradlew assembleDebug→ BUILD SUCCESSFUL;./gradlew lintDebug→ 0 errors.- APK badging verified (
aapt dump badging): correct package, label, launchable activity. - Manual smoke test on an Android 15 / API 35 emulator against a live instance (
http://10.0.2.2:8081): onboarding →/healthdiscovery card → admin login (POST /auth/login→200) → catalogGET /catalog/search→ book cards with real titles/authors + correct availability chips → Profile loaded. Two bugs found and fixed (see Fixes applied); re-verified green afterwards. - i18n verified live: in-app switch to Deutsch re-localized the whole UI immediately and persisted across an app restart.
- Not run: automated instrumented tests /
testDebugUnitTest(no unit tests authored for this build).