feat(kernel): add preview/demo runtime mode with auto-login and simulated identity

content/docs/references/kernel/context.mdx

@@ -14,8 +14,8 @@ Defines the operating mode of the kernel
 ## TypeScript Usage
 
 ```typescript
-import { KernelContext, RuntimeMode } from '@objectstack/spec/kernel';
-import type { KernelContext, RuntimeMode } from '@objectstack/spec/kernel';
+import { KernelContext, RuntimeMode, PreviewModeConfig } from '@objectstack/spec/kernel';
+import type { KernelContext, RuntimeMode, PreviewModeConfig } from '@objectstack/spec/kernel';
 
 // Validate data
 const result = KernelContext.parse(data);
@@ -30,13 +30,14 @@ const result = KernelContext.parse(data);
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **instanceId** | `string` | ✅ | Unique UUID for this running kernel process |
-| **mode** | `Enum<'development' \| 'production' \| 'test' \| 'provisioning'>` | ✅ | Kernel operating mode |
+| **mode** | `Enum<'development' \| 'production' \| 'test' \| 'provisioning' \| 'preview'>` | ✅ | Kernel operating mode |
 | **version** | `string` | ✅ | Kernel version |
 | **appName** | `string` | optional | Host application name |
 | **cwd** | `string` | ✅ | Current working directory |
 | **workspaceRoot** | `string` | optional | Workspace root if different from cwd |
 | **startTime** | `integer` | ✅ | Boot timestamp (ms) |
 | **features** | `Record<string, boolean>` | ✅ | Global feature toggles |
+| **previewMode** | `PreviewModeConfig` | optional | Preview/demo mode configuration (used when mode is `'preview'`) |
 
 
 ---
@@ -47,11 +48,56 @@ Kernel operating mode
 
 ### Allowed Values
 
-* `development`
-* `production`
-* `test`
-* `provisioning`
+* `development` — Hot-reload, verbose logging
+* `production` — Optimized, strict security
+* `test` — Mocked interfaces
+* `provisioning` — Setup/Migration mode
+* `preview` — Demo/preview mode — bypass auth, simulate admin identity
 
 
 ---
 
+## PreviewModeConfig
+
+Configures the kernel's preview/demo mode behaviour. When `mode` is set to `'preview'`, the platform
+skips authentication screens and simulates an admin identity so visitors can explore the system without
+registering or logging in.
+
+<Callout type="warn">
+**Security:** Preview mode should **never** be used in production environments.
+</Callout>
+
+### Properties
+
+| Property | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| **autoLogin** | `boolean` | `true` | Auto-login as simulated user, skipping login/registration pages |
+| **simulatedRole** | `Enum<'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** | `integer` | `0` | Preview session duration in seconds (0 = no expiration) |
+| **bannerMessage** | `string` | — | Banner message displayed in the UI during preview mode |
+
+### Example
+
+```typescript
+import { KernelContextSchema } from '@objectstack/spec/kernel';
+
+const ctx = KernelContextSchema.parse({
+ instanceId: '550e8400-e29b-41d4-a716-446655440000',
+ mode: 'preview',
+ version: '1.0.0',
+ cwd: '/app',
+ startTime: Date.now(),
+ previewMode: {
+ autoLogin: true,
+ simulatedRole: 'admin',
+ simulatedUserName: 'Demo Admin',
+ readOnly: false,
+ bannerMessage: 'You are exploring a demo — data will be reset periodically.',
+ },
+});
+```
+
+---
+

examples/README.md

@@ -152,14 +152,18 @@ pnpm build
 **Level:** 🔴 Advanced 
 **Protocols:** System, API, Data 
 
-**Complete server implementation** showing how to build a metadata-driven backend. Features dynamic schema loading from plugins, auto-generated REST APIs, unified metadata API, and plugin orchestration.
+**Complete server implementation** showing how to build a metadata-driven backend. Features dynamic schema loading from plugins, auto-generated REST APIs, unified metadata API, plugin orchestration, and **preview/demo mode**.
+
+**Preview Mode:** Run with `OS_MODE=preview` to bypass login/registration and simulate an admin identity — ideal for marketplace demos and app showcases.
 
 **Quick Start:**
 ```bash
 cd examples/app-host
 pnpm install
 pnpm dev
-# API available at http://localhost:3000
+
+# Preview mode (no login required)
+OS_MODE=preview pnpm dev
 ```
 
 ---
@@ -225,6 +229,7 @@ pnpm typecheck
 |----------|---------|----------|
 | Manifest | ✅ Complete | All examples with `objectstack.config.ts` |
 | Plugin System | ✅ Complete | [App Host](./app-host/) |
+| Preview Mode | ✅ Complete | [App Host](./app-host/) — `OS_MODE=preview` |
 | Datasources | 🟡 Partial | [App Host](./app-host/) |
 | I18n / Translations | ✅ Complete | [Todo Translations](./app-todo/src/translations/), [CRM Translations](./app-crm/src/translations/) |
 | Job Scheduling | 🔴 Missing | _Planned_ |

