sh3-core 0.5.2 → 0.5.5

package/dist/Shell.svelte

@@ -19,6 +19,7 @@
   import { registerLayerRoot, unregisterLayerRoot } from './overlays/roots';
   import { returnToHome, getActiveApp } from './api';
   import iconsUrl from './assets/icons.svg';
+  import GuestBanner from './auth/GuestBanner.svelte';
 
   // Layer metadata — order matches the stack in docs/design/layout.md.
   // Index 0 here is layer 1 (floating panels); layer 0 is the content area.
@@ -64,6 +65,8 @@
     {/if}
   </header>
 
+  <GuestBanner />
+
   <main class="shell-content" data-shell-region="content" data-shell-layer="0">
     <LayoutRenderer />
   </main>
@@ -97,7 +100,7 @@
 <style>
   .shell {
     display: grid;
-    grid-template-rows: var(--shell-tabbar-height) 1fr var(--shell-statusbar-height);
+    grid-template-rows: var(--shell-tabbar-height) auto 1fr var(--shell-statusbar-height);
     height: 100%;
     width: 100%;
     position: relative;
@@ -160,7 +163,7 @@
     background: transparent;
     color: var(--shell-fg-muted);
     border: 1px solid var(--shell-border);
-    border-radius: 4px;
+    border-radius: var(--shell-radius);
     cursor: pointer;
   }
   .shell-tabbar-home-button:hover {
@@ -180,6 +183,6 @@
     color: #fff;
     background: var(--shell-accent);
     padding: 1px 6px;
-    border-radius: 8px;
+    border-radius: var(--shell-radius-lg);
   }
 </style>

package/dist/admin/AuthSettingsView.svelte

