docs: add preview mode documentation to auth README, react README, and changelogs

- packages/auth/README.md: Add Preview Mode section with usage, PreviewModeOptions table, PreviewBanner docs, and detection example
- packages/auth/README.md: Update useAuth hook docs with isPreviewMode and previewMode fields
- packages/auth/CHANGELOG.md: Add preview mode feature entries
- packages/react/README.md: Add useDiscovery hook docs with DiscoveryInfo and preview mode fields
- CHANGELOG.md: Add @objectstack v3.0.4 upgrade and preview mode feature entries

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **@objectstack v3.0.4 Upgrade**: Upgraded all `@objectstack/*` packages from `^3.0.2` to `^3.0.4` across 42 references
 - **@objectstack v3.0.0 Upgrade**: Upgraded all `@objectstack/*` packages from `^2.0.7` to `^3.0.0` across 13 package.json files
 - **Breaking change migrations**:
   - `Hub` namespace → `Cloud` in @object-ui/types re-exports
@@ -22,6 +23,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Preview Mode** (`@object-ui/auth`): New `previewMode` prop on `AuthProvider` for auto-login with simulated identity — skip login/registration for marketplace demos and app showcases. Includes `PreviewBanner` component, `isPreviewMode` / `previewMode` on `useAuth()`, and `PreviewModeOptions` type. Aligns with `@objectstack/spec` kernel `PreviewModeConfig`.
+- **Discovery Preview Detection** (`@object-ui/react`): Extended `DiscoveryInfo` with `mode` and `previewMode` fields for server-driven preview mode detection.
+- **Console Preview Support**: `ConditionalAuthWrapper` auto-detects `mode === 'preview'` from server discovery and configures auth accordingly.
 - **Console Bundle Optimization**: Split monolithic 3.7 MB main chunk into 17 granular cacheable chunks via `manualChunks` — main entry reduced from 1,008 KB gzip to 48.5 KB gzip (95% reduction)
 - **Gzip + Brotli Compression**: Pre-compressed assets via `vite-plugin-compression2` — Brotli main entry at 40 KB
 - **Bundle Analysis**: Added `rollup-plugin-visualizer` generating interactive treemap at `dist/stats.html`; new `build:analyze` script

packages/auth/CHANGELOG.md

@@ -6,6 +6,17 @@
 
 - @object-ui/types@3.0.1
 
+### Added
+
+- **Preview Mode** (`previewMode` prop on `AuthProvider`): Auto-login with simulated identity for marketplace demos and app showcases. Configurable role, display name, session expiry, read-only mode, and banner message.
+- **PreviewBanner** component: Renders a status banner when preview mode is active.
+- `isPreviewMode` and `previewMode` fields exposed on `AuthContextValue` / `useAuth()` hook.
+- New `PreviewModeOptions` type mirroring spec's `PreviewModeConfig`.
+
+### Changed
+
+- Upgraded `@objectstack/spec` from `^3.0.2` to `^3.0.4`.
+
 ## 3.0.0
 
 ### Minor Changes

packages/auth/README.md

@@ -10,6 +10,7 @@ Authentication system for Object UI — AuthProvider, guards, login/register for
 - 👤 **UserMenu** - Display authenticated user info with sign-out support
 - 🔑 **Auth Client Factory** - `createAuthClient` for pluggable backend integration
 - 🌐 **Authenticated Fetch** - `createAuthenticatedFetch` for automatic token injection
+- 👀 **Preview Mode** - Auto-login with simulated identity for marketplace demos and app showcases
 - 🎯 **Type-Safe** - Full TypeScript support with exported types
 
 ## Installation
@@ -71,9 +72,31 @@ Wraps your application with authentication context:
 Hook for accessing auth state and methods:
 
 ```tsx
-const { user, session, signIn, signOut, signUp, isAuthenticated, isLoading } = useAuth();
+const {
+  user,
+  session,
+  signIn,
+  signOut,
+  signUp,
+  isAuthenticated,
+  isLoading,
+  isPreviewMode,
+  previewMode,
+} = useAuth();
 ```
 
+| Property | Type | Description |
+| --- | --- | --- |
+| `user` | `AuthUser \| null` | Current authenticated user |
+| `session` | `AuthSession \| null` | Current session information |
+| `isAuthenticated` | `boolean` | Whether the user is authenticated |
+| `isLoading` | `boolean` | Whether auth state is loading |
+| `isPreviewMode` | `boolean` | Whether the app is running in preview mode |
+| `previewMode` | `PreviewModeOptions \| null` | Preview mode configuration (only set when `isPreviewMode` is true) |
+| `signIn` | `(email, password) => Promise` | Sign in with credentials |
+| `signOut` | `() => Promise` | Sign out the current user |
+| `signUp` | `(name, email, password) => Promise` | Register a new user |
+
 ### AuthGuard
 
 Protects children from unauthenticated access:
