docs: update UI rendering to server-driven twrnc

Replace outdated UI Registry model with server-driven
json-render + twrnc approach. Update architecture diagram,
terminology (DataSource→FeedSource, Reconciler→FeedEngine),
and design principles to match current codebase.

Add ui, slots fields to FeedItem in actions spec. Add
Spotify example with twrnc className-based ui tree.

Co-authored-by: Ona <no-reply@ona.com>

apps/aris-backend/package.json

@@ -13,8 +13,6 @@
 		"@aris/source-location": "workspace:*",
 		"@aris/source-tfl": "workspace:*",
 		"@aris/source-weatherkit": "workspace:*",
-		"@hono/trpc-server": "^0.3",
-		"@trpc/server": "^11",
 		"arktype": "^2.1.29",
 		"better-auth": "^1",
 		"hono": "^4",

apps/aris-backend/src/auth/session-middleware.ts

@@ -1,13 +1,20 @@
-import type { Context, Next } from "hono"
+import type { Context, MiddlewareHandler, Next } from "hono"
+
+import type { AuthSession, AuthUser } from "./session.ts"
 
 import { auth } from "./index.ts"
 
-type SessionUser = typeof auth.$Infer.Session.user
-type Session = typeof auth.$Infer.Session.session
-
 export interface SessionVariables {
-	user: SessionUser | null
-	session: Session | null
+	user: AuthUser | null
+	session: AuthSession | null
+}
+
+export type AuthSessionEnv = { Variables: SessionVariables }
+
+export type AuthSessionMiddleware = MiddlewareHandler<AuthSessionEnv>
+
+declare module "hono" {
+	interface ContextVariableMap extends SessionVariables {}
 }
 
 /**
@@ -48,7 +55,22 @@ export async function requireSession(c: Context, next: Next): Promise<Response |
  */
 export async function getSessionFromHeaders(
 	headers: Headers,
-): Promise<{ user: SessionUser; session: Session } | null> {
+): Promise<{ user: AuthUser; session: AuthSession } | null> {
 	const session = await auth.api.getSession({ headers })
 	return session
 }
+
+/**
+ * Test-only middleware that injects a fake user and session.
+ * Pass userId to simulate an authenticated request, or omit to get 401.
+ */
+export function mockAuthSessionMiddleware(userId?: string): AuthSessionMiddleware {
+	return async (c: Context, next: Next): Promise<Response | void> => {
+		if (!userId) {
+			return c.json({ error: "Unauthorized" }, 401)
+		}
+		c.set("user", { id: userId } as AuthUser)
+		c.set("session", { id: "mock-session" } as AuthSession)
+		await next()
+	}
+}

apps/aris-backend/src/auth/session.ts

@@ -0,0 +1,4 @@
+import type { auth } from "./index.ts"
+
+export type AuthUser = typeof auth.$Infer.Session.user
+export type AuthSession = typeof auth.$Infer.Session.session

apps/aris-backend/src/feed/http.test.ts

@@ -0,0 +1,140 @@
+import type { ActionDefinition, Context, FeedItem, FeedSource } from "@aris/core"
+
+import { describe, expect, test } from "bun:test"
+import { Hono } from "hono"
+
+import { mockAuthSessionMiddleware } from "../auth/session-middleware.ts"
+import { UserSessionManager } from "../session/index.ts"
+import { registerFeedHttpHandlers } from "./http.ts"
+
+interface FeedResponse {
+	items: Array<{
+		id: string
+		type: string
+		priority: number
+		timestamp: string
+		data: Record<string, unknown>
+	}>
+	errors: Array<{ sourceId: string; error: string }>
+}
+
+function createStubSource(id: string, items: FeedItem[] = []): FeedSource {
+	return {
+		id,
+		async listActions(): Promise<Record<string, ActionDefinition>> {
+			return {}
+		},
+		async executeAction(): Promise<unknown> {
+			return undefined
+		},
+		async fetchContext(): Promise<Partial<Context> | null> {
+			return null
+		},
+		async fetchItems() {
+			return items
+		},
+	}
+}
+
+function buildTestApp(sessionManager: UserSessionManager, userId?: string) {
+	const app = new Hono()
+	registerFeedHttpHandlers(app, {
+		sessionManager,
+		authSessionMiddleware: mockAuthSessionMiddleware(userId),
+	})
+	return app
+}
+
+describe("GET /api/feed", () => {
+	test("returns 401 without auth", async () => {
+		const manager = new UserSessionManager([])
+		const app = buildTestApp(manager)
+
+		const res = await app.request("/api/feed")
+
+		expect(res.status).toBe(401)
+	})
+
+	test("returns cached feed when available", async () => {
+		const items: FeedItem[] = [
+			{
+				id: "item-1",
+				type: "test",
+				priority: 0.8,
+				timestamp: new Date("2025-01-01T00:00:00.000Z"),
+				data: { value: 42 },
+			},
+		]
+		const manager = new UserSessionManager([() => createStubSource("test", items)])
+		const app = buildTestApp(manager, "user-1")
+
+		// Prime the cache
+		const session = manager.getOrCreate("user-1")
+		await session.engine.refresh()
+		expect(session.engine.lastFeed()).not.toBeNull()
+
+		const res = await app.request("/api/feed")
+
+		expect(res.status).toBe(200)
+		const body = (await res.json()) as FeedResponse
+		expect(body.items).toHaveLength(1)
+		expect(body.items[0]!.id).toBe("item-1")
+		expect(body.items[0]!.type).toBe("test")
+		expect(body.items[0]!.priority).toBe(0.8)
+		expect(body.items[0]!.timestamp).toBe("2025-01-01T00:00:00.000Z")
+		expect(body.errors).toHaveLength(0)
+	})
+
+	test("forces refresh when no cached feed", async () => {
+		const items: FeedItem[] = [
+			{
+				id: "fresh-1",
+				type: "test",
+				priority: 0.5,
+				timestamp: new Date("2025-06-01T12:00:00.000Z"),
+				data: { fresh: true },
+			},
+		]
+		const manager = new UserSessionManager([() => createStubSource("test", items)])
+		const app = buildTestApp(manager, "user-1")
+
+		// No prior refresh — lastFeed() returns null, handler should call refresh()
+		const res = await app.request("/api/feed")
+
+		expect(res.status).toBe(200)
+		const body = (await res.json()) as FeedResponse
+		expect(body.items).toHaveLength(1)
+		expect(body.items[0]!.id).toBe("fresh-1")
+		expect(body.items[0]!.data.fresh).toBe(true)
+		expect(body.errors).toHaveLength(0)
+	})
+
+	test("serializes source errors as message strings", async () => {
+		const failingSource: FeedSource = {
+			id: "failing",
+			async listActions() {
+				return {}
+			},
+			async executeAction() {
+				return undefined
+			},
+			async fetchContext() {
+				return null
+			},
+			async fetchItems() {
+				throw new Error("connection timeout")
+			},
+		}
+		const manager = new UserSessionManager([() => failingSource])
+		const app = buildTestApp(manager, "user-1")
+
+		const res = await app.request("/api/feed")
+
+		expect(res.status).toBe(200)
+		const body = (await res.json()) as FeedResponse
+		expect(body.items).toHaveLength(0)
+		expect(body.errors).toHaveLength(1)
+		expect(body.errors[0]!.sourceId).toBe("failing")
+		expect(body.errors[0]!.error).toBe("connection timeout")
+	})
+})

