@astrale-os/shell-react 0.4.0-beta.21 → 0.4.0-beta.22

package/dist/components/astrale.d.ts

@@ -4,6 +4,7 @@ import type { ShellProviderProps } from '../session/provider.js';
 export interface AstraleProps {
     /** Defaults to the child-side sandbox handshake; pass a Shell for an embedded host or test. */
     readonly config?: ShellConfig | Shell;
+    /** Shared loading UI kept mounted across boot and initial content suspension. */
     readonly fallback?: ReactNode;
     readonly errorFallback?: ShellProviderProps['errorFallback'];
     readonly onError?: (error: unknown) => void;

package/dist/components/astrale.js

@@ -1,12 +1,25 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Suspense } from 'react';
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Suspense, useLayoutEffect, useState } from 'react';
 import { ShellProvider } from '../session/provider.js';
 import { ViewStage } from '../window/stage.js';
 import { defaultViewError, defaultViewLoading, ViewErrorBoundary } from './boundaries.js';
 const SANDBOXED_SHELL = Object.freeze({ mode: 'sandboxed' });
 /** Complete Astrale runtime root without taking ownership of application routing. */
 export function Astrale(props) {
-    const loading = props.fallback ?? defaultViewLoading();
+    const [loading, setLoading] = useState(true);
+    const loadingFallback = _jsx(LoadingPresence, { onChange: setLoading });
     const errorFallback = props.errorFallback ?? defaultViewError;
-    return (_jsxs(ShellProvider, { config: props.config ?? SANDBOXED_SHELL, fallback: loading, errorFallback: errorFallback, onError: ({ error }) => props.onError?.(error), children: [_jsx(ViewErrorBoundary, { fallback: errorFallback, onError: props.onError, children: _jsx(Suspense, { fallback: loading, children: props.children }) }), _jsx(ViewStage, {})] }));
+    return (_jsxs(_Fragment, { children: [loading ? (props.fallback ?? defaultViewLoading()) : null, _jsxs(ShellProvider, { config: props.config ?? SANDBOXED_SHELL, fallback: loadingFallback, errorFallback: errorFallback, onError: ({ error }) => props.onError?.(error), children: [_jsx(ViewErrorBoundary, { fallback: errorFallback, onError: props.onError, children: _jsx(Suspense, { fallback: loadingFallback, children: props.children }) }), _jsx(ViewStage, {})] })] }));
+}
+/**
+ * Boot and content fallbacks are mutually exclusive. Their layout-effect handoffs are
+ * batched before paint, so boot → content suspension keeps the same animated DOM
+ * node. Cleanup also releases it on errors, retries, and Suspense reveals.
+ */
+function LoadingPresence({ onChange }) {
+    useLayoutEffect(() => {
+        onChange(true);
+        return () => onChange(false);
+    }, [onChange]);
+    return null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/shell-react",
-  "version": "0.4.0-beta.21",
+  "version": "0.4.0-beta.22",
   "description": "Astrale shell-react — the React face of the shell (provider, hooks, view components)",
   "license": "Apache-2.0",
   "repository": {
@@ -32,7 +32,7 @@
     "zod": "4.4.3"
   },
   "devDependencies": {
-    "@astrale-os/sdk": "0.5.0-beta.146",
+    "@astrale-os/sdk": "0.5.0-beta.147",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/react": "^16.3.0",
     "@types/node": "^26.2.0",

package/src/components/astrale.tsx

@@ -1,7 +1,7 @@
 import type { Shell, ShellConfig } from '@astrale-os/shell'
 import type { ReactElement, ReactNode } from 'react'
 
-import { Suspense } from 'react'
+import { Suspense, useLayoutEffect, useState } from 'react'
 
 import type { ShellProviderProps } from '../session/provider.js'
 
@@ -14,6 +14,7 @@ const SANDBOXED_SHELL = Object.freeze({ mode: 'sandboxed' as const })
 export interface AstraleProps {
   /** Defaults to the child-side sandbox handshake; pass a Shell for an embedded host or test. */
   readonly config?: ShellConfig | Shell
+  /** Shared loading UI kept mounted across boot and initial content suspension. */
   readonly fallback?: ReactNode
   readonly errorFallback?: ShellProviderProps['errorFallback']
   readonly onError?: (error: unknown) => void
@@ -22,19 +23,36 @@ export interface AstraleProps {
 
 /** Complete Astrale runtime root without taking ownership of application routing. */
 export function Astrale(props: AstraleProps): ReactElement {
-  const loading = props.fallback ?? defaultViewLoading()
+  const [loading, setLoading] = useState(true)
+  const loadingFallback = <LoadingPresence onChange={setLoading} />
   const errorFallback = props.errorFallback ?? defaultViewError
   return (
-    <ShellProvider
-      config={props.config ?? SANDBOXED_SHELL}
-      fallback={loading}
-      errorFallback={errorFallback}
-      onError={({ error }) => props.onError?.(error)}
-    >
-      <ViewErrorBoundary fallback={errorFallback} onError={props.onError}>
-        <Suspense fallback={loading}>{props.children}</Suspense>
-      </ViewErrorBoundary>
-      <ViewStage />
-    </ShellProvider>
+    <>
+      {loading ? (props.fallback ?? defaultViewLoading()) : null}
+      <ShellProvider
+        config={props.config ?? SANDBOXED_SHELL}
+        fallback={loadingFallback}
+        errorFallback={errorFallback}
+        onError={({ error }) => props.onError?.(error)}
+      >
+        <ViewErrorBoundary fallback={errorFallback} onError={props.onError}>
+          <Suspense fallback={loadingFallback}>{props.children}</Suspense>
+        </ViewErrorBoundary>
+        <ViewStage />
+      </ShellProvider>
+    </>
   )
 }
+
+/**
+ * Boot and content fallbacks are mutually exclusive. Their layout-effect handoffs are
+ * batched before paint, so boot → content suspension keeps the same animated DOM
+ * node. Cleanup also releases it on errors, retries, and Suspense reveals.
+ */
+function LoadingPresence({ onChange }: { readonly onChange: (loading: boolean) => void }): null {
+  useLayoutEffect(() => {
+    onChange(true)
+    return () => onChange(false)
+  }, [onChange])
+  return null
+}