Developers

What changed in each release

Features, fixes, and breaking changes across the shell, SDK, identity, admin, and storage.

v0.6.0

7 October 2026

Edit your name, sign in with a magic link, expose email settings to apps, and call init before the shell sends settings.

View release

✨ Feature

  • Account management: Edit your name and delete your account from Settings, under user account, on the Shellui identity backend.
  • Magic link login: The login page uses a magic link when no method is set, shows "Check your email", and waits 60s before another send.
  • Email service: Optional email.url and email.showInAdmin in shellui.config reach apps as settings.email.

🛠 Improvements

  • Transfers: Uploads share one progress toaster, and downloads continue after you leave Settings.

🚨 Changed

  • Iframe handshake (breaking): Call init from @shellui/sdk first, because the shell sends settings only after that request and only to frames that are ready.

📚 Documentation

  • Agent guidelines: Root AGENTS.md links the Shellui writing and design guidelines.

🐛 Bug Fixes

  • Session restore: Reloading keeps you signed in during local development, and the shell shows a loading state while the session restores.
  • Toasts: Bottom toast lists no longer block clicks on the page behind them.
  • Staff magic links: A staff account that opens an old email link sees "Sign in with your usual sign-in method instead."

🐛 Bug Fixes

  • Localhost iframe white screen: embedded companions now auto-trust the parent shell origin (same as tiny), so cross-origin dev (:4000 ↔ :5173) accepts SHELLUI_SETTINGS and await shellui.init() completes. Proactive SHELLUI_LAYOUT_CHROME posts no longer race about:blank.

🐛 Bug Fixes

  • OAuth callback / deep shell routes on static hosts: shellui build now materializes nested dist/web/<path>/index.html for built-in shell routes (/login, /login/callback, settings, legal, …) in addition to navigation paths, with rewriteRelativeAssetDepth so ./assets/… resolves correctly on GitHub Pages and similar hosts. Without this, /login/callback fell through to root 404.html and loaded assets from /login/assets/… → white page.

🛠 Improvements

  • identity-service 0.5.0 auth: shell and CLI complete OAuth via one-time shellui_auth_code → POST /api/v1/oauth/session (default delivery). Legacy URL-fragment bounce and provider ?code= exchange remain supported during rollout. Token refresh persists rotated refresh tokens; logout sends refresh for server-side revocation when available.

