@burdenoff/fe-libs 2026.1013.1 → 2026.1013.3

package/dist/shell-native/boot.js

@@ -45,8 +45,8 @@ function j(j) {
 		...p(j.appName),
 		...j.backButton
 	})), O("deepLinks", () => _()), O("network", () => b(j.network ?? {})), O("runtimeHooks", () => u(j.runtimeHooks ?? {})), j.push?.enabled && j.plugins?.pushNotifications) {
-		let e = j.plugins.pushNotifications;
-		O("push", () => S(e, j.push ?? {}));
+		let e = j.plugins.pushNotifications, t = j.plugins.localNotifications;
+		O("push", () => S(e, j.push ?? {}, t));
 	}
 	return l() && j.splash?.autoHide !== !1 && O("splashSafetyTimer", () => T(j.splash?.maxWaitMs ?? 8e3)), O("pwa", () => w({
 		enabled: !0,

package/dist/shell-native/index.d.ts

@@ -16,6 +16,8 @@
  *   plugins: {
  *     updater: () => import('@capgo/capacitor-updater'),
  *     pushNotifications: () => import('@capacitor-firebase/messaging'),
+ *     // Android foreground push display only — see LocalNotificationsLike.
+ *     localNotifications: () => import('@capacitor/local-notifications'),
  *   },
  *   push: { enabled: true },
  * });
@@ -51,5 +53,5 @@ export { configureElectronGlobalKey, getDesktopBridge, getElectronGlobalKey, get
 export { defineCapacitorConfig, isValidAllowNavigationRule, type CapacitorConfigLike, } from './capacitor-config';
 export { defineWebManifest, type WebManifestIcon, type WebManifestLike, type WebManifestPushConfig, type WebManifestShortcut, } from './web-manifest';
 export { renderServiceWorker, SERVICE_WORKER_TEMPLATE } from './service-worker';
-export type { AuthInterceptOptions, BackButtonHandlers, BeforeInstallPromptEventLike, BootNativeShellOptions, CapacitorListenerHandleLike, CapacitorUpdaterLike, DeepLinkDetail, LegacyElectronBridge, MobileRuntimeHooks, NativeConfig, NativePreviewMode, NativeShellHandle, NativeShellPlatform, NetworkHooks, NetworkStatusDetail, OptionalPluginLoaders, PushActionPerformedLike, PushNotificationSchemaLike, PushNotificationsLike, PushNotificationsLoader, PushOptions, PushPermissionStateLike, PushTokenLike, PwaOptions, SplashOptions, UpdaterLoader, } from './types';
+export type { AuthInterceptOptions, BackButtonHandlers, BeforeInstallPromptEventLike, BootNativeShellOptions, CapacitorListenerHandleLike, CapacitorUpdaterLike, DeepLinkDetail, LegacyElectronBridge, MobileRuntimeHooks, NativeConfig, LocalNotificationsLike, LocalNotificationsLoader, NativePreviewMode, NativeShellHandle, NativeShellPlatform, NetworkHooks, NetworkStatusDetail, OptionalPluginLoaders, PushActionPerformedLike, PushNotificationSchemaLike, PushNotificationsLike, PushNotificationsLoader, PushOptions, PushPermissionStateLike, PushTokenLike, PwaOptions, SplashOptions, UpdaterLoader, } from './types';
 export { installPushOptIn, resetPushOptInForTests } from './push-optin';

package/dist/shell-native/push.d.ts

@@ -1,5 +1,5 @@
 import { PushTokenEventDetail } from '../shared/native/types';
-import { PushNotificationsLoader, PushOptions, PushPermissionStateLike } from './types';
+import { LocalNotificationsLoader, PushNotificationsLoader, PushOptions, PushPermissionStateLike } from './types';
 export declare const PUSH_TOKEN_EVENT = "burdenoff:pushToken";
 /**
  * Publish a push token to the rest of the app: `window.__burdenoffPushToken`
@@ -15,7 +15,7 @@ export declare function emitPushToken(value: string, platform: PushTokenEventDet
  * `window.__burdenoffPushToken`; notification tap → deep-link navigator).
  * Does NOT prompt for permission — call `requestPushPermission()` for that.
  */
-export declare function installPushNotifications(loader: PushNotificationsLoader, options?: Pick<PushOptions, 'onToken' | 'onNotificationAction' | 'onNotificationReceived'>): Promise<void>;
+export declare function installPushNotifications(loader: PushNotificationsLoader, options?: Pick<PushOptions, 'onToken' | 'onNotificationAction' | 'onNotificationReceived'>, localNotificationsLoader?: LocalNotificationsLoader): Promise<void>;
 /**
  * Read current native permission state WITHOUT prompting.
  *

package/dist/shell-native/push.js

@@ -22,7 +22,34 @@ async function s() {
 	}
 	return a;
 }
-function c(e) {
+var c = null, l = null;
+async function u(e) {
+	if (!e || !t()) return null;
+	if (l !== e && (c = null, l = e), c) return c;
+	try {
+		let t = (await e()).LocalNotifications ?? null;
+		c = t ? { plugin: t } : null;
+	} catch {
+		c = null;
+	}
+	return c;
+}
+var d = 0;
+async function f(e, t) {
+	try {
+		let n = await u(e);
+		if (!n || (await n.plugin.checkPermissions()).display !== "granted") return;
+		await n.plugin.schedule({ notifications: [{
+			id: ++d % 2147483647,
+			title: t.title ?? "",
+			body: t.body ?? "",
+			channelId: "default",
+			extra: t.data ?? void 0,
+			isExactNotification: !1
+		}] });
+	} catch {}
+}
+function p(e) {
 	let t = e.notification.data;
 	if (!t || typeof t != "object") return null;
 	let n = t.route;
@@ -36,7 +63,7 @@ function c(e) {
 	}
 	return null;
 }
-async function l(t, r = {}) {
+async function m(t, r = {}, c) {
 	o !== t && (a = null, o = t);
 	let l = await s();
 	if (!l) return;
@@ -47,9 +74,9 @@ async function l(t, r = {}) {
 			i(t.token, d), r.onToken?.(t.token, d);
 		}), await u.addListener("notificationReceived", (e) => {
 			let t = e;
-			r.onNotificationReceived?.(t.notification);
+			d === "android" && f(c, t.notification), r.onNotificationReceived?.(t.notification);
 		}), await u.addListener("notificationActionPerformed", (e) => {
-			let t = e, i = c(t);
+			let t = e, i = p(t);
 			i && n(i), r.onNotificationAction?.(t);
 		}), d === "android" && await u.createChannel({
 			id: "default",
@@ -61,7 +88,7 @@ async function l(t, r = {}) {
 		}
 	} catch {}
 }
-async function u() {
+async function h() {
 	try {
 		let e = await s();
 		return e ? (await e.plugin.checkPermissions()).receive : null;
@@ -69,7 +96,7 @@ async function u() {
 		return null;
 	}
 }
-async function d() {
+async function g() {
 	try {
 		let t = await s();
 		if (!t) return !1;
@@ -82,4 +109,4 @@ async function d() {
 	}
 }
 //#endregion
-export { r as PUSH_TOKEN_EVENT, u as checkPushPermission, i as emitPushToken, l as installPushNotifications, d as requestPushPermission };
+export { r as PUSH_TOKEN_EVENT, h as checkPushPermission, i as emitPushToken, m as installPushNotifications, g as requestPushPermission };

package/dist/shell-native/types.d.ts

@@ -201,17 +201,65 @@ export interface PushNotificationsLike {
     }): Promise<void>;
     addListener(eventName: 'tokenReceived' | 'notificationReceived' | 'notificationActionPerformed', listener: (payload: unknown) => void): Promise<CapacitorListenerHandleLike>;
 }
+/**
+ * Structural subset of `@capacitor/local-notifications`' `LocalNotifications`.
+ *
+ * Only used for ANDROID foreground push display. `notificationReceived`
+ * (`PushOptions.onNotificationReceived`) fires ONLY while the app is in the
+ * foreground — Android's OS auto-displays a backgrounded/killed app's
+ * notification-type message via the system tray directly, bypassing JS
+ * entirely, so this listener is never reached for that case. In the
+ * foreground, neither platform auto-displays anything: iOS's own
+ * `presentationOptions` config handles that side: Android has no such
+ * mechanism, and without this, a push received while the app is open is
+ * silently never shown — confirmed live: FCM reported successful delivery,
+ * nothing appeared, because the app was foregrounded and nothing built a
+ * system notification in response.
+ */
+export interface LocalNotificationsLike {
+    checkPermissions(): Promise<{
+        display: PushPermissionStateLike;
+    }>;
+    schedule(options: {
+        notifications: Array<{
+            id: number;
+            title: string;
+            body: string;
+            channelId?: string;
+            extra?: Record<string, unknown>;
+            /**
+             * Defaults to `true` in the plugin itself, and is checked at the
+             * `schedule()` call level regardless of whether a `schedule`
+             * (at/every/on) is even set — leaving it unset pops Android 12+'s
+             * "Alarms & reminders" settings screen before posting anything, even
+             * for an immediate, non-alarm notification. Always pass `false` here
+             * unless a future caller genuinely needs AlarmManager-backed exact
+             * scheduling.
+             */
+            isExactNotification?: boolean;
+        }>;
+    }): Promise<unknown>;
+}
 export type UpdaterLoader = () => Promise<{
     CapacitorUpdater: CapacitorUpdaterLike;
 }>;
 export type PushNotificationsLoader = () => Promise<{
     FirebaseMessaging: PushNotificationsLike;
 }>;
+export type LocalNotificationsLoader = () => Promise<{
+    LocalNotifications: LocalNotificationsLike;
+}>;
 export interface OptionalPluginLoaders {
     /** `() => import('@capgo/capacitor-updater')` */
     updater?: UpdaterLoader;
     /** `() => import('@capacitor-firebase/messaging')` */
     pushNotifications?: PushNotificationsLoader;
+    /**
+     * `() => import('@capacitor/local-notifications')` — Android foreground
+     * push display only. Optional: a shell that never enables push, or
+     * accepts silent foreground pushes, can omit this entirely.
+     */
+    localNotifications?: LocalNotificationsLoader;
 }
 export interface PushOptions {
     enabled: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@burdenoff/fe-libs",
-  "version": "2026.1013.1",
+  "version": "2026.1013.3",
   "description": "Burdenoff frontend primitives and domain libraries",
   "type": "module",
   "bin": {