Skip to content
OPEN PANEL · THROUGHLINE

OPEN PANEL — Desktop App Spec (`SPEC_DESKTOP.md`)

OPEN PANEL — Desktop App Spec (SPEC_DESKTOP.md)

Section titled “OPEN PANEL — Desktop App Spec (SPEC_DESKTOP.md)”

Surface spec for WS4 Desktop. Subordinate to CANON.md (single source of truth). Stack and contracts are locked by canon §3, §4, §6 — this document specializes them for the desktop surface; it does not re-decide them. Status: DRAFT v0.1 — 2026-06-13. Brand nouns ALL-UPPERCASE in prose per style guide.

1. Goals & role of the desktop app

Section titled “1. Goals & role of the desktop app”

The desktop app is the power surface of OPEN PANEL. Where WEB is reach and MOBILE is daily reading, DESKTOP is two things the other surfaces cannot do well:

  1. The collector’s library. A large, locally-held library of STANDARD ISSUES and VARIANT EDITIONS, read at high resolution on a big screen, fully offline-first. The reader who keeps hundreds of comics and reads them on a 27” display lives here.
  2. The preferred host for CREATOR TOOLING. Uploading, packaging, and authoring comics into CPF (Comic Package Format) is a heavy, filesystem-bound, multi-asset workflow that belongs on the desktop — not in a browser tab or on a phone. DESKTOP is the home of STUDIO MODE.
  3. The preferred host for FOUNDATION / VARIANT back-office tools (role-gated): rights & royalty LEDGER views, licensing deal entry, and analytics dashboards for staff.

Non-goals: DESKTOP is not the primary acquisition funnel (that is WEB), and it does not re-implement business logic — it is a client of the same backend contracts (canon §6).

2. Platforms, Tauri rationale, signing & update

Section titled “2. Platforms, Tauri rationale, signing & update”
  • Platforms: macOS (Apple Silicon + Intel universal), Windows (x64; arm64 best-effort), Linux (x86_64 AppImage + .deb; Flatpak best-effort).
  • Tauri rationale (canon §4 locked choice): Rust shell + web UI. Chosen over Electron for: small installers and low memory (system WebView, not a bundled Chromium), a real Rust layer for the heavy local work (CPF packaging, image tiling, local library index, offline cache), and a capability-based security model (§8). The web UI reuses the same React + TypeScript components and the @openpanel/reader engine shared with WEB and MOBILE — one engine, three clients.
  • Code signing: macOS — Developer ID + notarization + stapling; Windows — Authenticode (EV cert preferred for SmartScreen reputation); Linux — detached GPG signatures on AppImage/.deb plus published checksums.
  • Auto-update: Tauri updater against a signed update manifest served from R2/CDN (canon §4). Updates are signed with a dedicated update key (separate from app signing) and verified before apply. Channels: stable (default) and beta. Staged rollout; in-app “restart to update” with release notes. STUDIO and back-office users can be pinned to stable to avoid mid-deadline churn.

3. Two modes

Section titled “3. Two modes”

The app is one binary with two top-level modes; the mode switcher is gated by account role and entitlements. READER MODE ships first (MVP); STUDIO MODE is phase 2.

3.1 READER MODE (everyone)

Section titled “3.1 READER MODE (everyone)”
  • Collector library: large local library, fast grid/list browse, series → issues hierarchy.
  • Big-screen reading: page view and guided view (panel-by-panel pan/zoom along the authored reading path) rendered by @openpanel/reader from the CPF (canon §3, §6.1).
  • High-resolution reading using tiled page images; two-page spread mode for large displays.
  • Offline-first: the local library is the source of truth for reading; network is only needed to acquire new issues and to sync progress.
  • Resumable progress, bookmarks, reading history; accessibility (alt-text per panel, dyslexia-friendly mode) and locale switching per canon §3.

3.2 STUDIO MODE (creator role)

Section titled “3.2 STUDIO MODE (creator role)”

