feat: auth scaffold, notifications inbox, resources CRUD, vitest baseline, typed API client

Auth
- ~/lib/session.ts: Session type + loadSession/signIn/signOut/hasSession,
  reactive useSession hook (mock backend; replace fetch calls with your
  real auth endpoint when ready)
- routes/login.tsx: form with email/password (mock-validated), bounces
  to ?next= on success
- AppShell: redirects to /login when no session; account-menu Sign out
  now actually signs out; live session.name/email used for the appbar
  avatar (falls back to profile)

Notifications
- ~/lib/notifications.ts: persistent inbox with kinds (info/success/
  warning/error), unreadCount, markRead, markAllRead, dismiss,
  dismissAll; seedIfEmpty for a friendly first-run
- AppShell bell: 320px popover with badge, kind dots, per-row open
  (navigates to href) and dismiss; Mark all read + Clear actions
- Hidden NotificationDispatcher in AppShell so the action bus can
  create real notifications via fill notif-title / notif-body /
  notif-kind / notif-href + click notif-create

Data layer
- ~/lib/api.ts: typed apiFetch<T> + api.get/post/put/patch/del,
  auto-attaches the session token, throws structured ApiError, signs
  out on 401
- ~/lib/resources.ts: example domain entity (CRUD) backed by
  localStorage today; each call is a 1:1 swap for api.get/post/put/del
- routes/resources.tsx: real working table — search, add, inline
  status edit, delete; seeded demo rows on first load

Tests
- vitest + jsdom + @testing-library/react + @testing-library/jest-dom
  + vite-tsconfig-paths installed
- vitest.config.ts (jsdom, globals, ~ aliases via tsconfig-paths)
- vitest.setup.ts (RTL cleanup + localStorage clear between tests)
- app/lib/session.test.ts and resources.test.ts as starter coverage
- npm test / npm run test:watch scripts

UI Control catalog
- Login form, resources CRUD, notifications inbox, and the hidden
  notif-bridge ids tagged so the assistant can drive every new surface

Threads
- ThreadMessage now carries optional agentId so per-message authorship
  survives persona switches and handoffs

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

app/lib/api.ts

@@ -0,0 +1,83 @@
+// API — typed fetch wrapper. Auto-injects the session token, throws on
+// non-2xx with a parsed error, and supports AbortSignal for cancellation.
+//
+// Replace `apiBaseURL` with your backend root. The Resources route shows the
+// typical usage pattern.
+
+import { loadSession, signOut } from "~/lib/session"
+
+export const apiBaseURL = "/api"
+
+export class ApiError extends Error {
+  status: number
+  body: unknown
+  constructor(message: string, status: number, body: unknown) {
+    super(message)
+    this.name = "ApiError"
+    this.status = status
+    this.body = body
+  }
+}
+
+export type ApiInit = Omit<RequestInit, "body" | "method"> & {
+  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE"
+  body?: unknown
+}
+
+export async function apiFetch<T = unknown>(
+  path: string,
+  init: ApiInit = {},
+): Promise<T> {
+  const session = loadSession()
+  const headers = new Headers(init.headers)
+  if (session?.token) headers.set("Authorization", `Bearer ${session.token}`)
+  if (init.body !== undefined && !headers.has("Content-Type")) {
+    headers.set("Content-Type", "application/json")
+  }
+
+  const url = path.startsWith("http") ? path : `${apiBaseURL}${path}`
+  const res = await fetch(url, {
+    ...init,
+    method: init.method ?? "GET",
+    headers,
+    body:
+      init.body === undefined
+        ? undefined
+        : typeof init.body === "string"
+          ? init.body
+          : JSON.stringify(init.body),
+  })
+
+  if (res.status === 401) {
+    // Token rejected — clear session so the shell bounces to /login.
+    signOut()
+  }
+
+  const ct = res.headers.get("Content-Type") ?? ""
+  const parsed = ct.includes("application/json")
+    ? await res.json().catch(() => null)
+    : await res.text().catch(() => null)
+
+  if (!res.ok) {
+    const message =
+      (parsed && typeof parsed === "object" && "message" in parsed
+        ? String((parsed as { message: unknown }).message)
+        : null) ?? `${res.status} ${res.statusText}`
+    throw new ApiError(message, res.status, parsed)
+  }
+  return parsed as T
+}
+
+/** Convenience helpers. */
+export const api = {
+  get: <T = unknown>(path: string, init?: ApiInit) =>
+    apiFetch<T>(path, { ...init, method: "GET" }),
+  post: <T = unknown>(path: string, body?: unknown, init?: ApiInit) =>
+    apiFetch<T>(path, { ...init, method: "POST", body }),
+  put: <T = unknown>(path: string, body?: unknown, init?: ApiInit) =>
+    apiFetch<T>(path, { ...init, method: "PUT", body }),
+  patch: <T = unknown>(path: string, body?: unknown, init?: ApiInit) =>
+    apiFetch<T>(path, { ...init, method: "PATCH", body }),
+  del: <T = unknown>(path: string, init?: ApiInit) =>
+    apiFetch<T>(path, { ...init, method: "DELETE" }),
+}

