@absolutejs/absolute 0.20.0-beta.5 → 0.20.0-beta.50

package/README.md

@@ -105,6 +105,211 @@ export const server = new Elysia()
 2. Route handlers (`handleReactPageRequest`, `handleSveltePageRequest`, …) stream HTML and inject scripts/assets based on that manifest.
 3. The static plugin serves all compiled files from `/build`.
 
+### Installable PWA and offline Sync
+
+Enable the web-app shell once in `absolutejs.config.ts`. AbsoluteJS generates a
+single shared browser bootstrap, service worker, and optional manifest, then
+wires them into React, Vue, Svelte, Angular, HTML, HTMX, and island client
+entries. Route and page code does not change.
+
+```ts
+import { defineConfig } from '@absolutejs/absolute';
+
+export default defineConfig({
+	// Existing framework directories and build settings...
+	pwa: {
+		manifest: {
+			name: 'Acme',
+			shortName: 'Acme',
+			themeColor: '#111827',
+			icons: [
+				{
+					src: '/icons/app-512.png',
+					sizes: '512x512',
+					type: 'image/png'
+				}
+			]
+		},
+		serviceWorker: {
+			offline: {
+				fallback: '/offline.html',
+				assetPrefix: '/assets/'
+			}
+		},
+		// With @absolutejs/auth + syncSocket(), this provisions the existing
+		// HTTP-only web session and durable IndexedDB transport automatically.
+		sync: true,
+		// Optional: importing pushNotifications enables this automatically.
+		// The public key defaults to VAPID_PUBLIC_KEY at build time.
+		push: true
+	}
+});
+```
+
+The default outputs are `/sw.js`, `/manifest.webmanifest`, and the internal
+shared bootstrap at `/__absolute/pwa/bootstrap.js`. Put referenced icons and the
+offline fallback in `publicDirectory`. The worker uses Background Sync when the
+browser offers it, while online/focus/visibility resume remains the correctness
+path. Native Capacitor clients continue to use their Bearer and SQLite
+transport; no web cookie or token is copied into the worker.
+
+Portable push uses the same `pushNotifications` API in the browser and a
+Capacitor shell. AbsoluteJS generates Web Push registration and subscription
+rotation against the same-origin `/auth/push` route. Configure the trusted
+server once with `auth({ push: { registrar, tenant, topics } })`; Auth derives
+identity, tenant, and authorized topics, while page code never receives APNs,
+FCM, or Web Push credentials. Only the public VAPID key enters browser output;
+keep `VAPID_PRIVATE_KEY` in the server-side Dispatch sender.
+
+`@absolutejs/pwa/client` also exposes `onPwaSyncResult()` and
+`getLastPwaSyncResult()` (plus the `absolute:pwa-sync-result` DOM event) for
+application-owned diagnostics. Results contain only success, duration, trigger,
+and aggregate counts—never credentials, namespaces, endpoints, arguments, or
+rows. Account changes are re-resolved before focus/online/visible Sync and the
+old worker run is aborted and cleared before the new namespace can run.
+
+AbsoluteJS also generates one local-storage migration bundle for web and native
+from the app plus installed Sync packs. Routes stay unchanged. A package that
+owns persisted data declares its JSON-safe evolution in `package.json`:
+
+```json
+{
+	"absolutejs": {
+		"sync": {
+			"localSchema": {
+				"version": 2,
+				"migrations": [
+					{
+						"toVersion": 2,
+						"operations": [
+							{
+								"type": "set-default",
+								"collection": "tasks",
+								"field": "completed",
+								"value": false
+							}
+						]
+					}
+				]
+			}
+		}
+	}
+}
+```
+
+Absolute derives stable component IDs from package names, keeps independent
+version ledgers, validates migration gaps during build/doctor, and applies the
+same transaction atomically in IndexedDB or Capacitor SQLite before Sync starts.
+The same `localSchema` object can declare `localData` rules for sensitivity,
+encryption, memory-only fallback, whole-cache retention, eviction priority, and
+per-principal quota. Absolute mobile stores record payloads as AES-256-GCM
+ciphertext using a random key held by Keychain/Keystore; native background Sync
+uses the identical authenticated format. Browsers without an audited key
+provider either keep a declared fallback in memory only or fail closed. Pending
+mutations are never evicted to satisfy quota.
+
+App updates are consent-driven: `onUpdateAvailable()` latches a waiting worker
+for late UI subscribers, `checkForUpdate()` performs a passive check, and
+`applyUpdate()` activates and reloads only after the user accepts. AbsoluteJS
+does not silently replace a running application session.
+
+### Native device capabilities
+
+Application code uses one provider-neutral API in web pages and Capacitor apps:
+
+```ts
+import {
+	camera,
+	clipboard,
+	haptics,
+	keyboard,
+	photos,
+	share,
+	systemBars
+} from '@absolutejs/devices';
+
+await clipboard.writeText('Copied everywhere');
+await share.share({ text: 'Shared everywhere', url: 'https://absolutejs.com' });
+await haptics.impact('light');
+const removeKeyboard = await keyboard.onChange(({ visible, heightPx }) => {
+	document.documentElement.style.setProperty(
+		'--keyboard-height',
+		visible ? `${heightPx}px` : '0px'
+	);
+});
+await systemBars.setAppearance('light', 'status');
+const permission = await camera.requestPermission();
+if (permission.state === 'granted') {
+	const capture = await camera.takePhoto();
+	image.src = capture.webPath;
+}
+const chosen = await photos.pick({ limit: 1 });
+```
+
+`absolute mobile init` and `absolute mobile sync` discover these named value
+imports, read the tested mappings published by `@absolutejs/devices-capacitor`,
+and offer to install only the exact Capacitor plugins in use. The generated
+shell wires them into the shared device facade; users do not import Capacitor,
+edit Swift/Kotlin, or maintain native bootstrap code. Type-only imports and test
+sources do not provision plugins. `absolute mobile doctor release` rejects a
+missing or mismatched plugin before release.
+
+Run `absolute mobile inspect` from an application root for a read-only summary
+of the effective mobile config, runtime package versions, discovered
+capabilities/plugins, native-project state, embedded routes/frameworks, bundle
+validation, and release projection. Add `--json` for a redacted CI or support
+artifact; it omits credentials, device/account identifiers, absolute paths, and
+detailed doctor messages. See [mobile project inspection](docs/MOBILE_INSPECT.md).
+
+Before signing, run `absolute mobile doctor release`. It validates pinned and
+aligned Capacitor packages, dependency locking, HTTPS and signed-link identity,
+packaged app identity, SHA-256 page/style integrity, runtime compatibility, CSP,
+native deep-link projections, privacy/permission projections, debug residue,
+and Sync/device policy. Its `--json` output is a redacted format-versioned CI
+artifact containing public app facts, check IDs/statuses, totals, and explicit
+manual-review categories—never local paths or detailed failure text. See the
+[Capacitor mobile threat model](docs/MOBILE_SECURITY_THREAT_MODEL.md).
+
+Generate protected GitHub Actions for cryptographic pull-request validation,
+signed AAB/IPA builds, and optional Google Play/TestFlight publication:
+
+```sh
+bunx absolute mobile ci github server.ts --publish
+```
+
+The generated workflow keeps signing and provider credentials behind the
+`absolute-mobile-release` GitHub environment. See
+[mobile CI and store releases](docs/MOBILE_CI.md).
+
+An experimental Expo Router hybrid is also available behind
+`mobile.engine: 'expo'`. Explicit React Native routes use native UI while every
+unclaimed AbsoluteJS route remains an embedded, signed web route regardless of
+framework. Capacitor is still the default; Expo Android now supports audited,
+signed production AABs, generated CI, and Google Play publishing while Expo iOS
+release automation remains experimental. See the
+[Expo hybrid experiment](docs/MOBILE_EXPO_EXPERIMENT.md).
+For Expo development, `bun dev` now owns the Bun server, Metro development
+client, configured emulator/simulator builds, categorized logs, and both native
+Fast Refresh and framework-aware AbsoluteJS HMR from the application root.
+
+`keyboard` provides portable visibility, CSS-pixel height, dismissal, and
+cleanup-safe change events. `systemBars` controls modern edge-to-edge status and
+navigation bar foreground appearance/visibility through Capacitor 8 core. Its
+`light` and `dark` values name the icon/text foreground. Web appearance uses
+best-effort `color-scheme`; browser chrome visibility reports unsupported.
+
+Camera capture requires an explicit `camera.requestPermission()` call from an
+intentional user action. `photos.pick()` uses the item-scoped system picker
+without requesting broad library access. AbsoluteJS generates the required iOS
+usage descriptions from the same audited capability metadata; this first slice
+does not expose EXIF metadata or save captures into the gallery, and Android does
+not receive unnecessary camera/storage permissions.
+
+Clipboard and Share use browser standards on the web and fail with normalized
+errors when unavailable. Haptics uses vibration where supported and otherwise
+safely becomes a no-op, because tactile feedback must never be required to
+complete an action.
+
 ### Immutable production images
 
 Build production assets and the server bundle while constructing the image,