···11+# Repository Guidelines
22+33+## Project Structure & Module Organization
44+- `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`.
55+- `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`.
66+- Root app setup lives in `src/app.html` and `src/app.css`.
77+- `static` is for public assets served as-is.
88+- `docs` includes contributor-facing docs like custom cards and self-hosting.
99+1010+## Build, Test, and Development Commands
1111+- `pnpm dev` starts the Vite dev server.
1212+- `pnpm build` creates a production build.
1313+- `pnpm preview` builds and runs locally with Wrangler.
1414+- `pnpm check` runs `svelte-check` for type diagnostics.
1515+- `pnpm lint` runs Prettier check and ESLint.
1616+- `pnpm format` auto-formats the codebase with Prettier.
1717+- `pnpm deploy` builds and deploys to Cloudflare Workers.
1818+1919+## Coding Style & Naming Conventions
2020+- Indentation uses tabs, single quotes, and 100-column width (see `.prettierrc`).
2121+- Svelte components use PascalCase filenames; utilities and helpers use camelCase.
2222+- Prefer TypeScript in `src` and keep module boundaries aligned with `src/lib` subfolders (cards, components, website, oauth).
2323+2424+## Testing Guidelines
2525+- There is no dedicated test runner yet. Use `pnpm check` and `pnpm lint` before submitting changes.
2626+- For UI changes, verify key flows manually (login, card editing, save/load, and route navigation across `[handle]` pages).
2727+2828+## Commit & Pull Request Guidelines
2929+- Keep commits short and direct; recent history favors lowercase, imperative summaries (e.g., `small fixes`).
3030+- PRs should include a clear description, linked issues when relevant, and screenshots for UI changes.
3131+3232+## Configuration & Deployment Notes
3333+- Copy `.env.example` to `.env` and adjust `PUBLIC_*` values for local or self-hosted setups.
3434+- Cloudflare configuration lives in `wrangler.jsonc`; deployments use Wrangler via `pnpm deploy`.
+11-9
CLAUDE.md
···4455## Project Overview
6677-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.
77+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.
8899## Commands
1010···3232- Desktop position/size: `x`, `y`, `w`, `h`
3333- Mobile position/size: `mobileX`, `mobileY`, `mobileW`, `mobileH`
34343535-Grid margins: 20px desktop, 12px mobile.
3535+Grid margins: 16px desktop, 12px mobile.
36363737### Key Components
38383939**Website Rendering:**
40404141-- `Website.svelte` - Read-only view of a user's bento grid
4242-- `EditableWebsite.svelte` - Full editing interface with drag-and-drop, card creation, and save functionality
4141+- `src/lib/website/Website.svelte` - Read-only view of a user's bento grid
4242+- `src/lib/website/EditableWebsite.svelte` - Full editing interface with drag-and-drop, card creation, and save functionality
4343+- `src/lib/website/Settings.svelte` and `src/lib/website/Profile.svelte` - Editing panels and profile UI
4344- 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`, ...)
44454546**Card System (`src/lib/cards/`):**
46474748- `CardDefinition` type in `types.ts` defines the interface for card types
4849- 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`)
4949-- Card types: Text, Link, Image, Youtube, BlueskyPost, Embed, Map, Livestream, ATProtoCollections, Section
5050+- Card types include Text, Link, Image, Bluesky, Embed, Map, Livestream, ATProto collections, and special cards (see `src/lib/cards`).
5051- `AllCardDefinitions` and `CardDefinitionsByType` in `index.ts` aggregate all card types
5152- See e.g. `src/lib/cards/EmbedCard/` and `src/lib/cards/LivestreamCard/` for examples of implementation.
5253- 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).
···59606061**Data Loading (`src/lib/website/`):**
61626262-- `load.ts` - Fetches user data from their PDS, with Cloudflare KV caching (`USER_DATA_CACHE`)
6363+- `load.ts` - Fetches user data from their PDS, with optional KV caching via `UserCache`
6364- `data.ts` - Defines which collections/records to fetch
6465- `context.ts` - Svelte contexts for passing DID, handle, and data down the component tree
65666667### Routes
67686869- `/` - Landing page
6969-- `/[handle]` - View a user's bento site (loads from their PDS)
7070-- `/[handle]/edit` - Edit mode for the user's site
7070+- `/[handle]/[[page]]` - View a user's bento site (loads from their PDS)
7171+- `/[handle]/[[page]]/edit` - Edit mode for a user's site page
7172- `/edit` - Self-hosted edit mode
7273- `/api/links` - Link preview API
7374- `/api/geocoding` - Geocoding API for map cards
7575+- `/api/instagram`, `/api/reloadRecent`, `/api/update` - Additional data endpoints
74767577### Item Type
7678···80828183`src/lib/helper.ts` contains grid layout algorithms:
82848383-- `fixCollisions` - Push cards down when they overlap
8585+- `fixAllCollisions` - Push cards down when they overlap
8486- `compactItems` - Move cards up to fill gaps
8587- `simulateFinalPosition` - Preview where a dragged card will land