app/lib/notifications.ts

@@ -0,0 +1,155 @@
+// Notifications — small reactive store for in-app toasts/inbox items.
+// Pair with @crema/notification-ui's <ToastProvider /> for transient toasts;
+// this store is for the appbar bell's persistent inbox.
+
+import { useEffect, useSyncExternalStore } from "react"
+
+export type NotificationKind = "info" | "success" | "warning" | "error"
+
+export type AppNotification = {
+  id: string
+  kind: NotificationKind
+  title: string
+  body?: string
+  // Optional href to open when the row is clicked.
+  href?: string
+  createdAt: number
+  readAt?: number
+}
+
+const STORAGE_KEY = "crema.notifications"
+const CHANGE_EVENT = "crema:notifications-change"
+const MAX_ITEMS = 200
+
+function newId(): string {
+  return `n-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`
+}
+
+function readFromStorage(): AppNotification[] {
+  if (typeof window === "undefined") return []
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY)
+    if (!raw) return []
+    const parsed = JSON.parse(raw)
+    if (!Array.isArray(parsed)) return []
+    return parsed.filter(
+      (n): n is AppNotification =>
+        n &&
+        typeof n.id === "string" &&
+        typeof n.title === "string" &&
+        typeof n.createdAt === "number" &&
+        ["info", "success", "warning", "error"].includes(n.kind),
+    )
+  } catch {
+    return []
+  }
+}
+
+function writeToStorage(items: AppNotification[]) {
+  if (typeof window === "undefined") return
+  const trimmed = items.slice(0, MAX_ITEMS)
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(trimmed))
+    window.dispatchEvent(new CustomEvent(CHANGE_EVENT))
+  } catch {
+    /* quota — drop silently */
+  }
+}
+
+export function loadNotifications(): AppNotification[] {
+  return readFromStorage()
+}
+
+export function addNotification(
+  n: Omit<AppNotification, "id" | "createdAt">,
+): AppNotification {
+  const next: AppNotification = {
+    ...n,
+    id: newId(),
+    createdAt: Date.now(),
+  }
+  writeToStorage([next, ...readFromStorage()])
+  return next
+}
+
+export function markRead(id: string) {
+  const items = readFromStorage().map((n) =>
+    n.id === id ? { ...n, readAt: Date.now() } : n,
+  )
+  writeToStorage(items)
+}
+
+export function markAllRead() {
+  const now = Date.now()
+  const items = readFromStorage().map((n) =>
+    n.readAt ? n : { ...n, readAt: now },
+  )
+  writeToStorage(items)
+}
+
+export function dismiss(id: string) {
+  writeToStorage(readFromStorage().filter((n) => n.id !== id))
+}
+
+export function dismissAll() {
+  writeToStorage([])
+}
+
+let cached: AppNotification[] | null = null
+
+function subscribe(cb: () => void): () => void {
+  const onChange = () => {
+    cached = null
+    cb()
+  }
+  window.addEventListener(CHANGE_EVENT, onChange)
+  window.addEventListener("storage", (e) => {
+    if (e.key === STORAGE_KEY) onChange()
+  })
+  return () => window.removeEventListener(CHANGE_EVENT, onChange)
+}
+function getSnapshot(): AppNotification[] {
+  if (!cached) cached = readFromStorage()
+  return cached
+}
+function getServerSnapshot(): AppNotification[] {
+  return []
+}
+
+export function useNotifications(): AppNotification[] {
+  const value = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)
+  useEffect(() => {
+    cached = null
+  }, [])
+  return value
+}
+
+export function unreadCount(items: AppNotification[]): number {
+  return items.filter((n) => !n.readAt).length
+}
+
+/** Seed a few demo notifications on first load so the bell isn't empty. */
+export function seedIfEmpty() {
+  if (typeof window === "undefined") return
+  if (localStorage.getItem(STORAGE_KEY)) return
+  const now = Date.now()
+  const seed: AppNotification[] = [
+    {
+      id: newId(),
+      kind: "info",
+      title: "Welcome",
+      body: "Tag elements with data-action and the assistant can drive them.",
+      href: "/assistant",
+      createdAt: now - 60_000,
+    },
+    {
+      id: newId(),
+      kind: "success",
+      title: "Profile saved",
+      body: "Your display name and avatar are live across the app.",
+      href: "/profile",
+      createdAt: now - 5 * 60_000,
+    },
+  ]
+  writeToStorage(seed)
+}