@@ -110,6 +133,75 @@ Creates a fetch wrapper that injects auth tokens into DataSource requests:
 const authedFetch = createAuthenticatedFetch({ getToken: () => session.token });
 ```
 
+## Preview Mode
+
+Preview mode allows visitors (e.g. marketplace customers) to explore the platform without registering or logging in. The `AuthProvider` auto-authenticates with a simulated user identity and bypasses login/registration screens.
+
+This feature aligns with the `PreviewModeConfig` from `@objectstack/spec/kernel` ([spec PR #676](https://github.com/objectstack-ai/spec/pull/676)).
+
+### Usage
+
+```tsx
+import { AuthProvider, PreviewBanner } from '@object-ui/auth';
+
+function App() {
+  return (
+    <AuthProvider
+      authUrl="/api/auth"
+      previewMode={{
+        simulatedRole: 'admin',
+        simulatedUserName: 'Demo Admin',
+        readOnly: false,
+        bannerMessage: 'You are exploring a demo — data will be reset periodically.',
+      }}
+    >
+      <PreviewBanner />
+      <Dashboard />
+    </AuthProvider>
+  );
+}
+```
+
+### PreviewModeOptions
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `autoLogin` | `boolean` | `true` | Auto-login as simulated user, skipping login/registration pages |
+| `simulatedRole` | `'admin' \| 'user' \| 'viewer'` | `'admin'` | Permission role for the simulated preview user |
+| `simulatedUserName` | `string` | `'Preview User'` | Display name for the simulated preview user |
+| `readOnly` | `boolean` | `false` | Restrict the preview session to read-only operations |
+| `expiresInSeconds` | `number` | `0` | Preview session duration in seconds (0 = no expiration) |
+| `bannerMessage` | `string` | — | Banner message displayed in the UI during preview mode |
+
+### PreviewBanner
+
+A component that renders a status banner when preview mode is active. Shows `bannerMessage` from the preview config, or a default message.
+
+```tsx
+import { PreviewBanner } from '@object-ui/auth';
+
+// Only renders when isPreviewMode is true
+<PreviewBanner />
+```
+
+### Detecting Preview Mode
+
+Use the `useAuth` hook to check if the app is in preview mode:
+
+```tsx
+function MyComponent() {
+  const { isPreviewMode, previewMode } = useAuth();
+
+  if (isPreviewMode && previewMode?.readOnly) {
+    // Disable write operations
+  }
+
+  return <div>...</div>;
+}
+```
+
+> **⚠️ Security:** Preview mode should **never** be used in production environments.
+
 ## License
 
 MIT

packages/react/README.md

@@ -112,6 +112,47 @@ function MyComponent() {
 }
 ```
 
+### useDiscovery
+
+Access server discovery information including preview mode detection:
+
+```tsx
+import { useDiscovery } from '@object-ui/react'
+
+function MyComponent() {
+  const { discovery, isLoading, isAuthEnabled } = useDiscovery()
+  
+  // Check if the server is in preview mode
+  if (discovery?.mode === 'preview') {
+    console.log('Preview mode active:', discovery.previewMode)
+  }
+
+  return <div>Server: {discovery?.name}</div>
+}
+```
+
+#### DiscoveryInfo
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Server name |
+| `version` | `string` | Server version |
+| `mode` | `string` | Runtime mode (e.g. `'development'`, `'production'`, `'preview'`) |
+| `previewMode` | `object` | Preview mode configuration (present when mode is `'preview'`) |
+| `services` | `object` | Service availability status (auth, data, metadata) |
+| `capabilities` | `string[]` | API capabilities |
+
+The `previewMode` object contains:
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `autoLogin` | `boolean` | `true` | Skip login/registration pages |
+| `simulatedRole` | `'admin' \| 'user' \| 'viewer'` | `'admin'` | Simulated user role |
+| `simulatedUserName` | `string` | `'Preview User'` | Display name |
+| `readOnly` | `boolean` | `false` | Read-only mode |
+| `expiresInSeconds` | `number` | `0` | Session duration (0 = no expiry) |
+| `bannerMessage` | `string` | — | UI banner message |
+
 ## API Reference
 
 See [full documentation](https://objectui.org/api/react) for detailed API reference.