primitive-app 1.0.2

package/README.md

@@ -0,0 +1,1202 @@
+# primitive-app
+
+Primitive App is a **Vue 3–first helper library** that wires a Vue + Pinia + vue-router application into **js-bao-wss-client** with a cohesive set of:
+
+- **Bootstrapping helpers** (`createPrimitiveApp`)
+- **Routing & auth helpers** (`createPrimitiveRouter`, `PrimitiveRouterMeta`)
+- **Stores** (app config, user, navigation, breadcrumbs, document stores)
+- **Layouts & components** (`PrimitiveAppLayout`, auth layouts, navigation & document shells)
+- **Data-loading composables** (`useJsBaoDataLoader`)
+- **Debugging & test harness utilities** (Document Debugger, Test Runner)
+
+It is designed to be used in apps that already provide:
+
+- Vue 3
+- Pinia
+- vue-router
+- Tailwind (or compatible utility CSS)
+- `js-bao-wss-client` (and `js-bao` models in your app)
+
+For concrete examples, see the demo app available at https://primitive-app-demo.primitive.app/
+
+## It's recommended that apps wanting to use this library start by cloning https://github.com/Primitive-Labs/primitive-app-template
+
+## Documentation
+
+For guides and API reference docs, see **Primitive Docs**: https://primitive-labs.github.io/primitive-docs/
+
+## High-level architecture
+
+At a high level, `primitive-app` provides:
+
+- **Bootstrapping**
+  - `createPrimitiveApp` – mount your Vue app, wire in Pinia and vue-router, set up js-bao, and initialize shared stores.
+- **Routing & auth**
+  - `createPrimitiveRouter`, `AuthLevel`, `PrimitiveRouterMeta` – auth-guarded routes with breadcrumb metadata.
+- **Stores**
+  - Configuration: `useAppConfigStore`, `useNavigationStore`, `useBreadcrumbsStore`
+  - User: `useUserStore`
+  - Documents: `useJsBaoDocumentsStore`, `useSingleDocumentStore`, `useMultiDocumentStore`
+- **Layouts & components**
+  - `PrimitiveAppLayout`, `PrimitiveLoginLayout`, `PrimitiveStaticLayout`, navigation components, document management components, shared utilities.
+- **Data loading**
+  - `useJsBaoDataLoader` – standard pattern for loading data (typically js-bao models) with subscriptions and a document readiness gate.
+- **Debugging & test harness**
+  - `PrimitiveDebuggingSuite`, `PrimitiveTestRunner`, `DocumentDebugger`, and related pages for app-level integration tests and data inspection.
+
+---
+
+## Bootstrapping with `createPrimitiveApp`
+
+The recommended way to start a new app is to let `primitive-app` own the **initialization order**:
+
+1. Initialize js-bao and the user store.
+2. Initialize app config.
+3. Wire the document store (single-document, multi-document, or none).
+4. Wire breadcrumbs to the router.
+5. Wire navigation to the router.
+6. Mount your root component.
+
+```ts
+// src/main.ts
+import { createPrimitiveApp } from "primitive-app";
+import App from "./App.vue";
+import router from "./router/routes";
+import { getAppConfig, getSingleDocumentConfig } from "./config/appConfig";
+import { getJsBaoConfig, getLogLevel } from "./config/envConfig";
+import { getNavigationConfig } from "./config/navigationConfig";
+
+void createPrimitiveApp({
+  mainComponent: App,
+  router,
+  getAppConfig,
+  getJsBaoConfig,
+  getNavigationConfig,
+  getSingleDocumentConfig,
+  loginUrl: "/login",
+  getLogLevel,
+});
+```
+
+### `PrimitiveAppBootstrapOptions`
+
+`createPrimitiveApp` accepts:
+
+- **mainComponent**: your root Vue component (often `App.vue`).
+- **router**: a `vue-router` instance (typically created via `createPrimitiveRouter`, see below).
+- **getAppConfig**: `() => InitializeAppConfigOptions`
+- **getJsBaoConfig**: `() => JsBaoClientOptions` (from `js-bao-wss-client`)
+- **getNavigationConfig?**: `() => NavigationConfig`
+- **getSingleDocumentConfig?**: `() => InitializeSingleDocumentOptions`
+- **loginUrl**: path to your login route (e.g. `"/login"`), used by auth flows.
+- **getLogLevel?**: `() => LogLevel` – overrides internal logging defaults.
+- **mountTarget?**: CSS selector or DOM element (defaults to `"#app"`).
+
+> **Note:** The `documentStoreMode` in your `getAppConfig` determines which document store(s) are initialized:
+>
+> - `DocumentStoreMode.None`: No document store is initialized.
+> - `DocumentStoreMode.SingleDocument` or `DocumentStoreMode.SingleDocumentWithSwitching`: Requires `getSingleDocumentConfig`.
+> - `DocumentStoreMode.MultiDoc`: Initializes `jsBaoDocumentsStore` on auth; apps register collections dynamically via `multiDocumentStore.registerCollection()`.
+
+---
+
+## Routing & auth: `createPrimitiveRouter` and `PrimitiveRouterMeta`
+
+Primitive App supplies an opinionated `vue-router` factory that:
+
+- **Enforces auth** based on route metadata.
+- **Redirects unauthenticated users** to a configured login route or URL.
+- **Redirects non-admin users** away from admin-only routes.
+- **Provides breadcrumb metadata** for the breadcrumbs store and layouts.
+
+### Defining routes with `primitiveRouterMeta`
+
+```ts
+// src/router/routes.ts
+import type { RouteRecordRaw } from "vue-router";
+import {
+  createPrimitiveRouter,
+  PrimitiveAppLayout,
+  PrimitiveLoginLayout,
+  PrimitiveStaticLayout,
+} from "primitive-app";
+import LoginPage from "@/pages/LoginPage.vue";
+import HomePage from "@/pages/HomePage.vue";
+import TermsPage from "@/pages/TermsPage.vue";
+
+const routes: RouteRecordRaw[] = [
+  {
+    path: "/",
+    component: PrimitiveAppLayout,
+    children: [
+      {
+        path: "",
+        name: "home",
+        component: HomePage,
+        meta: {
+          primitiveRouterMeta: {
+            requireAuth: "member", // "none" | "member" | "admin"
+            breadcrumb: { title: "Home" },
+          },
+        },
+      },
+      {
+        path: "routing/:slug",
+        name: "routing-slug",
+        component: () => import("@/pages/RoutingExamplePage.vue"),
+        meta: {
+          primitiveRouterMeta: {
+            requireAuth: "member",
+            breadcrumb: {
+              title: "Routing",
+              generator: (params) => String(params.slug ?? "Routing"),
+            },
+          },
+        },
+      },
+    ],
+  },
+  {
+    path: "/",
+    component: PrimitiveLoginLayout,
+    children: [{ path: "login", name: "login", component: LoginPage }],
+  },
+  {
+    path: "/",
+    component: PrimitiveStaticLayout,
+    children: [
+      {
+        path: "terms-of-service",
+        name: "terms-of-service",
+        component: TermsPage,
+      },
+    ],
+  },
+];
+
+const router = createPrimitiveRouter({
+  routes,
+  // or loginUrl: "https://auth.example.com/login"
+  loginRouteName: "login",
+});
+
+export default router;
+```
+
+### Auth behavior
+
+- If `primitiveRouterMeta.requireAuth` is:
+  - `"none"`: route is public.
+  - `"member"`: user must be authenticated.
+  - `"admin"`: user must be authenticated and `useUserStore().isAdmin === true`.
+- For member/admin routes:
+  - Unauthenticated users are redirected to the login route or URL with a `continueURL` query parameter.
+  - Non-admin users on admin routes are redirected to the app's `homeRouteName` from `useAppConfigStore`.
+
+Breadcrumb metadata is consumed by `useBreadcrumbsStore` and `PrimitiveAppLayout` to render breadcrumb trails and page titles.
+
+---
+
+## Stores
+
+Primitive App provides several Pinia stores organized into three categories:
+
+1. **Configuration stores** – Static app configuration and UI state
+2. **User store** – Authentication and user preferences
+3. **Document stores** – js-bao document management
+
+### Configuration stores
+
+#### App config store: `useAppConfigStore`
+
+The app config store centralizes static configuration:
+
+| Option                | Type                | Description                                      |
+| --------------------- | ------------------- | ------------------------------------------------ |
+| `appName`             | `string`            | Display name for the app and default page titles |
+| `appIcon`             | `Component`         | Vue component rendered in login/static layouts   |
+| `homeRouteName`       | `RouteRecordName`   | Route used as the "home" destination             |
+| `loginRouteName`      | `RouteRecordName`   | Named login route                                |
+| `documentStoreMode`   | `DocumentStoreMode` | Controls document store behavior (see below)     |
+| `pageTitleFormatter?` | `function`          | Custom page title formatter                      |
+| `loadingComponent?`   | `Component`         | Global loading component used by layouts         |
+
+**DocumentStoreMode options:**
+
+- `DocumentStoreMode.None` – No document store initialized
+- `DocumentStoreMode.SingleDocument` – Single document per user, no switching UI
+- `DocumentStoreMode.SingleDocumentWithSwitching` – Single active document with switching/sharing UI
+- `DocumentStoreMode.MultiDoc` – Multiple document collections managed dynamically
+
+Example config:
+
+```ts
+// src/config/appConfig.ts
+import appIconUrl from "@/assets/app-icon.png";
+import { DocumentStoreMode, type AppIconComponent } from "primitive-app";
+import { defineComponent, h } from "vue";
+import type { RouteLocationNormalizedLoaded } from "vue-router";
+
+const AppIcon: AppIconComponent = defineComponent({
+  name: "AppIcon",
+  setup() {
+    return () => h("img", { src: appIconUrl, alt: "App Icon" });
+  },
+});
+
+function defaultPageTitleFormatter(input: {
+  breadcrumb: string | null;
+  appName: string;
+  route: RouteLocationNormalizedLoaded;
+}): string {
+  if (input.breadcrumb && input.breadcrumb.trim().length > 0) {
+    return `${input.breadcrumb} : ${input.appName}`;
+  }
+  return input.appName;
+}
+
+export function getAppConfig() {
+  return {
+    appName: "My Primitive App",
+    homeRouteName: "home",
+    loginRouteName: "login",
+    appIcon: AppIcon,
+    documentStoreMode: DocumentStoreMode.SingleDocumentWithSwitching,
+    pageTitleFormatter: defaultPageTitleFormatter,
+  } as const;
+}
+```
+
+> `createPrimitiveApp` calls `useAppConfigStore().initialize(getAppConfig())` during bootstrap and sets up a reactive `document.title` using the provided formatter.
+
+#### Navigation store: `useNavigationStore`
+
+The navigation store drives sidebar, bottom navigation, and user menu:
+
+**Configuration (`NavigationConfig`):**
+
+| Option                          | Type                            | Description                               |
+| ------------------------------- | ------------------------------- | ----------------------------------------- |
+| `navOptions?.overflowMode`      | `NavigationOverflowMode`        | How to handle overflow items              |
+| `navOptions?.maxVisibleTabs`    | `number`                        | Maximum tabs in bottom nav (default: 5)   |
+| `navOptions?.mobileNavEnabled`  | `boolean`                       | Enable mobile bottom nav (default: true)  |
+| `navOptions?.mobileBackEnabled` | `boolean`                       | Enable mobile back button (default: true) |
+| `navItems`                      | `Record<string, NavItemConfig>` | Navigation item definitions               |
+
+**NavItemConfig options:**
+
+| Option             | Type                                   | Description                                       |
+| ------------------ | -------------------------------------- | ------------------------------------------------- |
+| `key`              | `string`                               | Unique identifier for the item                    |
+| `navTitle`         | `string`                               | Display title                                     |
+| `navGroup`         | `"main" \| "secondary" \| "user-menu"` | Navigation group                                  |
+| `routeName?`       | `string`                               | Vue router route name                             |
+| `routeParams?`     | `object`                               | Route parameters                                  |
+| `externalHref?`    | `string`                               | External URL                                      |
+| `target?`          | `string`                               | Link target (e.g., "\_blank")                     |
+| `icon?`            | `Component`                            | Icon component                                    |
+| `parentKey?`       | `string`                               | Parent item key (for nesting)                     |
+| `navHeader?`       | `string`                               | Header text for grouped items                     |
+| `matchRouteNames?` | `string[]`                             | Additional routes that activate this item         |
+| `mobilePriority?`  | `number`                               | Priority for bottom nav (lower = higher priority) |
+| `hidden?`          | `boolean`                              | Hide this item                                    |
+
+Example:
+
+```ts
+// src/config/navigationConfig.ts
+import { NavigationOverflowMode, type NavigationConfig } from "primitive-app";
+import { BookOpen, Settings, LogOut } from "lucide-vue-next";
+
+export function getNavigationConfig(): NavigationConfig {
+  return {
+    navOptions: {
+      overflowMode: NavigationOverflowMode.Always,
+      maxVisibleTabs: 3,
+      mobileNavEnabled: true,
+      mobileBackEnabled: true,
+    },
+    navItems: {
+      gettingStarted: {
+        key: "gettingStarted",
+        navTitle: "Getting Started",
+        navGroup: "main",
+        routeName: "getting-started",
+        icon: BookOpen,
+        mobilePriority: 1,
+      },
+      settings: {
+        key: "settings",
+        navTitle: "Settings",
+        navGroup: "user-menu",
+        routeName: "settings",
+        icon: Settings,
+      },
+      logout: {
+        key: "logout",
+        navTitle: "Log out",
+        navGroup: "user-menu",
+        routeName: "logout",
+        icon: LogOut,
+        mobilePriority: 2,
+      },
+    },
+  } as const;
+}
+```
+
+**Dynamic navigation actions:**
+
+```ts
+const navigation = useNavigationStore();
+
+// Add items dynamically
+navigation.addNavItems({ ... });
+
+// Remove items
+navigation.removeNavItems(['itemKey']);
+
+// Show/hide items
+navigation.hideNavItems(['itemKey']);
+navigation.showNavItems(['itemKey']);
+
+// Badges
+navigation.setCountBadge('itemKey', 5);
+navigation.setDotBadge('itemKey');
+navigation.clearBadge('itemKey');
+```
+
+`PrimitiveAppLayout`, `PrimitiveSidebarNav`, `PrimitiveBottomNav`, and `PrimitiveUserMenu` all consume this store.
+
+#### Breadcrumbs store: `useBreadcrumbsStore`
+
+The breadcrumbs store maintains an array of breadcrumb segments derived from route metadata:
+
+- **State:** `segments: BreadcrumbSegment[]` – array of `{ label, href }` objects
+- **Actions:**
+  - `initialize({ router })` – Wire to Vue Router (called by `createPrimitiveApp`)
+  - `refreshCurrentRoute()` – Re-generate breadcrumbs for the current route
+
+Use `refreshCurrentRoute()` when other reactive state that influences breadcrumb generators changes (e.g., user display name).
+
+### User store: `useUserStore`
+
+`useUserStore` wires your app into js-bao auth and user profile management.
+
+**State:**
+
+| Property          | Type                  | Description                   |
+| ----------------- | --------------------- | ----------------------------- |
+| `currentUser`     | `UserProfile \| null` | Current user profile          |
+| `isAuthenticated` | `boolean`             | Whether user is authenticated |
+| `isAdmin`         | `boolean` (computed)  | Whether user has admin role   |
+| `isOnline`        | `boolean`             | Network connectivity status   |
+| `isInitialized`   | `boolean`             | Whether store has initialized |
+
+**Actions:**
+
+| Method                                              | Description                         |
+| --------------------------------------------------- | ----------------------------------- |
+| `initialize({ loginUrl })`                          | Initialize auth and event listeners |
+| `login(continueURL?)`                               | Start OAuth flow                    |
+| `handleOAuthCallback(defaultContinueUrl, loginUrl)` | Process OAuth callback              |
+| `logout(redirectTo?)`                               | Log out and optionally redirect     |
+
+**User preferences:**
+
+Preferences are stored via the internal `UserPref` js-bao model in a per-user root document:
+
+```ts
+const user = useUserStore();
+
+// Get a preference with default value
+const theme = user.getPref<string>("theme", "light");
+
+// Set a preference
+await user.setPref("theme", "dark");
+
+// Delete a preference
+await user.deletePref("theme");
+
+// Get all preferences
+const allPrefs = user.getAllPrefs();
+
+// Clear all preferences
+await user.clearAllPrefs();
+```
+
+### Document stores
+
+Primitive App provides three document stores that work together to manage js-bao documents. Understanding their relationship is key to choosing the right pattern for your app.
+
+#### How document stores relate
+
+```
+                    +---------------------------------------------+
+                    |           jsBaoDocumentsStore               |
+                    |  (All accessible documents & invitations)   |
+                    +---------------------------------------------+
+                                /                   \
+                               /                     \
+              +------------------------+    +------------------------+
+              |  singleDocumentStore   |    |  multiDocumentStore    |
+              |  (One active doc)      |    |  (Tag-based            |
+              |                        |    |   collections)         |
+              +------------------------+    +------------------------+
+```
+
+- **`jsBaoDocumentsStore`**: The foundational reactive store that tracks all documents the user has access to, plus pending invitations. It handles document metadata events from js-bao and maintains the authoritative list.
+- **`singleDocumentStore`**: Built on top of `jsBaoDocumentsStore`. Manages a single "active" document at a time. Ideal for simple apps.
+- **`multiDocumentStore`**: Built on top of `jsBaoDocumentsStore`. Manages multiple document collections based on tags. Ideal for complex apps with varied sharing needs.
+
+#### Choosing a document store pattern
+
+**1. SingleDocument mode** – Simple apps without sharing needs
+
+Best for: Personal apps, simple tools, single-user data.
+
+```ts
+// appConfig.ts
+documentStoreMode: DocumentStoreMode.SingleDocument;
+```
+
+- Each user automatically gets a single document created for them.
+- No document switching UI is shown.
+- Data is conceptually like a single database per user.
+
+**2. SingleDocumentWithSwitching mode** – Google Docs-like sharing pattern
+
+Best for: Apps with clear data "containers" that users might share.
+
+```ts
+// appConfig.ts
+documentStoreMode: DocumentStoreMode.SingleDocumentWithSwitching;
+```
+
+- Users automatically get a default document created.
+- Users can create additional documents, each of which can be shared with others.
+- Only one document is active at a time.
+- Built-in UI for document switching, sharing invitations, and management.
+- Examples: One document per "company", splitting "personal" from "shared" data.
+
+Configuration:
+
+```ts
+export function getSingleDocumentConfig() {
+  return {
+    userVisibleDocumentName: "Project",
+    userVisibleDocumentNamePlural: "Projects",
+    defaultDocumentTitle: "My First Project",
+    manageDocumentsRouteName: "projects-manage",
+  } as const;
+}
+```
+
+**3. MultiDoc mode** – Complex sharing and data modeling
+
+Best for: Apps with complex sharing needs, multiple data sets, or large data volumes.
+
+```ts
+// appConfig.ts
+documentStoreMode: DocumentStoreMode.MultiDoc;
+```
+
+- Multiple documents can be open simultaneously.
+- Documents are organized into "collections" based on tags.
+- Collections are registered dynamically at runtime.
+- Supports auto-opening documents and auto-accepting invitations per collection.
+- Recommended when: sharing different data sets with different users, data exceeds ~10MB per document, need to search across multiple documents.
+
+Usage:
+
+```ts
+import { useMultiDocumentStore } from "primitive-app";
+
+const multiDoc = useMultiDocumentStore();
+
+// Register a collection (typically on component mount)
+await multiDoc.registerCollection({
+  name: "workspaces",
+  tag: "workspace",
+  autoOpen: true, // Auto-open matching documents
+  autoAcceptInvites: true, // Auto-accept invitations for this collection
+});
+
+// Access documents in a collection
+const workspaces = computed(() => multiDoc.collections["workspaces"] ?? []);
+
+// Check collection readiness
+const isReady = multiDoc.getCollectionReadyRef("workspaces");
+
+// Create a document in a collection
+const newDoc = await multiDoc.createDocument("workspaces", "New Workspace");
+
+// Unregister when done
+await multiDoc.unregisterCollection("workspaces");
+```
+
+#### jsBaoDocumentsStore API
+
+The base store for all document operations:
+
+**State:**
+
+| Property               | Type                   | Description                 |
+| ---------------------- | ---------------------- | --------------------------- |
+| `documents`            | `TrackedDocument[]`    | All accessible documents    |
+| `pendingInvitations`   | `DocumentInvitation[]` | Pending sharing invitations |
+| `openDocumentIds`      | `Set<string>`          | Currently open document IDs |
+| `documentListLoaded`   | `boolean`              | Document list has loaded    |
+| `invitationListLoaded` | `boolean`              | Invitation list has loaded  |
+| `isReady`              | `boolean` (computed)   | Both lists have loaded      |
+
+**Actions:**
+
+| Method                                        | Description                    |
+| --------------------------------------------- | ------------------------------ |
+| `initialize()`                                | Load documents and invitations |
+| `reset()`                                     | Clear state and unsubscribe    |
+| `refreshDocuments()`                          | Reload document list           |
+| `openDocument(id)`                            | Open a document                |
+| `closeDocument(id)`                           | Close a document               |
+| `createDocument(title, tags?)`                | Create a new document          |
+| `renameDocument(id, title)`                   | Rename a document              |
+| `deleteDocument(id)`                          | Delete a document              |
+| `shareDocument(id, email, permission)`        | Share with another user        |
+| `refreshPendingInvitations()`                 | Reload invitations             |
+| `acceptInvitation(documentId)`                | Accept an invitation           |
+| `declineInvitation(documentId, invitationId)` | Decline an invitation          |
+
+#### singleDocumentStore API
+
+Manages a single active document:
+
+**State:**
+
+| Property                  | Type                      | Description                |
+| ------------------------- | ------------------------- | -------------------------- |
+| `currentDocumentId`       | `string \| null`          | Active document ID         |
+| `currentDocumentMetadata` | `TrackedDocument \| null` | Active document metadata   |
+| `isReady`                 | `boolean`                 | Document is open and ready |
+| `isCurrentDocReadOnly`    | `boolean`                 | User has read-only access  |
+
+**Actions:**
+
+| Method                | Description                    |
+| --------------------- | ------------------------------ |
+| `initialize(options)` | Initialize with config         |
+| `reset()`             | Clear state                    |
+| `switchDocument(id)`  | Switch to a different document |
+
+#### multiDocumentStore API
+
+Manages multiple document collections:
+
+**State:**
+
+| Property      | Type                                | Description                     |
+| ------------- | ----------------------------------- | ------------------------------- |
+| `collections` | `Record<string, TrackedDocument[]>` | Documents grouped by collection |
+
+**Actions:**
+
+| Method                              | Description                     |
+| ----------------------------------- | ------------------------------- |
+| `registerCollection(config)`        | Register a new collection       |
+| `unregisterCollection(name)`        | Unregister a collection         |
+| `getCollection(name)`               | Get documents in a collection   |
+| `isCollectionRegistered(name)`      | Check if collection exists      |
+| `isCollectionReady(name)`           | Check if collection is ready    |
+| `getCollectionReadyRef(name)`       | Get reactive readiness ref      |
+| `createDocument(collection, title)` | Create document in collection   |
+| `isDocumentReady(id)`               | Check if document is open       |
+| `getDocumentReadyRef(idRef)`        | Get reactive document readiness |
+| `reset()`                           | Clear all collections           |
+
+---
+
+## `PrimitiveAppLayout` usage patterns
+
+`PrimitiveAppLayout` is the main authenticated **app shell**. It:
+
+- Renders a sidebar (desktop), breadcrumb header, and optional bottom nav (mobile).
+- Integrates with:
+  - `useNavigationStore` (sidebar items, bottom nav, back behavior).
+  - `useBreadcrumbsStore` (breadcrumbs and page title).
+  - `useUserStore` (user menu, online status).
+  - `useAppConfigStore` and `DocumentStoreMode` (document switching vs static header).
+  - `useSingleDocumentStore` (optional single-document switcher).
+- Shows a service worker "update required" banner and an optional worktree label banner (for dev workflows).
+
+You can adopt it at different levels of complexity:
+
+### 1) Use it as-is (configure via stores and route metadata)
+
+This is the simplest path – use `PrimitiveAppLayout` as the root layout for authenticated routes, and configure:
+
+- App config (`getAppConfig`)
+- Document store (`getSingleDocumentConfig` + `DocumentStoreMode`)
+- Navigation (`getNavigationConfig`)
+- Routing meta (`primitiveRouterMeta`)
+
+Example (excerpt):
+
+```ts
+// src/router/routes.ts
+const routes: RouteRecordRaw[] = [
+  {
+    path: "/",
+    component: PrimitiveAppLayout,
+    children: [
+      {
+        path: "",
+        name: "home",
+        component: () => import("@/pages/HomePage.vue"),
+        meta: {
+          primitiveRouterMeta: {
+            requireAuth: "member",
+            breadcrumb: { title: "Home" },
+          },
+        },
+      },
+    ],
+  },
+  // login + static sections...
+];
+```
+
+You do **not** pass any props to `PrimitiveAppLayout` – it reads state from the shared stores.
+
+### 2) Wrap it in a layout that performs extra data loading or dynamic tweaks
+
+Wrap `PrimitiveAppLayout` in your own layout to:
+
+- Run data loaders (`useJsBaoDataLoader`, app-specific composables).
+- Dynamically modify navigation (`navigationStore.addNavItems`, badges).
+- Add theming or additional chrome around the shell.
+
+```vue
+<!-- src/layouts/ThemedPrimitiveAppLayout.vue -->
+<script setup lang="ts">
+import { PrimitiveAppLayout, useNavigationStore } from "primitive-app";
+import { onMounted } from "vue";
+
+const navigation = useNavigationStore();
+
+onMounted(() => {
+  navigation.addNavItems({
+    recentItems: {
+      key: "recentItems",
+      navTitle: "Recent Items",
+      navGroup: "main",
+      routeName: "recent-items",
+      mobilePriority: 2,
+    },
+  });
+});
+</script>
+
+<template>
+  <div class="min-h-screen bg-background text-foreground">
+    <PrimitiveAppLayout>
+      <router-view />
+    </PrimitiveAppLayout>
+  </div>
+</template>
+```
+
+Routes now use `ThemedPrimitiveAppLayout` instead of `PrimitiveAppLayout` directly.
+
+### 3) Override sidebar / bottom nav content via slots
+
+`PrimitiveAppLayout` exposes:
+
+- `#sidebar` – replaces the entire sidebar area.
+- `#bottomNav` – replaces the mobile bottom navigation bar.
+- Default slot – main content area (which typically renders `<router-view />`).
+
+This lets you keep the **overall shell behavior** (SW banner, worktree label, mobile back header, padding) while providing your own navigation components.
+
+```vue
+<!-- src/layouts/CustomShellLayout.vue -->
+<script setup lang="ts">
+import {
+  PrimitiveAppLayout,
+  PrimitiveUserMenu,
+  useNavigationStore,
+  useUserStore,
+} from "primitive-app";
+import { computed } from "vue";
+
+const navigation = useNavigationStore();
+const user = useUserStore();
+
+const mainNavItems = computed(() => navigation.navMain);
+const userMenuItems = computed(() => navigation.userMenuItems);
+</script>
+
+<template>
+  <PrimitiveAppLayout>
+    <template #sidebar>
+      <aside class="flex h-full flex-col border-r bg-background">
+        <header class="p-4 border-b">
+          <h1 class="text-sm font-semibold tracking-tight">
+            My Custom Sidebar
+          </h1>
+        </header>
+
+        <nav class="flex-1 overflow-y-auto p-2 space-y-1">
+          <RouterLink
+            v-for="item in mainNavItems"
+            :key="item.title"
+            :to="item.url"
+            class="block px-3 py-2 rounded-md text-sm hover:bg-accent"
+          >
+            {{ item.title }}
+          </RouterLink>
+        </nav>
+
+        <footer class="border-t p-2">
+          <PrimitiveUserMenu
+            :current-user="user.currentUser"
+            :is-online="user.isOnline"
+            :user-menu-items="userMenuItems"
+          />
+        </footer>
+      </aside>
+    </template>
+
+    <template #bottomNav>
+      <nav class="fixed inset-x-0 bottom-0 border-t bg-background md:hidden">
+        <!-- your own mobile tab bar implementation -->
+      </nav>
+    </template>
+
+    <router-view />
+  </PrimitiveAppLayout>
+</template>
+```
+
+You can also reconstruct the _default_ layout but insert custom elements (e.g. banners, diagnostics) inside the slots.
+
+### 4) Build a completely custom layout
+
+Finally, you can skip `PrimitiveAppLayout` entirely and build your own shell using the underlying stores and components:
+
+- `useAppConfigStore`, `useUserStore`, `useNavigationStore`, `useBreadcrumbsStore`, `useSingleDocumentStore`
+- Components: `PrimitiveSidebarNav`, `PrimitiveAppBreadcrumb`, `PrimitiveUserMenu`, `PrimitiveBottomNav`, `PrimitiveSingleDocumentSwitcher`, etc.
+
+```vue
+<!-- src/layouts/MyFullyCustomLayout.vue -->
+<script setup lang="ts">
+import {
+  PrimitiveAppBreadcrumb,
+  PrimitiveSidebarNav,
+  PrimitiveUserMenu,
+  useAppConfigStore,
+  useNavigationStore,
+  useUserStore,
+} from "primitive-app";
+
+const appConfig = useAppConfigStore();
+const navigation = useNavigationStore();
+const user = useUserStore();
+</script>
+
+<template>
+  <div class="min-h-screen grid grid-cols-[240px_1fr]">
+    <aside class="border-r bg-background flex flex-col">
+      <header class="p-4 border-b">
+        <span class="font-semibold text-sm">
+          {{ appConfig.appName() }}
+        </span>
+      </header>
+
+      <main class="flex-1 overflow-y-auto">
+        <PrimitiveSidebarNav />
+      </main>
+
+      <footer class="border-t p-2">
+        <PrimitiveUserMenu
+          :current-user="user.currentUser"
+          :is-online="user.isOnline"
+          :user-menu-items="navigation.userMenuItems"
+        />
+      </footer>
+    </aside>
+
+    <section class="flex flex-col">
+      <header class="h-12 flex items-center border-b px-4">
+        <PrimitiveAppBreadcrumb />
+      </header>
+
+      <main class="flex-1 overflow-y-auto p-4">
+        <router-view />
+      </main>
+    </section>
+  </div>
+</template>
+```
+
+This is useful if you have strong visual/UX requirements or are gradually adopting `primitive-app` in an existing application.
+
+---
+
+## Data loading with `useJsBaoDataLoader`
+
+`useJsBaoDataLoader` provides a standardized pattern for:
+
+- Loading data asynchronously (typically via js-bao models).
+- Watching a "document ready" gate (e.g., from `useSingleDocumentStore`).
+- Reacting to changes in query params.
+- Subscribing to js-bao models and automatically reloading when data changes.
+- Integrating with skeleton components like `PrimitiveSkeletonGate`.
+
+### API overview
+
+```ts
+import { useJsBaoDataLoader } from "primitive-app";
+
+const { data, initialDataLoaded, reload } = useJsBaoDataLoader<Data, Query>({
+  subscribeTo: [
+    /* models with Model.subscribe(cb) */
+  ],
+  queryParams, // ref/computed or plain value; null disables query-driven reloads
+  documentReady, // ref/computed/boolean gate
+  loadData: async ({ queryParams }) => {
+    /* ... */
+  },
+  pauseUpdates, // optional ref/computed/boolean
+  debounceMs: 50, // optional debounce for reloads
+  onError: (error) => {}, // optional error handler
+});
+```
+
+- **Result:**
+  - `data: Ref<Data | null>` – last successfully loaded value.
+  - `initialDataLoaded: Ref<boolean>` – becomes `true` after first successful load while `documentReady` is `true`.
+  - `reload(): void` – manually schedule a reload (respecting debounce and gates).
+
+### Example with js-bao models and the single-document store
+
+```ts
+// src/pages/ProductsPage.vue (script setup)
+import {
+  PrimitiveSkeletonGate,
+  useJsBaoDataLoader,
+  useSingleDocumentStore,
+} from "primitive-app";
+import { Product } from "@/models/Product";
+import { storeToRefs } from "pinia";
+import { computed, ref } from "vue";
+
+type PageData = { products: Product[] };
+
+const singleDoc = useSingleDocumentStore();
+const { isReady: documentReady } = storeToRefs(singleDoc);
+
+const queryParams = ref({}); // "load all" for this example
+
+const { data, initialDataLoaded, reload } = useJsBaoDataLoader<PageData>({
+  subscribeTo: [Product],
+  queryParams,
+  documentReady,
+  loadData: async () => {
+    const result = await Product.query(queryParams.value);
+    return { products: (result.data || []) as Product[] };
+  },
+  onError: (err) => {
+    console.error("Error loading products", err);
+  },
+});
+
+const products = computed(() => data.value?.products ?? []);
+```
+
+```vue
+<!-- template -->
+<PrimitiveSkeletonGate :is-ready="initialDataLoaded">
+  <template #skeleton>
+    <!-- skeleton UI -->
+  </template>
+
+  <ul>
+    <li v-for="product in products" :key="product.id">
+      {{ product.name }}
+    </li>
+  </ul>
+</PrimitiveSkeletonGate>
+```
+
+### Example without js-bao (simple async data)
+
+```ts
+import { useJsBaoDataLoader, PrimitiveSkeletonGate } from "primitive-app";
+import { ref } from "vue";
+
+type DemoData = { message: string };
+
+const simulateSlowLoad = async (): Promise<DemoData> => {
+  await new Promise((resolve) => setTimeout(resolve, 800));
+  return { message: "Loaded after a short delay." };
+};
+
+const { data, initialDataLoaded } = useJsBaoDataLoader<DemoData>({
+  subscribeTo: [],
+  queryParams: ref({}),
+  documentReady: ref(true),
+  loadData: simulateSlowLoad,
+});
+```
+
+---
+
+## Auth, navigation, documents, and debug components
+
+Primitive App includes higher-level components that sit on top of the stores:
+
+- **Auth components**
+  - `PrimitiveLogin`, `PrimitiveLogout`, `PrimitiveOauthCallback`
+- **Navigation components**
+  - `PrimitiveAppBreadcrumb`, `PrimitiveSidebarNav`, `PrimitiveBottomNav`,
+    `PrimitiveUserMenu`, `PrimitiveNavigationBadge`
+- **Document components**
+  - `PrimitiveManageDocuments`, `PrimitiveShareDocumentDialog`,
+    `PrimitiveSingleDocumentSwitcher`
+- **Shared components**
+  - `PrimitiveLogoSpinner`, `PrimitiveSkeletonGate`, `DeleteConfirmationDialog`
+- **Debug suite**
+  - `PrimitiveDebuggingSuite`, `PrimitiveTestRunner`, `DocumentDebugger`,
+    `DebugSuiteLayout`, plus debug pages you can mount on a `/debug` route.
+
+---
+
+## Debugging suite
+
+The debugging suite provides tools for testing and inspecting your app during development:
+
+### Document Debugger
+
+The Document Debugger is a powerful tool for inspecting and managing js-bao documents and model data:
+
+- **Document management**: View all documents, create new documents, rename, delete, and switch between documents
+- **Model inspection**: Browse all registered js-bao models and their records
+- **Record CRUD**: Create, read, update, and delete records directly
+- **Filtering & sorting**: Filter and sort records by any field
+- **Mass operations**: Bulk delete records or documents
+- **Schema inspection**: View model fields, types, indexes, relationships, and unique constraints
+
+The Document Debugger uses its own document context independent of the app's main document stores, so you can inspect data without affecting the app state.
+
+### Test Runner
+
+The test harness runs app-level integration tests. Tests are grouped into `PrimitiveTestGroup` objects and registered with the `DebugSuiteLayout`.
+
+#### Defining test groups
+
+Create a file for your test groups (e.g., `src/tests/myTests.ts`):
+
+```ts
+// src/tests/myTests.ts
+import type { PrimitiveTestGroup } from "primitive-app";
+import { useUserStore, useSingleDocumentStore } from "primitive-app";
+
+// Helper to format pass/fail scores (the runner parses this format)
+function formatScore(passed: number, total: number): string {
+  const percentage = total === 0 ? 100 : (passed / total) * 100;
+  return `${passed}/${total} (${percentage.toFixed(1)}%)`;
+}
+
+export const userPreferencesTestGroup: PrimitiveTestGroup = {
+  name: "User Preferences",
+  mode: "offline", // "offline" (default) or "online" – controls network requirement
+  tests: [
+    {
+      id: "user-pref-read-all",
+      name: "can read all user preferences without error",
+      async run(log?: (m: string) => void): Promise<string> {
+        const user = useUserStore();
+
+        log?.("Reading all preferences from userStore...");
+        const prefs = user.getAllPrefs();
+        log?.(`Retrieved ${Object.keys(prefs).length} preference(s)`);
+
+        // Returning a score string indicates success
+        return formatScore(1, 1);
+      },
+    },
+    {
+      id: "user-pref-default",
+      name: "getPref returns default value for missing key",
+      async run(log?: (m: string) => void): Promise<string> {
+        const user = useUserStore();
+        const defaultValue = "fallback";
+
+        log?.(`Requesting missing key with default "${defaultValue}"...`);
+        const value = user.getPref<string>("nonexistent_key", defaultValue);
+
+        // Throwing an Error fails the test
+        if (value !== defaultValue) {
+          throw new Error(`Expected "${defaultValue}", got "${value}"`);
+        }
+
+        log?.("Default value returned correctly");
+        return formatScore(1, 1);
+      },
+    },
+  ],
+};
+
+export const documentTestGroup: PrimitiveTestGroup = {
+  name: "Document Store",
+  mode: "offline",
+  tests: [
+    {
+      id: "doc-store-ready",
+      name: "single document store becomes ready",
+      async run(log?: (m: string) => void): Promise<string> {
+        const docStore = useSingleDocumentStore();
+
+        log?.(`Document store ready: ${docStore.isReady}`);
+        if (!docStore.isReady) {
+          throw new Error("Expected document store to be ready");
+        }
+
+        return formatScore(1, 1);
+      },
+    },
+  ],
+};
+
+// Export all test groups as an array
+export const appTestGroups: PrimitiveTestGroup[] = [
+  userPreferencesTestGroup,
+  documentTestGroup,
+];
+```
+
+#### Test function conventions
+
+- **`id`**: Unique identifier for the test (used for selection state).
+- **`name`**: Human-readable test name displayed in the UI.
+- **`run(log?)`**: Async function that executes the test.
+  - Use `log?.("message")` to output progress to the test runner.
+  - Return a score string like `"1/1 (100.0%)"` to indicate success (the runner parses this format).
+  - Throw an `Error` to fail the test.
+- **`mode`** (on the group): `"offline"` (default) runs tests without requiring network; `"online"` requires network connectivity.
+
+#### Registering tests with routes
+
+Mount the debug suite on a `/debug` route and pass your test groups to `DebugSuiteLayout`:
+
+```ts
+// src/router/routes.ts
+import {
+  createPrimitiveRouter,
+  DebugSuiteLayout,
+  DebuggingSuiteHome,
+  DebuggingSuiteTests,
+  DebuggingSuiteDocuments,
+} from "primitive-app";
+import { appTestGroups } from "@/tests/myTests";
+import type { RouteRecordRaw } from "vue-router";
+
+const routes: RouteRecordRaw[] = [
+  // ... your app routes ...
+
+  // Debug suite (admin-only recommended)
+  {
+    path: "/debug",
+    component: DebugSuiteLayout,
+    props: {
+      testGroups: appTestGroups,
+      appName: "My App",
+    },
+    meta: {
+      primitiveRouterMeta: {
+        requireAuth: "admin", // or "member" for broader access
+      },
+    },
+    children: [
+      {
+        path: "",
+        name: "debug-home",
+        component: DebuggingSuiteHome,
+      },
+      {
+        path: "test",
+        name: "debug-test",
+        component: DebuggingSuiteTests,
+      },
+      {
+        path: "documents",
+        name: "debug-documents",
+        component: DebuggingSuiteDocuments,
+      },
+    ],
+  },
+];
+
+const router = createPrimitiveRouter({
+  routes,
+  loginRouteName: "login",
+});
+
+export default router;
+```
+
+The debug suite provides:
+
+- **Home page** (`DebuggingSuiteHome`): Overview and quick actions.
+- **Test page** (`DebuggingSuiteTests`): Select and run tests, view results and logs.
+- **Documents page** (`DebuggingSuiteDocuments`): Inspect and manage js-bao documents via the Document Debugger.
+
+---
+
+## js-bao integration & logging
+
+### JsBao client service
+
+Primitive App centralizes js-bao client setup via:
+
+- `initializeJsBao(config: JsBaoClientOptions)` – called once at startup.
+- `jsBaoClientService.getClientAsync()` – used internally by stores to access the client.
+
+`config.models` from your app are merged with the library's internal models (such as `UserPref`) before initializing the client.
+
+### Logging
+
+`primitive-app` ships with a scoped logging utility:
+
+- `primitiveAppBaseLogger`
+- `createLogger({ level, scope })`
+- `LogLevel` (`"debug" | "info" | "warn" | "error" | "none"`)
+
+Example:
+
+```ts
+import { createLogger } from "primitive-app";
+
+const logger = createLogger({
+  level: import.meta.env.DEV ? "debug" : "info",
+  scope: ["MyApp", "ProductsPage"],
+});
+
+logger.debug("Loaded products", { count: 42 });
+```
+
+---
+
+## Reference and further examples
+
+For a more complete, real-world example, refer to:
+
+- **Demo app (`primitive-app-demo`)**
+  - `src/main.ts` – bootstrapping with `createPrimitiveApp`
+  - `src/router/routes.ts` – routes + `createPrimitiveRouter`
+  - `src/config/appConfig.ts`, `src/config/envConfig.ts`, `src/config/navigationConfig.ts`
+  - `src/pages/GettingStarted*` – focused pages on configuration, theming, routing, navigation, data loading, utilities
+- **Template app (`primitive-app-template`)**
+  - Minimal starter following the same patterns, useful for new apps.
+
+For a deeper, implementation-level map of the library (especially for automation or AI agents), see [`AGENTS.md`](./AGENTS.md).