app/lib/resources.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it, beforeEach } from "vitest"
+
+import {
+  createResource,
+  deleteResource,
+  listResources,
+  updateResource,
+} from "./resources"
+
+describe("resources", () => {
+  beforeEach(() => {
+    localStorage.clear()
+  })
+
+  it("creates, updates, and deletes", () => {
+    expect(listResources()).toEqual([])
+    const r = createResource({ name: "Test", owner: "Atlas" })
+    expect(r.status).toBe("active")
+    expect(listResources()).toHaveLength(1)
+
+    const updated = updateResource(r.id, { status: "paused" })
+    expect(updated?.status).toBe("paused")
+    expect(updated?.updatedAt).toBeGreaterThanOrEqual(r.updatedAt)
+
+    deleteResource(r.id)
+    expect(listResources()).toEqual([])
+  })
+
+  it("ignores updates for unknown ids", () => {
+    expect(updateResource("missing", { name: "x" })).toBeNull()
+  })
+})

app/lib/resources.ts

@@ -0,0 +1,157 @@
+// Resource store — example domain entity.
+// Backed by localStorage today, but written so each call is a single function
+// you can swap with `api.get/post/put/del` once you have a real backend.
+
+import { useEffect, useSyncExternalStore } from "react"
+
+export type Resource = {
+  id: string
+  name: string
+  status: "active" | "paused" | "archived"
+  owner: string
+  createdAt: number
+  updatedAt: number
+}
+
+const STORAGE_KEY = "crema.resources"
+const CHANGE_EVENT = "crema:resources-change"
+
+function newId() {
+  return `r-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`
+}
+
+function readFromStorage(): Resource[] {
+  if (typeof window === "undefined") return []
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY)
+    if (!raw) return []
+    const parsed = JSON.parse(raw)
+    if (!Array.isArray(parsed)) return []
+    return parsed.filter(
+      (r): r is Resource =>
+        r &&
+        typeof r.id === "string" &&
+        typeof r.name === "string" &&
+        ["active", "paused", "archived"].includes(r.status) &&
+        typeof r.owner === "string" &&
+        typeof r.createdAt === "number" &&
+        typeof r.updatedAt === "number",
+    )
+  } catch {
+    return []
+  }
+}
+
+function write(items: Resource[]) {
+  if (typeof window === "undefined") return
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(items))
+    window.dispatchEvent(new CustomEvent(CHANGE_EVENT))
+  } catch {
+    /* quota */
+  }
+}
+
+// CRUD — these mirror what `api.get/post/put/del` would look like.
+export function listResources(): Resource[] {
+  return readFromStorage()
+}
+
+export function createResource(input: {
+  name: string
+  owner: string
+  status?: Resource["status"]
+}): Resource {
+  const now = Date.now()
+  const r: Resource = {
+    id: newId(),
+    name: input.name,
+    owner: input.owner,
+    status: input.status ?? "active",
+    createdAt: now,
+    updatedAt: now,
+  }
+  write([r, ...readFromStorage()])
+  return r
+}
+
+export function updateResource(
+  id: string,
+  patch: Partial<Omit<Resource, "id" | "createdAt">>,
+): Resource | null {
+  const items = readFromStorage()
+  let updated: Resource | null = null
+  const next = items.map((r) => {
+    if (r.id !== id) return r
+    updated = { ...r, ...patch, updatedAt: Date.now() }
+    return updated
+  })
+  if (updated) write(next)
+  return updated
+}
+
+export function deleteResource(id: string) {
+  write(readFromStorage().filter((r) => r.id !== id))
+}
+
+let cached: Resource[] | null = null
+function subscribe(cb: () => void) {
+  const onChange = () => {
+    cached = null
+    cb()
+  }
+  window.addEventListener(CHANGE_EVENT, onChange)
+  window.addEventListener("storage", (e) => {
+    if (e.key === STORAGE_KEY) onChange()
+  })
+  return () => window.removeEventListener(CHANGE_EVENT, onChange)
+}
+function getSnapshot(): Resource[] {
+  if (!cached) cached = readFromStorage()
+  return cached
+}
+function getServerSnapshot(): Resource[] {
+  return []
+}
+
+export function useResources(): Resource[] {
+  const v = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)
+  useEffect(() => {
+    cached = null
+  }, [])
+  return v
+}
+
+/** Seed a few rows on first load so the table isn't empty. */
+export function seedResourcesIfEmpty() {
+  if (typeof window === "undefined") return
+  if (localStorage.getItem(STORAGE_KEY)) return
+  const now = Date.now()
+  const seed: Resource[] = [
+    {
+      id: newId(),
+      name: "Acme dashboard",
+      status: "active",
+      owner: "Atlas",
+      createdAt: now - 86_400_000 * 3,
+      updatedAt: now - 3600_000,
+    },
+    {
+      id: newId(),
+      name: "Onboarding pipeline",
+      status: "paused",
+      owner: "Forge",
+      createdAt: now - 86_400_000 * 7,
+      updatedAt: now - 86_400_000,
+    },
+    {
+      id: newId(),
+      name: "Q1 report draft",
+      status: "archived",
+      owner: "Inkwell",
+      createdAt: now - 86_400_000 * 30,
+      updatedAt: now - 86_400_000 * 14,
+    },
+  ]
+  write(seed)
+}

