@noy-db/in-pwa 0.4.0-pre.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vLannaAi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+# @noy-db/in-pwa
+
+[![npm](https://img.shields.io/npm/v/%40noy-db/in-pwa.svg)](https://www.npmjs.com/package/@noy-db/in-pwa)
+
+> Installable/offline shell helpers for noy-db SPAs
+
+Part of [**`@noy-db/hub`**](https://www.npmjs.com/package/@noy-db/hub) — the zero-knowledge, offline-first, encrypted document store.
+
+## Install
+
+```bash
+pnpm add @noy-db/hub @noy-db/in-pwa
+```
+
+## The premise: the PWA starts empty
+
+An installed PWA lives in **its own storage partition**. On first open it holds no
+data: the app runs the online enrollment (unlock + re-invite via
+[`@noy-db/on-oidc`](https://github.com/vLannaAi/noy-db/tree/main/packages/on-oidc))
+and hydrates the vault from the firm cloud store into
+[`@noy-db/to-browser-idb`](https://github.com/vLannaAi/noy-db/tree/main/packages/to-browser-idb).
+From then on the installed app is the **offline-capable home of the vault**:
+offline boot = cached app shell (service worker) + local IndexedDB vault.
+
+This package is the browser-shell plumbing around that lifecycle. It holds **no
+keys** and sees **no plaintext** — every helper here operates on browser shell
+APIs or on opaque ciphertext-store presence, so it adds nothing to the threat
+model.
+
+## Persistence & eviction
+
+Eviction of the local vault is the top PWA risk. iOS ITP evicts all
+script-writable storage (IndexedDB included) of **non-installed** web content
+after ~7 days without interaction; installed home-screen apps are safer, and
+`navigator.storage.persist()` exempts an origin from best-effort eviction where
+granted. Two helpers cover the risk:
+
+### `requestPersistence()`
+
+```ts
+import { requestPersistence } from '@noy-db/in-pwa'
+
+const res = await requestPersistence()
+// { persisted: boolean, quota?: number, usage?: number,
+//   grantedBy: 'already' | 'granted' | 'denied' | 'unsupported' }
+```
+
+Wraps `navigator.storage.persist()` + `estimate()` with a clear grant/deny
+signal. **Never throws** — browsers without the Storage API resolve to
+`grantedBy: 'unsupported'`. Call it during enrollment; warn the user on
+`'denied'`.
+
+### `guardLocalVault()` — fail closed at boot
+
+If the partition *was* evicted, the app must never crash and never present a
+silent empty vault as truth. The guard probes the local store before the vault
+is opened and routes a missing vault into re-enrollment:
+
+```ts
+import { guardLocalVault } from '@noy-db/in-pwa'
+import { browserIdb } from '@noy-db/to-browser-idb'
+
+const store = browserIdb()
+const { healthy } = await guardLocalVault(store, 'firm', (why) => {
+  // why: { present: false, reason: 'empty' | 'probe-failed', cause? }
+  routeToReEnrollment()
+})
+if (healthy) {
+  /* open the vault normally */
+}
+```
+
+The probe (`probeLocalVault(store, vaultId)`) is **store-agnostic** — it speaks
+only the 6-method `NoydbStore` contract (`@noy-db/hub/to`), never
+`to-browser-idb` internals. It checks the vault's `_keyring` marker records
+first (every encrypted vault persists its owner keyring at creation — the same
+signal the hub uses for "vault provisioned"), then falls back to a `loadAll()`
+envelope scan for plaintext-mode vaults. A **broken store is treated exactly
+like a missing vault**: probe errors resolve to
+`{ present: false, reason: 'probe-failed' }` and trigger `onEvicted` — fail
+closed, never a throw from the probe path.
+
+## Install UX
+
+```ts
+import { captureInstallPrompt, getDisplayContext, isIosSafari } from '@noy-db/in-pwa'
+
+// Android/desktop Chromium: defer the browser prompt, re-fire it from your UI.
+const install = captureInstallPrompt() // call once at boot
+// later, on a user gesture:
+const outcome = await install.promptInstall() // 'accepted' | 'dismissed' | 'unavailable'
+
+getDisplayContext() // 'pwa' (standalone display-mode / iOS navigator.standalone) | 'browser'
+isIosSafari()       // true → show the "Add to Home Screen" share-sheet interstitial
+                    // (iOS never fires beforeinstallprompt)
+```
+
+The shared shell-context contract with `@noy-db/in-liff` is exported here as a
+plain string union (no runtime coupling):
+
+```ts
+export type AppShellContext = 'liff' | 'browser' | 'pwa'
+```
+
+## Online/offline transitions
+
+```ts
+import { watchOnline } from '@noy-db/in-pwa'
+
+const stop = watchOnline((online) => syncStrategy.setOnline(online))
+```
+
+Invokes the callback immediately with `navigator.onLine`, then on every
+`online`/`offline` event — shaped for feeding the sync engine's `isOnline`
+flag (reconnect replay of the dirty queue lives in `with-sync`; this package
+does not import it).
+
+## Service-worker recipe (copy, don't import)
+
+This package ships **no service-worker runtime** — the SW below is a recipe you
+copy into your app and version yourself.
+
+> **Hard rule: vault data NEVER goes in the SW cache.** The vault lives
+> encrypted in `to-browser-idb`; the service worker caches the **app shell
+> only** (HTML/JS/CSS/icons). A SW cache of vault responses would create a
+> second, unmanaged copy of ciphertext outside the store contract — and a
+> plaintext copy if you cached decrypted API responses. Don't.
+
+```js
+// sw.js — app-shell caching only. Bump SHELL_CACHE on every deploy.
+const SHELL_CACHE = 'app-shell-v1'
+const SHELL_ASSETS = ['/', '/index.html', '/assets/app.js', '/assets/app.css', '/icons/192.png']
+
+self.addEventListener('install', (event) => {
+  event.waitUntil(caches.open(SHELL_CACHE).then((cache) => cache.addAll(SHELL_ASSETS)))
+  self.skipWaiting()
+})
+
+self.addEventListener('activate', (event) => {
+  // Drop caches from previous shell versions.
+  event.waitUntil(
+    caches
+      .keys()
+      .then((keys) => Promise.all(keys.filter((k) => k !== SHELL_CACHE).map((k) => caches.delete(k))))
+      .then(() => self.clients.claim()),
+  )
+})
+
+self.addEventListener('fetch', (event) => {
+  const url = new URL(event.request.url)
+  // App shell only: same-origin GET navigations and static assets.
+  // Everything else (sync traffic, APIs) passes straight to the network —
+  // vault data is never cached here.
+  if (event.request.method !== 'GET' || url.origin !== self.location.origin) return
+  event.respondWith(
+    caches.match(event.request).then((hit) => hit ?? fetch(event.request)),
+  )
+})
+```
+
+Offline boot then composes as: SW serves the cached shell → `guardLocalVault()`
+confirms the local vault is present → the app opens it from `to-browser-idb`
+with no network at all.
+
+## Detaching from LINE / re-enrollment
+
+Storage partitions are never transferable: LINE's WebView, the browser tab, and
+the installed PWA each have isolated storage, so moving the vault into the
+installed app is a **re-enroll + re-sync ceremony, never a data transfer** — the
+firm re-invites the device via the
+[`@noy-db/on-oidc`](https://github.com/vLannaAi/noy-db/tree/main/packages/on-oidc)
+unlock flow and the fresh partition hydrates from the firm cloud store, exactly
+like first enrollment. `guardLocalVault()`'s `onEvicted` hook is where that
+ceremony is (re-)entered.
+
+## Status
+
+**Pre-release** (`0.4.0-pre.1`). API may change before `1.0`.
+
+## Documentation
+
+See the [main repository](https://github.com/vLannaAi/noy-db#readme) for setup, examples, and the full subsystem catalog.
+
+- Source — [`packages/in-pwa`](https://github.com/vLannaAi/noy-db/tree/main/packages/in-pwa)
+- Issues — [github.com/vLannaAi/noy-db/issues](https://github.com/vLannaAi/noy-db/issues)
+- Spec — [`SPEC.md`](https://github.com/vLannaAi/noy-db-docs/blob/main/SPEC.md)
+
+## License
+
+[MIT](./LICENSE) © vLannaAi

package/dist/index.d.ts

@@ -0,0 +1,186 @@
+import { NoydbStore } from '@noy-db/hub';
+
+/**
+ * **@noy-db/in-pwa** — installable/offline shell helpers for noy-db SPAs.
+ *
+ * The premise: **the PWA starts empty.** First open in its own storage
+ * partition runs online enrollment and hydrates from the firm cloud
+ * store; from then on the installed app is the offline-capable home of
+ * the vault (data in `to-browser-idb`, app shell in the SW cache — see
+ * the README recipe). This package ships the browser-shell plumbing
+ * around that lifecycle:
+ *
+ * - {@link requestPersistence} — `navigator.storage.persist()` +
+ *   `estimate()` with a clear grant/deny signal. Never throws.
+ * - {@link guardLocalVault} / {@link probeLocalVault} — detect a
+ *   wiped/missing local store at boot and **fail closed** into the
+ *   re-enrollment flow. Never a crash, never a silent empty vault
+ *   presented as truth.
+ * - {@link captureInstallPrompt}, {@link getDisplayContext},
+ *   {@link isIosSafari} — install UX helpers.
+ * - {@link watchOnline} — online/offline wiring shaped for the sync
+ *   engine's `isOnline` flag.
+ *
+ * No service worker runtime is shipped — the SW is a copy-able recipe
+ * in the README. This package holds no keys and sees no plaintext.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * The three shells one noy-db SPA can boot in. Shared contract with
+ * `@noy-db/in-liff` (which detects `'liff'`); this package's
+ * {@link getDisplayContext} distinguishes the other two. A plain string
+ * union — no runtime coupling between the packages.
+ */
+type AppShellContext = 'liff' | 'browser' | 'pwa';
+/** Result of {@link requestPersistence}. */
+interface PersistenceResult {
+    /** True when the origin's storage is durable (not eviction-eligible). */
+    persisted: boolean;
+    /** `navigator.storage.estimate().quota`, when the browser reports it. */
+    quota?: number;
+    /** `navigator.storage.estimate().usage`, when the browser reports it. */
+    usage?: number;
+    /**
+     * How the answer was reached:
+     * - `'already'` — the origin was persistent before this call.
+     * - `'granted'` — `persist()` was requested and the browser granted it.
+     * - `'denied'` — `persist()` was requested and the browser declined.
+     * - `'unsupported'` — no Storage API on this browser (or it errored).
+     */
+    grantedBy: 'already' | 'granted' | 'denied' | 'unsupported';
+}
+/**
+ * Ask the browser to mark this origin's storage as persistent and report
+ * quota/usage. Eviction of the local vault is the top PWA risk (iOS ITP
+ * evicts script-writable storage of non-installed web content after ~7
+ * days of disuse; installed home-screen apps are safer) — call this
+ * during enrollment and surface a warning UI on `'denied'`.
+ *
+ * Never throws: unsupported browsers resolve to
+ * `{ persisted: false, grantedBy: 'unsupported' }`.
+ */
+declare function requestPersistence(): Promise<PersistenceResult>;
+/** Outcome of {@link probeLocalVault}. */
+type VaultPresence = {
+    present: true;
+    /**
+     * What proved presence: `'keyring'` — the vault's `_keyring`
+     * marker records exist (every encrypted vault persists one at
+     * creation); `'envelopes'` — no keyring (plaintext-mode vault)
+     * but `loadAll()` returned at least one envelope.
+     */
+    via: 'keyring' | 'envelopes';
+} | {
+    present: false;
+    /**
+     * `'empty'` — the store answered and holds nothing for this
+     * vault (wiped/evicted/never enrolled); `'probe-failed'` — the
+     * store itself errored. Both fail closed.
+     */
+    reason: 'empty' | 'probe-failed';
+    /** The underlying error when `reason` is `'probe-failed'`. */
+    cause?: unknown;
+};
+/**
+ * Cheap, store-agnostic probe: is a local vault actually present in
+ * `store`? Works against any `NoydbStore` (the 6-method contract from
+ * `@noy-db/hub/to`) — it never touches `to-browser-idb` internals.
+ *
+ * Presence check, in order:
+ * 1. `store.list(vaultId, '_keyring')` — an encrypted vault always
+ *    persists its owner keyring record at creation, so a non-empty
+ *    `_keyring` collection is the same marker the hub itself uses to
+ *    decide a vault is provisioned. One tiny `list()` call.
+ * 2. Fallback for plaintext-mode vaults (no keyring): `loadAll()` —
+ *    any envelope in any collection counts as present.
+ *
+ * Never throws — a store error resolves to
+ * `{ present: false, reason: 'probe-failed', cause }`.
+ */
+declare function probeLocalVault(store: NoydbStore, vaultId: string): Promise<VaultPresence>;
+/** Result of {@link guardLocalVault}. */
+interface GuardResult {
+    /** True iff the local vault is present. Never true on a failed probe. */
+    healthy: boolean;
+    /** The underlying probe outcome. */
+    presence: VaultPresence;
+}
+/**
+ * Boot-time eviction guard: probe the local store and **fail closed**
+ * into re-enrollment when the vault is gone.
+ *
+ * - Vault present → `{ healthy: true }`; `onEvicted` is not called.
+ * - Vault missing (wiped/evicted partition) **or the probe itself
+ *   failed** → `onEvicted` is invoked (and awaited) with the failure
+ *   detail, then `{ healthy: false }` is returned. A broken store is
+ *   treated exactly like a missing vault — the guard never presents an
+ *   empty or unreadable store as a healthy vault, and never throws
+ *   from the probe path.
+ *
+ * `onEvicted` is where the app routes to its re-enrollment flow (the
+ * online re-invite via `@noy-db/on-oidc`); errors thrown by the handler
+ * itself propagate to the caller.
+ */
+declare function guardLocalVault(store: NoydbStore, vaultId: string, onEvicted: (presence: Extract<VaultPresence, {
+    present: false;
+}>) => void | Promise<void>): Promise<GuardResult>;
+/** Handle returned by {@link captureInstallPrompt}. */
+interface CapturedInstallPrompt {
+    /** True once a `beforeinstallprompt` event has been captured (and not yet spent). */
+    readonly captured: boolean;
+    /**
+     * Re-fire the deferred browser install prompt. Resolves to the user's
+     * choice, or `'unavailable'` when no event was captured (iOS, already
+     * installed, or the prompt was already spent — the browser fires it
+     * at most once per capture).
+     */
+    promptInstall(): Promise<'accepted' | 'dismissed' | 'unavailable'>;
+    /** Remove the event listener and drop any captured prompt. */
+    dispose(): void;
+}
+/**
+ * Capture the `beforeinstallprompt` event (Android/desktop Chromium) so
+ * the app can show its own install UI and re-fire the prompt on a user
+ * gesture. Call once at boot, before the browser fires the event.
+ *
+ * On browsers that never fire the event (iOS Safari — see
+ * {@link isIosSafari} for the add-to-home-screen interstitial decision)
+ * `promptInstall()` simply resolves `'unavailable'`.
+ */
+declare function captureInstallPrompt(target?: EventTarget): CapturedInstallPrompt;
+/**
+ * Which shell the app is currently displayed in: `'pwa'` when running
+ * standalone (installed — `display-mode: standalone` media query, or
+ * iOS `navigator.standalone`), else `'browser'`. The `'liff'` value of
+ * {@link AppShellContext} is detected by `@noy-db/in-liff`, not here.
+ */
+declare function getDisplayContext(): Extract<AppShellContext, 'pwa' | 'browser'>;
+/**
+ * True on iOS Safari (including iPadOS masquerading as macOS), where
+ * `beforeinstallprompt` never fires and installing means the share-sheet
+ * "Add to Home Screen" flow — the signal for showing that interstitial.
+ * Third-party iOS browsers (Chrome/Firefox/Edge/Opera shells) return
+ * false.
+ */
+declare function isIosSafari(): boolean;
+/**
+ * Watch connectivity: invokes `callback` immediately with the current
+ * `navigator.onLine` state, then on every `online`/`offline` event.
+ * Returns an unsubscribe function.
+ *
+ * Shaped for feeding the sync engine's `isOnline` flag (this package
+ * deliberately does not import the sync engine):
+ *
+ * ```ts
+ * const stop = watchOnline((online) => syncStrategy.setOnline(online))
+ * ```
+ *
+ * In hosts without a `window`/events (or without `navigator.onLine`)
+ * the callback fires once with `true` (assume online) and the returned
+ * unsubscribe is a no-op.
+ */
+declare function watchOnline(callback: (online: boolean) => void, target?: EventTarget): () => void;
+
+export { type AppShellContext, type CapturedInstallPrompt, type GuardResult, type PersistenceResult, type VaultPresence, captureInstallPrompt, getDisplayContext, guardLocalVault, isIosSafari, probeLocalVault, requestPersistence, watchOnline };

package/dist/index.js

@@ -0,0 +1,122 @@
+// src/index.ts
+async function requestPersistence() {
+  const storage = globalThis.navigator?.storage;
+  if (!storage || typeof storage.persist !== "function") {
+    return { persisted: false, grantedBy: "unsupported" };
+  }
+  let persisted = false;
+  let grantedBy;
+  try {
+    const already = typeof storage.persisted === "function" ? await storage.persisted() : false;
+    if (already) {
+      persisted = true;
+      grantedBy = "already";
+    } else {
+      persisted = await storage.persist();
+      grantedBy = persisted ? "granted" : "denied";
+    }
+  } catch {
+    return { persisted: false, grantedBy: "unsupported" };
+  }
+  const result = { persisted, grantedBy };
+  if (typeof storage.estimate === "function") {
+    try {
+      const est = await storage.estimate();
+      if (typeof est.quota === "number") result.quota = est.quota;
+      if (typeof est.usage === "number") result.usage = est.usage;
+    } catch {
+    }
+  }
+  return result;
+}
+async function probeLocalVault(store, vaultId) {
+  try {
+    const keyringIds = await store.list(vaultId, "_keyring");
+    if (keyringIds.length > 0) return { present: true, via: "keyring" };
+    const snapshot = await store.loadAll(vaultId);
+    for (const records of Object.values(snapshot)) {
+      if (records && Object.keys(records).length > 0) {
+        return { present: true, via: "envelopes" };
+      }
+    }
+    return { present: false, reason: "empty" };
+  } catch (cause) {
+    return { present: false, reason: "probe-failed", cause };
+  }
+}
+async function guardLocalVault(store, vaultId, onEvicted) {
+  const presence = await probeLocalVault(store, vaultId);
+  if (presence.present) return { healthy: true, presence };
+  await onEvicted(presence);
+  return { healthy: false, presence };
+}
+function captureInstallPrompt(target) {
+  const t = target ?? globalThis.window;
+  let deferred = null;
+  const listener = (event) => {
+    event.preventDefault();
+    deferred = event;
+  };
+  t?.addEventListener("beforeinstallprompt", listener);
+  return {
+    get captured() {
+      return deferred !== null;
+    },
+    async promptInstall() {
+      const event = deferred;
+      if (!event || typeof event.prompt !== "function") return "unavailable";
+      deferred = null;
+      await event.prompt();
+      const choice = await event.userChoice;
+      return choice.outcome;
+    },
+    dispose() {
+      t?.removeEventListener("beforeinstallprompt", listener);
+      deferred = null;
+    }
+  };
+}
+function getDisplayContext() {
+  const g = globalThis;
+  try {
+    if (typeof g.matchMedia === "function" && g.matchMedia("(display-mode: standalone)").matches) {
+      return "pwa";
+    }
+  } catch {
+  }
+  if (g.navigator?.standalone === true) return "pwa";
+  return "browser";
+}
+function isIosSafari() {
+  const nav = globalThis.navigator;
+  if (!nav) return false;
+  const ua = nav.userAgent ?? "";
+  const iosDevice = /iPad|iPhone|iPod/.test(ua) || nav.platform === "MacIntel" && (nav.maxTouchPoints ?? 0) > 1;
+  if (!iosDevice) return false;
+  return /Safari/.test(ua) && !/CriOS|FxiOS|EdgiOS|OPiOS|OPT\//.test(ua);
+}
+function watchOnline(callback, target) {
+  const g = globalThis;
+  const t = target ?? g.window;
+  callback(g.navigator?.onLine ?? true);
+  if (!t || typeof t.addEventListener !== "function") return () => {
+  };
+  const onOnline = () => callback(true);
+  const onOffline = () => callback(false);
+  t.addEventListener("online", onOnline);
+  t.addEventListener("offline", onOffline);
+  return () => {
+    t.removeEventListener("online", onOnline);
+    t.removeEventListener("offline", onOffline);
+  };
+}
+export {
+  captureInstallPrompt,
+  getDisplayContext,
+  guardLocalVault,
+  isIosSafari,
+  probeLocalVault,
+  requestPersistence,
+  watchOnline
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * **@noy-db/in-pwa** — installable/offline shell helpers for noy-db SPAs.\n *\n * The premise: **the PWA starts empty.** First open in its own storage\n * partition runs online enrollment and hydrates from the firm cloud\n * store; from then on the installed app is the offline-capable home of\n * the vault (data in `to-browser-idb`, app shell in the SW cache — see\n * the README recipe). This package ships the browser-shell plumbing\n * around that lifecycle:\n *\n * - {@link requestPersistence} — `navigator.storage.persist()` +\n *   `estimate()` with a clear grant/deny signal. Never throws.\n * - {@link guardLocalVault} / {@link probeLocalVault} — detect a\n *   wiped/missing local store at boot and **fail closed** into the\n *   re-enrollment flow. Never a crash, never a silent empty vault\n *   presented as truth.\n * - {@link captureInstallPrompt}, {@link getDisplayContext},\n *   {@link isIosSafari} — install UX helpers.\n * - {@link watchOnline} — online/offline wiring shaped for the sync\n *   engine's `isOnline` flag.\n *\n * No service worker runtime is shipped — the SW is a copy-able recipe\n * in the README. This package holds no keys and sees no plaintext.\n *\n * @packageDocumentation\n */\n\nimport type { NoydbStore } from '@noy-db/hub'\n\n// ---------------------------------------------------------------------------\n// Shared app-shell context contract (also consumed/mirrored by @noy-db/in-liff)\n// ---------------------------------------------------------------------------\n\n/**\n * The three shells one noy-db SPA can boot in. Shared contract with\n * `@noy-db/in-liff` (which detects `'liff'`); this package's\n * {@link getDisplayContext} distinguishes the other two. A plain string\n * union — no runtime coupling between the packages.\n */\nexport type AppShellContext = 'liff' | 'browser' | 'pwa'\n\n// ---------------------------------------------------------------------------\n// Storage persistence\n// ---------------------------------------------------------------------------\n\n/** Result of {@link requestPersistence}. */\nexport interface PersistenceResult {\n  /** True when the origin's storage is durable (not eviction-eligible). */\n  persisted: boolean\n  /** `navigator.storage.estimate().quota`, when the browser reports it. */\n  quota?: number\n  /** `navigator.storage.estimate().usage`, when the browser reports it. */\n  usage?: number\n  /**\n   * How the answer was reached:\n   * - `'already'` — the origin was persistent before this call.\n   * - `'granted'` — `persist()` was requested and the browser granted it.\n   * - `'denied'` — `persist()` was requested and the browser declined.\n   * - `'unsupported'` — no Storage API on this browser (or it errored).\n   */\n  grantedBy: 'already' | 'granted' | 'denied' | 'unsupported'\n}\n\n/**\n * Ask the browser to mark this origin's storage as persistent and report\n * quota/usage. Eviction of the local vault is the top PWA risk (iOS ITP\n * evicts script-writable storage of non-installed web content after ~7\n * days of disuse; installed home-screen apps are safer) — call this\n * during enrollment and surface a warning UI on `'denied'`.\n *\n * Never throws: unsupported browsers resolve to\n * `{ persisted: false, grantedBy: 'unsupported' }`.\n */\nexport async function requestPersistence(): Promise<PersistenceResult> {\n  const storage = (globalThis as { navigator?: { storage?: StorageManager } }).navigator?.storage\n  if (!storage || typeof storage.persist !== 'function') {\n    return { persisted: false, grantedBy: 'unsupported' }\n  }\n\n  let persisted = false\n  let grantedBy: PersistenceResult['grantedBy']\n  try {\n    const already = typeof storage.persisted === 'function' ? await storage.persisted() : false\n    if (already) {\n      persisted = true\n      grantedBy = 'already'\n    } else {\n      persisted = await storage.persist()\n      grantedBy = persisted ? 'granted' : 'denied'\n    }\n  } catch {\n    // A throwing Storage API is indistinguishable from an absent one\n    // for the caller's purposes — report unsupported, never throw.\n    return { persisted: false, grantedBy: 'unsupported' }\n  }\n\n  const result: PersistenceResult = { persisted, grantedBy }\n  if (typeof storage.estimate === 'function') {\n    try {\n      const est = await storage.estimate()\n      if (typeof est.quota === 'number') result.quota = est.quota\n      if (typeof est.usage === 'number') result.usage = est.usage\n    } catch {\n      // estimate() failing must not mask the persistence answer.\n    }\n  }\n  return result\n}\n\n// ---------------------------------------------------------------------------\n// Eviction guard\n// ---------------------------------------------------------------------------\n\n/** Outcome of {@link probeLocalVault}. */\nexport type VaultPresence =\n  | {\n      present: true\n      /**\n       * What proved presence: `'keyring'` — the vault's `_keyring`\n       * marker records exist (every encrypted vault persists one at\n       * creation); `'envelopes'` — no keyring (plaintext-mode vault)\n       * but `loadAll()` returned at least one envelope.\n       */\n      via: 'keyring' | 'envelopes'\n    }\n  | {\n      present: false\n      /**\n       * `'empty'` — the store answered and holds nothing for this\n       * vault (wiped/evicted/never enrolled); `'probe-failed'` — the\n       * store itself errored. Both fail closed.\n       */\n      reason: 'empty' | 'probe-failed'\n      /** The underlying error when `reason` is `'probe-failed'`. */\n      cause?: unknown\n    }\n\n/**\n * Cheap, store-agnostic probe: is a local vault actually present in\n * `store`? Works against any `NoydbStore` (the 6-method contract from\n * `@noy-db/hub/to`) — it never touches `to-browser-idb` internals.\n *\n * Presence check, in order:\n * 1. `store.list(vaultId, '_keyring')` — an encrypted vault always\n *    persists its owner keyring record at creation, so a non-empty\n *    `_keyring` collection is the same marker the hub itself uses to\n *    decide a vault is provisioned. One tiny `list()` call.\n * 2. Fallback for plaintext-mode vaults (no keyring): `loadAll()` —\n *    any envelope in any collection counts as present.\n *\n * Never throws — a store error resolves to\n * `{ present: false, reason: 'probe-failed', cause }`.\n */\nexport async function probeLocalVault(store: NoydbStore, vaultId: string): Promise<VaultPresence> {\n  try {\n    const keyringIds = await store.list(vaultId, '_keyring')\n    if (keyringIds.length > 0) return { present: true, via: 'keyring' }\n\n    const snapshot = await store.loadAll(vaultId)\n    for (const records of Object.values(snapshot)) {\n      if (records && Object.keys(records).length > 0) {\n        return { present: true, via: 'envelopes' }\n      }\n    }\n    return { present: false, reason: 'empty' }\n  } catch (cause) {\n    return { present: false, reason: 'probe-failed', cause }\n  }\n}\n\n/** Result of {@link guardLocalVault}. */\nexport interface GuardResult {\n  /** True iff the local vault is present. Never true on a failed probe. */\n  healthy: boolean\n  /** The underlying probe outcome. */\n  presence: VaultPresence\n}\n\n/**\n * Boot-time eviction guard: probe the local store and **fail closed**\n * into re-enrollment when the vault is gone.\n *\n * - Vault present → `{ healthy: true }`; `onEvicted` is not called.\n * - Vault missing (wiped/evicted partition) **or the probe itself\n *   failed** → `onEvicted` is invoked (and awaited) with the failure\n *   detail, then `{ healthy: false }` is returned. A broken store is\n *   treated exactly like a missing vault — the guard never presents an\n *   empty or unreadable store as a healthy vault, and never throws\n *   from the probe path.\n *\n * `onEvicted` is where the app routes to its re-enrollment flow (the\n * online re-invite via `@noy-db/on-oidc`); errors thrown by the handler\n * itself propagate to the caller.\n */\nexport async function guardLocalVault(\n  store: NoydbStore,\n  vaultId: string,\n  onEvicted: (presence: Extract<VaultPresence, { present: false }>) => void | Promise<void>,\n): Promise<GuardResult> {\n  const presence = await probeLocalVault(store, vaultId)\n  if (presence.present) return { healthy: true, presence }\n  await onEvicted(presence)\n  return { healthy: false, presence }\n}\n\n// ---------------------------------------------------------------------------\n// Install UX helpers\n// ---------------------------------------------------------------------------\n\n/**\n * The `beforeinstallprompt` event shape (Chromium-only, not in the DOM\n * lib types).\n */\ninterface BeforeInstallPromptLike extends Event {\n  prompt(): Promise<void>\n  userChoice: Promise<{ outcome: 'accepted' | 'dismissed' }>\n}\n\n/** Handle returned by {@link captureInstallPrompt}. */\nexport interface CapturedInstallPrompt {\n  /** True once a `beforeinstallprompt` event has been captured (and not yet spent). */\n  readonly captured: boolean\n  /**\n   * Re-fire the deferred browser install prompt. Resolves to the user's\n   * choice, or `'unavailable'` when no event was captured (iOS, already\n   * installed, or the prompt was already spent — the browser fires it\n   * at most once per capture).\n   */\n  promptInstall(): Promise<'accepted' | 'dismissed' | 'unavailable'>\n  /** Remove the event listener and drop any captured prompt. */\n  dispose(): void\n}\n\n/**\n * Capture the `beforeinstallprompt` event (Android/desktop Chromium) so\n * the app can show its own install UI and re-fire the prompt on a user\n * gesture. Call once at boot, before the browser fires the event.\n *\n * On browsers that never fire the event (iOS Safari — see\n * {@link isIosSafari} for the add-to-home-screen interstitial decision)\n * `promptInstall()` simply resolves `'unavailable'`.\n */\nexport function captureInstallPrompt(target?: EventTarget): CapturedInstallPrompt {\n  const t = target ?? (globalThis as { window?: EventTarget }).window\n  let deferred: BeforeInstallPromptLike | null = null\n\n  const listener = (event: Event): void => {\n    // Suppress the browser's own mini-infobar; the app re-fires the\n    // prompt from its install UI instead.\n    event.preventDefault()\n    deferred = event as BeforeInstallPromptLike\n  }\n  t?.addEventListener('beforeinstallprompt', listener)\n\n  return {\n    get captured() {\n      return deferred !== null\n    },\n    async promptInstall() {\n      const event = deferred\n      if (!event || typeof event.prompt !== 'function') return 'unavailable'\n      deferred = null // the deferred prompt is single-use\n      await event.prompt()\n      const choice = await event.userChoice\n      return choice.outcome\n    },\n    dispose() {\n      t?.removeEventListener('beforeinstallprompt', listener)\n      deferred = null\n    },\n  }\n}\n\n/**\n * Which shell the app is currently displayed in: `'pwa'` when running\n * standalone (installed — `display-mode: standalone` media query, or\n * iOS `navigator.standalone`), else `'browser'`. The `'liff'` value of\n * {@link AppShellContext} is detected by `@noy-db/in-liff`, not here.\n */\nexport function getDisplayContext(): Extract<AppShellContext, 'pwa' | 'browser'> {\n  const g = globalThis as {\n    matchMedia?: (query: string) => { matches: boolean }\n    navigator?: { standalone?: boolean }\n  }\n  try {\n    if (typeof g.matchMedia === 'function' && g.matchMedia('(display-mode: standalone)').matches) {\n      return 'pwa'\n    }\n  } catch {\n    // matchMedia throwing (non-browser host) means not standalone.\n  }\n  if (g.navigator?.standalone === true) return 'pwa'\n  return 'browser'\n}\n\n/**\n * True on iOS Safari (including iPadOS masquerading as macOS), where\n * `beforeinstallprompt` never fires and installing means the share-sheet\n * \"Add to Home Screen\" flow — the signal for showing that interstitial.\n * Third-party iOS browsers (Chrome/Firefox/Edge/Opera shells) return\n * false.\n */\nexport function isIosSafari(): boolean {\n  const nav = (globalThis as {\n    navigator?: { userAgent?: string; platform?: string; maxTouchPoints?: number }\n  }).navigator\n  if (!nav) return false\n  const ua = nav.userAgent ?? ''\n  const iosDevice =\n    /iPad|iPhone|iPod/.test(ua) || (nav.platform === 'MacIntel' && (nav.maxTouchPoints ?? 0) > 1)\n  if (!iosDevice) return false\n  return /Safari/.test(ua) && !/CriOS|FxiOS|EdgiOS|OPiOS|OPT\\//.test(ua)\n}\n\n// ---------------------------------------------------------------------------\n// Online/offline transitions\n// ---------------------------------------------------------------------------\n\n/**\n * Watch connectivity: invokes `callback` immediately with the current\n * `navigator.onLine` state, then on every `online`/`offline` event.\n * Returns an unsubscribe function.\n *\n * Shaped for feeding the sync engine's `isOnline` flag (this package\n * deliberately does not import the sync engine):\n *\n * ```ts\n * const stop = watchOnline((online) => syncStrategy.setOnline(online))\n * ```\n *\n * In hosts without a `window`/events (or without `navigator.onLine`)\n * the callback fires once with `true` (assume online) and the returned\n * unsubscribe is a no-op.\n */\nexport function watchOnline(\n  callback: (online: boolean) => void,\n  target?: EventTarget,\n): () => void {\n  const g = globalThis as { window?: EventTarget; navigator?: { onLine?: boolean } }\n  const t = target ?? g.window\n  callback(g.navigator?.onLine ?? true)\n\n  if (!t || typeof t.addEventListener !== 'function') return () => {}\n  const onOnline = (): void => callback(true)\n  const onOffline = (): void => callback(false)\n  t.addEventListener('online', onOnline)\n  t.addEventListener('offline', onOffline)\n  return () => {\n    t.removeEventListener('online', onOnline)\n    t.removeEventListener('offline', onOffline)\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@noy-db/in-pwa",
+  "version": "0.4.0-pre.2",
+  "description": "PWA shell helpers for noy-db — storage persistence with a clear grant/deny signal, fail-closed eviction guard for the local vault, install-prompt capture, display-mode context detection, online/offline watcher, and the app-shell service-worker recipe.",
+  "license": "MIT",
+  "author": "vLannaAi <vicio@lanna.ai>",
+  "homepage": "https://github.com/vLannaAi/noy-db/tree/main/packages/in-pwa#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vLannaAi/noy-db.git",
+    "directory": "packages/in-pwa"
+  },
+  "bugs": {
+    "url": "https://github.com/vLannaAi/noy-db/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "peerDependencies": {
+    "@noy-db/hub": "0.4.0-pre.2"
+  },
+  "devDependencies": {
+    "@noy-db/hub": "0.4.0-pre.2",
+    "@noy-db/to-memory": "0.4.0-pre.2"
+  },
+  "keywords": [
+    "noy-db",
+    "in-pwa",
+    "pwa",
+    "offline",
+    "persistence",
+    "service-worker"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit"
+  }
+}