@symbiote-native/splash-screen 3.0.3 → 3.1.0

package/build/angular/index.d.ts

@@ -1,3 +1,3 @@
 export { hide, isVisible } from '../core';
 export { HideAnimationService } from './services/hide-animation.service';
-export type { IHideAnimationConfig, IHideAnimationResult, IManifest, IHideConfig } from '../core';
+export type { IHideAnimationConfig, IHideAnimationFailure, IHideAnimationFailureStage, IHideAnimationResult, IManifest, IHideConfig, } from '../core';

package/build/angular/services/hide-animation.service/index.js

@@ -33,13 +33,11 @@ var __runInitializers = (this && this.__runInitializers) || function (thisArg, i
     return useValue ? value : void 0;
 };
 import { computed, effect, inject, Injectable, Injector } from '@angular/core';
-import { computeHideAnimationStyles, getHideAnimationConstants, HideAnimationController, } from '../../../core/index.js';
+import { computeHideAnimationStyles, HideAnimationController, } from '../../../core/index.js';
 // Angular twin of React's `useHideAnimation` hook and Vue's `useHideAnimation` composable.
-// Angular has no per-instance hook — state and lifecycle live in DI instead, so `connect()`
-// stands in for the hook's role: call it ONCE (typically from a component's field initializer,
-// inside an injection context) with a GETTER, so it can keep reading the caller's own signals —
-// the same reason Vue's composable also takes a getter rather than a value: there is no
-// re-render/re-setup cycle here to hang a fresh read off of.
+// Angular has no per-instance hook, so `connect()` stands in for it: call it ONCE (typically
+// from a component's field initializer, inside an injection context) with a GETTER so it can
+// keep reading the caller's own signals — same reason Vue's composable takes a getter too.
 //
 //   readonly hideAnimation = inject(HideAnimationService).connect(() => this.config());
 //   // template: [style]="hideAnimation().container.style", (layout)="..." etc.
@@ -57,16 +55,17 @@ let HideAnimationService = (() => {
             if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
             __runInitializers(_classThis, _classExtraInitializers);
         }
-        // Captured in the constructor (itself always run inside an injection context by Angular's
-        // own DI) so `connect()` can create an `effect()` even when called from plain field-initializer
-        // code that is not, on its own, an active injection context — mirrors create-tunnel.ts's
-        // `TunnelOut`, which passes its own captured `Injector` to `effect()` for the same reason.
+        // Captured in the constructor (always run inside an injection context by Angular's own DI)
+        // so `connect()` can create an `effect()` even when called from field-initializer code that
+        // isn't itself an active injection context — mirrors create-tunnel.ts's `TunnelOut`.
         injector = inject(Injector);
+        // The controller reads the native constants in its constructor, so a missing RNBootSplash
+        // throws out of connect() and aborts the host component's construction — deliberately: that
+        // is a build error, and a splash quietly stuck in light mode would ship unnoticed.
         connect(getConfig) {
             const controller = new HideAnimationController(getConfig());
-            const constants = getHideAnimationConstants();
             effect(() => controller.updateConfig(getConfig()), { injector: this.injector });
-            return computed(() => computeHideAnimationStyles(getConfig(), constants, controller));
+            return computed(() => computeHideAnimationStyles(getConfig(), controller.constants, controller));
         }
     };
     return HideAnimationService = _classThis;

package/build/core/hide-animation-controller.d.ts

@@ -1,6 +1,8 @@
-import type { IHideAnimationConfig } from './types';
+import type { IHideAnimationConfig, IHideAnimationConstants } from './types';
 export declare class HideAnimationController {
+    readonly constants: IHideAnimationConstants;
     private readonly readiness;
+    private readonly reportFailure;
     constructor(config: IHideAnimationConfig);
     updateConfig(config: IHideAnimationConfig): void;
     readonly onContainerLayout: () => void;

package/build/core/hide-animation-controller.js

@@ -1,12 +1,29 @@
+import { dlog } from '@symbiote-native/engine';
 import { hide } from './hide.js';
+import { getHideAnimationConstants } from './native-module.js';
 // Faithful port of react-native-bootsplash's useHideAnimation readiness gate (its
 // src/index.ts): hide() fires exactly once, after layout + both images (if requested) +
 // the caller all report ready, then the caller's own fade-out `animate()` runs. logoReady/
 // brandReady are captured ONCE at construction (mirrors the original's useRef factory,
 // evaluated only on first render) — a config that later drops its logo/brand source does
 // NOT retroactively flip readiness back on, only updateConfig's animate/userReady do.
+//
+// DELIBERATE DIVERGENCE from upstream, one place only: upstream swallows a rejected hide() with a
+// bare `.catch(() => {})`, which strands the app under a splash it can no longer dismiss (see
+// maybeRunAnimate). We fail open and report instead. Everything else, the unguarded constants read
+// included, stays a faithful port.
 export class HideAnimationController {
+    // Read once here rather than once per adapter: the values never change over a splash's lifetime.
+    // Unguarded on purpose — a missing RNBootSplash is a build error that must stay loud, see
+    // native-module.ts for the full reasoning before wrapping this in anything.
+    constants;
     readiness;
+    // dlog is DEBUG-gated, so it is the developer's seam, not the report: config.onError is the
+    // channel the app actually hears about this on.
+    reportFailure = (failure) => {
+        dlog(`splash-screen: hide animation degraded at "${failure.stage}": ${String(failure.error)}`);
+        this.readiness.onError?.(failure);
+    };
     constructor(config) {
         this.readiness = {
             layoutReady: false,
@@ -14,11 +31,14 @@ export class HideAnimationController {
             brandReady: config.manifest.brand == null || config.brand == null,
             userReady: config.ready ?? true,
             animate: config.animate,
+            onError: config.onError,
             animateHasBeenCalled: false,
         };
+        this.constants = getHideAnimationConstants();
     }
     updateConfig(config) {
         this.readiness.animate = config.animate;
+        this.readiness.onError = config.onError;
         this.readiness.userReady = config.ready ?? true;
         this.maybeRunAnimate();
     }
@@ -42,9 +62,22 @@ export class HideAnimationController {
             state.userReady &&
             !state.animateHasBeenCalled) {
             state.animateHasBeenCalled = true;
+            // Fail open. animateHasBeenCalled is already true by the time hide() settles, so the gate
+            // is shut for good: on a rejection there is no readiness callback left that could retry,
+            // and skipping animate() means the caller's splash overlay never fades out — the app sits
+            // under it forever. Running animate() anyway costs at worst a fade over a native splash
+            // that is still up; not running it costs the whole app.
             hide({ fade: false })
-                .then(() => state.animate())
-                .catch(() => { });
+                .catch((error) => {
+                this.reportFailure({ stage: 'hide', error });
+            })
+                .then(() => {
+                state.animate();
+            })
+                .catch((error) => {
+                // The caller's own animation throwing must not become an unhandled rejection either.
+                this.reportFailure({ stage: 'animate', error });
+            });
         }
     }
 }

package/build/core/index.d.ts

@@ -2,4 +2,4 @@ export { hide, isVisible } from './hide';
 export { HideAnimationController } from './hide-animation-controller';
 export { computeHideAnimationStyles } from './compute-hide-animation-styles';
 export { getHideAnimationConstants } from './native-module';
-export type { IHideConfig, IManifest, IHideAnimationConfig, IHideAnimationContainerProps, IHideAnimationImageProps, IHideAnimationResult, IHideAnimationConstants, } from './types';
+export type { IHideConfig, IManifest, IHideAnimationConfig, IHideAnimationContainerProps, IHideAnimationFailure, IHideAnimationFailureStage, IHideAnimationImageProps, IHideAnimationResult, IHideAnimationConstants, } from './types';

package/build/core/native-module.js

@@ -7,6 +7,24 @@
 // (hide/isVisible/useHideAnimation) never exposes directly.
 import { getEnforcingNativeModule } from '@symbiote-native/engine';
 const RN_BOOT_SPLASH_MODULE_NAME = 'RNBootSplash';
+// DELIBERATELY UNGUARDED — do not wrap this in a try/catch or hand it a fallback.
+//
+// A missing RNBootSplash is a BUILD error, not a runtime condition: the module is either linked
+// into the binary or it is not, deterministically, on the very first launch. Upstream treats it
+// the same way and does not soften it either — react-native-bootsplash's whole spec file is
+// `TurboModuleRegistry.getEnforcing<Spec>("RNBootSplash")` (src/specs/NativeRNBootSplash.ts),
+// which throws at module-IMPORT time, and its useHideAnimation calls `NativeModule.getConstants()`
+// with no guard at all. `getEnforcing` exists precisely to make this loud.
+//
+// This repo has a live footgun that depends on it staying loud: `npm install` deletes the
+// `.rn-bootsplash/` folder this package's podspec vendors at pod-install time (see CLAUDE.md), so
+// a skipped `pod install` yields exactly this missing module. Degrading to light-mode defaults
+// would turn that into "the splash looks fine, just never dark" and it would ship.
+//
+// Note the failure is currently invisible under @symbiote-native/react specifically: mount()
+// (adapters/react/src/render.ts) wires the reconciler's uncaught-error callbacks to `noop`, so the
+// throw never reaches the app. That is a defect in THAT adapter, tracked separately — it is not a
+// reason to stop throwing here.
 export function getHideAnimationConstants() {
     return getEnforcingNativeModule(RN_BOOT_SPLASH_MODULE_NAME).getConstants();
 }

package/build/core/types.d.ts

@@ -16,6 +16,11 @@ export type IManifest = {
         height: number;
     };
 };
