@@ -0,0 +1,16 @@
+---
+'@object-ui/mobile': patch
+'@object-ui/console': patch
+---
+
+feat(mobile): native shell mode — the Console detects `window.ObjectStackNative` and talks to the ObjectStack mobile shell that hosts it
+
+Clause-②: yes (widening) — `@object-ui/mobile` is published and gains new exports; the seat writes the TIER_DEFAULT contract review.
+Metadata-protocol: none
+
+The ObjectStack mobile app hosts the web Console in a WebView and injects a bridge, `window.ObjectStackNative`, before the Console's scripts run (on older Android WebViews, possibly after them). The Console now knows when it is hosted.
+
+- **`@object-ui/mobile` gains the bridge type and detection.** `ObjectStackNative` types exactly the members of the shell's bridge contract (`version`, `platform`, `appVersion`, `capabilities`, `safeArea`, `has`, the five calls and the two events). `useNativeHost()` returns it, or `null` outside the shell; it reads the global lazily and re-checks at `DOMContentLoaded`, `load` and a few points after `load`, so a late injection still arrives. `getNativeHost()` is the same read outside React.
+- **Typed calls that never throw.** `nativeGetPushToken`, `nativeHaptic`, `nativeOpenExternal`, `nativeNavigate` and `nativeResetServer` check `has(capability)` and that the method exists, and resolve a `NativeCallResult`: `{ status: 'unavailable' }`, `{ status: 'ok', value }`, or `{ status: 'failed', code, message }`.
+- **Router wiring.** `useNativeHostRouting({ route, navigate })` posts `ready()` once per page load after the first route has rendered, posts `routeChanged(route)` once per route change, and answers the shell's cancelable `objectstack-native:navigate` window event by moving the router to `detail.route` (an in-app path only) and cancelling the event, so a notification tap does not reload the Console. Outside the shell it installs nothing.
+- **The Console uses it.** In the shell the Console posts those events from its router, marks the root element with `data-os-native-shell="ios|android"`, and drops the PWA install manifest. It adds no safe-area padding: the shell already pads its WebView. Without the global the Console behaves exactly as before.
@@ -12,8 +12,9 @@
  * with extra `<Route>` children.
  */
 
-import { lazy, Suspense, useMemo } from 'react';
-import { BrowserRouter, Routes, Route, Navigate, Outlet } from 'react-router-dom';
+import { lazy, Suspense, useEffect, useMemo } from 'react';
+import { BrowserRouter, Routes, Route, Navigate, Outlet, useLocation, useNavigate } from 'react-router-dom';
+import { useNativeHostRouting } from '@object-ui/mobile';
 import { AuthProvider, useAuth, createAuthenticatedFetch } from '@object-ui/auth';
 import { UploadProvider, createObjectStackUploadAdapter } from '@object-ui/providers';
 import { DevMasterDetail } from './dev/DevMasterDetail';