app/lib/session.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it, beforeEach } from "vitest"
+
+import { hasSession, loadSession, signIn, signOut } from "./session"
+
+describe("session", () => {
+  beforeEach(() => {
+    localStorage.clear()
+  })
+
+  it("starts unauthenticated", () => {
+    expect(loadSession()).toBeNull()
+    expect(hasSession()).toBe(false)
+  })
+
+  it("rejects empty credentials", async () => {
+    await expect(signIn("", "")).rejects.toThrow(/required/i)
+    await expect(signIn("not-an-email", "pw")).rejects.toThrow(/valid email/i)
+    expect(hasSession()).toBe(false)
+  })
+
+  it("creates a session on sign-in and clears on sign-out", async () => {
+    const session = await signIn("alice@example.com", "hunter2")
+    expect(session.email).toBe("alice@example.com")
+    expect(session.token).toMatch(/^dev-/)
+    expect(hasSession()).toBe(true)
+
+    signOut()
+    expect(loadSession()).toBeNull()
+    expect(hasSession()).toBe(false)
+  })
+})

app/lib/session.ts

@@ -0,0 +1,129 @@
+// Session — minimal auth scaffold backed by localStorage.
+// Swap loadSession/signIn/signOut for real calls (cookies + server) when you
+// wire a backend. The shape here matches what AppShell + useUser expect.
+
+import { useEffect, useSyncExternalStore } from "react"
+
+import { profileInitials } from "~/lib/profile"
+
+export type Session = {
+  userId: string
+  name: string
+  email: string
+  token: string
+  // Issued at, ms since epoch.
+  issuedAt: number
+}
+
+const STORAGE_KEY = "crema.session"
+const CHANGE_EVENT = "crema:session-change"
+
+function readFromStorage(): Session | null {
+  if (typeof window === "undefined") return null
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY)
+    if (!raw) return null
+    const parsed = JSON.parse(raw) as Partial<Session>
+    if (
+      typeof parsed.userId !== "string" ||
+      typeof parsed.email !== "string" ||
+      typeof parsed.token !== "string"
+    )
+      return null
+    return {
+      userId: parsed.userId,
+      name:
+        typeof parsed.name === "string" && parsed.name.trim()
+          ? parsed.name
+          : parsed.email,
+      email: parsed.email,
+      token: parsed.token,
+      issuedAt:
+        typeof parsed.issuedAt === "number" ? parsed.issuedAt : Date.now(),
+    }
+  } catch {
+    return null
+  }
+}
+
+export function loadSession(): Session | null {
+  return readFromStorage()
+}
+
+/**
+ * Mock sign-in. Validates only that email + password are non-empty; returns
+ * a fake session. Replace with a real fetch to your auth endpoint.
+ */
+export async function signIn(
+  email: string,
+  password: string,
+): Promise<Session> {
+  await new Promise((r) => setTimeout(r, 250))
+  if (!email.trim() || !password.trim()) {
+    throw new Error("Email and password are required.")
+  }
+  if (!email.includes("@")) {
+    throw new Error("Enter a valid email address.")
+  }
+  const session: Session = {
+    userId: `u-${Date.now().toString(36)}`,
+    name: email.split("@")[0].replace(/\W/g, " ").trim() || email,
+    email,
+    token: `dev-${Math.random().toString(36).slice(2, 14)}`,
+    issuedAt: Date.now(),
+  }
+  if (typeof window !== "undefined") {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(session))
+    window.dispatchEvent(new CustomEvent(CHANGE_EVENT))
+  }
+  return session
+}
+
+export function signOut() {
+  if (typeof window === "undefined") return
+  localStorage.removeItem(STORAGE_KEY)
+  window.dispatchEvent(new CustomEvent(CHANGE_EVENT))
+}
+
+/** True if a non-expired session is in storage. */
+export function hasSession(): boolean {
+  return !!readFromStorage()
+}
+
+let cached: Session | null = null
+let cacheValid = false
+
+function subscribe(cb: () => void): () => void {
+  const onChange = () => {
+    cacheValid = false
+    cb()
+  }
+  window.addEventListener(CHANGE_EVENT, onChange)
+  window.addEventListener("storage", (e) => {
+    if (e.key === STORAGE_KEY) onChange()
+  })
+  return () => window.removeEventListener(CHANGE_EVENT, onChange)
+}
+function getSnapshot(): Session | null {
+  if (!cacheValid) {
+    cached = readFromStorage()
+    cacheValid = true
+  }
+  return cached
+}
+function getServerSnapshot(): Session | null {
+  return null
+}
+
+export function useSession(): Session | null {
+  const s = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)
+  useEffect(() => {
+    cacheValid = false
+  }, [])
+  return s
+}
+
+export function sessionInitials(session: Session | null): string {
+  if (!session) return "?"
+  return profileInitials(session.name || session.email)
+}

app/lib/threads.ts

@@ -3,7 +3,12 @@
 
 import { useEffect, useSyncExternalStore } from "react"
 
-export type ThreadMessage = { role: "user" | "assistant"; content: string }
+export type ThreadMessage = {
+  role: "user" | "assistant"
+  content: string
+  /** Persona that authored this assistant message (omitted for user msgs). */
+  agentId?: string
+}
 
 export type Thread = {
   id: string