+export type IHideAnimationFailureStage = 'hide' | 'animate';
+export type IHideAnimationFailure = {
+    stage: IHideAnimationFailureStage;
+    error: unknown;
+};
 export type IHideAnimationConfig = {
     manifest: IManifest;
     ready?: boolean;
@@ -24,6 +29,7 @@ export type IHideAnimationConfig = {
     brand?: IImageSourceProp;
     darkBrand?: IImageSourceProp;
     animate: () => void;
+    onError?: (failure: IHideAnimationFailure) => void;
     statusBarTranslucent?: boolean;
     navigationBarTranslucent?: boolean;
 };

package/build/react/hooks/use-hide-animation/index.js

@@ -1,29 +1,25 @@
-// React lifecycle wiring over the framework-agnostic HideAnimationController + style
-// computation (core/) — mirrors the lifecycle-bucket naming convention of
-// adapters/react/src/hooks. Faithful port of react-native-bootsplash's own useHideAnimation:
-// the controller is constructed lazily ONCE (a useRef factory, never reconstructed across
-// re-renders), native constants are read once via useState's lazy initializer (they never
-// change), and an effect with NO dependency array re-syncs the controller's config after
-// EVERY render — intentional, since `ready` flipping true only gets picked up this way.
+// Port of react-native-bootsplash's own useHideAnimation over the framework-agnostic
+// HideAnimationController + style computation in core/. The controller is built lazily ONCE
+// via a useRef factory (never reconstructed across re-renders); the effect below has NO
+// dependency array and re-syncs the controller's config after EVERY render on purpose, since
+// `ready` flipping true is only picked up that way. The native constants ride along on that same
+// once-built controller, so there is no separate useState to hold them.
 //
-// No useMemo around the style computation: upstream lists ~15 individual primitive fields
-// (manifest.logo.width, backgroundColor, ...) as its memo's deps specifically so Object.is
-// compares by VALUE, not by the `config`/`manifest` object's reference — callers construct
-// that object fresh on every render (the normal way to call this hook), so keying a memo off
-// the whole object would recompute every render anyway while looking like it memoizes.
-// Reproducing the fine-grained list isn't worth it for a splash screen shown for a couple of
-// renders at boot; computing plainly is honest about the actual cost and simpler to read.
-import { useEffect, useRef, useState } from 'react';
-import { computeHideAnimationStyles, getHideAnimationConstants, HideAnimationController, } from '../../../core/index.js';
+// No useMemo around the style computation: upstream memoizes on ~15 individual primitive
+// fields so Object.is compares by value rather than by the config/manifest object's
+// reference (callers construct that object fresh every render, so keying off the whole
+// object would recompute anyway). Not worth reproducing for a splash screen shown a couple
+// of renders at boot — computing plainly is simpler and equally cheap.
+import { useEffect, useRef } from 'react';
+import { computeHideAnimationStyles, HideAnimationController, } from '../../../core/index.js';
 export function useHideAnimation(config) {
     const controllerRef = useRef(null);
     if (controllerRef.current == null) {
         controllerRef.current = new HideAnimationController(config);
     }
     const controller = controllerRef.current;
-    const [constants] = useState(() => getHideAnimationConstants());
     useEffect(() => {
         controller.updateConfig(config);
     });
-    return computeHideAnimationStyles(config, constants, controller);
+    return computeHideAnimationStyles(config, controller.constants, controller);
 }

package/build/react/index.d.ts

@@ -1,3 +1,3 @@
 export { hide, isVisible } from '../core';
 export { useHideAnimation } from './hooks/use-hide-animation';
-export type { IHideAnimationConfig, IHideAnimationResult, IManifest, IHideConfig } from '../core';
+export type { IHideAnimationConfig, IHideAnimationFailure, IHideAnimationFailureStage, IHideAnimationResult, IManifest, IHideConfig, } from '../core';

package/build/svelte/index.d.ts

@@ -0,0 +1,3 @@
+export { hide, isVisible } from '../core';
+export { useHideAnimation } from './runes/use-hide-animation.svelte';
+export type { IHideAnimationConfig, IHideAnimationFailure, IHideAnimationFailureStage, IHideAnimationResult, IManifest, IHideConfig, } from '../core';

package/build/svelte/index.js

@@ -0,0 +1,7 @@
+// @symbiote-native/splash-screen/svelte: the Svelte entry over the framework-agnostic core.
+// hide/isVisible carry zero lifecycle and are re-exported verbatim; useHideAnimation wraps
+// HideAnimationController + computeHideAnimationStyles with Svelte's own runes
+// (runes/use-hide-animation.svelte.ts) — mirrors the lifecycle-bucket naming convention of
+// adapters/svelte/src/runes (never `hooks`/`composables`, those are React's/Vue's terms).
+export { hide, isVisible } from '../core/index.js';
+export { useHideAnimation } from './runes/use-hide-animation.svelte';

package/build/svelte/runes/use-hide-animation.svelte.d.ts

@@ -0,0 +1,4 @@
+import { type IHideAnimationConfig, type IHideAnimationResult } from '../../core';
+export declare function useHideAnimation(getConfig: () => IHideAnimationConfig): {
+    readonly current: IHideAnimationResult;
+};

package/build/svelte/runes/use-hide-animation.svelte.js

@@ -0,0 +1,24 @@
+// Svelte lifecycle wiring over the framework-agnostic HideAnimationController + style
+// computation (core/). A Svelte component's `<script>` body runs ONCE (like Vue's setup,
+// unlike a React hook re-running every render), so this takes a config GETTER, not a plain
+// value — the boxed-getter convention from use-color-scheme.svelte.ts. The controller stays
+// a plain local, not `$state`: only its methods are called, nothing needs Svelte to react to
+// the reference itself. `$effect` re-syncs the controller's config on every reactive read
+// inside `getConfig()`, mirroring Vue's `watchEffect`. The controller also carries the native
+// constants, read once in its constructor — so a missing RNBootSplash throws straight out of the
+// component's script body, on purpose.
+import { computeHideAnimationStyles, HideAnimationController, } from '../../core/index.js';
+export function useHideAnimation(getConfig) {
+    const controller = new HideAnimationController(getConfig());
+    let result = $state(computeHideAnimationStyles(getConfig(), controller.constants, controller));
+    $effect(() => {
+        const config = getConfig();
+        controller.updateConfig(config);
+        result = computeHideAnimationStyles(config, controller.constants, controller);
+    });
+    return {
+        get current() {
+            return result;
+        },
+    };
+}

package/build/vue/composables/use-hide-animation/index.js

@@ -1,21 +1,20 @@
 // Vue lifecycle wiring over the framework-agnostic HideAnimationController + style
-// computation (core/). A Vue composable's setup body runs ONCE (unlike a React hook,
-// which re-runs every render), so this takes a config GETTER, not a plain value — Vue's
-// reactivity tracks whatever reactive refs the getter reads internally and re-runs the
-// watchEffect/computed below on their change, mirroring how a React consumer would pass a
-// fresh config object on every render.
+// computation (core/). A composable's setup body runs ONCE (unlike a React hook, which
+// re-runs every render), so this takes a config GETTER, not a plain value — Vue's
+// reactivity tracks whatever reactive refs the getter reads and re-runs the
+// watchEffect/computed below on their change, mirroring a React consumer passing a fresh
+// config object every render.
 //
-// The controller is a plain local, not a Vue ref: nothing needs Vue to react to the
-// controller reference itself (only its methods are called), so wrapping it would only
-// add an unnecessary reactive Proxy — same identity discipline as
-// `use-color-scheme.ts`'s subscription handle.
+// The controller is a plain local, not a Vue ref: only its methods are called, so wrapping
+// it would only add an unnecessary reactive Proxy — same identity discipline as
+// `use-color-scheme.ts`'s subscription handle. It also carries the native constants, read once in
+// its constructor — so a missing RNBootSplash throws straight out of setup, on purpose.
 import { computed, watchEffect } from '@vue/runtime-core';
-import { computeHideAnimationStyles, getHideAnimationConstants, HideAnimationController, } from '../../../core/index.js';
+import { computeHideAnimationStyles, HideAnimationController, } from '../../../core/index.js';
 export function useHideAnimation(getConfig) {
     const controller = new HideAnimationController(getConfig());
-    const constants = getHideAnimationConstants();
     watchEffect(() => {
         controller.updateConfig(getConfig());
     });
-    return computed(() => computeHideAnimationStyles(getConfig(), constants, controller));
+    return computed(() => computeHideAnimationStyles(getConfig(), controller.constants, controller));
 }

package/build/vue/index.d.ts

@@ -1,3 +1,3 @@
 export { hide, isVisible } from '../core';
 export { useHideAnimation } from './composables/use-hide-animation';
-export type { IHideAnimationConfig, IHideAnimationResult, IManifest, IHideConfig } from '../core';
+export type { IHideAnimationConfig, IHideAnimationFailure, IHideAnimationFailureStage, IHideAnimationResult, IManifest, IHideConfig, } from '../core';

package/build-ngc/angular/index.d.ts

@@ -1,3 +1,3 @@
 export { hide, isVisible } from '../core';
 export { HideAnimationService } from './services/hide-animation.service';
-export type { IHideAnimationConfig, IHideAnimationResult, IManifest, IHideConfig } from '../core';
+export type { IHideAnimationConfig, IHideAnimationFailure, IHideAnimationFailureStage, IHideAnimationResult, IManifest, IHideConfig, } from '../core';

package/build-ngc/angular/services/hide-animation.service/index.js

@@ -1,31 +1,30 @@
 import { computed, effect, inject, Injectable, Injector } from '@angular/core';
-import { computeHideAnimationStyles, getHideAnimationConstants, HideAnimationController, } from '../../../core';
+import { computeHideAnimationStyles, HideAnimationController, } from '../../../core';
 import * as i0 from "@angular/core";
 // Angular twin of React's `useHideAnimation` hook and Vue's `useHideAnimation` composable.
-// Angular has no per-instance hook — state and lifecycle live in DI instead, so `connect()`
-// stands in for the hook's role: call it ONCE (typically from a component's field initializer,
-// inside an injection context) with a GETTER, so it can keep reading the caller's own signals —
-// the same reason Vue's composable also takes a getter rather than a value: there is no
-// re-render/re-setup cycle here to hang a fresh read off of.
+// Angular has no per-instance hook, so `connect()` stands in for it: call it ONCE (typically
+// from a component's field initializer, inside an injection context) with a GETTER so it can
+// keep reading the caller's own signals — same reason Vue's composable takes a getter too.
 //
 //   readonly hideAnimation = inject(HideAnimationService).connect(() => this.config());
 //   // template: [style]="hideAnimation().container.style", (layout)="..." etc.
 export class HideAnimationService {
-    // Captured in the constructor (itself always run inside an injection context by Angular's
-    // own DI) so `connect()` can create an `effect()` even when called from plain field-initializer
-    // code that is not, on its own, an active injection context — mirrors create-tunnel.ts's
-    // `TunnelOut`, which passes its own captured `Injector` to `effect()` for the same reason.
+    // Captured in the constructor (always run inside an injection context by Angular's own DI)
+    // so `connect()` can create an `effect()` even when called from field-initializer code that
+    // isn't itself an active injection context — mirrors create-tunnel.ts's `TunnelOut`.
     injector = inject(Injector);
+    // The controller reads the native constants in its constructor, so a missing RNBootSplash
+    // throws out of connect() and aborts the host component's construction — deliberately: that
+    // is a build error, and a splash quietly stuck in light mode would ship unnoticed.
     connect(getConfig) {
         const controller = new HideAnimationController(getConfig());
-        const constants = getHideAnimationConstants();
         effect(() => controller.updateConfig(getConfig()), { injector: this.injector });
-        return computed(() => computeHideAnimationStyles(getConfig(), constants, controller));
+        return computed(() => computeHideAnimationStyles(getConfig(), controller.constants, controller));
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.5", ngImport: i0, type: HideAnimationService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
-    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "22.0.5", ngImport: i0, type: HideAnimationService, providedIn: 'root' });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.8", ngImport: i0, type: HideAnimationService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "22.0.8", ngImport: i0, type: HideAnimationService, providedIn: 'root' });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.5", ngImport: i0, type: HideAnimationService, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.8", ngImport: i0, type: HideAnimationService, decorators: [{
             type: Injectable,
             args: [{ providedIn: 'root' }]
         }] });