Authoring surface for turning raw artwork into a valid CPF:

  • Import pages from the local filesystem (ordered image sequence; PSD/TIFF/PNG/JPEG/ WebP) into a working project.
  • Define panels & guided-view path: draw panel regions over each page, order them, set the pan/zoom reading path the reader engine will follow.
  • Write alt-text & metadata: per-panel alt-text (accessibility), credits, series/issue info, locale, content rating (feeds the editorial/rating policy, operating contracts §8).
  • Export a valid CPF: package assets + manifest; validate against the CPF contract (canon §6.1) before export is allowed.
  • Submit for review: push the CPF to the backend review queue (canon §3 backend, §6.2 Content API) and track its status (submitted → in-review → changes-requested → accepted/published).

4. Local library management

Section titled “4. Local library management”
  • Import sources: acquire issues from the catalog (download CPF bundles from R2/CDN); also “open a local CPF file” for sideloading creator previews.
  • Organize: series/issues hierarchy, user collections/shelves, tags, read/unread, “want to read”; search across local metadata (titles, creators, tags) offline.
  • Offline storage: CPF bundles stored in an app-scoped library directory with a local index (SQLite via the Rust layer). Configurable library location and a storage budget / eviction policy for cached page tiles (keep manifests + low-res, evict high-res tiles on pressure, re-fetch on demand). User can pin issues to “keep offline forever”.
  • Sync progress with account: reading position, bookmarks, and library membership sync through the Identity & Entitlements + Content API contracts (canon §6.2, §6.3), so a comic started on MOBILE resumes on DESKTOP. Offline-first sync model in §6.

5. Creator / Studio workflow detail (the CPF authoring pipeline)

Section titled “5. Creator / Studio workflow detail (the CPF authoring pipeline)”
  1. New project → choose series/issue (new or existing the creator is credited on).
  2. Import & order pages → Rust layer ingests images, generates working thumbnails and tiled high-res derivatives locally (no upload yet).
  3. Panel & guided-view authoring → creator draws panel regions, sets reading order and per-panel pan/zoom; live preview in the real @openpanel/reader engine (guided view identical to what readers will see — no separate preview renderer).
  4. Metadata & accessibility → per-panel alt-text, credits, rating, locale, license note (the Creator Agreement data model, canon §6.5, governs downstream royalty attribution).
  5. Validate → run the CPF contract validator (canon §6.1): required fields, panel geometry within page bounds, guided-path completeness, alt-text coverage threshold, asset integrity/hashes. Validation errors block export; warnings are surfaced.
  6. Export CPF → produce the signed, valid package locally (creator can keep a copy).
  7. Submit for review → upload CPF assets to R2 via backend-issued credentials; create a review-queue entry (canon §6.2). Resumable uploads for large bundles; status tracking and reviewer comments shown in STUDIO.
  8. Iterate → on “changes requested”, reopen the project, fix, re-validate, resubmit.

The validator is the same contract artifact the backend enforces — STUDIO catches problems locally so submissions that pass STUDIO pass the backend, by construction.

6. Auth, entitlements & offline-first sync

Section titled “6. Auth, entitlements & offline-first sync”
  • Auth: Supabase Auth, one identity across surfaces (canon §4, §6.3). Desktop uses OS-secure token storage (Keychain / Credential Manager / libsecret) for refresh tokens; never plaintext on disk.
  • Entitlements: STANDARD ISSUES are always free (always granted). VARIANT EDITIONS use entitlement checks, not hard DRM (canon §4 DRM stance). Entitlements are fetched and cached for offline reading with a signed expiry; reading a downloaded premium issue offline works until the cached entitlement lapses, then re-verifies on reconnect.
  • Roles: reader (default), creator (unlocks STUDIO MODE), staff/foundation/ variant (unlock role-gated back-office surfaces, §7). Roles come from the account; the UI hides modes the role does not grant.
  • Offline-first sync model: local library + local progress index are authoritative for the reading experience. Mutations (progress, bookmarks, shelves) are written locally, queued, and synced opportunistically. Conflict resolution: last-write-wins per field with monotonic timestamps for progress; set-union for collections/bookmarks to avoid lost adds. STUDIO project state is local-only until export/submit.

7. Optional back-office surfaces (role-gated)

Section titled “7. Optional back-office surfaces (role-gated)”

