···1+# Repository Guidelines
2+3+## Project Structure & Module Organization
4+- `src/routes` contains SvelteKit routes, including dynamic handle pages in `src/routes/[handle]/[[page]]`, edit flows in `src/routes/[handle]/[[page]]/edit` and `src/routes/edit`, and API endpoints under `src/routes/api`.
5+- `src/lib` holds reusable modules: card implementations in `src/lib/cards`, shared UI in `src/lib/components`, OAuth helpers in `src/lib/oauth`, and site data/loading in `src/lib/website`.
6+- Root app setup lives in `src/app.html` and `src/app.css`.
7+- `static` is for public assets served as-is.
8+- `docs` includes contributor-facing docs like custom cards and self-hosting.
9+10+## Build, Test, and Development Commands
11+- `pnpm dev` starts the Vite dev server.
12+- `pnpm build` creates a production build.
13+- `pnpm preview` builds and runs locally with Wrangler.
14+- `pnpm check` runs `svelte-check` for type diagnostics.
15+- `pnpm lint` runs Prettier check and ESLint.
16+- `pnpm format` auto-formats the codebase with Prettier.
17+- `pnpm deploy` builds and deploys to Cloudflare Workers.
18+19+## Coding Style & Naming Conventions
20+- Indentation uses tabs, single quotes, and 100-column width (see `.prettierrc`).
21+- Svelte components use PascalCase filenames; utilities and helpers use camelCase.
22+- Prefer TypeScript in `src` and keep module boundaries aligned with `src/lib` subfolders (cards, components, website, oauth).
23+24+## Testing Guidelines
25+- There is no dedicated test runner yet. Use `pnpm check` and `pnpm lint` before submitting changes.
26+- For UI changes, verify key flows manually (login, card editing, save/load, and route navigation across `[handle]` pages).
27+28+## Commit & Pull Request Guidelines
29+- Keep commits short and direct; recent history favors lowercase, imperative summaries (e.g., `small fixes`).
30+- PRs should include a clear description, linked issues when relevant, and screenshots for UI changes.
31+32+## Configuration & Deployment Notes
33+- Copy `.env.example` to `.env` and adjust `PUBLIC_*` values for local or self-hosted setups.
34+- Cloudflare configuration lives in `wrangler.jsonc`; deployments use Wrangler via `pnpm deploy`.
+11-9
CLAUDE.md
···45## Project Overview
67-Blento is a Bluesky-powered customizable bento grid website builder. Users authenticate via ATProto OAuth and can create personalized websites with draggable/resizable cards that are stored directly in their Bluesky PDS (Personal Data Server) using the `app.blento.card` collection.
89## Commands
10···32- Desktop position/size: `x`, `y`, `w`, `h`
33- Mobile position/size: `mobileX`, `mobileY`, `mobileW`, `mobileH`
3435-Grid margins: 20px desktop, 12px mobile.
3637### Key Components
3839**Website Rendering:**
4041-- `Website.svelte` - Read-only view of a user's bento grid
42-- `EditableWebsite.svelte` - Full editing interface with drag-and-drop, card creation, and save functionality
043- Styling: two colors: base color (one the gray-ish tailwind colors: `gray`, `neutral`, `stone`, ...) and accent color (one of the not-gray-ish tailwind color: `rose`, `red`, `amber`, ...)
4445**Card System (`src/lib/cards/`):**
4647- `CardDefinition` type in `types.ts` defines the interface for card types
48- Each card type exports a definition with: `type`, `contentComponent`, optional `editingContentComponent`, `creationModalComponent`, `sidebarComponent`, `loadData`, `upload` (see more info and description in `src/lib/cards/types.ts`)
49-- Card types: Text, Link, Image, Youtube, BlueskyPost, Embed, Map, Livestream, ATProtoCollections, Section
50- `AllCardDefinitions` and `CardDefinitionsByType` in `index.ts` aggregate all card types
51- See e.g. `src/lib/cards/EmbedCard/` and `src/lib/cards/LivestreamCard/` for examples of implementation.
52- Cards should be styled to work in light and dark mode (with `dark:` class modifier) as well as when cards are colorful (= bg-color-500 for the card background) (with `accent:` modifier).
···5960**Data Loading (`src/lib/website/`):**
6162-- `load.ts` - Fetches user data from their PDS, with Cloudflare KV caching (`USER_DATA_CACHE`)
63- `data.ts` - Defines which collections/records to fetch
64- `context.ts` - Svelte contexts for passing DID, handle, and data down the component tree
6566### Routes
6768- `/` - Landing page
69-- `/[handle]` - View a user's bento site (loads from their PDS)
70-- `/[handle]/edit` - Edit mode for the user's site
71- `/edit` - Self-hosted edit mode
72- `/api/links` - Link preview API
73- `/api/geocoding` - Geocoding API for map cards
07475### Item Type
76···8081`src/lib/helper.ts` contains grid layout algorithms:
8283-- `fixCollisions` - Push cards down when they overlap
84- `compactItems` - Move cards up to fill gaps
85- `simulateFinalPosition` - Preview where a dragged card will land
···45## Project Overview
67+Blento is a Bluesky-powered customizable bento grid website builder. Users authenticate via ATProto OAuth and create draggable/resizable cards stored in their Bluesky PDS (Personal Data Server) using the `app.blento.card` collection.
89## Commands
10···32- Desktop position/size: `x`, `y`, `w`, `h`
33- Mobile position/size: `mobileX`, `mobileY`, `mobileW`, `mobileH`
3435+Grid margins: 16px desktop, 12px mobile.
3637### Key Components
3839**Website Rendering:**
4041+- `src/lib/website/Website.svelte` - Read-only view of a user's bento grid
42+- `src/lib/website/EditableWebsite.svelte` - Full editing interface with drag-and-drop, card creation, and save functionality
43+- `src/lib/website/Settings.svelte` and `src/lib/website/Profile.svelte` - Editing panels and profile UI
44- Styling: two colors: base color (one the gray-ish tailwind colors: `gray`, `neutral`, `stone`, ...) and accent color (one of the not-gray-ish tailwind color: `rose`, `red`, `amber`, ...)
4546**Card System (`src/lib/cards/`):**
4748- `CardDefinition` type in `types.ts` defines the interface for card types
49- Each card type exports a definition with: `type`, `contentComponent`, optional `editingContentComponent`, `creationModalComponent`, `sidebarComponent`, `loadData`, `upload` (see more info and description in `src/lib/cards/types.ts`)
50+- Card types include Text, Link, Image, Bluesky, Embed, Map, Livestream, ATProto collections, and special cards (see `src/lib/cards`).
51- `AllCardDefinitions` and `CardDefinitionsByType` in `index.ts` aggregate all card types
52- See e.g. `src/lib/cards/EmbedCard/` and `src/lib/cards/LivestreamCard/` for examples of implementation.
53- Cards should be styled to work in light and dark mode (with `dark:` class modifier) as well as when cards are colorful (= bg-color-500 for the card background) (with `accent:` modifier).
···6061**Data Loading (`src/lib/website/`):**
6263+- `load.ts` - Fetches user data from their PDS, with optional KV caching via `UserCache`
64- `data.ts` - Defines which collections/records to fetch
65- `context.ts` - Svelte contexts for passing DID, handle, and data down the component tree
6667### Routes
6869- `/` - Landing page
70+- `/[handle]/[[page]]` - View a user's bento site (loads from their PDS)
71+- `/[handle]/[[page]]/edit` - Edit mode for a user's site page
72- `/edit` - Self-hosted edit mode
73- `/api/links` - Link preview API
74- `/api/geocoding` - Geocoding API for map cards
75+- `/api/instagram`, `/api/reloadRecent`, `/api/update` - Additional data endpoints
7677### Item Type
78···8283`src/lib/helper.ts` contains grid layout algorithms:
8485+- `fixAllCollisions` - Push cards down when they overlap
86- `compactItems` - Move cards up to fill gaps
87- `simulateFinalPosition` - Preview where a dragged card will land