package/build-ngc/angular/services/hide-animation.service/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/angular/services/hide-animation.service/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAe,MAAM,eAAe,CAAC;AAC5F,OAAO,EACL,0BAA0B,EAC1B,yBAAyB,EACzB,uBAAuB,GAGxB,MAAM,eAAe,CAAC;;AAEvB,2FAA2F;AAC3F,4FAA4F;AAC5F,+FAA+F;AAC/F,gGAAgG;AAChG,wFAAwF;AACxF,6DAA6D;AAC7D,EAAE;AACF,wFAAwF;AACxF,gFAAgF;AAEhF,MAAM,OAAO,oBAAoB;IAC/B,0FAA0F;IAC1F,gGAAgG;IAChG,yFAAyF;IACzF,2FAA2F;IAC1E,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IAE7C,OAAO,CAAC,SAAqC;QAC3C,MAAM,UAAU,GAAG,IAAI,uBAAuB,CAAC,SAAS,EAAE,CAAC,CAAC;QAC5D,MAAM,SAAS,GAAG,yBAAyB,EAAE,CAAC;QAE9C,MAAM,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,SAAS,EAAE,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QAEhF,OAAO,QAAQ,CAAC,GAAG,EAAE,CAAC,0BAA0B,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC;IACxF,CAAC;uGAdU,oBAAoB;2GAApB,oBAAoB,cADP,MAAM;;2FACnB,oBAAoB;kBADhC,UAAU;mBAAC,EAAE,UAAU,EAAE,MAAM,EAAE"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/angular/services/hide-animation.service/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAe,MAAM,eAAe,CAAC;AAC5F,OAAO,EACL,0BAA0B,EAC1B,uBAAuB,GAGxB,MAAM,eAAe,CAAC;;AAEvB,2FAA2F;AAC3F,6FAA6F;AAC7F,6FAA6F;AAC7F,2FAA2F;AAC3F,EAAE;AACF,wFAAwF;AACxF,gFAAgF;AAEhF,MAAM,OAAO,oBAAoB;IAC/B,2FAA2F;IAC3F,4FAA4F;IAC5F,qFAAqF;IACpE,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IAE7C,0FAA0F;IAC1F,4FAA4F;IAC5F,mFAAmF;IACnF,OAAO,CAAC,SAAqC;QAC3C,MAAM,UAAU,GAAG,IAAI,uBAAuB,CAAC,SAAS,EAAE,CAAC,CAAC;QAE5D,MAAM,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,SAAS,EAAE,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QAEhF,OAAO,QAAQ,CAAC,GAAG,EAAE,CACnB,0BAA0B,CAAC,SAAS,EAAE,EAAE,UAAU,CAAC,SAAS,EAAE,UAAU,CAAC,CAC1E,CAAC;IACJ,CAAC;uGAjBU,oBAAoB;2GAApB,oBAAoB,cADP,MAAM;;2FACnB,oBAAoB;kBADhC,UAAU;mBAAC,EAAE,UAAU,EAAE,MAAM,EAAE"}