@@ -0,0 +1,105 @@
+<script lang="ts">
+  /**
+   * Admin Auth Settings view — toggle auth-related global settings.
+   */
+
+  import type { GlobalSettings } from '../auth/types';
+
+  let settings = $state<GlobalSettings | null>(null);
+  let loading = $state(true);
+  let saving = $state(false);
+  let error = $state<string | null>(null);
+
+  async function fetchSettings() {
+    loading = true;
+    try {
+      const res = await fetch('/api/admin/settings', { credentials: 'include' });
+      if (!res.ok) throw new Error('Failed to fetch settings');
+      settings = await res.json();
+    } catch (err) {
+      error = err instanceof Error ? err.message : 'Failed to load settings';
+    } finally {
+      loading = false;
+    }
+  }
+
+  async function save() {
+    if (!settings) return;
+    saving = true;
+    error = null;
+    try {
+      const res = await fetch('/api/admin/settings', {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        credentials: 'include',
+        body: JSON.stringify(settings),
+      });
+      if (!res.ok) throw new Error('Failed to save settings');
+      settings = await res.json();
+    } catch (err) {
+      error = err instanceof Error ? err.message : 'Failed to save';
+    } finally {
+      saving = false;
+    }
+  }
+
+  fetchSettings();
+</script>
+
+<div class="admin-auth">
+  <h2>Auth Settings</h2>
+
+  {#if loading}
+    <p class="admin-muted">Loading...</p>
+  {:else if settings}
+    <div class="admin-auth-fields">
+      <label class="admin-toggle">
+        <input type="checkbox" bind:checked={settings.auth.required} />
+        <span>Require sign-in</span>
+        <span class="admin-hint">When enabled, unauthenticated visitors see a sign-in wall.</span>
+      </label>
+
+      <label class="admin-toggle">
+        <input type="checkbox" bind:checked={settings.auth.guestAllowed} />
+        <span>Allow guest browsing</span>
+        <span class="admin-hint">When sign-in is required, guests can still browse with session-only data.</span>
+      </label>
+
+      <label class="admin-toggle">
+        <input type="checkbox" bind:checked={settings.auth.selfRegistration} />
+        <span>Self-registration</span>
+        <span class="admin-hint">Visitors can create their own accounts from the sign-in screen.</span>
+      </label>
+
+      <label class="admin-field">
+        <span>Session lifetime (hours)</span>
+        <input type="number" class="admin-input admin-input-sm" min="1" max="8760" bind:value={settings.auth.sessionTTL} />
+      </label>
+
+      <button type="button" class="admin-btn" onclick={save} disabled={saving}>
+        {saving ? 'Saving...' : 'Save'}
+      </button>
+    </div>
+
+    {#if error}
+      <div class="admin-error">{error}</div>
+    {/if}
+  {/if}
+</div>
+
+<style>
+  .admin-auth { padding: 24px; font-family: system-ui, sans-serif; color: var(--shell-fg); }
+  .admin-auth h2 { margin: 0 0 16px; font-size: 18px; }
+  .admin-auth-fields { display: flex; flex-direction: column; gap: 16px; max-width: 480px; }
+  .admin-toggle { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; cursor: pointer; }
+  .admin-toggle input { accent-color: var(--shell-accent, #7c7cf0); }
+  .admin-hint { flex-basis: 100%; font-size: 11px; color: var(--shell-fg-muted); margin-left: 24px; }
+  .admin-field { display: flex; flex-direction: column; gap: 4px; }
+  .admin-field span { font-size: 13px; }
+  .admin-input { padding: 8px 12px; background: var(--shell-bg); color: var(--shell-fg); border: 1px solid var(--shell-border); border-radius: var(--shell-radius, 6px); font-size: 13px; }
+  .admin-input-sm { max-width: 120px; }
+  .admin-btn { padding: 8px 16px; background: var(--shell-accent, #7c7cf0); color: var(--shell-bg); border: none; border-radius: var(--shell-radius, 6px); font-weight: 600; cursor: pointer; align-self: flex-start; }
+  .admin-btn:disabled { opacity: 0.6; cursor: not-allowed; }
+  .admin-error { margin-top: 8px; color: var(--shell-error, #d32f2f); font-size: 13px; }
+  .admin-muted { color: var(--shell-fg-muted); font-style: italic; }
+</style>

package/dist/admin/AuthSettingsView.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const AuthSettingsView: import("svelte").Component<Record<string, never>, {}, "">;
+type AuthSettingsView = ReturnType<typeof AuthSettingsView>;
+export default AuthSettingsView;

package/dist/admin/SystemView.svelte

@@ -0,0 +1,73 @@
+<script lang="ts">
+  /**
+   * Admin System view — server status and restart.
+   */
+
+  let version = $state('...');
+  let restarting = $state(false);
+  let restartError = $state<string | null>(null);
+
+  async function fetchVersion() {
+    try {
+      const res = await fetch('/api/version');
+      if (res.ok) {
+        const body = await res.json();
+        version = body.version;
+      }
+    } catch { /* ignore */ }
+  }
+
+  async function restart() {
+    restarting = true;
+    restartError = null;
+    try {
+      const res = await fetch('/api/admin/restart', {
+        method: 'POST',
+        credentials: 'include',
+      });
+      if (!res.ok) {
+        const body = await res.json().catch(() => ({}));
+        restartError = body.error || 'Restart failed';
+        restarting = false;
+      }
+      // If 202, server will restart — page will reconnect
+    } catch {
+      restartError = 'Network error';
+      restarting = false;
+    }
+  }
+
+  fetchVersion();
+</script>
+
+<div class="admin-system">
+  <h2>System</h2>
+
+  <div class="admin-system-info">
+    <div class="admin-system-row">
+      <span class="admin-system-label">Server version</span>
+      <span>{version}</span>
+    </div>
+  </div>
+
+  <div class="admin-system-actions">
+    <button type="button" class="admin-btn-danger" onclick={restart} disabled={restarting}>
+      {restarting ? 'Restarting...' : 'Restart server'}
+    </button>
+    {#if restartError}
+      <div class="admin-error">{restartError}</div>
+    {/if}
+  </div>
+</div>
+
+<style>
+  .admin-system { padding: 24px; font-family: system-ui, sans-serif; color: var(--shell-fg); }
+  .admin-system h2 { margin: 0 0 16px; font-size: 18px; }
+  .admin-system-info { margin-bottom: 24px; }
+  .admin-system-row { display: flex; gap: 12px; padding: 8px 0; border-bottom: 1px solid var(--shell-border, #3a3a5c); font-size: 13px; }
+  .admin-system-label { color: var(--shell-fg-subtle); min-width: 140px; }
+  .admin-system-actions { display: flex; flex-direction: column; gap: 8px; align-items: flex-start; }
+  .admin-btn-danger { padding: 8px 16px; background: transparent; color: var(--shell-error, #d32f2f); border: 1px solid var(--shell-error, #d32f2f); border-radius: var(--shell-radius, 6px); font-weight: 600; cursor: pointer; }
+  .admin-btn-danger:disabled { opacity: 0.6; cursor: not-allowed; }
+  .admin-error { color: var(--shell-error, #d32f2f); font-size: 13px; }
+</style>

package/dist/admin/SystemView.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const SystemView: import("svelte").Component<Record<string, never>, {}, "">;
+type SystemView = ReturnType<typeof SystemView>;
+export default SystemView;

package/dist/admin/UsersView.svelte

@@ -0,0 +1,189 @@
+<script lang="ts">
+  /**
+   * Admin Users view — list, create, edit, delete users.
+   */
+
+  import { getAuthHeader } from '../auth/index';
+  import type { AuthUser } from '../auth/types';
+
+  let users = $state<AuthUser[]>([]);
+  let loading = $state(true);
+  let error = $state<string | null>(null);
+
+  // Create form
+  let showCreate = $state(false);
+  let newUsername = $state('');
+  let newDisplayName = $state('');
+  let newPassword = $state('');
+  let newRole = $state<'admin' | 'user'>('user');
+  let createError = $state<string | null>(null);
+
+  // Edit state
+  let editingId = $state<string | null>(null);
+  let editDisplayName = $state('');
+  let editRole = $state<'admin' | 'user'>('user');
+  let editPassword = $state('');
+
+  async function fetchUsers() {
+    loading = true;
+    error = null;
+    try {
+      const res = await fetch('/api/admin/users', { credentials: 'include' });
+      if (!res.ok) throw new Error('Failed to fetch users');
+      users = await res.json();
+    } catch (err) {
+      error = err instanceof Error ? err.message : 'Failed to load users';
+    } finally {
+      loading = false;
+    }
+  }
+
+  async function createUser() {
+    createError = null;
+    try {
+      const res = await fetch('/api/admin/users', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        credentials: 'include',
+        body: JSON.stringify({
+          username: newUsername,
+          displayName: newDisplayName || newUsername,
+          password: newPassword,
+          role: newRole,
+        }),
+      });
+      if (!res.ok) {
+        const body = await res.json().catch(() => ({}));
+        createError = body.error || 'Failed to create user';
+        return;
+      }
+      newUsername = '';
+      newDisplayName = '';
+      newPassword = '';
+      newRole = 'user';
+      showCreate = false;
+      await fetchUsers();
+    } catch {
+      createError = 'Network error';
+    }
+  }
+
+  function startEdit(user: AuthUser) {
+    editingId = user.id;
+    editDisplayName = user.displayName;
+    editRole = user.role;
+    editPassword = '';
+  }
+
+  async function saveEdit() {
+    if (!editingId) return;
+    const patch: Record<string, unknown> = {
+      displayName: editDisplayName,
+      role: editRole,
+    };
+    if (editPassword.trim()) patch.password = editPassword;
+    try {
+      const res = await fetch(`/api/admin/users/${editingId}`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        credentials: 'include',
+        body: JSON.stringify(patch),
+      });
+      if (!res.ok) return;
+      editingId = null;
+      await fetchUsers();
+    } catch { /* ignore */ }
+  }
+
+  async function deleteUser(id: string) {
+    try {
+      await fetch(`/api/admin/users/${id}`, {
+        method: 'DELETE',
+        credentials: 'include',
+      });
+      await fetchUsers();
+    } catch { /* ignore */ }
+  }
+
+  fetchUsers();
+</script>
+
+<div class="admin-users">
+  <div class="admin-users-header">
+    <h2>Users</h2>
+    <button type="button" class="admin-btn" onclick={() => { showCreate = !showCreate; }}>
+      {showCreate ? 'Cancel' : 'New user'}
+    </button>
+  </div>
+
+  {#if showCreate}
+    <form class="admin-create-form" onsubmit={(e) => { e.preventDefault(); createUser(); }}>
+      <input class="admin-input" type="text" placeholder="Username" bind:value={newUsername} />
+      <input class="admin-input" type="text" placeholder="Display name" bind:value={newDisplayName} />
+      <input class="admin-input" type="password" placeholder="Password" bind:value={newPassword} />
+      <select class="admin-input" bind:value={newRole}>
+        <option value="user">User</option>
+        <option value="admin">Admin</option>
+      </select>
+      <button type="submit" class="admin-btn" disabled={!newUsername.trim() || !newPassword.trim()}>Create</button>
+      {#if createError}<div class="admin-error">{createError}</div>{/if}
+    </form>
+  {/if}
+
+  {#if loading}
+    <p class="admin-muted">Loading...</p>
+  {:else if error}
+    <p class="admin-error">{error}</p>
+  {:else}
+    <ul class="admin-user-list">
+      {#each users as user (user.id)}
+        <li class="admin-user-item">
+          {#if editingId === user.id}
+            <form class="admin-edit-form" onsubmit={(e) => { e.preventDefault(); saveEdit(); }}>
+              <input class="admin-input" type="text" bind:value={editDisplayName} />
+              <input class="admin-input" type="password" placeholder="New password (leave empty to keep)" bind:value={editPassword} />
+              <select class="admin-input" bind:value={editRole}>
+                <option value="user">User</option>
+                <option value="admin">Admin</option>
+              </select>
+              <div class="admin-edit-actions">
+                <button type="submit" class="admin-btn">Save</button>
+                <button type="button" class="admin-btn-secondary" onclick={() => { editingId = null; }}>Cancel</button>
+              </div>
+            </form>
+          {:else}
+            <div class="admin-user-info">
+              <span class="admin-user-name">{user.displayName}</span>
+              <span class="admin-user-meta">{user.username} · {user.role}</span>
+            </div>
+            <div class="admin-user-actions">
+              <button type="button" class="admin-btn-secondary" onclick={() => startEdit(user)}>Edit</button>
+              <button type="button" class="admin-btn-danger" onclick={() => deleteUser(user.id)}>Delete</button>
+            </div>
+          {/if}
+        </li>
+      {/each}
+    </ul>
+  {/if}
+</div>
+
+<style>
+  .admin-users { padding: 24px; font-family: system-ui, sans-serif; color: var(--shell-fg); }
+  .admin-users-header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 16px; }
+  .admin-users-header h2 { margin: 0; font-size: 18px; }
+  .admin-create-form, .admin-edit-form { display: flex; flex-direction: column; gap: 8px; margin-bottom: 16px; max-width: 400px; }
+  .admin-input { padding: 8px 12px; background: var(--shell-bg, #1a1a2e); color: var(--shell-fg); border: 1px solid var(--shell-border, #3a3a5c); border-radius: var(--shell-radius, 6px); font-size: 13px; }
+  .admin-btn { padding: 6px 14px; background: var(--shell-accent, #7c7cf0); color: var(--shell-bg); border: none; border-radius: var(--shell-radius, 6px); font-weight: 600; cursor: pointer; font-size: 13px; }
+  .admin-btn:disabled { opacity: 0.6; cursor: not-allowed; }
+  .admin-btn-secondary { padding: 6px 14px; background: transparent; color: var(--shell-fg-subtle); border: 1px solid var(--shell-border); border-radius: var(--shell-radius, 6px); cursor: pointer; font-size: 12px; }
+  .admin-btn-danger { padding: 6px 14px; background: transparent; color: var(--shell-error, #d32f2f); border: 1px solid var(--shell-error, #d32f2f); border-radius: var(--shell-radius, 6px); cursor: pointer; font-size: 12px; }
+  .admin-user-list { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 8px; }
+  .admin-user-item { display: flex; justify-content: space-between; align-items: center; padding: 12px 16px; background: var(--shell-bg-elevated, #252540); border: 1px solid var(--shell-border, #3a3a5c); border-radius: var(--shell-radius, 6px); }
+  .admin-user-info { display: flex; flex-direction: column; gap: 2px; }
+  .admin-user-name { font-weight: 600; }
+  .admin-user-meta { font-size: 11px; color: var(--shell-fg-subtle); }
+  .admin-user-actions { display: flex; gap: 6px; }
+  .admin-edit-actions { display: flex; gap: 6px; }
+  .admin-error { color: var(--shell-error, #d32f2f); font-size: 13px; }
+  .admin-muted { color: var(--shell-fg-muted); font-style: italic; }
+</style>

package/dist/admin/UsersView.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const UsersView: import("svelte").Component<Record<string, never>, {}, "">;
+type UsersView = ReturnType<typeof UsersView>;
+export default UsersView;

package/dist/admin/adminApp.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Built-in Admin app — user management, auth settings, and system controls.
+ * Framework-shipped: registered in host.ts during bootstrap.
+ * Admin-gated via manifest flag (ADR-011).
+ */
+import type { App } from '../apps/types';
+export declare const adminApp: App;

package/dist/admin/adminApp.js

@@ -0,0 +1,24 @@
+/**
+ * Built-in Admin app — user management, auth settings, and system controls.
+ * Framework-shipped: registered in host.ts during bootstrap.
+ * Admin-gated via manifest flag (ADR-011).
+ */
+export const adminApp = {
+    manifest: {
+        id: 'sh3-admin-app',
+        label: 'Admin',
+        version: '0.1.0',
+        requiredShards: ['sh3-admin'],
+        layoutVersion: 1,
+        admin: true,
+    },
+    initialLayout: {
+        type: 'tabs',
+        activeTab: 0,
+        tabs: [
+            { slotId: 'admin.users', viewId: 'sh3-admin:users', label: 'Users' },
+            { slotId: 'admin.auth', viewId: 'sh3-admin:auth', label: 'Auth' },
+            { slotId: 'admin.system', viewId: 'sh3-admin:system', label: 'System' },
+        ],
+    },
+};

package/dist/admin/adminShard.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { Shard } from '../shards/types';
+/** Module-level server URL, set during activate. */
+export declare let adminServerUrl: string;
+export declare const adminShard: Shard;

package/dist/admin/adminShard.svelte.js

@@ -0,0 +1,52 @@
+/*
+ * Admin shard — framework-shipped shard for user management,
+ * auth settings, and system controls.
+ *
+ * Contributes three views:
+ *   - `sh3-admin:users`  — user CRUD
+ *   - `sh3-admin:auth`   — auth settings toggles
+ *   - `sh3-admin:system` — restart + status
+ *
+ * `.svelte.ts` because mounting Svelte components requires rune access.
+ */
+import { mount, unmount } from 'svelte';
+import UsersView from './UsersView.svelte';
+import AuthSettingsView from './AuthSettingsView.svelte';
+import SystemView from './SystemView.svelte';
+/** Module-level server URL, set during activate. */
+export let adminServerUrl = '';
+export const adminShard = {
+    manifest: {
+        id: 'sh3-admin',
+        label: 'Admin',
+        version: '0.1.0',
+        views: [
+            { id: 'sh3-admin:users', label: 'Users' },
+            { id: 'sh3-admin:auth', label: 'Auth Settings' },
+            { id: 'sh3-admin:system', label: 'System' },
+        ],
+    },
+    activate(ctx) {
+        const usersFactory = {
+            mount(container, _context) {
+                const instance = mount(UsersView, { target: container });
+                return { unmount() { unmount(instance); } };
+            },
+        };
+        const authFactory = {
+            mount(container, _context) {
+                const instance = mount(AuthSettingsView, { target: container });
+                return { unmount() { unmount(instance); } };
+            },
+        };
+        const systemFactory = {
+            mount(container, _context) {
+                const instance = mount(SystemView, { target: container });
+                return { unmount() { unmount(instance); } };
+            },
+        };
+        ctx.registerView('sh3-admin:users', usersFactory);
+        ctx.registerView('sh3-admin:auth', authFactory);
+        ctx.registerView('sh3-admin:system', systemFactory);
+    },
+};

package/dist/api.d.ts

@@ -16,7 +16,8 @@ export type { RegistryIndex, PackageEntry, PackageVersion, RequiredDependency, I
 export type { ResolvedPackage } from './registry/client';
 export { fetchRegistries, fetchBundle, buildPackageMeta } from './registry/client';
 export { validateRegistryIndex } from './registry/schema';
-export { isAdmin, getAuthHeader } from './auth/index';
+export { isAdmin, isAuthenticated, isGuest, getUser, getAuthHeader } from './auth/index';
+export type { AuthUser, AuthSession, BootConfig } from './auth/types';
 /** Runtime feature flags for target-dependent behavior. */
 export declare const capabilities: {
     /** Whether this target supports hot-installing packages via dynamic import from blob URL. */

package/dist/api.js

@@ -38,7 +38,7 @@ export { registeredShards, activeShards } from './shards/activate.svelte';
 export { fetchRegistries, fetchBundle, buildPackageMeta } from './registry/client';
 export { validateRegistryIndex } from './registry/schema';
 // Admin mode (framework-internal components read admin status).
-export { isAdmin, getAuthHeader } from './auth/index';
+export { isAdmin, isAuthenticated, isGuest, getUser, getAuthHeader } from './auth/index';
 /** Runtime feature flags for target-dependent behavior. */
 export const capabilities = {
     /** Whether this target supports hot-installing packages via dynamic import from blob URL. */

package/dist/apps/lifecycle.d.ts

@@ -31,7 +31,12 @@ export declare function unloadApp(id: string): void;
  * refcount hold intact, and its view containers stay alive in the pool.
  * Launching the same app again is a root swap only.
  *
+ * Fires `suspend` hooks on all required shards (in order), then on the
+ * app itself. Any hook returning `false` cancels navigation — the user
+ * stays in the app. Returns `true` if navigation succeeded, `false` if
+ * cancelled.
+ *
  * Writes `null` to `__shell__:last-app` so reloading the page while on
  * home lands on home, not on the formerly-active app.
  */
-export declare function returnToHome(): void;
+export declare function returnToHome(): Promise<boolean>;

package/dist/apps/lifecycle.js

@@ -12,7 +12,7 @@
  * return-to-home (null). Boot reads it to decide whether to auto-launch.
  */
 import { createStateZones } from '../state/zones.svelte';
-import { activateShard, deactivateShard, registeredShards, } from '../shards/activate.svelte';
+import { activateShard, deactivateShard, getShardContext, registeredShards, } from '../shards/activate.svelte';
 import { attachApp, detachApp, switchToApp, switchToHome, } from '../layout/store.svelte';
 import { activeApp, getRegisteredApp } from './registry.svelte';
 import { createZoneManager } from '../state/manage';
@@ -69,7 +69,7 @@ function getOrCreateAppContext(appId) {
  * @throws If the app is not registered or a required shard is not registered.
  */
 export async function launchApp(id) {
-    var _a;
+    var _a, _b, _c;
     const app = getRegisteredApp(id);
     if (!app) {
         throw new Error(`Cannot launch app "${id}": not registered`);
@@ -82,6 +82,14 @@ export async function launchApp(id) {
         unloadApp(activeApp.id);
     }
     else if (activeApp.id === id) {
+        // Re-entering the same app from Home — fire resume hooks.
+        for (const shardId of app.manifest.requiredShards) {
+            const shard = registeredShards.get(shardId);
+            const shardCtx = getShardContext(shardId);
+            if (shard && shardCtx)
+                void ((_a = shard.resume) === null || _a === void 0 ? void 0 : _a.call(shard, shardCtx));
+        }
+        void ((_b = app.resume) === null || _b === void 0 ? void 0 : _b.call(app, getOrCreateAppContext(id)));
         switchToApp();
         writeLastApp(id);
         return;
@@ -99,7 +107,7 @@ export async function launchApp(id) {
     // Attach the layout (creates the workspace-zone proxy with version
     // gate) and run the app's optional activate hook.
     attachApp(app);
-    void ((_a = app.activate) === null || _a === void 0 ? void 0 : _a.call(app, getOrCreateAppContext(id)));
+    void ((_c = app.activate) === null || _c === void 0 ? void 0 : _c.call(app, getOrCreateAppContext(id)));
     activeApp.id = id;
     switchToApp();
     writeLastApp(id);
@@ -151,10 +159,26 @@ export function unloadApp(id) {
  * refcount hold intact, and its view containers stay alive in the pool.
  * Launching the same app again is a root swap only.
  *
+ * Fires `suspend` hooks on all required shards (in order), then on the
+ * app itself. Any hook returning `false` cancels navigation — the user
+ * stays in the app. Returns `true` if navigation succeeded, `false` if
+ * cancelled.
+ *
  * Writes `null` to `__shell__:last-app` so reloading the page while on
  * home lands on home, not on the formerly-active app.
  */
-export function returnToHome() {
+export async function returnToHome() {
+    const app = activeApp.id ? getRegisteredApp(activeApp.id) : null;
+    if (app) {
+        for (const shardId of app.manifest.requiredShards) {
+            const shard = registeredShards.get(shardId);
+            if ((shard === null || shard === void 0 ? void 0 : shard.suspend) && (await shard.suspend()) === false)
+                return false;
+        }
+        if (app.suspend && (await app.suspend()) === false)
+            return false;
+    }
     switchToHome();
     writeLastApp(null);
+    return true;
 }

package/dist/apps/registry.svelte.d.ts

@@ -14,8 +14,11 @@ export declare const activeApp: {
     id: string | null;
 };
 /**
- * Register an app with the framework. Must be called before `launchApp`.
- * Throws if an app with the same id is already registered.
+ * Register (or re-register) an app with the framework.
+ *
+ * If an app with the same id already exists it is silently replaced,
+ * which is the expected path during package updates — the new bundle is
+ * loaded and re-registered without requiring a full page reload.
  *
  * @param app - The app module to register.
  */

package/dist/apps/registry.svelte.js

@@ -21,17 +21,16 @@ export const registeredApps = $state(new Map());
  */
 export const activeApp = $state({ id: null });
 /**
- * Register an app with the framework. Must be called before `launchApp`.
- * Throws if an app with the same id is already registered.
+ * Register (or re-register) an app with the framework.
+ *
+ * If an app with the same id already exists it is silently replaced,
+ * which is the expected path during package updates — the new bundle is
+ * loaded and re-registered without requiring a full page reload.
  *
  * @param app - The app module to register.
  */
 export function registerApp(app) {
-    const id = app.manifest.id;
-    if (registeredApps.has(id)) {
-        throw new Error(`App "${id}" is already registered`);
-    }
-    registeredApps.set(id, app);
+    registeredApps.set(app.manifest.id, app);
 }
 /**
  * Reactive snapshot of all registered app manifests. Shell home iterates