@@ -135,6 +136,35 @@ function resolveBasename(): string {
 
 const BASENAME = resolveBasename();
 
+/**
+ * Native shell mode: wires the router to the ObjectStack mobile shell when it
+ * hosts this Console (`window.ObjectStackNative`, see `@object-ui/mobile`).
+ *
+ * Rendered beside `<Routes>`, inside `ConsoleShell`'s Suspense boundary, so
+ * its first effect runs once the first route has committed, which is when
+ * `ready()` is posted. Every navigation posts `routeChanged` with the router's
+ * path, query and hash (the basename is already stripped), and the shell's
+ * `objectstack-native:navigate` event moves this router instead of reloading
+ * the page. `data-os-native-shell` on the root element names the platform, so
+ * a stylesheet can tell shell mode apart. Without the bridge this renders
+ * nothing and installs nothing.
+ */
+function NativeShellRouting() {
+  const location = useLocation();
+  const navigate = useNavigate();
+  const host = useNativeHostRouting({
+    route: `${location.pathname}${location.search}${location.hash}`,
+    navigate,
+  });
+  const platform = host?.platform;
+  useEffect(() => {
+    if (!platform) return undefined;
+    document.documentElement.setAttribute('data-os-native-shell', platform);
+    return () => document.documentElement.removeAttribute('data-os-native-shell');
+  }, [platform]);
+  return null;
+}
+
 /** Wraps `DefaultHomeLayout` so the FAB gets the signed-in user id. */
 function HomeRoute() {
   const { user } = useAuth();
@@ -211,6 +241,7 @@ export function App() {
         <FaviconSync />
         <UploadProvider adapter={uploadAdapter}>
         <ConsoleShell>
+          <NativeShellRouting />
           <Routes>
             {/*
               * Public auth surfaces — render OUTSIDE ProtectedRoute so
 
@@ -0,0 +1,188 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Native shell mode, as the real `App` wires it to its router.
+ *
+ * The ObjectStack mobile shell injects `window.ObjectStackNative` before the
+ * Console's scripts run. With a fake bridge installed before `App` renders,
+ * the Console must post `ready()` once, after the first route has rendered,
+ * post `routeChanged` with the router path on every navigation, and move its
+ * own router (no document reload) when the shell dispatches
+ * `objectstack-native:navigate`. Without the global, every one of those is
+ * absent: that is the control half of each case.
+ *
+ * `App` is the real module under the real `BrowserRouter`; the pages and the
+ * shell chrome are stubs, as in `App.docsPortalLazy.test.tsx`, because this
+ * file is about the router wiring, not about what the pages draw.
+ */
+
+import { describe, expect, it, vi, afterEach, beforeEach } from 'vitest';
+import { render, screen, cleanup, act } from '@testing-library/react';
+import type { ReactNode } from 'react';
+import {
+  NATIVE_HOST_GLOBAL,
+  NATIVE_NAVIGATE_EVENT,
+  resetNativeHostEventsForTests,
+  type ObjectStackNative,
+} from '../../../../packages/mobile/src/nativeHost';
+import { resetNativeHostWatchForTests } from '../../../../packages/mobile/src/useNativeHost';
+
+const { passthrough, stub } = vi.hoisted(() => {
+  const passthrough = ({ children }: { children?: ReactNode }) => <>{children}</>;
+  const stub = (testid: string) => () => <div data-testid={testid} />;
+  return { passthrough, stub };
+});
+
+vi.mock('@object-ui/app-shell', async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  ConsoleShell: passthrough,
+  ConsoleToaster: () => null,
+  LoadingScreen: stub('loading-screen'),
+  RedirectWithSplash: stub('redirect-with-splash'),
+  RequireAiSurface: passthrough,
+  SystemRedirect: () => null,
+  DefaultHomeLayout: passthrough,
+  DefaultHomePage: stub('home-page'),
+  DefaultOrganizationsLayout: passthrough,
+  DefaultOrganizationsPage: stub('organizations-page'),
+  DefaultOrganizationLayout: stub('organization-layout'),
+  DefaultMembersPage: stub('members-page'),
+  DefaultInvitationsPage: stub('invitations-page'),
+  DefaultSettingsPage: stub('settings-page'),
+  DefaultAcceptInvitationPage: stub('accept-invitation-page'),
+  DefaultAiChatPage: stub('ai-chat-page'),
+  StudioDesignSurface: stub('studio-design-surface'),
+  BuilderLanding: stub('builder-landing'),
+  getProductName: () => 'ObjectOS',
+  getFaviconUrl: () => '',
+}));
+
+vi.mock('@object-ui/auth', async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  AuthProvider: passthrough,
+  useAuth: () => ({ user: { id: 'u1' } }),
+}));
+
+vi.mock('../AppContent', () => ({
+  AppContent: stub('app-content'),
+  ConsolePermissionsScope: ({ children }: { children?: ReactNode }) => <>{children}</>,
+}));
+vi.mock('../components/ProtectedRoute', () => ({ ProtectedRoute: passthrough }));
+vi.mock('../components/RootLandingRedirect', () => ({ RootLandingRedirect: stub('root-landing') }));
+vi.mock('../components/SetupRoute', () => ({ SetupRoute: stub('setup-route') }));
+vi.mock('../components/FormPage', () => ({ FormPage: stub('form-page') }));
+vi.mock('../components/InternalFormRoute', () => ({ InternalFormRoute: stub('internal-form-route') }));
+vi.mock('../components/MetadataHmrReloader', () => ({ MetadataHmrReloader: () => null }));
+vi.mock('../pages/auth/LoginPage', () => ({ LoginPage: stub('login-page') }));
+vi.mock('../pages/auth/RegisterPage', () => ({ RegisterPage: stub('register-page') }));
+vi.mock('../pages/auth/ForgotPasswordPage', () => ({ ForgotPasswordPage: stub('forgot-page') }));
+vi.mock('../pages/auth/ResetPasswordPage', () => ({ ResetPasswordPage: stub('reset-page') }));
+vi.mock('../pages/auth/SetPasswordPage', () => ({ SetPasswordPage: stub('set-password-page') }));
+vi.mock('../pages/auth/VerifyEmailPage', () => ({ VerifyEmailPage: stub('verify-email-page') }));
+vi.mock('../pages/auth/VerifyEmailPromptPage', () => ({ VerifyEmailPromptPage: stub('verify-prompt-page') }));
+vi.mock('../pages/auth/OAuthConsentPage', () => ({ OAuthConsentPage: stub('oauth-consent-page') }));
+vi.mock('../pages/auth/DeviceAuthPage', () => ({ DeviceAuthPage: stub('device-auth-page') }));
+vi.mock('../dev/DevMasterDetail', () => ({ DevMasterDetail: stub('dev-master-detail') }));
+vi.mock('../dev/DevLists', () => ({ DevLists: stub('dev-lists') }));
+vi.mock('../dev/DevModal', () => ({ DevModal: stub('dev-modal') }));
+vi.mock('../dev/DevLookup', () => ({ DevLookup: stub('dev-lookup') }));
+vi.mock('../dev/DevRowActions', () => ({ DevRowActions: stub('dev-row-actions') }));
+vi.mock('sonner', () => ({ toast: { success: vi.fn(), error: vi.fn() } }));
+
+import { App } from '../App';
+
+/** The fake bridge: the contract's members, recording what the Console posts. */
+function installBridge() {
+  const events: string[] = [];
+  const bridge: ObjectStackNative = {
+    version: 1,
+    platform: 'android',
+    appVersion: '2.0.0',
+    capabilities: ['getPushToken', 'haptic', 'openExternal', 'navigate', 'resetServer'],
+    safeArea: { top: 24, bottom: 16, left: 0, right: 0 },
+    has: () => true,
+    getPushToken: async () => null,
+    haptic: async () => null,
+    openExternal: async () => null,
+    navigate: async () => null,
+    resetServer: async () => null,
+    // What the page shows at the moment `ready` arrives: the shell lifts its
+    // loading cover on it, so the first route must already be on screen.
+    ready: () => events.push(`ready:${screen.queryByTestId('login-page') ? 'login-page' : 'nothing'}`),
+    routeChanged: (route: string) => events.push(`route:${route}`),
+  };
+  (window as unknown as Record<string, unknown>)[NATIVE_HOST_GLOBAL] = bridge;
+  return events;
+}
+
+function dispatchNavigate(route: unknown): CustomEvent {
+  const event = new CustomEvent(NATIVE_NAVIGATE_EVENT, { cancelable: true, detail: { route } });
+  act(() => {
+    window.dispatchEvent(event);
+  });
+  return event;
+}
+
+beforeEach(() => {
+  resetNativeHostEventsForTests();
+  resetNativeHostWatchForTests();
+  window.history.pushState({}, '', '/login');
+});
+
+afterEach(() => {
+  cleanup();
+  delete (window as unknown as Record<string, unknown>)[NATIVE_HOST_GLOBAL];
+  window.history.pushState({}, '', '/');
+});
+
+describe('the Console in the mobile shell', () => {
+  it('posts ready once, after the first route rendered, and the route the router is on', async () => {
+    const events = installBridge();
+    render(<App />);
+    expect(await screen.findByTestId('login-page')).toBeInTheDocument();
+    expect(events).toEqual(['ready:login-page', 'route:/login']);
+    expect(document.documentElement.getAttribute('data-os-native-shell')).toBe('android');
+  });
+
+  it('the shell navigate event moves the router without a reload, and posts that route once', async () => {
+    const events = installBridge();
+    render(<App />);
+    await screen.findByTestId('login-page');
+    const before = window.history.length;
+
+    const event = dispatchNavigate('/register?from=push');
+    expect(event.defaultPrevented).toBe(true);
+    expect(await screen.findByTestId('register-page')).toBeInTheDocument();
+    // The router pushed a history entry: an SPA move, not a document load.
+    expect(window.location.pathname).toBe('/register');
+    expect(window.history.length).toBe(before + 1);
+    expect(events).toEqual(['ready:login-page', 'route:/login', 'route:/register?from=push']);
+  });
+
+  it('a route that is not an in-app path is left to the shell', async () => {
+    const events = installBridge();
+    render(<App />);
+    await screen.findByTestId('login-page');
+    const event = dispatchNavigate('//evil.example/register');
+    expect(event.defaultPrevented).toBe(false);
+    expect(window.location.pathname).toBe('/login');
+    expect(events).toEqual(['ready:login-page', 'route:/login']);
+  });
+});
+
+describe('control: the Console in a browser behaves as today', () => {
+  it('posts nothing, marks nothing, and leaves the navigate event alone', async () => {
+    render(<App />);
+    expect(await screen.findByTestId('login-page')).toBeInTheDocument();
+    expect(document.documentElement.hasAttribute('data-os-native-shell')).toBe(false);
+    const event = dispatchNavigate('/register');
+    expect(event.defaultPrevented).toBe(false);
+    expect(window.location.pathname).toBe('/login');
+  });
+});
@@ -9,7 +9,7 @@ import ReactDOM from 'react-dom/client';
 import './index.css';
 import { App } from './App';
 import { I18nProvider, preloadBootstrapLocale } from '@object-ui/i18n';