apps/aris-backend/src/feed/http.ts

@@ -0,0 +1,41 @@
+import type { Context, Hono } from "hono"
+
+import { createMiddleware } from "hono/factory"
+
+import type { AuthSessionMiddleware } from "../auth/session-middleware.ts"
+import type { UserSessionManager } from "../session/index.ts"
+
+type Env = { Variables: { sessionManager: UserSessionManager } }
+
+interface FeedHttpHandlersDeps {
+	sessionManager: UserSessionManager
+	authSessionMiddleware: AuthSessionMiddleware
+}
+
+export function registerFeedHttpHandlers(
+	app: Hono,
+	{ sessionManager, authSessionMiddleware }: FeedHttpHandlersDeps,
+) {
+	const inject = createMiddleware<Env>(async (c, next) => {
+		c.set("sessionManager", sessionManager)
+		await next()
+	})
+
+	app.get("/api/feed", inject, authSessionMiddleware, handleGetFeed)
+}
+
+async function handleGetFeed(c: Context<Env>) {
+	const user = c.get("user")!
+	const sessionManager = c.get("sessionManager")
+	const session = sessionManager.getOrCreate(user.id)
+
+	const feed = session.engine.lastFeed() ?? (await session.engine.refresh())
+
+	return c.json({
+		items: feed.items,
+		errors: feed.errors.map((e) => ({
+			sourceId: e.sourceId,
+			error: e.error.message,
+		})),
+	})
+}

apps/aris-backend/src/location/http.ts

@@ -0,0 +1,56 @@
+import type { Context, Hono } from "hono"
+
+import { type } from "arktype"
+import { createMiddleware } from "hono/factory"
+
+import type { UserSessionManager } from "../session/index.ts"
+
+import { requireSession } from "../auth/session-middleware.ts"
+
+type Env = { Variables: { sessionManager: UserSessionManager } }
+
+const locationInput = type({
+	lat: "number",
+	lng: "number",
+	accuracy: "number",
+	timestamp: "string.date.iso",
+})
+
+export function registerLocationHttpHandlers(
+	app: Hono,
+	{ sessionManager }: { sessionManager: UserSessionManager },
+) {
+	const inject = createMiddleware<Env>(async (c, next) => {
+		c.set("sessionManager", sessionManager)
+		await next()
+	})
+
+	app.post("/api/location", inject, requireSession, handleUpdateLocation)
+}
+
+async function handleUpdateLocation(c: Context<Env>) {
+	let body: unknown
+	try {
+		body = await c.req.json()
+	} catch {
+		return c.json({ error: "Invalid JSON" }, 400)
+	}
+
+	const result = locationInput(body)
+
+	if (result instanceof type.errors) {
+		return c.json({ error: result.summary }, 400)
+	}
+
+	const user = c.get("user")!
+	const sessionManager = c.get("sessionManager")
+	const session = sessionManager.getOrCreate(user.id)
+	await session.engine.executeAction("aris.location", "update-location", {
+		lat: result.lat,
+		lng: result.lng,
+		accuracy: result.accuracy,
+		timestamp: new Date(result.timestamp),
+	})
+
+	return c.body(null, 204)
+}

apps/aris-backend/src/location/router.ts

@@ -1,28 +0,0 @@
-import { type } from "arktype"
-
-import type { UserSessionManager } from "../session/index.ts"
-import type { TRPC } from "../trpc/router.ts"
-
-const locationInput = type({
-	lat: "number",
-	lng: "number",
-	accuracy: "number",
-	timestamp: "Date",
-})
-
-export function createLocationRouter(
-	t: TRPC,
-	{ sessionManager }: { sessionManager: UserSessionManager },
-) {
-	return t.router({
-		update: t.procedure.input(locationInput).mutation(async ({ input, ctx }) => {
-			const session = sessionManager.getOrCreate(ctx.user.id)
-			await session.engine.executeAction("aris.location", "update-location", {
-				lat: input.lat,
-				lng: input.lng,
-				accuracy: input.accuracy,
-				timestamp: input.timestamp,
-			})
-		}),
-	})
-}

apps/aris-backend/src/server.ts

@@ -1,12 +1,12 @@
 import { LocationSource } from "@aris/source-location"
-import { trpcServer } from "@hono/trpc-server"
 import { Hono } from "hono"
 
 import { registerAuthHandlers } from "./auth/http.ts"
+import { requireSession } from "./auth/session-middleware.ts"
+import { registerFeedHttpHandlers } from "./feed/http.ts"
+import { registerLocationHttpHandlers } from "./location/http.ts"
 import { UserSessionManager } from "./session/index.ts"
 import { WeatherSourceProvider } from "./weather/provider.ts"
-import { createContext } from "./trpc/context.ts"
-import { createTRPCRouter } from "./trpc/router.ts"
 
 function main() {
 	const sessionManager = new UserSessionManager([
@@ -21,21 +21,13 @@ function main() {
 		}),
 	])
 
-	const trpcRouter = createTRPCRouter({ sessionManager })
-
 	const app = new Hono()
 
 	app.get("/health", (c) => c.json({ status: "ok" }))
 
 	registerAuthHandlers(app)
-
-	app.use(
-		"/trpc/*",
-		trpcServer({
-			router: trpcRouter,
-			createContext,
-		}),
-	)
+	registerFeedHttpHandlers(app, { sessionManager, authSessionMiddleware: requireSession })
+	registerLocationHttpHandlers(app, { sessionManager })
 
 	return app
 }

apps/aris-backend/src/session/user-session-manager.test.ts