examples/app-host/README.md

@@ -9,6 +9,7 @@ It demonstrates how to build a metadata-driven backend that dynamically loads ob
 - **Unified Metadata API**: `/api/v1/meta/objects`
 - **Unified Data API**: `/api/v1/data/:object` (CRUD)
 - **Zero-Code Backend**: No creating routes or controllers per object.
+- **Preview Mode**: Run in demo mode — bypass login, auto-simulate admin identity.
 
 ## Setup
 
@@ -28,6 +29,62 @@ It demonstrates how to build a metadata-driven backend that dynamically loads ob
  # Expected: Server starts at http://localhost:3000
  ```
 
+3. Run in **preview mode** (skip login, simulate admin):
+ ```bash
+ OS_MODE=preview pnpm dev
+ # Expected: Server starts in preview mode — no login required
+ ```
+
+## Preview / Demo Mode
+
+Preview mode allows visitors (e.g. marketplace customers) to explore the platform
+without registering or logging in. The kernel boots with `mode: 'preview'` and the
+frontend skips authentication screens, automatically simulating an admin session.
+
+### How It Works
+
+1. The runtime reads `OS_MODE=preview` from the environment (or the stack config).
+2. The `KernelContext` is created with `mode: 'preview'` and a `previewMode` config.
+3. The frontend detects `mode === 'preview'` and:
+ - Hides the login / registration pages.
+ - Automatically creates a simulated admin session.
+ - Shows a preview banner to indicate demo mode.
+
+### Configuration
+
+```typescript
+import { KernelContextSchema } from '@objectstack/spec/kernel';
+
+const ctx = KernelContextSchema.parse({
+ instanceId: '550e8400-e29b-41d4-a716-446655440000',
+ mode: 'preview',
+ version: '1.0.0',
+ cwd: process.cwd(),
+ startTime: Date.now(),
+ previewMode: {
+ autoLogin: true, // Skip login/registration pages
+ simulatedRole: 'admin', // Simulated user role (admin | user | viewer)
+ simulatedUserName: 'Demo Admin',
+ readOnly: false, // Allow writes (set true for read-only demos)
+ expiresInSeconds: 3600, // Session expires after 1 hour (0 = no expiration)
+ bannerMessage: 'You are exploring a demo — data will be reset periodically.',
+ },
+});
+```
+
+### PreviewModeConfig Properties
+
+| Property | Type | Default | Description |
+|:---|:---|:---|:---|
+| **autoLogin** | `boolean` | `true` | Auto-login as simulated user, skip login/registration |
+| **simulatedRole** | `'admin' \| 'user' \| 'viewer'` | `'admin'` | Permission role for the simulated user |
+| **simulatedUserName** | `string` | `'Preview User'` | Display name shown in the UI |
+| **readOnly** | `boolean` | `false` | Block all write operations |
+| **expiresInSeconds** | `integer` | `0` | Session duration (0 = no expiration) |
+| **bannerMessage** | `string` | — | Banner message displayed in the UI |
+
+> **⚠️ Security:** Preview mode should NEVER be used in production environments.
+
 ## API Usage Examples
 
 ### 1. Get All Objects

examples/app-host/objectstack.config.ts

@@ -33,3 +33,65 @@ export default defineStack({
  new AppPlugin(BiPluginManifest)
  ]
 });
+
+/**
+ * Preview Mode Host Example
+ *
+ * Demonstrates how to run the platform in "preview" mode.
+ * When `mode` is set to `'preview'`, the kernel signals the frontend to:
+ * - Skip login/registration screens
+ * - Automatically simulate an admin identity
+ * - Display a preview-mode banner to the user
+ *
+ * Use this for marketplace demos, app showcases, or onboarding
+ * tours where visitors should explore the system without signing up.
+ *
+ * ## Usage
+ *
+ * Set the `OS_MODE` environment variable to `preview` at boot:
+ *
+ * ```bash
+ * OS_MODE=preview pnpm dev
+ * ```
+ *
+ * Or use this stack definition directly as a starting point.
+ *
+ * ## KernelContext (created by the Runtime at boot)
+ *
+ * ```ts
+ * import { KernelContextSchema } from '@objectstack/spec/kernel';
+ *
+ * const ctx = KernelContextSchema.parse({
+ * instanceId: '550e8400-e29b-41d4-a716-446655440000',
+ * mode: 'preview',
+ * version: '1.0.0',
+ * cwd: process.cwd(),
+ * startTime: Date.now(),
+ * previewMode: {
+ * autoLogin: true,
+ * simulatedRole: 'admin',
+ * simulatedUserName: 'Demo Admin',
+ * readOnly: false,
+ * bannerMessage: 'You are exploring a demo — data will be reset periodically.',
+ * },
+ * });
+ * ```
+ */
+export const PreviewHostExample = defineStack({
+ manifest: {
+ id: 'app-host-preview',
+ name: 'app_host_preview',
+ version: '1.0.0',
+ description: 'Host application in preview/demo mode — bypasses login, simulates admin user',
+ type: 'app',
+ },
+
+ // Same plugins as the standard host
+ plugins: [
+ new ObjectQLPlugin(),
+ new DriverPlugin(new InMemoryDriver()),
+ new AppPlugin(CrmApp),
+ new AppPlugin(TodoApp),
+ new AppPlugin(BiPluginManifest)
+ ]
+});

packages/spec/src/kernel/context.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect } from 'vitest';
 import {
  RuntimeMode,
  KernelContextSchema,
+ PreviewModeConfigSchema,
  type KernelContext,
 } from './context.zod';
 
@@ -11,6 +12,7 @@ describe('RuntimeMode', () => {
  expect(() => RuntimeMode.parse('production')).not.toThrow();
  expect(() => RuntimeMode.parse('test')).not.toThrow();
  expect(() => RuntimeMode.parse('provisioning')).not.toThrow();
+ expect(() => RuntimeMode.parse('preview')).not.toThrow();
  });
 
  it('should reject invalid runtime modes', () => {
@@ -87,10 +89,81 @@ describe('KernelContextSchema', () => {
  });
 
  it('should accept all runtime modes in context', () => {
- const modes = ['development', 'production', 'test', 'provisioning'] as const;
+ const modes = ['development', 'production', 'test', 'provisioning', 'preview'] as const;
  modes.forEach(mode => {
  const parsed = KernelContextSchema.parse({ ...validContext, mode });
  expect(parsed.mode).toBe(mode);
  });
  });
+
+ it('should accept preview mode with previewMode config', () => {
+ const parsed = KernelContextSchema.parse({
+ ...validContext,
+ mode: 'preview',
+ previewMode: {
+ autoLogin: true,
+ simulatedRole: 'admin',
+ simulatedUserName: 'Demo Admin',
+ readOnly: true,
+ expiresInSeconds: 3600,
+ bannerMessage: 'You are viewing a demo of this application.',
+ },
+ });
+ expect(parsed.mode).toBe('preview');
+ expect(parsed.previewMode?.autoLogin).toBe(true);
+ expect(parsed.previewMode?.simulatedRole).toBe('admin');
+ expect(parsed.previewMode?.simulatedUserName).toBe('Demo Admin');
+ expect(parsed.previewMode?.readOnly).toBe(true);
+ expect(parsed.previewMode?.expiresInSeconds).toBe(3600);
+ expect(parsed.previewMode?.bannerMessage).toContain('demo');
+ });
+
+ it('should accept context without previewMode (optional)', () => {
+ const parsed = KernelContextSchema.parse(validContext);
+ expect(parsed.previewMode).toBeUndefined();
+ });
+});
+
+describe('PreviewModeConfigSchema', () => {
+ it('should apply defaults for zero-config preview', () => {
+ const parsed = PreviewModeConfigSchema.parse({});
+ expect(parsed.autoLogin).toBe(true);
+ expect(parsed.simulatedRole).toBe('admin');
+ expect(parsed.simulatedUserName).toBe('Preview User');
+ expect(parsed.readOnly).toBe(false);
+ expect(parsed.expiresInSeconds).toBe(0);
+ expect(parsed.bannerMessage).toBeUndefined();
+ });
+
+ it('should accept all simulated roles', () => {
+ const roles = ['admin', 'user', 'viewer'] as const;
+ roles.forEach(role => {
+ const parsed = PreviewModeConfigSchema.parse({ simulatedRole: role });
+ expect(parsed.simulatedRole).toBe(role);
+ });
+ });
+
+ it('should reject invalid simulated role', () => {
+ expect(() => PreviewModeConfigSchema.parse({ simulatedRole: 'superadmin' })).toThrow();
+ });
+
+ it('should accept read-only preview for marketplace demos', () => {
+ const parsed = PreviewModeConfigSchema.parse({
+ autoLogin: true,
+ simulatedRole: 'viewer',
+ readOnly: true,
+ bannerMessage: 'This is a preview. Sign up to get started!',
+ });
+ expect(parsed.readOnly).toBe(true);
+ expect(parsed.simulatedRole).toBe('viewer');
+ expect(parsed.bannerMessage).toContain('preview');
+ });
+
+ it('should reject negative expiresInSeconds', () => {
+ expect(() => PreviewModeConfigSchema.parse({ expiresInSeconds: -1 })).toThrow();
+ });
+
+ it('should reject non-integer expiresInSeconds', () => {
+ expect(() => PreviewModeConfigSchema.parse({ expiresInSeconds: 1.5 })).toThrow();
+ });
 });