Surfaced only for staff/foundation/variant roles; ordinary readers never see them. These are thin desktop clients over backend contracts — no business logic on the client.

  • Rights & Royalty LEDGER views — read-mostly dashboards over the Ledger schema (canon §6.4): works → rights → grants → licensees → royalty terms → payouts. FOUNDATION staff see IP-owner views; VARIANT staff see licensee views.
  • Licensing deal entry — create/edit licensing grants that link into VARIANT (canon §6.4, §6.6 inter-entity license). Writes go through the backend with the same conflict-of-interest controls the org enforces (operating contracts §2).
  • Analytics dashboards — privacy-respecting reading/engagement analytics (canon §6.7, §4 analytics). No third-party ad trackers; COPPA-aware aggregates only.

These are opt-in to build (phase 3+); the spec reserves the navigation slot and the role gate now so they slot in without a re-architecture.

8. Security (Tauri capability model)

Section titled “8. Security (Tauri capability model)”
  • Capability allowlist: enable only the Tauri commands each window needs; READER MODE windows get no filesystem-write or process capabilities; STUDIO MODE windows get scoped FS access only.
  • No nodeIntegration-style holes: the web UI cannot reach arbitrary native APIs — all privileged work goes through explicit, audited Rust commands with validated arguments. No eval of remote content; strict Content-Security-Policy on the WebView; remote URLs open in the system browser, not the app WebView.
  • Filesystem access scoping: the app may read/write only (a) its app-scoped library directory and (b) user-chosen import/export paths granted through native file dialogs. No ambient access to $HOME. Import reads are sandboxed; export writes are confined to the chosen destination.
  • Secrets: tokens in OS secure storage; update + package signing keys never ship in the app; no SERVICE_ROLE-class keys ever on the client (server-only, per canon backend).
  • Network: TLS only; backend calls are authenticated; downloaded CPF bundles are integrity-checked (hashes per CPF contract) before they enter the library.

9. Accessibility, i18n, performance, packaging

Section titled “9. Accessibility, i18n, performance, packaging”
  • Accessibility: full keyboard navigation; screen-reader labels driven by per-panel alt-text from the CPF; dyslexia-friendly reading mode; honors OS reduced-motion (guided view pans respect it); high-contrast theme; resizable type in chrome.
  • i18n: UI localized; content locale switching per CPF locale metadata; RTL layout support for reading and chrome.
  • Performance (large libraries): virtualized library grid; lazy thumbnail/tile loading; SQLite-indexed local search; tiled high-res rendering with prefetch of the next page; target smooth scroll/guided-view at 60fps on a mid-range laptop with a 1,000+ issue library; bounded memory via tile eviction (§4).
  • Packaging/distribution: signed installers per platform (§2); auto-update via signed R2/CDN manifest; primary distribution is direct download from the OPEN PANEL site, with store/managed channels (Mac App Store, MS Store, Flathub) as best-effort later.

10. Acceptance criteria

Section titled “10. Acceptance criteria”

MVP — READER MODE (phase 1)

Section titled “MVP — READER MODE (phase 1)”
  • Signed, auto-updating installers build for macOS, Windows, Linux.
  • Sign in with one OPEN PANEL identity; tokens stored in OS secure storage.
  • Acquire a STANDARD ISSUE from the catalog; it downloads as CPF into the local library.
  • Read offline in both page view and guided view via @openpanel/reader, high-resolution on a large display.
  • Library browse/organize/search works fully offline.
  • Reading progress + bookmarks sync with the account and resume across surfaces.
  • VARIANT EDITION reads via entitlement check (no hard DRM); offline grace honored.
  • Capability allowlist + scoped FS access verified; no ambient $HOME access.

Phase 2 — STUDIO MODE

Section titled “Phase 2 — STUDIO MODE”
  • Create a project, import & order pages, define panels and a guided-view path.
  • Author per-panel alt-text + issue metadata + rating; live preview in the real reader.
  • Export a CPF that passes the canon §6.1 validator; invalid packages cannot export.
  • Submit to the backend review queue and track status / reviewer comments end-to-end.

Phase 3+ — back-office (optional, role-gated)

Section titled “Phase 3+ — back-office (optional, role-gated)”
  • LEDGER views, licensing deal entry, and analytics render for authorized roles only, and are invisible to readers.