@@ -1,11 +1,11 @@
+import type { WeatherKitClient, WeatherKitResponse } from "@aris/source-weatherkit"
+
 import { LocationSource } from "@aris/source-location"
 import { describe, expect, mock, test } from "bun:test"
 
 import { WeatherSourceProvider } from "../weather/provider.ts"
 import { UserSessionManager } from "./user-session-manager.ts"
 
-import type { WeatherKitClient, WeatherKitResponse } from "@aris/source-weatherkit"
-
 const mockWeatherClient: WeatherKitClient = {
 	fetch: async () => ({}) as WeatherKitResponse,
 }

apps/aris-backend/src/session/user-session-manager.ts

@@ -1,4 +1,5 @@
 import type { FeedSourceProviderInput } from "./feed-source-provider.ts"
+
 import { UserSession } from "./user-session.ts"
 
 export class UserSessionManager {

apps/aris-backend/src/trpc/context.ts

@@ -1,14 +0,0 @@
-import type { FetchCreateContextFnOptions } from "@trpc/server/adapters/fetch"
-
-import { auth } from "../auth/index.ts"
-
-export async function createContext(opts: FetchCreateContextFnOptions) {
-	const session = await auth.api.getSession({ headers: opts.req.headers })
-
-	return {
-		user: session?.user ?? null,
-		session: session?.session ?? null,
-	}
-}
-
-export type Context = Awaited<ReturnType<typeof createContext>>

apps/aris-backend/src/trpc/router.ts

@@ -1,44 +0,0 @@
-import { initTRPC, TRPCError } from "@trpc/server"
-
-import type { UserSessionManager } from "../session/index.ts"
-import type { Context } from "./context.ts"
-
-import { createLocationRouter } from "../location/router.ts"
-
-export type TRPC = ReturnType<typeof createTRPC>
-
-export interface TRPCRouterDeps {
-	sessionManager: UserSessionManager
-}
-
-export function createTRPCRouter({ sessionManager }: TRPCRouterDeps) {
-	const t = createTRPC()
-
-	return t.router({
-		location: createLocationRouter(t, { sessionManager }),
-	})
-}
-
-export type TRPCRouter = ReturnType<typeof createTRPCRouter>
-
-function createTRPC() {
-	const t = initTRPC.context<Context>().create()
-
-	const isAuthed = t.middleware(({ ctx, next }) => {
-		if (!ctx.user || !ctx.session) {
-			throw new TRPCError({ code: "UNAUTHORIZED" })
-		}
-		return next({
-			ctx: {
-				user: ctx.user,
-				session: ctx.session,
-			},
-		})
-	})
-
-	return {
-		router: t.router,
-		procedure: t.procedure.use(isAuthed),
-	}
-}
-

bun.lock

@@ -21,8 +21,6 @@
         "@aris/source-location": "workspace:*",
         "@aris/source-tfl": "workspace:*",
         "@aris/source-weatherkit": "workspace:*",
-        "@hono/trpc-server": "^0.3",
-        "@trpc/server": "^11",
         "arktype": "^2.1.29",
         "better-auth": "^1",
         "hono": "^4",
@@ -468,8 +466,6 @@
 
     "@hapi/topo": ["@hapi/topo@5.1.0", "", { "dependencies": { "@hapi/hoek": "^9.0.0" } }, "sha512-foQZKJig7Ob0BMAYBfcJk8d77QtOe7Wo4ox7ff1lQYoNNAb6jwcY1ncdoy2e9wQZzvNy7ODZCYJkK8kzmcAnAg=="],
 
-    "@hono/trpc-server": ["@hono/trpc-server@0.3.4", "", { "peerDependencies": { "@trpc/server": "^10.10.0 || >11.0.0-rc", "hono": ">=4.*" } }, "sha512-xFOPjUPnII70FgicDzOJy1ufIoBTu8eF578zGiDOrYOrYN8CJe140s9buzuPkX+SwJRYK8LjEBHywqZtxdm8aA=="],
-
     "@humanfs/core": ["@humanfs/core@0.19.1", "", {}, "sha512-5DyQ4+1JEUzejeK1JGICcideyfUbGixgS9jNgex5nqkW+cY7WZhxBigmieN5Qnw9ZosSNVC9KQKyb+GUaGyKUA=="],
 
     "@humanfs/node": ["@humanfs/node@0.16.7", "", { "dependencies": { "@humanfs/core": "^0.19.1", "@humanwhocodes/retry": "^0.4.0" } }, "sha512-/zUx+yOsIrG4Y43Eh2peDeKCxlRt/gET6aHfaKpuq267qXdYDFViVHfMaLyygZOnl0kGWxFIgsBy8QFuTLUXEQ=="],
@@ -686,8 +682,6 @@
 
     "@standard-schema/spec": ["@standard-schema/spec@1.1.0", "", {}, "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w=="],
 
-    "@trpc/server": ["@trpc/server@11.10.0", "", { "peerDependencies": { "typescript": ">=5.7.2" } }, "sha512-zZjTrR6He61e5TiT7e/bQqab/jRcXBZM8Fg78Yoo8uh5pz60dzzbYuONNUCOkafv5ppXVMms4NHYfNZgzw50vg=="],
-
     "@tsconfig/node10": ["@tsconfig/node10@1.0.12", "", {}, "sha512-UCYBaeFvM11aU2y3YPZ//O5Rhj+xKyzy7mvcIoAjASbigy8mHMryP5cK7dgjlz2hWxh1g5pLw084E0a/wlUSFQ=="],
 
     "@tsconfig/node12": ["@tsconfig/node12@1.0.11", "", {}, "sha512-cqefuRsh12pWyGsIoBKJA9luFu3mRxCA+ORZvA4ktLSzIuCUtWVxGIuXigEwO5/ywWFMZ2QEGKWvkZG1zDMTag=="],

docs/architecture-draft.md

@@ -16,8 +16,8 @@ Examples of feed items:
 ## Design Principles
 
 1. **Extensibility**: The core must support different data sources, including third-party sources.
-2. **Separation of concerns**: Core handles data only. UI rendering is a separate system.
-3. **Parallel execution**: Sources run in parallel; no inter-source dependencies.
+2. **Separation of concerns**: Core handles data and UI description. The client is a thin renderer.
+3. **Dependency graph**: Sources declare dependencies on other sources. The engine resolves the graph and runs independent sources in parallel.
 4. **Graceful degradation**: Failed sources are skipped; partial results are returned.
 
 ## Architecture
@@ -25,26 +25,28 @@ Examples of feed items:
 ```
 ┌─────────────────────────────────────────────────────────────┐
 │                         Backend                              │
-│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────┐  │
-│  │  aris-core  │    │   Sources   │    │  UI Registry    │  │
-│  │             │    │  (plugins)  │    │  (schemas from  │  │
-│  │ - Reconciler│◄───│ - Calendar  │    │   third parties)│  │
-│  │ - Context   │    │ - Weather   │    │                 │  │
-│  │ - FeedItem  │    │ - Spotify   │    │                 │  │
-│  └─────────────┘    └─────────────┘    └─────────────────┘  │
-│         │                                      │             │
-│         ▼                                      ▼             │
-│    Feed (data only)                    UI Schemas (JSON)     │
+│  ┌─────────────┐    ┌─────────────┐                         │
+│  │  aris-core  │    │   Sources   │                         │
+│  │             │    │  (plugins)  │                         │
+│  │ - FeedEngine│◄───│ - Calendar  │                         │
+│  │ - Context   │    │ - Weather   │                         │
+│  │ - FeedItem  │    │ - TfL       │                         │
+│  │ - Actions   │    │ - Spotify   │                         │
+│  └─────────────┘    └─────────────┘                         │
+│         │                                                    │
+│         ▼                                                    │
+│    Feed items (data + ui trees + slots)                      │
 └─────────────────────────────────────────────────────────────┘
-                    │                           │
-                    ▼                           ▼
+                    │
+                    ▼ (WebSocket / JSON-RPC)
 ┌─────────────────────────────────────────────────────────────┐
-│                        Frontend                              │
+│                    Client (React Native)                      │
 │  ┌──────────────────────────────────────────────────────┐   │
-│  │  Renderer                                             │   │
-│  │  - Receives feed items                                │   │
-│  │  - Fetches UI schema by item type                     │   │
-│  │  - Renders using json-render or similar               │   │
+│  │  json-render + twrnc component map                    │   │
+│  │  - Receives feed items with ui trees                  │   │
+│  │  - Renders using registered RN components + twrnc     │   │
+│  │  - User interactions trigger source actions           │   │
+│  │  - Bespoke native components for rich interactions    │   │
 │  └──────────────────────────────────────────────────────┘   │
 └─────────────────────────────────────────────────────────────┘
 ```
@@ -54,15 +56,16 @@ Examples of feed items:
 The core is responsible for:
 
 - Defining the context and feed item interfaces
-- Providing a reconciler that orchestrates data sources
+- Providing a `FeedEngine` that orchestrates sources via a dependency graph
 - Returning a flat list of prioritized feed items
+- Routing action execution to the correct source
 
 ### Key Concepts
 
-- **Context**: Time and location (with accuracy) passed to all sources
-- **FeedItem**: Has an ID (source-generated, stable), type, priority, timestamp, and JSON-serializable data
-- **DataSource**: Interface that third parties implement to provide feed items
-- **Reconciler**: Orchestrates sources, runs them in parallel, returns items and any errors
+- **Context**: Time and location (with accuracy) passed to all sources. Sources can contribute to context (e.g., location source provides coordinates, weather source provides conditions).
+- **FeedItem**: Has an ID (source-generated, stable), type, timestamp, JSON-serializable data, optional actions, an optional `ui` tree, and optional `slots` for LLM-fillable content.
+- **FeedSource**: Interface that first and third parties implement to provide context, feed items, and actions. Uses reverse-domain IDs (e.g., `aris.weather`, `com.spotify`).
+- **FeedEngine**: Orchestrates sources respecting their dependency graph, runs independent sources in parallel, returns items and any errors. Routes action execution to the correct source.
 
 ## Data Sources
 
@@ -71,10 +74,13 @@ Key decisions:
 - Sources receive the full context and decide internally what to use
 - Each source returns a single item type (e.g., separate "Calendar Source" and "Location Suggestion Source" rather than a combined "Google Source")
 - Sources live in separate packages, not in the core
+- Sources declare dependencies on other sources (e.g., weather depends on location)
 - Sources are responsible for:
   - Transforming their domain data into feed items
   - Assigning priority based on domain logic (e.g., "event starting in 10 minutes" = high priority)
   - Returning empty arrays when nothing is relevant
+  - Providing a `ui` tree for each feed item
+  - Declaring and handling actions (e.g., RSVP, complete task, play/pause)
 
 ### Configuration
 
@@ -83,28 +89,323 @@ Configuration is passed at source registration time, not per reconcile call. Sou
 ## Feed Output
 
 - Flat list of `FeedItem` objects
-- No UI information (no icons, card types, etc.)
+- Items carry data, an optional `ui` field describing their layout, and optional `slots` for LLM enhancement
 - Items are a discriminated union by `type` field
-- Reconciler sorts by priority; can act as tiebreaker
 
-## UI Rendering (Separate from Core)
+## UI Rendering: Server-Driven UI
 
-The core does not handle UI. For extensible third-party UI:
+The UI for feed items is **server-driven**. Sources describe how their items look using a JSON tree (the `ui` field on `FeedItem`). The client renders these trees using [json-render](https://json-render.dev/) with a registered set of React Native components styled via [twrnc](https://github.com/jaredh159/tailwind-react-native-classnames).
 
-1. Third-party apps register their UI schemas through the backend (UI Registry)
-2. Frontend fetches UI schemas from the backend
-3. Frontend matches feed items to schemas by `type` and renders accordingly
+### How it works
 
-This approach:
+1. Sources return feed items with a `ui` field — a JSON tree describing the card layout using Tailwind class strings.
+2. The client passes a component map to json-render. Each component wraps a React Native primitive and resolves `className` via twrnc.
+3. json-render walks the tree and renders native components. twrnc parses Tailwind classes at runtime — no build step, arbitrary values work.
+4. User interactions (tap, etc.) map to source actions via the `actions` field on `FeedItem`. The client sends action requests to the backend, which routes them to the correct source via `FeedEngine.executeAction()`.
 
-- Keeps the core focused on data
-- Works across platforms (web, React Native)
-- Avoids the need for third parties to inject code into the app
-- Uses a json-render style approach for declarative UI from JSON schemas
+### Styling
 
-Reference: https://github.com/vercel-labs/json-render
+- Sources use Tailwind CSS class strings via the `className` prop (e.g., `"p-4 bg-white dark:bg-black rounded-xl"`).
+- twrnc resolves classes to React Native style objects at runtime. Supports arbitrary values (`mt-[31px]`, `bg-[#eaeaea]`), dark mode (`dark:bg-black`), and platform prefixes (`ios:pt-4 android:pt-2`).
+- Custom colors and spacing are configured via `tailwind.config.js` on the client.
+- No compile-time constraint — all styles resolve at runtime.
+
+### Two tiers of UI
+
+- **Server-driven (default):** Any source can return a `ui` tree. Covers most cards — weather, tasks, alerts, package tracking, news, etc. Simple interactions go through source actions. This is the default path for both first-party and third-party sources.
+- **Bespoke native:** For cards that need rich client interaction (gestures, animations, real-time updates), a native React Native component is registered in the json-render component map and referenced by type. Third parties that need this level of richness work with the ARIS team to get it integrated.
+
+### Why server-driven
+
+- Feed items are inherently server-driven — the data comes from sources on the backend. Attaching the layout alongside the data is a natural extension.
+- Card designs can be updated without shipping an app update.
+- Third-party sources can ship their own UI without bundling anything new into the app.
+
+Reference: https://json-render.dev/
+
+## Feed Items with UI and Slots
+
+> Note: the codebase has evolved since the sections above. The engine now uses a dependency graph with topological ordering (`FeedEngine`, `FeedSource`), not the parallel reconciler described above. The `priority` field is being replaced by post-processing (see the ideas doc). This section describes the UI and enhancement architecture going forward.
+
+Feed items carry an optional `ui` field containing a json-render tree, and an optional `slots` field for LLM-fillable content.
+
+```typescript
+interface FeedItem<TType, TData> {
+  id: string
+  type: TType
+  timestamp: Date
+  data: TData
+  ui?: JsonRenderNode
+  slots?: Record<string, Slot>
+}
+
+interface Slot {
+  /** Tells the LLM what this slot wants — the source writes this */
+  description: string
+  /** LLM-filled text content, null until enhanced */
+  content: string | null
+}
+```
+
+### How it works
+
+The source produces the item with a UI tree and empty slots:
+
+```typescript
+// Weather source produces:
+{
+  id: "weather-current-123",
+  type: "weather-current",
+  data: { temperature: 18, condition: "cloudy" },
+  ui: {
+    component: "VStack",
+    children: [
+      { component: "WeatherHeader", props: { temp: 18, condition: "cloudy" } },
+      { component: "Slot", props: { name: "insight" } },
+      { component: "HourlyChart", props: { hours: [...] } },
+      { component: "Slot", props: { name: "cross-source" } },
+    ]
+  },
+  slots: {
+    "insight": {
+      description: "A short contextual insight about the current weather and how it affects the user's day",
+      content: null
+    },
+    "cross-source": {
+      description: "Connection between weather and the user's calendar events or plans",
+      content: null
+    }
+  }
+}
+```
+
+The LLM enhancement harness fills `content`:
+
+```typescript
+slots: {
+  "insight": {
+    description: "...",
+    content: "Rain after 3pm — grab a jacket before your walk"
+  },
+  "cross-source": {
+    description: "...",
+    content: "Should be dry by 7pm for your dinner at The Ivy"
+  }
+}
+```
+
+The client renders the `ui` tree. When it hits a `Slot` node, it looks up `slots[name].content`. If non-null, render the text. If null, render nothing.
+
+### Separation of concerns
+
+- **Sources** own the UI layout and declare what slots exist with descriptions.
+- **The LLM** fills slot content. It doesn't know about layout or positioning.
+- **The client** renders the UI tree and resolves slots to their content.
+
+Sources define the prompt for each slot via the `description` field. The harness doesn't need to know what slots any source type has — it reads them dynamically from the items.
+
+Each source defines its own slots. The harness handles them automatically — no central registry needed.
+
+## Enhancement Harness
+
+The LLM enhancement harness fills slots and produces synthetic feed items. It runs reactively — triggered by context changes, not by a timer.
+
+### Execution model
+
+```
+FeedEngine.refresh()
+  → sources produce items with ui + empty slots
+         ↓
+Fast path (rule-based post-processors, <10ms)
+  → group, dedup, affinity, time-adjust
+  → merge LAST cached slot fills + synthetic items
+  → return feed to UI immediately
+         ↓
+Background: has context changed since last LLM run?
+  (hash of: item IDs + data + slot descriptions + user memory)
+         ↓
+No  → done, cache is still valid
+Yes → run LLM harness async
+      → fill slots + generate synthetic items
+      → cache result
+      → push updated feed to UI via WebSocket
+```
+
+The user never waits for the LLM. They see the feed instantly with the previous enhancement applied. If the LLM produces new slot content or synthetic items, the feed updates in place.
+
+### LLM input
+
+The harness serializes items with their unfilled slots into a single prompt. Items without slots are excluded. The LLM sees everything at once and fills whatever slots are relevant.
+
+```typescript
+function buildHarnessInput(
+  items: FeedItem[],
+  context: AgentContext,
+): HarnessInput {
+  const itemsWithSlots = items
+    .filter(item => item.slots && Object.keys(item.slots).length > 0)
+    .map(item => ({
+      id: item.id,
+      type: item.type,
+      data: item.data,
+      slots: Object.fromEntries(
+        Object.entries(item.slots!).map(
+          ([name, slot]) => [name, slot.description]
+        )
+      ),
+    }))
+
+  return {
+    items: itemsWithSlots,
+    userMemory: context.preferences,
+    currentTime: new Date().toISOString(),
+  }
+}
+```
+
+The LLM sees:
+
+```json
+{
+  "items": [
+    {
+      "id": "weather-current-123",
+      "type": "weather-current",
+      "data": { "temperature": 18, "condition": "cloudy" },
+      "slots": {
+        "insight": "A short contextual insight about the current weather and how it affects the user's day",
+        "cross-source": "Connection between weather and the user's calendar events or plans"
+      }
+    },
+    {
+      "id": "calendar-event-456",
+      "type": "calendar-event",
+      "data": { "title": "Dinner at The Ivy", "startTime": "19:00", "location": "The Ivy, West St" },
+      "slots": {
+        "context": "Background on this event, attendees, or previous meetings with these people",
+        "logistics": "Travel time, parking, directions to the venue",
+        "weather": "Weather conditions relevant to this event's time and location"
+      }
+    }
+  ],
+  "userMemory": { "commute": "victoria-line", "preference.walking_distance": "1 mile" },
+  "currentTime": "2025-02-26T14:30:00Z"
+}
+```
+
+### LLM output
+
+A flat map of item ID → slot name → text content. Slots left null are unfilled.
+
+```json
+{
+  "slotFills": {
+    "weather-current-123": {
+      "insight": "Rain after 3pm — grab a jacket before your walk",
+      "cross-source": "Should be dry by 7pm for your dinner at The Ivy"
+    },
+    "calendar-event-456": {
+      "context": null,
+      "logistics": "20-minute walk from home — leave by 18:40",
+      "weather": "Rain clears by evening, you'll be fine"
+    }
+  },
+  "syntheticItems": [
+    {
+      "id": "briefing-morning",
+      "type": "briefing",
+      "data": {},
+      "ui": { "component": "Text", "props": { "text": "Light afternoon — just your dinner at 7. Rain clears by then." } }
+    }
+  ],
+  "suppress": [],
+  "rankingHints": {}
+}
+```
+
+### Enhancement manager
+
+One per user, living in the `FeedEngineManager` on the backend:
+
+```typescript
+class EnhancementManager {
+  private cache: EnhancementResult | null = null
+  private lastInputHash: string | null = null
+  private running = false
+
+  async enhance(
+    items: FeedItem[],
+    context: AgentContext,
+  ): Promise<EnhancementResult> {
+    const hash = computeHash(items, context)
+
+    if (hash === this.lastInputHash && this.cache) {
+      return this.cache
+    }
+
+    if (this.running) {
+      return this.cache ?? emptyResult()
+    }
+
+    this.running = true
+    this.runHarness(items, context)
+      .then(result => {
+        this.cache = result
+        this.lastInputHash = hash
+        this.notifySubscribers(result)
+      })
+      .finally(() => { this.running = false })
+
+    return this.cache ?? emptyResult()
+  }
+}
+
+interface EnhancementResult {
+  slotFills: Record<string, Record<string, string | null>>
+  syntheticItems: FeedItem[]
+  suppress: string[]
+  rankingHints: Record<string, number>
+}
+```
+
+### Merging
+
+After the harness runs, the engine merges slot fills into items:
+
+```typescript
+function mergeEnhancement(
+  items: FeedItem[],
+  result: EnhancementResult,
+): FeedItem[] {
+  return items.map(item => {
+    const fills = result.slotFills[item.id]
+    if (!fills || !item.slots) return item
+
+    const mergedSlots = { ...item.slots }
+    for (const [name, content] of Object.entries(fills)) {
+      if (name in mergedSlots && content !== null) {
+        mergedSlots[name] = { ...mergedSlots[name], content }
+      }
+    }
+
+    return { ...item, slots: mergedSlots }
+  })
+}
+```
+
+### Cost control
+
+- **Hash-based cache gate.** Most refreshes reuse the cached result.
+- **Debounce.** Rapid context changes (location updates) settle before triggering a run.
+- **Skip inactive users.** Don't run if the user hasn't opened the app in 2+ hours.
+- **Exclude slotless items.** Only items with slots are sent to the LLM.
+- **Text-only output.** Slots produce strings, not UI trees — fewer output tokens, less variance.
 
 ## Open Questions
 
-- Exact schema format for UI registry
-- How third parties authenticate/register their sources and UI schemas
+- How third parties authenticate/register their sources
+- Exact set of React Native components exposed in the json-render component map
+- Validation/sandboxing of third-party ui trees
+- How synthetic items define their UI (full json-render tree vs. registered component)
+- Should slots support rich content (json-render nodes) in the future, or stay text-only?
+- How to handle slot content that references other items (e.g., "your dinner at The Ivy" linking to the calendar card)

docs/feed-source-actions-spec.md

@@ -125,7 +125,7 @@ interface FeedSource<TItem extends FeedItem = FeedItem> {
 
 ### Changes to FeedItem
 
-One optional field added.
+Optional fields added for actions, server-driven UI, and LLM slots.
 
 ```typescript
 interface FeedItem<
@@ -140,6 +140,12 @@ interface FeedItem<
 
 	/** Actions the user can take on this item. */
 	actions?: readonly ItemAction[]
+
+	/** Server-driven UI tree rendered by json-render on the client. */
+	ui?: JsonRenderNode
+
+	/** Named slots for LLM-fillable content. See architecture-draft.md. */
+	slots?: Record<string, Slot>
 }
 ```
 
@@ -222,6 +228,25 @@ class SpotifySource implements FeedSource<SpotifyFeedItem> {
 					{ actionId: "skip-track" },
 					{ actionId: "like-track", params: { trackId: track.id } },
 				],
+				ui: {
+					type: "View",
+					className: "flex-row items-center p-3 gap-3 bg-white dark:bg-black rounded-xl",
+					children: [
+						{
+							type: "Image",
+							source: { uri: track.albumArt },
+							className: "w-12 h-12 rounded-lg",
+						},
+						{
+							type: "View",
+							className: "flex-1",
+							children: [
+								{ type: "Text", className: "font-semibold text-black dark:text-white", text: track.name },
+								{ type: "Text", className: "text-sm text-gray-500 dark:text-gray-400", text: track.artist },
+							],
+						},
+					],
+				},
 			},
 		]
 	}
