@mdxui/do 2.1.1 → 3.0.0

package/README.md

@@ -3,11 +3,11 @@
 [![npm version](https://img.shields.io/npm/v/@mdxui/do.svg)](https://www.npmjs.com/package/@mdxui/do)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-Admin interface for the .do platform - manage Durable Objects, Things, Relationships, Workflows, Agents, and Integrations.
+Admin interface for the .do platform - manage Durable Objects and Things with a full dashboard shell.
 
 ## What is @mdxui/do?
 
-`@mdxui/do` provides a React-based admin interface for the [.do platform](https://do.md). It enables you to manage semantic entities (Things), graph relationships, business process workflows, and autonomous AI agents. Built on TanStack Query, the library supports two operational modes: traditional REST API fetching or local-first reactive data with TanStack DB and WebSocket sync.
+`@mdxui/do` provides a React-based admin interface for the [.do platform](https://do.md). It includes a complete dashboard shell with routing, authentication (WorkOS AuthKit), and multiple view experiences: data browser, spreadsheet-style grid, document editor, and function executor. The library uses capnweb for RPC communication and `@mdxui/admin` for UI components.
 
 ## Installation
 
@@ -27,7 +27,46 @@ npm install react react-dom
 
 ## Quick Start
 
-Wrap your application with `DOProvider` and start using hooks to fetch and mutate data:
+### Complete Admin App
+
+The easiest way to get started is with the `DOApp` component:
+
+```tsx
+import { DOApp } from '@mdxui/do/app'
+
+function App() {
+  return (
+    <DOApp
+      config={{
+        do: {
+          apiEndpoint: 'https://api.example.do',
+          authMethod: 'jwt',
+          bindings: [],
+          realTimeUpdates: false,
+        },
+        identity: {
+          clientId: 'client_xxx',
+          devMode: true,
+        },
+        branding: {
+          name: 'My Admin',
+        },
+        defaultNamespace: 'production',
+      }}
+    />
+  )
+}
+```
+
+This provides a complete admin experience with:
+- Dashboard shell with sidebar navigation
+- WorkOS AuthKit authentication
+- URL-based routing (Things, Databases, Functions, etc.)
+- Multiple view modes (browser, grid, document, function)
+
+### Using the Provider Directly
+
+For custom UIs, wrap your app with `DOProvider`:
 
 ```tsx
 import { DOProvider, useThings, useCreateThing } from '@mdxui/do'
@@ -36,13 +75,11 @@ function App() {
   return (
     <DOProvider
       config={{
-        apiEndpoint: 'https://api.example.do/admin',
-        doUrl: 'wss://api.example.do/do/workspace',
+        apiEndpoint: 'https://api.example.do',
         authMethod: 'jwt',
         authToken: 'your-token',
         bindings: [],
-        realTimeUpdates: true,
-        collections: ['Task', 'User', 'Project'],
+        realTimeUpdates: false,
       }}
       initialNamespace="default"
     >
@@ -58,173 +95,210 @@ function TaskList() {
   if (isLoading) return <div>Loading...</div>
   if (error) return <div>Error: {error.message}</div>
 
-  const handleCreate = () => {
-    createThing.mutate({
-      ns: 'default',
-      type: 'Task',
-      name: 'New Task',
-      data: { status: 'todo', priority: 'medium' },
-    })
-  }
-
   return (
-    <div>
-      <button onClick={handleCreate} disabled={createThing.isLoading}>
-        Add Task
-      </button>
-      <ul>
-        {data?.data.map((task) => (
-          <li key={task.id}>{task.name}</li>
-        ))}
-      </ul>
-    </div>
+    <ul>
+      {data?.data.map((task) => (
+        <li key={task.id}>{task.name}</li>
+      ))}
+    </ul>
   )
 }
 ```
 
-## Core Concepts
+### Using the RPC Client Directly
 
-### Things
+Access the capnweb client instance for direct RPC calls:
 
-Things are semantic entities (nouns) that form the foundation of your data model. Each Thing has:
+```tsx
+import { useDO, useDOClient } from '@mdxui/do'
+
+function MyComponent() {
+  const { client, isConnected } = useDO()
+  // or just: const client = useDOClient()
+
+  const fetchData = async () => {
+    // Promise pipelining - efficient batched RPC calls
+    const [users, projects] = await Promise.all([
+      client.Thing.list({ type: 'User' }),
+      client.Thing.list({ type: 'Project' }),
+    ])
+    return { users, projects }
+  }
+}
+```
 
-- **Namespace (`ns`)**: Tenant or domain isolation (e.g., `"default"`, `"production"`)
-- **Type**: Entity classification (e.g., `"Task"`, `"User"`, `"Project"`)
-- **ID**: Unique identifier within namespace/type
-- **Data**: JSON-LD compatible payload with flexible schema
+## Shell Components
+
+### DOApp
+
+Complete routed application with authentication and navigation:
 
 ```tsx
-const { data } = useThings({ type: 'Task', nameSearch: 'urgent' })
-const { data: task } = useThing('default', 'Task', 'task-123')
+import { DOApp } from '@mdxui/do/app'
+
+<DOApp config={shellConfig} />
 ```
 
-### Relationships
+### DOShell
 
-Relationships form a semantic knowledge graph connecting Things using 64+ built-in predicates across temporal, spatial, directional, relational, and causal categories.
+Dashboard shell layout for custom routing setups:
 
 ```tsx
-// Fetch relationships for an entity
-const { data } = useEntityRelationships(
-  { ns: 'default', type: 'Task', id: 'task-1', semanticId: 'default/Task/task-1' },
-  'both'
-)
-
-// Create a relationship
-const createRelationship = useCreateRelationship()
-createRelationship.mutate({
-  relationshipType: 'dependsOn',
-  from: { ns: 'default', type: 'Task', id: 'task-2', semanticId: 'default/Task/task-2' },
-  to: { ns: 'default', type: 'Task', id: 'task-1', semanticId: 'default/Task/task-1' },
-})
+import { DOShell, DOShellNav } from '@mdxui/do/app'
+
+<DOShell>
+  <YourContent />
+</DOShell>
 ```
 
-### Workflows
+### AuthGate
 
-Workflows orchestrate multi-step business processes with support for:
+Authentication guard that shows sign-in when unauthenticated:
 
-- Event, schedule, manual, or webhook triggers
-- Function steps (Code, Generative, Agentic, Human)
-- Conditional branching and parallel execution
-- Saga pattern for compensation/rollback
+```tsx
+import { AuthGate } from '@mdxui/do/app'
+
+<AuthGate>
+  <ProtectedContent />
+</AuthGate>
+```
+
+## View Modes
+
+`@mdxui/do` provides four view experiences for managing Things:
+
+| View | Component | Description |
+|------|-----------|-------------|
+| **Data Browser** | `DataBrowserView` | Browse and search Things with filtering and sorting |
+| **Data Grid** | `DataGridView` | Spreadsheet-style editing with inline cell editing |
+| **Document Editor** | `DocumentEditorView` | Form-based editing for individual Things |
+| **Function Editor** | `FunctionEditorView` | Execute code/functions against the DO |
 
 ```tsx
-const { data: workflows } = useWorkflows({ status: ['active'] })
-const triggerWorkflow = useTriggerWorkflow('workflow-id')
+import { DataBrowserView, DataGridView, DocumentEditorView } from '@mdxui/do/views'
 
-// Trigger with input
-triggerWorkflow.mutate({ customerId: 'cust-123' })
+// Use individual views in your own layout
+function CustomAdmin() {
+  return (
+    <DOProvider config={config}>
+      <DataBrowserView />
+    </DOProvider>
+  )
+}
 ```
 
-### Agents
+## Core Concepts
+
+### Things
 
-Agents are autonomous AI workers derived from O*NET occupations and NAICS industries, creating 40,000+ potential agent types. They include:
+Things are semantic entities (nouns) that form the foundation of your data model:
 
-- System prompts and character bibles for persona
-- Tool access and guardrails for safety
-- Handoff rules for multi-agent coordination
-- Performance metrics and feedback collection
+- **Namespace (`ns`)**: Tenant or domain isolation
+- **Type**: Entity classification (e.g., `"Task"`, `"User"`)
+- **ID**: Unique identifier within namespace/type
+- **Data**: JSON-LD compatible payload
 
 ```tsx
-const { data: agents } = useAgents({ roleCategory: ['engineer'], status: ['active'] })
-const executeAgent = useExecuteAgent('agent-id')
+import { useThings, useThing, useCreateThing } from '@mdxui/do'
+
+// Fetch multiple Things with filtering
+const { data } = useThings({ type: 'Task', nameSearch: 'urgent' })
 
-executeAgent.mutate({
-  task: 'Review this pull request for security issues',
-  context: { prUrl: 'https://github.com/...' },
+// Fetch a single Thing
+const { data: task } = useThing('default', 'Task', 'task-123')
+
+// Create a new Thing
+const createThing = useCreateThing()
+createThing.mutate({
+  ns: 'default',
+  type: 'Task',
+  name: 'New Task',
+  data: { priority: 'high' },
 })
 ```
 
-## Dual Mode Operation
+### Schema Discovery
 
-`@mdxui/do` supports two operational modes depending on your configuration:
+Automatically discover available types and their schemas:
 
-| Mode | Configuration | Use Case | Features |
-|------|---------------|----------|----------|
-| **REST API** | `apiEndpoint` only | Traditional server-rendered apps | Standard fetch, server-side caching |
-| **TanStack DB** | `apiEndpoint` + `doUrl` | Real-time collaborative apps | Local-first, WebSocket sync, offline support |
+```tsx
+import { useSchema, useTypes, useNamespaces } from '@mdxui/do'
 
-### REST API Mode
+// Get all namespaces
+const { data: namespaces } = useNamespaces()
 
-```tsx
-<DOProvider
-  config={{
-    apiEndpoint: 'https://api.example.do/admin',
-    authMethod: 'jwt',
-    authToken: 'your-token',
-    bindings: [],
-    realTimeUpdates: false,
-  }}
->
-  {children}
-</DOProvider>
+// Get all types in a namespace
+const { data: types } = useTypes({ namespace: 'default' })
+
+// Get schema for a specific type
+const { data: schema } = useSchema('Task')
 ```
 
-### TanStack DB Mode (Recommended)
+### Real-time Subscriptions
+
+Subscribe to Thing changes for real-time updates:
 
 ```tsx
-<DOProvider
-  config={{
-    apiEndpoint: 'https://api.example.do/admin',
-    doUrl: 'wss://api.example.do/do/workspace',
-    authMethod: 'jwt',
-    authToken: 'your-token',
-    bindings: [],
-    realTimeUpdates: true,
-    collections: ['Task', 'User', 'Project'],
-    conflictStrategy: 'last-write-wins',
-    offline: { enabled: true, dbName: 'my-app-cache' },
-  }}
->
-  {children}
-</DOProvider>
+import { useThingSubscription, useSingleThingSubscription } from '@mdxui/do'
+
+// Subscribe to all Things of a type
+useThingSubscription({
+  type: 'Task',
+  onEvent: (event) => {
+    console.log('Thing changed:', event)
+  },
+})
+
+// Subscribe to a single Thing
+useSingleThingSubscription({
+  ns: 'default',
+  type: 'Task',
+  id: 'task-123',
+  onEvent: (event) => {
+    console.log('Task updated:', event)
+  },
+})
 ```
 
 ## Configuration
 
-### DOAdminConfig
+### DOShellConfig
 
-| Property | Type | Required | Default | Description |
-|----------|------|----------|---------|-------------|
-| `apiEndpoint` | `string` | Yes | - | Base URL for REST API calls |
-| `doUrl` | `string` | No | - | WebSocket URL for Durable Object sync (enables TanStack DB mode) |
-| `authMethod` | `'jwt' \| 'api-key' \| 'oauth'` | Yes | - | Authentication method |
-| `authToken` | `string` | No | - | JWT token or API key |
-| `bindings` | `DOBinding[]` | Yes | - | Available Durable Object bindings |
-| `realTimeUpdates` | `boolean` | Yes | - | Enable real-time data updates |
-| `wsEndpoint` | `string` | No | - | Legacy WebSocket endpoint (prefer `doUrl`) |
-| `conflictStrategy` | `'last-write-wins' \| 'merge' \| ConflictResolver` | No | `'last-write-wins'` | How to resolve sync conflicts |
-| `offline` | `OfflineConfig` | No | - | Offline persistence settings |
-| `collections` | `string[]` | No | - | Entity types to auto-sync |
+Configuration for the complete `DOApp`:
 
-### DOProviderProps
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `do` | `DOAdminConfig` | Yes | RPC and API configuration |
+| `identity` | `DOIdentity` | Yes | WorkOS AuthKit configuration |
+| `basePath` | `string` | No | Base URL path for routing |
+| `defaultNamespace` | `string` | No | Initial namespace |
+| `branding` | `{ name?, logo? }` | No | Custom branding |
+| `theme` | `{ mode? }` | No | Theme preference (light/dark/system) |
+| `routes` | `Record<string, boolean>` | No | Enable/disable specific routes |
+
+### DOAdminConfig
 
 | Property | Type | Required | Default | Description |
 |----------|------|----------|---------|-------------|
-| `config` | `DOAdminConfig` | Yes | - | Admin configuration |
-| `initialNamespace` | `string` | No | `'default'` | Starting namespace |
-| `userId` | `string` | No | - | Current user ID |
-| `children` | `ReactNode` | Yes | - | Child components |
-| `queryClient` | `QueryClient` | No | - | Custom TanStack Query client |
+| `apiEndpoint` | `string` | Yes | - | Base URL for API calls |
+| `rpcUrl` | `string` | No | `${apiEndpoint}/rpc` | Explicit RPC URL for capnweb session |
+| `authMethod` | `'none' \| 'jwt' \| 'api-key' \| 'oauth'` | Yes | - | Authentication method |
+| `authToken` | `string` | No | - | JWT token or API key |
+| `bindings` | `DOBinding[]` | Yes | - | Durable Object bindings |
+| `realTimeUpdates` | `boolean` | Yes | - | Enable real-time updates via RPC subscriptions |
+| `clientType` | `'capnweb' \| 'json-rpc'` | No | `'capnweb'` | RPC client type |
+| `requestTimeout` | `number` | No | `30000` | Request timeout in ms |
+| `skipHealthCheck` | `boolean` | No | `false` | Skip health check on connection |
+| `healthCheckRetries` | `number` | No | `3` | Number of health check retries |
+
+### DOIdentity
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `clientId` | `string` | Yes | WorkOS client ID |
+| `apiHostname` | `string` | No | WorkOS API hostname |
+| `devMode` | `boolean` | No | Enable development mode |
+| `redirectUri` | `string` | No | OAuth redirect URI |
 
 ## Available Hooks
 
@@ -232,179 +306,92 @@ executeAgent.mutate({
 
 | Hook | Description |
 |------|-------------|
-| `useDO()` | Access the DO context (config, namespace, connection status) |
-| `useDOUrls()` | Get derived URLs (rpcUrl, syncUrl, apiEndpoint) |
-| `useSyncStatus()` | Get current sync status (`'disconnected'`, `'connecting'`, `'syncing'`, `'synced'`, `'error'`) |
+| `useDO()` | Access DO context (config, namespace, client, connection state) |
+| `useDOClient()` | Access the capnweb client instance directly |
+| `useDOUrls()` | Get derived URLs (rpcUrl, apiEndpoint) |
+| `useIdentity()` | Access WorkOS auth state (from AuthKit) |
+| `useDOShell()` | Access shell config and navigation state |
 
 ### Things Hooks
 
 | Hook | Description |
 |------|-------------|
-| `useThings(filter?, sort?, pagination?)` | Fetch a paginated list of Things |
-| `useThing(ns, type, id)` | Fetch a single Thing by semantic ID |
+| `useThings(filter?)` | Fetch paginated Things with filtering |
+| `useThing(ns, type, id)` | Fetch a single Thing |
 | `useThingVersions(ns, type, id)` | Fetch version history for a Thing |
-| `useTypeStats(ns, type)` | Fetch statistics for a Thing type |
+| `useTypeStats(type)` | Fetch statistics for a Thing type |
 | `useCreateThing()` | Create a new Thing |
 | `useUpdateThing(ns, type, id)` | Update an existing Thing |
-| `useDeleteThing(ns, type, id)` | Soft or hard delete a Thing |
+| `useDeleteThing(ns, type, id)` | Delete a Thing |
 
-### Relationships Hooks
+### Discovery Hooks
 
 | Hook | Description |
 |------|-------------|
-| `useRelationships(filter?)` | Fetch relationships with optional filters |
-| `useEntityRelationships(entity, direction?)` | Fetch relationships for a specific entity |
-| `useGraphTraversal(entity, pattern)` | Traverse the graph from a starting entity |
-| `useGraphStats()` | Fetch graph statistics |
-| `useCreateRelationship()` | Create a new relationship |
-| `useDeleteRelationship()` | Delete a relationship |
-
-### Workflows Hooks
+| `useSchema(type)` | Get schema for a Thing type |
+| `useSchemaDefinition(type)` | Get detailed schema definition |
+| `useNamespaces()` | List available namespaces |
+| `useTypes(options?)` | List available Thing types |
 
-| Hook | Description |
-|------|-------------|
-| `useWorkflows(filter?)` | Fetch workflows with optional filters |
-| `useWorkflow(id)` | Fetch a single workflow |
-| `useWorkflowExecutions(filter?)` | Fetch workflow executions |
-| `useWorkflowExecution(id)` | Fetch a single execution (auto-refetch while running) |
-| `useCreateWorkflow()` | Create a new workflow |
-| `useUpdateWorkflow(id)` | Update an existing workflow |
-| `useTriggerWorkflow(id)` | Manually trigger a workflow |
-| `useCancelExecution()` | Cancel a running execution |
-| `useDeleteWorkflow()` | Delete a workflow |
-
-### Agents Hooks
+### Subscription Hooks
 
 | Hook | Description |
 |------|-------------|
-| `useAgents(filter?)` | Fetch agents with optional filters |
-| `useAgent(id)` | Fetch a single agent |
-| `useAgentMetrics(id, periodDays?)` | Fetch performance metrics for an agent |
-| `useAgentExecutions(filter?)` | Fetch agent executions |
-| `useAgentExecution(id)` | Fetch a single execution (auto-refetch while running) |
-| `useCreateAgent()` | Create a new agent |
-| `useUpdateAgent(id)` | Update an existing agent |
-| `useExecuteAgent(id)` | Execute an agent with a task |
-| `useSubmitAgentFeedback(executionId)` | Submit feedback for an execution |
-| `useDeleteAgent()` | Delete an agent |
+| `useThingSubscription(options)` | Subscribe to Thing changes |
+| `useSingleThingSubscription(options)` | Subscribe to a single Thing |
 
-## Query Keys
-
-Each hook module exports query key factories for cache management:
+## Subpath Exports
 
 ```tsx
-import { thingsKeys, relationshipsKeys, workflowsKeys, agentsKeys } from '@mdxui/do/hooks'
-import { useQueryClient } from '@tanstack/react-query'
-
-const queryClient = useQueryClient()
+// Full package - types, providers, hooks, components, views, app
+import { DOProvider, useThings, DOApp } from '@mdxui/do'
 
-// Invalidate all things queries
-queryClient.invalidateQueries({ queryKey: thingsKeys.all })
+// App components - DOApp, DOShell, pages, routes
+import { DOApp, DOShell, DOShellNav, AuthGate } from '@mdxui/do/app'
 
-// Invalidate a specific thing
-queryClient.invalidateQueries({ queryKey: thingsKeys.detail('default', 'Task', 'task-1') })
+// Providers - DOProvider and context hooks
+import { DOProvider, useDO, useDOClient } from '@mdxui/do/providers'
 
-// Invalidate all workflow executions
-queryClient.invalidateQueries({ queryKey: workflowsKeys.executions() })
-```
+// Hooks - all data fetching hooks
+import { useThings, useSchema, useNamespaces } from '@mdxui/do/hooks'
 
-## Components
+// Things-specific hooks
+import { useThings, useCreateThing } from '@mdxui/do/hooks/things'
 
-The package includes pre-built UI components:
+// Views - the 4 view experiences
+import { DataBrowserView, DataGridView } from '@mdxui/do/views'
 
-```tsx
-import { DOShell, DOSidebar, DOHeader, ThingsList, StatsCards, ErrorBoundary } from '@mdxui/do/components'
-```
+// Components - UI components
+import { ErrorBoundary } from '@mdxui/do/components'
 
-| Component | Description |
-|-----------|-------------|
-| `DOShell` | Main application shell with sidebar and header |
-| `DOSidebar` | Navigation sidebar with customizable items |
-| `DOHeader` | Application header with namespace selector |
-| `ThingsList` | Data table for displaying Things |
-| `StatsCards` | Dashboard statistics cards |
-| `ErrorBoundary` | Error boundary with fallback UI |
+// Types - TypeScript types
+import type { Thing, DOAdminConfig, ThingFilter } from '@mdxui/do/types'
 
-## Types
+// Schemas - Zod schemas for validation
+import { ThingSchema, ThingFilterSchema } from '@mdxui/do/schemas'
 
-Import types for TypeScript projects:
-
-```tsx
-import type {
-  // Things
-  Thing,
-  ThingFilter,
-  ThingCreateInput,
-  ThingUpdateInput,
-  ThingQueryResult,
-
-  // Relationships
-  Relationship,
-  SemanticPredicate,
-  EntityReference,
-  GraphTraversalResult,
-
-  // Workflows
-  Workflow,
-  WorkflowExecution,
-  WorkflowStep,
-
-  // Agents
-  Agent,
-  AgentExecution,
-  AgentMetrics,
-
-  // Config
-  DOAdminConfig,
-  DOBinding,
-  SyncStatus,
-} from '@mdxui/do/types'
+// Lib - utilities
+import { cn, formatDate, APIError } from '@mdxui/do/lib'
 ```
 
-## Subpath Exports
+## Architecture
 
-The package provides granular imports for tree-shaking:
-
-```tsx
-// Full package
-import { DOProvider, useThings, Thing } from '@mdxui/do'
-
-// Just providers
-import { DOProvider, useDO } from '@mdxui/do/providers'
-
-// Just hooks
-import { useThings, useAgents } from '@mdxui/do/hooks'
-
-// Just components
-import { DOShell, ThingsList } from '@mdxui/do/components'
-
-// Just types
-import type { Thing, Agent } from '@mdxui/do/types'
 ```
-
-## Error Handling
-
-The package provides type guards for handling API errors:
-
-```tsx
-import { isValidationErrorData, isNotFoundError, isRateLimitError, isAppError } from '@mdxui/do/types'
-
-try {
-  await createThing.mutateAsync({ /* ... */ })
-} catch (error) {
-  if (isAppError(error)) {
-    if (isValidationErrorData(error)) {
-      // Handle validation errors (API response data)
-      error.errors.forEach(e => console.log(e.field, e.message))
-    } else if (isNotFoundError(error)) {
-      // Handle not found
-      console.log(`${error.resourceType}/${error.resourceId} not found`)
-    } else if (isRateLimitError(error)) {
-      // Handle rate limiting
-      console.log(`Retry after ${error.retryAfter}ms`)
-    }
-  }
-}
+@mdxui/do
+├── app/           # DOApp, DOShell, pages, routes, auth
+├── providers/     # DOProvider, context hooks
+├── hooks/         # Data fetching hooks (Things, Schema, etc.)
+├── views/         # View components (Browser, Grid, Document, Function)
+├── components/    # Shared UI components
+├── types/         # TypeScript types + Zod schemas
+└── lib/           # Utilities (cn, errors, formatters)
+
+Dependencies:
+├── capnweb              # Binary RPC over HTTP
+├── @workos-inc/authkit  # Authentication
+├── @mdxui/admin         # UI components
+├── @mdxui/primitives    # Base UI primitives
+└── @tanstack/react-query # Data fetching & caching
 ```
 
 ## License