builder alpha.2

Author: tannerlinsley

.claude/tanstack-patterns.md

@@ -0,0 +1,76 @@
+# TanStack Patterns
+
+## loaderDeps Must Be Specific
+
+Only include properties actually used in the loader. This ensures proper cache invalidation.
+
+```typescript
+// Bad: includes everything
+loaderDeps: ({ search }) => search,
+loader: async ({ deps }) => {
+  await fetchData({ page: deps.page, pageSize: deps.pageSize })
+}
+
+// Good: only what's used
+loaderDeps: ({ search }) => ({
+  page: search.page,
+  pageSize: search.pageSize,
+}),
+loader: async ({ deps }) => {
+  await fetchData({ page: deps.page, pageSize: deps.pageSize })
+}
+```
+
+## Loaders Are Isomorphic
+
+Loaders run on both server and client. They cannot directly access server-only APIs.
+
+```typescript
+// Bad: direct server API access
+loader: async () => {
+  const data = await fs.readFile('data.json')
+  return { data }
+}
+
+// Good: call a server function
+loader: async () => {
+  const data = await serverFn({ data: { id: '123' } })
+  return { data }
+}
+```
+
+## Environment Shaking
+
+TanStack Start strips any code not referenced by a `createServerFn` handler from the client build.
+
+- Server-only code (database, fs) is automatically excluded from client bundles
+- Only code inside `createServerFn` handlers goes to server bundles
+- Code outside handlers is included in both bundles
+
+## Importing Server Functions
+
+Server functions wrapped in `createServerFn` can be imported statically. Never use dynamic imports for server-only code in components.
+
+```typescript
+// Bad: dynamic import causes bundler issues
+const rolesQuery = useQuery({
+  queryFn: async () => {
+    const { listRoles } = await import('~/utils/roles.server')
+    return listRoles({ data: {} })
+  },
+})
+
+// Good: static import
+import { listRoles } from '~/utils/roles.server'
+
+const rolesQuery = useQuery({
+  queryFn: async () => listRoles({ data: {} }),
+})
+```
+
+## Server-Only Import Rules
+
+1. `createServerFn` wrappers can be imported statically anywhere
+2. Direct server-only code (database clients, fs) must only be imported:
+   - Inside `createServerFn` handlers
+   - In `*.server.ts` files

.claude/typescript.md

@@ -0,0 +1,45 @@
+# TypeScript Conventions
+
+## Avoid Type Casting
+
+Never cast types unless absolutely necessary. This includes:
+
+- Manual generic type parameters (e.g., `<Type>`)
+- Type assertions using `as`
+- Type assertions using `satisfies`
+
+## Prefer Type Inference
+
+Infer types by going up the logical chain:
+
+1. **Schema validation** as source of truth (Convex, Zod, etc.)
+2. **Type inference** from function return types, API responses
+3. **Fix at source** (schema, API definition, function signature) rather than casting at point of use
+
+```typescript
+// Bad
+const result = api.getData() as MyType
+const value = getValue<MyType>()
+
+// Good
+const result = api.getData() // Type inferred from return type
+const value = getValue() // Type inferred from implementation
+```
+
+## Generic Type Parameter Naming
+
+All generic type parameters must be prefixed with `T`.
+
+```typescript
+// Bad
+function withCapability<Args extends unknown[], R>(
+  handler: (user: AuthUser, ...args: Args) => R,
+) { ... }
+
+// Good
+function withCapability<TArgs extends unknown[], TReturn>(
+  handler: (user: AuthUser, ...args: TArgs) => TReturn,
+) { ... }
+```
+
+Common names: `T`, `TArgs`, `TReturn`, `TData`, `TError`, `TKey`, `TValue`

.claude/ui-style.md

@@ -0,0 +1,52 @@
+# UI Style Guide 2026
+
+## Layout
+
+- Fewer, well-defined containers over many small sections
+- Generous spacing creates separation before adding visual effects
+- Cards are acceptable when they express grouping or hierarchy
+
+## Corners
+
+- Rounded corners are standard
+- Subtle radius values that feel intentional, not playful
+- Avoid sharp 90-degree corners unless intentionally industrial
+
+## Shadows and Depth
+
+- Soft, low-contrast, diffused shadows
+- Shadows imply separation, not elevation theatrics
+- No heavy drop shadows or strong directional lighting
+- One to two shadow layers max
+
+## Cards
+
+- Cards should feel grounded, not floating
+- Light elevation, border plus shadow, or surface contrast
+- Don't overuse cards as a default layout primitive
+
+## Color and Surfaces
+
+- Soft neutrals, off-whites, warm grays
+- Surface contrast or translucency instead of strong outlines
+- Glass/frosted effects acceptable when subtle and accessible
+
+## Interaction
+
+- Micro transitions reinforce spatial relationships
+- Hover/focus states feel responsive, not animated
+- No excessive motion or springy effects
+
+## Typography
+
+- Strong headings, calm body text
+- No visual noise around content
+
+## What to Avoid
+
+- Chunky shadows
+- Overly flat, sterile layouts
+- Neumorphism as primary style
+- Over-designed card grids
+
+**Summary: If depth does not improve comprehension, remove it.**

.claude/workflow.md

@@ -0,0 +1,26 @@
+# Workflow
+
+## Build Commands
+
+- `pnpm test`: Run at end of task batches
+- `pnpm build`: Only for build/bundler issues or verifying production output
+- `pnpm lint`: Check for code issues
+- `dev` runs indefinitely in watch mode
+
+Don't build after every change. This is a visual site; assume changes work.
+
+## Debugging Visual Issues
+
+When something doesn't work or look right:
+
+1. Use Playwright MCP to view the page and debug visually
+2. Use `pnpm build` only for build/bundler issues
+3. Use `pnpm lint` for code issues
+
+## Playwright Testing
+
+Preferred method for verifying visual changes:
+
+- Navigate to the relevant page
+- Take snapshots/screenshots to verify UI
+- Interact with elements to test functionality