@@ -236,6 +261,8 @@ class SpotifySource implements FeedSource<SpotifyFeedItem> {
 4. `FeedSource.listActions()` is a required method returning `Record<string, ActionDefinition>` (empty record if no actions)
 5. `FeedSource.executeAction()` is a required method (no-op for sources without actions)
 6. `FeedItem.actions` is an optional readonly array of `ItemAction`
+6b. `FeedItem.ui` is an optional json-render tree describing server-driven UI
+6c. `FeedItem.slots` is an optional record of named LLM-fillable slots
 7. `FeedEngine.executeAction()` routes to correct source, returns `ActionResult`
 8. `FeedEngine.listActions()` aggregates actions from all sources
 9. Existing tests pass unchanged (all changes are additive)

packages/aris-core/src/feed-engine.test.ts

@@ -638,4 +638,290 @@ describe("FeedEngine", () => {
 			)
 		})
 	})
+
+	describe("lastFeed", () => {
+		test("returns null before any refresh", () => {
+			const engine = new FeedEngine()
+
+			expect(engine.lastFeed()).toBeNull()
+		})
+
+		test("returns cached result after refresh", async () => {
+			const location = createLocationSource()
+			location.simulateUpdate({ lat: 51.5, lng: -0.1 })
+
+			const weather = createWeatherSource()
+			const engine = new FeedEngine().register(location).register(weather)
+
+			const refreshResult = await engine.refresh()
+
+			const cached = engine.lastFeed()
+			expect(cached).not.toBeNull()
+			expect(cached!.items).toEqual(refreshResult.items)
+			expect(cached!.context).toEqual(refreshResult.context)
+		})
+
+		test("returns null after TTL expires", async () => {
+			const engine = new FeedEngine({ cacheTtlMs: 50 })
+			const location = createLocationSource()
+			location.simulateUpdate({ lat: 51.5, lng: -0.1 })
+
+			engine.register(location)
+			await engine.refresh()
+
+			expect(engine.lastFeed()).not.toBeNull()
+
+			await new Promise((resolve) => setTimeout(resolve, 60))
+
+			expect(engine.lastFeed()).toBeNull()
+		})
+
+		test("defaults to 5 minute TTL", async () => {
+			const engine = new FeedEngine()
+			const location = createLocationSource()
+			location.simulateUpdate({ lat: 51.5, lng: -0.1 })
+
+			engine.register(location)
+			await engine.refresh()
+
+			// Should still be cached immediately
+			expect(engine.lastFeed()).not.toBeNull()
+		})
+
+		test("refresh always fetches from sources", async () => {
+			let fetchCount = 0
+			const source: FeedSource = {
+				id: "counter",
+				...noActions,
+				async fetchContext() {
+					fetchCount++
+					return null
+				},
+			}
+
+			const engine = new FeedEngine().register(source)
+
+			await engine.refresh()
+			await engine.refresh()
+			await engine.refresh()
+
+			expect(fetchCount).toBe(3)
+		})
+
+		test("reactive context update refreshes cache", async () => {
+			const location = createLocationSource()
+			const weather = createWeatherSource()
+
+			const engine = new FeedEngine({ cacheTtlMs: 5000 }).register(location).register(weather)
+
+			engine.start()
+
+			// Simulate location update which triggers reactive refresh
+			location.simulateUpdate({ lat: 51.5, lng: -0.1 })
+
+			// Wait for async reactive refresh to complete
+			await new Promise((resolve) => setTimeout(resolve, 50))
+
+			const cached = engine.lastFeed()
+			expect(cached).not.toBeNull()
+			expect(cached!.items.length).toBeGreaterThan(0)
+
+			engine.stop()
+		})
+
+		test("reactive item update refreshes cache", async () => {
+			let itemUpdateCallback: (() => void) | null = null
+
+			const source: FeedSource = {
+				id: "reactive-items",
+				...noActions,
+				async fetchContext() {
+					return null
+				},
+				async fetchItems() {
+					return [
+						{
+							id: "item-1",
+							type: "test",
+							priority: 0.5,
+							timestamp: new Date(),
+							data: {},
+						},
+					]
+				},
+				onItemsUpdate(callback) {
+					itemUpdateCallback = callback
+					return () => {
+						itemUpdateCallback = null
+					}
+				},
+			}
+
+			const engine = new FeedEngine().register(source)
+			engine.start()
+
+			// Trigger item update
+			itemUpdateCallback!()
+
+			// Wait for async refresh
+			await new Promise((resolve) => setTimeout(resolve, 50))
+
+			const cached = engine.lastFeed()
+			expect(cached).not.toBeNull()
+			expect(cached!.items).toHaveLength(1)
+
+			engine.stop()
+		})
+
+		test("TTL resets after reactive update", async () => {
+			const location = createLocationSource()
+			const weather = createWeatherSource()
+
+			const engine = new FeedEngine({ cacheTtlMs: 100 }).register(location).register(weather)
+
+			engine.start()
+
+			// Initial reactive update
+			location.simulateUpdate({ lat: 51.5, lng: -0.1 })
+			await new Promise((resolve) => setTimeout(resolve, 50))
+
+			expect(engine.lastFeed()).not.toBeNull()
+
+			// Wait 70ms (total 120ms from first update, past original TTL)
+			// but trigger another update at 50ms to reset TTL
+			location.simulateUpdate({ lat: 52.0, lng: -0.2 })
+			await new Promise((resolve) => setTimeout(resolve, 50))
+
+			// Should still be cached because TTL was reset by second update
+			expect(engine.lastFeed()).not.toBeNull()
+
+			engine.stop()
+		})
+
+		test("cacheTtlMs is configurable", async () => {
+			const engine = new FeedEngine({ cacheTtlMs: 30 })
+			const location = createLocationSource()
+			location.simulateUpdate({ lat: 51.5, lng: -0.1 })
+
+			engine.register(location)
+			await engine.refresh()
+
+			expect(engine.lastFeed()).not.toBeNull()
+
+			await new Promise((resolve) => setTimeout(resolve, 40))
+
+			expect(engine.lastFeed()).toBeNull()
+		})
+
+		test("auto-refreshes on TTL interval after start", async () => {
+			let fetchCount = 0
+			const source: FeedSource = {
+				id: "counter",
+				...noActions,
+				async fetchContext() {
+					fetchCount++
+					return null
+				},
+				async fetchItems() {
+					return [
+						{
+							id: `item-${fetchCount}`,
+							type: "test",
+							priority: 0.5,
+							timestamp: new Date(),
+							data: {},
+						},
+					]
+				},
+			}
+
+			const engine = new FeedEngine({ cacheTtlMs: 50 }).register(source)
+			engine.start()
+
+			// Wait for two TTL intervals to elapse
+			await new Promise((resolve) => setTimeout(resolve, 120))
+
+			// Should have auto-refreshed at least twice
+			expect(fetchCount).toBeGreaterThanOrEqual(2)
+			expect(engine.lastFeed()).not.toBeNull()
+
+			engine.stop()
+		})
+
+		test("stop cancels periodic refresh", async () => {
+			let fetchCount = 0
+			const source: FeedSource = {
+				id: "counter",
+				...noActions,
+				async fetchContext() {
+					fetchCount++
+					return null
+				},
+			}
+
+			const engine = new FeedEngine({ cacheTtlMs: 50 }).register(source)
+			engine.start()
+			engine.stop()
+
+			const countAfterStop = fetchCount
+
+			// Wait past TTL
+			await new Promise((resolve) => setTimeout(resolve, 80))
+
+			// No additional fetches after stop
+			expect(fetchCount).toBe(countAfterStop)
+		})
+
+		test("reactive update resets periodic refresh timer", async () => {
+			let fetchCount = 0
+			const location = createLocationSource()
+			const countingWeather: FeedSource<WeatherFeedItem> = {
+				id: "weather",
+				dependencies: ["location"],
+				...noActions,
+				async fetchContext(ctx) {
+					fetchCount++
+					const loc = contextValue(ctx, LocationKey)
+					if (!loc) return null
+					return { [WeatherKey]: { temperature: 20, condition: "sunny" } }
+				},
+				async fetchItems(ctx) {
+					const weather = contextValue(ctx, WeatherKey)
+					if (!weather) return []
+					return [
+						{
+							id: `weather-${Date.now()}`,
+							type: "weather",
+							priority: 0.5,
+							timestamp: new Date(),
+							data: { temperature: weather.temperature, condition: weather.condition },
+						},
+					]
+				},
+			}
+
+			const engine = new FeedEngine({ cacheTtlMs: 100 })
+				.register(location)
+				.register(countingWeather)
+
+			engine.start()
+
+			// At 40ms, push a reactive update — this resets the timer
+			await new Promise((resolve) => setTimeout(resolve, 40))
+			const countBeforeUpdate = fetchCount
+			location.simulateUpdate({ lat: 51.5, lng: -0.1 })
+			await new Promise((resolve) => setTimeout(resolve, 20))
+
+			// Reactive update triggered a fetch
+			expect(fetchCount).toBeGreaterThan(countBeforeUpdate)
+			const countAfterUpdate = fetchCount
+
+			// At 100ms from start (60ms after reactive update), the original
+			// timer would have fired, but it was reset. No extra fetch yet.
+			await new Promise((resolve) => setTimeout(resolve, 40))
+			expect(fetchCount).toBe(countAfterUpdate)
+
+			engine.stop()
+		})
+	})
 })

