fix: move twrnc dep to aris-client

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

.devcontainer/devcontainer.json

@@ -10,12 +10,13 @@
 		"context": ".",
 		"dockerfile": "Dockerfile"
 	},
-	"postStartCommand": "./scripts/setup-git.sh && ./scripts/setup-nvim.sh"
+	"postCreateCommand": "bun install",
+	"postStartCommand": "./scripts/setup-git.sh && ./scripts/setup-nvim.sh",
 	// Features add additional features to your environment. See https://containers.dev/features
 	// Beware: features are not supported on all platforms and may have unintended side-effects.
-	// "features": {
-	//   "ghcr.io/devcontainers/features/docker-in-docker": {
-	//     "moby": false
-	//   }
-	// }
+	"features": {
+		"ghcr.io/tailscale/codespace/tailscale": {
+			"version": "latest"
+		}
+	}
 }

.gitignore

@@ -32,3 +32,4 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 
 # Finder (MacOS) folder config
 .DS_Store
+core

.ona/automations.yaml

@@ -0,0 +1,8 @@
+services:
+  expo:
+    name: Expo Dev Server
+    description: Expo development server for aris-client
+    triggeredBy:
+      - postDevcontainerStart
+    commands:
+      start: cd apps/aris-client && ./scripts/run-dev-server.sh

README.md

@@ -8,14 +8,14 @@ bun install
 
 ## Packages
 
-### @aris/data-source-tfl
+### @aris/source-tfl
 
-TfL (Transport for London) data source for tube, overground, and Elizabeth line alerts.
+TfL (Transport for London) feed source for tube, overground, and Elizabeth line alerts.
 
 #### Testing
 
 ```bash
-cd packages/aris-data-source-tfl
+cd packages/aris-source-tfl
 bun run test
 ```
 

apps/aris-backend/.env.example

@@ -0,0 +1,14 @@
+# PostgreSQL connection string
+DATABASE_URL=postgresql://user:password@localhost:5432/aris
+
+# BetterAuth secret (min 32 chars, generate with: openssl rand -base64 32)
+BETTER_AUTH_SECRET=
+
+# Base URL of the backend
+BETTER_AUTH_URL=http://localhost:3000
+
+# Apple WeatherKit credentials
+WEATHERKIT_PRIVATE_KEY=
+WEATHERKIT_KEY_ID=
+WEATHERKIT_TEAM_ID=
+WEATHERKIT_SERVICE_ID=

apps/aris-backend/package.json

@@ -2,18 +2,25 @@
 	"name": "@aris/backend",
 	"version": "0.0.0",
 	"type": "module",
-	"main": "src/index.ts",
+	"main": "src/server.ts",
 	"scripts": {
-		"dev": "bun run --watch src/index.ts",
-		"start": "bun run src/index.ts",
+		"dev": "bun run --watch src/server.ts",
+		"start": "bun run src/server.ts",
 		"test": "bun test src/"
 	},
 	"dependencies": {
 		"@aris/core": "workspace:*",
 		"@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",
-		"postgres": "^3"
+		"pg": "^8"
+	},
+	"devDependencies": {
+		"@types/pg": "^8"
 	}
 }

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

@@ -0,0 +1,7 @@
+import type { Hono } from "hono"
+
+import { auth } from "./index.ts"
+
+export function registerAuthHandlers(app: Hono): void {
+	app.on(["POST", "GET"], "/api/auth/*", (c) => auth.handler(c.req.raw))
+}

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

@@ -0,0 +1,10 @@
+import { betterAuth } from "better-auth"
+
+import { pool } from "../db.ts"
+
+export const auth = betterAuth({
+	database: pool,
+	emailAndPassword: {
+		enabled: true,
+	},
+})

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

@@ -0,0 +1,54 @@
+import type { Context, Next } from "hono"
+
+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
+}
+
+/**
+ * Middleware that attaches session and user to the context.
+ * Does not reject unauthenticated requests - use requireSession for that.
+ */
+export async function sessionMiddleware(c: Context, next: Next): Promise<void> {
+	const session = await auth.api.getSession({ headers: c.req.raw.headers })
+
+	if (session) {
+		c.set("user", session.user)
+		c.set("session", session.session)
+	} else {
+		c.set("user", null)
+		c.set("session", null)
+	}
+
+	await next()
+}
+
+/**
+ * Middleware that requires a valid session. Returns 401 if not authenticated.
+ */
+export async function requireSession(c: Context, next: Next): Promise<Response | void> {
+	const session = await auth.api.getSession({ headers: c.req.raw.headers })
+
+	if (!session) {
+		return c.json({ error: "Unauthorized" }, 401)
+	}
+
+	c.set("user", session.user)
+	c.set("session", session.session)
+	await next()
+}
+
+/**
+ * Get session from headers. Useful for WebSocket upgrade validation.
+ */
+export async function getSessionFromHeaders(
+	headers: Headers,
+): Promise<{ user: SessionUser; session: Session } | null> {
+	const session = await auth.api.getSession({ headers })
+	return session
+}

apps/aris-backend/src/db.ts

@@ -0,0 +1,5 @@
+import { Pool } from "pg"
+
+export const pool = new Pool({
+	connectionString: process.env.DATABASE_URL,
+})

apps/aris-backend/src/index.ts

@@ -1,10 +0,0 @@
-import { Hono } from "hono"
-
-const app = new Hono()
-
-app.get("/health", (c) => c.json({ status: "ok" }))
-
-export default {
-	port: 3000,
-	fetch: app.fetch,
-}

apps/aris-backend/src/lib/error.ts

@@ -0,0 +1,8 @@
+export class UserNotFoundError extends Error {
+	constructor(
+		public readonly userId: string,
+		message?: string,
+	) {
+		super(message ? `${message}: user not found: ${userId}` : `User not found: ${userId}`)
+	}
+}

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

@@ -0,0 +1,28 @@
+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

@@ -0,0 +1,48 @@
+import { LocationSource } from "@aris/source-location"
+import { trpcServer } from "@hono/trpc-server"
+import { Hono } from "hono"
+
+import { registerAuthHandlers } from "./auth/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([
+		() => new LocationSource(),
+		new WeatherSourceProvider({
+			credentials: {
+				privateKey: process.env.WEATHERKIT_PRIVATE_KEY!,
+				keyId: process.env.WEATHERKIT_KEY_ID!,
+				teamId: process.env.WEATHERKIT_TEAM_ID!,
+				serviceId: process.env.WEATHERKIT_SERVICE_ID!,
+			},
+		}),
+	])
+
+	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,
+		}),
+	)
+
+	return app
+}
+
+const app = main()
+
+export default {
+	port: 3000,
+	fetch: app.fetch,
+}

apps/aris-backend/src/session/feed-source-provider.ts

@@ -0,0 +1,9 @@
+import type { FeedSource } from "@aris/core"
+
+export interface FeedSourceProvider {
+	feedSourceForUser(userId: string): FeedSource
+}
+
+export type FeedSourceProviderFn = (userId: string) => FeedSource
+
+export type FeedSourceProviderInput = FeedSourceProvider | FeedSourceProviderFn

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

@@ -0,0 +1,7 @@
+export type {
+	FeedSourceProvider,
+	FeedSourceProviderFn,
+	FeedSourceProviderInput,
+} from "./feed-source-provider.ts"
+export { UserSession } from "./user-session.ts"
+export { UserSessionManager } from "./user-session-manager.ts"

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

@@ -0,0 +1,166 @@
+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,
+}
+
+describe("UserSessionManager", () => {
+	test("getOrCreate creates session on first call", () => {
+		const manager = new UserSessionManager([() => new LocationSource()])
+
+		const session = manager.getOrCreate("user-1")
+
+		expect(session).toBeDefined()
+		expect(session.engine).toBeDefined()
+	})
+
+	test("getOrCreate returns same session for same user", () => {
+		const manager = new UserSessionManager([() => new LocationSource()])
+
+		const session1 = manager.getOrCreate("user-1")
+		const session2 = manager.getOrCreate("user-1")
+
+		expect(session1).toBe(session2)
+	})
+
+	test("getOrCreate returns different sessions for different users", () => {
+		const manager = new UserSessionManager([() => new LocationSource()])
+
+		const session1 = manager.getOrCreate("user-1")
+		const session2 = manager.getOrCreate("user-2")
+
+		expect(session1).not.toBe(session2)
+	})
+
+	test("each user gets independent source instances", () => {
+		const manager = new UserSessionManager([() => new LocationSource()])
+
+		const session1 = manager.getOrCreate("user-1")
+		const session2 = manager.getOrCreate("user-2")
+
+		const source1 = session1.getSource<LocationSource>("aris.location")
+		const source2 = session2.getSource<LocationSource>("aris.location")
+
+		expect(source1).not.toBe(source2)
+	})
+
+	test("remove destroys session and allows re-creation", () => {
+		const manager = new UserSessionManager([() => new LocationSource()])
+
+		const session1 = manager.getOrCreate("user-1")
+		manager.remove("user-1")
+		const session2 = manager.getOrCreate("user-1")
+
+		expect(session1).not.toBe(session2)
+	})
+
+	test("remove is no-op for unknown user", () => {
+		const manager = new UserSessionManager([() => new LocationSource()])
+
+		expect(() => manager.remove("unknown")).not.toThrow()
+	})
+
+	test("accepts function providers", async () => {
+		const manager = new UserSessionManager([() => new LocationSource()])
+
+		const session = manager.getOrCreate("user-1")
+		const result = await session.engine.refresh()
+
+		expect(result.errors).toHaveLength(0)
+	})
+
+	test("accepts object providers", () => {
+		const provider = new WeatherSourceProvider({ client: mockWeatherClient })
+		const manager = new UserSessionManager([() => new LocationSource(), provider])
+
+		const session = manager.getOrCreate("user-1")
+
+		expect(session.getSource("aris.weather")).toBeDefined()
+	})
+
+	test("accepts mixed providers", () => {
+		const provider = new WeatherSourceProvider({ client: mockWeatherClient })
+		const manager = new UserSessionManager([() => new LocationSource(), provider])
+
+		const session = manager.getOrCreate("user-1")
+
+		expect(session.getSource("aris.location")).toBeDefined()
+		expect(session.getSource("aris.weather")).toBeDefined()
+	})
+
+	test("refresh returns feed result through session", async () => {
+		const manager = new UserSessionManager([() => new LocationSource()])
+
+		const session = manager.getOrCreate("user-1")
+		const result = await session.engine.refresh()
+
+		expect(result).toHaveProperty("context")
+		expect(result).toHaveProperty("items")
+		expect(result).toHaveProperty("errors")
+		expect(result.context.time).toBeInstanceOf(Date)
+	})
+
+	test("location update via executeAction works", async () => {
+		const manager = new UserSessionManager([() => new LocationSource()])
+
+		const session = manager.getOrCreate("user-1")
+		await session.engine.executeAction("aris.location", "update-location", {
+			lat: 51.5074,
+			lng: -0.1278,
+			accuracy: 10,
+			timestamp: new Date(),
+		})
+
+		const source = session.getSource<LocationSource>("aris.location")
+		expect(source?.lastLocation?.lat).toBe(51.5074)
+	})
+
+	test("subscribe receives updates after location push", async () => {
+		const manager = new UserSessionManager([() => new LocationSource()])
+		const callback = mock()
+
+		const session = manager.getOrCreate("user-1")
+		session.engine.subscribe(callback)
+
+		await session.engine.executeAction("aris.location", "update-location", {
+			lat: 51.5074,
+			lng: -0.1278,
+			accuracy: 10,
+			timestamp: new Date(),
+		})
+
+		// Wait for async update propagation
+		await new Promise((resolve) => setTimeout(resolve, 10))
+
+		expect(callback).toHaveBeenCalled()
+	})
+
+	test("remove stops reactive updates", async () => {
+		const manager = new UserSessionManager([() => new LocationSource()])
+		const callback = mock()
+
+		const session = manager.getOrCreate("user-1")
+		session.engine.subscribe(callback)
+
+		manager.remove("user-1")
+
+		// Create new session and push location — old callback should not fire
+		const session2 = manager.getOrCreate("user-1")
+		await session2.engine.executeAction("aris.location", "update-location", {
+			lat: 51.5074,
+			lng: -0.1278,
+			accuracy: 10,
+			timestamp: new Date(),
+		})
+
+		await new Promise((resolve) => setTimeout(resolve, 10))
+
+		expect(callback).not.toHaveBeenCalled()
+	})
+})

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

@@ -0,0 +1,31 @@
+import type { FeedSourceProviderInput } from "./feed-source-provider.ts"
+import { UserSession } from "./user-session.ts"
+
+export class UserSessionManager {
+	private sessions = new Map<string, UserSession>()
+	private readonly providers: FeedSourceProviderInput[]
+
+	constructor(providers: FeedSourceProviderInput[]) {
+		this.providers = providers
+	}
+
+	getOrCreate(userId: string): UserSession {
+		let session = this.sessions.get(userId)
+		if (!session) {
+			const sources = this.providers.map((p) =>
+				typeof p === "function" ? p(userId) : p.feedSourceForUser(userId),
+			)
+			session = new UserSession(sources)
+			this.sessions.set(userId, session)
+		}
+		return session
+	}
+
+	remove(userId: string): void {
+		const session = this.sessions.get(userId)
+		if (session) {
+			session.destroy()
+			this.sessions.delete(userId)
+		}
+	}
+}

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

@@ -0,0 +1,72 @@
+import type { ActionDefinition, Context, FeedSource } from "@aris/core"
+
+import { LocationSource } from "@aris/source-location"
+import { describe, expect, test } from "bun:test"
+
+import { UserSession } from "./user-session.ts"
+
+function createStubSource(id: string): 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 []
+		},
+	}
+}
+
+describe("UserSession", () => {
+	test("registers sources and starts engine", async () => {
+		const session = new UserSession([createStubSource("test-a"), createStubSource("test-b")])
+
+		const result = await session.engine.refresh()
+
+		expect(result.errors).toHaveLength(0)
+	})
+
+	test("getSource returns registered source", () => {
+		const location = new LocationSource()
+		const session = new UserSession([location])
+
+		const result = session.getSource<LocationSource>("aris.location")
+
+		expect(result).toBe(location)
+	})
+
+	test("getSource returns undefined for unknown source", () => {
+		const session = new UserSession([createStubSource("test")])
+
+		expect(session.getSource("unknown")).toBeUndefined()
+	})
+
+	test("destroy stops engine and clears sources", () => {
+		const session = new UserSession([createStubSource("test")])
+
+		session.destroy()
+
+		expect(session.getSource("test")).toBeUndefined()
+	})
+
+	test("engine.executeAction routes to correct source", async () => {
+		const location = new LocationSource()
+		const session = new UserSession([location])
+
+		await session.engine.executeAction("aris.location", "update-location", {
+			lat: 51.5,
+			lng: -0.1,
+			accuracy: 10,
+			timestamp: new Date(),
+		})
+
+		expect(location.lastLocation).toBeDefined()
+		expect(location.lastLocation!.lat).toBe(51.5)
+	})
+})

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

@@ -0,0 +1,24 @@
+import { FeedEngine, type FeedSource } from "@aris/core"
+
+export class UserSession {
+	readonly engine: FeedEngine
+	private sources = new Map<string, FeedSource>()
+
+	constructor(sources: FeedSource[]) {
+		this.engine = new FeedEngine()
+		for (const source of sources) {
+			this.sources.set(source.id, source)
+			this.engine.register(source)
+		}
+		this.engine.start()
+	}
+
+	getSource<T extends FeedSource>(sourceId: string): T | undefined {
+		return this.sources.get(sourceId) as T | undefined
+	}
+
+	destroy(): void {
+		this.engine.stop()
+		this.sources.clear()
+	}
+}

apps/aris-backend/src/tfl/provider.ts

@@ -0,0 +1,19 @@
+import { TflSource, type ITflApi } from "@aris/source-tfl"
+
+import type { FeedSourceProvider } from "../session/feed-source-provider.ts"
+
+export type TflSourceProviderOptions =
+	| { apiKey: string; client?: never }
+	| { apiKey?: never; client: ITflApi }
+
+export class TflSourceProvider implements FeedSourceProvider {
+	private readonly options: TflSourceProviderOptions
+
+	constructor(options: TflSourceProviderOptions) {
+		this.options = options
+	}
+
+	feedSourceForUser(_userId: string): TflSource {
+		return new TflSource(this.options)
+	}
+}

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

@@ -0,0 +1,14 @@
+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

@@ -0,0 +1,44 @@
+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),
+	}
+}
+

apps/aris-backend/src/weather/provider.ts

@@ -0,0 +1,15 @@
+import { WeatherSource, type WeatherSourceOptions } from "@aris/source-weatherkit"
+
+import type { FeedSourceProvider } from "../session/feed-source-provider.ts"
+
+export class WeatherSourceProvider implements FeedSourceProvider {
+	private readonly options: WeatherSourceOptions
+
+	constructor(options: WeatherSourceOptions) {
+		this.options = options
+	}
+
+	feedSourceForUser(_userId: string): WeatherSource {
+		return new WeatherSource(this.options)
+	}
+}

apps/aris-backend/tsconfig.json

@@ -1,7 +1,4 @@
 {
 	"extends": "../../tsconfig.json",
-	"compilerOptions": {
-		"types": ["bun-types"]
-	},
 	"include": ["src"]
 }

apps/aris-client/.gitignore

@@ -0,0 +1,43 @@
+# Learn more https://docs.github.com/en/get-started/getting-started-with-git/ignoring-files
+
+# dependencies
+node_modules/
+
+# Expo
+.expo/
+dist/
+web-build/
+expo-env.d.ts
+
+# Native
+.kotlin/
+*.orig.*
+*.jks
+*.p8
+*.p12
+*.key
+*.mobileprovision
+
+# Metro
+.metro-health-check*
+
+# debug
+npm-debug.*
+yarn-debug.*
+yarn-error.*
+
+# macOS
+.DS_Store
+*.pem
+
+# local env files
+.env*.local
+
+# typescript
+*.tsbuildinfo
+
+app-example
+
+# generated native folders
+/ios
+/android

apps/aris-client/.vscode/extensions.json

@@ -0,0 +1 @@
+{ "recommendations": ["expo.vscode-expo-tools"] }

apps/aris-client/.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+	"editor.codeActionsOnSave": {
+		"source.fixAll": "explicit",
+		"source.organizeImports": "explicit",
+		"source.sortMembers": "explicit"
+	}
+}

apps/aris-client/README.md