-import { MobileProvider, generatePWAManifest } from '@object-ui/mobile';
+import { MobileProvider, generatePWAManifest, getNativeHost } from '@object-ui/mobile';
 import { registerPlaceholders } from '@object-ui/components';
 import { initSentry, initRuntimeConfig, getProductName, getProductShortName, getFaviconUrl, getPwaDescription, getPwaThemeColor } from '@object-ui/app-shell';
 import { loadLanguage } from './loadLanguage';
@@ -133,27 +133,34 @@ Promise.all([
   // Generate a dynamic PWA manifest from runtime branding and inject it.
   // Blob URL replaces the static /manifest.json so PWA install prompts use
   // the branded name, short name, description, theme color, and favicon.
-  const manifestJson = generatePWAManifest({
-    enabled: true,
-    name: getProductName(),
-    shortName: getProductShortName(),
-    description: getPwaDescription(),
-    themeColor: getPwaThemeColor(),
-    backgroundColor: '#ffffff',
-    display: 'standalone',
-    startUrl: './',
-    scope: './',
-    orientation: 'any',
-    icons: [{ src: faviconUrl || './favicon.svg', sizes: 'any', type: 'image/svg+xml', purpose: 'any' }],
-  });
-  const blob = new Blob([JSON.stringify(manifestJson)], { type: 'application/json' });
-  const manifestUrl = URL.createObjectURL(blob);
+  // Inside the ObjectStack mobile shell (`window.ObjectStackNative`) the static
+  // manifest is removed and none is injected: the app is installed natively
+  // there, so an install manifest offers nothing. Read here, after the boot
+  // round-trips, not at module load; a bridge that lands even later only
+  // leaves the manifest in place, which a WebView never acts on.
   const existingManifest = document.querySelector<HTMLLinkElement>('link[rel="manifest"]');
   if (existingManifest) existingManifest.remove();
-  const manifestLink = document.createElement('link');
-  manifestLink.rel = 'manifest';
-  manifestLink.href = manifestUrl;
-  document.head.appendChild(manifestLink);
+  if (!getNativeHost()) {
+    const manifestJson = generatePWAManifest({
+      enabled: true,
+      name: getProductName(),
+      shortName: getProductShortName(),
+      description: getPwaDescription(),
+      themeColor: getPwaThemeColor(),
+      backgroundColor: '#ffffff',
+      display: 'standalone',
+      startUrl: './',
+      scope: './',
+      orientation: 'any',
+      icons: [{ src: faviconUrl || './favicon.svg', sizes: 'any', type: 'image/svg+xml', purpose: 'any' }],
+    });
+    const blob = new Blob([JSON.stringify(manifestJson)], { type: 'application/json' });
+    const manifestUrl = URL.createObjectURL(blob);
+    const manifestLink = document.createElement('link');
+    manifestLink.rel = 'manifest';
+    manifestLink.href = manifestUrl;
+    document.head.appendChild(manifestLink);
+  }
 
   // The two loaders wait for this page load's session answer. Signed in, they
   // read `/i18n` with the session's credentials; signed out, they request
 
@@ -11,6 +11,7 @@ Mobile optimization for Object UI — responsive hooks, gesture support, touch t
 - 📐 **Responsive Containers** - `ResponsiveContainer` for breakpoint-aware rendering
 - 🏗️ **MobileProvider** - Context provider for mobile-aware applications
 - 📲 **PWA Support** - Manifest generation and service worker registration
+- 🧩 **Native Shell Mode** - `useNativeHost` and typed calls into the ObjectStack mobile shell's bridge
 - ⚙️ **Configurable Breakpoints** - Customizable breakpoint definitions
 
 ## Installation
@@ -275,6 +276,51 @@ export const manifest = generatePWAManifest({
 void registerServiceWorker({ url: '/service-worker.js' });
 ```
 
+### Native shell mode
+
+The ObjectStack mobile app hosts the web Console in a WebView and injects a bridge,
+`window.ObjectStackNative`. Its presence is how a page knows it runs inside the
+shell; the bridge contract is owned by the mobile app (`docs/HYBRID-SHELL.md`,
+"Native bridge"), and `ObjectStackNative` types exactly its members.
+
+- `useNativeHost()` returns the bridge, or `null` outside the shell. It reads the
+  global lazily and re-checks at `DOMContentLoaded`, `load` and a few points after
+  `load`, so a bridge injected after the first render still arrives.
+- `useNativeHostRouting({ route, navigate })` wires a router to the shell: `ready()`
+  once per page load after the first commit, `routeChanged(route)` once per route
+  change, and the shell's cancelable `objectstack-native:navigate` window event moves
+  the router (in-app paths only) instead of reloading the page. Outside the shell it
+  installs nothing.
+- `nativeGetPushToken`, `nativeHaptic`, `nativeOpenExternal`, `nativeNavigate` and
+  `nativeResetServer` check `has(capability)` and that the method exists before
+  calling. They never throw: each resolves `{ status: 'unavailable' }` without the
+  capability, `{ status: 'ok', value }` on success, or
+  `{ status: 'failed', code, message }` when the shell refuses the call.
+
+```tsx
+import { nativeHaptic, useNativeHost } from '@object-ui/mobile';
+
+export function SaveButton({ onSave }: { onSave: () => Promise<void> }) {
+  const host = useNativeHost();
+  return (
+    <button
+      type="button"
+      onClick={async () => {
+        await onSave();
+        // Resolves { status: 'unavailable' } in a browser; nothing to branch on.
+        await nativeHaptic('success');
+      }}
+    >
+      {host ? 'Save' : 'Save changes'}
+    </button>
+  );
+}
+```
+
+The shell pads its WebView with the device safe area itself, so a page does not add
+padding in shell mode. The insets stay readable as the CSS variables
+`--os-native-safe-top|bottom|left|right` and as `useNativeHost()?.safeArea`.
+
 ## Links
 
 - 📦 [npm package](https://www.npmjs.com/package/@object-ui/mobile)