packages/aris-core/src/feed-engine.ts

@@ -16,6 +16,14 @@ export interface FeedResult<TItem extends FeedItem = FeedItem> {
 
 export type FeedSubscriber<TItem extends FeedItem = FeedItem> = (result: FeedResult<TItem>) => void
 
+const DEFAULT_CACHE_TTL_MS = 300_000 // 5 minutes
+const MIN_CACHE_TTL_MS = 10 // prevent spin from zero/negative values
+
+export interface FeedEngineConfig {
+	/** Cache TTL in milliseconds. Default: 300_000 (5 minutes). Minimum: 10. */
+	cacheTtlMs?: number
+}
+
 interface SourceGraph {
 	sources: Map<string, FeedSource>
 	sorted: FeedSource[]
@@ -59,6 +67,29 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
 	private cleanups: Array<() => void> = []
 	private started = false
 
+	private readonly cacheTtlMs: number
+	private cachedResult: FeedResult<TItems> | null = null
+	private cachedAt: number | null = null
+	private refreshTimer: ReturnType<typeof setTimeout> | null = null
+
+	constructor(config?: FeedEngineConfig) {
+		this.cacheTtlMs = Math.max(config?.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS, MIN_CACHE_TTL_MS)
+	}
+
+	/**
+	 * Returns the cached FeedResult if available and not expired.
+	 * Returns null if no refresh has completed or the cache TTL has elapsed.
+	 */
+	lastFeed(): FeedResult<TItems> | null {
+		if (this.cachedResult === null || this.cachedAt === null) {
+			return null
+		}
+		if (Date.now() - this.cachedAt > this.cacheTtlMs) {
+			return null
+		}
+		return this.cachedResult
+	}
+
 	/**
 	 * Registers a FeedSource. Invalidates the cached graph.
 	 */
@@ -124,7 +155,10 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
 
 		this.context = context
 
-		return { context, items: items as TItems[], errors }
+		const result: FeedResult<TItems> = { context, items: items as TItems[], errors }
+		this.updateCache(result)
+
+		return result
 	}
 
 	/**
@@ -138,7 +172,7 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
 	}
 
 	/**
-	 * Starts reactive subscriptions on all sources.
+	 * Starts reactive subscriptions on all sources and begins periodic refresh.
 	 * Sources with onContextUpdate will trigger re-computation of dependents.
 	 */
 	start(): void {
@@ -168,13 +202,16 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
 				this.cleanups.push(cleanup)
 			}
 		}