🔒 Security

  • Auth token storage (H-09 / M-17): split persisted session — profile metadata in localStorage, refresh token in tab-scoped sessionStorage, access token memory-only. Legacy shellui.auth.session auto-migrates.
  • Optional BFF auth: security.bffAuth.enabled routes /api/auth/{session,refresh,logout} through the shell host with HttpOnly refresh cookies (CLI dev + serve:dist). Identity-native cookie OAuth remains a documented follow-up.
  • Shell CSP: report-only by default with SHA-256 hash for the inline theme bootstrap; opt into enforcing via security.csp.enforce. See Security hardening.
  • Modal iframe allowlist: localhost origins are allowed only in development builds; production shells reject loopback modal URLs unless they match configured storage, admin, or same-origin targets. (#63)
  • Navigation route guard: routes with requiresStaff now show an access-forbidden view for signed-out and non-staff users (client-side UX guard; APIs must still enforce authorization). (#63)
  • Login branding panelUrl: restricted to same-origin relative paths, configured backend/login/storage origins, and loopback URLs in development only. Untrusted absolute URLs are ignored. (#63)
  • safeForAuthToken default is now opt-in (breaking): companion iframe apps no longer receive settings.accessToken unless their navigation item sets safeForAuthToken: true. First-party admin and storage file explorer frames are unchanged. The refresh token was never shared with companions and still is not. See Authentication — Iframe apps for migration.
  • StorageBridge trusted-frame gate (H-07): SHELLUI_STORAGE_REQUEST is honored only from registered iframe companions that pass the same trusted-frame policy as session JWT sharing (safeForAuthToken: true opt-in, admin URLs, storage.filesUrl). Untrusted senders receive 403 without storage I/O. Shared helpers live in features/security/trustedFrames.
  • postMessage hardening (H-06 / M-13 / M-14): inbound SHELLUI_ messages now require an allowed origin and a trusted source (registered iframe, parent shell, or same-window). Privileged companion commands (SHELLUI_LOGIN / LOGOUT, modal/drawer, toast/dialog, chrome actions, etc.) reject unregistered frames. Outbound SDK and shell replies use concrete target origins instead of ''. The Shellui host auto-derives companion origins from shellui.config.json navigation and storage URLs, plus optional security.allowedMessageOrigins for manual extras (preview/staging hosts, etc.). Standalone SDK embeds can still use shellui.configureMessageSecurity({ allowedOrigins: [...] }) or shellui.init({ allowedMessageOrigins: [...] }).
  • Track F (#65) — companion isolation + CLI hardening (M-18, L-10..L-14):

🐛 Bug Fixes

  • shellui init scaffolding: restore @shellui/cli in generated projects; pnpm build builds shell + app into deployable dist/web/ with relative / ${SHELLUI_APP_URL:-…} companion URLs; restore native framework boilerplate home (drop Welcome to Shellui); default layout: "fullscreen". Also fix deep-route relative asset paths after base: './', Next static export images.unoptimized, and stale template READMEs.

✨ Feature

  • Floating chrome actions (SDK): shellui.actions.set / clear declare optional back, title, trailing, and primary FAB chrome. The shell renders them (floating glass or windows title bar), posts SHELLUI_ACTION clicks into that iframe only, and clears on shell navigation. Caps: at most 3 trailing visible (rest in ···), at most 1 primary. See the chrome actions guide.
  • shellui init frameworks: Next.js, Nuxt, SvelteKit, and Alpine.js starters. Companions run on :3000 (Next/Nuxt) or :5173 (SvelteKit/Alpine). See framework starters.
  • Theming v1: curated OKLCH JSON themes (47, including Shellui, shadcn, and tweakcn), flexible config, and an Appearance theme selector. See themes.
  • Sidebar and app-bar layouts: shadcn sidebar with icon-collapse and rail (⌘B), drag-to-resize, and mobile sheet. App-bar is 42px chrome with text start links and icon end links. Inset twins use a padded, rounded main frame (layout: "sidebar-inset" / "app-bar-inset").
  • CLI companion: shellui start can spawn or follow a colocated app via dev.run / dev.url (or --run / --follow / --shell-only).
  • Identity-hosted login: authorize → callback → confirmation → token bounce. CLI shellui login opens the identity method picker (--provider skips it).
  • Host detection: isHomeScreenPwa(), isTauriRuntime(), and data-shellui-host tell Safari Home Screen installs apart from native WKWebView. iOS Home Screen PWAs skip stacked status scrims and theme-color. Tauri keeps controlled chrome and CSS safe-area. See browser PWA vs native iOS.

🛠 Improvements

  • Theme and i18n in starters: JS framework templates (react, vue, angular, next, nuxt, svelte, alpine) use @shellui/sdk/tiny with theme sync, en/fr language sync, and a Shellui-integrated home.
  • Desktop history buttons: back/forward stay available in Tauri fullscreen. App-bar shows them only in a live Tauri webview.

🚨 Changed

  • CSS variables are full colors (oklch(...) / hex) via var(--token). They are no longer HSL channel triples.
  • Official default theme is shellui (gold brand). AI-generated zinc/slate palettes are removed.
  • shellui init injects theme: "shellui".

🐛 Bug Fixes

  • Upload toaster: auto-dismiss ~2.5s after all uploads succeed. Stay open on failure so errors stay readable.
  • SDK layout chrome: inject .shellui-apply-layout-chrome-pad styles into the iframe app document so auto-padding works without shipping @shellui/core CSS.

🐛 Bug Fixes

  • Temporary fix for modalUrl undefined when the app is not localhost or same-domain: allow storage and admin.

✨ Feature

  • Administration panel: configure custom admin sidebar navigation via administration in shellui.config.ts (title, flat nav items, requiresStaff, openIn: 'external' for Django admin). Propagated to the admin app through SDK settings. (#6)
  • Storage: optional root storage.url / filesUrl in shellui.config.ts propagate as SDK settings.storage so Admin (and later the shell) can use storage-service. Admin shows Storage when storage.url is set. Settings → Storage shows the signed-in user's quota when storage.url is set; hide it with storage.showInSettings: false.
  • Storage SDK: iframe apps call shellui.storage (Supabase-like { data, error } API) for upload, download, list, move, and rename. Requests go to the root shell, which talks to storage-service with storage.url.
  • Company access pending UI: when identity-service blocks join (access_pending / access_denied), show an “account created, awaiting admin review” screen instead of a generic OAuth failure. Access is per company. (#15)

📚 Documentation

  • Document company access modes and pending-access UX in authentication docs. (#15)
  • Document Settings → Storage: only shown when storage is configured, and how to disable it with showInSettings.
  • Document the SDK file API (shellui.storage) with nested-folder samples.

🛠 Improvements

  • Improve login next params (#2)
  • Improve Tauri integration for developer experience (#9)

🐛 Bug Fixes

  • Default adminUrl value (#1)
  • Navigate via SDK fails on default URLs (#4)
  • Make Software update disabled by default and experimental (#5)

✨ Feature

  • Auth: support for Supabase and Shellui auth.
  • Legal documents: support for legalDocuments markdown content (privacyPolicy, termsOfService, legalNotice, dataProcessingAgreement).

🛠 Improvements

  • Router: route-aware login flow with next redirect support for smoother sign-in transitions.

✨ Feature

  • Application settings: navigation items can define a settings URL to show their own panel in Settings > Applications.
  • Layout: new app-bar layout with a 38px top bar: 9-square + current page name launcher (wrapping icon strip), Back/Forward on Tauri, and icon-only end links.
  • CLI: shellui init [root] creates a shellui.config.ts boilerplate (use --force to overwrite).

🛠 Improvements

  • Themes: default theme uses local fonts from static/fonts/ (Open Sans, Source Serif 4) instead of Google Fonts; theme docs updated for local font setup.
  • Navigation: support start_url to redirect / and navigation items with path "" or "/" as the start page.
  • Navigation: handle hash navigation for applications.
  • Improved Sentry error reporting integration.
  • CLI: shellui start --host exposes the dev server to the network.

🐛 Bug Fixes

  • iPad/Radix: fix modal/dialog buttons when using Apple Pencil or touch.

🔒 Security

  • Dependencies: update to address security issues.

✨ Feature

  • Multiple layout modes: sidebar navigation, fullscreen content view, and windows desktop mode with taskbar.
  • Flexible navigation menu with icons, grouped items, and customizable organization.
  • Open links in different ways: main content area, modal popups, side drawers, or external browser.
  • Side drawer panels that slide in from any direction (top, bottom, left, right).
  • Multi-language support with English and French translations.
  • Localized interface with translated navigation labels and UI text.
  • Custom themes with light and dark mode variants.
  • Custom fonts for headings and body text from external links or local files.
  • Toast notifications with multiple styles: success, error, warning, info, and loading states.
  • Alert dialogs with different button configurations (ok, ok/cancel, ok/cancel/secondary).
  • Modal windows for displaying content overlays.
  • Settings panel to customize appearance, language preferences, and privacy options.
  • Offline support and app updates through service worker.
  • Cookie consent management with categorized privacy controls.
  • Error reporting to help improve app stability.
  • Desktop app support for native applications.
  • Responsive design that adapts to mobile and desktop screens.
  • Customizable app branding with favicon and logo.
  • Software updates with version information and manual update checking in settings.
  • Customizable navigation item visibility for mobile and desktop.

Product releases from shellui/shellui (the homepage badge uses this version, not the website package). Upcoming work is on the roadmap. Full notes also live on GitHub.