package/build-ngc/core/hide-animation-controller.d.ts

@@ -1,6 +1,8 @@
-import type { IHideAnimationConfig } from './types';
+import type { IHideAnimationConfig, IHideAnimationConstants } from './types';
 export declare class HideAnimationController {
+    readonly constants: IHideAnimationConstants;
     private readonly readiness;
+    private readonly reportFailure;
     constructor(config: IHideAnimationConfig);
     updateConfig(config: IHideAnimationConfig): void;
     readonly onContainerLayout: () => void;

package/build-ngc/core/hide-animation-controller.js

@@ -1,12 +1,29 @@
+import { dlog } from '@symbiote-native/engine';
 import { hide } from './hide';
+import { getHideAnimationConstants } from './native-module';
 // Faithful port of react-native-bootsplash's useHideAnimation readiness gate (its
 // src/index.ts): hide() fires exactly once, after layout + both images (if requested) +
 // the caller all report ready, then the caller's own fade-out `animate()` runs. logoReady/
 // brandReady are captured ONCE at construction (mirrors the original's useRef factory,
 // evaluated only on first render) — a config that later drops its logo/brand source does
 // NOT retroactively flip readiness back on, only updateConfig's animate/userReady do.
+//
+// DELIBERATE DIVERGENCE from upstream, one place only: upstream swallows a rejected hide() with a
+// bare `.catch(() => {})`, which strands the app under a splash it can no longer dismiss (see
+// maybeRunAnimate). We fail open and report instead. Everything else, the unguarded constants read
+// included, stays a faithful port.
 export class HideAnimationController {
+    // Read once here rather than once per adapter: the values never change over a splash's lifetime.
+    // Unguarded on purpose — a missing RNBootSplash is a build error that must stay loud, see
+    // native-module.ts for the full reasoning before wrapping this in anything.
+    constants;
     readiness;
+    // dlog is DEBUG-gated, so it is the developer's seam, not the report: config.onError is the
+    // channel the app actually hears about this on.
+    reportFailure = (failure) => {
+        dlog(`splash-screen: hide animation degraded at "${failure.stage}": ${String(failure.error)}`);
+        this.readiness.onError?.(failure);
+    };
     constructor(config) {
         this.readiness = {
             layoutReady: false,
@@ -14,11 +31,14 @@ export class HideAnimationController {
             brandReady: config.manifest.brand == null || config.brand == null,
             userReady: config.ready ?? true,
             animate: config.animate,
+            onError: config.onError,
             animateHasBeenCalled: false,
         };
+        this.constants = getHideAnimationConstants();
     }
     updateConfig(config) {
         this.readiness.animate = config.animate;
+        this.readiness.onError = config.onError;
         this.readiness.userReady = config.ready ?? true;
         this.maybeRunAnimate();
     }
@@ -42,9 +62,22 @@ export class HideAnimationController {
             state.userReady &&
             !state.animateHasBeenCalled) {
             state.animateHasBeenCalled = true;
+            // Fail open. animateHasBeenCalled is already true by the time hide() settles, so the gate
+            // is shut for good: on a rejection there is no readiness callback left that could retry,
+            // and skipping animate() means the caller's splash overlay never fades out — the app sits
+            // under it forever. Running animate() anyway costs at worst a fade over a native splash
+            // that is still up; not running it costs the whole app.
             hide({ fade: false })
-                .then(() => state.animate())
-                .catch(() => { });
+                .catch((error) => {
+                this.reportFailure({ stage: 'hide', error });
+            })
+                .then(() => {
+                state.animate();
+            })
+                .catch((error) => {
+                // The caller's own animation throwing must not become an unhandled rejection either.
+                this.reportFailure({ stage: 'animate', error });
+            });
         }
     }
 }

package/build-ngc/core/hide-animation-controller.js.map

@@ -1 +1 @@
-{"version":3,"file":"hide-animation-controller.js","sourceRoot":"","sources":["../../src/core/hide-animation-controller.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAY9B,kFAAkF;AAClF,wFAAwF;AACxF,2FAA2F;AAC3F,uFAAuF;AACvF,yFAAyF;AACzF,sFAAsF;AACtF,MAAM,OAAO,uBAAuB;IACjB,SAAS,CAAkB;IAE5C,YAAY,MAA4B;QACtC,IAAI,CAAC,SAAS,GAAG;YACf,WAAW,EAAE,KAAK;YAClB,SAAS,EAAE,MAAM,CAAC,IAAI,IAAI,IAAI;YAC9B,UAAU,EAAE,MAAM,CAAC,QAAQ,CAAC,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,KAAK,IAAI,IAAI;YACjE,SAAS,EAAE,MAAM,CAAC,KAAK,IAAI,IAAI;YAC/B,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,oBAAoB,EAAE,KAAK;SAC5B,CAAC;IACJ,CAAC;IAED,YAAY,CAAC,MAA4B;QACvC,IAAI,CAAC,SAAS,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QACxC,IAAI,CAAC,SAAS,CAAC,SAAS,GAAG,MAAM,CAAC,KAAK,IAAI,IAAI,CAAC;QAChD,IAAI,CAAC,eAAe,EAAE,CAAC;IACzB,CAAC;IAEQ,iBAAiB,GAAG,GAAS,EAAE;QACtC,IAAI,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC;QAClC,IAAI,CAAC,eAAe,EAAE,CAAC;IACzB,CAAC,CAAC;IAEO,aAAa,GAAG,GAAS,EAAE;QAClC,IAAI,CAAC,SAAS,CAAC,SAAS,GAAG,IAAI,CAAC;QAChC,IAAI,CAAC,eAAe,EAAE,CAAC;IACzB,CAAC,CAAC;IAEO,cAAc,GAAG,GAAS,EAAE;QACnC,IAAI,CAAC,SAAS,CAAC,UAAU,GAAG,IAAI,CAAC;QACjC,IAAI,CAAC,eAAe,EAAE,CAAC;IACzB,CAAC,CAAC;IAEM,eAAe;QACrB,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC;QAE7B,IACE,KAAK,CAAC,WAAW;YACjB,KAAK,CAAC,SAAS;YACf,KAAK,CAAC,UAAU;YAChB,KAAK,CAAC,SAAS;YACf,CAAC,KAAK,CAAC,oBAAoB,EAC3B,CAAC;YACD,KAAK,CAAC,oBAAoB,GAAG,IAAI,CAAC;YAClC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;iBAClB,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;iBAC3B,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"hide-animation-controller.js","sourceRoot":"","sources":["../../src/core/hide-animation-controller.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAa5D,kFAAkF;AAClF,wFAAwF;AACxF,2FAA2F;AAC3F,uFAAuF;AACvF,yFAAyF;AACzF,sFAAsF;AACtF,EAAE;AACF,kGAAkG;AAClG,8FAA8F;AAC9F,mGAAmG;AACnG,mCAAmC;AACnC,MAAM,OAAO,uBAAuB;IAClC,iGAAiG;IACjG,0FAA0F;IAC1F,4EAA4E;IACnE,SAAS,CAA0B;IAE3B,SAAS,CAAkB;IAE5C,4FAA4F;IAC5F,gDAAgD;IAC/B,aAAa,GAAG,CAAC,OAA8B,EAAQ,EAAE;QACxE,IAAI,CAAC,8CAA8C,OAAO,CAAC,KAAK,MAAM,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC/F,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC,CAAC;IAEF,YAAY,MAA4B;QACtC,IAAI,CAAC,SAAS,GAAG;YACf,WAAW,EAAE,KAAK;YAClB,SAAS,EAAE,MAAM,CAAC,IAAI,IAAI,IAAI;YAC9B,UAAU,EAAE,MAAM,CAAC,QAAQ,CAAC,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,KAAK,IAAI,IAAI;YACjE,SAAS,EAAE,MAAM,CAAC,KAAK,IAAI,IAAI;YAC/B,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,oBAAoB,EAAE,KAAK;SAC5B,CAAC;QACF,IAAI,CAAC,SAAS,GAAG,yBAAyB,EAAE,CAAC;IAC/C,CAAC;IAED,YAAY,CAAC,MAA4B;QACvC,IAAI,CAAC,SAAS,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QACxC,IAAI,CAAC,SAAS,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QACxC,IAAI,CAAC,SAAS,CAAC,SAAS,GAAG,MAAM,CAAC,KAAK,IAAI,IAAI,CAAC;QAChD,IAAI,CAAC,eAAe,EAAE,CAAC;IACzB,CAAC;IAEQ,iBAAiB,GAAG,GAAS,EAAE;QACtC,IAAI,CAAC,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC;QAClC,IAAI,CAAC,eAAe,EAAE,CAAC;IACzB,CAAC,CAAC;IAEO,aAAa,GAAG,GAAS,EAAE;QAClC,IAAI,CAAC,SAAS,CAAC,SAAS,GAAG,IAAI,CAAC;QAChC,IAAI,CAAC,eAAe,EAAE,CAAC;IACzB,CAAC,CAAC;IAEO,cAAc,GAAG,GAAS,EAAE;QACnC,IAAI,CAAC,SAAS,CAAC,UAAU,GAAG,IAAI,CAAC;QACjC,IAAI,CAAC,eAAe,EAAE,CAAC;IACzB,CAAC,CAAC;IAEM,eAAe;QACrB,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC;QAE7B,IACE,KAAK,CAAC,WAAW;YACjB,KAAK,CAAC,SAAS;YACf,KAAK,CAAC,UAAU;YAChB,KAAK,CAAC,SAAS;YACf,CAAC,KAAK,CAAC,oBAAoB,EAC3B,CAAC;YACD,KAAK,CAAC,oBAAoB,GAAG,IAAI,CAAC;YAClC,0FAA0F;YAC1F,yFAAyF;YACzF,0FAA0F;YAC1F,wFAAwF;YACxF,wDAAwD;YACxD,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;iBAClB,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;gBACxB,IAAI,CAAC,aAAa,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;YAC/C,CAAC,CAAC;iBACD,IAAI,CAAC,GAAG,EAAE;gBACT,KAAK,CAAC,OAAO,EAAE,CAAC;YAClB,CAAC,CAAC;iBACD,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;gBACxB,qFAAqF;gBACrF,IAAI,CAAC,aAAa,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;YAClD,CAAC,CAAC,CAAC;QACP,CAAC;IACH,CAAC;CACF"}

package/build-ngc/core/index.d.ts

@@ -2,4 +2,4 @@ export { hide, isVisible } from './hide';
 export { HideAnimationController } from './hide-animation-controller';
 export { computeHideAnimationStyles } from './compute-hide-animation-styles';
 export { getHideAnimationConstants } from './native-module';
-export type { IHideConfig, IManifest, IHideAnimationConfig, IHideAnimationContainerProps, IHideAnimationImageProps, IHideAnimationResult, IHideAnimationConstants, } from './types';
+export type { IHideConfig, IManifest, IHideAnimationConfig, IHideAnimationContainerProps, IHideAnimationFailure, IHideAnimationFailureStage, IHideAnimationImageProps, IHideAnimationResult, IHideAnimationConstants, } from './types';

package/build-ngc/core/native-module.js

@@ -7,6 +7,24 @@
 // (hide/isVisible/useHideAnimation) never exposes directly.
 import { getEnforcingNativeModule } from '@symbiote-native/engine';
 const RN_BOOT_SPLASH_MODULE_NAME = 'RNBootSplash';
+// DELIBERATELY UNGUARDED — do not wrap this in a try/catch or hand it a fallback.
+//
+// A missing RNBootSplash is a BUILD error, not a runtime condition: the module is either linked
+// into the binary or it is not, deterministically, on the very first launch. Upstream treats it
+// the same way and does not soften it either — react-native-bootsplash's whole spec file is
+// `TurboModuleRegistry.getEnforcing<Spec>("RNBootSplash")` (src/specs/NativeRNBootSplash.ts),
+// which throws at module-IMPORT time, and its useHideAnimation calls `NativeModule.getConstants()`
+// with no guard at all. `getEnforcing` exists precisely to make this loud.
+//
+// This repo has a live footgun that depends on it staying loud: `npm install` deletes the
+// `.rn-bootsplash/` folder this package's podspec vendors at pod-install time (see CLAUDE.md), so
+// a skipped `pod install` yields exactly this missing module. Degrading to light-mode defaults
+// would turn that into "the splash looks fine, just never dark" and it would ship.
+//
+// Note the failure is currently invisible under @symbiote-native/react specifically: mount()
+// (adapters/react/src/render.ts) wires the reconciler's uncaught-error callbacks to `noop`, so the
+// throw never reaches the app. That is a defect in THAT adapter, tracked separately — it is not a
+// reason to stop throwing here.
 export function getHideAnimationConstants() {
     return getEnforcingNativeModule(RN_BOOT_SPLASH_MODULE_NAME).getConstants();
 }

package/build-ngc/core/native-module.js.map

@@ -1 +1 @@
-{"version":3,"file":"native-module.js","sourceRoot":"","sources":["../../src/core/native-module.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,gFAAgF;AAChF,wFAAwF;AACxF,qFAAqF;AACrF,yFAAyF;AACzF,oFAAoF;AACpF,4DAA4D;AAC5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAGnE,MAAM,0BAA0B,GAAG,cAAc,CAAC;AAMlD,MAAM,UAAU,yBAAyB;IACvC,OAAO,wBAAwB,CAAoB,0BAA0B,CAAC,CAAC,YAAY,EAAE,CAAC;AAChG,CAAC"}
+{"version":3,"file":"native-module.js","sourceRoot":"","sources":["../../src/core/native-module.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,gFAAgF;AAChF,wFAAwF;AACxF,qFAAqF;AACrF,yFAAyF;AACzF,oFAAoF;AACpF,4DAA4D;AAC5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAGnE,MAAM,0BAA0B,GAAG,cAAc,CAAC;AAMlD,kFAAkF;AAClF,EAAE;AACF,gGAAgG;AAChG,gGAAgG;AAChG,4FAA4F;AAC5F,8FAA8F;AAC9F,mGAAmG;AACnG,2EAA2E;AAC3E,EAAE;AACF,0FAA0F;AAC1F,kGAAkG;AAClG,+FAA+F;AAC/F,mFAAmF;AACnF,EAAE;AACF,6FAA6F;AAC7F,mGAAmG;AACnG,kGAAkG;AAClG,gCAAgC;AAChC,MAAM,UAAU,yBAAyB;IACvC,OAAO,wBAAwB,CAAoB,0BAA0B,CAAC,CAAC,YAAY,EAAE,CAAC;AAChG,CAAC"}

package/build-ngc/core/types.d.ts

@@ -16,6 +16,11 @@ export type IManifest = {
         height: number;
     };
 };
+export type IHideAnimationFailureStage = 'hide' | 'animate';
+export type IHideAnimationFailure = {
+    stage: IHideAnimationFailureStage;
+    error: unknown;
+};
 export type IHideAnimationConfig = {
     manifest: IManifest;
     ready?: boolean;
@@ -24,6 +29,7 @@ export type IHideAnimationConfig = {
     brand?: IImageSourceProp;
     darkBrand?: IImageSourceProp;
     animate: () => void;
+    onError?: (failure: IHideAnimationFailure) => void;
     statusBarTranslucent?: boolean;
     navigationBarTranslucent?: boolean;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbiote-native/splash-screen",
-  "version": "3.0.3",
+  "version": "3.1.0",
   "description": "Third-party splash-screen native module wrapped for SymbioteNative — one framework-agnostic core, built once and reachable from the React, Vue, and Angular adapters.",
   "license": "MIT",
   "repository": {
@@ -33,6 +33,10 @@
       "types": "./build/react/index.d.ts",
       "default": "./build/react/index.js"
     },
+    "./svelte": {
+      "types": "./build/svelte/index.d.ts",
+      "default": "./build/svelte/index.js"
+    },
     "./angular": {
       "types": "./build-ngc/angular/index.d.ts",
       "react-native": "./build-ngc/angular/index.js",
@@ -65,18 +69,20 @@
   "dependencies": {
     "react-native-bootsplash": "7.3.2",
     "react-native-is-edge-to-edge": "^1.3.1",
-    "@symbiote-native/components": "0.3.0"
+    "@symbiote-native/components": "0.4.0"
   },
   "peerDependencies": {
+    "@symbiote-native/angular": ">=0.6.2",
     "@symbiote-native/engine": ">=0.1.7",
+    "@symbiote-native/react": ">=0.2.8",
+    "@symbiote-native/svelte": ">=0.1.0",
+    "@symbiote-native/vue": ">=0.3.8",
     "@angular/core": ">=20",
     "@vue/runtime-core": "^3.5.13",
     "react": ">=19.0.0",
     "react-native": ">=0.86",
-    "vue": ">=3.5.0",
-    "@symbiote-native/angular": "0.6.2",
-    "@symbiote-native/react": "0.2.8",
-    "@symbiote-native/vue": "0.3.8"
+    "svelte": ">=5.0.0",
+    "vue": ">=3.5.0"
   },
   "peerDependenciesMeta": {
     "@symbiote-native/angular": {
@@ -85,6 +91,9 @@
     "@symbiote-native/react": {
       "optional": true
     },
+    "@symbiote-native/svelte": {
+      "optional": true
+    },
     "@symbiote-native/vue": {
       "optional": true
     },
@@ -97,24 +106,29 @@
     "react": {
       "optional": true
     },
+    "svelte": {
+      "optional": true
+    },
     "vue": {
       "optional": true
     }
   },
   "devDependencies": {
-    "@angular/compiler": "^22",
-    "@angular/compiler-cli": "^22",
-    "@angular/core": "^22",
+    "@angular/compiler": "~22.0.8",
+    "@angular/compiler-cli": "~22.0.8",
+    "@angular/core": "~22.0.8",
     "@types/node": "^26.0.0",
     "@types/react": "^19.2.0",
     "@vue/runtime-core": "^3.5.13",
     "react": "19.2.3",
+    "svelte": "^5.56.0",
     "typescript": "~6.0.0",
-    "@symbiote-native/angular": "0.6.2",
-    "@symbiote-native/engine": "0.1.7",
-    "@symbiote-native/react": "0.2.8",
+    "@symbiote-native/angular": "0.7.0",
+    "@symbiote-native/engine": "0.2.0",
+    "@symbiote-native/react": "0.3.0",
+    "@symbiote-native/svelte": "0.2.0",
     "@symbiote-native/test-utils": "0.1.6",
-    "@symbiote-native/vue": "0.3.8"
+    "@symbiote-native/vue": "0.4.0"
   },
   "scripts": {
     "typecheck": "tsc --build",

package/src/angular/index.ts

@@ -3,4 +3,11 @@
 // machine, style computation, and native-constants read all live in core, shared with React/Vue.
 export { hide, isVisible } from '../core';
 export { HideAnimationService } from './services/hide-animation.service';
-export type { IHideAnimationConfig, IHideAnimationResult, IManifest, IHideConfig } from '../core';
+export type {
+  IHideAnimationConfig,
+  IHideAnimationFailure,
+  IHideAnimationFailureStage,
+  IHideAnimationResult,
+  IManifest,
+  IHideConfig,
+} from '../core';

package/src/angular/services/hide-animation.service/index.ts

@@ -1,35 +1,35 @@
 import { computed, effect, inject, Injectable, Injector, type Signal } from '@angular/core';
 import {
   computeHideAnimationStyles,
-  getHideAnimationConstants,
   HideAnimationController,
   type IHideAnimationConfig,
   type IHideAnimationResult,
 } from '../../../core';
 
 // Angular twin of React's `useHideAnimation` hook and Vue's `useHideAnimation` composable.
-// Angular has no per-instance hook — state and lifecycle live in DI instead, so `connect()`
-// stands in for the hook's role: call it ONCE (typically from a component's field initializer,
-// inside an injection context) with a GETTER, so it can keep reading the caller's own signals —
-// the same reason Vue's composable also takes a getter rather than a value: there is no
-// re-render/re-setup cycle here to hang a fresh read off of.
+// Angular has no per-instance hook, so `connect()` stands in for it: call it ONCE (typically
+// from a component's field initializer, inside an injection context) with a GETTER so it can
+// keep reading the caller's own signals — same reason Vue's composable takes a getter too.
 //
 //   readonly hideAnimation = inject(HideAnimationService).connect(() => this.config());
 //   // template: [style]="hideAnimation().container.style", (layout)="..." etc.
 @Injectable({ providedIn: 'root' })
 export class HideAnimationService {
-  // Captured in the constructor (itself always run inside an injection context by Angular's
-  // own DI) so `connect()` can create an `effect()` even when called from plain field-initializer
-  // code that is not, on its own, an active injection context — mirrors create-tunnel.ts's
-  // `TunnelOut`, which passes its own captured `Injector` to `effect()` for the same reason.
+  // Captured in the constructor (always run inside an injection context by Angular's own DI)
+  // so `connect()` can create an `effect()` even when called from field-initializer code that
+  // isn't itself an active injection context — mirrors create-tunnel.ts's `TunnelOut`.
   private readonly injector = inject(Injector);
 
+  // The controller reads the native constants in its constructor, so a missing RNBootSplash
+  // throws out of connect() and aborts the host component's construction — deliberately: that
+  // is a build error, and a splash quietly stuck in light mode would ship unnoticed.
   connect(getConfig: () => IHideAnimationConfig): Signal<IHideAnimationResult> {
     const controller = new HideAnimationController(getConfig());
-    const constants = getHideAnimationConstants();
 
     effect(() => controller.updateConfig(getConfig()), { injector: this.injector });
 
-    return computed(() => computeHideAnimationStyles(getConfig(), constants, controller));
+    return computed(() =>
+      computeHideAnimationStyles(getConfig(), controller.constants, controller),
+    );
   }
 }

package/src/core/hide-animation-controller.ts

@@ -1,5 +1,7 @@
+import { dlog } from '@symbiote-native/engine';
 import { hide } from './hide';
-import type { IHideAnimationConfig } from './types';
+import { getHideAnimationConstants } from './native-module';
+import type { IHideAnimationConfig, IHideAnimationConstants, IHideAnimationFailure } from './types';
 
 type IReadinessState = {
   layoutReady: boolean;
@@ -7,6 +9,7 @@ type IReadinessState = {
   brandReady: boolean;
   userReady: boolean;
   animate: () => void;
+  onError: ((failure: IHideAnimationFailure) => void) | undefined;
   animateHasBeenCalled: boolean;
 };
 
@@ -16,9 +19,26 @@ type IReadinessState = {
 // brandReady are captured ONCE at construction (mirrors the original's useRef factory,
 // evaluated only on first render) — a config that later drops its logo/brand source does
 // NOT retroactively flip readiness back on, only updateConfig's animate/userReady do.
+//
+// DELIBERATE DIVERGENCE from upstream, one place only: upstream swallows a rejected hide() with a
+// bare `.catch(() => {})`, which strands the app under a splash it can no longer dismiss (see
+// maybeRunAnimate). We fail open and report instead. Everything else, the unguarded constants read
+// included, stays a faithful port.
 export class HideAnimationController {
+  // Read once here rather than once per adapter: the values never change over a splash's lifetime.
+  // Unguarded on purpose — a missing RNBootSplash is a build error that must stay loud, see
+  // native-module.ts for the full reasoning before wrapping this in anything.
+  readonly constants: IHideAnimationConstants;
+
   private readonly readiness: IReadinessState;
 
+  // dlog is DEBUG-gated, so it is the developer's seam, not the report: config.onError is the
+  // channel the app actually hears about this on.
+  private readonly reportFailure = (failure: IHideAnimationFailure): void => {
+    dlog(`splash-screen: hide animation degraded at "${failure.stage}": ${String(failure.error)}`);
+    this.readiness.onError?.(failure);
+  };
+
   constructor(config: IHideAnimationConfig) {
     this.readiness = {
       layoutReady: false,
@@ -26,12 +46,15 @@ export class HideAnimationController {
       brandReady: config.manifest.brand == null || config.brand == null,
       userReady: config.ready ?? true,
       animate: config.animate,
+      onError: config.onError,
       animateHasBeenCalled: false,
     };
+    this.constants = getHideAnimationConstants();
   }
 
   updateConfig(config: IHideAnimationConfig): void {
     this.readiness.animate = config.animate;
+    this.readiness.onError = config.onError;
     this.readiness.userReady = config.ready ?? true;
     this.maybeRunAnimate();
   }
@@ -62,9 +85,22 @@ export class HideAnimationController {
       !state.animateHasBeenCalled
     ) {
       state.animateHasBeenCalled = true;
+      // Fail open. animateHasBeenCalled is already true by the time hide() settles, so the gate
+      // is shut for good: on a rejection there is no readiness callback left that could retry,
+      // and skipping animate() means the caller's splash overlay never fades out — the app sits
+      // under it forever. Running animate() anyway costs at worst a fade over a native splash
+      // that is still up; not running it costs the whole app.
       hide({ fade: false })
-        .then(() => state.animate())
-        .catch(() => {});
+        .catch((error: unknown) => {
+          this.reportFailure({ stage: 'hide', error });
+        })
+        .then(() => {
+          state.animate();
+        })
+        .catch((error: unknown) => {
+          // The caller's own animation throwing must not become an unhandled rejection either.
+          this.reportFailure({ stage: 'animate', error });
+        });
     }
   }
 }

package/src/core/index.ts

@@ -7,6 +7,8 @@ export type {
   IManifest,
   IHideAnimationConfig,
   IHideAnimationContainerProps,
+  IHideAnimationFailure,
+  IHideAnimationFailureStage,
   IHideAnimationImageProps,
   IHideAnimationResult,
   IHideAnimationConstants,

package/src/core/native-module.ts

@@ -14,6 +14,24 @@ type IRNBootSplashSpec = {
   getConstants(): IHideAnimationConstants;
 };
 
+// DELIBERATELY UNGUARDED — do not wrap this in a try/catch or hand it a fallback.
+//
+// A missing RNBootSplash is a BUILD error, not a runtime condition: the module is either linked
+// into the binary or it is not, deterministically, on the very first launch. Upstream treats it
+// the same way and does not soften it either — react-native-bootsplash's whole spec file is
+// `TurboModuleRegistry.getEnforcing<Spec>("RNBootSplash")` (src/specs/NativeRNBootSplash.ts),
+// which throws at module-IMPORT time, and its useHideAnimation calls `NativeModule.getConstants()`
+// with no guard at all. `getEnforcing` exists precisely to make this loud.
+//
+// This repo has a live footgun that depends on it staying loud: `npm install` deletes the
+// `.rn-bootsplash/` folder this package's podspec vendors at pod-install time (see CLAUDE.md), so
+// a skipped `pod install` yields exactly this missing module. Degrading to light-mode defaults
+// would turn that into "the splash looks fine, just never dark" and it would ship.
+//
+// Note the failure is currently invisible under @symbiote-native/react specifically: mount()
+// (adapters/react/src/render.ts) wires the reconciler's uncaught-error callbacks to `noop`, so the
+// throw never reaches the app. That is a defect in THAT adapter, tracked separately — it is not a
+// reason to stop throwing here.
 export function getHideAnimationConstants(): IHideAnimationConstants {
   return getEnforcingNativeModule<IRNBootSplashSpec>(RN_BOOT_SPLASH_MODULE_NAME).getConstants();
 }

package/src/core/types.ts

@@ -19,6 +19,21 @@ export type IManifest = {
   };
 };
 
+// The two RECOVERABLE points in the hide sequence, both of them runtime failures of a native
+// module that does exist:
+//   hide    - the native hide() call rejected.
+//   animate - the caller's own fade-out threw.
+// Neither is allowed to strand the app under a splash it can no longer dismiss, so each is
+// reported and the sequence carries on. A `hide` failure means the native splash may still be up
+// underneath the caller's fade-out. A MISSING native module is deliberately not on this list —
+// that is a build error and it throws (see native-module.ts).
+export type IHideAnimationFailureStage = 'hide' | 'animate';
+
+export type IHideAnimationFailure = {
+  stage: IHideAnimationFailureStage;
+  error: unknown;
+};
+
 export type IHideAnimationConfig = {
   manifest: IManifest;
   ready?: boolean;
@@ -30,6 +45,10 @@ export type IHideAnimationConfig = {
 
   animate: () => void;
 
+  // The caller's only way to tell a nominal hide from a degraded one: `animate()` now runs in
+  // both cases, so its firing no longer proves the native side succeeded.
+  onError?: (failure: IHideAnimationFailure) => void;
+
   statusBarTranslucent?: boolean;
   navigationBarTranslucent?: boolean;
 };

package/src/react/hooks/use-hide-animation/index.ts

@@ -1,25 +1,20 @@
-// React lifecycle wiring over the framework-agnostic HideAnimationController + style
-// computation (core/) — mirrors the lifecycle-bucket naming convention of
-// adapters/react/src/hooks. Faithful port of react-native-bootsplash's own useHideAnimation:
-// the controller is constructed lazily ONCE (a useRef factory, never reconstructed across
-// re-renders), native constants are read once via useState's lazy initializer (they never
-// change), and an effect with NO dependency array re-syncs the controller's config after
-// EVERY render — intentional, since `ready` flipping true only gets picked up this way.
+// Port of react-native-bootsplash's own useHideAnimation over the framework-agnostic
+// HideAnimationController + style computation in core/. The controller is built lazily ONCE
+// via a useRef factory (never reconstructed across re-renders); the effect below has NO
+// dependency array and re-syncs the controller's config after EVERY render on purpose, since
+// `ready` flipping true is only picked up that way. The native constants ride along on that same
+// once-built controller, so there is no separate useState to hold them.
 //
-// No useMemo around the style computation: upstream lists ~15 individual primitive fields
-// (manifest.logo.width, backgroundColor, ...) as its memo's deps specifically so Object.is
-// compares by VALUE, not by the `config`/`manifest` object's reference — callers construct
-// that object fresh on every render (the normal way to call this hook), so keying a memo off
-// the whole object would recompute every render anyway while looking like it memoizes.
-// Reproducing the fine-grained list isn't worth it for a splash screen shown for a couple of
-// renders at boot; computing plainly is honest about the actual cost and simpler to read.
-import { useEffect, useRef, useState } from 'react';
+// No useMemo around the style computation: upstream memoizes on ~15 individual primitive
+// fields so Object.is compares by value rather than by the config/manifest object's
+// reference (callers construct that object fresh every render, so keying off the whole
+// object would recompute anyway). Not worth reproducing for a splash screen shown a couple
+// of renders at boot — computing plainly is simpler and equally cheap.
+import { useEffect, useRef } from 'react';
 import {
   computeHideAnimationStyles,
-  getHideAnimationConstants,
   HideAnimationController,
   type IHideAnimationConfig,
-  type IHideAnimationConstants,
   type IHideAnimationResult,
 } from '../../../core';
 
@@ -30,11 +25,9 @@ export function useHideAnimation(config: IHideAnimationConfig): IHideAnimationRe
   }
   const controller = controllerRef.current;
 
-  const [constants] = useState<IHideAnimationConstants>(() => getHideAnimationConstants());
-
   useEffect(() => {
     controller.updateConfig(config);
   });
 
-  return computeHideAnimationStyles(config, constants, controller);
+  return computeHideAnimationStyles(config, controller.constants, controller);
 }

package/src/react/index.ts

@@ -6,4 +6,11 @@
 
 export { hide, isVisible } from '../core';
 export { useHideAnimation } from './hooks/use-hide-animation';
-export type { IHideAnimationConfig, IHideAnimationResult, IManifest, IHideConfig } from '../core';
+export type {
+  IHideAnimationConfig,
+  IHideAnimationFailure,
+  IHideAnimationFailureStage,
+  IHideAnimationResult,
+  IManifest,
+  IHideConfig,
+} from '../core';

package/src/svelte/index.ts

@@ -0,0 +1,16 @@
+// @symbiote-native/splash-screen/svelte: the Svelte entry over the framework-agnostic core.
+// hide/isVisible carry zero lifecycle and are re-exported verbatim; useHideAnimation wraps
+// HideAnimationController + computeHideAnimationStyles with Svelte's own runes
+// (runes/use-hide-animation.svelte.ts) — mirrors the lifecycle-bucket naming convention of
+// adapters/svelte/src/runes (never `hooks`/`composables`, those are React's/Vue's terms).
+
+export { hide, isVisible } from '../core';
+export { useHideAnimation } from './runes/use-hide-animation.svelte';
+export type {
+  IHideAnimationConfig,
+  IHideAnimationFailure,
+  IHideAnimationFailureStage,
+  IHideAnimationResult,
+  IManifest,
+  IHideConfig,
+} from '../core';

package/src/svelte/runes/use-hide-animation.svelte.ts

@@ -0,0 +1,37 @@
+// Svelte lifecycle wiring over the framework-agnostic HideAnimationController + style
+// computation (core/). A Svelte component's `<script>` body runs ONCE (like Vue's setup,
+// unlike a React hook re-running every render), so this takes a config GETTER, not a plain
+// value — the boxed-getter convention from use-color-scheme.svelte.ts. The controller stays
+// a plain local, not `$state`: only its methods are called, nothing needs Svelte to react to
+// the reference itself. `$effect` re-syncs the controller's config on every reactive read
+// inside `getConfig()`, mirroring Vue's `watchEffect`. The controller also carries the native
+// constants, read once in its constructor — so a missing RNBootSplash throws straight out of the
+// component's script body, on purpose.
+import {
+  computeHideAnimationStyles,
+  HideAnimationController,
+  type IHideAnimationConfig,
+  type IHideAnimationResult,
+} from '../../core';
+
+export function useHideAnimation(getConfig: () => IHideAnimationConfig): {
+  readonly current: IHideAnimationResult;
+} {
+  const controller = new HideAnimationController(getConfig());
+
+  let result = $state<IHideAnimationResult>(
+    computeHideAnimationStyles(getConfig(), controller.constants, controller),
+  );
+
+  $effect(() => {
+    const config = getConfig();
+    controller.updateConfig(config);
+    result = computeHideAnimationStyles(config, controller.constants, controller);
+  });
+
+  return {
+    get current(): IHideAnimationResult {
+      return result;
+    },
+  };
+}

package/src/svelte/svelte-ambient.d.ts

@@ -0,0 +1,6 @@
+// Pulls in svelte's ambient global declarations ($state/$effect/...) for this package's tsc
+// program. adapters/svelte gets these for free because render.ts does a real value import from
+// 'svelte' (any file in a program importing a module loads its ambient globals for the whole
+// program); this package has no such import, so a triple-slash reference does the same job
+// explicitly rather than relying on an incidental side-effect.
+/// <reference types="svelte" />

package/src/vue/composables/use-hide-animation/index.ts

@@ -1,18 +1,17 @@
 // Vue lifecycle wiring over the framework-agnostic HideAnimationController + style
-// computation (core/). A Vue composable's setup body runs ONCE (unlike a React hook,
-// which re-runs every render), so this takes a config GETTER, not a plain value — Vue's
-// reactivity tracks whatever reactive refs the getter reads internally and re-runs the
-// watchEffect/computed below on their change, mirroring how a React consumer would pass a
-// fresh config object on every render.
+// computation (core/). A composable's setup body runs ONCE (unlike a React hook, which
+// re-runs every render), so this takes a config GETTER, not a plain value — Vue's
+// reactivity tracks whatever reactive refs the getter reads and re-runs the
+// watchEffect/computed below on their change, mirroring a React consumer passing a fresh
+// config object every render.
 //
-// The controller is a plain local, not a Vue ref: nothing needs Vue to react to the
-// controller reference itself (only its methods are called), so wrapping it would only
-// add an unnecessary reactive Proxy — same identity discipline as
-// `use-color-scheme.ts`'s subscription handle.
+// The controller is a plain local, not a Vue ref: only its methods are called, so wrapping
+// it would only add an unnecessary reactive Proxy — same identity discipline as
+// `use-color-scheme.ts`'s subscription handle. It also carries the native constants, read once in
+// its constructor — so a missing RNBootSplash throws straight out of setup, on purpose.
 import { computed, watchEffect, type ComputedRef } from '@vue/runtime-core';
 import {
   computeHideAnimationStyles,
-  getHideAnimationConstants,
   HideAnimationController,
   type IHideAnimationConfig,
   type IHideAnimationResult,
@@ -22,11 +21,10 @@ export function useHideAnimation(
   getConfig: () => IHideAnimationConfig,
 ): ComputedRef<IHideAnimationResult> {
   const controller = new HideAnimationController(getConfig());
-  const constants = getHideAnimationConstants();
 
   watchEffect(() => {
     controller.updateConfig(getConfig());
   });
 
-  return computed(() => computeHideAnimationStyles(getConfig(), constants, controller));
+  return computed(() => computeHideAnimationStyles(getConfig(), controller.constants, controller));
 }

package/src/vue/index.ts

@@ -6,4 +6,11 @@
 
 export { hide, isVisible } from '../core';
 export { useHideAnimation } from './composables/use-hide-animation';
-export type { IHideAnimationConfig, IHideAnimationResult, IManifest, IHideConfig } from '../core';
+export type {
+  IHideAnimationConfig,
+  IHideAnimationFailure,
+  IHideAnimationFailureStage,
+  IHideAnimationResult,
+  IManifest,
+  IHideConfig,
+} from '../core';

package/symbiote-splash-screen.podspec

@@ -17,6 +17,14 @@ native_splash_screen_root = File.dirname(native_splash_screen_package_json)
 # NSClassFromString crash on first launch, not a build error. Fix: vendor (copy) the native iOS
 # sources into a gitignored folder next to this podspec on every `pod install`, and point
 # source_files at that copy (a purely-downward relative pattern).
+#
+# CONSEQUENCE, and it looks like something else entirely: this copy is made at PODSPEC
+# EVALUATION time, i.e. during `pod install` — nothing in package.json regenerates it. So any
+# `npm install` that replaces this package's folder in an example app (the routine
+# pack-a-tarball-and-reinstall loop) deletes `.rn-bootsplash`, and the NEXT iOS build dies with
+#   Build input file cannot be found: '.../splash-screen/.rn-bootsplash/ios/RNBootSplash.mm'
+# buried under hundreds of lines of clang argument dumps. It reads like a corrupt install; it is
+# not. Fix: re-run `pod install` in that app's ios/ directory.
 vendored_dir = File.join(__dir__, '.rn-bootsplash')
 
 FileUtils.rm_rf(vendored_dir)