+
+		this.scheduleNextRefresh()
 	}
 
 	/**
-	 * Stops all reactive subscriptions.
+	 * Stops all reactive subscriptions and the periodic refresh timer.
 	 */
 	stop(): void {
 		this.started = false
+		this.cancelScheduledRefresh()
 		for (const cleanup of this.cleanups) {
 			cleanup()
 		}
@@ -279,11 +316,14 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
 
 		items.sort((a, b) => b.priority - a.priority)
 
-		this.notifySubscribers({
+		const result: FeedResult<TItems> = {
 			context: this.context,
 			items: items as TItems[],
 			errors,
-		})
+		}
+		this.updateCache(result)
+
+		this.notifySubscribers(result)
 	}
 
 	private collectDependents(sourceId: string, graph: SourceGraph): string[] {
@@ -307,11 +347,46 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
 		return graph.sorted.filter((s) => result.includes(s.id)).map((s) => s.id)
 	}
 
+	private updateCache(result: FeedResult<TItems>): void {
+		this.cachedResult = result
+		this.cachedAt = Date.now()
+		if (this.started) {
+			this.scheduleNextRefresh()
+		}
+	}
+
+	private scheduleNextRefresh(): void {
+		this.cancelScheduledRefresh()
+		this.refreshTimer = setTimeout(() => {
+			this.refresh()
+				.then((result) => {
+					this.notifySubscribers(result)
+				})
+				.catch(() => {
+					// Periodic refresh errors are non-fatal; schedule next attempt
+					if (this.started) {
+						this.scheduleNextRefresh()
+					}
+				})
+		}, this.cacheTtlMs)
+	}
+
+	private cancelScheduledRefresh(): void {
+		if (this.refreshTimer !== null) {
+			clearTimeout(this.refreshTimer)
+			this.refreshTimer = null
+		}
+	}
+
 	private scheduleRefresh(): void {
 		// Simple immediate refresh for now - could add debouncing later
-		this.refresh().then((result) => {
-			this.notifySubscribers(result)
-		})
+		this.refresh()
+			.then((result) => {
+				this.notifySubscribers(result)
+			})
+			.catch(() => {
+				// Reactive refresh errors are non-fatal
+			})
 	}
 
 	private notifySubscribers(result: FeedResult<TItems>): void {

packages/aris-core/src/index.ts

@@ -13,7 +13,7 @@ export type { FeedItem } from "./feed"
 export type { FeedSource } from "./feed-source"
 
 // Feed Engine
-export type { FeedResult, FeedSubscriber, SourceError } from "./feed-engine"
+export type { FeedEngineConfig, FeedResult, FeedSubscriber, SourceError } from "./feed-engine"
 export { FeedEngine } from "./feed-engine"
 
 // =============================================================================