qualia_cooperative_core/qapp_package/mod.rs
1//! Companion-qapp packaging: define a qapp, and generate an installable PWA scaffold for it.
2//!
3//! This is the transport-neutral **foundation** for the companion PWA feature — the means by which
4//! a person defines a qapp (a cooperative front, a health tracker, a journal, a directory, …) and
5//! obtains an installable, wasm-backed web app for their phone. It has two halves:
6//!
7//! - [`manifest`] — [`QappManifest`], the definition of a qapp: identity, semver, the extensible
8//! [`QappKind`], the **least-privilege** [`Capability`] scopes it requests, a content-addressed
9//! [`WasmRef`] to its wasm bundle, and PWA presentation metadata (icons, colours, display mode).
10//! - [`pwa`] — [`generate_pwa`], which turns a manifest into a [`PwaBundle`]: a
11//! `manifest.webmanifest` (W3C Web App Manifest), a cache-first `sw.js` service worker for
12//! offline capability, and an `index.html` loader that registers the service worker and
13//! instantiates the qapp's wasm.
14//!
15//! ## Honest scope — what this module does and does NOT do
16//!
17//! It **does**:
18//! - define a qapp in a transport-neutral way ([`QappManifest`]); and
19//! - generate a **correct, standards-compliant, installable-in-principle** PWA scaffold
20//! ([`generate_pwa`]) — valid Web App Manifest, a working cache-first service worker, and a
21//! loader page with the iOS/Android install meta tags.
22//!
23//! It **does NOT**:
24//! - **serve** anything. Browsers only offer to *install* a PWA when it is delivered from a
25//! **secure origin** (HTTPS, or `localhost` in development) with the manifest and service worker
26//! reachable under scope. That secure-origin delivery/pairing layer is a **separate, later
27//! piece** — this module produces the bytes, not the transport. A scaffold opened from a `file://`
28//! URL or a plain-HTTP origin will not register a service worker and will not be installable; that
29//! is a property of the delivery environment, not a defect here.
30//! - **compile wasm.** The wasm bundle is referenced by path + SHA-256 hash + size
31//! ([`WasmRef`]); building that bundle is out of scope for this module.
32//!
33//! Nothing here is a stub: the manifest model, validation, and PWA generation are fully
34//! implemented and tested. The two "does NOT" items above are genuine adjacent layers, not
35//! deferred work inside this module.
36
37pub mod manifest;
38pub mod pwa;
39pub mod remote_controller;
40
41pub use manifest::{Capability, IconRef, QappKind, QappManifest, WasmRef};
42pub use pwa::{generate_pwa, PwaBundle, PwaContent, PwaFile};
43pub use remote_controller::generate_remote_controller_pwa;