@@ -0,0 +1,50 @@
+# Welcome to your Expo app 👋
+
+This is an [Expo](https://expo.dev) project created with [`create-expo-app`](https://www.npmjs.com/package/create-expo-app).
+
+## Get started
+
+1. Install dependencies
+
+   ```bash
+   npm install
+   ```
+
+2. Start the app
+
+   ```bash
+   npx expo start
+   ```
+
+In the output, you'll find options to open the app in a
+
+- [development build](https://docs.expo.dev/develop/development-builds/introduction/)
+- [Android emulator](https://docs.expo.dev/workflow/android-studio-emulator/)
+- [iOS simulator](https://docs.expo.dev/workflow/ios-simulator/)
+- [Expo Go](https://expo.dev/go), a limited sandbox for trying out app development with Expo
+
+You can start developing by editing the files inside the **app** directory. This project uses [file-based routing](https://docs.expo.dev/router/introduction).
+
+## Get a fresh project
+
+When you're ready, run:
+
+```bash
+npm run reset-project
+```
+
+This command will move the starter code to the **app-example** directory and create a blank **app** directory where you can start developing.
+
+## Learn more
+
+To learn more about developing your project with Expo, look at the following resources:
+
+- [Expo documentation](https://docs.expo.dev/): Learn fundamentals, or go into advanced topics with our [guides](https://docs.expo.dev/guides).
+- [Learn Expo tutorial](https://docs.expo.dev/tutorial/introduction/): Follow a step-by-step tutorial where you'll create a project that runs on Android, iOS, and the web.
+
+## Join the community
+
+Join our community of developers creating universal apps.
+
+- [Expo on GitHub](https://github.com/expo/expo): View our open source platform and contribute.
+- [Discord community](https://chat.expo.dev): Chat with Expo users and ask questions.

apps/aris-client/app.json

@@ -0,0 +1,62 @@
+{
+	"expo": {
+		"name": "Aris",
+		"slug": "aris-client",
+		"version": "1.0.0",
+		"orientation": "portrait",
+		"icon": "./assets/images/icon.png",
+		"scheme": "aris",
+		"userInterfaceStyle": "automatic",
+		"newArchEnabled": true,
+		"ios": {
+			"infoPlist": {
+				"NSAppTransportSecurity": {
+					"NSAllowsArbitraryLoads": true
+				},
+				"ITSAppUsesNonExemptEncryption": false
+			},
+			"bundleIdentifier": "sh.nym.aris"
+		},
+		"android": {
+			"adaptiveIcon": {
+				"backgroundColor": "#E6F4FE",
+				"foregroundImage": "./assets/images/android-icon-foreground.png",
+				"backgroundImage": "./assets/images/android-icon-background.png",
+				"monochromeImage": "./assets/images/android-icon-monochrome.png"
+			},
+			"edgeToEdgeEnabled": true,
+			"predictiveBackGestureEnabled": false,
+			"package": "sh.nym.aris"
+		},
+		"web": {
+			"output": "static",
+			"favicon": "./assets/images/favicon.png"
+		},
+		"plugins": [
+			"expo-router",
+			[
+				"expo-splash-screen",
+				{
+					"image": "./assets/images/splash-icon.png",
+					"imageWidth": 200,
+					"resizeMode": "contain",
+					"backgroundColor": "#ffffff",
+					"dark": {
+						"backgroundColor": "#000000"
+					}
+				}
+			],
+			"expo-font"
+		],
+		"experiments": {
+			"typedRoutes": true,
+			"reactCompiler": true
+		},
+		"extra": {
+			"router": {},
+			"eas": {
+				"projectId": "61092d23-36aa-418e-929d-ea40dc912e8f"
+			}
+		}
+	}
+}

apps/aris-client/eas.json

@@ -0,0 +1,21 @@
+{
+	"cli": {
+		"version": ">= 18.0.1",
+		"appVersionSource": "remote"
+	},
+	"build": {
+		"development": {
+			"developmentClient": true,
+			"distribution": "internal"
+		},
+		"preview": {
+			"distribution": "internal"
+		},
+		"production": {
+			"autoIncrement": true
+		}
+	},
+	"submit": {
+		"production": {}
+	}
+}

apps/aris-client/eslint.config.js

@@ -0,0 +1,10 @@
+// https://docs.expo.dev/guides/using-eslint/
+const { defineConfig } = require("eslint/config")
+const expoConfig = require("eslint-config-expo/flat")
+
+module.exports = defineConfig([
+	expoConfig,
+	{
+		ignores: ["dist/*"],
+	},
+])

apps/aris-client/package.json

@@ -0,0 +1,54 @@
+{
+	"name": "aris-client",
+	"version": "1.0.0",
+	"private": true,
+	"main": "expo-router/entry",
+	"scripts": {
+		"start": "./scripts/run-dev-server.sh",
+		"reset-project": "node ./scripts/reset-project.js",
+		"android": "expo start --android",
+		"ios": "expo start --ios",
+		"web": "expo start --web",
+		"lint": "expo lint",
+		"build:ios": "eas build --profile development --platform ios --non-interactive",
+		"debugger": "bun run scripts/open-debugger.ts"
+	},
+	"dependencies": {
+		"@expo-google-fonts/inter": "^0.4.2",
+		"@expo/vector-icons": "^15.0.3",
+		"@react-navigation/bottom-tabs": "^7.4.0",
+		"@react-navigation/elements": "^2.6.3",
+		"@react-navigation/native": "^7.1.8",
+		"expo": "~54.0.33",
+		"expo-constants": "~18.0.13",
+		"expo-dev-client": "~6.0.20",
+		"expo-font": "~14.0.11",
+		"expo-haptics": "~15.0.8",
+		"expo-image": "~3.0.11",
+		"expo-linking": "~8.0.11",
+		"expo-location": "~19.0.8",
+		"expo-router": "~6.0.23",
+		"expo-splash-screen": "~31.0.13",
+		"expo-status-bar": "~3.0.9",
+		"expo-symbols": "~1.0.8",
+		"expo-system-ui": "~6.0.9",
+		"expo-web-browser": "~15.0.10",
+		"react": "19.1.0",
+		"react-dom": "19.1.0",
+		"react-native": "0.81.5",
+		"react-native-gesture-handler": "~2.28.0",
+		"react-native-reanimated": "~4.1.1",
+		"react-native-safe-area-context": "~5.6.0",
+		"react-native-screens": "~4.16.0",
+		"react-native-web": "~0.21.0",
+		"react-native-worklets": "0.5.1",
+		"twrnc": "^4.16.0"
+	},
+	"devDependencies": {
+		"@types/react": "~19.1.0",
+		"eas-cli": "^18.0.1",
+		"eslint": "^9.25.0",
+		"eslint-config-expo": "~10.0.0",
+		"typescript": "~5.9.2"
+	}
+}

apps/aris-client/scripts/dev-proxy.ts

@@ -0,0 +1,127 @@
+// Reverse proxy that sits in front of Metro so that all requests
+// (including those arriving via Tailscale or Ona port-forwarding) reach
+// Metro as loopback connections. This satisfies the isLocalSocket check
+// in Expo's debug middleware, making /debugger-frontend, /json, and
+// /open-debugger accessible from a remote browser.
+
+import type { ServerWebSocket } from "bun"
+
+const PROXY_PORT = parseInt(process.env.PROXY_PORT || "8080", 10)
+const METRO_PORT = parseInt(process.env.METRO_PORT || "8081", 10)
+const METRO_BASE = `http://127.0.0.1:${METRO_PORT}`
+
+function forwardHeaders(headers: Headers): Headers {
+	const result = new Headers(headers)
+	result.delete("origin")
+	result.delete("referer")
+	result.set("host", `127.0.0.1:${METRO_PORT}`)
+	return result
+}
+
+interface WsData {
+	upstream: WebSocket
+	isDevice: boolean
+}
+
+Bun.serve<WsData>({
+	port: PROXY_PORT,
+
+	async fetch(req, server) {
+		const url = new URL(req.url)
+
+		// WebSocket upgrade — bridge to Metro's ws endpoint
+		if (req.headers.get("upgrade")?.toLowerCase() === "websocket") {
+			const wsUrl = `ws://127.0.0.1:${METRO_PORT}${url.pathname}${url.search}`
+			const upstream = new WebSocket(wsUrl)
+
+			// Wait for upstream to connect before upgrading the client
+			try {
+				await new Promise<void>((resolve, reject) => {
+					upstream.addEventListener("open", () => resolve())
+					upstream.addEventListener("error", () => reject(new Error("upstream ws failed")))
+				})
+			} catch {
+				return new Response("Upstream WebSocket unavailable", { status: 502 })
+			}
+
+			const isDevice = url.pathname.startsWith("/inspector/device")
+			const ok = server.upgrade(req, { data: { upstream, isDevice } })
+			if (!ok) {
+				upstream.close()
+				return new Response("WebSocket upgrade failed", { status: 500 })
+			}
+			return undefined
+		}
+
+		// HTTP proxy
+		const upstream = `${METRO_BASE}${url.pathname}${url.search}`
+		const res = await fetch(upstream, {
+			method: req.method,
+			headers: forwardHeaders(req.headers),
+			body: req.body,
+			redirect: "manual",
+		})
+
+		return new Response(res.body, {
+			status: res.status,
+			statusText: res.statusText,
+			headers: res.headers,
+		})
+	},
+
+	websocket: {
+		message(ws: ServerWebSocket<WsData>, msg) {
+			ws.data.upstream.send(msg)
+		},
+		open(ws: ServerWebSocket<WsData>) {
+			const { upstream } = ws.data
+			upstream.addEventListener("message", (ev) => {
+				if (typeof ev.data === "string") {
+					ws.send(ev.data)
+				} else if (ev.data instanceof ArrayBuffer) {
+					ws.sendBinary(new Uint8Array(ev.data))
+				}
+			})
+			upstream.addEventListener("close", () => ws.close())
+			upstream.addEventListener("error", () => ws.close())
+
+			// Print debugger URL shortly after a device connects,
+			// giving Metro time to register the target.
+			if (ws.data.isDevice) {
+				setTimeout(() => printDebuggerUrl(), 1000)
+			}
+		},
+		close(ws: ServerWebSocket<WsData>) {
+			ws.data.upstream.close()
+		},
+	},
+})
+
+const tsIp = await Bun.$`tailscale ip -4`.text().then((s) => s.trim())
+
+async function printDebuggerUrl() {
+	const base = `http://${tsIp}:${PROXY_PORT}`
+	const res = await fetch(`${METRO_BASE}/json`)
+	if (!res.ok) return
+
+	interface DebugTarget {
+		webSocketDebuggerUrl: string
+		reactNative?: {
+			capabilities?: { prefersFuseboxFrontend?: boolean }
+		}
+	}
+
+	const targets: DebugTarget[] = await res.json()
+	const target = targets.find((t) => t.reactNative?.capabilities?.prefersFuseboxFrontend)
+	if (!target) return
+
+	const wsPath = target.webSocketDebuggerUrl
+		.replace(/^ws:\/\//, "")
+		.replace(`127.0.0.1:${METRO_PORT}`, `${tsIp}:${PROXY_PORT}`)
+
+	console.log(
+		`\n  React Native DevTools:\n  ${base}/debugger-frontend/rn_fusebox.html?ws=${encodeURIComponent(wsPath)}&sources.hide_add_folder=true&unstable_enableNetworkPanel=true\n`,
+	)
+}
+
+console.log(`[proxy] listening on :${PROXY_PORT}, forwarding to 127.0.0.1:${METRO_PORT}`)

apps/aris-client/scripts/open-debugger.ts

@@ -0,0 +1,52 @@
+// Opens React Native DevTools in Chrome, connected to the first
+// available Hermes debug target. Requires Metro + proxy to be running.
+
+import { $ } from "bun"
+
+const PROXY_PORT = process.env.PROXY_PORT || "8080"
+const METRO_PORT = process.env.METRO_PORT || "8081"
+const tsIp = (await $`tailscale ip -4`.text()).trim()
+const base = `http://${tsIp}:${PROXY_PORT}`
+
+interface DebugTarget {
+	devtoolsFrontendUrl: string
+	webSocketDebuggerUrl: string
+	reactNative?: {
+		capabilities?: {
+			prefersFuseboxFrontend?: boolean
+		}
+	}
+}
+
+const res = await fetch(`${base}/json`)
+if (!res.ok) {
+	console.error("Failed to fetch /json — is Metro running?")
+	process.exit(1)
+}
+
+const targets: DebugTarget[] = await res.json()
+const target = targets.find((t) => t.reactNative?.capabilities?.prefersFuseboxFrontend)
+
+if (!target) {
+	console.error("No debug target found. Is the app connected?")
+	process.exit(1)
+}
+
+const wsUrl = target.webSocketDebuggerUrl
+	.replace(/^ws:\/\//, "")
+	.replace(`127.0.0.1:${METRO_PORT}`, `${tsIp}:${PROXY_PORT}`)
+
+const url = `${base}/debugger-frontend/rn_fusebox.html?ws=${encodeURIComponent(wsUrl)}&sources.hide_add_folder=true&unstable_enableNetworkPanel=true`
+
+console.log(url)
+
+// Open in Chrome app mode if on macOS
+try {
+	await $`open -a "Google Chrome" --args --app=${url}`.quiet()
+} catch {
+	try {
+		await $`xdg-open ${url}`.quiet()
+	} catch {
+		console.log("Open the URL above in Chrome.")
+	}
+}

apps/aris-client/scripts/reset-project.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+/**
+ * This script is used to reset the project to a blank state.
+ * It deletes or moves the /app, /components, /hooks, /scripts, and /constants directories to /app-example based on user input and creates a new /app directory with an index.tsx and _layout.tsx file.
+ * You can remove the `reset-project` script from package.json and safely delete this file after running it.
+ */
+
+const fs = require("fs")
+const path = require("path")
+const readline = require("readline")
+
+const root = process.cwd()
+const oldDirs = ["app", "components", "hooks", "constants", "scripts"]
+const exampleDir = "app-example"
+const newAppDir = "app"
+const exampleDirPath = path.join(root, exampleDir)
+
+const indexContent = `import { Text, View } from "react-native";
+
+export default function Index() {
+  return (
+    <View
+      style={{
+        flex: 1,
+        justifyContent: "center",
+        alignItems: "center",
+      }}
+    >
+      <Text>Edit app/index.tsx to edit this screen.</Text>
+    </View>
+  );
+}
+`
+
+const layoutContent = `import { Stack } from "expo-router";
+
+export default function RootLayout() {
+  return <Stack />;
+}
+`
+
+const rl = readline.createInterface({
+	input: process.stdin,
+	output: process.stdout,
+})
+
+const moveDirectories = async (userInput) => {
+	try {
+		if (userInput === "y") {
+			// Create the app-example directory
+			await fs.promises.mkdir(exampleDirPath, { recursive: true })
+			console.log(`📁 /${exampleDir} directory created.`)
+		}
+
+		// Move old directories to new app-example directory or delete them
+		for (const dir of oldDirs) {
+			const oldDirPath = path.join(root, dir)
+			if (fs.existsSync(oldDirPath)) {
+				if (userInput === "y") {
+					const newDirPath = path.join(root, exampleDir, dir)
+					await fs.promises.rename(oldDirPath, newDirPath)
+					console.log(`➡️ /${dir} moved to /${exampleDir}/${dir}.`)
+				} else {
+					await fs.promises.rm(oldDirPath, { recursive: true, force: true })
+					console.log(`❌ /${dir} deleted.`)
+				}
+			} else {
+				console.log(`➡️ /${dir} does not exist, skipping.`)
+			}
+		}
+
+		// Create new /app directory
+		const newAppDirPath = path.join(root, newAppDir)
+		await fs.promises.mkdir(newAppDirPath, { recursive: true })
+		console.log("\n📁 New /app directory created.")
+
+		// Create index.tsx
+		const indexPath = path.join(newAppDirPath, "index.tsx")
+		await fs.promises.writeFile(indexPath, indexContent)
+		console.log("📄 app/index.tsx created.")
+
+		// Create _layout.tsx
+		const layoutPath = path.join(newAppDirPath, "_layout.tsx")
+		await fs.promises.writeFile(layoutPath, layoutContent)
+		console.log("📄 app/_layout.tsx created.")
+
+		console.log("\n✅ Project reset complete. Next steps:")
+		console.log(
+			`1. Run \`npx expo start\` to start a development server.\n2. Edit app/index.tsx to edit the main screen.${
+				userInput === "y"
+					? `\n3. Delete the /${exampleDir} directory when you're done referencing it.`
+					: ""
+			}`,
+		)
+	} catch (error) {
+		console.error(`❌ Error during script execution: ${error.message}`)
+	}
+}
+
+rl.question(
+	"Do you want to move existing files to /app-example instead of deleting them? (Y/n): ",
+	(answer) => {
+		const userInput = answer.trim().toLowerCase() || "y"
+		if (userInput === "y" || userInput === "n") {
+			moveDirectories(userInput).finally(() => rl.close())
+		} else {
+			console.log("❌ Invalid input. Please enter 'Y' or 'N'.")
+			rl.close()
+		}
+	},
+)

apps/aris-client/scripts/run-dev-server.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PROXY_PORT=8080
+METRO_PORT=8081
+
+# Start a reverse proxy so Metro sees all requests as loopback.
+# This makes debugger endpoints (/debugger-frontend, /json, /open-debugger)
+# accessible through the Tailscale IP.
+PROXY_PORT=$PROXY_PORT METRO_PORT=$METRO_PORT bun run scripts/dev-proxy.ts &
+PROXY_PID=$!
+trap "kill $PROXY_PID 2>/dev/null" EXIT
+
+EXPO_PACKAGER_PROXY_URL=http://$(tailscale ip -4):$PROXY_PORT bunx expo start --localhost -p $METRO_PORT
+

apps/aris-client/src/app/(tabs)/_layout.tsx

@@ -0,0 +1,36 @@
+import { Tabs } from "expo-router"
+import React from "react"
+
+import { HapticTab } from "@/components/haptic-tab"
+import { IconSymbol } from "@/components/ui/icon-symbol"
+import { Colors } from "@/constants/theme"
+import { useColorScheme } from "@/hooks/use-color-scheme"
+
+export default function TabLayout() {
+	const colorScheme = useColorScheme()
+
+	return (
+		<Tabs
+			screenOptions={{
+				tabBarActiveTintColor: Colors[colorScheme ?? "light"].tint,
+				headerShown: false,
+				tabBarButton: HapticTab,
+			}}
+		>
+			<Tabs.Screen
+				name="index"
+				options={{
+					title: "Home",
+					tabBarIcon: ({ color }) => <IconSymbol size={28} name="house.fill" color={color} />,
+				}}
+			/>
+			<Tabs.Screen
+				name="explore"
+				options={{
+					title: "Explore",
+					tabBarIcon: ({ color }) => <IconSymbol size={28} name="paperplane.fill" color={color} />,
+				}}
+			/>
+		</Tabs>
+	)
+}

apps/aris-client/src/app/(tabs)/explore.tsx

@@ -0,0 +1,114 @@
+import { Image } from "expo-image"
+import { Platform, StyleSheet } from "react-native"
+
+import { ExternalLink } from "@/components/external-link"
+import ParallaxScrollView from "@/components/parallax-scroll-view"
+import { ThemedText } from "@/components/themed-text"
+import { ThemedView } from "@/components/themed-view"
+import { Collapsible } from "@/components/ui/collapsible"
+import { IconSymbol } from "@/components/ui/icon-symbol"
+import { Fonts } from "@/constants/theme"
+
+export default function TabTwoScreen() {
+	return (
+		<ParallaxScrollView
+			headerBackgroundColor={{ light: "#D0D0D0", dark: "#353636" }}
+			headerImage={
+				<IconSymbol
+					size={310}
+					color="#808080"
+					name="chevron.left.forwardslash.chevron.right"
+					style={styles.headerImage}
+				/>
+			}
+		>
+			<ThemedView style={styles.titleContainer}>
+				<ThemedText
+					type="title"
+					style={{
+						fontFamily: Fonts.rounded,
+					}}
+				>
+					Explore
+				</ThemedText>
+			</ThemedView>
+			<ThemedText>This app includes example code to help you get started.</ThemedText>
+			<Collapsible title="File-based routing">
+				<ThemedText>
+					This app has two screens:{" "}
+					<ThemedText type="defaultSemiBold">app/(tabs)/index.tsx</ThemedText> and{" "}
+					<ThemedText type="defaultSemiBold">app/(tabs)/explore.tsx</ThemedText>
+				</ThemedText>
+				<ThemedText>
+					The layout file in <ThemedText type="defaultSemiBold">app/(tabs)/_layout.tsx</ThemedText>{" "}
+					sets up the tab navigator.
+				</ThemedText>
+				<ExternalLink href="https://docs.expo.dev/router/introduction">
+					<ThemedText type="link">Learn more</ThemedText>
+				</ExternalLink>
+			</Collapsible>
+			<Collapsible title="Android, iOS, and web support">
+				<ThemedText>
+					You can open this project on Android, iOS, and the web. To open the web version, press{" "}
+					<ThemedText type="defaultSemiBold">w</ThemedText> in the terminal running this project.
+				</ThemedText>
+			</Collapsible>
+			<Collapsible title="Images">
+				<ThemedText>
+					For static images, you can use the <ThemedText type="defaultSemiBold">@2x</ThemedText> and{" "}
+					<ThemedText type="defaultSemiBold">@3x</ThemedText> suffixes to provide files for
+					different screen densities
+				</ThemedText>
+				<Image
+					source={require("@assets/images/react-logo.png")}
+					style={{ width: 100, height: 100, alignSelf: "center" }}
+				/>
+				<ExternalLink href="https://reactnative.dev/docs/images">
+					<ThemedText type="link">Learn more</ThemedText>
+				</ExternalLink>
+			</Collapsible>
+			<Collapsible title="Light and dark mode components">
+				<ThemedText>
+					This template has light and dark mode support. The{" "}
+					<ThemedText type="defaultSemiBold">useColorScheme()</ThemedText> hook lets you inspect
+					what the user&apos;s current color scheme is, and so you can adjust UI colors accordingly.
+				</ThemedText>
+				<ExternalLink href="https://docs.expo.dev/develop/user-interface/color-themes/">
+					<ThemedText type="link">Learn more</ThemedText>
+				</ExternalLink>
+			</Collapsible>
+			<Collapsible title="Animations">
+				<ThemedText>
+					This template includes an example of an animated component. The{" "}
+					<ThemedText type="defaultSemiBold">components/HelloWave.tsx</ThemedText> component uses
+					the powerful{" "}
+					<ThemedText type="defaultSemiBold" style={{ fontFamily: Fonts.mono }}>
+						react-native-reanimated
+					</ThemedText>{" "}
+					library to create a waving hand animation.
+				</ThemedText>
+				{Platform.select({
+					ios: (
+						<ThemedText>
+							The <ThemedText type="defaultSemiBold">components/ParallaxScrollView.tsx</ThemedText>{" "}
+							component provides a parallax effect for the header image.
+						</ThemedText>
+					),
+				})}
+			</Collapsible>
+		</ParallaxScrollView>
+	)
+}
+
+const styles = StyleSheet.create({
+	headerImage: {
+		color: "#808080",
+		bottom: -90,
+		left: -35,
+		position: "absolute",
+	},
+	titleContainer: {
+		flexDirection: "row",
+		gap: 8,
+	},
+})

apps/aris-client/src/app/(tabs)/index.tsx

@@ -0,0 +1,96 @@
+import { Image } from "expo-image"
+import { Link } from "expo-router"
+import { Platform, StyleSheet } from "react-native"
+
+import { HelloWave } from "@/components/hello-wave"
+import ParallaxScrollView from "@/components/parallax-scroll-view"
+import { ThemedText } from "@/components/themed-text"
+import { ThemedView } from "@/components/themed-view"
+
+export default function HomeScreen() {
+	return (
+		<ParallaxScrollView
+			headerBackgroundColor={{ light: "#A1CEDC", dark: "#1D3D47" }}
+			headerImage={
+				<Image source={require("@assets/images/partial-react-logo.png")} style={styles.reactLogo} />
+			}
+		>
+			<ThemedView style={styles.titleContainer}>
+				<ThemedText type="title">Welcome!</ThemedText>
+				<HelloWave />
+			</ThemedView>
+			<ThemedView style={styles.stepContainer}>
+				<ThemedText type="subtitle">Step 1: Try it</ThemedText>
+				<ThemedText>
+					Edit <ThemedText type="defaultSemiBold">app/(tabs)/index.tsx</ThemedText> to see changes.
+					Press{" "}
+					<ThemedText type="defaultSemiBold">
+						{Platform.select({
+							ios: "cmd + d",
+							android: "cmd + m",
+							web: "F12",
+						})}
+					</ThemedText>{" "}
+					to open developer tools.
+				</ThemedText>
+			</ThemedView>
+			<ThemedView style={styles.stepContainer}>
+				<Link href="/modal">
+					<Link.Trigger>
+						<ThemedText type="subtitle">Step 2: Explore</ThemedText>
+					</Link.Trigger>
+					<Link.Preview />
+					<Link.Menu>
+						<Link.MenuAction title="Action" icon="cube" onPress={() => alert("Action pressed")} />
+						<Link.MenuAction
+							title="Share"
+							icon="square.and.arrow.up"
+							onPress={() => alert("Share pressed")}
+						/>
+						<Link.Menu title="More" icon="ellipsis">
+							<Link.MenuAction
+								title="Delete"
+								icon="trash"
+								destructive
+								onPress={() => alert("Delete pressed")}
+							/>
+						</Link.Menu>
+					</Link.Menu>
+				</Link>
+
+				<ThemedText>
+					{`Tap the Explore tab to learn more about what's included in this starter app.`}
+				</ThemedText>
+			</ThemedView>
+			<ThemedView style={styles.stepContainer}>
+				<ThemedText type="subtitle">Step 3: Get a fresh start</ThemedText>
+				<ThemedText>
+					{`When you're ready, run `}
+					<ThemedText type="defaultSemiBold">npm run reset-project</ThemedText> to get a fresh{" "}
+					<ThemedText type="defaultSemiBold">app</ThemedText> directory. This will move the current{" "}
+					<ThemedText type="defaultSemiBold">app</ThemedText> to{" "}
+					<ThemedText type="defaultSemiBold">app-example</ThemedText>.
+				</ThemedText>
+			</ThemedView>
+		</ParallaxScrollView>
+	)
+}
+
+const styles = StyleSheet.create({
+	titleContainer: {
+		flexDirection: "row",
+		alignItems: "center",
+		gap: 8,
+	},
+	stepContainer: {
+		gap: 8,
+		marginBottom: 8,
+	},
+	reactLogo: {
+		height: 178,
+		width: 290,
+		bottom: 0,
+		left: 0,
+		position: "absolute",
+	},
+})

apps/aris-client/src/app/_layout.tsx

@@ -0,0 +1,23 @@
+import { DarkTheme, DefaultTheme, ThemeProvider } from "@react-navigation/native"
+import { Stack } from "expo-router"
+import { StatusBar } from "expo-status-bar"
+import "react-native-reanimated"
+import { useColorScheme } from "@/hooks/use-color-scheme"
+
+export const unstable_settings = {
+	anchor: "(tabs)",
+}
+
+export default function RootLayout() {
+	const colorScheme = useColorScheme()
+
+	return (
+		<ThemeProvider value={colorScheme === "dark" ? DarkTheme : DefaultTheme}>
+			<Stack>
+				<Stack.Screen name="(tabs)" options={{ headerShown: false }} />
+				<Stack.Screen name="modal" options={{ presentation: "modal", title: "Modal" }} />
+			</Stack>
+			<StatusBar style="auto" />
+		</ThemeProvider>
+	)
+}

apps/aris-client/src/app/modal.tsx

@@ -0,0 +1,29 @@
+import { Link } from "expo-router"
+import { StyleSheet } from "react-native"
+
+import { ThemedText } from "@/components/themed-text"
+import { ThemedView } from "@/components/themed-view"
+
+export default function ModalScreen() {
+	return (
+		<ThemedView style={styles.container}>
+			<ThemedText type="title">This is a modal</ThemedText>
+			<Link href="/" dismissTo style={styles.link}>
+				<ThemedText type="link">Go to home screen</ThemedText>
+			</Link>
+		</ThemedView>
+	)
+}
+
+const styles = StyleSheet.create({
+	container: {
+		flex: 1,
+		alignItems: "center",
+		justifyContent: "center",
+		padding: 20,
+	},
+	link: {
+		marginTop: 15,
+		paddingVertical: 15,
+	},
+})

apps/aris-client/src/components/external-link.tsx

@@ -0,0 +1,25 @@
+import { Href, Link } from "expo-router"
+import { openBrowserAsync, WebBrowserPresentationStyle } from "expo-web-browser"
+import { type ComponentProps } from "react"
+
+type Props = Omit<ComponentProps<typeof Link>, "href"> & { href: Href & string }
+
+export function ExternalLink({ href, ...rest }: Props) {
+	return (
+		<Link
+			target="_blank"
+			{...rest}
+			href={href}
+			onPress={async (event) => {
+				if (process.env.EXPO_OS !== "web") {
+					// Prevent the default behavior of linking to the default browser on native.
+					event.preventDefault()
+					// Open the link in an in-app browser.
+					await openBrowserAsync(href, {
+						presentationStyle: WebBrowserPresentationStyle.AUTOMATIC,
+					})
+				}
+			}}
+		/>
+	)
+}

apps/aris-client/src/components/haptic-tab.tsx

@@ -0,0 +1,18 @@
+import { BottomTabBarButtonProps } from "@react-navigation/bottom-tabs"
+import { PlatformPressable } from "@react-navigation/elements"
+import * as Haptics from "expo-haptics"
+
+export function HapticTab(props: BottomTabBarButtonProps) {
+	return (
+		<PlatformPressable
+			{...props}
+			onPressIn={(ev) => {
+				if (process.env.EXPO_OS === "ios") {
+					// Add a soft haptic feedback when pressing down on the tabs.
+					Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light)
+				}
+				props.onPressIn?.(ev)
+			}}
+		/>
+	)
+}

apps/aris-client/src/components/hello-wave.tsx

@@ -0,0 +1,20 @@
+import Animated from "react-native-reanimated"
+
+export function HelloWave() {
+	return (
+		<Animated.Text
+			style={{
+				fontSize: 28,
+				lineHeight: 32,
+				marginTop: -6,
+				animationName: {
+					"50%": { transform: [{ rotate: "25deg" }] },
+				},
+				animationIterationCount: 4,
+				animationDuration: "300ms",
+			}}
+		>
+			👋
+		</Animated.Text>
+	)
+}

apps/aris-client/src/components/parallax-scroll-view.tsx

@@ -0,0 +1,82 @@
+import type { PropsWithChildren, ReactElement } from "react"
+
+import { StyleSheet } from "react-native"
+import Animated, {
+	interpolate,
+	useAnimatedRef,
+	useAnimatedStyle,
+	useScrollOffset,
+} from "react-native-reanimated"
+
+import { ThemedView } from "@/components/themed-view"
+import { useColorScheme } from "@/hooks/use-color-scheme"
+import { useThemeColor } from "@/hooks/use-theme-color"
+
+const HEADER_HEIGHT = 250
+
+type Props = PropsWithChildren<{
+	headerImage: ReactElement
+	headerBackgroundColor: { dark: string; light: string }
+}>
+
+export default function ParallaxScrollView({
+	children,
+	headerImage,
+	headerBackgroundColor,
+}: Props) {
+	const backgroundColor = useThemeColor({}, "background")
+	const colorScheme = useColorScheme() ?? "light"
+	const scrollRef = useAnimatedRef<Animated.ScrollView>()
+	const scrollOffset = useScrollOffset(scrollRef)
+	const headerAnimatedStyle = useAnimatedStyle(() => {
+		return {
+			transform: [
+				{
+					translateY: interpolate(
+						scrollOffset.value,
+						[-HEADER_HEIGHT, 0, HEADER_HEIGHT],
+						[-HEADER_HEIGHT / 2, 0, HEADER_HEIGHT * 0.75],
+					),
+				},
+				{
+					scale: interpolate(scrollOffset.value, [-HEADER_HEIGHT, 0, HEADER_HEIGHT], [2, 1, 1]),
+				},
+			],
+		}
+	})
+
+	return (
+		<Animated.ScrollView
+			ref={scrollRef}
+			style={{ backgroundColor, flex: 1 }}
+			scrollEventThrottle={16}
+		>
+			<Animated.View
+				style={[
+					styles.header,
+					{ backgroundColor: headerBackgroundColor[colorScheme] },
+					headerAnimatedStyle,
+				]}
+			>
+				{headerImage}
+			</Animated.View>
+			<ThemedView style={styles.content}>{children}</ThemedView>
+		</Animated.ScrollView>
+	)
+}
+
+const styles = StyleSheet.create({
+	container: {
+		flex: 1,
+	},
+	header: {
+		height: HEADER_HEIGHT,
+		overflow: "hidden",
+	},
+	content: {
+		flex: 1,
+		padding: 32,
+		gap: 16,
+		overflow: "hidden",
+	},
+})

apps/aris-client/src/components/themed-text.tsx

@@ -0,0 +1,60 @@
+import { StyleSheet, Text, type TextProps } from "react-native"
+
+import { useThemeColor } from "@/hooks/use-theme-color"
+
+export type ThemedTextProps = TextProps & {
+	lightColor?: string
+	darkColor?: string
+	type?: "default" | "title" | "defaultSemiBold" | "subtitle" | "link"
+}
+
+export function ThemedText({
+	style,
+	lightColor,
+	darkColor,
+	type = "default",
+	...rest
+}: ThemedTextProps) {
+	const color = useThemeColor({ light: lightColor, dark: darkColor }, "text")
+
+	return (
+		<Text
+			style={[
+				{ color },
+				type === "default" ? styles.default : undefined,
+				type === "title" ? styles.title : undefined,
+				type === "defaultSemiBold" ? styles.defaultSemiBold : undefined,
+				type === "subtitle" ? styles.subtitle : undefined,
+				type === "link" ? styles.link : undefined,
+				style,
+			]}
+			{...rest}
+		/>
+	)
+}
+
+const styles = StyleSheet.create({
+	default: {
+		fontSize: 16,
+		lineHeight: 24,
+	},
+	defaultSemiBold: {
+		fontSize: 16,
+		lineHeight: 24,
+		fontWeight: "600",
+	},
+	title: {
+		fontSize: 32,
+		fontWeight: "bold",
+		lineHeight: 32,
+	},
+	subtitle: {
+		fontSize: 20,
+		fontWeight: "bold",
+	},
+	link: {
+		lineHeight: 30,
+		fontSize: 16,
+		color: "#0a7ea4",
+	},
+})

apps/aris-client/src/components/themed-view.tsx

@@ -0,0 +1,14 @@
+import { View, type ViewProps } from "react-native"
+
+import { useThemeColor } from "@/hooks/use-theme-color"
+
+export type ThemedViewProps = ViewProps & {
+	lightColor?: string
+	darkColor?: string
+}
+
+export function ThemedView({ style, lightColor, darkColor, ...otherProps }: ThemedViewProps) {
+	const backgroundColor = useThemeColor({ light: lightColor, dark: darkColor }, "background")
+
+	return <View style={[{ backgroundColor }, style]} {...otherProps} />
+}

apps/aris-client/src/components/ui/collapsible.tsx

@@ -0,0 +1,46 @@
+import { PropsWithChildren, useState } from "react"
+import { StyleSheet, TouchableOpacity } from "react-native"
+
+import { ThemedText } from "@/components/themed-text"
+import { ThemedView } from "@/components/themed-view"
+import { IconSymbol } from "@/components/ui/icon-symbol"
+import { Colors } from "@/constants/theme"
+import { useColorScheme } from "@/hooks/use-color-scheme"
+
+export function Collapsible({ children, title }: PropsWithChildren & { title: string }) {
+	const [isOpen, setIsOpen] = useState(false)
+	const theme = useColorScheme() ?? "light"
+
+	return (
+		<ThemedView>
+			<TouchableOpacity
+				style={styles.heading}
+				onPress={() => setIsOpen((value) => !value)}
+				activeOpacity={0.8}
+			>
+				<IconSymbol
+					name="chevron.right"
+					size={18}
+					weight="medium"
+					color={theme === "light" ? Colors.light.icon : Colors.dark.icon}
+					style={{ transform: [{ rotate: isOpen ? "90deg" : "0deg" }] }}
+				/>
+
+				<ThemedText type="defaultSemiBold">{title}</ThemedText>
+			</TouchableOpacity>
+			{isOpen && <ThemedView style={styles.content}>{children}</ThemedView>}
+		</ThemedView>
+	)
+}
+
+const styles = StyleSheet.create({
+	heading: {
+		flexDirection: "row",
+		alignItems: "center",
+		gap: 6,
+	},
+	content: {
+		marginTop: 6,
+		marginLeft: 24,
+	},
+})

apps/aris-client/src/components/ui/icon-symbol.ios.tsx

@@ -0,0 +1,32 @@
+import { SymbolView, SymbolViewProps, SymbolWeight } from "expo-symbols"
+import { StyleProp, ViewStyle } from "react-native"
+
+export function IconSymbol({
+	name,
+	size = 24,
+	color,
+	style,
+	weight = "regular",
+}: {
+	name: SymbolViewProps["name"]
+	size?: number
+	color: string
+	style?: StyleProp<ViewStyle>
+	weight?: SymbolWeight
+}) {
+	return (
+		<SymbolView
+			weight={weight}
+			tintColor={color}
+			resizeMode="scaleAspectFit"
+			name={name}
+			style={[
+				{
+					width: size,
+					height: size,
+				},
+				style,
+			]}
+		/>
+	)
+}

apps/aris-client/src/components/ui/icon-symbol.tsx

@@ -0,0 +1,41 @@
+// Fallback for using MaterialIcons on Android and web.
+
+import MaterialIcons from "@expo/vector-icons/MaterialIcons"
+import { SymbolWeight, SymbolViewProps } from "expo-symbols"
+import { ComponentProps } from "react"
+import { OpaqueColorValue, type StyleProp, type TextStyle } from "react-native"
+
+type IconMapping = Record<SymbolViewProps["name"], ComponentProps<typeof MaterialIcons>["name"]>
+type IconSymbolName = keyof typeof MAPPING
+
+/**
+ * Add your SF Symbols to Material Icons mappings here.
+ * - see Material Icons in the [Icons Directory](https://icons.expo.fyi).
+ * - see SF Symbols in the [SF Symbols](https://developer.apple.com/sf-symbols/) app.
+ */
+const MAPPING = {
+	"house.fill": "home",
+	"paperplane.fill": "send",
+	"chevron.left.forwardslash.chevron.right": "code",
+	"chevron.right": "chevron-right",
+} as IconMapping
+
+/**
+ * An icon component that uses native SF Symbols on iOS, and Material Icons on Android and web.
+ * This ensures a consistent look across platforms, and optimal resource usage.
+ * Icon `name`s are based on SF Symbols and require manual mapping to Material Icons.
+ */
+export function IconSymbol({
+	name,
+	size = 24,
+	color,
+	style,
+}: {
+	name: IconSymbolName
+	size?: number
+	color: string | OpaqueColorValue
+	style?: StyleProp<TextStyle>
+	weight?: SymbolWeight
+}) {
+	return <MaterialIcons color={color} size={size} name={MAPPING[name]} style={style} />
+}

apps/aris-client/src/constants/theme.ts

@@ -0,0 +1,53 @@
+/**
+ * Below are the colors that are used in the app. The colors are defined in the light and dark mode.
+ * There are many other ways to style your app. For example, [Nativewind](https://www.nativewind.dev/), [unistyles](https://reactnativeunistyles.vercel.app), etc.
+ */
+
+import { Platform } from "react-native"
+
+const tintColorLight = "#0a7ea4"
+const tintColorDark = "#fff"
+
+export const Colors = {
+	light: {
+		text: "#11181C",
+		background: "#fff",
+		tint: tintColorLight,
+		icon: "#687076",
+		tabIconDefault: "#687076",
+		tabIconSelected: tintColorLight,
+	},
+	dark: {
+		text: "#ECEDEE",
+		background: "#151718",
+		tint: tintColorDark,
+		icon: "#9BA1A6",
+		tabIconDefault: "#9BA1A6",
+		tabIconSelected: tintColorDark,
+	},
+}
+
+export const Fonts = Platform.select({
+	ios: {
+		/** iOS `UIFontDescriptorSystemDesignDefault` */
+		sans: "system-ui",
+		/** iOS `UIFontDescriptorSystemDesignSerif` */
+		serif: "ui-serif",
+		/** iOS `UIFontDescriptorSystemDesignRounded` */
+		rounded: "ui-rounded",
+		/** iOS `UIFontDescriptorSystemDesignMonospaced` */
+		mono: "ui-monospace",
+	},
+	default: {
+		sans: "normal",
+		serif: "serif",
+		rounded: "normal",
+		mono: "monospace",
+	},
+	web: {
+		sans: "system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif",
+		serif: "Georgia, 'Times New Roman', serif",
+		rounded: "'SF Pro Rounded', 'Hiragino Maru Gothic ProN', Meiryo, 'MS PGothic', sans-serif",
+		mono: "SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace",
+	},
+})

apps/aris-client/src/hooks/use-color-scheme.ts

@@ -0,0 +1 @@
+export { useColorScheme } from "react-native"

apps/aris-client/src/hooks/use-color-scheme.web.ts

@@ -0,0 +1,21 @@
+import { useEffect, useState } from "react"
+import { useColorScheme as useRNColorScheme } from "react-native"
+
+/**
+ * To support static rendering, this value needs to be re-calculated on the client side for web
+ */
+export function useColorScheme() {
+	const [hasHydrated, setHasHydrated] = useState(false)
+
+	useEffect(() => {
+		setHasHydrated(true)
+	}, [])
+
+	const colorScheme = useRNColorScheme()
+
+	if (hasHydrated) {
+		return colorScheme
+	}
+
+	return "light"
+}

apps/aris-client/src/hooks/use-theme-color.ts

@@ -0,0 +1,21 @@
+/**
+ * Learn more about light and dark modes:
+ * https://docs.expo.dev/guides/color-schemes/
+ */
+
+import { Colors } from "@/constants/theme"
+import { useColorScheme } from "@/hooks/use-color-scheme"
+
+export function useThemeColor(
+	props: { light?: string; dark?: string },
+	colorName: keyof typeof Colors.light & keyof typeof Colors.dark,
+) {
+	const theme = useColorScheme() ?? "light"
+	const colorFromProps = props[theme]
+
+	if (colorFromProps) {
+		return colorFromProps
+	} else {
+		return Colors[theme][colorName]
+	}
+}

apps/aris-client/tsconfig.json

@@ -0,0 +1,11 @@
+{
+	"extends": "expo/tsconfig.base",
+	"compilerOptions": {
+		"strict": true,
+		"paths": {
+			"@/*": ["./src/*"],
+			"@assets/*": ["./assets/*"]
+		}
+	},
+	"include": ["**/*.ts", "**/*.tsx", ".expo/types/**/*.ts", "expo-env.d.ts"]
+}

docs/backend-service-architecture-spec.md

@@ -0,0 +1,306 @@
+# Backend Service Architecture: Per-User Refactor
+
+## Problem Statement
+
+The current backend uses a **per-source service** pattern: each source type (Location, Weather, TFL) has its own `XxxService` class that manages a `Map<userId, SourceInstance>`. Adding a new source requires:
+
+1. A new `XxxService` class with identical boilerplate (~30-40 lines: Map, get-or-create, removeUser)
+2. Wiring it into `server.ts` constructor
+3. Passing it to `FeedEngineService`
+4. Optionally adding source-specific tRPC routes
+
+With 3 sources this is manageable. With 10+ (calendar, music, transit, news, etc.) it becomes:
+
+- **Repetitive**: Every service class repeats the same Map + get-or-create + removeUser pattern
+- **Fragmented lifecycle**: User cleanup requires calling `removeUser` on every service independently
+- **No user-level config**: No unified place to store which sources a user has enabled or their per-source settings
+- **Hard to reason about**: User state is scattered across N independent Maps
+
+### Current Flow
+
+```
+server.ts
+  ├── new LocationService()          ← owns Map<userId, LocationSource>
+  ├── new WeatherService(creds)      ← owns Map<userId, WeatherSource>
+  ├── new TflService(api)            ← owns Map<userId, TflSource>
+  └── FeedEngineService([loc, weather, tfl])
+        └── owns Map<userId, FeedEngine>
+            └── on create: asks each service for feedSourceForUser(userId)
+```
+
+4 independent Maps for 3 sources. Each user's state lives in 4 different places.
+
+## Scope
+
+**Backend only** (`apps/aris-backend`). No changes to `aris-core` or source packages (`packages/aris-source-*`). The `FeedSource` interface and source implementations remain unchanged.
+
+## Architectural Options
+
+### Option A: UserSession Object
+
+A single `UserSession` class owns everything for one user. A `UserSessionManager` is the only top-level Map.
+
+```typescript
+class UserSession {
+  readonly userId: string
+  readonly engine: FeedEngine
+  private sources: Map<string, FeedSource>
+
+  constructor(userId: string, sourceFactories: SourceFactory[]) {
+    this.engine = new FeedEngine()
+    this.sources = new Map()
+    for (const factory of sourceFactories) {
+      const source = factory.create()
+      this.sources.set(source.id, source)
+      this.engine.register(source)
+    }
+    this.engine.start()
+  }
+
+  getSource<T extends FeedSource>(id: string): T | undefined {
+    return this.sources.get(id) as T | undefined
+  }
+
+  destroy(): void {
+    this.engine.stop()
+    this.sources.clear()
+  }
+}
+
+class UserSessionManager {
+  private sessions = new Map<string, UserSession>()
+
+  getOrCreate(userId: string): UserSession { ... }
+  remove(userId: string): void { ... }  // single cleanup point
+}
+```
+
+**Source-specific operations** use typed accessors:
+
+```typescript
+const session = manager.getOrCreate(userId)
+const location = session.getSource<LocationSource>("location")
+location?.pushLocation({ lat: 51.5, lng: -0.1, ... })
+```
+
+**Pros:**
+
+- Single Map, single cleanup point
+- All user state co-located
+- Easy to add TTL/eviction at one level
+- Source factories are simple functions, no service classes needed
+
+**Cons:**
+
+- `getSource<T>("id")` requires callers to know the source ID string and cast type
+- Shared resources (e.g., TFL API client) need to be passed through factories
+
+### Option B: Source Registry with Factories
+
+Keep `FeedEngineService` but replace per-source service classes with a registry of factory functions. No `XxxService` classes at all.
+
+```typescript
+interface SourceFactory {
+  readonly sourceId: string
+  create(userId: string): FeedSource
+}
+
+// Weather factory — closure over shared credentials
+function weatherSourceFactory(creds: WeatherKitCredentials): SourceFactory {
+  return {
+    sourceId: "weather",
+    create: () => new WeatherSource({ credentials: creds }),
+  }
+}
+
+// TFL factory — closure over shared API client
+function tflSourceFactory(api: ITflApi): SourceFactory {
+  return {
+    sourceId: "tfl",
+    create: () => new TflSource({ client: api }),
+  }
+}
+
+class FeedEngineService {
+  private engines = new Map<string, FeedEngine>()
+  private userSources = new Map<string, Map<string, FeedSource>>()
+
+  constructor(private readonly factories: SourceFactory[]) {}
+
+  engineForUser(userId: string): FeedEngine { ... }
+  getSourceForUser<T extends FeedSource>(userId: string, sourceId: string): T | undefined { ... }
+  removeUser(userId: string): void { ... }  // cleans up engine + all sources
+}
+```
+
+**Pros:**
+
+- Minimal change from current structure — `FeedEngineService` evolves, services disappear
+- Factory functions are 5-10 lines each, no classes
+- Shared resources handled naturally via closures
+
+**Cons:**
+
+- `FeedEngineService` grows in responsibility (engine + source tracking + source access)
+- Still two Maps (engines + userSources), though co-located
+
+### Option C: UserSession + Typed Source Handles (Recommended)
+
+Combines Option A's co-location with type-safe source access. `UserSession` owns everything. Source-specific operations go through **source handles** — thin typed wrappers registered at setup time.
+
+```typescript
+// Source handle: typed wrapper for source-specific operations
+interface SourceHandle<T extends FeedSource = FeedSource> {
+	readonly source: T
+}
+
+class UserSession {
+	readonly engine: FeedEngine
+	private handles = new Map<string, SourceHandle>()
+
+	register<T extends FeedSource>(source: T): SourceHandle<T> {
+		this.engine.register(source)
+		const handle: SourceHandle<T> = { source }
+		this.handles.set(source.id, handle)
+		return handle
+	}
+
+	destroy(): void {
+		this.engine.stop()
+		this.handles.clear()
+	}
+}
+
+// In setup code — handles are typed at creation time
+function createSession(userId: string, deps: SessionDeps): UserSession {
+	const session = new UserSession(userId)
+
+	const locationHandle = session.register(new LocationSource())
+	const weatherHandle = session.register(new WeatherSource(deps.weatherCreds))
+	const tflHandle = session.register(new TflSource({ client: deps.tflApi }))
+
+	return session
+}
+```
+
+**Source-specific operations** use the typed handles returned at registration:
+
+```typescript
+// In the tRPC router or wherever source-specific ops happen:
+// The handle is obtained during session setup and stored where needed
+locationHandle.source.pushLocation({ ... })
+tflHandle.source.setLinesOfInterest(["northern"])
+```
+
+**Pros:**
+
+- Single Map, single cleanup
+- Type-safe source access without string-based lookups or casts
+- No boilerplate service classes
+- Handles can be extended later (e.g., add per-source config, metrics)
+- Shared resources passed directly to constructors
+
+**Cons:**
+
+- Handles need to be threaded to where they're used (tRPC routers, etc.)
+- Slightly more setup code in the factory function
+
+## Source-Specific Operations: Approaches
+
+Orthogonal to the session model, there are three ways to handle operations like `pushLocation` or `setLinesOfInterest`:
+
+### Approach 1: Direct Source Access (Recommended)
+
+Callers get a typed reference to the source and call methods directly. This is what all three options above use in different ways.
+
+```typescript
+locationSource.pushLocation(location)
+tflSource.setLinesOfInterest(lines)
+```
+
+**Why this works:** Source packages already define these methods. The backend just needs to expose the source instance to the right caller. No new abstraction needed.
+
+### Approach 2: Command Dispatch
+
+A generic `dispatch(command)` method on the session routes typed commands to sources.
+
+```typescript
+session.dispatch({ type: "location.update", payload: { lat: 51.5, ... } })
+```
+
+**Tradeoff:** Adds indirection and a command type registry. Useful if sources are dynamically loaded plugins, but over-engineered for the current case where sources are known at compile time.
+
+### Approach 3: Context-Only
+
+All input goes through `FeedEngine` context updates. Sources react to context changes.
+
+```typescript
+engine.pushContext({ [LocationKey]: location })
+// LocationSource picks this up via onContextUpdate
+```
+
+**Tradeoff:** Location already works this way (it's a context provider). But not all operations map to context — `setLinesOfInterest` is configuration, not context. Would require stretching the context concept.
+
+## User Source Configuration (DB-Persisted)
+
+Regardless of which option is chosen, user source config needs a storage model:
+
+```sql
+CREATE TABLE user_source_config (
+  user_id    TEXT NOT NULL REFERENCES users(id),
+  source_id  TEXT NOT NULL,          -- e.g., "weather", "tfl", "location"
+  enabled    BOOLEAN NOT NULL DEFAULT true,
+  config     JSONB NOT NULL DEFAULT '{}',  -- source-specific settings
+  PRIMARY KEY (user_id, source_id)
+);
+```
+
+On session creation:
+
+1. Load `user_source_config` rows for the user
+2. Only create sources where `enabled = true`
+3. Pass `config` JSON to the source factory/constructor
+
+New users get default config rows inserted on first login.
+
+## Recommendation
+
+**Option C (UserSession + Typed Source Handles)** with **Approach 1 (Direct Source Access)**.
+
+Rationale:
+
+- Eliminates all per-source service boilerplate
+- Single user lifecycle management point
+- Type-safe without string-based lookups in hot paths
+- Minimal new abstraction — `UserSession` is a thin container, not a framework
+- Handles are just typed references, not a new pattern to learn
+- Natural extension point for per-user config loading from DB
+
+## Acceptance Criteria
+
+1. **No per-source service classes**: `LocationService`, `WeatherService`, `TflService` are removed
+2. **Single user state container**: All per-user state (engine, sources) lives in one object
+3. **Single cleanup**: Removing a user requires one call, not N
+4. **Type-safe source access**: Source-specific operations don't require string-based lookups or unsafe casts at call sites
+5. **Existing tests pass**: `FeedEngineService` tests are migrated to the new structure
+6. **tRPC routes work**: Location update route works through the new architecture
+7. **DB config table**: `user_source_config` table exists; session creation reads from it
+8. **Default config**: New users get default source config on first session
+
+## Implementation Steps
+
+1. Create `user_source_config` DB table and migration
+2. Create `UserSession` class with `register()`, `destroy()`, typed handle return
+3. Create `UserSessionManager` with `getOrCreate()`, `remove()`, config loading
+4. Create `createSession()` factory that reads DB config and registers enabled sources
+5. Refactor `server.ts` to use `UserSessionManager` instead of individual services
+6. Refactor tRPC router to receive session/handles instead of individual services
+7. Delete `LocationService`, `WeatherService`, `TflService` classes
+8. Migrate existing tests to new structure
+9. Add tests for session lifecycle (create, destroy, config loading)
+
+## Open Questions
+
+- **TTL/eviction**: Should `UserSessionManager` handle idle session cleanup? (Currently deferred in backend-spec.md)
+- **Hot reload config**: If a user changes their source config, should the session be recreated or patched in-place?
+- **Shared source instances**: Some sources (e.g., TFL) share an API client. Should the factory receive shared deps, or should there be a DI container?

docs/backend-spec.md

@@ -7,12 +7,14 @@ ARIS needs a backend service that manages per-user FeedEngine instances and deli
 ## Requirements
 
 ### Authentication
+
 - Email/password authentication using BetterAuth
 - PostgreSQL for session and user storage
 - Session tokens validated via `Authorization: Bearer <token>` header
 - Auth endpoints exposed via BetterAuth's built-in routes
 
 ### FeedEngine Management
+
 - Each authenticated user gets their own FeedEngine instance
 - Instances are cached in memory with a 30-minute TTL
 - TTL resets on any activity (WebSocket message, location update)
@@ -20,6 +22,7 @@ ARIS needs a backend service that manages per-user FeedEngine instances and deli
 - Source configuration is hardcoded initially (customization deferred)
 
 ### WebSocket Connection
+
 - Single endpoint: `GET /ws` (upgrades to WebSocket)
 - Authentication via `Authorization: Bearer <token>` header on upgrade request
 - Rejected before upgrade if token is invalid
@@ -28,39 +31,44 @@ ARIS needs a backend service that manages per-user FeedEngine instances and deli
 - On connect: immediately send current feed state
 
 ### JSON-RPC Protocol
+
 All WebSocket communication uses JSON-RPC 2.0.
 
 **Client → Server (Requests):**
+
 ```json
 { "jsonrpc": "2.0", "method": "location.update", "params": { "lat": 51.5, "lng": -0.1, "accuracy": 10, "timestamp": "2025-01-01T12:00:00Z" }, "id": 1 }
 { "jsonrpc": "2.0", "method": "feed.refresh", "params": {}, "id": 2 }
 ```
 
 **Server → Client (Responses):**
+
 ```json
 { "jsonrpc": "2.0", "result": { "ok": true }, "id": 1 }
 ```
 
 **Server → Client (Notifications - no id):**
+
 ```json
 { "jsonrpc": "2.0", "method": "feed.update", "params": { "items": [...], "errors": [...] } }
 ```
 
 ### JSON-RPC Methods
 
-| Method | Params | Description |
-|--------|--------|-------------|
+| Method            | Params                              | Description                                 |
+| ----------------- | ----------------------------------- | ------------------------------------------- |
 | `location.update` | `{ lat, lng, accuracy, timestamp }` | Push location update, triggers feed refresh |
-| `feed.refresh` | `{}` | Force manual feed refresh |
+| `feed.refresh`    | `{}`                                | Force manual feed refresh                   |
 
 ### Server Notifications
 
-| Method | Params | Description |
-|--------|--------|-------------|
-| `feed.update` | `{ context, items, errors }` | Feed state changed |
-| `error` | `{ code, message, data? }` | Source or system error |
+| Method        | Params                       | Description            |
+| ------------- | ---------------------------- | ---------------------- |
+| `feed.update` | `{ context, items, errors }` | Feed state changed     |
+| `error`       | `{ code, message, data? }`   | Source or system error |
 
 ### Error Handling
+
 - Source failures during refresh are reported via `error` notification
 - Format: `{ "jsonrpc": "2.0", "method": "error", "params": { "code": -32000, "message": "...", "data": { "sourceId": "weather" } } }`
 
@@ -96,16 +104,19 @@ All WebSocket communication uses JSON-RPC 2.0.
 ## Implementation Approach
 
 ### Phase 1: Project Setup
+
 1. Create `apps/aris-backend` with Hono
 2. Configure TypeScript, add dependencies (hono, better-auth, postgres driver)
 3. Set up database connection and BetterAuth
 
 ### Phase 2: Authentication
+
 4. Configure BetterAuth with email/password provider
 5. Mount BetterAuth routes at `/api/auth/*`
 6. Create session validation helper for extracting user from token
 
 ### Phase 3: FeedEngine Manager
+
 7. Create `FeedEngineManager` class:
    - `getOrCreate(userId): FeedEngine` - returns cached or creates new
    - `touch(userId)` - resets TTL
@@ -114,22 +125,26 @@ All WebSocket communication uses JSON-RPC 2.0.
 8. Factory function to create FeedEngine with default sources
 
 ### Phase 4: WebSocket Handler
+
 9. Create WebSocket upgrade endpoint at `/ws`
 10. Validate `Authorization` header before upgrade
 11. On connect: register connection, send initial feed state
 12. On disconnect: unregister connection
 
 ### Phase 5: JSON-RPC Handler
+
 13. Create JSON-RPC message parser and dispatcher
 14. Implement `location.update` method
 15. Implement `feed.refresh` method
 16. Wire FeedEngine subscription to broadcast `feed.update` to all user connections
 
 ### Phase 6: Connection Manager
+
 17. Create `ConnectionManager` to track WebSocket connections per user
 18. Broadcast helper to send to all connections for a user
 
 ### Phase 7: Integration & Testing
+
 19. Integration test: auth → connect → location update → receive feed
 20. Test multiple connections receive same updates
 21. Test TTL cleanup
@@ -158,15 +173,15 @@ apps/aris-backend/
 
 ```json
 {
-  "dependencies": {
-    "hono": "^4",
-    "better-auth": "^1",
-    "postgres": "^3",
-    "@aris/core": "workspace:*",
-    "@aris/source-location": "workspace:*",
-    "@aris/source-weatherkit": "workspace:*",
-    "@aris/data-source-tfl": "workspace:*"
-  }
+	"dependencies": {
+		"hono": "^4",
+		"better-auth": "^1",
+		"postgres": "^3",
+		"@aris/core": "workspace:*",
+		"@aris/source-location": "workspace:*",
+		"@aris/source-weatherkit": "workspace:*",
+		"@aris/data-source-tfl": "workspace:*"
+	}
 }
 ```
 

docs/feed-source-actions-spec.md

@@ -0,0 +1,269 @@
+# FeedSource Actions
+
+## Problem Statement
+
+`FeedSource` is read-only. Sources can provide context and feed items but can't expose write operations (play, RSVP, dismiss). This blocks interactive sources like Spotify, calendar, and tasks.
+
+## Scope
+
+**`aris-core` only.** Add action support to `FeedSource` and `FeedItem`. No changes to existing fields or methods — purely additive.
+
+## Design
+
+### Why Not MCP
+
+MCP was considered. It doesn't fit because:
+
+- MCP resources don't accept input context (FeedSource needs accumulated context as input)
+- MCP has no structured feed items (priority, timestamp, type)
+- MCP's isolation model conflicts with ARIS's dependency graph
+- Adding these as MCP extensions would mean the extensions are the entire protocol
+
+The interface is designed to be **protocol-compatible** — a future `RemoteFeedSource` adapter can map each field/method to a JSON-RPC operation without changing the interface:
+
+| FeedSource field/method | Future protocol operation |
+| ----------------------- | ------------------------- |
+| `id`, `dependencies`    | `source/describe`         |
+| `listActions()`         | `source/listActions`      |
+| `fetchContext()`        | `source/fetchContext`     |
+| `fetchItems()`          | `source/fetchItems`       |
+| `executeAction()`       | `source/executeAction`    |
+| `onContextUpdate()`     | `source/contextUpdated`   |
+| `onItemsUpdate()`       | `source/itemsUpdated`     |
+
+No interface changes needed when the transport layer is built.
+
+### Source ID & Action ID Convention
+
+Source IDs use reverse domain notation. Built-in sources use `aris.<name>`. Third parties use their own domain.
+
+Action IDs are descriptive verb-noun pairs in kebab-case, scoped to their source. The globally unique form is `<sourceId>/<actionId>`.
+
+| Source ID       | Action IDs                                                     |
+| --------------- | -------------------------------------------------------------- |
+| `aris.location` | `update-location` (migrated from `pushLocation()`)             |
+| `aris.tfl`      | `set-lines-of-interest` (migrated from `setLinesOfInterest()`) |
+| `aris.weather`  | _(none)_                                                       |
+| `com.spotify`   | `play-track`, `pause-playback`, `skip-track`, `like-track`     |
+| `aris.calendar` | `rsvp`, `create-event`                                         |
+| `com.todoist`   | `complete-task`, `snooze-task`                                 |
+
+This means existing source packages need their `id` updated (e.g., `"location"` → `"aris.location"`).
+
+### New Types
+
+```typescript
+/** Describes an action a source can perform. */
+interface ActionDefinition<TInput = unknown> {
+	/** Descriptive action name in kebab-case (e.g., "update-location", "play-track") */
+	readonly id: string
+	/** Human-readable label for UI (e.g., "Play", "RSVP Yes") */
+	readonly label: string
+	/** Optional longer description */
+	readonly description?: string
+	/** Schema for input validation. Accepts any Standard Schema compatible validator (arktype, zod, valibot, etc.). Omit if no params. */
+	readonly input?: StandardSchemaV1<TInput>
+}
+```
+
+`StandardSchemaV1` is the [Standard Schema](https://github.com/standard-schema/standard-schema) interface implemented by arktype, zod, and valibot. This means sources can use any validator:
+
+```typescript
+import { type } from "arktype"
+import { z } from "zod"
+
+// With arktype
+{ id: "play-track", label: "Play", input: type({ trackId: "string" }) }
+
+// With zod
+{ id: "play-track", label: "Play", input: z.object({ trackId: z.string() }) }
+
+// Without validation (e.g., remote sources using raw JSON Schema)
+{ id: "play-track", label: "Play" }
+
+/** Result of executing an action. */
+interface ActionResult {
+  ok: boolean
+  data?: Record<string, unknown>
+  error?: string
+}
+
+/** Reference to an action on a specific feed item. */
+interface ItemAction {
+  /** Action ID (matches ActionDefinition.id on the source) */
+  actionId: string
+  /** Per-item label override (e.g., "RSVP to standup") */
+  label?: string
+  /** Pre-filled params for this item (e.g., { eventId: "abc" }) */
+  params?: Record<string, unknown>
+}
+```
+
+### Changes to FeedSource
+
+Two optional fields added. Nothing else changes.
+
+```typescript
+interface FeedSource<TItem extends FeedItem = FeedItem> {
+  readonly id: string                              // unchanged
+  readonly dependencies?: readonly string[]        // unchanged
+  fetchContext(...): ...                            // unchanged
+  onContextUpdate?(...): ...                       // unchanged
+  fetchItems?(...): ...                            // unchanged
+  onItemsUpdate?(...): ...                         // unchanged
+
+  /** List actions this source supports. Empty record if none. Maps to: source/listActions */
+  listActions(): Promise<Record<string, ActionDefinition>>
+
+  /** Execute an action by ID. No-op returning { ok: false } if source has no actions. */
+  executeAction(
+    actionId: string,
+    params: Record<string, unknown>,
+  ): Promise<ActionResult>
+}
+```
+
+### Changes to FeedItem
+
+One optional field added.
+
+```typescript
+interface FeedItem<
+	TType extends string = string,
+	TData extends Record<string, unknown> = Record<string, unknown>,
+> {
+	id: string // unchanged
+	type: TType // unchanged
+	priority: number // unchanged
+	timestamp: Date // unchanged
+	data: TData // unchanged
+
+	/** Actions the user can take on this item. */
+	actions?: readonly ItemAction[]
+}
+```
+
+### Changes to FeedEngine
+
+Two new methods. Existing methods unchanged.
+
+```typescript
+class FeedEngine {
+	// All existing methods unchanged...
+
+	/** Route an action call to the correct source. */
+	async executeAction(
+		sourceId: string,
+		actionId: string,
+		params: Record<string, unknown>,
+	): Promise<ActionResult>
+
+	/** List all actions across all registered sources. */
+	listActions(): { sourceId: string; actions: readonly ActionDefinition[] }[]
+}
+```
+
+### Example: Spotify Source
+
+```typescript
+class SpotifySource implements FeedSource<SpotifyFeedItem> {
+	readonly id = "com.spotify"
+
+	async listActions() {
+		return {
+			"play-track": { id: "play-track", label: "Play", input: type({ trackId: "string" }) },
+			"pause-playback": { id: "pause-playback", label: "Pause" },
+			"skip-track": { id: "skip-track", label: "Skip" },
+			"like-track": { id: "like-track", label: "Like", input: type({ trackId: "string" }) },
+		}
+	}
+
+	async executeAction(actionId: string, params: Record<string, unknown>): Promise<ActionResult> {
+		switch (actionId) {
+			case "play-track":
+				await this.client.play(params.trackId as string)
+				return { ok: true }
+			case "pause-playback":
+				await this.client.pause()
+				return { ok: true }
+			case "skip-track":
+				await this.client.skip()
+				return { ok: true }
+			case "like-track":
+				await this.client.like(params.trackId as string)
+				return { ok: true }
+			default:
+				return { ok: false, error: `Unknown action: ${actionId}` }
+		}
+	}
+
+	async fetchContext(): Promise<null> {
+		return null
+	}
+
+	// Note: for a source with no actions, it would be:
+	// async listActions() { return {} }
+	// async executeAction(): Promise<ActionResult> {
+	//   return { ok: false, error: "No actions supported" }
+	// }
+
+	async fetchItems(context: Context): Promise<SpotifyFeedItem[]> {
+		const track = await this.client.getCurrentTrack()
+		if (!track) return []
+		return [
+			{
+				id: `spotify-${track.id}`,
+				type: "spotify-now-playing",
+				priority: 0.4,
+				timestamp: context.time,
+				data: { trackName: track.name, artist: track.artist },
+				actions: [
+					{ actionId: "pause-playback" },
+					{ actionId: "skip-track" },
+					{ actionId: "like-track", params: { trackId: track.id } },
+				],
+			},
+		]
+	}
+}
+```
+
+## Acceptance Criteria
+
+1. `ActionDefinition` type exists with `id`, `label`, `description?`, `inputSchema?`
+2. `ActionResult` type exists with `ok`, `data?`, `error?`
+3. `ItemAction` type exists with `actionId`, `label?`, `params?`
+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`
+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)
+10. New tests: action execution, unknown action ID, unknown source ID, source without actions, `listActions()` aggregation
+
+## Implementation Steps
+
+1. Create `action.ts` in `aris-core/src` with `ActionDefinition`, `ActionResult`, `ItemAction`
+2. Add optional `actions` and `executeAction` to `FeedSource` interface in `feed-source.ts`
+3. Add optional `actions` field to `FeedItem` interface in `feed.ts`
+4. Add `executeAction()` and `listActions()` to `FeedEngine` in `feed-engine.ts`
+5. Export new types from `aris-core/index.ts`
+6. Add tests for `FeedEngine.executeAction()` routing
+7. Add tests for `FeedEngine.listActions()` aggregation
+8. Add tests for error cases (unknown action, unknown source, source without actions)
+9. Update source IDs to reverse-domain format (`"location"` → `"aris.location"`, etc.) across all source packages
+10. Migrate `LocationSource.pushLocation()` → action `update-location` on `aris.location`
+11. Migrate `TflSource.setLinesOfInterest()` → action `set-lines-of-interest` on `aris.tfl`
+12. Add `async listActions() { return {} }` and no-op `executeAction()` to sources without actions (WeatherSource, GoogleCalendarSource, AppleCalendarSource)
+13. Update any tests or code referencing old source IDs
+14. Run all tests to confirm nothing breaks
+
+## What This Defers
+
+- Transport layer (JSON-RPC over HTTP/WebSocket) — built when remote sources are needed
+- `RemoteFeedSource` adapter — mechanical once transport exists
+- MCP adapter — wraps MCP servers as FeedSource
+- Runtime schema validation of action params
+- Action permissions / confirmation UI
+- Source discovery / registry API
+- Backend service consolidation (separate spec, depends on this one)

packages/aris-core/package.json

@@ -6,5 +6,8 @@
 	"types": "src/index.ts",
 	"scripts": {
 		"test": "bun test ."
+	},
+	"dependencies": {
+		"@standard-schema/spec": "^1.1.0"
 	}
 }

packages/aris-core/src/action.ts

@@ -0,0 +1,27 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec"
+
+/**
+ * Describes an action a source can perform.
+ *
+ * Action IDs use descriptive verb-noun kebab-case (e.g., "update-location", "play-track").
+ * Combined with the source's reverse-domain ID, they form a globally unique identifier:
+ * `<sourceId>/<actionId>` (e.g., "aris.location/update-location").
+ */
+export class UnknownActionError extends Error {
+	readonly actionId: string
+
+	constructor(actionId: string) {
+		super(`Unknown action: ${actionId}`)
+		this.name = "UnknownActionError"
+		this.actionId = actionId
+	}
+}
+
+export interface ActionDefinition<TInput = unknown> {
+	/** Descriptive action name in kebab-case (e.g., "update-location", "play-track") */
+	readonly id: string
+	/** Optional longer description */
+	readonly description?: string
+	/** Schema for input validation. Accepts any Standard Schema compatible validator (arktype, zod, valibot, etc.). */
+	readonly input?: StandardSchemaV1<TInput>
+}

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

@@ -1,9 +1,19 @@
 import { describe, expect, test } from "bun:test"
 
-import type { Context, ContextKey, FeedItem, FeedSource } from "./index"
+import type { ActionDefinition, Context, ContextKey, FeedItem, FeedSource } from "./index"
 
 import { FeedEngine } from "./feed-engine"
-import { contextKey, contextValue } from "./index"
+import { UnknownActionError, contextKey, contextValue } from "./index"
+
+// No-op action methods for test sources
+const noActions = {
+	async listActions(): Promise<Record<string, ActionDefinition>> {
+		return {}
+	},
+	async executeAction(actionId: string): Promise<void> {
+		throw new UnknownActionError(actionId)
+	},
+}
 
 // =============================================================================
 // CONTEXT KEYS
@@ -43,6 +53,7 @@ function createLocationSource(): SimulatedLocationSource {
 
 	return {
 		id: "location",
+		...noActions,
 
 		onContextUpdate(cb) {
 			callback = cb
@@ -71,10 +82,11 @@ function createWeatherSource(
 	return {
 		id: "weather",
 		dependencies: ["location"],
+		...noActions,
 
 		async fetchContext(context) {
 			const location = contextValue(context, LocationKey)
-			if (!location) return {}
+			if (!location) return null
 
 			const weather = await fetchWeather(location)
 			return { [WeatherKey]: weather }
@@ -104,6 +116,11 @@ function createAlertSource(): FeedSource<AlertFeedItem> {
 	return {
 		id: "alert",
 		dependencies: ["weather"],
+		...noActions,
+
+		async fetchContext() {
+			return null
+		},
 
 		async fetchItems(context) {
 			const weather = contextValue(context, WeatherKey)
@@ -164,39 +181,78 @@ describe("FeedEngine", () => {
 	})
 
 	describe("graph validation", () => {
-		test("throws on missing dependency", () => {
+		test("throws on missing dependency", async () => {
 			const engine = new FeedEngine()
 			const orphan: FeedSource = {
 				id: "orphan",
 				dependencies: ["nonexistent"],
+				...noActions,
+				async fetchContext() {
+					return null
+				},
 			}
 
 			engine.register(orphan)
 
-			expect(engine.refresh()).rejects.toThrow(
+			await expect(engine.refresh()).rejects.toThrow(
 				'Source "orphan" depends on "nonexistent" which is not registered',
 			)
 		})
 
-		test("throws on circular dependency", () => {
+		test("throws on circular dependency", async () => {
 			const engine = new FeedEngine()
-			const a: FeedSource = { id: "a", dependencies: ["b"] }
-			const b: FeedSource = { id: "b", dependencies: ["a"] }
+			const a: FeedSource = {
+				id: "a",
+				dependencies: ["b"],
+				...noActions,
+				async fetchContext() {
+					return null
+				},
+			}
+			const b: FeedSource = {
+				id: "b",
+				dependencies: ["a"],
+				...noActions,
+				async fetchContext() {
+					return null
+				},
+			}
 
 			engine.register(a).register(b)
 
-			expect(engine.refresh()).rejects.toThrow("Circular dependency detected: a → b → a")
+			await expect(engine.refresh()).rejects.toThrow("Circular dependency detected: a → b → a")
 		})
 
-		test("throws on longer cycles", () => {
+		test("throws on longer cycles", async () => {
 			const engine = new FeedEngine()
-			const a: FeedSource = { id: "a", dependencies: ["c"] }
-			const b: FeedSource = { id: "b", dependencies: ["a"] }
-			const c: FeedSource = { id: "c", dependencies: ["b"] }
+			const a: FeedSource = {
+				id: "a",
+				dependencies: ["c"],
+				...noActions,
+				async fetchContext() {
+					return null
+				},
+			}
+			const b: FeedSource = {
+				id: "b",
+				dependencies: ["a"],
+				...noActions,
+				async fetchContext() {
+					return null
+				},
+			}
+			const c: FeedSource = {
+				id: "c",
+				dependencies: ["b"],
+				...noActions,
+				async fetchContext() {
+					return null
+				},
+			}
 
 			engine.register(a).register(b).register(c)
 
-			expect(engine.refresh()).rejects.toThrow("Circular dependency detected")
+			await expect(engine.refresh()).rejects.toThrow("Circular dependency detected")
 		})
 	})
 
@@ -206,6 +262,7 @@ describe("FeedEngine", () => {
 
 			const location: FeedSource = {
 				id: "location",
+				...noActions,
 				async fetchContext() {
 					order.push("location")
 					return { [LocationKey]: { lat: 51.5, lng: -0.1 } }
@@ -215,6 +272,7 @@ describe("FeedEngine", () => {
 			const weather: FeedSource = {
 				id: "weather",
 				dependencies: ["location"],
+				...noActions,
 				async fetchContext(ctx) {
 					order.push("weather")
 					const loc = contextValue(ctx, LocationKey)
@@ -240,8 +298,14 @@ describe("FeedEngine", () => {
 
 			const { context } = await engine.refresh()
 
-			expect(contextValue(context, LocationKey)).toEqual({ lat: 51.5, lng: -0.1 })
-			expect(contextValue(context, WeatherKey)).toEqual({ temperature: 20, condition: "sunny" })
+			expect(contextValue(context, LocationKey)).toEqual({
+				lat: 51.5,
+				lng: -0.1,
+			})
+			expect(contextValue(context, WeatherKey)).toEqual({
+				temperature: 20,
+				condition: "sunny",
+			})
 		})
 
 		test("collects items from all sources", async () => {
@@ -281,8 +345,9 @@ describe("FeedEngine", () => {
 		test("handles missing upstream context gracefully", async () => {
 			const location: FeedSource = {
 				id: "location",
+				...noActions,
 				async fetchContext() {
-					return {} // No location available
+					return null // No location available
 				},
 			}
 
@@ -299,6 +364,7 @@ describe("FeedEngine", () => {
 		test("captures errors from fetchContext", async () => {
 			const failing: FeedSource = {
 				id: "failing",
+				...noActions,
 				async fetchContext() {
 					throw new Error("Context fetch failed")
 				},
@@ -316,6 +382,10 @@ describe("FeedEngine", () => {
 		test("captures errors from fetchItems", async () => {
 			const failing: FeedSource = {
 				id: "failing",
+				...noActions,
+				async fetchContext() {
+					return null
+				},
 				async fetchItems() {
 					throw new Error("Items fetch failed")
 				},
@@ -333,6 +403,7 @@ describe("FeedEngine", () => {
 		test("continues after source error", async () => {
 			const failing: FeedSource = {
 				id: "failing",
+				...noActions,
 				async fetchContext() {
 					throw new Error("Failed")
 				},
@@ -340,6 +411,10 @@ describe("FeedEngine", () => {
 
 			const working: FeedSource = {
 				id: "working",
+				...noActions,
+				async fetchContext() {
+					return null
+				},
 				async fetchItems() {
 					return [
 						{
@@ -380,7 +455,10 @@ describe("FeedEngine", () => {
 			await engine.refresh()
 
 			const context = engine.currentContext()
-			expect(contextValue(context, LocationKey)).toEqual({ lat: 51.5, lng: -0.1 })
+			expect(contextValue(context, LocationKey)).toEqual({
+				lat: 51.5,
+				lng: -0.1,
+			})
 		})
 	})
 
@@ -455,4 +533,109 @@ describe("FeedEngine", () => {
 			engine.stop()
 		})
 	})
+
+	describe("executeAction", () => {
+		test("routes action to correct source", async () => {
+			let receivedAction = ""
+			let receivedParams: unknown = {}
+
+			const source: FeedSource = {
+				id: "test-source",
+				async listActions() {
+					return {
+						"do-thing": { id: "do-thing" },
+					}
+				},
+				async executeAction(actionId, params) {
+					receivedAction = actionId
+					receivedParams = params
+				},
+				async fetchContext() {
+					return null
+				},
+			}
+
+			const engine = new FeedEngine().register(source)
+			await engine.executeAction("test-source", "do-thing", { key: "value" })
+
+			expect(receivedAction).toBe("do-thing")
+			expect(receivedParams).toEqual({ key: "value" })
+		})
+
+		test("throws for unknown source", async () => {
+			const engine = new FeedEngine()
+
+			await expect(engine.executeAction("nonexistent", "action", {})).rejects.toThrow(
+				"Source not found: nonexistent",
+			)
+		})
+
+		test("throws for unknown action on source", async () => {
+			const source: FeedSource = {
+				id: "test-source",
+				...noActions,
+				async fetchContext() {
+					return null
+				},
+			}
+
+			const engine = new FeedEngine().register(source)
+
+			await expect(engine.executeAction("test-source", "nonexistent", {})).rejects.toThrow(
+				'Action "nonexistent" not found on source "test-source"',
+			)
+		})
+	})
+
+	describe("listActions", () => {
+		test("returns actions for a specific source", async () => {
+			const source: FeedSource = {
+				id: "test-source",
+				async listActions() {
+					return {
+						"action-1": { id: "action-1" },
+						"action-2": { id: "action-2" },
+					}
+				},
+				async executeAction() {},
+				async fetchContext() {
+					return null
+				},
+			}
+
+			const engine = new FeedEngine().register(source)
+			const actions = await engine.listActions("test-source")
+
+			expect(Object.keys(actions)).toEqual(["action-1", "action-2"])
+		})
+
+		test("throws for unknown source", async () => {
+			const engine = new FeedEngine()
+
+			await expect(engine.listActions("nonexistent")).rejects.toThrow(
+				"Source not found: nonexistent",
+			)
+		})
+
+		test("throws on mismatched action ID", async () => {
+			const source: FeedSource = {
+				id: "bad-source",
+				async listActions() {
+					return {
+						"correct-key": { id: "wrong-id" },
+					}
+				},
+				async executeAction() {},
+				async fetchContext() {
+					return null
+				},
+			}
+
+			const engine = new FeedEngine().register(source)
+
+			await expect(engine.listActions("bad-source")).rejects.toThrow(
+				'Action ID mismatch on source "bad-source"',
+			)
+		})
+	})
 })

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

@@ -1,3 +1,4 @@
+import type { ActionDefinition } from "./action"
 import type { Context } from "./context"
 import type { FeedItem } from "./feed"
 import type { FeedSource } from "./feed-source"
@@ -89,16 +90,16 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
 
 		// Run fetchContext in topological order
 		for (const source of graph.sorted) {
-			if (source.fetchContext) {
-				try {
-					const update = await source.fetchContext(context)
+			try {
+				const update = await source.fetchContext(context)
+				if (update) {
 					context = { ...context, ...update }
-				} catch (err) {
-					errors.push({
-						sourceId: source.id,
-						error: err instanceof Error ? err : new Error(String(err)),
-					})
 				}
+			} catch (err) {
+				errors.push({
+					sourceId: source.id,
+					error: err instanceof Error ? err : new Error(String(err)),
+				})
 			}
 		}
 
@@ -187,6 +188,44 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
 		return this.context
 	}
 
+	/**
+	 * Execute an action on a registered source.
+	 * Validates the action exists before dispatching.
+	 *
+	 * In pull-only mode (before `start()` is called), the action mutates source
+	 * state but does not automatically refresh dependents. Call `refresh()`
+	 * after to propagate changes. In reactive mode (`start()` called), sources
+	 * that push context updates (e.g., LocationSource) will trigger dependent
+	 * refresh automatically.
+	 */
+	async executeAction(sourceId: string, actionId: string, params: unknown): Promise<unknown> {
+		const actions = await this.listActions(sourceId)
+		if (!(actionId in actions)) {
+			throw new Error(`Action "${actionId}" not found on source "${sourceId}"`)
+		}
+		return this.sources.get(sourceId)!.executeAction(actionId, params)
+	}
+
+	/**
+	 * List actions available on a specific source.
+	 * Validates that action definition IDs match their record keys.
+	 */
+	async listActions(sourceId: string): Promise<Record<string, ActionDefinition>> {
+		const source = this.sources.get(sourceId)
+		if (!source) {
+			throw new Error(`Source not found: ${sourceId}`)
+		}
+		const actions = await source.listActions()
+		for (const [key, definition] of Object.entries(actions)) {
+			if (key !== definition.id) {
+				throw new Error(
+					`Action ID mismatch on source "${sourceId}": key "${key}" !== definition.id "${definition.id}"`,
+				)
+			}
+		}
+		return actions
+	}
+
 	private ensureGraph(): SourceGraph {
 		if (!this.graph) {
 			this.graph = buildGraph(Array.from(this.sources.values()))
@@ -208,10 +247,12 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
 		// Re-run fetchContext for dependents in order
 		for (const id of toRefresh) {
 			const source = graph.sources.get(id)
-			if (source?.fetchContext) {
+			if (source) {
 				try {
 					const update = await source.fetchContext(this.context)
-					this.context = { ...this.context, ...update }
+					if (update) {
+						this.context = { ...this.context, ...update }
+					}
 				} catch {
 					// Errors during reactive updates are logged but don't stop propagation
 				}
@@ -238,7 +279,11 @@ export class FeedEngine<TItems extends FeedItem = FeedItem> {
 
 		items.sort((a, b) => b.priority - a.priority)
 
-		this.notifySubscribers({ context: this.context, items: items as TItems[], errors })
+		this.notifySubscribers({
+			context: this.context,
+			items: items as TItems[],
+			errors,
+		})
 	}
 
 	private collectDependents(sourceId: string, graph: SourceGraph): string[] {

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

@@ -1,8 +1,18 @@
 import { describe, expect, test } from "bun:test"
 
-import type { Context, ContextKey, FeedItem, FeedSource } from "./index"
+import type { ActionDefinition, Context, ContextKey, FeedItem, FeedSource } from "./index"
 
-import { contextKey, contextValue } from "./index"
+import { UnknownActionError, contextKey, contextValue } from "./index"
+
+// No-op action methods for test sources
+const noActions = {
+	async listActions(): Promise<Record<string, ActionDefinition>> {
+		return {}
+	},
+	async executeAction(actionId: string): Promise<void> {
+		throw new UnknownActionError(actionId)
+	},
+}
 
 // =============================================================================
 // CONTEXT KEYS
@@ -42,6 +52,7 @@ function createLocationSource(): SimulatedLocationSource {
 
 	return {
 		id: "location",
+		...noActions,
 
 		onContextUpdate(cb) {
 			callback = cb
@@ -70,10 +81,11 @@ function createWeatherSource(
 	return {
 		id: "weather",
 		dependencies: ["location"],
+		...noActions,
 
 		async fetchContext(context) {
 			const location = contextValue(context, LocationKey)
-			if (!location) return {}
+			if (!location) return null
 
 			const weather = await fetchWeather(location)
 			return { [WeatherKey]: weather }
@@ -103,6 +115,11 @@ function createAlertSource(): FeedSource<AlertFeedItem> {
 	return {
 		id: "alert",
 		dependencies: ["weather"],
+		...noActions,
+
+		async fetchContext() {
+			return null
+		},
 
 		async fetchItems(context) {
 			const weather = contextValue(context, WeatherKey)
@@ -194,8 +211,8 @@ async function refreshGraph(graph: SourceGraph): Promise<{ context: Context; ite
 
 	// Run fetchContext in topological order
 	for (const source of graph.sorted) {
-		if (source.fetchContext) {
-			const update = await source.fetchContext(context)
+		const update = await source.fetchContext(context)
+		if (update) {
 			context = { ...context, ...update }
 		}
 	}
@@ -245,9 +262,15 @@ describe("FeedSource", () => {
 
 			expect(source.id).toBe("alert")
 			expect(source.dependencies).toEqual(["weather"])
-			expect(source.fetchContext).toBeUndefined()
+			expect(source.fetchContext).toBeDefined()
 			expect(source.fetchItems).toBeDefined()
 		})
+
+		test("source without context returns null from fetchContext", async () => {
+			const source = createAlertSource()
+			const result = await source.fetchContext({ time: new Date() })
+			expect(result).toBeNull()
+		})
 	})
 
 	describe("graph validation", () => {
@@ -255,6 +278,10 @@ describe("FeedSource", () => {
 			const orphan: FeedSource = {
 				id: "orphan",
 				dependencies: ["nonexistent"],
+				...noActions,
+				async fetchContext() {
+					return null
+				},
 			}
 
 			expect(() => buildGraph([orphan])).toThrow(
@@ -263,16 +290,51 @@ describe("FeedSource", () => {
 		})
 
 		test("detects circular dependencies", () => {
-			const a: FeedSource = { id: "a", dependencies: ["b"] }
-			const b: FeedSource = { id: "b", dependencies: ["a"] }
+			const a: FeedSource = {
+				id: "a",
+				dependencies: ["b"],
+				...noActions,
+				async fetchContext() {
+					return null
+				},
+			}
+			const b: FeedSource = {
+				id: "b",
+				dependencies: ["a"],
+				...noActions,
+				async fetchContext() {
+					return null
+				},
+			}
 
 			expect(() => buildGraph([a, b])).toThrow("Circular dependency detected: a → b → a")
 		})
 
 		test("detects longer cycles", () => {
-			const a: FeedSource = { id: "a", dependencies: ["c"] }
-			const b: FeedSource = { id: "b", dependencies: ["a"] }
-			const c: FeedSource = { id: "c", dependencies: ["b"] }
+			const a: FeedSource = {
+				id: "a",
+				dependencies: ["c"],
+				...noActions,
+				async fetchContext() {
+					return null
+				},
+			}
+			const b: FeedSource = {
+				id: "b",
+				dependencies: ["a"],
+				...noActions,
+				async fetchContext() {
+					return null
+				},
+			}
+			const c: FeedSource = {
+				id: "c",
+				dependencies: ["b"],
+				...noActions,
+				async fetchContext() {
+					return null
+				},
+			}
 
 			expect(() => buildGraph([a, b, c])).toThrow("Circular dependency detected")
 		})
@@ -307,6 +369,7 @@ describe("FeedSource", () => {
 
 			const location: FeedSource = {
 				id: "location",
+				...noActions,
 				async fetchContext() {
 					order.push("location")
 					return { [LocationKey]: { lat: 51.5, lng: -0.1 } }
@@ -316,6 +379,7 @@ describe("FeedSource", () => {
 			const weather: FeedSource = {
 				id: "weather",
 				dependencies: ["location"],
+				...noActions,
 				async fetchContext(ctx) {
 					order.push("weather")
 					const loc = contextValue(ctx, LocationKey)
@@ -339,8 +403,14 @@ describe("FeedSource", () => {
 			const graph = buildGraph([location, weather])
 			const { context } = await refreshGraph(graph)
 
-			expect(contextValue(context, LocationKey)).toEqual({ lat: 51.5, lng: -0.1 })
-			expect(contextValue(context, WeatherKey)).toEqual({ temperature: 20, condition: "sunny" })
+			expect(contextValue(context, LocationKey)).toEqual({
+				lat: 51.5,
+				lng: -0.1,
+			})
+			expect(contextValue(context, WeatherKey)).toEqual({
+				temperature: 20,
+				condition: "sunny",
+			})
 		})
 
 		test("collects items from all sources", async () => {
@@ -376,12 +446,13 @@ describe("FeedSource", () => {
 		})
 
 		test("source without location context returns empty items", async () => {
-			// Location source exists but hasn't been updated (returns default 0,0)
+			// Location source exists but hasn't been updated
 			const location: FeedSource = {
 				id: "location",
+				...noActions,
 				async fetchContext() {
 					// Simulate no location available
-					return {}
+					return null
 				},
 			}
 

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

@@ -1,54 +1,60 @@
+import type { ActionDefinition } from "./action"
 import type { Context } from "./context"
 import type { FeedItem } from "./feed"
 
 /**
- * Unified interface for sources that provide context and/or feed items.
+ * Unified interface for sources that provide context, feed items, and actions.
  *
- * Sources form a dependency graph - a source declares which other sources
+ * Sources form a dependency graph — a source declares which other sources
  * it depends on, and the graph ensures dependencies are resolved before
  * dependents run.
  *
- * A source may:
- * - Provide context for other sources (implement fetchContext/onContextUpdate)
- * - Produce feed items (implement fetchItems/onItemsUpdate)
- * - Both
+ * Source IDs use reverse domain notation. Built-in sources use `aris.<name>`,
+ * third parties use their own domain (e.g., `com.spotify`).
+ *
+ * Every method maps to a protocol operation for remote source support:
+ * - `id`, `dependencies`       → source/describe
+ * - `listActions()`            → source/listActions
+ * - `executeAction()`          → source/executeAction
+ * - `fetchContext()`           → source/fetchContext
+ * - `fetchItems()`             → source/fetchItems
+ * - `onContextUpdate()`        → source/contextUpdated (notification)
+ * - `onItemsUpdate()`          → source/itemsUpdated (notification)
  *
  * @example
  * ```ts
- * // Location source - provides context only
  * const locationSource: FeedSource = {
- *   id: "location",
- *   fetchContext: async () => {
- *     const pos = await getCurrentPosition()
- *     return { location: { lat: pos.coords.latitude, lng: pos.coords.longitude } }
- *   },
- * }
- *
- * // Weather source - depends on location, provides both context and items
- * const weatherSource: FeedSource<WeatherFeedItem> = {
- *   id: "weather",
- *   dependencies: ["location"],
- *   fetchContext: async (ctx) => {
- *     const weather = await fetchWeather(ctx.location)
- *     return { weather }
- *   },
- *   fetchItems: async (ctx) => {
- *     return createWeatherFeedItems(ctx.weather)
- *   },
+ *   id: "aris.location",
+ *   async listActions() { return { "update-location": { id: "update-location" } } },
+ *   async executeAction(actionId) { throw new UnknownActionError(actionId) },
+ *   async fetchContext() { ... },
  * }
  * ```
  */
 export interface FeedSource<TItem extends FeedItem = FeedItem> {
-	/** Unique identifier for this source */
+	/** Unique identifier for this source in reverse-domain format */
 	readonly id: string
 
 	/** IDs of sources this source depends on */
 	readonly dependencies?: readonly string[]
 
+	/**
+	 * List actions this source supports. Empty record if none.
+	 * Maps to: source/listActions
+	 */
+	listActions(): Promise<Record<string, ActionDefinition>>
+
+	/**
+	 * Execute an action by ID. Throws on unknown action or invalid input.
+	 * Maps to: source/executeAction
+	 */
+	executeAction(actionId: string, params: unknown): Promise<unknown>
+
 	/**
 	 * Subscribe to reactive context updates.
 	 * Called when the source can push context changes proactively.
 	 * Returns cleanup function.
+	 * Maps to: source/contextUpdated (notification, source → host)
 	 */
 	onContextUpdate?(
 		callback: (update: Partial<Context>) => void,
@@ -58,19 +64,23 @@ export interface FeedSource<TItem extends FeedItem = FeedItem> {
 	/**
 	 * Fetch context on-demand.
 	 * Called during manual refresh or initial load.
+	 * Return null if this source cannot provide context.
+	 * Maps to: source/fetchContext
 	 */
-	fetchContext?(context: Context): Promise<Partial<Context>>
+	fetchContext(context: Context): Promise<Partial<Context> | null>
 
 	/**
 	 * Subscribe to reactive feed item updates.
 	 * Called when the source can push item changes proactively.
 	 * Returns cleanup function.
+	 * Maps to: source/itemsUpdated (notification, source → host)
 	 */
 	onItemsUpdate?(callback: (items: TItem[]) => void, getContext: () => Context): () => void
 
 	/**
 	 * Fetch feed items on-demand.
 	 * Called during manual refresh or when dependencies update.
+	 * Maps to: source/fetchItems
 	 */
 	fetchItems?(context: Context): Promise<TItem[]>
 }

packages/aris-core/src/index.ts

@@ -2,6 +2,10 @@
 export type { Context, ContextKey } from "./context"
 export { contextKey, contextValue } from "./context"
 
+// Actions
+export type { ActionDefinition } from "./action"
+export { UnknownActionError } from "./action"
+
 // Feed
 export type { FeedItem } from "./feed"
 

packages/aris-data-source-tfl/src/data-source.ts

@@ -1,115 +0,0 @@
-import type { Context, DataSource } from "@aris/core"
-
-import type {
-	StationLocation,
-	TflAlertData,
-	TflAlertFeedItem,
-	TflAlertSeverity,
-	TflDataSourceConfig,
-	TflDataSourceOptions,
-	TflLineId,
-} from "./types.ts"
-
-import { TflApi, type ITflApi } from "./tfl-api.ts"
-
-const SEVERITY_PRIORITY: Record<TflAlertSeverity, number> = {
-	closure: 100,
-	"major-delays": 80,
-	"minor-delays": 60,
-}
-
-function haversineDistance(lat1: number, lng1: number, lat2: number, lng2: number): number {
-	const R = 6371 // Earth's radius in km
-	const dLat = ((lat2 - lat1) * Math.PI) / 180
-	const dLng = ((lng2 - lng1) * Math.PI) / 180
-	const a =
-		Math.sin(dLat / 2) * Math.sin(dLat / 2) +
-		Math.cos((lat1 * Math.PI) / 180) *
-			Math.cos((lat2 * Math.PI) / 180) *
-			Math.sin(dLng / 2) *
-			Math.sin(dLng / 2)
-	const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a))
-	return R * c
-}
-
-function findClosestStationDistance(
-	lineId: TflLineId,
-	stations: StationLocation[],
-	userLat: number,
-	userLng: number,
-): number | null {
-	const lineStations = stations.filter((s) => s.lines.includes(lineId))
-	if (lineStations.length === 0) return null
-
-	let minDistance = Infinity
-	for (const station of lineStations) {
-		const distance = haversineDistance(userLat, userLng, station.lat, station.lng)
-		if (distance < minDistance) {
-			minDistance = distance
-		}
-	}
-
-	return minDistance
-}
-
-export class TflDataSource implements DataSource<TflAlertFeedItem, TflDataSourceConfig> {
-	readonly type = "tfl-alert"
-	private api: ITflApi
-
-	constructor(options: TflDataSourceOptions)
-	constructor(api: ITflApi)
-	constructor(optionsOrApi: TflDataSourceOptions | ITflApi) {
-		if ("fetchLineStatuses" in optionsOrApi) {
-			this.api = optionsOrApi
-		} else {
-			this.api = new TflApi(optionsOrApi.apiKey)
-		}
-	}
-
-	async query(context: Context, config: TflDataSourceConfig): Promise<TflAlertFeedItem[]> {
-		const [statuses, stations] = await Promise.all([
-			this.api.fetchLineStatuses(config.lines),
-			this.api.fetchStations(),
-		])
-
-		const items: TflAlertFeedItem[] = statuses.map((status) => {
-			const closestStationDistance = context.location
-				? findClosestStationDistance(
-						status.lineId,
-						stations,
-						context.location.lat,
-						context.location.lng,
-					)
-				: null
-
-			const data: TflAlertData = {
-				line: status.lineId,
-				lineName: status.lineName,
-				severity: status.severity,
-				description: status.description,
-				closestStationDistance,
-			}
-
-			return {
-				id: `tfl-alert-${status.lineId}-${status.severity}`,
-				type: this.type,
-				priority: SEVERITY_PRIORITY[status.severity],
-				timestamp: context.time,
-				data,
-			}
-		})
-
-		// Sort by severity (desc), then by proximity (asc) if location available
-		items.sort((a, b) => {
-			if (b.priority !== a.priority) {
-				return b.priority - a.priority
-			}
-			if (a.data.closestStationDistance !== null && b.data.closestStationDistance !== null) {
-				return a.data.closestStationDistance - b.data.closestStationDistance
-			}
-			return 0
-		})
-
-		return items
-	}
-}

packages/aris-data-source-tfl/src/index.ts

@@ -1,11 +0,0 @@
-export { TflDataSource } from "./data-source.ts"
-export { TflApi, type ITflApi, type TflLineStatus } from "./tfl-api.ts"
-export type {
-	TflAlertData,
-	TflAlertFeedItem,
-	TflAlertSeverity,
-	TflDataSourceConfig,
-	TflDataSourceOptions,
-	TflLineId,
-	StationLocation,
-} from "./types.ts"

packages/aris-data-source-tfl/src/integration.test.ts

@@ -1,208 +0,0 @@
-import type { Context } from "@aris/core"
-
-import { describe, expect, test } from "bun:test"
-
-import type { ITflApi, TflLineStatus } from "./tfl-api.ts"
-import type { StationLocation, TflLineId } from "./types.ts"
-
-import fixtures from "../fixtures/tfl-responses.json"
-import { TflDataSource } from "./data-source.ts"
-
-// Mock API that returns fixture data
-class FixtureTflApi implements ITflApi {
-	async fetchLineStatuses(_lines?: TflLineId[]): Promise<TflLineStatus[]> {
-		const statuses: TflLineStatus[] = []
-
-		for (const line of fixtures.lineStatuses as Record<string, unknown>[]) {
-			for (const status of line.lineStatuses as Record<string, unknown>[]) {
-				const severityCode = status.statusSeverity as number
-				const severity = this.mapSeverity(severityCode)
-				if (severity) {
-					statuses.push({
-						lineId: line.id as TflLineId,
-						lineName: line.name as string,
-						severity,
-						description: (status.reason as string) ?? (status.statusSeverityDescription as string),
-					})
-				}
-			}
-		}
-
-		return statuses
-	}
-
-	async fetchStations(): Promise<StationLocation[]> {
-		const stationMap = new Map<string, StationLocation>()
-
-		for (const [lineId, stops] of Object.entries(fixtures.stopPoints)) {
-			for (const stop of stops as Record<string, unknown>[]) {
-				const id = stop.naptanId as string
-				const existing = stationMap.get(id)
-				if (existing) {
-					if (!existing.lines.includes(lineId as TflLineId)) {
-						existing.lines.push(lineId as TflLineId)
-					}
-				} else {
-					stationMap.set(id, {
-						id,
-						name: stop.commonName as string,
-						lat: stop.lat as number,
-						lng: stop.lon as number,
-						lines: [lineId as TflLineId],
-					})
-				}
-			}
-		}
-
-		return Array.from(stationMap.values())
-	}
-
-	private mapSeverity(code: number): "minor-delays" | "major-delays" | "closure" | null {
-		const map: Record<number, "minor-delays" | "major-delays" | "closure" | null> = {
-			1: "closure",
-			2: "closure",
-			3: "closure",
-			4: "closure",
-			5: "closure",
-			6: "major-delays",
-			7: "major-delays",
-			8: "major-delays",
-			9: "minor-delays",
-			10: null,
-		}
-		return map[code] ?? null
-	}
-}
-
-const createContext = (location?: { lat: number; lng: number }): Context => ({
-	time: new Date("2026-01-15T12:00:00Z"),
-	location: location ? { ...location, accuracy: 10 } : undefined,
-})
-
-describe("TfL Feed Items (using fixture data)", () => {
-	const api = new FixtureTflApi()
-
-	test("query returns feed items array", async () => {
-		const dataSource = new TflDataSource(api)
-		const items = await dataSource.query(createContext(), {})
-		expect(Array.isArray(items)).toBe(true)
-	})
-
-	test("feed items have correct base structure", async () => {
-		const dataSource = new TflDataSource(api)
-		const items = await dataSource.query(createContext({ lat: 51.5074, lng: -0.1278 }), {})
-
-		for (const item of items) {
-			expect(typeof item.id).toBe("string")
-			expect(item.id).toMatch(/^tfl-alert-/)
-			expect(item.type).toBe("tfl-alert")
-			expect(typeof item.priority).toBe("number")
-			expect(item.timestamp).toBeInstanceOf(Date)
-		}
-	})
-
-	test("feed items have correct data structure", async () => {
-		const dataSource = new TflDataSource(api)
-		const items = await dataSource.query(createContext({ lat: 51.5074, lng: -0.1278 }), {})
-
-		for (const item of items) {
-			expect(typeof item.data.line).toBe("string")
-			expect(typeof item.data.lineName).toBe("string")
-			expect(["minor-delays", "major-delays", "closure"]).toContain(item.data.severity)
-			expect(typeof item.data.description).toBe("string")
-			expect(
-				item.data.closestStationDistance === null ||
-					typeof item.data.closestStationDistance === "number",
-			).toBe(true)
-		}
-	})
-
-	test("feed item ids are unique", async () => {
-		const dataSource = new TflDataSource(api)
-		const items = await dataSource.query(createContext(), {})
-
-		const ids = items.map((item) => item.id)
-		const uniqueIds = new Set(ids)
-		expect(uniqueIds.size).toBe(ids.length)
-	})
-
-	test("feed items are sorted by priority descending", async () => {
-		const dataSource = new TflDataSource(api)
-		const items = await dataSource.query(createContext(), {})
-
-		for (let i = 1; i < items.length; i++) {
-			const prev = items[i - 1]!
-			const curr = items[i]!
-			expect(prev.priority).toBeGreaterThanOrEqual(curr.priority)
-		}
-	})
-
-	test("priority values match severity levels", async () => {
-		const dataSource = new TflDataSource(api)
-		const items = await dataSource.query(createContext(), {})
-
-		const severityPriority: Record<string, number> = {
-			closure: 100,
-			"major-delays": 80,
-			"minor-delays": 60,
-		}
-
-		for (const item of items) {
-			expect(item.priority).toBe(severityPriority[item.data.severity]!)
-		}
-	})
-
-	test("closestStationDistance is number when location provided", async () => {
-		const dataSource = new TflDataSource(api)
-		const items = await dataSource.query(createContext({ lat: 51.5074, lng: -0.1278 }), {})
-
-		for (const item of items) {
-			expect(typeof item.data.closestStationDistance).toBe("number")
-			expect(item.data.closestStationDistance!).toBeGreaterThan(0)
-		}
-	})
-
-	test("closestStationDistance is null when no location provided", async () => {
-		const dataSource = new TflDataSource(api)
-		const items = await dataSource.query(createContext(), {})
-
-		for (const item of items) {
-			expect(item.data.closestStationDistance).toBeNull()
-		}
-	})
-})
-
-describe("TfL Fixture Data Shape", () => {
-	test("fixtures have expected structure", () => {
-		expect(typeof fixtures.fetchedAt).toBe("string")
-		expect(Array.isArray(fixtures.lineStatuses)).toBe(true)
-		expect(typeof fixtures.stopPoints).toBe("object")
-	})
-
-	test("line statuses have required fields", () => {
-		for (const line of fixtures.lineStatuses as Record<string, unknown>[]) {
-			expect(typeof line.id).toBe("string")
-			expect(typeof line.name).toBe("string")
-			expect(Array.isArray(line.lineStatuses)).toBe(true)
-
-			for (const status of line.lineStatuses as Record<string, unknown>[]) {
-				expect(typeof status.statusSeverity).toBe("number")
-				expect(typeof status.statusSeverityDescription).toBe("string")
-			}
-		}
-	})
-
-	test("stop points have required fields", () => {
-		for (const [lineId, stops] of Object.entries(fixtures.stopPoints)) {
-			expect(typeof lineId).toBe("string")
-			expect(Array.isArray(stops)).toBe(true)
-
-			for (const stop of stops as Record<string, unknown>[]) {
-				expect(typeof stop.naptanId).toBe("string")
-				expect(typeof stop.commonName).toBe("string")
-				expect(typeof stop.lat).toBe("number")
-				expect(typeof stop.lon).toBe("number")
-			}
-		}
-	})
-})

packages/aris-data-source-tfl/src/types.ts

@@ -1,33 +0,0 @@
-import type { FeedItem } from "@aris/core"
-
-import type { TflLineId } from "./tfl-api.ts"
-
-export type { TflLineId } from "./tfl-api.ts"
-
-export type TflAlertSeverity = "minor-delays" | "major-delays" | "closure"
-
-export interface TflAlertData extends Record<string, unknown> {
-	line: TflLineId
-	lineName: string
-	severity: TflAlertSeverity
-	description: string
-	closestStationDistance: number | null
-}
-
-export type TflAlertFeedItem = FeedItem<"tfl-alert", TflAlertData>
-
-export interface TflDataSourceConfig {
-	lines?: TflLineId[]
-}
-
-export interface TflDataSourceOptions {
-	apiKey: string
-}
-
-export interface StationLocation {
-	id: string
-	name: string
-	lat: number
-	lng: number
-	lines: TflLineId[]
-}

packages/aris-data-source-weatherkit/src/data-source.test.ts

@@ -26,14 +26,18 @@ const createMockContext = (location?: { lat: number; lng: number }): Context =>
 
 describe("WeatherKitDataSource", () => {
 	test("returns empty array when location is missing", async () => {
-		const dataSource = new WeatherKitDataSource({ credentials: mockCredentials })
+		const dataSource = new WeatherKitDataSource({
+			credentials: mockCredentials,
+		})
 		const items = await dataSource.query(createMockContext())
 
 		expect(items).toEqual([])
 	})
 
 	test("type is weather-current", () => {
-		const dataSource = new WeatherKitDataSource({ credentials: mockCredentials })
+		const dataSource = new WeatherKitDataSource({
+			credentials: mockCredentials,
+		})
 
 		expect(dataSource.type).toBe(WeatherFeedItemType.current)
 	})
@@ -100,7 +104,9 @@ describe("WeatherKitDataSource with fixture", () => {
 	})
 
 	test("default limits are applied", () => {
-		const dataSource = new WeatherKitDataSource({ credentials: mockCredentials })
+		const dataSource = new WeatherKitDataSource({
+			credentials: mockCredentials,
+		})
 
 		expect(dataSource["hourlyLimit"]).toBe(12)
 		expect(dataSource["dailyLimit"]).toBe(7)
@@ -163,8 +169,12 @@ describe("query() with mocked client", () => {
 		const dataSource = new WeatherKitDataSource({ client: mockClient })
 		const context = createMockContext({ lat: 37.7749, lng: -122.4194 })
 
-		const metricItems = await dataSource.query(context, { units: Units.metric })
-		const imperialItems = await dataSource.query(context, { units: Units.imperial })
+		const metricItems = await dataSource.query(context, {
+			units: Units.metric,
+		})
+		const imperialItems = await dataSource.query(context, {
+			units: Units.imperial,
+		})
 
 		const metricCurrent = metricItems.find((i) => i.type === WeatherFeedItemType.current)
 		const imperialCurrent = imperialItems.find((i) => i.type === WeatherFeedItemType.current)

packages/aris-source-apple-calendar/fixtures/all-day-event.ics

@@ -0,0 +1,11 @@
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Test//Test//EN
+BEGIN:VEVENT
+UID:all-day-001@test
+DTSTART;VALUE=DATE:20260115
+DTEND;VALUE=DATE:20260116
+SUMMARY:Company Holiday
+STATUS:CONFIRMED
+END:VEVENT
+END:VCALENDAR

packages/aris-source-apple-calendar/fixtures/cancelled-event.ics

@@ -0,0 +1,11 @@
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Test//Test//EN
+BEGIN:VEVENT
+UID:cancelled-001@test
+DTSTART:20260115T120000Z
+DTEND:20260115T130000Z
+SUMMARY:Cancelled Meeting
+STATUS:CANCELLED
+END:VEVENT
+END:VCALENDAR

packages/aris-source-apple-calendar/fixtures/minimal-event.ics

@@ -0,0 +1,10 @@
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Test//Test//EN
+BEGIN:VEVENT
+UID:minimal-001@test
+DTSTART:20260115T180000Z
+DTEND:20260115T190000Z
+SUMMARY:Quick Chat
+END:VEVENT
+END:VCALENDAR

packages/aris-source-apple-calendar/fixtures/recurring-event.ics

@@ -0,0 +1,20 @@
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Test//Test//EN
+BEGIN:VEVENT
+UID:recurring-001@test
+DTSTART:20260115T090000Z
+DTEND:20260115T093000Z
+SUMMARY:Weekly Sync
+RRULE:FREQ=WEEKLY;COUNT=4
+STATUS:CONFIRMED
+END:VEVENT
+BEGIN:VEVENT
+UID:recurring-001@test
+RECURRENCE-ID:20260122T090000Z
+DTSTART:20260122T100000Z
+DTEND:20260122T103000Z
+SUMMARY:Weekly Sync (moved)
+STATUS:CONFIRMED
+END:VEVENT
+END:VCALENDAR

packages/aris-source-apple-calendar/fixtures/single-event.ics

@@ -0,0 +1,26 @@
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Test//Test//EN
+BEGIN:VEVENT
+UID:single-event-001@test
+DTSTART:20260115T140000Z
+DTEND:20260115T150000Z
+SUMMARY:Team Standup
+LOCATION:Conference Room A
+DESCRIPTION:Daily standup meeting
+STATUS:CONFIRMED
+URL:https://example.com/meeting/123
+ORGANIZER;CN=Alice Smith:mailto:alice@example.com
+ATTENDEE;CN=Bob Jones;ROLE=REQ-PARTICIPANT;PARTSTAT=ACCEPTED:mailto:bob@example.com
+ATTENDEE;CN=Carol White;ROLE=OPT-PARTICIPANT;PARTSTAT=TENTATIVE:mailto:carol@example.com
+BEGIN:VALARM
+TRIGGER:-PT15M
+ACTION:DISPLAY
+DESCRIPTION:Reminder
+END:VALARM
+BEGIN:VALARM
+TRIGGER:-PT5M
+ACTION:AUDIO
+END:VALARM
+END:VEVENT
+END:VCALENDAR

packages/aris-source-apple-calendar/package.json

@@ -0,0 +1,15 @@
+{
+	"name": "@aris/source-apple-calendar",
+	"version": "0.0.0",
+	"type": "module",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"scripts": {
+		"test": "bun test ."
+	},
+	"dependencies": {
+		"@aris/core": "workspace:*",
+		"ical.js": "^2.1.0",
+		"tsdav": "^2.1.7"
+	}
+}

packages/aris-source-apple-calendar/src/calendar-context.ts

@@ -0,0 +1,24 @@
+import type { ContextKey } from "@aris/core"
+
+import { contextKey } from "@aris/core"
+
+import type { CalendarEventData } from "./types.ts"
+
+/**
+ * Calendar context for downstream sources.
+ *
+ * Provides a snapshot of the user's upcoming events so other sources
+ * can adapt (e.g. a commute source checking if there's a meeting soon).
+ */
+export interface CalendarContext {
+	/** Events happening right now */
+	inProgress: CalendarEventData[]
+	/** Next upcoming event, if any */
+	nextEvent: CalendarEventData | null
+	/** Whether the user has any events today */
+	hasTodayEvents: boolean
+	/** Total number of events today */
+	todayEventCount: number
+}
+
+export const CalendarKey: ContextKey<CalendarContext> = contextKey("calendar")

packages/aris-source-apple-calendar/src/calendar-source.test.ts

@@ -0,0 +1,473 @@
+import type { Context } from "@aris/core"
+
+import { contextValue } from "@aris/core"
+import { describe, expect, test } from "bun:test"
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import type {
+	CalendarCredentialProvider,
+	CalendarCredentials,
+	CalendarDAVCalendar,
+	CalendarDAVClient,
+	CalendarDAVObject,
+	CalendarEventData,
+} from "./types.ts"
+
+import { CalendarKey } from "./calendar-context.ts"
+import { CalendarSource, computePriority } from "./calendar-source.ts"
+
+function loadFixture(name: string): string {
+	return readFileSync(join(import.meta.dir, "..", "fixtures", name), "utf-8")
+}
+
+function createContext(time: Date): Context {
+	return { time }
+}
+
+const mockCredentials: CalendarCredentials = {
+	accessToken: "mock-access-token",
+	refreshToken: "mock-refresh-token",
+	expiresAt: Date.now() + 3600000,
+	tokenUrl: "https://appleid.apple.com/auth/token",
+	clientId: "com.example.aris",
+	clientSecret: "mock-secret",
+}
+
+class NullCredentialProvider implements CalendarCredentialProvider {
+	async fetchCredentials(_userId: string): Promise<CalendarCredentials | null> {
+		return null
+	}
+}
+
+class MockCredentialProvider implements CalendarCredentialProvider {
+	async fetchCredentials(_userId: string): Promise<CalendarCredentials | null> {
+		return mockCredentials
+	}
+}
+
+class MockDAVClient implements CalendarDAVClient {
+	credentials: Record<string, unknown> = {}
+	fetchCalendarsCallCount = 0
+	private calendars: CalendarDAVCalendar[]
+	private objectsByCalendarUrl: Record<string, CalendarDAVObject[]>
+
+	constructor(
+		calendars: CalendarDAVCalendar[],
+		objectsByCalendarUrl: Record<string, CalendarDAVObject[]>,
+	) {
+		this.calendars = calendars
+		this.objectsByCalendarUrl = objectsByCalendarUrl
+	}
+
+	async login(): Promise<void> {}
+
+	async fetchCalendars(): Promise<CalendarDAVCalendar[]> {
+		this.fetchCalendarsCallCount++
+		return this.calendars
+	}
+
+	async fetchCalendarObjects(params: {
+		calendar: CalendarDAVCalendar
+		timeRange: { start: string; end: string }
+	}): Promise<CalendarDAVObject[]> {
+		return this.objectsByCalendarUrl[params.calendar.url] ?? []
+	}
+}
+
+describe("CalendarSource", () => {
+	test("has correct id", () => {
+		const source = new CalendarSource(new NullCredentialProvider(), "user-1")
+		expect(source.id).toBe("aris.apple-calendar")
+	})
+
+	test("returns empty array when credentials are null", async () => {
+		const source = new CalendarSource(new NullCredentialProvider(), "user-1")
+		const items = await source.fetchItems(createContext(new Date("2026-01-15T12:00:00Z")))
+		expect(items).toEqual([])
+	})
+
+	test("returns empty array when no calendars exist", async () => {
+		const client = new MockDAVClient([], {})
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+		const items = await source.fetchItems(createContext(new Date("2026-01-15T12:00:00Z")))
+		expect(items).toEqual([])
+	})
+
+	test("returns feed items from a single calendar", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		const items = await source.fetchItems(createContext(new Date("2026-01-15T12:00:00Z")))
+
+		expect(items).toHaveLength(1)
+		expect(items[0]!.type).toBe("calendar-event")
+		expect(items[0]!.id).toBe("calendar-event-single-event-001@test")
+		expect(items[0]!.data.title).toBe("Team Standup")
+		expect(items[0]!.data.location).toBe("Conference Room A")
+		expect(items[0]!.data.calendarName).toBe("Work")
+		expect(items[0]!.data.attendees).toHaveLength(2)
+		expect(items[0]!.data.alarms).toHaveLength(2)
+	})
+
+	test("returns feed items from multiple calendars", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }],
+			"/cal/personal": [
+				{
+					url: "/cal/personal/event2.ics",
+					data: loadFixture("all-day-event.ics"),
+				},
+			],
+		}
+		const client = new MockDAVClient(
+			[
+				{ url: "/cal/work", displayName: "Work" },
+				{ url: "/cal/personal", displayName: "Personal" },
+			],
+			objects,
+		)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		const items = await source.fetchItems(createContext(new Date("2026-01-15T12:00:00Z")))
+
+		expect(items).toHaveLength(2)
+
+		const standup = items.find((i) => i.data.title === "Team Standup")
+		const holiday = items.find((i) => i.data.title === "Company Holiday")
+
+		expect(standup).toBeDefined()
+		expect(standup!.data.calendarName).toBe("Work")
+
+		expect(holiday).toBeDefined()
+		expect(holiday!.data.calendarName).toBe("Personal")
+		expect(holiday!.data.isAllDay).toBe(true)
+	})
+
+	test("skips objects with non-string data", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [
+				{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") },
+				{ url: "/cal/work/bad.ics", data: 12345 },
+				{ url: "/cal/work/empty.ics" },
+			],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		const items = await source.fetchItems(createContext(new Date("2026-01-15T12:00:00Z")))
+		expect(items).toHaveLength(1)
+		expect(items[0]!.data.title).toBe("Team Standup")
+	})
+
+	test("uses context time as feed item timestamp", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		const now = new Date("2026-01-15T12:00:00Z")
+		const items = await source.fetchItems(createContext(now))
+		expect(items[0]!.timestamp).toEqual(now)
+	})
+
+	test("assigns priority based on event proximity", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [
+				{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") },
+				{ url: "/cal/work/allday.ics", data: loadFixture("all-day-event.ics") },
+			],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		// 2 hours before the event at 14:00
+		const items = await source.fetchItems(createContext(new Date("2026-01-15T12:00:00Z")))
+
+		const standup = items.find((i) => i.data.title === "Team Standup")
+		const holiday = items.find((i) => i.data.title === "Company Holiday")
+
+		expect(standup!.priority).toBe(0.7) // within 2 hours
+		expect(holiday!.priority).toBe(0.3) // all-day
+	})
+
+	test("handles calendar with non-string displayName", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/weird": [
+				{
+					url: "/cal/weird/event1.ics",
+					data: loadFixture("minimal-event.ics"),
+				},
+			],
+		}
+		const client = new MockDAVClient(
+			[{ url: "/cal/weird", displayName: { _cdata: "Weird Calendar" } }],
+			objects,
+		)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		const items = await source.fetchItems(createContext(new Date("2026-01-15T12:00:00Z")))
+		expect(items[0]!.data.calendarName).toBeNull()
+	})
+
+	test("handles recurring events with exceptions", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [
+				{
+					url: "/cal/work/recurring.ics",
+					data: loadFixture("recurring-event.ics"),
+				},
+			],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		const items = await source.fetchItems(createContext(new Date("2026-01-15T08:00:00Z")))
+
+		expect(items).toHaveLength(2)
+
+		const base = items.find((i) => i.data.title === "Weekly Sync")
+		const exception = items.find((i) => i.data.title === "Weekly Sync (moved)")
+
+		expect(base).toBeDefined()
+		expect(base!.data.recurrenceId).toBeNull()
+
+		expect(exception).toBeDefined()
+		expect(exception!.data.recurrenceId).not.toBeNull()
+		expect(exception!.id).toContain("-")
+	})
+
+	test("caches events within the same refresh cycle", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		const context = createContext(new Date("2026-01-15T12:00:00Z"))
+
+		await source.fetchContext(context)
+		await source.fetchItems(context)
+
+		// Same context.time reference — fetchEvents should only hit the client once
+		expect(client.fetchCalendarsCallCount).toBe(1)
+	})
+
+	test("refetches events for a different context time", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		await source.fetchItems(createContext(new Date("2026-01-15T12:00:00Z")))
+		await source.fetchItems(createContext(new Date("2026-01-15T13:00:00Z")))
+
+		// Different context.time references — should fetch twice
+		expect(client.fetchCalendarsCallCount).toBe(2)
+	})
+})
+
+describe("CalendarSource.fetchContext", () => {
+	test("returns empty context when credentials are null", async () => {
+		const source = new CalendarSource(new NullCredentialProvider(), "user-1")
+		const ctx = await source.fetchContext(createContext(new Date("2026-01-15T12:00:00Z")))
+		const calendar = contextValue(ctx as Context, CalendarKey)
+
+		expect(calendar).toBeDefined()
+		expect(calendar!.inProgress).toEqual([])
+		expect(calendar!.nextEvent).toBeNull()
+		expect(calendar!.hasTodayEvents).toBe(false)
+		expect(calendar!.todayEventCount).toBe(0)
+	})
+
+	test("identifies in-progress events", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		// 14:30 is during the 14:00-15:00 event
+		const ctx = await source.fetchContext(createContext(new Date("2026-01-15T14:30:00Z")))
+		const calendar = contextValue(ctx as Context, CalendarKey)
+
+		expect(calendar!.inProgress).toHaveLength(1)
+		expect(calendar!.inProgress[0]!.title).toBe("Team Standup")
+	})
+
+	test("identifies next upcoming event", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") }],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		// 12:00 is before the 14:00 event
+		const ctx = await source.fetchContext(createContext(new Date("2026-01-15T12:00:00Z")))
+		const calendar = contextValue(ctx as Context, CalendarKey)
+
+		expect(calendar!.inProgress).toHaveLength(0)
+		expect(calendar!.nextEvent).not.toBeNull()
+		expect(calendar!.nextEvent!.title).toBe("Team Standup")
+	})
+
+	test("excludes all-day events from inProgress and nextEvent", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [{ url: "/cal/work/allday.ics", data: loadFixture("all-day-event.ics") }],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		const ctx = await source.fetchContext(createContext(new Date("2026-01-15T12:00:00Z")))
+		const calendar = contextValue(ctx as Context, CalendarKey)
+
+		expect(calendar!.inProgress).toHaveLength(0)
+		expect(calendar!.nextEvent).toBeNull()
+		expect(calendar!.hasTodayEvents).toBe(true)
+		expect(calendar!.todayEventCount).toBe(1)
+	})
+
+	test("counts all events including all-day in todayEventCount", async () => {
+		const objects: Record<string, CalendarDAVObject[]> = {
+			"/cal/work": [
+				{ url: "/cal/work/event1.ics", data: loadFixture("single-event.ics") },
+				{ url: "/cal/work/allday.ics", data: loadFixture("all-day-event.ics") },
+			],
+		}
+		const client = new MockDAVClient([{ url: "/cal/work", displayName: "Work" }], objects)
+		const source = new CalendarSource(new MockCredentialProvider(), "user-1", {
+			davClient: client,
+		})
+
+		const ctx = await source.fetchContext(createContext(new Date("2026-01-15T12:00:00Z")))
+		const calendar = contextValue(ctx as Context, CalendarKey)
+
+		expect(calendar!.todayEventCount).toBe(2)
+		expect(calendar!.hasTodayEvents).toBe(true)
+	})
+})
+
+describe("computePriority", () => {
+	const now = new Date("2026-01-15T12:00:00Z")
+
+	function makeEvent(overrides: Partial<CalendarEventData>): CalendarEventData {
+		return {
+			uid: "test-uid",
+			title: "Test",
+			startDate: new Date("2026-01-15T14:00:00Z"),
+			endDate: new Date("2026-01-15T15:00:00Z"),
+			isAllDay: false,
+			location: null,
+			description: null,
+			calendarName: null,
+			status: null,
+			url: null,
+			organizer: null,
+			attendees: [],
+			alarms: [],
+			recurrenceId: null,
+			...overrides,
+		}
+	}
+
+	test("all-day events get priority 0.3", () => {
+		const event = makeEvent({ isAllDay: true })
+		expect(computePriority(event, now)).toBe(0.3)
+	})
+
+	test("events starting within 30 minutes get priority 0.9", () => {
+		const event = makeEvent({
+			startDate: new Date("2026-01-15T12:20:00Z"),
+		})
+		expect(computePriority(event, now)).toBe(0.9)
+	})
+
+	test("events starting exactly at 30 minutes get priority 0.9", () => {
+		const event = makeEvent({
+			startDate: new Date("2026-01-15T12:30:00Z"),
+		})
+		expect(computePriority(event, now)).toBe(0.9)
+	})
+
+	test("events starting within 2 hours get priority 0.7", () => {
+		const event = makeEvent({
+			startDate: new Date("2026-01-15T13:00:00Z"),
+		})
+		expect(computePriority(event, now)).toBe(0.7)
+	})
+
+	test("events later today get priority 0.5", () => {
+		const event = makeEvent({
+			startDate: new Date("2026-01-15T20:00:00Z"),
+		})
+		expect(computePriority(event, now)).toBe(0.5)
+	})
+
+	test("in-progress events get priority 0.8", () => {
+		const event = makeEvent({
+			startDate: new Date("2026-01-15T11:00:00Z"),
+			endDate: new Date("2026-01-15T13:00:00Z"),
+		})
+		expect(computePriority(event, now)).toBe(0.8)
+	})
+
+	test("fully past events get priority 0.2", () => {
+		const event = makeEvent({
+			startDate: new Date("2026-01-15T09:00:00Z"),
+			endDate: new Date("2026-01-15T10:00:00Z"),
+		})
+		expect(computePriority(event, now)).toBe(0.2)
+	})
+
+	test("events on future days get priority 0.2", () => {
+		const event = makeEvent({
+			startDate: new Date("2026-01-16T10:00:00Z"),
+		})
+		expect(computePriority(event, now)).toBe(0.2)
+	})
+
+	test("priority boundaries are correct", () => {
+		// 31 minutes from now should be 0.7 (within 2 hours, not within 30 min)
+		const event31min = makeEvent({
+			startDate: new Date("2026-01-15T12:31:00Z"),
+		})
+		expect(computePriority(event31min, now)).toBe(0.7)
+
+		// 2 hours 1 minute from now should be 0.5 (later today, not within 2 hours)
+		const event2h1m = makeEvent({
+			startDate: new Date("2026-01-15T14:01:00Z"),
+		})
+		expect(computePriority(event2h1m, now)).toBe(0.5)
+	})
+})

packages/aris-source-apple-calendar/src/calendar-source.ts

@@ -0,0 +1,251 @@
+import type { ActionDefinition, Context, FeedSource } from "@aris/core"
+import { UnknownActionError } from "@aris/core"
+
+import { DAVClient } from "tsdav"
+
+import type {
+	CalendarCredentialProvider,
+	CalendarCredentials,
+	CalendarDAVClient,
+	CalendarEventData,
+	CalendarFeedItem,
+} from "./types.ts"
+
+export interface CalendarSourceOptions {
+	/** Number of additional days beyond today to fetch. Default: 0 (today only). */
+	lookAheadDays?: number
+	/** Optional DAVClient instance for testing. Uses tsdav DAVClient by default. */
+	davClient?: CalendarDAVClient
+}
+
+import { CalendarKey, type CalendarContext } from "./calendar-context.ts"
+import { parseICalEvents } from "./ical-parser.ts"
+
+const ICLOUD_CALDAV_URL = "https://caldav.icloud.com"
+const DEFAULT_LOOK_AHEAD_DAYS = 0
+
+/**
+ * A FeedSource that fetches Apple Calendar events via CalDAV.
+ *
+ * Credentials are provided by an injected CalendarCredentialProvider.
+ * The server is responsible for managing OAuth tokens and storage.
+ *
+ * @example
+ * ```ts
+ * const source = new CalendarSource(credentialProvider, "user-123")
+ * const engine = new FeedEngine()
+ * engine.register(source)
+ * ```
+ */
+export class CalendarSource implements FeedSource<CalendarFeedItem> {
+	readonly id = "aris.apple-calendar"
+
+	private readonly credentialProvider: CalendarCredentialProvider
+	private readonly userId: string
+	private readonly lookAheadDays: number
+	private readonly injectedClient: CalendarDAVClient | null
+	private davClient: CalendarDAVClient | null = null
+	private lastAccessToken: string | null = null
+	private cachedEvents: { time: Date; events: CalendarEventData[] } | null = null
+
+	constructor(
+		credentialProvider: CalendarCredentialProvider,
+		userId: string,
+		options?: CalendarSourceOptions,
+	) {
+		this.credentialProvider = credentialProvider
+		this.userId = userId
+		this.lookAheadDays = options?.lookAheadDays ?? DEFAULT_LOOK_AHEAD_DAYS
+		this.injectedClient = options?.davClient ?? null
+	}
+
+	async listActions(): Promise<Record<string, ActionDefinition>> {
+		return {}
+	}
+
+	async executeAction(actionId: string): Promise<void> {
+		throw new UnknownActionError(actionId)
+	}
+
+	async fetchContext(context: Context): Promise<Partial<Context> | null> {
+		const events = await this.fetchEvents(context)
+		if (events.length === 0) {
+			return {
+				[CalendarKey]: {
+					inProgress: [],
+					nextEvent: null,
+					hasTodayEvents: false,
+					todayEventCount: 0,
+				},
+			}
+		}
+
+		const now = context.time
+		const inProgress = events.filter((e) => !e.isAllDay && e.startDate <= now && e.endDate > now)
+
+		const upcoming = events
+			.filter((e) => !e.isAllDay && e.startDate > now)
+			.sort((a, b) => a.startDate.getTime() - b.startDate.getTime())
+
+		const calendarContext: CalendarContext = {
+			inProgress,
+			nextEvent: upcoming[0] ?? null,
+			hasTodayEvents: events.length > 0,
+			todayEventCount: events.length,
+		}
+
+		return { [CalendarKey]: calendarContext }
+	}
+
+	async fetchItems(context: Context): Promise<CalendarFeedItem[]> {
+		const now = context.time
+		const events = await this.fetchEvents(context)
+		return events.map((event) => createFeedItem(event, now))
+	}
+
+	private async fetchEvents(context: Context): Promise<CalendarEventData[]> {
+		if (this.cachedEvents && this.cachedEvents.time === context.time) {
+			return this.cachedEvents.events
+		}
+
+		const credentials = await this.credentialProvider.fetchCredentials(this.userId)
+		if (!credentials) {
+			return []
+		}
+
+		const client = await this.connectClient(credentials)
+		const calendars = await client.fetchCalendars()
+
+		const { start, end } = computeTimeRange(context.time, this.lookAheadDays)
+
+		const results = await Promise.allSettled(
+			calendars.map(async (calendar) => {
+				const objects = await client.fetchCalendarObjects({
+					calendar,
+					timeRange: {
+						start: start.toISOString(),
+						end: end.toISOString(),
+					},
+				})
+				// tsdav types displayName as string | Record<string, unknown> | undefined
+				// because the XML parser can return an object for some responses
+				const calendarName = typeof calendar.displayName === "string" ? calendar.displayName : null
+				return { objects, calendarName }
+			}),
+		)
+
+		const allEvents: CalendarEventData[] = []
+		for (const result of results) {
+			if (result.status !== "fulfilled") continue
+			const { objects, calendarName } = result.value
+			for (const obj of objects) {
+				if (typeof obj.data !== "string") continue
+
+				const events = parseICalEvents(obj.data, calendarName)
+				for (const event of events) {
+					allEvents.push(event)
+				}
+			}
+		}
+
+		this.cachedEvents = { time: context.time, events: allEvents }
+		return allEvents
+	}
+
+	/**
+	 * Returns a ready-to-use DAVClient. Creates and logs in a new client
+	 * on first call; reuses the existing one on subsequent calls, updating
+	 * credentials if the access token has changed.
+	 */
+	private async connectClient(credentials: CalendarCredentials): Promise<CalendarDAVClient> {
+		if (this.injectedClient) {
+			return this.injectedClient
+		}
+
+		const davCredentials = {
+			tokenUrl: credentials.tokenUrl,
+			refreshToken: credentials.refreshToken,
+			accessToken: credentials.accessToken,
+			expiration: credentials.expiresAt,
+			clientId: credentials.clientId,
+			clientSecret: credentials.clientSecret,
+		}
+
+		if (!this.davClient) {
+			this.davClient = new DAVClient({
+				serverUrl: ICLOUD_CALDAV_URL,
+				credentials: davCredentials,
+				authMethod: "Oauth",
+				defaultAccountType: "caldav",
+			})
+			await this.davClient.login()
+			this.lastAccessToken = credentials.accessToken
+			return this.davClient
+		}
+
+		if (credentials.accessToken !== this.lastAccessToken) {
+			this.davClient.credentials = davCredentials
+			this.lastAccessToken = credentials.accessToken
+		}
+
+		return this.davClient
+	}
+}
+
+function computeTimeRange(now: Date, lookAheadDays: number): { start: Date; end: Date } {
+	const start = new Date(now)
+	start.setUTCHours(0, 0, 0, 0)
+
+	const end = new Date(start)
+	end.setUTCDate(end.getUTCDate() + 1 + lookAheadDays)
+
+	return { start, end }
+}
+
+export function computePriority(event: CalendarEventData, now: Date): number {
+	if (event.isAllDay) {
+		return 0.3
+	}
+
+	const msUntilStart = event.startDate.getTime() - now.getTime()
+
+	// Event already started
+	if (msUntilStart < 0) {
+		const isInProgress = now.getTime() < event.endDate.getTime()
+		// Currently happening events are high priority; fully past events are low
+		return isInProgress ? 0.8 : 0.2
+	}
+
+	// Starting within 30 minutes
+	if (msUntilStart <= 30 * 60 * 1000) {
+		return 0.9
+	}
+
+	// Starting within 2 hours
+	if (msUntilStart <= 2 * 60 * 60 * 1000) {
+		return 0.7
+	}
+
+	// Later today (within 24 hours from start of day)
+	const startOfDay = new Date(now)
+	startOfDay.setUTCHours(0, 0, 0, 0)
+	const endOfDay = new Date(startOfDay)
+	endOfDay.setUTCDate(endOfDay.getUTCDate() + 1)
+
+	if (event.startDate.getTime() < endOfDay.getTime()) {
+		return 0.5
+	}
+
+	// Future days
+	return 0.2
+}
+
+function createFeedItem(event: CalendarEventData, now: Date): CalendarFeedItem {
+	return {
+		id: `calendar-event-${event.uid}${event.recurrenceId ? `-${event.recurrenceId}` : ""}`,
+		type: "calendar-event",
+		priority: computePriority(event, now),
+		timestamp: now,
+		data: event,
+	}
+}

packages/aris-source-apple-calendar/src/ical-parser.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, test } from "bun:test"
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { parseICalEvents } from "./ical-parser.ts"
+
+function loadFixture(name: string): string {
+	return readFileSync(join(import.meta.dir, "..", "fixtures", name), "utf-8")
+}
+
+describe("parseICalEvents", () => {
+	test("parses a full event with all fields", () => {
+		const events = parseICalEvents(loadFixture("single-event.ics"), "Work")
+
+		expect(events).toHaveLength(1)
+		const event = events[0]!
+
+		expect(event.uid).toBe("single-event-001@test")
+		expect(event.title).toBe("Team Standup")
+		expect(event.startDate).toEqual(new Date("2026-01-15T14:00:00Z"))
+		expect(event.endDate).toEqual(new Date("2026-01-15T15:00:00Z"))
+		expect(event.isAllDay).toBe(false)
+		expect(event.location).toBe("Conference Room A")
+		expect(event.description).toBe("Daily standup meeting")
+		expect(event.calendarName).toBe("Work")
+		expect(event.status).toBe("confirmed")
+		expect(event.url).toBe("https://example.com/meeting/123")
+		expect(event.organizer).toBe("Alice Smith")
+		expect(event.recurrenceId).toBeNull()
+
+		expect(event.attendees).toHaveLength(2)
+		expect(event.attendees[0]).toEqual({
+			name: "Bob Jones",
+			email: "bob@example.com",
+			role: "required",
+			status: "accepted",
+		})
+		expect(event.attendees[1]).toEqual({
+			name: "Carol White",
+			email: "carol@example.com",
+			role: "optional",
+			status: "tentative",
+		})
+
+		expect(event.alarms).toHaveLength(2)
+		expect(event.alarms[0]).toEqual({ trigger: "-PT15M", action: "DISPLAY" })
+		expect(event.alarms[1]).toEqual({ trigger: "-PT5M", action: "AUDIO" })
+	})
+
+	test("parses an all-day event with optional fields as null", () => {
+		const events = parseICalEvents(loadFixture("all-day-event.ics"), null)
+
+		expect(events).toHaveLength(1)
+		const event = events[0]!
+
+		expect(event.isAllDay).toBe(true)
+		expect(event.title).toBe("Company Holiday")
+		expect(event.calendarName).toBeNull()
+		expect(event.location).toBeNull()
+		expect(event.description).toBeNull()
+		expect(event.url).toBeNull()
+		expect(event.organizer).toBeNull()
+		expect(event.attendees).toEqual([])
+		expect(event.alarms).toEqual([])
+	})
+
+	test("parses recurring event with exception", () => {
+		const events = parseICalEvents(loadFixture("recurring-event.ics"), "Team")
+
+		expect(events).toHaveLength(2)
+		expect(events[0]!.uid).toBe("recurring-001@test")
+		expect(events[1]!.uid).toBe("recurring-001@test")
+
+		const base = events.find((e) => e.title === "Weekly Sync")
+		expect(base).toBeDefined()
+		expect(base!.recurrenceId).toBeNull()
+
+		const exception = events.find((e) => e.title === "Weekly Sync (moved)")
+		expect(exception).toBeDefined()
+		expect(exception!.recurrenceId).not.toBeNull()
+	})
+
+	test("parses minimal event with defaults", () => {
+		const events = parseICalEvents(loadFixture("minimal-event.ics"), null)
+
+		expect(events).toHaveLength(1)
+		const event = events[0]!
+
+		expect(event.uid).toBe("minimal-001@test")
+		expect(event.title).toBe("Quick Chat")
+		expect(event.startDate).toEqual(new Date("2026-01-15T18:00:00Z"))
+		expect(event.endDate).toEqual(new Date("2026-01-15T19:00:00Z"))
+		expect(event.location).toBeNull()
+		expect(event.description).toBeNull()
+		expect(event.status).toBeNull()
+		expect(event.url).toBeNull()
+		expect(event.organizer).toBeNull()
+		expect(event.attendees).toEqual([])
+		expect(event.alarms).toEqual([])
+		expect(event.recurrenceId).toBeNull()
+	})
+
+	test("parses cancelled status", () => {
+		const events = parseICalEvents(loadFixture("cancelled-event.ics"), null)
+		expect(events[0]!.status).toBe("cancelled")
+	})
+})

packages/aris-source-apple-calendar/src/ical-parser.ts

@@ -0,0 +1,150 @@
+import ICAL from "ical.js"
+
+import {
+	AttendeeRole,
+	AttendeeStatus,
+	CalendarEventStatus,
+	type CalendarAlarm,
+	type CalendarAttendee,
+	type CalendarEventData,
+} from "./types.ts"
+
+/**
+ * Parses a raw iCalendar string and extracts all VEVENT components
+ * into CalendarEventData objects.
+ *
+ * @param icsData - Raw iCalendar string from a CalDAV response
+ * @param calendarName - Display name of the calendar this event belongs to
+ */
+export function parseICalEvents(icsData: string, calendarName: string | null): CalendarEventData[] {
+	const jcal = ICAL.parse(icsData)
+	const comp = new ICAL.Component(jcal)
+	const vevents = comp.getAllSubcomponents("vevent")
+
+	return vevents.map((vevent: InstanceType<typeof ICAL.Component>) =>
+		parseVEvent(vevent, calendarName),
+	)
+}
+
+function parseVEvent(
+	vevent: InstanceType<typeof ICAL.Component>,
+	calendarName: string | null,
+): CalendarEventData {
+	const event = new ICAL.Event(vevent)
+
+	return {
+		uid: event.uid ?? "",
+		title: event.summary ?? "",
+		startDate: event.startDate?.toJSDate() ?? new Date(0),
+		endDate: event.endDate?.toJSDate() ?? new Date(0),
+		isAllDay: event.startDate?.isDate ?? false,
+		location: event.location ?? null,
+		description: event.description ?? null,
+		calendarName,
+		status: parseStatus(asStringOrNull(vevent.getFirstPropertyValue("status"))),
+		url: asStringOrNull(vevent.getFirstPropertyValue("url")),
+		organizer: parseOrganizer(asStringOrNull(event.organizer), vevent),
+		attendees: parseAttendees(Array.isArray(event.attendees) ? event.attendees : []),
+		alarms: parseAlarms(vevent),
+		recurrenceId: event.recurrenceId ? event.recurrenceId.toString() : null,
+	}
+}
+
+function parseStatus(raw: string | null): CalendarEventStatus | null {
+	if (!raw) return null
+	switch (raw.toLowerCase()) {
+		case "confirmed":
+			return CalendarEventStatus.Confirmed
+		case "tentative":
+			return CalendarEventStatus.Tentative
+		case "cancelled":
+			return CalendarEventStatus.Cancelled
+		default:
+			return null
+	}
+}
+
+function parseOrganizer(
+	value: string | null,
+	vevent: InstanceType<typeof ICAL.Component>,
+): string | null {
+	if (!value) return null
+
+	// Try CN parameter first
+	const prop = vevent.getFirstProperty("organizer")
+	if (prop) {
+		const cn = prop.getParameter("cn") as string | undefined
+		if (cn) return cn
+	}
+
+	// Fall back to mailto: value
+	return value.replace(/^mailto:/i, "")
+}
+
+function parseAttendees(properties: unknown[]): CalendarAttendee[] {
+	if (properties.length === 0) return []
+
+	return properties.map((prop) => {
+		const p = prop as InstanceType<typeof ICAL.Property>
+		const value = asStringOrNull(p.getFirstValue())
+		const cn = asStringOrNull(p.getParameter("cn"))
+		const role = asStringOrNull(p.getParameter("role"))
+		const partstat = asStringOrNull(p.getParameter("partstat"))
+
+		return {
+			name: cn,
+			email: value ? value.replace(/^mailto:/i, "") : null,
+			role: parseAttendeeRole(role),
+			status: parseAttendeeStatus(partstat),
+		}
+	})
+}
+
+function parseAttendeeRole(raw: string | null): AttendeeRole | null {
+	if (!raw) return null
+	switch (raw.toUpperCase()) {
+		case "CHAIR":
+			return AttendeeRole.Chair
+		case "REQ-PARTICIPANT":
+			return AttendeeRole.Required
+		case "OPT-PARTICIPANT":
+			return AttendeeRole.Optional
+		default:
+			return null
+	}
+}
+
+function parseAttendeeStatus(raw: string | null): AttendeeStatus | null {
+	if (!raw) return null
+	switch (raw.toUpperCase()) {
+		case "ACCEPTED":
+			return AttendeeStatus.Accepted
+		case "DECLINED":
+			return AttendeeStatus.Declined
+		case "TENTATIVE":
+			return AttendeeStatus.Tentative
+		case "NEEDS-ACTION":
+			return AttendeeStatus.NeedsAction
+		default:
+			return null
+	}
+}
+
+function parseAlarms(vevent: InstanceType<typeof ICAL.Component>): CalendarAlarm[] {
+	const valarms = vevent.getAllSubcomponents("valarm")
+	if (!valarms || valarms.length === 0) return []
+
+	return valarms.map((valarm: InstanceType<typeof ICAL.Component>) => {
+		const trigger = valarm.getFirstPropertyValue("trigger")
+		const action = asStringOrNull(valarm.getFirstPropertyValue("action"))
+
+		return {
+			trigger: trigger ? trigger.toString() : "",
+			action: action ?? "DISPLAY",
+		}
+	})
+}
+
+function asStringOrNull(value: unknown): string | null {
+	return typeof value === "string" ? value : null
+}

packages/aris-source-apple-calendar/src/index.ts

@@ -0,0 +1,16 @@
+export { CalendarKey, type CalendarContext } from "./calendar-context.ts"
+export { CalendarSource, type CalendarSourceOptions } from "./calendar-source.ts"
+export {
+	CalendarEventStatus,
+	AttendeeRole,
+	AttendeeStatus,
+	type CalendarCredentials,
+	type CalendarCredentialProvider,
+	type CalendarDAVClient,
+	type CalendarDAVCalendar,
+	type CalendarDAVObject,
+	type CalendarAttendee,
+	type CalendarAlarm,
+	type CalendarEventData,
+	type CalendarFeedItem,
+} from "./types.ts"

packages/aris-source-apple-calendar/src/types.ts

@@ -0,0 +1,101 @@
+import type { FeedItem } from "@aris/core"
+
+// -- Credential provider --
+
+export interface CalendarCredentials {
+	accessToken: string
+	refreshToken: string
+	/** Unix timestamp in milliseconds when the access token expires */
+	expiresAt: number
+	tokenUrl: string
+	clientId: string
+	clientSecret: string
+}
+
+export interface CalendarCredentialProvider {
+	fetchCredentials(userId: string): Promise<CalendarCredentials | null>
+}
+
+// -- Feed item types --
+
+export const CalendarEventStatus = {
+	Confirmed: "confirmed",
+	Tentative: "tentative",
+	Cancelled: "cancelled",
+} as const
+
+export type CalendarEventStatus = (typeof CalendarEventStatus)[keyof typeof CalendarEventStatus]
+
+export const AttendeeRole = {
+	Chair: "chair",
+	Required: "required",
+	Optional: "optional",
+} as const
+
+export type AttendeeRole = (typeof AttendeeRole)[keyof typeof AttendeeRole]
+
+export const AttendeeStatus = {
+	Accepted: "accepted",
+	Declined: "declined",
+	Tentative: "tentative",
+	NeedsAction: "needs-action",
+} as const
+
+export type AttendeeStatus = (typeof AttendeeStatus)[keyof typeof AttendeeStatus]
+
+export interface CalendarAttendee {
+	name: string | null
+	email: string | null
+	role: AttendeeRole | null
+	status: AttendeeStatus | null
+}
+
+export interface CalendarAlarm {
+	/** ISO 8601 duration relative to event start, e.g. "-PT15M" */
+	trigger: string
+	/** e.g. "DISPLAY", "AUDIO" */
+	action: string
+}
+
+export interface CalendarEventData extends Record<string, unknown> {
+	uid: string
+	title: string
+	startDate: Date
+	endDate: Date
+	isAllDay: boolean
+	location: string | null
+	description: string | null
+	calendarName: string | null
+	status: CalendarEventStatus | null
+	url: string | null
+	organizer: string | null
+	attendees: CalendarAttendee[]
+	alarms: CalendarAlarm[]
+	recurrenceId: string | null
+}
+
+export type CalendarFeedItem = FeedItem<"calendar-event", CalendarEventData>
+
+// -- DAV client interface --
+
+export interface CalendarDAVObject {
+	data?: unknown
+	etag?: string
+	url: string
+}
+
+export interface CalendarDAVCalendar {
+	displayName?: string | Record<string, unknown>
+	url: string
+}
+
+/** Subset of DAVClient used by CalendarSource. */
+export interface CalendarDAVClient {
+	login(): Promise<void>
+	fetchCalendars(): Promise<CalendarDAVCalendar[]>
+	fetchCalendarObjects(params: {
+		calendar: CalendarDAVCalendar
+		timeRange: { start: string; end: string }
+	}): Promise<CalendarDAVObject[]>
+	credentials: Record<string, unknown>
+}

packages/aris-source-google-calendar/fixtures/events.json

@@ -0,0 +1,72 @@
+{
+	"kind": "calendar#events",
+	"summary": "primary",
+	"items": [
+		{
+			"id": "evt-ongoing",
+			"status": "confirmed",
+			"htmlLink": "https://calendar.google.com/event?eid=evt-ongoing",
+			"summary": "Team Standup",
+			"description": "Daily standup meeting",
+			"location": "Room 3A",
+			"start": {
+				"dateTime": "2026-01-20T09:30:00Z"
+			},
+			"end": {
+				"dateTime": "2026-01-20T10:15:00Z"
+			}
+		},
+		{
+			"id": "evt-soon",
+			"status": "confirmed",
+			"htmlLink": "https://calendar.google.com/event?eid=evt-soon",
+			"summary": "1:1 with Manager",
+			"start": {
+				"dateTime": "2026-01-20T10:10:00Z"
+			},
+			"end": {
+				"dateTime": "2026-01-20T10:40:00Z"
+			}
+		},
+		{
+			"id": "evt-later",
+			"status": "confirmed",
+			"htmlLink": "https://calendar.google.com/event?eid=evt-later",
+			"summary": "Design Review",
+			"description": "Review new dashboard designs",
+			"location": "Conference Room B",
+			"start": {
+				"dateTime": "2026-01-20T14:00:00Z"
+			},
+			"end": {
+				"dateTime": "2026-01-20T15:00:00Z"
+			}
+		},
+		{
+			"id": "evt-tentative",
+			"status": "tentative",
+			"htmlLink": "https://calendar.google.com/event?eid=evt-tentative",
+			"summary": "Lunch with Alex",
+			"location": "Cafe Nero",
+			"start": {
+				"dateTime": "2026-01-20T12:00:00Z"
+			},
+			"end": {
+				"dateTime": "2026-01-20T13:00:00Z"
+			}
+		},
+		{
+			"id": "evt-allday",
+			"status": "confirmed",
+			"htmlLink": "https://calendar.google.com/event?eid=evt-allday",
+			"summary": "Company Holiday",
+			"description": "Office closed",
+			"start": {
+				"date": "2026-01-20"
+			},
+			"end": {
+				"date": "2026-01-21"
+			}
+		}
+	]
+}

packages/aris-source-google-calendar/package.json

@@ -0,0 +1,14 @@
+{
+	"name": "@aris/source-google-calendar",
+	"version": "0.0.0",
+	"type": "module",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"scripts": {
+		"test": "bun test ."
+	},
+	"dependencies": {
+		"@aris/core": "workspace:*",
+		"arktype": "^2.1.0"
+	}
+}

packages/aris-source-google-calendar/src/calendar-context.ts

@@ -0,0 +1,13 @@
+import type { ContextKey } from "@aris/core"
+
+import { contextKey } from "@aris/core"
+
+export interface NextEvent {
+	title: string
+	startTime: Date
+	endTime: Date
+	minutesUntilStart: number
+	location: string | null
+}
+
+export const NextEventKey: ContextKey<NextEvent> = contextKey("nextEvent")

packages/aris-source-google-calendar/src/feed-items.ts

@@ -0,0 +1,22 @@
+import type { FeedItem } from "@aris/core"
+
+import type { CalendarEventData } from "./types"
+
+export const CalendarFeedItemType = {
+	event: "calendar-event",
+	allDay: "calendar-all-day",
+} as const
+
+export type CalendarFeedItemType = (typeof CalendarFeedItemType)[keyof typeof CalendarFeedItemType]
+
+export interface CalendarEventFeedItem extends FeedItem<
+	typeof CalendarFeedItemType.event,
+	CalendarEventData
+> {}
+
+export interface CalendarAllDayFeedItem extends FeedItem<
+	typeof CalendarFeedItemType.allDay,
+	CalendarEventData
+> {}
+
+export type CalendarFeedItem = CalendarEventFeedItem | CalendarAllDayFeedItem

packages/aris-source-google-calendar/src/google-calendar-api.ts

@@ -0,0 +1,122 @@
+// Google Calendar REST API v3 client
+// https://developers.google.com/calendar/api/v3/reference/events/list
+
+import { type } from "arktype"
+
+import type {
+	ApiCalendarEvent,
+	GoogleCalendarClient,
+	GoogleOAuthProvider,
+	ListEventsOptions,
+} from "./types"
+
+import { EventStatus } from "./types"
+
+const eventStatusSchema = type.enumerated(
+	EventStatus.Confirmed,
+	EventStatus.Tentative,
+	EventStatus.Cancelled,
+)
+
+const eventDateTimeSchema = type({
+	"dateTime?": "string",
+	"date?": "string",
+	"timeZone?": "string",
+})
+
+const eventSchema = type({
+	id: "string",
+	status: eventStatusSchema,
+	htmlLink: "string",
+	"summary?": "string",
+	"description?": "string",
+	"location?": "string",
+	start: eventDateTimeSchema,
+	end: eventDateTimeSchema,
+})
+
+const calendarListEntrySchema = type({
+	id: "string",
+})
+
+const calendarListResponseSchema = type({
+	"items?": calendarListEntrySchema.array(),
+	"nextPageToken?": "string",
+})
+
+const eventsResponseSchema = type({
+	"items?": eventSchema.array(),
+	"nextPageToken?": "string",
+})
+
+export class DefaultGoogleCalendarClient implements GoogleCalendarClient {
+	private static readonly API_BASE = "https://www.googleapis.com/calendar/v3"
+
+	private readonly oauthProvider: GoogleOAuthProvider
+
+	constructor(oauthProvider: GoogleOAuthProvider) {
+		this.oauthProvider = oauthProvider
+	}
+
+	async listCalendarIds(): Promise<string[]> {
+		const url = `${DefaultGoogleCalendarClient.API_BASE}/users/me/calendarList?fields=items(id)`
+		const json = await this.request(url)
+		const result = calendarListResponseSchema(json)
+
+		if (result instanceof type.errors) {
+			throw new Error(`Google Calendar API response validation failed: ${result.summary}`)
+		}
+
+		if (!result.items) {
+			return []
+		}
+		return result.items.map((entry) => entry.id)
+	}
+
+	async listEvents(options: ListEventsOptions): Promise<ApiCalendarEvent[]> {
+		const url = new URL(
+			`${DefaultGoogleCalendarClient.API_BASE}/calendars/${encodeURIComponent(options.calendarId)}/events`,
+		)
+		url.searchParams.set("timeMin", options.timeMin.toISOString())
+		url.searchParams.set("timeMax", options.timeMax.toISOString())
+		url.searchParams.set("singleEvents", "true")
+		url.searchParams.set("orderBy", "startTime")
+
+		const json = await this.request(url.toString())
+		const result = eventsResponseSchema(json)
+
+		if (result instanceof type.errors) {
+			throw new Error(`Google Calendar API response validation failed: ${result.summary}`)
+		}
+
+		if (!result.items) {
+			return []
+		}
+
+		return result.items
+	}
+
+	/** Authenticated GET with auto token refresh on 401. */
+	private async request(url: string): Promise<unknown> {
+		const token = await this.oauthProvider.fetchAccessToken()
+		let response = await fetch(url, {
+			headers: { Authorization: `Bearer ${token}` },
+		})
+
+		if (response.status === 401) {
+			const newToken = await this.oauthProvider.refresh()
+			response = await fetch(url, {
+				headers: { Authorization: `Bearer ${newToken}` },
+			})
+		}
+
+		if (!response.ok) {
+			const body = await response.text()
+			throw new Error(
+				`Google Calendar API error: ${response.status} ${response.statusText}: ${body}`,
+			)
+		}
+
+		return response.json()
+	}
+}